@rarebit-one/harness-kernel 0.5.1

package/dist/loop.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Extension point 7 — the control loop itself.
+ *
+ * Every other seam in this kernel answers "which implementation?" for something
+ * the loop *uses*: a model, a route, a context source, a tool. The loop that
+ * ties them together was the one piece an application could not replace, so
+ * anything that needed different control flow — a plan-then-execute shape, a
+ * loop that pauses on `ToolMetadata.requiresConfirmation`, a loop that fans a
+ * step out to subagents — had to fork {@link runAgent} and inherit every future
+ * fix by hand.
+ *
+ * That gap is not hypothetical: `ToolMetadata` already declares
+ * `requiresConfirmation`, and `toolsRequiringConfirmation()` already selects
+ * for it, but a confirmation flow has to interpose between "the model asked for
+ * this tool" and "the tool ran" — the exact seam that did not exist. The
+ * metadata described a control-flow decision the kernel gave no way to make.
+ *
+ * The kernel still ships exactly one loop, `nativeLoop`, and it is the same
+ * code that has always run. This adds the interface around it, not an
+ * alternative to it.
+ */
+import type { LoopEventEmitter, RunEventEmitter, RunOutcome } from "./events.js";
+import type { ChatModel } from "./models/chat.js";
+import type { Tool } from "./tools/registry.js";
+/**
+ * One run's materials, resolved.
+ *
+ * Everything here is already decided: the model is bound (registry-resolved and
+ * middleware-wrapped if it was going to be), the prompts are built, the tool
+ * surface is projected, the budgets are numbers rather than optionals. A loop
+ * decides *control flow* and nothing else — which is what keeps a second
+ * implementation small enough to be worth writing.
+ */
+export interface LoopRequest {
+    model: ChatModel;
+    system: string;
+    userPrompt: string;
+    tools: Tool[];
+    limits: {
+        maxSteps: number;
+        maxDurationMs: number;
+    };
+}
+/**
+ * What a loop is given to talk to the outside world. Both are the same channels
+ * the rest of the kernel uses, so a loop needs no privileged access.
+ *
+ * `events` is an **emitter, not a raw sink**, and that distinction is the whole
+ * point: `seq` and `at` are the emitter's to stamp, so a loop physically cannot
+ * emit an unnumbered event and quietly break the gapless-sequence guarantee that
+ * makes a dropped event detectable. It is required rather than optional because
+ * `runEventEmitter(undefined)` is a working no-op — a loop never has to branch
+ * on whether anyone is listening.
+ *
+ * A loop emits only what happens *inside* it — turns, tool calls, budgets. The
+ * bookends are not its job, and the emitter's type says so: `LoopEventEmitter`
+ * excludes `run.started` and `run.finished`, so a loop cannot emit a duplicate
+ * start or a premature terminal event even by accident. See
+ * {@link runWithEvents}.
+ */
+export interface LoopContext {
+    log: (line: string) => void;
+    events: LoopEventEmitter;
+}
+/**
+ * What {@link runWithEvents} is given: the same shape, but with the unrestricted
+ * emitter, because the bookends are its job and nobody else's.
+ */
+export interface RunContext {
+    log: (line: string) => void;
+    events: RunEventEmitter;
+}
+/**
+ * What a loop returns.
+ *
+ * Richer than {@link runAgent}'s bare string on purpose: `outcome` and `steps`
+ * are facts the loop alone knows, and a caller that had to infer "did this
+ * finish or did it run out of budget?" from the prose would be guessing. The
+ * same two values appear on the `run.finished` event, and they must agree —
+ * the event stream and the return value are two views of one run, never two
+ * sources of truth.
+ */
+export interface LoopResult {
+    text: string;
+    steps: number;
+    /**
+     * Why the run stopped. The native loop never *returns* `"failed"` — that path
+     * throws, and the terminal event is emitted before the error propagates. The
+     * value is in the union because a custom loop may legitimately choose to
+     * report a failure rather than throw one.
+     */
+    outcome: RunOutcome;
+}
+/**
+ * A pluggable control loop. Implementations: the native tool-use loop, or an
+ * application's own.
+ *
+ * `name` exists for the same reason `AgentEngine.name` does — so a log line or
+ * an event can say which one ran. There is deliberately no `supports()`: a loop
+ * is handed materials that are already resolved, so there is no capability for
+ * it to refuse. An engine still refuses through its own `supports()`.
+ */
+export interface Loop {
+    readonly name: string;
+    run(req: LoopRequest, ctx: LoopContext): Promise<LoopResult>;
+}
+/**
+ * The kernel's one loop: the provider-neutral tool-use loop that `runAgent` has
+ * always run, behind the interface.
+ *
+ * This is the same code path, not a reimplementation — `runAgent` and
+ * `nativeLoop` both delegate to it, so there is no second behaviour to keep in
+ * sync and no way for the two to drift.
+ */
+export declare const nativeLoop: Loop;
+/**
+ * Run a loop with the run's bookend events emitted around it.
+ *
+ * The bookends belong HERE rather than inside any loop, because a loop that
+ * forgets them produces a run that appears never to have started — and after
+ * the loop became a seam, "any loop" includes ones this kernel has never seen.
+ * A guarantee that depends on every future implementor remembering it is not a
+ * guarantee. Both entry points — `runAgent` and `NativeEngine` — come through
+ * here, so the property holds no matter whose loop runs.
+ *
+ * On a throw it closes the stream with `outcome: "failed"` and then **rethrows
+ * the original error, untouched**. This changes what is observed, never what is
+ * thrown. `steps` and `text` are omitted on that path: the loop never returned
+ * a result, so there is no honest value for them.
+ */
+export declare function runWithEvents(loop: Loop, req: LoopRequest, ctx: RunContext): Promise<LoopResult>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAA;AAE/C;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;CACpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,MAAM,EAAE,gBAAgB,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,MAAM,EAAE,eAAe,CAAA;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,OAAO,EAAE,UAAU,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC7D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,IAGxB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,UAAU,CAAC,CA2BrB"}

