@fabric-harness/sdk

Core SDK for Fabric Harness — a headless TypeScript framework for building durable, deployable autonomous agents.

Install

npm install @fabric-harness/sdk
# or
pnpm add @fabric-harness/sdk

Quick start

Minimal — bare import, headless defaults (8 lines)

import { agent } from '@fabric-harness/sdk';

export default agent<{ message: string }>({
  name: 'echo',
  triggers: { webhook: true },
  run: async ({ init, input }) => {
    const session = await (await init({ model: 'openai/gpt-5.5' })).session();
    return { reply: await session.prompt<string>(input.message) };
  },
});

Complete — same import, more fields

With typed I/O + capability policy + skills (same import)

import { agent, schema } from '@fabric-harness/sdk';

export default agent({
  name: 'triage',
  input: schema.object({ issueNumber: schema.number(), title: schema.string() }),
  output: schema.object({ severity: schema.enum(['low','medium','high']), summary: schema.string() }),
  model: process.env.FABRIC_MODEL,
  run: async ({ init, input }) => {
    const session = await (await init()).session();
    return await session.prompt('Triage and return the typed result.');
  },
});

Both forms share the same init(), session.prompt() / skill() / task() / shell() APIs. Runtime (stateless, inline, or temporal) is a separate choice configured at init().

One SDK, one import

@fabric-harness/sdk is the single import everyone uses. agent({...}) from the bare import auto-injects headless defaults (runtime: 'stateless', sandbox: 'virtual', loopRuntime: pi-agent-core, compaction: { enabled: true }) on every init() call. Override any of them by passing values to init(). Add typed input/output schemas, policy, artifacts, custom stores, telemetry — they're all options on the same agent({...})/init() shape.

For Temporal-backed durable agents or compliance workloads where no implicit behaviour is wanted, use @fabric-harness/sdk/strict — same call shape, no defaults injected.

Runtime (stateless, inline, or temporal) controls persistence and durability and is configured at init(). The deploy target (node, temporal-worker, docker, cloudflare, …) is chosen via fh build --target.

What's in the box

• init({ model, sandbox, policy, runtime, ... }) — initialize an agent runtime.
• session.prompt / skill / task / shell — the four agent operations.
• agent({...}) — single builder. Same call shape from the bare @fabric-harness/sdk import and from @fabric-harness/sdk/strict; the import you choose controls whether headless defaults are injected at runtime.
• defineCommand — bind a privileged CLI (gh, npm, …) with secrets at the command level, never in model context.
• withFilesystemSources — mount read-only content (knowledge base, runbooks) into the sandbox; the agent's built-in grep / glob / read tools see it as ordinary files.
• runtime: 'inline' | 'stateless' | 'temporal' — pick by persistence needs; the agent code is unchanged.
• Schemas (schema.object, schema.enum, etc.) — validate inputs/outputs without external deps.
• MCP — connectMcpServer for remote tool servers.

Documentation

• Headless agents with the minimal entrypoint
• SDK entrypoints, runtimes, and targets
• Runtime modes
• Filesystem sources
• Full reference

License

Apache-2.0