@ashulab/carrier 0.0.0-stage → 0.1.0

package/dist/chat/folder.js

@@ -0,0 +1,56 @@
+import { realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, sep } from 'node:path';
+import { ChatRefused } from './runner.js';
+// A session never works in the engine's folder (ADR 0016); the projects folder also stays out of the chat's own state, logs and worktrees.
+const engineFolders = ['engine'];
+const chatOwnFolders = [...engineFolders, join('chat', 'state'), join('chat', 'logs'), join('chat', 'worktrees')];
+const realOrSelf = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+};
+/** The real path of the folder a session may work in, or a `ChatRefused` saying why not. A symlink into an engine folder is refused too. */
+export function checkFolder(folder, home) {
+    if (isAbsolute(folder) === false)
+        throw new ChatRefused('The folder must be an absolute path');
+    let real;
+    try {
+        real = realpathSync(folder);
+    }
+    catch {
+        throw new ChatRefused('That folder does not exist');
+    }
+    if (statSync(real).isDirectory() === false)
+        throw new ChatRefused('That path is not a folder');
+    refuseInside(real, home, engineFolders);
+    return real;
+}
+function refuseInside(real, home, names) {
+    const realHome = realOrSelf(home);
+    for (const name of names) {
+        const refused = join(realHome, name);
+        if (real === refused || real.startsWith(refused + sep))
+            throw new ChatRefused(`That folder is inside Carrier's own ${name} folder; a chat never works there`);
+    }
+}
+// The real path of a path that may not exist yet: its nearest existing ancestor, resolved, plus the rest.
+const realOfNearest = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        const parent = dirname(path);
+        return parent === path ? path : join(realOfNearest(parent), basename(path));
+    }
+};
+/** The projects folder as the host will use it (it may not exist yet), or a `ChatRefused` saying why not. The engine-folder rule of `checkFolder` plus the chat's own state, logs and worktrees, with symlinks resolved. */
+export function checkProjectsFolder(folder, home) {
+    if (isAbsolute(folder) === false)
+        throw new ChatRefused('The projects folder must be an absolute path');
+    const real = realOfNearest(folder);
+    refuseInside(real, home, chatOwnFolders);
+    return folder;
+}

package/dist/chat/git.js

@@ -0,0 +1,27 @@
+import { execFile } from 'node:child_process';
+const TIMEOUT_MS = 20_000;
+const MAX_OUTPUT = 16 * 1024 * 1024;
+/** The host's own environment plus `GIT_TERMINAL_PROMPT=0`, so a command that wants a password fails instead of waiting for one. */
+export const realGit = {
+    run: (folder, args, options) => new Promise((resolve) => {
+        const { onProgress } = options ?? {};
+        const child = execFile('git', onProgress === undefined ? args : [args[0], '--progress', ...args.slice(1)], { cwd: folder, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...options?.env }, signal: options?.signal, timeout: options?.timeoutMs ?? TIMEOUT_MS, maxBuffer: MAX_OUTPUT, encoding: 'utf8' }, (error, stdout, stderr) => {
+            if (error === null)
+                return resolve({ ok: true, out: stdout });
+            const { code, killed } = error;
+            if (killed)
+                return resolve({ ok: false, code: null, timedOut: true, stderr: 'git took too long' });
+            resolve({ ok: false, code: typeof code === 'number' ? code : null, stderr: stderr || error.message });
+        });
+        if (onProgress !== undefined) {
+            // git ends a progress line with a carriage return, so it is not a line until the next one comes
+            let partial = '';
+            child.stderr?.on('data', (chunk) => {
+                const lines = (partial + chunk).split(/[\r\n]+/);
+                partial = lines.pop();
+                for (const line of lines)
+                    onProgress(line);
+            });
+        }
+    }),
+};

package/dist/chat/group.js

@@ -0,0 +1,28 @@
+import { accessSync, constants } from 'node:fs';
+import { resolveBinary } from '../harnesses/common.js';
+/** The binary to run for a chat agent: `command` when it is a path, else `command` or `fallback` looked up on the path. Throws when there is none. */
+export const resolveAgentBinary = (fallback, command, env) => {
+    if (command?.includes('/'))
+        return accessSync(command, constants.X_OK), command;
+    return resolveBinary(command ?? fallback, env.PATH);
+};
+/** SIGTERM to the agent's whole group (the agent process and the servers it started), SIGKILL if it is still there after a few seconds. */
+export async function endGroup(pid) {
+    const send = (signal) => {
+        try {
+            process.kill(-pid, signal);
+            return true;
+        }
+        catch {
+            return false; // the group is gone
+        }
+    };
+    if (!send('SIGTERM'))
+        return;
+    for (let i = 0; i < 30; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        if (!send(0))
+            return;
+    }
+    send('SIGKILL');
+}

