@with-logic/elwood 0.1.0

package/dist/state/validate-loops.js

@@ -0,0 +1,81 @@
+/**
+ * Runtime validation for canonical persisted recurring-loop definitions.
+ * Implements PRD §8.2 and C-LOOP-04/C-LOOP-07/C-LOOP-11/C-LOOP-13/C-LOOP-21.
+ */
+import { IDLE_LOOP_INTERVAL_MS, LOOP_EXPIRATION_MS, MAX_ACTIVE_LOOPS, MAX_LOOP_INTERVAL_MS, MAX_LOOP_JITTER_MS, MAX_LOOP_MESSAGE_BYTES, MIN_LOOP_INTERVAL_MS, MIN_LOOP_MESSAGE_BYTES, } from "../core/loops/constants.js";
+import { isRecord } from "./validate-predicates.js";
+export const LOOP_SIDECAR_SCHEMA_VERSION = 1;
+/** Return fresh allowlisted definitions, or null when any part is unsafe. */
+export function validateLoopSidecar(value) {
+    if (!isRecord(value) || value["schemaVersion"] !== LOOP_SIDECAR_SCHEMA_VERSION)
+        return null;
+    const loops = value["loops"];
+    if (!Array.isArray(loops) || loops.length > MAX_ACTIVE_LOOPS)
+        return null;
+    const result = [];
+    const ids = new Set();
+    for (const value of loops) {
+        const definition = validateDefinition(value);
+        if (definition === null || ids.has(definition.id))
+            return null;
+        ids.add(definition.id);
+        result.push(definition);
+    }
+    return result;
+}
+function validateDefinition(value) {
+    if (!isRecord(value))
+        return null;
+    const common = validateCommon(value);
+    if (common === null)
+        return null;
+    if (value["mode"] === "fixed") {
+        const intervalMs = value["intervalMs"];
+        if (!(validInterval(intervalMs) && validJitter(common.jitterMs, intervalMs)))
+            return null;
+        return { ...common, mode: "fixed", intervalMs };
+    }
+    if (value["mode"] !== "idle" ||
+        "intervalMs" in value ||
+        !validJitter(common.jitterMs, IDLE_LOOP_INTERVAL_MS)) {
+        return null;
+    }
+    return { ...common, mode: "idle" };
+}
+function validateCommon(value) {
+    const id = value["id"];
+    const message = value["message"];
+    const jitterMs = value["jitterMs"];
+    const createdAt = value["createdAt"];
+    const expiresAt = value["expiresAt"];
+    if (typeof id !== "string" ||
+        id.length === 0 ||
+        typeof message !== "string" ||
+        !validMessageSize(message) ||
+        !safeTimestamp(createdAt) ||
+        !safeTimestamp(expiresAt) ||
+        expiresAt !== createdAt + LOOP_EXPIRATION_MS ||
+        typeof jitterMs !== "number" ||
+        !Number.isSafeInteger(jitterMs)) {
+        return null;
+    }
+    return { id, message, jitterMs, createdAt, expiresAt };
+}
+function validMessageSize(message) {
+    const bytes = Buffer.byteLength(message, "utf8");
+    return bytes >= MIN_LOOP_MESSAGE_BYTES && bytes <= MAX_LOOP_MESSAGE_BYTES;
+}
+function safeTimestamp(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function validInterval(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= MIN_LOOP_INTERVAL_MS &&
+        value < MAX_LOOP_INTERVAL_MS);
+}
+function validJitter(value, intervalMs) {
+    const cap = Math.min(Math.floor(intervalMs / 10), MAX_LOOP_JITTER_MS);
+    return value >= 0 && value <= cap;
+}
+//# sourceMappingURL=validate-loops.js.map

package/dist/state/validate-loops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-loops.js","sourceRoot":"","sources":["../../src/state/validate-loops.ts"],"names":[],"mappings":"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"}

package/dist/state/validate-posture.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Adapter-specific validation of a persisted launch posture (C-STATE-13).
+ *
+ * A persisted posture must round-trip through the same narrow public unions the
+ * session launched with; an out-of-union `permissionMode`, `sandbox`, or
+ * `approvalPolicy` invalidates the record rather than resuming with a corrupted
+ * policy (PRD §8.2). The runtime allowlists are the single source of truth for
+ * each union and are checked against the public types at compile time below.
+ */
+/**
+ * Validates the launch posture for the record's adapter. Codex records must not
+ * carry Claude posture fields and vice versa; any unknown key invalidates.
+ */
+export declare function isLaunchPosture(value: unknown, adapter: "claude" | "codex"): boolean;
+//# sourceMappingURL=validate-posture.d.ts.map

