@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/storage/db.js

@@ -0,0 +1,8 @@
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
+export function openDatabase(file) {
+    const db = drizzle(new Database(file));
+    migrate(db, { migrationsFolder: `${import.meta.dirname}/migrations` });
+    return db;
+}

package/dist/storage/epic-review-threads.js

@@ -0,0 +1,19 @@
+import { integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+// A cache of what GitHub said about the final pull request's review threads the last time the poll asked (ADR 0008). Never read to decide anything.
+export const epicReviewThreads = sqliteTable('epic_review_threads', {
+    epicId: integer().notNull(),
+    id: text().notNull(), // GraphQL node id
+    position: integer().notNull(), // GitHub's order
+    path: text().notNull(),
+    line: integer(),
+    resolved: integer({ mode: 'boolean' }).notNull(),
+    outdated: integer({ mode: 'boolean' }).notNull(),
+    author: text(),
+    bot: integer({ mode: 'boolean' }).notNull(),
+    firstLine: text().notNull(),
+    commentCount: integer().notNull(),
+    url: text().notNull(),
+    readAt: integer().notNull(), // ms since epoch
+    // Only the first hundred threads are read; the same on every row of an epic, like epic_slices.
+    truncated: integer({ mode: 'boolean' }).notNull().default(false),
+}, (table) => [primaryKey({ columns: [table.epicId, table.id] })]);

package/dist/storage/epic-slices.js

@@ -0,0 +1,17 @@
+import { integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+// A cache of what GitHub said about an epic's slices the last time the poll asked (ADR 0008). Never read to decide anything.
+export const epicSlices = sqliteTable('epic_slices', {
+    epicId: integer().notNull(),
+    number: integer().notNull(),
+    title: text().notNull(),
+    state: text({ enum: ['closed', 'skipped', 'in_progress', 'waiting', 'ready'] }).notNull(),
+    blockedBy: text({ mode: 'json' }).$type().notNull(), // the numbers of the blockers still open
+    assignee: text(),
+    prNumber: integer(),
+    prState: text({ enum: ['open', 'draft', 'merged', 'closed'] }),
+    prMergedAt: integer(), // ms since epoch
+    closedAt: integer(), // ms since epoch
+    readAt: integer().notNull(), // ms since epoch
+    // Only the first hundred slices are read; the same on every row of an epic. ponytail: per row, a column of its own if more flags ever join it.
+    truncated: integer({ mode: 'boolean' }).notNull().default(false),
+}, (table) => [primaryKey({ columns: [table.epicId, table.number] })]);

package/dist/storage/events.js

@@ -0,0 +1,52 @@
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { executions } from './executions.js';
+import { epics } from './schema.js';
+// Append-only history of what the engine did to an epic; the autoincrement id keeps the order.
+export const epicEvents = sqliteTable('epic_events', {
+    id: integer().primaryKey({ autoIncrement: true }),
+    epicId: integer().notNull().references(() => epics.id),
+    at: integer().notNull(), // ms since epoch
+    type: text().notNull(),
+    data: text({ mode: 'json' }).$type().notNull(),
+});
+// What an agent did during an execution (ADR 0006), already bounded and redacted. The id is the cursor of the `events` request.
+// A tool call is two rows with the same callId. Deleted with the logs, 30 days after the epic ends.
+export const executionEvents = sqliteTable('execution_events', {
+    id: integer().primaryKey({ autoIncrement: true }),
+    executionId: text().notNull().references(() => executions.executionId),
+    at: integer().notNull(), // ms since epoch: the line's own time, else when it arrived
+    kind: text({ enum: ['say', 'tool_start', 'tool_end', 'note', 'error', 'task'] }).notNull(),
+    callId: text(),
+    agentId: text(), // the Claude subagent that did it
+    tool: text(),
+    arg: text(),
+    summary: text(),
+    status: text({ enum: ['ok', 'err'] }),
+    durationMs: integer(),
+    payload: text({ mode: 'json' }).$type(), // the text of a message, a command's output, a diff, the slice and lane hints
+}, (table) => [index('execution_events_execution').on(table.executionId, table.id)]);
+/** Stores the events of one output chunk in a single transaction; `arrival` is the time of those without their own. */
+export function recordEvents(db, executionId, events, arrival) {
+    if (events.length === 0)
+        return;
+    db.transaction((tx) => {
+        for (const { at, kind, callId, agentId, tool, arg, summary, status, durationMs, ...rest } of events) {
+            const payload = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
+            tx.insert(executionEvents)
+                .values({
+                executionId,
+                at: at ?? arrival,
+                kind,
+                callId: callId ?? null,
+                agentId: agentId ?? null,
+                tool: tool ?? null,
+                arg: arg ?? null,
+                summary: summary ?? null,
+                status: status ?? null,
+                durationMs: durationMs ?? null,
+                payload: Object.keys(payload).length > 0 ? payload : null,
+            })
+                .run();
+        }
+    });
+}

package/dist/storage/executions.js

@@ -0,0 +1,31 @@
+import { integer, real, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { epics } from './schema.js';
+export const executionStates = ['running', 'finished', 'failed', 'timed_out', 'interrupted', 'invalid_result'];
+export const failureKinds = ['usage_limit', 'api_error', 'killed', 'crashed', 'spawn_error', 'auth', 'session_lost', 'timeout', 'invalid_result', 'unknown'];
+export const executions = sqliteTable('executions', {
+    executionId: text().primaryKey(),
+    epicId: integer().notNull().references(() => epics.id),
+    stage: text({ enum: ['ship', 'review', 'fix'] }).notNull(),
+    status: text({ enum: executionStates }).notNull().default('running'),
+    sessionId: text(), // saved as soon as the runner reports it, not when it ends
+    // Why a technical failure ended it; set only for the ones the engine retries or stops for a person (auth_failed).
+    error: text(),
+    // Why it ended badly (glossary: Failure kind); all null on an execution that ended ok, that Carrier stopped, or that predates them.
+    failureKind: text({ enum: failureKinds }),
+    failureDetail: text(),
+    exitCode: integer(),
+    signal: text(),
+    hostFreeMemMb: integer(), // only for killed, crashed and unknown
+    hostLoad: real(), // one-minute load average, same cases
+    // The agent and the folder this execution ran with, written when the row is inserted; null on rows from before they were recorded.
+    harness: text(),
+    model: text(),
+    provider: text(),
+    option: text(), // the agent option the role ran on
+    configDir: text(), // that option's config folder, absolute; null when it had none
+    workspace: text(), // the cwd of the session: what resuming it needs
+    round: integer(), // the review round, null for ship
+    resultPath: text().notNull(),
+    startedAt: integer().notNull(),
+    finishedAt: integer(),
+});

package/dist/storage/lock.js

@@ -0,0 +1,21 @@
+import { chmodSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+// The lock is an exclusive SQLite transaction on a file in the engine's state folder, held for the life of
+// the process. The OS drops it when the process dies, so a crash never leaves it stuck.
+export function acquireLock(stateDir) {
+    mkdirSync(stateDir, { recursive: true });
+    chmodSync(stateDir, 0o700); // the database, the control socket and the lock in here are for the user only, also when the folder already existed with a looser mode
+    // timeout 0: no waiting, a held lock fails immediately with SQLITE_BUSY.
+    const db = new Database(join(stateDir, 'carrier.lock'), { timeout: 0 });
+    try {
+        db.exec('BEGIN EXCLUSIVE');
+    }
+    catch (error) {
+        db.close();
+        if (error instanceof Error && 'code' in error && error.code === 'SQLITE_BUSY')
+            return { ok: false };
+        throw error;
+    }
+    return { ok: true, release: () => db.close() };
+}

package/dist/storage/migrations/0000_nosy_demogoblin.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `epics` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`repo` text NOT NULL,
+	`issue` integer NOT NULL
+);

package/dist/storage/migrations/0001_worried_grey_gargoyle.sql

@@ -0,0 +1,3 @@
+ALTER TABLE `epics` ADD `status` text DEFAULT 'queued' NOT NULL;--> statement-breakpoint
+ALTER TABLE `epics` ADD `queuedAt` integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX `epics_repo_issue` ON `epics` (`repo`,`issue`);

package/dist/storage/migrations/0002_tough_squirrel_girl.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `caller_results` (
+	`executionId` text PRIMARY KEY NOT NULL,
+	`outcome` text NOT NULL,
+	`result` text NOT NULL
+);

package/dist/storage/migrations/0003_loose_maria_hill.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `epics` ADD `startedAt` integer;--> statement-breakpoint
+ALTER TABLE `epics` ADD `config` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `cancelReason` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `labelPending` integer DEFAULT false NOT NULL;

package/dist/storage/migrations/0004_long_cerise.sql

@@ -0,0 +1,18 @@
+CREATE TABLE `executions` (
+	`executionId` text PRIMARY KEY NOT NULL,
+	`epicId` integer NOT NULL,
+	`stage` text NOT NULL,
+	`status` text DEFAULT 'running' NOT NULL,
+	`sessionId` text,
+	`resultPath` text NOT NULL,
+	`startedAt` integer NOT NULL,
+	`finishedAt` integer,
+	FOREIGN KEY (`epicId`) REFERENCES `epics`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+ALTER TABLE `epics` ADD `stage` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `round` integer;--> statement-breakpoint
+ALTER TABLE `epics` ADD `prNumber` integer;--> statement-breakpoint
+ALTER TABLE `epics` ADD `prHeadSha` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `needsHumanReason` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `finishedAt` integer;

package/dist/storage/migrations/0005_review_result.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `epics` ADD `reviewedSha` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `verification` text;

package/dist/storage/migrations/0006_melted_menace.sql

@@ -0,0 +1,10 @@
+CREATE TABLE `epic_events` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`epicId` integer NOT NULL,
+	`at` integer NOT NULL,
+	`type` text NOT NULL,
+	`data` text NOT NULL,
+	FOREIGN KEY (`epicId`) REFERENCES `epics`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+ALTER TABLE `executions` ADD `error` text;

package/dist/storage/migrations/0007_powerful_bloodscream.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `epics` ADD `removedFrom` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `removedReason` text;

package/dist/storage/migrations/0008_panel_state.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `epics` ADD `stageStartedAt` integer;--> statement-breakpoint
+ALTER TABLE `epics` ADD `workspace` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `lastActivityAt` integer;--> statement-breakpoint
+ALTER TABLE `epics` ADD `lastError` text;

package/dist/storage/migrations/0009_workable_tiger_shark.sql

@@ -0,0 +1,5 @@
+ALTER TABLE `executions` ADD `harness` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `model` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `provider` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `workspace` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `round` integer;

package/dist/storage/migrations/0010_nasty_blue_marvel.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `epics` ADD `needsHumanKind` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `title` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `labels` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `branch` text;

package/dist/storage/migrations/0011_steep_lila_cheney.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `epic_slices` (
+	`epicId` integer NOT NULL,
+	`number` integer NOT NULL,
+	`title` text NOT NULL,
+	`state` text NOT NULL,
+	`blockedBy` text NOT NULL,
+	`assignee` text,
+	`prNumber` integer,
+	`closedAt` integer,
+	`readAt` integer NOT NULL,
+	`truncated` integer DEFAULT false NOT NULL,
+	PRIMARY KEY(`epicId`, `number`)
+);

package/dist/storage/migrations/0012_talented_big_bertha.sql

@@ -0,0 +1 @@
+ALTER TABLE `epics` ADD `pr` text;

package/dist/storage/migrations/0013_third_mulholland_black.sql

@@ -0,0 +1,17 @@
+CREATE TABLE `execution_events` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`executionId` text NOT NULL,
+	`at` integer NOT NULL,
+	`kind` text NOT NULL,
+	`callId` text,
+	`agentId` text,
+	`tool` text,
+	`arg` text,
+	`summary` text,
+	`status` text,
+	`durationMs` integer,
+	`payload` text,
+	FOREIGN KEY (`executionId`) REFERENCES `executions`(`executionId`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE INDEX `execution_events_execution` ON `execution_events` (`executionId`,`id`);

package/dist/storage/migrations/0014_perfect_marten_broadcloak.sql

@@ -0,0 +1,20 @@
+CREATE TABLE `epic_review_threads` (
+	`epicId` integer NOT NULL,
+	`id` text NOT NULL,
+	`position` integer NOT NULL,
+	`path` text NOT NULL,
+	`line` integer,
+	`resolved` integer NOT NULL,
+	`outdated` integer NOT NULL,
+	`author` text,
+	`bot` integer NOT NULL,
+	`firstLine` text NOT NULL,
+	`commentCount` integer NOT NULL,
+	`url` text NOT NULL,
+	`readAt` integer NOT NULL,
+	`truncated` integer DEFAULT false NOT NULL,
+	PRIMARY KEY(`epicId`, `id`)
+);
+--> statement-breakpoint
+-- The cached pull request blocks of finished epics predate the threads: clear them so the next poll reads block and threads once (a cache of GitHub, nothing decides from it).
+UPDATE `epics` SET `pr` = NULL WHERE `status` IN ('merged', 'cancelled');

package/dist/storage/migrations/0015_long_bloodaxe.sql

@@ -0,0 +1 @@
+ALTER TABLE `epics` ADD `observationsPassAt` integer;

package/dist/storage/migrations/0016_neat_true_believers.sql

@@ -0,0 +1,5 @@
+ALTER TABLE `epic_slices` ADD `prState` text;--> statement-breakpoint
+ALTER TABLE `epic_slices` ADD `prMergedAt` integer;
+--> statement-breakpoint
+-- The cached slices predate the own-pull-request rule (some linked a sibling's or the final PR): clear them so the next poll reads them again (a cache of GitHub, nothing decides from it).
+DELETE FROM `epic_slices`;

package/dist/storage/migrations/0017_previous_swarm.sql

@@ -0,0 +1,6 @@
+ALTER TABLE `executions` ADD `failureKind` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `failureDetail` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `exitCode` integer;--> statement-breakpoint
+ALTER TABLE `executions` ADD `signal` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `hostFreeMemMb` integer;--> statement-breakpoint
+ALTER TABLE `executions` ADD `hostLoad` real;

package/dist/storage/migrations/0018_opposite_plazm.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `executions` ADD `option` text;--> statement-breakpoint
+ALTER TABLE `executions` ADD `configDir` text;

package/dist/storage/migrations/0019_hesitant_triton.sql

@@ -0,0 +1,3 @@
+ALTER TABLE `epics` ADD `authorOption` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `reviewerOption` text;--> statement-breakpoint
+ALTER TABLE `epics` ADD `choiceDeadline` integer;

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

@@ -0,0 +1,49 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "19a61b42-1053-4c64-9523-b6e8e8f69dd3",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "epics": {
+      "name": "epics",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "repo": {
+          "name": "repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "issue": {
+          "name": "issue",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/dist/storage/migrations/meta/0001_snapshot.json

@@ -0,0 +1,74 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "e7f9ace3-49db-4427-8845-2ac122e12331",
+  "prevId": "19a61b42-1053-4c64-9523-b6e8e8f69dd3",
+  "tables": {
+    "epics": {
+      "name": "epics",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "repo": {
+          "name": "repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "issue": {
+          "name": "issue",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'queued'"
+        },
+        "queuedAt": {
+          "name": "queuedAt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "epics_repo_issue": {
+          "name": "epics_repo_issue",
+          "columns": [
+            "repo",
+            "issue"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/dist/storage/migrations/meta/0002_snapshot.json

@@ -0,0 +1,105 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "29475005-f7df-4081-90f2-9bc2ed9c809e",
+  "prevId": "e7f9ace3-49db-4427-8845-2ac122e12331",
+  "tables": {
+    "epics": {
+      "name": "epics",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "repo": {
+          "name": "repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "issue": {
+          "name": "issue",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'queued'"
+        },
+        "queuedAt": {
+          "name": "queuedAt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "epics_repo_issue": {
+          "name": "epics_repo_issue",
+          "columns": [
+            "repo",
+            "issue"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "caller_results": {
+      "name": "caller_results",
+      "columns": {
+        "executionId": {
+          "name": "executionId",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "outcome": {
+          "name": "outcome",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "result": {
+          "name": "result",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}