@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/prompt.d.ts

@@ -0,0 +1,83 @@
+import type { Agent } from './types.js';
+/**
+ * Reserved variable namespaces the runtime injects automatically.
+ * Callers do not (and cannot) declare these as `PromptParameter`s —
+ * they're populated by `renderInstructions` at invoke time.
+ *
+ *   - `today`         — ISO date string (yyyy-mm-dd) at UTC.
+ *   - `now`           — ISO datetime string at UTC.
+ *   - `agent.id`      — the invoked agent's id.
+ *   - `agent.name`    — display name.
+ *   - `agent.version` — semver of the invoked definition.
+ *   - `conversation.id`   — current conversation id (undefined for one-shot).
+ *   - `conversation.turn` — 1-indexed turn number within this conversation.
+ *   - `input`             — the turn's structured input (`InvokeAgentInput.input`),
+ *                           e.g. `{{ input.grievance.summary }}`; unset when
+ *                           the turn has none.
+ */
+export declare const AUTO_INJECTED_VARS: readonly ["today", "now", "agent", "conversation", "input"];
+/**
+ * Shape passed to `renderInstructions`. Framework auto-vars are
+ * computed inside; the caller supplies parameter values only.
+ */
+export interface RenderContext {
+    /** Caller-supplied parameter values. Keyed by `PromptParameter.name`. */
+    readonly parameters: Readonly<Record<string, string | number | boolean>>;
+    /** Turn context — used to fill in `conversation.*` and stamp `now`. */
+    readonly conversation?: {
+        readonly id: string;
+        readonly turn: number;
+    };
+    /** The turn's structured input, rendered as `{{ input.* }}`. */
+    readonly input?: unknown;
+    /**
+     * Optional clock override — tests inject a fixed date. Defaults to
+     * `new Date()`.
+     */
+    readonly clock?: () => Date;
+}
+export interface RenderResult {
+    readonly rendered: string;
+    /**
+     * The full context the template was rendered against (parameters +
+     * auto-vars). Captured for provenance — the auditor sees exactly
+     * what values filled the placeholders.
+     */
+    readonly context: Readonly<Record<string, unknown>>;
+}
+export type PromptRenderError = MissingParameterError | RenderFailureError;
+/**
+ * A required parameter has no value at invoke time.
+ * `parameterName` is undefined if LiquidJS caught a variable that isn't
+ * even declared (typo, or template references a name we didn't validate
+ * at define time).
+ */
+export interface MissingParameterError {
+    readonly code: 'missing-parameter';
+    readonly message: string;
+    readonly parameterName?: string;
+}
+/** Template failed to render for a reason other than a missing var. */
+export interface RenderFailureError {
+    readonly code: 'render-failure';
+    readonly message: string;
+    readonly cause: unknown;
+}
+/**
+ * Render an agent's instructions template with the given context.
+ * Populates framework auto-vars, merges caller parameter values, and
+ * applies defaults for optional parameters. Missing required parameters
+ * are surfaced as `missing-parameter` before Liquid ever runs.
+ *
+ * Uses `strictVariables: true` so an unresolved `{{ var }}` is an error
+ * — never a silent empty string. This is load-bearing for correctness
+ * (a system prompt with a missing firm name is worse than a hard fail).
+ */
+export declare function renderInstructions(agent: Agent, context: RenderContext): {
+    readonly ok: true;
+    readonly value: RenderResult;
+} | {
+    readonly ok: false;
+    readonly error: PromptRenderError;
+};
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAmB,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,6DAA8D,CAAC;AAE9F;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IACzE,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,kBAAkB,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,aAAa,GAEpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CA2C5D"}

