@inixiative/foundry-core 0.5.8 → 0.5.10

package/src/middleware.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:middleware
+ */
 import type { ExecutionResult } from './base-agent';
 import type { ContextStackView } from './context-stack';
 

package/src/model-registry.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind registry
+ * @partOf primitive:modelRegistry
+ */
 /**
  * The model registry: the vocabulary of what models are worth using for, the
  * table of providers and models, and the lookups over it.
@@ -18,6 +23,7 @@ export type ProviderType =
   | 'gemini'
   | 'claude-code'
   | 'codex'
+  | 'muse'
   | 'xai'
   | 'typesafe'
   | 'custom';
@@ -82,7 +88,17 @@ export const MODEL_CAPABILITIES: readonly ModelCapability[] = [
 export type ProviderCredential = 'api-key' | 'subscription' | 'local';
 
 /** Effort levels hosts publish. A superset of CompletionOpts.thinking. */
-export type ReasoningEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
+export const REASONING_EFFORTS = [
+  'none',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+  'ultra',
+] as const;
+/** The one effort vocabulary: every effort setting and picker is a subset of it. */
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
 
 /**
  * How one model takes its reasoning controls. This is the map that replaced a
@@ -195,6 +211,13 @@ const MUSE_REASONING: ModelReasoning = {
   fallback: 'medium',
   outputField: 'max_completion_tokens',
 };
+/** Muse Code's catalogue (`<muse data>/model-catalog`): the CLI sends `effort` on each turn, high by default.
+ * `minimal` is offered too; Foundry's effort ladder starts at low. */
+const MUSE_CODE_REASONING: ModelReasoning = {
+  param: 'reasoning_effort',
+  efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+  fallback: 'high',
+};
 
 export interface FoundryProviderInfo {
   id: string;
@@ -236,6 +259,12 @@ export const SUBSCRIPTION_DECISION_MODELS = {
   claude: DECISION_MODEL,
   codex: 'gpt-5.6-luna',
 } as const;
+/** A subscription worker's main-thread model when a thread runs on a worker other than its project's default. */
+export const SUBSCRIPTION_WORKER_MODELS = {
+  'claude-code': 'fable',
+  codex: 'gpt-6-astra',
+  muse: 'muse-wonder-1.0',
+} as const;
 
 /** Tag rule: every model judges. Cheap models review and route; capable models execute and advise. */
 const FAST = ['judgment', 'learning-review', 'tool-use'] as ModelCapability[];
@@ -724,6 +753,55 @@ export const MODEL_REGISTRY: Record<string, FoundryProviderInfo> = {
       },
     ],
   },
+  muse: {
+    id: 'muse',
+    lab: 'meta',
+    type: 'muse',
+    label: 'Muse Code (Meta subscription)',
+    description:
+      "Native Muse Code harness (`muse serve`) using the user's own Muse login. Separate from Meta's pay-as-you-go Model API.",
+    credential: 'subscription',
+    // Off until the user turns on Meta's subscription mode: few machines have Muse Code signed in.
+    enabledByDefault: false,
+    models: [
+      // From the Muse Code 1.4.14 catalogue a Muse Code Everyday Usage login is served
+      // (`<muse data>/model-catalog`, 2026-11-01). The -contributor ids are hidden there and not listed.
+      {
+        id: 'muse-wonder-1.0',
+        label: 'Muse Wonder 1.0',
+        tier: 'powerful',
+        costTier: 'high',
+        contextWindow: 1_007_997,
+        maxOutputTokens: 128_000,
+        runtimeKind: 'native-harness',
+        capabilities: POWERFUL_REASONING,
+        reasoning: MUSE_CODE_REASONING,
+        notes: 'The Muse Code default.',
+      },
+      {
+        id: 'muse-spark-1.3',
+        label: 'Muse Spark 1.3',
+        tier: 'powerful',
+        costTier: 'high',
+        contextWindow: 1_007_997,
+        maxOutputTokens: 128_000,
+        runtimeKind: 'native-harness',
+        capabilities: POWERFUL_REASONING,
+        reasoning: MUSE_CODE_REASONING,
+      },
+      {
+        id: 'muse-spark-1.2',
+        label: 'Muse Spark 1.2',
+        tier: 'powerful',
+        costTier: 'high',
+        contextWindow: 1_007_997,
+        maxOutputTokens: 128_000,
+        runtimeKind: 'native-harness',
+        capabilities: POWERFUL_REASONING,
+        reasoning: { ...MUSE_CODE_REASONING, efforts: ['low', 'medium', 'high', 'xhigh'] },
+      },
+    ],
+  },
   meta: {
     id: 'meta',
     lab: 'meta',
@@ -1672,7 +1750,7 @@ export const MODEL_VENDORS: readonly ModelVendor[] = [
     id: 'meta',
     label: 'Meta (Muse)',
     lab: 'meta',
-    subscription: { comingSoon: true },
+    subscription: { provider: 'muse' },
     api: { provider: 'meta' },
   },
   {
@@ -1723,6 +1801,18 @@ export function modelOptionsByCapability(...capabilities: ModelCapability[]): Mo
   );
 }
 
