harnery 0.8.0 → 0.10.0

package/dist/core/presence/relay-protocol.js

@@ -0,0 +1,169 @@
+/**
+ * Relay protocol for cross-machine presence (ADR 0016, phase 2): the shared,
+ * host-agnostic logic both relay hosts (the Cloudflare Durable Objects worker
+ * and `harn relay serve`) and the client transport build on.
+ *
+ * Capability-based rooms: the room id and the E2E symmetric key are BOTH
+ * derived client-side via HKDF-SHA256 from (repo root-commit SHA, normalized
+ * origin URL, a rotatable salt). Anyone who can read the repo can derive them;
+ * nobody else can — including the relay operator, who sees only an opaque
+ * room id, opaque sender ids, and AES-GCM ciphertext. Rotating the salt
+ * rotates the room.
+ *
+ * The committed salt is NOT a secret and must never be treated as one: the
+ * derivation needs the root-commit SHA + origin URL too, which only
+ * repo-readers have. Repo access is the trust boundary (same as the git-refs
+ * transport).
+ *
+ * Wire format (JSON text frames over WebSocket):
+ *   client → relay:  { t: "pub", sender, iv, ct }        broadcast + cache
+ *   relay  → client: { t: "pub", sender, iv, ct }        live or warm-join replay
+ *   relay  → client: { t: "hello", peers }               on join (peer count)
+ * The relay never sees plaintext: `ct` is AES-GCM over the presence-blob JSON,
+ * `sender` is an HMAC-derived opaque id, `iv` is the per-message nonce.
+ *
+ * Uses WebCrypto only (globalThis.crypto.subtle) so the same module runs on
+ * Bun, Node ≥ 20, and Cloudflare Workers.
+ */
+const ROOM_INFO = "harnery-presence/room-id/v1";
+const KEY_INFO = "harnery-presence/room-key/v1";
+const SENDER_INFO = "harnery-presence/sender-id/v1";
+const HKDF_SALT = "harnery-presence/hkdf-salt/v1";
+/** Default derivation salt when a repo hasn't minted `.harnery/presence-salt`.
+ * Public by design (see module docs); committing a random per-repo salt just
+ * rotates the room away from anything derived before. */
+export const DEFAULT_ROOM_SALT = "harnery-presence-salt/v1";
+/**
+ * Normalize a git remote URL so every clone shape of the same repo derives
+ * the same room: `git@github.com:Org/Repo.git`, `ssh://git@github.com/org/repo`,
+ * and `https://github.com/org/repo.git` all → `github.com/org/repo`.
+ */
+export function normalizeOriginUrl(raw) {
+    let s = raw.trim();
+    // scp-like syntax: [user@]host:path
+    const scp = /^(?:[^@/]+@)?([^:/]+):(?!\/\/)(.+)$/.exec(s);
+    if (scp) {
+        s = `${scp[1]}/${scp[2]}`;
+    }
+    else {
+        // URL syntax: strip scheme, then credentials.
+        s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+        s = s.replace(/^[^@/]+@/, "");
+    }
+    // Drop an explicit port, trailing slashes, trailing .git; lowercase.
+    // (Slashes first so `…/repo.git/` still sheds its .git suffix.)
+    s = s.replace(/^([^/:]+):\d+\//, "$1/");
+    s = s.replace(/\/+$/, "");
+    s = s.replace(/\.git$/i, "");
+    return s.toLowerCase();
+}
+async function hkdfBits(ikm, info, bits) {
+    const key = await crypto.subtle.importKey("raw", ikm, "HKDF", false, [
+        "deriveBits",
+    ]);
+    return crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new TextEncoder().encode(HKDF_SALT),
+        info: new TextEncoder().encode(info),
+    }, key, bits);
+}
+function hex(buf) {
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Derive the room id, E2E key, and sender-id key from the repo identity. */
+export async function deriveRoomCredentials(inputs) {
+    const ikm = new TextEncoder().encode([
+        inputs.rootCommitSha.trim().toLowerCase(),
+        normalizeOriginUrl(inputs.originUrl),
+        inputs.salt ?? DEFAULT_ROOM_SALT,
+    ].join("\n"));
+    const roomBits = await hkdfBits(ikm, ROOM_INFO, 128);
+    const keyBits = await hkdfBits(ikm, KEY_INFO, 256);
+    const senderBits = await hkdfBits(ikm, SENDER_INFO, 256);
+    const key = await crypto.subtle.importKey("raw", keyBits, { name: "AES-GCM" }, false, [
+        "encrypt",
+        "decrypt",
+    ]);
+    return { roomId: hex(roomBits), key, senderKeyBytes: new Uint8Array(senderBits) };
+}
+/** Opaque, stable per-machine sender id: HMAC(senderKey, machineLabel). The
+ * relay caches last-message-per-sender by this without learning the label. */
+export async function computeSenderId(creds, machineLabel) {
+    const hmacKey = await crypto.subtle.importKey("raw", creds.senderKeyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", hmacKey, new TextEncoder().encode(machineLabel));
+    return hex(sig).slice(0, 32);
+}
+function toB64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+function fromB64(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** AES-GCM-encrypt a plaintext payload → { iv, ct } base64 pair. */
+export async function encryptPayload(creds, plaintext) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, creds.key, new TextEncoder().encode(plaintext));
+    return { iv: toB64(iv), ct: toB64(new Uint8Array(ct)) };
+}
+/** Decrypt an { iv, ct } pair. Returns null on any failure (wrong room key,
+ * tampered frame) — callers drop the frame silently. */
+export async function decryptPayload(creds, frame) {
+    try {
+        const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromB64(frame.iv) }, creds.key, fromB64(frame.ct));
+        return new TextDecoder().decode(pt);
+    }
+    catch {
+        return null;
+    }
+}
+/** Hard cap a relay enforces per text frame (ciphertext of a ~2KB blob is far
+ * smaller; anything bigger is abuse or a bug). */
+export const MAX_FRAME_BYTES = 16 * 1024;
+/** Parse + shape-validate an incoming relay frame. Null on anything off. */
+export function parseRelayFrame(raw) {
+    if (raw.length > MAX_FRAME_BYTES)
+        return null;
+    let j;
+    try {
+        j = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!j || typeof j !== "object")
+        return null;
+    const f = j;
+    if (f.t === "pub") {
+        if (typeof f.sender !== "string" ||
+            f.sender.length === 0 ||
+            f.sender.length > 64 ||
+            typeof f.iv !== "string" ||
+            typeof f.ct !== "string" ||
+            f.iv.length > 64 ||
+            f.ct.length > MAX_FRAME_BYTES) {
+            return null;
+        }
+        return { t: "pub", sender: f.sender, iv: f.iv, ct: f.ct };
+    }
+    if (f.t === "hello") {
+        if (typeof f.peers !== "number")
+            return null;
+        return { t: "hello", peers: f.peers };
+    }
+    return null;
+}
+/** Room ids are 32 lowercase hex chars; relays reject anything else. */
+export function isValidRoomId(roomId) {
+    return /^[0-9a-f]{32}$/.test(roomId);
+}