package/dist/loop.js

@@ -0,0 +1,77 @@
+/**
+ * Extension point 7 — the control loop itself.
+ *
+ * Every other seam in this kernel answers "which implementation?" for something
+ * the loop *uses*: a model, a route, a context source, a tool. The loop that
+ * ties them together was the one piece an application could not replace, so
+ * anything that needed different control flow — a plan-then-execute shape, a
+ * loop that pauses on `ToolMetadata.requiresConfirmation`, a loop that fans a
+ * step out to subagents — had to fork {@link runAgent} and inherit every future
+ * fix by hand.
+ *
+ * That gap is not hypothetical: `ToolMetadata` already declares
+ * `requiresConfirmation`, and `toolsRequiringConfirmation()` already selects
+ * for it, but a confirmation flow has to interpose between "the model asked for
+ * this tool" and "the tool ran" — the exact seam that did not exist. The
+ * metadata described a control-flow decision the kernel gave no way to make.
+ *
+ * The kernel still ships exactly one loop, `nativeLoop`, and it is the same
+ * code that has always run. This adds the interface around it, not an
+ * alternative to it.
+ */
+import { runNativeLoop } from "./agent.js";
+/**
+ * The kernel's one loop: the provider-neutral tool-use loop that `runAgent` has
+ * always run, behind the interface.
+ *
+ * This is the same code path, not a reimplementation — `runAgent` and
+ * `nativeLoop` both delegate to it, so there is no second behaviour to keep in
+ * sync and no way for the two to drift.
+ */
+export const nativeLoop = {
+    name: "native",
+    run: (req, ctx) => runNativeLoop(req, ctx),
+};
+/**
+ * Run a loop with the run's bookend events emitted around it.
+ *
+ * The bookends belong HERE rather than inside any loop, because a loop that
+ * forgets them produces a run that appears never to have started — and after
+ * the loop became a seam, "any loop" includes ones this kernel has never seen.
+ * A guarantee that depends on every future implementor remembering it is not a
+ * guarantee. Both entry points — `runAgent` and `NativeEngine` — come through
+ * here, so the property holds no matter whose loop runs.
+ *
+ * On a throw it closes the stream with `outcome: "failed"` and then **rethrows
+ * the original error, untouched**. This changes what is observed, never what is
+ * thrown. `steps` and `text` are omitted on that path: the loop never returned
+ * a result, so there is no honest value for them.
+ */
+export async function runWithEvents(loop, req, ctx) {
+    ctx.events.emit({
+        type: "run.started",
+        maxSteps: req.limits.maxSteps,
+        maxDurationMs: req.limits.maxDurationMs,
+        tools: req.tools.map((t) => t.spec.name),
+    });
+    let result;
+    try {
+        result = await loop.run(req, ctx);
+    }
+    catch (err) {
+        ctx.events.emit({
+            type: "run.finished",
+            outcome: "failed",
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+    ctx.events.emit({
+        type: "run.finished",
+        outcome: result.outcome,
+        steps: result.steps,
+        text: result.text,
+    });
+    return result;
+}
+//# sourceMappingURL=loop.js.map

package/dist/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAyF1C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAS;IAC9B,IAAI,EAAE,QAAQ;IACd,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC;CAC3C,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,GAAgB,EAChB,GAAe;IAEf,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QACd,IAAI,EAAE,aAAa;QACnB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ;QAC7B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,aAAa;QACvC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;KACzC,CAAC,CAAA;IAEF,IAAI,MAAkB,CAAA;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAA;QACF,MAAM,GAAG,CAAA;IACX,CAAC;IAED,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QACd,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC,CAAA;IACF,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/models/chat.d.ts

@@ -0,0 +1,65 @@
+import type { AgentMessage, ConverseRequest, ConverseResult, Provider, ToolSpec } from "../providers/types.js";
+import { type ModelCaps, type ModelInvocation } from "./types.js";
+/**
+ * A reference to binary content a multimodal request carries. Inline base64 for
+ * content the caller already holds; a URL when the provider should fetch it.
+ */
+export type BinaryRef = {
+    kind: "base64";
+    mediaType: string;
+    data: string;
+} | {
+    kind: "url";
+    mediaType?: string;
+    url: string;
+};
+/**
+ * A non-text part of a chat request. Sending any of these requires
+ * `caps.multimodalInput`; a model that lacks it rejects the request rather than
+ * quietly dropping the attachment.
+ */
+export type ChatPart = {
+    type: "image";
+    source: BinaryRef;
+} | {
+    type: "audio";
+    source: BinaryRef;
+} | {
+    type: "binary";
+    source: BinaryRef;
+};
+/**
+ * The `chat` kind's request. It is the existing {@link ConverseRequest} plus an
+ * optional multimodal channel, so every current caller's request is already a
+ * valid `ChatRequest`.
+ */
+export interface ChatRequest extends ConverseRequest {
+    /** Attachments for the latest user turn. Requires `caps.multimodalInput`. */
+    parts?: ChatPart[];
+}
+/** The `chat` kind's result: prose plus the tool calls that drive the loop. */
+export type ChatResponse = ConverseResult;
+/** The `chat` kind's invocation type. */
+export type ChatModel = ModelInvocation<ChatRequest, ChatResponse>;
+/** The kind string every chat model registers under. */
+export declare const CHAT_KIND = "chat";
+/**
+ * Adapt a {@link Provider} onto the model seam as the `chat` kind.
+ *
+ * This wraps rather than rewrites: the provider's own `converse` still does the
+ * work, so the tool-use loop's behaviour is unchanged. What the wrapper adds is
+ * a uniform envelope, declared capabilities, and a place for middleware to sit —
+ * the same place a perception model sits.
+ *
+ * Capabilities are reported conservatively, from what the `Provider` interface
+ * can actually express: it has no streaming method, no attachment channel and
+ * reports no usage, so only `tools` is true. A richer adapter can declare more.
+ */
+export declare function chatModel(provider: Provider, caps?: Partial<ModelCaps>): ChatModel;
+/** True when a value is already a model invocation rather than a bare `Provider`. */
+export declare function isChatModel(value: Provider | ChatModel): value is ChatModel;
+/** Accept either a `Provider` or a `ChatModel` and always yield a `ChatModel`. */
+export declare function asChatModel(value: Provider | ChatModel): ChatModel;
+/** Build a `chat` request from the loop's working state. */
+export declare function chatRequest(system: string, messages: AgentMessage[], tools: ToolSpec[], parts?: ChatPart[]): ChatRequest;
+//# sourceMappingURL=chat.d.ts.map

package/dist/models/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/models/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,QAAQ,EACR,QAAQ,EACT,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,eAAe,EAErB,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAEzC;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,6EAA6E;IAC7E,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,cAAc,CAAA;AAEzC,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;AAElE,wDAAwD;AACxD,eAAO,MAAM,SAAS,SAAS,CAAA;AAE/B;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAiDtF;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,IAAI,SAAS,CAE3E;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAElE;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,QAAQ,EAAE,EACjB,KAAK,CAAC,EAAE,QAAQ,EAAE,GACjB,WAAW,CAEb"}

package/dist/models/chat.js

@@ -0,0 +1,66 @@
+import { requireCapability, } from "./types.js";
+/** The kind string every chat model registers under. */
+export const CHAT_KIND = "chat";
+/**
+ * Adapt a {@link Provider} onto the model seam as the `chat` kind.
+ *
+ * This wraps rather than rewrites: the provider's own `converse` still does the
+ * work, so the tool-use loop's behaviour is unchanged. What the wrapper adds is
+ * a uniform envelope, declared capabilities, and a place for middleware to sit —
+ * the same place a perception model sits.
+ *
+ * Capabilities are reported conservatively, from what the `Provider` interface
+ * can actually express: it has no streaming method, no attachment channel and
+ * reports no usage, so only `tools` is true. A richer adapter can declare more.
+ */
+export function chatModel(provider, caps = {}) {
+    const resolved = {
+        streaming: false,
+        tools: true,
+        multimodalInput: false,
+        usage: false,
+        ...caps,
+    };
+    return {
+        id: provider.name,
+        kind: CHAT_KIND,
+        caps: resolved,
+        async invoke(req, ctx) {
+            if (req.parts?.length) {
+                requireCapability({ id: provider.name, kind: CHAT_KIND, caps: resolved }, "multimodalInput", "request carries parts");
+            }
+            if (req.tools.length > 0) {
+                requireCapability({ id: provider.name, kind: CHAT_KIND, caps: resolved }, "tools", "request carries tool definitions");
+            }
+            ctx.signal?.throwIfAborted();
+            const value = await provider.converse({
+                system: req.system,
+                messages: req.messages,
+                tools: req.tools,
+            });
+            return { value };
+        },
+        // The `Provider` interface exposes no health endpoint, so report the honest
+        // answer rather than inventing an `up` — a probe that always says "fine" is
+        // worse than one that admits it doesn't know.
+        probe() {
+            return Promise.resolve({
+                status: "unknown",
+                detail: `provider ${provider.name} exposes no health endpoint`,
+            });
+        },
+    };
+}
+/** True when a value is already a model invocation rather than a bare `Provider`. */
+export function isChatModel(value) {
+    return "invoke" in value && "kind" in value && "caps" in value;
+}
+/** Accept either a `Provider` or a `ChatModel` and always yield a `ChatModel`. */
+export function asChatModel(value) {
+    return isChatModel(value) ? value : chatModel(value);
+}
+/** Build a `chat` request from the loop's working state. */
+export function chatRequest(system, messages, tools, parts) {
+    return { system, messages, tools, ...(parts?.length ? { parts } : {}) };
+}
+//# sourceMappingURL=chat.js.map

package/dist/models/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../src/models/chat.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,iBAAiB,GAMlB,MAAM,YAAY,CAAA;AAoCnB,wDAAwD;AACxD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAA;AAE/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,QAAkB,EAAE,OAA2B,EAAE;IACzE,MAAM,QAAQ,GAAc;QAC1B,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,IAAI;QACX,eAAe,EAAE,KAAK;QACtB,KAAK,EAAE,KAAK;QACZ,GAAG,IAAI;KACR,CAAA;IAED,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,IAAI;QACjB,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,QAAQ;QAEd,KAAK,CAAC,MAAM,CAAC,GAAgB,EAAE,GAAkB;YAC/C,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;gBACtB,iBAAiB,CACf,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,EACtD,iBAAiB,EACjB,uBAAuB,CACxB,CAAA;YACH,CAAC;YACD,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,iBAAiB,CACf,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,EACtD,OAAO,EACP,kCAAkC,CACnC,CAAA;YACH,CAAC;YACD,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAA;YAE5B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC;gBACpC,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,KAAK,EAAE,GAAG,CAAC,KAAK;aACjB,CAAC,CAAA;YACF,OAAO,EAAE,KAAK,EAAE,CAAA;QAClB,CAAC;QAED,4EAA4E;QAC5E,4EAA4E;QAC5E,8CAA8C;QAC9C,KAAK;YACH,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,YAAY,QAAQ,CAAC,IAAI,6BAA6B;aAC/D,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,WAAW,CAAC,KAA2B;IACrD,OAAO,QAAQ,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,CAAA;AAChE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,KAA2B;IACrD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AACtD,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,QAAwB,EACxB,KAAiB,EACjB,KAAkB;IAElB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AACzE,CAAC"}

package/dist/models/middleware.d.ts

@@ -0,0 +1,63 @@
+import { type Health, type HealthStatus, type InvokeContext, type ModelIdentity, type ModelInvocation, type ModelResult, type StreamSink } from "./types.js";
+/** A non-streaming invocation, with its payload types erased. */
+export type Invoker = (req: unknown, ctx: InvokeContext) => Promise<ModelResult<unknown>>;
+/** A streaming invocation, with its payload types erased. */
+export type StreamInvoker = (req: unknown, sink: StreamSink, ctx: InvokeContext) => Promise<ModelResult<unknown>>;
+/**
+ * A cross-cutting concern wrapped around an invocation.
+ *
+ * Middleware is deliberately payload-blind: it sees `unknown` in and
+ * `ModelResult<unknown>` out. That is the whole point — tracing, redaction,
+ * health tracking and budget enforcement are identical whether the call is a
+ * chat completion or an object-detection pass, so one implementation must cover
+ * both. A middleware that needs to know the payload type has stopped being
+ * cross-cutting and belongs in the kind's own implementation.
+ *
+ * Both hooks are optional: a middleware that only cares about buffered calls
+ * implements `invoke` and leaves streaming untouched.
+ */
+export interface Middleware {
+    readonly name: string;
+    invoke?: (next: Invoker, model: ModelIdentity) => Invoker;
+    invokeStream?: (next: StreamInvoker, model: ModelIdentity) => StreamInvoker;
+}
+/**
+ * Wrap an invocation in a middleware chain. The first entry is outermost, so
+ * `withMiddleware(m, [trace, redact])` runs trace's before-logic first and its
+ * after-logic last.
+ *
+ * The returned invocation keeps the original's `id`, `kind` and `caps`, and
+ * only exposes `invokeStream` when the original did — wrapping must never
+ * appear to add a capability the underlying model doesn't have.
+ */
+export declare function withMiddleware<Req, Res>(model: ModelInvocation<Req, Res>, middleware: Middleware[]): ModelInvocation<Req, Res>;
+/**
+ * Ensure every call carries a correlation id, minting one when the caller
+ * didn't supply it, so a whole chain of invocations shares a single id. Pass
+ * your own `mint` to adopt an ambient trace id from the surrounding request.
+ */
+export declare function correlationMiddleware(mint?: () => string): Middleware;
+/** Log each invocation's start, outcome and duration through `ctx.log`. */
+export declare function loggingMiddleware(): Middleware;
+/** Records per-model health derived from invocation outcomes. */
+export declare class HealthTracker {
+    private readonly statuses;
+    record(model: ModelIdentity, status: HealthStatus, detail?: string): void;
+    get(model: ModelIdentity): Health;
+    /** Every model this tracker has observed, keyed `kind:id`. */
+    snapshot(): Record<string, Health>;
+}
+/**
+ * Track reachability from real traffic rather than a separate probe: a
+ * successful invocation marks the model up, a thrown one marks it down. This is
+ * the generic form of the health bookkeeping a hand-rolled client does inline.
+ */
+export declare function healthTrackingMiddleware(tracker: HealthTracker): Middleware;
+/**
+ * Map thrown errors through a caller-supplied redactor before they propagate,
+ * so a failure carrying a prompt, an image payload or an auth header can be
+ * scrubbed once instead of at every catch site. The kernel supplies the seam,
+ * never the notion of what is sensitive — that is the application's call.
+ */
+export declare function errorRedactionMiddleware(redact: (err: unknown) => unknown): Middleware;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/models/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/models/middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA;AAEnB,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;AAEzF,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;AAElC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,KAAK,OAAO,CAAA;IACzD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,KAAK,aAAa,CAAA;CAC5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EACrC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAChC,UAAU,EAAE,UAAU,EAAE,GACvB,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAgC3B;AAOD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAM,MAA2B,GAAG,UAAU,CASzF;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,IAAI,UAAU,CAwB9C;AAED,iEAAiE;AACjE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAIzE,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;IASjC,8DAA8D;IAC9D,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAGnC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,CAiB3E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,UAAU,CActF"}

package/dist/models/middleware.js

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { modelIdentity, } from "./types.js";
+/**
+ * Wrap an invocation in a middleware chain. The first entry is outermost, so
+ * `withMiddleware(m, [trace, redact])` runs trace's before-logic first and its
+ * after-logic last.
+ *
+ * The returned invocation keeps the original's `id`, `kind` and `caps`, and
+ * only exposes `invokeStream` when the original did — wrapping must never
+ * appear to add a capability the underlying model doesn't have.
+ */
+export function withMiddleware(model, middleware) {
+    if (middleware.length === 0)
+        return model;
+    const identity = modelIdentity(model);
+    const baseInvoke = (req, ctx) => model.invoke(req, ctx);
+    const invoke = middleware
+        .filter((m) => m.invoke)
+        .reduceRight((next, m) => m.invoke(next, identity), baseInvoke);
+    const streaming = model.invokeStream?.bind(model);
+    const invokeStream = streaming
+        ? middleware
+            .filter((m) => m.invokeStream)
+            .reduceRight((next, m) => m.invokeStream(next, identity), (req, sink, ctx) => streaming(req, sink, ctx))
+        : undefined;
+    return {
+        id: model.id,
+        kind: model.kind,
+        caps: model.caps,
+        invoke: async (req, ctx) => (await invoke(req, ctx)),
+        ...(invokeStream
+            ? {
+                invokeStream: async (req, sink, ctx) => (await invokeStream(req, sink, ctx)),
+            }
+            : {}),
+        probe: () => model.probe(),
+    };
+}
+// ── Built-in middleware ──────────────────────────────────────────────────────
+// Generic mechanics only. Anything that encodes a *policy* (which model to fall
+// back to, what a given product considers sensitive) belongs in an app layer
+// that supplies its own middleware.
+/**
+ * Ensure every call carries a correlation id, minting one when the caller
+ * didn't supply it, so a whole chain of invocations shares a single id. Pass
+ * your own `mint` to adopt an ambient trace id from the surrounding request.
+ */
+export function correlationMiddleware(mint = () => randomUUID()) {
+    const withId = (ctx) => ctx.correlationId ? ctx : { ...ctx, correlationId: mint() };
+    return {
+        name: "correlation",
+        invoke: (next) => (req, ctx) => next(req, withId(ctx)),
+        invokeStream: (next) => (req, sink, ctx) => next(req, sink, withId(ctx)),
+    };
+}
+/** Log each invocation's start, outcome and duration through `ctx.log`. */
+export function loggingMiddleware() {
+    const run = async (model, ctx, call) => {
+        const started = Date.now();
+        const label = `${model.kind}:${model.id}`;
+        try {
+            const result = await call();
+            ctx.log(`model ${label} ok (${Date.now() - started}ms)`);
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            ctx.log(`model ${label} error after ${Date.now() - started}ms: ${message}`);
+            throw err;
+        }
+    };
+    return {
+        name: "logging",
+        invoke: (next, model) => (req, ctx) => run(model, ctx, () => next(req, ctx)),
+        invokeStream: (next, model) => (req, sink, ctx) => run(model, ctx, () => next(req, sink, ctx)),
+    };
+}
+/** Records per-model health derived from invocation outcomes. */
+export class HealthTracker {
+    statuses = new Map();
+    record(model, status, detail) {
+        this.statuses.set(`${model.kind}:${model.id}`, { status, ...(detail ? { detail } : {}) });
+    }
+    get(model) {
+        return (this.statuses.get(`${model.kind}:${model.id}`) ?? {
+            status: "unknown",
+            detail: "no invocation recorded yet",
+        });
+    }
+    /** Every model this tracker has observed, keyed `kind:id`. */
+    snapshot() {
+        return Object.fromEntries(this.statuses);
+    }
+}
+/**
+ * Track reachability from real traffic rather than a separate probe: a
+ * successful invocation marks the model up, a thrown one marks it down. This is
+ * the generic form of the health bookkeeping a hand-rolled client does inline.
+ */
+export function healthTrackingMiddleware(tracker) {
+    const run = async (model, call) => {
+        try {
+            const result = await call();
+            tracker.record(model, "up");
+            return result;
+        }
+        catch (err) {
+            tracker.record(model, "down", err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    };
+    return {
+        name: "health-tracking",
+        invoke: (next, model) => (req, ctx) => run(model, () => next(req, ctx)),
+        invokeStream: (next, model) => (req, sink, ctx) => run(model, () => next(req, sink, ctx)),
+    };
+}
+/**
+ * Map thrown errors through a caller-supplied redactor before they propagate,
+ * so a failure carrying a prompt, an image payload or an auth header can be
+ * scrubbed once instead of at every catch site. The kernel supplies the seam,
+ * never the notion of what is sensitive — that is the application's call.
+ */
+export function errorRedactionMiddleware(redact) {
+    const run = async (call) => {
+        try {
+            return await call();
+        }
+        catch (err) {
+            throw redact(err);
+        }
+    };
+    return {
+        name: "error-redaction",
+        invoke: (next) => (req, ctx) => run(() => next(req, ctx)),
+        invokeStream: (next) => (req, sink, ctx) => run(() => next(req, sink, ctx)),
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/models/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/models/middleware.ts"],"names":[],"mappings":"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"}

package/dist/models/registry.d.ts

@@ -0,0 +1,78 @@
+import type { Middleware } from "./middleware.js";
+import type { ModelInvocation, ModelKind } from "./types.js";
+/**
+ * A model reference: which kind, and which implementation within that kind.
+ * This is the routing key — everything the registry needs to bind a concrete
+ * invocation.
+ */
+export interface ModelRef {
+    kind: ModelKind;
+    id: string;
+}
+/** Builds an invocation on demand, so registration stays cheap and lazy. */
+export type ModelFactory<Req, Res> = () => ModelInvocation<Req, Res>;
+/** The outcome of a capability check, mirroring `AgentEngine.supports()`. */
+export type ModelSupport = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Thrown when a `kind`+`id` has no registered implementation. */
+export declare class UnknownModelError extends Error {
+    readonly ref: ModelRef;
+    constructor(ref: ModelRef, known: string[]);
+}
+/**
+ * Binds `kind`+`id` to a concrete {@link ModelInvocation}.
+ *
+ * This is the **low** layer of routing: it answers "which implementation is
+ * `vision.detect:yolo-v8`?", not "which model should capability X use?" — that
+ * second question belongs to a `RouteResolver`, which sits above and produces
+ * the {@link ModelRef} this registry then binds.
+ *
+ * Registering a new kind requires no kernel change: an application registers
+ * its own factory and resolves it back through the same call the built-in chat
+ * models use. That is what makes a perception layer an extension rather than a
+ * fork.
+ */
+export declare class ModelRegistry {
+    private readonly factories;
+    private readonly middleware;
+    /**
+     * Register an implementation. Re-registering the same `kind`+`id` throws:
+     * a silent overwrite is how two layers end up fighting over one route.
+     */
+    register<Req, Res>(ref: ModelRef, factory: ModelFactory<Req, Res>): this;
+    /** Register an already-constructed invocation under its own `kind`/`id`. */
+    registerInstance<Req, Res>(model: ModelInvocation<Req, Res>): this;
+    /**
+     * Add middleware applied to every invocation this registry hands out. Order is
+     * outermost-first, so the first registered middleware sees a call before the
+     * ones after it.
+     */
+    use(...middleware: Middleware[]): this;
+    has(ref: ModelRef): boolean;
+    /** Whether this registry can serve a ref, with a reason when it cannot. */
+    supports(ref: ModelRef): ModelSupport;
+    /**
+     * Bind a ref to its invocation, with this registry's middleware applied.
+     *
+     * The type parameters are the **caller's assertion** about the kind's
+     * contract — the registry stores implementations kind-erased, so asking for
+     * `resolve<ChatRequest, ChatResponse>({kind: "vision.detect", ...})` compiles
+     * but is a bug. Resolve through a kind's own helper where one exists.
+     *
+     * Fails loud on an unregistered ref rather than returning undefined: an
+     * unresolved route is a configuration error, and the earliest possible throw
+     * is the most useful one.
+     */
+    resolve<Req, Res>(ref: ModelRef): ModelInvocation<Req, Res>;
+    /** Every registered kind, in registration order. */
+    kinds(): ModelKind[];
+    /** The ids registered under one kind. */
+    ids(kind: ModelKind): string[];
+    /** Every registered ref rendered as `kind:id`, for diagnostics. */
+    registered(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map