package/dist/prompt.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Liquid } from 'liquidjs';
+/**
+ * Reserved variable namespaces the runtime injects automatically.
+ * Callers do not (and cannot) declare these as `PromptParameter`s —
+ * they're populated by `renderInstructions` at invoke time.
+ *
+ *   - `today`         — ISO date string (yyyy-mm-dd) at UTC.
+ *   - `now`           — ISO datetime string at UTC.
+ *   - `agent.id`      — the invoked agent's id.
+ *   - `agent.name`    — display name.
+ *   - `agent.version` — semver of the invoked definition.
+ *   - `conversation.id`   — current conversation id (undefined for one-shot).
+ *   - `conversation.turn` — 1-indexed turn number within this conversation.
+ *   - `input`             — the turn's structured input (`InvokeAgentInput.input`),
+ *                           e.g. `{{ input.grievance.summary }}`; unset when
+ *                           the turn has none.
+ */
+export const AUTO_INJECTED_VARS = ['today', 'now', 'agent', 'conversation', 'input'];
+/**
+ * Render an agent's instructions template with the given context.
+ * Populates framework auto-vars, merges caller parameter values, and
+ * applies defaults for optional parameters. Missing required parameters
+ * are surfaced as `missing-parameter` before Liquid ever runs.
+ *
+ * Uses `strictVariables: true` so an unresolved `{{ var }}` is an error
+ * — never a silent empty string. This is load-bearing for correctness
+ * (a system prompt with a missing firm name is worse than a hard fail).
+ */
+export function renderInstructions(agent, context) {
+    const declared = agent.parameters ?? [];
+    const missing = requiredMissing(declared, context.parameters);
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'missing-parameter',
+                message: `Required parameter${missing.length === 1 ? '' : 's'} missing: ${missing.join(', ')}`,
+                ...(missing.length === 1 && missing[0] !== undefined && { parameterName: missing[0] }),
+            },
+        };
+    }
+    const merged = mergeContext(agent, declared, context);
+    const liquid = new Liquid({ strictVariables: true, strictFilters: true });
+    try {
+        const rendered = liquid.parseAndRenderSync(agent.instructions, merged);
+        return { ok: true, value: { rendered, context: merged } };
+    }
+    catch (cause) {
+        // LiquidJS throws UndefinedVariableError for unresolved refs — surface
+        // as missing-parameter so callers get one consistent error code.
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (message.includes('undefined variable')) {
+            const nameMatch = /undefined variable: ([\w.]+)/.exec(message);
+            return {
+                ok: false,
+                error: {
+                    code: 'missing-parameter',
+                    message: `Template references an unresolved variable: ${nameMatch?.[1] ?? '?'}`,
+                    ...(nameMatch?.[1] !== undefined && { parameterName: nameMatch[1] }),
+                },
+            };
+        }
+        return {
+            ok: false,
+            error: {
+                code: 'render-failure',
+                message: `Template render failed: ${message}`,
+                cause,
+            },
+        };
+    }
+}
+function requiredMissing(declared, supplied) {
+    const missing = [];
+    for (const p of declared) {
+        const isRequired = p.required !== false;
+        if (!isRequired)
+            continue;
+        if (p.default !== undefined)
+            continue;
+        if (!(p.name in supplied) || supplied[p.name] === undefined)
+            missing.push(p.name);
+    }
+    return missing;
+}
+function mergeContext(agent, declared, context) {
+    const clock = context.clock ?? (() => new Date());
+    const at = clock();
+    const today = at.toISOString().slice(0, 10);
+    const now = at.toISOString();
+    // Start with declared defaults, layer caller-supplied on top so
+    // callers can override defaults explicitly.
+    const values = {};
+    for (const p of declared) {
+        if (p.default !== undefined)
+            values[p.name] = p.default;
+    }
+    for (const [k, v] of Object.entries(context.parameters))
+        values[k] = v;
+    values.today = today;
+    values.now = now;
+    values.agent = {
+        id: agent.id,
+        name: agent.name,
+        version: agent.version,
+    };
+    if (context.conversation !== undefined) {
+        values.conversation = {
+            id: context.conversation.id,
+            turn: context.conversation.turn,
+        };
+    }
+    if (context.input !== undefined)
+        values.input = context.input;
+    return values;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

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

package/dist/provenance-emit.d.ts

@@ -0,0 +1,44 @@
+import type { KeyProvider, Provenance, ProvenanceBuilder, ProvenanceEmitBinding } from '@kindgi/provenance';
+import type { Result } from '@kindgi/types';
+import type { PersistenceError } from './errors.js';
+/**
+ * Bindings the provenance emission flow consumes. All optional — if
+ * `newBuilder` isn't set, provenance is skipped entirely.
+ */
+export interface ProvenanceBindings {
+    /**
+     * Factory the runtime calls at turn start to construct a fresh
+     * builder. Callers supply this so they control id + flowRef +
+     * schema version.
+     */
+    readonly newBuilder?: (opts: {
+        readonly runId: string;
+        readonly tenantId: string;
+    }) => ProvenanceBuilder;
+    /**
+     * When true, the DAG persists via `emitBinding.emit(...)` after a
+     * successful turn. Failed turns still build the DAG but don't emit —
+     * the caller sees them via the streaming event stream.
+     */
+    readonly emit?: boolean;
+    /**
+     * Caller-plugged emit surface. Required whenever `emit` is true.
+     * The Kindgi runtime supplies a Postgres-backed implementation;
+     * any conforming object works.
+     */
+    readonly emitBinding?: ProvenanceEmitBinding;
+    /**
+     * When set, `signProvenance` is called with this key provider before
+     * emit. Unsigned DAGs still emit but forensic verification can't
+     * chain back to a keyId.
+     */
+    readonly keyProvider?: KeyProvider;
+}
+/**
+ * Persist a completed provenance DAG. Signs first if a key provider is
+ * bound. Failures surface as `persistence-error`; upstream turn logic
+ * decides how much to bail out — usually the turn already succeeded so
+ * this is best-effort.
+ */
+export declare function persistProvenance(builder: ProvenanceBuilder, bindings: ProvenanceBindings): Promise<Result<Provenance, PersistenceError>>;
+//# sourceMappingURL=provenance-emit.d.ts.map

package/dist/provenance-emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-emit.d.ts","sourceRoot":"","sources":["../src/provenance-emit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,KAAK,iBAAiB,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CA0C/C"}

package/dist/provenance-emit.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { signProvenance } from '@kindgi/provenance';
+/**
+ * Persist a completed provenance DAG. Signs first if a key provider is
+ * bound. Failures surface as `persistence-error`; upstream turn logic
+ * decides how much to bail out — usually the turn already succeeded so
+ * this is best-effort.
+ */
+export async function persistProvenance(builder, bindings) {
+    let provenance = builder.snapshot();
+    if (bindings.keyProvider !== undefined) {
+        const signed = signProvenance(provenance, bindings.keyProvider);
+        if (signed.kind === 'err') {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'persistence-error',
+                    message: `Failed to sign provenance: ${signed.error.message}`,
+                    cause: signed.error,
+                },
+            };
+        }
+        provenance = signed.value;
+    }
+    if (bindings.emit === true) {
+        if (bindings.emitBinding === undefined) {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'persistence-error',
+                    message: 'Provenance emit=true but no emitBinding wired — pass a ProvenanceEmitBinding as bindings.provenance.emitBinding.',
+                    cause: null,
+                },
+            };
+        }
+        const emitted = await bindings.emitBinding.emit(provenance);
+        if (emitted.kind === 'err') {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'persistence-error',
+                    message: `Failed to emit provenance: ${emitted.error.message}`,
+                    cause: emitted.error,
+                },
+            };
+        }
+    }
+    return { kind: 'ok', value: provenance };
+}
+//# sourceMappingURL=provenance-emit.js.map

