@wrongstack/core 0.309.0 → 0.310.0

package/dist/types/context.d.ts

@@ -0,0 +1,212 @@
+/**
+ * AgentContext — the structural contract of the agent-run object.
+ *
+ * Dependency-leaf module (Roadmap 10A): imports ONLY from sibling `types/*`
+ * modules. The concrete `Context` class (core/context.ts) implements this
+ * interface; tsc enforces structural compatibility on every build, so the
+ * interface cannot drift from the class silently.
+ *
+ * Why this exists: the CYCLE-12 type SCC was caused by `types/*.ts` and
+ * `utils/*` modules importing the `Context` CLASS type back from
+ * `core/context.ts`. Consumers below declare `AgentContext` instead — the
+ * back-edge disappears while the class stays the single implementation.
+ *
+ * Scope (2026-08-23): only `types/compactor.ts` and `conversation-state.ts`
+ * consume `AgentContext` today. Six back-edges on the `Context` class type
+ * remain (`types/tool.ts`, `types/error-handler.ts`, `types/provider-runner.ts`,
+ * `types/permission.ts`, `types/slash-command.ts`, `types/plugin.ts`) — they
+ * require the full class surface (state, file-tracking, catalogTools) which
+ * needs `ConversationState` resolved in this leaf first. Do not claim
+ * acyclicity until those flip.
+ *
+ * Statics (`Context.MAX_MESSAGES`, `Context.MAX_MESSAGE_TOKENS`) are read
+ * through the `messageLimits` accessor so runtime subclass overrides keep
+ * working (the reason the old `ctx.constructor` cast existed) without any
+ * consumer importing the class type.
+ */
+import type { ContextEvidenceState } from './context-evidence.js';
+import type { ConversationStateApi } from './conversation-state.js';
+import type { TextBlock } from './blocks.js';
+import type { FileEventRecord } from './file-event-record.js';
+import type { Message } from './messages.js';
+import type { Usage } from './provider.js';
+import type { RunEnv } from './run-env.js';
+import type { SessionEvent, SessionWriter } from './session.js';
+import type { SideEffect } from './side-effect.js';
+import type { Tool } from './tool.js';
+/** A single todo row projected to the model and the UI. */
+export interface TodoItem {
+    id: string;
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    activeForm?: string | undefined;
+    /** When promoted from a plan item, stores the plan item's id. */
+    promotedFromPlan?: string | undefined;
+    /** When promoted from a task, stores the task's id. */
+    promotedFromTask?: string | undefined;
+    /** Durable Kanban owner when the todo row is a UI projection of a real card. */
+    kanbanBoardId?: string | undefined;
+    /** Durable Kanban card represented by this todo row. */
+    kanbanTaskId?: string | undefined;
+    /** Titles of the unfinished work this row waits on (board-derived). */
+    blockedBy?: string[] | undefined;
+}
+/** Conversation retention limits, honoring runtime subclass overrides. */
+export interface ContextMessageLimits {
+    readonly maxMessages: number;
+    readonly maxMessageTokens: number;
+}
+/**
+ * Provider-bound memory evidence kept outside conversation history.
+ * Owners replace their own slot instead of appending (see class JSDoc).
+ */
+export interface ProviderMemoryEvidence {
+    /** Stable owner key, for example `sage.tool-memory`. */
+    source: string;
+    /** Provider-bound evidence text; never appended to chat/tool history. */
+    text: string;
+}
+/**
+ * The conversation-facing surface of the run object — the COMPLETE instance
+ * surface of the `Context` class (Roadmap 10A close-out). Mirrored 1:1 from
+ * the class declaration; `class Context implements RunEnv, AgentContext`
+ * makes tsc enforce compatibility on every core build.
+ */
+export interface AgentContext extends RunEnv {
+    messages: Message[];
+    meta: Record<string, unknown>;
+    todos: TodoItem[];
+    toolAdjacencyDirty: boolean;
+    systemPrompt: TextBlock[];
+    tools: Tool[];
+    contextEvidence: ContextEvidenceState;
+    /** Observable mutation wrapper; the concrete class satisfies this structurally. */
+    readonly state: ConversationStateApi;
+    registerAbortHook(fn: () => void | Promise<void>): () => void;
+    /** Retention limits honoring runtime subclass overrides of the statics. */
+    readonly messageLimits: ContextMessageLimits;
+    /**
+     * File-tracking surface (see the Context class for full semantics).
+     * `readFiles` is the permission write-bypass source of truth — it must
+     * NEVER contain files only touched by edit/write.
+     */
+    readFiles: Set<string>;
+    /** Files written by edit/write this session (observability only). */
+    writtenFiles: Set<string>;
+    /** Last-known mtime per tracked path; permission + edit-staleness checks. */
+    fileMtimes: Map<string, number>;
+    /** sha-256 (hex) at last recorded read/write; authoritative staleness arbiter. */
+    fileHashes: Map<string, string>;
+    /**
+     * Record a file observation. `source: 'write'` routes to writtenFiles;
+     * 'user' (default) routes to readFiles. `contentHash`, when available,
+     * becomes the authoritative staleness arbiter for later edits.
+     */
+    recordRead(absPath: string, mtimeMs: number, source?: 'user' | 'write', contentHash?: string): void;
+    /** Tool instances visible to tool_search/catalog surfaces. */
+    catalogTools: Tool[];
+    /** Structured side-effect records for the current run (bounded, MAX_SIDE_EFFECTS). */
+    sideEffects: SideEffect[];
+    /** Tracked file events for the current session (bounded, MAX_FILE_EVENTS). */
+    fileEvents: FileEventRecord[];
+    /** When false (default), file tools reject paths outside projectRoot. */
+    allowOutsideProjectRoot: boolean;
+    /** Current kanban task ID; tools use this via recordFileEvent() for task scope. */
+    currentKanbanTaskId: string | undefined;
+    /** Current kanban board ID, paired with currentKanbanTaskId. */
+    currentKanbanBoardId: string | undefined;
+    /** Session-level trace ID for correlating storage events with agent iterations. */
+    traceId: string | undefined;
+    /** Logical provider request whose response produced the current tool calls. */
+    activeLogicalRequestId: string | undefined;
+    /** Content-addressed prompt composition for activeLogicalRequestId. */
+    activePromptManifestId: string | undefined;
+    /**
+     * Session id pinned to the currently-executing run; event sites must
+     * prefer this over session.id (see Context class for session-swap
+     * rationale).
+     */
+    activeRunSessionId: string | undefined;
+    /** Writer pinned alongside activeRunSessionId for run-scoped appends. */
+    activeRunSessionWriter: SessionWriter | undefined;
+    /**
+     * Session id that events of the in-flight run must be stamped with:
+     * run-pinned id when active, otherwise the live session id.
+     */
+    eventSessionId(): string;
+    /** WorkingDir-change callbacks; public for structural typing. */
+    readonly _onWorkingDirChanged: Array<(newDir: string, oldDir: string) => void>;
+    /** Barrier serializing externally requested provider/model changes. */
+    _modelTransition: Promise<void>;
+    runModelTransition<T>(transition: () => T | Promise<T>): Promise<T>;
+    waitForModelTransition(): Promise<void>;
+    /** True when conversation gained new tool_use/tool_result blocks (adjacency repair). */
+    pendingPostToolContext: string | undefined;
+    /** Provider-bound memory evidence outside conversation/tool history. */
+    memoryEvidence: ProviderMemoryEvidence[];
+    setMemoryEvidence(source: string, text: string | undefined, maxChars?: number): void;
+    clearMemoryEvidence(source?: string): void;
+    /** Pre-computed total-request token estimate from the last pre-flight. */
+    lastRequestTokens: number | undefined;
+    /** Provider-authoritative prompt-token count from the most recent response. */
+    lastRealInputTokens: number | undefined;
+    /** Lazy observable wrapper backing `state`. */
+    _state: ConversationStateApi | null;
+    readonly _conversationJournalQueue: Array<{
+        event: SessionEvent;
+        bytes: number;
+        writer: SessionWriter;
+    }>;
+    _conversationJournalBytes: number;
+    _conversationJournalDrain: Promise<void> | null;
+    /** Wait until every exact conversation event queued so far is in the writer buffer. */
+    flushConversationJournal(): Promise<void>;
+    conversationJournalBytes(event: SessionEvent): number;
+    _journalDropCount: number;
+    _journalDropWarnAt: number;
+    /** Throttled notice that a conversation event never reached the journal. */
+    warnConversationJournalDrop(eventType: SessionEvent['type']): void;
+    enqueueConversationJournal(event: SessionEvent, writer: SessionWriter): void;
+    startConversationJournalDrain(): void;
+    /** Run-scoped abort hooks (drained by drainAbortHooks). */
+    readonly abortHooks: Set<() => void | Promise<void>>;
+    registerAgentHook(fn: () => void | Promise<void>): () => void;
+    drainAbortHooks(): Promise<void>;
+    /** Session-lifetime teardown hooks (drained by drainAgentHooks). */
+    readonly agentHooks: Set<() => void | Promise<void>>;
+    drainAgentHooks(): Promise<void>;
+    /** Enforce MAX_TRACKED_FILES cap on all four tracking structures. */
+    trimTrackedFiles(): void;
+    /** Clear accumulated file-read metadata after compaction/boundaries. */
+    clearFileTracking(): void;
+    /** Record a structured side effect for the audit trail (no undo). */
+    recordSideEffect(sideEffect: SideEffect): void;
+    /** Set the current kanban task context for file operations. */
+    setCurrentKanbanTask(taskId: string | undefined, boardId?: string | undefined): void;
+    /** Record a comprehensive file event (audit trail + JSONL persistence). */
+    recordFileEvent(input: {
+        operation: 'create' | 'read' | 'update' | 'delete' | 'rename';
+        filePath: string;
+        absPath: string;
+        toolName: string;
+        toolUseId: string;
+        durationMs?: number | undefined;
+        fileSize?: number | undefined;
+        lines?: number | undefined;
+        bytes?: number | undefined;
+    }): void;
+    /** True if the model/user explicitly saw this file's content. */
+    hasRead(absPath: string): boolean;
+    /** True if edit/write wrote this file in the current session. */
+    hasWritten(absPath: string): boolean;
+    lastReadMtime(absPath: string): number | undefined;
+    /** sha-256 (hex) of the content at the last recorded read/write, if any. */
+    lastReadHash(absPath: string): string | undefined;
+    /** Change the working directory (validated within projectRoot); fires callbacks. */
+    setWorkingDir(dir: string): string;
+    /** Register a workingDir-change callback; returns unsubscribe. */
+    onWorkingDirChanged(cb: (newDir: string, oldDir: string) => void): () => void;
+    /** Current usage snapshot from tokenCounter. */
+    usage(): Usage;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/types/conversation-state.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Conversation-state type leaf (Roadmap 10A).
+ *
+ * Dependency-leaf module: imports ONLY from sibling `types/*` modules. The
+ * concrete `ConversationState` class stays in `core/conversation-state.ts`
+ * (it has a runtime dep on `utils/token-estimate.js`); this leaf carries its
+ * TYPE surface so `AgentContext` (types/context.ts) can declare
+ * `state: ConversationStateApi` without importing the class module — the
+ * remaining CYCLE-12 back-edge (`types/tool.ts` et al. → `core/context.ts`)
+ * needs exactly this to flip.
+ *
+ * The class satisfies `ConversationStateApi` structurally; tsc enforces the
+ * compatibility on every build of core (the class re-exports these types for
+ * existing import paths).
+ */
+import type { ContentBlock } from './blocks.js';
+import type { TodoItem } from './context.js';
+import type { Message } from './messages.js';
+export type StateChange = {
+    kind: 'message_appended';
+    message: Message;
+} | {
+    kind: 'messages_replaced';
+    messages: readonly Message[];
+}
+/** The oldest `count` messages were evicted; see the `messages_dropped` SessionEvent. */
+ | {
+    kind: 'messages_dropped';
+    count: number;
+} | {
+    kind: 'message_updated';
+    index: number;
+    message: Message;
+} | {
+    kind: 'todos_replaced';
+    todos: readonly TodoItem[];
+    /**
+     * Final all-completed snapshot when the tactical list auto-clears.
+     * Observational mirrors use this to move cards to Done instead of
+     * interpreting the empty active list as "the work vanished".
+     */
+    completedSnapshot?: readonly TodoItem[] | undefined;
+} | {
+    kind: 'meta_set';
+    key: string;
+    value: unknown;
+} | {
+    kind: 'meta_deleted';
+    key: string;
+} | {
+    kind: 'meta_cleared';
+};
+export interface ReadonlyConversationState {
+    readonly messages: readonly Message[];
+    readonly todos: readonly TodoItem[];
+    readonly meta: Readonly<Record<string, unknown>>;
+}
+/**
+ * Structural API of the ConversationState wrapper — the COMPLETE instance
+ * surface of the concrete class in `core/conversation-state.ts` (Roadmap
+ * 10A). The class satisfies this interface structurally (it holds no
+ * private instance members), which makes `AgentContext.state` assignable
+ * both to the API and from the class — the property that lets the
+ * CYCLE-12 back-edges flip without importing the class module.
+ */
+export interface ConversationStateApi {
+    readonly messages: readonly Message[];
+    readonly todos: readonly TodoItem[];
+    readonly meta: Readonly<Record<string, unknown>>;
+    /** Monotonic mutation counter for consumers that need to detect rewrites. */
+    readonly revision: number;
+    /** Cheap O(1)-freeze immutable snapshot (see class JSDoc for semantics). */
+    snapshot(): ReadonlyConversationState;
+    appendMessage(message: Message): void;
+    /**
+     * Append a content block to the trailing user message's content array.
+     * Returns false when there is no trailing user message to fold into.
+     */
+    appendBlockToLastUserMessage(block: ContentBlock): boolean;
+    replaceMessages(messages: Message[]): void;
+    replaceTodos(todos: TodoItem[]): void;
+    setMeta(key: string, value: unknown): void;
+    deleteMeta(key: string): void;
+    clearMeta(): void;
+    /**
+     * Subscribe to mutations that go through this wrapper. Direct mutations of
+     * the compatibility arrays are intentionally not observed. Returns an
+     * unsubscribe function.
+     */
+    onChange(listener: (change: StateChange, state: ConversationStateApi) => void): () => void;
+    /** Owning context the wrapper reads/mutates. */
+    readonly ctx: import('./context.js').AgentContext;
+    /**
+     * Registered change subscribers. The concrete class and this leaf both
+     * type the handler parameter identically (`state: ConversationStateApi`),
+     * so the class's Set is assignable in both directions without the class
+     * importing anything from this leaf — and without variance escapes.
+     */
+    listeners: Set<(change: StateChange, state: ConversationStateApi) => void>;
+    /** Backing mutation counter behind the `revision` getter. */
+    _revision: number;
+    /** Retention-cap overflow computation (see class JSDoc). */
+    overflowCount(arr: readonly Message[]): number;
+    /** Protocol-safe front-eviction boundary (see class JSDoc). */
+    protocolSafeDropCount(arr: readonly Message[], drop: number): number;
+    /** Notify subscribers of a mutation and bump the revision. */
+    emit(change: StateChange): void;
+}
+//# sourceMappingURL=conversation-state.d.ts.map

package/dist/types/error-handler.d.ts

@@ -1,4 +1,4 @@
-import type { Context } from '../core/context.js';
+import type { AgentContext } from './context.js';
 import type { Response } from './provider.js';
 export type RecoveryDecision = {
     /**
@@ -30,7 +30,7 @@ export interface ErrorHandler {
      * retry the current turn, continue with a substitute response, or fail
      * deliberately. Callers should not infer control flow from truthiness.
      */
-    recover(err: unknown, ctx: Context): Promise<RecoveryDecision | null>;
+    recover(err: unknown, ctx: AgentContext): Promise<RecoveryDecision | null>;
     classify(err: unknown): {
         kind: 'rate_limit' | 'overloaded' | 'server' | 'client' | 'network' | 'abort' | 'context_overflow' | 'content_filter' | 'unknown';
         retryable: boolean;

package/dist/types/file-event-record.d.ts

@@ -39,6 +39,12 @@ export interface FileEventRecord {
     provider: string;
     /** LLM model id (e.g. "claude-sonnet-4-20250514") */
     model: string;
+    /** Logical provider request that produced the mutating tool call. */
+    logicalRequestId?: string | undefined;
+    /** Content-addressed provider-visible prompt identity. */
+    promptManifestId?: string | undefined;
+    /** Strength of the prompt-to-file attribution edge. */
+    provenanceConfidence: 'explicit' | 'correlated' | 'inferred' | 'unknown';
     /** Tool that performed the operation (e.g. "read", "write", "edit") */
     toolName: string;
     /** Tool-use block correlation ID for pairing start/end */

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@ export type { AdaptiveConcurrencyConfig, AgentLearningConfig, AutonomyConfig, Br
 export { DEFAULT_TUI_THINKING_WORD, FLEET_CHAT_VERBOSITY_VALUES, MAX_TUI_THINKING_WORD_LENGTH, normalizeTokenSavingTier, normalizeTuiThinkingWord, resolveFleetChatVerbosity, resolveTokenSavingTier, THEME_PRESET_IDS, } from './config.js';
 export type { CompletedWorkEvidence, CompletedWorkSource, ContextEvidenceState, ContextFileEvidence, ContextIntentEvidence, ContextRepeatedReadEvidence, ToolEvidenceStatus, ToolOutputMetadata, } from './context-evidence.js';
 export type { ContextSnapshot, ContextWindowAggressiveOn, ContextWindowConfigLike, ContextWindowMode, ContextWindowModeId, ContextWindowModeSelectionId, ContextWindowPolicy, ContextWindowThresholds, DeprecatedContextWindowModeId, } from './context-window.js';
-export { CONTEXT_WINDOW_MODES, CONTEXT_WINDOW_MODE_PINNED_META_KEY, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, LARGE_WINDOW_DEEP_MODE_THRESHOLD, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy, } from './context-window.js';
+export { CONTEXT_WINDOW_MODE_PINNED_META_KEY, CONTEXT_WINDOW_MODES, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, LARGE_WINDOW_DEEP_MODE_THRESHOLD, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy, } from './context-window.js';
 export type { CouncilDistinctness, CouncilLLMCaller, CouncilModelTarget, CouncilOption, CouncilPersona, CouncilProfileConfig, CouncilQuestion, CouncilResolutionMethod, CouncilResult, CouncilSeatConfig, CouncilUsage, CouncilVoteResult, CouncilVoteStatus, ResolvedCouncilProfile, ResolvedCouncilSeat, } from './council.js';
 export { DEFAULT_AUTONOMY_CONFIG, DEFAULT_CIRCUIT_BREAKER_CONFIG, DEFAULT_CONTEXT_CONFIG, DEFAULT_SESSION_LOGGING_CONFIG, DEFAULT_SESSION_PRUNE_DAYS, DEFAULT_TOOLS_CONFIG, } from './default-config.js';
 export type { DesignKitEntry, DesignKitLoader, DesignKitManifest, DesignKitTokens, DesignStack, DesignStudioState, DesignTokenSet, TokenValueKind, } from './design-kit.js';
@@ -34,7 +34,7 @@ export { BUILTIN_PROMPT_CATEGORIES, isBuiltinCategory, PROMPT_CATEGORY_LABELS }
 export type { InstalledPromptEntry, ManifestValidation, PromptManifestData, PromptRegistryManifest, PromptRegistryRef, RegistryDiff, } from './prompt-registry.js';
 export { diffRegistry, validateRegistryManifest } from './prompt-registry.js';
 export type { CacheTtl, Capabilities, JsonSchemaSpec, Provider, ProviderContextLimit, ProviderErrorBody, ProviderErrorKind, ReasoningConfig, ReasoningEffort, ReasoningRequest, Request, RequestCacheControl, Response, ResponseFormat, SafetySetting, StopReason, StreamEvent, Usage, } from './provider.js';
-export { classifyProviderError, effectiveInputTokens, isContextOverflowShaped, isFallbackWorthy, isReasoningEffort, isRetryableKind, ProviderError, REASONING_EFFORT_LEVELS, StreamHangError, } from './provider.js';
+export { classifyProviderError, effectiveInputTokens, freshInputTokens, isContextOverflowShaped, isFallbackWorthy, isReasoningEffort, isRetryableKind, ProviderError, promptCacheHitRatio, REASONING_EFFORT_LEVELS, StreamHangError, } from './provider.js';
 export type { ProviderRunner, RunProviderOptions } from './provider-runner.js';
 export type { Renderer } from './renderer.js';
 export type { SecretScrubber } from './secret-scrubber.js';
@@ -53,7 +53,7 @@ export type { BuildContext, ModelCapabilities, SystemPromptBuilder, SystemPrompt
 export { flattenSystemPromptRegions } from './system-prompt.js';
 export type { SystemPromptContributor } from './system-prompt-contributor.js';
 export type { CriticalPathResult, SerializableTaskGraph, SerializableTaskGraphNodes, SerializedTaskGraph, TaskAssignment, TaskDependency, TaskEdge, TaskFilter, TaskGraph, TaskNode, TaskPriority, TaskProgress, TaskSort, TaskStatus, TaskType, } from './task-graph.js';
-export type { CacheStats, TokenCounter } from './token-counter.js';
+export type { CacheStats, ProviderCacheStats, TokenCounter } from './token-counter.js';
 export type { JSONSchema, Permission, RiskTier, Tool, ToolCallContext, ToolErrorInfo, ToolFinalEvent, ToolIconId, ToolProgressEvent, ToolStreamEvent, } from './tool.js';
 export { ToolErrorCategory } from './tool.js';
 export type { ConfirmAwaiter, GovernedToolExecutionResult, GovernedToolExecutor, ToolBatchResult, ToolConfirmPendingResult, ToolExecution, ToolExecutionOutput, ToolExecutorInit, ToolExecutorLike, ToolExecutorOptions, ToolExecutorStrategy, } from './tool-executor.js';

package/dist/types/index.js

@@ -929,6 +929,15 @@ function isReasoningEffort(value) {
 function effectiveInputTokens(usage) {
   return usage.input + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
 }
+function freshInputTokens(usage) {
+  return Math.max(0, effectiveInputTokens(usage) - (usage.cacheRead ?? 0));
+}
+function promptCacheHitRatio(usage) {
+  const total = effectiveInputTokens(usage);
+  if (!Number.isFinite(total) || total <= 0) return 0;
+  const cached = Number.isFinite(usage.cacheRead) ? Math.max(0, usage.cacheRead ?? 0) : 0;
+  return Math.min(1, cached / total);
+}
 var CONTEXT_OVERFLOW_RE = /context.length|context.window|maximum context|max.*tokens?.*exceeded|(?:prompt|request|input|messages?).{0,12}too (?:large|long)|exceeds the context|\btokens\b.*exceed|too many tokens|reduce the length|resulted in \d+ tokens|context_length_exceeded/i;
 var CONTENT_FILTER_RE = /content.(filter|policy|moderation)|safety (system|filter)/i;
 var RATE_LIMIT_EXCEEDED_RE = /rate[-_\s]*limit[-_\s]*exceeded/i;
@@ -1064,7 +1073,12 @@ function isContextOverflowShaped(err) {
   const providerErr = err;
   if (providerErr.kind === "context_overflow" || providerErr.status === 413) return true;
   if (providerErr.status < 400) return false;
-  const text = [providerErr.message, providerErr.body?.message, providerErr.body?.type, providerErr.body?.raw].filter(Boolean).join("\n");
+  const text = [
+    providerErr.message,
+    providerErr.body?.message,
+    providerErr.body?.type,
+    providerErr.body?.raw
+  ].filter(Boolean).join("\n");
   return CONTEXT_OVERFLOW_RE.test(text);
 }
 function describeStatus(status, type) {
@@ -1375,6 +1389,7 @@ export {
   effectiveInputTokens,
   flattenSystemPromptRegions,
   formatContextWindowModeList,
+  freshInputTokens,
   getContextWindowMode,
   isAgentError,
   isBuiltinCategory,
@@ -1406,6 +1421,7 @@ export {
   normalizeTokenSavingTier,
   normalizeTuiThinkingWord,
   projectSessionMarkers,
+  promptCacheHitRatio,
   resolveContextWindowPolicy,
   resolveFleetChatVerbosity,
   resolveTokenSavingTier,

package/dist/types/permission.d.ts

@@ -1,4 +1,4 @@
-import type { Context } from '../core/context.js';
+import type { AgentContext } from './context.js';
 import type { Permission, Tool } from './tool.js';
 export interface TrustPolicy {
     [toolNameOrPattern: string]: {
@@ -110,13 +110,13 @@ export interface DirectoryPolicy {
     rules: DirectoryRule[];
 }
 export interface PermissionPolicy {
-    evaluate(tool: Tool, input: unknown, ctx: Context): Promise<PermissionDecision>;
+    evaluate(tool: Tool, input: unknown, ctx: AgentContext): Promise<PermissionDecision>;
     /**
      * Side-effect-free permission evaluation trace. Returns the same
      * logical result as `evaluate()` without prompting the user,
      * writing to trust files, or mutating session state.
      */
-    explain?(tool: Tool, input: unknown, ctx: Context): Promise<PermissionTrace>;
+    explain?(tool: Tool, input: unknown, ctx: AgentContext): Promise<PermissionTrace>;
     trust(rule: {
         tool: string;
         pattern: string;

package/dist/types/plugin.d.ts

@@ -2,7 +2,7 @@ import type { Mailbox } from '../coordination/mailbox-types.js';
 import type { Notifier } from '../notifications/notifier.js';
 export type { Notifier };
 import type { ToolCallPipelinePayload } from '../core/agent.js';
-import type { Context } from '../core/context.js';
+import type { AgentContext } from './context.js';
 import type { ExtensionRegistry } from '../extension/registry.js';
 import type { Container } from '../kernel/container.js';
 import type { EventBus, EventName, Listener } from '../kernel/events.js';
@@ -174,10 +174,10 @@ export interface PluginPipelines {
     userInput: ReadonlyPipeline<{
         content: import('./blocks.js').ContentBlock[];
         text: string;
-        ctx: Context;
+        ctx: AgentContext;
     }>;
     assistantOutput: ReadonlyPipeline<TextBlock>;
-    contextWindow: ReadonlyPipeline<Context>;
+    contextWindow: ReadonlyPipeline<AgentContext>;
     [k: string]: ReadonlyPipeline<any>;
 }
 export interface PluginAPI {

package/dist/types/provider-runner.d.ts

@@ -1,9 +1,9 @@
 import type { EventBus } from '../kernel/events.js';
+import type { AgentContext } from './context.js';
 import type { Logger } from './logger.js';
 import type { Tracer } from './observability.js';
 import type { Provider, Request, Response } from './provider.js';
 import type { RetryPolicy } from './retry-policy.js';
-import type { Context } from '../core/context.js';
 /**
  * Options passed to a ProviderRunner when calling the provider.
  * Shape intentionally mirrors runProviderWithRetry's parameters
@@ -13,7 +13,7 @@ export interface RunProviderOptions {
     provider: Provider;
     request: Request;
     signal: AbortSignal;
-    ctx: Context;
+    ctx: AgentContext;
     events: EventBus;
     retry: RetryPolicy;
     logger: Logger;

package/dist/types/provider.d.ts

@@ -101,6 +101,16 @@ export interface Usage {
  * full prompt the model saw, not only the bill-at-full-rate slice.
  */
 export declare function effectiveInputTokens(usage: Usage): number;
+/** Prompt tokens that were not served by a cache read. */
+export declare function freshInputTokens(usage: Usage): number;
+/**
+ * Cache-read share of the complete prompt context, normalized to [0, 1].
+ *
+ * Keeping the clamp at the shared telemetry boundary protects every UI from
+ * malformed/hybrid gateway counters while provider adapters preserve the
+ * real total context in the disjoint Usage buckets.
+ */
+export declare function promptCacheHitRatio(usage: Usage): number;
 export interface ReasoningRequest {
     enabled?: boolean | undefined;
     effort?: ReasoningEffort | undefined;

package/dist/types/run-env.d.ts

@@ -0,0 +1,32 @@
+/**
+ * RunEnv — the read-only environment view of the agent run.
+ *
+ * Dependency-leaf module (Roadmap 10A): imports ONLY from sibling `types/*`
+ * modules, never from `core/`. The concrete `Context` class satisfies this
+ * interface structurally; `extractRunEnv()` (in `core/run-env.ts`) builds a
+ * frozen view for subsystems that want to declare "env-only" access.
+ *
+ * Consumers that only need these fields should type their parameters as
+ * `RunEnv` — not `Context` — so the type module graph stays acyclic.
+ */
+import type { Provider } from './provider.js';
+import type { SessionWriter } from './session.js';
+import type { TextBlock } from './blocks.js';
+import type { TokenCounter } from './token-counter.js';
+import type { Tool } from './tool.js';
+export interface RunEnv {
+    readonly provider: Provider;
+    readonly session: SessionWriter;
+    readonly signal: AbortSignal;
+    readonly tokenCounter: TokenCounter;
+    readonly cwd: string;
+    readonly projectRoot: string;
+    /** Mutable working directory — starts as `cwd`. */
+    readonly workingDir: string;
+    readonly model: string;
+    readonly systemPrompt: readonly TextBlock[];
+    readonly tools: readonly Tool[];
+    readonly agentId: string;
+    readonly agentName: string;
+}
+//# sourceMappingURL=run-env.d.ts.map

package/dist/types/session.d.ts

@@ -416,6 +416,9 @@ export type SessionEvent = {
     agentName: string;
     provider: string;
     model: string;
+    logicalRequestId?: string | undefined;
+    promptManifestId?: string | undefined;
+    provenanceConfidence?: 'explicit' | 'correlated' | 'inferred' | 'unknown' | undefined;
     toolName: string;
     toolUseId: string;
     scope: 'project' | 'session' | 'task';

package/dist/types/slash-command.d.ts

@@ -1,4 +1,4 @@
-import type { Context } from '../core/context.js';
+import type { AgentContext } from './context.js';
 /**
  * A slash command registered with the CLI or available to plugins.
  * Plugins receive a view of the registry via PluginAPI.slashCommands.
@@ -49,7 +49,7 @@ export interface SlashCommand {
      * the model's response starts streaming. `{ metadata }` carries
      * structured data for the REPL/TUI to act on (e.g. SDD session state).
      */
-    run(args: string, ctx?: Context | undefined): Promise<{
+    run(args: string, ctx?: AgentContext | undefined): Promise<{
         exit?: boolean | undefined;
         message?: string | undefined;
         runText?: string | undefined;

package/dist/types/token-counter.d.ts

@@ -1,10 +1,37 @@
 import type { Usage } from './provider.js';
+export interface ProviderCacheStats {
+    provider: string;
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** cacheRead / complete prompt context for this provider. Clamped to [0, 1]. */
+    hitRatio: number;
+    /**
+     * Tokens written into the cache by this provider, split by TTL when the
+     * upstream exposes the breakdown. Anthropic-family providers (incl.
+     * MiniMax on the Anthropic surface) emit `cache_creation` with a 5-min
+     * and a 1-hour sub-bucket; OpenAI-family gateways emit a single
+     * aggregate and leave these undefined.
+     */
+    cacheWrite5m?: number | undefined;
+    cacheWrite1h?: number | undefined;
+}
 export interface CacheStats {
     /** Tokens served from cache (cheaper). */
     readTokens: number;
     /** Tokens written into the cache (more expensive than input on first hit). */
     writeTokens: number;
-    /** Hit ratio: cacheRead / (cacheRead + input). 0 when nothing cached. */
+    /**
+     * 5-minute cache-write tokens for providers that expose the TTL split
+     * (Anthropic family). Undefined when the provider only emits an aggregate.
+     */
+    cacheWrite5m?: number | undefined;
+    /**
+     * 1-hour cache-write tokens for providers that expose the TTL split
+     * (Anthropic family). Undefined when the provider only emits an aggregate.
+     */
+    cacheWrite1h?: number | undefined;
+    /** Hit ratio: cacheRead / total prompt context. Clamped to [0, 1]. */
     hitRatio: number;
     /**
      * USD saved by cache reads: cacheRead tokens billed at the cache-read rate
@@ -13,6 +40,8 @@ export interface CacheStats {
      * this is the gross read discount, the figure users recognize as "saved".
      */
     savedUsd: number;
+    /** Session totals split by routed provider, most cache-read tokens first. */
+    providers?: ProviderCacheStats[] | undefined;
 }
 export interface TokenCounter {
     account(usage: Usage, model?: string, providerId?: string): void | undefined;

package/dist/types/tool-executor.d.ts

@@ -1,5 +1,5 @@
-import type { ToolResultBlock, ToolUseBlock } from '../types/blocks.js';
-import type { Tool } from '../types/tool.js';
+import type { ToolResultBlock, ToolUseBlock } from './blocks.js';
+import type { Tool } from './tool.js';
 /** Context.meta key installed by ToolExecutor for governed calls made by meta-tools. */
 export declare const GOVERNED_TOOL_EXECUTOR_META_KEY = "toolExecutor.executeGoverned";
 /** Result returned to meta-tools after a nested call traverses the normal executor. */