SDK Reference

The @clawkernel/sdk package provides everything you need to build a CKP-conformant agent in TypeScript. It has zero runtime dependencies and handles the full protocol stack: JSON-RPC 2.0 routing, lifecycle state machine, heartbeat, and the L2 tool execution pipeline.

Installation

npm install @clawkernel/sdk

Current npm release: @clawkernel/[email protected].

Quick start

A working L1 agent in under 10 lines:

import { createAgent } from "@clawkernel/sdk";

const agent = createAgent({
  name: "my-agent",
  version: "1.0.0",
});

agent.listen(); // stdio JSON-RPC 2.0 — passes all 13 L1 vectors

That agent handles initialization, status queries, shutdown, heartbeat, and all error conditions required by L1.

Conformance coverage

The SDK supports all three conformance levels. What you configure determines your level:

Level	What you configure	Test vectors
L1	`name` + `version`	13/13
L2	+ `tools`, `policy`, `sandbox`, `quota`, `approval`	10/10
L3	+ `memory`, `swarm`	8/8

Current result: 31 PASS, 0 SKIP across all levels against the reconciled CKP harness matrix (L3 CONFORMANT).

In CKP 0.3.0, the SDK also exports manifest-facing types for richer Memory declarations and the optional WorldModel primitive. Those are schema-level/runtime-profile features; the SDK does not add new JSON-RPC world-model methods in this release.

API reference

`createAgent(options: AgentOptions): Agent`

Factory function that returns a configured Agent instance. Pass your configuration as a single options object and the SDK wires up all JSON-RPC handlers automatically.

Agent class

Method	Description
`listen()`	Start reading JSON-RPC messages from stdin
`close()`	Stop the heartbeat timer and close the transport

AgentOptions

Field	Type	Required	Level	Description
`name`	`string`	Yes	L1	Agent identity name
`version`	`string`	Yes	L1	Agent version (semver)
`heartbeatInterval`	`number`	No	L1	Heartbeat interval in ms (default: 30000, min: 1000, 0 to disable)
`tools`	`Record<string, ToolDefinition>`	No	L2	Tool registry
`policy`	`PolicyEvaluator`	No	L2	Policy gate
`sandbox`	`SandboxChecker`	No	L2	Sandbox gate
`quota`	`QuotaChecker`	No	L2	Quota gate
`approval`	`ApprovalConfig`	No	L2	Approval gate
`memory`	`MemoryHandler`	No	L3	Memory handler
`swarm`	`SwarmHandler`	No	L3	Swarm handler
`tasks`	`TaskHandler`	No	Interop	A2A task bridge (`claw.task.*`)

ToolDefinition

Each tool in the tools record must conform to this interface:

interface ToolDefinition {
  execute: (args: Record<string, unknown>) => Promise<ToolCallResult>;
  timeout_ms?: number; // Default: 30000
}

The execute function receives the parsed arguments and must return an object with a content array. If timeout_ms is exceeded, the SDK automatically returns a -32014 error.

GateResult

Returned by policy, sandbox, and quota evaluators to allow or deny a tool call:

interface GateResult {
  allowed: boolean;
  code?: number;    // CKP error code when denied
  message?: string; // Human-readable denial reason
}

Tool execution pipeline

Every claw.tool.call request flows through five gates in strict order:

quota -> policy -> sandbox -> exists -> approval -> execute (with timeout)

Each gate can reject the call with a specific error code. Gates run before tool existence is checked, so a denied tool never reveals whether it actually exists.

Error helpers

The SDK exports helper functions for all 11 CKP error codes. Use them when building custom handlers:

import {
  sendOk,
  sendError,
  policyDenied,
  ToolTimeoutError,
} from "@clawkernel/sdk";

Helper	Code	Description
`parseError`	-32700	Malformed JSON
`invalidRequest`	-32600	Invalid JSON-RPC envelope
`methodNotFound`	-32601	Unknown method
`invalidParams`	-32602	Missing or invalid params
`versionMismatch`	-32001	Protocol version mismatch
`sandboxDenied`	-32010	Sandbox blocked the call
`policyDenied`	-32011	Policy blocked the call
`approvalTimeout`	-32012	Approval not received in time
`approvalDenied`	-32013	Approval explicitly denied
`toolTimeout`	-32014	Tool execution timeout
`quotaExceeded`	-32021	Provider quota exceeded

The CKP_ERROR_CODES constant object is also exported with all code values.

Hardening

The SDK validates all incoming JSON-RPC messages with several safety mechanisms:

Type guards on every params field (no unsafe as casts internally)
State machine enforcement — methods like claw.tool.call are rejected before claw.initialize completes
Heartbeat bound — minimum interval of 1000ms to prevent CPU saturation
ToolTimeoutError class for reliable timeout detection instead of string comparison
request_id validation in the approval gate, rejecting missing or empty IDs
params type validation — arrays and primitives are rejected with -32602

Running conformance tests

# Clone and build the conformance harness
git clone https://github.com/angelgalvisc/ckp-test.git
cd ckp-test && npm install && npm run build

# Build SDK examples
cd ../clawkernel/sdk && npm run build:dev

# Run L3 vectors against the SDK example
node ../../ckp-test/dist/cli.js run \
  --target "node dist/examples/l3-agent.js" \
  --manifest examples/l3.claw.yaml \
  --level 3

# Expected: 31 PASS + 0 SKIP -> L3 CONFORMANT

See the Testing page for full details on the conformance harness.