@a5c-ai/babysitter-breakpoints 0.0.27

package/.codex/skills/babysitter-breakpoint/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: babysitter-breakpoint
+description: Use the breakpoint API to communicate with users during babysitter runs (post breakpoints, poll for release, fetch feedback, and read context files). Trigger whenever a babysitter workflow needs approval, input, or status updates via breakpoints.
+---
+
+# babysitter-breakpoint
+
+Use this skill to handle all user communication via the `breakpoints` CLI. Do
+not prompt the user directly. Always post a breakpoint and poll until it is
+released, then fetch feedback and continue.
+
+## Workflow
+
+1. Create a breakpoint with the required payload and `payload.context.files`.
+2. Poll `breakpoints breakpoint wait <id> --interval 3` until `released`.
+3. Apply feedback from the printed details and continue.
+
+## Payload structure
+
+Always include a `context.files` array for referenced files:
+
+```json
+{
+  "context": {
+    "runId": "run-...",
+    "files": [
+      { "path": ".a5c/runs/<runId>/artifacts/process.md", "format": "markdown" },
+      { "path": ".a5c/runs/<runId>/inputs.json", "format": "code", "language": "json" },
+      { "path": ".a5c/runs/<runId>/code/main.js", "format": "code", "language": "javascript" }
+    ]
+  }
+}
+```
+
+See `references/breakpoint-api.md` for curl examples and endpoints.

package/.codex/skills/babysitter-breakpoint/references/breakpoint-api.md

@@ -0,0 +1,57 @@
+# Breakpoint CLI + API
+
+Use the `breakpoints` CLI to communicate with the user. The CLI wraps the local
+API. Never prompt directly.
+
+## Base URL
+- Default: `http://localhost:3000`
+- Override with `BREAKPOINT_API_URL` if set.
+
+## Auth
+- Agent token: `AGENT_TOKEN`
+- Human token: `HUMAN_TOKEN`
+- Use `Authorization: Bearer <token>` when set.
+
+## Create a breakpoint (agent)
+```bash
+breakpoints breakpoint create \
+  --question "Approve process + inputs + main.js?" \
+  --run-id run-... \
+  --title "Approval needed" \
+  --file ".a5c/runs/<runId>/artifacts/process.md,markdown" \
+  --file ".a5c/runs/<runId>/inputs.json,code,json" \
+  --file ".a5c/runs/<runId>/code/main.js,code,javascript"
+```
+
+## Poll for status
+```bash
+breakpoints breakpoint status <id>
+```
+
+## Fetch full details (including feedback)
+```bash
+breakpoints breakpoint show <id>
+```
+
+## Wait for release (prints details)
+```bash
+breakpoints breakpoint wait <id> --interval 3
+```
+
+## Fetch context file content (API)
+```bash
+curl -s "$BREAKPOINT_API_URL/api/breakpoints/<id>/context?path=path/to/file"
+```
+
+## Release with feedback (human)
+```bash
+curl -s -X POST "$BREAKPOINT_API_URL/api/breakpoints/<id>/feedback" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $HUMAN_TOKEN" \
+  -d '{"author":"reviewer","comment":"approved","release":true}'
+```
+
+## Notes
+- Poll every 2-10 seconds.
+- Continue orchestration only after `status` becomes `released` and feedback is retrieved.
+- Context files must be listed in the breakpoint payload and use allowlisted extensions.

package/README.md