+/**
+ * The efforts a registered model accepts, in order; undefined for a model the registry does not
+ * list (a local server's), which callers take as "not known, don't narrow".
+ */
+export function modelEfforts(
+  providerId: string,
+  modelId: string,
+): readonly ReasoningEffort[] | undefined {
+  const model = registryModel(providerId, modelId);
+  return model ? (model.reasoning?.efforts ?? []) : undefined;
+}
+
 export function registryModel(providerId: string, modelId: string): FoundryModelInfo | undefined {
   return MODEL_REGISTRY[providerId]?.models.find((model) => model.id === modelId);
 }

package/src/native-evidence.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind transformer
+ * @partOf primitive:nativeSessions
+ */
 /** Public, owned projection. Raw protocol and reasoning are deliberately absent. */
 export interface NativeOwner {
   readonly threadId: string;
@@ -220,6 +225,8 @@ export interface NativeObservation {
   observe(evidence: NativeEvidence): void | Promise<void>;
   /** Receives the stop for this owner's registered admission, where the runtime acknowledges stops. */
   interruptible?(interrupt: NativeInterrupt): void;
+  /** Receives how to steer more input into this owner's registered admission, or why it can't be. */
+  steerable?(steer: NativeSteer): void;
   /**
    * The executor's public thinking text, for live display only. It never becomes evidence:
    * nothing here is journalled, traced or projected (reasoning stays out of NativeEvidence).
@@ -229,6 +236,17 @@ export interface NativeObservation {
 /** `acknowledged`: the runtime confirmed the stop and the turn reached its native terminal. */
 export type NativeInterruptOutcome = 'acknowledged' | 'no-turn' | 'unacknowledged';
 export type NativeInterrupt = (opts?: { timeoutMs?: number }) => Promise<NativeInterruptOutcome>;
+/** What became of a steer: taken into the running turn, sent but unconfirmed, or not delivered (with why). */
+export type NativeSteerOutcome =
+  | { readonly outcome: 'steered' | 'unknown' }
+  | { readonly outcome: 'ignored'; readonly reason: string };
+/**
+ * A running admission's steer (CORE-001): `push` adds text to that turn, where the runtime can steer.
+ * Where it can't, `push` is absent and `reason` says why, so the caller queues and says so.
+ */
+export type NativeSteer =
+  | { readonly push: (text: string) => Promise<NativeSteerOutcome> }
+  | { readonly push?: undefined; readonly reason: string };
 export function freezeEvidence<T>(value: T): T {
   const copy = structuredClone(value);
   const freeze = (v: unknown) => {

package/src/native-tools.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind constant
+ * @partOf primitive:tools
+ */
 import type { Capability } from './capability';
 
 // Native harness tools by what they do: one list for Foundry's tool gate and work items, and for

package/src/retry.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind middleware
+ * @partOf primitive:middleware
+ */
 import { CapabilityDeniedError } from './capability';
 import type { DispatchContext, Middleware, MiddlewareNext } from './middleware';
 import { BudgetExceededError } from './token-tracker';

package/src/router.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind agent
+ * @partOf primitive:agents
+ */
 import type { AgentConfig } from './base-agent';
 import type { ContextStack } from './context-stack';
 import { Decider, type DeciderConfig, type Decision } from './decider';

package/src/scope.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind type
+ * @partOf primitive:thread
+ */
 /**
  * Ownership scope — which thread and project an operation belongs to.
  *

package/src/serialized-queue.ts

@@ -0,0 +1,35 @@
+/**
+ * @atlas
+ * @kind utils
+ * @partOf primitive:concurrency
+ */
+// Copied from the template's packages/shared/src/utils/serializedQueue.ts.
+// Each run(fn) waits for the previous to settle before invoking fn; a failure
+// does not poison the chain. Errors still reject the caller's promise.
+
+export type SerializedQueue = {
+  run: <T>(fn: () => Promise<T>) => Promise<T>;
+  size: () => number;
+};
+
+export const createSerializedQueue = (): SerializedQueue => {
+  let tail: Promise<unknown> = Promise.resolve();
+  let pending = 0;
+
+  return {
+    run: <T>(fn: () => Promise<T>): Promise<T> => {
+      pending++;
+      const wrapped = async (): Promise<T> => {
+        try {
+          return await fn();
+        } finally {
+          pending--;
+        }
+      };
+      const next = tail.then(wrapped, wrapped);
+      tail = next;
+      return next;
+    },
+    size: () => pending,
+  };
+};

package/src/session-delivery.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind helper
+ * @partOf primitive:nativeSessions
+ */
 import { computeHash } from './context-layer';
 import type { PromptBlock } from './context-stack';
 

package/src/signal.ts

@@ -1,3 +1,8 @@
+/**
+ * @atlas
+ * @kind service
+ * @partOf primitive:signals
+ */
 /**
  * Signal kinds — the Librarian's taxonomy.
  * Extensible via string union, not a closed enum.

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,6 +267,9 @@ 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;
 
@@ -105,6 +285,9 @@ export interface ThreadMeta {
   /** 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;
 
@@ -214,8 +397,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 +453,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 +639,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.