@inixiative/foundry-core 0.5.9 → 0.5.11

package/src/thread.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:thread
+ */
 import type { BaseAgent, ExecutionResult } from './base-agent';
 import { CacheLifecycle } from './cache-lifecycle';
 import type { ContextStack, ContextStackView, LayerFilter } from './context-stack';
@@ -14,6 +19,8 @@ export type ThreadStatus = 'idle' | 'active' | 'waiting' | 'archived';
 export interface ThreadName {
   readonly text: string;
   readonly updatedAt: number;
+  /** A Foundry name the thread's agent gave (`rename_thread`): Foundry's namer leaves it alone. */
+  readonly by?: 'agent';
 }
 
 /** Tracked work a thread links to, in Archive's integration-reference shape (`github` `owner/repo#12`, `linear` `ENG-4`). */
@@ -23,6 +30,132 @@ export interface ThreadReference {
   readonly url?: string;
 }
 
+/**
+ * A thread's worktree record. `mode` is how its repository makes worktrees (`template`: slots via
+ * `worktree:create`; `classic`: plain git; `none`: the thread works outside any git checkout).
+ * `released` means the recorded checkout no longer exists on disk; the rest is what it was.
+ */
+export interface ThreadCheckout {
+  readonly mode: 'template' | 'classic' | 'none';
+  /** Worktree root (absent for `none`). */
+  readonly path?: string;
+  /** The repository's main checkout (absent for `none`). */
+  readonly root?: string;
+  /** The repository's main checkout rather than a linked worktree. */
+  readonly main: boolean;
+  /** Template mode: the slot the worktree holds (main checkout = 0). */
+  readonly slot?: number;
+  /** The branch was squash-merged into the repository's default branch (tree equality), and when it was first seen. */
+  readonly merged?: { readonly into: string; readonly at: number };
+  /** `recreating`: the mode's create is running for a released worktree. */
+  readonly state: 'live' | 'released' | 'recreating';
+  /** The last recreate failed: the command's error. */
+  readonly error?: string;
+}
+
+/** What a thread finished: a merge of its branch, or a plan outcome marked done. */
+export interface ThreadDone {
+  readonly kind: 'merged' | 'milestone';
+  readonly text: string;
+  readonly at: number;
+}
+
+/** One item of a plan section: a short line, and its detail when the line is not enough. */
+export interface ThreadPlanItem {
+  readonly text: string;
+  readonly detail?: string;
+}
+
+/**
+ * The thread's plan, written by its agent through Foundry's `set_plan` tool. Outcomes are what the
+ * person gets (`you`: waits on the person); pains what hurts today; strategy how the work goes;
+ * reasons why this way. Each technical row names, per concern (auth, permissions, db access,
+ * requests, locks, jobs, events, errors…), the existing system it uses and where, or why none fits.
+ */
+export interface ThreadPlan {
+  readonly outcomes: readonly (ThreadPlanItem & {
+    readonly status: 'todo' | 'doing' | 'done' | 'you';
+  })[];
+  readonly pains: readonly ThreadPlanItem[];
+  readonly strategy: readonly ThreadPlanItem[];
+  readonly reasons: readonly ThreadPlanItem[];
+  readonly technical: readonly {
+    readonly concern: string;
+    readonly decision: 'reuse' | 'extend' | 'new' | 'combine' | 'refactor' | 'migrate' | 'none';
+    readonly system: string;
+    readonly path?: string;
+    readonly reason: string;
+  }[];
+  /**
+   * Who wrote it: the thread's agent (`set_plan`), or Foundry's draft when a turn that brought new
+   * work ended with no plan recorded. A draft is shown as one and the agent's next `set_plan`
+   * replaces it whole.
+   */
+  readonly draftedBy?: 'agent' | 'foundry';
+  readonly updatedAt: number;
+}
+
+/** One round of a thread's loop: how it went and what it found. */
+export interface ThreadLoopRound {
+  readonly round: number;
+  readonly result: 'pass' | 'fail' | 'partial';
+  readonly note: string;
+  readonly at: number;
+}
+
+/**
+ * The thread's loop: the process the agent repeats to reach the plan's outcomes (Aron, 2026-11-01:
+ * "The plan is the goals that you want to achieve. The loop is the process you're doing to achieve
+ * them"). Recorded by the agent (`set_loop`, `loop_round`, `stop_loop`) for work that needs several
+ * rounds of build, check and fix; shown in the Loop tab.
+ */
+export interface ThreadLoop {
+  /** What the loop drives toward, in a line. */
+  readonly goal: string;
+  /** One round, in order: e.g. build, run the check, fix what failed. */
+  readonly steps: readonly ThreadPlanItem[];
+  /** When it stops: the check that passing means done. */
+  readonly until: string;
+  /** Rounds at most before the agent stops and asks. */
+  readonly maxRounds?: number;
+  readonly rounds: readonly ThreadLoopRound[];
+  /** `done`: the stop condition held. `stopped`: ended without it (the reason says why). */
+  readonly state: 'running' | 'done' | 'stopped';
+  readonly stopReason?: string;
+  readonly startedAt: number;
+  readonly updatedAt: number;
+}
+
+/**
+ * What the thread's agent says about where it stands, when Foundry can't see it: it waits on the
+ * person (an orange "the agent asks"), or it is blocked (red). Working, queued, failed, approvals
+ * and archived are Foundry's to know and never set here; done is `ThreadMeta.done`. Cleared by the
+ * owner's next message.
+ */
+export interface ThreadAgentStatus {
+  readonly state: 'needs-you' | 'blocked';
+  readonly text: string;
+  readonly at: number;
+}
+
+/** Where a thread runs: the Foundry device it was recorded on, and that Foundry's name then. */
+export interface ThreadMachine {
+  readonly deviceId: string;
+  readonly deviceName: string;
+  readonly installationName?: string;
+}
+
+/**
+ * A thread snoozed by its person: quiet until `until` (ISO), then cleared. `condition` names what
+ * the time was resolved from (`quota-reset`: when the reached usage window resets). A snooze never
+ * changes the thread's status, so clearing it leaves the thread as it was.
+ */
+export interface ThreadSnooze {
+  readonly until: string;
+  readonly condition?: 'quota-reset';
+  readonly setAt: string;
+}
+
 /** Where a thread's work lives, as the runtime last observed it. */
 export interface ThreadContext {
   /** `owner/repo` of the worktree's origin. */
@@ -31,19 +164,36 @@ export interface ThreadContext {
   readonly branch?: string;
   /** Worktree root containing the thread's cwd. */
   readonly worktree?: string;
+  /** The thread's checkout as a worktree record (FEAT-003): mode, slot and whether it still exists. */
+  readonly checkout?: ThreadCheckout;
   readonly references: readonly ThreadReference[];
   readonly updatedAt: number;
 }
 
-/** The name a thread shows: a person's name overrides the agent-maintained one. */
+/** The name a thread shows: a person's name overrides the one Foundry gives it. */
 export function threadTitle(
-  meta: Pick<ThreadMeta, 'name' | 'agentName' | 'description'>,
-): { text: string; source: 'human' | 'agent' | 'description' } | undefined {
+  meta: Pick<ThreadMeta, 'name' | 'foundryName' | 'description'>,
+): { text: string; source: 'human' | 'agent' | 'foundry' | 'description' } | undefined {
   if (meta.name?.text) return { text: meta.name.text, source: 'human' };
-  if (meta.agentName?.text) return { text: meta.agentName.text, source: 'agent' };
+  if (meta.foundryName?.text)
+    return {
+      text: meta.foundryName.text,
+      source: meta.foundryName.by === 'agent' ? 'agent' : 'foundry',
+    };
   return meta.description ? { text: meta.description, source: 'description' } : undefined;
 }
 
+/**
+ * Where a forked thread came from: provenance, not nesting. A fork is a top-level thread (Aron,
+ * 2026-11-01: delegated threads are top-level; nesting is for subagents), so it is not a
+ * `parentThreadId`. Its first session is seeded with the source's conversation through `journalSeq`.
+ */
+export interface ThreadFork {
+  readonly threadId: string;
+  /** The source's journal seq the fork was cut at. */
+  readonly journalSeq: number;
+}
+
 /** How a subagent thread came to be: who spawned it, through what, and its native identity. */
 export interface ThreadSpawn {
   readonly via: 'foundry' | 'native-claude' | 'native-codex' | 'host-paseo' | 'host-t3';
@@ -66,8 +216,11 @@ export interface ThreadMeta {
   /** 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;
+  /**
+   * Name Foundry gives the thread from the person's messages (its first message, then again when
+   * the work moves) while no person has named it. Never set once a person has.
+   */
+  foundryName?: ThreadName;
 
   /** Branch, worktree and linked PRs/tickets, derived by the runtime. */
   context?: ThreadContext;
@@ -78,6 +231,30 @@ export interface ThreadMeta {
   /** Current status. */
   status: ThreadStatus;
 
+  /**
+   * The thread's last finished piece of work, shown as its done state until the next task starts:
+   * its branch merged (`merged`), or a plan outcome reached `done` (`milestone`, with its text).
+   */
+  done?: ThreadDone;
+
+  /** The agent's plan for the thread's work (`set_plan`, the Plan view): what, why, and how. */
+  plan?: ThreadPlan;
+  /** The process the agent repeats to reach the plan (`set_loop`, the Loop view). */
+  loop?: ThreadLoop;
+  /** Where the agent says it stands: waiting on the person or blocked (`set_status`). */
+  agentStatus?: ThreadAgentStatus;
+  /** The machine (Foundry device identity, `~/.foundry/device.json`) the thread runs on. */
+  machine?: ThreadMachine;
+
+  /** Put out of mind until a time (or a condition, resolved to its time); status is untouched. */
+  snooze?: ThreadSnooze;
+
+  /**
+   * When the owner last looked at the thread (epoch ms; the viewer marks it on open and while open).
+   * A turn that completed after it is a hand-back, a "new arrival" (VIEWER-001's seen-by-Aron mark).
+   */
+  seenAt?: number;
+
   /** Working directory for this thread's tool execution (worktree path). */
   cwd?: string;
 
@@ -90,21 +267,21 @@ export interface ThreadMeta {
   /** The parent's turn that spawned this thread (a subagent). */
   parentTurnId?: string;
 
+  /** The thread and point this one was forked from (provenance; a fork is top-level). */
+  forkedFrom?: ThreadFork;
+
   /** How this subagent thread was spawned. */
   spawn?: ThreadSpawn;
 
   /** 1 for a child of a main thread. */
   depth?: number;
 
-  /**
-   * Start-up of a thread whose Wardens are held in its own process (docs/THREAD-TREE.md spec C):
-   * turns typed meanwhile wait as `queued` until it is `ready` (or `degraded`).
-   */
-  setup?: ThreadSetup;
-
   /** Project that owns this thread. Scopes memory sources and tool calls. */
   projectId?: string;
 
+  /** The harness running this thread's main session (`claude-code`, `codex`). Set at creation; never changed silently. */
+  worker?: string;
+
   /** When this thread was created. */
   readonly createdAt: number;
 
@@ -115,15 +292,6 @@ export interface ThreadMeta {
   archivedAt?: number;
 }
 
-export interface ThreadSetup {
-  status: 'starting' | 'ready' | 'degraded';
-  startedAt: number;
-  readyAt?: number;
-  /** Every configured Warden, those holding a spare, and those that did not by the deadline. */
-  wardens: { expected: number; held: number; failed: string[] };
-  runtime: 'claude-in-session' | 'codex-in-process' | 'side-session';
-}
-
 export interface Dispatch<T = unknown> {
   readonly agentId: string;
   readonly timestamp: number;
@@ -214,8 +382,12 @@ export interface ThreadConfig {
   branch?: string;
   /** Parent thread when this thread is a subagent spawned by another. */
   parentThreadId?: string;
+  /** The thread and point this one was forked from. */
+  forkedFrom?: ThreadFork;
   /** Project that owns this thread. Scopes memory sources and tool calls. */
   projectId?: string;
+  /** The harness running this thread's main session. */
+  worker?: string;
   /** Optional token tracker — auto-records costs for every dispatch. */
   tokenTracker?: TokenTracker;
 }
@@ -266,7 +438,9 @@ export class Thread {
       cwd: opts?.cwd,
       branch: opts?.branch,
       parentThreadId: opts?.parentThreadId,
+      ...(opts?.forkedFrom ? { forkedFrom: opts.forkedFrom } : {}),
       projectId: opts?.projectId,
+      ...(opts?.worker ? { worker: opts.worker } : {}),
       createdAt: now,
       lastActiveAt: now,
     };
@@ -450,6 +624,7 @@ export class Thread {
             register: opts.nativeObservation.register,
             observe: opts.nativeObservation.observe,
             interruptible: opts.nativeObservation.interruptible,
+            steerable: opts.nativeObservation.steerable,
             thought: opts.nativeObservation.thought,
             owner: Object.freeze({
               threadId: this.id,

package/src/token-counts.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind helper
+ * @partOf feature:usage
+ */
 /** Cache counts, when supplied, are disjoint from input. Thinking and TTL
  * breakdowns are subsets of output/cacheWrite, never additional tokens.
  * Missing optional counters mean unreported, not a measured zero.

package/src/token-tracker.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf feature:usage
+ */
 import { sumTokenCounts, type TokenCounts, totalTokenCount } from './token-counts';
 
 // ---------------------------------------------------------------------------
@@ -140,6 +145,10 @@ const attributionMatches = (
 export interface ModelPricing {
   readonly inputPer1M: number;
   readonly outputPer1M: number;
+  /** Cache reads; default a tenth of input. */
+  readonly cacheReadPer1M?: number;
+  /** Cache writes (5-minute); default 1.25x input. */
+  readonly cacheWritePer1M?: number;
 }
 
 /**
@@ -209,11 +218,22 @@ export interface UsageSummary {
 }
 
 // ---------------------------------------------------------------------------
-// Default cost table (approximate pricing as of early 2026)
+// Default cost table. Anthropic: first-party API list prices per 1M tokens, as published at
+// https://platform.claude.com/docs/en/about-claude/pricing (read 2026-11-01; cache writes are the
+// 5-minute rate, 1.25x input). Haiku 5.5 is its rate up to 100K-token prompts.
 // ---------------------------------------------------------------------------
 
 export const DEFAULT_COST_TABLE: CostTable = {
   anthropic: {
+    'claude-fable-5-1': { inputPer1M: 10, outputPer1M: 50, cacheReadPer1M: 0.25 },
+    'claude-fable-5': { inputPer1M: 10, outputPer1M: 50 },
+    'claude-opus-5-5': { inputPer1M: 4, outputPer1M: 20, cacheReadPer1M: 0.2 },
+    'claude-opus-5': { inputPer1M: 5, outputPer1M: 25 },
+    'claude-opus-4-8': { inputPer1M: 5, outputPer1M: 25 },
+    'claude-sonnet-5-5': { inputPer1M: 2, outputPer1M: 10, cacheReadPer1M: 0.2 },
+    'claude-sonnet-5': { inputPer1M: 2, outputPer1M: 10 },
+    'claude-haiku-5-5': { inputPer1M: 0.1, outputPer1M: 0.5 },
+    'claude-haiku-4-5': { 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 },
@@ -239,10 +259,24 @@ export const DEFAULT_COST_TABLE: CostTable = {
     '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': {},
 };
 
+/**
+ * A model's price: its own provider's row, else the same model id under any provider. A Claude
+ * model run through the Claude Code login (provider `claude-code` or a decision host) is priced at
+ * its API list price: an API-equivalent cost, not what a subscription bills.
+ */
+export function modelPricing(
+  table: CostTable,
+  provider: string,
+  model: string,
+): ModelPricing | undefined {
+  const own = table[provider]?.[model];
+  if (own) return own;
+  for (const rows of Object.values(table)) if (rows[model]) return rows[model];
+  return undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Token estimation
 // ---------------------------------------------------------------------------
@@ -316,19 +350,14 @@ export class TokenTracker {
    * Throws if budget.haltAt is exceeded (when configured).
    */
   record(entry: Omit<UsageEntry, 'timestamp' | 'cost'>): UsageEntry {
-    const cost = this._computeCost(
-      entry.provider,
-      entry.model,
-      entry.tokens.input,
-      entry.tokens.output,
-      entry.cached,
-    );
+    const pricing = modelPricing(this._costTable, entry.provider, entry.model);
+    const cost = pricing ? this._computeCost(pricing, entry.tokens, entry.cached) : 0;
 
     const full: UsageEntry = {
       ...entry,
       timestamp: Date.now(),
       cost,
-      costKnown: !!this._costTable[entry.provider]?.[entry.model],
+      costKnown: !!pricing,
     };
 
     this._entries.push(full);
@@ -474,20 +503,16 @@ export class TokenTracker {
   // Private helpers
   // -----------------------------------------------------------------------
 
-  private _computeCost(
-    provider: string,
-    model: string,
-    input: number,
-    output: number,
-    cached?: boolean,
-  ): number {
-    const pricing = this._costTable[provider]?.[model];
-    if (!pricing) return 0;
-
-    // Cached input tokens are typically free or heavily discounted
-    const effectiveInput = cached ? input * 0.1 : input;
+  private _computeCost(pricing: ModelPricing, tokens: TokenCounts, cached?: boolean): number {
+    // `cached` marks a whole call served from a provider cache that reports no split.
+    const input = cached ? tokens.input * 0.1 : tokens.input;
+    const perToken = (count: number | undefined, per1M: number) =>
+      ((count ?? 0) / 1_000_000) * per1M;
     return (
-      (effectiveInput / 1_000_000) * pricing.inputPer1M + (output / 1_000_000) * pricing.outputPer1M
+      perToken(input, pricing.inputPer1M) +
+      perToken(tokens.output, pricing.outputPer1M) +
+      perToken(tokens.cacheRead, pricing.cacheReadPer1M ?? pricing.inputPer1M * 0.1) +
+      perToken(tokens.cacheWrite, pricing.cacheWritePer1M ?? pricing.inputPer1M * 1.25)
     );
   }
 

package/src/tools.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind type
+ * @partOf primitive:tools
+ */
 // ---------------------------------------------------------------------------
 // Tools — typed interfaces for agent execution environments
 // ---------------------------------------------------------------------------
@@ -721,7 +726,7 @@ export class ToolRegistry {
             const api = tool.scoped ? tool.scoped(opts?.scope ?? {}) : tool;
             return await api.request({
               url: input.url as string,
-              method: (input.method as any) ?? 'GET',
+              method: (input.method as ApiRequest['method']) ?? 'GET',
               body: input.body,
               headers: input.headers as Record<string, string>,
             });

package/src/trace.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:traces
+ */
 import type { TokenCounts } from './token-counts';
 /**
  * A single span in a message's journey through the system.

package/src/types.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind type
+ * @partOf primitive:agents
+ */
 import type { TokenCounts } from './token-counts';
 // ---------------------------------------------------------------------------
 // Shared types — used by harness for conditional invocation/activation
@@ -212,8 +217,6 @@ export interface LLMProvider {
    * `threadPrefix` starts at once. `messages` end at those prefixes; no decision is made. Optional.
    */
   prestart?(messages: LLMMessage[], opts: CompletionOpts): void;
-  /** A thread closed: release whatever the provider holds for it. Optional. */
-  releaseThread?(threadId: string): Promise<void>;
 }
 
 export interface EmbeddingProvider {

package/src/hooks.ts

@@ -1,133 +0,0 @@
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export type HookPoint =
-  | 'pre:dispatch'
-  | 'post:dispatch'
-  | 'pre:classify'
-  | 'post:classify'
-  | 'pre:route'
-  | 'post:route'
-  | 'pre:compact'
-  | 'post:compact'
-  | 'session:create'
-  | 'session:archive'
-  | 'budget:warning'
-  | 'budget:exceeded'
-  | 'plan:enter'
-  | 'plan:exit'
-  | 'error:agent'
-  | 'error:provider';
-
-export interface HookContext {
-  hookPoint: HookPoint;
-  threadId?: string;
-  agentId?: string;
-  payload?: unknown;
-  result?: unknown;
-  meta: Record<string, unknown>;
-  timestamp: number;
-}
-
-export interface HookResult {
-  action: 'continue' | 'skip' | 'abort' | 'redirect';
-  redirectTo?: string;
-  modified?: Partial<HookContext>;
-  annotations?: Record<string, unknown>;
-}
-
-export interface HookHandler {
-  id: string;
-  points: HookPoint[];
-  priority?: number;
-  handler: (ctx: HookContext) => Promise<HookResult>;
-}
-
-export interface PlanModeTrigger {
-  kind: 'complexity' | 'newDomain' | 'largeDiff' | 'custom';
-  threshold?: number;
-  detect?: (ctx: HookContext) => boolean;
-}
-
-export interface PlanModeConfig {
-  triggers: PlanModeTrigger[];
-  plannerAgentId: string;
-  requireApproval?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// HookRegistry — engine mechanism, no built-in behaviors
-// ---------------------------------------------------------------------------
-
-const DEFAULT_PRIORITY = 100;
-
-export class HookRegistry {
-  private _handlers: Map<string, HookHandler> = new Map();
-
-  register(handler: HookHandler): () => void {
-    this._handlers.set(handler.id, handler);
-    return () => {
-      this._handlers.delete(handler.id);
-    };
-  }
-
-  unregister(id: string): boolean {
-    return this._handlers.delete(id);
-  }
-
-  async execute(
-    point: HookPoint,
-    ctx: HookContext,
-  ): Promise<HookContext & { action: HookResult['action'] }> {
-    const handlers = this.forPoint(point);
-    let current = { ...ctx };
-    let action: HookResult['action'] = 'continue';
-
-    for (const handler of handlers) {
-      const result = await handler.handler(current);
-      action = result.action;
-
-      if (result.modified) {
-        current = {
-          ...current,
-          ...result.modified,
-          meta: { ...current.meta, ...result.modified.meta },
-        };
-      }
-
-      if (result.annotations) {
-        current.meta = { ...current.meta, ...result.annotations };
-      }
-
-      if (result.redirectTo) {
-        current.meta = { ...current.meta, redirectTo: result.redirectTo };
-      }
-
-      if (action === 'abort' || action === 'skip' || action === 'redirect') {
-        break;
-      }
-    }
-
-    return { ...current, action };
-  }
-
-  forPoint(point: HookPoint): ReadonlyArray<HookHandler> {
-    const matching: HookHandler[] = [];
-    for (const handler of this._handlers.values()) {
-      if (handler.points.includes(point)) {
-        matching.push(handler);
-      }
-    }
-    matching.sort((a, b) => (a.priority ?? DEFAULT_PRIORITY) - (b.priority ?? DEFAULT_PRIORITY));
-    return matching;
-  }
-
-  get size(): number {
-    return this._handlers.size;
-  }
-
-  get handlers(): ReadonlyArray<HookHandler> {
-    return [...this._handlers.values()];
-  }
-}