API Reference

Little Harness mirrors the AI SDK shape: define a reusable harness once, then choose a streaming or final-result execution API per request.

import {
  createHarness,
  generateHarness,
  inputType,
  localHost,
  memory,
  skill,
  streamHarness,
} from "@little-stack/harness";

Core APIs

The root entry exports only what an app needs to build and run an agent. Everything else has its own subpath, listed under Other subpaths. The root also re-exports the AI SDK LanguageModel, ModelMessage, and UIMessage types. ai is a peer dependency (^7.0.0); install with pnpm add @little-stack/harness@alpha ai@^7 zod @ai-sdk/<provider> on Node.js 22+.

@little-stack/harness/connectors

The connector subpath is optional. It exports chatSdkConnector, emailConnector, loadChatSdkConnector, webRichConnector, loadWebRichConnector, discoverConnectors, portable session helpers such as attachSessionConnector, connector tool helpers such as extendTool and harnessToolContext (also on the root entry), and type helpers for tool UI parts. It does not make Chat SDK a required dependency for createHarness, streamHarness, or loadHarness.

Both /connectors and /connectors/runtime statically reach node:fs/promises (through the shared streamHarness → skill-staging code), so a value import from either is server-only — neither is browser-safe. A types-only import (import type) from any subpath is always safe. Pick the subpath by which helpers you need:

• @little-stack/harness/connectors/runtime — descriptors, loaders, session registry, tool-context helpers, and tool-UI types. It omits the filesystem discovery helpers, so a bundler never statically links the connector-module dynamic-import machinery through this subpath — the reason it is the right surface for server route bundles. String connector ids still work here because the loaders import discovery dynamically at call time.
• @little-stack/harness/connectors — everything above plus the discovery helpers (discoverConnectors, loadConnectorDescriptor, loadConnectorToolExtensions, loadConnectorToolExtensionsFromDir) and the attachment and reaction helpers listed under Attachment and reaction helpers. A value import statically links the discovery module (and its connector-module traversal) into the graph.
• @little-stack/harness/connectors/discovery — just the discovery helpers.

A route that needs no connector code imports streamHarness from the root entry.

Other subpaths

• @little-stack/harness/sandbox — for writing your own sandbox: createShellRuntime, createEnvironmentToolBridge, createRuntimeToolBridge, localSessionWorkspace, resolveSandbox, the just-bash building blocks, tracked-mount helpers (snapshotTrackedMounts, emitTrackedMountFileChanges) and tier-0 command classification (classifyCommand, detectEmulationGap, tier0CapabilityMatrix). See Sandboxes.
• @little-stack/harness/host — for writing or tuning a host: createInMemoryOrchestrationServices, createDurableOrchestrationServices, the durable stores, resolveLocalHostPaths, LocalSessionStore and LocalSessionQueue, LocalHarnessSession, sessionKeyToPathKey, and the local trace readers (readLocalTrace, listLocalSessions, doctorSession, …). See Local Host.
• @little-stack/harness/events — the durable event contract for a custom session log: HarnessSessionLog, DurableHarnessEventInput, PersistedDurableHarnessEvent, createHarnessAppendIdempotencyKey, canonicalHarnessEventRequestDigest, normalizePersistedDurableHarnessEvent, emitHarnessOccurrence, the event names (HARNESS_EVENT_TYPES, isHarnessEventType, and the side-channel equivalents), the HARNESS_SESSION_EVENT_* schema versions, and their errors. See Events.
• @little-stack/harness/remote-session — ready-made session logs and the remote session-log service: fileSessionLog, inMemorySessionLog, remoteSessionLog, startSessionLogServer, createHarnessFileMutationEvents, and the lh.remote-session.v1 protocol helpers (REMOTE_SESSION_LOG_PROTOCOL_VERSION, RemoteSessionProtocolError).
• @little-stack/harness/agents — experimental: the Agent Group launcher port (HarnessAgentGroupLauncher), its request/result types, the HarnessAgentGroup*Error classes, the HARNESS_AGENT_GROUPS_PROTOCOL_VERSION / HARNESS_AGENT_GROUP_PAGES_PROTOCOL_VERSION constants, and the task-ledger projection types. See Agent Groups.
• @little-stack/harness/scaffold — what little-harness init/new use: initWorkspace, scaffoldAgent, scaffoldProject, renderAgentSource, resolveProvider, resolveModelChoice, and the pinned dependency table scaffoldDependencyVersions() / providerDependency().
• @little-stack/harness/workflow-harness — the Little Workflow harness adapter.
• @little-stack/harness/internals — what Little Workflow and Little Compute build on (hashing and id helpers, skill and MCP resolution, workflow-tool plumbing, folder discovery). It has no stability promise: names can change in any release. Apps should not import from it.
• @little-stack/harness/package.json — exported for tooling. Every entry uses the default export condition, so require() works through Node's require(esm).

