@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/chat/projects.js

@@ -0,0 +1,242 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { carrierHome } from '../config/default-path.js';
+import { listAvailableRepos } from '../integrations/available-repos.js';
+import { repoNamePattern } from '../config/schema.js';
+import { readChatConfig } from './config.js';
+import { checkProjectsFolder } from './folder.js';
+import { ChatRefused } from './runner.js';
+import { parseOrigin } from './workspace.js';
+const log = createScopedLogger('chat');
+/** A project's name: one plain folder name (no empty, `.`, `..`, leading dot or slash), at most a hundred characters. */
+export const projectNamePattern = /^\w[\w.-]{0,99}$/;
+/** Per git command, the engine's limit. */
+export const GIT_TIMEOUT_MS = 10 * 60_000;
+/** The token of the person's active `gh` login. Throws a `ChatRefused` saying what to do when `gh` is missing or signed out. */
+export const ghToken = () => new Promise((resolve, reject) => {
+    execFile('gh', ['auth', 'token'], { encoding: 'utf8', timeout: 15_000 }, (error, stdout) => {
+        if (error?.code === 'ENOENT')
+            return reject(new ChatRefused('The GitHub CLI (gh) is not installed'));
+        const token = stdout.trim();
+        if (error !== null || token === '')
+            return reject(new ChatRefused('gh is not signed in to GitHub; run "gh auth login"'));
+        resolve(token);
+    });
+});
+/** What a failed `gh` call comes to, in a sentence for the person: gh missing, signed out, offline or too slow. What gh printed is logged by code only, never forwarded. */
+export function ghRefusal(error, did) {
+    const { code, killed, stderr } = error;
+    const said = typeof stderr === 'string' ? stderr : '';
+    log.error(`gh ${did} failed`, { code: typeof code === 'number' || typeof code === 'string' ? code : null, killed: killed === true });
+    if (code === 'ENOENT')
+        return new ChatRefused('The GitHub CLI (gh) is not installed');
+    if (killed === true)
+        return new ChatRefused('GitHub took too long to answer');
+    if (/gh auth login|not logged in|http 401|bad credentials/i.test(said))
+        return new ChatRefused('gh is not signed in to GitHub; run "gh auth login"');
+    if (/error connecting|could not resolve|no such host|dial tcp|network is unreachable|timed out/i.test(said))
+        return new ChatRefused('GitHub could not be reached; check the network connection');
+    return new ChatRefused(`GitHub did not answer; check "gh auth status"`);
+}
+/** One page of every repository the person's `gh` login can read, thirty at a time, newest push first. */
+export const ghRepos = (page, timeoutMs) => listAvailableRepos(page, timeoutMs, 'read').catch((error) => {
+    throw ghRefusal(error, 'repos');
+});
+/** The login that is active in `gh`. */
+export const ghLogin = (timeoutMs) => promisify(execFile)('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf8', timeout: timeoutMs }).then(({ stdout }) => stdout.trim(), (error) => {
+    throw ghRefusal(error, 'login');
+});
+const BRANCHES_PER_PAGE = 100;
+/** The default branch and the first hundred branches of a repository (`owner/name`, already checked against `repoNamePattern`) the person's `gh` login can read. */
+export async function ghBranches(repo, timeoutMs) {
+    const gh = (args) => promisify(execFile)('gh', ['api', ...args], { encoding: 'utf8', timeout: timeoutMs });
+    try {
+        const [head, listed] = await Promise.all([gh([`repos/${repo}`, '--jq', '.default_branch']), gh([`repos/${repo}/branches?per_page=${BRANCHES_PER_PAGE}`, '--jq', '.[].name'])]);
+        const branches = listed.stdout.split('\n').filter((name) => name !== '');
+        return { default: head.stdout.trim(), branches, hasMore: branches.length === BRANCHES_PER_PAGE };
+    }
+    catch (error) {
+        throw ghRefusal(error, 'branches');
+    }
+}
+// What git's stderr says, read here and never forwarded: it can hold a URL.
+const notVisible = /repository not found|not found|authentication failed|could not read username|error: 40[134]/i;
+const offline = /could not resolve host|failed to connect|connection (timed out|refused|reset)|network is unreachable|unable to access/i;
+function refusal(result, did, repo) {
+    log.error(`git ${did} failed`, { repo, code: result.code, timedOut: result.timedOut === true });
+    if (result.timedOut === true)
+        return new ChatRefused(`The ${did} took more than ten minutes and was stopped`);
+    if (notVisible.test(result.stderr))
+        return new ChatRefused(`${repo} was not found, or your GitHub login cannot see it`);
+    if (offline.test(result.stderr))
+        return new ChatRefused('GitHub could not be reached; check the network connection');
+    return new ChatRefused(`git could not ${did} ${repo}`);
+}
+/** The projects folder of `chat.json`, read at each call. `inside` is a path below it that is checked again: a projects folder that is the Carrier folder itself would put `engine/x` in the engine's own folder. */
+const projectsFolder = (inside) => {
+    const loaded = readChatConfig();
+    if (loaded.ok === false)
+        throw new ChatRefused(`chat.json is not valid: ${loaded.errors[0].path}: ${loaded.errors[0].message}`);
+    const folder = checkProjectsFolder(loaded.settings.projectsFolder, carrierHome());
+    return inside === undefined ? folder : checkProjectsFolder(join(folder, inside), carrierHome());
+};
+/** Where a new project of this name is made: `<projects folder>/local/<name>`. */
+export function projectFolder(name) {
+    if (projectNamePattern.test(name) === false)
+        throw new ChatRefused(`"${name}" is not a plain folder name`);
+    return join(projectsFolder(), 'local', name);
+}
+/** Makes the project's folder and runs `git init -b main` in it. A name that is taken is refused and nothing is changed; a `git init` that fails removes what this call made. */
+export async function createProject(git, name) {
+    const dest = projectFolder(name);
+    await mkdir(dirname(dest), { recursive: true });
+    try {
+        await mkdir(dest); // not recursive: it fails when anything is there, and what is there is not ours to touch
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new ChatRefused(`${name} is already a project; choose another name`);
+        throw error;
+    }
+    const init = await git.run(dest, ['init', '-b', 'main']);
+    if (init.ok === false) {
+        log.error('git init failed', { name, code: init.code });
+        await rm(dest, { recursive: true, force: true });
+        throw new ChatRefused(`git could not start the project ${name}`);
+    }
+    return { folder: dest };
+}
+// The only stderr lines of git that leave this file: its progress, as "Receiving objects: 45%". Anything else can hold a URL.
+const progressLine = /^(?:remote: )?((?:Counting|Compressing|Receiving|Resolving|Updating) [A-Za-z ]+: +\d+)%/;
+/**
+ * Brings GitHub repositories into the projects folder with the person's own `gh` login (ADR 0015). The folder is read
+ * from `chat.json` at each request, so a change applies to the next one.
+ */
+export function createProjects({ git, token, github, clock }) {
+    const running = new Map();
+    // Not in argv, in a file or in a log: git reads the header from its environment, as `git-workspaces.ts` does.
+    const authEnv = async () => {
+        const basic = Buffer.from(`x-access-token:${await token()}`).toString('base64');
+        return { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'http.extraHeader', GIT_CONFIG_VALUE_0: `Authorization: Basic ${basic}` };
+    };
+    async function fetchOrClone(repo, dest, signal, onProgress) {
+        if (existsSync(dest)) {
+            const origin = existsSync(join(dest, '.git')) ? await git.run(dest, ['config', '--get', 'remote.origin.url']) : undefined;
+            const found = origin?.ok === true ? parseOrigin(origin.out) : null;
+            if (found === null || `${found.owner}/${found.name}`.toLowerCase() !== repo.toLowerCase())
+                throw new ChatRefused(`${dest} is already there and is not a clone of ${repo}; it was left as it is`);
+            const fetched = await git.run(dest, ['fetch', 'origin', '--prune'], { timeoutMs: GIT_TIMEOUT_MS, env: await authEnv(), signal });
+            if (fetched.ok === false)
+                throw refusal(fetched, 'fetch', repo);
+            return { folder: dest, repo, fetched: true };
+        }
+        const env = await authEnv();
+        await mkdir(dirname(dest), { recursive: true });
+        try {
+            await mkdir(dest); // not recursive: it fails if something appeared since the check, and what is there now is ours to remove only if we made it
+        }
+        catch {
+            throw new ChatRefused(`${dest} is already there and is not a clone of ${repo}; it was left as it is`);
+        }
+        try {
+            const cloned = await git.run(dirname(dest), ['clone', '--', `https://github.com/${repo}.git`, dest], { timeoutMs: GIT_TIMEOUT_MS, env, signal, onProgress });
+            if (cloned.ok === false)
+                throw refusal(cloned, 'clone', repo);
+        }
+        catch (error) {
+            await rm(dest, { recursive: true, force: true });
+            throw error;
+        }
+        return { folder: dest, repo, fetched: false };
+    }
+    /** `<projects folder>/<owner>/<name>`, where `repo` is or would be cloned. */
+    const repoFolder = (repo) => {
+        if (repoNamePattern.test(repo) === false)
+            throw new ChatRefused(`"${repo}" is not a repository; write it as owner/name`);
+        return projectsFolder(repo);
+    };
+    return {
+        repoFolder,
+        /** What bringing `repo` is: `fetch` when it is already in the projects folder, `clone` when it is not, or what the one in progress is doing (a clone being made is not yet a repository to fetch). */
+        stepOf(repo) {
+            const dest = repoFolder(repo);
+            return running.get(dest.toLowerCase())?.mode ?? (existsSync(dest) ? 'fetch' : 'clone');
+        },
+        /** The default branch and the branches of a repository that need not be on disk, read from GitHub with the person's login. */
+        repoBranches({ repo }) {
+            if (repoNamePattern.test(repo) === false)
+                throw new ChatRefused(`"${repo}" is not a repository; write it as owner/name`);
+            return github.branches(repo);
+        },
+        /** A page of the repositories the person's login can read; page 1 also says the login. */
+        async githubRepos({ page }) {
+            if (page > 1)
+                return github.repos(page);
+            const [first, who] = await Promise.all([github.repos(page), github.login()]);
+            return { ...first, login: who };
+        },
+        /** Makes `<projects folder>/local/<name>` and runs `git init -b main` in it (the `createProject` request, for apps older than the plan). */
+        createProject: ({ name }) => createProject(git, name),
+        /**
+         * Clones `repo` to `<projects folder>/<owner>/<name>`, or fetches it when it is already there. `signal` is the waiter's: when it aborts, this waiter
+         * leaves, and git is aborted and a destination this request made is removed once nobody waits for it. `onProgress` gets git's progress lines of a
+         * clone ("Receiving objects: 45%"), at most one a second and no other line of git's.
+         */
+        async cloneRepo({ repo }, signal, onProgress) {
+            const dest = repoFolder(repo);
+            const key = dest.toLowerCase();
+            // a clone being aborted finishes first, so a new one never meets its leftovers
+            for (let old = running.get(key); old?.abort.signal.aborted === true; old = running.get(key))
+                await old.done.catch(() => { });
+            let job = running.get(key);
+            if (job === undefined) {
+                const abort = new AbortController();
+                const listeners = new Set();
+                let last = -Infinity;
+                const report = (raw) => {
+                    const found = progressLine.exec(raw.trim());
+                    if (found === null || clock.now() - last < 1000)
+                        return;
+                    last = clock.now();
+                    const line = `${found[1].replace(/ +/g, ' ')}%`;
+                    started.latest = line;
+                    for (const listener of listeners)
+                        listener(line);
+                };
+                const started = { done: fetchOrClone(repo, dest, abort.signal, report), mode: existsSync(dest) ? 'fetch' : 'clone', waiters: 0, abort, listeners };
+                const forget = () => void (running.get(key) === started && running.delete(key));
+                started.done.then(forget, forget);
+                running.set(key, (job = started));
+            }
+            const joined = job;
+            joined.waiters++;
+            if (onProgress !== undefined) {
+                joined.listeners.add(onProgress);
+                if (joined.latest !== undefined)
+                    onProgress(joined.latest);
+            }
+            return new Promise((resolve, reject) => {
+                // the clone stops when nobody waits for it any more, and the last one to leave hears of it once the half clone is removed
+                const leave = async () => {
+                    if (onProgress !== undefined)
+                        joined.listeners.delete(onProgress);
+                    if (--joined.waiters === 0) {
+                        joined.abort.abort();
+                        await joined.done.catch(() => { });
+                    }
+                    reject(new ChatRefused('The clone was cancelled'));
+                };
+                if (signal.aborted)
+                    return leave();
+                signal.addEventListener('abort', leave, { once: true });
+                const settled = () => (signal.removeEventListener('abort', leave), onProgress !== undefined && joined.listeners.delete(onProgress));
+                // a waiter that has left is answered by `leave`
+                joined.done.then((reply) => (settled(), signal.aborted || resolve(reply)), (error) => (settled(), signal.aborted || reject(error)));
+            });
+        },
+    };
+}

