@inixiative/foundry-core 0.1.0

package/src/intervention.ts

@@ -0,0 +1,134 @@
+import type { Signal, SignalBus } from "./signal";
+import type { Trace, Span } from "./trace";
+import { newId } from "./id";
+
+/**
+ * An intervention — a manual override from a human operator.
+ *
+ * When the system forks erroneously, routes to the wrong place,
+ * or makes a bad classification, the operator can intervene.
+ * The intervention:
+ *   1. Records what happened (the trace/span that was wrong)
+ *   2. Records what should have happened (the correction)
+ *   3. Optionally replays with the correction
+ *   4. Emits a "correction" signal so the system learns
+ *
+ * Over time, corrections accumulate and shape the context layers —
+ * the system makes fewer mistakes on the same patterns.
+ */
+export interface Intervention {
+  readonly id: string;
+  readonly timestamp: number;
+
+  /** What trace this intervention targets. */
+  readonly traceId: string;
+
+  /** Which span was wrong (the specific stage — route, classify, dispatch). */
+  readonly spanId: string;
+
+  /** What the system did. */
+  readonly actual: unknown;
+
+  /** What the operator says it should have done. */
+  readonly correction: unknown;
+
+  /** Free-form reason — becomes part of the correction signal's content. */
+  readonly reason?: string;
+
+  /** Who intervened. */
+  readonly operator: string;
+}
+
+/**
+ * Manages manual interventions.
+ *
+ * When an operator overrides a decision, the InterventionLog:
+ * - Records the intervention
+ * - Emits a correction signal on the signal bus
+ * - Provides the intervention history for the UI
+ *
+ * The correction signal flows through the normal signal pipeline —
+ * the Librarian classifies it, it gets routed to the right memory layer,
+ * and future decisions are shaped by it.
+ */
+export class InterventionLog {
+  private _interventions: Intervention[] = [];
+  private _signals: SignalBus;
+  private _maxHistory: number;
+
+  constructor(signals: SignalBus, maxHistory: number = 1000) {
+    this._signals = signals;
+    this._maxHistory = maxHistory;
+  }
+
+  /**
+   * Record an intervention and emit a correction signal.
+   */
+  async intervene(
+    traceId: string,
+    spanId: string,
+    actual: unknown,
+    correction: unknown,
+    operator: string,
+    reason?: string
+  ): Promise<Intervention> {
+    const intervention: Intervention = {
+      id: newId("int"),
+      timestamp: Date.now(),
+      traceId,
+      spanId,
+      actual,
+      correction,
+      reason,
+      operator,
+    };
+
+    this._interventions.push(intervention);
+    if (this._interventions.length > this._maxHistory) {
+      this._interventions.shift();
+    }
+
+    // Emit as a correction signal so the system learns
+    await this._signals.emit({
+      id: `sig_${intervention.id}`,
+      kind: "correction",
+      source: `operator:${operator}`,
+      content: {
+        traceId,
+        spanId,
+        actual,
+        correction,
+        reason,
+      },
+      confidence: 1.0, // human corrections are high confidence
+      timestamp: Date.now(),
+    });
+
+    return intervention;
+  }
+
+  /** Get all interventions, most recent first. */
+  get history(): ReadonlyArray<Intervention> {
+    return [...this._interventions].reverse();
+  }
+
+  /** Get interventions for a specific trace. */
+  forTrace(traceId: string): Intervention[] {
+    return this._interventions.filter((i) => i.traceId === traceId);
+  }
+
+  /** Get recent corrections as signal content (for feeding into context layers). */
+  recentCorrections(limit: number = 20): Array<{
+    actual: unknown;
+    correction: unknown;
+    reason?: string;
+    timestamp: number;
+  }> {
+    return this._interventions.slice(-limit).map((i) => ({
+      actual: i.actual,
+      correction: i.correction,
+      reason: i.reason,
+      timestamp: i.timestamp,
+    }));
+  }
+}

package/src/messages.ts

