@vybestack/llxprt-code-core 0.11.0 → 0.12.0-nightly.260910.2aac6841e

package/src/recording/types.ts

@@ -24,6 +24,7 @@
  */
 
 import { type IContent } from '../services/history/IContent.js';
+import type { LocalMediaStore } from '../storage/local-media-store.js';
 
 export const SESSION_TITLE_MAX_LENGTH = 120;
 
@@ -52,7 +53,8 @@ export type SessionEventType =
   | 'checkpoint_renamed'
   | 'checkpoint_deleted'
   | 'session_forked'
-  | 'session_named';
+  | 'session_named'
+  | 'semantic_media_purge';
 
 // ---------------------------------------------------------------------------
 // Event envelope
@@ -113,11 +115,28 @@ export interface CompressedPayload {
 }
 
 /**
- * Payload for the `rewind` event — removes the last N items from history.
+ * Payload for the `rewind` event — removes the tail of history from the cut
+ * point onwards.
  */
 export interface RewindPayload {
   /** Positive integer — number of items removed from the end of history. */
   itemsRemoved: number;
+
+  /**
+   * Chronology `seq` of the FIRST removed item, when that item carried a
+   * chronology marker (#1721). Replay cuts at the item whose marker `seq`
+   * EQUALS this value, which stays correct even when live history and the
+   * journal have diverged — density optimization removes items from live
+   * history without journalling anything, so `itemsRemoved` alone removes the
+   * wrong amount on replay.
+   *
+   * Absent on legacy events and whenever the cut item has no marker. Replay
+   * falls back to `itemsRemoved` whenever it is absent, unreadable, or names
+   * an item that is not in the replayed history.
+   *
+   * @issue #2934
+   */
+  cutSeq?: number;
 }
 
 /**
@@ -157,6 +176,14 @@ export interface DirectoriesChangedPayload {
   directories: string[];
 }
 
+export interface SemanticMediaPurgePayload {
+  readonly history: readonly IContent[];
+  readonly frontier: {
+    readonly contentIndex: number;
+    readonly blockIndex: number;
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Checkpoint and session-branching metadata event payloads.
 //
@@ -243,6 +270,10 @@ export interface SessionRecordingServiceConfig {
   cwd?: string;
   provider: string;
   model: string;
+  /** Hard bound for serialized records waiting for durable write. */
+  maxQueueBytes?: number;
+  /** Project-owned store used to verify referenced media during lifecycle replay. */
+  mediaStore?: LocalMediaStore;
 }
 
 // ---------------------------------------------------------------------------
@@ -294,6 +325,10 @@ export type ReplayResult =
       sessionName?: string | null;
       /** Self-contained child ancestry from the `session_forked` event. */
       ancestry?: SessionForkedPayload;
+      readonly semanticMediaPurgeFrontier?: {
+        readonly contentIndex: number;
+        readonly blockIndex: number;
+      };
     }
   | {
       ok: false;

package/src/runtime/AgentRuntimeContext.ts

@@ -77,6 +77,7 @@ export interface ReadonlySettingsSnapshot {
    * to catch omissions in the summary. Defaults to false.
    */
   compressionVerification?: boolean;
+  'media.semantic-purge'?: 'off' | 'remove' | 'summary';
 }
 
 /**
@@ -228,6 +229,7 @@ export interface AgentRuntimeContext {
      * to catch omissions in the summary. Defaults to false.
      */
     compressionVerification(): boolean;
+    semanticMediaPurge(): 'off' | 'remove' | 'summary';
     /**
      * @plan PLAN-20251202-THINKING.P03b
      * @requirement REQ-THINK-006
@@ -263,6 +265,15 @@ export interface AgentRuntimeContext {
 
   /** Provider runtime snapshot for downstream provider calls */
   readonly providerRuntime: ProviderRuntimeContext;
+
+  /** Project-owned local media store shared with session lifecycle services. */
+  readonly mediaStore?: LocalMediaStore;
+
+  /** Async boundary that replaces newly created local image bytes before use. */
+  readonly mediaAdmission?: MediaAdmissionService;
+
+  /** Provider-neutral late materialization boundary for physical requests. */
+  readonly mediaResolver?: RequestMediaResolver;
 }
 
 /**
@@ -294,11 +305,23 @@ export interface AgentRuntimeContextFactoryOptions {
 
   /** Required: provider runtime context */
   providerRuntime: ProviderRuntimeContext;
