@inixiative/foundry-core 0.1.0

package/src/native-evidence.ts

@@ -0,0 +1,140 @@
+/** Public, owned projection. Raw protocol and reasoning are deliberately absent. */
+export interface NativeOwner {
+  readonly threadId: string;
+  readonly projectId?: string;
+  readonly generation: string;
+  readonly messageId?: string;
+  readonly dispatchId: string;
+  readonly reviewJobId?: string;
+  /** Foundry's provider pool key, distinct from every native identity. */
+  readonly providerSessionKey?: string;
+}
+/** Compare typed ownership fields, not serialization order or prompt text. */
+export function sameNativeOwner(a: NativeOwner | undefined, b: NativeOwner | undefined): boolean {
+  return !!a && !!b && (["threadId", "projectId", "generation", "messageId", "dispatchId", "reviewJobId", "providerSessionKey"] as const)
+    .every(key => a[key] === b[key]);
+}
+export interface OwnedAdmissionInspection {
+  readonly evidence: NativeEvidence;
+  /** Physical call settlement is independent of a native terminal and local waiter. */
+  readonly call: "settled" | "pending" | "unknown";
+  readonly cleanup: "not-requested" | "pending" | "released" | "unknown";
+  readonly capacity: "settled" | "unknown";
+}
+export interface NativeEvidence {
+  readonly schema: 1;
+  readonly executionMode?: "controlled-fixture";
+  readonly owner?: NativeOwner;
+  readonly admissionId?: string;
+  readonly nativeSessionId?: string;
+  readonly externalSessionId?: string;
+  readonly threadId?: string;
+  readonly turnId?: string;
+  readonly itemId?: string;
+  readonly callId?: string;
+  readonly rpcRequestId?: string | number;
+  readonly nativeOutcome: "unknown" | "completed" | "failed";
+  readonly localOutcome?: "pending" | "resolved" | "rejected";
+  readonly dispatch?: "not-dispatched" | "attempted";
+  readonly transportOutcome?: "open" | "failed" | "closed";
+  readonly rpcOutcome?: "pending" | "resolved" | "failed" | "unknown";
+  readonly localFailure?: string;
+  readonly localError?: string;
+  readonly observedAt?: number;
+  readonly terminal?: Readonly<{ type: string; eventId?: string; turnId?: string; subtype?: string; reason?: string; apiErrorStatus?: number }>;
+  readonly content?: string;
+  readonly correlation?: string;
+  readonly kind?: string;
+  readonly toolName?: string;
+  readonly toolServer?: string;
+  readonly toolMethod?: string;
+  readonly toolInput?: Readonly<Record<string, unknown>>;
+  readonly toolInputOmitted?: string;
+  readonly toolOutput?: string;
+  readonly toolOutputOmitted?: boolean;
+  /** tool_result only: exact public tool names from tool-search reference blocks, in order,
+   * duplicates preserved, copied and frozen. Never a retrieval success by itself. */
+  readonly toolReferences?: readonly string[];
+  /** tool_result only: public allowlisted labels of omitted result blocks; unknown shapes are
+   * "unsupported". Present only with toolOutputOmitted. */
+  readonly toolOutputOmittedTypes?: readonly string[];
+  readonly toolError?: boolean;
+  readonly observationFailures?: number;
+  readonly configuration?: Readonly<{ requestedModel: string; observedModel?: string; requestedMaxTurns?: number | null;
+    engine?: "mcp" | "app-server"; transportMode?: "controlled-fixture"; requestedEffort?: string; observedEffort?: string | null;
+    history?: Readonly<{source:"thread/start"|"thread/resume";available:boolean;hasMore:boolean;turns:readonly Readonly<{id:string;status:string}>[]}>;
+    turnBudgetEnforcement: "launch-option" | "unavailable"; tokenBudget: "unavailable"; effortBudget: "unavailable" }>;
+  readonly text?: string;
+  /** Public text form only; reasoning is never projected. Missing phase is not a final-answer acknowledgment. */
+  readonly textKind?: "delta" | "snapshot";
+  readonly textPhase?: "commentary" | "final_answer";
+  /** Safe setup/status evidence, never launch paths or config values. */
+  readonly runtimeStatus?: Readonly<{ type: string; status?: string; reason?: string; server?: string; tools?: readonly string[] }>;
+  readonly bridge?: { readonly id: string; readonly configurationHash: string; readonly toolPolicy?: NativeToolPolicy; readonly tools: readonly NativeToolEvidence[] };
+}
+export interface NativeToolRecord {
+  readonly id: string;
+  readonly bridgeId: string;
+  readonly operation: string;
+  readonly owner: { readonly threadId: string; readonly projectId?: string; readonly generation: string };
+  readonly association: { readonly kind: "registered-admission-window" | "unassociated"; readonly admissionId?: string; readonly owner?: NativeOwner };
+  readonly sdkRequestId?: string | number;
+  readonly sdkSessionId?: string;
+  readonly nativeCorrelation: "unknown";
+  readonly startedAt: number;
+  readonly finishedAt: number;
+  readonly arguments: Readonly<Record<string, unknown>>;
+  readonly result: string;
+  readonly digest: string;
+  readonly status: string;
+  readonly refusal?: string;
+}
+export interface NativeToolEvidence {
+  readonly record: NativeToolRecord;
+  readonly persistence: "pending" | "committed" | "failed";
+  readonly publication: "pending" | "published" | "reconciliation-needed";
+  readonly error?: string;
+}
+/** Process lifetime grant. Data/functions never become part of a provider prompt. */
+export interface NativeBridgeSource {
+  readonly key: string;
+  readonly toolPolicy?: NativeToolPolicy;
+  check(owner: NativeOwner): void;
+  acquire(): Promise<NativeBridgeLease>;
+}
+export interface NativeBridgeLease {
+  readonly id: string;
+  readonly name: string;
+  readonly owner: { readonly threadId: string; readonly projectId?: string; readonly generation: string };
+  readonly configurationHash: string;
+  readonly toolPolicy?: NativeToolPolicy;
+  /** Private, empty native cwd owned by a restricted fixture lease. */
+  readonly fixtureCwd?: string;
+  readonly launch: { readonly claudeJson: string; readonly codexOverrides: readonly string[] };
+  check(): void;
+  register(evidence: NativeEvidence): void;
+  observe(evidence: NativeEvidence): void;
+  evidence(admissionId?: string): readonly NativeToolEvidence[];
+  status?(): Readonly<{ closed: boolean; pendingCleanups: number; cleanupFailures: number; evictedRecords: number }>;
+  close(): Promise<void>;
+}
+/** Immutable policy identity; contains no credentials, launch paths or tool input. */
+export interface NativeToolPolicy {
+  readonly version: "isolated-fixture-v1";
+  readonly digest: string;
+}
+export interface NativeObservation {
+  readonly owner: NativeOwner;
+  readonly bridge?: NativeBridgeSource;
+  /** Durable capacity check before constructing/resuming a process. Registration still rechecks atomically. */
+  preflight?(owner: NativeOwner): void | Promise<void>;
+  /** Required registration. A failed write here must prevent native admission. */
+  register(evidence: NativeEvidence): void | Promise<void>;
+  /** Fallible observer; never vetoes executor completion. */
+  observe(evidence: NativeEvidence): void | Promise<void>;
+}
+export function freezeEvidence<T>(value: T): T {
+  const copy = structuredClone(value);
+  const freeze = (v: unknown) => { if (v && typeof v === "object" && !Object.isFrozen(v)) { for (const nested of Object.values(v)) freeze(nested); Object.freeze(v); } };
+  freeze(copy); return copy;
+}