@@ -0,0 +1,315 @@
+import type { AssembledContext, PromptBlock } from "./context-stack";
+import { computeHash } from "./context-layer";
+import type { LayerInstanceState, LogicalMessageIdentity } from "./context-layer";
+import type { LLMMessage } from "./types";
+
+export type InjectionSegmentKind =
+  | "instructions"
+  | "domain-knowledge"
+  | "thread-knowledge"
+  | "routing"
+  | "guard-findings";
+
+export interface InjectionBlock {
+  readonly id: string;
+  readonly kind: InjectionSegmentKind;
+  readonly source: string;
+  readonly text: string;
+  readonly hash: string;
+  readonly tokens: number;
+  readonly freshness?: {
+    readonly state?: string;
+    readonly lastWarmed?: number | null;
+  };
+}
+
+/** One decorator's recorded participation in a turn. */
+export interface DecorationParticipant {
+  readonly id: string;
+  /** contribute | abstain | error | timeout | omitted */
+  readonly decision: string;
+  readonly reason?: string;
+  /** The three named inputs the participant worked from, never inferred. */
+  readonly segments: {
+    readonly instructions: string;
+    readonly domainKnowledge: string;
+    readonly threadKnowledge: string;
+  };
+  readonly provenance: Record<string, unknown>;
+  /**
+   * The provider input this participant supplied at its phase, frozen at the call boundary, or
+   * that no call was made. Absent on records written before capture existed. Recording the input
+   * is evidence of what was supplied to the provider interface, not that a native model received it.
+   */
+  readonly request?: ParticipantRequest;
+}
+
+/** What one participant supplied to its provider at one phase, or why it made no call. */
+export type ParticipantRequest =
+  | {
+      readonly status: "supplied";
+      readonly phase: string;
+      readonly providerId: string;
+      readonly messages: readonly LLMMessage[];
+      readonly capturedAt: number;
+    }
+  | { readonly status: "not-sent"; readonly phase: string; readonly reason: string }
+  /** A call may have been made, but its input was never observed (e.g. the caller threw first). Not "not-sent". */
+  | { readonly status: "unobserved"; readonly phase: string; readonly reason: string };
+
+/**
+ * The composed, immutable decoration delivered alongside a user message:
+ * the blocks appended to the executor context plus who contributed them.
+ */
+export interface MessageDecoration {
+  readonly input: { readonly hash: string; readonly capturedAt: number; readonly currentMessage?: LogicalMessageIdentity };
+  readonly blocks: PromptBlock[];
+  readonly participants: DecorationParticipant[];
+  readonly omissions: Array<{ readonly id: string; readonly reason: string }>;
+  readonly conflicts: Array<{ readonly kind: string; readonly id: string; readonly detail: string }>;
+}
+
+/**
+ * What a completed dispatch actually delivered, per included layer, against
+ * what the decorator assessed. Attached to `ExecutionResult.meta.delivery`
+ * by the runtime after the delivery ledger is committed.
+ */
+export interface DeliveryRecord {
+  readonly layers: Array<{
+    readonly id: string;
+    readonly threadId?: string;
+    readonly projectId?: string;
+    /** Domain that owns this layer, when a participant assessed it. */
+    readonly domain?: string;
+    /** Hash the decorator assessed, when a domain owns this layer. */
+    readonly assessedHash?: string;
+    /** Owner revision the decorator assessed, for owner-versioned layers. */
+    readonly assessedRevision?: number;
+    /** Hash the executor assembled and sent. */
+    readonly deliveredHash: string;
+    /** Owner revision of the bytes actually assembled, from the layer's own version mark at assembly. */
+    readonly deliveredRevision?: number;
+    /**
+     * How the delivered snapshot relates to the assessed one: the same revision, a later revision committed
+     * between assessment and assembly, no owner mark on the delivered bytes, or an inconsistent pair.
+     */
+    readonly relation?: "assessed" | "advanced" | "unknown" | "inconsistent";
+    /** True when the layer changed between assessment and delivery. */
+    readonly drift: boolean;
+  }>;
+  /** Layer ids committed to the delivery ledger. */
+  readonly committed: string[];
+  /**
+   * How the turn treated learning still pending from earlier work:
+   * `pending` means preparation continued immediately with committed knowledge.
+   * `settled` and `timeout` are retained for historical artifacts.
+   */
+  readonly learningBarrier?: {
+    readonly outcome: "none" | "settled" | "timeout" | "pending" | "closed";
+    readonly closed?: ReadonlyArray<{ domain: string; reason: string }>;
+    readonly waitedMs: number;
+    readonly pending: Array<{ readonly domain: string; readonly reviews: number }>;
+    readonly stale: string[];
+  };
+}
+
+export interface InjectionArtifact {
+  readonly capturedAt?: number;
+  readonly threadId?: string;
+  readonly projectId?: string;
+  readonly messageId?: string;
+  /** Integrity-bound initial provider callback; never a native acknowledgment. */
+  readonly providerBoundary?: import("./delivery-evidence").ProviderBoundaryReceipt;
+  readonly userMessage: string;
+  readonly blocks: InjectionBlock[];
+  /** Decoration delivered with this turn, when a decorator ran. */
+  readonly decoration?: MessageDecoration;
+  /** The sealed pre-message plan that produced the decoration. */
+  readonly plan?: unknown;
+  /** Segmented reading view, not the provider's wire format. */
+  readonly text: string;
+  readonly tokens: number;
+  readonly executorContext?: string;
+  /** Initial provider messages, before native-runtime wrapping or tool followups. */
+  readonly providerMessages?: LLMMessage[];
+  readonly layers?: Array<LayerInstanceState & {
+    id: string;
+    prompt?: string;
+    sourceIds: string[];
+    included: boolean;
+  }>;
+}
+
+export interface BuildInjectionArtifactOpts {
+  readonly userMessage: string;
+  readonly assembled: AssembledContext;
+  readonly layerFreshness?: Record<string, { state?: string; lastWarmed?: number | null }>;
+  readonly routing?: string;
+  readonly guardFindings?: string;
+  /** Decoration blocks are appended after the assembled layers, in order. */
+  readonly decoration?: MessageDecoration;
+}
+
+function estimateTextTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+function segmentKindForBlock(block: PromptBlock): InjectionSegmentKind {
+  if (block.role === "system") return "instructions";
+  if (block.role === "layer") return "instructions";
+  if (block.id === "__thread-state" || block.id === "thread-state" || block.id === "memory") {
+    return "thread-knowledge";
+  }
+  return "domain-knowledge";
+}
+
+function blockTitle(kind: InjectionSegmentKind): string {
+  switch (kind) {
+    case "routing":
+      return "Tags / Routing";
+    case "instructions":
+      return "Instructions";
+    case "domain-knowledge":
+      return "Domain Knowledge";
+    case "thread-knowledge":
+      return "Thread State";
+    case "guard-findings":
+      return "Prior Guard Findings";
+  }
+}
+
+function makeBlock(
+  kind: InjectionSegmentKind,
+  source: string,
+  text: string,
+  freshness?: InjectionBlock["freshness"],
+): InjectionBlock {
+  return {
+    id: `${kind}:${source}:${computeHash(text)}`,
+    kind,
+    source,
+    text,
+    hash: computeHash(text),
+    tokens: estimateTextTokens(text),
+    freshness,
+  };
+}
+
+/**
+ * Build a segmented reading view of the context supplied to an executor.
+ *
+ * The artifact keeps Foundry's intervention boundaries visible: the user
+ * message remains separate from injected routing, instructions, domain
+ * knowledge, thread state, and guard findings.
+ */
+export function buildInjectionArtifact(opts: BuildInjectionArtifactOpts): InjectionArtifact {
+  const blocks: InjectionBlock[] = [];
+
+  if (opts.routing?.trim()) {
+    blocks.push(makeBlock("routing", "route", opts.routing.trim()));
+  }
+
+  for (const block of [...opts.assembled.blocks, ...(opts.decoration?.blocks ?? [])]) {
+    if (!block.text.trim()) continue;
+    // An explicit segment always wins; the id heuristic only classifies plain layers.
+    const kind = (block.segment as InjectionSegmentKind | undefined) ?? segmentKindForBlock(block);
+    const source = block.source ?? block.id ?? block.role;
+    blocks.push(makeBlock(kind, source, block.text, block.id ? opts.layerFreshness?.[block.id] : undefined));
+  }
+
+  if (opts.guardFindings?.trim()) {
+    blocks.push(makeBlock("guard-findings", "guards", opts.guardFindings.trim()));
+  }
+
+  const sections = [
+    "# User Message",
+    opts.userMessage,
+    "# Foundry Injection",
+  ];
+
+  const byKind = new Map<InjectionSegmentKind, InjectionBlock[]>();
+  for (const block of blocks) {
+    const existing = byKind.get(block.kind) ?? [];
+    existing.push(block);
+    byKind.set(block.kind, existing);
+  }
+
+  const order: InjectionSegmentKind[] = [
+    "routing",
+    "instructions",
+    "domain-knowledge",
+    "thread-knowledge",
+    "guard-findings",
+  ];
+
+  for (const kind of order) {
+    const grouped = byKind.get(kind);
+    if (!grouped?.length) continue;
+    sections.push(`## ${blockTitle(kind)}`);
+    sections.push(grouped.map((block) => block.text).join("\n\n"));
+  }
+
+  const text = sections.join("\n\n");
+  return {
+    userMessage: opts.userMessage,
+    blocks,
+    text,
+    tokens: estimateTextTokens(text),
+    ...(opts.decoration ? { decoration: opts.decoration } : {}),
+  };
+}
+
+/**
+ * Convert an AssembledContext (from stack.assemble()) into LLMMessages
+ * ready for any provider.
+ */
+export function assembledToMessages(
+  assembled: AssembledContext,
+  userPayload: string
+): LLMMessage[] {
+  const messages: LLMMessage[] = [];
+
+  if (assembled.blocks.length > 0) {
+    const systemParts: string[] = [];
+
+    for (const block of assembled.blocks) {
+      if (block.role === "system") {
+        systemParts.push(block.text);
+      } else if (block.role === "layer") {
+        systemParts.push(`[${block.id}]: ${block.text}`);
+      } else if (block.role === "content") {
+        systemParts.push(block.text);
+      }
+    }
+
+    messages.push({ role: "system", content: systemParts.join("\n\n") });
+  }
+
+  messages.push({ role: "user", content: userPayload });
+
+  return messages;
+}
+
+/**
+ * Split LLMMessages into provider-friendly parts.
+ */
+export function splitSystemMessage(messages: LLMMessage[]): {
+  system: string | undefined;
+  turns: LLMMessage[];
+} {
+  const systemParts: string[] = [];
+  const turns: LLMMessage[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      systemParts.push(msg.content);
+    } else {
+      turns.push(msg);
+    }
+  }
+
+  return {
+    system: systemParts.length > 0 ? systemParts.join("\n\n") : undefined,
+    turns,
+  };
+}

