humanish 0.105.0 → 0.106.0

package/TELEMETRY.md

@@ -0,0 +1,112 @@
+# Telemetry
+
+humanish collects **anonymous** usage data by default, so that the people
+maintaining it can tell whether anyone gets to a working first run. It is
+disclosed the first time it happens, and you can switch it off in one command.
+
+This follows the convention the Next.js and Vercel CLIs established, with one
+difference: humanish is stricter about what may be collected, because a study's
+subject is your product and a lab id can name something you have not announced.
+
+## Why
+
+humanish shipped sixty-one releases without being able to answer _"does anyone
+get to a working first run?"_. The answer, when it finally arrived, came from an
+adoption post-mortem: the first live run had been impossible for months, because
+the starter labs shipped with a placeholder URL. Nobody reported it. Without
+telemetry, humanish cannot tell whether new users reach a working first run.
+
+## What is collected
+
+- which command ran (`run`, `lab run`, `init`, …)
+- the humanish version, your OS, your Node major version, whether you are in CI
+- whether the command succeeded (its exit code), and roughly how long it took
+  (a bucket such as `1-5m`, never an exact duration)
+- for a study: whether it was a dry run or live, its outcome (one of a fixed
+  set of words such as `passed`, `abandoned`, `all_passed`), which brain route
+  ran it (`provider-key`, `local-agent`, or `none` for a dry run), and which lab
+  ran, **only if it is one of the starter labs `humanish init` writes**
+- when a command fails: humanish's own error code (`HUMANISH_…`), never the
+  message. Which failure ends a first run is the question this exists to answer.
+- for CUA results with diagnostics: `diagnostic_category` is exactly one of
+  `preview`, `participant_outcome`, `session_interrupted`, `execution_error`,
+  `evidence_invalid`, `mixed`, or `unknown`. These describe the study result;
+  a participant outcome does not establish a target-app defect.
+- when recorded or derivable from a typed session ending, `stop_cause` is exactly
+  one of `provider_output_limit`, `provider_token_limit`, `time_limit`,
+  `spend_limit`, `study_spend_limit`, `provider_incomplete`, `provider_status`,
+  `provider_refused_prompt`, `harness_aborted`, `adapter_limit`,
+  `usage_unreported`, `unspecified_limit`, `mixed`, or `unknown`.
+  Older limits stay broad. Different participant endings remain mixed. No raw
+  error message or participant detail is sent. Absent diagnostics stay absent.
+
+Successful CUA previews report `contract_proof_only`; no participant was run.
+Failed previews report `error`. Live `all_passed`/`some_passed`/`none_passed`
+values remain pass summaries, not explanations of why a session ended.
+
+See the exact document that would be sent, for your machine, right now:
+
+```bash
+humanish telemetry status
+```
+
+Or watch it without sending anything:
+
+```bash
+HUMANISH_TELEMETRY_DEBUG=1 humanish run first-run
+```
+
+## What is never collected
+
+Your own lab ids and titles. Your subjects: repos, URLs, app names. Personas,
+missions, or any prompt text. Paths, working directories, hostnames, usernames.
+Run ids, evidence, screenshots, traces. Credential names or values. There is no
+field in the payload that could carry any of these. `src/cli/telemetry.ts` enforces
+the allowlist and `tests/cli/telemetry.test.ts` pins it.
+
+Your machine is identified by a random id generated locally on first use, tied
+to nothing.
+
+The request that carries an event has a source IP address, like any HTTP
+request. Three things keep it out of the dataset: every event asks the receiver
+not to derive a location from it (`$geoip_disable`, visible in the document
+above), every event asks for no person profile to be built for the machine id
+(`$process_person_profile: false`), and the receiving project is set to
+discard the client address at ingestion. Events sent by versions before 0.66.0 did not carry the opt-out, so
+the receiver attached a city-level location to them; that setting has been
+turned off for the project and the doc said "anonymous" while it was on. This page
+records that so the fix is not silent.
+
+## What never reports
+
+- **humanish's own repository checkout.** A command started inside a checkout of this repository
+  (a `package.json` named `humanish` above the working directory, outside `node_modules`) sends
+  nothing, and so does a CLI whose own files live inside such a checkout, wherever it was started
+  from. The second rule exists because tests, the TUI smoke and the release dogfood spawn
+  `dist/cli.js` into temporary directories; one development machine put 1,251 of its own events
+  into the adoption count before that rule existed (2026-08-31 to 2026-09-03). An installed copy
+  lives under `node_modules` and is never matched by either rule.
+- **Continuous integration** still reports, with `ci: true`, because an adopter's pipeline is real
+  usage; the dashboards separate it.
+- **Study participants.** A humanish CLI that a study participant runs inside a sandbox carries
+  `studyParticipant: true` and is excluded from adoption counts.
+
+## How to opt out
+
+```bash
+humanish telemetry disable
+```
+
+or set either of these in your environment:
+
+```bash
+DO_NOT_TRACK=1
+HUMANISH_TELEMETRY_DISABLED=1
+```
+
+`DO_NOT_TRACK` is the cross-tool standard and humanish honours it without any
+humanish-specific configuration. The opt-out is stored under your user config
+(`~/.config/humanish/telemetry.json`), never inside the project you are studying.
+
+Telemetry never blocks, slows, or fails a command: it is fire-and-forget, bounded
+by a two-second timeout, and every error inside it is swallowed.