package/dist/core/workflow/billing.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Billing-mode probe: which auth a headless harness child will actually use.
+ *
+ * The engine never handles credentials — children are plain harness CLIs and
+ * authenticate however that CLI does. But the CLIs prefer an exported API key
+ * over a stored (subscription) login when both are present, and that override
+ * is almost always an accident: a sourced .env or a leftover export silently
+ * moves the run from subsidized subscription billing to per-token API billing.
+ * This probe classifies the state per harness so the engine can refuse the
+ * silent-override case (see decision 0015 addendum) while leaving deliberate
+ * key-only hosts (CI boxes with no login) working.
+ *
+ * Detection is a heuristic over well-known credential locations; when a
+ * location can't prove presence or absence (e.g. Claude Code stores its OAuth
+ * token in the macOS keychain, not a file), the state is "unknown" and the
+ * engine never hard-fails on it — the harness CLI itself is the final
+ * authority and will error loudly if truly unauthenticated.
+ */
+import type { HarnessName } from "./types.js";
+/** The env var each harness CLI reads as an API key (preferred over a stored
+ * login when set). Shared with the child-env builder's subscription-only
+ * scrub. */
+export declare const API_KEY_VARS: Record<string, string>;
+export type LoginState = "present" | "absent" | "unknown";
+export type BillingMode = 
+/** No API key exported; the child rides the stored (subscription) login. */
+"subscription"
+/** API key present, no stored login detected: a deliberate key-only host. */
+ | "api-key"
+/** API key present AND a stored login exists: the key silently overrides
+ * subsidized auth. The engine refuses this unless explicitly allowed. */
+ | "api-key-override";
+export interface BillingProbe {
+    harness: HarnessName;
+    /** The env var checked (from API_KEY_VARS), or a note when the key was
+     * found in a credential file instead of the environment. */
+    apiKeySource: string | null;
+    apiKeyPresent: boolean;
+    login: LoginState;
+    mode: BillingMode;
+}
+export interface ProbeIo {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}
+export type BillingProber = (harness: HarnessName) => BillingProbe;
+export declare function probeBilling(harness: HarnessName, io?: ProbeIo): BillingProbe;
+//# sourceMappingURL=billing.d.ts.map