package/dist/chat/runner.js

@@ -0,0 +1,6 @@
+// The chat runner: the port through which the host drives one provider (docs/specs/chat-host.md, Decisions). It speaks
+// Carrier's own chat events whatever the provider speaks, and it is not the engine's `AgentRunner`: nothing in it is
+// epic-shaped, there is no result file and the process is not done after one answer.
+/** A failure whose message is for the person, in words: it travels to the client as it is. Any other error is logged and reaches the client as "internal error". */
+export class ChatRefused extends Error {
+}

package/dist/chat/schema.js

@@ -0,0 +1,48 @@
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+export const sessionStates = ['working', 'waiting_approval', 'idle', 'preparing'];
+/** A user session: one conversation with a provider's agent in a folder. */
+export const sessions = sqliteTable('sessions', {
+    id: text().primaryKey(),
+    agent: text().notNull(), // the configured agent's name
+    harness: text({ enum: ['claude', 'codex'] }).notNull(),
+    folder: text().notNull(), // where the agent runs: the base folder, or the worktree when there is one
+    workspaceKind: text({ enum: ['folder', 'worktree'] }).notNull().default('folder'),
+    worktreeBranch: text(), // the four below are set for a worktree session only
+    worktreeFrom: text(), // the branch it was cut from, as `workspace` listed it
+    worktreeBase: text(), // the folder it was made from
+    worktreePath: text(),
+    title: text(),
+    options: text({ mode: 'json' }).$type(),
+    plan: text({ mode: 'json' }).$type(), // what the host is preparing, or failed to, with the first message; null once the agent answered it
+    nativeId: text(), // the provider's id for the conversation, to resume it
+    state: text({ enum: sessionStates }).notNull().default('idle'),
+    pid: integer(), // of the live agent process, null when closed
+    pgid: integer(),
+    command: text(), // what that process was started with, so a sweep knows it is still the agent
+    createdAt: integer().notNull(), // ms since epoch
+    lastActiveAt: integer().notNull(),
+    archived: integer({ mode: 'boolean' }).notNull().default(false),
+    keptAt: integer(), // ms since epoch: when the clock's delete spared this archived session for unsaved work; null otherwise
+});
+/**
+ * What was said and done in a session, already redacted and bounded (`transcript.ts`). The id is the cursor of the `events`
+ * request. A `delta` is never stored. `data` holds the event's fields other than its kind.
+ */
+export const chatEvents = sqliteTable('chat_events', {
+    id: integer().primaryKey({ autoIncrement: true }),
+    sessionId: text().notNull().references(() => sessions.id),
+    at: integer().notNull(), // ms since epoch
+    kind: text().notNull(),
+    data: text({ mode: 'json' }).$type().notNull(),
+}, (table) => [index('chat_events_session').on(table.sessionId, table.id)]);
+/** One row per finished turn, so statistics can be built later without touching the transcripts. */
+export const chatTurns = sqliteTable('chat_turns', {
+    id: integer().primaryKey({ autoIncrement: true }),
+    sessionId: text().notNull().references(() => sessions.id),
+    startedAt: integer().notNull(),
+    model: text(),
+    outcome: text({ enum: ['ok', 'interrupted', 'error'] }).notNull(),
+    durationMs: integer().notNull(),
+    toolCalls: integer().notNull(),
+    usage: text({ mode: 'json' }).$type(), // as the provider gave it
+}, (table) => [index('chat_turns_session').on(table.sessionId)]);

