@ashulab/carrier 0.0.0-stage → 0.1.0

package/dist/storage/migrations/meta/_journal.json

@@ -0,0 +1,146 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1792107368123,
+      "tag": "0000_nosy_demogoblin",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1792110236763,
+      "tag": "0001_worried_grey_gargoyle",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1792110369085,
+      "tag": "0002_tough_squirrel_girl",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1792110528735,
+      "tag": "0003_loose_maria_hill",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1792110685939,
+      "tag": "0004_long_cerise",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1792110971681,
+      "tag": "0005_review_result",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1792111308909,
+      "tag": "0006_melted_menace",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1792112657720,
+      "tag": "0007_powerful_bloodscream",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1792115524318,
+      "tag": "0008_panel_state",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1792623095914,
+      "tag": "0009_workable_tiger_shark",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "6",
+      "when": 1792623358681,
+      "tag": "0010_nasty_blue_marvel",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1792626772918,
+      "tag": "0011_steep_lila_cheney",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1792627173096,
+      "tag": "0012_talented_big_bertha",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1792627711767,
+      "tag": "0013_third_mulholland_black",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "6",
+      "when": 1792686570245,
+      "tag": "0014_perfect_marten_broadcloak",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1792694856099,
+      "tag": "0015_long_bloodaxe",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "6",
+      "when": 1792696928274,
+      "tag": "0016_neat_true_believers",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "6",
+      "when": 1793069239835,
+      "tag": "0017_previous_swarm",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "6",
+      "when": 1793159586953,
+      "tag": "0018_opposite_plazm",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "6",
+      "when": 1793159956678,
+      "tag": "0019_hesitant_triton",
+      "breakpoints": true
+    }
+  ]
+}

package/dist/storage/schema.js

@@ -0,0 +1,43 @@
+import { integer, sqliteTable, text, uniqueIndex } from 'drizzle-orm/sqlite-core';
+export const needsHumanKinds = ['review_limit', 'agent_needs_human', 'retries_exhausted', 'timeout', 'auth', 'workspace', 'pr_invalid', 'usage_limit'];
+export const epicStates = ['queued', 'running', 'ready_for_test', 'needs_human', 'cancelled', 'merged', 'repo_removed'];
+export const epics = sqliteTable('epics', {
+    // Autoincrement id is the stable queue order: rows are never reused or reordered.
+    id: integer().primaryKey({ autoIncrement: true }),
+    repo: text().notNull(),
+    issue: integer().notNull(),
+    status: text({ enum: epicStates }).notNull().default('queued'),
+    queuedAt: integer().notNull().default(0), // ms since epoch, when the poll registered it
+    startedAt: integer(), // ms since epoch, when the scheduler reserved it
+    // Effective repo config frozen at reservation: later config changes do not touch a running epic.
+    config: text({ mode: 'json' }).$type(),
+    cancelReason: text(),
+    // The running label is a reflection of SQLite: true while it has not reached GitHub yet.
+    labelPending: integer({ mode: 'boolean' }).notNull().default(false),
+    stage: text({ enum: ['ship', 'review', 'fix'] }), // null until the author is launched
+    stageStartedAt: integer(), // ms since epoch, when the epic entered its current stage
+    // Where the author's epic worktree really is (read back from `git worktree list` after ship); fix turns run there.
+    workspace: text(),
+    lastActivityAt: integer(), // ms since epoch of the agent's last output, written at most every 10 s
+    lastError: text(), // the last technical failure of a stage; cleared when a result is imported
+    round: integer(), // review round, from 1 once the final PR is validated
+    prNumber: integer(),
+    prHeadSha: text(),
+    pr: text({ mode: 'json' }).$type(), // what GitHub said about the PR the last time the poll asked: a cache, never read to decide anything
+    reviewedSha: text(), // head the reviewer approved, set when the epic becomes ready_for_test
+    verification: text({ mode: 'json' }).$type(), // what the reviewer reported about the checks
+    observationsPassAt: integer(), // ms since epoch, when the observations pass started (once per epic); null until then
+    needsHumanReason: text(),
+    needsHumanKind: text({ enum: needsHumanKinds }), // what kind of stop the reason is; set together with it
+    title: text(), // the issue's title and labels as the poll last read them
+    labels: text({ mode: 'json' }).$type(),
+    branch: text(), // the final PR's branch, set when ship is validated
+    // Set while `repo_removed`: where the epic was and why it stopped, so it goes back there when the repo returns.
+    removedFrom: text({ enum: epicStates }),
+    removedReason: text(),
+    finishedAt: integer(), // ms since epoch, when the epic left `running`
+    // The agent option each role runs on, set when the epic is reserved and replaced by a choice; null on epics from before options existed.
+    authorOption: text(),
+    reviewerOption: text(),
+    choiceDeadline: integer(), // ms since epoch: while set, the running epic waits for its choice and has launched nothing
+}, (table) => [uniqueIndex('epics_repo_issue').on(table.repo, table.issue)]);