package/dist/core/workflow/billing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;YAEY;AACZ,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI/C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,WAAW;AACrB,4EAA4E;AAC1E,cAAc;AAChB,6EAA6E;GAC3E,SAAS;AACX;yEACyE;GACvE,kBAAkB,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,WAAW,CAAC;IACrB;gEAC4D;IAC5D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,CAAC;AAEnE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAE,OAAY,GAAG,YAAY,CA+CjF"}

package/dist/core/workflow/billing.js

@@ -0,0 +1,108 @@
+/**
+ * Billing-mode probe: which auth a headless harness child will actually use.
+ *
+ * The engine never handles credentials — children are plain harness CLIs and
+ * authenticate however that CLI does. But the CLIs prefer an exported API key
+ * over a stored (subscription) login when both are present, and that override
+ * is almost always an accident: a sourced .env or a leftover export silently
+ * moves the run from subsidized subscription billing to per-token API billing.
+ * This probe classifies the state per harness so the engine can refuse the
+ * silent-override case (see decision 0015 addendum) while leaving deliberate
+ * key-only hosts (CI boxes with no login) working.
+ *
+ * Detection is a heuristic over well-known credential locations; when a
+ * location can't prove presence or absence (e.g. Claude Code stores its OAuth
+ * token in the macOS keychain, not a file), the state is "unknown" and the
+ * engine never hard-fails on it — the harness CLI itself is the final
+ * authority and will error loudly if truly unauthenticated.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The env var each harness CLI reads as an API key (preferred over a stored
+ * login when set). Shared with the child-env builder's subscription-only
+ * scrub. */
+export const API_KEY_VARS = {
+    "claude-code": "ANTHROPIC_API_KEY",
+    codex: "OPENAI_API_KEY",
+    cursor: "CURSOR_API_KEY",
+};
+export function probeBilling(harness, io = {}) {
+    const env = io.env ?? process.env;
+    const home = io.home ?? homedir();
+    const keyVar = API_KEY_VARS[harness];
+    const envKey = keyVar ? Boolean(env[keyVar]?.trim()) : false;
+    let login;
+    let apiKeyPresent = envKey;
+    let apiKeySource = envKey ? keyVar : null;
+    switch (harness) {
+        case "claude-code":
+            login = probeClaudeLogin(home);
+            break;
+        case "codex": {
+            const codex = probeCodexAuth(env, home);
+            login = codex.login;
+            // `codex login --api-key` stores the key in auth.json rather than the
+            // env; that is still API-key billing and should surface as such.
+            if (!envKey && codex.storedApiKey) {
+                apiKeyPresent = true;
+                apiKeySource = codex.storedApiKeyNote;
+            }
+            break;
+        }
+        case "cursor":
+            // cursor-agent's stored-login location is not yet verified against a
+            // live install (adapter itself is pending verification); never claim
+            // presence or absence we can't prove.
+            login = "unknown";
+            break;
+        default:
+            // External adapters own their authentication. The generic engine must
+            // not guess credential locations or fail a plugin on a built-in-only
+            // heuristic.
+            login = "unknown";
+            break;
+    }
+    const mode = apiKeyPresent && login === "present"
+        ? "api-key-override"
+        : apiKeyPresent
+            ? "api-key"
+            : "subscription";
+    return { harness, apiKeySource, apiKeyPresent, login, mode };
+}
+/** Claude Code: OAuth login lives at ~/.claude/.credentials.json on Linux;
+ * macOS stores it in the keychain (dir exists, file doesn't → unknown). */
+function probeClaudeLogin(home) {
+    const dir = join(home, ".claude");
+    const credFile = join(dir, ".credentials.json");
+    if (existsSync(credFile)) {
+        try {
+            const parsed = JSON.parse(readFileSync(credFile, "utf8"));
+            return parsed.claudeAiOauth?.accessToken ? "present" : "absent";
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    return existsSync(dir) ? "unknown" : "absent";
+}
+/** codex: auth lives at $CODEX_HOME/auth.json (default ~/.codex). A `tokens`
+ * object means a ChatGPT (subscription) login; an OPENAI_API_KEY field means
+ * a stored API key (`codex login --api-key`). */
+function probeCodexAuth(env, home) {
+    const authPath = join(env.CODEX_HOME?.trim() || join(home, ".codex"), "auth.json");
+    const storedApiKeyNote = `${authPath} (stored key)`;
+    if (!existsSync(authPath))
+        return { login: "absent", storedApiKey: false, storedApiKeyNote };
+    try {
+        const parsed = JSON.parse(readFileSync(authPath, "utf8"));
+        return {
+            login: parsed.tokens ? "present" : "absent",
+            storedApiKey: !parsed.tokens && Boolean(parsed.OPENAI_API_KEY),
+            storedApiKeyNote,
+        };
+    }
+    catch {
+        return { login: "unknown", storedApiKey: false, storedApiKeyNote };
+    }
+}

package/dist/core/workflow/child-env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Child-process environment builder shared by every spawn adapter.
+ *
+ * Rules (the first is a hard-won Phase 1 spike finding):
+ * 1. **Delete inherited harness-session vars, never blank them.** A nested
+ *    harness CLI under a live session inherits vars that make it exit 1 with
+ *    empty output; an empty-string var still reads as set. Scrub all three
+ *    families (CLAUDE*, CODEX*, CURSOR*) regardless of which adapter spawns —
+ *    a codex child launched from inside a Claude Code session must not
+ *    inherit CLAUDE* either.
+ * 2. **The scrub targets SESSION vars, not credentials.** CURSOR_API_KEY
+ *    matches the CURSOR* prefix but is an auth credential, so it is carved
+ *    out and re-added — a key-only cursor host must keep working. (The other
+ *    two key vars, ANTHROPIC_API_KEY and OPENAI_API_KEY, don't collide with
+ *    the scrub prefixes.)
+ * 3. **subscriptionOnly deletes every API-key var** (see billing.ts) so the
+ *    child can only authenticate via its stored subscription login — the
+ *    guarantee behind `workflow run --subscription-only`.
+ * 4. **Mark the child as a workflow child** (HARNERY_WORKFLOW_CHILD=1): the
+ *    stop-hook rule exempts it from the human-facing end-of-turn ritual while
+ *    hooks stay on, keeping heartbeat + event capture.
+ * 5. **Stamp the run id** (HARNERY_WORKFLOW_RUN_ID) so the coord layer and
+ *    web UI can associate child sessions with their workflow run.
+ */
+export interface ChildEnvOpts {
+    /** Delete all API-key vars so children can only use stored logins. */
+    subscriptionOnly?: boolean;
+}
+export declare function buildChildEnv(runId?: string, opts?: ChildEnvOpts): Record<string, string>;
+//# sourceMappingURL=child-env.d.ts.map

package/dist/core/workflow/child-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-env.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/child-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAY7F"}

package/dist/core/workflow/child-env.js

@@ -0,0 +1,43 @@
+/**
+ * Child-process environment builder shared by every spawn adapter.
+ *
+ * Rules (the first is a hard-won Phase 1 spike finding):
+ * 1. **Delete inherited harness-session vars, never blank them.** A nested
+ *    harness CLI under a live session inherits vars that make it exit 1 with
+ *    empty output; an empty-string var still reads as set. Scrub all three
+ *    families (CLAUDE*, CODEX*, CURSOR*) regardless of which adapter spawns —
+ *    a codex child launched from inside a Claude Code session must not
+ *    inherit CLAUDE* either.
+ * 2. **The scrub targets SESSION vars, not credentials.** CURSOR_API_KEY
+ *    matches the CURSOR* prefix but is an auth credential, so it is carved
+ *    out and re-added — a key-only cursor host must keep working. (The other
+ *    two key vars, ANTHROPIC_API_KEY and OPENAI_API_KEY, don't collide with
+ *    the scrub prefixes.)
+ * 3. **subscriptionOnly deletes every API-key var** (see billing.ts) so the
+ *    child can only authenticate via its stored subscription login — the
+ *    guarantee behind `workflow run --subscription-only`.
+ * 4. **Mark the child as a workflow child** (HARNERY_WORKFLOW_CHILD=1): the
+ *    stop-hook rule exempts it from the human-facing end-of-turn ritual while
+ *    hooks stay on, keeping heartbeat + event capture.
+ * 5. **Stamp the run id** (HARNERY_WORKFLOW_RUN_ID) so the coord layer and
+ *    web UI can associate child sessions with their workflow run.
+ */
+import { API_KEY_VARS } from "./billing.js";
+const SCRUB_PREFIXES = ["CLAUDE", "CODEX", "CURSOR"];
+export function buildChildEnv(runId, opts = {}) {
+    const env = {};
+    const keyVars = new Set(Object.values(API_KEY_VARS));
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v === undefined)
+            continue;
+        if (opts.subscriptionOnly && keyVars.has(k))
+            continue;
+        if (SCRUB_PREFIXES.some((p) => k.startsWith(p)) && !keyVars.has(k))
+            continue;
+        env[k] = v;
+    }
+    env.HARNERY_WORKFLOW_CHILD = "1";
+    if (runId)
+        env.HARNERY_WORKFLOW_RUN_ID = runId;
+    return env;
+}