package/dist/provenance-emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-emit.js","sourceRoot":"","sources":["../src/provenance-emit.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAQjC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAuCpD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA0B,EAC1B,QAA4B;IAE5B,IAAI,UAAU,GAAe,OAAO,CAAC,QAAQ,EAAE,CAAC;IAChD,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;QAChE,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC1B,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,KAAK,EAAE;oBACL,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EAAE,8BAA8B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;oBAC7D,KAAK,EAAE,MAAM,CAAC,KAAK;iBACpB;aACF,CAAC;QACJ,CAAC;QACD,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC;IAC5B,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACvC,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,KAAK,EAAE;oBACL,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EACL,kHAAkH;oBACpH,KAAK,EAAE,IAAI;iBACZ;aACF,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5D,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC3B,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,KAAK,EAAE;oBACL,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EAAE,8BAA8B,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE;oBAC9D,KAAK,EAAE,OAAO,CAAC,KAAK;iBACrB;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC3C,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,38 @@
+import type { Result } from '@kindgi/types';
+import type { AgentAlreadyRegisteredError, AgentNotFoundError } from './errors.js';
+import type { Agent, AgentId } from './types.js';
+/**
+ * In-memory catalog of agent definitions. Keyed by `(id, version)`,
+ * because the same agent id at different versions is a different
+ * agent for provenance / audit purposes. `getLatest(id)` returns the
+ * highest semver registered under that id.
+ *
+ * The registry is per-tenant at the application layer — callers
+ * typically instantiate one registry per tenant boot. The registry
+ * itself does not enforce tenancy: it's a substrate primitive, and
+ * multi-tenant deployments layer RLS + tenant-scoped registries on
+ * top.
+ */
+export interface AgentRegistry {
+    register(agent: Agent): Result<void, AgentAlreadyRegisteredError>;
+    /**
+     * Look up an agent by id + version. If `version` is omitted, returns
+     * the latest semver registered under `id`.
+     */
+    get(id: AgentId, version?: string): Result<Agent, AgentNotFoundError>;
+    /** Enumerate every version of every registered agent. */
+    list(): readonly Agent[];
+    /** Enumerate all versions registered under a given id, semver-sorted asc. */
+    listVersions(id: AgentId): readonly Agent[];
+    /**
+     * Latest semver for id, or `agent-not-found`.
+     */
+    getLatest(id: AgentId): Result<Agent, AgentNotFoundError>;
+    /**
+     * Deregister a specific version. Rare — typically used for
+     * pack-uninstall flows. Returns `agent-not-found` on miss.
+     */
+    unregister(id: AgentId, version: string): Result<void, AgentNotFoundError>;
+}
+export declare function createAgentRegistry(seed?: readonly Agent[]): AgentRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,2BAA2B,CAAC,CAAC;IAClE;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;IACtE,yDAAyD;IACzD,IAAI,IAAI,SAAS,KAAK,EAAE,CAAC;IACzB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,KAAK,EAAE,CAAC;IAC5C;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;IAC1D;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;CAC5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,SAAS,KAAK,EAAO,GAAG,aAAa,CAoG9E"}