package/src/permission-middleware.ts

@@ -0,0 +1,92 @@
+import type { Middleware, DispatchContext, MiddlewareNext } from "./middleware";
+import {
+  CapabilityGate,
+  CapabilityDeniedError,
+  type Capability,
+} from "./capability";
+
+export interface PermissionCheckResult {
+  action: "allow" | "deny" | "ask";
+  /** Optional modified payload (like Claude Code's updatedInput). */
+  modifiedPayload?: unknown;
+  /** Reason for denial. */
+  reason?: string;
+}
+
+export interface PermissionCheck {
+  /** Which capability this check relates to. */
+  capability: Capability;
+  /** Narrow the check to specific agents. If omitted, applies to all. */
+  agentIds?: string[];
+  /** Custom check logic beyond the gate. */
+  check: (ctx: DispatchContext) => PermissionCheckResult | Promise<PermissionCheckResult>;
+}
+
+export interface PermissionMiddlewareConfig {
+  /** The capability gate to check against. */
+  gate: CapabilityGate;
+  /** Thread ID for prompt context. */
+  threadId: string;
+  /** Default capability to check for all dispatches. Default: "llm:call". */
+  defaultCapability?: Capability;
+  /** Additional custom permission checks. */
+  checks?: PermissionCheck[];
+}
+
+/**
+ * Creates a middleware that checks permissions before dispatch.
+ *
+ * Integrates the existing CapabilityGate into the dispatch pipeline.
+ * Records permission decisions in ctx.annotations.
+ */
+export function permissionMiddleware(config: PermissionMiddlewareConfig): Middleware {
+  const {
+    gate,
+    threadId,
+    defaultCapability = "llm:call",
+    checks,
+  } = config;
+
+  return async (ctx: DispatchContext, next: MiddlewareNext) => {
+    // Check default capability via gate
+    const resolution = await gate.check(defaultCapability, {
+      agentId: ctx.agentId,
+      threadId,
+      detail: `Dispatch to agent ${ctx.agentId}`,
+    });
+
+    if (resolution.action === "rejected") {
+      ctx.annotations["permission:denied"] = true;
+      ctx.annotations["permission:capability"] = defaultCapability;
+      throw new CapabilityDeniedError(defaultCapability, "deny");
+    }
+
+    ctx.annotations["permission:approved"] = true;
+    ctx.annotations["permission:by"] = resolution.by;
+
+    // Run custom checks
+    if (checks) {
+      for (const check of checks) {
+        if (check.agentIds && !check.agentIds.includes(ctx.agentId)) continue;
+
+        const result = await check.check(ctx);
+
+        if (result.action === "deny") {
+          ctx.annotations["permission:denied"] = true;
+          ctx.annotations["permission:capability"] = check.capability;
+          ctx.annotations["permission:reason"] = result.reason;
+          throw new CapabilityDeniedError(
+            check.capability,
+            "deny",
+          );
+        }
+
+        if (result.modifiedPayload !== undefined) {
+          ctx.annotations["permission:modifiedPayload"] = result.modifiedPayload;
+        }
+      }
+    }
+
+    return next();
+  };
+}