+
+  /** Optional project-owned local media store. */
+  mediaStore?: LocalMediaStore;
+
+  /** Optional async local-media admission boundary. */
+  mediaAdmission?: MediaAdmissionService;
+
+  /** Optional provider-neutral request media resolver. */
+  mediaResolver?: RequestMediaResolver;
 }
 
 // Type imports (these will be resolved from existing modules)
 import type { AgentRuntimeState } from './AgentRuntimeState.js';
 import type { HistoryService } from '../services/history/HistoryService.js';
+import type { MediaAdmissionService } from '../storage/media-admission-service.js';
+import type { LocalMediaStore } from '../storage/local-media-store.js';
+import type { RequestMediaResolver } from '../storage/request-media-resolver.js';
 import type { RuntimeProvider as IProvider } from './contracts/RuntimeProvider.js';
 import type { ProviderRuntimeContext } from './providerRuntimeContext.js';
 
@@ -309,12 +332,12 @@ import type { ProviderRuntimeContext } from './providerRuntimeContext.js';
  * compatible objects.
  */
 export interface RuntimeUsageMetadata {
-  promptTokenCount?: number;
-  candidatesTokenCount?: number;
+  inputTokenCount?: number;
+  outputTokenCount?: number;
   totalTokenCount?: number;
-  cachedContentTokenCount?: number;
-  thoughtsTokenCount?: number;
-  toolUsePromptTokenCount?: number;
+  cachedTokenCount?: number;
+  thinkingTokenCount?: number;
+  toolUseInputTokenCount?: number;
   [key: string]: unknown;
 }
 

package/src/runtime/AgentRuntimeLoader.ts

@@ -5,7 +5,11 @@
  */
 
 import { HistoryService } from '../services/history/HistoryService.js';
+import { createHistoryProviderFileBindingStore } from '../services/history/provider-file-binding.js';
 import type { Config } from '../config/config.js';
