@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/hosts/codex/native.d.ts

@@ -0,0 +1,345 @@
+import { type NativeReply, type NativeEvent, type NativeEntry } from './protocol.js';
+export interface TransportOptions {
+    cwd: string;
+    codexBin?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    args?: never;
+    deadlineMs?: number;
+    maxBytes?: number | undefined;
+    controlled?: boolean;
+    initialize?: boolean;
+    onServerRequest?: (request: {
+        id: string | number;
+        method: string;
+        params: unknown;
+    }) => Record<string, unknown>;
+}
+interface RequestLog {
+    id: string;
+    method: string;
+    at: string;
+    ok: boolean;
+    code?: string | null;
+}
+interface StopOptions {
+    termMs?: number | undefined;
+    killMs?: number | undefined;
+}
+export type CodexTransport = Awaited<ReturnType<typeof openCodexTransport>>;
+export interface AttemptOptions {
+    taskRoot: string;
+    subtaskId: string;
+    attempt: number;
+    ownerEpoch: number;
+    agentId: string;
+    sessionId: string;
+    threadId: string;
+    turnId: string;
+    cwd: string;
+    transport: CodexTransport;
+    timeoutMs?: number;
+    reason?: string;
+    evidenceDir?: string;
+    stopTermMs?: number;
+    stopKillMs?: number;
+}
+export interface HistoryOptions extends TransportOptions {
+    threadId: string;
+    turnId?: string;
+    timeoutMs?: number;
+    requireCompleted?: boolean;
+}
+export interface CodexObservation {
+    schema: string;
+    status: string;
+    claims_retained: boolean;
+    blockers?: string[];
+    detail?: string | null;
+    evidence?: Record<string, unknown>;
+    native?: {
+        turn_status?: string | null;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare class CodexNativeRefusal extends Error {
+    readonly status: string;
+    readonly code: string;
+    readonly detail: string | null;
+    constructor(status: string, code: string, detail?: string | null);
+}
+/**
+ * Own one `codex app-server --stdio` child and speak bounded JSONL with it. Opening is a local
+ * no-inference process start; `initialize` performs no model work.
+ */
+export declare function openCodexTransport(options: TransportOptions): Promise<Readonly<{
+    schema: "harness-collab/codex-native/1";
+    identity: Readonly<{
+        kind: "codex-app-server-stdio";
+        argv: string[];
+        cwd: string;
+        pid: number | null;
+        client_info: Readonly<{
+            name: "harness-collab-codex-native";
+            version: "1";
+        }>;
+        opened_at: string;
+        model_inference: "none";
+        admitted_launcher: false;
+        scope: "controlled-owned-group" | "default-process";
+    }>;
+    pid: number | null;
+    request: (method: string, params: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }) => Promise<NativeReply>;
+    notify: (method: string, params: Record<string, unknown>) => void;
+    events: () => NativeEvent[];
+    requestLog: () => RequestLog[];
+    serverRequestsRefused: () => {
+        id: string | number;
+        method: string;
+        at: string;
+    }[];
+    fatal: () => CodexNativeRefusal | null;
+    requestIds: () => string[];
+    ownedThread: (threadId: string) => boolean;
+    ownedTurn: (threadId: string, turnId: string) => boolean;
+    owned: (threadId: string, turnId: string) => boolean;
+    createdThreads: () => string[];
+    createdTurns: () => {
+        threadId: string;
+        turnId: string;
+    }[];
+    waitForNotification: (predicate: (event: NativeEvent) => boolean, opts?: {
+        timeoutMs?: number;
+        fromIndex?: number;
+    }) => Promise<NativeEvent>;
+    initialize: () => Promise<NativeReply>;
+    /** Explicit low-level fixture creation. Never called by query/cancel/recover. */
+    startThread: (params: Record<string, unknown> & {
+        cwd: string;
+    }) => Promise<{
+        threadId: string;
+        thread: import("./protocol.js").NativeThread;
+    }>;
+    /** Explicit low-level fixture creation. Never called by query/cancel/recover. */
+    startTurn: (params: Record<string, unknown> & {
+        threadId: string;
+    }) => Promise<{
+        threadId: string;
+        turnId: string;
+        turn: NativeEntry;
+    }>;
+    /**
+     * Explicit native shell turn on an owned, idle thread. This performs no model request: it
+     * runs a local shell command through the app-server's own user-shell surface. The event
+     * wait is installed before the request, so a `turn/started` that precedes the empty
+     * acknowledgement is still correlated by thread and turn id.
+     */
+    startShellTurn: (params: {
+        threadId: string;
+        command: string;
+        waitMs?: number;
+        timeoutMs?: number;
+    }) => Promise<{
+        threadId: string;
+        turnId: string;
+        ack: NativeReply;
+        event: {
+            method: string;
+            seq: number;
+            at: string;
+        };
+        event_preceded_ack: boolean;
+        native_timeout_ms: number | null;
+    }>;
+    threadRead: (threadId: string, params?: {
+        includeTurns?: boolean;
+    }) => Promise<NativeReply>;
+    listTurns: (threadId: string, params?: {
+        itemsView?: string;
+        sortDirection?: string;
+        limit?: number;
+    }) => Promise<NativeReply>;
+    listItems: (threadId: string, params?: {
+        turnId?: string;
+        sortDirection?: string;
+        limit?: number;
+    }) => Promise<NativeReply>;
+    /**
+     * Frozen runtime capability. `stop` terminates ONLY the owned process group created for a
+     * controlled transport (bounded TERM then KILL) and positively re-observes the group. In
+     * default mode it refuses; it never releases resources and never signals a caller-supplied
+     * pid/pgid. Descendants that escaped the group via setsid are outside this guarantee.
+     */
+    runtime: Readonly<{
+        scope: "controlled-owned-group" | "default-process";
+        controlled: boolean;
+        stop: (stopOptions?: StopOptions) => Promise<{
+            scope: string;
+            child_pid: number | null;
+            group_observed: boolean;
+            group_live: boolean;
+            live_members: number[];
+            parent_exited: boolean;
+            stopped: boolean;
+            term_sent: boolean;
+            kill_sent: boolean;
+            remaining: {
+                pid: number;
+                state: string;
+                start_identity: string;
+            }[];
+            note: string;
+        }>;
+        /**
+         * Read-only snapshot of the owned root and its actual descendant groups (they may live in
+         * their own process groups, as a real native user-shell does). Frozen opaque token backed
+         * by private state; only `stopTree` accepts it, and the snapshot is privately bound to the
+         * exact owned group handle that captured it.
+         */
+        snapshotTree: () => Readonly<{
+            scope: "owned-descendant-tree-snapshot";
+            captured_at: string;
+            original_pgid: number;
+            root: {
+                pid: number;
+                pgid: number;
+                start_identity: string;
+            };
+            descendants: {
+                pid: number;
+                ppid: number;
+                pgid: number;
+                start_identity: string;
+            }[];
+            groups: {
+                pgid: number;
+                member_count: number;
+            }[];
+        }>;
+        /**
+         * Stops only the groups captured in this exact snapshot and only when this transport's own
+         * owned group captured it. Members are re-verified against their captured PID + start
+         * identity and captured PGID before TERM, again before any KILL escalation, and once more
+         * before a positive `stopped: true` proof.
+         */
+        stopTree: (snapshot: unknown, stopOptions?: StopOptions) => Promise<{
+            scope: string;
+            original_pgid: number;
+            root_pid: number;
+            groups: number[];
+            targeted_groups: number[];
+            stopped: boolean;
+            already_stopped: boolean;
+            term_sent: boolean;
+            kill_sent: boolean;
+            group_observed: boolean;
+            escalation_refused: string;
+            remaining: never[];
+        } | {
+            scope: string;
+            original_pgid: number;
+            root_pid: number;
+            groups: number[];
+            targeted_groups: number[];
+            stopped: boolean;
+            already_stopped: boolean;
+            term_sent: boolean;
+            kill_sent: boolean;
+            group_observed: boolean;
+            escalation_refused: string;
+            escalation_detail: string;
+            remaining: {
+                pid: number;
+                pgid: number;
+                state: string;
+                start_identity: string;
+            }[];
+        } | {
+            scope: string;
+            original_pgid: number;
+            root_pid: number;
+            groups: number[];
+            targeted_groups: number[];
+            stopped: boolean;
+            already_stopped: boolean;
+            term_sent: boolean;
+            kill_sent: boolean;
+            group_observed: boolean;
+            final_proof_refused: string;
+            final_proof_detail: string;
+            remaining: {
+                pid: number;
+                pgid: number;
+                state: string;
+                start_identity: string;
+            }[];
+        } | {
+            scope: string;
+            original_pgid: number;
+            root_pid: number;
+            groups: number[];
+            targeted_groups: number[];
+            stopped: boolean;
+            already_stopped: boolean;
+            term_sent: boolean;
+            kill_sent: boolean;
+            remaining: {
+                pid: number;
+                pgid: number;
+                state: string;
+                start_identity: string;
+            }[];
+            group_observed: boolean;
+        }>;
+    }>;
+    close: () => Promise<{
+        exit_code: number | null;
+        signal: NodeJS.Signals | null;
+        parent_exited: boolean;
+        stream_closed: boolean;
+        streams_detached: boolean;
+        killed_after_eof_timeout: boolean;
+        signaled_kill: boolean;
+        request_ids: string[];
+        server_requests_refused: number;
+    }>;
+}>>;
+/** In-flight status of one exact recorded attempt on its owned original transport and turn. */
+export declare function queryCodexAttempt(options: AttemptOptions): Promise<CodexObservation>;
+/**
+ * Requests cancellation of one exact recorded attempt. Requires a fresh active observation on
+ * the owned original transport, records the CANCEL intent, invokes `turn/interrupt` with the
+ * exact ids, and accepts only terminal `turn/completed` with `interrupted` as evidence - even
+ * if it precedes the interrupt response. Claims stay held and no CANCELLED is sent; any failure
+ * after the recorded intent still returns `reconciliation_required: true`.
+ */
+export declare function cancelCodexAttempt(options: AttemptOptions): Promise<CodexObservation>;
+/**
+ * Recovery of a completed turn whose notification was lost. Only the exact requested terminal
+ * turn is accepted, and it must carry a usable original native result: a model agent message or
+ * an explicit successful native shell command output. Nothing is synthesized.
+ */
+export declare function recoverCodexCompleted(options: AttemptOptions): Promise<CodexObservation>;
+/**
+ * Persisted-history read on a FRESH server. `notLoaded` describes only this server's load state,
+ * never the original execution. The canonical thread cwd is always validated against the
+ * requested cwd, and with `requireCompleted` only an exact completed turn with a usable native
+ * result is accepted.
+ */
+export declare function queryPersistedHistory(options: HistoryOptions): Promise<CodexObservation>;
+/**
+ * Cancellation plus controlled-runtime stop for one exact recorded attempt.
+ *
+ * The native handshake (CANCEL intent + `turn/interrupt` + observed terminal event) is reported
+ * separately from the group/process stop proof. The owned process group is stopped ONLY when the
+ * cancellation intent was actually recorded, and only for a controlled transport that created
+ * the original runtime. Claims are retained, no CANCELLED is sent, and the result always carries
+ * `reconciliation_required: true` once the intent exists. A non-terminal native handshake may
+ * still require the controlled shutdown; it is never reported as a native interruption.
+ * Task-specific evidence (known child pids/heartbeats) remains the caller's responsibility:
+ * an empty owned group is not proof that every OS side effect stopped.
+ */
+export declare function cancelAndStopCodexAttempt(options: AttemptOptions): Promise<CodexObservation>;
+export {};