package/src/retry.ts

@@ -0,0 +1,91 @@
+import type { Middleware, DispatchContext, MiddlewareNext } from "./middleware";
+import { CapabilityDeniedError } from "./capability";
+import { BudgetExceededError } from "./token-tracker";
+
+export interface RetryConfig {
+  /** Maximum retry attempts. Default: 3. */
+  maxRetries?: number;
+  /** Initial delay in ms before first retry. Default: 1000. */
+  initialDelayMs?: number;
+  /** Maximum delay cap in ms. Default: 30_000. */
+  maxDelayMs?: number;
+  /** Backoff multiplier. Default: 2. */
+  backoffFactor?: number;
+  /** Add jitter to prevent thundering herd. Default: true. */
+  jitter?: boolean;
+  /** Give-up threshold in ms (total elapsed). Default: 120_000. */
+  giveUpAfterMs?: number;
+  /** Predicate: which errors should be retried. Default: all except denied/budget. */
+  isRetryable?: (error: unknown) => boolean;
+  /** Called on each retry attempt (for logging/observability). */
+  onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+
+function defaultIsRetryable(error: unknown): boolean {
+  if (error instanceof CapabilityDeniedError) return false;
+  if (error instanceof BudgetExceededError) return false;
+  return true;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Creates a middleware that wraps dispatch with exponential backoff retry.
+ *
+ * Composable: register globally or per-agent via `middleware.useWhen()`.
+ */
+export function retryMiddleware(config: RetryConfig = {}): Middleware {
+  const {
+    maxRetries = 3,
+    initialDelayMs = 1000,
+    maxDelayMs = 30_000,
+    backoffFactor = 2,
+    jitter = true,
+    giveUpAfterMs = 120_000,
+    isRetryable = defaultIsRetryable,
+    onRetry,
+  } = config;
+
+  return async (ctx: DispatchContext, next: MiddlewareNext) => {
+    const startTime = Date.now();
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await next();
+      } catch (error) {
+        lastError = error;
+
+        if (attempt >= maxRetries) break;
+        if (!isRetryable(error)) break;
+
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= giveUpAfterMs) break;
+
+        let delay = initialDelayMs * Math.pow(backoffFactor, attempt);
+        delay = Math.min(delay, maxDelayMs);
+
+        if (jitter) {
+          // Randomize between 50% and 100% of computed delay
+          delay = delay * (0.5 + Math.random() * 0.5);
+        }
+
+        // Don't exceed give-up threshold
+        const remaining = giveUpAfterMs - elapsed;
+        if (delay > remaining) {
+          delay = Math.max(0, remaining);
+        }
+
+        onRetry?.(attempt + 1, error, delay);
+        ctx.annotations["retry:attempt"] = attempt + 1;
+        ctx.annotations["retry:lastError"] = String(error);
+
+        await sleep(delay);
+      }
+    }
+
+    throw lastError;
+  };
+}

