{
  "id": "page:docs-user-guide-ecosystem-babysitter-sdk",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/ecosystem/babysitter-sdk.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/ecosystem/babysitter-sdk.md",
    "sourceKind": "repo-docs",
    "title": "babysitter-sdk — the core engine",
    "displayName": "babysitter-sdk — the core engine",
    "slug": "docs/user-guide/ecosystem/babysitter-sdk",
    "articlePath": "wiki/docs/user-guide/ecosystem/babysitter-sdk.md",
    "article": "\n[Docs](../index.md) › [Ecosystem](./overview.md) › babysitter-sdk\n\n# babysitter-sdk — the core engine\n\n**Package:** `@a5c-ai/babysitter-sdk` · **Metapackage:** `@a5c-ai/babysitter` · **Version:** 6.0.0 · **Maturity:** GA / core\n\n**`babysitter-sdk` is the event-sourced orchestration engine at the center of the whole ecosystem. It is what makes Babysitter deterministic and obedient: your workflow is real code, the orchestrator can only do what that code permits, and every step is recorded in an immutable journal.**\n\n---\n\n## On this page\n\n- [What it is](#what-it-is)\n- [What it contains](#what-it-contains)\n- [The metapackage](#the-metapackage)\n- [Who depends on it](#who-depends-on-it)\n- [A minimal example](#a-minimal-example)\n- [Next steps](#next-steps)\n\n---\n\n## What it is\n\nThe SDK is described in its own package as \"storage and run-registry primitives for event-sourced babysitter workflows.\" In practice it is both the **core library** and the **implementation behind the core CLI**.\n\nThe defining behaviors:\n\n- **Process as code.** A process is an `async function process(inputs, ctx)`. The orchestrator executes only what that function asks for — there is no out-of-band agency.\n- **Event sourcing.** State lives as an append-only sequence of events in an immutable journal under `~/.a5c/runs/`. The current state is a replay of those events, which gives you **deterministic replay** and **resume from any point**.\n- **Mandatory stop + gate enforcement.** After each step the engine stops, asks the process what is permitted next, and either permits the next task or halts until a gate passes. This is the obedience mechanism — *gates block progression; they are not suggestions.*\n\n---\n\n## What it contains\n\n| Piece | Role |\n|-------|------|\n| `defineTask` | The primitive for declaring a durable unit of work in a process. |\n| Effect / journal engine | Records every effect request and resolution as journal events; reconstructs state by replay. |\n| Built-in **Pi execution engine** | Powers the \"internal\" / headless harness used by `genty call --harness internal`. |\n| 4-layer token compression subsystem | Reduces context by roughly 50–67%; hooks are auto-registered. |\n\n**Entrypoints (bins):** `babysitter`, `babysitter-sdk`, `babysitter-mcp-server`.\n\n---\n\n## The metapackage\n\n`@a5c-ai/babysitter` is the **metapackage** — \"metapackage for installing all babysitter npm packages.\" It is the recommended human-facing install and ships the `babysitter` bin shim. Most users install this rather than reaching for `babysitter-sdk` directly:\n\n```bash\nnpm install -g @a5c-ai/babysitter\nbabysitter --version\n```\n\nReach for `@a5c-ai/babysitter-sdk` directly only when you are **authoring processes or embedding Babysitter in your own code**:\n\n```bash\nnpm install @a5c-ai/babysitter-sdk\n```\n\n---\n\n## Who depends on it\n\nEffectively everything: every Babysitter process, the `babysitter` CLI, and the adapters, hooks, and genty layers all consume the SDK. Atlas supplies metadata *to* the runtime; the SDK is the runtime.\n\n---\n\n## A minimal example\n\nA process is ordinary code. The orchestrator runs the tasks you declare, in the order your code allows, stopping after each one:\n\n```javascript\n// process.js — illustrative shape\nasync function process(inputs, ctx) {\n  const research = await ctx.task('research', { prompt: `Analyze ${inputs.repo}` });\n\n  const impl = await ctx.task('implement', {\n    prompt: 'Implement the change',\n    dependsOn: [research],\n  });\n\n  // A gate is just code logic — it blocks progression until satisfied.\n  let score = await ctx.task('score', { prompt: 'Score the result 0-100' });\n  if (score < 80) {\n    await ctx.task('refine', { prompt: 'Improve until the score clears the gate' });\n  }\n\n  // Park for human approval — durable, survives restarts (tasks/Breakpoints Adapter).\n  await ctx.breakpoint('approve-release', { summary: impl.summary });\n  return { done: true };\n}\n```\n\nEvery `ctx.task`, `ctx.breakpoint`, and decision above becomes journal events under `~/.a5c/runs/<runId>/`. The quality gate (`score < 80`) is just one piece of code logic — one capability, not the headline.\n\n---\n\n## Next steps\n\n- **See how the engine connects to everything else:** [Architecture & How It Fits Together](../architecture.md)\n- **Run it:** [Installation](../getting-started/installation.md) → [Quickstart](../getting-started/quickstart.md)\n- **Author processes:** [Process Definitions](../features/process-definitions.md) and the [Custom Process tutorial](../tutorials/intermediate-custom-process.md)\n- **Understand the model:** [Two-Loops Architecture](../features/two-loops-architecture.md) and [Journal System](../features/journal-system.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-babysitter-sdk",
      "kind": "contains_page"
    }
  ]
}