@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/src/mesh/dispatcher.ts

@@ -0,0 +1,301 @@
+/**
+ * src/mesh/dispatcher.ts
+ *
+ * Mesh dispatcher — routes a {@link DispatchIntent} to a concrete executor
+ * (LLM, OODA, MCP tool, plugin, fallback) and returns a uniform result shape.
+ *
+ * @experimental — sprint-585. Public API may change before v1.x freeze.
+ *
+ * The dispatcher knows NOTHING about budget tokens or capability attenuation —
+ * those concerns live in `delegate.ts`. Keep this module narrowly scoped to
+ * "given an intent kind, run the right executor".
+ *
+ * Default classifier is a heuristic (no LLM call). Callers may inject their own.
+ */
+
+import type { MeshAgentKind } from "./types.js";
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface DispatchIntent {
+  /** Resolved kind — caller (or default classifier) decided which executor to use. */
+  readonly kind: MeshAgentKind;
+  /** Natural-language need. */
+  readonly need: string;
+  /** Optional context (structured data stringified, or free text). */
+  readonly context?: string;
+  /** Wall-clock deadline in ms. */
+  readonly deadline_ms?: number;
+  /** Max cost in EUR. */
+  readonly max_cost_eur?: number;
+  /** Optional MCP tool name (only used when kind === "mcp-tool"). */
+  readonly toolName?: string;
+  /** Opaque MCP tool args (only used when kind === "mcp-tool"). */
+  readonly toolArgs?: unknown;
+}
+
+export interface DispatchResult {
+  readonly output: string;
+  readonly costEur: number;
+  readonly durationMs: number;
+  /** True if the executor stopped on deadline before producing a final answer. */
+  readonly truncated: boolean;
+}
+
+export interface MeshDispatcher {
+  dispatch(intent: DispatchIntent): Promise<DispatchResult>;
+}
+
+// ─── Classifier (heuristic, no LLM) ──────────────────────────────────────────
+
+/**
+ * Tokens that suggest a long-running observation/audit loop → OODA.
+ * Order-stable, lowercase, word-boundary matched in {@link defaultClassifier}.
+ */
+const OODA_HINTS = [
+  "scan",
+  "audit",
+  "monitor",
+  "watch",
+  "step by step",
+  "analyze then",
+  "investigate",
+  "diagnose",
+  "post-mortem",
+];
+
+/**
+ * Tokens that suggest a single tool call → MCP tool dispatch.
+ */
+const MCP_HINTS = [
+  "get price",
+  "fetch",
+  "call api",
+  "lookup",
+  "read contract",
+  "check balance",
+  "get_",
+];
+
+/**
+ * Default heuristic classifier — zero LLM cost.
+ *
+ *  - OODA when need contains an OODA hint OR has ≥ 3 sentence-terminating marks.
+ *  - MCP-tool when need contains an MCP hint and is short (< 80 chars).
+ *  - LLM-router otherwise.
+ *
+ * Note: callers wanting LLM-based classification should inject a custom
+ * `classifier` via {@link DispatcherConfig}.
+ */
+export function defaultClassifier(need: string): MeshAgentKind {
+  const n = need.toLowerCase().trim();
+  if (n.length === 0) return "llm-router";
+
+  for (const hint of OODA_HINTS) {
+    if (n.includes(hint)) return "ooda";
+  }
+  // 3+ sentence terminators = multi-step instruction → OODA.
+  const terminators = (n.match(/[.!?]/g) ?? []).length;
+  if (terminators >= 3) return "ooda";
+
+  if (n.length < 80) {
+    for (const hint of MCP_HINTS) {
+      if (n.includes(hint)) return "mcp-tool";
+    }
+  }
+
+  return "llm-router";
+}
+
+// ─── DispatcherConfig & DefaultMeshDispatcher ────────────────────────────────
+
+export interface DispatcherConfig {
+  /** Override the default heuristic classifier. */
+  readonly classifier?: (need: string) => MeshAgentKind;
+  /**
+   * Executor for `kind === "llm-router"`.
+   * Must respect `deadline_ms` (caller-provided).
+   */
+  readonly llmExecutor?: (prompt: string, deadlineMs: number) => Promise<string>;
+  /**
+   * Executor for `kind === "ooda"`. Receives need + optional context.
+   * Must respect `deadline_ms` (passed via 3rd arg).
+   */
+  readonly oodaExecutor?: (
+    need: string,
+    context: string | undefined,
+    deadlineMs: number,
+  ) => Promise<string>;
+  /**
+   * Registry of MCP tools. Keyed by tool name; values are pre-bound async fns.
+   */
+  readonly mcpTools?: Readonly<Record<string, (args: unknown) => Promise<string>>>;
+  /**
+   * Optional plugin executor (last-resort, kind === "plugin").
+   */
+  readonly pluginExecutor?: (need: string, context: string | undefined) => Promise<string>;
+  /**
+   * Fallback executor when no other kind matches. Default: echoes need.
+   */
+  readonly fallbackExecutor?: (intent: DispatchIntent) => Promise<string>;
+  /**
+   * Cost model in EUR per millisecond. Default 0 (free-tier accounting).
+   * Production: inject a model that consults `tracking/provider-usage`.
+   */
+  readonly costPerMs?: number;
+}
+
+const DEFAULT_DEADLINE_MS = 30_000;
+
+/**
+ * Default dispatcher — composes injected executors into a uniform
+ * "intent → result" pipeline, including deadline enforcement and cost
+ * accounting.
+ *
+ * Concurrency notes:
+ *  - Uses `AbortController` + `setTimeout` to enforce `deadline_ms`.
+ *  - On deadline trip, returns `truncated: true` and the executor must respect
+ *    the abort signal it received via Promise.race.
+ */
+export class DefaultMeshDispatcher implements MeshDispatcher {
+  private readonly classifier: (need: string) => MeshAgentKind;
+  private readonly llm: NonNullable<DispatcherConfig["llmExecutor"]>;
+  private readonly ooda: NonNullable<DispatcherConfig["oodaExecutor"]>;
+  private readonly mcpTools: Readonly<Record<string, (args: unknown) => Promise<string>>>;
+  private readonly plugin: NonNullable<DispatcherConfig["pluginExecutor"]>;
+  private readonly fallback: NonNullable<DispatcherConfig["fallbackExecutor"]>;
+  private readonly costPerMs: number;
+
+  constructor(config: DispatcherConfig = {}) {
+    this.classifier = config.classifier ?? defaultClassifier;
+    this.llm =
+      config.llmExecutor ?? (async (prompt) => `[llm-router stub] ${prompt.slice(0, 200)}`);
+    this.ooda = config.oodaExecutor ?? (async (need) => `[ooda stub] ${need.slice(0, 200)}`);
+    this.mcpTools = config.mcpTools ?? {};
+    this.plugin = config.pluginExecutor ?? (async (need) => `[plugin stub] ${need.slice(0, 200)}`);
+    this.fallback = config.fallbackExecutor ?? (async (i) => `[fallback] ${i.need.slice(0, 200)}`);
+    this.costPerMs = config.costPerMs ?? 0;
+  }
+
+  /** Classify a need without dispatching — exposed for callers that pre-route. */
+  classify(need: string): MeshAgentKind {
+    return this.classifier(need);
+  }
+
+  async dispatch(intent: DispatchIntent): Promise<DispatchResult> {
+    const deadlineMs = intent.deadline_ms ?? DEFAULT_DEADLINE_MS;
+    if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+      throw new RangeError(
+        `DefaultMeshDispatcher.dispatch: deadline_ms must be > 0, got ${deadlineMs}`,
+      );
+    }
+    const maxCost = intent.max_cost_eur ?? Number.POSITIVE_INFINITY;
+    if (maxCost < 0) {
+      throw new RangeError(
+        `DefaultMeshDispatcher.dispatch: max_cost_eur must be ≥ 0, got ${maxCost}`,
+      );
+    }
+
+    const start = performance.now();
+    const exec = this.executorFor(intent);
+
+    let truncated = false;
+    let output: string;
+    try {
+      output = await this.runWithDeadline(exec, deadlineMs);
+    } catch (err) {
+      if (err instanceof DeadlineExceededError) {
+        truncated = true;
+        output = err.partial ?? "";
+      } else {
+        throw err;
+      }
+    }
+
+    const durationMs = performance.now() - start;
+    const costEur = Math.min(maxCost, durationMs * this.costPerMs);
+
+    return { output, costEur, durationMs, truncated };
+  }
+
+  // ─── internals ─────────────────────────────────────────────────────────────
+
+  private executorFor(intent: DispatchIntent): () => Promise<string> {
+    const deadlineMs = intent.deadline_ms ?? DEFAULT_DEADLINE_MS;
+    switch (intent.kind) {
+      case "llm-router": {
+        const prompt = intent.context
+          ? `${intent.need}\n\n[context]\n${intent.context}`
+          : intent.need;
+        return () => this.llm(prompt, deadlineMs);
+      }
+      case "ooda":
+        return () => this.ooda(intent.need, intent.context, deadlineMs);
+      case "mcp-tool": {
+        const name = intent.toolName;
+        if (!name) {
+          return async () => {
+            throw new MeshDispatchError(
+              "mcp-tool intent missing toolName",
+              "MCP_TOOL_NAME_MISSING",
+            );
+          };
+        }
+        const tool = this.mcpTools[name];
+        if (!tool) {
+          return async () => {
+            throw new MeshDispatchError(`mcp-tool "${name}" not registered`, "MCP_TOOL_NOT_FOUND");
+          };
+        }
+        return () => tool(intent.toolArgs);
+      }
+      case "plugin":
+        return () => this.plugin(intent.need, intent.context);
+      case "fallback":
+        return () => this.fallback(intent);
+      default: {
+        const _exhaustive: never = intent.kind;
+        return async () => {
+          throw new MeshDispatchError(
+            `Unknown intent kind: ${String(_exhaustive)}`,
+            "UNKNOWN_KIND",
+          );
+        };
+      }
+    }
+  }
+
+  private async runWithDeadline(exec: () => Promise<string>, deadlineMs: number): Promise<string> {
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        reject(new DeadlineExceededError(deadlineMs));
+      }, deadlineMs);
+    });
+    try {
+      return await Promise.race([exec(), timeout]);
+    } finally {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+    }
+  }
+}
+
+// ─── Errors ──────────────────────────────────────────────────────────────────
+
+export class DeadlineExceededError extends Error {
+  override readonly name = "MeshDeadlineExceededError";
+  readonly partial?: string;
+  constructor(deadlineMs: number, partial?: string) {
+    super(`mesh.dispatch: deadline ${deadlineMs}ms exceeded`);
+    this.partial = partial;
+  }
+}
+
+export class MeshDispatchError extends Error {
+  override readonly name = "MeshDispatchError";
+  readonly code: string;
+  constructor(message: string, code: string) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/mesh/index.ts

@@ -0,0 +1,39 @@
+/**
+ * src/mesh/index.ts
+ *
+ * Public barrel for the mesh.delegate() surface (sprint-585).
+ *
+ * @experimental — API may change before v1.x freeze.
+ */
+
+export {
+  attenuateScope,
+  buildToken,
+  parseToken,
+  scopeAllows,
+  type AttenuatedToken,
+  type CapabilityScope,
+  type MeshCapabilityScope,
+} from "./attenuation.js";
+
+export {
+  DefaultMeshDispatcher,
+  DeadlineExceededError as MeshDeadlineExceededError,
+  MeshDispatchError,
+  defaultClassifier,
+  type DispatchIntent,
+  type DispatchResult,
+  type DispatcherConfig,
+  type MeshDispatcher,
+} from "./dispatcher.js";
+
+export {
+  DelegateAttenuationError,
+  createMeshDelegate,
+  meshDelegate,
+  type DelegateChunk,
+  type DelegateOptions,
+  type DelegateResult,
+} from "./delegate.js";
+
+export type { DelegationLink, MeshAgentKind } from "./types.js";

package/src/mesh/types.ts

@@ -0,0 +1,31 @@
+/**
+ * src/mesh/types.ts
+ *
+ * Shared types for mesh.delegate() and dispatcher.
+ *
+ * @experimental — sprint-585. Renamed from "AgentKind" to "MeshAgentKind" to
+ * avoid clash with `registry/agent-capability.ts::AgentKind` (which uses
+ * uppercase enum values ARCHITECT/BUILDER/...).
+ */
+
+/**
+ * Kind of executor selected by the dispatcher.
+ *  - `"ooda"`          : long-running Observe→Orient→Decide→Act loop
+ *  - `"llm-router"`    : single LLM call (single-shot or BoN-MAV)
+ *  - `"mcp-tool"`      : direct MCP tool invocation
+ *  - `"plugin"`        : in-process plugin executor
+ *  - `"fallback"`      : last-resort echo / static handler
+ */
+export type MeshAgentKind = "ooda" | "llm-router" | "mcp-tool" | "plugin" | "fallback";
+
+/** One step of the delegation chain (audit trail for capability narrowing). */
+export interface DelegationLink {
+  /** Parent / delegator agent identifier. */
+  readonly from: string;
+  /** Child / delegatee agent identifier. */
+  readonly to: string;
+  /** Scope handed down (subset of parent's scope). */
+  readonly scope: ReadonlyArray<string>;
+  /** Budget handed down in EUR. */
+  readonly budget: number;
+}

package/src/orchestration/ooda/skills.ts

@@ -16,6 +16,92 @@
 import type { DbClient } from "../../tracking/agent-run-tracker.js";
 import type { LoggerPort } from "../../ports/logger.js";
 
+/**
+ * Secrets access surface handed to skills. Implementations MUST track every
+ * lookup in `accessedSecrets` so callers can audit which secrets a skill
+ * actually consumed (required for ADR-ECO-027 proof-grade tripartite and
+ * future VPSF skill attestations).
+ *
+ * @public @since 1.2.0
+ */
+export interface SecretsAccessor {
+  /**
+   * Get a secret by name. Returns `defaultValue` if missing and provided;
+   * otherwise throws when `defaultValue` is undefined and the secret is
+   * not configured. Implementations MUST record the lookup in
+   * {@link accessedSecrets} regardless of outcome.
+   */
+  get(name: string, defaultValue?: string): string;
+  /** Whether a secret with this name is available. Counts as access. */
+  has(name: string): boolean;
+  /** Set of secret names the skill actually consulted during this invocation. */
+  readonly accessedSecrets: ReadonlySet<string>;
+}
+
+/**
+ * Error thrown by {@link InMemorySecretsAccessor} when a secret is requested
+ * without a default value and is not configured.
+ *
+ * @public @since 1.2.0
+ */
+export class SecretNotFoundError extends Error {
+  readonly secretName: string;
+  constructor(secretName: string) {
+    super(`secret '${secretName}' is not configured`);
+    this.name = "SecretNotFoundError";
+    this.secretName = secretName;
+  }
+}
+
+/**
+ * In-memory {@link SecretsAccessor} suitable for tests and ephemeral
+ * runtimes. Production hosts can implement their own accessor backed by
+ * Vault, SOPS, or k8s SealedSecrets while preserving the audit semantics.
+ *
+ * @public @since 1.2.0
+ */
+export class InMemorySecretsAccessor implements SecretsAccessor {
+  private readonly store: ReadonlyMap<string, string>;
+  private readonly accessed: Set<string> = new Set();
+
+  constructor(secrets: Readonly<Record<string, string>> = {}) {
+    this.store = new Map(Object.entries(secrets));
+  }
+
+  get(name: string, defaultValue?: string): string {
+    this.accessed.add(name);
+    const value = this.store.get(name);
+    if (value !== undefined) return value;
+    if (defaultValue !== undefined) return defaultValue;
+    throw new SecretNotFoundError(name);
+  }
+
+  has(name: string): boolean {
+    this.accessed.add(name);
+    return this.store.has(name);
+  }
+
+  get accessedSecrets(): ReadonlySet<string> {
+    return this.accessed;
+  }
+}
+
+/**
+ * Noop accessor — used as default for skills that declare no secrets.
+ * Always returns `defaultValue` when provided, otherwise throws.
+ *
+ * @public @since 1.2.0
+ */
+export const NOOP_SECRETS: SecretsAccessor = new InMemorySecretsAccessor();
+
+/**
+ * Progress callback invoked by skills via `ctx.progress(value, message?)`.
+ * `value` is clamped into `[0, 1]` by implementations.
+ *
+ * @public @since 1.2.0
+ */
+export type ProgressCallback = (value: number, message?: string) => void;
+
 /**
  * Context handed to each skill invocation.
  *
@@ -23,14 +109,105 @@ import type { LoggerPort } from "../../ports/logger.js";
  * the skill must short-circuit and emit no observable mutation (no LLM
  * call, no HTTP, no DB INSERT). This guarantees replay safety for the
  * OODA cycle log.
+ *
+ * Fields added in SDK v1.2.0 (executionId, secrets, progress,
+ * elapsedSeconds, remainingSeconds) are OPTIONAL by design — existing
+ * skills compile unchanged. New skills can opt in via the
+ * {@link createSkillContext} factory.
  */
 export interface SkillContext {
   readonly isReplay: boolean;
   readonly dryRunMocks: Record<string, (input: unknown) => unknown>;
   readonly db: DbClient;
   readonly logger: LoggerPort;
+  /** Unique invocation identifier. Optional for backwards compatibility. */
+  readonly executionId?: string;
+  /** Audit-trail-bearing secret access. Defaults to {@link NOOP_SECRETS}. */
+  readonly secrets?: SecretsAccessor;
+  /** Report execution progress in [0, 1]. Noop when absent. */
+  readonly progress?: ProgressCallback;
+  /** Seconds since invocation began. Returns 0 when not tracked. */
+  readonly elapsedSeconds?: number;
+  /** Seconds remaining until timeout. Returns +Infinity when not tracked. */
+  readonly remainingSeconds?: number;
+}
+
+/**
+ * Options for {@link createSkillContext}.
+ *
+ * @public @since 1.2.0
+ */
+export interface CreateSkillContextOptions {
+  isReplay?: boolean;
+  dryRunMocks?: Record<string, (input: unknown) => unknown>;
+  db: DbClient;
+  logger: LoggerPort;
+  executionId?: string;
+  secrets?: SecretsAccessor;
+  progress?: ProgressCallback;
+  /** Absolute timeout in seconds; used to compute remainingSeconds. Default: +Infinity. */
+  timeoutSeconds?: number;
+  /** Reference Date for elapsed/remaining computation. Default: new Date(). */
+  startedAt?: Date;
 }
 
+/**
+ * Build a {@link SkillContext} with sane defaults for the optional fields.
+ * Useful for hosts that want a uniform context without writing the boilerplate.
+ *
+ * Time accessors are LIVE — `elapsedSeconds` and `remainingSeconds` are
+ * recomputed on each property read, so a skill that loops can observe them
+ * decreasing without rebuilding the context.
+ *
+ * @public @since 1.2.0
+ */
+export function createSkillContext(
+  opts: CreateSkillContextOptions
+): SkillContext {
+  const startedAt = opts.startedAt ?? new Date();
+  const timeoutSeconds = opts.timeoutSeconds ?? Number.POSITIVE_INFINITY;
+  const secrets = opts.secrets ?? NOOP_SECRETS;
+  const progressFn = opts.progress ?? noopProgress;
+
+  const ctx: SkillContext = {
+    isReplay: opts.isReplay ?? false,
+    dryRunMocks: opts.dryRunMocks ?? {},
+    db: opts.db,
+    logger: opts.logger,
+    secrets,
+    progress: (value, message) => {
+      const clamped = clampProgress(value);
+      progressFn(clamped, message);
+    },
+    get elapsedSeconds() {
+      return Math.max(0, (Date.now() - startedAt.getTime()) / 1000);
+    },
+    get remainingSeconds() {
+      if (!Number.isFinite(timeoutSeconds)) return Number.POSITIVE_INFINITY;
+      const elapsed = (Date.now() - startedAt.getTime()) / 1000;
+      return Math.max(0, timeoutSeconds - elapsed);
+    },
+  };
+  if (opts.executionId !== undefined) {
+    Object.defineProperty(ctx, "executionId", {
+      value: opts.executionId,
+      writable: false,
+      enumerable: true,
+      configurable: false,
+    });
+  }
+  return ctx;
+}
+
+function clampProgress(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+const noopProgress: ProgressCallback = () => {};
+
 /**
  * Skill — single named callable unit invoked from an OODA phase.
  *

package/src/orchestration/ooda/types.ts

@@ -250,16 +250,10 @@ export interface OODAAgentConfig<
   /**
    * Port dependencies injected at boot (BYOM — plan v6 §3.7).
    *
-   * Optional in SDK 0.17 for backward compatibility.
-   * Will be required in SDK 1.0.
-   *
-   * When `SDK_STRICT_DEPS !== "false"` (default), boot validation throws
-   * `MissingDependencyError` if this field is absent or `deps.llm` is missing.
-   *
-   * @deprecated Omitting `deps` is supported only in legacy mode. Will be required in 1.0.
+   * Required since SDK 1.0. Boot validation throws `MissingDependencyError`
+   * if this field is absent or `deps.llm` is missing.
    */
-  // Will be required in 1.0
-  readonly deps?: OODAAgentDeps;
+  readonly deps: OODAAgentDeps;
 
   readonly phases: {
     readonly observe: PhaseDef<void, TObs>;