An agent kernel for TypeScript.

Install · Quick start · What you get · Documentation

An agent that works in a demo is a loop around a model call. An agent that works in production is that loop plus everything around it — a budget that stops it, an identity that attributes it, a boundary it cannot talk its way past, a record that survives the process, and a way to shrink a conversation that is about to overflow without corrupting it.

This is those other things. It runs an agent the way an operating system runs a process: given an identity and a budget, confined, scheduled, checkpointed, and what it did is written down. It renders no UI, requires no database, hosts no service, and has no preferred model vendor.

Install

pnpm add @namzu/sdk

Requires Node.js 20+, ESM, and TypeScript strict mode.

The kernel ships alone. Add a driver for whichever backend you use — @namzu/anthropic, @namzu/openai, @namzu/bedrock, @namzu/openrouter, @namzu/ollama, @namzu/lmstudio, or the zero-dependency @namzu/http. With none of them the kernel still runs against MockLLMProvider, which is pre-registered and scriptable.

Quick start

import { defineTool, ProviderRegistry, ReactiveAgent, ToolRegistry } from '@namzu/sdk'
import { registerOpenRouter } from '@namzu/openrouter'
import { z } from 'zod'

registerOpenRouter()

const searchWeb = defineTool({
  name: 'search_web',
  description: 'Search the web for information',
  inputSchema: z.object({ query: z.string() }),
  category: 'network',
  permissions: ['network_access'],
  readOnly: true,
  destructive: false,
  concurrencySafe: true,
  execute: async ({ query }) => {
    const r = await fetch(`https://api.search.com?q=${query}`)
    return { success: true, output: await r.text() }
  },
})

const { provider } = ProviderRegistry.create({
  type: 'openrouter',
  apiKey: process.env.OPENROUTER_KEY ?? '',
})

const tools = new ToolRegistry()
tools.register(searchWeb)

const agent = new ReactiveAgent({
  id: 'researcher',
  name: 'Research Assistant',
  version: '1.0.0',
  category: 'research',
  description: 'Finds and synthesizes information',
})

const result = await agent.run(
  {
    messages: [{ role: 'user', content: 'Summarize the latest LLM benchmarks' }],
    workingDirectory: process.cwd(),
  },
  { model: 'anthropic/claude-sonnet-4', tokenBudget: 8192, timeoutMs: 600_000, provider, tools },
)

That run is sandbox-isolated, checkpointed and instrumented, with prompt caching, progressive tool disclosure and structured compaction already wired in. Those are not features you enable — they are how the kernel runs. Swap the registerOpenRouter() line for any other driver and everything below it is unchanged.

What you get

| | | |---|---| | Boundary | tool calls run confined; a permission gate decides before, not after | | Budget | tokens, money, wall clock and iterations, enforced rather than hoped for | | Identity | tenant → project → topic → session → run, on every record and span | | Durability | checkpoints a run resumes from, and a record that outlives the process | | Compaction | a conversation about to overflow is shrunk without being corrupted | | Observability | OpenTelemetry spans and metrics, and a log pipeline you own the sink for |

Before a provider receives carried history, the kernel validates tool-call chronology. Orphaned and displaced results are removed, abandoned calls receive an explicit unknown-outcome error result, and duplicate call ids fail closed. Durable approval or crash-resume authority is resolved first so an owned call is completed exactly once. Hosts receive message_history_repaired with source and counts before the model call; conversation and tool content stay out of the event.

Stored image and document references are materialized under the run's caller signal before provider work starts. A pre-cancelled run performs no attachment store I/O; cancellation also settles the run when a custom or remote store ignores the signal, while retaining the unresolved references in its durable message record. AttachmentStore.get receives an optional AttachmentOperationOptions so implementations can stop their own I/O. The caller keeps ownership of its controller, and a late store result is never published into a cancelled run. resumeRun carries its already-selected checkpoint snapshot into the same boundary, so cancellation neither rereads a non-cooperative checkpoint backend nor replaces prior history, usage, or a new queued reference with an incomplete snapshot. The selected checkpoint also carries its durable trace parent into the cancelled run, preserving one cross-process timeline without a second checkpoint read.

Hosts that discover scoped repository policy can supply a ProjectInstructionContext to query, runAgent, ReactiveAgent, or SupervisorAgent. Its first-request snapshot is structurally tagged and retained; completed registry calls, including nested dispatch, can publish a replacement immediately after the complete tool-result batch. Each callback receives the run signal and the exact accepted message prefix; each returned snapshot is committed before the next observation starts, so cancellation can discard an unfinished suffix without losing accepted policy state. This channel does not create a human continuation, so a terminal tool or stop predicate cannot strand the update. Canonical project-relative AGENTS.md provenance survives compaction and lets a reconstructed host re-read disk authority rather than trusting persisted policy text.

TopicManager is the lifecycle authority for the durable subject above a session. Supply it to agent and handoff dependencies as topicManager; spawn and handoff then share the same archived-topic gate. Hosts can distinguish TopicArchivedError, TopicNotEmptyError, and StaleTopicError directly from the package root, and each carries details.topicId.

Documentation

• The kernel in depth — every subsystem, the design principles, the event protocol
• An agent is a folder
• Tools and safety · Observability · Integrations
• All docs

License

FSL-1.1-MIT, converting to MIT two years after each release.