@kb-labs/agent-sdk 0.6.0

package/dist/loop-BeFjNV2F.d.ts

@@ -0,0 +1,379 @@
+import { LLMTier, IterationSnapshot, RunEvaluation } from '@kb-labs/agent-contracts';
+import { LLMMessage, LLMTool } from '@kb-labs/sdk';
+
+/**
+ * AgentEventBus — typed pub/sub for passive observers.
+ *
+ * EventBus is for observers that don't affect execution flow.
+ * For flow control, use AgentMiddleware instead.
+ *
+ * Policies (enforced by agent-core implementation):
+ *   - bounded queue: max 1000 pending async handlers
+ *   - max recursion depth: 1 (emit inside handler does not recurse)
+ *   - error isolation: handler throw does not break other handlers
+ *   - async handler timeout: 5000ms (configurable per handler)
+ */
+
+interface AgentEvents {
+    'run:start': {
+        task: string;
+        tier: LLMTier;
+    };
+    'run:end': {
+        success: boolean;
+        totalTokens: number;
+        durationMs: number;
+        stopReason: string;
+    };
+    'iteration:start': {
+        iteration: number;
+        maxIterations: number;
+    };
+    'iteration:end': {
+        iteration: number;
+    };
+    'llm:start': {
+        iteration: number;
+        messageCount: number;
+        toolCount: number;
+        systemPromptChars: number;
+    };
+    'llm:end': {
+        iteration: number;
+        promptTokens: number;
+        completionTokens: number;
+        stopReason: string;
+        hasToolCalls: boolean;
+        toolCallCount: number;
+        durationMs: number;
+        content?: string;
+    };
+    'tool:start': {
+        iteration: number;
+        toolName: string;
+        input: Record<string, unknown>;
+    };
+    'tool:end': {
+        iteration: number;
+        toolName: string;
+        success: boolean;
+        durationMs: number;
+        outputLength: number;
+        output?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** Generic middleware decision event — emitted by any middleware into the bus */
+    'middleware:event': {
+        name: string;
+        event: string;
+        data: Record<string, unknown>;
+    };
+    /** Debug-only: full LLM prompt + response (emitted when RunContext.debug = true) */
+    'llm:debug': {
+        iteration: number;
+        systemPrompt: string;
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        responseContent: string;
+    };
+    'escalate': {
+        fromTier: LLMTier;
+        toTier: LLMTier;
+        reason: string;
+    };
+    'abort': {
+        reason: string;
+    };
+    'spawn': {
+        profileId: string;
+        childRunId: string;
+    };
+}
+type Unsubscribe = () => void;
+interface AgentEventBus {
+    emit<K extends keyof AgentEvents>(event: K, data: AgentEvents[K]): void;
+    /** Subscribe with a synchronous handler */
+    on<K extends keyof AgentEvents>(event: K, handler: (data: AgentEvents[K]) => void): Unsubscribe;
+    /** Subscribe with an async handler (subject to timeout policy) */
+    onAsync<K extends keyof AgentEvents>(event: K, handler: (data: AgentEvents[K]) => Promise<void>): Unsubscribe;
+    /** Wait for all pending async handlers to settle */
+    drain(): Promise<void>;
+    /** Remove all subscriptions */
+    clear(): void;
+}
+
+/**
+ * Execution context objects for the Agent SDK.
+ *
+ * Each context carries only what that layer needs — no `this` references,
+ * no god-object coupling. Low coupling = easy mocking in tests.
+ *
+ * Key invariant: RunContext.messages is readonly.
+ * The only way to append to history is via LoopContext.appendMessage().
+ */
+
+interface ContextMeta {
+    get<T>(namespace: string, key: string): T | undefined;
+    set<T>(namespace: string, key: string, value: T): void;
+    /** Returns shallow copy of the namespace map */
+    getNamespace(namespace: string): Record<string, unknown>;
+}
+interface RunContext {
+    /** Current task string */
+    task: string;
+    /** Current LLM tier */
+    tier: LLMTier;
+    /**
+     * Conversation messages — readonly.
+     * Append only via LoopContext.appendMessage() to prevent accidental mutation.
+     */
+    readonly messages: ReadonlyArray<LLMMessage>;
+    /** Available tools for this run */
+    tools: LLMTool[];
+    /** Current iteration number (1-based) */
+    iteration: number;
+    /** Maximum iterations allowed */
+    maxIterations: number;
+    /** Whether abort was requested */
+    aborted: boolean;
+    /** AbortSignal — mandatory, for graceful cancel propagation */
+    abortSignal: AbortSignal;
+    /** Unique run ID — used for tracing and linking sub-agent spans */
+    requestId: string;
+    /** Optional hard deadline (unix ms). Enforcement is middleware's responsibility. */
+    deadlineMs?: number;
+    /** Session ID (if any) */
+    sessionId?: string;
+    /** Namespaced side-channel metadata for middleware */
+    meta: ContextMeta;
+    /** Event bus for middleware-to-middleware and middleware-to-observer communication */
+    eventBus: AgentEventBus;
+    /** Debug mode: middleware emit full prompts/responses via llm:debug events */
+    debug: boolean;
+}
+interface LLMCtx {
+    run: RunContext;
+    /** Messages to send — may be patched by beforeLLMCall middleware */
+    messages: LLMMessage[];
+    /** Tools available for this call */
+    tools: LLMTool[];
+    /** Tier-specific temperature override */
+    temperature?: number;
+}
+interface LLMCallPatch {
+    messages?: LLMMessage[];
+    tools?: LLMTool[];
+    temperature?: number;
+    /** Force a specific tool choice. Use to require the LLM to call a specific tool. */
+    toolChoice?: 'auto' | 'required' | 'none' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+}
+interface LLMCallResult {
+    content: string;
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    /** LLM stop reason: 'end_turn' | 'tool_use' | 'max_tokens' | undefined */
+    stopReason?: string;
+}
+interface ToolCallInput {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolOutput {
+    toolCallId: string;
+    output: string;
+    success: boolean;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ToolExecCtx {
+    run: RunContext;
+    /** Tool name being executed */
+    toolName: string;
+    /** Raw tool input from LLM */
+    input: Record<string, unknown>;
+    /** Iteration in which the tool is being called */
+    iteration: number;
+    /** AbortSignal inherited from run — for cancelling long-running tool calls */
+    abortSignal: AbortSignal;
+    /** Same as run.requestId — for cross-referencing in traces */
+    requestId: string;
+}
+
+/**
+ * Middleware interface for the Agent SDK.
+ *
+ * Middleware hooks into the execution pipeline at well-defined points.
+ * Implement only the hooks you need — all are optional.
+ *
+ * Ordering:
+ *   before-hooks (onStart, beforeIteration, beforeLLMCall, beforeToolExec) — ascending order
+ *   after-hooks (afterToolExec, afterLLMCall, afterIteration, onStop, onComplete) — descending order
+ *
+ * Fail policies:
+ *   'fail-open'  — if middleware throws, log and continue (default, for observers)
+ *   'fail-closed' — if middleware throws, stop the run (for critical guards)
+ */
+
+type ControlAction = 'continue' | 'stop' | 'escalate';
+interface AgentMiddleware {
+    /** Unique name for logging and deduplication */
+    name: string;
+    /**
+     * Execution order. Lower = runs first in before-hooks, last in after-hooks.
+     * Core middlewares: 0–99. Custom: 100+.
+     */
+    order: number;
+    config?: {
+        /** On error: continue silently ('fail-open') or stop run ('fail-closed'). Default: 'fail-open' */
+        failPolicy: 'fail-open' | 'fail-closed';
+        /** Hook timeout in ms (0 = no timeout). Default: 5000 */
+        timeoutMs?: number;
+    };
+    /** Called once at pipeline construction — if returns false, middleware is skipped entirely */
+    enabled?(): boolean;
+    /** Called once when the run starts, before the first iteration */
+    onStart?(ctx: RunContext): Promise<void> | void;
+    /** Called when the run ends for any reason (complete, abort, error) */
+    onStop?(ctx: RunContext, reason: string): Promise<void> | void;
+    /** Called only on successful completion, after onStop */
+    onComplete?(ctx: RunContext): Promise<void> | void;
+    /**
+     * Called before each iteration.
+     * Return 'stop' to end the run early.
+     * Return 'escalate' to trigger tier escalation.
+     * Return 'continue' (or undefined) to proceed normally.
+     */
+    beforeIteration?(ctx: RunContext): Promise<ControlAction> | ControlAction;
+    /** Called after each iteration — useful for metrics, logging, snapshots */
+    afterIteration?(ctx: RunContext): Promise<void> | void;
+    /**
+     * Called before the LLM API call.
+     * Returns a patch of what to change in the request (messages, tools, temperature).
+     * Returning undefined (or empty object) = no change.
+     * Patches from all middlewares are merged in order.
+     */
+    beforeLLMCall?(ctx: LLMCtx): Promise<LLMCallPatch | undefined> | LLMCallPatch | undefined;
+    /** Called after the LLM responded. Read-only — cannot modify the response. */
+    afterLLMCall?(ctx: LLMCtx, result: LLMCallResult): Promise<void> | void;
+    /**
+     * Called before each tool execution.
+     * Return 'skip' to prevent the tool from running (output will be empty).
+     * Return 'execute' (or undefined) to proceed.
+     */
+    beforeToolExec?(ctx: ToolExecCtx): Promise<'execute' | 'skip'> | 'execute' | 'skip';
+    /** Called after each tool execution (even if skipped or errored) */
+    afterToolExec?(ctx: ToolExecCtx, result: ToolOutput): Promise<void> | void;
+}
+/**
+ * Extend this to implement only the hooks you need.
+ *
+ * @example
+ * class RateLimitMiddleware extends BaseMiddleware {
+ *   name = 'rate-limit';
+ *   order = 50;
+ *
+ *   async beforeIteration(ctx: RunContext): Promise<ControlAction> {
+ *     if (this.isOverLimit()) return 'stop';
+ *     return 'continue';
+ *   }
+ * }
+ */
+declare abstract class BaseMiddleware implements AgentMiddleware {
+    abstract name: string;
+    abstract order: number;
+    config: {
+        failPolicy: "fail-open";
+    };
+}
+
+/**
+ * ExecutionLoop — the iteration engine of an agent run.
+ *
+ * LoopContext provides only infrastructure primitives:
+ *   - appendMessage()  — the only way to mutate message history
+ *   - callLLM()        — makes the LLM call (with middleware pipeline applied)
+ *   - executeTools()   — executes tool calls (guards + output processors applied)
+ *
+ * Business logic (stop conditions, report detection, result building)
+ * lives in the ExecutionLoop implementation (LinearExecutionLoop in agent-core),
+ * not in LoopContext. This keeps the contract minimal and testable.
+ *
+ * Built-in: LinearExecutionLoop (agent-core)
+ * Custom example: GraphExecutionLoop (parallel branches)
+ */
+
+interface LoopContext {
+    run: RunContext;
+    /**
+     * The only way to append messages to history.
+     * Enforces the readonly constraint on RunContext.messages.
+     */
+    appendMessage(message: LLMMessage): void;
+    /**
+     * Makes the LLM call with the current context.
+     * Applies beforeLLMCall / afterLLMCall middleware pipeline internally.
+     */
+    callLLM(): Promise<LLMCallResult>;
+    /**
+     * Executes a batch of tool calls.
+     * Applies guard pipeline + output processors internally.
+     */
+    executeTools(calls: ToolCallInput[]): Promise<ToolOutput[]>;
+    /**
+     * Evaluates run progress after a meaningful iteration using structured loop signals.
+     * ExecutionLoop uses this to decide whether to continue, narrow scope, or synthesize.
+     */
+    evaluateRun(snapshot: IterationSnapshot): Promise<RunEvaluation | null>;
+    /**
+     * Runs beforeIteration middleware hooks.
+     * Returns 'continue', 'stop', or 'escalate'.
+     */
+    beforeIteration(): Promise<ControlAction>;
+    /**
+     * Runs afterIteration middleware hooks.
+     * Should be called at the end of every iteration (before checking stop conditions
+     * that return early, call this just before returning).
+     */
+    afterIteration(): Promise<void>;
+}
+interface LoopOutput {
+    /** Final answer text (from report tool or last LLM response) */
+    answer: string;
+    /** Machine-readable stop reason */
+    reasonCode: string;
+    /** Whether the loop completed successfully */
+    success: boolean;
+    /** Extra metadata from the stop condition */
+    metadata?: Record<string, unknown>;
+}
+type LoopResult = {
+    outcome: 'complete';
+    result: LoopOutput;
+} | {
+    outcome: 'escalate';
+    reason: string;
+} | {
+    outcome: 'handoff';
+    toAgent: string;
+    context: unknown;
+};
+interface ExecutionLoop {
+    run(ctx: LoopContext): Promise<LoopResult>;
+}
+
+export { type AgentMiddleware as A, BaseMiddleware as B, type ContextMeta as C, type ExecutionLoop as E, type LLMCallResult as L, type RunContext as R, type ToolExecCtx as T, type Unsubscribe as U, type LLMCtx as a, type LLMCallPatch as b, type ToolCallInput as c, type ToolOutput as d, type ControlAction as e, type LoopContext as f, type LoopOutput as g, type LoopResult as h, type AgentEvents as i, type AgentEventBus as j };

package/dist/testing.d.ts

@@ -0,0 +1,42 @@
+import { C as ContextMeta, R as RunContext, a as LLMCtx, T as ToolExecCtx, L as LLMCallResult, d as ToolOutput, f as LoopContext, A as AgentMiddleware, e as ControlAction } from './loop-BeFjNV2F.js';
+import '@kb-labs/agent-contracts';
+import '@kb-labs/sdk';
+
+/**
+ * @kb-labs/agent-sdk/testing
+ *
+ * Ready-made mock helpers for testing agent-core, plugins, and any code
+ * that works with SDK types. Import from this sub-path — never from main index.
+ *
+ * @example
+ *   import { makeRunCtx, makeLoopCtx, makeLLMResponse } from '@kb-labs/agent-sdk/testing';
+ *
+ * All helpers use vitest's `vi.fn()` — vitest must be available in the test env.
+ */
+
+declare function makeMeta(): ContextMeta & {
+    _store: Map<string, Map<string, unknown>>;
+};
+declare function makeRunCtx(overrides?: Partial<RunContext>): RunContext;
+declare function makeLLMCtx(runCtx?: RunContext, overrides?: Partial<LLMCtx>): LLMCtx;
+declare function makeToolExecCtx(runCtx?: RunContext, overrides?: Partial<ToolExecCtx>): ToolExecCtx;
+declare function makeLLMResponse(overrides?: Partial<LLMCallResult>): LLMCallResult;
+/** Shorthand: LLM response that calls the report tool */
+declare function makeReportResponse(answer: string): LLMCallResult;
+declare function makeToolOutput(overrides?: Partial<ToolOutput>): ToolOutput;
+interface LoopCtxOptions {
+    run?: RunContext;
+    /** Sequential LLM responses — each call pops the next one */
+    llmResponses?: LLMCallResult[];
+    /** Tool outputs returned by executeTools */
+    toolOutputs?: ToolOutput[];
+}
+declare function makeLoopCtx(opts?: LoopCtxOptions): LoopContext;
+declare function makeMiddleware(overrides: Partial<AgentMiddleware> & {
+    name: string;
+    order: number;
+}): AgentMiddleware;
+/** Middleware that always returns a fixed ControlAction from beforeIteration */
+declare function makeControlMiddleware(name: string, order: number, action: ControlAction): AgentMiddleware;
+
+export { type LoopCtxOptions, makeControlMiddleware, makeLLMCtx, makeLLMResponse, makeLoopCtx, makeMeta, makeMiddleware, makeReportResponse, makeRunCtx, makeToolExecCtx, makeToolOutput };

package/dist/testing.js

@@ -0,0 +1,114 @@
+import { vi } from 'vitest';
+
+// src/testing.ts
+function makeMeta() {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    _store: store,
+    get: vi.fn(
+      (ns, key) => store.get(ns)?.get(key)
+    ),
+    set: vi.fn((ns, key, value) => {
+      if (!store.has(ns)) {
+        store.set(ns, /* @__PURE__ */ new Map());
+      }
+      store.get(ns).set(key, value);
+    }),
+    getNamespace: vi.fn(
+      (ns) => Object.fromEntries(store.get(ns) ?? /* @__PURE__ */ new Map())
+    )
+  };
+}
+function makeRunCtx(overrides = {}) {
+  return {
+    task: "test task",
+    tier: "medium",
+    messages: [],
+    tools: [],
+    iteration: 0,
+    maxIterations: 20,
+    aborted: false,
+    abortSignal: new AbortController().signal,
+    requestId: "req-test",
+    meta: makeMeta(),
+    ...overrides
+  };
+}
+function makeLLMCtx(runCtx, overrides = {}) {
+  return {
+    run: runCtx ?? makeRunCtx(),
+    messages: [{ role: "user", content: "hello" }],
+    tools: [],
+    ...overrides
+  };
+}
+function makeToolExecCtx(runCtx, overrides = {}) {
+  const run = runCtx ?? makeRunCtx();
+  return {
+    run,
+    toolName: "fs_read",
+    input: {},
+    iteration: run.iteration,
+    abortSignal: run.abortSignal,
+    requestId: run.requestId,
+    ...overrides
+  };
+}
+function makeLLMResponse(overrides = {}) {
+  return {
+    content: "",
+    toolCalls: [],
+    ...overrides
+  };
+}
+function makeReportResponse(answer) {
+  return makeLLMResponse({
+    toolCalls: [{ id: "tc-report", name: "report", input: { answer } }]
+  });
+}
+function makeToolOutput(overrides = {}) {
+  return {
+    toolCallId: "tc-1",
+    output: "result",
+    success: true,
+    ...overrides
+  };
+}
+function makeLoopCtx(opts = {}) {
+  const run = opts.run ?? makeRunCtx();
+  const responses = [...opts.llmResponses ?? [makeLLMResponse()]];
+  let callIndex = 0;
+  return {
+    run,
+    appendMessage: vi.fn(),
+    callLLM: vi.fn(async () => {
+      const r = responses[callIndex] ?? makeLLMResponse();
+      callIndex++;
+      return r;
+    }),
+    executeTools: vi.fn(
+      async (_calls) => opts.toolOutputs ?? []
+    ),
+    evaluateRun: vi.fn(async () => null),
+    beforeIteration: vi.fn(async () => "continue"),
+    afterIteration: vi.fn(async () => {
+    })
+  };
+}
+function makeMiddleware(overrides) {
+  return {
+    config: { failPolicy: "fail-open" },
+    ...overrides
+  };
+}
+function makeControlMiddleware(name, order, action) {
+  return makeMiddleware({
+    name,
+    order,
+    beforeIteration: async () => action
+  });
+}
+
+export { makeControlMiddleware, makeLLMCtx, makeLLMResponse, makeLoopCtx, makeMeta, makeMiddleware, makeReportResponse, makeRunCtx, makeToolExecCtx, makeToolOutput };
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"names":[],"mappings":"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","file":"testing.js","sourcesContent":["/**\n * @kb-labs/agent-sdk/testing\n *\n * Ready-made mock helpers for testing agent-core, plugins, and any code\n * that works with SDK types. Import from this sub-path — never from main index.\n *\n * @example\n *   import { makeRunCtx, makeLoopCtx, makeLLMResponse } from '@kb-labs/agent-sdk/testing';\n *\n * All helpers use vitest's `vi.fn()` — vitest must be available in the test env.\n */\n\nimport { vi } from 'vitest';\nimport type { RunContext, ContextMeta, LLMCtx, LLMCallResult, ToolExecCtx, ToolOutput, ToolCallInput } from './contexts.js';\nimport type { LoopContext } from './loop.js';\nimport type { AgentMiddleware, ControlAction } from './middleware.js';\n\n// ─── ContextMeta mock ─────────────────────────────────────────────────────────\n\nexport function makeMeta(): ContextMeta & { _store: Map<string, Map<string, unknown>> } {\n  const store = new Map<string, Map<string, unknown>>();\n  return {\n    _store: store,\n    get: vi.fn((ns: string, key: string) =>\n      store.get(ns)?.get(key),\n    ) as ContextMeta['get'],\n    set: vi.fn((ns: string, key: string, value: unknown) => {\n      if (!store.has(ns)) {\n        store.set(ns, new Map());\n      }\n      store.get(ns)!.set(key, value);\n    }),\n    getNamespace: vi.fn((ns: string) =>\n      Object.fromEntries(store.get(ns) ?? new Map()),\n    ),\n  };\n}\n\n// ─── RunContext mock ──────────────────────────────────────────────────────────\n\nexport function makeRunCtx(overrides: Partial<RunContext> = {}): RunContext {\n  return {\n    task: 'test task',\n    tier: 'medium',\n    messages: [],\n    tools: [],\n    iteration: 0,\n    maxIterations: 20,\n    aborted: false,\n    abortSignal: new AbortController().signal,\n    requestId: 'req-test',\n    meta: makeMeta(),\n    ...overrides,\n  } as RunContext;\n}\n\n// ─── LLMCtx mock ─────────────────────────────────────────────────────────────\n\nexport function makeLLMCtx(runCtx?: RunContext, overrides: Partial<LLMCtx> = {}): LLMCtx {\n  return {\n    run: runCtx ?? makeRunCtx(),\n    messages: [{ role: 'user', content: 'hello' }],\n    tools: [],\n    ...overrides,\n  };\n}\n\n// ─── ToolExecCtx mock ─────────────────────────────────────────────────────────\n\nexport function makeToolExecCtx(\n  runCtx?: RunContext,\n  overrides: Partial<ToolExecCtx> = {},\n): ToolExecCtx {\n  const run = runCtx ?? makeRunCtx();\n  return {\n    run,\n    toolName: 'fs_read',\n    input: {},\n    iteration: run.iteration,\n    abortSignal: run.abortSignal,\n    requestId: run.requestId,\n    ...overrides,\n  };\n}\n\n// ─── LLMCallResult mock ───────────────────────────────────────────────────────\n\nexport function makeLLMResponse(overrides: Partial<LLMCallResult> = {}): LLMCallResult {\n  return {\n    content: '',\n    toolCalls: [],\n    ...overrides,\n  };\n}\n\n/** Shorthand: LLM response that calls the report tool */\nexport function makeReportResponse(answer: string): LLMCallResult {\n  return makeLLMResponse({\n    toolCalls: [{ id: 'tc-report', name: 'report', input: { answer } }],\n  });\n}\n\n// ─── ToolOutput mock ──────────────────────────────────────────────────────────\n\nexport function makeToolOutput(overrides: Partial<ToolOutput> = {}): ToolOutput {\n  return {\n    toolCallId: 'tc-1',\n    output: 'result',\n    success: true,\n    ...overrides,\n  };\n}\n\n// ─── LoopContext mock ─────────────────────────────────────────────────────────\n\nexport interface LoopCtxOptions {\n  run?: RunContext;\n  /** Sequential LLM responses — each call pops the next one */\n  llmResponses?: LLMCallResult[];\n  /** Tool outputs returned by executeTools */\n  toolOutputs?: ToolOutput[];\n}\n\nexport function makeLoopCtx(opts: LoopCtxOptions = {}): LoopContext {\n  const run = opts.run ?? makeRunCtx();\n  const responses = [...(opts.llmResponses ?? [makeLLMResponse()])];\n  let callIndex = 0;\n\n  return {\n    run,\n    appendMessage: vi.fn(),\n    callLLM: vi.fn(async (): Promise<LLMCallResult> => {\n      const r = responses[callIndex] ?? makeLLMResponse();\n      callIndex++;\n      return r;\n    }),\n    executeTools: vi.fn(async (_calls: ToolCallInput[]): Promise<ToolOutput[]> =>\n      opts.toolOutputs ?? [],\n    ),\n    evaluateRun: vi.fn(async () => null),\n    beforeIteration: vi.fn(async () => 'continue' as const),\n    afterIteration: vi.fn(async () => {}),\n  };\n}\n\n// ─── AgentMiddleware mock ─────────────────────────────────────────────────────\n\nexport function makeMiddleware(\n  overrides: Partial<AgentMiddleware> & { name: string; order: number },\n): AgentMiddleware {\n  return {\n    config: { failPolicy: 'fail-open' },\n    ...overrides,\n  };\n}\n\n/** Middleware that always returns a fixed ControlAction from beforeIteration */\nexport function makeControlMiddleware(\n  name: string,\n  order: number,\n  action: ControlAction,\n): AgentMiddleware {\n  return makeMiddleware({\n    name,\n    order,\n    beforeIteration: async () => action,\n  });\n}\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kb-labs/agent-sdk",
+  "version": "0.6.0",
+  "type": "module",
+  "description": "Agent SDK — contracts and interfaces for composing agents. No logic, only types.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "types": "./dist/testing.d.ts"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@kb-labs/agent-contracts": "^0.6.0",
+    "@kb-labs/sdk": "^1.5.0",
+    "vitest": "^3.2.4"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}