@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/tool_response_store.d.ts

@@ -1,15 +1,43 @@
 /**
  * ToolResponseStore — disk-backed store for tool results.
  *
- * Every tool result is written to
- *   ~/.ztc/sessions/{projectHash}/{sessionId}/tool_responses/{tool_use_id}.json
+ * Non-ephemeral tool results are written to
+ *   ~/.ztc/sessions/{projectHash}/{sessionId}/tool_responses/{bounded source filename}.json
  * The conversation thread keeps a small placeholder for large/old results and
  * inlines the full text only when the request-level inline budget allows it.
  * Mirror SSE events carry the full content from the agent's `tool_end`
  * emission, so UX is untouched — the store only governs what appears in the
- * model's context.
+ * model's context. Explicit host-selected ephemeral tools remain memory-only;
+ * their durable evidence contains a placeholder rather than the private body.
  */
+import { type EphemeralToolRule } from '../utils/ephemeral_tools.js';
 import { type ToolCompressionMode } from './tool_compression.js';
+import { type ToolResponseDirectoryAdmission } from './tool_response_directory.js';
+import { EvidenceLedger, type EvidenceAvailability, type EvidenceSource } from './runtime/evidence.js';
+export interface ToolResponseChunkOptions {
+    cursor?: number;
+    maxBytes?: number;
+}
+export declare const TOOL_RESPONSE_MAX_STORED_RESPONSES = 128;
+export declare const TOOL_RESPONSE_MAX_STORED_BYTES: number;
+export interface ToolResponseRetentionOptions {
+    maxStoredResponses: number;
+    maxStoredBytes: number;
+}
+export interface ToolResponseChunk {
+    toolUseId: string;
+    observationId: string;
+    content: string;
+    cursor: number;
+    nextCursor: number;
+    totalBytes: number;
+    sha256: string;
+    complete: boolean;
+    availability: EvidenceAvailability;
+}
+export declare class ToolResponseIntegrityError extends Error {
+    constructor(message: string);
+}
 export declare const INLINE_SIZE_THRESHOLD_TOKENS_DEFAULT = 2000;
 export declare const INLINE_AGE_TURNS_DEFAULT = 8;
 export declare const CONFIGURED_INLINE_BUDGET_TOKENS_DEFAULT: number;
@@ -18,6 +46,7 @@ export interface PlaceholderPreview {
     tail: string;
 }
 export interface ToolResponseMeta {
+    ephemeral?: boolean;
     tool_name: string;
     tool_use_id: string;
     size_tokens: number;
@@ -27,10 +56,16 @@ export interface ToolResponseMeta {
     is_error?: boolean;
     source_path?: string;
     content_hash?: string;
+    /** Full immutable source identity, separate from the compression dedup hash. */
+    result_sha256?: string;
+    observation_id?: string;
     recalledAtTurn?: number;
     preview?: PlaceholderPreview | null;
 }
 export interface ToolResponseStoreConfig {
+    /** Host-selected exact tool names whose raw results must remain memory-only. */
+    ephemeralToolNames?: readonly string[];
+    ephemeralToolRules?: readonly EphemeralToolRule[];
     offloadEnabled: boolean;
     inlineSizeThresholdTokens: number;
     inlineAgeTurns: number;
@@ -55,6 +90,7 @@ export declare function describeOffloadPlaceholderFormat(): string;
  */
 export declare function isPreviewSafe(content: string): boolean;
 export declare class ToolResponseStore {
+    readonly evidence: EvidenceLedger;
     private dir;
     private config;
     private meta;
@@ -62,9 +98,29 @@ export declare class ToolResponseStore {
     private totalCachedTokens;
     private turnCounter;
     private pendingWrites;
+    private persistenceError;
+    private failedSourceWrites;
+    private persistenceRecovery;
+    private loadingEvidence;
+    private generation;
+    private indexDirty;
+    private indexWrite;
+    private readonly availability;
+    private readonly invalidSources;
+    private readonly retention;
+    private readonly retainedSources;
+    private directoryAdmission;
+    private retentionQueue;
     private lastRenderInline;
     private renderMemo;
     private compressionStats;
+    constructor(retention?: Partial<ToolResponseRetentionOptions>);
+    private retentionVictim;
+    private forgetSource;
+    private overRetentionLimit;
+    private enforceRetention;
+    private boundMemoryCache;
+    private scheduleEvidenceWrite;
     setConfig(cfg: Partial<ToolResponseStoreConfig>): void;
     getConfig(): ToolResponseStoreConfig;
     /**
@@ -72,7 +128,7 @@ export declare class ToolResponseStore {
      * fraction of the active model's context window so a small-context model
      * (gpt-4 8k → 2k effective) doesn't get crushed by a Claude-tuned default.
      */
-    effectiveBudget(model: string): number;
+    effectiveBudget(model: string, windowOverride?: number | null): number;
     private cacheBudgetTokens;
     /**
      * Swap to a new session directory. Preloads only `meta` from each record
@@ -83,6 +139,8 @@ export declare class ToolResponseStore {
     setSessionDir(dir: string): Promise<void>;
     clear(): void;
     hasSession(): boolean;
+    /** A bounded discovery result never claims that unseen historical files are absent. */
+    getDirectoryAdmission(): ToolResponseDirectoryAdmission;
     /** True when the content for `toolUseId` is currently in the in-memory cache. */
     hasCached(toolUseId: string): boolean;
     /**
@@ -91,21 +149,34 @@ export declare class ToolResponseStore {
      * also used by tests that need to observe a settled filesystem.
      */
     flush(): Promise<void>;
+    private awaitWrites;
+    private rememberFailedSource;
+    /** Retry stored bytes and the evidence index, never the producing tool. */
+    private recoverPersistence;
+    private scheduleSourceWrite;
     /**
      * Persist a tool result and return the text to inject into context (full
      * content if small, placeholder if over the size cap). Disk write is
      * fire-and-forget.
      */
     put(toolUseId: string, toolName: string, content: string, partial?: boolean, context?: {
+        args?: Record<string, unknown>;
         sourcePath?: string | null;
         dedupable?: boolean;
         isError?: boolean;
+        observationId?: string;
+        source?: EvidenceSource;
     }): {
         meta: ToolResponseMeta;
         rendered: string;
     };
     /** Load the full content for a tool_use_id. Returns null if missing. */
     get(toolUseId: string): Promise<string | null>;
+    getChunk(toolUseId: string, options?: ToolResponseChunkOptions): Promise<ToolResponseChunk | null>;
+    private markInvalid;
+    private readSource;
+    private decodeRecord;
+    private admitLoadedRecord;
     private cacheContent;
     getMeta(toolUseId: string): ToolResponseMeta | undefined;
     /**