@kya-os/cli 1.8.1 → 1.8.3

package/dist/utils/agent/spawn-agent.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Headless AI-agent spawn wrapper, shared by `kya-os agent task` (the
+ * implementation pass) and `kya-os agent review` (the analysis pass).
+ *
+ * Provider-agnostic by design (2026-08-22 revision, epic decision 12: no
+ * kya-os surface hardcodes a model provider — an agent is a general actor
+ * on behalf of its user, Claude is the default adapter, never the
+ * architecture). `PROVIDER_PRESETS` carries `claude`'s exact behavior
+ * (headless `-p`, `--output-format json`, its own envelope + usage
+ * parsing); a caller can instead point at an arbitrary command via
+ * `agentCmd`, or (once review-loop P15 lands agent profiles) resolve a
+ * preset from the invoking agent's own profile. Mirrors review-loop P8's
+ * spawn pattern (injectable process spawn, honest token accounting,
+ * defensive JSON parsing that throws rather than guessing) without
+ * importing it: P8's implementation lives in `@kya-os/compute`, which
+ * `@kya-os/cli` must never import. The prompt is piped over stdin rather
+ * than passed as an argument value, so a large prompt (a full diff, or a
+ * task description plus repository context) never risks an OS
+ * argv-length limit the way an `execFile` argument would.
+ *
+ * The agent process never sees or holds signing key material: this module
+ * only runs it and returns its text output; every caller signs
+ * separately, in the command process, using the agent's key file directly
+ * (see `resolveSigningIdentity` / `ssh-key.ts`).
+ */
+export interface SpawnOutcome {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+}
+/**
+ * Injectable process spawn. Tests supply a fake implementation; production
+ * uses {@link defaultSpawnImpl}. Never invoked with a real agent binary in
+ * CI.
+ */
+export type SpawnImpl = (cmd: string, args: string[], options: {
+    cwd: string;
+    input: string;
+    timeoutMs: number;
+}) => Promise<SpawnOutcome>;
+export interface HeadlessAgentUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface HeadlessAgentResult {
+    /** The agent's final text response — the actual content, not any CLI envelope. */
+    text: string;
+    usage: HeadlessAgentUsage;
+}
+/**
+ * How to build the argument list for one spawn. `writeCapable` signals
+ * "this pass needs to create/edit files unattended" (no TTY to approve a
+ * permission prompt) — what a preset does with that is its own business:
+ * the `claude` preset adds `--dangerously-skip-permissions` plus a
+ * `--disallowedTools` denylist scoped to the git/gh subcommands this
+ * feature's own signing process is responsible for; a different preset
+ * might need nothing at all, or its own equivalent flag.
+ */
+export interface BuildArgsOptions {
+    model?: string;
+    extraArgs?: string[];
+    writeCapable?: boolean;
+}
+export interface ProviderPreset {
+    /** The executable to run. */
+    command: string;
+    buildArgs(options: BuildArgsOptions): string[];
+    /**
+     * Parse this provider's raw process output into `{text, usage}`. Throws
+     * on malformed/failed output — never returns a partial/garbled result,
+     * since a caller signs and posts whatever this returns.
+     */
+    parseOutput(outcome: SpawnOutcome): HeadlessAgentResult;
+    /** This preset's own default timeout, used when the caller doesn't override. */
+    defaultTimeoutMs: number;
+}
+/**
+ * Known provider presets, keyed by the name `--provider <preset>` accepts.
+ * Kept as a CLI-local table, not imported from `@kya-os/compute` (which has
+ * its own equivalent `PROVIDER_PRESETS` for the DIDComm reviewer runtime) —
+ * the CLI never imports compute. Add a preset here to support a new
+ * headless AI CLI without touching any caller.
+ */
+export declare const PROVIDER_PRESETS: Record<string, ProviderPreset>;
+export interface RunHeadlessAgentOptions {
+    /** Working directory the agent process runs in (its tool calls operate here). */
+    cwd: string;
+    /** A preset name from {@link PROVIDER_PRESETS}. Default `"claude"`. Mutually exclusive with `agentCmd`; `agentCmd` wins if both are given. */
+    provider?: string;
+    /**
+     * A full command line to run instead of any preset, e.g. `"my-agent-cli --flag"`.
+     * Split on whitespace (no quoting support in this v1); `extraArgs` are appended.
+     * Its raw stdout is treated as the text result directly — see {@link parseGenericOutput}.
+     */
+    agentCmd?: string;
+    model?: string;
+    /** Overrides the resolved preset's own default timeout. */
+    timeoutMs?: number;
+    /** "This pass needs unattended write access" — see {@link BuildArgsOptions}. */
+    writeCapable?: boolean;
+    extraArgs?: string[];
+    spawnImpl?: SpawnImpl;
+}
+/**
+ * Run a headless AI agent with `prompt` on stdin and return its text result
+ * plus honest token counts. Resolution order: `agentCmd` (an explicit raw
+ * command) overrides everything; else `provider` names a preset from
+ * {@link PROVIDER_PRESETS}; else the `claude` preset is the default. Throws
+ * — never silently produces a partial result — on an unknown provider
+ * name, a spawn error, a non-zero exit, a timeout, or (for a preset) output
+ * that doesn't match its expected envelope: a garbled or failed response
+ * must never be mistaken for a real one by a caller that then signs and
+ * posts it.
+ */
+export declare function runHeadlessAgent(prompt: string, options: RunHeadlessAgentOptions): Promise<HeadlessAgentResult>;
+//# sourceMappingURL=spawn-agent.d.ts.map

