{
  "id": "page:docs-v6-spec-and-roadmap-v6-1-graph-alignment-tasks",
  "_kind": "Page",
  "_file": "wiki/docs/v6-spec-and-roadmap/v6-1/graph-alignment-tasks.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/v6-spec-and-roadmap/v6.1/graph-alignment-tasks.md",
    "sourceKind": "repo-docs",
    "title": "Graph Alignment Tasks — Make the Repo Match the Graph",
    "displayName": "Graph Alignment Tasks — Make the Repo Match the Graph",
    "slug": "docs/v6-spec-and-roadmap/v6-1/graph-alignment-tasks",
    "articlePath": "wiki/docs/v6-spec-and-roadmap/v6.1/graph-alignment-tasks.md",
    "article": "\n# Graph Alignment Tasks — Make the Repo Match the Graph\n\nThe Atlas graph is the source of truth. This document lists every task needed to make the repo's package names, structure, and capabilities match the 9 canonical muxes, 14 stack layers, and the agent-stack node kinds defined in the graph.\n\n## Guiding Principle\n\nWhen a package name doesn't match the graph → rename the package.\nWhen a graph concept has no package → create one or assign ownership.\nWhen a package implements something not in the graph → update the graph or remove the code.\n\n---\n\n## Phase 1: Package Renames\n\nMake npm package names and directory names match graph adapter names.\n\n### 1.1 extensions-adapter → extensions-adapter\n\n| Aspect | Current | Target |\n|--------|---------|--------|\n| Graph adapter | `adapter:extensions-adapter` | — |\n| npm name | `@a5c-ai/extensions-adapter` | `@a5c-ai/extensions-adapter` |\n| Directory | `packages/extensions-adapter/` | `packages/extensions-adapter/` |\n| Binary | (none) | (none) |\n\n**Tasks:**\n- [ ] Rename directory `packages/extensions-adapter/` → `packages/extensions-adapter/`\n- [ ] Update `package.json` name to `@a5c-ai/extensions-adapter`\n- [ ] Update all workspace references in root `package.json`\n- [ ] Update all import paths across the monorepo\n- [ ] Update CI workflows referencing the old name\n- [ ] Publish `@a5c-ai/extensions-adapter` and deprecate `@a5c-ai/extensions-adapter` on npm\n- [ ] Update graph YAML to reference new package name in SourceRef nodes\n\n### 1.2 tasks-adapter → tasks-adapter\n\n| Aspect | Current | Target |\n|--------|---------|--------|\n| Graph adapter | `adapter:tasks-adapter` | — |\n| npm name | `@a5c-ai/tasks-adapter` | `@a5c-ai/tasks-adapter` |\n| Directory | `packages/tasks-adapter/` | `packages/tasks-adapter/` |\n| Binary | `tasks-adapter` | `tasks-adapter` |\n\n**Tasks:**\n- [ ] Rename directory `packages/tasks-adapter/` → `packages/tasks-adapter/`\n- [ ] Update `package.json` name to `@a5c-ai/tasks-adapter`\n- [ ] Update binary name in package.json bin field\n- [ ] Update all workspace references\n- [ ] Update all import paths across the monorepo\n- [ ] Update CI workflows\n- [ ] Publish `@a5c-ai/tasks-adapter` and deprecate `@a5c-ai/tasks-adapter`\n- [ ] Update graph YAML SourceRef nodes\n\n### 1.3 adapters decomposition — align sub-packages to graph muxes\n\nThe graph defines 3 muxes inside what's currently the adapters monolith:\n- `agent-launch-adapter` (spawn/lifecycle)\n- `agent-comm-adapter` (event streaming)\n- `agent-config-adapter` (install/config/auth)\n\nCurrently these are split differently:\n- `agent-comm-adapter` = agent-comm-adapter + types\n- `adapters-cli` = agent-launch-adapter + agent-config-adapter + interaction\n- `adapters-adapters` = part of agent-config-adapter\n\n**Tasks:**\n- [ ] Extract `agent-launch-adapter` from `adapters-cli/src/commands/launch.ts` into `packages/adapters/launch/`\n  - npm: `@a5c-ai/launch-adapter`\n  - Owns: InvocationOptions, SpawnArgs, process lifecycle, signal propagation, retry\n- [ ] Extract `agent-config-adapter` from `adapters-cli/src/commands/install*.ts` + `adapters-adapters/` into `packages/adapters/config/`\n  - npm: `@a5c-ai/config-adapter`\n  - Owns: install, uninstall, update, detect, auth verification per adapter\n- [ ] Rename `agent-comm-adapter` to `agent-comm-adapter`\n  - npm: `@a5c-ai/comm-adapter`\n  - Owns: event streaming, client, canonical event schema\n- [ ] Keep `adapters-cli` as the composition CLI (`adapters`) that wires the 3 muxes together\n- [ ] Keep `adapters-gateway`, `adapters-tui`, `adapters-ui`, `adapters-webui` as presentation packages (they consume muxes)\n\n### 1.4 sdk → orchestration-adapter (or keep as-is)\n\nThe graph layer is \"Orchestration\" and the concept of \"session-storage-adapter\" lives inside the SDK.\n\n**Decision needed:** The SDK is intentionally monolithic per v6.0. Splitting it would be a v7 concern. For v6.1, annotate the SDK with its graph layer ownership rather than renaming.\n\n**Tasks:**\n- [ ] Add `\"atlas\": { \"layers\": [\"L13-orchestration\"], \"muxes\": [\"session-storage-adapter\"] }` to sdk `package.json`\n- [ ] Extract session-storage-adapter interface (not implementation) for documentation\n\n### 1.5 agent-platform — align to graph\n\nGraph has `AgentRuntimeImpl` and `AgentPlatformImpl`. agent-platform implements both.\n\n**Tasks:**\n- [ ] Add `\"atlas\": { \"layers\": [\"L5-agent-runtime\", \"L6-agent-platform\"], \"nodeKinds\": [\"AgentRuntimeImpl\"] }` to package.json\n- [ ] Document the seam between agent-runtime (L5) and agent-platform (L6) concerns within the package\n\n---\n\n## Phase 2: Missing Packages\n\nCreate packages for graph muxes that have no implementation.\n\n### 2.1 Create tools-adapter package\n\nGraph: `adapter:tools-adapter` — CLI→MCP gateway, tool-level hooks, tool dispatch policies.\n\nCurrently scattered across:\n- `babysitter-sdk/src/mcp/` (MCP server)\n- `agent-platform/` (tool dispatch)\n- `agent-comm-adapter/` (tool call events)\n\n**Tasks:**\n- [ ] Create `packages/tools-adapter/` with npm name `@a5c-ai/tools-adapter`\n- [ ] Define `ToolDescriptor` interface (from graph node kind)\n- [ ] Implement tool schema translation: MCP ↔ OpenAI function calling ↔ Anthropic tools ↔ Google functionDeclarations\n- [ ] Implement `ToolDispatchPolicy` (from graph): routing rules for which tool server handles which tool\n- [ ] Move MCP serving surface from babysitter-sdk to tools-adapter (or re-export)\n- [ ] Wire hooks-adapter PreToolUse/PostToolUse through tools-adapter\n\n### 2.2 Formalize agent-comm-adapter event schema\n\nGraph defines this as a adapter but there's no formal schema.\n\n**Tasks:**\n- [ ] Define canonical event types in TypeScript: `AgentEvent`, `ToolCallEvent`, `MessageEvent`, `SessionEvent`, `ErrorEvent`\n- [ ] Create JSON Schema for each event type\n- [ ] Validate adapter output against schema in tests\n- [ ] Publish schema as part of `@a5c-ai/comm-adapter` package\n\n---\n\n## Phase 3: Missing Functionality\n\nImplement graph-defined capabilities that don't exist in code.\n\n### 3.1 agent-launch-adapter: 9-state invocation lifecycle\n\nGraph defines: spawned → running → paused → interrupted → aborted | timed-out | completed | crashed | killed.\n\nCurrent: spawned → running → completed | crashed.\n\n**Tasks:**\n- [ ] Define `InvocationState` enum with all 9 states\n- [ ] Implement state machine with valid transitions\n- [ ] Add `pause()` — send SIGSTOP or equivalent\n- [ ] Add `resume()` — send SIGCONT\n- [ ] Add `interrupt()` — graceful stop with timeout\n- [ ] Add lifecycle hooks: `onSpawnError`, `onTimeout`, `onProcessExit`, `shouldRetry`\n- [ ] Implement retry policy (exponential backoff, max retries)\n- [ ] Add min-version enforcement (semver gate against AgentVersion)\n\n### 3.2 transport-adapter: complete codec architecture\n\nGraph: \"Adding a new native impl is a Catalog edit.\"\n\n**Tasks:**\n- [ ] Define `TransportCodec` interface: decode request, encode response, encode stream chunk\n- [ ] Implement per-protocol codecs: anthropic, openai-chat, openai-responses, google, bedrock\n- [ ] Tool schema translation in each codec\n- [ ] Cost/usage normalization: input_tokens ↔ prompt_tokens ↔ promptTokenCount\n- [ ] Make codec selection data-driven from atlas graph `TransportDescriptor` records\n- [ ] Streaming codec for SSE/NDJSON translation\n\n### 3.3 agent-config-adapter: structured install results\n\n**Tasks:**\n- [ ] Return structured error from install failures (not just `installed: false`)\n- [ ] Include npm stderr, exit code, and suggested fix in the result\n- [ ] Add auth verification step per adapter (check API key validity)\n- [ ] Add min-version check post-install\n\n### 3.4 session-storage-adapter: backend abstraction\n\nGraph defines this as a adapter (multiple backends). Current: filesystem only.\n\n**Tasks:**\n- [ ] Define `SessionStorageBackend` interface: read, write, list, delete\n- [ ] Implement `FileSystemBackend` (current behavior)\n- [ ] Define `CloudBackend` interface (S3/GCS/Azure Blob)\n- [ ] Make backend selection configurable via environment or config\n\n---\n\n## Phase 4: Graph Updates\n\nUpdate the atlas graph to reflect actual code structure.\n\n### 4.1 Add adapters internal decomposition to graph\n\n**Tasks:**\n- [ ] Add `AgentCoreImpl` record for agent-comm-adapter / agent-comm-adapter\n- [ ] Add `AgentRuntimeImpl` record for adapters-cli (as composition runtime)\n- [ ] Link Presentation records to their implementing packages (adapters-tui, adapters-ui, adapters-webui)\n- [ ] Add SourceRef nodes for each adapters sub-package\n\n### 4.2 Move misplaced node kinds to correct clusters\n\n**Tasks:**\n- [ ] Move `ProviderTranslation` from extensions → compute cluster\n- [ ] Move `TransportRuntime` from extensions → compute cluster\n- [ ] Move `AdapterModel` from extensions → capabilities-and-models cluster\n- [ ] Verify all node kinds are in their architectural layer's cluster\n\n### 4.3 Add layer annotations to graph\n\n**Tasks:**\n- [ ] For each adapter record, add `implementedBy` edge to the package SourceRef\n- [ ] For each AgentProduct, add `decomposedInto` edges to its sub-packages\n- [ ] Add `layer` metadata to each package SourceRef node\n\n---\n\n## Phase 5: Package Metadata\n\nLow-effort tasks that improve discoverability.\n\n**Tasks:**\n- [ ] Add `\"atlas\"` field to every package.json: `{ \"layers\": [...], \"muxes\": [...], \"nodeKinds\": [...] }`\n- [ ] Add graph layer reference to every package README header\n- [ ] Add \"Canonical adapter\" section to each adapter package README linking to the atlas record\n- [ ] Update CLAUDE.md with graph-aligned package descriptions\n\n---\n\n## Execution Order\n\n```\nPhase 1.1 (extensions-adapter rename)\nPhase 1.2 (tasks-adapter rename)\n  ↓\nPhase 2.1 (tools-adapter create) — can start in parallel with renames\nPhase 2.2 (event schema) — can start in parallel\n  ↓\nPhase 1.3 (adapters decomposition) — biggest refactor, do after renames settle\n  ↓\nPhase 3.1 (9-state lifecycle) — depends on agent-launch-adapter extraction\nPhase 3.2 (codec architecture) — independent\nPhase 3.3 (install results) — independent\nPhase 3.4 (session backend) — independent\n  ↓\nPhase 4 (graph updates) — do alongside each code change\nPhase 5 (metadata) — do last, sweep pass\n```\n\n## Estimated Effort\n\n| Phase | Tasks | Effort | Risk |\n|-------|-------|--------|------|\n| 1.1 extensions-adapter rename | 7 | Medium | Low (rename + deprecate) |\n| 1.2 tasks-adapter rename | 8 | Medium | Low |\n| 1.3 adapters decomposition | 5 | **Large** | Medium (API surface changes) |\n| 1.4 SDK annotation | 2 | Small | None |\n| 1.5 agent-platform annotation | 2 | Small | None |\n| 2.1 tools-adapter package | 6 | **Large** | Medium (new abstraction) |\n| 2.2 event schema | 4 | Medium | Low |\n| 3.1 9-state lifecycle | 8 | **Large** | High (runtime behavior change) |\n| 3.2 codec architecture | 6 | **Large** | Medium |\n| 3.3 install results | 4 | Small | Low |\n| 3.4 session backend | 4 | Medium | Low |\n| 4.x graph updates | 6 | Small | None |\n| 5.x metadata | 4 | Small | None |\n| **Total** | **66** | | |\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-v6-spec-and-roadmap-v6-1",
      "to": "page:docs-v6-spec-and-roadmap-v6-1-graph-alignment-tasks",
      "kind": "contains_page"
    }
  ]
}