@a5c-ai/babysitter-sdk 0.0.16 → 0.0.18

package/dist/cli/main.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 export declare function createBabysitterCli(): {
     run(argv?: string[]): Promise<number>;
     formatHelp(): string;

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAo5CA,wBAAgB,mBAAmB;eAEf,MAAM,EAAE,GAA2B,OAAO,CAAC,MAAM,CAAC;kBAyCpD,MAAM;EAIvB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAonDA,wBAAgB,mBAAmB;eAEf,MAAM,EAAE,GAA2B,OAAO,CAAC,MAAM,CAAC;kBA4CpD,MAAM;EAIvB"}

package/dist/cli/main.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -36,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBabysitterCli = createBabysitterCli;
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
 const nodeTaskRunner_1 = require("./nodeTaskRunner");
 const orchestrateIteration_1 = require("../runtime/orchestrateIteration");
 const createRun_1 = require("../runtime/createRun");
@@ -54,6 +56,7 @@ const USAGE = `Usage:
   babysitter run:continue <runDir> [--runs-dir <dir>] [--json] [--dry-run] [--auto-node-tasks] [--auto-node-max <n>] [--auto-node-label <text>]
   babysitter task:list <runDir> [--runs-dir <dir>] [--pending] [--kind <kind>] [--json]
   babysitter task:show <runDir> <effectId> [--runs-dir <dir>] [--json]
+  babysitter skill:install [--type <claude|codex|cursor>] [--scope <local|global>] [--skills-dir <dir>] [--force] [--json] [--dry-run]
 
 Global flags:
   --runs-dir <dir>   Override the runs directory (defaults to current working directory).
@@ -62,14 +65,20 @@ Global flags:
   --verbose          Log resolved paths and options to stderr for debugging.
   --help, -h         Show this help text.`;
 const LARGE_RESULT_PREVIEW_LIMIT = 1024 * 1024; // 1 MiB
+const DEFAULT_SKILL_TARGET = "codex";
+const DEFAULT_SKILL_SCOPE = "local";
 function parseArgs(argv) {
     const [initialCommand, ...rest] = argv;
     const parsed = {
         command: initialCommand,
         runsDir: ".",
+        skillsDir: undefined,
+        skillType: DEFAULT_SKILL_TARGET,
+        skillScope: DEFAULT_SKILL_SCOPE,
         json: false,
         dryRun: false,
         verbose: false,
+        force: false,
         helpRequested: false,
         autoNodeTasks: false,
         pendingOnly: false,
@@ -90,6 +99,18 @@ function parseArgs(argv) {
             parsed.runsDir = expectFlagValue(rest, ++i, "--runs-dir");
             continue;
         }
+        if (arg === "--skills-dir") {
+            parsed.skillsDir = expectFlagValue(rest, ++i, "--skills-dir");
+            continue;
+        }
+        if (arg === "--type") {
+            parsed.skillType = expectSkillTarget(expectFlagValue(rest, ++i, "--type"), "--type");
+            continue;
+        }
+        if (arg === "--scope") {
+            parsed.skillScope = expectSkillScope(expectFlagValue(rest, ++i, "--scope"), "--scope");
+            continue;
+        }
         if (arg === "--json") {
             parsed.json = true;
             continue;
@@ -98,6 +119,10 @@ function parseArgs(argv) {
             parsed.dryRun = true;
             continue;
         }
+        if (arg === "--force") {
+            parsed.force = true;
+            continue;
+        }
         if (arg === "--verbose") {
             parsed.verbose = true;
             continue;
@@ -211,6 +236,29 @@ function parsePositiveInteger(raw, flag) {
     }
     return Math.floor(parsed);
 }
+function expectSkillTarget(raw, flag) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "claude" || normalized === "codex" || normalized === "cursor") {
+        return normalized;
+    }
+    throw new Error(`${flag} must be one of: claude, codex, cursor`);
+}
+function expectSkillScope(raw, flag) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "local" || normalized === "global") {
+        return normalized;
+    }
+    throw new Error(`${flag} must be one of: local, global`);
+}
+function resolveSkillsDir(parsed) {
+    if (parsed.skillsDir) {
+        return path.resolve(parsed.skillsDir);
+    }
+    const scopeBase = parsed.skillScope === "global"
+        ? path.join(os.homedir(), `.${parsed.skillType}`)
+        : path.resolve(`.${parsed.skillType}`);
+    return path.join(scopeBase, "skills");
+}
 function summarizeActions(actions) {
     return actions.map((action) => ({
         effectId: action.effectId,
@@ -308,6 +356,84 @@ function formatVerboseValue(value) {
         return String(value);
     return JSON.stringify(value);
 }
+function resolveBundledSkillsRoot() {
+    return path.resolve(__dirname, "..", "..", "skills");
+}
+async function listBundledSkillDirs() {
+    const root = resolveBundledSkillsRoot();
+    const entries = await node_fs_1.promises.readdir(root, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+async function pathExists(filePath) {
+    try {
+        await node_fs_1.promises.stat(filePath);
+        return true;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function toPosixPath(value) {
+    return value.replace(/\\/g, "/");
+}
+async function installBundledSkillDir(skillName, options) {
+    const sourceDir = path.join(resolveBundledSkillsRoot(), skillName);
+    const destinationDir = path.join(options.skillsDir, skillName);
+    try {
+        const sourceExists = await pathExists(sourceDir);
+        if (!sourceExists) {
+            return {
+                name: skillName,
+                status: "error",
+                sourceDir,
+                destinationDir,
+                message: "bundled skill missing",
+            };
+        }
+        const destinationExists = await pathExists(destinationDir);
+        if (destinationExists && !options.force) {
+            return {
+                name: skillName,
+                status: "skipped",
+                sourceDir,
+                destinationDir,
+                message: "already installed",
+            };
+        }
+        if (options.dryRun) {
+            return {
+                name: skillName,
+                status: "planned",
+                sourceDir,
+                destinationDir,
+            };
+        }
+        if (destinationExists && options.force) {
+            await node_fs_1.promises.rm(destinationDir, { recursive: true, force: true });
+        }
+        await node_fs_1.promises.mkdir(options.skillsDir, { recursive: true });
+        await node_fs_1.promises.cp(sourceDir, destinationDir, { recursive: true });
+        return {
+            name: skillName,
+            status: "installed",
+            sourceDir,
+            destinationDir,
+        };
+    }
+    catch (error) {
+        return {
+            name: skillName,
+            status: "error",
+            sourceDir,
+            destinationDir,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 function allowSecretLogs(parsed) {
     if (!parsed.json || !parsed.verbose) {
         return false;
@@ -1036,6 +1162,86 @@ async function handleTaskShow(parsed) {
     }
     return 0;
 }
+async function handleSkillInstall(parsed) {
+    const skillsDir = resolveSkillsDir(parsed);
+    logVerbose("skill:install", parsed, {
+        skillsDir,
+        type: parsed.skillType,
+        scope: parsed.skillScope,
+        dryRun: parsed.dryRun,
+        force: parsed.force,
+        json: parsed.json,
+    });
+    const results = [];
+    let skillNames;
+    try {
+        skillNames = await listBundledSkillDirs();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (parsed.json) {
+            console.log(JSON.stringify({ skillsDir, type: parsed.skillType, scope: parsed.skillScope, error: message, results: [] }));
+        }
+        else {
+            console.error(`[skill:install] failed to read bundled skills: ${message}`);
+        }
+        return 1;
+    }
+    if (!skillNames.length) {
+        if (parsed.json) {
+            console.log(JSON.stringify({ skillsDir, type: parsed.skillType, scope: parsed.skillScope, error: "no bundled skills found", results: [] }));
+        }
+        else {
+            console.error("[skill:install] no bundled skills found");
+        }
+        return 1;
+    }
+    for (const skillName of skillNames) {
+        results.push(await installBundledSkillDir(skillName, { skillsDir, dryRun: parsed.dryRun, force: parsed.force }));
+    }
+    const counts = { installed: 0, skipped: 0, planned: 0, error: 0 };
+    for (const result of results) {
+        if (result.status === "installed")
+            counts.installed += 1;
+        else if (result.status === "skipped")
+            counts.skipped += 1;
+        else if (result.status === "planned")
+            counts.planned += 1;
+        else
+            counts.error += 1;
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify({ skillsDir, type: parsed.skillType, scope: parsed.skillScope, results }));
+        return counts.error > 0 ? 1 : 0;
+    }
+    const parts = [`[skill:install] dir=${skillsDir}`];
+    if (!parsed.skillsDir) {
+        parts.push(`type=${parsed.skillType}`);
+        parts.push(`scope=${parsed.skillScope}`);
+    }
+    if (parsed.dryRun)
+        parts.push("dryRun=true");
+    if (parsed.force)
+        parts.push("force=true");
+    if (counts.installed)
+        parts.push(`installed=${counts.installed}`);
+    if (counts.skipped)
+        parts.push(`skipped=${counts.skipped}`);
+    if (counts.planned)
+        parts.push(`planned=${counts.planned}`);
+    if (counts.error)
+        parts.push(`errors=${counts.error}`);
+    console.log(parts.join(" "));
+    for (const result of results) {
+        const relativeDest = toPosixPath(path.relative(skillsDir, result.destinationDir));
+        const relativeSource = toPosixPath(path.relative(skillsDir, result.sourceDir));
+        const destLabel = relativeDest.startsWith("..") ? toPosixPath(result.destinationDir) : relativeDest;
+        const sourceLabel = relativeSource.startsWith("..") ? toPosixPath(result.sourceDir) : relativeSource;
+        const messageSuffix = result.message ? ` message=${result.message}` : "";
+        console.log(`- ${result.name} status=${result.status} dest=${destLabel} src=${sourceLabel}${messageSuffix}`);
+    }
+    return counts.error > 0 ? 1 : 0;
+}
 function toTaskListEntry(record, runDir) {
     return {
         effectId: record.effectId,
@@ -1325,6 +1531,9 @@ function createBabysitterCli() {
                 if (parsed.command === "task:show") {
                     return await handleTaskShow(parsed);
                 }
+                if (parsed.command === "skill:install") {
+                    return await handleSkillInstall(parsed);
+                }
                 console.error(USAGE);
                 return 1;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a5c-ai/babysitter-sdk",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Storage and run-registry primitives for event-sourced babysitter workflows.",
   "license": "UNLICENSED",
   "type": "commonjs",
@@ -10,7 +10,8 @@
     "babysitter": "dist/cli/main.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/babysitter/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: babysitter
+description: Orchestrate .a5c runs via @a5c-ai/babysitter-sdk CLI (create, continue, inspect, task ops). Use when the user asks to orchestrate or babysit a run; delegate breakpoint communication to the babysitter-breakpoint skill.
+---
+
+# babysitter
+
+You are **babysitter**—the orchestrator that keeps `.a5c/runs/<runId>/` in a healthy, deterministic state. Follow an event-sourced workflow and use the `@a5c-ai/babysitter-sdk` CLI wherever possible instead of manual scripts. The CLI exposes the surface documented in `docs/cli-examples.md` (`run:create`, `run:status`, `run:events`, `run:continue`, `task:list`, `task:run`, etc.).
+
+We operate in an **iterative, quality-gated loop**:
+
+1. Run preflight checks (CLI version, global flags) before every session.
+2. Execute a single CLI-driven orchestration step.
+3. Verify the output against the SDK/CLI references (field names, metadata, redaction rules).
+4. Repeat until the run converges (status `completed`/`failed`). Stop immediately if verification fails; fix the drift first.
+
+> **CLI alias:** all examples use  
+> `CLI="npx -y @a5c-ai/babysitter-sdk"`  
+> so you can run commands from repo root like `"$CLI run:status .a5c/runs/<id>"`. Adjust if you install the binary globally.
+
+---
+
+## 1. Setup & quality gate
+
+1. Verify CLI availability **and capture version** (quality gate)
+
+   ```bash
+   $CLI --version
+   $CLI run:status .a5c/runs/example --help   # sanity check output
+   ```
+
+   Ensure the help text matches the options documented in `docs/cli-examples.md` (global flags, redaction notes). Record the version in your notes.
+2. Ensure the CLI orchestration output is accessible by running a quick
+   `run:status` or `run:events` check before you proceed.
+
+Do **not** proceed if the CLI check fails; fix the issue (missing Node, npx resolution, command errors) first—this is your quality gate.
+
+---
+
+## 2. Core orchestration rules (self-contained)
+
+- **CLI-first**: use the babysitter CLI for all run state and orchestration.
+- **Run entry**: you are either resuming a run id or creating a new run from a high-level task.
+- **Main.js approval**: when you create a new run, inspect `.a5c/processes/**` for a suitable starting point, generate `.a5c/runs/<runId>/code/main.js`, and create `.a5c/runs/<runId>/artifacts/process.md`. Before any orchestration, use the `babysitter-breakpoint` skill to request approval of the process, inputs, and `main.js`. Do not proceed until the breakpoint is released with approval. After approval, do not change `main.js` without explicit instruction.
+- **Missing babysitter-breakpoint skill**: if the `babysitter-breakpoint` skill is unavailable, install it from npm by running `npm install -g @a5c-ai/babysitter-breakpoints`, then `breakpoints install-skill --target codex --scope global`. If the `breakpoints` CLI is not on PATH, run `npx -y @a5c-ai/babysitter-breakpoints install-skill --target codex --scope global`. Restart Codex after install.
+- **Do the work**: execute the CLI-provided next action yourself; do not defer
+  to agent runners or function templates.
+- **Follow the process**: execute exactly what `code/main.js` (and imported files) prescribe; only deviate when the user explicitly instructs it.
+- **Helper scripts**: if needed, store them in `.a5c/orchestrator_scripts/` or `.a5c/runs/<runId>/orchestrator/`, never as whole-iteration automation.
+- **Journal/state ownership**: do not edit `journal.jsonl` or `state.json` by hand; use the CLI and agent outputs so state stays deterministic.
+- **Wrapper semantics**: if a function call is wrapped with `newRun` or `@run`, create a new run and orchestrate it separately, then report the result to the parent run. If a function list is wrapped with `parallel(...)`, orchestrate them in parallel and return once all are complete.
+- **Sleep handling**: when encountering `sleep(...)`, record start/end via CLI events/notes so the process is resumable.
+
+
+
+---
+
+## 3. Inputs you may receive
+
+- **Resume existing run**: user supplies run id (e.g., `run-20260109-101648-dev-build`). All artifacts live under `.a5c/runs/<runId>/`.
+- **Create new run**: user provides a high-level task. You must initialize a fresh run id, craft `code/main.js`, update `inputs.json`, etc.
+
+Regardless of the entry point, always:
+
+1. Read/understand `.a5c/runs/<runId>/code/main.js` and referenced recipe files (`.a5c/processes/**`).
+2. Review `inputs.json`, `state.json`, and the latest journal entries (via CLI).
+
+---
+
+## 4. CLI workflows
+
+### 3.1 Inspecting a run
+
+```bash
+$CLI run:status .a5c/runs/<runId>
+$CLI run:events .a5c/runs/<runId> --limit 50 --reverse   # tail recent events
+```
+
+Use `--json` when you need machine-readable data. These commands replace manual `tail` or ad-hoc scripts; they also echo deterministic metadata pairs (`stateVersion`, `journalHead`, `pending[...]`).
+
+### 3.2 Creating a run
+
+```bash
+$CLI run:create \
+  --process-id dev/build \
+  --entry .a5c/processes/roles/development/recipes/full_project.js#fullProject \
+  --inputs examples/inputs/build.json \
+  --run-id "run-$(date -u +%Y%m%d-%H%M%S)-dev-build"
+```
+
+The CLI prints the new run id + directory. Immediately open `.a5c/runs/<runId>/code/main.js` to ensure it reflects the requested recipe; if you generate a custom `main.js`, still store it under `code/` and capture the narrative in `artifacts/process.md`. Mermaid diagrams are no longer required.
+
+### 3.3 Driving iterations
+
+Use `run:step` for single iterations or `run:continue` for full loops:
+
+```bash
+$CLI run:step .a5c/runs/<runId> --json
+$CLI run:continue .a5c/runs/<runId> --auto-node-tasks \
+  --auto-node-max 5 \
+  --runs-dir .a5c/runs
+```
+
+CLI output tells you the status (`waiting/completed/failed`), pending effects, and metadata. If it hits a breakpoint or needs manual input, use the `babysitter-breakpoint` skill; wait for release before continuing. When auto-running node tasks, the CLI logs each `effectId` and scheduler hints so you don’t need to script those paths yourself.
+
+> **Quality gate:** compare the JSON payload to the structure documented in `docs/cli-examples.md` §3–§6 (`pending`, `autoRun.executed/pending`, `metadata.stateVersion/pendingEffectsByKind`). If a field is missing or renamed, stop and reconcile with the SDK team before proceeding; otherwise documentation and harnesses will drift.
+
+### 3.4 Working with tasks
+
+```bash
+$CLI task:list .a5c/runs/<runId> --pending
+$CLI task:show .a5c/runs/<runId> <effectId> --json
+$CLI task:run .a5c/runs/<runId> <effectId> --dry-run
+$CLI task:run .a5c/runs/<runId> <effectId> \
+  --json --verbose \
+  -- env BABYSITTER_ALLOW_SECRET_LOGS=true
+```
+
+Use these instead of manually inspecting `tasks/<effectId>`. Remember: raw payloads remain redacted unless `BABYSITTER_ALLOW_SECRET_LOGS` **and** `--json --verbose` are set. Verify the output includes `payloads: redacted…` whenever the guard is disabled; treat deviations as failures that must be investigated.
+
+### 3.5 Journal utilities
+
+```bash
+$CLI run:events .a5c/runs/<runId> --limit 20
+$CLI run:events .a5c/runs/<runId> --reverse --json > tmp/events.json
+```
+
+The CLI already writes events for actions, notes, artifacts, sleeps, etc.
+
+---
+
+## 5. Orchestration loop (CLI-first)
+
+1. **Read process + state**  
+   - `code/main.js`, imported recipes  
+   - `state.json`, `inputs.json`, plus recent journal entries via `$CLI run:events …`
+2. **Determine next action** from `code/main.js` and/or the CLI orchestration
+   output (pending effects, task payloads, or explicit next-step notes).
+3. **Execute the next action** directly in the repo, following the CLI
+   instructions verbatim and updating artifacts as needed.
+4. **Journal & state are auto-managed** by the CLI as long as you drive iterations with `run:step` / `run:continue`. Do not edit `journal.jsonl` or `state.json` directly.
+5. **Breakpoints/sleep**: when CLI reports `Awaiting input`, use the `babysitter-breakpoint` skill to collect the missing information and wait for release. For sleeps, log start/end using CLI events; no manual timers.
+
+Loop until `status` is `completed` or `failed`. Never edit `journal.jsonl` or `state.json` directly; use CLI commands or agent outputs that update them.
+
+> **Iteration verification:** after every CLI loop, run `$CLI run:status .a5c/runs/<runId> --json` and confirm `stateVersion` increased (or stayed steady when waiting), pending counts match expectations, and metadata fields are present (for example `stateVersion`, `pendingEffectsByKind`, and `autoRun`). If not, pause and reconcile before issuing more actions.
+
+---
+
+## 6. Artifacts & documentation
+
+- Store specs, summaries, and diagrams under `.a5c/runs/<runId>/artifacts/`. Reference them in CLI notes (e.g., `$CLI run:events … --note "uploaded part7_spec.md"` currently not supported; instead, add an `artifact` journal entry by running the documented helper script if needed, but prefer CLI notes once available).
+- Provide an updated `process.md` for every `main.js` you craft (Mermaid diagrams have been retired, so no additional `.mermaid.md` artifact is needed).
+
+---
+
+## 7. Troubleshooting
+
+| Issue | Resolution |
+| --- | --- |
+| CLI missing / npx fails | Verify Node/npm are on PATH and retry `npx -y @a5c-ai/babysitter-sdk --version` |
+| CLI command fails (bad args) | Run `$CLI help` or `$CLI <command> --help` and fix flags |
+| Need alternate runs dir | Pass `--runs-dir <path>` on every CLI invocation |
+| Want JSON output | Append `--json` (many commands support it) |
+| Need to view CLI env | `env | grep BABYSITTER` |
+
+If a CLI command crashes mid-iteration, capture the stderr, add a note to the run, and re-run `run:step` once fixed.
+
+---
+
+## 8. Next-action execution
+
+When `code/main.js` or the CLI orchestration indicates a next action, execute it
+immediately and record outputs through the CLI-driven workflow. Avoid any
+function-template or agent-runner indirection.
+
+---
+
+## 9. Example session
+
+```bash
+CLI="npx -y @a5c-ai/babysitter-sdk"
+
+# Start work on a new request
+$CLI run:create --process-id dev/project --entry .a5c/processes/... --inputs ./inputs.json
+# => runId=run-20260114-101500-dev-project
+
+# Review latest instructions
+$CLI run:status .a5c/runs/run-20260114-101500-dev-project
+$CLI run:events .a5c/runs/run-20260114-101500-dev-project --limit 20 --reverse
+
+# Drive the next iteration
+$CLI run:continue .a5c/runs/run-20260114-101500-dev-project --auto-node-tasks --auto-node-max 3
+
+# List and run pending tasks if needed
+$CLI task:list .a5c/runs/run-20260114-101500-dev-project --pending
+$CLI task:run  .a5c/runs/run-20260114-101500-dev-project ef-node-123 --dry-run
+
+# Resume after breakpoint release + feedback
+$CLI run:continue .a5c/runs/run-20260114-101500-dev-project
+```
+
+Use this pattern anytime the user says “babysit this run” or “orchestrate via babysitter.” Keep the process deterministic by staying inside the CLI wherever it offers a command; only fall back to manual scripts when the CLI surface truly lacks a capability.

package/skills/babysitter-score/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: babysitter-score
+allowed-tools: Bash(*) Read Write
+description: Executes the next CLI-orchestrated action when a score step is requested.
+metadata:
+  author: a5c-ai
+  version: "1.0"
+---
+
+# babysitter-score
+
+You are a next-action executor. The CLI orchestration output is the source of
+truth for what to do next.
+
+## Task
+Execute the next action described by the CLI orchestration output. Treat any
+inputs you receive as instructions for that next action.
+
+## Constraints
+- Make the smallest correct change set.
+- Follow any `AGENTS.md` instructions in scope.
+- Prefer adding a self-contained demo or runnable artifact when applicable.
+- If there are tests that are cheap and relevant, run them and report results.
+- Do not invent new steps beyond the CLI-provided action.
+
+## Deliverable
+- Apply changes directly to the working tree.
+- Write a short work summary to stdout:
+  - What changed (files)
+  - Why
+  - How to run / verify
+  - Commands run (if any) and results
+
+## Output
+Return a summary of the work and files touched as the final message.