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

package/dist/agent/agent.d.ts

@@ -1,20 +1,36 @@
 import { Message, ToolCall, AgentEvent } from '../types.js';
-import { AgentBackend, BackendRequest, TokenUsage } from './backends/index.js';
+import type { ModelUsageObserver } from '../types.js';
+import { type TaskHandoffProjection } from '../session_handoff_contract.js';
+import { AgentBackend, BackendRequest, ContentBlock, TokenUsage } from './backends/index.js';
 import type { ClientToolCallResult } from './backends/types.js';
+import { type UsageSnapshot } from '../usage_snapshot.js';
 import type { ApiRetrySettings } from '../config/types.js';
 import { type ExecutionSettings } from '../config/execution.js';
 import { type ExecutionContext } from './runtime/execution_context.js';
 import { Policy } from './runtime/policy.js';
 import { Tracer } from './runtime/tracing.js';
+import { type DiagnosticEventKind, type DiagnosticJsonObject, type DiagnosticSnapshot } from '../diagnostics/session_export.js';
 import type { Tool } from './tools/types.js';
 import { ToolResponseStore } from './tool_response_store.js';
+import { type EvidenceSnapshot } from './runtime/evidence.js';
 import type { HostApprovalContext } from './runtime/tool_runtime.js';
 import { ToolCapability } from './runtime/capabilities.js';
 import { HookDispatcher } from '../hooks/dispatcher.js';
 import type { HookApprovalRequester } from '../hooks/types.js';
-import type { ToolEffectObserver } from './runtime/tool_effects.js';
+import type { ToolEffectObserver, LocalFileChangeObserver } from './runtime/tool_effects.js';
+import type { ToolCheckpointHandler } from './runtime/tool_checkpoints.js';
 import type { ConversationDriver, ConversationTurn } from '../host/index.js';
