|
|
@@ -1,559 +0,0 @@
|
|
|
-# Interaction Control Layer Design
|
|
|
-
|
|
|
-## Goal
|
|
|
-
|
|
|
-Build a shared interaction control layer for InkOS so that `TUI` and `Studio` stop acting like separate products and instead become two shells over the same writing control brain.
|
|
|
-
|
|
|
-This layer must let users:
|
|
|
-- create a book through natural conversation
|
|
|
-- continue an active book inside a project workspace
|
|
|
-- see exactly what the system is doing right now
|
|
|
-- intervene safely on chapters, truth files, and direction
|
|
|
-- choose how much autonomy the system has
|
|
|
-
|
|
|
-## Why This Exists
|
|
|
-
|
|
|
-Current InkOS has strong execution primitives but weak control ergonomics.
|
|
|
-
|
|
|
-Today the user experience is split across:
|
|
|
-- CLI commands
|
|
|
-- Studio buttons and pages
|
|
|
-- a shallow `/api/agent` chat box
|
|
|
-- daemon logs
|
|
|
-- direct truth-file editing
|
|
|
-
|
|
|
-That produces the exact failures users complain about:
|
|
|
-- the system keeps writing when the user expected it to stop
|
|
|
-- the user cannot tell what stage the system is in
|
|
|
-- edits to truth files do not feel authoritative
|
|
|
-- rejecting or revising a chapter does not feel like part of one coherent flow
|
|
|
-- Studio chat does not hold enough session context to feel like a real assistant
|
|
|
-
|
|
|
-The solution is not “more buttons” and not “just add a TUI”. The solution is a single interaction control layer that owns:
|
|
|
-- session context
|
|
|
-- book binding
|
|
|
-- autonomy policy
|
|
|
-- natural-language intent routing
|
|
|
-- execution status
|
|
|
-- human edit transactions
|
|
|
-
|
|
|
-## Product Principles
|
|
|
-
|
|
|
-### 1. Project-first
|
|
|
-
|
|
|
-InkOS should behave like a writing version of Coding CLI.
|
|
|
-
|
|
|
-The user opens a project directory and runs:
|
|
|
-
|
|
|
-```bash
|
|
|
-inkos
|
|
|
-```
|
|
|
-
|
|
|
-The current working directory is the project context. The control layer restores:
|
|
|
-- project config
|
|
|
-- books in the project
|
|
|
-- active book, if one exists
|
|
|
-- current running task, if one exists
|
|
|
-
|
|
|
-The user should not be thrown into a global dashboard first.
|
|
|
-
|
|
|
-### 2. Conversation-first, not form-first
|
|
|
-
|
|
|
-When there is no active task, the interface should be quiet.
|
|
|
-
|
|
|
-It should not dump a questionnaire. It should wait for the user to speak first. The system then gradually narrows the task by asking only the most important next question.
|
|
|
-
|
|
|
-Bad:
|
|
|
-- “Choose language / genre / length / mode / trend scanning / source mode”
|
|
|
-
|
|
|
-Good:
|
|
|
-- user: “I want to write a cold urban mystery”
|
|
|
-- system: “I’ll hold it as a cold urban mystery. Do you want something long-running, or something that can close within about 10-20 chapters?”
|
|
|
-
|
|
|
-### 3. Status must stay visible at all times
|
|
|
-
|
|
|
-The user must always be able to answer:
|
|
|
-- which book is active?
|
|
|
-- what chapter is being worked on?
|
|
|
-- which stage is running right now?
|
|
|
-- why is the system waiting or blocked?
|
|
|
-
|
|
|
-### 4. Human edits are transactions, not raw file writes
|
|
|
-
|
|
|
-Users must be able to change:
|
|
|
-- a person name
|
|
|
-- a chapter
|
|
|
-- a paragraph
|
|
|
-- `current_focus`
|
|
|
-- `author_intent`
|
|
|
-- truth files
|
|
|
-
|
|
|
-But these changes cannot be “write to one file and hope the rest follows”. The control layer must route human edits through a consistency-preserving edit controller.
|
|
|
-
|
|
|
-### 5. TUI and Studio share the same brain
|
|
|
-
|
|
|
-`TUI` and `Studio` may have different layouts, but they must share:
|
|
|
-- session model
|
|
|
-- intent routing
|
|
|
-- autonomy policy
|
|
|
-- control actions
|
|
|
-- execution status
|
|
|
-- pending decisions
|
|
|
-
|
|
|
-No duplicate business logic in both shells.
|
|
|
-
|
|
|
-## User Journeys
|
|
|
-
|
|
|
-### Journey A: New book from a vague idea
|
|
|
-
|
|
|
-1. User runs `inkos` inside a project.
|
|
|
-2. No active book exists.
|
|
|
-3. User types: “I want to write a quiet harbor mystery.”
|
|
|
-4. The control layer opens a book-creation conversation.
|
|
|
-5. Through a few turns, the system gathers enough intent to draft:
|
|
|
- - title direction
|
|
|
- - genre
|
|
|
- - target scale
|
|
|
- - language
|
|
|
- - source mode: original / continuation / fanfic
|
|
|
- - autonomy preference
|
|
|
-6. System proposes a structured book draft.
|
|
|
-7. User confirms or adjusts.
|
|
|
-8. System runs foundation generation.
|
|
|
-9. If the autonomy policy allows, it proceeds into writing; otherwise it waits for outline review.
|
|
|
-
|
|
|
-### Journey B: Continue an active book
|
|
|
-
|
|
|
-1. User runs `inkos` in a project that already has books.
|
|
|
-2. The control layer restores the active book.
|
|
|
-3. The interface opens on that book’s current session.
|
|
|
-4. User types “continue”.
|
|
|
-5. Control layer maps that to `write_next`.
|
|
|
-6. Status stream shows:
|
|
|
- - planning
|
|
|
- - composing
|
|
|
- - writing
|
|
|
- - assessing
|
|
|
- - repairing
|
|
|
- - persisting
|
|
|
-7. If a stop condition is met, the task switches to `waiting_human`.
|
|
|
-
|
|
|
-### Journey C: Intervene on a chapter
|
|
|
-
|
|
|
-1. User types: “Rewrite chapter 3, but keep the ending reveal.”
|
|
|
-2. Control layer identifies:
|
|
|
- - action: `rewrite_chapter`
|
|
|
- - chapter: `3`
|
|
|
- - constraint: keep ending reveal
|
|
|
-3. It builds an edit transaction.
|
|
|
-4. Runtime executes rewrite + reanalysis + truth/state rebuild for affected scope.
|
|
|
-5. User sees diff, updated status, and any downstream invalidations.
|
|
|
-
|
|
|
-### Journey D: Fix authority confusion
|
|
|
-
|
|
|
-1. User types: “Why is the protagonist still called Lu Chen?”
|
|
|
-2. Control layer resolves authoritative sources:
|
|
|
- - story bible
|
|
|
- - current state
|
|
|
- - book rules
|
|
|
- - recent chapters
|
|
|
- - active entity state
|
|
|
-3. It explains which source currently wins.
|
|
|
-4. User can then say:
|
|
|
- - “Rename the protagonist to Lin Yan everywhere”
|
|
|
-5. Control layer opens an entity-level rename transaction instead of editing random files manually.
|
|
|
-
|
|
|
-## Architecture
|
|
|
-
|
|
|
-There should be one new subsystem spanning `core`, `cli`, and `studio`.
|
|
|
-
|
|
|
-### Layer 1: Interaction Core
|
|
|
-
|
|
|
-New `core` module family that owns conversation state and intent routing.
|
|
|
-
|
|
|
-Responsibilities:
|
|
|
-- maintain `InteractionSession`
|
|
|
-- bind current project and active book
|
|
|
-- classify user messages into intent types
|
|
|
-- ask follow-up questions when required
|
|
|
-- emit structured requests for execution
|
|
|
-
|
|
|
-This layer does not directly run writing logic.
|
|
|
-
|
|
|
-### Layer 2: Control Runtime
|
|
|
-
|
|
|
-Execution orchestrator for interaction requests.
|
|
|
-
|
|
|
-Responsibilities:
|
|
|
-- turn a request into an executable action plan
|
|
|
-- call existing pipeline capabilities
|
|
|
-- track stage transitions
|
|
|
-- publish execution events
|
|
|
-- manage waiting-human transitions
|
|
|
-
|
|
|
-This layer is the bridge between conversation and pipeline.
|
|
|
-
|
|
|
-### Layer 3: Execution Substrate
|
|
|
-
|
|
|
-Existing InkOS capabilities remain underneath:
|
|
|
-- `PipelineRunner`
|
|
|
-- `writer`
|
|
|
-- `review`
|
|
|
-- `repair-state`
|
|
|
-- truth file read/write
|
|
|
-- `scheduler`
|
|
|
-
|
|
|
-This design avoids rewriting the execution engine from scratch.
|
|
|
-
|
|
|
-### Layer 4: Shells
|
|
|
-
|
|
|
-Two shells sit above the same control layer:
|
|
|
-- `TUI`
|
|
|
-- `Studio`
|
|
|
-
|
|
|
-Both subscribe to the same session and status model.
|
|
|
-
|
|
|
-## Core Objects
|
|
|
-
|
|
|
-### `InteractionSession`
|
|
|
-
|
|
|
-Represents one project-scoped working conversation.
|
|
|
-
|
|
|
-Fields:
|
|
|
-- `sessionId`
|
|
|
-- `projectRoot`
|
|
|
-- `activeBookId?`
|
|
|
-- `activeChapterNumber?`
|
|
|
-- `messages`
|
|
|
-- `automationMode`
|
|
|
-- `pendingDecision?`
|
|
|
-- `currentExecution?`
|
|
|
-- `lastResolvedIntent?`
|
|
|
-
|
|
|
-### `AutomationMode`
|
|
|
-
|
|
|
-Three explicit modes:
|
|
|
-- `auto`
|
|
|
-- `semi`
|
|
|
-- `manual`
|
|
|
-
|
|
|
-Meaning:
|
|
|
-- `auto`: continue chapters automatically unless a true hard stop occurs
|
|
|
-- `semi`: user starts each chapter; chapter-internal loop stays automatic
|
|
|
-- `manual`: no autonomous progression; only explicit user commands run
|
|
|
-
|
|
|
-### `InteractionIntent`
|
|
|
-
|
|
|
-Normalized intent categories:
|
|
|
-- `create_book`
|
|
|
-- `select_book`
|
|
|
-- `continue_book`
|
|
|
-- `write_next`
|
|
|
-- `pause_book`
|
|
|
-- `resume_book`
|
|
|
-- `revise_chapter`
|
|
|
-- `rewrite_chapter`
|
|
|
-- `edit_truth`
|
|
|
-- `update_focus`
|
|
|
-- `update_author_intent`
|
|
|
-- `explain_status`
|
|
|
-- `explain_failure`
|
|
|
-- `export_book`
|
|
|
-- `switch_mode`
|
|
|
-
|
|
|
-### `InterventionRequest`
|
|
|
-
|
|
|
-The structured handoff from interaction core to runtime.
|
|
|
-
|
|
|
-Fields:
|
|
|
-- `intent`
|
|
|
-- `bookId`
|
|
|
-- `chapterNumber?`
|
|
|
-- `instruction?`
|
|
|
-- `truthFile?`
|
|
|
-- `modeOverride?`
|
|
|
-- `constraints`
|
|
|
-
|
|
|
-### `ExecutionStatus`
|
|
|
-
|
|
|
-Normalized, shell-friendly runtime state:
|
|
|
-- `idle`
|
|
|
-- `planning`
|
|
|
-- `composing`
|
|
|
-- `writing`
|
|
|
-- `assessing`
|
|
|
-- `repairing`
|
|
|
-- `persisting`
|
|
|
-- `waiting_human`
|
|
|
-- `blocked`
|
|
|
-- `completed`
|
|
|
-- `failed`
|
|
|
-
|
|
|
-### `PendingDecision`
|
|
|
-
|
|
|
-Represents a human decision that must be surfaced clearly.
|
|
|
-
|
|
|
-Examples:
|
|
|
-- approve current chapter before continuing
|
|
|
-- choose whether to rewrite or keep a chapter
|
|
|
-- resolve a truth authority conflict
|
|
|
-- confirm a project-level change
|
|
|
-
|
|
|
-## Edit Controller
|
|
|
-
|
|
|
-This is required. Without it, human intervention will keep poisoning consistency.
|
|
|
-
|
|
|
-### Why It Exists
|
|
|
-
|
|
|
-Users need to change:
|
|
|
-- names
|
|
|
-- chapters
|
|
|
-- paragraphs
|
|
|
-- direction
|
|
|
-- truth files
|
|
|
-
|
|
|
-Those changes can affect:
|
|
|
-- chapter text
|
|
|
-- current state
|
|
|
-- hook state
|
|
|
-- chapter summaries
|
|
|
-- future chapter assumptions
|
|
|
-
|
|
|
-So edits must be transactional.
|
|
|
-
|
|
|
-### Edit Types
|
|
|
-
|
|
|
-#### 1. Entity edits
|
|
|
-
|
|
|
-Examples:
|
|
|
-- rename protagonist
|
|
|
-- change a character attribute
|
|
|
-
|
|
|
-These are not text replacements. They must update the authoritative entity definition and then determine which downstream material must be rebuilt or flagged.
|
|
|
-
|
|
|
-#### 2. Chapter edits
|
|
|
-
|
|
|
-Examples:
|
|
|
-- rewrite chapter 3
|
|
|
-- revise chapter 5
|
|
|
-
|
|
|
-These rebuild chapter-derived truth outputs.
|
|
|
-
|
|
|
-#### 3. Local text edits
|
|
|
-
|
|
|
-Examples:
|
|
|
-- rewrite one paragraph
|
|
|
-- change the ending sentence
|
|
|
-
|
|
|
-These still require reanalysis of the affected chapter.
|
|
|
-
|
|
|
-#### 4. Direction/rule edits
|
|
|
-
|
|
|
-Examples:
|
|
|
-- update `current_focus`
|
|
|
-- update `author_intent`
|
|
|
-- edit `book_rules`
|
|
|
-- edit `volume_outline`
|
|
|
-
|
|
|
-These do not always require rewriting old chapters, but they must affect future planning deterministically.
|
|
|
-
|
|
|
-### Consistency Rules
|
|
|
-
|
|
|
-The edit controller should enforce:
|
|
|
-- chapter body is authoritative for “what happened in this chapter”
|
|
|
-- explicit user override is authoritative for user-owned fields
|
|
|
-- truth projections must be regenerated from edited content where applicable
|
|
|
-- downstream chapters may be marked stale if an upstream edit invalidates assumptions
|
|
|
-
|
|
|
-## Status, Events, and Interaction Feedback
|
|
|
-
|
|
|
-This system needs explicit event flow, not ad-hoc log strings.
|
|
|
-
|
|
|
-### Event Stream
|
|
|
-
|
|
|
-New shared execution events should include:
|
|
|
-- `session.bound`
|
|
|
-- `book.selected`
|
|
|
-- `task.started`
|
|
|
-- `task.progress`
|
|
|
-- `task.waiting_human`
|
|
|
-- `task.completed`
|
|
|
-- `task.failed`
|
|
|
-- `edit.applied`
|
|
|
-- `truth.updated`
|
|
|
-- `mode.changed`
|
|
|
-
|
|
|
-### Stage Visibility
|
|
|
-
|
|
|
-The user should always see:
|
|
|
-- active book
|
|
|
-- active chapter
|
|
|
-- stage
|
|
|
-- last successful action
|
|
|
-- current warning/block reason
|
|
|
-
|
|
|
-### Interaction Animation
|
|
|
-
|
|
|
-Animations should communicate process, not decoration.
|
|
|
-
|
|
|
-Required feedback:
|
|
|
-- active stage indicator
|
|
|
-- progress/event stream
|
|
|
-- visible `waiting_human` state
|
|
|
-- clear acceptance / rollback / rewrite transitions
|
|
|
-
|
|
|
-No decorative motion that does not improve process readability.
|
|
|
-
|
|
|
-## TUI Shape
|
|
|
-
|
|
|
-The `TUI` is the first shell, but it must be designed as a reusable client for the shared control layer.
|
|
|
-
|
|
|
-### Main layout
|
|
|
-
|
|
|
-- **Top status bar**
|
|
|
- - project
|
|
|
- - active book
|
|
|
- - automation mode
|
|
|
- - current stage
|
|
|
-- **Center conversation pane**
|
|
|
- - user messages
|
|
|
- - assistant responses
|
|
|
- - system event summaries
|
|
|
-- **Right or bottom process pane**
|
|
|
- - current task
|
|
|
- - last 10 events
|
|
|
- - pending decisions
|
|
|
- - current warnings
|
|
|
-- **Input row**
|
|
|
- - natural-language input
|
|
|
- - optional slash commands
|
|
|
-
|
|
|
-### Slash commands
|
|
|
-
|
|
|
-Support a small, stable command layer:
|
|
|
-- `/books`
|
|
|
-- `/open <book>`
|
|
|
-- `/new`
|
|
|
-- `/write`
|
|
|
-- `/pause`
|
|
|
-- `/resume`
|
|
|
-- `/mode`
|
|
|
-- `/revise`
|
|
|
-- `/rewrite`
|
|
|
-- `/focus`
|
|
|
-- `/intent`
|
|
|
-- `/truth`
|
|
|
-- `/export`
|
|
|
-- `/status`
|
|
|
-
|
|
|
-Natural language remains primary.
|
|
|
-
|
|
|
-## Studio Shape
|
|
|
-
|
|
|
-Studio should stop treating chat as a side widget over a page collection.
|
|
|
-
|
|
|
-Instead:
|
|
|
-- chat becomes a first-class surface over the same interaction core
|
|
|
-- book pages become supporting views, not the only control mechanism
|
|
|
-- daemon/log/truth views subscribe to the same execution event model
|
|
|
-
|
|
|
-Studio should preserve its richer visual editing affordances, but it should not own separate orchestration logic.
|
|
|
-
|
|
|
-## File and Module Boundaries
|
|
|
-
|
|
|
-This task is large, so file size control must be a design constraint from day one.
|
|
|
-
|
|
|
-### New core modules
|
|
|
-
|
|
|
-Create a focused module family, for example:
|
|
|
-
|
|
|
-- `packages/core/src/interaction/session.ts`
|
|
|
-- `packages/core/src/interaction/intents.ts`
|
|
|
-- `packages/core/src/interaction/router.ts`
|
|
|
-- `packages/core/src/interaction/runtime.ts`
|
|
|
-- `packages/core/src/interaction/events.ts`
|
|
|
-- `packages/core/src/interaction/modes.ts`
|
|
|
-- `packages/core/src/interaction/edit-controller.ts`
|
|
|
-- `packages/core/src/interaction/truth-authority.ts`
|
|
|
-
|
|
|
-### New CLI/TUI modules
|
|
|
-
|
|
|
-- `packages/cli/src/tui/app.tsx`
|
|
|
-- `packages/cli/src/tui/layout.tsx`
|
|
|
-- `packages/cli/src/tui/session-view.tsx`
|
|
|
-- `packages/cli/src/tui/status-pane.tsx`
|
|
|
-- `packages/cli/src/tui/input-bar.tsx`
|
|
|
-- `packages/cli/src/tui/commands.ts`
|
|
|
-
|
|
|
-### Studio changes
|
|
|
-
|
|
|
-Keep Studio changes shallow:
|
|
|
-- replace `/api/agent` one-shot orchestration with shared control-layer API
|
|
|
-- adapt existing pages to subscribe to shared events
|
|
|
-- move current `ChatBar` toward a shared interaction client
|
|
|
-
|
|
|
-### File size guardrails
|
|
|
-
|
|
|
-Hard constraints:
|
|
|
-- New files should target `< 250` lines.
|
|
|
-- Orchestrator files may reach `<= 350` lines if unavoidable.
|
|
|
-- No new monolith comparable to `runner.ts`.
|
|
|
-- Shared types go in dedicated model files, not in shells.
|
|
|
-- UI shells should remain thin and call shared control-layer modules.
|
|
|
-
|
|
|
-## Rollout Plan
|
|
|
-
|
|
|
-### Phase 1: Shared models and runtime bridge
|
|
|
-
|
|
|
-Build:
|
|
|
-- session model
|
|
|
-- intent model
|
|
|
-- execution status/events
|
|
|
-- automation modes
|
|
|
-- runtime bridge to existing pipeline actions
|
|
|
-
|
|
|
-No UI replacement yet.
|
|
|
-
|
|
|
-### Phase 2: TUI shell
|
|
|
-
|
|
|
-Build the project-scoped TUI:
|
|
|
-- project startup
|
|
|
-- active book binding
|
|
|
-- chat input
|
|
|
-- process/status pane
|
|
|
-- core commands
|
|
|
-
|
|
|
-### Phase 3: Human edit transactions
|
|
|
-
|
|
|
-Add:
|
|
|
-- chapter-level edit controller
|
|
|
-- truth-file-aware edit flow
|
|
|
-- entity rename flow
|
|
|
-
|
|
|
-### Phase 4: Studio adoption
|
|
|
-
|
|
|
-Refit Studio:
|
|
|
-- shared conversation brain
|
|
|
-- shared event/status model
|
|
|
-- replace one-shot chat behavior
|
|
|
-
|
|
|
-## What This Design Explicitly Avoids
|
|
|
-
|
|
|
-- no separate Studio and TUI orchestration stacks
|
|
|
-- no top-heavy onboarding questionnaire
|
|
|
-- no raw file editing as the primary mutation model
|
|
|
-- no giant new “god file”
|
|
|
-- no rewriting the entire pipeline before the control layer exists
|
|
|
-
|
|
|
-## Recommendation
|
|
|
-
|
|
|
-Implement this as a new long-running branch rooted in an isolated worktree.
|
|
|
-
|
|
|
-The order should be:
|
|
|
-1. shared interaction/control models
|
|
|
-2. runtime bridge
|
|
|
-3. TUI shell
|
|
|
-4. edit controller
|
|
|
-5. Studio migration
|
|
|
-
|
|
|
-That keeps the architecture correct while still delivering the writing-workbench experience early through TUI.
|
Ma