package/src/router.ts

@@ -0,0 +1,41 @@
+import { Decider, type DeciderConfig, type Decision } from "./decider";
+import type { AgentConfig } from "./base-agent";
+import type { ContextStack } from "./context-stack";
+import type { ExecuteMeta } from "./executor";
+
+/**
+ * A routing decision — "where should this go?"
+ */
+export interface Route {
+  readonly destination: string;
+  readonly priority?: number;
+  /** Optional context slice hint — what context the destination should receive. */
+  readonly contextSlice?: string[];
+}
+
+export type RouteHandler<TPayload> = (
+  context: string,
+  payload: TPayload,
+  meta?: ExecuteMeta
+) => Promise<Decision<Route>>;
+
+export interface RouterConfig<TPayload = unknown> extends AgentConfig {
+  handler: RouteHandler<TPayload>;
+}
+
+/**
+ * A Router is a Decider that returns a destination.
+ *
+ * "Given everything you know about the topology, where does this GO?"
+ * The Router has the full map loaded in its context layers.
+ * The caller sends a payload and gets back a destination — not the map.
+ */
+export class Router<TPayload = unknown> extends Decider<TPayload, Route> {
+  constructor(config: RouterConfig<TPayload>) {
+    super(config as DeciderConfig<TPayload, Route>);
+  }
+
+  override withStack(stack: ContextStack): Router<TPayload> {
+    return new Router<TPayload>({ ...this.agentConfig(stack), handler: this._handler });
+  }
+}

package/src/scope.ts

@@ -0,0 +1,20 @@
+/**
+ * Ownership scope — which thread and project an operation belongs to.
+ *
+ * Threads bind their context sources and tool calls to a scope so that
+ * per-thread captures never leak into other threads or projects. A scope
+ * with neither field is "unscoped": it sees only knowledge that was
+ * explicitly published to everyone.
+ */
+export interface OwnershipScope {
+  readonly threadId?: string;
+  readonly projectId?: string;
+}
+
+/** Copy a scope, dropping undefined fields so equality checks are stable. */
+export function normalizeScope(scope: OwnershipScope | undefined): OwnershipScope {
+  const out: { threadId?: string; projectId?: string } = {};
+  if (scope?.threadId) out.threadId = scope.threadId;
+  if (scope?.projectId) out.projectId = scope.projectId;
+  return out;
+}

