{
  "id": "page:docs-agent-reference-command-surfaces",
  "_kind": "Page",
  "_file": "wiki/docs/agent-reference/command-surfaces.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-reference/command-surfaces.md",
    "sourceKind": "repo-docs",
    "title": "Command Surfaces",
    "displayName": "Command Surfaces",
    "slug": "docs/agent-reference/command-surfaces",
    "articlePath": "wiki/docs/agent-reference/command-surfaces.md",
    "article": "\n# Command Surfaces\n\nThis page is the concise command map for contributors and coding agents. It is intentionally grouped by surface so `AGENTS.md` and `CLAUDE.md` do not need to inline large command dumps.\n\n## Core CLI: `babysitter`\n\nThe `babysitter` binary is shipped by [`@a5c-ai/babysitter`](../../packages/babysitter/package.json) and [`@a5c-ai/babysitter-sdk`](../../packages/babysitter-sdk/package.json). The command families currently registered in the repo source live in [`packages/babysitter-sdk/src/cli/main/program.ts`](../../packages/babysitter-sdk/src/cli/main/program.ts).\n\n### Agent-facing help\n\n`babysitter --help` is the automation surface. Its usage text is generated from [`packages/babysitter-sdk/src/cli/main/usage.ts`](../../packages/babysitter-sdk/src/cli/main/usage.ts) and centers on:\n\n- `run:*` and `task:*` for deterministic replay loops (includes `run:assign-process` for attaching a process to a bare run)\n- `session:*` for session binding and iteration guards\n- `skill:discover`\n- `process-library:active`\n- `profile:*`\n- `instructions:babysit-skill`\n- `harness:install` and `harness:install-plugin`\n\n### Human-facing help\n\n`babysitter --help-human` is the operator surface. It adds:\n\n- `log`, `hook:*`, `compress-output`\n- `skill:fetch-remote`\n- `process-library:clone|update|use`\n- `plugin:*`\n- `tokens:stats`\n- `compression:*`\n- `harness:discover|list`\n- `instructions:process-create|orchestrate|breakpoint-handling`\n- `breakpoint:*`\n- `health`, `configure`, `version`\n\n## Product CLI: `genty`\n\nThe product CLI implementation lives in [`@a5c-ai/genty`](../../packages/genty/package.json) and is exposed as `genty`.\n\nUse `genty call` for new runtime orchestration examples. The legacy `babysitter harness:call` alias has been removed and must not appear in new tests or docs.\n\nSetup remains on the core CLI through `babysitter harness:install` and `babysitter harness:install-plugin`.\n\nUse it for human-invoked orchestration sessions and runtime services:\n\n- `create-run`, `call`, `yolo`, `plan`, `forever`\n- `resume-run`, `resume`\n- `retrospect`, `cleanup`, `assimilate`, `doctor`, `contrib`\n- `anycli`, `session-history`\n- `observe`, `tui`\n- `daemon:*`, `cost:stats`, `start-server`\n- `discover`, `list`, `invoke`\n\n## External Agent Dispatch\n\nExternal agent tasks start as normal `ctx.task()` effects. The difference is the\nagent routing hint: `agent.responderType: \"agent\"` plus a required `adapter`.\nDuring orchestration, tasks-adapter chooses the responder backend. Internal\nresponders continue through the normal agent-core path, human responders use the\nbreakpoint path, and agent responders route to `AgentMuxResponderBackend`, which\nuses adapters and the lower-level `adapterBridge` integration.\n\nThe command surfaces involved are split by responsibility:\n\n| Surface | Use |\n| --- | --- |\n| `babysitter run:create`, `run:iterate`, `task:list`, `task:post` | Create and replay the run, inspect pending effects, and post resolved task results. |\n| `babysitter process-library:active`, `skill:discover`, `profile:*` | Gather process-authoring context, available skills, and user/project preferences before deciding whether an external responder is appropriate. |\n| `genty discover`, `genty list`, `genty invoke` | Human-facing discovery and invocation surface for available runtime agents and services. |\n| `adapters doctor`, `adapters launch`, `adapters auth`, `adapters install` | adapters checks and adapter operations. See the adapters reference for the exact CLI flags. |\n\nTroubleshooting common external agent failures:\n\n| Scenario | Expected behavior |\n| --- | --- |\n| adapters is missing | If the task explicitly allows internal fallback, route internally; otherwise fail the task with an unavailable adapters error. |\n| Adapter is missing | Fail with an adapter-not-installed message and install guidance for the selected adapter. |\n| Adapter is unauthenticated | Fail with an authentication message and run the adapter auth flow before retrying. |\n| Task times out | Fail the task with timeout details; include partial output only when the responder backend provides it. |\n| Adapter process crashes | Fail the task with the adapter stderr or exit details so the next iteration can diagnose the crash. |\n| Fallback is disabled | Do not silently switch to an internal agent. The failed external responder is part of the task result. |\n\nOlder design docs may still say `agent.external: true`,\n`fallbackToInternal`, or direct `adapterBridge` dispatch. The current contributor\nsurface should describe the tasks-adapter responder route and use\n`responderType: \"agent\"` in new examples.\n\n## Runs Directory Defaults\n\nThe repo source now treats global runs storage as the default:\n\n- default scope: `~/.a5c/runs`\n- repo scope: `<repo>/.a5c/runs` when `BABYSITTER_RUNS_SCOPE=repo`\n- explicit override: `BABYSITTER_RUNS_DIR` or `--runs-dir`\n\nThe implementation lives in [`packages/babysitter-sdk/src/config/runs.ts`](../../packages/babysitter-sdk/src/config/runs.ts) and the default config in [`packages/babysitter-sdk/src/config/defaults.ts`](../../packages/babysitter-sdk/src/config/defaults.ts).\n\nWhen reading existing runs, the SDK also probes repo-local `.a5c/runs` for backward compatibility.\n\n## Plugin Commands\n\nPlugin concepts are covered in [Plugins Overview](../plugins.md). The dedicated command reference is [Plugin CLI Reference](../plugins/cli-reference.md).\n\nOne current implementation detail worth remembering: `plugin:install`, `plugin:update`, and `plugin:configure` can auto-resolve the marketplace when `--marketplace-name` is omitted, as implemented in [`packages/babysitter-sdk/src/cli/commands/plugin/packageCommands.ts`](../../packages/babysitter-sdk/src/cli/commands/plugin/packageCommands.ts).\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-reference",
      "to": "page:docs-agent-reference-command-surfaces",
      "kind": "contains_page"
    }
  ]
}