@postqode/agent

Pluggable agent loop and tool execution for PostQode. Built on @postqode/ai. Ships no tools or prompts — consumers supply their own or layer @postqode/coding-agent on top.

What ships

• Agent class — drives the multi-turn LLM loop, executes tools, emits streaming events.
• Contracts: Tool, ToolContext, ToolOutput, Host, FileSystem, Terminal, Logger, AgentEvent (union), Hooks, AgentConfig, AgentResult, AgentMessage.
• NodeHost — default Host implementation using node:fs/promises and node:child_process. Works from any CLI or server context.
• assistant-message/ — tool-use block parsing, diff construction helpers.
• Persistent memory — AgentMemoryContext and TaskMemoryManager build a MEMORY.md-indexed store per agent or per task. Memory scopes: user / project / local; the home-dir resolver is a constructor callback so non-VS-Code hosts plug their own.

Minimal example

import { getProvider } from "@postqode/ai"
import { Agent } from "@postqode/agent"

const api = getProvider("anthropic")!(
	{ apiKey, agentModeApiModelId: "claude-sonnet-4-5-20250929", planModeApiModelId: "claude-sonnet-4-5-20250929" },
	"agent",
)

const agent = new Agent({ api, systemPrompt: "You are a helpful assistant." })
const { messages, usage } = await agent.run("Hello!")

Streaming + hooks

for await (const event of agent.runStream("Summarize foo.ts")) {
	if (event.type === "text_delta") process.stdout.write(event.delta)
}

// Or pass hooks:
new Agent({
	api,
	systemPrompt: "...",
	hooks: {
		onToolStart: ({ name }) => console.log("→", name),
		onToolEnd: ({ name, output }) => console.log("✓", name, output.content.slice(0, 80)),
		onEvent: (e) => metrics.record(e),
	},
})

Custom tools

import type { Tool } from "@postqode/agent"

const readTool: Tool<{ path: string }> = {
	name: "read_file",
	description: "Read a file's contents.",
	inputSchema: {
		type: "object",
		properties: { path: { type: "string" } },
		required: ["path"],
	},
	async execute({ path }, ctx) {
		return { content: await ctx.host.fs.read(path) }
	},
}

new Agent({ api, systemPrompt: "...", tools: [readTool] })

Config knobs

| Field | Default | Purpose | |---|---|---| | api | — | Required. From @postqode/ai. | | systemPrompt | — | Required. | | tools | [] | Provider-agnostic; converted per toolFormat. | | toolFormat | "anthropic" | "anthropic" or "openai". | | host | createNodeHost() | Filesystem + terminal injection. Override with a Vscode-backed host in extensions. | | hooks | {} | onTurnStart/End, onToolStart/End (with cancel), onEvent. | | maxTurns | 50 | Hard cap. | | maxParallelTools | 1 | Concurrency for tool execution. | | cwd | process.cwd() | Working directory for tools. | | signal | new AC | External abort signal. agent.abort() also trips it. |

Sibling packages

• @postqode/ai — provider registry.
• @postqode/coding-agent — factory + default tools + prompt.
• @postqode/browser — browser-automation tool pack.
• @postqode/evals — real-LLM eval harness.