axon

The axon global is the agent runtime API. Available in scripts and route handlers. There is no cross-agent access — axon is always scoped to the running agent instance.

axon.request

One-shot invocation. Sends a task to the agent loop and awaits the full result.

// Shorthand — plain string, uses the execution thread
const result = await axon.request("hello")

// With options
const result = await axon.request({
    prompt,           // string | AxonRenderedPrompt | (string | AxonRenderedPrompt)[]
    thread: "name",   // Named thread. Omit to use the execution thread.
    policy: { ... },  // Narrowing only. Cannot expand base policy.
})

// result: { text: string, entries: AnyThreadEntry[], threadId: string }

axon.stream

Streaming invocation. Returns an async generator that yields entries as the loop produces them.

// Shorthand
const { stream } = axon.stream("hello")

// With options — same shape as axon.request
const { stream } = axon.stream({
    prompt,
    thread: "name",
    policy: { ... },
})

for await (const entry of stream) { ... }

Use axon.stream when forwarding output incrementally — chat surfaces, long-running tasks, progress display.

axon.thread

A handle for repeated calls to the same named thread. Avoids repeating the thread name on every call. .request() and .stream() have the same signatures as the top-level calls, minus the thread field.

const research = axon.thread("research")

await research.request("find everything about the eiffel tower")
await research.request("now find the history of its construction")

const { stream } = research.stream("summarise into 3 bullet points")

For named threads, parallel branches, and persistence across script runs, see axon.thread.

axon.prompt

Render an authored prompt from src/prompts/ or an installed module. Returns a rendered prompt object to pass to axon.request or axon.stream.

const context = await axon.prompt("project-context")
const review  = await axon.prompt("code-review", { issueId: "bd-42" })

// compose multiple prompts — Axon concatenates in order
const { stream } = axon.stream({ prompt: [context, review] })

axon.scripts

Invoke another script from within a script or route.

// collect all entries
const result = await axon.scripts.request("close-plan", { issueId: "bd-yiq" })

// stream entries as they arrive
const { stream } = axon.scripts.stream("scout")
for await (const entry of stream) { ... }

axon.tools

Call installed tool functions by namespace. Typed — axon prepare generates declarations.

const issues = await axon.tools.kanban.list()
const pr = await axon.tools.github.openPr("fix: auth", "...", "feat/auth")

axon.proc

Spawn shell commands. Returns a ProcHandle for streaming output and checking exit status.

const proc = axon.proc.spawn("git push --set-upstream origin HEAD")

for await (const line of proc.watch()) {
    process.stdout.write(line + "\n")
}

if (proc.exitCode !== 0) throw new Error("Push failed")

axon.capabilities

Query what the current engine supports. Synchronous — the engine declares capabilities at boot.

const caps = axon.capabilities()
// → { text: boolean, audio: boolean, image: boolean }

if (caps.image) {
    // include image attachments in the prompt
}

axon.hooks

Subscribe to lifecycle and module events. Use in server plugins.

axon.hooks.on("github:issue.opened", async ({ number, title }) => {
    const prompt = await axon.prompt("issue-triage", { number, title })
    await axon.request({ prompt, thread: "issue-triage" })
})

Modules emit named hooks from their routes using axon.hooks.callHook(event, payload).

axon.ui

Request input from a connected TUI host. Returns { unavailable } when running headlessly.

const response = await axon.ui.ask({
    message: "Which approach should I take?",
    options: ["refactor", "rewrite", "leave it"],
})

if ("unavailable" in response) {
    // no connected host — proceed with default or abort
}

Where axon is available