@@ -0,0 +1,154 @@
+# Breakpoint Manager
+
+Lightweight breakpoint manager with API, queue worker, and web UI.
+
+This package now lives at `packages/breakpoints`.
+
+## Requirements
+- Node.js 18+
+
+## Setup
+```bash
+cd packages/breakpoints
+npm install
+npm run init:db
+```
+
+## Run (dev)
+```bash
+cd packages/breakpoints
+npm run dev
+```
+
+## Run (installed CLI)
+```bash
+breakpoints start
+```
+
+Or run separately:
+```bash
+npm run start:api
+npm run start:worker
+```
+
+## CLI Examples
+Start the full system (API + web UI + worker):
+```bash
+breakpoints start
+```
+
+Create a breakpoint (agent):
+```bash
+breakpoints breakpoint create --question "Need approval?" --title "Approval"
+```
+
+Check status:
+```bash
+breakpoints breakpoint status <id>
+```
+
+Wait for release:
+```bash
+breakpoints breakpoint wait <id> --interval 3
+```
+
+Install the babysitter-breakpoint skill:
+```bash
+breakpoints install-skill --target codex --scope global
+```
+
+## Configuration
+Environment variables:
+- `PORT` (default 3185)
+- `WEB_PORT` (default 3184)
+- `DB_PATH` (default `~/.a5c/breakpoints/db/breakpoints.db`)
+- `REPO_ROOT` (default package root / current working directory)
+- `AGENT_TOKEN` (optional)
+- `HUMAN_TOKEN` (optional)
+- `WORKER_POLL_MS` (default 2000)
+- `WORKER_BATCH_SIZE` (default 10)
+
+## API Examples
+Create breakpoint (agent):
+```bash
+curl -X POST http://localhost:3185/api/breakpoints \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -d '{"agentId":"agent-1","title":"Need review","payload":{"summary":"check this"},"tags":["review"],"ttlSeconds":3600}'
+```
+
+Check status:
+```bash
+curl http://localhost:3185/api/breakpoints/<id>/status
+```
+
+Release with feedback (human):
+```bash
+curl -X POST http://localhost:3185/api/breakpoints/<id>/feedback \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $HUMAN_TOKEN" \
+  -d '{"author":"reviewer","comment":"Looks good","release":true}'
+```
+
+## Breakpoint Context Payload
+To enable context rendering in the UI, include a `context.files` array in the
+breakpoint payload:
+```json
+{
+  "context": {
+    "runId": "run-...",
+    "files": [
+      { "path": "docs/plan.md", "format": "markdown" },
+      { "path": "api/routes.js", "format": "code", "language": "javascript" }
+    ]
+  }
+}
+```
+
+The API serves file content via:
+```
+GET /api/breakpoints/:id/context?path=path/to/file
+```
+Only allowlisted extensions are served, and the file must be listed in the
+breakpoint payload.
+
+## Web UI
+Open `http://localhost:3184` and provide the human token in the UI.
+
+## Install the babysitter-breakpoint skill
+```bash
+breakpoints install-skill
+```
+Defaults to global Codex install. Options:
+```bash
+breakpoints install-skill --target codex --scope global
+breakpoints install-skill --target codex --scope local
+breakpoints install-skill --target claude --scope global
+breakpoints install-skill --target claude --scope local
+breakpoints install-skill --target cursor --scope global
+breakpoints install-skill --target cursor --scope local
+```
+Global targets use `CODEX_HOME` or `~/.codex` for Codex, and `~/.claude` or `~/.cursor` for Claude/Cursor. Local installs write to `.codex/skills`, `.claude/skills`, or `.cursor/skills` under the package root. Restart the app after install.
+
+When installed from npm, the skill is bundled at `.codex/skills/babysitter-breakpoint/` inside the package and copied to the target location by `breakpoints install-skill`.
+
+## Breakpoint CLI (agent-friendly)
+Create a breakpoint:
+```bash
+breakpoints breakpoint create \
+  --question "Approve process + inputs + main.js?" \
+  --run-id run-123 \
+  --title "Approval needed" \
+  --file ".a5c/runs/run-123/artifacts/process.md,markdown" \
+  --file ".a5c/runs/run-123/inputs.json,code,json" \
+  --file ".a5c/runs/run-123/code/main.js,code,javascript"
+```
+
+Wait for release (prints full details when released):
+```bash
+breakpoints breakpoint wait <id> --interval 3
+```
+
+## Notes
+- Tags are stored as JSON in SQLite; tag filtering uses a simple string match.
+- The queue worker processes TTL expiration jobs; notification jobs are stubbed.

package/api/db.js

@@ -0,0 +1,93 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const sqlite3 = require("sqlite3");
+
+function defaultDbPath() {
+  const home = os.homedir();
+  return path.join(home, ".a5c", "breakpoints", "db", "breakpoints.db");
+}
+
+function expandHome(value) {
+  if (!value) return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith(`~${path.sep}`)) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function resolveDbPath(value) {
+  const expanded = expandHome(value);
+  if (!expanded) return expanded;
+  const normalized = path.normalize(expanded);
+  if (normalized.endsWith(path.sep)) {
+    return path.join(normalized, "breakpoints.db");
+  }
+  if (!path.extname(normalized)) {
+    return path.join(normalized, "breakpoints.db");
+  }
+  return normalized;
+}
+
+const DB_PATH = resolveDbPath(process.env.DB_PATH || defaultDbPath());
+
+function openDb() {
+  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+  return new sqlite3.Database(DB_PATH);
+}
+
+function run(db, sql, params = []) {
+  return new Promise((resolve, reject) => {
+    db.run(sql, params, function onRun(err) {
+      if (err) return reject(err);
+      resolve(this);
+    });
+  });
+}
+
+function get(db, sql, params = []) {
+  return new Promise((resolve, reject) => {
+    db.get(sql, params, (err, row) => {
+      if (err) return reject(err);
+      resolve(row);
+    });
+  });
+}
+
+function all(db, sql, params = []) {
+  return new Promise((resolve, reject) => {
+    db.all(sql, params, (err, rows) => {
+      if (err) return reject(err);
+      resolve(rows);
+    });
+  });
+}
+
+async function initDb(db) {
+  const schemaPath = path.join(__dirname, "..", "db", "schema.sql");
+  const schema = fs.readFileSync(schemaPath, "utf8");
+  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+  await run(db, "PRAGMA foreign_keys = ON;");
+  const statements = schema
+    .split(";")
+    .map((statement) => statement.trim())
+    .filter((statement) => statement.length);
+  for (const statement of statements) {
+    await run(db, statement);
+  }
+}
+
+module.exports = {
+  DB_PATH,
+  openDb,
+  run,
+  get,
+  all,
+  initDb,
+};