package/src/signal.ts

@@ -0,0 +1,117 @@
+/**
+ * Signal kinds — the Librarian's taxonomy.
+ * Extensible via string union, not a closed enum.
+ */
+export type SignalKind =
+  | "correction"
+  | "convention"
+  | "taste"
+  | "ci_rule"
+  | "adr"
+  | "security"
+  | (string & {});
+
+/**
+ * A signal — a typed piece of information flowing through the system.
+ * Signals are the atoms of the capture → classify → route → verify loop.
+ */
+export interface Signal<T = unknown> {
+  readonly id: string;
+  readonly kind: SignalKind;
+  readonly source: string; // agent id or "user" or system id
+  readonly content: T;
+  readonly confidence?: number;
+  readonly timestamp: number;
+  readonly refs?: Array<{ system: string; locator: string }>; // pointers to related knowledge
+}
+
+export type SignalHandler<T = unknown> = (signal: Signal<T>) => void | Promise<void>;
+
+/**
+ * A pub/sub bus for signals.
+ *
+ * Agents emit signals as side-channel information.
+ * Observers (Librarian, Herald, writeback rules) subscribe
+ * to signal kinds and act on them.
+ *
+ * Separate from dispatch — signals are observations about what happened,
+ * not the primary output.
+ */
+export class SignalBus {
+  private _handlers: Map<string, SignalHandler[]> = new Map();
+  private _globalHandlers: SignalHandler[] = [];
+  private _history: Signal[] = [];
+  private _maxHistory: number;
+
+  constructor(maxHistory: number = 1000) {
+    this._maxHistory = maxHistory;
+  }
+
+  /** Subscribe to a specific signal kind. */
+  on(kind: SignalKind, handler: SignalHandler): () => void {
+    if (!this._handlers.has(kind)) {
+      this._handlers.set(kind, []);
+    }
+    this._handlers.get(kind)!.push(handler);
+
+    return () => {
+      const handlers = this._handlers.get(kind);
+      if (handlers) {
+        const idx = handlers.indexOf(handler);
+        if (idx !== -1) handlers.splice(idx, 1);
+      }
+    };
+  }
+
+  /** Subscribe to ALL signals. */
+  onAny(handler: SignalHandler): () => void {
+    this._globalHandlers.push(handler);
+    return () => {
+      const idx = this._globalHandlers.indexOf(handler);
+      if (idx !== -1) this._globalHandlers.splice(idx, 1);
+    };
+  }
+
+  /** Emit a signal. Notifies kind-specific and global handlers. One handler failure doesn't kill the rest. */
+  async emit(signal: Signal): Promise<void> {
+    // Record history
+    this._history.push(signal);
+    if (this._history.length > this._maxHistory) {
+      this._history.shift();
+    }
+
+    // Snapshot handler arrays to avoid mutation during iteration
+    const kindHandlers = [...(this._handlers.get(signal.kind) ?? [])];
+    const globalHandlers = [...this._globalHandlers];
+
+    // Run all handlers — one failure doesn't block the rest
+    for (const handler of kindHandlers) {
+      try {
+        await handler(signal);
+      } catch (err) {
+        console.warn(`[SignalBus] handler error for signal "${signal.kind}":`, (err as Error).message ?? err);
+      }
+    }
+
+    for (const handler of globalHandlers) {
+      try {
+        await handler(signal);
+      } catch (err) {
+        console.warn(`[SignalBus] global handler error for signal "${signal.kind}":`, (err as Error).message ?? err);
+      }
+    }
+  }
+
+  /** Get recent signals, optionally filtered by kind. */
+  recent(kind?: SignalKind, limit: number = 50): ReadonlyArray<Signal> {
+    const filtered = kind
+      ? this._history.filter((s) => s.kind === kind)
+      : this._history;
+    return filtered.slice(-limit);
+  }
+
+  /** Clear history. */
+  clearHistory(): void {
+    this._history = [];
+  }
+}