edsger 0.64.0 → 0.66.0

package/dist/commands/session-serve/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `edsger session-serve <channelId>` — long-lived conversational agent for one
+ * chat session.
+ *
+ * Where `session-turn` runs a single turn and exits, `session-serve` prepares
+ * the session context once (repo clone, MCP toolbelt, system prompt) and then
+ * stays alive, running one turn per command it reads from stdin. The SDK
+ * session id is kept in memory and carried into the next turn automatically, so
+ * the conversation (and prompt cache) stays warm without a per-turn cold start.
+ *
+ * Protocol — one JSON object per line on stdin:
+ *   {"type":"turn"}                                  process pending messages
+ *   {"type":"run-finished","runId":"…","command":"…"} report a finished cli_* run
+ *   {"type":"shutdown"}                               drain + exit cleanly
+ *
+ * Turns run strictly one at a time (a session never has two turns in flight).
+ * When stdin closes, the process exits after the current turn drains. Markers
+ * (session id, background cli runs) are written to stdout exactly as the
+ * one-shot command emits them, so the desktop's existing parsing is unchanged.
+ */
+import { type SessionTurnCliOptions } from '../session-turn/index.js';
+/**
+ * Emitted once the session context is built and the process is ready to accept
+ * turn commands on stdin. The desktop may use it to know the daemon is live;
+ * it is harmless to ignore.
+ */
+export declare const SESSION_READY_MARKER = "__EDSGER_SESSION_READY__";
+export type SessionServeCliOptions = Omit<SessionTurnCliOptions, 'runFinished'> & {
+    /** SDK session id to resume on the first turn (e.g. after a crash-restart). */
+    resumeSessionId?: string;
+};
+export declare function runSessionServeCommand(options: SessionServeCliOptions): Promise<void>;

package/dist/commands/session-serve/index.js

