@inixiative/foundry-core 0.2.0 → 0.3.0

package/src/thread.ts

@@ -1,20 +1,62 @@
-import { ContextStack } from "./context-stack";
-import type { LayerFilter, ContextStackView } from "./context-stack";
-import { CacheLifecycle } from "./cache-lifecycle";
-import { BaseAgent, type ExecutionResult } from "./base-agent";
-import { MiddlewareChain, type DispatchContext } from "./middleware";
-import { SignalBus } from "./signal";
-import type { TokenTracker } from "./token-tracker";
-import type { ToolCallObservation } from "./tools";
-import type { InjectionArtifact } from "./messages";
-import { newId } from "./id";
-
-export type ThreadStatus = "idle" | "active" | "waiting" | "archived";
+import type { BaseAgent, ExecutionResult } from './base-agent';
+import { CacheLifecycle } from './cache-lifecycle';
+import type { ContextStack, ContextStackView, LayerFilter } from './context-stack';
+import { newId } from './id';
+import type { InjectionArtifact } from './messages';
+import { type DispatchContext, MiddlewareChain } from './middleware';
+import { SignalBus } from './signal';
+import type { TokenTracker } from './token-tracker';
+import type { ToolCallObservation } from './tools';
+
+export type ThreadStatus = 'idle' | 'active' | 'waiting' | 'archived';
+
+/** A thread name and when it was set. */
+export interface ThreadName {
+  readonly text: string;
+  readonly updatedAt: number;
+}
+
+/** Tracked work a thread links to, in Archive's integration-reference shape (`github` `owner/repo#12`, `linear` `ENG-4`). */
+export interface ThreadReference {
+  readonly integration: string;
+  readonly ref: string;
+  readonly url?: string;
+}
+
+/** Where a thread's work lives, as the runtime last observed it. */
+export interface ThreadContext {
+  /** `owner/repo` of the worktree's origin. */
+  readonly repository?: string;
+  /** Branch checked out in the worktree now (may differ from the assigned `branch`). */
+  readonly branch?: string;
+  /** Worktree root containing the thread's cwd. */
+  readonly worktree?: string;
+  readonly references: readonly ThreadReference[];
+  readonly updatedAt: number;
+}
+
+/** The name a thread shows: a person's name overrides the agent-maintained one. */
+export function threadTitle(
+  meta: Pick<ThreadMeta, 'name' | 'agentName' | 'description'>,
+): { text: string; source: 'human' | 'agent' | 'description' } | undefined {
+  if (meta.name?.text) return { text: meta.name.text, source: 'human' };
+  if (meta.agentName?.text) return { text: meta.agentName.text, source: 'agent' };
+  return meta.description ? { text: meta.description, source: 'description' } : undefined;
+}
 
 export interface ThreadMeta {
   /** Living description — what this thread is doing right now. */
   description: string;
 
+  /** Name a person set. A hard override: agents never change it. */
+  name?: ThreadName;
+
+  /** Name an agent maintains while no person has named the thread. */
+  agentName?: ThreadName;
+
+  /** Branch, worktree and linked PRs/tickets, derived by the runtime. */
+  context?: ThreadContext;
+
   /** Classification tags — what kind of work this thread handles. */
   tags: string[];
 
@@ -53,7 +95,7 @@ export interface Dispatch<T = unknown> {
 
 export interface FanResult {
   readonly agentId: string;
-  readonly status: "fulfilled" | "rejected";
+  readonly status: 'fulfilled' | 'rejected';
   readonly result?: ExecutionResult;
   readonly error?: unknown;
 }
@@ -69,8 +111,10 @@ export interface BackgroundHandle {
  * observation signal; the thread never invents them.
  */
 export interface DispatchOptions {
-  nativeObservation?: Omit<import("./native-evidence").NativeObservation, "owner"> & { generation: string };
-  recordNative?: (evidence: import("./native-evidence").NativeEvidence) => void;
+  nativeObservation?: Omit<import('./native-evidence').NativeObservation, 'owner'> & {
+    generation: string;
+  };
+  recordNative?: (evidence: import('./native-evidence').NativeEvidence) => void;
   recordCompleted?: (output: unknown) => void;
   /** Streaming sink for executor text deltas. */
   onDelta?: (text: string) => void;
@@ -167,9 +211,9 @@ export class Thread {
 
     const now = Date.now();
     this.meta = {
-      description: opts?.description ?? "",
+      description: opts?.description ?? '',
       tags: opts?.tags ?? [],
-      status: "idle",
+      status: 'idle',
       cwd: opts?.cwd,
       branch: opts?.branch,
       parentThreadId: opts?.parentThreadId,
@@ -204,6 +248,13 @@ export class Thread {
     this.meta.description = description;
   }
 
+  /** Set (or with an empty name, clear) the person-given name. */
+  rename(name: string): void {
+    const text = name.trim();
+    if (!text) delete this.meta.name;
+    else if (text !== this.meta.name?.text) this.meta.name = { text, updatedAt: Date.now() };
+  }
+
   /** Update tags. */
   tag(...tags: string[]): void {
     for (const t of tags) {
@@ -256,7 +307,7 @@ export class Thread {
 
   /** Archive this thread. Sets the terminal status, then disposes. */
   archive(): void {
-    this.meta.status = "archived";
+    this.meta.status = 'archived';
     this.meta.archivedAt = Date.now();
     this.dispose();
   }
@@ -277,7 +328,7 @@ export class Thread {
     // This dispatch's observation and middleware must retain the same logical
     // identity even if a caller later reuses/mutates its options object.
     opts = opts ? { ...opts } : undefined;
-    if (this.meta.status === "archived") {
+    if (this.meta.status === 'archived') {
       throw new Error(`Thread archived: ${this.id} cannot dispatch "${agentId}"`);
     }
     if (this._disposed) {
@@ -287,13 +338,13 @@ export class Thread {
     if (!agent) throw new Error(`Agent not found: ${agentId}`);
 
     this._activeDispatches++;
-    this.meta.status = "active";
+    this.meta.status = 'active';
     this.meta.lastActiveAt = Date.now();
 
     // Explicit identity for this dispatch. Middleware sees it, tool calls
     // executed on its behalf are observed with it, and the completion
     // observation carries it, so evidence never drifts to another completion.
-    const dispatchId = newId("dispatch");
+    const dispatchId = newId('dispatch');
     const ctx: DispatchContext<TPayload> = {
       agentId,
       payload,
@@ -315,33 +366,52 @@ export class Thread {
       messageId: ctx.messageId,
       dispatchId,
       observeTool: (observation: ToolCallObservation) => {
-        void this.signals.emit({
-          id: newId("sig-tool"),
-          kind: "tool_observation",
-          source: `thread:${this.id}`,
-          content: { threadId: this.id, dispatchId, agentId, ...observation, timestamp: Date.now() },
-          timestamp: Date.now(),
-        }).catch((err) => {
-          console.warn(`[Thread] tool observation failed for "${agentId}":`, (err as Error).message ?? err);
-        });
+        void this.signals
+          .emit({
+            id: newId('sig-tool'),
+            kind: 'tool_observation',
+            source: `thread:${this.id}`,
+            content: {
+              threadId: this.id,
+              dispatchId,
+              agentId,
+              ...observation,
+              timestamp: Date.now(),
+            },
+            timestamp: Date.now(),
+          })
+          .catch((err) => {
+            console.warn(
+              `[Thread] tool observation failed for "${agentId}":`,
+              (err as Error).message ?? err,
+            );
+          });
       },
       annotations: ctx.annotations,
       onDelta: opts?.onDelta,
       recordInjection: opts?.recordInjection,
       recordNative: opts?.recordNative,
       recordCompleted: opts?.recordCompleted,
-      nativeObservation: opts?.nativeObservation ? {
-        preflight: opts.nativeObservation.preflight,
-        bridge: opts.nativeObservation.bridge,
-        register: opts.nativeObservation.register, observe: opts.nativeObservation.observe,
-        owner: Object.freeze({ threadId: this.id, projectId: this.meta.projectId, generation: opts.nativeObservation.generation,
-          messageId: ctx.messageId, dispatchId }),
-      } : undefined,
+      nativeObservation: opts?.nativeObservation
+        ? {
+            preflight: opts.nativeObservation.preflight,
+            bridge: opts.nativeObservation.bridge,
+            register: opts.nativeObservation.register,
+            observe: opts.nativeObservation.observe,
+            owner: Object.freeze({
+              threadId: this.id,
+              projectId: this.meta.projectId,
+              generation: opts.nativeObservation.generation,
+              messageId: ctx.messageId,
+              dispatchId,
+            }),
+          }
+        : undefined,
     };
 
     try {
       const result = await this.middleware.execute(ctx, () =>
-        agent.run(payload, filterOverride, meta)
+        agent.run(payload, filterOverride, meta),
       );
 
       const durationMs = performance.now() - start;
@@ -350,8 +420,8 @@ export class Thread {
       if (this._tokenTracker && result.tokens) {
         const llm = agent.llm;
         this._tokenTracker.record({
-          provider: llm?.provider ?? "unknown",
-          model: llm?.model ?? "unknown",
+          provider: llm?.provider ?? 'unknown',
+          model: llm?.model ?? 'unknown',
           agentId,
           threadId: this.id,
           tokens: result.tokens,
@@ -389,8 +459,8 @@ export class Thread {
       this._activeDispatches--;
       // Only the last finishing dispatch returns the thread to idle, and a
       // late completion must not resurrect an archived (or paused) thread.
-      if (this._activeDispatches === 0 && this.meta.status === "active") {
-        this.meta.status = "idle";
+      if (this._activeDispatches === 0 && this.meta.status === 'active') {
+        this.meta.status = 'idle';
       }
     }
   }
@@ -405,12 +475,10 @@ export class Thread {
     filterOverride?: LayerFilter,
     opts?: DispatchOptions,
   ): BackgroundHandle {
-    const promise = this.dispatch(agentId, payload, filterOverride, opts).catch(
-      async (err) => {
-        console.warn(`[Thread] background dispatch "${agentId}" failed:`, (err as Error).message);
-        return { output: null, contextHash: "" } as ExecutionResult;
-      }
-    );
+    const promise = this.dispatch(agentId, payload, filterOverride, opts).catch(async (err) => {
+      console.warn(`[Thread] background dispatch "${agentId}" failed:`, (err as Error).message);
+      return { output: null, contextHash: '' } as ExecutionResult;
+    });
     return { agentId, promise };
   }
 
@@ -425,14 +493,14 @@ export class Thread {
     opts?: DispatchOptions,
   ): Promise<FanResult[]> {
     const settled = await Promise.allSettled(
-      agentIds.map((id) => this.dispatch(id, payload, filterOverride, opts))
+      agentIds.map((id) => this.dispatch(id, payload, filterOverride, opts)),
     );
 
     return settled.map((s, i) => {
-      if (s.status === "fulfilled") {
-        return { agentId: agentIds[i], status: "fulfilled" as const, result: s.value };
+      if (s.status === 'fulfilled') {
+        return { agentId: agentIds[i], status: 'fulfilled' as const, result: s.value };
       } else {
-        return { agentId: agentIds[i], status: "rejected" as const, error: s.reason };
+        return { agentId: agentIds[i], status: 'rejected' as const, error: s.reason };
       }
     });
   }
@@ -444,7 +512,7 @@ export class Thread {
     payload: unknown,
     opts: DispatchOptions | undefined,
     dispatchId: string,
-    outcome: Pick<DispatchObservation, "durationMs" | "ok" | "error" | "contextHash" | "output">,
+    outcome: Pick<DispatchObservation, 'durationMs' | 'ok' | 'error' | 'contextHash' | 'output'>,
   ): Promise<void> {
     const content: DispatchObservation = {
       threadId: this.id,
@@ -458,14 +526,17 @@ export class Thread {
     };
     try {
       await this.signals.emit({
-        id: newId("sig-dispatch"),
-        kind: "dispatch",
+        id: newId('sig-dispatch'),
+        kind: 'dispatch',
         source: opts?.role ? `harness:${agentId}` : `thread:${this.id}`,
         content,
         timestamp: Date.now(),
       });
     } catch (err) {
-      console.warn(`[Thread] dispatch observation failed for "${agentId}":`, (err as Error).message ?? err);
+      console.warn(
+        `[Thread] dispatch observation failed for "${agentId}":`,
+        (err as Error).message ?? err,
+      );
     }
   }
 
@@ -481,11 +552,15 @@ export class Thread {
       },
       getContent: (id) => {
         const l = stack.getLayer(id);
-        return l?.isWarm ? l.content : "";
+        return l?.isWarm ? l.content : '';
       },
       getState: (id) => stack.getLayer(id)?.state,
-      get layerIds() { return stack.layers.map((l) => l.id); },
-      get estimatedTokens() { return stack.estimateTokens(); },
+      get layerIds() {
+        return stack.layers.map((l) => l.id);
+      },
+      get estimatedTokens() {
+        return stack.estimateTokens();
+      },
     };
   }
 
@@ -502,7 +577,9 @@ export class Thread {
    */
   start(): void {
     if (this._disposed) {
-      throw new Error(`Thread disposed: ${this.id} cannot be started; create a new thread to restore it`);
+      throw new Error(
+        `Thread disposed: ${this.id} cannot be started; create a new thread to restore it`,
+      );
     }
     this.lifecycle.start();
   }
@@ -515,7 +592,7 @@ export class Thread {
 /** Serialize a dispatch payload for observation, bounded in size. */
 function serializePayload(payload: unknown): string {
   let text: string;
-  if (typeof payload === "string") {
+  if (typeof payload === 'string') {
     text = payload;
   } else {
     try {

package/src/token-counts.ts

@@ -21,7 +21,15 @@ export function totalTokenCount(tokens: TokenCounts): number {
 export function sumTokenCounts(entries: Iterable<TokenCounts>): TokenCounts {
   const total: TokenCounts = { input: 0, output: 0 };
   for (const entry of entries) {
-    for (const key of ["input", "output", "cacheRead", "cacheWrite", "cacheWrite5m", "cacheWrite1h", "thinking"] as const) {
+    for (const key of [
+      'input',
+      'output',
+      'cacheRead',
+      'cacheWrite',
+      'cacheWrite5m',
+      'cacheWrite1h',
+      'thinking',
+    ] as const) {
       const value = entry[key];
       if (value !== undefined) total[key] = (total[key] ?? 0) + value;
     }

package/src/token-tracker.ts

@@ -1,4 +1,4 @@
-import { type TokenCounts, sumTokenCounts, totalTokenCount } from "./token-counts";
+import { sumTokenCounts, type TokenCounts, totalTokenCount } from './token-counts';
 
 // ---------------------------------------------------------------------------
 // Token & Cost Tracking
@@ -111,24 +111,33 @@ export interface UsageSummary {
 
 export const DEFAULT_COST_TABLE: CostTable = {
   anthropic: {
-    "claude-opus-4-7": { inputPer1M: 5, outputPer1M: 25 },
-    "claude-opus-4-6": { inputPer1M: 5, outputPer1M: 25 },
-    "claude-sonnet-4-6": { inputPer1M: 3, outputPer1M: 15 },
-    "claude-haiku-4-5-20251001": { inputPer1M: 1, outputPer1M: 5 },
+    'claude-opus-4-7': { inputPer1M: 5, outputPer1M: 25 },
+    'claude-opus-4-6': { inputPer1M: 5, outputPer1M: 25 },
+    'claude-sonnet-4-6': { inputPer1M: 3, outputPer1M: 15 },
+    'claude-haiku-4-5-20251001': { inputPer1M: 1, outputPer1M: 5 },
   },
   openai: {
-    "gpt-5.4": { inputPer1M: 2.5, outputPer1M: 15 },
-    "gpt-5.4-mini": { inputPer1M: 0.75, outputPer1M: 4.5 },
-    "gpt-5.3-codex": { inputPer1M: 1.75, outputPer1M: 14 },
-    "o4-mini": { inputPer1M: 1.1, outputPer1M: 4.4 }, // retired Feb 2026 — kept for historical cost tracking
+    'gpt-5.4': { inputPer1M: 2.5, outputPer1M: 15 },
+    'gpt-5.4-mini': { inputPer1M: 0.75, outputPer1M: 4.5 },
+    'gpt-5.3-codex': { inputPer1M: 1.75, outputPer1M: 14 },
+    'o4-mini': { inputPer1M: 1.1, outputPer1M: 4.4 }, // retired Feb 2026 — kept for historical cost tracking
   },
   gemini: {
-    "gemini-3.1-pro-preview": { inputPer1M: 2, outputPer1M: 12 },
-    "gemini-3-flash-preview": { inputPer1M: 0.5, outputPer1M: 3 },
-    "gemini-3.1-flash-lite-preview": { inputPer1M: 0.25, outputPer1M: 1.5 },
+    'gemini-3.1-pro-preview': { inputPer1M: 2, outputPer1M: 12 },
+    'gemini-3-flash-preview': { inputPer1M: 0.5, outputPer1M: 3 },
+    'gemini-3.1-flash-lite-preview': { inputPer1M: 0.25, outputPer1M: 1.5 },
+  },
+  meta: {
+    // The -contributor ids are the same models, ~21x cheaper because Meta trains
+    // on the traffic. Tracking both makes the saving show up next to what bought it.
+    'muse-spark-1.3': { inputPer1M: 1.25, outputPer1M: 4.25 },
+    'muse-spark-1.3-contributor': { inputPer1M: 0.1, outputPer1M: 0.2 },
+    'muse-spark-1.2': { inputPer1M: 1.25, outputPer1M: 4.25 },
+    'muse-spark-1.2-contributor': { inputPer1M: 0.1, outputPer1M: 0.2 },
+    'muse-spark-1.1': { inputPer1M: 1.25, outputPer1M: 4.25 },
   },
   // Claude Code provider tracks usage via session output, not cost table
-  "claude-code": {},
+  'claude-code': {},
 };
 
 // ---------------------------------------------------------------------------
@@ -136,7 +145,8 @@ export const DEFAULT_COST_TABLE: CostTable = {
 // ---------------------------------------------------------------------------
 
 /** Heuristic patterns that indicate source code rather than prose. */
-const CODE_SIGNALS = /[{}();=]|=>|function\s|import\s|export\s|const\s|let\s|var\s|class\s|def\s|return\s/;
+const CODE_SIGNALS =
+  /[{}();=]|=>|function\s|import\s|export\s|const\s|let\s|var\s|class\s|def\s|return\s/;
 
 /**
  * Estimate the number of tokens in `text` without a full tokenizer.
@@ -201,15 +211,13 @@ export class TokenTracker {
    *
    * Throws if budget.haltAt is exceeded (when configured).
    */
-  record(
-    entry: Omit<UsageEntry, "timestamp" | "cost">
-  ): UsageEntry {
+  record(entry: Omit<UsageEntry, 'timestamp' | 'cost'>): UsageEntry {
     const cost = this._computeCost(
       entry.provider,
       entry.model,
       entry.tokens.input,
       entry.tokens.output,
-      entry.cached
+      entry.cached,
     );
 
     const full: UsageEntry = {
@@ -267,7 +275,7 @@ export class TokenTracker {
 
   /** Full usage summary across all dimensions. */
   summary(): UsageSummary {
-    const tokens = sumTokenCounts(this._entries.map(e => e.tokens));
+    const tokens = sumTokenCounts(this._entries.map((e) => e.tokens));
     return {
       tokens,
       totalInput: tokens.input,
@@ -275,10 +283,10 @@ export class TokenTracker {
       totalTokens: totalTokenCount(tokens),
       totalCost: this._entries.reduce((s, e) => s + e.cost, 0),
       totalCalls: this._entries.length,
-      byProvider: this._groupBy("provider"),
-      byModel: this._groupBy("model"),
-      byAgent: this._groupBy("agentId"),
-      byThread: this._groupBy("threadId"),
+      byProvider: this._groupBy('provider'),
+      byModel: this._groupBy('model'),
+      byAgent: this._groupBy('agentId'),
+      byThread: this._groupBy('threadId'),
       budget: this._buildBudgetStatus(),
     };
   }
@@ -320,7 +328,7 @@ export class TokenTracker {
     model: string,
     input: number,
     output: number,
-    cached?: boolean
+    cached?: boolean,
   ): number {
     const pricing = this._costTable[provider]?.[model];
     if (!pricing) return 0;
@@ -328,19 +336,20 @@ export class TokenTracker {
     // Cached input tokens are typically free or heavily discounted
     const effectiveInput = cached ? input * 0.1 : input;
     return (
-      (effectiveInput / 1_000_000) * pricing.inputPer1M +
-      (output / 1_000_000) * pricing.outputPer1M
+      (effectiveInput / 1_000_000) * pricing.inputPer1M + (output / 1_000_000) * pricing.outputPer1M
     );
   }
 
   private _aggregate(entries: UsageEntry[]): TokenUsage {
-    const tokens = sumTokenCounts(entries.map(e => e.tokens));
-    return { ...tokens, total: totalTokenCount(tokens), estimatedCost: entries.reduce((sum, e) => sum + e.cost, 0) };
+    const tokens = sumTokenCounts(entries.map((e) => e.tokens));
+    return {
+      ...tokens,
+      total: totalTokenCount(tokens),
+      estimatedCost: entries.reduce((sum, e) => sum + e.cost, 0),
+    };
   }
 
-  private _groupBy(
-    field: "provider" | "model" | "agentId" | "threadId"
-  ): UsageBreakdown[] {
+  private _groupBy(field: 'provider' | 'model' | 'agentId' | 'threadId'): UsageBreakdown[] {
     const groups = new Map<string, UsageEntry[]>();
     for (const entry of this._entries) {
       const key = entry[field];
@@ -356,7 +365,7 @@ export class TokenTracker {
   }
 
   private _buildBudgetStatus(): BudgetStatus {
-    const usedTokens = totalTokenCount(sumTokenCounts(this._entries.map(e => e.tokens)));
+    const usedTokens = totalTokenCount(sumTokenCounts(this._entries.map((e) => e.tokens)));
     const usedCost = this._entries.reduce((s, e) => s + e.cost, 0);
 
     const limitTokens = this._budget.maxTokens;
@@ -426,8 +435,8 @@ export class BudgetExceededError extends Error {
     if (status.limitCost != null) {
       parts.push(`$${status.usedCost.toFixed(4)}/$${status.limitCost.toFixed(2)}`);
     }
-    super(`Budget exceeded: ${parts.join(", ")} (${(status.percentage * 100).toFixed(1)}%)`);
-    this.name = "BudgetExceededError";
+    super(`Budget exceeded: ${parts.join(', ')} (${(status.percentage * 100).toFixed(1)}%)`);
+    this.name = 'BudgetExceededError';
     this.status = status;
   }
 }