@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/src/prompt.ts

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Liquid } from 'liquidjs';
+
+import type { Agent, PromptParameter } 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 const AUTO_INJECTED_VARS = ['today', 'now', 'agent', 'conversation', 'input'] as const;
+
+/**
+ * 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 function renderInstructions(
+  agent: Agent,
+  context: RenderContext,
+):
+  | { readonly ok: true; readonly value: RenderResult }
+  | { readonly ok: false; readonly error: PromptRenderError } {
+  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: readonly PromptParameter[],
+  supplied: Readonly<Record<string, unknown>>,
+): string[] {
+  const missing: string[] = [];
+  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: Agent,
+  declared: readonly PromptParameter[],
+  context: RenderContext,
+): Record<string, unknown> {
+  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: Record<string, unknown> = {};
+  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;
+}

package/src/provenance-emit.ts

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type {
+  KeyProvider,
+  Provenance,
+  ProvenanceBuilder,
+  ProvenanceEmitBinding,
+} from '@kindgi/provenance';
+import { signProvenance } 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 async function persistProvenance(
+  builder: ProvenanceBuilder,
+  bindings: ProvenanceBindings,
+): Promise<Result<Provenance, PersistenceError>> {
+  let provenance: 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 };
+}

package/src/registry.ts

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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 function createAgentRegistry(seed: readonly Agent[] = []): AgentRegistry {
+  const byIdVersion = new Map<string, Agent>();
+
+  function key(id: string, version: string): string {
+    return `${id}@${version}`;
+  }
+
+  function versionsForId(id: AgentId): Agent[] {
+    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): Result<void, AgentAlreadyRegisteredError> {
+      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): Result<Agent, AgentNotFoundError> {
+      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(): readonly Agent[] {
+      return [...byIdVersion.values()];
+    },
+    listVersions(id): readonly Agent[] {
+      return versionsForId(id);
+    },
+    getLatest(id): Result<Agent, AgentNotFoundError> {
+      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): Result<void, AgentNotFoundError> {
+      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: string, b: string): number {
+  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);
+}

package/src/retrieval.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
+import type { Fact, MemoryQueryBinding, RetrievalHit } from '@kindgi/memory';
+import type { ProjectId, Result, TenantId, ThreadId } from '@kindgi/types';
+
+import type { AgentError, PersistenceError } from './errors.js';
+import type {
+  Agent,
+  Conversation,
+  ConversationId,
+  RetrievalIntent,
+  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 async function runRetrievals(
+  agent: Agent,
+  conversation: Conversation,
+  conversationId: ConversationId,
+  userMessage: string,
+  bindings: RetrievalBindings,
+): Promise<Result<readonly RetrievedFact[], AgentError>> {
+  const out: RetrievedFact[] = [];
+  for (const intent of agent.retrieval) {
+    for (const type of intent.types) {
+      const one = await runOneIntent(
+        conversation,
+        conversationId,
+        userMessage,
+        intent,
+        type,
+        bindings,
+      );
+      if (one.kind === 'err') return one;
+      out.push(...one.value);
+    }
+  }
+  return { kind: 'ok', value: out };
+}
+
+/**
+ * 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 function formatRetrievedForPrompt(facts: readonly RetrievedFact[]): string {
+  if (facts.length === 0) return '';
+  const parts: string[] = ['[Retrieved context — background facts for this turn]', ''];
+  for (const { fact, intent, score } of facts) {
+    const header = `## Fact type=${fact.type} id=${fact.id} version=${fact.version}${score !== undefined ? ` score=${score.toFixed(3)}` : ''} scope=${intent.scope}`;
+    parts.push(header);
+    parts.push(stringifyContent(fact.content));
+    parts.push('');
+  }
+  return parts.join('\n').trim();
+}
+
+// ============ internals ============
+
+async function runOneIntent(
+  conversation: Conversation,
+  conversationId: ConversationId,
+  userMessage: string,
+  intent: RetrievalIntent,
+  type: string,
+  bindings: RetrievalBindings,
+): Promise<Result<readonly RetrievedFact[], PersistenceError>> {
+  const limit = intent.limit ?? 10;
+  const tenantId = conversation.tenantId;
+  const scope = scopeFilter(intent, conversation, conversationId);
+
+  if (intent.mode === undefined) {
+    return await listMode(bindings.memory, tenantId, type, scope, limit, intent);
+  }
+
+  const doKeyword = intent.mode === 'keyword' || intent.mode === 'both';
+  const doSemantic =
+    (intent.mode === 'semantic' || intent.mode === 'both') &&
+    bindings.embeddingRegistry !== undefined;
+
+  const results: RetrievedFact[] = [];
+  if (doKeyword) {
+    const kw = await bindings.memory.searchByKeyword({
+      tenantId,
+      query: userMessage,
+      type,
+      ...(scope !== undefined && { scope }),
+      topK: limit,
+    });
+    if (kw.kind === 'err') return persistErr('runOneIntent.keyword', kw.error);
+    results.push(...kw.value.map((h) => hitToRetrieved(h, intent)));
+  }
+  if (doSemantic && bindings.embeddingRegistry !== undefined) {
+    const sem = await bindings.memory.searchBySemantic({
+      tenantId,
+      query: userMessage,
+      embeddingRegistry: bindings.embeddingRegistry,
+      ...(bindings.embeddingModel !== undefined && { embeddingModel: bindings.embeddingModel }),
+      type,
+      ...(scope !== undefined && { scope }),
+      topK: limit,
+    });
+    if (sem.kind === 'err') return persistErr('runOneIntent.semantic', sem.error);
+    results.push(...sem.value.map((h) => hitToRetrieved(h, intent)));
+  }
+  return { kind: 'ok', value: dedupById(results).slice(0, limit) };
+}
+
+async function listMode(
+  memory: MemoryQueryBinding,
+  tenantId: TenantId,
+  type: string,
+  scope: Partial<import('@kindgi/memory').MemoryScope> | undefined,
+  limit: number,
+  intent: RetrievalIntent,
+): Promise<Result<readonly RetrievedFact[], PersistenceError>> {
+  const listed = await memory.listFacts({
+    tenantId,
+    type,
+    ...(scope !== undefined && { scope }),
+    limit,
+    latestOnly: true,
+  });
+  if (listed.kind === 'err') return persistErr('runOneIntent.list', listed.error);
+  return {
+    kind: 'ok',
+    value: listed.value.map((f) => ({ fact: f as Fact<unknown>, intent })),
+  };
+}
+
+function scopeFilter(
+  intent: RetrievalIntent,
+  conversation: Conversation,
+  conversationId: ConversationId,
+): Partial<import('@kindgi/memory').MemoryScope> | undefined {
+  if (intent.scope === 'same-conversation') {
+    return { threadId: conversationId as unknown as ThreadId };
+  }
+  if (intent.scope === 'same-project') {
+    const projectId = conversation.scope.projectId;
+    // If the conversation has no project scope, treat as tenant-wide
+    // rather than empty-result — the intent still applies conceptually.
+    if (projectId === undefined) return undefined;
+    return { projectId: projectId as ProjectId };
+  }
+  return undefined;
+}
+
+function hitToRetrieved(hit: RetrievalHit<unknown>, intent: RetrievalIntent): RetrievedFact {
+  return {
+    fact: hit.fact,
+    intent,
+    score: hit.score,
+  };
+}
+
+function dedupById(facts: readonly RetrievedFact[]): readonly RetrievedFact[] {
+  const seen = new Set<string>();
+  const out: RetrievedFact[] = [];
+  for (const f of facts) {
+    if (seen.has(f.fact.id)) continue;
+    seen.add(f.fact.id);
+    out.push(f);
+  }
+  return out;
+}
+
+function stringifyContent(content: unknown): string {
+  if (content === undefined) return '(no content)';
+  if (typeof content === 'string') return content;
+  return JSON.stringify(content, null, 2);
+}
+
+function persistErr(step: string, cause: unknown): Result<never, PersistenceError> {
+  return {
+    kind: 'err',
+    error: {
+      code: 'persistence-error',
+      message: `Agents operation "${step}" failed`,
+      cause,
+    },
+  };
+}