package/dist/state/validate-posture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-posture.d.ts","sourceRoot":"","sources":["../../src/state/validate-posture.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+CH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,CAIpF"}

package/dist/state/validate-posture.js

@@ -0,0 +1,69 @@
+/**
+ * Adapter-specific validation of a persisted launch posture (C-STATE-13).
+ *
+ * A persisted posture must round-trip through the same narrow public unions the
+ * session launched with; an out-of-union `permissionMode`, `sandbox`, or
+ * `approvalPolicy` invalidates the record rather than resuming with a corrupted
+ * policy (PRD §8.2). The runtime allowlists are the single source of truth for
+ * each union and are checked against the public types at compile time below.
+ */
+import { isRecord, isStringArray } from "./validate-predicates.js";
+// The allowlisted KEYS for each posture, coupled to the public type's keys below so
+// adding a persisted posture field can't compile while the validator silently rejects
+// it on resume (making Elwood reject its own record).
+const claudePostureKeys = ["permissionMode", "allowedTools", "disallowedTools", "tools"];
+const codexPostureKeys = ["sandbox", "approvalPolicy"];
+const claudePermissionModes = [
+    "default",
+    "acceptEdits",
+    "plan",
+    "auto",
+    "dontAsk",
+    "bypassPermissions",
+];
+const codexSandboxModes = ["read-only", "workspace-write", "danger-full-access"];
+const codexApprovalPolicies = ["untrusted", "on-request", "never"];
+const _permissionModeExact = true;
+const _sandboxExact = true;
+const _approvalExact = true;
+// The key allowlists must exactly cover their posture type's keys (both directions).
+const _claudeKeysExact = true;
+const _codexKeysExact = true;
+void _permissionModeExact;
+void _sandboxExact;
+void _approvalExact;
+void _claudeKeysExact;
+void _codexKeysExact;
+/**
+ * Validates the launch posture for the record's adapter. Codex records must not
+ * carry Claude posture fields and vice versa; any unknown key invalidates.
+ */
+export function isLaunchPosture(value, adapter) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value))
+        return false;
+    return adapter === "claude" ? isClaudePosture(value) : isCodexPosture(value);
+}
+function isClaudePosture(value) {
+    return (keysAllowed(value, claudePostureKeys) &&
+        optionalOneOf(value["permissionMode"], claudePermissionModes) &&
+        optionalStringArray(value["allowedTools"]) &&
+        optionalStringArray(value["disallowedTools"]) &&
+        optionalStringArray(value["tools"]));
+}
+function isCodexPosture(value) {
+    return (keysAllowed(value, codexPostureKeys) &&
+        optionalOneOf(value["sandbox"], codexSandboxModes) &&
+        optionalOneOf(value["approvalPolicy"], codexApprovalPolicies));
+}
+function keysAllowed(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function optionalOneOf(value, allowed) {
+    return value === undefined || (typeof value === "string" && allowed.includes(value));
+}
+function optionalStringArray(value) {
+    return value === undefined || isStringArray(value);
+}
+//# sourceMappingURL=validate-posture.js.map

package/dist/state/validate-posture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-posture.js","sourceRoot":"","sources":["../../src/state/validate-posture.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEnE,oFAAoF;AACpF,sFAAsF;AACtF,sDAAsD;AACtD,MAAM,iBAAiB,GAAG,CAAC,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,OAAO,CAAU,CAAC;AAClG,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,gBAAgB,CAAU,CAAC;AAEhE,MAAM,qBAAqB,GAAG;IAC5B,SAAS;IACT,aAAa;IACb,MAAM;IACN,MAAM;IACN,SAAS;IACT,mBAAmB;CACX,CAAC;AAEX,MAAM,iBAAiB,GAAG,CAAC,WAAW,EAAE,iBAAiB,EAAE,oBAAoB,CAAU,CAAC;AAC1F,MAAM,qBAAqB,GAAG,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAU,CAAC;AAM5E,MAAM,oBAAoB,GAGtB,IAAI,CAAC;AACT,MAAM,aAAa,GAAsE,IAAI,CAAC;AAC9F,MAAM,cAAc,GAClB,IAAI,CAAC;AACP,qFAAqF;AACrF,MAAM,gBAAgB,GACpB,IAAI,CAAC;AACP,MAAM,eAAe,GACnB,IAAI,CAAC;AACP,KAAK,oBAAoB,CAAC;AAC1B,KAAK,aAAa,CAAC;AACnB,KAAK,cAAc,CAAC;AACpB,KAAK,gBAAgB,CAAC;AACtB,KAAK,eAAe,CAAC;AAErB;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,OAA2B;IACzE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,eAAe,CAAC,KAAwC;IAC/D,OAAO,CACL,WAAW,CAAC,KAAK,EAAE,iBAAiB,CAAC;QACrC,aAAa,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;QAC7D,mBAAmB,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC1C,mBAAmB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAC7C,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CACpC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAwC;IAC9D,OAAO,CACL,WAAW,CAAC,KAAK,EAAE,gBAAgB,CAAC;QACpC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;QAClD,aAAa,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAClB,KAAwC,EACxC,OAA0B;IAE1B,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,OAA0B;IAC/D,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,KAAK,KAAK,SAAS,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC"}

package/dist/state/validate-predicates.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Low-level predicates for persisted session-record validation (PRD §8.2, §10).
+ * These are the shared trust-boundary primitives from `core/predicates.ts`,
+ * re-exported under the state module so validate.ts and validate-posture.ts share
+ * one definition with hook-payload and CLI-config validation.
+ */
+export { isRecord, isString, isStringArray } from "../core/predicates.ts";
+//# sourceMappingURL=validate-predicates.d.ts.map

package/dist/state/validate-predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-predicates.d.ts","sourceRoot":"","sources":["../../src/state/validate-predicates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/state/validate-predicates.js

@@ -0,0 +1,8 @@
+/**
+ * Low-level predicates for persisted session-record validation (PRD §8.2, §10).
+ * These are the shared trust-boundary primitives from `core/predicates.ts`,
+ * re-exported under the state module so validate.ts and validate-posture.ts share
+ * one definition with hook-payload and CLI-config validation.
+ */
+export { isRecord, isString, isStringArray } from "../core/predicates.js";
+//# sourceMappingURL=validate-predicates.js.map

package/dist/state/validate-predicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-predicates.js","sourceRoot":"","sources":["../../src/state/validate-predicates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/state/validate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime validation for persisted Elwood session records.
+ * Implements PRD §8.2 and §10: the persisted record carries only the minimal fields
+ * resume needs. An unknown adapter, a mismatched id, or a corrupted launch posture
+ * invalidates the record rather than resuming with corrupted state.
+ */
+import type { SessionRecord } from "./store.ts";
+/**
+ * Validates a persisted record and returns a FRESH canonical `SessionRecord` built
+ * from ONLY the allowlisted validated fields — never the untrusted object itself.
+ * A legacy record carrying now-removed fields (a stale bridge token, socket/runtime
+ * paths, persisted warnings, metadata, terminal size) is therefore stripped on the
+ * next write, so a former IPC credential can never round-trip back onto disk (§8.2).
+ */
+export declare function validateSessionRecord(value: unknown, id: string): SessionRecord | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/state/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/state/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAUtF"}

package/dist/state/validate.js

@@ -0,0 +1,55 @@
+/**
+ * Runtime validation for persisted Elwood session records.
+ * Implements PRD §8.2 and §10: the persisted record carries only the minimal fields
+ * resume needs. An unknown adapter, a mismatched id, or a corrupted launch posture
+ * invalidates the record rather than resuming with corrupted state.
+ */
+import { isLaunchPosture } from "./validate-posture.js";
+import { isRecord, isString } from "./validate-predicates.js";
+/**
+ * Validates a persisted record and returns a FRESH canonical `SessionRecord` built
+ * from ONLY the allowlisted validated fields — never the untrusted object itself.
+ * A legacy record carrying now-removed fields (a stale bridge token, socket/runtime
+ * paths, persisted warnings, metadata, terminal size) is therefore stripped on the
+ * next write, so a former IPC credential can never round-trip back onto disk (§8.2).
+ */
+export function validateSessionRecord(value, id) {
+    if (!isRecord(value))
+        return null;
+    const adapter = value["adapter"];
+    if (value["schemaVersion"] !== 1 || value["elwoodSessionId"] !== id)
+        return null;
+    if (adapter !== "claude" && adapter !== "codex")
+        return null;
+    if (!isString(value["cwd"]))
+        return null;
+    const claude = adapterState(value["claude"], "claude");
+    const codex = adapterState(value["codex"], "codex");
+    if (claude === null || codex === null)
+        return null;
+    return { schemaVersion: 1, elwoodSessionId: id, adapter, cwd: value["cwd"], claude, codex };
+}
+// C-STATE-13: a persisted launch posture must round-trip; unknown shapes and
+// out-of-union policy values invalidate the record rather than resuming with a
+// corrupted policy. The posture type is CORRELATED to the `adapter` argument via
+// `PostureFor<A>`, so `adapterState(v, "codex")` can only produce a Codex-typed
+// state — a mismatched adapter/posture pair cannot compile. Returns a FRESH
+// adapter-state carrying ONLY resumeId + launch; legacy extras (e.g. a persisted
+// `name`) are dropped, not carried forward.
+function adapterState(value, adapter) {
+    if (!isRecord(value))
+        return null;
+    const resumeId = value["resumeId"];
+    if (!optionalString(resumeId))
+        return null;
+    if (!isLaunchPosture(value["launch"], adapter))
+        return null;
+    return {
+        ...(resumeId === undefined ? {} : { resumeId }),
+        ...(value["launch"] === undefined ? {} : { launch: value["launch"] }),
+    };
+}
+function optionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+//# sourceMappingURL=validate.js.map

package/dist/state/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/state/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,EAAU;IAC9D,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACjF,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC7D,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,eAAe,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC9F,CAAC;AAOD,6EAA6E;AAC7E,+EAA+E;AAC/E,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,iFAAiF;AACjF,4CAA4C;AAC5C,SAAS,YAAY,CACnB,KAAc,EACd,OAAU;IAEV,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,OAAO;QACL,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC/C,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAkB,EAAE,CAAC;KACvF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AAC1D,CAAC"}

package/dist/terminal/headless.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Headless xterm.js terminal model for PTY rendering and input control.
+ * Implements PRD §4.1, §5.3, and §9.
+ */
+import type { TerminalSize } from "../core/types.ts";
+import type { PtyProcess } from "../pty/types.ts";
+export type XtermTerminal = import("@xterm/headless").Terminal;
+export type TerminalSnapshot = {
+    readonly cols: number;
+    readonly rows: number;
+    readonly cursorX: number;
+    readonly cursorY: number;
+    readonly lines: readonly string[];
+    readonly text: string;
+};
+export interface ElwoodTerminal {
+    readonly xterm: XtermTerminal;
+    readonly size: TerminalSize;
+    /** Latest OSC 0/1/2 window title, or "" before any title is set. */
+    readonly title: string;
+    writeOutput(data: string | Uint8Array): Promise<void>;
+    sendInput(input: string | Uint8Array): Promise<void>;
+    resize(size: TerminalSize): void;
+    snapshot(): TerminalSnapshot;
+    settled(): Promise<void>;
+    dispose(): void;
+}
+export declare function createHeadlessTerminal(size: TerminalSize, onInput: (input: string | Uint8Array) => void): ElwoodTerminal;
+export declare function attachPtyTerminal(size: TerminalSize, pty: PtyProcess, onRendered: (data: string, terminal: ElwoodTerminal) => void): ElwoodTerminal;
+//# sourceMappingURL=headless.d.ts.map

package/dist/terminal/headless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless.d.ts","sourceRoot":"","sources":["../../src/terminal/headless.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,aAAa,GAAG,OAAO,iBAAiB,EAAE,QAAQ,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,QAAQ,IAAI,gBAAgB,CAAC;IAC7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,KAAK,IAAI,GAC5C,cAAc,CAEhB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAC3D,cAAc,CAchB"}

package/dist/terminal/headless.js

@@ -0,0 +1,132 @@
+/**
+ * Headless xterm.js terminal model for PTY rendering and input control.
+ * Implements PRD §4.1, §5.3, and §9.
+ */
+import xtermHeadless from "@xterm/headless";
+export function createHeadlessTerminal(size, onInput) {
+    return new HeadlessTerminal(size, onInput);
+}
+export function attachPtyTerminal(size, pty, onRendered) {
+    const terminal = new HeadlessTerminal(size, (input) => pty.write(input));
+    const unsubscribe = pty.onData((data) => {
+        // Own the whole continuation: a throwing public `terminal:data` listener reached
+        // via onRendered, or a render failure, must not surface as an unhandled rejection
+        // on normal PTY output. There is no caller to reject to on the render path, so the
+        // failure is swallowed here (the write itself already can't poison the queue).
+        void terminal
+            .writeOutput(data)
+            .then(() => onRendered(data, terminal))
+            .catch(() => undefined);
+    });
+    terminal.onDispose(unsubscribe);
+    return terminal;
+}
+class HeadlessTerminal {
+    xterm;
+    currentSize;
+    writeQueue = Promise.resolve();
+    onInput;
+    inputWaiters = [];
+    disposers = [];
+    disposed = false;
+    currentTitle = "";
+    constructor(size, onInput) {
+        this.currentSize = size;
+        this.onInput = onInput;
+        this.xterm = new xtermHeadless.Terminal({
+            allowProposedApi: true,
+            cols: size.cols,
+            rows: size.rows,
+        });
+        this.xterm.onData((input) => this.forwardInput(input));
+        this.xterm.onTitleChange((title) => {
+            this.currentTitle = title;
+        });
+    }
+    get size() {
+        return this.currentSize;
+    }
+    get title() {
+        return this.currentTitle;
+    }
+    writeOutput(data) {
+        if (this.disposed)
+            return Promise.resolve();
+        const write = this.writeQueue.then(() => new Promise((resolve) => this.xterm.write(data, resolve)));
+        // Chain the NEXT write off a never-rejecting tail so a single failed write
+        // (e.g. a synchronous xterm.write throw) cannot poison every subsequent write
+        // by leaving `writeQueue` permanently rejected. The caller still sees the real
+        // result via the returned `write` promise.
+        this.writeQueue = write.catch(() => undefined);
+        return write;
+    }
+    sendInput(input) {
+        if (this.disposed)
+            return Promise.reject(new Error("Terminal is disposed."));
+        if (typeof input !== "string")
+            return this.forwardBytes(input);
+        return new Promise((resolve, reject) => {
+            this.inputWaiters.push({ resolve, reject });
+            this.xterm.input(input);
+        });
+    }
+    resize(size) {
+        this.currentSize = size;
+        this.xterm.resize(size.cols, size.rows);
+    }
+    snapshot() {
+        const buffer = this.xterm.buffer.active;
+        const lines = Array.from({ length: this.currentSize.rows }, (_, index) => buffer.getLine(buffer.viewportY + index)?.translateToString(true) ?? "");
+        return {
+            cols: this.currentSize.cols,
+            rows: this.currentSize.rows,
+            cursorX: buffer.cursorX,
+            cursorY: buffer.cursorY,
+            lines,
+            text: lines.join("\n"),
+        };
+    }
+    settled() {
+        return this.writeQueue;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const dispose of this.disposers.splice(0))
+            dispose();
+        this.xterm.dispose();
+    }
+    onDispose(dispose) {
+        this.disposers.push(dispose);
+    }
+    forwardInput(input) {
+        const waiter = this.inputWaiters.shift();
+        if (!waiter) {
+            try {
+                this.onInput(input);
+            }
+            catch {
+                // Unsolicited xterm protocol replies have no caller promise to reject.
+            }
+            return;
+        }
+        try {
+            this.onInput(input);
+            waiter.resolve();
+        }
+        catch (error) {
+            waiter.reject(error);
+        }
+    }
+    forwardBytes(input) {
+        try {
+            this.onInput(input);
+            return Promise.resolve();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+}
+//# sourceMappingURL=headless.js.map

package/dist/terminal/headless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless.js","sourceRoot":"","sources":["../../src/terminal/headless.ts"],"names":[],"mappings":"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"}

package/docs/api.md

@@ -0,0 +1,184 @@
+# Low-level session API
+
+Purpose: the full control surface under `ClaudeSession` / `CodexSession`, for
+callers who need more than `send` and `stream`.
+
+`ClaudeSession` and `CodexSession` are the primary API. Each delegates the
+operational and lifecycle methods of the low-level session and exposes the raw
+session object (for `elwoodSessionId`, `cwd`, `terminal`, and
+`statusDecisions()`) as `session.session` after startup. The eager
+`startClaude` / `startCodex` factories below are deprecated but remain
+available; the examples use them to show every option in one place.
+
+## Claude
+
+```ts
+import { startClaude } from "@with-logic/elwood"; // deprecated; prefer `new ClaudeSession(...)`
+
+const claude = await startClaude({
+  cwd: "/path/to/project",
+  disallowedTools: ["AskUserQuestion"],
+  autotrust: true,
+  persona: "You are a terse reviewer. Prefer diffs over prose.",
+  hooks: {
+    PreToolUse(event) {
+      if (event.tool_name === "Bash" && event.tool_input.command.includes("rm -rf")) {
+        return { permissionDecision: "deny", permissionDecisionReason: "Dangerous shell command." };
+      }
+      return undefined;
+    },
+  },
+});
+
+await claude.sendMessage("Implement the next PRD slice.");
+```
+
+Claude launches through the user's interactive login shell with generated
+session-scoped settings passed via `--settings`. Elwood does not mutate
+`.claude/settings.local.json`. `startClaude` also accepts `model`, forwarded
+to Claude's `--model` flag, and `reasoningEffort`, forwarded to `--effort`.
+
+## Codex
+
+```ts
+import { startCodex } from "@with-logic/elwood"; // deprecated; prefer `new CodexSession(...)`
+
+const codex = await startCodex({
+  cwd: "/path/to/project",
+  model: "gpt-5.3-codex",
+  approvalPolicy: "never",
+  autotrust: true,
+  hooks: {
+    PermissionRequest(event) {
+      if (event.tool_name === "Bash") return { behavior: "allow", message: "Approved by policy." };
+      return { behavior: "deny", message: "Only Bash is allowed in this mode." };
+    },
+  },
+});
+
+codex.on("codex:transcript", (event) => {
+  console.log(event.summary.kind, event.summary.label, event.summary.text ?? "");
+});
+```
+
+Codex uses session-scoped `-c` overrides for hooks. Elwood reserves
+`features.hooks=true` and `hookTrust="trust-all"` because the library is not
+useful if the bridge hooks do not run. If Codex still shows a hook-review
+prompt, Elwood answers it through the PTY. `reasoningEffort` is forwarded as
+`-c model_reasoning_effort=<value>` and validated against Codex's enum before
+spawn.
+
+## Common surface
+
+Both sessions satisfy the exported `ElwoodAgentSession` type. Code generic over
+"any agent session" should use it; it covers the shared events, io, commands,
+loops, and lifecycle. The sketch below is illustrative, not the exact
+declaration:
+
+```ts
+interface ElwoodAgentSession {
+  readonly elwoodSessionId: string;
+  readonly cwd: string;
+  readonly status: "starting" | "running" | "ready" | "blocked" | "stopped" | "exited" | "killed" | "torn_down";
+  readonly terminal: ElwoodTerminal;
+
+  statusDecisions(): readonly ElwoodStatusDecision[];
+  waitForStatus(match: (status: ElwoodSessionStatus) => boolean, timeoutMs?: number): Promise<ElwoodSessionStatus>;
+  waitForActivity(match: (event: ElwoodActivityEvent) => boolean, timeoutMs?: number): Promise<ElwoodActivityEvent>;
+
+  sendPrompt(prompt: string, options?: SendOptions): Promise<void>;
+  sendMessage(message: string, options?: SendOptions): Promise<void>;
+  sendGuidance(message: string, options?: SendOptions): Promise<void>;
+  sendKeys(input: string | Uint8Array): Promise<void>;
+  resize(size: { cols: number; rows: number }): Promise<void>;
+  interrupt(options?: { readonly timeoutMs?: number }): Promise<void>;
+  compact(options?: { readonly timeoutMs?: number }): Promise<void>;
+  listModels(options?: { readonly timeoutMs?: number }): Promise<readonly AgentModelOption[]>;
+  setModel(id: string, options?: { readonly timeoutMs?: number }): Promise<void>;
+  createLoop(request: ElwoodLoopRequest): Promise<ElwoodLoopSnapshot>;
+  listLoops(): Promise<readonly ElwoodLoopSnapshot[]>;
+  cancelLoop(loopId: string): Promise<void>;
+  stop(): Promise<void>;
+  kill(): Promise<void>;
+  teardown(): Promise<void>;
+}
+```
+
+## Sending input
+
+`sendMessage` is the adapter-neutral chat-loop operation. If the session is
+ready it writes through the PTY immediately. If the session is alive but busy,
+Elwood queues it and submits it on the next `ready` transition.
+
+`sendPrompt` uses bracketed paste so multi-line text is submitted as one
+prompt. It does not wait for `ready`: it dispatches as soon as no other
+submission is in flight, like a human typing into the TUI. It may overtake
+readiness-waiting messages but never interleaves with an in-flight paste/Enter
+sequence.
+
+`sendGuidance` is for a coordinator intervening in an active turn. It queues
+before the session's first readiness and while a blocking dialog is visible.
+After the session has been ready once, guidance sent while `running` bypasses
+readiness and enters the TUI immediately. It stays serialized with other queued
+operations, and its promise resolves after the text and its Enter are written.
+
+`sendKeys` is the immediate escape hatch and bypasses the control queue. A
+string flows through the headless xterm input pipeline, which applies terminal
+input semantics. A `Uint8Array` is written to the PTY verbatim; use bytes to
+forward a user's real keystrokes from your own terminal UI.
+
+All three send methods accept `images` (see [images.md](images.md)). Slash
+prefixed text is sent literally; see [loops.md](loops.md) for `/loop`.
+
+## Commands
+
+`interrupt` cancels the in-flight turn with a programmatic Escape. Once the
+session has reached initial readiness it writes Escape immediately when the
+session is `running` or `blocked`, then resolves once the session is `ready`
+again, or rejects with `interrupt_failed` after `timeoutMs` (default 10 s).
+With no turn in flight it resolves without touching the terminal. Concurrent
+calls coalesce into one Escape.
+
+`compact` types the adapter's `/compact` command and resolves when the adapter
+reports completion through its `PostCompact` hook.
+
+`listModels` and `setModel` drive the adapter's `/model` picker through the
+headless terminal. `listModels` returns rows (`id`, `label`, `description`,
+`isCurrent`, `isDefault`) and leaves the model unchanged. `setModel` switches
+the session's model and leaves the user's saved defaults untouched: Claude
+applies session-only; Codex persists picker selections into the user's
+`config.toml` on its own, so Elwood restores the prior default afterwards via
+compare-and-swap and emits `codex_default_model_persisted` instead of
+clobbering a file that changed in other ways. Layout drift in either picker
+surfaces as `model_automation_failed`.
+
+To enumerate models without holding a session, use the standalone
+`listClaudeModels` / `listCodexModels` functions. Each starts a throwaway
+session from an Elwood-owned temp state directory, lists, and tears it down
+(removing the directory even if startup fails). The probe only opens and
+cancels the picker, so it never applies a selection:
+
+```ts
+import { listClaudeModels, listCodexModels } from "@with-logic/elwood";
+
+const claudeModels = await listClaudeModels({ cwd: "/path/to/project" });
+const codexModels = await listCodexModels({ cwd: "/path/to/project" });
+```
+
+They accept `cwd`, `stateDir`, `autoupdate`, `hookTimeoutMs`,
+`strictVersionCheck`, and a `timeoutMs` for the picker automation. A start
+failure surfaces the adapter's normal typed error; a picker failure rejects
+with `model_automation_failed` (a secondary teardown failure is attached as
+`cause`). Trust note: the probe starts with `autotrust: true` for the given
+`cwd`, so it answers that directory's workspace, skill, plugin, and MCP trust
+prompts automatically. Point these functions at a directory you already trust.
+
+Both adapters accept a `persona` start option: an instruction delivered as the
+session's guaranteed first user message once the agent is ready, ahead of
+anything else queued. It is never persisted and not re-sent on resume.
+
+Input and command methods on a terminated session reject with
+`session_not_running`; they never throw synchronously.
+
+Event delivery guarantees, the default terminal size, and persisting/resuming
+are in [lifecycle.md](lifecycle.md).