@alpacakit/agents 0.1.0-beta.39 → 0.2.0-beta.3

package/dist/kernel/session.js

@@ -0,0 +1,314 @@
+/**
+ * The session driver (design "Kernel", session plane): as `RunDriver`
+ * drives an adapter's generator, `driveSession` drives a host's
+ * `SessionProtocol`. The driver owns the conversation's lifecycle — one
+ * turn at a time, the approval registry and its lifetime, the event
+ * stream, and the end of it all when the child is gone. A protocol only
+ * encodes the five verbs for its host and decodes one incoming item into
+ * the neutral session signals; it never keeps turn or approval state.
+ */
+import { endProcessGracefully, failureEvidence, LineBuffer, appendTail, resolveCommand, } from "../core/cli-child.js";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { APPROVAL_DECISION, SESSION_EVENT_TYPE, TURN_OUTCOME, } from "../core/session.js";
+import { OUTPUT_CHANNEL } from "../core/values.js";
+import { EventBroadcast } from "./handle.js";
+const EVENT_BASE_COST_BYTES = 64;
+const UNKNOWN_EXIT = { code: null, signal: null };
+/** Both hosts use UUID-shaped conversation ids; anything else never reaches a path. */
+const HOST_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** Every host takes both answers (Claude allow/deny; Codex accepts `decline` for every request, T53 h2). */
+const APPROVAL_DECISIONS = [
+    APPROVAL_DECISION.accept,
+    APPROVAL_DECISION.decline,
+];
+export function assertHostSessionId(id, agentId) {
+    if (HOST_SESSION_ID.test(id)) {
+        return;
+    }
+    throw new AgentError({
+        code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
+        message: `Agent "${agentId}" session id is not a UUID`,
+        data: { reason: "session id must be a UUID" },
+        agentId,
+    });
+}
+function sessionEventCost(event) {
+    return (EVENT_BASE_COST_BYTES +
+        (event.type === SESSION_EVENT_TYPE.message ? event.text.length : 0));
+}
+export function sessionStateError(agentId, reason) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
+        message: `Agent "${agentId}" session: ${reason}`,
+        data: { reason },
+        agentId,
+    });
+}
+export function sessionExitedError(agentId, exit, stderrTail) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
+        message: `Agent "${agentId}" session process exited`,
+        data: failureEvidence({
+            stdout: "",
+            stderr: stderrTail,
+            exitCode: exit?.code ?? null,
+        }),
+        agentId,
+    });
+}
+/**
+ * One interactive child held for the life of a Session: stdout is read as
+ * NDJSON lines, stdin stays open for incremental writes, and `close()`
+ * ends stdin first (both hosts exit on EOF) before escalating to signals.
+ */
+export class SessionProcess {
+    process;
+    clock;
+    exitValue = null;
+    stderrTail = "";
+    constructor(process, clock) {
+        this.process = process;
+        this.clock = clock;
+        void process.exit.then((exit) => {
+            this.exitValue = exit;
+        }, () => {
+            this.exitValue = UNKNOWN_EXIT;
+        });
+    }
+    static async spawn(input) {
+        const command = await resolveCommand(input.ctx.exec, input.command, input.ctx.env, input.agentId);
+        const process = input.ctx.exec.spawn({
+            command,
+            args: [...input.args],
+            cwd: input.cwd,
+            env: input.ctx.env,
+            stdin: null,
+            keepStdinOpen: true,
+        });
+        return new SessionProcess(process, input.ctx.clock);
+    }
+    get exit() {
+        return this.process.exit;
+    }
+    get exited() {
+        return this.exitValue;
+    }
+    get stderr() {
+        return this.stderrTail;
+    }
+    writeLine(line) {
+        this.process.writeStdin(`${line}\n`);
+    }
+    /** Non-empty stdout lines in order; stderr is kept as a tail for errors. */
+    async *lines() {
+        const buffer = new LineBuffer();
+        for await (const chunk of this.process.chunks) {
+            if (chunk.channel === OUTPUT_CHANNEL.stderr) {
+                this.stderrTail = appendTail(this.stderrTail, chunk.text);
+                continue;
+            }
+            yield* buffer.push(chunk.text);
+        }
+        yield* buffer.flush();
+    }
+    close() {
+        if (this.exitValue !== null) {
+            return Promise.resolve(this.exitValue);
+        }
+        return endProcessGracefully(this.process, this.clock);
+    }
+}
+/**
+ * The Session every host gets. Exactly one turn runs at a time: `send`
+ * needs idle (including while the host has not yet acknowledged a start),
+ * `steer` / `interrupt` need active — both typed `invalid_input`, never a
+ * silent queue. Approval requests belong to the turn that raised them and
+ * die with it; the child's exit fails the running turn, publishes
+ * `exited`, and ends the stream.
+ */
+class DrivenSession {
+    id;
+    agentId;
+    protocol;
+    logger;
+    broadcast = new EventBroadcast(undefined, sessionEventCost);
+    approvals = new Map();
+    /** Items that arrived while the host had not yet acknowledged the turn. */
+    held = [];
+    reading;
+    active = null;
+    starting = false;
+    ended = false;
+    sink;
+    constructor(id, agentId, protocol, logger) {
+        this.id = id;
+        this.agentId = agentId;
+        this.protocol = protocol;
+        this.logger = logger;
+        const driver = this;
+        this.sink = {
+            get activeTurnId() {
+                return driver.active?.turnId ?? null;
+            },
+            message: (text) => this.message(text),
+            tool: (name) => this.emit({ type: SESSION_EVENT_TYPE.tool, name }),
+            approvalRequested: (requestId, summary, payload) => {
+                this.approvals.set(requestId, payload);
+                this.emit({
+                    type: SESSION_EVENT_TYPE.approvalRequested,
+                    requestId,
+                    summary,
+                    decisions: APPROVAL_DECISIONS,
+                });
+            },
+            endTurn: (outcome, text) => this.endTurn(outcome, text),
+        };
+        this.reading = this.read();
+    }
+    get events() {
+        return this.broadcast.events;
+    }
+    async send(text) {
+        this.requireIdle();
+        // The slot is taken from here: a second send() during the host's
+        // round trip is refused, and items that beat the acknowledgement wait.
+        this.starting = true;
+        let turnId;
+        try {
+            turnId = await this.protocol.startTurn(text);
+        }
+        catch (error) {
+            this.starting = false;
+            this.held.splice(0);
+            throw error;
+        }
+        const turn = this.beginTurn(turnId);
+        for (const item of this.held.splice(0)) {
+            this.protocol.decode(item, this.sink);
+        }
+        return turn;
+    }
+    async steer(text) {
+        await this.protocol.steer(this.requireActive(), text);
+    }
+    async interrupt() {
+        await this.protocol.interrupt(this.requireActive());
+    }
+    async respond(requestId, decision) {
+        this.requireOpen();
+        if (!this.approvals.has(requestId)) {
+            throw sessionStateError(this.agentId, `no pending approval request "${requestId}"`);
+        }
+        const payload = this.approvals.get(requestId);
+        this.approvals.delete(requestId);
+        this.protocol.respond(payload, decision);
+    }
+    async close() {
+        await this.protocol.close();
+        await this.reading;
+    }
+    async read() {
+        try {
+            for await (const item of this.protocol.incoming) {
+                if (this.starting) {
+                    this.held.push(item);
+                }
+                else {
+                    this.protocol.decode(item, this.sink);
+                }
+            }
+        }
+        catch (error) {
+            this.logger.log("error", "session reader failed", error);
+        }
+        finally {
+            // Whatever happened above, the stream must end so `events` consumers
+            // and `close()` are released. A child whose exit rejects (spawn-time
+            // `error`) is gone all the same: no code, no signal.
+            this.end(await this.protocol.exit.catch(() => UNKNOWN_EXIT), this.protocol.stderrTail);
+        }
+    }
+    emit(event) {
+        this.broadcast.push(event);
+    }
+    message(text) {
+        this.active?.messages.push(text);
+        this.emit({ type: SESSION_EVENT_TYPE.message, text });
+    }
+    requireOpen() {
+        if (this.ended) {
+            throw sessionStateError(this.agentId, "session is closed");
+        }
+    }
+    requireIdle() {
+        this.requireOpen();
+        if (this.active !== null || this.starting) {
+            throw sessionStateError(this.agentId, "a turn is in progress; use steer() or interrupt()");
+        }
+    }
+    requireActive() {
+        this.requireOpen();
+        if (this.active === null) {
+            throw sessionStateError(this.agentId, "no turn is in progress");
+        }
+        return this.active.turnId;
+    }
+    beginTurn(turnId) {
+        this.starting = false;
+        return new Promise((resolve, reject) => {
+            this.active = { turnId, messages: [], resolve, reject };
+            this.emit({ type: SESSION_EVENT_TYPE.turnStarted, turnId });
+        });
+    }
+    endTurn(outcome, text) {
+        const turn = this.active;
+        if (turn === null) {
+            return;
+        }
+        this.active = null;
+        this.approvals.clear();
+        this.emit({
+            type: SESSION_EVENT_TYPE.turnEnded,
+            turnId: turn.turnId,
+            outcome,
+        });
+        turn.resolve({
+            turnId: turn.turnId,
+            outcome,
+            text: text ?? turn.messages.join("\n"),
+        });
+    }
+    /** The child is gone: fail the running turn, publish `exited`, end the stream. */
+    end(exit, stderrTail) {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        this.starting = false;
+        this.held.splice(0);
+        this.approvals.clear();
+        const turn = this.active;
+        this.active = null;
+        if (turn !== null) {
+            this.emit({
+                type: SESSION_EVENT_TYPE.turnEnded,
+                turnId: turn.turnId,
+                outcome: TURN_OUTCOME.failed,
+            });
+            turn.reject(sessionExitedError(this.agentId, exit, stderrTail));
+        }
+        this.emit({
+            type: SESSION_EVENT_TYPE.exited,
+            code: exit.code,
+            signal: exit.signal,
+        });
+        this.broadcast.end();
+    }
+}
+/** Bind a host protocol to the one Session lifecycle. */
+export function driveSession(input) {
+    return new DrivenSession(input.id, input.agentId, input.protocol, input.logger);
+}