package/dist/core/workflow/engine.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Workflow engine: loads a workflow script (plain JS, `export default
+ * async (ctx) => …`), injects the ctx API, enforces the caps, journals every
+ * step to `.harnery/workflows/<run-id>/journal.jsonl`, and returns a RunReport.
+ *
+ * Guarantees the engine makes (the pitch, in code):
+ *   - **Bounded**: hard total-agent ceiling + bounded parallel() concurrency.
+ *     A runaway loop hits `maxAgents` and the run fails loud, not silently.
+ *   - **Terminating**: the run is over when the script's default export
+ *     returns. There is no recursive self-spawning path: subagents are leaf
+ *     processes; only the top-level script can spawn.
+ *   - **Schema-gated**: with `schema`, an agent's reply must strict-parse and
+ *     validate; failures re-prompt with the validation errors appended, up to
+ *     `maxAttempts`, then throw. Routing decisions read validated fields, so
+ *     the deterministic script — not a model — decides what runs next.
+ *   - **Journaled**: every stage/agent start+end lands in the run journal with
+ *     cost, duration, and child session id (the resume + web-UI substrate).
+ */
+import type { EngineOpts, RunReport } from "./types.js";
+export declare function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/workflow/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAEV,UAAU,EAEV,SAAS,EAIV,MAAM,YAAY,CAAC;AASpB,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAgS1F"}