package/dist/terminal/cli/args.js

@@ -0,0 +1,91 @@
+import { parseArgs } from 'node:util';
+import { defaultConfigPath } from '../../config/default-path.js';
+export const commandNames = ['init', 'doctor', 'schema', 'start', 'status', 'watch', 'stop', 'pause', 'resume', 'check', 'restart', 'chat', 'chat-host'];
+export const usage = () => `Usage: carrier --config <path>          run the orchestrator
+       carrier start --config <path>     run it in the background, without a terminal
+       carrier init [flags]              guided setup: writes the config and checks it
+       carrier doctor --config <path> [--json]   check the config and what this machine needs (--json: the checks as a JSON array on stdout, for the app)
+       carrier schema                    print the JSON Schema of the config
+       carrier status                    show once what the running Carrier is doing (exit 1: not running)
+       carrier watch                     the live panel of the running Carrier; q leaves it running (exit 1: not running)
+       carrier stop|pause|resume|check   stop Carrier, pause or resume intake, look at GitHub now
+       carrier restart <owner/name>#<issue> [--author <option>] [--reviewer <option>]   resume a stopped epic on the options you choose
+       carrier chat --workspace <folder> [--agent <name>]   talk to an agent in a folder (starts the chat host if needed)
+       carrier chat --resume <id>        go on with a closed chat session, after the end of its transcript
+       carrier chat --list [--archived]  list chat sessions (the archived ones with --archived)
+       carrier chat --archive|--unarchive|--delete <id>   archive, unarchive or delete a chat session
+       carrier chat --stop               stop the chat host
+       carrier chat-host                 run the chat host in the foreground
+       carrier --version                 print the installed version
+
+--config defaults to ${defaultConfigPath()} (where init writes it) when that file exists.
+
+restart: with neither flag it asks for each role in a terminal and keeps the current options without one. --author and --reviewer name an option
+of the config here, not the <harness>:<model> of init.
+
+init flags (each one skips its question; --yes never asks):
+  --repo <owner/name>            repeat for several repos
+  --identities <separate|shared>  separate: a different identity per role (default); shared: your gh login for both
+  --author-profile <forge:<agent>|gh>   --reviewer-profile <forge:<agent>|gh>   --lead-reviewer-profile <forge:<agent>|gh>
+  --author <harness>:<model>            --reviewer <harness>:<model>            --lead-reviewer <harness>:<model>
+  --author-provider <lmstudio|ollama>   --reviewer-provider <lmstudio|ollama>   --lead-reviewer-provider <lmstudio|ollama>
+  --author-persona-name <text>   --reviewer-persona-name <text>   --lead-reviewer-persona-name <text>
+  --author-persona-prompt <text> --reviewer-persona-prompt <text> --lead-reviewer-persona-prompt <text>
+  --out <path>                   default is the --config default above
+  --yes                          no questions; overwrite the output file (without --author and --reviewer, one claude option runs both roles)`;
+const options = {
+    config: { type: 'string' },
+    repo: { type: 'string', multiple: true },
+    identities: { type: 'string' },
+    'author-profile': { type: 'string' },
+    'reviewer-profile': { type: 'string' },
+    'lead-reviewer-profile': { type: 'string' },
+    author: { type: 'string' },
+    reviewer: { type: 'string' },
+    'lead-reviewer': { type: 'string' },
+    'author-provider': { type: 'string' },
+    'reviewer-provider': { type: 'string' },
+    'lead-reviewer-provider': { type: 'string' },
+    'author-persona-name': { type: 'string' },
+    'author-persona-prompt': { type: 'string' },
+    'reviewer-persona-name': { type: 'string' },
+    'reviewer-persona-prompt': { type: 'string' },
+    'lead-reviewer-persona-name': { type: 'string' },
+    'lead-reviewer-persona-prompt': { type: 'string' },
+    out: { type: 'string' },
+    yes: { type: 'boolean' },
+    json: { type: 'boolean' },
+    list: { type: 'boolean' },
+    stop: { type: 'boolean' },
+    workspace: { type: 'string' },
+    agent: { type: 'string' },
+    resume: { type: 'string' },
+    archived: { type: 'boolean' },
+    archive: { type: 'string' },
+    unarchive: { type: 'string' },
+    delete: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+};
+const targetPattern = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9]\d*)$/;
+/** The command line as data: no process exit, no output. A bad flag or an unknown command is `ok: false` with what to say. */
+export function parseCli(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, allowPositionals: true, options });
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+    const [command, ...extra] = parsed.positionals;
+    if (command === 'restart') {
+        const match = extra.length === 1 ? targetPattern.exec(extra[0]) : null;
+        const repo = match?.[1];
+        if (!match || repo.split('/').some((part) => part === '.' || part === '..') || !Number.isSafeInteger(Number(match[2])))
+            return { ok: false, message: 'restart takes one epic as owner/name#N, for example AshuLab/carrier#12' };
+        return { ok: true, command, flags: parsed.values, target: { repo: repo, issue: Number(match[2]) } };
+    }
+    if (extra.length > 0 || (command !== undefined && !commandNames.includes(command)))
+        return { ok: false, message: `Unknown command: ${parsed.positionals.join(' ')}` };
+    return { ok: true, command: command, flags: parsed.values };
+}

