harnery 0.8.0 → 0.10.0

package/dist/core/workflow/spawn-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-cursor.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/spawn-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AASrE,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,CAWA;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,CAS1E;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,WAAW,CA6BxE;AAED,eAAO,MAAM,aAAa,EAAE,OAe3B,CAAC"}

package/dist/core/workflow/spawn-cursor.js

@@ -0,0 +1,91 @@
+/**
+ * cursor spawn adapter: runs one subagent as a headless `cursor-agent -p`
+ * subprocess with `--output-format json`.
+ *
+ * Contract notes (LIVE-VERIFIED 2026-07-17 against cursor-agent
+ * 2026.07.16-899851b: schema-gated triage + text stages round-trip via
+ * `--harness cursor`, session_id parses from the envelope):
+ * - `cursor-agent -p "<prompt>" --output-format json` prints a single result
+ *   envelope modeled on Claude Code's (`{type: "result", is_error, result,
+ *   session_id, …}`).
+ * - `--trust` is required: headless runs refuse untrusted workspaces (exit 1,
+ *   "Workspace Trust Required") — see the argv comment below.
+ * - Envelope drift guard: when stdout doesn't parse as JSON but the process
+ *   exited 0, the raw stdout is returned as the reply text.
+ * - No per-run cost surface → undefined. No max-turns equivalent → `maxTurns`
+ *   accepted and ignored (documented in the CLI docs page).
+ */
+import { exec } from "../../lib/exec.js";
+import { validateHarnessEffort } from "../harnesses/profiles.js";
+import { buildChildEnv } from "./child-env.js";
+import { notFoundError } from "./harnesses.js";
+/** Exported for unit tests (no live binary to test against). */
+export function parseCursorOutput(stdout) {
+    try {
+        const envelope = JSON.parse(stdout);
+        return {
+            text: String(envelope.result ?? ""),
+            sessionId: envelope.session_id,
+            isError: Boolean(envelope.is_error),
+        };
+    }
+    catch {
+        return { text: stdout, isError: false };
+    }
+}
+export function buildCursorInvocation(req) {
+    validateHarnessEffort("cursor", req.effort);
+    // --trust: headless cursor-agent refuses untrusted workspaces (exit 1,
+    // "Workspace Trust Required"). Workflow children run in the engine's cwd
+    // deliberately and may edit files — the same posture as the codex adapter's
+    // `--sandbox workspace-write` — so trusting that directory is implied.
+    const argv = ["cursor-agent", "-p", req.prompt, "--output-format", "json", "--trust"];
+    if (req.model)
+        argv.push("--model", req.model);
+    return { argv };
+}
+export function normalizeCursorResult(raw) {
+    if (raw.exitCode === 127) {
+        return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
+    }
+    if (raw.exitCode !== 0) {
+        return {
+            ok: false,
+            text: "",
+            durationMs: raw.durationMs,
+            error: `cursor-agent exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
+        };
+    }
+    const parsed = parseCursorOutput(raw.stdout);
+    if (parsed.isError) {
+        return {
+            ok: false,
+            text: parsed.text,
+            sessionId: parsed.sessionId,
+            durationMs: raw.durationMs,
+            error: `cursor-agent reported is_error: ${parsed.text.slice(0, 300)}`,
+        };
+    }
+    return {
+        ok: true,
+        text: parsed.text,
+        sessionId: parsed.sessionId,
+        durationMs: raw.durationMs,
+    };
+}
+export const cursorSpawner = async (req) => {
+    const t0 = Date.now();
+    let invocation;
+    try {
+        invocation = buildCursorInvocation(req);
+    }
+    catch (error) {
+        return { ok: false, text: "", durationMs: 0, error: error.message };
+    }
+    const r = await exec(invocation.argv, {
+        cwd: req.cwd,
+        env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+        timeout: req.timeoutMs,
+    });
+    return normalizeCursorResult({ ...r, durationMs: Date.now() - t0 });
+};

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

@@ -0,0 +1,152 @@
+/**
+ * Workflow engine contracts. A workflow is a small throwaway JS script with
+ * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * subagents; the SCRIPT (deterministic code), not any model, decides routing
+ * between stages, and the run always terminates when the script returns.
+ *
+ * Design record: decision 0015 (portable coordination-aware workflows).
+ */
+import type { BillingMode, BillingProber } from "./billing.js";
+/** JSON-schema *subset* accepted by stage gates (see validate.ts). */
+export interface StageSchema {
+    type: "object" | "array" | "string" | "number" | "boolean";
+    /** type=object */
+    properties?: Record<string, StageSchema>;
+    required?: string[];
+    /** type=array */
+    items?: StageSchema;
+    /** any type: closed value set (compared with ===) */
+    enum?: Array<string | number | boolean>;
+}
+export interface AgentOpts {
+    /** Stage gate: when present, the agent's reply must strict-parse as JSON and
+     * validate; the engine retries with the validation error appended, up to
+     * `maxAttempts`. Without it, `agent()` resolves to the raw reply text. */
+    schema?: StageSchema;
+    /** Model slug passed through to the harness CLI (default: the CLI's default). */
+    model?: string;
+    /** Reasoning effort mapped through the selected harness profile. Unsupported
+     * values fail before the vendor process starts. */
+    effort?: string;
+    /** Attempt ceiling for the schema-retry loop (default 2). */
+    maxAttempts?: number;
+    /** Subprocess timeout ms (default 300_000). */
+    timeoutMs?: number;
+    /** Harness-turn ceiling for the child (default 25; use 1 for pure
+     * classification stages — cheaper and faster). */
+    maxTurns?: number;
+    /** Display label in the journal (default: prompt head). */
+    label?: string;
+    /** Which harness runs this agent (default: the run's default harness).
+     * Mixed-harness workflows are legal: triage on one CLI, deep work on
+     * another. */
+    harness?: HarnessName;
+}
+/** Open registry key. The built-in catalog currently contains Claude Code,
+ * Codex, and Cursor; consumers may register another adapter without widening
+ * a package-owned union first. */
+export type HarnessName = string;
+/** What a spawn adapter returns for one subagent run. */
+export interface SpawnResult {
+    ok: boolean;
+    /** The model's final reply text (envelope-unwrapped). */
+    text: string;
+    /** Child harness session id when the envelope carries one. */
+    sessionId?: string;
+    costUsd?: number;
+    durationMs: number;
+    /** Populated when ok=false. */
+    error?: string;
+}
+export interface SpawnRequest {
+    prompt: string;
+    model?: string;
+    effort?: string;
+    timeoutMs: number;
+    maxTurns: number;
+    cwd: string;
+    /** Run id, stamped into the child env (HARNERY_WORKFLOW_RUN_ID) so the
+     * coord layer can associate child sessions with their workflow run. */
+    runId?: string;
+    /** Scrub all API-key vars from the child env so it can only authenticate
+     * via its stored (subscription) login. See billing.ts. */
+    subscriptionOnly?: boolean;
+}
+/** One headless-subagent runner. The engine is adapter-agnostic; claude-code
+ * ships first, codex/cursor land behind the same signature (plan Phase 4). */
+export type Spawner = (req: SpawnRequest) => Promise<SpawnResult>;
+/** The API surface injected into a workflow script's default export. Explicit
+ * injection (no ambient globals): keeps scripts portable and unit-testable. */
+export interface WorkflowContext {
+    /** Spawn one subagent; resolves to validated JSON (schema) or reply text. */
+    agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
+    /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
+    parallel: <T>(thunks: Array<() => Promise<T>>) => Promise<Array<T | null>>;
+    /** Declare the current stage (journal + progress grouping). */
+    stage: (title: string) => void;
+    /** Narrate progress (stderr + journal). */
+    log: (message: string) => void;
+}
+export interface WorkflowMeta {
+    name: string;
+    description?: string;
+}
+/** Loaded script shape: `export const meta` + `export default async (ctx) => …`. */
+export interface WorkflowModule {
+    meta?: WorkflowMeta;
+    default: (ctx: WorkflowContext) => Promise<unknown>;
+}
+export interface EngineOpts {
+    /** Repo root whose .harnery/ receives the run journal. */
+    coordRoot: string;
+    /** Spawner registry keyed by harness. A single-harness caller registers one
+     * entry and names it in `defaultHarness`. */
+    spawners: Readonly<Record<HarnessName, Spawner | undefined>>;
+    /** Harness used when an agent() call doesn't name one (default "claude-code"). */
+    defaultHarness?: HarnessName;
+    /** Resume: run id of a prior run whose journal supplies cached results.
+     * agent() calls whose (stage, prompt, model, maxTurns, schema) key matches a
+     * completed prior agent return the journaled result without spawning. */
+    resumeFrom?: string;
+    /** Total-agent ceiling for the run (default 50): the runaway backstop. */
+    maxAgents?: number;
+    /** Concurrent-subagent cap for parallel() (default 4). */
+    concurrency?: number;
+    /** Working directory children spawn in (default: coordRoot). */
+    cwd?: string;
+    /** Progress sink (default: process.stderr). */
+    onLog?: (line: string) => void;
+    /** Guarantee subscription billing: API-key vars are scrubbed from every
+     * child env, and a harness whose stored login is provably absent fails
+     * loud before spawning. */
+    subscriptionOnly?: boolean;
+    /** Permit the api-key-override billing state (an exported API key silently
+     * shadowing a stored subscription login), which the engine otherwise
+     * refuses. Deliberate key-only hosts don't need this — only the
+     * both-present case does. */
+    allowApiBilling?: boolean;
+    /** Billing-probe override for tests (default: the real probeBilling). */
+    probeBilling?: BillingProber;
+}
+export interface RunReport {
+    runId: string;
+    name: string;
+    /** What the script's default export returned. */
+    result: unknown;
+    agentsSpawned: number;
+    /** agent() calls satisfied from the resumeFrom journal without spawning. */
+    agentsCached: number;
+    costUsd: number;
+    durationMs: number;
+    journalPath: string;
+    /** Estimated tokens of repo instructions (CLAUDE.md/AGENTS.md at the child
+     * cwd) that EVERY child cache-writes on spawn — the fixed per-child context
+     * overhead a fan-out multiplies. bytes/4 heuristic; 0 when no such file. */
+    contextTokensPerChildEstimate: number;
+    /** Billing mode per harness actually used this run (probed on first use). */
+    billing: Array<{
+        harness: HarnessName;
+        mode: BillingMode;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/workflow/types.js

@@ -0,0 +1,9 @@
+/**
+ * Workflow engine contracts. A workflow is a small throwaway JS script with
+ * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * subagents; the SCRIPT (deterministic code), not any model, decides routing
+ * between stages, and the run always terminates when the script returns.
+ *
+ * Design record: decision 0015 (portable coordination-aware workflows).
+ */
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
+ * a full JSON Schema implementation would pull a dependency (ajv) for
+ * validation depth workflow gates don't need. Supported: type, properties,
+ * required, items, enum. Returns a list of human-readable problems (empty =
+ * valid) so the engine can feed failures back into the retry prompt verbatim.
+ */
+import type { StageSchema } from "./types.js";
+export declare function validateAgainstSchema(value: unknown, schema: StageSchema, path?: string): string[];
+/** Strip accidental markdown code fences, then strict-parse JSON. */
+export declare function parseStageOutput(text: string): {
+    value?: unknown;
+    error?: string;
+};
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/validate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CA8C/F;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAUlF"}

package/dist/core/workflow/validate.js

@@ -0,0 +1,70 @@
+/**
+ * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
+ * a full JSON Schema implementation would pull a dependency (ajv) for
+ * validation depth workflow gates don't need. Supported: type, properties,
+ * required, items, enum. Returns a list of human-readable problems (empty =
+ * valid) so the engine can feed failures back into the retry prompt verbatim.
+ */
+export function validateAgainstSchema(value, schema, path = "$") {
+    const problems = [];
+    if (schema.enum) {
+        if (!schema.enum.some((v) => v === value)) {
+            problems.push(`${path}: expected one of ${JSON.stringify(schema.enum)}, got ${short(value)}`);
+        }
+        return problems; // enum is exhaustive; type check is implied by membership
+    }
+    switch (schema.type) {
+        case "object": {
+            if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                return [`${path}: expected object, got ${short(value)}`];
+            }
+            const obj = value;
+            for (const key of schema.required ?? []) {
+                if (!(key in obj))
+                    problems.push(`${path}.${key}: required property missing`);
+            }
+            for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+                if (key in obj)
+                    problems.push(...validateAgainstSchema(obj[key], sub, `${path}.${key}`));
+            }
+            return problems;
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                return [`${path}: expected array, got ${short(value)}`];
+            if (schema.items) {
+                for (const [i, item] of value.entries()) {
+                    problems.push(...validateAgainstSchema(item, schema.items, `${path}[${i}]`));
+                }
+            }
+            return problems;
+        }
+        case "string":
+        case "number":
+        case "boolean": {
+            if (typeof value !== schema.type) {
+                problems.push(`${path}: expected ${schema.type}, got ${short(value)}`);
+            }
+            return problems;
+        }
+        default:
+            return [`${path}: unsupported schema type ${String(schema.type)}`];
+    }
+}
+/** Strip accidental markdown code fences, then strict-parse JSON. */
+export function parseStageOutput(text) {
+    const stripped = text
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "");
+    try {
+        return { value: JSON.parse(stripped) };
+    }
+    catch (err) {
+        return { error: `not valid JSON: ${err.message}` };
+    }
+}
+function short(value) {
+    const s = JSON.stringify(value);
+    return s === undefined ? String(value) : s.length > 60 ? `${s.slice(0, 60)}…` : s;
+}

package/dist/lib/browser/client.d.ts

@@ -47,6 +47,14 @@ export interface BrowserOptions {
      * via this callback (e.g., a Cloudflare-bypass header for specific zones).
      */
     extraHeaders?: (url: string) => Record<string, string>;
+    /**
+     * Extra Chromium command-line flags, passed through to Playwright's
+     * `launchPersistentContext` `args`. Used for environment-specific
+     * workarounds — most notably `--disable-gpu` for headed windows under
+     * WSLg (see `./launch-args.ts`). Empty/undefined means Playwright's
+     * defaults only.
+     */
+    launchArgs?: string[];
 }
 export interface NavigateResult {
     url: string;
@@ -71,6 +79,14 @@ export interface FailedRequest {
     method: string;
     failure: string;
     resourceType: string;
+    /** HTTP status for kind "http" entries; null for network-level failures. */
+    status: number | null;
+    /** "http" = request completed with a >=400 response; "network" = never completed (DNS, TLS, aborts, tunnel). */
+    kind: "http" | "network";
+    /** True when the entry is the main frame's document response — lets consumers
+     *  distinguish an expected error-page status (a 404 route under test) from a
+     *  broken subresource. */
+    document?: boolean;
 }
 export interface Diagnostics {
     consoleEvents: ConsoleEvent[];

package/dist/lib/browser/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/client.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/client.js

@@ -32,6 +32,9 @@ export class Browser {
         this.context = await chromium.launchPersistentContext(this.profileDir, {
             headless: !this.opts.headed,
             viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+            ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
+                ? { args: this.opts.launchArgs }
+                : {}),
             ...(this.opts.recordHarPath
                 ? { recordHar: { path: this.opts.recordHarPath, mode: "full" } }
                 : {}),
@@ -84,6 +87,25 @@ export class Browser {
                 method: req.method(),
                 failure: req.failure()?.errorText ?? "unknown",
                 resourceType: req.resourceType(),
+                status: null,
+                kind: "network",
+            });
+        });
+        // HTTP-level failures: `requestfailed` only fires for requests that never
+        // complete (DNS, TLS, aborts), so a script/stylesheet answered with a
+        // 4xx/5xx would otherwise be invisible to failedRequests-based gates.
+        page.on("response", (res) => {
+            if (res.status() < 400)
+                return;
+            const req = res.request();
+            this.failedRequests.push({
+                url: res.url(),
+                method: req.method(),
+                failure: `HTTP ${res.status()}`,
+                resourceType: req.resourceType(),
+                status: res.status(),
+                kind: "http",
+                document: req.resourceType() === "document" && res.frame() === page.mainFrame(),
             });
         });
     }

package/dist/lib/browser/index.d.ts

@@ -1,5 +1,6 @@
 export { Browser, type BrowserOptions, type ConsoleEvent, type Diagnostics, type FailedRequest, type NavigateResult, type PageErrorEvent, } from "./client.js";
 export { captureDevOverlay, type DevOverlayError, type DevOverlayResult, } from "./dev-overlay.js";
+export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export type { OverflowElement, OverflowResult, WidthResult, } from "./layout.js";
 export type { RuntHit, RuntsResult, } from "./runts.js";
 export type { CheckVisibilityOptions, VisibilityResult, VisibilitySample, } from "./visibility.js";

package/dist/lib/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/lib/browser/index.js

@@ -1,2 +1,3 @@
 export { Browser, } from "./client.js";
 export { captureDevOverlay, } from "./dev-overlay.js";
+export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";

package/dist/lib/browser/launch-args.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Chromium launch-arg helpers for environment-specific workarounds.
+ *
+ * The one that matters today is WSLg: a headed Chromium window renders its
+ * page to a GPU-backed surface that WSLg composites over an RDP stream to the
+ * Windows host. On a range of Windows / GPU-driver / WSLg combinations that
+ * GPU-composited surface never presents, so the window shows in the taskbar
+ * but paints blank — even though the page itself runs fine (JS, navigation,
+ * and DOM all work). Forcing Chromium onto its software compositor with
+ * `--disable-gpu` restores on-screen paint. It only matters for headed mode
+ * (headless never composites to a display) and only under WSL.
+ */
+/** True when running under WSL (WSL1 or WSL2). */
+export declare function isWSL(): boolean;
+/**
+ * Chromium launch flags to make a headed window paint under WSLg. Returns
+ * `["--disable-gpu"]` on WSL, `[]` elsewhere. Callers apply these only for
+ * headed launches. See the module doc for the failure mode.
+ */
+export declare function wslHeadedLaunchArgs(): string[];
+//# sourceMappingURL=launch-args.d.ts.map

package/dist/lib/browser/launch-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-args.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/launch-args.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,kDAAkD;AAClD,wBAAgB,KAAK,IAAI,OAAO,CAO/B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}

package/dist/lib/browser/launch-args.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+/**
+ * Chromium launch-arg helpers for environment-specific workarounds.
+ *
+ * The one that matters today is WSLg: a headed Chromium window renders its
+ * page to a GPU-backed surface that WSLg composites over an RDP stream to the
+ * Windows host. On a range of Windows / GPU-driver / WSLg combinations that
+ * GPU-composited surface never presents, so the window shows in the taskbar
+ * but paints blank — even though the page itself runs fine (JS, navigation,
+ * and DOM all work). Forcing Chromium onto its software compositor with
+ * `--disable-gpu` restores on-screen paint. It only matters for headed mode
+ * (headless never composites to a display) and only under WSL.
+ */
+/** True when running under WSL (WSL1 or WSL2). */
+export function isWSL() {
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP)
+        return true;
+    try {
+        return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Chromium launch flags to make a headed window paint under WSLg. Returns
+ * `["--disable-gpu"]` on WSL, `[]` elsewhere. Callers apply these only for
+ * headed launches. See the module doc for the failure mode.
+ */
+export function wslHeadedLaunchArgs() {
+    return isWSL() ? ["--disable-gpu"] : [];
+}

package/dist/lib/claude-desktop.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Claude desktop app session-index access.
+ *
+ * The Claude desktop app keeps each signed-in account's Claude Code session
+ * sidebar as plain JSON files:
+ *
+ *   <dataDir>/claude-code-sessions/<account-uuid>/<env-id>/local_<uuid>.json
+ *
+ * One file per sidebar entry: { sessionId, cliSessionId, cwd, title, ... }.
+ * Nothing inside the file binds it to an account — the scoping is purely
+ * which <account-uuid> directory it sits in, and the transcripts themselves
+ * live in the (account-agnostic) `~/.claude/projects/` tree of the runtime
+ * environment. So when a user signs out of account A and into account B,
+ * their sessions "disappear" from the sidebar even though every byte is
+ * still on disk. Copying an entry file into another account's directory
+ * makes the session visible (and resumable) there.
+ *
+ * These helpers locate the desktop app's data directory (including the
+ * Windows one from inside WSL, where the app runs on the Windows side but
+ * the CLI runs in the distro), enumerate the per-account entries, and
+ * plan/apply cross-account mirrors. The file format is the desktop app's
+ * private state, not a public API — everything here treats it read-mostly
+ * and copies files verbatim rather than rewriting them.
+ */
+export interface DesktopSessionEntry {
+    /** Absolute path of the local_*.json entry file. */
+    file: string;
+    /** Account UUID directory the entry sits under (= sidebar scoping). */
+    accountUuid: string;
+    /** Environment directory between account and entry (VM/env identity). */
+    envId: string;
+    /** The entry's own id (usually "local_<uuid>", mirrors the filename). */
+    sessionId: string | null;
+    /** The Claude Code session id — matches the JSONL transcript filename. */
+    cliSessionId: string | null;
+    cwd: string | null;
+    title: string | null;
+    model: string | null;
+    isArchived: boolean;
+    createdAt: number | null;
+    lastActivityAt: number | null;
+}
+export interface DesktopAccount {
+    accountUuid: string;
+    path: string;
+    entries: DesktopSessionEntry[];
+}
+export interface MirrorAction {
+    from: string;
+    to: string;
+    entry: DesktopSessionEntry;
+    targetAccountUuid: string;
+}
+export interface MirrorPlan {
+    actions: MirrorAction[];
+    /** Entries skipped because the target already lists that cliSessionId. */
+    skippedExisting: number;
+    /** Entries skipped because they are archived (opt in via includeArchived). */
+    skippedArchived: number;
+}
+/**
+ * Candidate desktop-app data directories for this machine, most specific
+ * first. Only directories that exist AND contain a claude-code-sessions/
+ * subdirectory are returned. Precedence: explicit arg, then
+ * HARNERY_CLAUDE_DESKTOP_DIR, then platform defaults (on WSL that means
+ * scanning every /mnt/c/Users/<user>/AppData/Roaming/Claude).
+ */
+export declare function findDesktopDataDirs(explicit?: string): string[];
+/** Enumerate every account directory + its session entries under one data dir. */
+export declare function listAccounts(dataDir: string): DesktopAccount[];
+/**
+ * The account the runtime environment's Claude Code CLI is signed into,
+ * read from ~/.claude.json (best-effort; null when unavailable). Lets the
+ * command label an otherwise-opaque account UUID with an email address.
+ */
+export declare function readCliAccount(): {
+    accountUuid: string;
+    email: string | null;
+} | null;
+export interface MirrorOptions {
+    /** Restrict targets to accounts whose uuid starts with one of these. */
+    to?: string[];
+    /** Restrict sources to accounts whose uuid starts with one of these. */
+    from?: string[];
+    /**
+     * Selectors: each matches a cliSessionId / sessionId exactly, or a title
+     * case-insensitively as a substring. Empty/undefined = every entry.
+     */
+    sessions?: string[];
+    includeArchived?: boolean;
+}
+export declare function entryMatchesSelector(entry: DesktopSessionEntry, selector: string): boolean;
+/**
+ * Plan the copies that would make each target account list the selected
+ * sessions. Union semantics: every entry a source account has and a target
+ * account lacks (keyed by cliSessionId, falling back to filename) becomes a
+ * copy action. Idempotent by construction — planning again after applying
+ * yields zero actions.
+ */
+export declare function planMirror(accounts: DesktopAccount[], opts?: MirrorOptions): MirrorPlan;
+/** Apply a plan: verbatim file copies (never rewrites entry contents). */
+export declare function applyMirror(plan: MirrorPlan): {
+    copied: number;
+};
+//# sourceMappingURL=claude-desktop.d.ts.map

package/dist/lib/claude-desktop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/lib/claude-desktop.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,mBAAmB,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;CACzB;AAaD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAgC/D;AA4CD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAyB9D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAerF;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG1F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,UAAU,CA2C3F;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAQhE"}