@@ -0,0 +1,100 @@
+/**
+ * `edsger session-serve <channelId>` — long-lived conversational agent for one
+ * chat session.
+ *
+ * Where `session-turn` runs a single turn and exits, `session-serve` prepares
+ * the session context once (repo clone, MCP toolbelt, system prompt) and then
+ * stays alive, running one turn per command it reads from stdin. The SDK
+ * session id is kept in memory and carried into the next turn automatically, so
+ * the conversation (and prompt cache) stays warm without a per-turn cold start.
+ *
+ * Protocol — one JSON object per line on stdin:
+ *   {"type":"turn"}                                  process pending messages
+ *   {"type":"run-finished","runId":"…","command":"…"} report a finished cli_* run
+ *   {"type":"shutdown"}                               drain + exit cleanly
+ *
+ * Turns run strictly one at a time (a session never has two turns in flight).
+ * When stdin closes, the process exits after the current turn drains. Markers
+ * (session id, background cli runs) are written to stdout exactly as the
+ * one-shot command emits them, so the desktop's existing parsing is unchanged.
+ */
+import { createInterface } from 'node:readline';
+import { logError, logInfo } from '../../utils/logger.js';
+import { prepareSessionContext, runTurn, } from '../session-turn/index.js';
+/**
+ * Emitted once the session context is built and the process is ready to accept
+ * turn commands on stdin. The desktop may use it to know the daemon is live;
+ * it is harmless to ignore.
+ */
+export const SESSION_READY_MARKER = '__EDSGER_SESSION_READY__';
+export async function runSessionServeCommand(options) {
+    const ctx = await prepareSessionContext(options);
+    process.stdout.write(`\n${SESSION_READY_MARKER}\n`);
+    logInfo(`Session ${ctx.channelId} ready — awaiting turns on stdin.`);
+    // Commands queue up here; we drain them one at a time so a session never has
+    // two turns running concurrently. `shuttingDown` stops accepting new work.
+    const queue = [];
+    let running = false;
+    let shuttingDown = false;
+    let stdinEnded = false;
+    const maybeExit = () => {
+        if ((shuttingDown || stdinEnded) && !running && queue.length === 0) {
+            logInfo(`Session ${ctx.channelId} shutting down.`);
+            process.exit(0);
+        }
+    };
+    const drain = async () => {
+        if (running) {
+            return;
+        }
+        running = true;
+        try {
+            while (queue.length > 0) {
+                const cmd = queue.shift();
+                if (cmd.type === 'shutdown') {
+                    shuttingDown = true;
+                    continue;
+                }
+                try {
+                    if (cmd.type === 'run-finished' && cmd.runId) {
+                        await runTurn(ctx, {
+                            runFinished: { runId: cmd.runId, command: cmd.command },
+                        });
+                    }
+                    else {
+                        await runTurn(ctx);
+                    }
+                }
+                catch (error) {
+                    logError(`Turn failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        finally {
+            running = false;
+            maybeExit();
+        }
+    };
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed || shuttingDown) {
+            return;
+        }
+        let cmd;
+        try {
+            cmd = JSON.parse(trimmed);
+        }
+        catch {
+            logError(`Ignoring malformed command: ${trimmed}`);
+            return;
+        }
+        queue.push(cmd);
+        void drain();
+    });
+    // stdin closing is the desktop's normal "stop this session" signal.
+    rl.on('close', () => {
+        stdinEnded = true;
+        maybeExit();
+    });
+}

package/dist/commands/session-turn/index.d.ts

@@ -4,12 +4,70 @@
  * its own line and free of logger formatting so it parses cleanly.
  */
 export declare const SESSION_ID_MARKER = "__EDSGER_SESSION_ID__=";
+/**
+ * Marker emitted on stdout for each background `cli_*` run still in flight when
+ * the turn ends. The desktop main process parses these, watches each run to
+ * completion (the turn process itself exits immediately), and then re-engages
+ * the agent via `--run-finished` so it reports results without the user having
+ * to ask. The JSON payload is `{ run_id, pid, log_path, command }`.
+ */
+export declare const CLI_RUN_MARKER = "__EDSGER_CLI_RUN__=";
+import { loadExternalMcpServers } from 'edsger-tools';
 export interface SessionTurnCliOptions {
     channelId: string;
     productId: string;
     repositoryIds?: string[];
     /** SDK session id from a previous turn, to resume the same conversation. */
     resumeSessionId?: string;
+    /**
+     * Follow-up turn triggered by the desktop watcher when a background `cli_*`
+     * run finishes. When set, the turn is driven by a synthetic prompt instead of
+     * the channel's pending human messages: the agent inspects what the run
+     * produced and reports it to the user.
+     */
+    runFinished?: {
+        runId: string;
+        command?: string;
+    };
     verbose?: boolean;
 }
+/**
+ * Everything a session needs to run turns, built once and reused. The daemon
+ * keeps a single instance alive across turns so repo clones, the MCP toolbelt,
+ * the system prompt, and the SDK session id all persist.
+ */
+export interface SessionContext {
+    channelId: string;
+    productId: string;
+    repositoryIds: string[];
+    verbose: boolean;
+    sessionDir?: string;
+    systemPrompt: string;
+    sessionServer: any;
+    external: ReturnType<typeof loadExternalMcpServers>;
+    /** Latest SDK session id; carried into the next turn's `resume`. Mutable. */
+    sdkSessionId: string;
+}
+/**
+ * Build the one-time session context: clone repos, assemble the MCP toolbelt
+ * and external servers, and build the system prompt. Cheap to call once per
+ * session process; expensive to call per turn (which is why the daemon doesn't).
+ */
+export declare function prepareSessionContext(options: SessionTurnCliOptions): Promise<SessionContext>;
+/**
+ * Run a single agent turn against an already-prepared {@link SessionContext}.
+ * Mutates `ctx.sdkSessionId` so the next turn resumes the same SDK conversation
+ * (and prompt cache). Safe to call repeatedly for the life of the process.
+ */
+export declare function runTurn(ctx: SessionContext, opts?: {
+    runFinished?: {
+        runId: string;
+        command?: string;
+    };
+}): Promise<void>;
+/**
+ * One-shot `session-turn`: prepare the context and run a single turn. Retained
+ * for callers that want the previous per-turn-process behaviour (and as the
+ * building block the daemon reuses).
+ */
 export declare function runSessionTurnCommand(options: SessionTurnCliOptions): Promise<void>;

package/dist/commands/session-turn/index.js

@@ -4,6 +4,14 @@
  * its own line and free of logger formatting so it parses cleanly.
  */
 export const SESSION_ID_MARKER = '__EDSGER_SESSION_ID__=';
+/**
+ * Marker emitted on stdout for each background `cli_*` run still in flight when
+ * the turn ends. The desktop main process parses these, watches each run to
+ * completion (the turn process itself exits immediately), and then re-engages
+ * the agent via `--run-finished` so it reports results without the user having
+ * to ask. The JSON payload is `{ run_id, pid, log_path, command }`.
+ */
+export const CLI_RUN_MARKER = '__EDSGER_CLI_RUN__=';
 /**
  * `edsger session-turn <channelId>` — run one conversational agent turn for a
  * chat session (an ai_assistant channel bound to a product).
@@ -15,9 +23,15 @@ export const SESSION_ID_MARKER = '__EDSGER_SESSION_ID__=';
  * to the channel and marks the messages processed. The agent decides what to
  * do (answer, generate stories/test cases, launch cli_* analyses, open PRs);
  * there is no fixed pipeline.
+ *
+ * The per-turn work is split into {@link prepareSessionContext} (one-time
+ * workspace clone + toolbelt + prompt build) and {@link runTurn} (one agent
+ * turn against that context). The one-shot `session-turn` command does both
+ * once; the long-lived `session-serve` daemon prepares the context once and
+ * calls {@link runTurn} repeatedly, keeping the SDK session warm across turns.
  */
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { buildSessionAgentOptions, buildSessionSystemPrompt, buildSessionUserPrompt, createSessionMcpServer, loadExternalMcpServers, SESSION_MAX_TURNS, } from 'edsger-tools';
+import { buildSessionAgentOptions, buildSessionSystemPrompt, buildSessionUserPrompt, createSessionMcpServer, listActiveCliRuns, loadExternalMcpServers, SESSION_MAX_TURNS, } from 'edsger-tools';
 import { callMcpEndpoint } from '../../api/mcp-client.js';
 import { DEFAULT_MODEL } from '../../constants.js';
 import { getToolDeps } from '../../tools/bootstrap.js';
@@ -45,33 +59,21 @@ async function prepareSessionWorkspace(opts) {
         repoScopeNote: workspace ? describeSessionRepos(workspace.repos) : '',
     };
 }
-export async function runSessionTurnCommand(options) {
+/**
+ * Build the one-time session context: clone repos, assemble the MCP toolbelt
+ * and external servers, and build the system prompt. Cheap to call once per
+ * session process; expensive to call per turn (which is why the daemon doesn't).
+ */
+export async function prepareSessionContext(options) {
     const { channelId, productId, repositoryIds = [], resumeSessionId, verbose = false, } = options;
-    // Emit the SDK session id so the desktop can persist it for the next turn.
-    const emitSessionId = (id) => {
-        if (id) {
-            process.stdout.write(`\n${SESSION_ID_MARKER}${id}\n`);
-        }
-    };
-    // 1. Load the pending human messages that triggered this turn.
-    const pendingResult = (await callMcpEndpoint('chat/messages/pending', {
-        channel_id: channelId,
-    }));
-    const messages = pendingResult.messages ?? [];
-    if (messages.length === 0) {
-        logInfo('No pending messages for this session — nothing to do.');
-        return;
-    }
-    logInfo(`Processing ${messages.length} message(s) for session ${channelId}`);
-    // 2. Clone the product's in-scope repositories into a local session
-    //    directory so the agent's Read/Grep/Glob can inspect the real code.
+    // Clone the product's in-scope repositories into a local session directory
+    // so the agent's Read/Grep/Glob can inspect the real code.
     const { sessionDir, repoScopeNote } = await prepareSessionWorkspace({
         channelId,
         productId,
         repositoryIds,
         verbose,
     });
-    // 3. Build the session toolbelt + prompts.
     const deps = getToolDeps({
         verbose,
         context: { productId, channelId, repositoryIds },
@@ -89,36 +91,95 @@ export async function runSessionTurnCommand(options) {
         repoScopeNote,
         externalMcpNames: external.names,
     });
-    const userPrompt = buildSessionUserPrompt(messages);
-    // 4. Run one SDK turn. Resume the prior SDK session when we have its id so
+    return {
+        channelId,
+        productId,
+        repositoryIds,
+        verbose,
+        sessionDir,
+        systemPrompt,
+        sessionServer,
+        external,
+        sdkSessionId: resumeSessionId ?? '',
+    };
+}
+/** Emit the SDK session id so the desktop can persist it for the next turn. */
+function emitSessionId(id) {
+    if (id) {
+        process.stdout.write(`\n${SESSION_ID_MARKER}${id}\n`);
+    }
+}
+/**
+ * Emit a marker for every background cli_* run still in flight, so the desktop
+ * watcher can poll each to completion and re-engage the agent.
+ */
+function emitActiveCliRuns() {
+    for (const run of listActiveCliRuns()) {
+        const payload = JSON.stringify({
+            run_id: run.run_id,
+            pid: run.pid,
+            log_path: run.log_path,
+            command: run.command,
+        });
+        process.stdout.write(`\n${CLI_RUN_MARKER}${payload}\n`);
+    }
+}
+/**
+ * Run a single agent turn against an already-prepared {@link SessionContext}.
+ * Mutates `ctx.sdkSessionId` so the next turn resumes the same SDK conversation
+ * (and prompt cache). Safe to call repeatedly for the life of the process.
+ */
+export async function runTurn(ctx, opts = {}) {
+    const { runFinished } = opts;
+    // 1. Decide what drives this turn. A normal turn replays the channel's
+    //    pending human messages; a watcher-triggered follow-up replays a
+    //    synthetic prompt about the background run that just finished.
+    let messages = [];
+    if (runFinished) {
+        logInfo(`Reporting completion of background run ${runFinished.runId} for session ${ctx.channelId}`);
+    }
+    else {
+        const pendingResult = (await callMcpEndpoint('chat/messages/pending', {
+            channel_id: ctx.channelId,
+        }));
+        messages = pendingResult.messages ?? [];
+        if (messages.length === 0) {
+            logInfo('No pending messages for this session — nothing to do.');
+            return;
+        }
+        logInfo(`Processing ${messages.length} message(s) for session ${ctx.channelId}`);
+    }
+    const userPrompt = runFinished
+        ? buildRunFinishedPrompt(runFinished)
+        : buildSessionUserPrompt(messages);
+    // 2. Run one SDK turn. Resume the prior SDK session when we have its id so
     //    the conversation (and prompt cache) carries across turns. Point the
     //    agent's cwd at the session directory so its read-only file tools resolve
     //    against the cloned repos. Prompt + tool/MCP wiring come from the shared
     //    session core (edsger-tools) so CLI and worker can't drift apart.
     let finalResponse = '';
-    let sdkSessionId = resumeSessionId ?? '';
     try {
         for await (const message of query({
             prompt: userPrompt,
             options: {
-                ...buildSessionAgentOptions(systemPrompt, {
-                    sessionServer,
-                    externalServers: external.servers,
-                    externalNames: external.names,
-                    sessionDir,
+                ...buildSessionAgentOptions(ctx.systemPrompt, {
+                    sessionServer: ctx.sessionServer,
+                    externalServers: ctx.external.servers,
+                    externalNames: ctx.external.names,
+                    sessionDir: ctx.sessionDir,
                     maxTurns: SESSION_MAX_TURNS,
                 }),
                 model: DEFAULT_MODEL,
-                ...(resumeSessionId ? { resume: resumeSessionId } : {}),
+                ...(ctx.sdkSessionId ? { resume: ctx.sdkSessionId } : {}),
             },
         })) {
             const msg = message;
             // The system/init and result messages carry the (possibly new) session
             // id — keep the latest so we persist what the next turn should resume.
             if (msg.session_id) {
-                sdkSessionId = msg.session_id;
+                ctx.sdkSessionId = msg.session_id;
             }
-            if (verbose && msg.type === 'assistant') {
+            if (ctx.verbose && msg.type === 'assistant') {
                 logInfo('· agent step');
             }
             if (msg.type === 'result') {
@@ -131,21 +192,22 @@ export async function runSessionTurnCommand(options) {
         const reason = error instanceof Error ? error.message : String(error);
         logError(`Session turn failed: ${reason}`);
         await callMcpEndpoint('chat/messages/send_ai', {
-            channel_id: channelId,
+            channel_id: ctx.channelId,
             content: `I hit an error processing that: ${reason}`,
             message_type: 'text',
             metadata: {},
         }).catch(() => undefined);
-        emitSessionId(sdkSessionId);
+        emitSessionId(ctx.sdkSessionId);
+        emitActiveCliRuns();
         await markProcessed(messages);
         return;
     }
-    // 5. Post the final reply (the agent may also have posted via
+    // 3. Post the final reply (the agent may also have posted via
     //    send_chat_message during the turn; this carries the closing summary).
     const reply = finalResponse.trim();
     if (reply) {
         await callMcpEndpoint('chat/messages/send_ai', {
-            channel_id: channelId,
+            channel_id: ctx.channelId,
             content: reply,
             message_type: 'text',
             metadata: {},
@@ -153,12 +215,36 @@ export async function runSessionTurnCommand(options) {
             logError(`Failed to post reply: ${e instanceof Error ? e.message : String(e)}`);
         });
     }
-    // 6. Mark the triggering messages processed so they aren't re-run.
+    // 4. Mark the triggering messages processed so they aren't re-run. (No-op for
+    //    a watcher follow-up, which has no triggering human messages.)
     await markProcessed(messages);
-    // 7. Emit the SDK session id so the desktop persists it for the next turn.
-    emitSessionId(sdkSessionId);
+    // 5. Emit the SDK session id so the desktop persists it for the next turn,
+    //    plus a marker for any background run launched this turn so the watcher
+    //    keeps following it to completion.
+    emitSessionId(ctx.sdkSessionId);
+    emitActiveCliRuns();
     logSuccess('Session turn complete.');
 }
+/**
+ * One-shot `session-turn`: prepare the context and run a single turn. Retained
+ * for callers that want the previous per-turn-process behaviour (and as the
+ * building block the daemon reuses).
+ */
+export async function runSessionTurnCommand(options) {
+    const ctx = await prepareSessionContext(options);
+    await runTurn(ctx, { runFinished: options.runFinished });
+}
+/**
+ * The synthetic user prompt for a watcher-triggered follow-up turn. Steers the
+ * agent to inspect what the finished run produced and report it — explicitly
+ * NOT to ask the user whether it should check.
+ */
+function buildRunFinishedPrompt(runFinished) {
+    const which = runFinished.command
+        ? `the \`${runFinished.command}\` analysis (run ${runFinished.runId})`
+        : `a background analysis you launched earlier (run ${runFinished.runId})`;
+    return `${which} just finished. Inspect what it produced — call get_cli_run with run_id "${runFinished.runId}" for the log tail, then use the list_* / get_* tools (e.g. list_issues) to see the findings it filed. Summarize the results for the user via send_chat_message. Do not ask whether you should check — just report what you found. If nothing of note was produced, say so briefly.`;
+}
 async function markProcessed(messages) {
     for (const m of messages) {
         await callMcpEndpoint('chat/messages/mark_processed', {

package/dist/index.js

@@ -32,6 +32,7 @@ import { runRefactor } from './commands/refactor/refactor.js';
 import { runReleaseSyncCommand } from './commands/release-sync/index.js';
 import { runRunSheetCommand } from './commands/run-sheet/index.js';
 import { runScreenFlow } from './commands/screen-flow/index.js';
+import { runSessionServeCommand } from './commands/session-serve/index.js';
 import { runSessionTurnCommand } from './commands/session-turn/index.js';
 import { runSmokeTestCommand } from './commands/smoke-test/index.js';
 import { runSyncAws } from './commands/sync-aws/index.js';
@@ -441,10 +442,43 @@ program
     .requiredOption('--product <productId>', 'Product the session is bound to')
     .option('--repos <ids>', 'Comma-separated repository IDs the agent may touch', '')
     .option('--resume <sessionId>', 'SDK session id from a previous turn to resume the same conversation')
+    .option('--run-finished <runId>', 'Follow-up turn: report the results of a background cli_* run that finished')
+    .option('--run-command <command>', 'The command name of the finished run (used with --run-finished)')
     .option('-v, --verbose', 'Verbose output')
     .action(async (channelId, opts) => {
     try {
         await runSessionTurnCommand({
+            channelId,
+            productId: opts.product,
+            repositoryIds: (opts.repos ?? '')
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean),
+            resumeSessionId: opts.resume,
+            runFinished: opts.runFinished
+                ? { runId: opts.runFinished, command: opts.runCommand }
+                : undefined,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
+// Subcommand: edsger session-serve <channelId>
+// ============================================================
+program
+    .command('session-serve <channelId>')
+    .description('Run a long-lived conversational agent for a chat session, taking one turn per command read from stdin')
+    .requiredOption('--product <productId>', 'Product the session is bound to')
+    .option('--repos <ids>', 'Comma-separated repository IDs the agent may touch', '')
+    .option('--resume <sessionId>', 'SDK session id to resume on the first turn (e.g. after a crash-restart)')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (channelId, opts) => {
+    try {
+        await runSessionServeCommand({
             channelId,
             productId: opts.product,
             repositoryIds: (opts.repos ?? '')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"
@@ -51,7 +51,7 @@
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.4.5",
     "edsger-contract": "0.7.0",
-    "edsger-tools": "0.7.0",
+    "edsger-tools": "0.8.0",
     "gray-matter": "^4.0.3",
     "zod": "^4.0.0"
   },