tickmarkr 2.0.0 → 2.1.1

package/dist/drivers/orca.d.ts

@@ -0,0 +1,189 @@
+import { type ShResult } from "../run/git.js";
+import { type ExecutorDriver, type NotifyOpts, type Slot, type SlotOpts } from "./types.js";
+/** The response families the ONE shared envelope parser serves. There is no second JSON seam. */
+export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close"];
+export type OrcaFamily = (typeof ORCA_RESPONSE_FAMILIES)[number];
+export declare const STALE_HANDLE_CODE = "terminal_handle_stale";
+export declare const NOT_WRITABLE_CODE = "terminal_not_writable";
+/** The ONLY terminal status that licenses reading a terminal's bytes or its agent state. */
+export declare const RUNNING_STATUS = "running";
+export declare const STATUS_GOVERNED_METHODS: readonly ["read", "waitOutput", "status", "waitAgentStatus"];
+export interface OrcaExec {
+    (args: string[], cwd: string, timeoutMs?: number): Promise<ShResult>;
+}
+export interface OrcaTimeSource {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/** Every failure this driver produces is explicit and carries the raw bytes that produced it. */
+export declare class OrcaError extends Error {
+    readonly family: string;
+    readonly reason: string;
+    readonly raw: string;
+    readonly code?: string;
+    readonly runtimeId?: string;
+    constructor(family: string, reason: string, raw: string, opts?: {
+        code?: string;
+        runtimeId?: string;
+    });
+}
+/** The slot cannot be addressed: dead/unknown terminal record, or a handle that cannot be recovered
+ *  to exactly one owned terminal in the slot's own worktree. Never a silent false or empty string. */
+export declare class OrcaUnavailableError extends OrcaError {
+    readonly terminalStatus?: string | undefined;
+    constructor(family: string, reason: string, raw: string, terminalStatus?: string | undefined);
+}
+export interface OrcaEnvelope {
+    result: Record<string, unknown>;
+    runtimeId: string;
+    raw: string;
+}
+/**
+ * The one JSON seam. Fails CLOSED on every degenerate response — empty, unparseable (a truncated
+ * body lands here), non-object, no boolean `ok`, `ok:false`, `ok:true` with no result object, or a
+ * successful response without a usable `_meta.runtimeId` —
+ * and preserves the raw bytes on the thrown error for diagnostics. Callers never see a partial
+ * envelope, so no caller can reinterpret a parse failure as empty output, an unknown-but-successful
+ * status, or a successful close.
+ */
+export declare function parseEnvelope(family: OrcaFamily, stdout: string, raw?: string): OrcaEnvelope;
+/** The worktree a terminal record binds to. The spike pinned the record's shape but not this key's
+ *  spelling, so the known aliases are accepted and nothing else — a record with none is unbound,
+ *  which fails every identity comparison below rather than passing one by default. */
+export declare function terminalWorktree(term: Record<string, unknown>): string | undefined;
+/**
+ * The same checkout under two spellings. git hands tickmarkr one (`/tmp/...` on darwin, or anything
+ * below a symlinked parent) while Orca answers the canonicalized one (`/private/tmp/...`), and
+ * `resolve()` collapses `..` but never a symlink — so string equality on resolved paths reports two
+ * different checkouts and leaves a perfectly valid slot unreacquirable after a runtime restart.
+ * Identity is FILESYSTEM identity. A path that does not exist has no filesystem identity to read, so
+ * it keeps its resolved spelling: deterministic, and still comparable to another spelling of itself.
+ */
+export declare function canonicalWorktreePath(path: string): string;
+/** Conservative agent-state mapping over orca's ACTUAL surfaces: `blocked` only when the show
+ *  record reports agentWait:true, `idle` only when the `terminal wait --for tui-idle` condition is
+ *  satisfied. The recorded 1.4.186 show response carries NO agent field at all — an absent signal
+ *  is "unknown", never a fabricated definite status. */
+export declare function mapAgentState(term: Record<string, unknown>, tuiIdle: boolean): string;
+/**
+ * The renderer hard-wraps long lines, paints margin chrome, and a cursor page boundary splits a
+ * marker exactly like a wrap does. `parseWorkerResult` (src/adapters/prompt.ts) already de-wraps
+ * trailers this way, so marker matching gets the same joined view beside the raw one.
+ * ponytail: joining every line can in principle glue two unrelated lines into a marker — the same
+ * tolerance parseWorkerResult has carried since v1.2; raw is matched first, so an unwrapped hit
+ * never depends on this.
+ */
+export declare function joinWrapped(raw: string): string;
+export interface OrcaDriverOpts {
+    bin?: string;
+    exec?: OrcaExec;
+    time?: OrcaTimeSource;
+    pageLines?: number;
+    pollMs?: number;
+    /** Bounded, seam-adjustable staleness window for runtime probes before mutations. */
+    probeStalenessMs?: number;
+}
+export declare class OrcaDriver implements ExecutorDriver {
+    id: string;
+    interactive: boolean;
+    private slots;
+    private n;
+    private bin;
+    private exec;
+    private time;
+    private pageLines;
+    private pollMs;
+    private probeStalenessMs;
+    constructor(opts?: OrcaDriverOpts);
+    private call;
+    /** The live runtime's identity, or an explicit failure. A missing or unreachable runtime is a
+     *  driver-level failure carrying the raw refusal — never a reachable-looking default. */
+    private runtimeEnv;
+    /** Explicit runtime probe. Also T3's doctor probe. */
+    probeRuntime(cwd?: string): Promise<string>;
+    slot(cwd: string, name: string, opts?: SlotOpts): Promise<Slot>;
+    /** Where to invoke the CLI for this slot's calls (see OrcaSlotState.dir). */
+    private cliCwd;
+    private state;
+    private latched;
+    private assertAvailable;
+    run(slot: Slot, cmd: string): Promise<void>;
+    private create;
+    /**
+     * Every terminal-addressed call — read AND write — goes through here, and the runtime identity is
+     * established BEFORE the runtime-scoped handle goes on the wire. Discarding a lookalike's answer
+     * after reading it is still having addressed it, so the probe comes first; the post-call check
+     * only closes the narrow race of a restart landing between probe and call. Same for an explicit
+     * `terminal_handle_stale`. Either way the driver relists the slot's exact worktree and replaces
+     * the handle exactly once, then re-issues the operation against the replacement.
+     */
+    private terminalOp;
+    private recover;
+    /** Validated READ terminal record, or an explicit unavailable failure. Called BEFORE any caller
+     *  looks at tail bytes — on every page, on every read-governed method. Read records are the one
+     *  place orca reports a literal `status` (recorded: "running" live, "exited" on the dead record). */
+    private validated;
+    /** Validated SHOW terminal record, or an explicit unavailable failure. The recorded 1.4.186 show
+     *  response reports liveness through connected/orphaned and carries NO status and NO agent field,
+     * so this is the status discipline's show leg: a terminal that cannot prove connected-and-not-
+     * orphaned is unavailable for state questions, exactly as a non-running read record is for bytes. */
+    private liveShowTerm;
+    private tailText;
+    private readPage;
+    /** A single UNPAGED tail read — exactly what the caller asked for and nothing more. Markers split
+     *  across cursor pages are not reassembled here; that is waitOutput's job. */
+    read(slot: Slot, lines: number): Promise<string>;
+    /**
+     * Bounded cursor-paged sweep into the slot's accumulated buffer. The first read of a slot carries
+     * no cursor: it is the ANCHOR, whose `oldestCursor` says where the retained buffer starts (its own
+     * tail is the newest lines, not the oldest, so it is not appended). Every page after it appends,
+     * and every one of them — anchor included — is status-validated before a single byte is matched.
+     */
+    private sweep;
+    waitOutput(slot: Slot, pattern: string, timeoutMs: number, opts?: {
+        regex?: boolean;
+    }): Promise<boolean>;
+    status(slot: Slot): Promise<string>;
+    /** One `terminal wait` through the full identity machinery. The recorded 1.4.186 elapsed answer
+     *  is rc 1 + ok:true + {handle, condition, satisfied:false, status:"running"}; it is "not yet"
+     *  only after this method validates all four fields. Any malformed/refused wait remains explicit. */
+    private waitCondition;
+    waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
+    notify(msg: string, opts?: NotifyOpts): Promise<void>;
+    close(slot: Slot): Promise<void>;
+    /**
+     * The one destructive call in this driver, for a slot's own terminal AND for a reconcile candidate
+     * alike. It goes through terminalOp deliberately: the live runtime identity is proven immediately
+     * BEFORE the handle goes on the wire, and a runtime that changed does not merely fail the close —
+     * the handle is DISCARDED and re-derived from the owned tab title in that exact checkout, where a
+     * handle value the new runtime happened to reissue to somebody else's terminal is refused by
+     * construction (recover()). Checking identity on the receipt afterwards could not undo a close.
+     */
+    private closeTerminal;
+    /**
+     * The WHOLE terminal table. `terminal list` caps rows at its own default and says so through
+     * `truncated`/`totalCount`; a capped listing is not an ownership snapshot, because the row it
+     * dropped is precisely the older run's leftover no later sweep would ever see again.
+     * ponytail: two asks, not a paging loop — `--limit` takes the whole table in one go, and a runtime
+     * that still reports truncated at totalCount rows is a listing this sweep declines to judge on.
+     */
+    private listAll;
+    /**
+     * Sweep tickmarkr-owned terminals down to `desired`. Ownership is decided ONLY by parseOwnedName
+     * over the owned TAB title, through the same panesToClose fold herdr uses (drivers/types.ts): an
+     * owned-and-undesired terminal closes whichever run — and whichever daemon — created it, and a
+     * title that does not parse is never a candidate however much it resembles one.
+     *
+     * The listing is UNSCOPED and layout-bearing. Unscoped because an older run's leftover sits in a
+     * checkout this run never knew, so a `--worktree`-filtered sweep is exactly how such a leftover
+     * survives forever. Layout-bearing because the owned title survives at TAB identity only — a list
+     * row's `title` is the shell-controlled pane title, and closing on that is how a foreign pane that
+     * happens to be running an owned-looking command gets killed.
+     *
+     * Cosmetic by contract: every failure is swallowed, per candidate and overall.
+     */
+    reconcile(desired: Set<string>, runId: string, opts?: {
+        spareLiveLlm?: boolean;
+    }): Promise<void>;
+    worktree(repo: string, branch: string, baseRef: string): Promise<string>;
+}