+import type { LocalMediaStore } from '../storage/local-media-store.js';
+import { MediaAdmissionService } from '../storage/media-admission-service.js';
+import { RequestMediaResolver } from '../storage/request-media-resolver.js';
 import {
   hasToolSchema,
   resolveToolDescription,
@@ -48,6 +52,9 @@ export interface AgentRuntimeLoaderOverrides {
   telemetryAdapter?: AgentRuntimeTelemetryAdapter;
   toolsView?: ToolRegistryView;
   historyService?: HistoryService;
+  mediaStore?: LocalMediaStore;
+  mediaAdmission?: MediaAdmissionService;
+  mediaResolver?: RequestMediaResolver;
   contentGenerator?: ContentGenerator;
   contentGeneratorFactory?: ContentGeneratorFactory;
 }
@@ -196,16 +203,18 @@ function createFilteredToolRegistryView(
   };
 }
 
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted !== true) return;
+  const error = new Error('Runtime load aborted');
+  error.name = 'AbortError';
+  throw error;
+}
+
 export async function loadAgentRuntime(
   options: AgentRuntimeLoaderOptions,
 ): Promise<AgentRuntimeLoaderResult> {
   const { profile, overrides = {}, signal } = options;
-
-  if (signal?.aborted === true) {
-    const error = new Error('Runtime load aborted');
-    error.name = 'AbortError';
-    throw error;
-  }
+  throwIfAborted(signal);
 
   const history = overrides.historyService ?? new HistoryService();
 
@@ -226,6 +235,13 @@ export async function loadAgentRuntime(
       profile.toolRegistry ?? profile.config.getToolRegistry(),
       governance,
     );
+  const mediaStore =
+    overrides.mediaStore ?? profile.config.getLocalMediaStore();
+  const mediaAdmission =
+    overrides.mediaAdmission ?? new MediaAdmissionService(mediaStore);
+  const mediaResolver =
+    overrides.mediaResolver ?? new RequestMediaResolver(mediaStore);
+  const requestMediaBudgetBytes = profile.config.getImagePayloadBudgetBytes();
 
   const runtimeContext = createAgentRuntimeContext({
     state: profile.state,
@@ -234,9 +250,18 @@ export async function loadAgentRuntime(
     telemetry: telemetryAdapter,
     tools: toolsView,
     history,
-    providerRuntime: profile.providerRuntime,
+    providerRuntime: {
+      ...profile.providerRuntime,
+      mediaResolver,
+      requestMediaBudgetBytes,
+      providerFileBindings: createHistoryProviderFileBindingStore(history),
+    },
+    mediaStore,
+    mediaAdmission,
+    mediaResolver,
   });
 
+  await history.settleMediaOwnership();
   let contentGenerator: ContentGenerator;
   if (overrides.contentGenerator) {
     contentGenerator = overrides.contentGenerator;

package/src/runtime/contracts/PromptEstimation.ts

@@ -47,6 +47,7 @@ export interface PromptEnvelopeProjection {
   readonly finalizedProjection: unknown;
   readonly legacyEstimate: () => Promise<number>;
   readonly accounting?: PromptEnvelopeAccountingProjection;
+  readonly releaseIfUnsent?: () => Promise<void>;
 }
 
 export interface PromptEnvelopeEstimate {

package/src/runtime/contracts/RuntimeProvider.ts

@@ -66,6 +66,9 @@ export interface RuntimeProvider {
   isPaidMode?(): boolean;
   getModelParams?(): Record<string, unknown> | undefined;
   getContextLimit?(): number | undefined;
+  getMediaTransportCapabilities?(): {
+    readonly explicitCacheBreakpoints: boolean;
+  };
   clearAuthCache?(): void;
   clearAuth?(): void;
 
@@ -78,14 +81,6 @@ export interface RuntimeProvider {
       | null,
   ): void;
 
-  getServerTools(): string[];
-  invokeServerTool(
-    toolName: string,
-    params: unknown,
-    config?: unknown,
-    signal?: AbortSignal,
-  ): Promise<unknown>;
-
   generateChatCompletion(
     options: RuntimeGenerateChatOptions,
   ): AsyncIterableIterator<IContent>;

package/src/runtime/contracts/RuntimeProviderManager.ts

@@ -60,8 +60,6 @@ export interface RuntimeProviderManager {
   prepareStatelessProviderInvocation?(runtimeContext?: unknown): unknown;
   getProviderMetrics(): RuntimeProviderMetrics;
   getSessionTokenUsage(): RuntimeSessionTokenUsage;
-  getServerToolsProvider(): RuntimeProvider | null | undefined;
-  setServerToolsProvider(provider: RuntimeProvider | null): void;
   setConfig(config: Config): void;
   setRuntimeContext(runtimeContext: ProviderRuntimeContext): void;
   hasActiveProvider(): boolean;

package/src/runtime/createAgentRuntimeContext.ts

@@ -13,6 +13,7 @@
  */
 
 import { HistoryService } from '../services/history/HistoryService.js';
+import { HistoryMediaOwnership } from '../storage/history-media-ownership.js';
 import type {
   AgentRuntimeContext,
   AgentRuntimeContextFactoryOptions,
@@ -25,7 +26,10 @@ import {
   resolveProviderReportedLimit,
 } from '../core/tokenLimits.js';
 /** @plan PLAN-20260211-COMPRESSION.P12 */
-import { getSettingSpec } from '@vybestack/llxprt-code-settings';
+import {
+  getSettingSpec,
+  validateSetting,
+} from '@vybestack/llxprt-code-settings';
 
 const EPHEMERAL_DEFAULTS = {
   compressionThreshold: 0.85,
@@ -123,6 +127,30 @@ function resolveProviderContextLimit(
   }
 }
 
+function resolveSemanticMediaPurgeSetting(
+  getLiveSetting: ReturnType<typeof createGetLiveSetting>,
+  options: AgentRuntimeContextFactoryOptions,
+): 'off' | 'remove' | 'summary' {
+  const value = getLiveSetting<unknown>(
+    'media.semantic-purge',
+    options.settings['media.semantic-purge'],
+  );
+  const validation = validateSetting('media.semantic-purge', value ?? 'off');
+  if (!validation.success) {
+    throw new Error(
+      "Invalid media.semantic-purge setting: expected 'off', 'remove', or 'summary'",
+    );
+  }
+  if (
+    validation.value === 'off' ||
+    validation.value === 'remove' ||
+    validation.value === 'summary'
+  ) {
+    return validation.value;
+  }
+  throw new Error('Semantic media purge validator returned an invalid value');
+}
+
 /**
  * Build compression-related ephemeral accessors.
  */
@@ -188,6 +216,8 @@ function buildCompressionEphemerals(
       );
       return typeof value === 'boolean' ? value : false;
     },
+    semanticMediaPurge: (): 'off' | 'remove' | 'summary' =>
+      resolveSemanticMediaPurgeSetting(getLiveSetting, options),
   };
 }
 
@@ -328,6 +358,9 @@ export function createAgentRuntimeContext(
   validateRequiredOptions(options);
 
   const history = options.history ?? new HistoryService();
+  if (options.mediaStore !== undefined) {
+    history.registerMediaOwner(new HistoryMediaOwnership(options.mediaStore));
+  }
 
   const getLiveSetting = createGetLiveSetting(options);
 
@@ -351,6 +384,15 @@ export function createAgentRuntimeContext(
     provider: options.provider,
     tools: options.tools,
     providerRuntime,
+    ...(options.mediaStore === undefined
+      ? {}
+      : { mediaStore: options.mediaStore }),
+    ...(options.mediaAdmission === undefined
+      ? {}
+      : { mediaAdmission: options.mediaAdmission }),
+    ...(options.mediaResolver === undefined
+      ? {}
+      : { mediaResolver: options.mediaResolver }),
   };
 
   return Object.freeze(context);

package/src/runtime/providerRuntimeContext.ts

@@ -20,6 +20,19 @@
  */
 import type { Config } from '../config/config.js';
 import { MissingRuntimeProviderError } from './errors/MissingRuntimeProviderError.js';
+import type { RequestMediaResolutionService } from '../storage/request-media-resolver.js';
+import type { ProviderFileReferenceMetadata } from '../services/history/IContent.js';
+
+export interface ProviderFileBindingStore {
+  bind(
+    contentId: string,
+    reference: ProviderFileReferenceMetadata,
+  ): Promise<void>;
+  unbind(
+    contentId: string,
+    reference: ProviderFileReferenceMetadata,
+  ): Promise<void>;
+}
 
 export interface RuntimeSettingsState {
   get(key: string): unknown;
@@ -48,6 +61,9 @@ export interface ProviderRuntimeContext {
   config?: Config;
   runtimeId?: string;
   metadata?: Record<string, unknown>;
+  mediaResolver?: RequestMediaResolutionService;
+  requestMediaBudgetBytes?: number;
+  providerFileBindings?: ProviderFileBindingStore;
 }
 
 let activeContext: ProviderRuntimeContext | null = null;
@@ -63,6 +79,9 @@ export interface ProviderRuntimeContextInit {
   config?: Config;
   runtimeId?: string;
   metadata?: Record<string, unknown>;
+  mediaResolver?: RequestMediaResolutionService;
+  requestMediaBudgetBytes?: number;
+  providerFileBindings?: ProviderFileBindingStore;
 }
 
 /**
@@ -112,6 +131,9 @@ export function createProviderRuntimeContext(
     config: init.config,
     runtimeId: init.runtimeId,
     metadata: init.metadata,
+    mediaResolver: init.mediaResolver,
+    requestMediaBudgetBytes: init.requestMediaBudgetBytes,
+    providerFileBindings: init.providerFileBindings,
   };
 }
 

package/src/runtime/runtimeAdapters.ts

@@ -91,8 +91,8 @@ export function createTelemetryAdapterFromConfig(
         event.usageMetadata ??
         (event.usage !== undefined
           ? {
-              promptTokenCount: event.usage.inputTokens,
-              candidatesTokenCount: event.usage.outputTokens,
+              inputTokenCount: event.usage.inputTokens,
+              outputTokenCount: event.usage.outputTokens,
               totalTokenCount: event.usage.totalTokens,
             }
           : undefined);

package/src/services/history/ContentConverters.ts

@@ -114,14 +114,18 @@ export class ContentConverters {
   }
 
   /**
-   * Canonical Gemini-shaped encoding of a failed tool response (issue #3076).
+   * Gemini-shaped encoding of a failed tool response (issue #3076).
    *
-   * The only live consumer of this outbound encoding is the Google code-assist
-   * request path (contentGeneratorAdapters). The matching inbound decoder
-   * exists so the Gemini-shaped representation stays symmetric and lossless as
-   * #3076 requires; it has no other live consumer today. The part carries the
-   * `llxprtToolFailure` flag so a successful tool whose result merely happens
-   * to be shaped like `{ status: 'error', ... }` is never misdecoded.
+   * ContentConverters is the hook-wire converter: hook responses arrive as
+   * Gemini-shaped parts and are decoded to IContent via toIContent, while
+   * history writes encode symmetrically back. This outbound encoding turns a
+   * `tool_response` into that Gemini `functionResponse` shape so an
+   * IContent → Gemini → IContent round trip restores the failure verbatim. The
+   * matching inbound decoder (decodeFailureEnvelope) exists so the Gemini-shaped
+   * representation stays symmetric and lossless as #3076 requires. The part
+   * carries the `llxprtToolFailure` flag so a successful tool whose result
+   * merely happens to be shaped like `{ status: 'error', ... }` is never
+   * misdecoded.
    *
    * The legacy representation carries `callId`, `toolName`, `result` and the
    * `error` marker and nothing else: `isComplete` and `providerMetadata` are