@inixiative/foundry-core 0.1.0

package/src/trace.ts

@@ -0,0 +1,261 @@
+import type { TokenCounts } from "./token-counts";
+/**
+ * A single span in a message's journey through the system.
+ * Each stage (classify, route, dispatch, writeback, middleware) creates a span.
+ */
+export interface Span {
+  readonly id: string;
+  readonly parentId?: string;
+  readonly name: string;
+  readonly kind: SpanKind;
+  readonly agentId?: string;
+  readonly threadId?: string;
+
+  /** What layers were visible to this stage. */
+  readonly layerIds?: string[];
+
+  /** Context hash at the time of this span. */
+  readonly contextHash?: string;
+
+  /** Input to this stage. */
+  readonly input?: unknown;
+
+  /** Output from this stage. */
+  readonly output?: unknown;
+
+  readonly startedAt: number;
+  endedAt?: number;
+  durationMs?: number;
+
+  /** Status of this span. */
+  status: SpanStatus;
+
+  /** If errored, the error detail. */
+  error?: unknown;
+
+  /** Token usage for this span's LLM call (if any). */
+  tokens?: TokenCounts;
+
+  /** Estimated cost in dollars for this span's LLM call. */
+  cost?: number;
+
+  /** Arbitrary annotations from middleware or handlers. */
+  annotations: Record<string, unknown>;
+
+  /** Child spans (for nested dispatch, fan-out, etc.) */
+  children: Span[];
+}
+
+export type SpanKind =
+  | "ingress"
+  | "classify"
+  | "route"
+  | "dispatch"
+  | "execute"
+  | "decide"
+  | "middleware"
+  | "writeback"
+  | "egress"
+  | "fan"
+  | (string & {});
+
+export type SpanStatus = "running" | "ok" | "error";
+
+import { newId } from "./id";
+
+function nextSpanId(): string {
+  return newId("span");
+}
+
+/**
+ * A Trace is the full journey of a single message through the system.
+ *
+ * Created at ingress, it accumulates spans as the message flows through
+ * classify → route → dispatch → middleware → execute → writeback → egress.
+ * Each span can have child spans (e.g. a dispatch span contains an execute span,
+ * a fan span contains multiple dispatch children).
+ *
+ * The UI renders a Trace as a drillable tree — click any span to see
+ * what layers it saw, what it received, what it produced, how long it took.
+ */
+export class Trace {
+  readonly id: string;
+  readonly messageId: string;
+  readonly startedAt: number;
+  endedAt?: number;
+
+  /** The root span — usually "ingress". Children branch from here. */
+  readonly root: Span;
+
+  /** Flat index of all spans for quick lookup. */
+  private _spans: Map<string, Span> = new Map();
+
+  /** Current active span stack — the innermost is where new children attach. */
+  private _stack: Span[] = [];
+
+  constructor(messageId: string, detail?: Pick<Span, "input" | "threadId">) {
+    this.id = newId("trace");
+    this.messageId = messageId;
+    this.startedAt = performance.now();
+
+    this.root = this._createSpan("ingress", "ingress", undefined, detail);
+    this._stack.push(this.root);
+  }
+
+  /** Start a new span as a child of the current active span. */
+  start(name: string, kind: SpanKind, detail?: Partial<Span>): Span {
+    const parent = this._stack[this._stack.length - 1];
+    const span = this._createSpan(name, kind, parent?.id, detail);
+    if (parent) {
+      parent.children.push(span);
+    }
+    this._stack.push(span);
+    return span;
+  }
+
+  /** End the current active span. */
+  end(output?: unknown, error?: unknown): Span | undefined {
+    const span = this._stack.pop();
+    if (!span) return undefined;
+
+    span.endedAt = performance.now();
+    span.durationMs = span.endedAt - span.startedAt;
+
+    if (error) {
+      span.status = "error";
+      span.error = error;
+    } else {
+      span.status = "ok";
+    }
+
+    if (output !== undefined) {
+      (span as { output: unknown }).output = output;
+    }
+
+    return span;
+  }
+
+  /** End the entire trace. Closes any remaining open spans. */
+  finish(): void {
+    const now = performance.now();
+    // Close any unclosed spans — preserve their current status if already set
+    while (this._stack.length > 0) {
+      const span = this._stack.pop()!;
+      if (!span.endedAt) {
+        span.endedAt = now;
+        span.durationMs = span.endedAt - span.startedAt;
+      }
+      if (span.status === "running") {
+        span.status = "ok";
+      }
+    }
+    this.endedAt = now;
+  }
+
+  /** Get a span by id. */
+  getSpan(id: string): Span | undefined {
+    return this._spans.get(id);
+  }
+
+  /** All spans as a flat list, ordered by start time. */
+  get spans(): ReadonlyArray<Span> {
+    return [...this._spans.values()].sort((a, b) => a.startedAt - b.startedAt);
+  }
+
+  /** Total duration of the trace. */
+  get durationMs(): number | undefined {
+    return this.endedAt ? this.endedAt - this.startedAt : undefined;
+  }
+
+  /** The current active span (innermost). */
+  get current(): Span | undefined {
+    return this._stack[this._stack.length - 1];
+  }
+
+  /** How deep we are in the span stack. */
+  get depth(): number {
+    return this._stack.length;
+  }
+
+  /**
+   * Produce a summary for display — the key stages and their outcomes.
+   * This is what shows up in a message list before you drill in.
+   */
+  summary(): TraceSummary {
+    const stages: StageSummary[] = [];
+
+    const walk = (span: Span, depth: number) => {
+      stages.push({
+        name: span.name,
+        kind: span.kind,
+        status: span.status,
+        durationMs: span.durationMs,
+        agentId: span.agentId,
+        tokens: span.tokens,
+        cost: span.cost,
+        depth,
+      });
+      for (const child of span.children) {
+        walk(child, depth + 1);
+      }
+    };
+
+    walk(this.root, 0);
+
+    return {
+      traceId: this.id,
+      messageId: this.messageId,
+      totalDurationMs: this.durationMs,
+      spanCount: this._spans.size,
+      stages,
+    };
+  }
+
+  // -- Internal --
+
+  private _createSpan(
+    name: string,
+    kind: SpanKind,
+    parentId?: string,
+    detail?: Partial<Span>
+  ): Span {
+    const span: Span = {
+      id: nextSpanId(),
+      parentId,
+      name,
+      kind,
+      agentId: detail?.agentId,
+      threadId: detail?.threadId,
+      layerIds: detail?.layerIds,
+      contextHash: detail?.contextHash,
+      input: detail?.input,
+      output: undefined,
+      startedAt: performance.now(),
+      status: "running",
+      annotations: detail?.annotations ?? {},
+      children: [],
+    };
+
+    this._spans.set(span.id, span);
+    return span;
+  }
+}
+
+export interface TraceSummary {
+  readonly traceId: string;
+  readonly messageId: string;
+  readonly totalDurationMs?: number;
+  readonly spanCount: number;
+  readonly stages: StageSummary[];
+}
+
+export interface StageSummary {
+  readonly name: string;
+  readonly kind: SpanKind;
+  readonly status: SpanStatus;
+  readonly durationMs?: number;
+  readonly agentId?: string;
+  readonly tokens?: TokenCounts;
+  readonly cost?: number;
+  readonly depth: number;
+}