+/** The supplied correction source is part of this standalone turn's ordered history. */
+export interface SteeringAdmissionCheckpoint {
+    messages: readonly Message[];
+    sourceMessageIds: readonly string[];
+    /** A native fallback retains uncertainty about its original steering delivery. */
+    deliveryState?: 'unknown' | 'delivered';
+    signal?: AbortSignal;
+}
+export type SteeringAdmissionCheckpointHandler = (checkpoint: SteeringAdmissionCheckpoint) => Promise<void>;
 export interface AgentConfig {
+    remoteResourceSession?: import('./runtime/remote_resources.js').RemoteResourceSession;
     model?: string;
     apiKey?: string;
     /** Prevent ambient provider-key fallback for credential-brokered hosts. */
@@ -31,10 +47,12 @@ export interface AgentConfig {
     execution?: ExecutionSettings;
     sessionId?: string;
     runtimeFacts?: {
+        provider?: string;
         mode?: string;
         mux?: boolean;
         configScope?: string;
         outputLimitSource?: string;
+        permissions?: import('../config/permissions.js').PermissionPolicySnapshot;
     };
     /**
      * Retry/timeout policy for LLM requests. Renderer hosts normally leave this
@@ -76,8 +94,14 @@ export interface AgentConfig {
      * stripped. Undefined preserves the legacy inherited environment.
      */
     subprocessEnv?: Readonly<Record<string, string>>;
+    commandPolicy?: import('../utils/sandbox.js').SandboxCommandOptions;
     /** Host callback fired after approval and immediately before each tool runs. */
     toolEffectObserver?: ToolEffectObserver;
+    onLocalFileChange?: LocalFileChangeObserver;
+    /** Persist canonical call intent and terminal observations before proceeding. */
+    toolCheckpoint?: ToolCheckpointHandler;
+    /** Host-owned source store for Agent replacement in one durable session. */
+    toolResponseStore?: ToolResponseStore;
     /** Host-owned cloud conversation lifecycle for each terminal turn. */
     conversationBinding?: AgentConversationBinding;
     hooks?: HookDispatcher;
@@ -117,6 +141,9 @@ export interface AgentRunResult {
     usage?: TokenUsage;
     stopReason: 'complete' | 'interactive' | 'max_iterations';
     reasoning?: string;
+    nativeContent?: ContentBlock[];
+    nativeModel?: string;
+    nativeContextId?: string;
     /** Ordered model-facing messages produced during every turn. */
     turnMessages?: Message[];
 }
@@ -128,6 +155,7 @@ export interface HarnessToolCallOptions {
     callId?: string;
     signal?: AbortSignal;
     onActivity?: () => void;
+    onUsage?: ModelUsageObserver;
 }
 export declare class AgentError extends Error {
     code?: string | undefined;
@@ -152,6 +180,8 @@ export declare class Agent {
     private backend;
     private policy;
     private tracer;
+    private diagnostics;
+    private usageSnapshot;
     private streamChunkSize;
     /**
      * True when the last callAPI() consumed the backend's generateStream and
@@ -165,8 +195,34 @@ export declare class Agent {
     /** Auto-continues spent since the last tool run; reset per turn and per tool. */
     private _consecutiveAutoContinues;
     private readonly _subprocessEnv?;
+    private readonly commandPolicy?;
     private readonly toolEffectObserver?;
+    private readonly onLocalFileChange?;
+    private readonly toolCheckpoint?;
+    private toolCheckpointTail;
+    private toolCheckpointFailure;
+    private failedToolCheckpoint;
+    private nativeEvidencePending;
+    private nativeEvidenceFailure;
+    private nativeEvidenceCaptureDepth;
+    private readonly recordedToolCalls;
+    private readonly remoteResourceSession?;
     readonly toolResponseStore: ToolResponseStore;
+    private readonly evidenceUnsubscribe;
+    getEvidenceSnapshot(): EvidenceSnapshot;
+    getDiagnosticSessionId(): string;
+    getUsageSessionId(): string;
+    getUsageSnapshot(): UsageSnapshot;
+    restoreUsageSnapshot(snapshot: UsageSnapshot): void;
+    private retainUsageReceipt;
+    getDiagnosticSnapshot(): DiagnosticSnapshot;
+    restoreDiagnosticSnapshot(snapshot: DiagnosticSnapshot): void;
+    recordDiagnosticEvent(kind: DiagnosticEventKind, data: DiagnosticJsonObject): void;
+    /** Persist only factual API metadata, never prompts, credentials, or raw response bodies. */
+    private captureDiagnosticTrace;
+    private toolTraceData;
+    /** Fresh applicability is a projection; original process/source observations remain immutable. */
+    refreshVerificationCoverage(): Promise<void>;
     readonly discoveredTools: Set<string>;
     readonly alwaysLoadedToolNames: Set<string>;
     private hooks?;
@@ -200,10 +256,12 @@ export declare class Agent {
     private getDefaultSystemPrompt;
     on(handler: EventHandler): () => void;
     private emit;
+    private toolOutputObserver;
     private nextToolEventId;
     private _selectorVerdict;
     private _currentRequestToolIds;
     private _currentTransientOverageTokens;
+    private _nativeContextId?;
     private formatMessages;
     private _encodeDeps;
     private contentLength;
@@ -251,6 +309,9 @@ export declare class Agent {
      * genuinely multi-task long-lived agents is deferred (plan A10).
      */
     private _taskHeader;
+    private taskHandoff;
+    /** Only a host-selected checkpoint may supply historical task context. */
+    setTaskHandoff(projection: TaskHandoffProjection | null): void;
     /**
      * Drop the explicitly pinned task for the next conversation. Wired into the /clear-only path (clearTransientState), never into
      * /compact — the pin must survive compaction (that is the whole point of R7).
@@ -273,12 +334,12 @@ export declare class Agent {
     /** Append the pinned task header (R7) to the static system prompt. */
     getExecutionContext(): ExecutionContext;
     private systemWithTaskHeader;
-    /**
-     * Execute one terminal turn. A host binding makes the remote conversation the
-     * authoritative history and mirrors the accepted user/assistant pair around
-     * the same core loop used by unhosted ZTC.
-     */
-    run(messages: Message[], signal?: AbortSignal, takeSteering?: () => Message[]): Promise<AgentRunResult>;
+    private persistToolCheckpoint;
+    private checkpointPersistenceError;
+    /** Retry persistence only, before a new public invocation can admit effects. */
+    private recoverToolCheckpoint;
+    /** Execute a host-bound or standalone turn through the same core loop. */
+    run(messages: Message[], signal?: AbortSignal, takeSteering?: () => Message[], toolCheckpoint?: ToolCheckpointHandler | undefined, steeringAdmission?: SteeringAdmissionCheckpointHandler, onUsage?: ModelUsageObserver): Promise<AgentRunResult>;
     private runBound;
     private runCore;
     /**
@@ -297,6 +358,11 @@ export declare class Agent {
      * approval requester, tool-response store, and mirror-visible tool events.
      */
     executeHarnessToolCall(name: string, args: Record<string, unknown>, options?: HarnessToolCallOptions): Promise<HarnessToolCallResult>;
+    private recordedToolCall;
+    private hasStoredToolIdentity;
+    private executeHarnessToolCallWithCheckpoint;
+    private captureUserInstructions;
+    private evidenceSource;
     private callAPI;
     private parseAPIError;
 }