package/src/middleware.ts

@@ -0,0 +1,118 @@
+import type { ExecutionResult } from "./base-agent";
+import type { ContextStackView } from "./context-stack";
+
+export interface DispatchContext<TPayload = unknown> {
+  readonly agentId: string;
+  readonly payload: TPayload;
+  readonly timestamp: number;
+
+  /** Mutable bag for middleware to annotate. */
+  annotations: Record<string, unknown>;
+
+  /** Read-only view of the thread's context stack. */
+  readonly stack?: ContextStackView;
+  /** Thread identity. */
+  readonly threadId?: string;
+  readonly projectId?: string;
+  /** Logical message being processed; absent for unidentified direct/background work. */
+  readonly messageId?: string;
+  /** Identity of this dispatch; tool observations for it carry the same id. */
+  readonly dispatchId?: string;
+}
+
+export interface DispatchOutcome<TResult = unknown> {
+  readonly context: DispatchContext;
+  readonly result: ExecutionResult<TResult>;
+  readonly durationMs: number;
+}
+
+export type MiddlewareNext = () => Promise<ExecutionResult>;
+
+export type Middleware = (
+  ctx: DispatchContext,
+  next: MiddlewareNext
+) => Promise<ExecutionResult>;
+
+/**
+ * When a middleware should run.
+ *
+ * - "always": runs on every dispatch (logging, tracing, metrics)
+ * - "conditional": runs only when its `when` predicate returns true
+ *   (deep classification, expensive enrichment, guardrails)
+ */
+export type MiddlewareTier = "always" | "conditional";
+
+export interface MiddlewareEntry {
+  readonly id: string;
+  readonly tier: MiddlewareTier;
+  readonly fn: Middleware;
+  readonly when?: (ctx: DispatchContext) => boolean;
+}
+
+/**
+ * A composable middleware chain with tiered execution.
+ *
+ * "always" middleware runs on every request — lightweight, fast.
+ * "conditional" middleware runs only when its predicate matches —
+ * heavier, richer, only when needed.
+ *
+ * Both tiers compose in registration order on the way in,
+ * reverse order on the way out (Koa-style).
+ */
+export class MiddlewareChain {
+  private _middleware: MiddlewareEntry[] = [];
+
+  /** Register always-on middleware. */
+  use(id: string, fn: Middleware): void {
+    this._middleware.push({ id, tier: "always", fn });
+  }
+
+  /** Register conditional middleware with a predicate. */
+  useWhen(
+    id: string,
+    when: (ctx: DispatchContext) => boolean,
+    fn: Middleware
+  ): void {
+    this._middleware.push({ id, tier: "conditional", fn, when });
+  }
+
+  remove(id: string): boolean {
+    const idx = this._middleware.findIndex((m) => m.id === id);
+    if (idx === -1) return false;
+    this._middleware.splice(idx, 1);
+    return true;
+  }
+
+  /** Execute the chain. Conditional middleware only runs when its predicate matches. */
+  async execute(
+    ctx: DispatchContext,
+    handler: MiddlewareNext
+  ): Promise<ExecutionResult> {
+    // Build the active stack for this request
+    const active = this._middleware.filter((m) => {
+      if (m.tier === "always") return true;
+      return m.when ? m.when(ctx) : false;
+    });
+
+    let idx = 0;
+
+    const run = async (): Promise<ExecutionResult> => {
+      if (idx >= active.length) {
+        return handler();
+      }
+      const current = active[idx++];
+      return current.fn(ctx, run);
+    };
+
+    return run();
+  }
+
+  get size(): number {
+    return this._middleware.length;
+  }
+
+  /** Get entries by tier (for UI display). */
+  byTier(tier: MiddlewareTier): ReadonlyArray<MiddlewareEntry> {
+    return this._middleware.filter((m) => m.tier === tier);
+  }
+}