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

package/dist/kernel/session.js

@@ -0,0 +1,255 @@
+/**
+ * Session driver pieces shared by the built-in hosts: the definition-side
+ * capability contract, the long-lived interactive child (spawn, NDJSON
+ * lines, EOF-first close), and the turn/event state
+ * every Session keeps. Protocol knowledge (what to write, how to read a
+ * line) stays in the adapter modules.
+ */
+import { AGENT_ERROR_CODE, AgentError, NOT_AVAILABLE_CAUSE, } from "../core/error.js";
+import { redactSecrets } from "../core/redact.js";
+import { SESSION_EVENT_TYPE, TURN_OUTCOME, } from "../core/session.js";
+import { endProcessGracefully } from "../core/process-close.js";
+import { OUTPUT_CHANNEL } from "../core/values.js";
+import { EventBroadcast } from "./handle.js";
+const OUTPUT_TAIL_CHARS = 2_000;
+const EVENT_BASE_COST_BYTES = 64;
+/** 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;
+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));
+}
+function appendTail(current, next) {
+    const combined = current + next;
+    return combined.length <= OUTPUT_TAIL_CHARS
+        ? combined
+        : combined.slice(-OUTPUT_TAIL_CHARS);
+}
+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) {
+    const tail = redactSecrets(stderrTail);
+    return new AgentError({
+        code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
+        message: `Agent "${agentId}" session process exited`,
+        data: {
+            exitCode: exit?.code ?? null,
+            stdoutTail: null,
+            stderrTail: tail === "" ? null : tail,
+        },
+        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 = { code: null, signal: null };
+        });
+    }
+    static async spawn(input) {
+        const command = await input.ctx.exec.which(input.command, input.ctx.env);
+        if (command === null) {
+            throw new AgentError({
+                code: AGENT_ERROR_CODE.notAvailable,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
+                message: `Command "${input.command}" was not found on PATH`,
+                data: { cause: NOT_AVAILABLE_CAUSE.notInstalled },
+                agentId: 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() {
+        let pending = "";
+        for await (const chunk of this.process.chunks) {
+            if (chunk.channel === OUTPUT_CHANNEL.stderr) {
+                this.stderrTail = appendTail(this.stderrTail, chunk.text);
+                continue;
+            }
+            pending += chunk.text;
+            const lines = pending.split(/\r?\n/u);
+            pending = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed !== "") {
+                    yield trimmed;
+                }
+            }
+        }
+        const last = pending.trim();
+        if (last !== "") {
+            yield last;
+        }
+    }
+    close() {
+        if (this.exitValue !== null) {
+            return Promise.resolve(this.exitValue);
+        }
+        return endProcessGracefully(this.process, this.clock);
+    }
+}
+/**
+ * Turn bookkeeping and the event stream. Exactly one turn runs at a time:
+ * `send` needs idle, `steer`/`interrupt` need active — both are typed
+ * `invalid_input`, never a silent queue.
+ */
+export class SessionState {
+    agentId;
+    broadcast = new EventBroadcast(undefined, sessionEventCost);
+    active = null;
+    /** A turn whose start the host has not acknowledged yet (Codex `turn/start` in flight). */
+    starting = false;
+    ended = false;
+    constructor(agentId) {
+        this.agentId = agentId;
+    }
+    get events() {
+        return this.broadcast.events;
+    }
+    get activeTurnId() {
+        return this.active?.turnId ?? null;
+    }
+    get isEnded() {
+        return this.ended;
+    }
+    get isStarting() {
+        return this.starting;
+    }
+    emit(event) {
+        this.broadcast.push(event);
+    }
+    /** Record a message for the turn's fallback text and publish it. */
+    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()");
+        }
+    }
+    /** Reserve the idle slot while the host is asked to start the turn. */
+    markStarting() {
+        this.starting = true;
+    }
+    /** The host refused to start the turn; the slot is idle again. */
+    clearStarting() {
+        this.starting = false;
+    }
+    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 });
+        });
+    }
+    /** `text === null` falls back to the turn's collected messages. */
+    endTurn(outcome, text) {
+        const turn = this.active;
+        if (turn === null) {
+            return;
+        }
+        this.active = null;
+        this.emit({
+            type: SESSION_EVENT_TYPE.turnEnded,
+            turnId: turn.turnId,
+            outcome,
+        });
+        turn.resolve({
+            turnId: turn.turnId,
+            outcome,
+            text: text ?? turn.messages.join("\n"),
+        });
+    }
+    /** The process is gone: fail the running turn, publish `exited`, end the stream. */
+    end(exit, stderrTail) {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        this.starting = false;
+        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();
+    }
+}

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

@@ -13,6 +13,12 @@ export type FakeExecScript = {
         stderr(text: string): void;
         exit(exit: ExecExit): void;
     }) => void;
+    /** Runs when the caller ends stdin — script `controls.exit(...)` here for a child that exits on EOF. */
+    onStdinEnd?: (controls: {
+        stdout(text: string): void;
+        stderr(text: string): void;
+        exit(exit: ExecExit): void;
+    }) => 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,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;IACV,wGAAwG;IACxG,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE;QACtB,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,KAAK,IAAI,CAAC;CACZ,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,CAqFjE"}

package/dist/testing/fake-exec.js

@@ -56,7 +56,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpacakit/agents",
-  "version": "0.1.0-beta.39",
+  "version": "0.2.0-beta.2",
   "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.2"
   },
   "devDependencies": {
     "typescript": "^5.9.3",