package/dist/registry.js

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export function createAgentRegistry(seed = []) {
+    const byIdVersion = new Map();
+    function key(id, version) {
+        return `${id}@${version}`;
+    }
+    function versionsForId(id) {
+        return [...byIdVersion.values()]
+            .filter((a) => a.id === id)
+            .sort((a, b) => compareSemver(a.version, b.version));
+    }
+    for (const agent of seed)
+        byIdVersion.set(key(agent.id, agent.version), agent);
+    return {
+        register(agent) {
+            const k = key(agent.id, agent.version);
+            if (byIdVersion.has(k)) {
+                return {
+                    kind: 'err',
+                    error: {
+                        code: 'agent-already-registered',
+                        message: `Agent "${agent.id}" version "${agent.version}" is already registered`,
+                        agentId: agent.id,
+                        version: agent.version,
+                    },
+                };
+            }
+            byIdVersion.set(k, agent);
+            return { kind: 'ok', value: undefined };
+        },
+        get(id, version) {
+            if (version !== undefined) {
+                const hit = byIdVersion.get(key(id, version));
+                if (hit === undefined) {
+                    return {
+                        kind: 'err',
+                        error: {
+                            code: 'agent-not-found',
+                            message: `No agent "${id}" at version "${version}"`,
+                            agentId: id,
+                            version,
+                        },
+                    };
+                }
+                return { kind: 'ok', value: hit };
+            }
+            const versions = versionsForId(id);
+            const latest = versions[versions.length - 1];
+            if (latest === undefined) {
+                return {
+                    kind: 'err',
+                    error: {
+                        code: 'agent-not-found',
+                        message: `No agent registered with id "${id}"`,
+                        agentId: id,
+                    },
+                };
+            }
+            return { kind: 'ok', value: latest };
+        },
+        list() {
+            return [...byIdVersion.values()];
+        },
+        listVersions(id) {
+            return versionsForId(id);
+        },
+        getLatest(id) {
+            const versions = versionsForId(id);
+            const latest = versions[versions.length - 1];
+            if (latest === undefined) {
+                return {
+                    kind: 'err',
+                    error: {
+                        code: 'agent-not-found',
+                        message: `No agent registered with id "${id}"`,
+                        agentId: id,
+                    },
+                };
+            }
+            return { kind: 'ok', value: latest };
+        },
+        unregister(id, version) {
+            const k = key(id, version);
+            if (!byIdVersion.has(k)) {
+                return {
+                    kind: 'err',
+                    error: {
+                        code: 'agent-not-found',
+                        message: `No agent "${id}" at version "${version}" to unregister`,
+                        agentId: id,
+                        version,
+                    },
+                };
+            }
+            byIdVersion.delete(k);
+            return { kind: 'ok', value: undefined };
+        },
+    };
+}
+/**
+ * Compare two semver strings. Returns negative if a < b, positive if
+ * a > b, 0 if equal. Handles pre-release tags by treating any tagged
+ * version as lower than the equivalent untagged version — matches
+ * semver.org §11.
+ */
+function compareSemver(a, b) {
+    const [aBase, aPre] = a.split('-', 2);
+    const [bBase, bPre] = b.split('-', 2);
+    const aParts = (aBase ?? '0.0.0').split('.').map(Number);
+    const bParts = (bBase ?? '0.0.0').split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const diff = (aParts[i] ?? 0) - (bParts[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (aPre === undefined && bPre === undefined)
+        return 0;
+    if (aPre === undefined)
+        return 1;
+    if (bPre === undefined)
+        return -1;
+    return aPre.localeCompare(bPre);
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/retrieval.d.ts

@@ -0,0 +1,47 @@
+import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
+import type { MemoryQueryBinding } from '@kindgi/memory';
+import type { Result } from '@kindgi/types';
+import type { AgentError } from './errors.js';
+import type { Agent, Conversation, ConversationId, RetrievedFact } from './types.js';
+/** Bindings the retrieval flow consumes. `memory` is required; the
+ * rest are optional — without an embedding registry, the semantic
+ * part of an intent is silently skipped. `embeddingModel` picks a
+ * specific registered provider; omit to fall back to the registry's
+ * sole provider. */
+export interface RetrievalBindings {
+    /**
+     * Caller-plugged data-access surface for memory reads. Every listFacts /
+     * searchByKeyword / searchBySemantic call inside `runRetrievals` routes
+     * through this binding — the runtime never touches a database client directly.
+     */
+    readonly memory: MemoryQueryBinding;
+    readonly embeddingRegistry?: EmbeddingProviderRegistry;
+    readonly embeddingModel?: string;
+}
+/**
+ * Execute every retrieval intent declared on the agent against the
+ * current conversation's scope. Returns retrieved facts paired with
+ * the intent that pulled them, so downstream provenance can attribute
+ * each fact to its retrieval declaration.
+ *
+ * Retrieval modes:
+ *   - `mode: 'keyword'`  — `searchByKeyword` with the user's message
+ *     as the query (full-text search in the memory implementation).
+ *   - `mode: 'semantic'` — `searchBySemantic` with the user's message
+ *     embedded. Requires `bindings.embeddingRegistry`; without one,
+ *     the semantic search is silently skipped.
+ *   - `mode: 'both'`     — run both, merge results, dedup by fact id
+ *     with keyword score preserved.
+ *   - `mode` omitted     — `listFacts` scoped + typed, latest-first.
+ *     No query needed; useful for "always pull the current
+ *     working-memory snapshot."
+ */
+export declare function runRetrievals(agent: Agent, conversation: Conversation, conversationId: ConversationId, userMessage: string, bindings: RetrievalBindings): Promise<Result<readonly RetrievedFact[], AgentError>>;
+/**
+ * Format retrieved facts as a system-role message the model can read
+ * as background context. Kept structural (fact headers + JSON content)
+ * rather than freeform prose — models handle discriminable fact
+ * boundaries better than blended narrative.
+ */
+export declare function formatRetrievedForPrompt(facts: readonly RetrievedFact[]): string;
+//# sourceMappingURL=retrieval.d.ts.map

package/dist/retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../src/retrieval.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAQ,kBAAkB,EAAgB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAa,MAAM,EAAsB,MAAM,eAAe,CAAC;AAE3E,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EACZ,cAAc,EAEd,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;oBAIoB;AACpB,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,EAAE,UAAU,CAAC,CAAC,CAiBvD;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAUhF"}