package/dist/utils/agent/spawn-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-agent.d.ts","sourceRoot":"","sources":["../../../src/utils/agent/spawn-agent.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACvD,OAAO,CAAC,YAAY,CAAC,CAAC;AAuC3B,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAAC;IAC/C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,mBAAmB,CAAC;IACxD,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AA6ED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAE3D,CAAC;AAgBF,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,8IAA8I;IAC9I,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CA2C9B"}

package/dist/utils/agent/spawn-agent.js

@@ -0,0 +1,177 @@
+import { spawn } from "child_process";
+import { z } from "zod";
+const defaultSpawnImpl = (cmd, args, { cwd, input, timeoutMs }) => {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, exitCode, timedOut });
+        });
+        child.stdin?.write(input);
+        child.stdin?.end();
+    });
+};
+/**
+ * The subset of the Claude Code CLI's `--output-format json` envelope this
+ * preset actually depends on. Deliberately loose (`.passthrough()`): the
+ * real envelope carries many more fields (session id, cost, duration, ...)
+ * this has no use for, and pinning to an exact shape would break on every
+ * unrelated CLI field addition.
+ */
+const ClaudeCliEnvelopeSchema = z
+    .object({
+    result: z.string(),
+    is_error: z.boolean().optional(),
+    usage: z
+        .object({
+        input_tokens: z.number().nonnegative().optional(),
+        output_tokens: z.number().nonnegative().optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const CLAUDE_WRITE_CAPABLE_ARGS = [
+    "--dangerously-skip-permissions",
+    "--disallowedTools",
+    "Bash(git commit*) Bash(git push*) Bash(gh pr create*) Bash(gh pr review*)",
+];
+function parseClaudeOutput(outcome) {
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(outcome.stdout);
+    }
+    catch {
+        throw new Error(`claude did not return valid JSON output (--output-format json): ${outcome.stdout.slice(0, 500)}`);
+    }
+    const envelope = ClaudeCliEnvelopeSchema.safeParse(parsedJson);
+    if (!envelope.success) {
+        throw new Error(`claude's JSON output did not match the expected envelope shape: ${envelope.error.message}`);
+    }
+    if (envelope.data.is_error) {
+        throw new Error(`claude reported a failed result: ${envelope.data.result}`);
+    }
+    return {
+        text: envelope.data.result,
+        usage: {
+            // Returning 0 when usage is genuinely absent is honest, not a
+            // fallback to hide behind: a caller that feeds this into a token
+            // budget must see 0, not a guessed nonzero value, when the CLI truly
+            // reported nothing.
+            inputTokens: envelope.data.usage?.input_tokens ?? 0,
+            outputTokens: envelope.data.usage?.output_tokens ?? 0,
+        },
+    };
+}
+const CLAUDE_PRESET = {
+    command: "claude",
+    buildArgs: ({ model, extraArgs, writeCapable }) => {
+        const args = ["-p", "--output-format", "json"];
+        if (writeCapable) {
+            args.push(...CLAUDE_WRITE_CAPABLE_ARGS);
+        }
+        args.push(...(extraArgs ?? []));
+        if (model) {
+            args.push("--model", model);
+        }
+        return args;
+    },
+    parseOutput: parseClaudeOutput,
+    defaultTimeoutMs: 300000,
+};
+/**
+ * Known provider presets, keyed by the name `--provider <preset>` accepts.
+ * Kept as a CLI-local table, not imported from `@kya-os/compute` (which has
+ * its own equivalent `PROVIDER_PRESETS` for the DIDComm reviewer runtime) —
+ * the CLI never imports compute. Add a preset here to support a new
+ * headless AI CLI without touching any caller.
+ */
+export const PROVIDER_PRESETS = {
+    claude: CLAUDE_PRESET,
+};
+/**
+ * A fully custom command line (`--agent-cmd`), bypassing the preset table
+ * entirely. There's no known envelope to unwrap for an arbitrary command,
+ * so its raw stdout IS the text result, verbatim; a caller that needs
+ * structured content (e.g. `agent review`'s findings JSON) parses that text
+ * itself, the same way it would parse a preset's already-unwrapped text.
+ * Token usage is honestly reported as unknown (0), never guessed.
+ */
+function parseGenericOutput(outcome) {
+    return { text: outcome.stdout, usage: { inputTokens: 0, outputTokens: 0 } };
+}
+const GENERIC_DEFAULT_TIMEOUT_MS = 300000;
+/**
+ * Run a headless AI agent with `prompt` on stdin and return its text result
+ * plus honest token counts. Resolution order: `agentCmd` (an explicit raw
+ * command) overrides everything; else `provider` names a preset from
+ * {@link PROVIDER_PRESETS}; else the `claude` preset is the default. Throws
+ * — never silently produces a partial result — on an unknown provider
+ * name, a spawn error, a non-zero exit, a timeout, or (for a preset) output
+ * that doesn't match its expected envelope: a garbled or failed response
+ * must never be mistaken for a real one by a caller that then signs and
+ * posts it.
+ */
+export async function runHeadlessAgent(prompt, options) {
+    const spawnImpl = options.spawnImpl ?? defaultSpawnImpl;
+    let command;
+    let args;
+    let parseOutput;
+    let defaultTimeoutMs;
+    if (options.agentCmd) {
+        const parts = options.agentCmd.trim().split(/\s+/).filter(Boolean);
+        if (parts.length === 0) {
+            throw new Error("--agent-cmd was given but is empty after trimming");
+        }
+        command = parts[0];
+        args = [...parts.slice(1), ...(options.extraArgs ?? [])];
+        parseOutput = parseGenericOutput;
+        defaultTimeoutMs = GENERIC_DEFAULT_TIMEOUT_MS;
+    }
+    else {
+        const presetName = options.provider ?? "claude";
+        const preset = PROVIDER_PRESETS[presetName];
+        if (!preset) {
+            throw new Error(`unknown provider preset "${presetName}"; known presets: ${Object.keys(PROVIDER_PRESETS).join(", ")}`);
+        }
+        command = preset.command;
+        args = preset.buildArgs({ model: options.model, extraArgs: options.extraArgs, writeCapable: options.writeCapable });
+        parseOutput = preset.parseOutput;
+        defaultTimeoutMs = preset.defaultTimeoutMs;
+    }
+    const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+    const outcome = await spawnImpl(command, args, { cwd: options.cwd, input: prompt, timeoutMs });
+    if (outcome.timedOut) {
+        throw new Error(`${command} timed out after ${timeoutMs}ms`);
+    }
+    if (outcome.exitCode !== 0) {
+        const detail = outcome.stderr.trim() || outcome.stdout.trim() || "(no output)";
+        throw new Error(`${command} exited with code ${outcome.exitCode}: ${detail}`);
+    }
+    return parseOutput(outcome);
+}
+//# sourceMappingURL=spawn-agent.js.map

package/dist/utils/agent/spawn-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-agent.js","sourceRoot":"","sources":["../../../src/utils/agent/spawn-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8CxB,MAAM,gBAAgB,GAAc,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE;IAC3E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACzE,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC,EAAE,SAAS,CAAC,CAAC;QAEd,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE;YAC7B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AA0CF;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,KAAK,EAAE,CAAC;SACL,MAAM,CAAC;QACN,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;QACjD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;KACnD,CAAC;SACD,WAAW,EAAE;SACb,QAAQ,EAAE;CACd,CAAC;KACD,WAAW,EAAE,CAAC;AAEjB,MAAM,yBAAyB,GAAG;IAChC,gCAAgC;IAChC,mBAAmB;IACnB,2EAA2E;CAC5E,CAAC;AAEF,SAAS,iBAAiB,CAAC,OAAqB;IAC9C,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,mEAAmE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAClG,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC/D,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mEAAmE,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC1B,KAAK,EAAE;YACL,8DAA8D;YAC9D,iEAAiE;YACjE,qEAAqE;YACrE,oBAAoB;YACpB,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC;YACnD,YAAY,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,IAAI,CAAC;SACtD;KACF,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAmB;IACpC,OAAO,EAAE,QAAQ;IACjB,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,EAAE,EAAE;QAChD,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,YAAY,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,GAAG,yBAAyB,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;QAChC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,WAAW,EAAE,iBAAiB;IAC9B,gBAAgB,EAAE,MAAO;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmC;IAC9D,MAAM,EAAE,aAAa;CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,kBAAkB,CAAC,OAAqB;IAC/C,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;AAC9E,CAAC;AAED,MAAM,0BAA0B,GAAG,MAAO,CAAC;AAsB3C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAc,EACd,OAAgC;IAEhC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAC;IAExD,IAAI,OAAe,CAAC;IACpB,IAAI,IAAc,CAAC;IACnB,IAAI,WAA2D,CAAC;IAChE,IAAI,gBAAwB,CAAC;IAE7B,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;QACzD,WAAW,GAAG,kBAAkB,CAAC;QACjC,gBAAgB,GAAG,0BAA0B,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;QAChD,MAAM,MAAM,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,4BAA4B,UAAU,qBAAqB,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtG,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;QACpH,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACjC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC7C,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAC;IACxD,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAE/F,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,oBAAoB,SAAS,IAAI,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,aAAa,CAAC;QAC/E,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,qBAAqB,OAAO,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC"}

package/dist/utils/agent/task.d.ts

@@ -0,0 +1,101 @@
+import { ensureColdStartRepo, type ResolveSigningIdentityResult } from "../dco/dispatch.js";
+import { type AgentPublicKeyResolution } from "../dco/verify.js";
+import { type DcoFixOptions, type DcoFixResult } from "../dco/fix.js";
+import { type PullRequestReview, type PullRequestSummary } from "../dco/github.js";
+import { type RunHeadlessAgentOptions } from "./spawn-agent.js";
+export interface RunAgentTaskOptions {
+    agentSlug: string;
+    /** Target an existing repo (owner/name) instead of cold-starting a fresh scratch one. */
+    repo?: string;
+    /**
+     * PR base branch. When omitted, `gh pr create` is left to auto-detect the
+     * repo's own default branch, rather than forcing "main" — a cold-started
+     * scratch repo's default branch name follows the LOCAL git installation's
+     * `init.defaultBranch` config (often "master", not "main"), and hardcoding
+     * "main" made `gh pr create` fail outright ("Base ref must be a branch")
+     * on such a machine, confirmed live.
+     */
+    base?: string;
+    /** Directory under which scratch/clone directories are created. Default `os.tmpdir()`. */
+    workDir?: string;
+    /** Provider selection (`--provider`/`--agent-cmd`) and other headless-agent options; see `spawn-agent.ts`. */
+    agentOptions?: Omit<RunHeadlessAgentOptions, "cwd" | "writeCapable">;
+    resolveIdentity?: (cwd: string, agentSlug: string | undefined) => Promise<ResolveSigningIdentityResult>;
+    ensureColdStart?: typeof ensureColdStartRepo;
+}
+export interface RunAgentTaskResult {
+    ok: boolean;
+    failure?: string;
+    agent?: {
+        name: string;
+        slug: string;
+    };
+    did?: string;
+    /**
+     * The fresh clone directory the agent worked in — left on disk (not cleaned
+     * up) so `--watch`'s fix rounds can reuse it via `runDcoFix`, which
+     * requires `cwd` to already be a clone with `origin` pointing at the PR's
+     * repo.
+     */
+    cloneDir?: string;
+    branch?: string;
+    commitSha?: string;
+    signed?: boolean;
+    createdRemote?: string;
+    prUrl?: string;
+}
+export declare function runAgentTask(description: string, options: RunAgentTaskOptions): Promise<RunAgentTaskResult>;
+export interface AgentTaskGithubClient {
+    getPullRequestSummary: (target: string, repo?: string) => Promise<PullRequestSummary>;
+    getPullRequestReviews: (target: string, repo?: string) => Promise<PullRequestReview[]>;
+}
+export type AgentTaskWatchStopReason = "approved" | "fix-rounds-exhausted" | "pr-closed" | "task-failed" | "fix-failed";
+export interface AgentTaskWatchResult {
+    ok: boolean;
+    stopReason: AgentTaskWatchStopReason;
+    fixesUsed: number;
+    prUrl?: string;
+    failure?: string;
+}
+export interface RunAgentTaskWatchOptions extends RunAgentTaskOptions {
+    fixRounds?: number;
+    pollSeconds?: number;
+    github?: AgentTaskGithubClient;
+    resolvePublicKey?: (did: string) => Promise<AgentPublicKeyResolution>;
+    runDcoFixImpl?: (cwd: string, options: DcoFixOptions) => Promise<DcoFixResult>;
+    sleepImpl?: (ms: number) => Promise<void>;
+    /**
+     * Invoked once, immediately after the initial `runAgentTask` call
+     * succeeds and BEFORE this function enters its (potentially long-running)
+     * poll loop. Without this, a caller has no way to learn the PR URL until
+     * the entire watch loop concludes — which could be many minutes later —
+     * even though a second process (the reviewer, in the two-party demo)
+     * needs that URL right away to start watching the same PR concurrently.
+     */
+    onTaskOpened?: (result: RunAgentTaskResult) => void;
+}
+/**
+ * Open the PR ({@link runAgentTask}) and then keep watching it: on every
+ * poll, look for a review whose `kya-os-verdict:v1` marker names the
+ * CURRENT head, is signed for THIS repo/PR (never a verdict genuinely
+ * signed for a different repo/PR that happens to share this head SHA,
+ * which a fork trivially can), and whose fenced
+ * `kya-os-signed-verdict` block verifies against the marker's reviewer DID.
+ * Anything else — no marker, a stale head, a context mismatch, an
+ * unresolvable reviewer, or a verdict that fails signature verification —
+ * is silently ignored: this loop acts only on cryptographically verified
+ * verdicts.
+ *
+ * **Trust boundary, by design, not oversight**: there is no reviewer
+ * allowlist here. ANY `did:web` identity that can produce a valid Ed25519
+ * signature is trusted — matching this feature's own design doc ("this
+ * agent acts only on cryptographic verdicts") and the two-party demo's
+ * threat model, which deliberately has no registry/quorum (that's the
+ * separate hub-backed production loop's job). On a cold-started (private
+ * by default) scratch repo this is low-exposure; pointing `--repo` at a
+ * PUBLIC repo means anyone who can comment or review on that PR can forge
+ * an approve/request-changes from their own self-hosted DID. Do not point
+ * `--repo` at a public repo you don't control the review surface of.
+ */
+export declare function runAgentTaskWatch(description: string, options: RunAgentTaskWatchOptions): Promise<AgentTaskWatchResult>;
+//# sourceMappingURL=task.d.ts.map

package/dist/utils/agent/task.d.ts.map

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