@inixiative/foundry-core 0.5.6 → 0.5.7

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./delivery-evidence": "./src/delivery-evidence.ts"
+    "./delivery-evidence": "./src/delivery-evidence.ts",
+    "./archive": "./src/feedback/archive-turns.ts"
   },
   "scripts": {
     "test": "bun test tests/",
@@ -30,5 +31,16 @@
   },
   "engines": {
     "bun": ">=1.4.2"
+  },
+  "peerDependencies": {
+    "@inixiative/archive": "^0.23.0"
+  },
+  "peerDependenciesMeta": {
+    "@inixiative/archive": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@inixiative/archive": "^0.23.0"
   }
 }

package/src/context-layer.ts

@@ -146,6 +146,11 @@ export interface CompositionSnapshot {
     readonly instructions: readonly OmittedSource[];
     readonly domainKnowledge: readonly OmittedSource[];
   };
+  /**
+   * The charter the call ran under, when it is not the Warden charter (a classify stage's own):
+   * its audited subject and text.
+   */
+  readonly charter?: { readonly subject: string; readonly text: string };
 }
 
 export interface OmittedSource {

package/src/executor.ts

@@ -9,7 +9,7 @@ import {
   standingParts,
 } from './session-delivery';
 import type { ToolCallObservation } from './tools';
-import type { LLMMessage } from './types';
+import { type ImageInput, type LLMMessage, withoutImageData } from './types';
 
 /** Runtime metadata passed to executor handlers at dispatch time. */
 export interface ExecuteMeta {
@@ -48,6 +48,8 @@ export interface ExecuteMeta {
   delivery?: SessionDelivery;
   /** The handler reports what a session provider delivered (CompletionResult.delivery). */
   recordDelivery?: (report: SessionDeliveryReport) => void;
+  /** Images sent with the payload; the handler puts them on the user message it sends. */
+  images?: readonly ImageInput[];
 }
 
 export type ExecuteHandler<TPayload, TResult> = (
@@ -228,7 +230,9 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
             observe(() => meta?.recordNative?.(evidence));
           }
         },
-        recordProviderInput: (messages) => {
+        recordProviderInput: (sentMessages) => {
+          // Evidence holds each image by identity; its bytes stay with the attachment.
+          const messages = withoutImageData(sentMessages);
           // The initial boundary input must not be replaced by tool followups.
           if (providerMessages === undefined) {
             providerMessages = structuredClone(messages);

package/src/feedback/archive-turns.ts

@@ -0,0 +1,52 @@
+import type { ArchiveSnapshot } from '@inixiative/archive';
+import { typedPrompt } from '@inixiative/archive/import';
+import type { TranscriptTurn } from './correction';
+
+// An Archive session as transcript turns, the input `extractCorrections` reads. Shared by Foundry's
+// `foundry repeats` and Oracle's session miner; its own export, so the core root never loads Archive.
+
+const INTERRUPTED = /^\s*\[Request interrupted by user/;
+const COMMIT_BRACKET = /\[[^[\]\n]+\s([0-9a-f]{7,40})\]/g;
+const COMMIT_LINE = /^commit ([0-9a-f]{40})/gm;
+
+/** Commit SHAs a tool result printed: `git commit`'s `[branch sha]` line, `git log`'s `commit <sha>`. */
+export const commitsIn = (text: string) => [
+  ...[...text.matchAll(COMMIT_BRACKET)].map((m) => m[1]!),
+  ...[...text.matchAll(COMMIT_LINE)].map((m) => m[1]!),
+];
+
+export interface SnapshotTurnsOptions {
+  /** Also a turn per tool result that printed commits (`commits`): where the work landed. */
+  readonly commits?: boolean;
+}
+
+/** The transcript as turns: what the person typed, the agent's prose, and interruptions. */
+export function snapshotTurns(
+  snapshot: Pick<ArchiveSnapshot, 'entries'>,
+  options: SnapshotTurnsOptions = {},
+): TranscriptTurn[] {
+  const turns: TranscriptTurn[] = [];
+  for (const entry of snapshot.entries) {
+    const timestamp = entry.timestamp === null ? '' : new Date(entry.timestamp).toISOString();
+    if (entry.kind === 'assistant') turns.push({ role: 'assistant', text: entry.text, timestamp });
+    else if ((entry.kind === 'user' || entry.kind === 'event') && INTERRUPTED.test(entry.text))
+      turns.push({ role: 'user', text: '', timestamp, interrupted: true });
+    else if (entry.kind === 'user') {
+      const text = typedPrompt(entry.text);
+      if (text)
+        turns.push({ role: 'user', id: entry.id, text, timestamp, sourceRef: entry.sourceRef });
+    } else if (options.commits && entry.kind === 'tool-result') {
+      const commits = commitsIn(entry.text);
+      if (commits.length)
+        turns.push({
+          role: 'assistant',
+          id: entry.id,
+          text: '',
+          timestamp,
+          sourceRef: entry.sourceRef,
+          commits,
+        });
+    }
+  }
+  return turns;
+}

package/src/feedback/correction.ts

@@ -20,6 +20,8 @@ export interface TranscriptTurn {
   interrupted?: boolean;
   /** Where the turn sits in its source, e.g. `line:42`. */
   sourceRef?: string;
+  /** Commit SHAs a tool result printed in this turn (`snapshotTurns` with `commits`). */
+  commits?: string[];
 }
 
 export interface CorrectionEvent {

package/src/feedback/warden-labels.ts

@@ -14,7 +14,12 @@ export interface WardenLabel {
   readonly shouldKnow?: string;
 }
 
-export type WardenTriggerKind = 'user-message' | 'agent-action' | 'agent-plan' | 'subagent-spawn';
+export type WardenTriggerKind =
+  | 'user-message'
+  | 'consumed'
+  | 'agent-action'
+  | 'agent-plan'
+  | 'subagent-spawn';
 
 /**
  * A labelled moment for the Warden prefilter: which Warden domains the trigger touches. Never commit

package/src/feedback/warden-prefilter.ts

@@ -173,6 +173,7 @@ export function prefilterQuestion(description: string) {
 export function prefilterState(trigger: PrefilterTrigger, text: string, context?: string): string {
   const label = {
     'user-message': "The user's message",
+    consumed: 'A work item the agent took in (a ticket, spec, issue or page)',
     'agent-action': "The agent's actions this turn",
     'agent-plan': "The agent's plan",
     'subagent-spawn': 'The task the agent is handing to a subagent',

package/src/feedback/warden-probes.ts

@@ -66,6 +66,55 @@ export function probeTriggers(probe: WardenProbe): WardenProbeTrigger[] {
   ];
 }
 
+/** A classification's answer: in the region (`yes`), possibly (`unsure`, ternary stages only), or not. */
+export type ClassifyOutcome = 'yes' | 'unsure' | 'no';
+
+/**
+ * One stage of a classification run (Foundry's `classify`), as answered: what it read, what it said
+ * and what it cost. A stage that failed or answered out of shape carries `error` and no outcome:
+ * counted, never guessed.
+ */
+export interface ClassifyStageTrace {
+  /** 0-based, in run order. */
+  readonly stage: number;
+  readonly task: 'recognise' | 'point';
+  /** The region doc it read (e.g. `knowledge.md`) and the content hash of what it read. */
+  readonly doc: string;
+  readonly docHash?: string;
+  /**
+   * sha256 of the full system message the stage sent (its charter above the Warden's instructions),
+   * so runs that change any prompt section, the region line included, are told apart per call.
+   */
+  readonly systemHash?: string;
+  /** The model and effort that answered, as the provider reported them. */
+  readonly model?: string;
+  readonly effort?: string;
+  readonly outcome?: ClassifyOutcome;
+  /** The why, when the stage was asked for one (`reason: inline | followup`). */
+  readonly why?: string;
+  /** `reason: followup`: whether the stage, asked why, kept its answer or names the one it now holds. */
+  readonly revised?: 'keep' | ClassifyOutcome;
+  /** `reason: followup`: the follow-up call failed (the stage's own answer stands). */
+  readonly followupError?: string;
+  /** Its remarks in order (advice snippets or guard finding descriptions). */
+  readonly remarks?: readonly string[];
+  /** A recognise stage: the regions it named, with their line and outcome. */
+  readonly regions?: readonly {
+    readonly regionId: string;
+    readonly why: string;
+    readonly outcome: ClassifyOutcome;
+  }[];
+  readonly tokens?: Omit<TokenCounts, 'providerUsage'>;
+  readonly elapsedMs?: number;
+  /** The answer was out of protocol (counted apart from failures of the call). */
+  readonly malformed?: true;
+  readonly error?: string;
+  /** No answer within the stage's share of the trigger's deadline: the run kept the previous stage's outcome. */
+  readonly timedOut?: true;
+  /** Region ids a recogniser named that it does not hold: counted, never followed. */
+  readonly unknownRegions?: readonly string[];
+}
+
 /** One Warden's answer on one probe, and the judge's verdict when it spoke. */
 export interface WardenProbeAnswer {
   readonly probeId: string;
@@ -79,9 +128,15 @@ export interface WardenProbeAnswer {
   readonly elapsedMs?: number;
   /** What the call used, as the provider reported it (cache reads show a warm, primed prefix). */
   readonly tokens?: Omit<TokenCounts, 'providerUsage'>;
+  /** An unstaged call: sha256 of its full system message (a staged row has it on each stage's trace). */
+  readonly systemHash?: string;
   /** Transport failures of earlier attempts at this call, re-asked before this answer. */
   readonly retried?: readonly string[];
   readonly judged?: WardenJudgement;
+  /** The run's final outcome; a final `unsure` is delivered as nothing (`noComment`). */
+  readonly outcome?: ClassifyOutcome;
+  /** Every stage the run asked, in order. */
+  readonly stages?: readonly ClassifyStageTrace[];
 }
 
 /** One probe run as a turn: every Warden asked at once, as the live chorus is. */
@@ -144,6 +199,8 @@ export interface CharterScore {
   >;
   readonly remarks: number;
   readonly silences: number;
+  /** Silences whose final outcome was `unsure` (a ternary last stage): delivered as nothing, counted apart. */
+  readonly unsure: number;
   /** Remarks the judge could not grade: counted as unmatched, reported apart. */
   readonly unjudged: number;
   /** Per-turn load at roster scale: calls and wall clock, when the run recorded turns. */
@@ -192,6 +249,7 @@ export function scoreCharterRun(
     remarksRight = 0,
     scope = 0,
     silences = 0,
+    unsure = 0,
     unjudged = 0;
   const recalled = new Set<string>();
   const anticipated = new Set<string>();
@@ -220,8 +278,10 @@ export function scoreCharterRun(
     };
     perTrigger.set(trigger, tally);
     tally.probes.add(probe.id);
-    if (a.noComment) silences++;
-    else {
+    if (a.noComment) {
+      silences++;
+      if (a.outcome === 'unsure') unsure++;
+    } else {
       remarks++;
       tally.remarks++;
       if (!a.judged) unjudged++;
@@ -284,6 +344,7 @@ export function scoreCharterRun(
     byTrigger,
     remarks,
     silences,
+    unsure,
     unjudged,
     ...(turns.length
       ? {

package/src/harness.ts

@@ -144,6 +144,8 @@ interface SendOptions {
   onExecutorInput?: () => void;
   /** The payload the execute stage's agent receives instead of `message.payload` (see DispatchOptions.agentPayload). */
   executorPayload?: unknown;
+  /** Images sent with the message; only the execute stage's agent receives them. */
+  images?: readonly import('./types').ImageInput[];
 }
 
 /**
@@ -670,6 +672,7 @@ export class Harness {
           ...(stage.role === 'execute' && opts?.executorPayload !== undefined
             ? { agentPayload: opts.executorPayload }
             : {}),
+          ...(stage.role === 'execute' && opts?.images?.length ? { images: opts.images } : {}),
           recordInjection: (artifact) => {
             stageSpan.annotations.injection = artifact;
             if (stage.role === 'execute' && !executorInput) {

package/src/index.ts

@@ -251,6 +251,8 @@ export {
 export {
   type Authorship,
   type CharterScore,
+  type ClassifyOutcome,
+  type ClassifyStageTrace,
   CONCEPT_CLUSTERS,
   CORRECTION_TARGET_PROMPT,
   type CorrectionTarget,
@@ -346,16 +348,19 @@ export {
   MODEL_CAPABILITIES,
   MODEL_REGISTRY,
   MODEL_REGISTRY_UPDATED_AT,
+  MODEL_VENDORS,
   type ModelCapability,
   type ModelLab,
   type ModelReasoning,
   type ModelSweepOption,
   type ModelTier,
+  type ModelVendor,
   mainThreadLab,
   modelCapabilities,
   modelHasCapability,
   modelOptionsByCapability,
   type ProviderCredential,
+  type ProviderMode,
   type ProviderType,
   providersWithCapability,
   type ReasoningEffort,
@@ -363,6 +368,8 @@ export {
   registryModel,
   resolveDecisionModel,
   SUBSCRIPTION_DECISION_MODELS,
+  vendorModeProvider,
+  vendorOfProvider,
 } from './model-registry';
 export * from './native-evidence';
 // Retry middleware
@@ -464,6 +471,8 @@ export type {
   CompletionResult,
   EmbeddingProvider,
   EmbeddingResult,
+  ImageInput,
+  ImageMediaType,
   InvocationCondition,
   LayerModeConfig,
   LLMMessage,
@@ -473,3 +482,4 @@ export type {
   ToolCallResult,
   ToolDefinition,
 } from './types';
+export { IMAGE_MEDIA_TYPES, withoutImageData } from './types';

package/src/messages.ts

@@ -61,6 +61,8 @@ export type ParticipantRequest =
       readonly served?: ServedModel;
       /** What the call's instructions and domain knowledge were composed of; the journal stores version ids for it. */
       readonly composition?: CompositionSnapshot;
+      /** A staged classification (Foundry's classify): which stage, 0-based, this call was. */
+      readonly stage?: 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". */

package/src/model-registry.ts

@@ -234,7 +234,7 @@ export const DECISION_MODEL = 'claude-haiku-5-5';
 /** Subscription decision default per native runtime; settings choose the runtime. */
 export const SUBSCRIPTION_DECISION_MODELS = {
   claude: DECISION_MODEL,
-  codex: 'gpt-6-luna',
+  codex: 'gpt-5.6-luna',
 } as const;
 
 /** Tag rule: every model judges. Cheap models review and route; capable models execute and advise. */
@@ -490,6 +490,10 @@ export const MODEL_REGISTRY: Record<string, FoundryProviderInfo> = {
       // Slugs, effort ladders and the 272k session window come from the local
       // Codex catalogue (~/.codex/models_cache.json); the same models carry a
       // 1,050,000 window on the platform API, which the openai entry records.
+      // Only models a ChatGPT login serves are listed: Codex refuses gpt-5.5 on a
+      // ChatGPT account ("not supported when using Codex with a ChatGPT account"). The
+      // GPT-6 models need a current Codex: 0.153.4 is refused them, 0.163.0 is served
+      // them (2026-10-16); the GPT-5.6 models run on both.
       {
         id: 'gpt-6-astra',
         label: 'GPT-6 Astra',
@@ -521,7 +525,7 @@ export const MODEL_REGISTRY: Record<string, FoundryProviderInfo> = {
         runtimeKind: 'native-harness',
         capabilities: FAST_REASONING,
         reasoning: CODEX_REASONING,
-        notes: "Foundry's decision model.",
+        notes: 'Needs a current Codex CLI on a ChatGPT login (0.153.4 is refused it).',
       },
       {
         id: 'gpt-5.6-sol',
@@ -552,20 +556,8 @@ export const MODEL_REGISTRY: Record<string, FoundryProviderInfo> = {
         runtimeKind: 'native-harness',
         capabilities: FAST_REASONING,
         reasoning: CODEX_REASONING,
-      },
-      {
-        id: 'gpt-5.5',
-        label: 'GPT-5.5',
-        tier: 'standard',
-        costTier: 'medium',
-        contextWindow: 272_000,
-        runtimeKind: 'native-harness',
-        capabilities: STANDARD_REASONING,
-        reasoning: {
-          ...CODEX_REASONING,
-          efforts: ['low', 'medium', 'high', 'xhigh'],
-          fallback: 'xhigh',
-        },
+        notes:
+          "Foundry's Codex decision model: fast, and served to a ChatGPT login on every Codex CLI.",
       },
     ],
   },
@@ -1631,6 +1623,95 @@ export const MODEL_REGISTRY: Record<string, FoundryProviderInfo> = {
   },
 };
 
+/**
+ * A vendor, the way a person thinks of who serves their models: one row for Anthropic, not one for
+ * the Claude Code subscription and another for the API key. A vendor reaches its models in up to two
+ * modes, and a person may have either or both:
+ *
+ * - subscription: the person's own subscription login, through a native CLI transport (Claude Code,
+ *   Codex). `comingSoon` marks a vendor that sells a subscription Foundry has no transport for yet.
+ * - api: an API key (or, for a local server, none), through the registry provider named here.
+ *
+ * Each mode names the registry provider that serves it, so the provider table stays the one source
+ * of models, transports and credentials; the vendor only groups them.
+ */
+export type ProviderMode = 'subscription' | 'api';
+export interface ModelVendor {
+  id: string;
+  label: string;
+  /** Absent for gateways and local hosts. */
+  lab?: ModelLab;
+  subscription?: { provider: string } | { comingSoon: true };
+  api?: { provider: string };
+}
+
+/** The five main-thread labs first, in this order, then every other vendor alphabetically. */
+export const MODEL_VENDORS: readonly ModelVendor[] = [
+  {
+    id: 'anthropic',
+    label: 'Anthropic (Claude)',
+    lab: 'anthropic',
+    subscription: { provider: 'claude-code' },
+    api: { provider: 'anthropic' },
+  },
+  {
+    id: 'openai',
+    label: 'OpenAI (Codex, GPT)',
+    lab: 'openai',
+    subscription: { provider: 'codex' },
+    api: { provider: 'openai' },
+  },
+  {
+    id: 'google',
+    label: 'Google (Gemini)',
+    lab: 'google',
+    subscription: { comingSoon: true },
+    api: { provider: 'gemini' },
+  },
+  {
+    id: 'meta',
+    label: 'Meta (Muse)',
+    lab: 'meta',
+    subscription: { comingSoon: true },
+    api: { provider: 'meta' },
+  },
+  {
+    id: 'xai',
+    label: 'xAI (Grok)',
+    lab: 'xai',
+    subscription: { comingSoon: true },
+    api: { provider: 'xai' },
+  },
+  { id: 'alibaba', label: 'Alibaba (Qwen)', lab: 'alibaba', api: { provider: 'qwen' } },
+  { id: 'deepseek', label: 'DeepSeek', lab: 'deepseek', api: { provider: 'deepseek' } },
+  { id: 'fireworks', label: 'Fireworks AI', api: { provider: 'fireworks' } },
+  { id: 'groq', label: 'Groq', api: { provider: 'groq' } },
+  { id: 'mistral', label: 'Mistral AI', lab: 'mistral', api: { provider: 'mistral' } },
+  { id: 'moonshot', label: 'Moonshot AI (Kimi)', lab: 'moonshot', api: { provider: 'kimi' } },
+  { id: 'ollama', label: 'Ollama (local)', api: { provider: 'ollama' } },
+  { id: 'openrouter', label: 'OpenRouter', api: { provider: 'openrouter' } },
+  { id: 'together', label: 'Together AI', api: { provider: 'together' } },
+  { id: 'typesafe', label: 'TypeSafe (Jev)', lab: 'typesafe', api: { provider: 'typesafe' } },
+  { id: 'vllm', label: 'vLLM (local)', api: { provider: 'vllm' } },
+  { id: 'zhipu', label: 'Zhipu (GLM)', lab: 'zhipu', api: { provider: 'glm' } },
+];
+
+/** The registry provider serving a vendor's mode, or undefined when the mode has no transport. */
+export function vendorModeProvider(vendor: ModelVendor, mode: ProviderMode): string | undefined {
+  const entry = vendor[mode];
+  return entry && 'provider' in entry ? entry.provider : undefined;
+}
+
+/** The vendor and mode a registry provider serves. Every registered provider serves exactly one. */
+export function vendorOfProvider(
+  providerId: string,
+): { vendor: ModelVendor; mode: ProviderMode } | undefined {
+  for (const vendor of MODEL_VENDORS)
+    for (const mode of ['subscription', 'api'] as const)
+      if (vendorModeProvider(vendor, mode) === providerId) return { vendor, mode };
+  return undefined;
+}
+
 /** Every registered model carrying all of the requested capabilities. */
 export function modelOptionsByCapability(...capabilities: ModelCapability[]): ModelSweepOption[] {
   return Object.values(MODEL_REGISTRY).flatMap((provider) =>

package/src/thread.ts

@@ -90,7 +90,7 @@ export interface ThreadMeta {
   /** The parent's turn that spawned this thread (a subagent). */
   parentTurnId?: string;
 
-  /** How this subagent thread was spawned (docs/reference/SUBAGENTS.md §4.1). */
+  /** How this subagent thread was spawned. */
   spawn?: ThreadSpawn;
 
   /** 1 for a child of a main thread. */
@@ -170,6 +170,8 @@ export interface DispatchOptions {
    * everything that learns from the message sees only the user's words.
    */
   agentPayload?: unknown;
+  /** Images sent with the payload, for the agent alone (`ExecuteMeta.images`). */
+  images?: readonly import('./types').ImageInput[];
   /** Lets this dispatch's middleware include an on-demand layer in its assembly (`RequestContext.requestLayer`). */
   requestLayer?: (layerId: string) => void;
 }
@@ -437,6 +439,7 @@ export class Thread {
       },
       annotations: ctx.annotations,
       onDelta: opts?.onDelta,
+      ...(opts?.images?.length ? { images: opts.images } : {}),
       recordInjection: opts?.recordInjection,
       recordNative: opts?.recordNative,
       recordCompleted: opts?.recordCompleted,

package/src/types.ts

@@ -38,9 +38,34 @@ export interface LayerModeConfig {
 // LLM provider interface — the abstraction, not implementations
 // ---------------------------------------------------------------------------
 
+export const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'] as const;
+export type ImageMediaType = (typeof IMAGE_MEDIA_TYPES)[number];
+
+/** An image sent with a user message. */
+export interface ImageInput {
+  /** Identity of the stored image; what evidence records in place of the bytes. */
+  readonly id: string;
+  readonly mediaType: ImageMediaType;
+  /** Size of the image in bytes. */
+  readonly bytes: number;
+  /** The image, base64. Present at the provider boundary, dropped from recorded evidence. */
+  readonly data?: string;
+}
+
 export interface LLMMessage {
   readonly role: 'system' | 'user' | 'assistant';
   readonly content: string;
+  /** Images sent with this (user) message, for a provider that declares `imageInput`. */
+  readonly images?: readonly ImageInput[];
+}
+
+/** Messages as evidence records them: each image by identity, without its bytes. */
+export function withoutImageData(messages: readonly LLMMessage[]): LLMMessage[] {
+  return messages.map((message) =>
+    message.images
+      ? { ...message, images: message.images.map(({ data: _data, ...image }) => image) }
+      : message,
+  );
 }
 
 /** Tool definition sent to the LLM so it can call tools. */
@@ -155,6 +180,8 @@ export interface LLMStreamEvent {
 
 export interface LLMProvider {
   readonly id: string;
+  /** Accepts `LLMMessage.images`. A provider without it refuses a message that carries images. */
+  readonly imageInput?: boolean;
   /** 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. */