package/dist/chat/health.js

@@ -0,0 +1,49 @@
+import { execFile } from 'node:child_process';
+import { cliLoggedIn } from '../doctor/doctor.js';
+import { resolveBinary } from '../harnesses/common.js';
+export const PROBE_LIMIT_MS = 5_000;
+export const HEALTH_KEPT_MS = 30_000;
+const SYSTEM_GIT = '/usr/bin/git';
+export const realProbes = {
+    loggedIn: (harness, timeoutMs) => cliLoggedIn(harness, undefined, timeoutMs),
+    exitCode: (command, args, timeoutMs) => new Promise((resolve, reject) => execFile(command, args, { timeout: timeoutMs }, (error) => {
+        if (error === null)
+            return resolve(0);
+        const { code } = error;
+        // a number is the exit status; anything else is a process that did not start or was killed on time
+        typeof code === 'number' ? resolve(code) : reject(error);
+    })),
+    gitPath: () => resolveBinary('git'),
+};
+/**
+ * `git` is never run when it is the system's `/usr/bin/git`: on a Mac without the Command Line Tools that is a stub that opens the
+ * installer dialog, so `xcode-select -p` asks instead. Any other `git` runs `--version`.
+ */
+export async function gitState({ binaryFound, probes }) {
+    if (binaryFound('git') === false)
+        return 'missing';
+    const path = probes.gitPath();
+    const code = path === SYSTEM_GIT ? await probes.exitCode('xcode-select', ['-p'], PROBE_LIMIT_MS) : await probes.exitCode(path, ['--version'], PROBE_LIMIT_MS);
+    return code === 0 ? 'ready' : 'missing';
+}
+/** The health of what the chat needs, kept for thirty seconds unless a refresh is asked; the probes of one request run in parallel. */
+export function createHealth({ agents, clock, binaryFound, probes }) {
+    // A probe that fails, or does not answer in time, is `unknown`: the race holds even for a probe that ignores its own timeout.
+    const limited = (probe) => new Promise((resolve) => {
+        const cancel = clock.after(PROBE_LIMIT_MS, async () => resolve('unknown'));
+        probe().then(resolve, () => resolve('unknown')).finally(cancel);
+    });
+    const signedIn = async (ok) => ((await ok) ? 'ready' : 'signedOut');
+    const gh = async () => (binaryFound('gh') ? signedIn(probes.exitCode('gh', ['auth', 'status', '--hostname', 'github.com'], PROBE_LIMIT_MS).then((code) => code === 0)) : 'missing');
+    const agent = async ({ command, harness }) => (binaryFound(command ?? harness) ? signedIn(probes.loggedIn(harness, PROBE_LIMIT_MS)) : 'missing');
+    const probe = async () => {
+        const [git, ghState, ...states] = await Promise.all([limited(() => gitState({ binaryFound, probes })), limited(gh), ...agents.map((chosen) => limited(() => agent(chosen)))]);
+        return { git, gh: ghState, agents: agents.map(({ name, harness }, index) => ({ name, harness, state: states[index] })) };
+    };
+    let kept;
+    return ({ refresh = false }) => {
+        if (refresh || kept === undefined || clock.now() - kept.at >= HEALTH_KEPT_MS)
+            kept = { at: clock.now(), health: probe() };
+        return kept.health;
+    };
+}

