From a3d2ddf34cc026a6f406ab272361b5bf2213a4a5 Mon Sep 17 00:00:00 2001 From: Ramnique Singh <30795890+ramnique@users.noreply.github.com> Date: Fri, 10 Jul 2026 11:52:40 +0530 Subject: [PATCH] docs(x): design docs and prompt catalogs follow the runtime/ move MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Path pass over turn-runtime-design.md, session-design.md, VIDEO_MODE.md, and LIVE_NOTE.md: every source pointer updated to the runtime/ layout, the turn doc's suggested-module-layout section (§28) refreshed to the real tree (it predated the event hub, bridges, and composer), and the session doc's §14 layout fixed including its old §11/§14 contradiction about where the headless runner lives. Co-Authored-By: Claude Fable 5 --- apps/x/LIVE_NOTE.md | 14 +++++----- apps/x/VIDEO_MODE.md | 10 +++---- apps/x/packages/core/docs/session-design.md | 13 ++++++--- .../packages/core/docs/turn-runtime-design.md | 27 +++++++++---------- 4 files changed, 34 insertions(+), 30 deletions(-) diff --git a/apps/x/LIVE_NOTE.md b/apps/x/LIVE_NOTE.md index d8a157d7..85f16786 100644 --- a/apps/x/LIVE_NOTE.md +++ b/apps/x/LIVE_NOTE.md @@ -326,7 +326,7 @@ Three branches by `trigger`: ### 5. Live Note skill (Copilot-facing) - **Purpose**: teaches Copilot the `live:` model — operational posture (act-first), the strong/medium/anti-signal taxonomy and how to act on each, the **always-extend-not-fork** rule for already-live notes, user-facing language (call them "live notes"; surface the **Live Note panel** by name), the auto-run-once-on-create/edit default, schema, triggers, YAML-safety rules, insertion workflow, and the `run-live-note-agent` tool with `context` backfills. -- **File**: `packages/core/src/application/assistant/skills/live-note/skill.ts`. Exported `skill` constant. +- **File**: `packages/core/src/runtime/assembly/skills/live-note/skill.ts`. Exported `skill` constant. - **Schema interpolation**: at module load, `stringifyYaml(z.toJSONSchema(LiveNoteSchema))` is interpolated into the "Canonical Schema" section. Edits to `LiveNoteSchema` propagate automatically. - **Output**: markdown, injected into the Copilot system prompt when `loadSkill('live-note')` fires. - **Invoked by**: Copilot's `loadSkill` builtin tool. Registration in `skills/index.ts`. @@ -334,7 +334,7 @@ Three branches by `trigger`: ### 6. Copilot trigger paragraph - **Purpose**: tells Copilot *when* to load the `live-note` skill, and frames how aggressively to act once loaded. -- **File**: `packages/core/src/application/assistant/instructions.ts` (look for the "Live Notes" paragraph). +- **File**: `packages/core/src/runtime/assembly/copilot/instructions.ts` (look for the "Live Notes" paragraph). - **Strong signals (load + act without asking)**: cadence words ("every morning / daily / hourly…"), living-document verbs ("keep a running summary of…", "maintain a digest of…"), watch/monitor verbs, pin-live framings ("always show the latest X here"), direct ("track / follow X"), event-conditional ("whenever a relevant email comes in…"). - **Medium signals (load + answer the one-off + offer)**: time-decaying questions ("what's the weather?", "USD/INR right now?", "service X status?"), note-anchored snapshots ("show me my schedule here"), recurring artifacts ("morning briefing", "weekly review", "Acme dashboard"), topic-following / catch-up. - **Anti-signals (do NOT make live)**: definitional questions, one-off lookups, manual document editing. @@ -343,7 +343,7 @@ Three branches by `trigger`: ### 7. `run-live-note-agent` tool — `context` parameter description - **Purpose**: a mini-prompt (a Zod `.describe()`) that guides Copilot on when to pass extra context for a run. -- **File**: `packages/core/src/application/lib/builtin-tools.ts` (the `run-live-note-agent` tool definition). +- **File**: `packages/core/src/runtime/tools/catalog.ts` (the `run-live-note-agent` tool definition). - **Inputs**: `filePath` (workspace-relative; the tool strips the `knowledge/` prefix internally), optional `context`. - **Output**: flows into `runLiveNoteAgent(..., 'manual')` → `buildMessage` → appended as `**Context:**` in the agent message. - **Key use case**: backfill a newly-made-live note so its body isn't empty on day 1. @@ -394,10 +394,10 @@ Conventions: | Deprecated Today.md one-time migration | `packages/core/src/knowledge/deprecate_today_note.ts` | | Gmail event producer | `packages/core/src/knowledge/sync_gmail.ts` | | Calendar event producer + digest | `packages/core/src/knowledge/sync_calendar.ts` | -| Copilot skill | `packages/core/src/application/assistant/skills/live-note/skill.ts` | -| Skill registration | `packages/core/src/application/assistant/skills/index.ts` | -| Copilot trigger paragraph | `packages/core/src/application/assistant/instructions.ts` | -| `run-live-note-agent` builtin tool | `packages/core/src/application/lib/builtin-tools.ts` | +| Copilot skill | `packages/core/src/runtime/assembly/skills/live-note/skill.ts` | +| Skill registration | `packages/core/src/runtime/assembly/skills/index.ts` | +| Copilot trigger paragraph | `packages/core/src/runtime/assembly/copilot/instructions.ts` | +| `run-live-note-agent` builtin tool | `packages/core/src/runtime/tools/catalog.ts` | | Editor toolbar (Radio button → panel) | `apps/renderer/src/components/editor-toolbar.tsx` | | Live Note panel (single-view editor) | `apps/renderer/src/components/live-note-sidebar.tsx` | | Status hook (`useLiveNoteAgentStatus`) | `apps/renderer/src/hooks/use-live-note-agent-status.ts` | diff --git a/apps/x/VIDEO_MODE.md b/apps/x/VIDEO_MODE.md index 15549906..abfeaf07 100644 --- a/apps/x/VIDEO_MODE.md +++ b/apps/x/VIDEO_MODE.md @@ -108,7 +108,7 @@ is live) to the outgoing message as `UserImagePart`s and sets (`data`, `mediaType`), `source: 'camera' | 'screen'`, `capturedAt`. Unlike file attachments (path references read via the `LLMParse` tool), image parts go to the model as real multimodal image parts. -- `packages/core/src/agents/message-encoding.ts` `convertFromMessages`: +- `packages/core/src/runtime/assembly/message-encoding.ts` `convertFromMessages`: emits a context line (frame counts + time span), then labeled groups — a `"Webcam frames (oldest to newest):"` text part before camera images and a `"Screen-share frames (oldest to newest):"` text part before screen @@ -176,11 +176,11 @@ Push-to-talk is disabled while a call owns the mic. | Prompt | Where | |--------|-------| -| `# Video Mode (Live Camera)` system section — how to use webcam frames, coaching guidance, screen-share rules ("treat the screen as the primary subject", "last screen frame is current"), etiquette (never comment on appearance) | `packages/core/src/application/assistant/capabilities/modes.ts` (the `VIDEO_MODE` fragment of the `video-mode` capability, composed by `agents/compose-instructions.ts`) | +| `# Video Mode (Live Camera)` system section — how to use webcam frames, coaching guidance, screen-share rules ("treat the screen as the primary subject", "last screen frame is current"), etiquette (never comment on appearance) | `packages/core/src/runtime/assembly/capabilities/modes.ts` (the `VIDEO_MODE` fragment of the `video-mode` capability, composed by `agents/compose-instructions.ts`) | | `# Practice Session (Coach Mode)` system section — coaching persona: specific/actionable feedback after each take, one-sentence interjections mid-flow, structured debrief on wrap-up | `capabilities/modes.ts` (the `COACH_MODE` fragment, directly after the video capability) | -| "Driving the app" paragraph in the video-mode section — on calls, prefer app-navigation read-view/open-item (show while telling) over describing or squinting at frames | same `# Video Mode` section; full action docs in the `app-navigation` skill (`application/assistant/skills/app-navigation/skill.ts`) | -| Per-message frame context line `[Video mode: N live webcam frames … and M frames of the user's shared screen …]` + group labels | `packages/core/src/agents/runtime.ts` (`convertFromMessages`) | -| `videoMode` / `coachMode` composition overrides (session-sticky; flips bust prefix cache) | `packages/core/src/turns/bridges/real-agent-resolver.ts` (`CompositionOverrides`); set from `App.tsx` `sendConfig` | +| "Driving the app" paragraph in the video-mode section — on calls, prefer app-navigation read-view/open-item (show while telling) over describing or squinting at frames | same `# Video Mode` section; full action docs in the `app-navigation` skill (`runtime/assembly/skills/app-navigation/skill.ts`) | +| Per-message frame context line `[Video mode: N live webcam frames … and M frames of the user's shared screen …]` + group labels | `packages/core/src/runtime/legacy/engine.ts` (`convertFromMessages`) | +| `videoMode` / `coachMode` composition overrides (session-sticky; flips bust prefix cache) | `packages/core/src/runtime/turns/bridges/real-agent-resolver.ts` (`CompositionOverrides`); set from `App.tsx` `sendConfig` | Voice input/output prompt sections (`# Voice Input`, `# Voice Output`) are reused untouched — calls set `voiceInput` per utterance and force diff --git a/apps/x/packages/core/docs/session-design.md b/apps/x/packages/core/docs/session-design.md index ab4f122d..f92acd47 100644 --- a/apps/x/packages/core/docs/session-design.md +++ b/apps/x/packages/core/docs/session-design.md @@ -520,16 +520,21 @@ All tests use the in-memory/mocked turn runtime and repo fakes. ## 14. Suggested module layout ```text -apps/x/packages/shared/src/sessions.ts # event schemas, reducer, index types +apps/x/packages/shared/src/sessions.ts # event schemas, reducer, index types -apps/x/packages/core/src/sessions/ +apps/x/packages/core/src/runtime/sessions/ sessions.ts # ISessions implementation + api.ts # public contract repo.ts # ISessionRepo contract fs-repo.ts # filesystem implementation - index.ts # in-memory index + startup scan - headless.ts # runHeadlessTurn + session-index.ts # in-memory index + bus.ts # index-changed fan-out ``` +The headless helper of §11 is implemented as `HeadlessAgentRunner` in +`runtime/assembly/headless.ts` (not under `sessions/`). + + Awilix registration mirrors the turn runtime: singleton scope, PROXY constructor injection, no container resolution from inside the classes. diff --git a/apps/x/packages/core/docs/turn-runtime-design.md b/apps/x/packages/core/docs/turn-runtime-design.md index d487aa90..8abee863 100644 --- a/apps/x/packages/core/docs/turn-runtime-design.md +++ b/apps/x/packages/core/docs/turn-runtime-design.md @@ -1888,21 +1888,20 @@ tests for: This is a suggested organization, not a locked implementation requirement: ```text -apps/x/packages/shared/src/turns.ts +apps/x/packages/shared/src/turns.ts # durable schemas + reducer (unchanged home) -apps/x/packages/core/src/turns/ - runtime.ts - reducer.ts # if implementation is re-exported through shared, - # locate pure code to avoid dependency cycles - repo.ts - fs-repo.ts - stream.ts - agent-resolver.ts - context-resolver.ts - model-registry.ts - tool-registry.ts - permission.ts - index.ts +apps/x/packages/core/src/runtime/ + turns/ # the engine: runtime.ts, stream, event-hub, context + # resolution/elision, request composer, repos, inspect-cli + bridges/ # real implementations of the engine's seams (agent/tool/ + # model resolvers, permission checker/classifier) + sessions/ # session layer (session-design.md) + assembly/ # what an agent is: registry, compose-instructions, + # workspace-context, message-encoding, permission-metadata, + # headless runners, spawn-agent, copilot/, capabilities/, + # skills/ + tools/ # builtin-tool catalog + domain modules + exec plumbing + legacy/ # the dying runs engine (engine.ts + runs.ts + repos) ``` The final reducer location must permit both core and renderer to use exactly the