A string connector reference is the shortest way for a route to opt into connector folder discovery:

const supportSlack = await loadChatSdkConnector({
  agentDir: "agents/support",
  connector: "slack",
});

That lets Little Harness load agents/support/connectors/slack/connector.ts, discover agents/support/connectors/slack/tools/* extensions, and attach the active endpoint to the portable session registry. A statically imported descriptor object plus connectorId is functionally equivalent — the same folder discovery, session attachment, and mirror delivery — and it is the typed option: a descriptor reference infers TExtraBody (and TUser for web-rich), while a string reference is typed unknown. Choose per route; neither form is universally preferred.

Portable connector registry updates are serialized within one runtime process. If your deployment can process the same session on multiple serverless instances, add host-level locking or compare-and-swap around session file writes before treating connector attachment as globally atomic.

Common Flow

import { openai } from "@ai-sdk/openai";
import type { UIMessage } from "ai";
import { createHarness, localHost, skill, streamHarness } from "@little-stack/harness";

const harness = createHarness({
  host: localHost({ dataDir: ".little-harness" }),
  model: openai("gpt-5"),
  system: "Answer account questions using the tools available to you.",
  tools: { searchDocs, queryCustomers },
  skills: [
    skill("./skills/account-research"),
    skill("https://github.com/anthropics/skills", {
      skills: ["frontend-design"],
    }),
  ],
});

export async function POST(req: Request) {
  const { messages, chatId, extraBody }: {
    messages: UIMessage[];
    chatId: string;
    extraBody: { userId: string; teamId: string };
  } = await req.json();

  const result = streamHarness({
    harness,
    messages,
    session: chatId,
    extraBody,
  });

  return result.toUIMessageStreamResponse();
}

For a final-result caller, use the same harness with generateHarness().

import { Output } from "ai";
import { generateHarness } from "@little-stack/harness";

const result = await generateHarness({
  harness,
  type: "account.renewal_brief",
  input: { accountId: "acct_123" },
  output: Output.object({ schema: renewalBriefSchema }),
  session: "acct_123-renewal",
});

if (result.status === "completed") {
  console.log(result.output.risks);
}
console.log(result.trace.id);
console.log(result.trace.path);

Trace Policy

Tracing is enabled by default for Local Host. Developers can tune capture limits on createHarness() and override them per run:

const harness = createHarness({
  host: localHost({ dataDir: ".little-harness" }),
  model,
  system,
  tools,
  trace: {
    content: {
      previewBytes: 512,
      maxInlineBytes: 16 * 1024,
    },
    fileDiffs: {
      enabled: true,
      maxInlineBytes: 8 * 1024,
      maxBytesToDiff: 256 * 1024,
    },
    redaction: {
      metadataKeys: ["authorization", "cookie", "token", "password", "secret"],
      paths: ["/persistent/company/secrets"],
    },
  },
});

await generateHarness({
  harness,
  type: "account.renewal_brief",
  input: { accountId: "acct_123" },
  trace: {
    content: {
      maxInlineBytes: 4096,
    },
  },
});

Set trace: false at the harness or run level to disable trace persistence for that scope.

Mental Model

The execution APIs share the same runtime machinery:

createHarness(config)
streamHarness(...) or generateHarness(...)
-> create or resume session
-> load Persistent Dirs
-> stage message/input files
-> run model and tools
-> write session files and artifacts
-> commit Persistent Dirs
-> return stream/result + trace metadata

The important part is that streaming and non-streaming calls do not create two different products. They are two ways to run the same harness.

Connector Reference

Field-by-field reference for the connector descriptor and loader option surface. See Chat Connectors for the guided walkthrough.

Exactly two connector kinds exist today — "chat-sdk" and "web-rich" — and the ConnectorKind union is closed in this alpha. chatSdkConnector(...) produces the first; webRichConnector(...) produces the second. emailConnector(...) is a "chat-sdk" descriptor with email defaults.

ChatSdkConnectorOptions

Passed to chatSdkConnector(options).

Chat-sdk has no afterRun and no transport option (the transport field was removed).

EmailConnectorOptions

Passed to emailConnector(options). Every ChatSdkConnectorOptions field except triggers and reactions (set for email), plus the fields below. userName becomes optional. See Email Connector for the guided walkthrough.

EmailSkipReason is "automated" | "not-addressed" | "sender-not-allowed" | "dmarc-not-passed" | "other-sender" | "reply-limit" | "duplicate" | "rejected". The email helpers readInboundEmail, parseEmailAddress, automatedEmailReason, senderAllowed, dmarcResult, authenticationResults, and stripQuotedReply are exported alongside. Unverified in this alpha: no real email has been received through Resend Inbound yet, and whether Resend adds Authentication-Results (and its authserv-id) is unconfirmed.

WebRichConnectorOptions

Passed to webRichConnector(options).

ConnectorHistoryPolicy

"latest" | { source: "thread"; limit; fallback? } | { source: "transcript"; limit; fallback? } | (ctx) => Promise<UIMessage[]>

• "latest" — only the inbound message.
• source: "thread" — up to limit messages from the thread (iterated newest-first, returned oldest-first). Honors fallback: "latest"; without a fallback, an unavailable thread throws Thread history is unavailable. with { adapterName, threadId }.
• source: "transcript" — Chat SDK transcripts for the message's userKey. Honors fallback.
• For thread/transcript, the inbound message is appended (matched by id) if the source omits it.
• A custom callback owns history entirely and receives the run context without messages.

Delivery

ConnectorDeliveryOptions (the loader delivery option):

ConnectorTextDeliverer receives { session, sessionId, text, target, active, extraBody? }. Resolution order per target: explicit deliverers[connectorId] → target descriptor deliver (loaded lazily by id, cached) → skip. Sibling-load failures call onError and skip that target.

Loaders and loaded connectors

LoadChatSdkConnectorOptions: { agentDir, connector (string | descriptor), loadHarness?, createChat?, streamHarness?, loadConnectorToolExtensions?, connectorId?, delivery? }. A descriptor object infers TExtraBody; a string reference is typed unknown.

LoadedChatSdkConnector: { chat, adapter, webhook(request, options?), adapterName, harness, descriptor, simulateInbound(args), close() }. descriptor is the resolved descriptor typed to the same TExtraBody; simulateInbound drives a synthetic turn for tests (see Testing Connectors).

LoadWebRichConnectorOptions: { agentDir, connector, loadHarness?, streamHarness?, loadConnectorToolExtensions?, connectorId?, delivery?, waitUntil? }. waitUntil keeps the fire-and-forget afterRun/mirror-delivery work alive on serverless hosts (there is no createChat here). LoadedWebRichConnector: { POST(request), harness, descriptor, connectorId?, close() }.

Loading a descriptor object without connectorId logs one console.warn per loadChatSdkConnector/loadWebRichConnector call and disables folder tools, session attachment, and mirror delivery.

Chat SPI (ChatSdkChatLike / ChatSdkChatConstructor)

Chat SDK connectors do not depend on a concrete Chat class — they depend on a structural contract, so a real adapter, a custom Chat, or a test double are interchangeable. loadChatSdkConnector builds the chat by calling a ChatSdkChatConstructor (new (config: Record<string, unknown>) => ChatSdkChatLike), and a ChatSdkChatLike implementation must provide:

createChat is a loader option on LoadChatSdkConnectorOptions — pass a ChatSdkChatConstructor (for example createTestChat()) to substitute the Chat implementation for a whole loaded connector. There is intentionally no descriptor-level createChat: the Chat is a runtime/host concern, so the substitution point is the loader, not the portable chatSdkConnector(...) descriptor. See Testing Connectors for the createTestChat / createTestThread / createTestMessage doubles that satisfy these types cast-free.

Web-rich HTTP error semantics

On a pre-stream failure POST calls the descriptor onError (best-effort) and returns a status response:

• 400 — body is not JSON or is missing id / messages.
• 401 — authenticate returned null.
• 500 — any other error during history/streamHarness/attachment.

The response body depends on the environment: outside production (process.env.NODE_ENV !== "production") the failure text is included in the body so a broken route is debuggable straight from the client; in production the response stays bodyless so internal error messages are never leaked to end users. When the descriptor declares no onError, the route also logs a single-line console.error (little-harness: web-rich route error (phase=…, status=…): …) so a failing route is never completely silent — this default log is unconditional, not dev-only.

Errors thrown mid-stream — after the 200 response headers are already sent — cannot change the status code; they surface as an error chunk in the UI message stream. descriptor.onError is the observer escape hatch, and the client-facing error-chunk text is shaped by the uiMessageStream.onError option — passable on loadWebRichConnector (forwarded to streamHarness) as well as directly to streamHarness. Without one, the stream emits the generic "An error occurred.".

Session registry

Endpoints are recorded in /session/.harness/connectors.json. Exported from @little-stack/harness/connectors and .../runtime:

SessionConnectorRef is { connectorId, endpointId }; delivery states are active | passive | mirror | disabled. A corrupt registry file is preserved as connectors.recovered-*.json, reset to empty, and logged once via console.warn.

Attachment and reaction helpers

Exported from @little-stack/harness/connectors (not /runtime); the Chat SDK loader already uses them, so call them directly only when building a custom chat pipeline.

Tool-context helpers

These are exported from the root @little-stack/harness entry and from both connector subpaths. (UNRELEASED: the root export is in the current source only; published 0.2.0-alpha.0 exports them from the connector subpaths.)

import { tool } from "ai";
import { z } from "zod";
import { harnessToolContext } from "@little-stack/harness";

const saveNote = tool({
  description: "Save a note to the session workspace.",
  inputSchema: z.object({ text: z.string() }),
  execute: async ({ text }, options) => {
    const { files } = harnessToolContext(options);
    await files.writeText("/session/note.txt", text);
    return { saved: true };
  },
});

• harnessToolContext<TExtraBody>(options) — reads the harness execution context out of a tool's execute(input, options) second argument. Throws outside a harness run.
• tryHarnessToolContext<TExtraBody>(options) — same, but returns undefined outside a harness run.
• HarnessToolCallContext<TExtraBody> = ToolExecutionOptions & HarnessToolExecutionContext<TExtraBody>. ctx.connector?.endpoint is a typed SessionConnectorEndpoint.

streamHarness connector options

streamHarness accepts connector (active connector identity), connectorTools (resolved connectors/<id>/tools/*), and toolPolicy. The loaders set these automatically; see streamHarness().

Related Guides

• Generating And Streaming shows complete route, worker, and callback examples.
• Chat Connectors explains Chat SDK platform connectors, web text mode, web-rich mode, and typed tool UI helpers.
• Email Connector gives an agent its own email address.
• Memory shows opt-in long-term memory the agent keeps as plain files, in one folder or in layers.
• Message Files explains uploaded chat files.
• Input Types explains non-chat type + input calls.
• Local Host documents local sessions, local storage, localDir(), and projectDir().
• CLI Reference documents the scaffolding, test, and read-only inspection commands.
• Execution Environments and Execution Tiers document where commands run.
• Outcome Capture documents outcome reporting and aggregation.
• Events documents the HarnessEvent envelope, durable replay payload shape, and event vocabulary.
• Persistent Dir Reference documents cross-session storage callbacks.