XSAF

Extra Small Agent Framework for TypeScript. Build useful AI agents with a fluent API, explicit security boundaries, a fetch-native Hono runtime, and MCP v2 built in.

Documentation · Getting started · Roadmap · GitHub

import { agent } from "@xsaf/agent";

const bot = agent(config).sandbox(sandbox).tool(search).memory(memory).serve();

await bot.start();

XSAF coordinates models, tools, memory, channels, delegated agents, schedules, and MCP without turning your application into a workflow platform. Configuration stays visible, lifecycle stays deterministic, and deployment remains yours.

• Small, fluent core — compose only the capabilities your agent needs.
• Fetch native — every agent owns a Hono app and a web-standard fetch handler; XSAF never forces a server or opens a socket.
• MCP v2 built in — expose local tools or consume remote MCP tools over HTTP using the official MCP SDK backbone.
• One tool pipeline — validation, approval, cancellation, timeout, retries, sandbox selection, events, and errors follow one path.
• Session aware — serialize work within a session while independent sessions run concurrently.
• Easy to test — deterministic model and channel adapters exercise complete agents without network calls or AI tokens.
• Replaceable infrastructure — memory, channels, models, schedules, sandboxes, and MCP connections are structural drivers.

bun add @xsaf/agent

npm install @xsaf/agent

XSAF is ESM-only and declares Node.js 20 or newer. Its core HTTP surface uses web-standard Request, Response, and fetch APIs.

This complete example is deterministic and makes no network requests:

import { agent } from "@xsaf/agent";
import mockChannel from "@xsaf/agent/channel/mock";
import mockModel from "@xsaf/agent/model/mock";

const model = mockModel({
  response(request) {
    const prompt = request.messages.findLast((message) => message.role === "user")?.content;

    return { text: `Agent received: ${prompt ?? ""}` };
  },
});

const channel = mockChannel();
const bot = agent({
  name: "mock_assistant",
  description: "A deterministic local assistant.",
  model,
  persona: "You are a concise assistant.",
  stream: false,
})
  .channel(channel)
  .serve({ path: "/mcp" });

await bot.start();
await channel.receive({ sessionId: "demo", text: "hello xsaf" });

console.log(channel.sent[0]?.payload);
await bot.stop();

Move from the mock adapter to xsAI-backed models without changing the surrounding agent architecture.

Install the standalone CLI and connect it to an agent exposing the authenticated HTTP channel:

npm install --global @xsaf/cli
API_KEY=asd123 xsaf -u http://localhost:3000

The server remains the only owner of the agent. Response chunks and tool/delegate activity stream to the terminal over HTTP without sharing its process or stdout.

Every started agent exposes a shared Hono application:

await bot.start();

export default {
  fetch(request: Request) {
    return bot.fetch(request);
  },
};

Built-in routes include:

Use the same handler with a compatible Node adapter, Bun, Deno, Workers, or another fetch-native host supported by XSAF's dependencies.

XSAF does not silently execute model-selected tools on the host. Executable local tools, delegates, and MCP tools require an explicit sandbox driver.

import local from "@xsaf/agent/sandbox/local";

agent.sandbox(local({ unsafe: true })); // Explicit opt-in: no isolation.

The bundled local adapter is intended for development and trusted code. Production isolation should use an AgentOS-compatible XsafSandboxDriver or another sandbox implementation. Untrusted MCP tools require human approval by default, and public approval events never expose tool arguments.

Read Tools & Security before enabling executable tools.

• xsAI model adapter with generation, streaming, and structured output
• Standard Schema validation and Standard JSON Schema publication for tools
• In-memory session memory with replaceable durable drivers
• Mock and HTTP channels
• Delegated child agents with context isolation by default
• Process-local cron scheduling with overlap protection
• MCP 2026-07-28 HTTP client and server support
• Typed lifecycle and telemetry events
• Deterministic reverse-order cleanup

XSAF is currently 0.1.0-alpha.0. The core is tested and usable, but APIs may change before a stable release. The alpha intentionally does not include a production sandbox implementation, durable/distributed scheduling, authentication, rate limiting, or a socket listener. Optional durable memory (db0 / unstorage) and chat-sdk channels ship as subpath adapters.

See the Roadmap for current boundaries and planned work.

packages/xsaf/   Framework core, adapters, and tests
packages/cli/    Optional Pi-powered terminal chat UI
apps/website/    Nimbus documentation site
SPEC.md          Alpha behavior and scope

bun install
bun run typecheck
bun run lint
bun test
bun run build

Tests use mocked models and make no real AI requests.

MIT