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

package/dist/diagnostics/session_evidence_package.d.ts

@@ -0,0 +1,40 @@
+import { type EvidenceSnapshot } from '../agent/runtime/evidence.js';
+import { type TaskHandoffProjection } from '../session_handoff_contract.js';
+import type { Message } from '../types.js';
+import { type DiagnosticSnapshot } from './session_export.js';
+export interface SessionEvidencePackageInput {
+    sessionId?: string | null;
+    messages: readonly Message[];
+    diagnostics?: DiagnosticSnapshot;
+    evidence?: EvidenceSnapshot;
+    taskHandoff?: TaskHandoffProjection | null;
+}
+export interface SessionEvidencePackageSource {
+    sessionId: string | null;
+    asOf: string | null;
+    evidenceRevision: number | null;
+    handoffRevision: number | null;
+    taskId: string | null;
+}
+export interface SessionEvidencePackageEntry {
+    path: string;
+    content: string;
+}
+export interface SessionEvidencePackageManifestEntry {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface SessionEvidencePackage {
+    schemaVersion: 1;
+    packageId: string;
+    source: SessionEvidencePackageSource;
+    indexMarkdown: string;
+    entries: SessionEvidencePackageEntry[];
+    manifest: SessionEvidencePackageManifestEntry[];
+}
+export declare const SESSION_EVIDENCE_INDEX_MAX_BYTES: number;
+/** Capture/validate once, then redact the combined credential context before deriving entries or hashes. */
+export declare function buildSessionEvidencePackage(input: SessionEvidencePackageInput): SessionEvidencePackage;
+/** Save to a new explicit file. Existing files, directories and symlinks are never overwritten. */
+export declare function saveSessionEvidencePackage(pkg: SessionEvidencePackage, path: string): Promise<void>;

package/dist/diagnostics/session_evidence_package.js

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, unlink } from 'node:fs/promises';
+import { parseEvidenceSnapshot } from '../agent/runtime/evidence.js';
+import { parseTaskHandoffProjection } from '../session_handoff_contract.js';
+import { buildSessionDiagnosticDocument, exportSessionDiagnostics, formatSessionDiagnosticsMarkdown, parseDiagnosticSnapshot, redactDiagnosticValue } from './session_export.js';
+export const SESSION_EVIDENCE_INDEX_MAX_BYTES = 32 * 1024;
+const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+const bytes = (text) => Buffer.byteLength(text, 'utf8');
+const json = (value) => JSON.stringify(value, null, 2) + '\n';
+const shown = (value) => value === null || value === undefined ? 'unknown' : JSON.stringify(value);
+function dateText(value, label) {
+    if (value === undefined)
+        return undefined;
+    // Public loaded checkpoints retain ISO strings; live messages use Date.
+    const date = value instanceof Date ? value : typeof value === 'string' ? new Date(value) : null;
+    if (date === null || !Number.isFinite(date.getTime()))
+        throw new TypeError(`Invalid ${label} timestamp in captured checkpoint`);
+    return date.toISOString();
+}
+/** Only declared Message timestamps are converted; arbitrary non-JSON values are rejected. */
+function messageJson(message) {
+    return { ...message, timestamp: dateText(message.timestamp, 'message'),
+        ...(message.toolCalls === undefined ? {} : { toolCalls: message.toolCalls.map(call => ({ ...call,
+                ...(call.startedAt === undefined ? {} : { startedAt: dateText(call.startedAt, 'tool start') }),
+                ...(call.completedAt === undefined ? {} : { completedAt: dateText(call.completedAt, 'tool completion') }),
+            })) }) };
+}
+function plainJson(value, ancestors = new Set(), depth = 0) {
+    if (depth > 32)
+        throw new TypeError('Captured checkpoint JSON is excessively deep');
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'object' || ancestors.has(value))
+        throw new TypeError('Invalid or cyclic captured checkpoint JSON');
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+        throw new TypeError('Invalid non-JSON captured checkpoint value');
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map(item => plainJson(item, ancestors, depth + 1));
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            // Optional typed fields can be absent; undefined array elements and all
+            // other non-JSON values remain invalid rather than fabricated facts.
+            if (item !== undefined)
+                Object.defineProperty(result, key, { enumerable: true, value: plainJson(item, ancestors, depth + 1) });
+        }
+        return result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function utf8Prefix(text, maximum) {
+    const buffer = Buffer.from(text, 'utf8');
+    if (buffer.length <= maximum)
+        return text;
+    let end = maximum;
+    while (end > 0 && (buffer[end] & 0xc0) === 0x80)
+        end--;
+    return buffer.subarray(0, end).toString('utf8');
+}
+function boundedIndex(rows) {
+    const selected = [];
+    let size = 0;
+    let omittedRows = 0;
+    let omittedBytes = 0;
+    for (const row of rows) {
+        const length = bytes(row + '\n');
+        if (size + length > SESSION_EVIDENCE_INDEX_MAX_BYTES - 256) {
+            omittedRows++;
+            omittedBytes += length;
+            continue;
+        }
+        selected.push(row);
+        size += length;
+    }
+    selected.push(`\nIndex omissions: ${omittedRows} rows / ${omittedBytes} UTF-8 bytes. Fixed package entries retain the exported source data; omitted or unavailable originals cannot be retrieved from a digest alone.`);
+    return selected.join('\n') + '\n';
+}
+function excerpt(text) {
+    const prefix = utf8Prefix(text, 2048);
+    return JSON.stringify(prefix) + (prefix === text ? '' : ` (index excerpt omits ${bytes(text) - bytes(prefix)} bytes)`);
+}
+function indexFor(source, input) {
+    const document = buildSessionDiagnosticDocument(input);
+    const evidence = input.evidence;
+    const handoff = input.taskHandoff;
+    const rows = ['# ZTC evidence package (v1)', '',
+        'Retained checkpoint only. This captured, possibly incomplete view does not prove verified completion. Sharing does not collect new evidence or change execution.',
+        `Session: ${shown(source.sessionId)}; as-of: ${shown(source.asOf)}. Owner liveness and current/final task completion are unknown.`,
+        `Evidence revision: ${source.evidenceRevision ?? 'unknown'}; handoff revision: ${source.handoffRevision ?? 'unknown'}; task ID: ${shown(source.taskId)}.`,
+        'Known credential fields and common token formats are redacted in exported values. Original source/receipt digests are recorded claims, distinct from manifest hashes of redacted exported bytes.',
+        '', '## Task checkpoint'];
+    if (handoff) {
+        const task = handoff.snapshot;
+        rows.push(`Objective (${task.objective.kind}; retained source ${shown(task.objective.sourceMessageId ?? task.objective.goalId)}; ${task.objective.sourceAvailability}): ${excerpt(task.objective.text)}`, `Task status: ${task.taskStatus} (checkpoint-reported, not a verification verdict). Provenance: ${handoff.provenance}; owner liveness: ${handoff.ownerLiveness}.`, `Source captured at: ${shown(task.source.capturedAt)}; original messages SHA256: ${task.source.messagesSha256}; original evidence SHA256: ${task.source.evidenceSha256}.`, `Next action: ${task.nextAction.text === null ? 'unavailable' : excerpt(task.nextAction.text)}; availability: ${task.nextAction.availability}; source: ${shown(task.nextAction.sourceMessageId)}.`);
+        for (const correction of task.corrections)
+            rows.push(`- Correction ${shown(correction.id)}: ${correction.deliveryState}; source ${shown(correction.sourceMessageId)}; ${excerpt(correction.text)}.`);
+        for (const observation of task.completedObservations)
+            rows.push(`- Retained process observation ${shown(observation.observationId)}: ${observation.status}; tool ${shown(observation.toolCallId)}; job ${shown(observation.jobId)}; exit ${observation.exitCode ?? 'unknown'}; verification ${observation.verification}.`);
+        for (const call of task.unresolvedCalls)
+            rows.push(`- Unresolved tool ${shown(call.toolCallId)} (${shown(call.name)}): outcome unknown; source ${shown(call.sourceMessageId)}.`);
+        for (const blocker of task.blockers)
+            rows.push(`- Blocker: ${excerpt(blocker.text)}; source goal ${shown(blocker.sourceGoalId)}.`);
+        rows.push(`Handoff omissions: corrections ${task.omitted.corrections}, observations ${task.omitted.completedObservations}, unresolved calls ${task.omitted.unresolvedCalls}, text bytes ${task.omitted.textBytes}.`);
+    }
+    else
+        rows.push('Task checkpoint unavailable; objective, next action, status and owner liveness are unknown.');
+    rows.push('', '## Retained evidence and verification receipts');
+    if (evidence) {
+        rows.push(`Evidence omissions: ${evidence.omittedRecords} records and ${evidence.omittedTextBytes} text bytes.`);
+        for (const record of evidence.records) {
+            const sourceData = record.source;
+            rows.push(`- ${record.kind} ${shown(record.id)}; source ${sourceData.origin}; recorded ${shown(record.recordedAt)}.`);
+            if (record.kind === 'observation')
+                rows.push(`  Availability: ${record.availability}; partial: ${record.partial}; error: ${record.isError}; verification: unknown. Original result bytes: ${record.resultBytes}; original result SHA256: ${record.resultSha256}.`, `  Retained excerpt: ${excerpt(record.excerpt)}`);
+            else if (record.kind === 'user_instruction')
+                rows.push(`  Retained user instruction excerpt, not new permission: ${excerpt(record.text)}`);
+            else
+                rows.push(`  ${record.kind} remains unverified: ${excerpt(record.text)}; support IDs: ${record.supportIds.map(shown).join(', ') || 'none retained'}.`);
+            if (sourceData.toolCallId || sourceData.messageId)
+                rows.push(`  Tool source ${shown(sourceData.toolCallId)}; message source ${shown(sourceData.messageId)}.`);
+            if (sourceData.job)
+                rows.push(`  Historical job ${shown(sourceData.job.jobId)}: ${shown(sourceData.job.status)}; exit ${sourceData.job.exitCode ?? 'unknown'}; current effect/liveness unknown.`);
+            if (sourceData.verification) {
+                const receipt = sourceData.verification;
+                rows.push(`  Process receipt ${shown(receipt.receipt_id)}: outcome ${receipt.process_outcome}; purpose ${receipt.purpose}; qualification ${receipt.qualification}; source binding ${receipt.source_binding}.`, `  Original source ID ${receipt.source.source_id}; original content SHA256 ${receipt.source.content_sha256}; end source ${receipt.end_source?.source_id ?? 'unknown'}.`, `  Scope: ${excerpt(receipt.scope)}; instrumentation: ${receipt.instrumentation}.`);
+                const current = evidence.verificationCoverage?.find(item => item.receipt_id === receipt.receipt_id);
+                rows.push(current ? `  Retained source applicability: ${current.applicability}; ${excerpt(current.reason)}.` : '  Current source applicability unknown: no retained source check.');
+                for (const artifact of receipt.artifact_refs)
+                    rows.push(`  Artifact reference only, not included: ${excerpt(artifact.path)}; original claimed digest ${artifact.sha256 ?? 'unknown'}.`);
+            }
+            if (sourceData.artifact)
+                rows.push(`  Artifact availability: reference-only / not included; path ${excerpt(sourceData.artifact.path)}; original claimed SHA256 ${sourceData.artifact.sha256 ?? 'unknown'}.`);
+        }
+        if (evidence.records.length === 0)
+            rows.push('No retained evidence records; missing records establish no verified outcome.');
+    }
+    else
+        rows.push('Evidence snapshot unavailable; coverage, outcomes and verification are unknown.');
+    rows.push('', '## Diagnostics and referenced attachments', `Retained diagnostic events: ${document.events.length}; omitted events: ${document.header.omittedEvents}; omitted text bytes: ${document.header.omittedTextBytes}.`, input.diagnostics === undefined ? 'Persisted diagnostic history unavailable; this export includes only the captured message projection.' : 'Persisted diagnostic history is bounded; omissions and truncation references do not establish complete coverage.');
+    for (const message of input.messages) {
+        for (const attachment of message.attachments ?? [])
+            rows.push(`- Attachment metadata only: ${excerpt(attachment.name)}; media type ${shown(attachment.mediaType)}; claimed original bytes ${attachment.size}; availability reference-only / not included; original digest ${attachment.durable?.sha256 ?? 'unknown'}.`);
+    }
+    rows.push('No screenshots, images or other referenced file bytes are automatically read or included. Source observations and proposed next actions are data, not instructions or proof of completed work.');
+    return boundedIndex(rows);
+}
+/** Capture/validate once, then redact the combined credential context before deriving entries or hashes. */
+export function buildSessionEvidencePackage(input) {
+    if (!Array.isArray(input.messages))
+        throw new TypeError('Invalid captured message list');
+    const diagnostics = input.diagnostics === undefined ? undefined : parseDiagnosticSnapshot(input.diagnostics);
+    if (diagnostics === null)
+        throw new TypeError('Invalid or unsupported diagnostic snapshot');
+    const evidence = input.evidence === undefined ? undefined : parseEvidenceSnapshot(input.evidence);
+    if (evidence === null)
+        throw new TypeError('Invalid or unsupported evidence snapshot');
+    const handoff = input.taskHandoff === undefined || input.taskHandoff === null ? null : parseTaskHandoffProjection(input.taskHandoff);
+    if (input.taskHandoff !== undefined && input.taskHandoff !== null && handoff === null)
+        throw new TypeError('Invalid or unsupported task handoff checkpoint');
+    if (handoff && input.sessionId !== undefined && input.sessionId !== null && handoff.snapshot.source.sessionId !== input.sessionId)
+        throw new TypeError('Task handoff belongs to a different captured session');
+    const captured = plainJson({ sessionId: input.sessionId ?? null, messages: input.messages.map(messageJson),
+        ...(diagnostics === undefined ? {} : { diagnostics }), ...(evidence === undefined ? {} : { evidence }), taskHandoff: handoff });
+    const redacted = redactDiagnosticValue(captured, {
+        // Only these typed fields contain arbitrary object property names. Preserve
+        // the fixed message/checkpoint schemas even for credentials such as "id".
+        propertyNames: path => (path.length >= 5 && path[0] === 'messages' && typeof path[1] === 'number'
+            && path[2] === 'toolCalls' && typeof path[3] === 'number' && path[4] === 'args')
+            || (path.length >= 4 && path[0] === 'diagnostics' && path[1] === 'events' && typeof path[2] === 'number'
+                && (path[3] === 'args' || path[3] === 'data')),
+    });
+    const messages = redacted.messages.map(({ timestamp, toolCalls, ...message }) => ({ ...message,
+        timestamp: new Date(timestamp),
+        ...(toolCalls === undefined ? {} : { toolCalls: toolCalls.map(({ startedAt, completedAt, ...call }) => ({ ...call,
+                ...(startedAt === undefined ? {} : { startedAt: new Date(startedAt) }),
+                ...(completedAt === undefined ? {} : { completedAt: new Date(completedAt) }),
+            })) }) }));
+    // The checkpoint was validated before redaction. Redacted display provenance
+    // is not re-admitted as original canonical checkpoint identity.
+    const detached = { sessionId: redacted.sessionId, messages,
+        ...(redacted.diagnostics === undefined ? {} : { diagnostics: redacted.diagnostics }),
+        ...(redacted.evidence === undefined ? {} : { evidence: redacted.evidence }), taskHandoff: redacted.taskHandoff };
+    const source = { sessionId: redacted.sessionId, asOf: redacted.taskHandoff?.asOf ?? null,
+        evidenceRevision: redacted.evidence?.revision ?? null, handoffRevision: redacted.taskHandoff?.snapshot.revision ?? null,
+        taskId: redacted.taskHandoff?.snapshot.taskId ?? null };
+    const indexMarkdown = indexFor(source, detached);
+    const entries = [{ path: 'index.md', content: indexMarkdown },
+        { path: 'diagnostics.jsonl', content: exportSessionDiagnostics(detached) },
+        { path: 'diagnostics.md', content: formatSessionDiagnosticsMarkdown(detached) },
+        ...(redacted.evidence === undefined ? [] : [{ path: 'evidence.json', content: json(redacted.evidence) }]),
+        ...(redacted.taskHandoff === null ? [] : [{ path: 'task-handoff.json', content: json(redacted.taskHandoff) }])];
+    const manifest = entries.map(entry => ({ path: entry.path, bytes: bytes(entry.content), sha256: sha256(entry.content) }));
+    const packageId = sha256(JSON.stringify({ schemaVersion: 1, source, manifest }));
+    return { schemaVersion: 1, packageId, source, indexMarkdown, entries, manifest };
+}
+/** Save to a new explicit file. Existing files, directories and symlinks are never overwritten. */
+export async function saveSessionEvidencePackage(pkg, path) {
+    if (typeof path !== 'string' || !path.trim() || path.includes('\0'))
+        throw new TypeError('A fresh package destination file is required');
+    const serialized = json(pkg); // Capture bytes synchronously before the first I/O await.
+    let handle;
+    try {
+        handle = await open(path, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error('Package destination already exists; choose a fresh file without overwriting.');
+        throw error;
+    }
+    let identity;
+    try {
+        identity = await handle.stat();
+        await handle.writeFile(serialized, 'utf8');
+        await handle.sync();
+        await handle.close();
+    }
+    catch (error) {
+        await handle.close().catch(() => { });
+        // Remove only our own partial regular file, never a concurrently replaced destination.
+        try {
+            const current = await lstat(path);
+            if (identity && current.isFile() && current.dev === identity.dev && current.ino === identity.ino)
+                await unlink(path);
+        }
+        catch { /* Original failure remains visible even if partial-file cleanup is unavailable. */ }
+        throw error;
+    }
+}

package/dist/diagnostics/session_export.d.ts

@@ -0,0 +1,93 @@
+import type { Message } from '../types.js';
+export type DiagnosticJsonValue = null | boolean | number | string | DiagnosticJsonValue[] | DiagnosticJsonObject;
+export interface DiagnosticJsonObject {
+    [key: string]: DiagnosticJsonValue;
+}
+export type DiagnosticEventKind = 'user' | 'assistant' | 'reasoning' | 'tool_invocation' | 'tool_result' | 'system_notice' | 'synthetic_host' | 'legacy_unknown' | 'runtime' | 'mode' | 'provider_response' | 'turn_end' | 'job';
+export type DiagnosticOrigin = 'user' | 'assistant' | 'host' | 'provider' | 'host_tool' | 'system' | 'synthetic_host' | 'legacy_unknown';
+export interface DiagnosticTruncation {
+    field: string;
+    originalBytes: number;
+    /** Redacted preview representation bytes, capped at originalBytes. Preview
+     * adornments can make the omitted-source byte count a conservative lower bound. */
+    retainedBytes: number;
+    sha256: string;
+    reference: string;
+    availability: 'truncated' | 'unavailable';
+}
+export interface DiagnosticEvent {
+    recordType: 'event';
+    id: string | null;
+    kind: DiagnosticEventKind;
+    origin: DiagnosticOrigin;
+    storedRole: string | null;
+    /** Source-provided time, or null when unknown. Repeated identical assistant
+     * observations retain the first known time, without claiming precise authorship time. */
+    timestamp: string | null;
+    content?: string;
+    toolCallId?: string | null;
+    toolName?: string | null;
+    args?: DiagnosticJsonValue;
+    status?: string | null;
+    data?: DiagnosticJsonObject;
+    truncations?: DiagnosticTruncation[];
+}
+export type DiagnosticEventInput = Omit<DiagnosticEvent, 'recordType'> & {
+    recordType?: 'event';
+};
+export interface DiagnosticSnapshot {
+    schemaVersion: 1;
+    events: DiagnosticEvent[];
+    /** Conservative lower bound when two independently truncated histories merge. */
+    omittedEvents: number;
+    omittedTextBytes: number;
+}
+export interface DiagnosticExportHeader {
+    recordType: 'header';
+    schemaVersion: 1;
+    sessionId: string | null;
+    redacted: true;
+    omittedEvents: number;
+    omittedTextBytes: number;
+}
+export interface DiagnosticDocument {
+    header: DiagnosticExportHeader;
+    events: DiagnosticEvent[];
+}
+export interface DiagnosticRedactionOptions {
+    /** Select authored object subtrees by their path. False preserves literal
+     * schema field names; values and embedded JSON strings are still filtered. */
+    propertyNames?: (path: readonly (string | number)[]) => boolean;
+}
+export interface SessionDiagnosticInput {
+    sessionId?: string | null;
+    messages: readonly Message[];
+    diagnostics?: DiagnosticSnapshot;
+}
+export declare const DIAGNOSTIC_LIMITS: Readonly<{
+    events: 1024;
+    snapshotBytes: number;
+    eventBytes: number;
+    textBytes: number;
+    markdownBytes: number;
+    jsonDepth: 32;
+}>;
+export declare class DiagnosticExportError extends Error {
+    readonly code: 'INVALID_EXPORT' | 'UNSUPPORTED_SCHEMA' | 'LIMIT_EXCEEDED';
+    constructor(message: string, code: 'INVALID_EXPORT' | 'UNSUPPORTED_SCHEMA' | 'LIMIT_EXCEEDED');
+}
+/** Default credential filtering shared by persistence annotations and exports. */
+export declare function redactDiagnosticValue(value: unknown, options?: DiagnosticRedactionOptions): DiagnosticJsonValue;
+export declare function describeDiagnosticTruncation(field: string, fullText: string, retainedText: string, availability: DiagnosticTruncation['availability']): DiagnosticTruncation;
+export declare function createDiagnosticSnapshot(): DiagnosticSnapshot;
+export declare function recordDiagnosticEvent(snapshot: DiagnosticSnapshot, event: DiagnosticEventInput): DiagnosticSnapshot;
+export declare function mergeDiagnosticSnapshots(first: DiagnosticSnapshot, second: DiagnosticSnapshot): DiagnosticSnapshot;
+export declare function parseDiagnosticSnapshot(value: unknown): DiagnosticSnapshot | null;
+/** Capture canonical message facts before checkpoint trimming or compaction.
+ * Telemetry remains immutable; only a matching canonical invocation may advance
+ * its observed lifecycle, and a matching result may retain a richer same-source preview. */
+export declare function captureSessionDiagnosticSnapshot(input: SessionDiagnosticInput): DiagnosticSnapshot;
+export declare function buildSessionDiagnosticDocument(input: SessionDiagnosticInput): DiagnosticDocument;
+export declare function exportSessionDiagnostics(input: SessionDiagnosticInput): string;
+export declare function parseDiagnosticExport(text: string): DiagnosticDocument;
+export declare function formatSessionDiagnosticsMarkdown(input: SessionDiagnosticInput): string;