package/dist/terminal/cli/cli-error.js

@@ -0,0 +1,11 @@
+/** A failure to report to the person at the terminal and exit with `code`: bad usage (2) or a problem they can fix (1). */
+export class CliError extends Error {
+    code;
+    lines;
+    // No parameter properties: Node strips types at runtime and cannot run that syntax.
+    constructor(code, ...lines) {
+        super(lines.join('\n'));
+        this.code = code;
+        this.lines = lines;
+    }
+}

package/dist/terminal/cli/commands/chat-host.js

@@ -0,0 +1,18 @@
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { ChatConfigInvalid, HostBusy, startChatHost } from '../../../chat/host.js';
+import { CliError } from '../cli-error.js';
+/** `carrier chat-host`: the chat host in the foreground, from the Carrier folder alone, until a `stop` request, the idle exit or a signal. How a client's host runs, and how to debug it. */
+export async function chatHostCommand() {
+    try {
+        await startChatHost();
+    }
+    catch (error) {
+        if (error instanceof HostBusy)
+            throw new CliError(1, error.message);
+        if (error instanceof ChatConfigInvalid)
+            throw new CliError(1, ...error.message.split('\n'));
+        createScopedLogger('cli').error('chat host failed to start', error); // logging is installed by now: the stack goes to the log file
+        throw new CliError(1, `the chat host failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.stdout.write(`Chat host running (pid ${process.pid}).\n`);
+}

package/dist/terminal/cli/commands/chat.js

@@ -0,0 +1,321 @@
+import { createInterface } from 'node:readline';
+import { join, resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { chatConfigPathOf, chatLogsOf, chatSocketOf } from '../../../chat/config.js';
+import { CliError } from '../cli-error.js';
+import { connectControl, ControlUnreachable } from '../control-client.js';
+import { startDetached } from '../detached.js';
+import { socketGone } from './control.js';
+/** A client on the chat host's socket; null when no host answers. */
+async function connectHost(path) {
+    try {
+        return await connectControl(path);
+    }
+    catch (error) {
+        if (error instanceof ControlUnreachable === false)
+            throw error;
+        if (error.reason === 'not-running')
+            return null;
+        if (error.reason === 'incompatible')
+            throw new CliError(2, 'The running chat host speaks a protocol this command does not (it expects 1). Update one of them.');
+        throw new CliError(1, `The chat host does not answer on ${path}`);
+    }
+}
+export const POLL_MS = 200;
+/** The chat host's client, started on demand. */
+async function hostClient(socketPath, start) {
+    const client = await connectHost(socketPath);
+    if (client !== null)
+        return client;
+    await start({ label: 'The chat host', args: ['chat-host'], socketPath, logPath: join(chatLogsOf(), 'start.log') });
+    const started = await connectHost(socketPath);
+    if (started === null)
+        throw new CliError(1, 'The chat host stopped answering right after it started');
+    return started;
+}
+const HISTORY_EVENTS = 20;
+/** How long ago, in the largest whole unit. */
+const ageOf = (ms) => {
+    const minutes = Math.floor(Math.max(ms, 0) / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    if (minutes < 24 * 60)
+        return `${Math.floor(minutes / 60)}h ago`;
+    return `${Math.floor(minutes / (24 * 60))}d ago`;
+};
+const describeOption = (o) => `${o.label} (${o.id}): ${o.current}\n    offers: ${o.values.map((v) => v.id).join(', ')}\n`;
+/**
+ * Opens a conversation, or resumes a session, and runs it in plain lines: one line in, the answer out as it streams. `/quit` leaves and the
+ * session stays open. Ctrl+C (`sigint`) while a turn runs interrupts it and returns to the prompt; at the prompt it leaves.
+ */
+async function converse(client, { start, input, pollMs, sigint }) {
+    const write = (text) => void process.stdout.write(text);
+    let opened;
+    try {
+        opened = (await client.request(start.cmd, start.cmd === 'open' ? { agent: start.agent, folder: start.folder } : { sessionId: start.sessionId }));
+    }
+    catch (error) {
+        throw new CliError(1, error instanceof Error ? error.message : String(error));
+    }
+    const sessionId = opened.session.id;
+    write(`Chat ${sessionId} with ${opened.session.agent} in ${opened.session.folder}. /options, /option <id> <value>, /quit leaves it open.\n`);
+    let cursor = 0;
+    let printed = 0; // characters of the message being written that are already on screen
+    let finished = false; // a turn_end has been shown
+    const show = (reply) => {
+        for (const event of reply.events) {
+            if (event.kind === 'assistant')
+                write(`${String(event.text).slice(printed)}\n`), (printed = 0);
+            else if (event.kind === 'tool_start')
+                write(`  [${event.tool}${event.arg ? ` ${event.arg}` : ''}]\n`);
+            else if (event.kind === 'error')
+                write(`error: ${event.text}\n`);
+            else if (event.kind === 'turn_end') {
+                finished = true;
+                printed = 0;
+                if (event.outcome === 'interrupted')
+                    write('\n[interrupted]\n');
+            }
+        }
+        if (reply.streaming.length > printed)
+            write(reply.streaming.slice(printed)), (printed = reply.streaming.length);
+        cursor = reply.cursor;
+    };
+    const poll = async () => (await client.request('events', { sessionId, after: cursor, limit: 200 }));
+    let waitingOn = false; // a resumed session that was waiting for an approval when the person left
+    if (start.cmd === 'resume') {
+        // the socket pages forward by cursor only, so the end of the transcript is found by reading to its end
+        let tail = [];
+        for (let page = await poll();; page = await poll()) {
+            tail = [...tail, ...page.events].slice(-HISTORY_EVENTS);
+            cursor = page.cursor;
+            waitingOn = page.approvals.length > 0;
+            if (page.events.length < 200)
+                break;
+        }
+        for (const event of tail) {
+            if (event.kind === 'user')
+                write(`> ${event.text}\n`);
+            else if (event.kind === 'assistant')
+                write(`${event.text}\n`);
+            else if (event.kind === 'tool_start')
+                write(`  [${event.tool}${event.arg ? ` ${event.arg}` : ''}]\n`);
+            else if (event.kind === 'error')
+                write(`error: ${event.text}\n`);
+        }
+    }
+    const reader = createInterface({ input });
+    const lines = reader[Symbol.asyncIterator]();
+    // A line asked for and not used (the approval it was for was answered elsewhere) stays asked for, so the next read gets it.
+    let waiting;
+    const nextLine = () => (waiting ??= lines.next());
+    const used = () => void (waiting = undefined);
+    let turning = false;
+    let left = false;
+    const onSigint = () => {
+        if (turning === false)
+            return reader.close(); // at the prompt: leave, as /quit does
+        client.request('interrupt', { sessionId }).catch((error) => write(`${error instanceof Error ? error.message : String(error)}\n`));
+    };
+    sigint.on('SIGINT', onSigint);
+    /** Shows an approval with the provider's choices and sends the one the person picks; gives up when it is no longer pending (an interrupt, another client). */
+    const decide = async (approval) => {
+        write(`${approval.tool}${approval.arg ? ` ${approval.arg}` : ''} needs your approval:\n${approval.choices.map((choice, i) => `  ${i + 1}) ${choice.label}\n`).join('')}`);
+        const watch = { on: true, still: () => watch.on };
+        const gone = (async () => {
+            while (watch.on) {
+                await sleep(pollMs);
+                const reply = await poll();
+                if (watch.still() === false)
+                    return;
+                show(reply);
+                if (reply.approvals.some((a) => a.approvalId === approval.approvalId) === false)
+                    return;
+            }
+        })();
+        try {
+            for (;;) {
+                write('choose> ');
+                const got = await Promise.race([nextLine(), gone]);
+                if (got === undefined)
+                    return write('\n');
+                used();
+                if (got.done)
+                    return void (left = true); // the person left: the approval stays pending
+                const text = String(got.value).trim();
+                const choice = approval.choices[Number(text) - 1] ?? approval.choices.find((c) => c.id === text);
+                if (choice === undefined) {
+                    write(`Type a number from 1 to ${approval.choices.length}\n`);
+                    continue;
+                }
+                watch.on = false;
+                try {
+                    await client.request('answer', { sessionId, approvalId: approval.approvalId, choiceId: choice.id });
+                }
+                catch (error) {
+                    write(`${error instanceof Error ? error.message : String(error)}\n`);
+                }
+                return;
+            }
+        }
+        finally {
+            watch.on = false;
+        }
+    };
+    const asked = new Set();
+    /** Follows the turn that runs until it ends, asking each approval it raises. */
+    const follow = async () => {
+        finished = false;
+        while (finished === false && left === false) {
+            const reply = await poll();
+            show(reply);
+            for (const approval of reply.approvals) {
+                if (finished || left)
+                    break;
+                if (asked.has(approval.approvalId))
+                    continue;
+                asked.add(approval.approvalId);
+                await decide(approval);
+            }
+            if (finished === false && left === false)
+                await sleep(pollMs);
+        }
+    };
+    try {
+        if (waitingOn) {
+            turning = true;
+            try {
+                await follow();
+            }
+            catch (error) {
+                write(`${error instanceof Error ? error.message : String(error)}\n`);
+            }
+            finally {
+                turning = false;
+            }
+        }
+        while (left === false) {
+            write('> ');
+            const { value, done } = await nextLine();
+            used();
+            const text = done ? '/quit' : String(value).trim();
+            if (text === '/quit')
+                break;
+            if (text === '')
+                continue;
+            if (text === '/options' || text.startsWith('/option ')) {
+                try {
+                    if (text === '/options') {
+                        // after the cursor, so what is waiting to be shown is not consumed
+                        const { options } = (await client.request('events', { sessionId, after: cursor, limit: 1 }));
+                        write(options.map(describeOption).join('') || 'This agent lists no options.\n');
+                    }
+                    else {
+                        const [id, value, ...extra] = text.split(/\s+/).slice(1);
+                        if (id === undefined || value === undefined || extra.length > 0) {
+                            write('Usage: /option <id> <value>\n');
+                            continue;
+                        }
+                        const { options } = (await client.request('setOption', { sessionId, option: id, value }));
+                        write(describeOption(options.find((o) => o.id === id)));
+                    }
+                }
+                catch (error) {
+                    write(`${error instanceof Error ? error.message : String(error)}\n`);
+                }
+                continue;
+            }
+            turning = true;
+            try {
+                await client.request('send', { sessionId, text });
+                await follow();
+            }
+            catch (error) {
+                write(`${error instanceof Error ? error.message : String(error)}\n`);
+            }
+            finally {
+                turning = false;
+            }
+        }
+    }
+    finally {
+        sigint.off('SIGINT', onSigint);
+    }
+    write('\n');
+}
+/**
+ * `carrier chat --workspace <folder> [--agent <name>]`, `--resume <id>`, `--list [--archived]`, `--archive|--unarchive|--delete <id>` and `--stop`. A host is started on demand by --list and
+ * by a chat (`start` is replaceable in tests). The host is the one in the Carrier folder (`CARRIER_HOME`, else `~/.carrier`). Returns the exit code.
+ */
+export async function chatCommand(flags, { start = startDetached, input = process.stdin, pollMs = POLL_MS, now = Date.now, sigint = process } = {}) {
+    const socketPath = chatSocketOf();
+    if (flags.stop) {
+        const client = await connectHost(socketPath);
+        if (client === null) {
+            process.stdout.write('No chat host is running\n');
+            return 0;
+        }
+        await client.request('stop');
+        client.close();
+        if ((await socketGone(socketPath)) === false)
+            throw new CliError(1, `The chat host still answers on ${socketPath} after 15 seconds`);
+        process.stdout.write('Chat host stopped\n');
+        return 0;
+    }
+    if (flags.list) {
+        const client = await hostClient(socketPath, start);
+        const { sessions } = (await client.request('list', flags.archived ? { archived: true } : {}));
+        client.close();
+        if (sessions.length === 0)
+            process.stdout.write(flags.archived ? 'No archived chat sessions.\n' : 'No chat sessions.\n');
+        // a session whose agent is not running is closed, whatever state it was left in
+        for (const s of sessions)
+            process.stdout.write(`${s.id}  ${s.agent}  ${s.live ? s.state : 'closed'}  ${ageOf(now() - s.lastActiveAt)}  ${s.folder}\n`);
+        return 0;
+    }
+    const change = flags.archive !== undefined ? [flags.archive, 'archive', { archived: true }, 'archived']
+        : flags.unarchive !== undefined ? [flags.unarchive, 'archive', { archived: false }, 'unarchived']
+            : flags.delete !== undefined ? [flags.delete, 'delete', {}, 'deleted']
+                : undefined;
+    if (change !== undefined) {
+        const [sessionId, cmd, extra, done] = change;
+        const client = await hostClient(socketPath, start);
+        try {
+            await client.request(cmd, { sessionId, ...extra });
+        }
+        catch (error) {
+            throw new CliError(1, error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            client.close();
+        }
+        process.stdout.write(`Session ${sessionId} ${done}\n`);
+        return 0;
+    }
+    if (flags.resume !== undefined) {
+        const client = await hostClient(socketPath, start);
+        try {
+            await converse(client, { start: { cmd: 'resume', sessionId: flags.resume }, input, pollMs, sigint });
+        }
+        finally {
+            client.close();
+        }
+        return 0;
+    }
+    if (flags.workspace !== undefined) {
+        const client = await hostClient(socketPath, start);
+        try {
+            const agent = flags.agent ?? (await client.request('agents'))[0]?.name;
+            if (agent === undefined)
+                throw new CliError(1, `chat.json lists no agents, so there is none to chat with; add one to the "agents" of ${chatConfigPathOf()}`);
+            await converse(client, { start: { cmd: 'open', agent, folder: resolve(flags.workspace) }, input, pollMs, sigint });
+        }
+        finally {
+            client.close();
+        }
+        return 0;
+    }
+    throw new CliError(2, 'Usage: carrier chat --workspace <folder> [--agent <name>] | --resume <id> | --list [--archived] | --archive|--unarchive|--delete <id> | --stop');
+}