package/dist/testing/fake-exec.d.ts

@@ -1,4 +1,11 @@
 import type { Exec, ExecChunk, ExecExit, ExecSpawnOptions, InteractiveExecSpawnOptions } from "../core/ports.js";
+export type FakeExecControls = {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    exit(exit: ExecExit): void;
+    /** The child never settled normally: `exit` rejects, output ends. */
+    fail(error: Error): void;
+};
 export type FakeExecScript = {
     chunks?: ExecChunk[];
     exitCode?: number;
@@ -8,11 +15,9 @@ export type FakeExecScript = {
     hang?: boolean;
     /** Survive SIGTERM so SIGKILL escalation can be observed. */
     ignoreSigterm?: boolean;
-    onWrite?: (text: string, controls: {
-        stdout(text: string): void;
-        stderr(text: string): void;
-        exit(exit: ExecExit): void;
-    }) => void;
+    onWrite?: (text: string, controls: FakeExecControls) => void;
+    /** Runs when the caller ends stdin — script `controls.exit(...)` here for a child that exits on EOF. */
+    onStdinEnd?: (controls: FakeExecControls) => void;
 };
 export type FakeExec = Exec & {
     readonly spawns: (ExecSpawnOptions | InteractiveExecSpawnOptions)[];

package/dist/testing/fake-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-exec.d.ts","sourceRoot":"","sources":["../../src/testing/fake-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,gBAAgB,EAEhB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;QACR,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;KAC5B,KACE,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,gBAAgB,GAAG,2BAA2B,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvC,CAAC;AAWF,wBAAgB,QAAQ,CAAC,OAAO,GAAE,cAAc,EAAO,GAAG,QAAQ,CAmFjE"}
+{"version":3,"file":"fake-exec.d.ts","sourceRoot":"","sources":["../../src/testing/fake-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,gBAAgB,EAEhB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,qEAAqE;IACrE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC7D,wGAAwG;IACxG,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,gBAAgB,GAAG,2BAA2B,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvC,CAAC;AAWF,wBAAgB,QAAQ,CAAC,OAAO,GAAE,cAAc,EAAO,GAAG,QAAQ,CAkGjE"}

package/dist/testing/fake-exec.js

@@ -18,9 +18,12 @@ export function fakeExec(scripts = []) {
         stdinWrites.push(writes);
         const chunks = new AsyncQueue();
         let settleExit = () => { };
-        const exit = new Promise((resolve) => {
+        let failExit = () => { };
+        const exit = new Promise((resolve, reject) => {
             settleExit = resolve;
+            failExit = reject;
         });
+        void exit.catch(() => { });
         let settleTermination = () => { };
         const termination = new Promise((resolve) => {
             settleTermination = resolve;
@@ -35,10 +38,20 @@ export function fakeExec(scripts = []) {
             settleTermination();
             settleExit(value);
         };
+        const fail = (error) => {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            chunks.end();
+            settleTermination();
+            failExit(error);
+        };
         const controls = {
             stdout: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stdout, text }),
             stderr: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stderr, text }),
             exit: finish,
+            fail,
         };
         for (const chunk of script.chunks ?? []) {
             chunks.push(chunk);
@@ -56,7 +69,9 @@ export function fakeExec(scripts = []) {
                 writes.push(text);
                 script.onWrite?.(text, controls);
             },
-            endStdin: () => { },
+            endStdin: () => {
+                script.onStdinEnd?.(controls);
+            },
             kill: (signal) => {
                 killSignals.push(signal);
                 if (signal === PROCESS_SIGNAL.sigterm &&

package/dist/testing/index.d.ts

@@ -6,6 +6,6 @@
 export { FAKE_AGENT_BEHAVIOR_KIND, type FakeAgentBehavior, type FakeAgentCall, type FakeAgentDefinition, fakeAgent, } from "./fake-agent.js";
 export { type FakeClock, fakeClock } from "./fake-clock.js";
 export { createFakeControlledExec, type FakeControlledExec, type FakeControlledExecScript, } from "./fake-controlled-exec.js";
-export { type FakeExec, type FakeExecScript, fakeExec } from "./fake-exec.js";
+export { type FakeExec, type FakeExecControls, type FakeExecScript, fakeExec, } from "./fake-exec.js";
 export { fakeSecretResolver } from "./fake-secrets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,QAAQ,GACT,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/testing/index.js

@@ -6,5 +6,5 @@
 export { FAKE_AGENT_BEHAVIOR_KIND, fakeAgent, } from "./fake-agent.js";
 export { fakeClock } from "./fake-clock.js";
 export { createFakeControlledExec, } from "./fake-controlled-exec.js";
-export { fakeExec } from "./fake-exec.js";
+export { fakeExec, } from "./fake-exec.js";
 export { fakeSecretResolver } from "./fake-secrets.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpacakit/agents",
-  "version": "0.1.0-beta.39",
+  "version": "0.2.0-beta.3",
   "description": "Run AI coding agents programmatically: execute, stream, classify failures, fail over.",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@alpacakit/core": "0.1.0-beta.39"
+    "@alpacakit/core": "0.2.0-beta.3"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

package/dist/agents/claude.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+CH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAC7D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAsK1D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CA0CvD;AA6TD,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CAClD,CAAC;AAEF,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAgF7E"}