spexcode 0.6.2 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/harness.d.ts

@@ -0,0 +1,338 @@
+import { type SlashCommand } from './slash-commands.js';
+import { type ExecutionTrace, type ExecutionTurn } from './execution-trace.js';
+import { type HarnessId } from '@spexcode/spec-core';
+export type { HarnessId } from '@spexcode/spec-core';
+export type HarnessLivenessRecord = {
+    session: string;
+    harnessSessionId?: string | null;
+    stopped?: boolean;
+    archived?: boolean;
+};
+export type HarnessLaunchReadyRecord = HarnessLivenessRecord & {
+    governed?: boolean;
+    runtimeDir: string;
+};
+export type HarnessLaunchReadinessFence = {
+    readonly proof: Readonly<Record<string, unknown>>;
+    validate(current: () => HarnessLaunchReadyRecord | null): Promise<boolean>;
+};
+export type TurnFailure = {
+    message: string;
+    completedAt: number | null;
+};
+export type FailureSubscription = {
+    close(): void;
+    readonly closed: Promise<string | null>;
+};
+export type DeliveryTransportState = {
+    kind: 'reachable';
+} | {
+    kind: 'unproven';
+} | {
+    kind: 'unreachable';
+    reason: string;
+};
+export type ProcTable = Map<number, {
+    ppid: number;
+    comm: string;
+}>;
+export type PaneProbe = {
+    panePid?: number;
+    procs?: ProcTable;
+    pidAlive?: boolean;
+};
+export type SharedRuntimeDescriptor = {
+    key: string;
+    label: string;
+    pidFile: string;
+    receiptFile: string;
+    targetDescriptorKey?: (rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }) => string | null;
+    residency?: () => Promise<{
+        healthy: boolean;
+        referenceIds: string[];
+        error?: string;
+        rootAbsent?: boolean;
+    }>;
+    mutationGuard?: (targetReferenceId: string, opts?: {
+        coldReceipt?: unknown;
+    }) => Promise<SharedRuntimeMutationGuard>;
+    probe(): Promise<SharedRuntimeProbe>;
+};
+export type SharedRuntimeMutationGuard = {
+    healthy: boolean;
+    referenceIds: string[];
+    targetTurnPresence: 'none' | 'idle' | 'active' | 'unknown';
+    descendantIds: string[];
+    coldTeardownAuthorized?: boolean;
+    error?: string;
+};
+export type SharedRuntimeProbe = {
+    healthy: boolean;
+    references: Array<{
+        referenceId: string;
+        turnPresence: 'idle' | 'active' | 'unknown';
+        turnId?: string;
+    }>;
+    error?: string;
+};
+export type HarnessColdPreflight = {
+    ok: true;
+    alreadyCold?: boolean;
+    receipt?: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+export type HarnessOrphanThreadQuarantine = {
+    ok: true;
+    audit: {
+        adapter: string;
+        threadId: string;
+        action: 'archived' | 'already-unloaded';
+    };
+    compensate(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+} | {
+    ok: false;
+    reason: string;
+};
+export type AdapterLoadedReferenceState = {
+    healthy: boolean;
+    loaded: boolean;
+    error?: string;
+};
+export declare function adapterLoadedReferenceState(records: readonly (HarnessLivenessRecord & {
+    harness?: string;
+})[], runtimeDir?: string): Promise<Map<string, AdapterLoadedReferenceState>>;
+export interface Harness {
+    readonly id: HarnessId;
+    readonly dispatchId: 'claude' | 'codex' | 'opencode' | 'pi' | 'zcode';
+    readonly headless: boolean;
+    readonly launchOneShot?: boolean;
+    readonly runtimeOwnership?: 'leaf' | 'adapter';
+    readonly sharedRuntimeSpawn?: boolean;
+    readonly fatalLaunchOutput?: readonly string[];
+    readonly events: readonly string[];
+    readonly ownsRendezvous: boolean;
+    readonly paneTitleIsSelfSummary: boolean;
+    executionTrace(threadId: string, turn: ExecutionTurn | null): ExecutionTrace | null;
+    launchCmd(id: string, runtimeDir?: string, cmd?: string): string;
+    baseCmd(cmd?: string): string;
+    oneShotTurn?(prompt: string, cmd?: string): {
+        command: string;
+        stdin: string;
+    };
+    sessionIdArg(id: string): string;
+    readonly sessionEnvVar: string;
+    launchEnv(id: string): string[];
+    shimFile(proj: string): string;
+    shimScope: 'tree' | 'project';
+    worktreeHookAnchor(proj: string): string | null;
+    contractFiles(proj: string): string[];
+    skillDir(proj: string): string | null;
+    agentDir(proj: string): string | null;
+    shim(dispatch: string, spex: string): {
+        content: string;
+        cmd: (e: string) => string;
+    };
+    writeTrust(proj: string, cmdFor: (e: string) => string): readonly string[];
+    slashCommands(): SlashCommand[];
+    liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline';
+    launchReady?(current: () => HarnessLaunchReadyRecord | null, deadline: number): Promise<HarnessLaunchReadinessFence | null>;
+    launchPayloadProof?: true;
+    exactNativeTargetId(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): string | null;
+    deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>;
+    deliveryTransport?(rec: HarnessDeliveryRecord): Promise<DeliveryTransportState>;
+    observeTurnFailures?(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription;
+    interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>;
+    cleanupRuntime(rec: HarnessLivenessRecord): Promise<void>;
+    coldPreflight?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): Promise<HarnessColdPreflight>;
+    coldRetirementPreflight?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): Promise<{
+        ok: true;
+        alreadyCold: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    coldRuntime?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }, receipt?: unknown): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    restoreRuntime?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }, receipt?: unknown): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    quarantineOrphanThread?(threadId: string, opts: {
+        excludingSessionId: string;
+    }): Promise<HarnessOrphanThreadQuarantine>;
+    sharedRuntimes?(runtimeDir: string): readonly SharedRuntimeDescriptor[];
+    targetDescriptorKey?(rec: HarnessLivenessRecord & {
+        harnessSessionId?: string | null;
+    }): string | null;
+    deliveryBlockedBy?(paneText: string): string | null;
+    clean(proj: string, arts: HarnessArtifacts, preserveProject?: boolean): void;
+    removeTrust(proj: string): void;
+    resumeArg(rec: {
+        session: string;
+        harnessSessionId?: string | null;
+    }, pendingLaunchPayload?: string | null): string;
+}
+export type DispatchResult = {
+    ok: boolean;
+    error?: string;
+};
+export type HarnessDeliveryRecord = {
+    session: string;
+    stopped?: boolean;
+    archived?: boolean;
+    worktreePath?: string;
+    harnessSessionId?: string | null;
+    runtimeDir?: string;
+    launchCmd?: string | null;
+    mid?: string;
+};
+export type HarnessArtifacts = {
+    skills: readonly string[];
+    agents: readonly string[];
+};
+export declare const legacyRvSock: (id: string) => string;
+export declare const scopedRvSock: (id: string, dir?: string) => string;
+export declare function assertRvSockPath(id: string, dir?: string): string;
+export declare const rvSock: (id: string) => string;
+export declare function stampRvSock(id: string, dir?: string): string;
+export type ListenerProbe = 'live' | 'dead' | 'unproven';
+export declare function listenerAt(path: string, timeoutMs?: number): Promise<ListenerProbe>;
+export declare const rendezvousListening: (id: string, timeoutMs?: number) => Promise<ListenerProbe>;
+export declare const codexAppServerSock: (dir?: string) => string;
+export declare const codexAppServerPid: (dir?: string) => string;
+export declare const codexAppServerReceipt: (dir?: string) => string;
+export declare function deliverViaRendezvous(id: string, text: string, mid?: string): Promise<DispatchResult>;
+export declare function deliverViaClaudeRendezvous(id: string, text: string, mid?: string, runtimeDir?: string): Promise<DispatchResult>;
+export declare function deliverViaSocketOrWake(id: string, text: string, mid: string | undefined, coldWake: () => Promise<DispatchResult>, unprovenError: string): Promise<DispatchResult>;
+type JsonRpc = {
+    id?: number;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code?: number;
+        message?: string;
+    };
+};
+export declare function codexHandshakeMessages(threadId: string): JsonRpc[];
+export declare function codexInjectMessage(threadId: string, text: string, cwd: string | undefined, activeTurnId: string | null, id?: number, clientUserMessageId?: string): JsonRpc;
+export declare function activeTurnIdFromThread(readResult: unknown): string | null;
+export declare function codexBinary(codexCmd: string): string;
+export type CodexThreadPolicy = {
+    approvalPolicy?: 'untrusted' | 'on-request' | 'never';
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+};
+export declare function codexLauncherThreadPolicy(command: string): CodexThreadPolicy;
+export declare function codexSupportsBypassHookTrust(binary: string): boolean;
+export declare function reportHeadlessTurnExit(id: string, harness: string, code: number | null, cwd?: string): Promise<void>;
+export declare function headlessTurnFailureShell(harness: string, swallow?: boolean): string;
+export declare function sessionIdentityEnvVars(): string[];
+export declare function codexLaunchCommand(id: string, codexCmd?: string, serverCmd?: string, dir?: string, attachTui?: boolean): string;
+export declare function codexTurnFailureObserver(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription;
+export declare const CODEX_THREAD_SOURCE_KINDS: readonly ["cli", "vscode", "exec", "appServer", "subAgent", "subAgentReview", "subAgentCompact", "subAgentThreadSpawn", "subAgentOther", "unknown"];
+export declare function codexLoadedReferenceIds(sock: string): Promise<{
+    ok: true;
+    referenceIds: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexThreadList(sock: string, params: Record<string, unknown>): Promise<{
+    ok: true;
+    ids: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexThreadId(sock: string): Promise<{
+    ok: true;
+    threadId: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexSharedRuntimeProbe(dir?: string, endpoint?: Readonly<{
+    id: string;
+    pidFile: string;
+    receiptFile: string;
+    logFile: string;
+    socketPath: string;
+}>): Promise<SharedRuntimeProbe>;
+export declare function codexStartThreadParams(cwd?: string, bypassHookTrust?: boolean, shellEnv?: Record<string, string>, policy?: CodexThreadPolicy): Record<string, unknown>;
+export declare function codexStartThread(sock: string, cwd?: string, bypassHookTrust?: boolean, shellEnv?: Record<string, string>, policy?: CodexThreadPolicy): Promise<{
+    ok: true;
+    threadId: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function codexTurn(sock: string, threadId: string, text: string, cwd?: string, clientUserMessageId?: string): Promise<DispatchResult>;
+export declare function codexRolloutExists(threadId: string, root?: string): boolean;
+export declare function codexRolloutBytes(threadId: string, root?: string): {
+    bytes: number;
+} | {
+    unreadable: true;
+};
+export declare function waitForCodexRollout(threadId: string, timeoutMs?: number): Promise<boolean>;
+export declare function writeManagedBlock(file: string, body: string, comment?: readonly [string, string]): boolean;
+export declare function removeManagedBlock(file: string, comment?: readonly [string, string], deleteIfEmpty?: boolean): void;
+export declare function codexHookHash(snakeEvent: string, command: string, timeout?: number, asyncFlag?: boolean): string;
+export declare function writeCodexTrust(proj: string, events: readonly string[], cmdFor: (e: string) => string): string;
+export declare function paneTreeRunsCodex(pane?: PaneProbe): boolean;
+export declare function procSnapshot(timeoutMs?: number): Promise<ProcTable>;
+export declare function opencodeLaunchCommand(opencodeCmd?: string): string;
+export declare const unlinkSocks: (...paths: string[]) => Promise<void>;
+export declare const claudeHarness: Harness;
+export declare const claudeHeadlessHarness: Harness;
+export declare const codexHarness: Harness;
+export declare const codexHeadlessHarness: Harness;
+export declare const piHarness: Harness;
+export declare const piHeadlessHarness: Harness;
+export declare const zcodeHarness: Harness;
+export declare const opencodeHarness: Harness;
+export declare const opencodeHeadlessHarness: Harness;
+export declare const HARNESSES: readonly Harness[];
+export declare const defaultHarness: Harness;
+export declare function harnessByIdOrNull(id: string): Harness | null;
+export declare function harnessById(id: string): Harness;
+export type Launcher = {
+    name: string;
+    harness: string;
+    cmd: string;
+    headless: boolean;
+};
+export type LauncherDefault = {
+    default: string | null;
+    error: string | null;
+};
+export declare function launcherList(root?: string): Launcher[];
+export declare function dashboardLauncherList(root?: string): Launcher[];
+export declare const MISSING_DEFAULT_LAUNCHER_ERROR = "sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {\"sessions\":{\"defaultLauncher\":\"claude\"}})";
+export declare function defaultLauncher(root?: string): string;
+export declare function launcherDefault(root?: string): LauncherDefault;
+export declare function resolveLauncher(name: string, root?: string): Launcher;