@osdlc/agent-seat 0.0.0-stage → 0.7.1

package/dist/harness.d.ts

@@ -0,0 +1,305 @@
+/**
+ * The harness axis — pure argv-building + naming for whichever coding-agent
+ * CLI a host opens a session in.
+ *
+ * `Harness` is independent of `HostName` (`contract.ts`): every host composes
+ * `harnessArgv` to run whichever harness the caller asked for.
+ *
+ * Not `@osdlc/agent-call`'s planner: that plans HEADLESS calls (`claude -p`,
+ * `codex exec`) whose output a program reads. A session is the opposite — a
+ * person sits in it — so the argv is the bare CLI with the first message,
+ * plus the Claude-only flags in {@link claudeSessionArgv}.
+ *
+ * This module also carries harness-specific machinery: codex's own on-disk
+ * session-index lookup (`codexSessionsDir` et al. — harness-specific, not
+ * host-specific, so it belongs on this axis), `wrapperSession`, the one body
+ * every wrapper host's `session()` shares ("build argv, run it, best-effort
+ * resolve a session id"), and `harnessNativeSend`, a per-harness
+ * message-injection mechanism independent of any host (`contract.ts`'s
+ * `Host.send` is the host-level counterpart).
+ */
+import { z } from 'zod';
+import { type ModelChoice } from '@osdlc/agent-call';
+import { type CommandRunner, type EnvOverrides } from '@osdlc/command-seam';
+import { type CommandRequest, type HostName, type SendReceipt, type SessionRequest } from './contract.ts';
+/**
+ * The coding-agent CLI a session runs, by its tool id: a built-in one
+ * (`BUILTIN_HARNESSES` from `@osdlc/detect-harness`, e.g. `claude`) or one a caller declares. This file
+ * builds the interactive argv ({@link INTERACTIVE_ARGV}).
+ */
+export type Harness = string;
+/**
+ * The schema a harness field validates against. A tool id, not a closed list,
+ * since a caller may run a tool of its own.
+ */
+export declare const HarnessSchema: z.ZodString;
+/**
+ * `value` (what a host reports running in a pane) as a built-in harness id, or null when
+ * it names none. An alias or binary name maps to its id (`cursor-agent` → `cursor`), by
+ * `harnessId` from `@osdlc/detect-harness`.
+ */
+export declare function harnessOrNull(value: unknown): Harness | null;
+/** Whether an interactive argv can be built for `tool`. */
+export declare function hasInteractiveArgv(tool: string): boolean;
+/**
+ * The argv that opens `harness`, run as `binary` (a name on PATH or an
+ * absolute path), interactively with `prompt` as its first message
+ * ({@link INTERACTIVE_ARGV}). A resolved `choice` adds its launch mode,
+ * model and effort flags (`modelArgs`, `@osdlc/agent-call`) before the `--` guard; a
+ * tool with no model or effort flags wired throws on a choice rather than
+ * dropping it. Throws for a tool with no interactive launch.
+ *
+ * `injected` is the argv a per-launch observation adds (pi's
+ * `--session-id` and `-e <extension>`); it sits before the prompt.
+ */
+export declare function harnessArgv(harness: Harness, binary: string, prompt: string, claude?: ClaudeLaunchFlags, choice?: ModelChoice, injected?: readonly string[]): string[];
+/** Session flags only `claude` takes; a caller can store them to resume with the same flags. */
+export declare const ClaudeSessionFlagsSchema: z.ZodObject<{
+    appendSystemPrompt: z.ZodOptional<z.ZodString>;
+    plugins: z.ZodOptional<z.ZodObject<{
+        dirs: z.ZodArray<z.ZodString>;
+        disable: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    hookCommand: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The parsed {@link ClaudeSessionFlagsSchema}: the session flags only `claude` takes.
+ */
+export type ClaudeSessionFlags = z.infer<typeof ClaudeSessionFlagsSchema>;
+/** {@link ClaudeSessionFlags} plus what only a fresh launch passes: the session id to preset. */
+export interface ClaudeLaunchFlags extends ClaudeSessionFlags {
+    /**
+     * The harness's own session id to preset (`claude --session-id`), so its id and transcript
+     * are known at launch. Never with a resume. Not the caller's id: that is
+     * `SessionRequest.sessionId`.
+     */
+    harnessSessionId?: string | undefined;
+}
+/**
+ * The Claude Code hook events the caller listens to. Everything is async except
+ * `SessionEnd`, which has to finish its write before Claude exits (its budget
+ * is the hook's own `timeout`). `PreToolUse` is matched to `AskUserQuestion`
+ * alone: the question is what puts the agent in `waiting_for_input` there, and
+ * a hook on every tool call would cost a process each. `PermissionRequest` and
+ * `StopFailure` mark a tool-permission prompt and a turn that ended on an API error.
+ */
+export declare const CLAUDE_HOOK_EVENTS: {
+    readonly SessionStart: {
+        readonly async: true;
+    };
+    readonly UserPromptSubmit: {
+        readonly async: true;
+    };
+    readonly PreToolUse: {
+        readonly async: true;
+        readonly matcher: "AskUserQuestion";
+    };
+    readonly PermissionRequest: {
+        readonly async: true;
+    };
+    readonly PostToolUse: {
+        readonly async: true;
+    };
+    readonly PostToolUseFailure: {
+        readonly async: true;
+    };
+    readonly Stop: {
+        readonly async: true;
+    };
+    readonly StopFailure: {
+        readonly async: true;
+    };
+    readonly SubagentStart: {
+        readonly async: true;
+    };
+    readonly SubagentStop: {
+        readonly async: true;
+    };
+    readonly Notification: {
+        readonly async: true;
+    };
+    readonly PreCompact: {
+        readonly async: true;
+    };
+    readonly PostModelSwitch: {
+        readonly async: true;
+    };
+    readonly SessionEnd: {
+        readonly async: false;
+    };
+};
+/** The `hooks` settings object that runs `command` for every {@link CLAUDE_HOOK_EVENTS} event. */
+export declare function claudeHookSettings(command: string): {
+    hooks: Record<string, unknown[]>;
+};
+/** The argv for {@link ClaudeLaunchFlags}, shared by the launches and {@link claudeResumeArgv}. */
+export declare function claudeSessionArgv(flags: ClaudeLaunchFlags): string[];
+/**
+ * `claude --resume=<id>` plus the launch's session flags, so a resumed session
+ * keeps its plugins and prompt pin. Does not validate `id`; `claudeResumeFlag`
+ * (`@osdlc/agent-call`) binds it with `=`.
+ */
+export declare function claudeResumeArgv(id: string, flags?: ClaudeSessionFlags): string[];
+/**
+ * Whether `harness`'s CLI, `binary` (a name on PATH or an absolute path), is
+ * on PATH. A synchronous lookup that spawns nothing. Only a PATH hit counts: an
+ * installed app bundle (Cursor.app) gives a session nothing to run.
+ */
+export declare function harnessAvailable(_harness: Harness, binary: string): boolean;
+/** {@link SendReceipt}'s shape, reused here under its own name: both answer "did the message get in", one via a host, one via the harness's own process/daemon directly. */
+export type NativeSendResult = SendReceipt;
+/** `NATIVE_SEND[harness]`, called if present; `null` — not a thrown error — when the harness has no known native-send mechanism at all (see the map's own doc for which). */
+export declare function harnessNativeSend(harness: Harness, sessionId: string, text: string, opts?: {
+    runner?: CommandRunner | undefined;
+}): NativeSendResult | null;
+/** `~/.codex/sessions` (or under an injected `codexHome`, for tests). */
+export declare function codexSessionsDir(codexHome?: string): string;
+/**
+ * Recursively finds every `rollout-*.jsonl` file under `dir`. Missing/
+ * unreadable dirs yield `[]`. Exported so a caller that needs the transcript
+ * path can reuse this walk; {@link findCodexSessionId} returns only the id.
+ */
+export declare function walkRolloutFiles(dir: string): string[];
+/** The `cwd`/session-id pair recorded in a rollout file's first (`session_meta`) line, or null if unparsable. */
+export declare function parseRolloutMeta(firstLine: string): {
+    cwd: string;
+    sessionId: string;
+} | null;
+/**
+ * How far before the launch instant a rollout's creation may fall and still
+ * count as this launch's: the file name has one-second resolution, and file
+ * timestamps come from a coarser clock than `Date.now()`, so a file created
+ * just after the launch can read a little before it.
+ */
+export declare const ROLLOUT_CREATED_MARGIN_MS = 2000;
+/**
+ * The instant in a rollout file name, `rollout-<YYYY-MM-DDTHH-MM-SS>-<uuid>.jsonl`,
+ * or null when the name has none. Read as LOCAL time: codex stamps the name
+ * (and the `yyyy/mm/dd` buckets) from its local clock, so this is exact only
+ * when codex ran in the same time zone as this process.
+ */
+export declare function rolloutNameTimeMs(path: string): number | null;
+/**
+ * When a rollout file was created: its birthtime when the file system records
+ * one (a birthtime of 0 means it does not), else the time in its name, else its
+ * mtime. The name is read in this process's time zone ({@link rolloutNameTimeMs}),
+ * so it is off by the zone difference when codex ran elsewhere; a name time
+ * later than the file's last write (beyond the margin) cannot be right and
+ * falls through to the mtime.
+ */
+export declare function rolloutCreatedMs(path: string, stats: {
+    birthtimeMs: number;
+    mtimeMs: number;
+}): number;
+/**
+ * The session id of the newest candidate (by creation instant) created no more
+ * than {@link ROLLOUT_CREATED_MARGIN_MS} before `sinceMs` whose rollout `cwd`
+ * names the same directory as `opts.cwd` (compared as real paths, so a cwd
+ * reached through a symlink matches), or null when none qualifies. Takes
+ * canned candidates, so a test needs no rollout files.
+ */
+export declare function newestRolloutSessionIdSince(candidates: {
+    firstLine: string;
+    createdMs: number;
+}[], opts: {
+    sinceMs: number;
+    cwd: string;
+}): string | null;
+/** How long, and with which clock, a session-id lookup keeps looking for a file not written yet. */
+export interface SessionIdWaitOptions {
+    /** How long to keep looking, ms; 0 (the default) looks once. */
+    waitMs?: number | undefined;
+    /** Pause between looks, ms; default 250. */
+    pollMs?: number | undefined;
+    /** Blocks for the given ms; default `sleepSync`. */
+    sleep?: ((ms: number) => void) | undefined;
+    /** The clock, ms; default `Date.now`. */
+    now?: (() => number) | undefined;
+    /** Codex's home directory; default `~/.codex`. */
+    codexHome?: string | undefined;
+}
+/**
+ * The `yyyy/mm/dd` folders under `sessionsDir` a rollout created between
+ * `fromMs` and `toMs` can sit in. codex names a folder by its own local date,
+ * which can differ from this process's by up to {@link ROLLOUT_NAME_ZONE_SLACK_MS},
+ * so the range is widened by that much on each side (one or two days).
+ */
+export declare function rolloutDayDirs(sessionsDir: string, fromMs: number, toMs: number): string[];
+/**
+ * The codex session started in `cwd` at or after `sinceMs`
+ * ({@link newestRolloutSessionIdSince}), or null.
+ *
+ * Reads codex's own on-disk session index. `~/.codex/session_index.jsonl` is
+ * NOT used: it only records threads that were given a name. Instead this scans
+ * the rollout files, `~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl`, in
+ * the date folders from the launch through now ({@link rolloutDayDirs}), for
+ * the session created at or after the launch whose first line, a
+ * `session_meta` record
+ * (`{"type":"session_meta","payload":{"session_id":"<uuid>","cwd":"<path>",…}}`),
+ * names `cwd`. The cwds are compared as real paths: codex records its
+ * process's directory with symlinks resolved.
+ *
+ * Selection is by the rollout's creation instant ({@link rolloutCreatedMs}),
+ * not its mtime: another codex session in the same cwd keeps appending to its
+ * own rollout, so its mtime would pass a launch-time cutoff. This is still
+ * best-effort: two codex sessions launched from the same cwd within a couple of
+ * seconds of each other (or one launched in that cwd while a waiting host holds
+ * ours) can be mistaken for each other. No local signal tells them apart.
+ *
+ * With `waitMs`, keeps looking that long for a rollout file codex has not
+ * written yet; a file ruled out once (created too early, or another cwd) is not
+ * read again. `listFiles` and `codexHome` are injectable so a test needs no
+ * real `~/.codex/`.
+ */
+export declare function findCodexSessionId(sinceMs: number, cwd: string, opts?: {
+    listFiles?: (() => string[]) | undefined;
+} & SessionIdWaitOptions): string | null;
+/** How long {@link wrapperSession} waits for the agent to record its session after a host returned early. */
+export declare const SESSION_ID_WAIT_MS = 3000;
+/**
+ * `argv` carrying `env`, so the vars reach the process whatever terminal runs it.
+ * POSIX: prefixed with `env [-u K ...] [K=V ...]`. win32 has no `env`, so the
+ * argv becomes a `powershell -Command` that sets (`$env:K='V'`) or clears
+ * (`Remove-Item Env:K`) each variable and then runs the original command.
+ *
+ * Windows limits (not run on Windows): `powershell` is Windows PowerShell 5.1,
+ * which passes an argument containing `"` to a native program without escaping
+ * it (the program sees it split, or with the quotes gone) and drops an empty
+ * argument; and `-Command` turns the program's exit code into 0 or 1. Every
+ * word of the command is single-quoted, even one that needs no quoting: Windows
+ * PowerShell 5.1 drops a bare `--` (the guard `harnessArgv` puts before the
+ * prompt) and splits a bare `-name.value`, which a quoted word avoids.
+ */
+export declare function withEnv(argv: string[], env: EnvOverrides | undefined, platform?: NodeJS.Platform): string[];
+/**
+ * The shared body of every wrapper host's `session()`: build `harnessArgv`
+ * under `req.env`, run it, best-effort resolve a session id.
+ *
+ * Most hosts return as soon as the pane exists, before the agent has recorded
+ * its session, so after a clean launch the lookup keeps trying for
+ * `opts.waitMs` (default {@link SESSION_ID_WAIT_MS}). With `opts.hostWaited`
+ * (the host held the launch until the agent exited) it looks once.
+ *
+ * @param terminal The calling host's own `terminal()`, which opens its
+ *   terminal or workspace.
+ */
+export declare function wrapperSession(terminal: (req: CommandRequest) => number, req: SessionRequest, opts?: SessionIdWaitOptions & {
+    hostWaited?: boolean | undefined;
+}): {
+    exitCode: number;
+    harnessSessionId: string | null;
+};
+/**
+ * The `session` part of a host whose `terminal` part opens the harness: assign
+ * it as `session: sessionViaTerminal`. `this` is the host the part is called on,
+ * so the host's own `terminal` runs; a host that has none throws rather than
+ * start nothing. A host honouring `req.wait` returns only once the agent
+ * exited, so the session-id lookup does not wait.
+ */
+export declare function sessionViaTerminal(this: {
+    name?: HostName;
+    terminal?: (req: CommandRequest) => number;
+}, req: SessionRequest): {
+    exitCode: number;
+    harnessSessionId: string | null;
+};