@inixiative/foundry-core 0.5.5 → 0.5.7

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.5.5",
+  "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
@@ -410,9 +417,15 @@ export {
   type ModelPricing,
   TokenTracker,
   type TokenUsage,
+  type UsageAttribution,
   type UsageBreakdown,
   type UsageEntry,
+  type UsageFilter,
+  type UsageRecord,
   type UsageSummary,
+  type UsageWindow,
+  type WindowReading,
+  windowDelta,
 } from './token-tracker';
 // Tools — typed execution interfaces
 export {
@@ -458,6 +471,8 @@ export type {
   CompletionResult,
   EmbeddingProvider,
   EmbeddingResult,
+  ImageInput,
+  ImageMediaType,
   InvocationCondition,
   LayerModeConfig,
   LLMMessage,
@@ -467,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/token-tracker.ts

@@ -15,15 +15,28 @@ export interface TokenUsage extends TokenCounts {
 }
 
 /**
- * A single recorded usage entry — one LLM call.
+ * What a usage entry or window reading is for, beyond the built-in dimensions: e.g. a replay's
+ * `fixtureId`, `arm`, `runId` and `role`. Filters match on these keys exactly.
+ */
+export type UsageAttribution = Readonly<Record<string, string>>;
+
+/**
+ * A single recorded usage entry — one LLM call (for a native session, one turn).
  */
 export interface UsageEntry {
   readonly timestamp: number;
   readonly provider: string;
   readonly model: string;
+  readonly effort?: string;
   readonly agentId?: string;
   readonly threadId?: string;
   readonly spanId?: string;
+  /**
+   * The subscription login the call ran on, by a non-secret id: a Kingdom Integration id, or a
+   * local label (`local`, `setup-token:<sha256 prefix>`). Never the credential itself.
+   */
+  readonly integrationId?: string;
+  readonly attribution?: UsageAttribution;
   readonly tokens: Readonly<TokenCounts>;
   readonly cost: number;
   /** False means cost is an unpriced subtotal, not a zero-price acknowledgment. */
@@ -31,6 +44,96 @@ export interface UsageEntry {
   readonly cached?: boolean;
 }
 
+/**
+ * One reading of a subscription login's usage windows (percent used per window id, e.g.
+ * `five_hour`), taken over the provider's control channel, not a model call. A window covers the
+ * whole login, so its growth between two readings is an upper bound on what the calls between them
+ * spent.
+ */
+/** One usage window in a reading. */
+export interface UsageWindow {
+  /** 0–100. */
+  readonly usedPercent: number;
+  /** When the window resets (epoch ms); a different value in a later reading means it reset. */
+  readonly resetsAt?: number;
+  readonly windowMinutes?: number;
+}
+
+export interface WindowReading {
+  /** When the provider observed it (epoch ms). */
+  readonly timestamp: number;
+  readonly provider: string;
+  readonly integrationId?: string;
+  /** Where in the work it was taken, e.g. `before`, `after`, `gate`. */
+  readonly phase: string;
+  /** How it was read, e.g. `session` (the work's own session) or `probe` (a separate one). */
+  readonly source: string;
+  readonly windows: Readonly<Record<string, UsageWindow>>;
+  /** The provider reports ordinary usage blocked. Absent means not reported. */
+  readonly blocked?: boolean;
+  /** The provider's reason label when a limit is reached. */
+  readonly reachedType?: string;
+  readonly plan?: string;
+  readonly attribution?: UsageAttribution;
+}
+
+/**
+ * Selects entries and readings: every given field must match, and every given attribution key.
+ * Window readings carry no model, effort, agent, thread or span, so only `provider`,
+ * `integrationId` and `attribution` select them.
+ */
+export interface UsageFilter {
+  readonly provider?: string;
+  readonly model?: string;
+  readonly effort?: string;
+  readonly agentId?: string;
+  readonly threadId?: string;
+  readonly spanId?: string;
+  readonly integrationId?: string;
+  readonly attribution?: UsageAttribution;
+}
+
+/** The usage a filter selects: its calls, their totals and the window readings, as recorded. */
+export interface UsageRecord {
+  readonly calls: number;
+  readonly totals: TokenUsage;
+  readonly entries: ReadonlyArray<UsageEntry>;
+  readonly windowReadings: ReadonlyArray<WindowReading>;
+}
+
+/** Two readings of one reset time this far apart are different windows (reset times jitter). */
+const RESET_TOLERANCE_MS = 60_000;
+
+/**
+ * Growth per window id present in both readings, in percentage points (2 decimals). A window
+ * whose reset time moved between the readings reset in between: its growth is unknown, so it is
+ * listed under `reset` instead of `delta`.
+ */
+export function windowDelta(
+  before: WindowReading['windows'],
+  after: WindowReading['windows'],
+): { delta: Record<string, number>; reset: string[] } {
+  const delta: Record<string, number> = {};
+  const reset: string[] = [];
+  for (const [id, a] of Object.entries(after)) {
+    const b = before[id];
+    if (!b) continue;
+    if (
+      b.resetsAt !== undefined &&
+      a.resetsAt !== undefined &&
+      Math.abs(a.resetsAt - b.resetsAt) > RESET_TOLERANCE_MS
+    )
+      reset.push(id);
+    else delta[id] = Number((a.usedPercent - b.usedPercent).toFixed(2));
+  }
+  return { delta, reset };
+}
+
+const attributionMatches = (
+  attribution: UsageAttribution | undefined,
+  want: UsageAttribution | undefined,
+): boolean => !want || Object.entries(want).every(([key, value]) => attribution?.[key] === value);
+
 /**
  * Per-model pricing: cost in dollars per 1 million tokens.
  */
@@ -188,6 +291,7 @@ type EventHandler = (status: BudgetStatus) => void;
 
 export class TokenTracker {
   private readonly _entries: UsageEntry[] = [];
+  private readonly _windowReadings: WindowReading[] = [];
   private readonly _costTable: CostTable;
   private readonly _budget: BudgetConfig;
   private readonly _warningHandlers: EventHandler[] = [];
@@ -232,10 +336,56 @@ export class TokenTracker {
     return full;
   }
 
+  /**
+   * Record a reading of a login's usage windows. It spends nothing, so no budget is checked.
+   * `timestamp` defaults to now.
+   */
+  recordWindows(reading: Omit<WindowReading, 'timestamp'> & { timestamp?: number }): WindowReading {
+    const full: WindowReading = { ...reading, timestamp: reading.timestamp ?? Date.now() };
+    this._windowReadings.push(full);
+    return full;
+  }
+
   // -----------------------------------------------------------------------
   // Queries
   // -----------------------------------------------------------------------
 
+  /** Every entry the filter selects, in recording order. */
+  entries(filter: UsageFilter = {}): ReadonlyArray<UsageEntry> {
+    return this._entries.filter(
+      (e) =>
+        (filter.provider === undefined || e.provider === filter.provider) &&
+        (filter.model === undefined || e.model === filter.model) &&
+        (filter.effort === undefined || e.effort === filter.effort) &&
+        (filter.agentId === undefined || e.agentId === filter.agentId) &&
+        (filter.threadId === undefined || e.threadId === filter.threadId) &&
+        (filter.spanId === undefined || e.spanId === filter.spanId) &&
+        (filter.integrationId === undefined || e.integrationId === filter.integrationId) &&
+        attributionMatches(e.attribution, filter.attribution),
+    );
+  }
+
+  /** Every window reading the filter selects (by provider, integrationId and attribution). */
+  windowReadings(filter: UsageFilter = {}): ReadonlyArray<WindowReading> {
+    return this._windowReadings.filter(
+      (r) =>
+        (filter.provider === undefined || r.provider === filter.provider) &&
+        (filter.integrationId === undefined || r.integrationId === filter.integrationId) &&
+        attributionMatches(r.attribution, filter.attribution),
+    );
+  }
+
+  /** The calls, totals and window readings a filter selects, as one record. */
+  usageRecord(filter: UsageFilter = {}): UsageRecord {
+    const entries = this.entries(filter);
+    return {
+      calls: entries.length,
+      totals: this._aggregate(entries),
+      entries,
+      windowReadings: this.windowReadings(filter),
+    };
+  }
+
   get totalTokens(): TokenUsage {
     return this._aggregate(this._entries);
   }
@@ -291,9 +441,10 @@ export class TokenTracker {
     };
   }
 
-  /** Clear all recorded entries and reset warning state. */
+  /** Clear all recorded entries and window readings, and reset warning state. */
   reset(): void {
     this._entries.length = 0;
+    this._windowReadings.length = 0;
     this._warningEmitted = false;
   }
 
@@ -340,7 +491,7 @@ export class TokenTracker {
     );
   }
 
-  private _aggregate(entries: UsageEntry[]): TokenUsage {
+  private _aggregate(entries: ReadonlyArray<UsageEntry>): TokenUsage {
     const tokens = sumTokenCounts(entries.map((e) => e.tokens));
     return {
       ...tokens,

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. */