@skarmy/agent-sdk

The SDK for building Skarmy agents. It provides the container supervisor entrypoint, buffered event emission, and typed HTTP clients for the hub's session-scoped endpoints.

Install

npm install @skarmy/agent-sdk

Usage

An agent's container entry wires its run function through the supervisor, which parses the run config written by the hub, provides the event/files/search clients, and guarantees a crash emits an ERROR event plus an ERROR status before exit.

import { runContainerAgent } from "@skarmy/agent-sdk";

runContainerAgent(async ({ config, events, files, search }) => {
  events.push({ sourceId: `${config.runId}:start`, kind: "STATUS", payload: { status: "RUNNING" } });
  // ...agent logic...
});

Exports

• container — runContainerAgent, the supervisor entrypoint.
• batcher — EventBatcher, interval-flushed event buffering.
• clients — FilesClient, SearchClient for hub endpoints.
• protocol / manifest / config — event, manifest, and run-config types (Zod schemas).
• prompt — prompt-runtime AgentDefinition types.
• @skarmy/agent-sdk/protocol — the protocol types alone, safe to import from a browser/client bundle (no Node deps).
• @skarmy/agent-sdk/contract-tests — the conformance checks every agent repo runs in CI (see below).

Contract tests

Every agent repo runs the SDK's contract tests in its own CI so protocol drift is caught at the source (spec §11). The checks are framework-agnostic — each throws on violation and returns void on success — so wrap them in whatever runner the repo uses:

import { describe, it } from "vitest";
import { checkPromptAgent, checkContainerAgent } from "@skarmy/agent-sdk/contract-tests";
import { manifest, definition } from "../src"; // your agent's artifacts

describe("contract", () => {
  it("conforms to the prompt-agent contract", () => {
    checkPromptAgent({ manifest, definition });
  });
});

Available checks: checkManifest, checkProtocolCompatible, checkEvents (per-kind payload validation, rejects hub-only kinds), checkConfigRoundTrips, and the composite checkPromptAgent / checkContainerAgent (the latter takes an optional sampleEvents array to validate a real event stream the agent emitted).

Versioning & compatibility policy (pre-1.0)

• PROTOCOL_VERSION (exported from protocol) is a single integer — the wire contract between the hub and every agent. It bumps only on a breaking protocol change (a new/removed event kind, a payload shape change, a RunConfig field change).
• The hub speaks exactly one protocol version at a time. An agent whose manifest protocolVersion differs from the hub's SDK is incompatible; checkProtocolCompatible fails its CI, and the hub refuses to pin it. There is no multi-version negotiation before 1.0.
• SDK package version is independent of PROTOCOL_VERSION. Additive SDK features (new helpers, a new client method, the contract-tests export) are minor/patch bumps and do not move PROTOCOL_VERSION. Only a wire change does.
• Agents pin an SDK range (^0.x) and re-run contract tests on every SDK bump. When PROTOCOL_VERSION changes, agents bump their protocolVersion to match and republish; the hub pins the new agent artifact in the same change.

License

MIT