package/src/types.ts

@@ -0,0 +1,167 @@
+import type { TokenCounts } from "./token-counts";
+// ---------------------------------------------------------------------------
+// Shared types — used by harness for conditional invocation/activation
+// ---------------------------------------------------------------------------
+
+/**
+ * Condition for conditional invocation/activation.
+ * Matches when ANY specified field matches (OR across fields, OR within arrays).
+ */
+export interface InvocationCondition {
+  /** Match if classification.category is one of these. */
+  categories?: string[];
+  /** Match if any classification tag overlaps with these. */
+  tags?: string[];
+  /** Match if route.destination is one of these. */
+  routes?: string[];
+}
+
+/**
+ * Minimal agent mode config — what the harness needs from config.
+ * Full AgentSettingsConfig lives in @inixiative/foundry.
+ */
+export interface AgentModeConfig {
+  invocation?: "always" | "on-demand" | "conditional";
+  condition?: InvocationCondition;
+}
+
+/**
+ * Minimal layer mode config — what the harness needs from config.
+ * Full LayerSettingsConfig lives in @inixiative/foundry.
+ */
+export interface LayerModeConfig {
+  activation?: "always" | "on-demand" | "conditional";
+  condition?: InvocationCondition;
+}
+
+// ---------------------------------------------------------------------------
+// LLM provider interface — the abstraction, not implementations
+// ---------------------------------------------------------------------------
+
+export interface LLMMessage {
+  readonly role: "system" | "user" | "assistant";
+  readonly content: string;
+}
+
+/** Tool definition sent to the LLM so it can call tools. */
+export interface ToolDefinition {
+  /** Tool name (e.g., "shell_exec", "memory_search"). */
+  name: string;
+  /** Short description for the LLM. */
+  description: string;
+  /** JSON Schema for the tool's input parameters. */
+  inputSchema: Record<string, unknown>;
+}
+
+/** A tool call returned by the LLM. */
+export interface ToolCall {
+  /** Provider-assigned call ID (for matching results). */
+  id: string;
+  /** Tool name to invoke. */
+  name: string;
+  /** Parsed input arguments. */
+  input: Record<string, unknown>;
+}
+
+/** Result of executing a tool call, fed back to the LLM. */
+export interface ToolCallResult {
+  /** Matches the ToolCall.id. */
+  toolCallId: string;
+  /** Serialized result content. */
+  content: string;
+  /** Whether the tool call succeeded. */
+  isError?: boolean;
+}
+
+export interface CompletionOpts {
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  topP?: number;
+  stop?: string[];
+  /** Max agentic turns (for runtimes that support tool use). */
+  maxTurns?: number | null;
+  /** Additive native ownership contract; optional for standalone/legacy providers. */
+  nativeObservation?: import("./native-evidence").NativeObservation;
+  /** Enable/disable tool use. False = pure text completion. */
+  tools?: boolean;
+  /** Tool definitions for the LLM to call. Providers map to native format. */
+  toolDefinitions?: ToolDefinition[];
+
+  // -- Extended knobs (providers map these to their native APIs) --
+
+  /**
+   * Extended thinking / reasoning effort level.
+   * Providers translate: Anthropic → thinking.budget_tokens, OpenAI → reasoning_effort.
+   * "none" = no thinking, "low"/"medium"/"high" = increasing effort, number = explicit budget tokens.
+   */
+  thinking?: "none" | "low" | "medium" | "high" | number;
+  /** Permission level for code execution runtimes (claude-code, codex). */
+  permissions?: "bypass" | "supervised" | "restricted";
+  /** Per-call timeout in ms. Provider uses its own default if omitted. */
+  timeout?: number;
+  /** Enable prompt caching where supported. */
+  cacheControl?: boolean;
+  /** Thread ID — used by session-aware providers (e.g. ClaudeCode) to resume sessions. */
+  threadId?: string;
+  /** Working directory for this completion (worktree path). Provider uses its own default if omitted. */
+  cwd?: string;
+  /** Scheduling hint for providers that queue calls: higher runs first. Default 0. Others ignore it. */
+  priority?: number;
+}
+
+export interface CompletionResult {
+  readonly native?: import("./native-evidence").NativeEvidence;
+  readonly content: string;
+  readonly model: string;
+  readonly tokens?: TokenCounts;
+  readonly finishReason?: string;
+  /** Tool calls requested by the LLM (present when finishReason is "tool_use"). */
+  readonly toolCalls?: ToolCall[];
+  readonly raw?: unknown;
+}
+
+export interface EmbeddingResult {
+  readonly embedding: number[];
+  readonly tokens?: number;
+}
+
+export interface LLMStreamEvent {
+  type: "text" | "usage" | "done" | "error";
+  text?: string;
+  tokens?: TokenCounts;
+  error?: string;
+  finishReason?: string;
+}
+
+export interface LLMProvider {
+  readonly id: string;
+  /** Native callback support, distinct from stateless/legacy serializable options. */
+  readonly nativeOwnership?: "required-prewrite";
+  /** Optional owned-call evidence. A rejected waiter alone never proves remote settlement. */
+  readonly completionLifecycle?: {
+    readonly kind: "request" | "session";
+    settlement(outcome: { result?: CompletionResult; error?: unknown }): "settled" | "unknown";
+    admission?(outcome: { result?: CompletionResult; error?: unknown }): "not-admitted" | "attempted" | "unknown";
+    /** Read only the original registered admission. Never sends, resumes or replaces work. */
+    inspectOwnedAdmission?(owner: import("./native-evidence").NativeOwner, admissionId: string): Promise<import("./native-evidence").OwnedAdmissionInspection | undefined>;
+    /** Cleanup of that original, confirmed idle pool entry; never a current-scope lookup. */
+    releaseOwnedAdmission?(owner: import("./native-evidence").NativeOwner, admissionId: string): Promise<"released" | "unknown" | "unavailable">;
+    /** Release only a confirmed idle owned resource; never clear its resume binding. */
+    releaseIdle?(opts: CompletionOpts): Promise<"released" | "unknown" | "unavailable">;
+  };
+  complete(
+    messages: LLMMessage[],
+    opts?: CompletionOpts
+  ): Promise<CompletionResult>;
+  stream?(
+    messages: LLMMessage[],
+    opts?: CompletionOpts
+  ): AsyncGenerator<LLMStreamEvent>;
+}
+
+export interface EmbeddingProvider {
+  readonly id: string;
+  embed(text: string): Promise<EmbeddingResult>;
+  embedBatch?(texts: string[]): Promise<EmbeddingResult[]>;
+}