package/dist/actors/affordance.d.ts

@@ -0,0 +1,56 @@
+import type { CuaAction } from "./computer-use/loop.js";
+export declare const AFFORDANCE_CLASS_SCHEMA = "humanish.affordance-use.v1";
+/**
+ * The affordance classes, named after the surrounding literature rather than invented here:
+ * "naturalistic actions" (AndroidWorld) for the human-modality subset, "nav" (BrowserGym) for
+ * direct navigation, "shortcut" (MAS-Bench) for a non-UI route to the same outcome.
+ */
+export type AffordanceClass = 
+/** Pointer or drag interaction with what is rendered on screen — the naturalistic core. */
+"pointer"
+/** Keyboard input into the page: typed text that is not a URL and not script. */
+ | "keyboard"
+/** Spoken input sent through the participant's admitted microphone path. */
+ | "speech"
+/** Direct navigation by URL (the `nav` subset). A human affordance; see the note above. */
+ | "url-navigation"
+/** Script execution via the address bar (a `javascript:` URL). Not a human affordance. */
+ | "script-execution"
+/** Developer tooling opened by keyboard shortcut. Not a human affordance. */
+ | "devtools"
+/**
+ * A browser surface rather than the product: chrome://, about:, view-source:, devtools:, file:,
+ * edge:, brave:.
+ */
+ | "browser-internal"
+/** The actor observing or pausing rather than acting: screenshots, waits, pointer moves. */
+ | "observation";
+/** Classes that a person operating this product through its own surfaces could produce. */
+export declare const NATURALISTIC_AFFORDANCE_CLASSES: readonly AffordanceClass[];
+/** Classes that reach past the rendered product surface. Recorded, never blocked. */
+export declare const SHORTCUT_AFFORDANCE_CLASSES: readonly AffordanceClass[];
+export interface AffordanceObservation {
+    affordance: AffordanceClass;
+    /**
+     * A public-safe hint about WHY this class was assigned, when one exists — a URL scheme or the
+     * devtools chord. Never the typed text, never a full URL (which can carry a session token).
+     */
+    signal?: string;
+}
+/** Aggregate per-run record: how many actions fell into each class. */
+export interface AffordanceUse {
+    schema: typeof AFFORDANCE_CLASS_SCHEMA;
+    /** Counts by class; a class with zero actions is omitted so the record stays small and honest. */
+    counts: Partial<Record<AffordanceClass, number>>;
+    /** Total classified actions (the denominator for any rate an adopter computes). */
+    total: number;
+    /** Convenience roll-up: actions in the shortcut classes. Zero is a meaningful, common value. */
+    shortcutTotal: number;
+}
+/**
+ * Classify one computer-use action. PURE: same action in, same class out, no I/O, no clock. The
+ * returned signal is public-safe (a scheme or a chord), never the action's text.
+ */
+export declare function classifyCuaAction(action: CuaAction): AffordanceObservation;
+/** Fold a sequence of observations into the per-run aggregate. */
+export declare function summarizeAffordanceUse(observations: readonly AffordanceObservation[]): AffordanceUse;

