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

package/dist/agent/runtime/source_verification_contract.js

@@ -0,0 +1,203 @@
+export const VERIFICATION_REQUEST_MAX_BYTES = 8 * 1024;
+export const SOURCE_SNAPSHOT_MAX_BYTES = 16 * 1024;
+export const VERIFICATION_RECEIPT_MAX_BYTES = 48 * 1024;
+const encoder = new TextEncoder();
+const purposeValues = ['compile', 'test', 'benchmark', 'qualification'];
+const instrumentationValues = ['production', 'diagnostic', 'unknown'];
+const outcomeValues = ['running', 'passed', 'failed', 'timed_out', 'cancelled', 'interrupted', 'unknown'];
+function invalid() { throw new TypeError('Invalid bounded source verification contract'); }
+function object(value, required, optional = []) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return invalid();
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return invalid();
+    const row = value;
+    if (!required.every(key => Object.hasOwn(row, key))
+        || Object.keys(row).some(key => !required.includes(key) && !optional.includes(key)))
+        return invalid();
+    return row;
+}
+function text(value, limit, empty = false) {
+    if (typeof value !== 'string' || (!empty && value.length === 0)
+        || /[\u0000-\u001f\u007f]/u.test(value) || encoder.encode(value).byteLength > limit)
+        return invalid();
+    return value;
+}
+function bounded(value, limit) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined || encoder.encode(encoded).byteLength > limit)
+        invalid();
+}
+function enumeration(value, values) {
+    if (typeof value !== 'string' || !values.includes(value))
+        return invalid();
+    return value;
+}
+function integer(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        return invalid();
+    return value;
+}
+function digest(value) {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value))
+        return invalid();
+    return value;
+}
+function timestamp(value) {
+    const parsed = text(value, 64);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.test(parsed)
+        || !Number.isFinite(Date.parse(parsed)))
+        return invalid();
+    return parsed;
+}
+function relativePath(value) {
+    const path = text(value, 512);
+    if (path.startsWith('/') || /^[A-Za-z]:/.test(path) || path.includes('\\')
+        || path.split('/').some(part => part === '' || part === '.' || part === '..'))
+        return invalid();
+    return path;
+}
+function list(value, minimum, maximum) {
+    if (!Array.isArray(value) || value.length < minimum || value.length > maximum)
+        return invalid();
+    return [...value];
+}
+function unique(values) {
+    if (new Set(values).size !== values.length)
+        invalid();
+}
+function parse(value, limit, decode) {
+    try {
+        bounded(value, limit);
+        const parsed = decode(value);
+        bounded(parsed, limit);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function request(value) {
+    const row = object(value, ['purpose', 'scope', 'source_paths'], ['instrumentation', 'environment_id', 'build_identity']);
+    const paths = list(row.source_paths, 1, 64).map(relativePath);
+    unique(paths);
+    return { purpose: enumeration(row.purpose, purposeValues), scope: text(row.scope, 512), source_paths: paths,
+        instrumentation: Object.hasOwn(row, 'instrumentation') ? enumeration(row.instrumentation, instrumentationValues) : 'unknown',
+        ...(Object.hasOwn(row, 'environment_id') ? { environment_id: text(row.environment_id, 256) } : {}),
+        ...(Object.hasOwn(row, 'build_identity') ? { build_identity: text(row.build_identity, 256) } : {}) };
+}
+function snapshot(value) {
+    bounded(value, SOURCE_SNAPSHOT_MAX_BYTES);
+    const row = object(value, ['schema_version', 'source_id', 'content_sha256', 'cwd', 'origin', 'captured_at', 'git', 'coverage', 'files'], ['reason']);
+    if (row.schema_version !== 1)
+        invalid();
+    const git = object(row.git, ['commit', 'dirty']);
+    if (git.commit !== null && (typeof git.commit !== 'string' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(git.commit)))
+        invalid();
+    if (git.dirty !== null && typeof git.dirty !== 'boolean')
+        invalid();
+    const files = list(row.files, 1, 64).map(value => {
+        const file = object(value, ['path', 'kind', 'sha256', 'bytes', 'mode']);
+        const kind = enumeration(file.kind, ['file', 'missing', 'unavailable']);
+        const sha256 = file.sha256 === null ? null : digest(file.sha256);
+        if ((kind === 'file') !== (sha256 !== null))
+            invalid();
+        return { path: relativePath(file.path), kind, sha256, bytes: integer(file.bytes), mode: integer(file.mode) };
+    });
+    unique(files.map(file => file.path));
+    const coverage = enumeration(row.coverage, ['complete', 'incomplete']);
+    if (coverage === 'complete' && files.some(file => file.kind !== 'file'))
+        invalid();
+    return { schema_version: 1, source_id: digest(row.source_id), content_sha256: digest(row.content_sha256),
+        cwd: text(row.cwd, 4096), origin: enumeration(row.origin, ['local', 'external']), captured_at: timestamp(row.captured_at),
+        git: { commit: git.commit, dirty: git.dirty }, coverage, files,
+        ...(Object.hasOwn(row, 'reason') ? { reason: text(row.reason, 512, true) } : {}) };
+}
+/** Compare Unicode codepoints, independently of locale and UTF-16 surrogate ordering. */
+function comparePath(left, right) {
+    const a = [...left];
+    const b = [...right];
+    for (let index = 0; index < Math.min(a.length, b.length); index++) {
+        const difference = a[index].codePointAt(0) - b[index].codePointAt(0);
+        if (difference !== 0)
+            return difference;
+    }
+    return a.length - b.length;
+}
+function content(value) {
+    return JSON.stringify({ schema_version: 1, files: [...value.files].sort((a, b) => comparePath(a.path, b.path)) });
+}
+function identity(value) {
+    return JSON.stringify({ schema_version: 1, cwd: value.cwd, origin: value.origin,
+        coverage: value.coverage, content_sha256: value.content_sha256 });
+}
+function artifact(value) {
+    const row = object(value, ['origin', 'path', 'sha256'], ['source_observation_id']);
+    return { origin: enumeration(row.origin, ['local', 'external']), path: text(row.path, 4096), sha256: digest(row.sha256),
+        ...(Object.hasOwn(row, 'source_observation_id') ? { source_observation_id: text(row.source_observation_id, 256) } : {}) };
+}
+function receipt(value) {
+    const row = object(value, ['schema_version', 'receipt_id', 'source', 'end_source', 'purpose', 'scope', 'command_sha256',
+        'command_kind', 'environment', 'build_identity', 'instrumentation', 'process_outcome', 'source_binding', 'qualification', 'artifact_refs']);
+    if (row.schema_version !== 1 || row.qualification !== 'unverified')
+        invalid();
+    const source = snapshot(row.source);
+    const endSource = row.end_source === null ? null : snapshot(row.end_source);
+    const outcome = enumeration(row.process_outcome, outcomeValues);
+    const binding = enumeration(row.source_binding, ['observed_endpoints', 'unknown']);
+    if (outcome === 'running' && (endSource !== null || binding !== 'unknown'))
+        invalid();
+    if (source.origin === 'external' && binding !== 'unknown')
+        invalid();
+    if (endSource !== null) {
+        const paths = source.files.map(file => file.path).sort(comparePath);
+        const endPaths = endSource.files.map(file => file.path).sort(comparePath);
+        if (endSource.origin !== 'local' || source.cwd !== endSource.cwd || JSON.stringify(paths) !== JSON.stringify(endPaths))
+            invalid();
+    }
+    if (binding === 'observed_endpoints' && (endSource === null || source.origin !== 'local'
+        || source.coverage !== 'complete' || endSource.coverage !== 'complete'
+        || source.source_id !== endSource.source_id || source.content_sha256 !== endSource.content_sha256
+        || content(source) !== content(endSource)))
+        invalid();
+    const environment = object(row.environment, ['platform', 'arch', 'node_version', 'declared_id']);
+    return { schema_version: 1, receipt_id: text(row.receipt_id, 256), source, end_source: endSource,
+        purpose: enumeration(row.purpose, purposeValues), scope: text(row.scope, 512), command_sha256: digest(row.command_sha256),
+        command_kind: enumeration(row.command_kind, ['shell', 'checked', 'host_verifier']),
+        environment: { platform: text(environment.platform, 256), arch: text(environment.arch, 256),
+            node_version: text(environment.node_version, 256), declared_id: environment.declared_id === null ? null : text(environment.declared_id, 256) },
+        build_identity: row.build_identity === null ? null : text(row.build_identity, 256),
+        instrumentation: enumeration(row.instrumentation, instrumentationValues), process_outcome: outcome,
+        source_binding: binding, qualification: 'unverified', artifact_refs: list(row.artifact_refs, 0, 8).map(artifact) };
+}
+function projection(value) {
+    const row = object(value, ['receipt_id', 'checked_at', 'source_id', 'applicability', 'reason']);
+    const applicability = enumeration(row.applicability, ['current', 'stale', 'unknown']);
+    const sourceId = row.source_id === null ? null : digest(row.source_id);
+    if (applicability === 'current' && sourceId === null)
+        invalid();
+    return { receipt_id: text(row.receipt_id, 256), checked_at: timestamp(row.checked_at), source_id: sourceId,
+        applicability, reason: text(row.reason, 512, true) };
+}
+export function parseVerificationRequest(value) {
+    return parse(value, VERIFICATION_REQUEST_MAX_BYTES, request);
+}
+export function parseSourceSnapshot(value) {
+    return parse(value, SOURCE_SNAPSHOT_MAX_BYTES, snapshot);
+}
+export function parseCommandVerificationReceipt(value) {
+    return parse(value, VERIFICATION_RECEIPT_MAX_BYTES, receipt);
+}
+export function parseCurrentVerificationProjection(value) {
+    return parse(value, SOURCE_SNAPSHOT_MAX_BYTES, projection);
+}
+/** Canonical preimages, not digest verification. The host scanner hashes these observed fields. */
+export function canonicalSourceContent(value) {
+    const parsed = parseSourceSnapshot(value);
+    return parsed === null ? null : content(parsed);
+}
+export function canonicalSourceIdentity(value) {
+    const parsed = parseSourceSnapshot(value);
+    return parsed === null ? null : identity(parsed);
+}

package/dist/agent/runtime/tool_checkpoints.d.ts

@@ -0,0 +1,11 @@
+import type { Message } from '../../types.js';
+/** Canonical invocation history admitted by the session-owning host. */
+export interface ToolCheckpoint {
+    sessionId: string;
+    phase: 'before_execute' | 'terminal';
+    toolCallId: string;
+    messages: readonly Message[];
+}
+export type ToolCheckpointHandler = (checkpoint: ToolCheckpoint) => Promise<void>;
+/** Merge cumulative source rows without replacing independently accepted input. */
+export declare function mergeToolCheckpointMessages(live: readonly Message[], ordered: readonly Message[]): Message[];

package/dist/agent/runtime/tool_checkpoints.js

@@ -0,0 +1,26 @@
+/** Merge cumulative source rows without replacing independently accepted input. */
+export function mergeToolCheckpointMessages(live, ordered) {
+    const messages = [...live];
+    for (const source of ordered) {
+        const row = structuredClone(source);
+        const index = messages.findIndex(message => message.id === row.id
+            || message.toolCalls?.some(call => row.toolCalls?.some(sourceCall => sourceCall.id === call.id)));
+        if (index >= 0) {
+            const existing = messages[index];
+            if (row.toolCalls?.length && existing.id !== row.id) {
+                const sources = new Map(row.toolCalls.map(call => [call.id, call]));
+                const calls = (existing.toolCalls ?? []).map(call => sources.get(call.id) ?? call);
+                calls.push(...row.toolCalls.filter(call => !calls.some(retained => retained.id === call.id)));
+                messages[index] = { ...row, id: existing.id, content: existing.content, toolCalls: calls,
+                    metadata: { ...existing.metadata, ...row.metadata } };
+            }
+            else {
+                messages[index] = { ...row, ...(row.role === 'user' && !row.metadata?.toolResult
+                        ? { metadata: { ...row.metadata, ...existing.metadata } } : {}) };
+            }
+        }
+        else
+            messages.push(row);
+    }
+    return messages;
+}

package/dist/agent/runtime/tool_effects.d.ts

@@ -14,8 +14,13 @@ export interface ToolEffectEvent {
     effect: ToolEffectKind;
     args: Record<string, unknown>;
     toolCallId?: string;
+    /** Actual tool cwd and cancellation owner; absent on older host events. */
+    cwd?: string;
+    signal?: AbortSignal;
 }
 export type ToolEffectObserver = (event: ToolEffectEvent) => void | Promise<void>;
+/** Successful managed file changes, independently of optional user hooks. */
+export type LocalFileChangeObserver = (paths: readonly string[], cwd: string) => void | Promise<void>;
 /**
  * Resolve the effective host boundary conservatively. Tool authors can
  * override the capability-derived result with explicit metadata.

package/dist/agent/runtime/tool_progress.d.ts

@@ -0,0 +1,12 @@
+import type { AgentToolProgress } from '../../types.js';
+/** Clock boundary for deterministic publication pacing tests. */
+export interface ToolProgressClock {
+    now: () => number;
+    schedule: (callback: () => void, delayMs: number) => () => void;
+}
+/** Aggregate decoded command output without retaining the full output stream. */
+export declare function createToolProgressAccumulator(startedAt: number, publish: (progress: AgentToolProgress) => void, clock?: ToolProgressClock): {
+    onOutput: (stream: 'stdout' | 'stderr', chunk: string) => void;
+    snapshot: () => AgentToolProgress;
+    close: () => void;
+};

package/dist/agent/runtime/tool_progress.js

@@ -0,0 +1,76 @@
+const MAX_LINE_BYTES = 512;
+const PUBLICATION_INTERVAL_MS = 250;
+const systemClock = {
+    now: Date.now,
+    schedule: (callback, delayMs) => {
+        const timer = setTimeout(callback, delayMs);
+        return () => clearTimeout(timer);
+    },
+};
+function linePrefix(text) {
+    let prefix = '', bytes = 0;
+    for (const character of text) {
+        const length = Buffer.byteLength(character);
+        if (bytes + length > MAX_LINE_BYTES)
+            break;
+        prefix += character;
+        bytes += length;
+    }
+    return prefix;
+}
+/** Aggregate decoded command output without retaining the full output stream. */
+export function createToolProgressAccumulator(startedAt, publish, clock = systemClock) {
+    const partial = { stdout: '', stderr: '' };
+    const clipped = { stdout: false, stderr: false };
+    const progress = { startedAt, outputBytes: 0, outputLines: 0, latestLine: '' };
+    let closed = false;
+    let pending = false;
+    let lastPublishedAt;
+    let cancelPublication;
+    const snapshot = () => ({ ...progress });
+    const flush = () => {
+        cancelPublication?.();
+        cancelPublication = undefined;
+        if (!pending || closed)
+            return;
+        pending = false;
+        lastPublishedAt = clock.now();
+        // Display observers cannot change command effects or final output.
+        try {
+            publish(snapshot());
+        }
+        catch { /* informational observer only */ }
+    };
+    return {
+        snapshot,
+        close: () => { flush(); closed = true; },
+        onOutput: (stream, chunk) => {
+            if (closed || chunk.length === 0)
+                return;
+            progress.outputBytes += Buffer.byteLength(chunk);
+            progress.lastOutputAt = Math.max(progress.lastOutputAt ?? startedAt, clock.now());
+            const pieces = chunk.split('\n');
+            progress.outputLines += pieces.length - 1;
+            for (let index = 0; index < pieces.length; index++) {
+                if (pieces[index].length > 0) {
+                    if (!clipped[stream]) {
+                        const source = partial[stream] + pieces[index];
+                        partial[stream] = linePrefix(source);
+                        clipped[stream] = partial[stream].length < source.length;
+                    }
+                }
+                if (partial[stream] && (pieces[index].length > 0 || index < pieces.length - 1))
+                    progress.latestLine = partial[stream];
+                if (index < pieces.length - 1) {
+                    partial[stream] = '';
+                    clipped[stream] = false;
+                }
+            }
+            pending = true;
+            if (lastPublishedAt === undefined || clock.now() - lastPublishedAt >= PUBLICATION_INTERVAL_MS)
+                flush();
+            else if (!cancelPublication)
+                cancelPublication = clock.schedule(flush, Math.min(PUBLICATION_INTERVAL_MS, PUBLICATION_INTERVAL_MS - (clock.now() - lastPublishedAt)));
+        },
+    };
+}

package/dist/agent/runtime/tool_runtime.d.ts

@@ -3,8 +3,14 @@ import type { Policy } from './policy.js';
 import { ToolCapability } from './capabilities.js';
 import { HookDispatcher } from '../../hooks/dispatcher.js';
 import type { HookApprovalRequester } from '../../hooks/types.js';
-import { type ToolEffectObserver } from './tool_effects.js';
+import { type ToolEffectObserver, type LocalFileChangeObserver } from './tool_effects.js';
+import { type RemoteResourceSession } from './remote_resources.js';
+import type { ManagedCommandObservation } from './command_jobs.js';
+import { type CommandVerificationReceipt } from './source_verification_contract.js';
+import type { BenchmarkComparisonDecision } from './benchmark_comparison.js';
+import type { HostVerifierDecision } from './verifier_contract.js';
 export interface ToolRuntimeOptions {
+    remoteResourceSession?: RemoteResourceSession;
     tools: Tool[];
     context?: ToolContext;
     policy?: Policy;
@@ -12,6 +18,9 @@ export interface ToolRuntimeOptions {
     approvalRequester?: HookApprovalRequester;
     /** Called after permission is granted and immediately before execution. */
     onToolEffect?: ToolEffectObserver;
+    onLocalFileChange?: LocalFileChangeObserver;
+    /** Required host persistence, distinct from informational effect observers. */
+    beforeExecute?: (args: Record<string, unknown>) => Promise<void>;
     /** Capabilities that always require the host's explicit approval. */
     approvalRequiredCapabilities?: readonly ToolCapability[];
     /** Stable host-owned context used for direct approval requests. */
@@ -24,8 +33,14 @@ export interface HostApprovalContext {
     isSubagent: boolean;
 }
 export interface ToolRuntimeResult {
+    /** Host applied the tool-result cap; the captured text is incomplete. */
+    contentTruncated?: boolean;
     content: string;
     isError: boolean;
     effectiveArgs: Record<string, unknown>;
+    managedCommand?: ManagedCommandObservation;
+    verificationReceipt?: CommandVerificationReceipt;
+    verifierDecision?: HostVerifierDecision;
+    benchmarkComparisonDecision?: BenchmarkComparisonDecision;
 }
 export declare function executeToolWithRuntime(name: string, args: Record<string, unknown>, options: ToolRuntimeOptions): Promise<ToolRuntimeResult>;