inkos/docs/plans/2026-04-10-interaction-create-export-runtime.md

Interaction Create/Export Runtime Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Finish the remaining shared interaction-layer work by wiring create_book and export_book into the shared runtime and moving Studio's create/export flows onto the same execution path.

Architecture: Keep the existing natural-language interaction path for chat/TUI/OpenClaw, but add a structured interaction entrypoint for UI-driven actions. Shared runtime tools will own create/export behavior so CLI, Studio, and external agents can reuse the same capability surface.

Tech Stack: TypeScript, Vitest, Hono, Commander, InkOS core pipeline/session tooling.

---

Task 1: Add failing core tests for create/export runtime behavior

Files:

• Modify: packages/core/src/__tests__/interaction-runtime.test.ts
• Modify: packages/core/src/__tests__/project-interaction.test.ts

Step 1: Write failing tests

• Add a runtime test proving create_book calls a new createBook tool, binds the created book, and returns its summary text.
• Add a runtime test proving export_book calls a new exportBook tool with format/approved-only options and returns export metadata text.
• Add a project-control test proving structured interaction requests persist session updates for create_book.

Step 2: Run tests to verify they fail

Run:

pnpm --dir packages/core exec vitest run \
  src/__tests__/interaction-runtime.test.ts \
  src/__tests__/project-interaction.test.ts

Expected: failing tests due to missing runtime tool methods / structured request helper.

Task 2: Implement shared create/export runtime support

Files:

• Modify: packages/core/src/interaction/intents.ts
• Modify: packages/core/src/interaction/runtime.ts
• Modify: packages/core/src/interaction/project-control.ts
• Modify: packages/core/src/interaction/project-tools.ts

Step 1: Extend interaction request/runtime contracts

• Add structured fields for create/export:
  • title
  • genre
  • platform
  • chapterWordCount
  • targetChapters
  • format
  • approvedOnly
  • outputPath
• Add runtime tool methods:
  • createBook
  • exportBook

Step 2: Implement structured project interaction helper

• Add processProjectInteractionRequest(...) alongside the existing natural-language helper.
• It should:
  • load session
  • optionally bind activeBookId
  • execute runInteractionRequest
  • persist the updated session

Step 3: Implement create/export tool behavior

• createBook:
  • derive a book config
  • call PipelineRunner.initBook
  • return interaction metadata with responseText
• exportBook:
  • centralize the existing CLI export logic into the shared tool
  • return output path / exported chapter count in interaction metadata

Step 4: Run tests

Run:

pnpm --dir packages/core exec vitest run \
  src/__tests__/interaction-runtime.test.ts \
  src/__tests__/project-interaction.test.ts

Expected: PASS.

Task 3: Add CLI routing/tests for shared create/export

Files:

• Modify: packages/core/src/interaction/nl-router.ts
• Modify: packages/core/src/__tests__/interaction-nl-router.test.ts
• Modify: packages/cli/src/__tests__/interact-command.test.ts

Step 1: Write failing tests

• Add NL routing coverage for:
  • /new <title>
  • /export
  • /export md
• Add interact command coverage for structured/shared export output where useful.

Step 2: Implement minimal routing

• Route slash commands into create_book / export_book.
• Keep this scoped to explicit commands, not full ideation.

Step 3: Run tests

Run:

pnpm --dir packages/core exec vitest run src/__tests__/interaction-nl-router.test.ts
pnpm --dir packages/cli exec vitest run src/__tests__/interact-command.test.ts

Expected: PASS.

Task 4: Move Studio create/export endpoints onto shared interaction execution

Files:

• Modify: packages/studio/src/api/server.ts
• Modify: packages/studio/src/api/server.test.ts

Step 1: Write failing tests

• Add server tests proving:
  • /api/books/create routes through shared structured interaction execution
  • /api/books/:id/export-save routes through shared structured interaction execution

Step 2: Implement endpoint changes

• Use the same shared interaction tools built from pipeline + state.
• Replace direct initBook / custom export-save logic with calls to the shared structured helper.
• Preserve existing response shape expected by the Studio UI.

Step 3: Run tests

Run:

pnpm --dir packages/studio exec vitest run src/api/server.test.ts

Expected: PASS.

Task 5: Final verification

Files:

• No new files

Step 1: Run focused test/build suite

pnpm --dir packages/core exec vitest run \
  src/__tests__/interaction-runtime.test.ts \
  src/__tests__/project-interaction.test.ts \
  src/__tests__/interaction-nl-router.test.ts
pnpm --dir packages/cli exec vitest run src/__tests__/interact-command.test.ts
pnpm --dir packages/studio exec vitest run src/api/server.test.ts
pnpm --dir packages/core run build
pnpm --dir packages/cli run build
pnpm --dir packages/studio run build

Expected: all green.

Step 2: Commit

git add packages/core/src/interaction packages/core/src/__tests__ \
  packages/cli/src/__tests__/interact-command.test.ts \
  packages/studio/src/api/server.ts packages/studio/src/api/server.test.ts \
  docs/plans/2026-04-10-interaction-create-export-runtime.md
git commit -m "feat(interaction): add shared create and export flows"