package/dist/chat/host.js

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { carrierHome } from '../config/default-path.js';
+import { installFileLogging } from '../logging/logger.js';
+import { realClock } from '../orchestration/clock.js';
+import { acquireLock } from '../storage/lock.js';
+import { claudeChatRunner } from './claude.js';
+import { codexChatRunner } from './codex.js';
+import { chatConfigProblem, chatDirOf, chatLogsOf, chatStateOf, readChatConfig } from './config.js';
+import { realGit } from './git.js';
+import { createProjects, ghBranches, ghLogin, ghRepos, ghToken } from './projects.js';
+import { openChatDatabase } from './db.js';
+import { idleExit } from './idle.js';
+import { startChatServer } from './server.js';
+import { realProbes } from './health.js';
+import { binaryFound, createSessions } from './sessions.js';
+import { realProcesses, sweepDeadHost } from './sweep.js';
+const HOUR_MS = 3_600_000;
+export class HostBusy extends Error {
+}
+/** `chat.json` cannot be read or does not match its schema; the message names the file and each key. */
+export class ChatConfigInvalid extends Error {
+}
+const realGithub = ({ githubCallTimeoutSeconds }) => ({
+    repos: (page) => ghRepos(page, githubCallTimeoutSeconds * 1000),
+    login: () => ghLogin(githubCallTimeoutSeconds * 1000),
+    branches: (repo) => ghBranches(repo, githubCallTimeoutSeconds * 1000),
+});
+const realDeps = (settings) => ({ installLogging: installFileLogging, clock: realClock, exit: process.exit, signals: true, runners: { claude: claudeChatRunner(), codex: codexChatRunner() }, env: process.env, git: realGit, token: ghToken, github: realGithub(settings), binaryFound, probes: realProbes, processes: realProcesses });
+/**
+ * Runs the chat host from the Carrier folder alone (`CARRIER_HOME`, else `~/.carrier`): its own lock, database and socket under
+ * `chat/state/` and its log under `chat/logs/`, sharing nothing with the engine. Its settings are `chat/chat.json`'s, read at start (the
+ * projects folder again at each request, the session ages at each `list` and at each hourly pass); a file that is wrong at start throws
+ * ChatConfigInvalid before anything is created. Throws HostBusy when another host holds the lock. Resolves once the socket answers and
+ * the first pass of the session clock is done; the returned `stop()` is the one shutdown (`stop` request, idle exit, signals), and it
+ * waits for a pass in flight.
+ */
+export async function startChatHost(overrides = {}) {
+    const loaded = readChatConfig();
+    if (loaded.ok === false)
+        throw new ChatConfigInvalid(chatConfigProblem(carrierHome(), loaded.errors));
+    const { settings } = loaded;
+    const deps = { ...realDeps(settings), ...overrides };
+    const stateDir = chatStateOf();
+    const lock = acquireLock(stateDir);
+    if (!lock.ok)
+        throw new HostBusy(`Another chat host is already running on ${chatDirOf()}`);
+    deps.installLogging(join(chatLogsOf(), 'chat-host.log'), settings.logLevel);
+    const log = createScopedLogger('chat');
+    const db = openChatDatabase(join(stateDir, 'chat.db'));
+    await sweepDeadHost(db, deps.processes); // the lock is ours, so any recorded process belongs to a host that died
+    let closeServer = () => { };
+    let idle;
+    // `list` says from the ages in chat.json, read fresh; a wrong file keeps the last ages that were good.
+    let ages = settings;
+    const currentAges = () => {
+        const current = readChatConfig();
+        if (current.ok)
+            ages = current.settings;
+        return ages;
+    };
+    const projects = createProjects({ git: deps.git, token: deps.token, github: deps.github, clock: deps.clock });
+    const sessions = createSessions({ db, agents: settings.agents, clock: deps.clock, runners: deps.runners, env: deps.env, git: deps.git, projects, binaryFound: deps.binaryFound, probes: deps.probes, ages: currentAges, onLiveChange: () => idle?.recheck() });
+    // The clock's pass, at start and every hour while the host runs; the ages are read from chat.json each time, and a wrong file skips the pass.
+    let cancelPass = () => { };
+    let stopped = false;
+    let passInFlight = Promise.resolve();
+    const runPass = async () => {
+        try {
+            const current = readChatConfig();
+            if (current.ok)
+                await sessions.applyClock(current.settings);
+            else
+                log.error('the session lifecycle pass was skipped', new Error(chatConfigProblem(carrierHome(), current.errors)));
+        }
+        catch (error) {
+            log.error('the session lifecycle pass failed', error);
+        }
+    };
+    const clockPass = async () => {
+        if (stopped)
+            return;
+        passInFlight = runPass();
+        await passInFlight;
+        if (!stopped)
+            cancelPass = deps.clock.after(HOUR_MS, clockPass);
+    };
+    const close = () => {
+        stopped = true;
+        idle?.stop();
+        cancelPass();
+        closeServer();
+        db.$client.close();
+        lock.release();
+    };
+    let stopping;
+    const stop = () => (stopping ??= (async () => {
+        stopped = true;
+        await sessions.closeAll(); // also tells the pass in flight to leave the next session alone
+        await passInFlight; // so the database is not closed under a worktree that is half removed
+        close();
+        log.info('chat host stopped');
+        deps.exit(0);
+    })());
+    idle = idleExit({ clock: deps.clock, afterMs: deps.idleMs, live: sessions.liveCount, exit: stop });
+    try {
+        const clients = {
+            joined: () => void (idle?.joined(), sessions.clientJoined()),
+            left: () => void (idle?.left(), sessions.clientLeft()),
+        };
+        closeServer = (await startChatServer({ stateDir, startedAt: deps.clock.now(), controls: { ...sessions, cloneRepo: projects.cloneRepo, createProject: projects.createProject, githubRepos: projects.githubRepos, repoBranches: projects.repoBranches }, stop, clients })).close;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    if (deps.signals)
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+            process.on(signal, () => void stop());
+    await clockPass();
+    log.info('chat host started', { folder: carrierHome() });
+    return { stop };
+}

package/dist/chat/idle.js

@@ -0,0 +1,20 @@
+export const IDLE_EXIT_MS = 60_000;
+/**
+ * The host's exit rule: it ends `afterMs` after the later of its start and the last client leaving, as long as no
+ * session is live. A client arriving or a session living cancels the countdown; `recheck()` re-arms it when the live count drops.
+ */
+export function idleExit({ clock, afterMs = IDLE_EXIT_MS, live, exit }) {
+    let clients = 0;
+    let cancel;
+    const arm = () => {
+        cancel?.();
+        cancel = clients === 0 && live() === 0 ? clock.after(afterMs, exit) : undefined;
+    };
+    arm();
+    return {
+        joined: () => void (clients++, arm()),
+        left: () => void (clients--, arm()),
+        recheck: arm,
+        stop: () => cancel?.(),
+    };
+}

package/dist/chat/migrations/0000_lame_quasar.sql

@@ -0,0 +1,15 @@
+CREATE TABLE `sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent` text NOT NULL,
+	`harness` text NOT NULL,
+	`folder` text NOT NULL,
+	`title` text,
+	`options` text,
+	`nativeId` text,
+	`state` text DEFAULT 'idle' NOT NULL,
+	`pid` integer,
+	`pgid` integer,
+	`createdAt` integer NOT NULL,
+	`lastActiveAt` integer NOT NULL,
+	`archived` integer DEFAULT false NOT NULL
+);

