spark-coder — Fast Code Generation via Structured Output

2026-03-29

Talon now ships a built-in sub-agent for fast, single-shot code generation: spark-coder. It landed in PR #132.

The problem

Agents often need to generate or modify files — scaffold a component, rewrite a function, produce boilerplate. Doing this inline in the main agent’s context burns tokens and occupies the main conversation loop with mechanical work.

Sub-agents already solve delegation, but the existing built-ins (summarizer, memory groomer, file searcher) are about reading and organizing. We needed one that writes code.

What spark-coder does

spark-coder takes a task description, optional context files, and optional constraints. It returns structured file operations — not free-form text.

Input:

{
  "task": "Create a TypeScript utility that validates email addresses",
  "constraints": "Pure function, no dependencies, include JSDoc",
  "contextFiles": [
    {
      "path": "src/utils/index.ts",
      "content": "export { validateUrl } from './validate-url';\n"
    }
  ]
}

Output:

{
  "files": [
    {
      "path": "src/utils/validate-email.ts",
      "content": "/** Validates an email address... */\nexport function validateEmail(email: string): boolean { ... }",
      "action": "create"
    }
  ],
  "explanation": "Created a validateEmail utility with RFC 5322 basic validation."
}

Each file operation is either create (new file) or replace (overwrite existing). The calling agent decides what to do with the result — apply it, modify it, or discard it.

The model: gpt-5.4-spark

spark-coder uses OpenAI’s gpt-5.4-spark, a model optimized for fast structured output. It runs with a 60-second timeout and 16,384 max tokens — enough for substantial file generation without blocking the main agent for long.

Path traversal protection

The output schema rejects absolute paths (/etc/passwd) and directory traversal segments (../../secrets) before the result reaches the calling agent. This is enforced at the schema validation layer — a defense-in-depth measure on top of whatever path validation the main agent does.

requiresEnv — a new generic mechanism

PR #132 also introduces a new manifest field: requiresEnv. This is a list of environment variable names that must be present for the sub-agent to load.

name: spark-coder
model: gpt-5.4-spark
requiresEnv:
  - OPENAI_API_KEY

If any listed variable is missing from process.env, the loader silently skips the sub-agent at info level. No warning, no error — it just doesn’t exist in that environment.

This is generic — any custom sub-agent can use it:

name: my-custom-agent
model: gpt-4o-mini
requiresEnv:
  - MY_SERVICE_API_KEY
  - MY_SERVICE_URL

Use cases:

• API-dependent sub-agents that need external keys
• Multi-environment deployments where not all instances have all keys
• Graceful degradation — the agent works fine, it just has fewer sub-agents available

The field defaults to [] (no requirements), so existing sub-agents are unaffected.

Using spark-coder

Add it to your persona’s sub-agent allow-list:

personas:
  - name: assistant
    subagents:
      - session-summarizer
      - memory-retriever
      - spark-coder
    capabilities:
      allow:
        - subagent.invoke

Make sure OPENAI_API_KEY is set in your environment. Then invoke it like any other sub-agent:

subagent_invoke({
  name: "spark-coder",
  input: {
    task: "Add a health check endpoint to the Express app",
    contextFiles: [
      { path: "src/app.ts", content: "..." }
    ]
  }
})

The main agent gets back structured file operations it can apply directly — no parsing, no guessing where the code boundaries are.

What’s next

spark-coder is the first sub-agent that writes code. The requiresEnv mechanism opens the door for more provider-specific sub-agents without cluttering environments that don’t have the right keys. Expect more specialized code-generation sub-agents as we find repeatable patterns worth offloading.