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

package/dist/session.d.ts

@@ -13,12 +13,23 @@
  * colony children, but new chat and mux artifacts stay out of the git worktree.
  */
 import type { Message } from './types.js';
-import type { MuxSessionState } from './ui/ratatui/protocol.js';
+import type { PaneLabels, MuxSessionState } from './ui/ratatui/protocol.js';
 import type { PaneSessionSpec } from './panes/types.js';
 import type { GoalRecord } from './agent/commands/goal.js';
 import type { HostedSessionSettings } from './hosted/session_settings.js';
 import type { ToolResponseStore } from './agent/tool_response_store.js';
+import { type EvidenceSnapshot } from './agent/runtime/evidence.js';
+import { type DiagnosticSnapshot } from './diagnostics/session_export.js';
+import { type UsageSnapshot } from './usage_snapshot.js';
+import { type TaskHandoffInput, type TaskHandoffProjection, type TaskHandoffSnapshot } from './session_handoff_contract.js';
+import { type BoardSessionBinding } from './board/binding.js';
 export interface SessionMetadata {
+    environment?: {
+        id: string;
+        name: string;
+    } | null;
+    authMode?: 'auto' | 'direct' | 'zrouter';
+    routerOrigin?: string;
     id: string;
     projectHash: string;
     cwd: string;
@@ -30,8 +41,8 @@ export interface SessionMetadata {
     updatedAt: string;
     messageCount: number;
     /**
-     * Auto-derived from the first user message. Updated on every save.
-     * Treat as a preview; user-facing surfaces should prefer `name` when set.
+     * Derived from the first real user message and retained across compaction.
+     * User-facing surfaces should prefer `name` when set.
      */
     title?: string;
     /**
@@ -42,6 +53,7 @@ export interface SessionMetadata {
      * `title` for tab/border display.
      */
     name?: string;
+    labels?: Omit<PaneLabels, 'manual_title'>;
     mode?: string;
     planFile?: string | null;
     artifactPath?: string | null;
@@ -49,6 +61,19 @@ export interface SessionMetadata {
     goal?: GoalRecord | null;
 }
 export interface SessionRuntimeState {
+    /** Match the host's memory-only tool response policy when not using env config. */
+    ephemeralToolNames?: readonly string[];
+    ephemeralToolRules?: readonly import('./utils/ephemeral_tools.js').EphemeralToolRule[];
+    environment?: {
+        id: string;
+        name: string;
+    } | null;
+    taskHandoffInput?: TaskHandoffInput;
+    evidence?: EvidenceSnapshot;
+    diagnostics?: DiagnosticSnapshot;
+    usage?: UsageSnapshot;
+    authMode?: 'auto' | 'direct' | 'zrouter';
+    routerOrigin?: string;
     mode?: string;
     planFile?: string | null;
     artifactPath?: string | null;
@@ -66,6 +91,12 @@ export declare const SESSION_SCHEMA_VERSION = 1;
 /** Shared guard for latency-sensitive session reads such as launch and navigator previews. */
 export declare const MAX_SESSION_FILE_BYTES: number;
 export interface Session {
+    /** One explicit terminal task/card association, not a second task store. */
+    board_binding?: BoardSessionBinding;
+    task_handoff?: TaskHandoffSnapshot;
+    evidence?: EvidenceSnapshot;
+    diagnostics?: DiagnosticSnapshot;
+    usage?: UsageSnapshot;
     schemaVersion?: number;
     metadata: SessionMetadata;
     messages: Message[];
@@ -78,10 +109,10 @@ export interface Session {
  * Raised by loadSessionFromFile when a file exists but cannot be used.
  */
 export declare class SessionLoadError extends Error {
-    readonly reason: 'unreadable' | 'invalid-json' | 'invalid-shape' | 'schema-mismatch';
+    readonly reason: 'unreadable' | 'invalid-json' | 'invalid-shape' | 'schema-mismatch' | 'handoff-invalid' | 'handoff-source-mismatch' | 'handoff-schema-mismatch' | 'diagnostics-invalid' | 'usage-invalid' | 'board-binding-invalid';
     readonly path: string;
     readonly cause?: unknown | undefined;
-    constructor(message: string, reason: 'unreadable' | 'invalid-json' | 'invalid-shape' | 'schema-mismatch', path: string, cause?: unknown | undefined);
+    constructor(message: string, reason: 'unreadable' | 'invalid-json' | 'invalid-shape' | 'schema-mismatch' | 'handoff-invalid' | 'handoff-source-mismatch' | 'handoff-schema-mismatch' | 'diagnostics-invalid' | 'usage-invalid' | 'board-binding-invalid', path: string, cause?: unknown | undefined);
 }
 export interface SessionSummary {
     id: string;
@@ -89,6 +120,7 @@ export interface SessionSummary {
     title: string;
     /** User-set name; undefined when the session has not been /rename'd. */
     name?: string;
+    labels?: Omit<PaneLabels, 'manual_title'>;
     messageCount: number;
     updatedAt: string;
 }
@@ -111,6 +143,8 @@ export declare function ensureSessionSelector(args: string[], sessionId: string)
 export declare function getSessionDir(projectHash: string, sessionId: string): string;
 /** Tool response directory for a single global session. */
 export declare function getToolResponsesDir(projectHash: string, sessionId: string): string;
+/** Compare-and-set the association without rewriting captured chat/media state. */
+export declare function updateSessionBoardBinding(path: string, sessionId: string, expected: BoardSessionBinding | undefined, next: BoardSessionBinding | undefined): Promise<void>;
 export interface RecentSessionLookupOptions {
     excludeSessionId?: string;
     maxFileBytes?: number;
@@ -121,6 +155,19 @@ export interface RecentSessionLookupOptions {
  * are skipped, and parsing stops as soon as a useful summary is found.
  */
 export declare function findRecentSessionSummary(cwd: string, options?: RecentSessionLookupOptions): Promise<SessionSummary | undefined>;
+export interface SessionHandoffLookupOptions {
+    excludeSessionId?: string;
+    /** Hard cap on complete session payloads read; at most sixteen per lookup. */
+    maxCandidates?: number;
+}
+/**
+ * Inspect a bounded same-project window and offer exact, validated checkpoints.
+ * Metadata inspection is bounded to 128 heads and, for canonical alias recovery,
+ * 128 project directories. File mtime orders the selected window; checkpoint
+ * as-of and session ID determine offer ordering. This is not a complete history
+ * search. Selection never imports a task or asserts liveness.
+ */
+export declare function findSessionHandoffOffers(cwd: string, options?: SessionHandoffLookupOptions): Promise<TaskHandoffProjection[]>;
 export declare function getSessionDirForCwd(cwd: string): string;
 export declare function getSessionPathForCwd(cwd: string, sessionId: string): string;
 export declare function getMuxStatePathForCwd(cwd: string, sessionId: string): string | null;
@@ -135,20 +182,17 @@ export declare function bindToolResponseStoreToSession(store: ToolResponseStore,
     inlineAgeTurns: number;
     toolCompression?: 'off' | 'safe' | 'aggressive';
 }, sessionFile?: string): Promise<void>;
-export declare function saveSession(sessionId: string, cwd: string, messages: Message[], model: string, provider: string, muxState?: MuxSessionState, paneSpecs?: PaneSessionSpec[], runtimeState?: SessionRuntimeState, hostedSettings?: HostedSessionSettings): Promise<string>;
+export declare function saveSession(sessionId: string, cwd: string, messages: Message[], model: string, provider: string, muxState?: MuxSessionState, paneSpecs?: PaneSessionSpec[], runtimeState?: SessionRuntimeState, hostedSettings?: HostedSessionSettings, signal?: AbortSignal): Promise<string>;
 /**
  * Load a global session from disk. Handles legacy flat-file migration.
  */
 export declare function loadSession(projectHash: string, sessionId: string): Promise<Session | null>;
-/**
- * Load a session from an arbitrary file path (bypasses the ~/.ztc/sessions tree).
- * Used by embedders that manage session storage themselves.
- */
-export declare function loadSessionFromFile(path: string): Promise<Session | null>;
+/** Load a managed session or an arbitrary file owned by an embedder. */
+export declare function loadSessionFromFile(path: string, retain?: boolean): Promise<Session | null>;
 /**
  * Save a session to an arbitrary file path (bypasses the ~/.ztc/sessions tree).
  */
-export declare function saveSessionToFile(path: string, sessionId: string, cwd: string, messages: Message[], model: string, provider: string, muxState?: MuxSessionState, paneSpecs?: PaneSessionSpec[], runtimeState?: SessionRuntimeState, hostedSettings?: HostedSessionSettings): Promise<string>;
+export declare function saveSessionToFile(path: string, sessionId: string, cwd: string, messages: Message[], model: string, provider: string, muxState?: MuxSessionState, paneSpecs?: PaneSessionSpec[], runtimeState?: SessionRuntimeState, hostedSettings?: HostedSessionSettings, signal?: AbortSignal): Promise<string>;
 export declare function saveMuxStateOnly(sessionId: string, cwd: string, muxState: MuxSessionState): Promise<boolean>;
 export declare function loadMostRecentSession(cwd: string): Promise<Session | null>;
 export declare function loadSessionById(sessionId: string, cwd?: string): Promise<Session | null>;
@@ -183,6 +227,11 @@ export declare function setSessionName(sessionId: string, cwd: string, name: str
     model: string;
     provider: string;
 }): Promise<Session | null>;
+/** Atomically persist label choices; metadata.name remains the resume-name owner. */
+export declare function setSessionLabels(sessionId: string, cwd: string, labels: PaneLabels, defaults: {
+    model: string;
+    provider: string;
+}): Promise<Session>;
 /**
  * List all sessions for a project
  */
@@ -210,4 +259,7 @@ export declare function listWorkspaceSessions(cwd: string, options?: SessionCata
  * sessions are excluded — they are only addressable from their own worktree.
  */
 export declare function listAllSessions(options?: SessionCatalogOptions): Promise<SessionCatalogEntry[]>;
-export declare function cleanupOldSessions(cwd: string, keepCount?: number): Promise<number>;
+/** Protect the current session even before its first save. */
+export declare function retainCurrentSession(cwd: string, sessionId: string): Promise<void>;
+/** Opt-in retention of unowned, unnamed sessions; null disables pruning. */
+export declare function cleanupOldSessions(cwd: string, keepCount?: number | null): Promise<number>;