package/dist/actors/affordance.js

@@ -0,0 +1,155 @@
+// Affordance classification (#369): WHICH KIND of route an actor took to accomplish a step.
+//
+// Why this exists. A computer-use actor in a human-persona study typed a `javascript:` URL into
+// the address bar to get past a step, and the run finished green: the actor routed around the
+// friction the study existed to measure, and nothing in the evidence said so. Whether that is a
+// defect depends on a question the bundle never recorded — who is this study's user? For a human
+// population it invalidates the run; for an agent-facing product whose users ARE agents the same
+// act is faithful, and the fact the agent reached for it is itself a finding about how legible
+// the surface is. So the harness records the class and bakes NO verdict: the adopter's scorer
+// (review.scorer.ref) decides what it means, because that judgment is product semantics.
+//
+// Two design facts drive the shape:
+//
+//  1. The computer-use action space is mouse + keyboard only — there is no `goto` action. Typing a
+//     URL is a `type` action whose TEXT happens to be a URL, and typing script is a `type` action
+//     whose text happens to start with `javascript:`. Classification therefore has to look at the
+//     typed text, which exists only at dispatch time.
+//  2. Raw typed text is never persisted (describeCuaAction deliberately renders `type [N chars]`),
+//     so this module returns a CLASS and at most a scheme-shaped signal — never the text. The
+//     class is public-safe by construction.
+//
+// Direct URL navigation is deliberately its own class and NOT lumped with script execution:
+// `load(url)` appears in 99.4% of 2,337 real human web demonstrations (WebLINX), so address-bar
+// use is ordinary human behavior. The anomalous classes are script execution and developer
+// tooling. See docs/principles/actor-fidelity.md for the evidence and the scoping of the claim.
+export const AFFORDANCE_CLASS_SCHEMA = "humanish.affordance-use.v1";
+/** Classes that a person operating this product through its own surfaces could produce. */
+export const NATURALISTIC_AFFORDANCE_CLASSES = [
+    "pointer",
+    "keyboard",
+    "speech",
+    "url-navigation",
+    "observation",
+];
+/** Classes that reach past the rendered product surface. Recorded, never blocked. */
+export const SHORTCUT_AFFORDANCE_CLASSES = [
+    "script-execution",
+    "devtools",
+    "browser-internal",
+];
+// A `javascript:` URL typed into the address bar. Tolerates leading whitespace and mixed case;
+// the scheme is what matters, not the payload (which is never recorded).
+const SCRIPT_URL = /^\s*(?:javascript|data):/i;
+// Browser-internal surfaces: not the product under study, and not something a study of the
+// product's UX can attribute to the product.
+const BROWSER_INTERNAL_URL = /^\s*(?:chrome|about|view-source|devtools|file|edge|brave):/i;
+// An http(s) URL, or a bare host-looking string a browser resolves as navigation.
+const HTTP_URL = /^\s*https?:\/\//i;
+const BARE_HOST = /^\s*(?:www\.)?[a-z0-9-]+(?:\.[a-z0-9-]+)+(?:[/:?#]\S*)?\s*$/i;
+// The common devtools chords across platforms.
+const DEVTOOLS_CHORDS = new Set([
+    "f12",
+    "ctrl+shift+i",
+    "ctrl+shift+j",
+    "ctrl+shift+c",
+    "cmd+alt+i",
+    "cmd+alt+j",
+    "cmd+alt+c",
+    "meta+alt+i",
+    "meta+alt+j",
+    "meta+alt+c",
+]);
+/**
+ * Classify one computer-use action. PURE: same action in, same class out, no I/O, no clock. The
+ * returned signal is public-safe (a scheme or a chord), never the action's text.
+ */
+export function classifyCuaAction(action) {
+    switch (action.kind) {
+        case "click":
+        case "double_click":
+        case "drag":
+        case "scroll":
+            return { affordance: "pointer" };
+        case "wait":
+        case "screenshot":
+        // A bare pointer move actuates nothing on its own; it is the actor looking around.
+        case "move":
+            return { affordance: "observation" };
+        case "keypress": {
+            const chord = normalizeChord(action.keys);
+            if (DEVTOOLS_CHORDS.has(chord)) {
+                return { affordance: "devtools", signal: chord };
+            }
+            return { affordance: "keyboard" };
+        }
+        case "type": {
+            const text = action.text;
+            if (SCRIPT_URL.test(text)) {
+                // The payload after the scheme is deliberately dropped: it is arbitrary author text and
+                // could carry anything. The scheme alone is the finding. `data:` rides here with
+                // `javascript:` because a data URL can carry executable HTML.
+                return { affordance: "script-execution", signal: schemeOf(text) };
+            }
+            if (BROWSER_INTERNAL_URL.test(text)) {
+                return { affordance: "browser-internal", signal: schemeOf(text) };
+            }
+            if (HTTP_URL.test(text)) {
+                // Scheme only — a full URL can carry a session token or an identifying path.
+                return { affordance: "url-navigation", signal: schemeOf(text) };
+            }
+            if (BARE_HOST.test(text)) {
+                return { affordance: "url-navigation", signal: "bare-host" };
+            }
+            return { affordance: "keyboard" };
+        }
+        case "speak":
+            return { affordance: "speech" };
+        default:
+            // The wire->CuaAction mapper drops unrecognized action types before they reach here, so
+            // this is unreachable today; classify defensively rather than throwing inside a run.
+            return { affordance: "observation" };
+    }
+}
+/**
+ * Normalize a key chord so the same physical shortcut matches however a provider spells it:
+ * `Control`/`ctrl`, `Meta`/`Command`/`cmd`, `Option`/`alt` all collapse, and modifier ORDER is
+ * normalized so ["Shift","Control","J"] and ["Control","Shift","J"] are one chord.
+ */
+function normalizeChord(keys) {
+    const alias = {
+        control: "ctrl",
+        ctl: "ctrl",
+        meta: "cmd",
+        command: "cmd",
+        super: "cmd",
+        os: "cmd",
+        option: "alt",
+        opt: "alt",
+    };
+    const parts = keys.map((key) => {
+        const lowered = key.trim().toLowerCase();
+        return alias[lowered] ?? lowered;
+    });
+    const order = ["ctrl", "cmd", "alt", "shift"];
+    const modifiers = parts
+        .filter((part) => order.includes(part))
+        .sort((a, b) => order.indexOf(a) - order.indexOf(b));
+    const rest = parts.filter((part) => !order.includes(part));
+    return [...modifiers, ...rest].join("+");
+}
+/** The scheme alone, lowercased — never the rest of a URL, which can carry a session token. */
+function schemeOf(text) {
+    const trimmed = text.trim();
+    const colon = trimmed.indexOf(":");
+    return colon === -1 ? "" : `${trimmed.slice(0, colon).toLowerCase()}:`;
+}
+/** Fold a sequence of observations into the per-run aggregate. */
+export function summarizeAffordanceUse(observations) {
+    const counts = {};
+    for (const observation of observations) {
+        counts[observation.affordance] = (counts[observation.affordance] ?? 0) + 1;
+    }
+    const shortcutTotal = SHORTCUT_AFFORDANCE_CLASSES.reduce((sum, klass) => sum + (counts[klass] ?? 0), 0);
+    return { schema: AFFORDANCE_CLASS_SCHEMA, counts, total: observations.length, shortcutTotal };
+}

package/dist/actors/agent-session.js

@@ -0,0 +1,42 @@
+// Is the terminal on the other end of this process a PERSON's, or an agent's?
+//
+// WHY THIS EXISTS: `humanish tui` refused a non-TTY, on the reasoning that an agent driving an
+// interactive surface has asked for something that cannot exist. A study of that refusal
+// (labs/handed-a-human-surface.yaml) found it never fires: `codex exec` allocates a PTY for the
+// commands it runs, so both streams ARE terminals. The TUI launched, the agent navigated the labs
+// list, opened one, and — its own words — "accidentally triggered a zero-cost dry run while
+// navigating". A stray Enter on a live row is the same two keystrokes as a deliberate one.
+//
+// So a TTY is a real answer to the wrong question. It says a terminal exists; it does not say
+// anyone is reading it. Agent runners announce themselves in the environment, which is the only
+// signal available before the first keystroke, and is what `is-in-ci` has always done for CI.
+//
+// EVERY MARKER BELOW WAS OBSERVED, not guessed. Two runtimes are covered because two are what we
+// could verify: Claude Code (read off a live session) and Codex (read off the study sandbox, by a
+// names-only `env | cut -d= -f1` probe that never touched a value). Others certainly exist — add
+// them the same way, from a real session, rather than from a plausible-looking guess. A marker
+// that is wrong refuses a person for no reason.
+const MARKERS = [
+    { marker: "CLAUDECODE", runner: "Claude Code" },
+    { marker: "CLAUDE_CODE_SESSION_ID", runner: "Claude Code" },
+    { marker: "CODEX_SESSION_ID", runner: "Codex" },
+    { marker: "CODEX_THREAD_ID", runner: "Codex" },
+    // Generic, and set alongside the Claude Code markers on the machine this was written on. Kept
+    // last so a named runner wins the attribution.
+    { marker: "AI_AGENT", runner: "an AI agent runner" },
+];
+/**
+ * The agent runner driving this process, when one identifies itself. `undefined` means nothing
+ * claimed to be an agent — which is NOT proof a person is there, only the absence of a claim.
+ */
+export function detectAgentSession(env = process.env) {
+    for (const { marker, runner } of MARKERS) {
+        const value = env[marker];
+        // Presence is the signal, but an explicitly empty or "0" value is treated as absence: a
+        // wrapper that unsets a marker by blanking it means it.
+        if (value !== undefined && value.trim().length > 0 && value.trim() !== "0") {
+            return { runner, marker };
+        }
+    }
+    return undefined;
+}

package/dist/actors/codex/app-server-actor-trace.d.ts

@@ -0,0 +1,11 @@
+import { type ActorCompletionReason, type ActorPersonaRef, type ActorTrace } from "../contract.js";
+import type { CodexAppServerRunResult } from "./app-server.js";
+import type { CodexAppServerStatus } from "./app-server-trace.js";
+export declare function codexStatusToCompletionReason(status: CodexAppServerStatus): ActorCompletionReason;
+/**
+ * Map a Codex app-server run result into the provider-neutral ActorTrace. Pure
+ * and side-effect-free. The persona reference is supplied by the harness; until
+ * personas are load-bearing it is a minimal stub ({ id, traitsApplied: [],
+ * promptDigest }).
+ */
+export declare function codexResultToActorTrace(result: CodexAppServerRunResult, persona: ActorPersonaRef): ActorTrace;

package/dist/actors/codex/app-server-actor-trace.js

@@ -0,0 +1,211 @@
+// Maps a Codex app-server run into the provider-neutral ActorTrace.
+import { ACTOR_TRACE_SCHEMA, CODEX_APP_SERVER_CAPABILITIES, } from "../contract.js";
+import { redactText } from "../../evidence/redaction.js";
+// Codex app-server reports four terminal statuses but no explicit completion
+// reason enum, so map status -> reason. App-server "blocked" is approval-driven
+// (an action was declined and the turn could not proceed). "goal_satisfied" and
+// "gave_up" are not reachable from Codex today; they arrive with persona-driven
+// scenario predicates and harness-enforced turn budgets in a later PR.
+export function codexStatusToCompletionReason(status) {
+    switch (status) {
+        case "passed":
+            return "turn_completed";
+        case "timed_out":
+            return "timed_out";
+        case "blocked":
+            return "blocked_approval";
+        case "failed":
+            return "actor_error";
+    }
+}
+function codexItemKind(type) {
+    switch (type) {
+        case "commandExecution":
+            return "command";
+        case "fileChange":
+            return "file_change";
+        case "mcpToolCall":
+        case "dynamicToolCall":
+            return "tool_call";
+        case "agentMessage":
+            return "message";
+        case "reasoning":
+            return "reasoning";
+        default: {
+            const lowered = type.toLowerCase();
+            if (lowered.includes("message"))
+                return "message";
+            if (lowered.includes("reason"))
+                return "reasoning";
+            if (lowered.includes("command"))
+                return "command";
+            if (lowered.includes("file"))
+                return "file_change";
+            if (lowered.includes("tool"))
+                return "tool_call";
+            if (lowered.includes("plan"))
+                return "plan";
+            return "notice";
+        }
+    }
+}
+function pickTokenUsage(raw) {
+    if (raw === undefined || raw === null || typeof raw !== "object") {
+        return undefined;
+    }
+    const record = raw;
+    const numberFrom = (keys) => {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === "number" && Number.isFinite(value)) {
+                return value;
+            }
+        }
+        return undefined;
+    };
+    const input = numberFrom(["input", "input_tokens", "inputTokens", "prompt_tokens"]);
+    const output = numberFrom(["output", "output_tokens", "outputTokens", "completion_tokens"]);
+    const total = numberFrom(["total", "total_tokens", "totalTokens"]);
+    const costUsd = numberFrom(["costUsd", "cost_usd", "cost"]);
+    const usage = {
+        ...(input === undefined ? {} : { input }),
+        ...(output === undefined ? {} : { output }),
+        ...(total === undefined ? {} : { total }),
+        ...(costUsd === undefined ? {} : { costUsd }),
+    };
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
+// Flatten the Codex trace into provider-neutral items. The lifecycle rows in
+// trace.items only cover message/reasoning/command/file/tool; approvals, plans,
+// warnings, and errors live only in sibling arrays and are synthesized here so
+// no evidence is silently dropped.
+function codexTraceToActorItems(trace) {
+    const commandByItem = new Map(trace.commands.map((command) => [command.itemId, command]));
+    const toolByItem = new Map(trace.tools.map((tool) => [tool.itemId, tool]));
+    const messageByItem = new Map(trace.messages.map((message) => [message.itemId, message]));
+    const reasoningByItem = new Map(trace.reasoning.map((entry) => [entry.itemId, entry]));
+    const fileChangeByItem = new Map(trace.fileChanges.map((change) => [change.itemId, change]));
+    const items = trace.items.map((item) => {
+        const kind = codexItemKind(item.type);
+        const base = {
+            id: item.id,
+            kind,
+            lifecycle: item.lifecycle,
+            title: item.title,
+            ...(item.status === undefined ? {} : { status: item.status }),
+        };
+        if (kind === "command") {
+            const command = commandByItem.get(item.id);
+            if (command) {
+                return {
+                    ...base,
+                    command: {
+                        ...(command.command === undefined ? {} : { text: command.command }),
+                        ...(command.cwd === undefined ? {} : { cwd: command.cwd }),
+                        ...(command.exitCode === undefined ? {} : { exitCode: command.exitCode }),
+                        ...(command.outputTail === undefined ? {} : { outputTail: command.outputTail }),
+                    },
+                };
+            }
+        }
+        if (kind === "tool_call") {
+            const tool = toolByItem.get(item.id);
+            if (tool) {
+                return {
+                    ...base,
+                    tool: {
+                        ...(tool.server === undefined ? {} : { server: tool.server }),
+                        ...(tool.tool === undefined ? {} : { name: tool.tool }),
+                    },
+                };
+            }
+        }
+        if (kind === "message") {
+            const message = messageByItem.get(item.id);
+            if (message) {
+                return { ...base, text: message.text };
+            }
+        }
+        if (kind === "reasoning") {
+            const reasoning = reasoningByItem.get(item.id);
+            if (reasoning) {
+                return { ...base, text: reasoning.text };
+            }
+        }
+        if (kind === "file_change") {
+            const change = fileChangeByItem.get(item.id);
+            if (change?.outputTail !== undefined) {
+                return { ...base, text: change.outputTail };
+            }
+        }
+        return base;
+    });
+    for (const approval of trace.approvals) {
+        items.push({
+            id: `approval-${String(approval.id)}`,
+            kind: "approval",
+            lifecycle: "completed",
+            status: approval.decision,
+            title: `${approval.method} (${approval.decision})`,
+            ...(approval.reason ? { text: approval.reason } : {}),
+        });
+    }
+    trace.plans.forEach((plan, index) => {
+        items.push({
+            id: `plan-${index + 1}`,
+            kind: "plan",
+            lifecycle: "completed",
+            title: plan.explanation ?? "Plan update",
+            ...(plan.steps.length > 0 ? { text: plan.steps.join("\n") } : {}),
+        });
+    });
+    [...trace.warnings, ...trace.errors].forEach((notice, index) => {
+        items.push({
+            id: `notice-${index + 1}`,
+            kind: "notice",
+            lifecycle: "completed",
+            title: notice.method,
+            ...(notice.message ? { text: notice.message } : {}),
+        });
+    });
+    return items;
+}
+/**
+ * Map a Codex app-server run result into the provider-neutral ActorTrace. Pure
+ * and side-effect-free. The persona reference is supplied by the harness; until
+ * personas are load-bearing it is a minimal stub ({ id, traitsApplied: [],
+ * promptDigest }).
+ */
+export function codexResultToActorTrace(result, persona) {
+    const trace = result.trace;
+    const tokenUsage = pickTokenUsage(trace.tokenUsage);
+    return {
+        schema: ACTOR_TRACE_SCHEMA,
+        provider: "codex-app-server",
+        ...(trace.server.codexCliVersion === undefined
+            ? {}
+            : { providerVersion: trace.server.codexCliVersion }),
+        protocol: "json-rpc",
+        lane: "code",
+        persona,
+        redaction: { status: "passed", screenshots: "n/a", notes: trace.redaction.notes },
+        startedAt: trace.startedAt,
+        completedAt: trace.completedAt,
+        durationMs: trace.durationMs,
+        status: trace.status,
+        completionReason: codexStatusToCompletionReason(trace.status),
+        // result.reason is the raw reason; the codex trace redacts its own reason, so
+        // redact here too to keep the actor projection consistent (defense in depth).
+        reason: redactText(result.reason),
+        ids: {
+            ...(result.sessionId === undefined ? {} : { sessionId: result.sessionId }),
+            ...(result.threadId === undefined ? {} : { threadId: result.threadId }),
+            ...(result.turnId === undefined ? {} : { turnId: result.turnId }),
+            ...(result.model === undefined ? {} : { model: result.model }),
+        },
+        counts: { ...trace.counts },
+        items: codexTraceToActorItems(trace),
+        ...(tokenUsage === undefined ? {} : { tokenUsage }),
+        capabilities: CODEX_APP_SERVER_CAPABILITIES,
+    };
+}

package/dist/actors/codex/app-server-client.d.ts

@@ -0,0 +1,39 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { type JsonObject } from "./app-server-trace.js";
+export interface CodexStdioHandlers {
+    /** Every message sent or received, before it is acted on. */
+    envelope(direction: "client" | "server", message: JsonObject): void;
+    /** A request from the server; the return value is sent back as its result. */
+    serverRequest(message: JsonObject): JsonObject;
+    /** A server message that carries a method and no id. */
+    notification(message: JsonObject): void;
+    /** Stderr output, unparseable stdout and stdin failures, already redacted and capped. */
+    warning(source: string, message: string): void;
+    /** A process-level failure, already redacted and capped. */
+    error(source: string, message: string): void;
+}
+export declare class CodexStdioClient {
+    private readonly child;
+    /** The command line, named in the error when the process exits mid-request. */
+    private readonly commandName;
+    private readonly handlers;
+    /** Resolves when the child process has closed. */
+    readonly closed: Promise<void>;
+    exitCode: number | undefined;
+    signal: NodeJS.Signals | undefined;
+    private processError;
+    private stdinError;
+    private nextId;
+    private readonly pending;
+    constructor(child: ChildProcessWithoutNullStreams, 
+    /** The command line, named in the error when the process exits mid-request. */
+    commandName: string, handlers: CodexStdioHandlers);
+    request(method: string, params: JsonObject | undefined): Promise<JsonObject>;
+    notify(method: string, params: JsonObject): void;
+    /** The response to a request, or an error naming the request if the process closes first. */
+    response(promise: Promise<JsonObject>, method: string): Promise<JsonObject>;
+    /** Rejects every request still waiting for a response. */
+    rejectPending(reason: string): void;
+    private send;
+    private receive;
+}