package/dist/chat/server.js

@@ -0,0 +1,202 @@
+import { rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { z } from 'zod';
+import { repoNamePattern } from '../config/schema.js';
+import { socketPathFits, version } from '../control/server.js';
+import { plan } from './plan.js';
+import { projectNamePattern } from './projects.js';
+import { ChatRefused } from './runner.js';
+const log = createScopedLogger('chat');
+// 1 MiB, not the engine's 16 KiB: a pasted spec is a request.
+const MAX_LINE_BYTES = 1024 * 1024;
+const capabilities = ['agents', 'list', 'open', 'resume', 'send', 'answer', 'interrupt', 'setOption', 'agentOptions', 'events', 'close', 'archive', 'delete', 'workspace', 'fetch', 'suggestName', 'checkName', 'deletePreview', 'cloneRepo', 'createProject', 'githubRepos', 'repoBranches', 'health', 'plan', 'stop'];
+const id = z.number().int().positive();
+const sessionId = z.uuid();
+// An allowlist, strict like the engine's: any other command, field or type is rejected before anything acts on it.
+export const chatRequest = z.union([
+    z.strictObject({ id, cmd: z.literal('agents') }),
+    z.strictObject({ id, cmd: z.literal('list'), archived: z.boolean().optional() }),
+    z.strictObject({ id, cmd: z.literal('open'), agent: z.string().min(1), folder: z.string().min(1), options: z.record(z.string(), z.string()).optional(), worktree: z.strictObject({ from: z.string().min(1).max(1000), name: z.string().max(1000).optional() }).optional() }),
+    z.strictObject({ id, cmd: z.literal('open'), plan }),
+    z.strictObject({ id, cmd: z.literal('retryPreparation'), sessionId }),
+    z.strictObject({ id, cmd: z.literal('cancelPreparation'), sessionId }),
+    z.strictObject({ id, cmd: z.literal('resume'), sessionId }),
+    // a message has text, unless it invokes a command, which may take nothing after its name
+    z.strictObject({ id, cmd: z.literal('send'), sessionId, text: z.string(), command: z.string().min(1).max(1000).optional() }).refine((r) => r.text.length > 0 || r.command !== undefined),
+    z.strictObject({ id, cmd: z.literal('answer'), sessionId, approvalId: z.string().min(1), choiceId: z.string().min(1) }),
+    z.strictObject({ id, cmd: z.literal('interrupt'), sessionId }),
+    z.strictObject({ id, cmd: z.literal('agentOptions'), agent: z.string().min(1) }),
+    z.strictObject({ id, cmd: z.literal('setOption'), sessionId, option: z.string().min(1), value: z.string().min(1) }),
+    z.strictObject({ id, cmd: z.literal('events'), sessionId, after: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(200) }),
+    z.strictObject({ id, cmd: z.literal('close'), sessionId }),
+    z.strictObject({ id, cmd: z.literal('archive'), sessionId, archived: z.boolean() }),
+    z.strictObject({ id, cmd: z.literal('delete'), sessionId }),
+    z.strictObject({ id, cmd: z.literal('workspace'), folder: z.string().min(1) }),
+    z.strictObject({ id, cmd: z.literal('fetch'), folder: z.string().min(1) }),
+    z.strictObject({ id, cmd: z.literal('suggestName'), folder: z.string().min(1) }),
+    z.strictObject({ id, cmd: z.literal('checkName'), folder: z.string().min(1), name: z.string().max(1000) }),
+    z.strictObject({ id, cmd: z.literal('deletePreview'), sessionIds: z.array(sessionId).min(1).max(500) }),
+    z.strictObject({ id, cmd: z.literal('cloneRepo'), repo: z.string().regex(repoNamePattern) }),
+    z.strictObject({ id, cmd: z.literal('createProject'), name: z.string().regex(projectNamePattern) }),
+    z.strictObject({ id, cmd: z.literal('githubRepos'), page: z.int().min(1).max(100) }),
+    z.strictObject({ id, cmd: z.literal('repoBranches'), repo: z.string().regex(repoNamePattern) }),
+    z.strictObject({ id, cmd: z.literal('health'), refresh: z.boolean().optional() }),
+    z.strictObject({ id, cmd: z.literal('stop') }),
+]);
+async function run(request, controls, gone) {
+    switch (request.cmd) {
+        case 'agents':
+            return controls.agents();
+        case 'list':
+            return controls.list({ archived: request.archived });
+        case 'open':
+            return 'plan' in request ? controls.openPlan({ plan: request.plan }) : controls.open({ agent: request.agent, folder: request.folder, options: request.options, worktree: request.worktree });
+        case 'retryPreparation':
+            return controls.retryPreparation({ sessionId: request.sessionId });
+        case 'cancelPreparation':
+            return controls.cancelPreparation({ sessionId: request.sessionId });
+        case 'resume':
+            return controls.resume({ sessionId: request.sessionId });
+        case 'send':
+            return controls.send({ sessionId: request.sessionId, text: request.text, command: request.command });
+        case 'answer':
+            return controls.answer({ sessionId: request.sessionId, approvalId: request.approvalId, choiceId: request.choiceId });
+        case 'interrupt':
+            return controls.interrupt({ sessionId: request.sessionId });
+        case 'agentOptions':
+            return controls.agentOptions({ agent: request.agent });
+        case 'setOption':
+            return controls.setOption({ sessionId: request.sessionId, option: request.option, value: request.value });
+        case 'events':
+            return controls.events({ sessionId: request.sessionId, after: request.after, limit: request.limit });
+        case 'close':
+            return controls.close({ sessionId: request.sessionId });
+        case 'archive':
+            return controls.archive({ sessionId: request.sessionId, archived: request.archived });
+        case 'delete':
+            return controls.delete({ sessionId: request.sessionId });
+        case 'workspace':
+            return controls.workspace({ folder: request.folder });
+        case 'fetch':
+            return controls.fetch({ folder: request.folder });
+        case 'suggestName':
+            return controls.suggestName({ folder: request.folder });
+        case 'checkName':
+            return controls.checkName({ folder: request.folder, name: request.name });
+        case 'deletePreview':
+            return controls.deletePreview({ sessionIds: request.sessionIds });
+        case 'cloneRepo':
+            return controls.cloneRepo({ repo: request.repo }, gone);
+        case 'createProject':
+            return controls.createProject({ name: request.name });
+        case 'githubRepos':
+            return controls.githubRepos({ page: request.page });
+        case 'repoBranches':
+            return controls.repoBranches({ repo: request.repo });
+        case 'health':
+            return controls.health({ refresh: request.refresh });
+    }
+}
+async function answer(line, controls, gone, stopAfterReply) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return { id: null, ok: false, error: 'invalid JSON' };
+    }
+    const parsed = chatRequest.safeParse(value);
+    if (parsed.success === false) {
+        // the id is echoed only when it is a valid one, so the client can match the error
+        const given = typeof value === 'object' && value !== null ? id.safeParse(value.id) : null;
+        return { id: given?.success ? given.data : null, ok: false, error: 'invalid request' };
+    }
+    if (parsed.data.cmd === 'stop') {
+        stopAfterReply();
+        return { id: parsed.data.id, ok: true };
+    }
+    try {
+        return { id: parsed.data.id, ok: true, data: await run(parsed.data, controls, gone) };
+    }
+    catch (error) {
+        if (error instanceof ChatRefused)
+            return { id: parsed.data.id, ok: false, error: error.message };
+        log.error(`${parsed.data.cmd} failed`, error);
+        return { id: parsed.data.id, ok: false, error: 'internal error' };
+    }
+}
+/**
+ * Opens `chat.sock` in `stateDir`: newline-delimited JSON, a hello on connect and one reply per request, like the engine's.
+ * The caller holds the chat lock, so a socket file already there is a leftover of a crash. Unlike the engine, a socket
+ * that cannot open rejects: a host without it is of no use. `clients` is told when a client connects or leaves.
+ * `close()` is synchronous and removes the file.
+ */
+export async function startChatServer({ stateDir, startedAt, controls, stop, clients }) {
+    const path = join(stateDir, 'chat.sock');
+    const { fits, bytes } = socketPathFits(path);
+    if (fits === false)
+        throw new Error(`${path} is ${bytes} bytes, too long for a socket; use a shorter CARRIER_HOME`);
+    const sockets = new Set();
+    const hello = { event: 'hello', protocol: 1, pid: process.pid, startedAt, version, capabilities };
+    const send = (socket, message, written) => void socket.write(`${JSON.stringify(message)}\n`, written);
+    const server = createServer((socket) => {
+        sockets.add(socket);
+        clients.joined();
+        const gone = new AbortController();
+        socket.setEncoding('utf8');
+        // a client that goes away mid-write is routine, not a failure
+        socket.on('error', (error) => log.debug('chat connection error', error));
+        socket.on('close', () => {
+            gone.abort();
+            sockets.delete(socket);
+            clients.left();
+        });
+        send(socket, hello);
+        let pending = '';
+        let replies = Promise.resolve(); // one reply per request, in the order asked: a slow `open` does not let a later reply overtake it
+        socket.on('data', (chunk) => {
+            pending += chunk;
+            for (let end = pending.indexOf('\n'); end >= 0; end = pending.indexOf('\n')) {
+                const line = pending.slice(0, end);
+                pending = pending.slice(end + 1);
+                if (Buffer.byteLength(line) > MAX_LINE_BYTES)
+                    return tooLong(socket);
+                // `stop`: the reply is flushed first, then the shutdown runs
+                replies = replies.then(async () => {
+                    let afterReply;
+                    const reply = await answer(line, controls, gone.signal, () => void (afterReply = () => void stop().catch((error) => log.error('stop failed', error))));
+                    send(socket, reply, afterReply);
+                });
+            }
+            if (Buffer.byteLength(pending) > MAX_LINE_BYTES)
+                tooLong(socket);
+        });
+    });
+    const tooLong = (socket) => {
+        socket.removeAllListeners('data'); // nothing more is read from this client
+        socket.end(`${JSON.stringify({ id: null, ok: false, error: 'line too long' })}\n`);
+    };
+    server.on('error', (error) => log.error('chat socket error', error));
+    rmSync(path, { force: true });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        // bind is synchronous: with this umask the file is born 0600, and the umask is back before anything else runs
+        const umask = process.umask(0o177);
+        try {
+            server.listen(path, resolve);
+        }
+        finally {
+            process.umask(umask);
+        }
+    });
+    return {
+        close: () => {
+            server.close();
+            for (const socket of sockets)
+                socket.destroy();
+            rmSync(path, { force: true });
+        },
+    };
+}