package/dist/chat/migrations/0001_quiet_penance.sql

@@ -0,0 +1,23 @@
+CREATE TABLE `chat_events` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`sessionId` text NOT NULL,
+	`at` integer NOT NULL,
+	`kind` text NOT NULL,
+	`data` text NOT NULL,
+	FOREIGN KEY (`sessionId`) REFERENCES `sessions`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE INDEX `chat_events_session` ON `chat_events` (`sessionId`,`id`);--> statement-breakpoint
+CREATE TABLE `chat_turns` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`sessionId` text NOT NULL,
+	`startedAt` integer NOT NULL,
+	`model` text,
+	`outcome` text NOT NULL,
+	`durationMs` integer NOT NULL,
+	`toolCalls` integer NOT NULL,
+	`usage` text,
+	FOREIGN KEY (`sessionId`) REFERENCES `sessions`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE INDEX `chat_turns_session` ON `chat_turns` (`sessionId`);

package/dist/chat/migrations/0002_slim_ezekiel_stane.sql

@@ -0,0 +1 @@
+ALTER TABLE `sessions` ADD `command` text;

package/dist/chat/migrations/0003_naive_iron_lad.sql

@@ -0,0 +1,5 @@
+ALTER TABLE `sessions` ADD `workspaceKind` text DEFAULT 'folder' NOT NULL;--> statement-breakpoint
+ALTER TABLE `sessions` ADD `worktreeBranch` text;--> statement-breakpoint
+ALTER TABLE `sessions` ADD `worktreeFrom` text;--> statement-breakpoint
+ALTER TABLE `sessions` ADD `worktreeBase` text;--> statement-breakpoint
+ALTER TABLE `sessions` ADD `worktreePath` text;

package/dist/chat/migrations/0004_skinny_dakota_north.sql

@@ -0,0 +1 @@
+ALTER TABLE `sessions` ADD `keptAt` integer;

package/dist/chat/migrations/0005_tidy_strong_guy.sql

@@ -0,0 +1 @@
+ALTER TABLE `sessions` ADD `plan` text;

package/dist/chat/migrations/meta/0000_snapshot.json

@@ -0,0 +1,121 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "ef674763-66c1-408a-94c1-fcfe9d8c53db",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent": {
+          "name": "agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "harness": {
+          "name": "harness",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "folder": {
+          "name": "folder",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "options": {
+          "name": "options",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "nativeId": {
+          "name": "nativeId",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'idle'"
+        },
+        "pid": {
+          "name": "pid",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "pgid": {
+          "name": "pgid",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "createdAt": {
+          "name": "createdAt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "lastActiveAt": {
+          "name": "lastActiveAt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}