diff --git a/.env.example b/.env.example
index 4b75d30..50066fb 100644
--- a/.env.example
+++ b/.env.example
@@ -170,6 +170,12 @@ ASR_AZURE_BASE_URL=https://{region}.api.cognitive.microsoft.com
# ASR_OPENAI_ENABLED=false
# ASR_BROWSER_NATIVE_ENABLED=false
+# Optional local audio/video material extraction uses the first enabled server
+# ASR provider above. It also requires the system `ffmpeg` and `ffprobe`
+# executables on PATH; no bundled binary or npm dependency is installed.
+# Without both executables, OpenMAIC skips the local extractor and uses a
+# configured AliDocMind cloud extractor when available. With neither path
+# enabled, media materials fail cleanly with setup guidance.
# --- PDF Processing -----------------------------------------------------------
@@ -295,7 +301,14 @@ WEB_SEARCH_CLAUDE_MODELS=
# Boolean feature flags accept "true" or "1". NEXT_PUBLIC_* values are compiled
# into the browser bundle at build time, so changing them requires a rebuild.
-# Master gate for the MAIC Editor Pro-mode entry point.
+# Enable the Pro workbench entry (the workbench also requires the agent
+# runtime to be configured server-side; see the Agent Runtime section).
+# Implies the MAIC Editor gate below — Pro mode always ships with the editor.
+# NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
+
+# Master gate for the MAIC Editor Pro-mode entry point. Implied by
+# NEXT_PUBLIC_PRO_WORKBENCH_ENABLED; set it alone to enable the classroom
+# editor on a deployment without the workbench.
# NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true
# Select @openmaic/editor inside Pro mode. This does not enable Pro mode by itself.
@@ -321,6 +334,58 @@ WEB_SEARCH_CLAUDE_MODELS=
# blank defaults to open.maic.chat; set to "off" to omit it.
# NEXT_PUBLIC_VIDEO_EXPORT_CTA_DESTINATION=open.maic.chat
+# --- Agent Runtime (experimental) ---------------------------------------------
+
+# Server-only gate for durable background agent sessions: the /api/agent
+# session and owner-event control-plane routes plus the in-process session
+# runner. Default OFF — while disabled, every /api/agent/sessions* and
+# /api/agent/owner-events route answers 404. Truthy values are "true" or "1";
+# anything else (including unset) is treated as disabled.
+# OPENMAIC_AGENT_RUNTIME_ENABLED=true
+
+# The runtime is server-backed and requires the PostgreSQL connection from the
+# "Server-backed Persistence" section below: without a non-empty DATABASE_URL
+# the runner never starts and the session store rejects requests, even with the
+# flag above enabled.
+# DATABASE_URL=postgres://openmaic:password@postgres:5432/openmaic
+
+# REQUIRED while the runtime is enabled: MODEL_ROUTES must explicitly route the
+# "maic-agent-driver" stage to a provider-prefixed model id. There is
+# intentionally no fallback — without this route every agent session fails at
+# run start. The route object must set api (or its alias dialect) to
+# "openai-completions" or "openai-responses"; any other value is rejected, and
+# a bare model id without a provider prefix is rejected too. Optional fields:
+# contextWindow pins the effective context window below the provider catalog
+# value (used by compaction thresholds), and thinking must never set effort
+# (the tool-using driver cannot combine reasoning_effort with function tools on
+# this transport).
+# MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'
+
+# Runner tuning. Defaults are shown; only relevant once the runtime is enabled.
+# OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS=1000
+# OPENMAIC_AGENT_RUNTIME_HEARTBEAT_MS=2000
+# OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS=10000
+# OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT=2
+# OPENMAIC_AGENT_RUNTIME_MAX_ATTEMPTS=5
+
+# Global per-tool-call execution bound for every agent run (ms). A tool call
+# that neither resolves nor rejects within the budget is aborted and settles as
+# an error tool-result the agent can retry or proceed from; the session does
+# not die. Default 600000 (10 minutes). Tools with known longer budgets (media
+# synthesis, material extraction) carry their own explicit bounds in code.
+# OPENMAIC_AGENT_TOOL_TIMEOUT_MS=600000
+
+# Conversation compaction is reserved and OFF by default. The reusable
+# compaction runtime is not implemented yet — it lands in a later slice of
+# work — and until then the runner runs without context transformation, so
+# these knobs are inert placeholders.
+# OPENMAIC_AGENT_COMPACTION_ENABLED=true
+# OPENMAIC_AGENT_COMPACTION_RESERVE_TOKENS=0
+# OPENMAIC_AGENT_COMPACTION_KEEP_RECENT_TOKENS=0
+
+# Session prompts and follow-up messages are capped server-side at a fixed
+# 100,000 characters; this limit is a constant and is not configurable.
+
# --- Proxy (optional) --------------------------------------------------------
# HTTP_PROXY=
@@ -353,13 +418,19 @@ DEFAULT_MODEL=
# but are deprecated — write provider:model). Warnings only: the server starts
# regardless, so a bad value is caught here instead of at request time.
# Routable stages: scene-outlines-stream, scene-content, scene-actions,
-# agent-profiles, quiz-grade, pbl-chat, chat-adapter, generate-classroom,
-# web-search-query-rewrite.
+# agent-profiles, quiz-grade, pbl-chat, pbl-v2-runtime, chat-adapter,
+# generate-classroom, web-search-query-rewrite, maic-agent,
+# maic-agent-driver.
# scene-content can also be routed per scene type with composite keys:
# scene-content:slide, scene-content:quiz, scene-content:interactive,
# scene-content:pbl. A type falls back to the base scene-content route when it
# has no key of its own (so scene-content: > scene-content > x-model >
# DEFAULT_MODEL).
+# pbl-v2-runtime follows the same composite fallback pattern with
+# pbl-v2-runtime:instructor, pbl-v2-runtime:open-task, pbl-v2-runtime:evaluate
+# and pbl-v2-runtime:simulator, falling back to the base pbl-v2-runtime route.
+# maic-agent-driver is REQUIRED when the agent runtime is enabled; see the
+# "Agent runtime (experimental)" section for its api/dialect constraints.
# A route value can be a model string, OR an object {"model","thinking"} where
# `thinking` is the full ThinkingConfig: mode (default|disabled|enabled|auto),
# effort (none|minimal|low|medium|high|xhigh|max), level (minimal|low|medium|
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c256c5b..f629591 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,7 +6,7 @@ on:
# only ever proves one part merged into the branch, so without a push
# trigger the accumulated state of the branch that eventually reaches main
# is never built on its own.
- branches: [main, integration/kv-asset-server-backend]
+ branches: [main, integration/kv-asset-server-backend, integration/agent-workbench]
pull_request:
branches:
[
@@ -15,6 +15,7 @@ on:
feat/maic-editor-v1,
runtime-server-backend,
integration/kv-asset-server-backend,
+ integration/agent-workbench,
]
concurrency:
diff --git a/README-zh.md b/README-zh.md
index 2c3380f..92a22ac 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -10,6 +10,12 @@
一键生成沉浸式多智能体互动课堂。
+
+
+
+
+
+
diff --git a/README.md b/README.md
index 05ac6bb..496f1dd 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,12 @@
Get an immersive, multi-agent learning experience in just one click
+## 🎉 OpenMAIC v1.0.0 — Build courses with an agent
+
+**One prompt in, a whole course out — and now you can steer.** Released August 27, 2026, OpenMAIC v1.0.0 adds a **Pro workbench** alongside the classic one-click generator: chat with an agent that plans your curriculum, builds and revises every page, and works straight from your materials.
+
+- 🤖 **Agent workbench** — a chat-first workspace that plans, builds, and revises whole courses
+- 💾 **Durable sessions** — server-backed runs survive restarts; cancel, resume, and steer anytime
+- 📎 **Session materials** — upload documents, audio, and video, or pull from web search; the agent builds from them
+- 🧰 **Course tools + 20 built-in skills** — slides, quizzes, interactives, PBL, images, video, voices, `.pptx` import
+- 🔌 **Neutral by design** — bring your own models, media, search providers, and storage backend
+
+Take the full tour in [Features](#-features), then set it up with [Agent workbench and runtime](#optional-agent-workbench-and-runtime).
+
## 🗞️ News
+- **2026-08-27** — **OpenMAIC v1.0.0:** an agent workbench, durable course-building sessions, reusable skills, session materials, provider-neutral server capabilities, and a pluggable persistence stack.
- **2026-08-14** — [v0.3.2 released!](https://github.com/THU-MAIC/OpenMAIC/releases/tag/v0.3.2) Video export hardening (deterministic Quiz/PBL covers, fidelity polish, interactive HTML capture, CPU resource profiles); server-backed persistence completed (full document cutover, one-command Postgres stack, incremental saves) plus the asset registry; the `@openmaic/generation` package; four new locales; Amazon Bedrock, Atlas Cloud, and Claude search providers; FunASR ASR. See [changelog](CHANGELOG.md).
- **2026-07-21** — [v0.3.1 released!](https://github.com/THU-MAIC/OpenMAIC/releases/tag/v0.3.1) One-click MP4 video export; server-backed runtime storage with a Postgres reference server; direct slide manipulation in the editor (drag, resize, rotate, multi-select); smarter "Edit with AI" (validated JSON Patch edits, multi-session history); expanded Document Parsing (multi-format upload, audio/video extraction, AliDocMind, MinerU); new providers (Azure OpenAI, SearXNG, ComfyUI) and the GPT-5.6 model family; action-level playback navigation; SSRF hardening. See [changelog](CHANGELOG.md).
- **2026-06-28** — [v0.3.0 released!](https://github.com/THU-MAIC/OpenMAIC/releases/tag/v0.3.0) Project-Based Learning (PBL) v2 with classroom UI; "Edit with AI" Pro-mode editor agent; the `@openmaic/*` SDK family (DSL/renderer/importer) published to npm; optional per-stage model routing; new models (GLM-5.2, Kimi K2.7 Code, Qwen3.7 Plus/Max); a vocational-learning task engine; Korean (ko-KR) locale; and relicensing from AGPL-3.0 to MIT. See [changelog](CHANGELOG.md).
@@ -187,6 +206,12 @@ ASR_FUNASR_BASE_URL=http://localhost:8000/v1
Use `funasr-server --device cpu --model sensevoice` for a CPU-only setup. See the [FunASR deployment guide](https://github.com/modelscope/FunASR#deploy) for production options.
+### Optional: Local Audio and Video Extraction
+
+OpenMAIC can extract timestamped transcripts and prepared video keyframes locally. Install the system `ffmpeg` package so both `ffmpeg` and `ffprobe` are executable on `PATH`, then configure one server ASR provider (for example FunASR, Lemonade, or OpenAI) using the variables above. The application resolves the executables at extraction time; ffmpeg is not an npm dependency and is not required to start or use OpenMAIC.
+
+If the executables are unavailable, the local extractor is skipped. A configured AliDocMind provider remains available as the cloud extraction path. When neither local ffmpeg extraction nor AliDocMind is available, audio/video materials are marked failed with an actionable setup message instead of hanging or completing with an empty transcript.
+
OpenAI quick example:
```env
@@ -409,6 +434,36 @@ and
Leave `NEXT_PUBLIC_PERSISTENCE` unset to retain the existing browser-only
behavior.
+### Optional: Agent workbench and runtime
+
+The Pro workbench is a usable course-building surface entered from the home
+page. Its collapsible navigation rail, conversation pane, and tabbed classroom
+pane share `/api/agent/*` control-plane routes and an in-process session runner.
+It is off by default. Enable its build-time entry point and the server runtime
+with the same PostgreSQL connection used by server-backed persistence:
+
+```env
+NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
+OPENMAIC_AGENT_RUNTIME_ENABLED=true
+DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic
+MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'
+```
+
+While the flag is off, the `/api/agent/sessions*` and `/api/agent/owner-events`
+routes answer `404`. Enabling it
+without a `DATABASE_URL` never starts the runner and makes the session routes
+error, so the runtime is server-backed by design. `MODEL_ROUTES` must explicitly
+route `maic-agent-driver` to a provider-prefixed model with an
+`openai-completions` or `openai-responses` `api`/`dialect`; there is intentionally
+no fallback.
+
+To make the browser use the same server-backed document and runtime stores,
+also build with `NEXT_PUBLIC_PERSISTENCE=1` and configure the matching
+development tokens described in [Server-backed persistence](#server-backed-persistence-postgresql).
+Without these opt-ins, OpenMAIC retains its existing browser-only behavior.
+Runner cadence (scan interval, heartbeat, lease TTL, concurrency, attempts) and
+the reserved compaction knobs are listed in `.env.example`.
+
### Optional: MP4 Video Export (Render Service)
The "Export Video" menu builds a self-contained [Hyperframes](https://www.npmjs.com/package/@hyperframes/producer) project entirely in the browser. Turning that into an MP4 needs Chromium + FFmpeg on Node 22, so it runs in an isolated `render-service` container rather than the app.
@@ -463,6 +518,64 @@ TTS_VOXCPM_BASE_URL=http://localhost:8000/v1
## ✨ Features
+### Agent Workbench and Pro Mode (v1.0.0)
+
+The workbench adds a conversational course-building agent to OpenMAIC.
+Its durable sessions can be resumed after a worker restart, accept follow-up
+instructions while running, and stream a replayable event history to the chat
+surface.
+
+Open it from the Pro control on the home page. The workspace combines a
+transient, collapsible folders/conversations rail with a chat pane and a
+classroom pane whose open courses stay in tabs. Workspace controls return to
+classic mode, and either entry remains gated by the public workbench flag plus
+the configured server runtime.
+
+The agent works through explicit, validated tools rather than editing opaque
+blobs:
+
+| Area | Capabilities |
+| --- | --- |
+| **Plan and organize** | Plan multi-lesson curricula; create courses and folders; rename and move courses |
+| **Build and edit** | Read/search the stage DSL; atomically patch one scene; generate, duplicate, insert, delete, and reorder pages; edit narration and deck structure |
+| **Use materials** | Upload files; extract documents, audio, and video; search extracted text; fetch trusted web URLs; reuse material media |
+| **Create media** | Generate images and videos through configured server providers; generate narration audio |
+| **Import and inspect** | Import `.pptx` slides with their layout preserved; render scene previews for visual inspection when available |
+| **Configure the classroom** | List available voices, set the agent roster, and clone/register a voice when a pluggable registration adapter is configured |
+
+Twenty built-in skills cover curriculum planning, deep research, interactive,
+lecture, workshop, vocational, and other teaching styles, slide/stage craft,
+PPTX import, editing, and style reuse. User-authored skills are stored per owner
+and can be created, read, and patched through the same runtime.
+
+The server-backed workbench also exposes owner-scoped folder routes and a
+per-viewer stage metadata sidecar for ownership, publication, and
+generation-complete state. A stage ID acts as the capability for reading a
+non-deleted course, but stage mutations remain restricted to its owner. The
+material upload contract stores supported source bytes before lease-fenced
+document or media extraction records derived text and images; media extraction
+can select AliDocMind or the optional local ffmpeg/ffprobe provider.
+
+Under the hood, agent sessions are database-backed with leases, heartbeats,
+crash resume, cancellation, and follow-up steering, and database-maintained
+revision counters keep per-stage and per-scene freshness monotonic so the
+workbench refetches only the scenes that changed. Server routes resolve LLM,
+media, ASR/TTS, and search configuration provider-neutrally: credentials never
+reach the browser, uniform `__ENABLED=false` switches can force
+off any served capability, startup validation warns about bad model
+configuration, and unresolved model routes fail loudly instead of guessing a
+vendor.
+
+### Pluggable Storage
+
+OpenMAIC runs without a database by default: course documents, learner runtime
+records, device/account KV values, and assets use browser storage. The
+`@openmaic/storage` package defines swappable stores for those primitives and
+adds PostgreSQL-backed documents, learner runtime, assets, durable agent
+sessions, session materials, and user skills. HTTP clients connect the browser
+to the embedded persistence endpoint, while the server asset layer can keep
+bytes in PostgreSQL or S3.
+
### Deep Interactive Mode (New!)
**Passive listening? ❌ Hands-on exploration! ✅**
@@ -573,7 +686,10 @@ If you are looking for a version with richer functionality, stronger interactivi
### Lesson Generation
-Describe what you want to learn or attach reference materials. OpenMAIC's two-stage pipeline handles the rest:
+Describe what you want to learn or attach reference materials. PDF, Word,
+PowerPoint, spreadsheet, text, image, audio, and video inputs can enter the
+material pipeline; configured extractors turn supported sources into content
+for generation. OpenMAIC's classic two-stage pipeline handles the rest:
| Stage | What Happens |
|-------|-------------|
@@ -739,6 +855,8 @@ Optional config in `~/.openclaw/openclaw.json`:
- **Text-to-Speech** — Multiple voice providers with customizable voices
- **Speech Recognition** — Talk to your AI teacher using your microphone
- **Web Search** — Agents search the web for up-to-date information during class
+- **Provider controls** — Server-side capability discovery, model resolution, force-off switches, and fail-loud routing keep deployments explicit
+- **Course freshness** — Database-triggered per-scene revision counters, freshness events, and targeted scene fetches keep workbench views synchronized
- **i18n** — Interface supports 12 locales across 11 languages: Simplified Chinese, Traditional Chinese, English, Japanese, Korean, Russian, Arabic, Portuguese (Brazil), Spanish (Mexico), French, Vietnamese, and German
- **Dark Mode** — Easy on the eyes for late-night study sessions
@@ -792,7 +910,9 @@ We welcome contributions from the community! Whether it's bug reports, feature i
```
OpenMAIC/
├── app/ # Next.js App Router
-│ ├── api/ # Server API routes (~18 endpoints)
+│ ├── api/ # Generation, media, persistence, and agent APIs
+│ │ ├── agent/ # Durable session, event, material, and skill control plane
+│ │ ├── stages/ # Owner-scoped course reads, writes, manifests, and scene fetches
│ │ ├── generate/ # Scene generation pipeline (outlines, content, images, TTS …)
│ │ ├── generate-classroom/ # Async classroom job submission + polling
│ │ ├── chat/ # Multi-agent discussion (SSE streaming)
@@ -812,6 +932,8 @@ OpenMAIC/
│ ├── types/ # Centralized TypeScript type definitions
│ ├── audio/ # TTS & ASR providers
│ ├── media/ # Image & video generation providers
+│ ├── persistence/ # Browser/server persistence wiring and PostgreSQL provider
+│ ├── server/agent-runtime/ # Durable runner, skills, materials, and course-building tools
│ ├── export/ # PPTX & HTML export
│ ├── hooks/ # React custom hooks (55+)
│ ├── i18n/ # Internationalization (zh-CN, zh-TW, en-US, ja-JP, ko-KR, ru-RU, ar-SA, pt-BR, es-MX, fr-FR, vi-VN, de-DE)
@@ -823,6 +945,7 @@ OpenMAIC/
│ │ └── components/element/ # Element renderers (text, image, shape, table, chart …)
│ ├── scene-renderers/ # Quiz, Interactive, PBL scene renderers
│ ├── generation/ # Lesson generation toolbar & progress
+│ ├── workbench/ # Pro workbench conversation and course-reference UI
│ ├── chat/ # Chat area & session management
│ ├── settings/ # Settings panel (providers, TTS, ASR, media …)
│ ├── whiteboard/ # SVG-based whiteboard drawing
@@ -831,6 +954,12 @@ OpenMAIC/
│ └── ... # audio, roundtable, stage, ai-elements
│
├── packages/ # Workspace packages
+│ ├── @openmaic/dsl/ # Versioned course/slide data contract and validators
+│ ├── @openmaic/renderer/ # React renderer for the slide DSL
+│ ├── @openmaic/editor/ # Composable slide editing core and React surface
+│ ├── @openmaic/importer/ # PPTX → OpenMAIC slide importer
+│ ├── @openmaic/generation/ # Generation contracts, pipeline, and prompt assets
+│ ├── @openmaic/storage/ # Browser, HTTP, PostgreSQL, and S3 persistence primitives
│ ├── pptxgenjs/ # Customized PowerPoint generation
│ └── mathml2omml/ # MathML → Office Math conversion
│
@@ -846,6 +975,8 @@ OpenMAIC/
### Key Architecture
- **Generation Pipeline** (`@openmaic/generation`) — Two-stage: outline generation → scene content generation
+- **Agent Runtime** (`lib/server/agent-runtime/`) — PostgreSQL-backed sessions with leased execution, resume/steer semantics, skills, materials, and validated course tools
+- **Persistence Layer** (`@openmaic/storage`) — Swappable document, runtime, KV, asset, agent-session, material, and user-skill stores
- **Multi-Agent Orchestration** (`lib/orchestration/`) — LangGraph state machine managing agent turns and discussions
- **Playback Engine** (`lib/playback/`) — State machine driving classroom playback and live interaction
- **Action Engine** (`lib/action/`) — Executes 28+ action types (speech, whiteboard draw/text/shape/chart, spotlight, laser …)
diff --git a/app/api/agent/edit/route.ts b/app/api/agent/edit/route.ts
deleted file mode 100644
index 0ebae3b..0000000
--- a/app/api/agent/edit/route.ts
+++ /dev/null
@@ -1,210 +0,0 @@
-/**
- * MAIC Agent — SSE transport endpoint.
- *
- * Hosts a server-side pi Agent and streams its `AgentEvent`s to the editor
- * sidebar as Server-Sent Events. The whole feature is gated behind the master
- * editor flag.
- */
-import type { NextRequest } from 'next/server';
-import type { AgentEvent, AgentMessage } from '@earendil-works/pi-agent-core';
-import { isMaicEditorEnabled } from '@/lib/config/feature-flags';
-import { resolveModelFromRequest } from '@/lib/server/resolve-model';
-import type { LlmStage } from '@/lib/server/model-routes';
-import { createCallLlmStreamFn } from '@/lib/agent/runtime/stream-fn';
-import { buildAgent, buildSystemPrompt } from '@/lib/agent/runtime/build-agent';
-import { buildToolset } from '@/lib/agent/tools/registry';
-import { callLLM } from '@/lib/ai/llm';
-import { createLogger } from '@/lib/logger';
-import type { SceneContext } from '@/lib/agent/tools/regenerate-scene-actions';
-
-const log = createLogger('MAIC Agent');
-
-// A single `regenerate_scene` tool call runs slide content generation *and*
-// action generation inside this SSE turn, matching the dedicated scene-content
-// route's budget (300s) — not the 60s a plain chat turn needs. Cap to 300 so
-// slow models / media-heavy slides aren't terminated mid-stream.
-export const maxDuration = 300;
-
-/**
- * Scene/stage context map sent by the client.
- * Keyed by scene id; the client reads `useStageStore` to build this so the
- * server never has to access a (non-existent) server-side scene store.
- */
-export type SceneContextMap = Record;
-
-interface AgentEditBody {
- message: string;
- scene?: { id: string; title: string };
- /**
- * Prior conversation turns (text only) sent by the client so the agent has
- * multi-turn memory — without this each request is stateless and the agent
- * cannot recall earlier exchanges.
- */
- history?: Array<{ role: 'user' | 'assistant'; text: string }>;
- /**
- * Trusted scene/stage context for every scene the agent may act on.
- * The client includes the active scene (and all sibling scenes) so the
- * `regenerate_scene_actions` tool can resolve outline + content without
- * relying on model-fabricated arguments.
- */
- sceneContextMap?: SceneContextMap;
- /**
- * Current canvas selection (element ids) for selection-aware `edit_elements`.
- * Client-sourced from `useCanvasStore.activeElementIdList`.
- */
- selection?: string[];
-}
-
-/** Max prior turns carried into context (keeps the prompt bounded). */
-const MAX_HISTORY_TURNS = 24;
-
-/** Convert the client's text-only history into pi `AgentMessage`s. */
-function toHistoryMessages(history: AgentEditBody['history']): AgentMessage[] {
- if (!Array.isArray(history)) return [];
- const turns = history
- .filter(
- (m): m is { role: 'user' | 'assistant'; text: string } =>
- !!m &&
- (m.role === 'user' || m.role === 'assistant') &&
- typeof m.text === 'string' &&
- m.text.trim().length > 0,
- )
- .slice(-MAX_HISTORY_TURNS);
- // Don't let the seeded transcript end on a user turn: agent.prompt() appends
- // the new user message, and two consecutive user messages degrade on some
- // providers. (Trailing user turns are dropped tool-call-only replies, etc.)
- while (turns.length > 0 && turns[turns.length - 1].role === 'user') turns.pop();
- return turns.map((m) =>
- m.role === 'user'
- ? ({ role: 'user', content: m.text } as AgentMessage)
- : ({ role: 'assistant', content: [{ type: 'text', text: m.text }] } as AgentMessage),
- );
-}
-
-export async function POST(req: NextRequest) {
- if (!isMaicEditorEnabled()) {
- return new Response('Not found', { status: 404 });
- }
-
- const body = (await req.json()) as AgentEditBody & Record;
- const message = (body.message ?? '').toString().trim();
- if (!message) {
- return new Response('message is required', { status: 400 });
- }
-
- // Resolve via the 'maic-agent' stage so operators can route the editor agent
- // to a dedicated model via MODEL_ROUTES (per-stage config). When unrouted it
- // falls back to the client's active frontend model config (x-model headers +
- // thinkingConfig body), then DEFAULT_MODEL — see resolveModel.
- const { model, modelInfo, thinkingConfig, modelString } = await resolveModelFromRequest(
- req,
- body,
- 'maic-agent',
- );
-
- // Per-stage model resolution for the generation tools. Each tool is a
- // self-contained black box that names the generation stage it produces (e.g.
- // `scene-content:interactive`, `scene-content:slide`, `scene-actions`); we
- // resolve that stage's model via MODEL_ROUTES (cached per stage for this turn),
- // independent of the `maic-agent` conversation model that drives streamFn below.
- // Unrouted stages fall back to the client's active frontend model, so default
- // behaviour is unchanged unless an operator routes a stage explicitly.
- const stageCache = new Map>>();
- const aiCall = async (
- stage: LlmStage,
- system: string,
- prompt: string,
- signal?: AbortSignal,
- ): Promise => {
- let resolved = stageCache.get(stage);
- if (!resolved) {
- resolved = await resolveModelFromRequest(req, body, stage);
- stageCache.set(stage, resolved);
- }
- const r = await callLLM(
- {
- model: resolved.model,
- system,
- prompt,
- maxOutputTokens: resolved.modelInfo?.outputWindow,
- // Abort the in-flight generation when the user cancels the turn — pi
- // passes each tool an AbortSignal, which the tools thread through here.
- abortSignal: signal,
- },
- 'maic-agent-regen',
- undefined,
- resolved.thinkingConfig,
- );
- return r.text;
- };
-
- const sceneContextMap: SceneContextMap = body.sceneContextMap ?? {};
- const selectionIds: readonly string[] = Array.isArray(body.selection)
- ? body.selection.filter((id): id is string => typeof id === 'string')
- : [];
- const tools = buildToolset({
- aiCall,
- getSceneContext: (sceneId) => sceneContextMap[sceneId],
- activeSceneId: body.scene?.id,
- getSelection: () => selectionIds,
- });
-
- const abortController = new AbortController();
- const streamFn = createCallLlmStreamFn({
- languageModel: model,
- maxOutputTokens: modelInfo?.outputWindow,
- thinkingConfig,
- source: 'maic-agent',
- abortSignal: abortController.signal,
- });
-
- const agent = buildAgent({
- streamFn,
- systemPrompt: buildSystemPrompt(body.scene),
- tools,
- history: toHistoryMessages(body.history),
- });
- log.info(`agent edit turn [model=${modelString}] scene=${body.scene?.id ?? 'none'}`);
-
- const encoder = new TextEncoder();
- const stream = new ReadableStream({
- async start(controller) {
- const send = (event: AgentEvent) => {
- try {
- controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
- } catch {
- /* controller closed */
- }
- };
- const unsubscribe = agent.subscribe((event) => {
- send(event);
- });
- try {
- await agent.prompt(message);
- await agent.waitForIdle();
- } catch (err) {
- log.error(`agent run failed: ${err instanceof Error ? err.message : String(err)}`);
- } finally {
- unsubscribe();
- try {
- controller.enqueue(encoder.encode('event: close\ndata: {}\n\n'));
- } catch {
- /* ignore */
- }
- controller.close();
- }
- },
- cancel() {
- agent.abort();
- abortController.abort();
- },
- });
-
- return new Response(stream, {
- headers: {
- 'Content-Type': 'text/event-stream; charset=utf-8',
- 'Cache-Control': 'no-cache, no-transform',
- Connection: 'keep-alive',
- },
- });
-}
diff --git a/app/api/agent/owner-events/route.ts b/app/api/agent/owner-events/route.ts
new file mode 100644
index 0000000..10ac2f7
--- /dev/null
+++ b/app/api/agent/owner-events/route.ts
@@ -0,0 +1,323 @@
+/**
+ * Durable, sparse SSE tail for the current owner's session summaries.
+ * A degraded caught_up is not authoritative: clients should schedule one full
+ * reconciliation and may later receive a non-degraded caught_up on recovery.
+ *
+ * Access model: there is no per-route auth challenge. Every request is
+ * granted an anonymous cookie identity, and every store read is scoped to
+ * that identity.
+ */
+import type { PersistedOwnerSessionEvent } from '@openmaic/storage';
+import type { NextRequest } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { subscribeAgentEventWakeup } from '@/lib/server/agent-runtime/event-notify-bus';
+import { resolveRequestOwnerId } from '@/lib/server/agent-runtime/owner';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+
+export const runtime = 'nodejs';
+// Self-hosted `next start` ignores maxDuration; Vercel's adapter can still use
+// it. The 25s heartbeat keeps this sparse stream active through idle periods.
+export const maxDuration = 300;
+
+// LISTEN/NOTIFY supplies low latency. This is deliberately retained as a
+// correctness fallback because NOTIFY is lossy across listener disconnects.
+export const OWNER_EVENT_POLL_INTERVAL_MS = 30_000;
+export const SSE_HEARTBEAT_INTERVAL_MS = 25_000;
+export const OWNER_EVENT_REPLAY_LIMIT = 1_000;
+const BACKLOG_PAGE = 500;
+
+function parseLastEventId(value: string | null): bigint {
+ if (!value || !/^\d+$/.test(value)) return BigInt(0);
+ try {
+ return BigInt(value);
+ } catch {
+ return BigInt(0);
+ }
+}
+
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ // Identity belongs to the request, not the URL. EventSource reconnects to
+ // this same stable path with the anonymous cookie minted on first attach.
+ // This slice resolves only the anonymous cookie identity; a future auth
+ // integration must thread `authenticatedOwnerId` through here, or sessions
+ // created under authenticated identities would be unreachable by their own
+ // owner.
+ const responseHeaders = new Headers();
+ const ownerId = resolveRequestOwnerId(req, responseHeaders);
+ const store = await getAgentSessionStore();
+
+ const url = new URL(req.url);
+ const lastEventId = parseLastEventId(
+ req.headers.get('last-event-id') ?? url.searchParams.get('lastEventId'),
+ );
+ const encoder = new TextEncoder();
+ let pollTimer: ReturnType | null = null;
+ let heartbeatTimer: ReturnType | null = null;
+ let unsubscribeWakeup: (() => void) | null = null;
+ let closed = false;
+
+ const clearTimers = () => {
+ if (pollTimer) clearTimeout(pollTimer);
+ if (heartbeatTimer) clearInterval(heartbeatTimer);
+ pollTimer = null;
+ heartbeatTimer = null;
+ unsubscribeWakeup?.();
+ unsubscribeWakeup = null;
+ };
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ let backlogDone = false;
+ let sentSinceAttach = 0;
+ let cursor = lastEventId;
+ let retirementCheckInFlight = false;
+ let consecutiveBacklogFailures = 0;
+ let degradedCaughtUp = false;
+ let attachCursorChecked = false;
+ let backlogSkippedForResync = false;
+ let initializing = true;
+ let wakeDuringInitialization = false;
+ let repollRequested = false;
+ let pollInFlight: Promise | null = null;
+
+ const write = (chunk: string) => {
+ if (closed) return false;
+ try {
+ controller.enqueue(encoder.encode(chunk));
+ return true;
+ } catch {
+ // Some runtimes do not invoke cancel() for every broken socket.
+ // Treat an enqueue failure as closure so this dead connection cannot
+ // retain its heartbeat and poll timers indefinitely.
+ closed = true;
+ clearTimers();
+ return false;
+ }
+ };
+
+ const close = () => {
+ if (closed) return;
+ closed = true;
+ clearTimers();
+ try {
+ controller.close();
+ } catch {
+ // The request closed between the guard and close.
+ }
+ };
+
+ const emitCaughtUp = (degraded = false) =>
+ write(
+ `event: caught_up\ndata: ${JSON.stringify({
+ type: 'caught_up',
+ replayed: sentSinceAttach,
+ fromEventId: lastEventId.toString(),
+ ...(degraded ? { degraded: true } : {}),
+ })}\n\n`,
+ );
+
+ const markCaughtUp = (degraded = false) => {
+ if (backlogDone) return;
+ if (!emitCaughtUp(degraded)) return;
+ backlogDone = true;
+ degradedCaughtUp = degraded;
+ };
+
+ const checkAttachCursor = async () => {
+ if (attachCursorChecked) return true;
+ let currentEventId: bigint;
+ try {
+ currentEventId = await store.readMaxId(ownerId);
+ } catch {
+ consecutiveBacklogFailures += 1;
+ if (consecutiveBacklogFailures >= 3) markCaughtUp(true);
+ return false;
+ }
+ consecutiveBacklogFailures = 0;
+ attachCursorChecked = true;
+
+ const reason =
+ lastEventId > currentEventId
+ ? 'cursor_ahead'
+ : currentEventId - lastEventId > BigInt(OWNER_EVENT_REPLAY_LIMIT)
+ ? 'too_far_behind'
+ : null;
+ if (!reason) return true;
+
+ cursor = currentEventId;
+ backlogDone = true;
+ degradedCaughtUp = false;
+ backlogSkippedForResync = true;
+ return write(
+ `event: resync_required\ndata: ${JSON.stringify({
+ type: 'resync_required',
+ reason,
+ fromEventId: lastEventId.toString(),
+ currentEventId: currentEventId.toString(),
+ })}\n\n`,
+ );
+ };
+
+ const writePage = (events: PersistedOwnerSessionEvent[]) => {
+ for (const event of events) {
+ if (
+ !write(
+ `id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify({
+ ...event,
+ // A degraded catch-up set `backlogDone` without draining, so
+ // the events that arrive while recovering are still history:
+ // keep labelling them backlog until the real signal goes out.
+ phase: backlogDone && !degradedCaughtUp ? 'live' : 'backlog',
+ })}\n\n`,
+ )
+ ) {
+ return false;
+ }
+ cursor = BigInt(event.id);
+ sentSinceAttach += 1;
+ }
+ return true;
+ };
+
+ const readPage = () => store.readAfter(ownerId, cursor, BACKLOG_PAGE);
+
+ const drainBacklog = async () => {
+ if (!(await checkAttachCursor()) || backlogSkippedForResync) return;
+ for (;;) {
+ if (closed) return;
+ let page: PersistedOwnerSessionEvent[];
+ try {
+ page = await readPage();
+ } catch {
+ consecutiveBacklogFailures += 1;
+ if (consecutiveBacklogFailures >= 3) markCaughtUp(true);
+ return;
+ }
+ consecutiveBacklogFailures = 0;
+ if (!writePage(page)) return;
+ if (page.length < BACKLOG_PAGE) break;
+ }
+ markCaughtUp();
+ };
+
+ const poll = async () => {
+ if (closed) return;
+ if (!attachCursorChecked) {
+ if (!(await checkAttachCursor()) || backlogSkippedForResync) return;
+ }
+ try {
+ const page = await readPage();
+ consecutiveBacklogFailures = 0;
+ if (!writePage(page)) return;
+ if (degradedCaughtUp) {
+ // The authoritative signal has to pass the SAME exhaustion check
+ // as the normal path. A degraded window is exactly when backlog
+ // piles up, so the first successful page is often full: emitting
+ // here would announce "the list is authoritative now" while
+ // thousands of events are still queued behind it.
+ if (page.length < BACKLOG_PAGE && emitCaughtUp()) degradedCaughtUp = false;
+ return;
+ }
+ if (!backlogDone && page.length < BACKLOG_PAGE) markCaughtUp();
+ } catch {
+ // Before initial catch-up, retain backlog mode and retry. Only after
+ // three consecutive failures do we unblock the UI with an explicit
+ // degraded signal. Live-tail failures simply retry next tick.
+ if (!backlogDone) {
+ consecutiveBacklogFailures += 1;
+ if (consecutiveBacklogFailures >= 3) markCaughtUp(true);
+ }
+ }
+ };
+
+ // Both timer and NOTIFY enter the same serialized gate. If a wakeup
+ // lands during a read, exactly one follow-up read runs after it settles;
+ // concurrent reads could duplicate frames or move the cursor backwards.
+ const requestPoll = (): Promise => {
+ if (closed) return Promise.resolve();
+ if (initializing) {
+ wakeDuringInitialization = true;
+ return Promise.resolve();
+ }
+ if (pollInFlight) {
+ repollRequested = true;
+ return pollInFlight;
+ }
+ pollInFlight = (async () => {
+ do {
+ repollRequested = false;
+ await poll();
+ } while (repollRequested && !closed);
+ })().finally(() => {
+ pollInFlight = null;
+ });
+ return pollInFlight;
+ };
+
+ const tick = () => {
+ if (closed) return;
+ pollTimer = setTimeout(() => {
+ if (closed) return;
+ void requestPoll().then(tick, tick);
+ }, OWNER_EVENT_POLL_INTERVAL_MS);
+ };
+
+ // Retirement is checked on the independent heartbeat, not every event
+ // poll. Owner merges are rare; this caps idle cost at one indexed lookup
+ // per 25s while noticing established stale streams.
+ heartbeatTimer = setInterval(() => {
+ if (closed) return;
+ write(': ping\n\n');
+ if (closed || retirementCheckInFlight) return;
+ retirementCheckInFlight = true;
+ void store
+ .readRetirement(ownerId)
+ .then((newOwnerId) => {
+ if (!newOwnerId || closed) return;
+ // Native EventSource reconnects a clean 200 EOF with the same
+ // Last-Event-ID. The client MUST close this instance, construct a
+ // new EventSource without that cursor, and perform one full session
+ // list reconciliation because session_created omits list fields
+ // such as prompt/stageId.
+ write(
+ `event: owner_moved\ndata: ${JSON.stringify({
+ type: 'owner_moved',
+ newOwnerId,
+ action: 'reconnect',
+ })}\n\n`,
+ );
+ close();
+ })
+ .catch(() => {
+ // A transient PG failure is retried on the next heartbeat.
+ })
+ .finally(() => {
+ retirementCheckInFlight = false;
+ });
+ }, SSE_HEARTBEAT_INTERVAL_MS);
+
+ // Register before the initial read so a commit racing with backlog
+ // exhaustion cannot fall into the 30s fallback window. The callback is
+ // removed on every stream close path together with both timers.
+ unsubscribeWakeup = subscribeAgentEventWakeup({ kind: 'owner', ownerId }, () => {
+ void requestPoll();
+ });
+ await drainBacklog();
+ initializing = false;
+ if (wakeDuringInitialization) await requestPoll();
+ tick();
+ },
+ cancel() {
+ closed = true;
+ clearTimers();
+ },
+ });
+
+ responseHeaders.set('Content-Type', 'text/event-stream; charset=utf-8');
+ responseHeaders.set('Cache-Control', 'no-cache, no-transform');
+ responseHeaders.set('Connection', 'keep-alive');
+ return new Response(stream, { headers: responseHeaders });
+}
diff --git a/app/api/agent/runtime/route.ts b/app/api/agent/runtime/route.ts
new file mode 100644
index 0000000..8b61f15
--- /dev/null
+++ b/app/api/agent/runtime/route.ts
@@ -0,0 +1,25 @@
+/**
+ * Server-side agent runtime status probe.
+ *
+ * GET /api/agent/runtime -> { enabled: boolean, runtimeEnabled: boolean }
+ *
+ * `enabled` reports usability, not intent: the workbench client gates its
+ * entry on this field, so it is true only when the runtime can actually serve
+ * a request — the flag AND a `DATABASE_URL` (the runner and every
+ * persistence-touching route need the store). `runtimeEnabled` carries the
+ * raw intent flag so a client can tell "off by choice" (`runtimeEnabled:
+ * false`) from "on but unusable" (`runtimeEnabled: true`, missing
+ * DATABASE_URL).
+ */
+import { isAgentRuntimeConfigured, isAgentRuntimeEnabled } from '@/lib/config/feature-flags';
+
+export const runtime = 'nodejs';
+
+export async function GET() {
+ // Intentionally no materials flag: isAgentMaterialsEnabled does not exist in
+ // this repo (the materials routes gate on the runtime, like the stages).
+ return Response.json({
+ enabled: isAgentRuntimeConfigured(),
+ runtimeEnabled: isAgentRuntimeEnabled(),
+ });
+}
diff --git a/app/api/agent/sessions/[id]/cancel/route.ts b/app/api/agent/sessions/[id]/cancel/route.ts
new file mode 100644
index 0000000..e8f1781
--- /dev/null
+++ b/app/api/agent/sessions/[id]/cancel/route.ts
@@ -0,0 +1,45 @@
+/**
+ * Agent runtime control plane for cancellation.
+ *
+ * The route makes the request durable. The lease holder observes it and
+ * writes the terminal event, keeping the event log single-writer.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+export async function POST(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getAgentSessionStore();
+ const meta = await store.getSession(id);
+ if (!meta || meta.ownerId !== ownerId) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+ if (meta.status === 'succeeded' || meta.status === 'failed' || meta.status === 'cancelled') {
+ return NextResponse.json(
+ {
+ code: 'SESSION_ALREADY_TERMINAL',
+ status: meta.status,
+ error: `session is already ${meta.status}`,
+ },
+ { status: 409, headers: responseHeaders },
+ );
+ }
+
+ await store.requestCancel(id);
+ return NextResponse.json(
+ { id, cancelRequested: true },
+ { status: 202, headers: responseHeaders },
+ );
+ });
+}
diff --git a/app/api/agent/sessions/[id]/events/route.ts b/app/api/agent/sessions/[id]/events/route.ts
new file mode 100644
index 0000000..fb3fc68
--- /dev/null
+++ b/app/api/agent/sessions/[id]/events/route.ts
@@ -0,0 +1,300 @@
+/**
+ * Agent runtime control plane — the session event stream (SSE).
+ *
+ * GET /api/agent/sessions/:id/events
+ * Honors `Last-Event-ID` (header or `?lastEventId=`): everything durable
+ * with `seq > lastEventId` is replayed first (intermediate `message_update`
+ * tokens are dropped; the last update in each run already has the full
+ * text), then whatever lands afterwards. A client attaching mid-run and
+ * one attaching between runs take the exact same path. The log is the
+ * single source of truth; the live stream is just its tail.
+ *
+ * Frames:
+ * - one `caught_up` event when the backlog has been drained (a real, named
+ * event rather than a comment, which `EventSource` would drop). A
+ * `degraded: true` caught_up is not authoritative and asks the client to
+ * schedule a full reconciliation; recovery emits one plain caught_up;
+ * - runner/pi/control-plane events as `id:` + `event:` + `data:`.
+ *
+ * The stream does NOT close at `session_end`: a session is a long-lived
+ * conversation (continuous chat), and a run boundary is just another frame.
+ * The attach ends when the client disconnects or an HTTP intermediary cuts
+ * the stream. Native `EventSource` then reconnects with `Last-Event-ID` and
+ * resumes through the same replay path without losing durable events.
+ *
+ * Access model: there is no per-route auth challenge. Every request is
+ * granted an anonymous cookie identity, and every store read is scoped to
+ * that identity. A session owned by another identity is indistinguishable
+ * from a missing one — both are 404 with the same response.
+ *
+ * This handler is a pure READER of the store. A disconnect closes this
+ * reader and nothing else: the runner keeps running, and its events keep
+ * landing in the log.
+ */
+import type { PersistedAgentSessionEvent } from '@openmaic/storage';
+import type { NextRequest } from 'next/server';
+
+import { HOST_AGENT_LIFECYCLE as LIFECYCLE } from '@/lib/agent-runtime/lifecycle';
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { subscribeAgentEventWakeup } from '@/lib/server/agent-runtime/event-notify-bus';
+import { resolveRequestOwnerId } from '@/lib/server/agent-runtime/owner';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+
+export const runtime = 'nodejs';
+// Self-hosted `next start` does not enforce maxDuration; it remains useful to
+// Vercel's build adapter. EventSource resumes durable events with Last-Event-ID.
+// The 25s heartbeat prevents idle intermediaries from ending the stream early.
+export const maxDuration = 300;
+
+// LISTEN/NOTIFY supplies low latency. Polling remains an explicit correctness
+// fallback for notifications lost during disconnects; terminal streams retain
+// their longer backoff.
+export const POLL_INTERVAL_MS = 5_000;
+// Terminal streams poll less often than active ones, but 10s is the ceiling.
+// The worst case is "session already terminal -> user steers": this is exactly
+// the moment the user is waiting for the result. Terminal streams exist only
+// while the user actually has that session open, so the extra cost is small.
+export const TERMINAL_POLL_INTERVAL_MS = 10_000;
+const HEARTBEAT_INTERVAL_MS = 25_000;
+/** Same default as `readEventsAfter`. A full page means more backlog remains. */
+const BACKLOG_PAGE = 500;
+
+export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+ const { id } = await params;
+ const responseHeaders = new Headers();
+ // The identity cookie is minted for the requester regardless of the target
+ // session, and the owner is resolved before the session lookup: a request
+ // for a missing session and one for a session owned by someone else return
+ // byte-identical 404s (same status, body, and cookie headers), so the
+ // response cannot be used to probe whether a session UUID exists. This
+ // slice resolves only the anonymous cookie identity; a future auth
+ // integration must thread `authenticatedOwnerId` through here, or sessions
+ // created under authenticated identities would be unreachable by their own
+ // owner.
+ const ownerId = resolveRequestOwnerId(req, responseHeaders);
+ const store = await getAgentSessionStore();
+ const meta = await store.getSession(id);
+ if (!meta) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+ if (meta.ownerId !== ownerId) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+
+ const url = new URL(req.url);
+ const headerId = req.headers.get('last-event-id');
+ const lastEventId = Number(headerId ?? url.searchParams.get('lastEventId') ?? 0) || 0;
+
+ const encoder = new TextEncoder();
+ let pollTimer: ReturnType | null = null;
+ let heartbeatTimer: ReturnType | null = null;
+ let unsubscribeWakeup: (() => void) | null = null;
+ // Hoisted so cancel() can stop an in-flight-then-scheduled poll, not just
+ // the timer: after a client disconnect, `closed` makes every later poll a
+ // no-op and `write` a dead end.
+ let closed = false;
+
+ const clearTimers = () => {
+ if (pollTimer) clearTimeout(pollTimer);
+ if (heartbeatTimer) clearInterval(heartbeatTimer);
+ pollTimer = null;
+ heartbeatTimer = null;
+ unsubscribeWakeup?.();
+ unsubscribeWakeup = null;
+ };
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ let backlogDone = false;
+ let sentSinceAttach = 0;
+ let cursor = lastEventId;
+ let terminal = false;
+ let consecutiveBacklogFailures = 0;
+ let degradedCaughtUp = false;
+ let initializing = true;
+ let wakeDuringInitialization = false;
+ let repollRequested = false;
+ let pollInFlight: Promise | null = null;
+
+ const write = (chunk: string) => {
+ if (closed) return false;
+ try {
+ controller.enqueue(encoder.encode(chunk));
+ return true;
+ } catch {
+ // A broken socket is not guaranteed to invoke cancel() in every
+ // runtime. Stop both timers as soon as enqueue proves it is closed.
+ closed = true;
+ clearTimers();
+ return false;
+ }
+ };
+
+ // "You are caught up" is a real, named SSE event, not a comment: a
+ // client attaching during a long tool call would otherwise sit on
+ // "replaying" until the next event, and a re-attach at the last event
+ // id of an idle session would receive zero frames and wait forever.
+ const emitCaughtUp = (degraded = false) =>
+ write(
+ `event: caught_up\ndata: ${JSON.stringify({
+ type: 'caught_up',
+ replayed: sentSinceAttach,
+ fromEventId: lastEventId,
+ ...(degraded ? { degraded: true } : {}),
+ })}\n\n`,
+ );
+
+ const markCaughtUp = (degraded = false) => {
+ if (backlogDone) return;
+ if (!emitCaughtUp(degraded)) return;
+ backlogDone = true;
+ degradedCaughtUp = degraded;
+ };
+
+ const writePage = (events: PersistedAgentSessionEvent[]) => {
+ for (const event of events) {
+ if (
+ !write(
+ `id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify({
+ ...event,
+ // A degraded catch-up set `backlogDone` without draining, so
+ // events arriving while recovering are still history: keep
+ // labelling them backlog until the real signal goes out.
+ phase: backlogDone && !degradedCaughtUp ? 'live' : 'backlog',
+ })}\n\n`,
+ )
+ ) {
+ return false;
+ }
+ cursor = event.id;
+ sentSinceAttach += 1;
+ const data = event.data as { status?: unknown } | null;
+ const isTerminalEnd =
+ event.type === LIFECYCLE.sessionEnd &&
+ (data?.status === 'succeeded' ||
+ data?.status === 'failed' ||
+ data?.status === 'cancelled');
+ // A terminal session_end is normally the last frame. Any later
+ // durable frame proves activity resumed (usually user_message then
+ // session_start/session_resumed), so polling switches both ways.
+ if (isTerminalEnd) terminal = true;
+ else if (terminal) terminal = false;
+ }
+ return true;
+ };
+
+ const drainBacklog = async () => {
+ for (;;) {
+ if (closed) return;
+ let page;
+ try {
+ page = await store.readEventsAfterForReplay(id, cursor, BACKLOG_PAGE);
+ } catch {
+ consecutiveBacklogFailures += 1;
+ if (consecutiveBacklogFailures >= 3) markCaughtUp(true);
+ return;
+ }
+ consecutiveBacklogFailures = 0;
+ if (!writePage(page.events)) return;
+ // Pagination judges by the RAW page size (`scanned`), not the
+ // compacted length: a page of pure message_update compacts to two
+ // frames and would otherwise look "exhausted" mid-log.
+ if (page.scanned < BACKLOG_PAGE) break;
+ }
+ markCaughtUp();
+ };
+
+ const poll = async () => {
+ if (closed) return;
+ let page;
+ try {
+ page = await store.readEventsAfterForReplay(id, cursor, BACKLOG_PAGE);
+ } catch {
+ if (!backlogDone) {
+ consecutiveBacklogFailures += 1;
+ if (consecutiveBacklogFailures >= 3) markCaughtUp(true);
+ }
+ return; // transient PG hiccup — the next poll retries
+ }
+ consecutiveBacklogFailures = 0;
+ if (!writePage(page.events)) return;
+ if (degradedCaughtUp) {
+ // Same exhaustion check as the normal path below: a degraded window
+ // is when backlog piles up, so the first successful page is often
+ // full and announcing catch-up there would be another lie.
+ if (page.scanned < BACKLOG_PAGE && emitCaughtUp()) degradedCaughtUp = false;
+ return;
+ }
+ if (!backlogDone && page.scanned < BACKLOG_PAGE) markCaughtUp();
+ };
+
+ const requestPoll = (): Promise => {
+ if (closed) return Promise.resolve();
+ if (initializing) {
+ wakeDuringInitialization = true;
+ return Promise.resolve();
+ }
+ if (pollInFlight) {
+ repollRequested = true;
+ return pollInFlight;
+ }
+ pollInFlight = (async () => {
+ do {
+ repollRequested = false;
+ await poll();
+ } while (repollRequested && !closed);
+ })().finally(() => {
+ pollInFlight = null;
+ });
+ return pollInFlight;
+ };
+
+ // Serialized polling: the next poll is scheduled only after the
+ // previous one has SETTLED, so a PG read slower than the interval can
+ // never start a second concurrent poll. Two in-flight polls share the
+ // cursor and would emit duplicate frames — worse, the slower one would
+ // rewind the cursor for the poll after it.
+ const tick = () => {
+ if (closed) return;
+ // An idle historical session may wait up to 10 seconds for its first
+ // reactivation frame; the user action already has optimistic UI. Once
+ // that frame arrives, the next read returns to the 5s cadence.
+ const interval = terminal ? TERMINAL_POLL_INTERVAL_MS : POLL_INTERVAL_MS;
+ pollTimer = setTimeout(() => {
+ if (closed) return;
+ // Reschedule only after poll settles. tick then re-reads terminal, so
+ // a reactivation discovered by this poll restores the 5s cadence.
+ void requestPoll().then(tick, tick);
+ }, interval);
+ };
+
+ write(`: replaying from event ${lastEventId}\n\n`);
+ heartbeatTimer = setInterval(() => {
+ if (closed) return;
+ write(': ping\n\n');
+ }, HEARTBEAT_INTERVAL_MS);
+ // Register before the initial read so a commit racing with backlog
+ // exhaustion cannot fall into the 5s fallback window. The callback is
+ // removed on every stream close path together with both timers.
+ unsubscribeWakeup = subscribeAgentEventWakeup({ kind: 'session', sessionId: id }, () => {
+ void requestPoll();
+ });
+ await drainBacklog();
+ initializing = false;
+ if (wakeDuringInitialization) await requestPoll();
+ tick();
+ },
+ cancel() {
+ closed = true;
+ clearTimers();
+ },
+ });
+
+ responseHeaders.set('Content-Type', 'text/event-stream; charset=utf-8');
+ responseHeaders.set('Cache-Control', 'no-cache, no-transform');
+ responseHeaders.set('Connection', 'keep-alive');
+ return new Response(stream, { headers: responseHeaders });
+}
diff --git a/app/api/agent/sessions/[id]/messages/route.ts b/app/api/agent/sessions/[id]/messages/route.ts
new file mode 100644
index 0000000..e663928
--- /dev/null
+++ b/app/api/agent/sessions/[id]/messages/route.ts
@@ -0,0 +1,122 @@
+/** Agent runtime control plane for durable follow-up messages. */
+import { AgentSessionAccessError } from '@openmaic/storage';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { apiError } from '@/lib/server/api-response';
+import { MAX_SESSION_TEXT_LENGTH } from '@/lib/server/agent-runtime/limits';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import { decodeElementRefs } from '@/lib/workbench/element-refs';
+import { decodeCourseRefs } from '@/lib/workbench/course-refs';
+import {
+ bindOwnerMaterialsToSession,
+ SessionMaterialBindingError,
+} from '@/lib/server/agent-runtime/session-materials';
+
+export const runtime = 'nodejs';
+
+export async function POST(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getAgentSessionStore();
+ const meta = await store.getSession(id);
+ if (!meta || meta.ownerId !== ownerId) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+
+ let body: {
+ text?: string;
+ materialIds?: unknown;
+ elementRefs?: unknown;
+ courseRefs?: unknown;
+ } = {};
+ try {
+ body = ((await req.json()) ?? {}) as typeof body;
+ } catch {
+ const response = apiError('INVALID_REQUEST', 400, 'invalid JSON body');
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+
+ const text = (body.text ?? '').toString().trim();
+ if (
+ body.materialIds !== undefined &&
+ (!Array.isArray(body.materialIds) || body.materialIds.some((id) => typeof id !== 'string'))
+ ) {
+ const response = apiError('INVALID_REQUEST', 400, 'materialIds must be an array of strings');
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+ const materialIds = [...new Set((body.materialIds ?? []).map((id: string) => id.trim()))];
+ if (materialIds.length > 20 || materialIds.some((id) => !id)) {
+ const response = apiError('INVALID_REQUEST', 400, 'materialIds are invalid');
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+ const decodedElementRefs = decodeElementRefs(body.elementRefs ?? []);
+ if (!decodedElementRefs.ok) {
+ const response = apiError('INVALID_REQUEST', 400, decodedElementRefs.error);
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+ const decodedCourseRefs = decodeCourseRefs(body.courseRefs ?? []);
+ if (!decodedCourseRefs.ok) {
+ const response = apiError('INVALID_REQUEST', 400, decodedCourseRefs.error);
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+ if (!text && materialIds.length === 0) {
+ const response = apiError('MISSING_REQUIRED_FIELD', 400, 'text is required');
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+ if (text.length > MAX_SESSION_TEXT_LENGTH) {
+ const response = apiError(
+ 'INVALID_REQUEST',
+ 400,
+ `text exceeds the ${MAX_SESSION_TEXT_LENGTH} character limit`,
+ );
+ responseHeaders.forEach((value, name) => response.headers.append(name, value));
+ return response;
+ }
+
+ try {
+ const materials = materialIds.length
+ ? await bindOwnerMaterialsToSession(id, ownerId, materialIds)
+ : [];
+ const posted = await store.postUserMessage(
+ id,
+ {
+ text,
+ ...(materials.length ? { materials } : {}),
+ ...(decodedElementRefs.refs.length ? { elementRefs: decodedElementRefs.refs } : {}),
+ ...(decodedCourseRefs.refs.length ? { courseRefs: decodedCourseRefs.refs } : {}),
+ },
+ { expectedOwnerId: ownerId },
+ );
+ return NextResponse.json(
+ {
+ id,
+ message: { seq: posted.seq, text, delivery: posted.delivery },
+ elementRefsAccepted: decodedElementRefs.refs.length > 0,
+ courseRefsAccepted: decodedCourseRefs.refs.length > 0,
+ },
+ { status: 202, headers: responseHeaders },
+ );
+ } catch (error) {
+ if (error instanceof SessionMaterialBindingError) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+ if (error instanceof AgentSessionAccessError) {
+ return new Response('Forbidden', { status: 403, headers: responseHeaders });
+ }
+ throw error;
+ }
+ });
+}
diff --git a/app/api/agent/sessions/[id]/route.ts b/app/api/agent/sessions/[id]/route.ts
new file mode 100644
index 0000000..06a83cc
--- /dev/null
+++ b/app/api/agent/sessions/[id]/route.ts
@@ -0,0 +1,25 @@
+/** Agent runtime control plane for reading one owned session. */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getAgentSessionStore();
+ const meta = await store.getSession(id);
+ if (!meta || meta.ownerId !== ownerId) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+ return NextResponse.json(meta, { headers: responseHeaders });
+ });
+}
diff --git a/app/api/agent/sessions/route.ts b/app/api/agent/sessions/route.ts
new file mode 100644
index 0000000..ad88cb9
--- /dev/null
+++ b/app/api/agent/sessions/route.ts
@@ -0,0 +1,196 @@
+/**
+ * Agent runtime control plane for session creation and listing.
+ *
+ * These handlers only use the durable session store. A separately running
+ * worker claims queued sessions after the request has returned.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { apiError } from '@/lib/server/api-response';
+import { MAX_SESSION_TEXT_LENGTH } from '@/lib/server/agent-runtime/limits';
+import { findSkill, inferSkillIdFromPrompt, listSkills } from '@/lib/server/agent-runtime/skills';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+import {
+ bindOwnerMaterialsToSession,
+ SessionMaterialBindingError,
+} from '@/lib/server/agent-runtime/session-materials';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import { buildRequestOrigin, isValidClassroomId } from '@/lib/server/classroom-storage';
+import { decodeCourseRefs } from '@/lib/workbench/course-refs';
+
+export const runtime = 'nodejs';
+
+interface CreateSessionBody {
+ prompt?: string;
+ stageId?: string;
+ skill?: string;
+ /** Attach to an already-built classroom instead of starting a new course. */
+ existingCourse?: boolean;
+ /** Existing owner-library uploads to bind before the first run is queued. */
+ materialIds?: unknown;
+ /** Classrooms named on the opening message. */
+ courseRefs?: unknown;
+}
+
+export async function POST(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+
+ let body: CreateSessionBody = {};
+ try {
+ body = ((await req.json()) ?? {}) as CreateSessionBody;
+ } catch {
+ return apiError('INVALID_REQUEST', 400, 'invalid JSON body');
+ }
+
+ const existingCourse = body.existingCourse === true;
+ const stageId = body.stageId?.toString().trim() || undefined;
+ if (existingCourse && !stageId) {
+ return apiError('MISSING_REQUIRED_FIELD', 400, 'existingCourse requires stageId');
+ }
+ if (existingCourse && stageId && !isValidClassroomId(stageId)) {
+ return apiError('INVALID_REQUEST', 400, 'existingCourse stageId has an invalid format');
+ }
+
+ const prompt =
+ (body.prompt ?? '').toString().trim() || (existingCourse ? (stageId ?? 'existing-course') : '');
+ if (!prompt) {
+ return apiError('MISSING_REQUIRED_FIELD', 400, 'prompt is required');
+ }
+ if (prompt.length > MAX_SESSION_TEXT_LENGTH) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ `prompt exceeds the ${MAX_SESSION_TEXT_LENGTH} character limit`,
+ );
+ }
+ if (
+ body.materialIds !== undefined &&
+ (!Array.isArray(body.materialIds) || body.materialIds.some((id) => typeof id !== 'string'))
+ ) {
+ return apiError('INVALID_REQUEST', 400, 'materialIds must be an array of strings');
+ }
+ const materialIds = [...new Set(((body.materialIds ?? []) as string[]).map((id) => id.trim()))];
+ if (materialIds.length > 20 || materialIds.some((id) => !id)) {
+ return apiError('INVALID_REQUEST', 400, 'materialIds are invalid');
+ }
+ if (existingCourse && materialIds.length > 0) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ 'existingCourse does not accept attachments; send them on the first message instead',
+ );
+ }
+ const decodedCourseRefs = decodeCourseRefs(body.courseRefs ?? []);
+ if (!decodedCourseRefs.ok) {
+ return apiError('INVALID_REQUEST', 400, decodedCourseRefs.error);
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ // An EXPLICIT skill — a `?skill=` launch link, not composer UI — is
+ // rejected here rather than at claim time: a session created with a typo'd
+ // skill would otherwise sit queued and then quietly build an ordinary
+ // conversation. The runner's `findSkill` matches a reference by id OR name
+ // (a user skill's natural handle is `name`, `my-*`), so the route validates
+ // with the same lookup and freezes the resolved id.
+ let explicitSkillId = (body.skill ?? '').toString().trim() || undefined;
+ if (explicitSkillId) {
+ const found = await findSkill(explicitSkillId, ownerId);
+ if (!found) {
+ const known = await listSkills(ownerId);
+ return new NextResponse(
+ JSON.stringify({
+ success: false as const,
+ errorCode: 'INVALID_REQUEST',
+ error: `unknown skill "${explicitSkillId}"; installed: ${
+ known.map((s) => s.id).join(', ') || '(none)'
+ }`,
+ }),
+ { status: 400, headers: responseHeaders },
+ );
+ }
+ explicitSkillId = found.id;
+ }
+ /**
+ * Otherwise, read the skill off the message itself.
+ *
+ * Skills are written as `/handle` TEXT — there is no chip and no skill
+ * field in the UI, because an input box is an input box. Nothing needs to
+ * parse that text for the agent (skills are listed in the system prompt
+ * and opened with pi's native `read`), but the session's `skillId` still
+ * feeds the outline-constraint pointer. So the SERVER recognises the
+ * structure in the text and records it.
+ *
+ * Forgiving by design: an unrecognised handle simply means no skill — never
+ * an error, never a fallback to a default — and the text stays in the
+ * prompt either way, so the model still sees what the user asked for.
+ */
+ const skillId = explicitSkillId ?? (await inferSkillIdFromPrompt(prompt, ownerId));
+
+ // Upstream classrooms do not carry an owner partition, so existing-course
+ // sessions validate only the identifier format here. Full existence and
+ // ownership validation is deferred until a later slice consumes stageId —
+ // the upstream document store has no owner partition yet.
+ const store = await getAgentSessionStore();
+ const hasOpeningContext = materialIds.length > 0 || decodedCourseRefs.refs.length > 0;
+ const meta = await store.createSession({
+ ownerId,
+ prompt,
+ ...(stageId ? { stageId } : {}),
+ ...(skillId ? { skillId } : {}),
+ existingCourse,
+ origin: buildRequestOrigin(req),
+ // Keep the runner from claiming the session until its opening materials
+ // and references are durable. postUserMessage below atomically requeues it.
+ ...(existingCourse || hasOpeningContext ? { status: 'succeeded' as const } : {}),
+ });
+
+ if (!hasOpeningContext) {
+ return NextResponse.json(meta, { status: 202, headers: responseHeaders });
+ }
+
+ try {
+ const materials = materialIds.length
+ ? await bindOwnerMaterialsToSession(meta.id, ownerId, materialIds)
+ : [];
+ await store.postUserMessage(
+ meta.id,
+ {
+ text: prompt,
+ ...(materials.length ? { materials } : {}),
+ ...(decodedCourseRefs.refs.length ? { courseRefs: decodedCourseRefs.refs } : {}),
+ },
+ { expectedOwnerId: ownerId },
+ );
+ return NextResponse.json(
+ {
+ ...meta,
+ status: 'queued',
+ ...(decodedCourseRefs.refs.length ? { courseRefs: decodedCourseRefs.refs } : {}),
+ },
+ { status: 202, headers: responseHeaders },
+ );
+ } catch (error) {
+ await store.softDeleteSession(meta.id, ownerId).catch(() => false);
+ if (error instanceof SessionMaterialBindingError) {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+ throw error;
+ }
+ });
+}
+
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const store = await getAgentSessionStore();
+ const sessions = await store.listSessionsByOwner(ownerId);
+ return NextResponse.json(sessions, { headers: responseHeaders });
+ });
+}
diff --git a/app/api/agent/sessions/status/route.ts b/app/api/agent/sessions/status/route.ts
new file mode 100644
index 0000000..42a5a1e
--- /dev/null
+++ b/app/api/agent/sessions/status/route.ts
@@ -0,0 +1,20 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getAgentSessionStore } from '@/lib/server/agent-runtime/store';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+/** Return a sparse status map for all sessions visible to this owner. */
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const store = await getAgentSessionStore();
+ const sessions = await store.listSessionsByOwner(ownerId);
+ const statuses = Object.fromEntries(sessions.map((session) => [session.id, session.status]));
+ return NextResponse.json(statuses, { headers: responseHeaders });
+ });
+}
diff --git a/app/api/agent/skills/[id]/route.ts b/app/api/agent/skills/[id]/route.ts
new file mode 100644
index 0000000..2ad2596
--- /dev/null
+++ b/app/api/agent/skills/[id]/route.ts
@@ -0,0 +1,50 @@
+/**
+ * One user-owned Skill body, without bloating the global picker payload.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import {
+ deleteUserSkill,
+ findUserSkill,
+ UserSkillError,
+} from '@/lib/server/agent-runtime/user-skills';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const skill = await findUserSkill(id, ownerId);
+ if (!skill) return new Response('Not found', { status: 404 });
+ return NextResponse.json(
+ { id: skill.id, content: skill.content },
+ { headers: responseHeaders },
+ );
+ });
+}
+
+export async function DELETE(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ if (!id.startsWith('usk_')) {
+ return new Response('Built-in skills cannot be deleted.', {
+ status: 405,
+ headers: responseHeaders,
+ });
+ }
+ try {
+ await deleteUserSkill(ownerId, id);
+ return new Response(null, { status: 204, headers: responseHeaders });
+ } catch (error) {
+ if (error instanceof UserSkillError && error.code === 'not-found') {
+ return new Response('Not found', { status: 404, headers: responseHeaders });
+ }
+ throw error;
+ }
+ });
+}
diff --git a/app/api/agent/skills/route.ts b/app/api/agent/skills/route.ts
new file mode 100644
index 0000000..805539b
--- /dev/null
+++ b/app/api/agent/skills/route.ts
@@ -0,0 +1,101 @@
+/**
+ * Agent runtime control plane — the installed skills.
+ *
+ * GET /api/agent/skills -> [{ id, name, title, description, hasConstraints, source }]
+ *
+ * Drives the `/` picker (a skill the user names there becomes the session's
+ * user-locked skill at creation). `title` is the skill's display name from its
+ * frontmatter; every surface shows it beside the id, which stays the English
+ * contract.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { listSkills } from '@/lib/server/agent-runtime/skills';
+import { createUserSkill, UserSkillError } from '@/lib/server/agent-runtime/user-skills';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import {
+ parseUserSkillMarkdown,
+ parseUserSkillZip,
+ UserSkillUploadError,
+} from '@/lib/server/skill-export';
+
+export const runtime = 'nodejs';
+
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) {
+ return new Response('Not found', { status: 404 });
+ }
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const skills = await listSkills(ownerId);
+ return NextResponse.json(
+ skills.map((s) => ({
+ id: s.id,
+ name: s.name,
+ ...(s.title ? { title: s.title } : {}),
+ description: s.description,
+ hasConstraints: !!s.constraints,
+ source: s.source,
+ })),
+ { headers: responseHeaders },
+ );
+ });
+}
+
+/** Upload one owner Skill as the exporter zip or a bare canonical SKILL.md. */
+export async function POST(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ try {
+ const form = await req.formData();
+ const upload = form.get('file');
+ if (!upload || typeof upload === 'string' || typeof upload.arrayBuffer !== 'function') {
+ return new Response('A skill file is required.', {
+ status: 400,
+ headers: responseHeaders,
+ });
+ }
+ const bytes = Buffer.from(await upload.arrayBuffer());
+ // Exported owner zips are at most a little over the 64 KiB content cap.
+ // Bound compressed input before JSZip expands it; field validation below
+ // remains the authoritative create limit after parsing.
+ if (bytes.byteLength > 1_048_576) {
+ return new Response('The skill upload is too large.', {
+ status: 413,
+ headers: responseHeaders,
+ });
+ }
+ const input = upload.name.toLowerCase().endsWith('.zip')
+ ? await parseUserSkillZip(bytes)
+ : parseUserSkillMarkdown(bytes.toString('utf8'));
+ const skill = await createUserSkill(ownerId, input);
+ return NextResponse.json(
+ {
+ id: skill.id,
+ name: skill.name,
+ title: skill.title,
+ description: skill.description,
+ hasConstraints: false,
+ source: 'user',
+ },
+ { status: 201, headers: responseHeaders },
+ );
+ } catch (error) {
+ if (error instanceof UserSkillError) {
+ const status = error.code === 'duplicate' || error.code === 'quota' ? 409 : 400;
+ return NextResponse.json(
+ { error: error.code, message: error.message },
+ { status, headers: responseHeaders },
+ );
+ }
+ if (error instanceof UserSkillUploadError) {
+ return NextResponse.json(
+ { error: 'invalid-upload', message: error.message },
+ { status: 400, headers: responseHeaders },
+ );
+ }
+ throw error;
+ }
+ });
+}
diff --git a/app/api/extract-document/route.ts b/app/api/extract-document/route.ts
index 9d4f0fd..63925f1 100644
--- a/app/api/extract-document/route.ts
+++ b/app/api/extract-document/route.ts
@@ -228,19 +228,26 @@ async function runExtraction(
// flattened to the same text shape documents produce. Same route, same
// downstream generation path.
if (SUPPORTED_MEDIA_MIME_TYPES.includes(mimeType)) {
- logState.resolvedProviderId = requestConfig.providerId || 'alidocmind';
+ logState.resolvedProviderId = requestConfig.providerId || '';
// Reject a document-only provider (e.g. unpdf/mineru) for a media upload
// with a clear 4xx instead of forwarding it into the media registry and
// surfacing an opaque 500.
- const mediaProvider = getMediaExtractorProvider(logState.resolvedProviderId);
- if (!mediaProvider || !mediaProvider.supportedMimeTypes.includes(mimeType)) {
+ const mediaProvider = requestConfig.providerId
+ ? getMediaExtractorProvider(requestConfig.providerId)
+ : undefined;
+ if (
+ requestConfig.providerId &&
+ (!mediaProvider || !mediaProvider.supportedMimeTypes.includes(mimeType))
+ ) {
return apiError(
'INVALID_REQUEST',
400,
- `Provider "${logState.resolvedProviderId}" cannot extract ${mimeType}. Choose a media-capable provider (e.g. AliDocMind).`,
+ `Provider "${requestConfig.providerId}" cannot extract ${mimeType}. Choose a media-capable provider (AliDocMind or local ffmpeg).`,
);
}
- const mediaManaged = isServerConfiguredProvider('pdf', logState.resolvedProviderId);
+ const mediaManaged =
+ requestConfig.providerId !== 'local-ffmpeg' &&
+ isServerConfiguredProvider('pdf', 'alidocmind');
// When managed, resolve the server-owned AK/SK (env OR YAML) explicitly so
// a YAML-only deployment works — the client-level env fallback reads env
// vars only. Client-entered creds are used only when unmanaged.
@@ -260,7 +267,7 @@ async function runExtraction(
fileSize,
mimeType,
config: {
- providerId: logState.resolvedProviderId,
+ providerId: requestConfig.providerId || '',
apiKey: mediaManaged ? undefined : requestConfig.apiKey || undefined,
baseUrl: mediaManaged ? mediaManagedCreds?.baseUrl : mediaClientBaseUrl,
accessKeyId: mediaManaged
@@ -274,6 +281,8 @@ async function runExtraction(
allowEnvFallback: mediaManaged,
},
});
+ logState.resolvedProviderId =
+ mediaArtifact.metadata.providerId || requestConfig.providerId || '';
const mediaText = mediaArtifactToText(mediaArtifact);
// An artifact with no transcript, keyframes, or synopsis carries no usable
diff --git a/app/api/folders/[id]/route.ts b/app/api/folders/[id]/route.ts
new file mode 100644
index 0000000..de5be9d
--- /dev/null
+++ b/app/api/folders/[id]/route.ts
@@ -0,0 +1,121 @@
+/**
+ * PATCH /api/folders/[id] — rename { name }
+ * DELETE /api/folders/[id]?mode=ungroup|remove — delete a folder
+ *
+ * `mode=ungroup` (default): the folder is dropped and its courses become
+ * unfiled. `mode=remove`: the folder is dropped and the captured member
+ * course ids are returned, so the caller can run its own cascade (the
+ * workbench deletes the owner courses it captured).
+ *
+ * Every handler is owner-scoped exactly like the other workbench routes (see
+ * `app/api/folders/route.ts`), and the whole family is gated on the
+ * configured runtime.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import type { DocumentFolder, DocumentFolderStore } from '@openmaic/storage';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerJson } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import { folderNameErrorResponse } from '@/lib/server/folder-name-errors';
+import { validateFolderName } from '@/lib/utils/folder-name-validation';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+/** The wire shape is the reference's `FolderItem`; see `app/api/folders/route.ts`. */
+function folderResponse(folder: DocumentFolder, userKey: string) {
+ return { ...folder, userKey };
+}
+
+function jsonError(status: number, code: string, message: string, headers?: Headers): NextResponse {
+ return NextResponse.json({ error: { code, message } }, { status, headers });
+}
+
+// PATCH /api/folders/[id] — rename { name }.
+export async function PATCH(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return jsonError(400, 'INVALID_BODY', 'request body must be JSON');
+ }
+ const name = (body as { name?: unknown })?.name;
+ if (typeof name !== 'string') {
+ return jsonError(400, 'FOLDER_NAME_INVALID', 'name must be a string');
+ }
+ const trimmed = name.trim();
+ const check = validateFolderName(trimmed);
+ if (!check.ok) {
+ return jsonError(
+ 400,
+ check.kind === 'empty' ? 'FOLDER_NAME_EMPTY' : 'FOLDER_NAME_TOO_LONG',
+ check.kind === 'empty' ? 'folder name must not be empty' : 'folder name is too long',
+ );
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ try {
+ const store = (await getOwnerScopedDocumentStore(ownerId)) as unknown as DocumentFolderStore;
+ // Excluding itself, same case-insensitive rule as create.
+ const existing = await store.listFolders();
+ const clash = existing.some(
+ (folder) => folder.id !== id && folder.name.toLowerCase() === trimmed.toLowerCase(),
+ );
+ if (clash) {
+ return jsonError(
+ 409,
+ 'FOLDER_NAME_DUPLICATE',
+ 'a folder with this name already exists',
+ responseHeaders,
+ );
+ }
+
+ const updated = await store.renameFolder(id, trimmed);
+ if (!updated) {
+ return jsonError(404, 'FOLDER_NOT_FOUND', 'folder not found', responseHeaders);
+ }
+ return ownerJson({ folder: folderResponse(updated, ownerId) }, 200, responseHeaders);
+ } catch (error) {
+ // The rename re-checks the name through the unique index; a duplicate
+ // that slipped past the pre-check answers the same 409.
+ const nameError = folderNameErrorResponse(error);
+ if (nameError) {
+ for (const [key, value] of responseHeaders) nameError.headers.append(key, value);
+ return nameError;
+ }
+ console.error(`[Folders] Failed to rename [owner=${ownerId}, id=${id}]:`, error);
+ return jsonError(500, 'FOLDER_RENAME_FAILED', 'Failed to rename folder', responseHeaders);
+ }
+ });
+}
+
+// DELETE /api/folders/[id]?mode=ungroup|remove
+export async function DELETE(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ const modeParam = req.nextUrl.searchParams.get('mode');
+ const mode: 'ungroup' | 'remove' = modeParam === 'remove' ? 'remove' : 'ungroup';
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ try {
+ const store = (await getOwnerScopedDocumentStore(ownerId)) as unknown as DocumentFolderStore;
+ const result = await store.deleteFolder(id, mode);
+ if (!result) {
+ return jsonError(404, 'FOLDER_NOT_FOUND', 'folder not found', responseHeaders);
+ }
+ return ownerJson({ ok: true, removedStageIds: result.removedStageIds }, 200, responseHeaders);
+ } catch (error) {
+ console.error(`[Folders] Failed to delete [owner=${ownerId}, id=${id}]:`, error);
+ return jsonError(500, 'FOLDER_DELETE_FAILED', 'Failed to delete folder', responseHeaders);
+ }
+ });
+}
diff --git a/app/api/folders/members/route.ts b/app/api/folders/members/route.ts
new file mode 100644
index 0000000..9b4c04b
--- /dev/null
+++ b/app/api/folders/members/route.ts
@@ -0,0 +1,73 @@
+/**
+ * POST /api/folders/members — set which folder a course belongs to.
+ *
+ * Body: { stageId: string, folderId: string | null }
+ * folderId = string → file the course into that folder (must belong to the
+ * caller, else 404 FOLDER_NOT_FOUND).
+ * folderId = null → unfile the course (the membership is removed; an
+ * absent membership already means unfiled, so this is
+ * idempotent).
+ *
+ * Membership is a pure (owner, stage) → folder organization row on the
+ * document row — deliberately decoupled from the course list itself (the
+ * document index is the UI's gate), and `stageId` is a soft reference: the
+ * server may delete a stage.
+ *
+ * Owner-scoped and gated exactly like the rest of the folder family.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import type { DocumentFolderStore } from '@openmaic/storage';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerJson } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+function jsonError(status: number, code: string, message: string, headers?: Headers): NextResponse {
+ return NextResponse.json({ error: { code, message } }, { status, headers });
+}
+
+// POST /api/folders/members
+export async function POST(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return jsonError(400, 'INVALID_BODY', 'request body must be JSON');
+ }
+ const { stageId, folderId } = (body ?? {}) as { stageId?: unknown; folderId?: unknown };
+ if (typeof stageId !== 'string' || stageId.length === 0) {
+ return jsonError(400, 'MISSING_STAGE_ID', 'stageId must be a non-empty string');
+ }
+ if (folderId !== null && (typeof folderId !== 'string' || folderId.length === 0)) {
+ return jsonError(400, 'INVALID_FOLDER_ID', 'folderId must be a non-empty string or null');
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ try {
+ const store = (await getOwnerScopedDocumentStore(ownerId)) as unknown as DocumentFolderStore;
+ const ok = await store.setStageFolder(stageId, folderId);
+ if (!ok) {
+ return jsonError(404, 'FOLDER_NOT_FOUND', 'folder not found', responseHeaders);
+ }
+ return ownerJson({ ok: true }, 200, responseHeaders);
+ } catch (error) {
+ console.error(
+ `[Folders] Failed to set membership [owner=${ownerId}, stage=${stageId}]:`,
+ error,
+ );
+ return jsonError(
+ 500,
+ 'FOLDER_MEMBER_FAILED',
+ 'Failed to set folder membership',
+ responseHeaders,
+ );
+ }
+ });
+}
diff --git a/app/api/folders/route.ts b/app/api/folders/route.ts
new file mode 100644
index 0000000..55dc6f6
--- /dev/null
+++ b/app/api/folders/route.ts
@@ -0,0 +1,117 @@
+/**
+ * GET/POST /api/folders — the workbench's course-folder API (server-side
+ * counterpart of the local `lib/utils/stage-storage.ts` folder API; the
+ * configured runtime routes the seam through these handlers instead of the
+ * Dexie tables).
+ *
+ * Every handler is owner-scoped exactly like the other workbench routes: the
+ * owner resolves from the anonymous cookie (`withRequestOwnerId`) and is never
+ * a request parameter, and all reads and writes go through the owner-bound
+ * document store (`getOwnerScopedDocumentStore`), the same seam the runner
+ * binds for the stage tools. A folder created here is visible to this browser
+ * and to nobody else.
+ *
+ * Name validation is the shared display-width rule (full-width = 2, half-width
+ * = 1, ≤ 40) from `lib/utils/folder-name-validation.ts` — the same module the
+ * client dialogs import, so the two ends cannot drift.
+ *
+ * The configured runtime gates the whole family (see `app/api/stages/route.ts`):
+ * off, or on without a DATABASE_URL, answers the same plain 404.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import type { DocumentFolder, DocumentFolderStore } from '@openmaic/storage';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerJson } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import { folderNameErrorResponse } from '@/lib/server/folder-name-errors';
+import { createFolderForOwner, listFoldersForOwner } from '@/lib/server/folder-persistence';
+import { validateFolderName } from '@/lib/utils/folder-name-validation';
+
+export const runtime = 'nodejs';
+
+/**
+ * The wire shape is the reference's `FolderItem`: the owner id the folder
+ * belongs to (its `userKey`) plus the stored row. The owner-bound store is
+ * partitioned by `owner_id`, which is exactly the reference's `user_key`, so
+ * the request owner IS the folder's user key.
+ */
+function folderResponse(folder: DocumentFolder, userKey: string) {
+ return { ...folder, userKey };
+}
+
+/** The reference's error envelope: `{ error: { code, message } }`. */
+function jsonError(status: number, code: string, message: string, headers?: Headers): NextResponse {
+ return NextResponse.json({ error: { code, message } }, { status, headers });
+}
+
+// GET /api/folders — list the caller's folders, ordered by `order` asc.
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ try {
+ const store = (await getOwnerScopedDocumentStore(ownerId)) as unknown as DocumentFolderStore;
+ const folders = await listFoldersForOwner(store);
+ return ownerJson(
+ { folders: folders.map((folder) => folderResponse(folder, ownerId)) },
+ 200,
+ responseHeaders,
+ );
+ } catch (error) {
+ console.error(`[Folders] Failed to list [owner=${ownerId}]:`, error);
+ return jsonError(500, 'FOLDER_LIST_FAILED', 'Failed to list folders', responseHeaders);
+ }
+ });
+}
+
+// POST /api/folders — create a folder { name }.
+//
+// Validation happens before owner resolution, like the stage routes: a
+// malformed body must not mint an anonymous cookie partition for a request
+// that will not proceed.
+export async function POST(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return jsonError(400, 'INVALID_BODY', 'request body must be JSON');
+ }
+ const name = (body as { name?: unknown })?.name;
+ if (typeof name !== 'string') {
+ return jsonError(400, 'FOLDER_NAME_INVALID', 'name must be a string');
+ }
+ const trimmed = name.trim();
+ const check = validateFolderName(trimmed);
+ if (!check.ok) {
+ return jsonError(
+ 400,
+ check.kind === 'empty' ? 'FOLDER_NAME_EMPTY' : 'FOLDER_NAME_TOO_LONG',
+ check.kind === 'empty' ? 'folder name must not be empty' : 'folder name is too long',
+ );
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ try {
+ const store = (await getOwnerScopedDocumentStore(ownerId)) as unknown as DocumentFolderStore;
+ const { folder } = await createFolderForOwner(store, trimmed, { reuseExisting: false });
+ return ownerJson({ folder: folderResponse(folder, ownerId) }, 200, responseHeaders);
+ } catch (error) {
+ // The storage re-checks duplicates + count limit inside its owner-scoped
+ // transaction; map its refusals onto the same machine codes the
+ // pre-checks use.
+ const nameError = folderNameErrorResponse(error);
+ if (nameError) {
+ for (const [key, value] of responseHeaders) nameError.headers.append(key, value);
+ return nameError;
+ }
+ console.error(`[Folders] Failed to create [owner=${ownerId}]:`, error);
+ return jsonError(500, 'FOLDER_CREATE_FAILED', 'Failed to create folder', responseHeaders);
+ }
+ });
+}
diff --git a/app/api/generate/scene-content/route.ts b/app/api/generate/scene-content/route.ts
index 9901099..d3ac580 100644
--- a/app/api/generate/scene-content/route.ts
+++ b/app/api/generate/scene-content/route.ts
@@ -28,7 +28,6 @@ import { resolveModelFromRequest } from '@/lib/server/resolve-model';
import { resolveVocationalActive } from '@/lib/config/feature-flags';
import { MAX_VISION_IMAGES } from '@/lib/constants/generation';
import { sortDocumentImagesForVision } from '@/lib/document/bundle';
-import { DEFAULT_INGEST_AWAIT_TIMEOUT_MS } from '@/lib/document/extract-source';
import {
resolveVisionImagesForPrompt,
type VisionPromptImage,
@@ -47,7 +46,7 @@ export const maxDuration = 300;
* sequentially: when the budget expires the phase STOPS and generation
* proceeds with whatever resolved so far (degrade, never fail).
*/
-const VISION_RESOLUTION_BUDGET_MS = DEFAULT_INGEST_AWAIT_TIMEOUT_MS;
+const VISION_RESOLUTION_BUDGET_MS = 15_000;
/**
* Consecutive-failure fuse for the resolve-with-refill loop: after this many
diff --git a/app/api/materials/[id]/route.ts b/app/api/materials/[id]/route.ts
new file mode 100644
index 0000000..c69f855
--- /dev/null
+++ b/app/api/materials/[id]/route.ts
@@ -0,0 +1,44 @@
+/**
+ * GET /api/materials/[id]?sessionId= — one owned session's material, in the
+ * same public projection the list and the agent's `list_materials` tool use.
+ *
+ * Materials are session-scoped; the client names the session and the session's
+ * owner row is the authorization. A foreign or missing session, and a material
+ * id that does not exist or belongs to another session, all answer the same
+ * plain 404 (no existence oracle).
+ *
+ * Deletion is deliberately not exposed: the session-material store from the
+ * materials slice has no delete operation, and this slice adds no persistence
+ * — a later slice grows deletion on the store, then the route.
+ */
+import type { NextRequest } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { apiError } from '@/lib/server/api-response';
+import {
+ getSessionMaterial,
+ publicMaterialView,
+ resolveOwnedSession,
+} from '@/lib/server/agent-runtime/session-materials';
+import { ownerJson, ownerNotFound } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function GET(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ const sessionId = new URL(req.url).searchParams.get('sessionId')?.trim();
+ if (!sessionId) return apiError('MISSING_REQUIRED_FIELD', 400, 'sessionId is required');
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const session = await resolveOwnedSession(sessionId, ownerId);
+ if (!session) return ownerNotFound(responseHeaders);
+ const { id } = await params;
+ const material = await getSessionMaterial(sessionId, id);
+ if (!material) return ownerNotFound(responseHeaders);
+ return ownerJson({ material: publicMaterialView(material) }, 200, responseHeaders);
+ });
+}
diff --git a/app/api/materials/route.ts b/app/api/materials/route.ts
new file mode 100644
index 0000000..00b416c
--- /dev/null
+++ b/app/api/materials/route.ts
@@ -0,0 +1,416 @@
+/**
+ * /api/materials — the workbench's material list and upload face.
+ *
+ * The uploader (`uploadWorkbenchMaterial` in `lib/workbench/session-store.ts`)
+ * is OWNER-scoped: it posts a file with no session id and expects the flat
+ * `{ materialId, originalName, bytes, mime, extraction }` 201 view. This route
+ * implements the reference's upload contract on the owner-scoped material
+ * library (`lib/persistence/owner-materials.ts`) with the neutral local
+ * material byte store.
+ *
+ * ## Upload contract (the reference's)
+ *
+ * - `content-type` is the MIME type; it is normalized and validated against
+ * the workbench policy — an unsupported type answers 415.
+ * - `x-material-filename` is the display name (required).
+ * - Size caps are per class: media (audio/video) uploads cap at
+ * `maxUploadBytes`, documents/images at `min(maxDocumentBytes,
+ * maxUploadBytes)` — both 413 when exceeded, checked on the declared
+ * `content-length` AND on the streamed body.
+ * - Lifecycle: the upload reclaims crashed `uploading` leftovers older than
+ * 24 hours (their byte objects first, then the reservations), reserves a
+ * quota-checked `uploading` row (429 when the owner's count or byte quota is
+ * exceeded), streams the bytes through a sha256 meter into the byte store,
+ * and finalizes the row to `ready` with the digest. Failures
+ * abandon the reservation; crash leftovers are reclaimed by the next
+ * upload's 24-hour sweep.
+ * - Every response echoes the `x-request-id` header so the uploader can pair
+ * a failure with its log line.
+ *
+ * The configured runtime gates the family (the workbench is agent-runtime
+ * territory): off, or on without a DATABASE_URL, answers the same plain 404.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { basename } from 'node:path';
+
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { createMaterialId } from '@openmaic/storage';
+import type { ConnectableQueryable } from '@openmaic/storage/server/reference';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { apiError } from '@/lib/server/api-response';
+import { agentRuntimeConfig } from '@/lib/server/agent-runtime/config';
+import { ownerJson, ownerNotFound } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import {
+ resolveOwnedSession,
+ listSessionMaterials,
+ publicMaterialView,
+} from '@/lib/server/agent-runtime/session-materials';
+import {
+ abandonOwnerMaterial,
+ finalizeOwnerMaterial,
+ MaterialQuotaExceededError,
+ publicMaterial,
+ reclaimStaleOwnerMaterialUploads,
+ registerOwnerMaterial,
+} from '@/lib/persistence/owner-materials';
+import { getServerPersistenceProvider } from '@/lib/persistence/server-provider';
+import { getMaterialByteStore } from '@/lib/server/materials/bytes';
+import {
+ isWorkbenchMaterialMime,
+ MEDIA_MIME_TYPES,
+ normalizeWorkbenchMaterialMime,
+} from '@/lib/workbench/material-upload-policy';
+
+export const runtime = 'nodejs';
+
+const DOCUMENT_UPLOAD_LIMIT = Math.min(
+ agentRuntimeConfig.maxDocumentBytes,
+ agentRuntimeConfig.maxUploadBytes,
+);
+const MEDIA_MIME_SET = new Set(MEDIA_MIME_TYPES);
+
+/** The store's keyset-paging ceiling (default 50, capped at 200). */
+export const MAX_MATERIAL_LIST_LIMIT = 200;
+
+class MaterialPayloadTooLarge extends Error {}
+
+/** The `x-material-filename` header, sanitized to a bare file name. */
+function materialFilename(req: NextRequest): string | null {
+ const raw = req.headers.get('x-material-filename');
+ if (!raw) return null;
+ let decoded = raw;
+ try {
+ decoded = decodeURIComponent(raw);
+ } catch {
+ // Preserve a plain header value; malformed percent escapes are not paths.
+ }
+ const name = basename(decoded.replace(/\\/g, '/')).trim().slice(0, 512);
+ return name || null;
+}
+
+function materialUploadRequestId(req: NextRequest): string {
+ const upstream = req.headers.get('x-request-id')?.trim();
+ return upstream && /^[A-Za-z0-9._:-]{1,128}$/.test(upstream) ? upstream : randomUUID();
+}
+
+function parseLimit(raw: string | null): { limit?: number } | { invalid: true } {
+ if (raw === null || raw === '') return {};
+ if (!/^\d+$/.test(raw)) return { invalid: true };
+ const parsed = Number(raw);
+ if (parsed < 1 || parsed > MAX_MATERIAL_LIST_LIMIT) return { invalid: true };
+ return { limit: parsed };
+}
+
+// GET /api/materials?sessionId=&limit=&before= — list one owned session's
+// materials, newest first, keyset-paged (the agent-tools list surface).
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ const url = new URL(req.url);
+ const sessionId = url.searchParams.get('sessionId')?.trim();
+ if (!sessionId) return apiError('MISSING_REQUIRED_FIELD', 400, 'sessionId is required');
+
+ const parsedLimit = parseLimit(url.searchParams.get('limit'));
+ if ('invalid' in parsedLimit) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ `limit must be an integer between 1 and ${MAX_MATERIAL_LIST_LIMIT}`,
+ );
+ }
+ const before = url.searchParams.get('before')?.trim() || undefined;
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const session = await resolveOwnedSession(sessionId, ownerId);
+ if (!session) return ownerNotFound(responseHeaders);
+ const materials = await listSessionMaterials(sessionId, {
+ ...(parsedLimit.limit === undefined ? {} : { limit: parsedLimit.limit }),
+ ...(before ? { before } : {}),
+ });
+ return ownerJson(
+ { materials: materials.map((material) => publicMaterialView(material)) },
+ 200,
+ responseHeaders,
+ );
+ });
+}
+
+// POST /api/materials — upload a source file into the caller's durable
+// material library. The raw bytes ride the body; `content-type` is the MIME
+// type and `x-material-filename` the display name.
+export async function POST(req: NextRequest) {
+ const requestId = materialUploadRequestId(req);
+ const startedAt = Date.now();
+ let phase = 'feature_gate';
+ let materialId: string | undefined;
+ let mime = '';
+ let declaredBytes = 0;
+ let receivedBytes = 0;
+ let failureLogged = false;
+ const context = (extra: Record = {}) => ({
+ requestId,
+ phase,
+ ...(materialId ? { materialId } : {}),
+ ...(mime ? { mime } : {}),
+ declaredBytes,
+ receivedBytes,
+ durationMs: Date.now() - startedAt,
+ ...extra,
+ });
+ const reject = (response: Response, reason: string, headers: Headers) => {
+ console.warn('material upload rejected', context({ status: response.status, reason }));
+ response.headers.set('x-request-id', requestId);
+ for (const [key, value] of headers) response.headers.append(key, value);
+ return response;
+ };
+
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ try {
+ phase = 'validate_request';
+ const rawMime = (req.headers.get('content-type') ?? '').split(';', 1)[0];
+ mime = normalizeWorkbenchMaterialMime(rawMime);
+ if (!isWorkbenchMaterialMime(mime)) {
+ return reject(
+ apiError(
+ 'INVALID_REQUEST',
+ 415,
+ `unsupported material mime type: ${mime || '(missing)'}`,
+ ),
+ 'unsupported_mime',
+ responseHeaders,
+ );
+ }
+ const uploadLimit = MEDIA_MIME_SET.has(mime)
+ ? agentRuntimeConfig.maxUploadBytes
+ : DOCUMENT_UPLOAD_LIMIT;
+
+ declaredBytes = Number(req.headers.get('content-length') ?? 0);
+ if (Number.isFinite(declaredBytes) && declaredBytes > uploadLimit) {
+ return reject(
+ apiError('INVALID_REQUEST', 413, `upload exceeds ${uploadLimit} bytes`),
+ 'declared_body_too_large',
+ responseHeaders,
+ );
+ }
+ if (!req.body) {
+ return reject(
+ apiError('INVALID_REQUEST', 400, 'empty body'),
+ 'empty_body',
+ responseHeaders,
+ );
+ }
+
+ const originalName = materialFilename(req);
+ if (!originalName) {
+ return reject(
+ apiError('MISSING_REQUIRED_FIELD', 400, 'x-material-filename header is required'),
+ 'missing_filename',
+ responseHeaders,
+ );
+ }
+ const createdMaterialId = createMaterialId();
+ materialId = createdMaterialId;
+ const ossKey = `materials/${ownerId}/${createdMaterialId}`;
+
+ const provider = await getServerPersistenceProvider(process.env.DATABASE_URL ?? '');
+ const byteStore = getMaterialByteStore();
+
+ // Browsers send Content-Length for a File body. When an intermediary
+ // strips it, reserve the per-file maximum so an unmeasured stream can
+ // never bypass the owner byte quota; finalize shrinks the reservation to
+ // its actual size.
+ const reservedBytes =
+ Number.isFinite(declaredBytes) && declaredBytes > 0 ? declaredBytes : uploadLimit;
+
+ // Reclaim uploads that crashed before finalize and are older than the
+ // 24-hour horizon. Each reservation's byte object is removed first; the reservation is
+ // deleted only after that, so a failure here keeps the reservation for
+ // the next pass instead of losing the pointer to its bytes.
+ phase = 'reclaim_stale_uploads';
+ await reclaimStaleOwnerMaterialUploads(
+ provider.pool as unknown as ConnectableQueryable,
+ ownerId,
+ async (objectKey) => {
+ try {
+ await byteStore.delete(objectKey);
+ } catch (error) {
+ console.warn(
+ 'material stale byte deletion failed; keeping its reservation for the next pass',
+ context({ objectKey }),
+ error,
+ );
+ throw error;
+ }
+ },
+ ).catch((error) => {
+ console.warn(
+ 'material stale-upload reclaim failed; retrying on the next upload',
+ context(),
+ error,
+ );
+ });
+
+ phase = 'reserve_material';
+ try {
+ await registerOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ {
+ id: createdMaterialId,
+ ownerId,
+ kind: 'source',
+ mime,
+ bytes: reservedBytes,
+ originalName,
+ ossKey,
+ extraction: { status: 'idle' },
+ },
+ {
+ maxCount: agentRuntimeConfig.maxMaterialsPerOwner,
+ maxTotalBytes: agentRuntimeConfig.maxMaterialBytesPerOwner,
+ },
+ );
+ } catch (error) {
+ if (error instanceof MaterialQuotaExceededError) {
+ return reject(
+ apiError('INVALID_REQUEST', 429, error.message),
+ 'quota_exceeded',
+ responseHeaders,
+ );
+ }
+ throw error;
+ }
+
+ phase = 'store_bytes';
+ // Read the body through a sha256 meter, enforcing the per-class cap on
+ // the streamed size (an unmeasured stream cannot bypass the cap).
+ let bytes: Buffer;
+ try {
+ bytes = await readMeteredBody(req, uploadLimit);
+ receivedBytes = bytes.byteLength;
+ } catch (error) {
+ if (error instanceof MaterialPayloadTooLarge) {
+ await abandonOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ createdMaterialId,
+ ).catch(() => undefined);
+ return reject(
+ apiError('INVALID_REQUEST', 413, `upload exceeds ${uploadLimit} bytes`),
+ 'streamed_body_too_large',
+ responseHeaders,
+ );
+ }
+ failureLogged = true;
+ await abandonOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ createdMaterialId,
+ ).catch(() => undefined);
+ throw error;
+ }
+ if (bytes.byteLength === 0) {
+ await abandonOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ createdMaterialId,
+ ).catch(() => undefined);
+ return reject(
+ apiError('INVALID_REQUEST', 400, 'empty body'),
+ 'empty_stream',
+ responseHeaders,
+ );
+ }
+ if (bytes.byteLength > reservedBytes) {
+ await abandonOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ createdMaterialId,
+ ).catch(() => undefined);
+ return reject(
+ apiError('INVALID_REQUEST', 413, 'upload body exceeds its declared content length'),
+ 'declared_length_mismatch',
+ responseHeaders,
+ );
+ }
+
+ // The object key is recorded by the reservation before bytes are stored.
+ // A crash after the write therefore leaves a durable pointer for the
+ // 24-hour reclaim, preserving delete-before-reservation-removal order.
+ const hash = createHash('sha256').update(bytes).digest('hex');
+ let bytesStored = false;
+ try {
+ await byteStore.put(ossKey, bytes, mime);
+ bytesStored = true;
+ const row = await finalizeOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ createdMaterialId,
+ bytes.byteLength,
+ hash,
+ );
+ const view = publicMaterial(row);
+ const res = NextResponse.json(
+ {
+ materialId: view.materialId,
+ originalName: view.originalName,
+ bytes: view.bytes,
+ mime: view.mime,
+ extraction: view.extraction,
+ },
+ { status: 201 },
+ );
+ res.headers.set('x-request-id', requestId);
+ for (const [key, value] of responseHeaders) res.headers.append(key, value);
+ console.info('material upload completed', context({ status: 201 }));
+ return res;
+ } catch (error) {
+ let bytesDeleted = !bytesStored;
+ if (bytesStored) {
+ try {
+ await byteStore.delete(ossKey);
+ bytesDeleted = true;
+ } catch (cleanupError) {
+ console.warn(
+ 'material byte cleanup failed; keeping its reservation for stale reclaim',
+ context({ objectKey: ossKey }),
+ cleanupError,
+ );
+ }
+ }
+ if (bytesDeleted) {
+ await abandonOwnerMaterial(
+ provider.pool as unknown as ConnectableQueryable,
+ createdMaterialId,
+ ).catch(() => undefined);
+ }
+ throw error;
+ }
+ } catch (error) {
+ if (!failureLogged) console.error('material upload failed', context({ status: 500 }), error);
+ const res = apiError('INTERNAL_ERROR', 500, 'material upload failed');
+ res.headers.set('x-request-id', requestId);
+ for (const [key, value] of responseHeaders) res.headers.append(key, value);
+ return res;
+ }
+ });
+}
+
+/** Read the body up to `limit` bytes; throws {@link MaterialPayloadTooLarge} over the cap. */
+async function readMeteredBody(req: NextRequest, limit: number): Promise {
+ const chunks: Buffer[] = [];
+ let total = 0;
+ const reader = req.body!.getReader();
+ for (;;) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ const buffer = Buffer.from(value);
+ total += buffer.byteLength;
+ if (total > limit) {
+ await reader.cancel().catch(() => undefined);
+ throw new MaterialPayloadTooLarge();
+ }
+ chunks.push(buffer);
+ }
+ return Buffer.concat(chunks);
+}
diff --git a/app/api/persistence/[...path]/route.ts b/app/api/persistence/[...path]/route.ts
index 0d84367..730451e 100644
--- a/app/api/persistence/[...path]/route.ts
+++ b/app/api/persistence/[...path]/route.ts
@@ -9,28 +9,25 @@ import {
import { validateAppScene, validateAppStage } from '@/lib/document-store/validators';
import { resolveAssetCollectionGraceMs } from '@/lib/persistence/asset-collection-grace';
+import {
+ decideDocumentAccess,
+ parseDocumentAction,
+ type DocumentAccess,
+} from '@/lib/persistence/document-access';
+import { createOwnerBoundDocumentStore } from '@/lib/persistence/owner-bound-document-store';
import { authenticatePersistenceRequest } from '@/lib/persistence/server-auth';
import {
getServerPersistenceProvider,
type PersistencePoolFactory,
} from '@/lib/persistence/server-provider';
+import { readStageMeta } from '@/lib/persistence/stage-meta';
import { APP_RUNTIME_PAYLOAD_VALIDATORS } from '@/lib/runtime/payload-validators';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
export const runtime = 'nodejs';
const ROUTE_PREFIX = '/api/persistence';
-interface PersistenceHandlerState {
- connectionString?: string;
- handlerPromise?: Promise;
-}
-
-const HANDLER_STATE_KEY = Symbol.for('openmaic.persistence-route.handler');
-const globalState = globalThis as typeof globalThis & {
- [key: symbol]: PersistenceHandlerState | undefined;
-};
-const handlerState = (globalState[HANDLER_STATE_KEY] ??= {});
-
function jsonError(status: number, code: string, message: string): Response {
return Response.json({ error: { code, message } }, { status });
}
@@ -81,19 +78,25 @@ function indirectEgressWithinGrace(
async function createPersistenceHandler(
connectionString: string,
+ ownerId: string,
+ access: DocumentAccess,
poolFactory?: PersistencePoolFactory,
): Promise {
- const { runtimeStore, documentStore, assetStore } = await getServerPersistenceProvider(
+ const { pool, runtimeStore, assetStore } = await getServerPersistenceProvider(
connectionString,
poolFactory,
);
- // The asset contract requires a server-derived principal; this development
- // authenticator instead takes the partition key from a client-supplied header.
- // Cross-principal isolation is therefore not in force: asset bytes are as
- // reachable as documents and runtime records under this authenticator. Before
- // asset routes carry anything that matters, production must replace
- // authenticatePersistenceRequest with real session verification. See
- // lib/persistence/server-auth.ts for the token's limits.
+ const documentStore = createOwnerBoundDocumentStore({
+ pool,
+ ownerId,
+ validateScene: validateAppScene,
+ validateStage: validateAppStage,
+ });
+ // Runtime and asset requests retain the development authenticator, which
+ // takes their partition key from a client-supplied header. Document requests
+ // use the server-resolved anonymous owner below. Before runtime or asset
+ // routes carry production data, their authenticator must also be replaced
+ // with real session verification.
// Reclamation is not scheduled from here, and must not be: a route module
// has no once-per-process guarantee and no shutdown hook. AssetCollector
// runs from instrumentation.ts instead, over the byte store this same
@@ -103,10 +106,13 @@ async function createPersistenceHandler(
configuredAssetByteEgress(process.env.ASSET_BYTE_EGRESS),
);
return createStorageHttpHandler(runtimeStore, documentStore, {
- authenticate: authenticatePersistenceRequest,
+ authenticate: async (request) =>
+ request.url?.startsWith('/documents')
+ ? { learnerKey: ownerId }
+ : authenticatePersistenceRequest(request),
authorizeMerge: async () => false,
authorizeAdmin: async () => false,
- authorizeDocuments: async () => true,
+ authorizeDocuments: async () => access === 'allow',
validateScene: validateAppScene,
validateStage: validateAppStage,
payloadValidators: APP_RUNTIME_PAYLOAD_VALIDATORS,
@@ -115,26 +121,9 @@ async function createPersistenceHandler(
});
}
-function getPersistenceHandler(
- connectionString: string,
- poolFactory?: PersistencePoolFactory,
-): Promise {
- if (handlerState.handlerPromise && handlerState.connectionString === connectionString) {
- return handlerState.handlerPromise;
- }
-
- handlerState.connectionString = connectionString;
- const initialization = createPersistenceHandler(connectionString, poolFactory).catch((error) => {
- // Do not poison the singleton with a rejected promise. createPersistenceHandler
- // has already closed its failed pool, and the next request gets a clean retry.
- if (handlerState.handlerPromise === initialization) {
- handlerState.handlerPromise = undefined;
- handlerState.connectionString = undefined;
- }
- throw error;
- });
- handlerState.handlerPromise = initialization;
- return initialization;
+function routeRelativePath(request: Request): string {
+ const pathname = new URL(request.url).pathname;
+ return pathname.startsWith(ROUTE_PREFIX) ? pathname.slice(ROUTE_PREFIX.length) || '/' : pathname;
}
function nodeRequest(request: Request): IncomingMessage {
@@ -291,15 +280,46 @@ export async function handlePersistenceRequest(
);
}
- try {
- return await runNodeHandler(
- await getPersistenceHandler(connectionString, deps.poolFactory),
- request,
- );
- } catch (error) {
- console.error('Embedded persistence route initialization failed', error);
- return jsonError(500, 'PERSISTENCE_INIT_FAILED', 'server persistence initialization failed');
- }
+ return withRequestOwnerId(request, async (ownerId, responseHeaders) => {
+ try {
+ const path = routeRelativePath(request);
+ const action = parseDocumentAction(request.method, path);
+ let access: DocumentAccess = 'allow';
+ if (path === '/documents' || path.startsWith('/documents/')) {
+ const { pool } = await getServerPersistenceProvider(connectionString, deps.poolFactory);
+ const queryable = pool;
+ access = await decideDocumentAccess(
+ action,
+ ownerId,
+ (stageId) => readStageMeta(queryable, stageId),
+ (stageId) =>
+ pool
+ .query('SELECT 1 FROM document_stages WHERE id = $1', [stageId])
+ .then((result) => result.rows.length > 0),
+ (stageId) => readStageMeta(queryable, stageId),
+ );
+ }
+
+ const response =
+ access === 'not-found'
+ ? jsonError(404, 'DOCUMENT_NOT_FOUND', '@openmaic/storage: document not found')
+ : await runNodeHandler(
+ await createPersistenceHandler(connectionString, ownerId, access, deps.poolFactory),
+ request,
+ );
+ for (const [name, value] of responseHeaders.entries()) response.headers.append(name, value);
+ return response;
+ } catch (error) {
+ console.error('Embedded persistence route initialization failed', error);
+ const response = jsonError(
+ 500,
+ 'PERSISTENCE_INIT_FAILED',
+ 'server persistence initialization failed',
+ );
+ for (const [name, value] of responseHeaders.entries()) response.headers.append(name, value);
+ return response;
+ }
+ });
}
export const GET = (request: Request) => handlePersistenceRequest(request);
diff --git a/app/api/skills/[id]/route.ts b/app/api/skills/[id]/route.ts
new file mode 100644
index 0000000..f4a97ff
--- /dev/null
+++ b/app/api/skills/[id]/route.ts
@@ -0,0 +1,49 @@
+/** Download the OpenMAIC skill, a builtin agent skill, or one owner skill as zip. */
+import type { NextRequest } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { findUserSkill } from '@/lib/server/agent-runtime/user-skills';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import {
+ buildBuiltinSkillZip,
+ buildOpenClawSkillZip,
+ buildUserSkillZip,
+ isSafeSkillId,
+} from '@/lib/server/skill-export';
+
+export const runtime = 'nodejs';
+
+function zipResponse(id: string, zip: Buffer, headers = new Headers()): Response {
+ headers.set('Content-Type', 'application/zip');
+ headers.set('Content-Disposition', `attachment; filename="${id}-skill.zip"`);
+ headers.set('Cache-Control', 'no-store');
+ return new Response(new Uint8Array(zip), { headers });
+}
+
+export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+ const { id } = await params;
+ if (!isSafeSkillId(id)) return new Response('Invalid skill id', { status: 400 });
+
+ if (id === 'openmaic') {
+ const zip = await buildOpenClawSkillZip();
+ return zip ? zipResponse(id, zip) : new Response('Not found', { status: 404 });
+ }
+ const builtin = await buildBuiltinSkillZip(id);
+ if (builtin) return zipResponse(id, builtin);
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const skill = await findUserSkill(id, ownerId);
+ if (!skill) return new Response('Not found', { status: 404, headers: responseHeaders });
+ return zipResponse(
+ id,
+ await buildUserSkillZip({
+ name: skill.name,
+ title: skill.title,
+ description: skill.description,
+ content: skill.content,
+ }),
+ responseHeaders,
+ );
+ });
+}
diff --git a/app/api/stage-meta/[stageId]/route.ts b/app/api/stage-meta/[stageId]/route.ts
new file mode 100644
index 0000000..325c1fb
--- /dev/null
+++ b/app/api/stage-meta/[stageId]/route.ts
@@ -0,0 +1,80 @@
+/**
+ * GET /api/stage-meta/[stageId] — the per-viewer facts a document does not carry
+ * (the reference's stage-meta sidecar, ported onto this branch's owner model).
+ *
+ * The document seam returns a DOCUMENT: stage + scenes + outline, and nothing
+ * about who is asking. The classroom branches on exactly that — `isOwner`
+ * decides read-only vs editable — so the split is explicit: the document
+ * carries content, this sidecar carries tenancy, and the client fetches both
+ * in parallel.
+ *
+ * ## Everything here is fail-closed on the tombstone
+ *
+ * `resolveStageAccess` answers `null` for a deleted course exactly as it does
+ * for one that never existed, so a deleted course 404s here too. This endpoint
+ * is unauthenticated-friendly (any visitor may ask about any id), so if it
+ * leaked `{isPublic: true}` for a tombstoned course it would be a public oracle
+ * for "this course used to exist".
+ *
+ * ## No `ownerId` in the response, ever
+ *
+ * `isOwner` is a boolean derived server-side. Returning the owner's identity
+ * key would hand every visitor a stable cross-course identifier for the author.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { resolveStageAccess } from '@/lib/server/stage-access';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+// Per-viewer and mutable on every publish/unpublish/delete: this response must
+// never be cached, by Next or by anything in front of it.
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ stageId: string }> };
+
+export async function GET(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { stageId } = await params;
+ try {
+ const access = await resolveStageAccess(stageId);
+
+ // Absent or tombstoned — indistinguishable, deliberately.
+ if (!access) {
+ return NextResponse.json({ error: 'not_found' }, { status: 404, headers: responseHeaders });
+ }
+
+ // Identity comparison, and nothing else: this boolean is the client's
+ // ONLY owner signal, so a `true` here must mean every write through the
+ // owner-bound store will be accepted (the store re-checks the owner
+ // scope inside its write transactions).
+ const isOwner = access.ownerId === ownerId;
+
+ return NextResponse.json(
+ {
+ isOwner,
+ isPublic: access.isPublic,
+ publishedAt: access.publishedAt,
+ generationComplete: access.generationComplete,
+ // Which layer answered. Diagnostic only — the client must not branch
+ // on it.
+ source: access.source,
+ },
+ { status: 200, headers: responseHeaders },
+ );
+ } catch (error) {
+ console.error('Failed to resolve stage meta', {
+ stageId,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ return NextResponse.json(
+ { error: 'internal_error' },
+ { status: 500, headers: responseHeaders },
+ );
+ }
+ });
+}
diff --git a/app/api/stages/[id]/freshness/route.ts b/app/api/stages/[id]/freshness/route.ts
new file mode 100644
index 0000000..242aca6
--- /dev/null
+++ b/app/api/stages/[id]/freshness/route.ts
@@ -0,0 +1,152 @@
+/**
+ * GET /api/stages/[id]/freshness — volatile freshness SSE for one course (the
+ * reference's `stages/:id/freshness`, ported onto the owner-bound store).
+ *
+ * The workbench's push side: when the stage's revision moves, this stream
+ * sends the client one frame carrying the current `rev`; the client reacts by
+ * pulling the manifest and re-fetching only the scenes that changed.
+ *
+ * The reference woke this stream from a DB trigger's NOTIFY; the upstream
+ * storage package exposes no LISTEN/NOTIFY, so this stream POLLS the
+ * owner-bound store for the stage's trigger-maintained revision (the same
+ * correctness mechanism as `app/api/agent/owner-events/route.ts`). A frame is
+ * emitted when the rev moves; the first frame is sent on connect. `rev` is the
+ * per-stage monotonic revision the manifest exposes, so a frame that arrives
+ * always reflects the same signal the manifest serves.
+ *
+ * Degradation is by design: this stream is a pure optimization. A dead or
+ * missing stream only costs latency — the client's low-frequency fallback
+ * poll still converges. Conventions mirror the sibling SSE routes: a 25s
+ * heartbeat comment frame keeps intermediaries from ending the stream, an
+ * explicit `retry:` hint sets the browser's reconnect delay, the stream never
+ * closes on a terminal state, and a broken socket is the client's
+ * EventSource problem, not this route's.
+ */
+import type { NextRequest } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { resolveRequestOwnerId } from '@/lib/server/agent-runtime/owner';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerNotFound } from '@/lib/server/agent-runtime/route-response';
+
+export const runtime = 'nodejs';
+// Self-hosted `next start` ignores maxDuration; Vercel's adapter can still use
+// it. The 25s heartbeat keeps this sparse stream active through idle periods.
+export const maxDuration = 300;
+
+/** How often the stream re-checks the stage's revision. */
+export const STAGE_FRESHNESS_POLL_INTERVAL_MS = 5_000;
+/** Same ceiling as the sibling SSE streams. */
+export const STAGE_FRESHNESS_HEARTBEAT_MS = 25_000;
+/** Browser reconnect delay, sent as the SSE `retry:` field. */
+export const STAGE_FRESHNESS_RETRY_MS = 3_000;
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function GET(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ const responseHeaders = new Headers();
+ const ownerId = resolveRequestOwnerId(req, responseHeaders);
+ const { id: stageId } = await params;
+
+ // Existence-gated, exactly like the manifest route: the owner-bound store
+ // reads a foreign or missing stage as absent, and the 404 carries the
+ // owner cookie the same way every response of this family does.
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ const initial = await store.readFreshnessManifest(stageId);
+ if (!initial) return ownerNotFound(responseHeaders);
+
+ const encoder = new TextEncoder();
+ let pollTimer: ReturnType | null = null;
+ let heartbeatTimer: ReturnType | null = null;
+ let closed = false;
+
+ const clearTimers = () => {
+ if (pollTimer) clearTimeout(pollTimer);
+ if (heartbeatTimer) clearInterval(heartbeatTimer);
+ pollTimer = null;
+ heartbeatTimer = null;
+ };
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ const write = (chunk: string) => {
+ if (closed) return false;
+ try {
+ controller.enqueue(encoder.encode(chunk));
+ return true;
+ } catch {
+ // A broken socket is not guaranteed to invoke cancel() in every
+ // runtime; stop the timers the moment enqueue proves it closed.
+ closed = true;
+ clearTimers();
+ return false;
+ }
+ };
+
+ let lastRev = 0;
+
+ // The frame carries the current rev so a client that wants to skip the
+ // manifest round-trip when nothing changed can, but the contract is
+ // "pull the manifest on every frame" — rev is informational, never
+ // authoritative. A read failure sends rev 0 (never a terminal state: a
+ // stage can always be written again), matching the reference.
+ const emitFreshness = async () => {
+ if (closed) return;
+ let rev = 0;
+ try {
+ const manifest = await store.readFreshnessManifest(stageId);
+ rev = manifest ? manifest.rev : 0;
+ } catch {
+ // Fall through to the rev-0 frame.
+ }
+ if (rev === lastRev) return;
+ lastRev = rev;
+ write(
+ `event: stage_freshness\ndata: ${JSON.stringify({
+ type: 'stage_freshness',
+ stageId,
+ rev,
+ })}\n\n`,
+ );
+ };
+
+ // Chained setTimeout: the next poll is scheduled only after the previous
+ // read settles, so polls can never overlap.
+ const schedulePoll = () => {
+ if (closed) return;
+ pollTimer = setTimeout(async () => {
+ try {
+ await emitFreshness();
+ } finally {
+ schedulePoll();
+ }
+ }, STAGE_FRESHNESS_POLL_INTERVAL_MS);
+ };
+
+ // Reconnect hint + the first frame of the stream.
+ write(`retry: ${STAGE_FRESHNESS_RETRY_MS}\n\n`);
+ await emitFreshness();
+
+ heartbeatTimer = setInterval(() => {
+ if (closed) return;
+ write(': ping\n\n');
+ }, STAGE_FRESHNESS_HEARTBEAT_MS);
+ schedulePoll();
+ },
+ cancel() {
+ closed = true;
+ clearTimers();
+ },
+ });
+
+ return new Response(stream, {
+ headers: {
+ 'Content-Type': 'text/event-stream; charset=utf-8',
+ 'Cache-Control': 'no-cache, no-transform',
+ Connection: 'keep-alive',
+ ...Object.fromEntries(responseHeaders),
+ },
+ });
+}
diff --git a/app/api/stages/[id]/generation-complete/route.ts b/app/api/stages/[id]/generation-complete/route.ts
new file mode 100644
index 0000000..66d89c6
--- /dev/null
+++ b/app/api/stages/[id]/generation-complete/route.ts
@@ -0,0 +1,60 @@
+/**
+ * POST /api/stages/[id]/generation-complete
+ *
+ * Monotonically marks an existing stage outline as generation-complete.
+ * Owner-only. This route deliberately performs a narrow UPDATE so a stale
+ * load-time repair cannot overwrite newer classroom content.
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { markStageGenerationComplete } from '@/lib/persistence/stage-meta';
+import { getStageAccessDb, resolveStageAccess } from '@/lib/server/stage-access';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function POST(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id: stageId } = await params;
+ try {
+ const access = await resolveStageAccess(stageId);
+
+ // Absent and tombstoned are the same 404 — the caller must not learn
+ // that an id used to be a real course, and a deleted course has no
+ // state left worth repairing.
+ if (!access) {
+ return NextResponse.json({ error: 'not_found' }, { status: 404, headers: responseHeaders });
+ }
+
+ // Owner only.
+ if (access.ownerId !== ownerId) {
+ return NextResponse.json({ error: 'forbidden' }, { status: 403, headers: responseHeaders });
+ }
+
+ const db = await getStageAccessDb();
+ const touched = await markStageGenerationComplete(db, stageId);
+
+ if (!touched) {
+ return NextResponse.json({ error: 'not_found' }, { status: 404, headers: responseHeaders });
+ }
+
+ console.info('Stage generation marked complete', { stageId, ownerId });
+ return NextResponse.json({ ok: true }, { status: 200, headers: responseHeaders });
+ } catch (error) {
+ console.error('Failed to mark stage generation complete', {
+ stageId,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ return NextResponse.json(
+ { error: 'internal_error' },
+ { status: 500, headers: responseHeaders },
+ );
+ }
+ });
+}
diff --git a/app/api/stages/[id]/manifest/route.ts b/app/api/stages/[id]/manifest/route.ts
new file mode 100644
index 0000000..43bbf12
--- /dev/null
+++ b/app/api/stages/[id]/manifest/route.ts
@@ -0,0 +1,38 @@
+/**
+ * GET /api/stages/[id]/manifest — freshness manifest for one course (the
+ * reference's `stages/:id/manifest`, ported onto the owner-bound store).
+ *
+ * Returns `{rev, scenes: [{id, order, rev}]}` — the per-stage monotonic
+ * revision and each scene's own revision, produced by DB triggers on
+ * `document_stages` / `document_scenes` (provisioned by the storage package's
+ * schema), so every write seam — HTTP routes, agent tools, jobs, manual SQL —
+ * moves them without application cooperation. The workbench canvas diffs this
+ * manifest against what it rendered with and re-fetches only the scenes whose
+ * rev changed.
+ *
+ * Permission boundary is the same as every stage route: the owner-bound store
+ * reads a foreign or missing stage as absent, and both answer the identical
+ * 404 (the id is not an existence oracle).
+ */
+import type { NextRequest } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerJson, ownerNotFound } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function GET(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ const manifest = await store.readFreshnessManifest(id);
+ if (!manifest) return ownerNotFound(responseHeaders);
+ return ownerJson(manifest, 200, responseHeaders);
+ });
+}
diff --git a/app/api/stages/[id]/publish/route.ts b/app/api/stages/[id]/publish/route.ts
new file mode 100644
index 0000000..d0bf05d
--- /dev/null
+++ b/app/api/stages/[id]/publish/route.ts
@@ -0,0 +1,68 @@
+/**
+ * POST /api/stages/[id]/publish — make a document-backed course public.
+ *
+ * Owner-only; anonymous owners are refused with the reference's
+ * `login_required` (a published course is a durable public artifact, so it
+ * needs a real account, not an anonymous cookie partition).
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { setStagePublished } from '@/lib/persistence/stage-meta';
+import { getStageAccessDb, resolveStageAccess } from '@/lib/server/stage-access';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function POST(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id: stageId } = await params;
+ try {
+ if (ownerId.startsWith('anon:')) {
+ return NextResponse.json(
+ { error: 'login_required' },
+ { status: 401, headers: responseHeaders },
+ );
+ }
+
+ const access = await resolveStageAccess(stageId);
+ if (!access) {
+ return NextResponse.json({ error: 'not_found' }, { status: 404, headers: responseHeaders });
+ }
+ if (access.ownerId !== ownerId) {
+ return NextResponse.json({ error: 'forbidden' }, { status: 403, headers: responseHeaders });
+ }
+
+ if (access.isPublic) {
+ return NextResponse.json(
+ { success: true, publishedAt: access.publishedAt, name: access.name },
+ { status: 200, headers: responseHeaders },
+ );
+ }
+
+ const publishedAt = Date.now();
+ const db = await getStageAccessDb();
+ await setStagePublished(db, stageId, true, publishedAt);
+
+ console.info('Stage published', { stageId, ownerId });
+ return NextResponse.json(
+ { success: true, publishedAt, name: access.name },
+ { status: 200, headers: responseHeaders },
+ );
+ } catch (error) {
+ console.error('Failed to publish stage', {
+ stageId,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ return NextResponse.json(
+ { error: 'internal_error' },
+ { status: 500, headers: responseHeaders },
+ );
+ }
+ });
+}
diff --git a/app/api/stages/[id]/route.ts b/app/api/stages/[id]/route.ts
new file mode 100644
index 0000000..6bc07e8
--- /dev/null
+++ b/app/api/stages/[id]/route.ts
@@ -0,0 +1,189 @@
+/**
+ * /api/stages/[id] — read, rename, save, and delete one owned course document.
+ *
+ * Ownership is enforced by the store itself, not by a pre-check: every read
+ * and write goes through the owner-bound document store, so a foreign or
+ * missing id answers the identical 404 (the no-existence-oracle posture of
+ * the agent-runtime routes), and a write into a foreign document is refused
+ * inside the store's transaction (`persistStage` re-checks the owner scope).
+ *
+ * - GET returns the whole document (stage + scenes + outline).
+ * - PATCH renames the course ({ name }), the reference's update path.
+ * - PUT saves a whole document ({ stage, scenes, outline? }) — the coarse
+ * "update stage document" write the UI saves through; the server
+ * bumps `stage.updatedAt` so the freshness signal sees the change.
+ * - DELETE removes the course and its cascading child rows.
+ *
+ * The configured runtime gates the family (see `app/api/stages/route.ts`):
+ * off, or on without a DATABASE_URL, answers the same plain 404.
+ */
+import type { NextRequest } from 'next/server';
+
+import { DocumentNotFoundError, DocumentVersionError, type MaicDocument } from '@openmaic/storage';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { apiError } from '@/lib/server/api-response';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerApiError, ownerJson, ownerNotFound } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+import { STAGE_NAME_MAX_LENGTH } from '@/lib/server/agent-runtime/stage-limits';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+/** A save refused because the payload is not a structurally valid document. */
+function isStoreValidationError(error: unknown): error is Error {
+ return (
+ error instanceof Error &&
+ error.message.startsWith('@openmaic/storage:') &&
+ !(error instanceof DocumentNotFoundError) &&
+ !(error instanceof DocumentVersionError)
+ );
+}
+
+/** Map a store save failure onto the route's error surface. */
+function mapSaveError(error: unknown, headers: Headers) {
+ if (error instanceof DocumentNotFoundError) return ownerNotFound(headers);
+ if (error instanceof DocumentVersionError) {
+ // A document written by a newer client cannot be saved by this one.
+ return ownerApiError(
+ 'INVALID_REQUEST',
+ 400,
+ 'document was written by a newer client; reload before saving',
+ headers,
+ error.message,
+ );
+ }
+ if (isStoreValidationError(error)) {
+ return ownerApiError('INVALID_REQUEST', 400, 'invalid stage document', headers, error.message);
+ }
+ throw error;
+}
+
+// GET /api/stages/[id] — the full document.
+export async function GET(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ const document = await store.loadDocument(id);
+ if (!document) return ownerNotFound(responseHeaders);
+ return ownerJson(document, 200, responseHeaders);
+ });
+}
+
+// PATCH /api/stages/[id] — rename the course (owner-only).
+export async function PATCH(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return apiError('INVALID_REQUEST', 400, 'invalid JSON body');
+ }
+ const rawName = (body as { name?: unknown })?.name;
+ if (typeof rawName !== 'string' || rawName.trim().length === 0) {
+ return apiError('INVALID_REQUEST', 400, 'name must be a non-empty string');
+ }
+ const name = rawName.trim();
+ if (name.length > STAGE_NAME_MAX_LENGTH) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ `name exceeds the ${STAGE_NAME_MAX_LENGTH} character limit`,
+ );
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ const document = await store.loadDocument(id);
+ if (!document) return ownerNotFound(responseHeaders);
+ try {
+ await store.saveDocument({
+ ...document,
+ stage: { ...document.stage, name, updatedAt: Date.now() },
+ });
+ } catch (error) {
+ return mapSaveError(error, responseHeaders);
+ }
+ return ownerJson({ success: true, name }, 200, responseHeaders);
+ });
+}
+
+// PUT /api/stages/[id] — save a whole document.
+export async function PUT(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return apiError('INVALID_REQUEST', 400, 'invalid JSON body');
+ }
+ const candidate = body as {
+ stage?: { id?: unknown; updatedAt?: unknown };
+ scenes?: unknown;
+ };
+ if (
+ typeof candidate !== 'object' ||
+ candidate === null ||
+ typeof candidate.stage !== 'object' ||
+ candidate.stage === null ||
+ typeof candidate.stage.id !== 'string' ||
+ !Array.isArray(candidate.scenes)
+ ) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ 'request body must be a stage document with `stage` and `scenes`',
+ );
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ if (candidate.stage!.id !== id) {
+ return ownerApiError(
+ 'INVALID_REQUEST',
+ 400,
+ 'document stage id does not match the requested stage',
+ responseHeaders,
+ );
+ }
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ // Save is existence-gated (the reference's update path is too): PUT
+ // updates a course that exists; it must not resurrect a deleted one or
+ // mint a course under a client-chosen id. The owner scope is re-checked
+ // inside the write transaction, so a foreign id still refuses there.
+ const existing = await store.loadDocument(id);
+ if (!existing) return ownerNotFound(responseHeaders);
+ try {
+ // The server is authoritative for "last modified": bumping updatedAt
+ // keeps the manifest/freshness signal accurate for this route's writes.
+ // The full payload is validated inside the store before anything is
+ // persisted (invalid stage/scene shapes throw and map to 400 below).
+ await store.saveDocument({
+ ...(body as MaicDocument),
+ stage: { ...(body as MaicDocument).stage, updatedAt: Date.now() },
+ });
+ } catch (error) {
+ return mapSaveError(error, responseHeaders);
+ }
+ return ownerJson({ success: true }, 200, responseHeaders);
+ });
+}
+
+// DELETE /api/stages/[id] — remove the course and its scenes/outline.
+export async function DELETE(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ await store.deleteDocument(id);
+ return ownerJson({ ok: true }, 200, responseHeaders);
+ });
+}
diff --git a/app/api/stages/[id]/scenes/route.ts b/app/api/stages/[id]/scenes/route.ts
new file mode 100644
index 0000000..524438e
--- /dev/null
+++ b/app/api/stages/[id]/scenes/route.ts
@@ -0,0 +1,81 @@
+/**
+ * GET /api/stages/[id]/scenes?ids=a,b,c — batch scene read (reference
+ * `stages/:id/scenes`, ported onto the owner-bound document store).
+ *
+ * Returns ONLY the requested scenes, in document (`scene_order`) order — the
+ * narrow re-fetch half of the workbench's manifest sync: the client diffs
+ * `GET /api/stages/:id/manifest` against what it rendered with, then asks
+ * this endpoint for exactly the scene ids whose rev changed. One page commit
+ * therefore moves one scene instead of the whole document.
+ *
+ * Ownership and existence share the store's no-existence-oracle posture: the
+ * owner-bound store reads a foreign or missing stage as absent, and both
+ * answer the identical 404. A requested id that does not exist (deleted
+ * between the manifest read and here) is simply absent from the array.
+ *
+ * Ids are bounded: a pathological diff could name every scene, so the request
+ * is capped at MAX_BATCH_SCENE_IDS; over the cap is a 400 rather than a
+ * silent truncation (truncating would drop scenes the client believes it
+ * fetched). The client treats 400 as a failed pass and retries on the next
+ * trigger.
+ */
+import type { NextRequest } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { apiError } from '@/lib/server/api-response';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerJson, ownerNotFound } from '@/lib/server/agent-runtime/route-response';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+/** Upper bound on `ids` — see the file header. */
+export const MAX_BATCH_SCENE_IDS = 200;
+
+/**
+ * Scene ids travel the same wire as stage ids, so they face the same driver
+ * hazard: a `\0` or a lone surrogate in the query parameter would make an id
+ * comparison throw at the driver. Such an id can never match a stored scene,
+ * so dropping it is exact (reference rationale).
+ */
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+function isQueryableSceneId(sceneId: string): boolean {
+ return !sceneId.includes('\u0000') && !LONE_SURROGATE.test(sceneId);
+}
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function GET(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ const rawIds = new URL(req.url).searchParams.get('ids');
+ const requested = (rawIds ?? '')
+ .split(',')
+ .map((value) => value.trim())
+ .filter((value) => value.length > 0)
+ // Dedupe: a repeated id is the same scene; counting it twice would also
+ // inflate the bound check.
+ .filter((value, index, all) => all.indexOf(value) === index)
+ .filter(isQueryableSceneId);
+ if (requested.length === 0) {
+ return apiError('INVALID_REQUEST', 400, 'empty_scene_ids');
+ }
+ if (requested.length > MAX_BATCH_SCENE_IDS) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ 'too_many_scene_ids',
+ `limit ${MAX_BATCH_SCENE_IDS}, requested ${requested.length}`,
+ );
+ }
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id } = await params;
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ const document = await store.loadDocument(id);
+ if (!document) return ownerNotFound(responseHeaders);
+ const wanted = new Set(requested);
+ const scenes = document.scenes.filter((scene) => wanted.has(scene.id));
+ return ownerJson({ scenes }, 200, responseHeaders);
+ });
+}
diff --git a/app/api/stages/[id]/status/route.ts b/app/api/stages/[id]/status/route.ts
new file mode 100644
index 0000000..fe16713
--- /dev/null
+++ b/app/api/stages/[id]/status/route.ts
@@ -0,0 +1,45 @@
+/**
+ * GET /api/stages/[id]/status
+ *
+ * Returns the public-state metadata for a stage. Used by the Share menu CTA
+ * to know whether to show "Publish" or "Already published · Unpublish".
+ *
+ * No auth required — any caller who has the stage ID can read its public flag.
+ *
+ * Convention: snake_case error codes (e.g. `not_found`, `internal_error`).
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { resolveStageAccess } from '@/lib/server/stage-access';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function GET(_req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ const { id } = await params;
+ try {
+ const access = await resolveStageAccess(id);
+
+ // Tombstoned and never-existed must be indistinguishable: this endpoint is
+ // unauthenticated, so an answer other than plain 404 would let anyone
+ // confirm that a given id used to be a real course.
+ if (!access) {
+ return NextResponse.json({ error: 'not_found' }, { status: 404 });
+ }
+
+ // Field names are the wire contract; they stay `isPublic` / `publishedAt`
+ // regardless of which layer answered.
+ return NextResponse.json({ isPublic: access.isPublic, publishedAt: access.publishedAt });
+ } catch (error) {
+ console.error('Failed to fetch stage status', {
+ stageId: id,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ return NextResponse.json({ error: 'internal_error' }, { status: 500 });
+ }
+}
diff --git a/app/api/stages/[id]/unpublish/route.ts b/app/api/stages/[id]/unpublish/route.ts
new file mode 100644
index 0000000..4ce8def
--- /dev/null
+++ b/app/api/stages/[id]/unpublish/route.ts
@@ -0,0 +1,56 @@
+/**
+ * POST /api/stages/[id]/unpublish — make a document-backed course private.
+ *
+ * Owner-only; anonymous owners are refused with the reference's
+ * `login_required` (same rationale as publish).
+ */
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import { setStagePublished } from '@/lib/persistence/stage-meta';
+import { getStageAccessDb, resolveStageAccess } from '@/lib/server/stage-access';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+type Params = { params: Promise<{ id: string }> };
+
+export async function POST(req: NextRequest, { params }: Params) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const { id: stageId } = await params;
+ try {
+ if (ownerId.startsWith('anon:')) {
+ return NextResponse.json(
+ { error: 'login_required' },
+ { status: 401, headers: responseHeaders },
+ );
+ }
+
+ const access = await resolveStageAccess(stageId);
+ if (!access) {
+ return NextResponse.json({ error: 'not_found' }, { status: 404, headers: responseHeaders });
+ }
+ if (access.ownerId !== ownerId) {
+ return NextResponse.json({ error: 'forbidden' }, { status: 403, headers: responseHeaders });
+ }
+
+ const db = await getStageAccessDb();
+ await setStagePublished(db, stageId, false, null);
+
+ console.info('Stage unpublished', { stageId, ownerId });
+ return NextResponse.json({ success: true }, { status: 200, headers: responseHeaders });
+ } catch (error) {
+ console.error('Failed to unpublish stage', {
+ stageId,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ return NextResponse.json(
+ { error: 'internal_error' },
+ { status: 500, headers: responseHeaders },
+ );
+ }
+ });
+}
diff --git a/app/api/stages/route.ts b/app/api/stages/route.ts
new file mode 100644
index 0000000..a85831b
--- /dev/null
+++ b/app/api/stages/route.ts
@@ -0,0 +1,116 @@
+/**
+ * /api/stages — the workbench's course-document index and create face.
+ *
+ * Every handler is owner-scoped exactly like the agent tools: the owner
+ * resolves from the anonymous cookie (`withRequestOwnerId`) and is never a
+ * request parameter, and all reads and writes go through the owner-bound
+ * document store (`getOwnerScopedDocumentStore`), the same seam the runner
+ * binds for the stage tools. A stage created here is visible to this browser
+ * and to nobody else.
+ *
+ * The configured runtime gates the whole family: these routes serve the
+ * workbench, which is agent-runtime territory, so a runtime that is off OR
+ * enabled without a DATABASE_URL answers the same plain 404 as the agent
+ * control-plane routes — never a 500 from a store that cannot connect.
+ */
+import type { NextRequest } from 'next/server';
+import { randomBytes } from 'node:crypto';
+
+import { isAgentRuntimeConfigured } from '@/lib/config/feature-flags';
+import type { AppDocumentOutline } from '@/lib/document-store/persistence-types';
+import { apiError } from '@/lib/server/api-response';
+import { getOwnerScopedDocumentStore } from '@/lib/server/agent-runtime/owner-scoped-documents';
+import { ownerJson } from '@/lib/server/agent-runtime/route-response';
+import { STAGE_NAME_MAX_LENGTH } from '@/lib/server/agent-runtime/stage-limits';
+import { withRequestOwnerId } from '@/lib/server/agent-runtime/with-owner';
+
+export const runtime = 'nodejs';
+
+/** Mint a fresh, collision-free course id in the same `stage-` family as the agent tools. */
+function createStageId(): string {
+ return `stage-${randomBytes(9).toString('base64url')}`;
+}
+
+// GET /api/stages — list every stage document owned by the caller.
+export async function GET(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ const stages = await store.listDocuments();
+ return ownerJson({ stages }, 200, responseHeaders);
+ });
+}
+
+// POST /api/stages — create a stage document shell { name, description? }.
+//
+// Validation happens before owner resolution, like the agent session routes:
+// a malformed body must not mint an anonymous cookie partition for a request
+// that will not proceed.
+export async function POST(req: NextRequest) {
+ if (!isAgentRuntimeConfigured()) return new Response('Not found', { status: 404 });
+
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return apiError('INVALID_REQUEST', 400, 'invalid JSON body');
+ }
+ if (typeof body !== 'object' || body === null) {
+ return apiError('INVALID_REQUEST', 400, 'request body must be a JSON object');
+ }
+ const { name, description } = body as { name?: unknown; description?: unknown };
+ if (typeof name !== 'string' || name.trim().length === 0) {
+ return apiError('MISSING_REQUIRED_FIELD', 400, 'name is required');
+ }
+ const trimmedName = name.trim();
+ if (trimmedName.length > STAGE_NAME_MAX_LENGTH) {
+ return apiError(
+ 'INVALID_REQUEST',
+ 400,
+ `name exceeds the ${STAGE_NAME_MAX_LENGTH} character limit`,
+ );
+ }
+ if (description !== undefined && typeof description !== 'string') {
+ return apiError('INVALID_REQUEST', 400, 'description must be a string when present');
+ }
+ const trimmedDescription = description?.trim();
+
+ return withRequestOwnerId(req, async (ownerId, responseHeaders) => {
+ const id = createStageId();
+ const now = Date.now();
+ const outline: AppDocumentOutline = {
+ outlines: [],
+ requirement: trimmedName,
+ generationComplete: false,
+ createdAt: now,
+ updatedAt: now,
+ };
+ const store = await getOwnerScopedDocumentStore(ownerId);
+ await store.saveDocument({
+ stage: {
+ id,
+ name: trimmedName,
+ ...(trimmedDescription ? { description: trimmedDescription } : {}),
+ createdAt: now,
+ updatedAt: now,
+ },
+ scenes: [],
+ outline,
+ });
+ return ownerJson(
+ {
+ stage: {
+ id,
+ name: trimmedName,
+ ...(trimmedDescription ? { description: trimmedDescription } : {}),
+ createdAt: now,
+ updatedAt: now,
+ sceneCount: 0,
+ },
+ },
+ 201,
+ responseHeaders,
+ );
+ });
+}
diff --git a/app/classroom/[id]/page.tsx b/app/classroom/[id]/page.tsx
index 119199e..dfbaaf4 100644
--- a/app/classroom/[id]/page.tsx
+++ b/app/classroom/[id]/page.tsx
@@ -15,6 +15,8 @@ import { createLogger } from '@/lib/logger';
import { MediaStageProvider } from '@/lib/contexts/media-stage-context';
import { generateMediaForOutlines } from '@/lib/media/media-orchestrator';
import { useAgentRegistry } from '@/lib/orchestration/registry/store';
+import { fetchStageMeta } from '@/lib/classroom/stage-meta-client';
+import { noteStageOwnership } from '@/lib/classroom/stage-ownership-signal';
import {
applyClassroomStageAndScenes,
defaultClassroomLoadDeps,
@@ -71,6 +73,37 @@ export default function ClassroomDetailPage() {
setLoading,
log,
});
+
+ // The stage-meta sidecar resolves the viewer-facing ownership facts the
+ // document seam does not carry — `isOwner` decides read-only vs editable
+ // (see `stage-meta-client.ts`). Run it strictly AFTER the load applied
+ // its defaults so its answer wins, and fire it without blocking the
+ // render that already happened.
+ if (isEffectCurrent()) {
+ void fetchStageMeta(classroomId)
+ .then((result) => {
+ if (!isEffectCurrent()) return;
+ if (result.outcome === 'found') {
+ noteStageOwnership(classroomId, true, {
+ isOwner: result.meta.isOwner,
+ });
+ useStageStore.getState().setViewerAccess({
+ isOwner: result.meta.isOwner,
+ });
+ } else if (result.outcome === 'unavailable') {
+ // A silent sidecar is not "this is a stranger's course": record
+ // the outage so nothing treats `isOwner === false` as a visitor
+ // conclusion. The edit gate stays on the upstream defaults.
+ noteStageOwnership(classroomId, false, null);
+ } else {
+ // 'absent' — no sidecar row for this id. This classroom also
+ // serves local-only courses, so the upstream editable default
+ // stays; the server's owner-scoped writes remain the authority.
+ noteStageOwnership(classroomId, true, null);
+ }
+ })
+ .catch(() => noteStageOwnership(classroomId, false, null));
+ }
},
[classroomId, loadFromStorage],
);
diff --git a/app/generation-preview/page.tsx b/app/generation-preview/page.tsx
index e5daa0a..f2acc52 100644
--- a/app/generation-preview/page.tsx
+++ b/app/generation-preview/page.tsx
@@ -34,22 +34,7 @@ import {
storeImages,
} from '@/lib/utils/image-storage';
import { getCurrentModelConfig } from '@/lib/utils/model-config';
-import { isAssetPoolServerBacked } from '@/lib/media/asset-pool-config';
-import { getPersistenceRequestHeaders } from '@/lib/persistence/bootstrap';
import { resolveSessionDocumentSources } from '@/lib/document/session-sources';
-import {
- computeConfigFingerprint,
- createExtractionDeduplicator,
- fetchExtractionWithCache,
- resolveExpectedExtractor,
- type ExtractionCacheDomain,
-} from '@/lib/document/extraction-cache';
-import { DEFAULT_INGEST_AWAIT_TIMEOUT_MS } from '@/lib/document/extract-source';
-import {
- awaitWithFallback,
- materializeBundleImages,
-} from '@/lib/document/extraction-materialization';
-import { SUPPORTED_MEDIA_MIME_TYPES } from '@/lib/document/mime';
import { MAX_VISION_IMAGES } from '@/lib/constants/generation';
import {
MAX_DOCUMENT_BUNDLE_FILES,
@@ -87,8 +72,6 @@ type ParsedDocumentResponseImage = {
description?: string;
width?: number;
height?: number;
- /** Pool asset id of the image bytes (server-backed cache-hit rebuilds). */
- assetId?: string;
};
function validateDocumentSources(
@@ -333,13 +316,6 @@ function GenerationPreviewContent() {
// Use a local mutable copy so we can update it after document extraction
let currentSession = generationSession;
- // A server-backed asset pool can resolve bytes by allocated asset id; a
- // browser-backed (self-deploy) pool cannot, so the client keeps the byte
- // transport. The probe is read ONCE per run so a mid-run configuration
- // change cannot split the bundle across the two forms (RFC #1153 part 0/1,
- // and part 2's imageMapping transport decision rides the same probe).
- const serverBacked = isAssetPoolServerBacked();
-
setError(null);
setCurrentStepIndex(0);
@@ -361,10 +337,6 @@ function GenerationPreviewContent() {
log.debug('=== Generation Preview: Extracting course material bundle ===');
validateDocumentSources(documentSources, t);
const sortedDocumentSources = [...documentSources].sort((a, b) => a.order - b.order);
- // K3 (in-run dedupe): sources with the same content digest AND the same
- // expected extractor identity share ONE extraction, so two same-byte
- // files under different names never both pay for the paid extraction.
- const deduplicateExtraction = createExtractionDeduplicator();
const parsedParts = await Promise.all(
sortedDocumentSources.map(async (source): Promise => {
const providerId = source.providerId || currentSession.pdfProviderId;
@@ -379,186 +351,37 @@ function GenerationPreviewContent() {
}
).providerConfig;
const providerConfig = currentSession.pdfProviderConfig || legacySourceConfig;
- // The caller-supplied endpoint (fingerprinted into the cache key)
- // and the derivation domain (L6: `alidocmind` exists in both the
- // document and media registries at the same version, so the page —
- // which knows which path a source takes — must discriminate them).
- const sourceBaseUrl = providerConfig?.baseUrl?.trim() || undefined;
- const sourceDomain: ExtractionCacheDomain =
- source.mimeType && SUPPORTED_MEDIA_MIME_TYPES.includes(source.mimeType.toLowerCase())
- ? 'media'
- : 'doc';
- // The config fingerprint feeds ONLY the in-run dedupe key below. A
- // computation failure (Web Crypto unavailable) must never fail the
- // extraction: the source falls back to un-deduped extraction, and
- // the cache lookup/write paths recompute the fingerprint under
- // their own degrade-to-miss guards (RFC #1153 part 1, M1).
- let sourceConfigFingerprint: string | undefined;
- try {
- sourceConfigFingerprint = await computeConfigFingerprint(sourceBaseUrl);
- } catch (error) {
- log.warn(
- 'Config fingerprinting failed; skipping in-run dedupe for this source:',
- error,
- );
+ const documentBlob = await loadDocumentBlob(source.storageKey);
+ if (!(documentBlob instanceof Blob) || documentBlob.size === 0) {
+ throw new Error(t('generation.courseMaterialLoadFailed'));
}
-
- // The extractor the route is expected to run under, resolved
- // client-side. It feeds the extraction-cache lookup, which must
- // happen BEFORE the extract API is called: the cache key is
- // (content digest × domain × extractor identity × config
- // fingerprint), and on a hit the rebuilt parse result skips the
- // paid extraction entirely.
- const expectedExtractor = source.contentDigest
- ? resolveExpectedExtractor(source.mimeType ?? 'application/pdf', providerId)
- : null;
-
- // Cache lookup first; on a miss this runs the extract API (asset-id
- // JSON form with a per-source fallback to the legacy byte upload,
- // see `fetchExtractionResponse`) and caches the result best-effort.
- // The full outcome is kept — a server-backed run needs the
- // best-effort cache write's derived image ids, not just the data.
- const runExtraction = () =>
- fetchExtractionWithCache({
- serverBacked,
- hasAssetId: Boolean(source.assetId),
- logWarning: (message, ...args) => log.warn(message, ...args),
- fetchers: {
- submitAssetIdForm: async () => {
- // Server-backed pool: extract by the asset id allocated at
- // upload. The server resolves the original bytes from the
- // server asset store, so no bytes cross the wire.
- const persistenceHeaders = await getPersistenceRequestHeaders();
- return fetch('/api/extract-document', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json', ...persistenceHeaders },
- body: JSON.stringify({
- assetId: source.assetId,
- fileName: source.name,
- mimeType: source.mimeType,
- providerId: providerId || undefined,
- apiKey: providerConfig?.apiKey?.trim() ? providerConfig.apiKey : undefined,
- baseUrl: providerConfig?.baseUrl?.trim()
- ? providerConfig.baseUrl
- : undefined,
- // AliDocMind uses AK/SK instead of a single apiKey.
- accessKeyId: providerConfig?.accessKeyId?.trim()
- ? providerConfig.accessKeyId
- : undefined,
- accessKeySecret: providerConfig?.accessKeySecret?.trim()
- ? providerConfig.accessKeySecret
- : undefined,
- }),
- signal,
- });
- },
- submitByteForm: async () => {
- // Browser-backed pool (or a legacy storageKey-only session,
- // or a fallback after a failed asset-id form): the server
- // cannot resolve a browser-side asset, so upload the bytes
- // exactly as before.
- const documentBlob = await loadDocumentBlob(source.storageKey);
- if (!documentBlob) {
- throw new Error(t('generation.courseMaterialLoadFailed'));
- }
-
- if (!(documentBlob instanceof Blob) || documentBlob.size === 0) {
- log.error('Invalid course material blob:', {
- source: source.name,
- type: typeof documentBlob,
- size: documentBlob instanceof Blob ? documentBlob.size : 'N/A',
- });
- throw new Error(t('generation.courseMaterialLoadFailed'));
- }
-
- const documentFile = new File([documentBlob], source.name || 'document.pdf', {
- type: source.mimeType || documentBlob.type || 'application/pdf',
- });
-
- const parseFormData = new FormData();
- parseFormData.append('file', documentFile);
- if (providerId) parseFormData.append('providerId', providerId);
- if (providerConfig?.apiKey?.trim()) {
- parseFormData.append('apiKey', providerConfig.apiKey);
- }
- if (providerConfig?.baseUrl?.trim()) {
- parseFormData.append('baseUrl', providerConfig.baseUrl);
- }
- // AliDocMind uses AK/SK instead of a single apiKey.
- if (providerConfig?.accessKeyId?.trim()) {
- parseFormData.append('accessKeyId', providerConfig.accessKeyId);
- }
- if (providerConfig?.accessKeySecret?.trim()) {
- parseFormData.append('accessKeySecret', providerConfig.accessKeySecret);
- }
-
- return fetch('/api/extract-document', {
- method: 'POST',
- body: parseFormData,
- signal,
- });
- },
- },
- contentDigest: source.contentDigest,
- domain: sourceDomain,
- extractorId: expectedExtractor?.extractorId,
- extractorVersion: expectedExtractor?.extractorVersion,
- baseUrl: sourceBaseUrl,
- sourceDocAssetId: source.assetId,
- parseFailedMessage: t('generation.courseMaterialParseFailed'),
- // Part 2 B: a server-backed deployment names images by their
- // allocated pool asset ids, so a cache hit feeds generation by
- // id instead of materializing image bytes client-side.
- imageMappingMode: serverBacked ? 'asset-id' : 'data-url',
- });
- // K3 (in-run dedupe): sources whose extraction cache key is
- // identical (same content digest + domain + expected extractor +
- // config fingerprint) share ONE extraction; two same-byte files
- // never both pay, and per-source config differences never share.
- // The memo now carries the FULL outcome, so a deduplicated second
- // source reaches the shared derivation's image asset ids through
- // the winner's cacheWrite (part 2 B).
- const extractionOutcome =
- source.contentDigest && expectedExtractor && sourceConfigFingerprint
- ? await deduplicateExtraction.run(
- {
- contentDigest: source.contentDigest,
- domain: sourceDomain,
- extractorId: expectedExtractor.extractorId,
- extractorVersion: expectedExtractor.extractorVersion,
- configFingerprint: sourceConfigFingerprint,
- },
- runExtraction,
- )
- : await runExtraction();
- const parseData = extractionOutcome.data;
-
- // Part 2 B: on a server-backed deployment the extracted images are
- // pool assets (part 1). A cache hit carries their ids on the
- // rebuilt result; a fresh extraction's ids come from the
- // best-effort cache write — awaited here because the session must
- // name the images by id without materializing their bytes. When
- // no ids are available (KV unavailable), the source falls back to
- // the data-URL transport below — the routes accept both.
- //
- // N2: the await is BOUNDED by the same 15 s budget as the
- // upload-time ingest drain, so a server that accepts the
- // connection but never answers degrades to the per-source
- // data-URL fallback instead of hanging startGeneration. The
- // detached write keeps running and benefits the NEXT run (the
- // extraction-cache L5 contract stays true — it is this caller's
- // await that is bounded).
- let imageAssetIds: Map | undefined;
- if (serverBacked && !extractionOutcome.cacheHit) {
- const derived = await awaitWithFallback(
- (extractionOutcome.cacheWrite ?? Promise.resolve([])).catch(() => []),
- DEFAULT_INGEST_AWAIT_TIMEOUT_MS,
- [],
- );
- if (derived.length > 0) {
- imageAssetIds = new Map(derived.map((image) => [image.id, image.assetId]));
- }
+ const documentFile = new File([documentBlob], source.name || 'document.pdf', {
+ type: source.mimeType || documentBlob.type || 'application/pdf',
+ });
+ const parseFormData = new FormData();
+ parseFormData.append('file', documentFile);
+ if (providerId) parseFormData.append('providerId', providerId);
+ if (providerConfig?.apiKey?.trim())
+ parseFormData.append('apiKey', providerConfig.apiKey);
+ if (providerConfig?.baseUrl?.trim())
+ parseFormData.append('baseUrl', providerConfig.baseUrl);
+ if (providerConfig?.accessKeyId?.trim()) {
+ parseFormData.append('accessKeyId', providerConfig.accessKeyId);
}
+ if (providerConfig?.accessKeySecret?.trim()) {
+ parseFormData.append('accessKeySecret', providerConfig.accessKeySecret);
+ }
+ const parseResponse = await fetch('/api/extract-document', {
+ method: 'POST',
+ body: parseFormData,
+ signal,
+ });
+ if (!parseResponse.ok) throw new Error(t('generation.courseMaterialParseFailed'));
+ const parseResult = await parseResponse.json();
+ if (!parseResult.success || !parseResult.data) {
+ throw new Error(t('generation.courseMaterialParseFailed'));
+ }
+ const parseData = parseResult.data;
const rawImages = parseData.metadata?.pdfImages;
const images = rawImages
? rawImages.map((img: ParsedDocumentResponseImage) => ({
@@ -568,8 +391,6 @@ function GenerationPreviewContent() {
description: img.description,
width: img.width,
height: img.height,
- ...(img.assetId ? { assetId: img.assetId } : {}),
- ...(imageAssetIds?.get(img.id) ? { assetId: imageAssetIds.get(img.id) } : {}),
}))
: ((parseData.images as string[] | undefined) ?? []).map((src, i) => ({
id: `img_${i + 1}`,
@@ -596,22 +417,7 @@ function GenerationPreviewContent() {
);
const bundle = buildDocumentBundle(parsedParts);
- // Part 2 B/C + N4: the byte transport is decided PER SOURCE, not for
- // the whole bundle. A server-backed source whose images all carry
- // allocated asset ids feeds generation by id; a source with any image
- // lacking an id (a failed best-effort cache write, a legacy session)
- // materializes ITS images into IndexedDB as data URLs — one source's
- // failure never silently drops another source's images. The resulting
- // `imageMapping` may MIX asset ids and data URLs; the routes and
- // `resolveImageIds` are shape-based and accept both.
- const { storageIds: perImageStorageIds } = await materializeBundleImages(
- serverBacked,
- bundle.images,
- storeImages,
- );
- const imageStorageIds = perImageStorageIds.filter(
- (storageId): storageId is string => storageId !== undefined,
- );
+ const imageStorageIds = await storeImages(bundle.images);
const pdfImages: PdfImage[] = bundle.images.map((img, i) => ({
id: img.id,
@@ -625,10 +431,7 @@ function GenerationPreviewContent() {
sourceDocumentName: img.sourceDocumentName,
sourceDocumentOrder: img.sourceDocumentOrder,
visionPriority: img.visionPriority,
- // Per source: id-fed images carry their pool asset id; materialized
- // images carry their IndexedDB storage id (never both).
- ...(img.assetId && perImageStorageIds[i] === undefined ? { assetId: img.assetId } : {}),
- ...(perImageStorageIds[i] !== undefined ? { storageId: perImageStorageIds[i] } : {}),
+ storageId: imageStorageIds[i],
}));
// Update session with extracted document data
@@ -715,35 +518,8 @@ function GenerationPreviewContent() {
}
// Load imageMapping early (needed for both outline and scene generation).
- // The transport is decided once per run by the same probe as part 0/1
- // (RFC #1153 part 2 B): a server-backed pool names images by their
- // allocated asset ids (the extracted images are pool assets — part 1); a
- // browser-backed pool materializes base64 data URLs exactly as before.
- // Per source (N4) the mapping may MIX allocated asset ids and IndexedDB
- // data URLs — a source whose cache write failed materializes its own
- // images — and the routes / `resolveImageIds` are shape-based, so both
- // value kinds ride the same mapping.
let imageMapping: ImageMapping = {};
- const sessionImages = currentSession.pdfImages ?? [];
- if (serverBacked) {
- const mapped: ImageMapping = {};
- for (const img of sessionImages) {
- if (img.assetId) mapped[img.id] = img.assetId;
- }
- const storageIds = sessionImages
- .filter((img): img is PdfImage & { storageId: string } => !img.assetId && !!img.storageId)
- .map((img) => img.storageId);
- if (storageIds.length > 0) {
- Object.assign(mapped, await loadImageMapping(storageIds));
- } else if (currentSession.imageStorageIds && currentSession.imageStorageIds.length > 0) {
- // Legacy session: storage ids live on the session, not on pdfImages.
- Object.assign(mapped, await loadImageMapping(currentSession.imageStorageIds));
- }
- if (Object.keys(mapped).length > 0) {
- log.debug('Using per-source imageMapping (server-backed pool, ids + data URLs)');
- imageMapping = mapped;
- }
- } else if (currentSession.imageStorageIds && currentSession.imageStorageIds.length > 0) {
+ if (currentSession.imageStorageIds && currentSession.imageStorageIds.length > 0) {
log.debug('Loading images from IndexedDB');
imageMapping = await loadImageMapping(currentSession.imageStorageIds);
} else if (
diff --git a/app/globals.css b/app/globals.css
index d9aa954..fee2b44 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -1,6 +1,8 @@
@import 'tailwindcss';
@import 'tw-animate-css';
@import 'shadcn/tailwind.css';
+/* Workbench chat (agent workbench surface): scoped .wbchat tokens + prose skin. */
+@import '../components/workbench/chat/workbench-chat.css';
/* Streamdown (AI sidebar markdown) styles itself with Tailwind utilities —
Tailwind must scan its dist so those classes get generated. */
diff --git a/app/layout.tsx b/app/layout.tsx
index f3bffa0..e66ab91 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -11,6 +11,7 @@ import { Toaster } from '@/components/ui/sonner';
import { ServerProvidersInit } from '@/components/server-providers-init';
import { StorageHealthNotice } from '@/components/storage-health-notice';
import { AccessCodeGuard } from '@/components/access-code-guard';
+import { ProSwapWatcher } from '@/components/workbench/ProSwapWatcher';
// The UI font is loaded from @fontsource's stylesheet rather than next/font,
// because only the stylesheet carries the per-subset `unicode-range`
@@ -47,6 +48,7 @@ export default function RootLayout({
+ {children}
{/* After the Toaster: this one raises a toast on mount when
diff --git a/app/page.tsx b/app/page.tsx
index f83a9ed..6dc44c0 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -40,20 +40,12 @@ import { GenerationToolbar } from '@/components/generation/generation-toolbar';
import { AgentBar } from '@/components/agent/agent-bar';
import { useTheme } from '@/lib/hooks/use-theme';
import { nanoid } from 'nanoid';
-import { putAsset, removeAsset } from '@/lib/media/asset-pool';
import { deleteDocumentBlob, storeDocumentBlob } from '@/lib/utils/image-storage';
import { normalizeDocumentMimeType } from '@/lib/document/mime';
import {
courseMaterialFingerprint,
dedupeCourseMaterialFiles,
} from '@/lib/document/course-materials';
-import {
- awaitPendingIngests,
- DEFAULT_INGEST_AWAIT_TIMEOUT_MS,
- resolvedAssetIdForIngest,
-} from '@/lib/document/extract-source';
-import { computeContentDigest } from '@/lib/document/extraction-cache';
-import { upsertMaterialLibraryEntry } from '@/lib/materials/library';
import type {
SelectedCourseMaterial,
SessionDocumentSource,
@@ -90,9 +82,19 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip
import { useDraftCache } from '@/lib/hooks/use-draft-cache';
import { SpeechButton } from '@/components/audio/speech-button';
import { useImportClassroom } from '@/lib/import/use-import-classroom';
-import { isPptxImportEnabled, shouldShowVocationalTestUi } from '@/lib/config/feature-flags';
+import {
+ isProWorkbenchEnabled,
+ isPptxImportEnabled,
+ shouldShowVocationalTestUi,
+} from '@/lib/config/feature-flags';
import { useImportPptx } from '@/lib/import/use-import-pptx';
import { InteractiveModeButton } from '@/components/generation/interactive-mode-button';
+import { ProBadge } from '@/components/workbench/ProBadge';
+import { arrivedByProSwap, startProSwap } from '@/lib/workbench/pro-swap';
+import {
+ readLastWorkspaceSessionId,
+ workspaceResumeHref,
+} from '@/lib/workbench/workspace-session-memory';
const log = createLogger('Home');
@@ -105,6 +107,9 @@ const INTERACTIVE_MODE_STORAGE_KEY = 'interactiveModeEnabled';
// flag until it's wired end-to-end, so the UI doesn't expose a no-op button.
const PPTX_IMPORT_ENABLED = isPptxImportEnabled();
+/** The configured runtime probe result, retained across client navigations. */
+let workbenchRuntimeCache: boolean | null = null;
+
interface FormState {
courseMaterials: SelectedCourseMaterial[];
requirement: string;
@@ -125,7 +130,39 @@ function HomePage() {
const { t } = useI18n();
const { theme, setTheme } = useTheme();
const router = useRouter();
+ // Do not replay the classic hero's entrance after the route handoff already
+ // carried the lockup and composer into place.
+ const [swapped] = useState(arrivedByProSwap);
+ const heroEnter = (from: Record) => (swapped ? false : from);
const showVocationalTestUi = shouldShowVocationalTestUi();
+ const workbenchBuildEnabled = isProWorkbenchEnabled();
+ const [workbenchRuntimeEnabled, setWorkbenchRuntimeEnabled] = useState(
+ workbenchRuntimeCache === true,
+ );
+ useEffect(() => {
+ if (!workbenchBuildEnabled || workbenchRuntimeCache !== null) return;
+ let cancelled = false;
+ fetch('/api/agent/runtime')
+ .then((response) => (response.ok ? response.json() : null))
+ .then((body) => {
+ workbenchRuntimeCache = body?.enabled === true;
+ if (!cancelled) setWorkbenchRuntimeEnabled(workbenchRuntimeCache);
+ })
+ .catch(() => {
+ // A failed probe keeps the entry hidden and allows a later visit to retry.
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [workbenchBuildEnabled]);
+ const workbenchEntryEnabled = workbenchBuildEnabled && workbenchRuntimeEnabled;
+ const enterWorkbench = () => {
+ const href = workspaceResumeHref(readLastWorkspaceSessionId());
+ startProSwap(href, (next) => router.push(next));
+ };
+ useEffect(() => {
+ if (workbenchEntryEnabled) router.prefetch('/workspace');
+ }, [router, workbenchEntryEnabled]);
const [form, setForm] = useState(initialFormState);
const [settingsOpen, setSettingsOpen] = useState(false);
const [settingsSection, setSettingsSection] = useState<
@@ -218,21 +255,6 @@ function HomePage() {
const toolbarRef = useRef(null);
const textareaRef = useRef(null);
const thumbnailsRef = useRef>({});
- // In-flight asset-pool ingests, keyed by course material id, so removing a
- // file whose pool entry is still being allocated can still release it.
- const pendingMaterialIngestsRef = useRef(new Map>());
- // In-flight content-digest computations, keyed the same way. The digest is
- // the stable half of the extraction-cache key, so the session build reads it
- // from the settled promise just like the asset id (see
- // `resolvedAssetIdForIngest` for the commit-timing rationale).
- const pendingMaterialDigestsRef = useRef(new Map>());
- // Course-material ids whose ingest was ABANDONED: removed from the
- // selection (the source file handle is gone) or released at prep-timeout
- // because no durable holder would ever exist for the id. The material-library
- // upsert skips these — minting would record bytes the user deliberately
- // discarded (RFC #1153 part 2, N1). Written synchronously by the removal
- // path and the prep-timeout drain, read by the upsert settlement below.
- const abandonedMaterialIngestIdsRef = useRef(new Set());
const replaceThumbnails = (slides: Record) => {
const previous = thumbnailsRef.current;
@@ -496,108 +518,11 @@ function HomePage() {
}
};
- // Ingest a selected file into the asset pool as soon as it is picked, so the
- // material gets its allocated asset id at upload time (RFC #1153 part 0).
- // The file still appears in the form immediately; the asset id is patched in
- // when the pool entry lands. A failure only loses the pool entry — the
- // source keeps working through the legacy blob-stash byte upload — so it is
- // logged, not surfaced.
- //
- // A tab closing mid-ingest can still orphan a pool entry: the browser gives
- // no reliable release hook once the page tears down. Accepted — the
- // material-library milestone of RFC #1153 brings visibility and management
- // for such entries.
- const ingestCourseMaterialIntoPool = (addition: SelectedCourseMaterial) => {
- const ingest = putAsset(addition.file).then((assetId) => {
- setForm((prev) =>
- prev.courseMaterials.some((item) => item.id === addition.id)
- ? {
- ...prev,
- courseMaterials: prev.courseMaterials.map((item) =>
- item.id === addition.id ? { ...item, assetId } : item,
- ),
- }
- : prev,
- );
- return assetId;
- });
- // The pending entry is the durable release handle for this pool entry and
- // is intentionally NOT deleted when the ingest settles: deleting it inside
- // the ingest's own settlement would race the state patch above (React
- // commits it after this promise resolves), orphaning the entry if the user
- // removes the file in that window. Only the removal path deletes it (see
- // removeCourseMaterial), so an entry is always retrievable until the id
- // has a durable holder. Entries for never-removed sources stay until the
- // page unmounts — bounded by the files picked in one session.
- pendingMaterialIngestsRef.current.set(addition.id, ingest);
- void ingest.catch((error) => {
- log.error(`Failed to ingest course material "${addition.name}" into the asset pool:`, error);
- });
-
- // Content identity: the SHA-256 of the file bytes, computed in parallel
- // with the pool ingest (the file is already in memory for putAsset). It is
- // the stable half of the extraction-cache key — two uploads of the same
- // bytes get different allocated asset ids but the same digest. A digest
- // failure only means the source skips the extraction cache (a conservative
- // miss); it never blocks the upload or the extraction.
- const contentDigest = computeContentDigest(addition.file).catch((error) => {
- log.error(`Failed to compute the content digest for "${addition.name}":`, error);
- return undefined;
- });
- pendingMaterialDigestsRef.current.set(addition.id, contentDigest);
- void contentDigest.then((digest) => {
- if (digest === undefined) return;
- setForm((prev) =>
- prev.courseMaterials.some((item) => item.id === addition.id)
- ? {
- ...prev,
- courseMaterials: prev.courseMaterials.map((item) =>
- item.id === addition.id ? { ...item, contentDigest: digest } : item,
- ),
- }
- : prev,
- );
- });
-
- // Material library manifest (RFC #1153 part 2): once BOTH the ingest's
- // allocated asset id and the content digest have settled, upsert the
- // library entry keyed by digest — same bytes re-imported refresh the same
- // entry (`addedAt` bumped, `assetId` advanced). The library allocates its
- // OWN pool entry from the file bytes and stores that id, so the entry
- // stays resolvable after this selection's pool entry is released (N1,
- // RFC §5 root model). The upsert must NOT fire for a material whose
- // ingest was already abandoned — removed from the selection (the source
- // file handle is gone) or released at prep-timeout — so it is gated on
- // the same settlement as before AND on the abandoned set. Best-effort by
- // contract: a KV failure or a failed library allocation never fails the
- // upload.
- void Promise.all([ingest, contentDigest]).then(([, digest]) => {
- if (!digest) return;
- if (abandonedMaterialIngestIdsRef.current.has(addition.id)) return;
- void upsertMaterialLibraryEntry({
- file: addition.file,
- contentDigest: digest,
- name: addition.name,
- mimeType:
- normalizeDocumentMimeType({
- mimeType: addition.file.type,
- fileName: addition.file.name,
- }) || undefined,
- size: addition.size,
- }).catch((error) => {
- log.error(`Failed to record the material library entry for "${addition.name}":`, error);
- });
- });
- };
-
const addCourseMaterials = (files: File[]) => {
// The set is frozen for the duration of generate-prep: adding is inert
// while `preparingGenerate` is set (the toolbar affordance is disabled
// via the same state), so nothing can slip into the set mid-prep.
if (preparingGenerate) return;
- // Compute the additions before touching state: the ingest loop must not
- // run inside the setForm updater, which React may invoke more than once —
- // each replay would putAsset again and orphan an allocated id.
const dedupedFiles = dedupeCourseMaterialFiles(form.courseMaterials, files);
const startOrder = form.courseMaterials.length + 1;
const additions = dedupedFiles.map((file, index) => ({
@@ -610,10 +535,6 @@ function HomePage() {
order: startOrder + index,
}));
- for (const addition of additions) {
- ingestCourseMaterialIntoPool(addition);
- }
-
if (additions.length === 0) return;
setForm((prev) => {
// Pure updater: drop any addition the latest state already carries — by
@@ -637,36 +558,6 @@ function HomePage() {
// while `preparingGenerate` is set (the toolbar affordance is disabled
// via the same state), so nothing can slip out of the set mid-prep.
if (preparingGenerate) return;
- const removed = form.courseMaterials.find((item) => item.id === id);
- // The source file handle is gone: the material-library upsert must not
- // fire for this id once its ingest settles (N1). Mark it synchronously so
- // the settlement closure — which runs after this handler returns — skips
- // minting an entry for bytes the user deliberately discarded.
- abandonedMaterialIngestIdsRef.current.add(id);
- // Release the pool entry allocated for this file, mirroring the blob-stash
- // cleanup: if the ingest is still in flight, release once it lands.
- const release = removed?.assetId
- ? Promise.resolve(removed.assetId)
- : (pendingMaterialIngestsRef.current.get(id) ?? Promise.resolve(undefined));
- void release
- .then((assetId) => {
- if (assetId) return removeAsset(assetId);
- })
- .catch((error) => {
- log.error('Failed to release course material asset pool entry:', error);
- })
- .finally(() => {
- // This removal path is the sole consumer of the pending entry: the
- // pool entry has been released (or the ingest itself failed, leaving
- // nothing to release), so the entry can go. Deleting it here — rather
- // than in the ingest's own settlement — keeps it retrievable until
- // the id has a durable holder.
- pendingMaterialIngestsRef.current.delete(id);
- // The content digest has no release to perform; drop its pending entry
- // so a removed material cannot leak it into a later session build.
- pendingMaterialDigestsRef.current.delete(id);
- });
-
setForm((prev) => ({
...prev,
courseMaterials: prev.courseMaterials
@@ -710,46 +601,9 @@ function HomePage() {
}
: undefined;
- // Flip the generating UI state BEFORE the drain so the click visibly does
- // something even when an ingest stalls.
+ // Flip the generating UI state before material bytes are copied locally.
setPreparingGenerate(true);
- const unsettledIngestIds = new Set();
try {
- // Drain any in-flight ingests before building the session, so a resolved
- // asset id lands in the session instead of being dropped when this page
- // unmounts. The await is bounded (~15 s): on timeout, the unsettled
- // sources proceed with their storageKey and the legacy byte path, and
- // each late-resolving id is released since no durable holder will ever
- // exist for it. A rejected ingest is fine: that source proceeds with its
- // storageKey and the byte path. The drain loops until the pending map is
- // stable — despite the freeze guard, an add that slipped in before the
- // flag took effect is still drained (belt-and-braces).
- const awaitedIngestIds = new Set();
- for (;;) {
- const unawaited = [...pendingMaterialIngestsRef.current.entries()].filter(
- ([id]) => !awaitedIngestIds.has(id),
- );
- if (unawaited.length === 0) break;
- for (const [id] of unawaited) awaitedIngestIds.add(id);
- const batchUnsettled = await awaitPendingIngests(new Map(unawaited), {
- timeoutMs: DEFAULT_INGEST_AWAIT_TIMEOUT_MS,
- onUnsettled: (ingestId, ingest) => {
- unsettledIngestIds.add(ingestId);
- // The ingest was abandoned: no durable holder will ever exist for
- // its id, so release it when it lands — and mark it abandoned so
- // the material-library upsert skips minting an entry for bytes
- // the session deliberately discarded (N1).
- abandonedMaterialIngestIdsRef.current.add(ingestId);
- void ingest
- .then((assetId) => (assetId ? removeAsset(assetId) : undefined))
- .catch((error) => {
- log.error('Failed to release timed-out course material asset pool entry:', error);
- });
- },
- });
- for (const id of batchUnsettled) unsettledIngestIds.add(id);
- }
-
const userProfile = useUserProfileStore.getState();
const requirements: UserRequirements = {
requirement: form.requirement,
@@ -778,19 +632,6 @@ function HomePage() {
for (const [index, item] of frozenMaterials.entries()) {
const storageKey = await storeDocumentBlob(item.file);
storedDocumentKeys.push(storageKey);
- // The awaited ingests patched their asset ids into form state via
- // setForm, which this closure may not reflect yet; read the settled
- // value from the pending map so a just-resolved id still lands in
- // the session regardless of React commit timing. A timed-out ingest
- // is never awaited again — its source goes byte-path (no assetId).
- const settledAssetId = unsettledIngestIds.has(item.id)
- ? undefined
- : await resolvedAssetIdForIngest(pendingMaterialIngestsRef.current, item.id);
- // Same for the content digest: read the settled value (undefined
- // when the computation failed or never started) so the extraction
- // cache key is available in the session even before the form patch
- // commits. Digest is local and fast, so no time budget is needed.
- const settledContentDigest = await pendingMaterialDigestsRef.current.get(item.id);
documentSources.push({
id: item.id,
name: item.name,
@@ -802,12 +643,6 @@ function HomePage() {
}),
order: index + 1,
storageKey,
- // The asset id was allocated at upload; new sessions carry it so
- // a server-backed pool can extract by id instead of re-uploading.
- assetId: item.assetId ?? settledAssetId,
- // Content identity of the bytes: the stable half of the
- // extraction-cache key (RFC #1153 part 1).
- contentDigest: item.contentDigest ?? settledContentDigest,
providerId: pdfProviderId,
});
}
@@ -990,29 +825,39 @@ function HomePage() {
{/* ═══ Hero section: title + input (centered, wider) ═══ */}
{/* ── Logo ── */}
-
+
+
+ {workbenchEntryEnabled ? (
+
+
+
+ ) : null}
+
{/* ── Slogan ── */}
-
+
{/* ── Greeting + Profile + Agents ── */}
diff --git a/app/workbench/new/client.tsx b/app/workbench/new/client.tsx
new file mode 100644
index 0000000..619de63
--- /dev/null
+++ b/app/workbench/new/client.tsx
@@ -0,0 +1,139 @@
+'use client';
+
+/**
+ * Compatibility bridge for launch links shipped before the workspace composer
+ * started creating sessions in place. This route intentionally has no second
+ * composer: it consumes the legacy intent once, creates the session, and
+ * replaces itself with the canonical workspace URL.
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+import {
+ createWorkbenchSession,
+ WorkbenchApiError,
+ type WorkbenchMaterial,
+} from '@/lib/workbench/session-store';
+import type { CourseRef } from '@/lib/workbench/course-refs';
+import { workspaceHref } from '@/lib/workbench/workspace-panes';
+import { useI18n } from '@/lib/hooks/use-i18n';
+
+// Older deployed home composers may still write this key during a rolling deploy.
+const LEGACY_LAUNCH_HANDOFF_KEY = 'workbench.launchPrompt';
+
+interface LegacyLaunchIntent {
+ readonly prompt: string;
+ readonly skill?: string;
+ readonly materials?: WorkbenchMaterial[];
+ readonly courseRefs?: CourseRef[];
+}
+
+function parseLegacyHandoff(raw: string): LegacyLaunchIntent {
+ const trimmed = raw.trim();
+ if (trimmed.startsWith('{')) {
+ try {
+ const parsed = JSON.parse(trimmed) as LegacyLaunchIntent & { v?: number };
+ if (parsed?.v === 1 && typeof parsed.prompt === 'string') return parsed;
+ } catch {
+ // Old plain-string handoffs are handled below.
+ }
+ }
+ return { prompt: trimmed };
+}
+
+export function WorkbenchLaunchBridge() {
+ const router = useRouter();
+ const searchParams = useSearchParams();
+ const { t } = useI18n();
+ const launched = useRef(null);
+ const [error, setError] = useState(null);
+ const [attempt, setAttempt] = useState(0);
+ const [skillOverride, setSkillOverride] = useState(undefined);
+ const intent = useMemo(() => {
+ const prompt = searchParams.get('prompt')?.trim();
+ if (prompt) {
+ const skill = searchParams.get('skill')?.trim();
+ return { prompt, ...(skill ? { skill } : {}) };
+ }
+ if (typeof window === 'undefined') return null;
+ try {
+ const raw = window.sessionStorage.getItem(LEGACY_LAUNCH_HANDOFF_KEY);
+ return raw?.trim() ? parseLegacyHandoff(raw) : null;
+ } catch {
+ return null;
+ }
+ }, [searchParams]);
+ const skill = skillOverride === undefined ? intent?.skill : (skillOverride ?? undefined);
+
+ useEffect(() => {
+ const launchKey = `${attempt}:${skill ?? ''}`;
+ if (launched.current === launchKey) return;
+ launched.current = launchKey;
+ if (!intent?.prompt.trim()) {
+ router.replace('/workspace');
+ return;
+ }
+ createWorkbenchSession({
+ prompt: intent.prompt.trim(),
+ ...(skill ? { skill } : {}),
+ ...(intent.materials?.length ? { materials: intent.materials } : {}),
+ ...(intent.courseRefs?.length ? { courseRefs: intent.courseRefs } : {}),
+ })
+ .then((session) => {
+ if (session.courseRefsAccepted === false) {
+ toast.warning(t('workspace.courseMention.notAccepted'));
+ }
+ try {
+ window.sessionStorage.removeItem(LEGACY_LAUNCH_HANDOFF_KEY);
+ } catch {
+ // The session exists; a denied cleanup does not invalidate it.
+ }
+ router.replace(workspaceHref({ sessionId: session.id, courseId: null }));
+ })
+ .catch((cause: unknown) => {
+ if (
+ skill &&
+ cause instanceof WorkbenchApiError &&
+ cause.status === 400 &&
+ /unknown skill/i.test(cause.message)
+ ) {
+ toast.error(t('workbench.launch.unknownSkill'));
+ setSkillOverride(null);
+ setAttempt((current) => current + 1);
+ return;
+ }
+ setError(cause instanceof Error ? cause.message : t('workbench.launch.createFailed'));
+ });
+ }, [attempt, intent, router, skill, t]);
+
+ if (error) {
+ return (
+
+
{error}
+
+
+ {t('workbench.common.backToWorkspace')}
+
+
+ );
+ }
+
+ return (
+
+
+
+ );
+}
diff --git a/app/workbench/new/page.tsx b/app/workbench/new/page.tsx
new file mode 100644
index 0000000..22e827a
--- /dev/null
+++ b/app/workbench/new/page.tsx
@@ -0,0 +1,21 @@
+/**
+ * Backward-compatible bridge for historical `/workbench/new?prompt=&skill=`
+ * links and rolling-deployment sessionStorage handoffs. New launches happen
+ * directly inside `/workspace`; this route owns no composer or product UI.
+ */
+import { Suspense } from 'react';
+import { notFound } from 'next/navigation';
+import { isWorkbenchEntryEnabled } from '@/lib/workbench/entry-gate';
+import { WorkbenchLaunchBridge } from './client';
+
+export const dynamic = 'force-dynamic';
+
+export default function WorkbenchNewCompatibilityPage() {
+ if (!isWorkbenchEntryEnabled()) notFound();
+
+ return (
+
+
+
+ );
+}
diff --git a/app/workspace/page.tsx b/app/workspace/page.tsx
new file mode 100644
index 0000000..ed0adf3
--- /dev/null
+++ b/app/workspace/page.tsx
@@ -0,0 +1,42 @@
+/**
+ * `/workspace` — the Pro workspace home.
+ *
+ * Pro mode used to be a `useState` on `app/page.tsx`, which meant the global
+ * `SiteHeader` could not know about it and stacked a second navigation bar on
+ * top of the workspace's own sidebar. As a route it is addressable instead:
+ * `AppChrome` suppresses the header by path prefix, a refresh keeps you here,
+ * and the workspace can be linked to.
+ *
+ * The gate is server-side and checks the pair of workbench flags:
+ * `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` (build-time, client-visible) and
+ * the server-only configured runtime truth. A workspace whose
+ * every submit 404s is worse than no workspace, so either flag off redirects
+ * to `/` rather than rendering. `/` hides its Pro badge behind the same pair,
+ * learned through the `/api/agent/runtime` probe (the client cannot read the
+ * server flag), so the entry and the destination agree.
+ *
+ * `force-dynamic` keeps the flags request-scoped instead of baking them into a
+ * prerender.
+ *
+ * The Suspense boundary covers the route seam that reads the initial deep-link
+ * snapshot from `useSearchParams`. Once mounted, the workspace owns pane state
+ * locally and mirrors it with the History API, so ordinary pane changes do not
+ * ask the server route to render again.
+ *
+ */
+import { Suspense } from 'react';
+import { redirect } from 'next/navigation';
+import { isWorkbenchEntryEnabled } from '@/lib/workbench/entry-gate';
+import { WorkspaceEntry } from '@/components/workbench/WorkspaceEntry';
+
+export const dynamic = 'force-dynamic';
+
+export default function WorkspacePage() {
+ if (!isWorkbenchEntryEnabled()) redirect('/');
+
+ return (
+
+
+
+ );
+}
diff --git a/components/ai-elements/prompt-input.tsx b/components/ai-elements/prompt-input.tsx
index 3826687..e2da563 100644
--- a/components/ai-elements/prompt-input.tsx
+++ b/components/ai-elements/prompt-input.tsx
@@ -1018,10 +1018,9 @@ interface SpeechRecognitionErrorEvent extends Event {
error: string;
}
-// Window.SpeechRecognition / webkitSpeechRecognition are declared globally by
-// @assistant-ui/core's speech adapter; we deliberately do NOT re-augment them
-// here (an `any` re-declaration conflicts with that typing). The local
-// `SpeechRecognition` interface above is the richer instance shape we use.
+// Window.SpeechRecognition / webkitSpeechRecognition have minimal constructor
+// declarations in types/web-speech.d.ts. The local `SpeechRecognition`
+// interface above is the richer instance shape this component consumes.
export type PromptInputSpeechButtonProps = ComponentProps & {
textareaRef?: RefObject;
diff --git a/components/canvas/canvas-area.tsx b/components/canvas/canvas-area.tsx
index 26ea78a..c8cde09 100644
--- a/components/canvas/canvas-area.tsx
+++ b/components/canvas/canvas-area.tsx
@@ -1,6 +1,6 @@
'use client';
-import { useCallback } from 'react';
+import { useCallback, type ReactNode } from 'react';
import { motion, AnimatePresence } from 'motion/react';
import { Play } from 'lucide-react';
import { cn } from '@/lib/utils';
@@ -12,6 +12,8 @@ import type { CanvasToolbarProps } from '@/components/canvas/canvas-toolbar';
import type { Scene, StageMode } from '@/lib/types/stage';
import { useI18n } from '@/lib/hooks/use-i18n';
import { ClassroomCompletePageConnected } from '@/components/scene-renderers/classroom-complete';
+import { ContainBox } from '@/components/edit/ContainBox';
+import { useInWorkbenchPanel } from '@/lib/workbench/panel-context';
interface CanvasAreaProps extends CanvasToolbarProps {
readonly currentScene: Scene | null;
@@ -53,6 +55,7 @@ export function CanvasArea({
onRetryGeneration,
}: CanvasAreaProps) {
const { t } = useI18n();
+ const inWorkbenchPanel = useInWorkbenchPanel();
const showControls = mode === 'playback' && !whiteboardOpen;
const showPlayHint =
showControls &&
@@ -96,9 +99,11 @@ export function CanvasArea({
: 'bg-gray-50/30 dark:bg-gray-900/30',
)}
>
-
)}
-
+
{/* ── Canvas Toolbar — in document flow, only when not merged into roundtable ── */}
@@ -278,3 +283,42 @@ export function CanvasArea({
+
+ );
+}
diff --git a/components/classroom/ClassroomSurface.tsx b/components/classroom/ClassroomSurface.tsx
new file mode 100644
index 0000000..649a7a2
--- /dev/null
+++ b/components/classroom/ClassroomSurface.tsx
@@ -0,0 +1,391 @@
+'use client';
+
+/**
+ * ClassroomSurface — the classroom, wherever it is mounted.
+ *
+ * This is the body `/classroom/[id]` has always had: the load pipeline, the
+ * generation-resume policy and the `Stage` dispatch under `ThemeProvider` /
+ * `MediaStageProvider`. It moved out of the route file for exactly one reason
+ * — the Pro workspace's third pane hosts the REAL classroom, not a preview and
+ * not an iframe, so both surfaces must run the same code rather than two
+ * copies that drift.
+ *
+ * `variant` is only layout/load-context: `page` fills the viewport and treats
+ * a course that cannot be found as terminal; `pane` fills its column and runs
+ * a bounded availability probe because a newly linked course may be committed
+ * shortly afterward. Neither host accepts conversation/session state. A
+ * classroom's lifecycle is keyed only by its course id; document and manifest
+ * data then converge in place as writers update them.
+ *
+ * The reference (live deployment) additionally runs non-owner visitor
+ * hydration, a transport-persistence UI fence and a background uploader; all
+ * three depend on server-side ownership/persistence machinery this workspace
+ * does not have, so they are dropped and the load follows the ordinary
+ * single-user path (`app/classroom/[id]/page.tsx`).
+ */
+
+import { Stage } from '@/components/stage';
+import { ThemeProvider } from '@/lib/hooks/use-theme';
+import { useStageStore } from '@/lib/store';
+import { useSettingsStore } from '@/lib/store/settings';
+import { claimStageSceneLoadToken, isCurrentStageSceneLoadToken } from '@/lib/store/stage';
+import { loadImageMapping } from '@/lib/utils/image-storage';
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { useSceneGenerator } from '@/lib/hooks/use-scene-generator';
+import { useMediaGenerationStore } from '@/lib/store/media-generation';
+import { useWhiteboardHistoryStore } from '@/lib/store/whiteboard-history';
+import { useCanvasStore } from '@/lib/store/canvas';
+import { createLogger } from '@/lib/logger';
+import { MediaStageProvider } from '@/lib/contexts/media-stage-context';
+import { generateMediaForOutlines } from '@/lib/media/media-orchestrator';
+import { useI18n } from '@/lib/hooks/use-i18n';
+import { FileQuestion, Loader2 } from 'lucide-react';
+import Link from 'next/link';
+import { useAgentRegistry } from '@/lib/orchestration/registry/store';
+import {
+ applyClassroomStageAndScenes,
+ defaultClassroomLoadDeps,
+ runClassroomLoad,
+} from '@/lib/classroom/load-classroom';
+import {
+ paneAvailabilityRetryDelay,
+ shouldResumeClassroomGeneration,
+} from '@/lib/classroom/progressive-load-policy';
+
+const log = createLogger('Classroom');
+
+type ClassroomLoadOutcome = 'loaded' | 'unavailable' | 'failed' | 'cancelled';
+
+// stage_link can become visible shortly before its document. Probe only that
+// explicit availability gap, with a small bounded backoff; media conversion
+// and ordinary failures never enter this schedule.
+export function ClassroomSurface({
+ classroomId,
+ variant = 'page',
+}: {
+ readonly classroomId: string;
+ readonly variant?: 'page' | 'pane';
+}) {
+ const { loadFromStorage } = useStageStore();
+ const loadedClassroomId = useStageStore((s) => s.stage?.id ?? null);
+ const { t } = useI18n();
+ // The retry loop below reads the message after async gaps, so it must see
+ // the CURRENT translation (a locale switch may have happened since mount).
+ // Written in an effect, not during render.
+ const notFoundMessageRef = useRef(t('classroom.notFound'));
+ useEffect(() => {
+ notFoundMessageRef.current = t('classroom.notFound');
+ }, [t]);
+
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState(null);
+ /**
+ * The load resolved and no source has this course. A TERMINAL state, kept
+ * separate from `error`: an error offers a retry, and there is nothing here
+ * to retry.
+ *
+ * The copy it renders is deliberately the SAME whether the course was
+ * deleted or never existed.
+ */
+ const [notFound, setNotFound] = useState(false);
+
+ const generationStartedRef = useRef(false);
+
+ const { generateRemaining, retrySingleOutline, stop } = useSceneGenerator({
+ onComplete: () => {
+ log.info('[Classroom] All scenes generated');
+ },
+ });
+
+ const loadClassroom = useCallback(
+ async (isEffectCurrent: () => boolean = () => true): Promise => {
+ const loadToken = claimStageSceneLoadToken();
+ const isCurrent = () => isEffectCurrent() && isCurrentStageSceneLoadToken(loadToken);
+ let outcome: ClassroomLoadOutcome = 'loaded';
+
+ try {
+ await runClassroomLoad({
+ classroomId,
+ loadToken,
+ isCurrent,
+ loadFromStorage,
+ getCurrentStage: () => useStageStore.getState().stage,
+ fetchClassroom: defaultClassroomLoadDeps.fetchClassroom,
+ applyFallbackScenes: (args) =>
+ defaultClassroomLoadDeps.applyFallbackScenes({
+ ...args,
+ isCurrent,
+ applyStageAndScenes: applyClassroomStageAndScenes,
+ }),
+ loadRestoredMediaTasks: defaultClassroomLoadDeps.loadRestoredMediaTasks,
+ applyRestoredMediaTasks: defaultClassroomLoadDeps.applyRestoredMediaTasks,
+ discardRestoredMediaTasks: defaultClassroomLoadDeps.discardRestoredMediaTasks,
+ loadLegacyAgentFallbacks: defaultClassroomLoadDeps.loadLegacyAgentFallbacks,
+ commitMigratedAgentConfigs: defaultClassroomLoadDeps.commitMigratedAgentConfigs,
+ applyGeneratedAgents: defaultClassroomLoadDeps.applyGeneratedAgents,
+ getSettings: () => useSettingsStore.getState(),
+ getAgent: (id) => useAgentRegistry.getState().getAgent(id),
+ restoreAgentSelection: defaultClassroomLoadDeps.restoreAgentSelection,
+ setError,
+ setLoading,
+ log,
+ });
+ if (!isCurrent()) return 'cancelled';
+ // The load completed without landing this course in the store. The
+ // reference learns the same fact from a server 404; here the absence
+ // of a stage after every source answered is the equivalent signal. A
+ // standalone URL can give a definitive answer; inside the workspace
+ // the pane treats it as the bounded availability gap instead of
+ // replacing its lifecycle.
+ if (useStageStore.getState().stage?.id !== classroomId) {
+ if (variant === 'page') {
+ setNotFound(true);
+ return 'loaded';
+ }
+ outcome = 'unavailable';
+ }
+ return isCurrent() ? outcome : 'cancelled';
+ } catch (error) {
+ log.error('Failed to load classroom:', error);
+ if (isCurrent()) {
+ setError(error instanceof Error ? error.message : 'Failed to load classroom');
+ setLoading(false);
+ }
+ return isCurrent() ? 'failed' : 'cancelled';
+ }
+ },
+ [classroomId, loadFromStorage, variant],
+ );
+
+ useEffect(() => {
+ // Reset loading state on course switch to unmount Stage during transition,
+ // preventing stale data from syncing back to the new course
+ /* eslint-disable react-hooks/set-state-in-effect -- Course switch must hide stale Stage before async load */
+ setLoading(true);
+ setError(null);
+ setNotFound(false);
+ /* eslint-enable react-hooks/set-state-in-effect */
+ generationStartedRef.current = false;
+
+ // Clear previous classroom's media tasks to prevent cross-classroom contamination.
+ // Placeholder IDs (gen_img_1, gen_vid_1) are NOT globally unique across stages,
+ // so stale tasks from a previous classroom would shadow the new one's.
+ const mediaStore = useMediaGenerationStore.getState();
+ mediaStore.revokeObjectUrls();
+ useMediaGenerationStore.setState({ tasks: {} });
+
+ // Clear whiteboard history to prevent snapshots from a previous course leaking in.
+ useWhiteboardHistoryStore.getState().clearHistory();
+
+ // Reset edit-time canvas selection/scale: the classroom load paths set
+ // mode:'playback' via raw setState (not setMode), so an unfinished Pro-mode
+ // session in the previous course wouldn't otherwise clear its canvas state.
+ useCanvasStore.getState().resetCanvasState();
+
+ let cancelled = false;
+ let retryTimer: ReturnType | null = null;
+ let availabilityAttempt = 0;
+ const loadUntilAvailable = async () => {
+ if (cancelled) return;
+ // A previous pane attempt may have observed a transient read failure.
+ // Clear only its presentation before retrying; do not raise `loading`
+ // again, so an already mounted classroom never flashes away.
+ if (variant === 'pane') setError(null);
+ const outcome = await loadClassroom(() => !cancelled);
+ if (cancelled || variant !== 'pane' || outcome !== 'unavailable') return;
+
+ const delay = paneAvailabilityRetryDelay(availabilityAttempt);
+ availabilityAttempt += 1;
+ if (delay !== null) {
+ retryTimer = setTimeout(loadUntilAvailable, delay);
+ } else {
+ setLoading(false);
+ setError(notFoundMessageRef.current);
+ }
+ };
+ void loadUntilAvailable();
+
+ // Cancel ongoing generation when classroomId changes or component unmounts
+ return () => {
+ cancelled = true;
+ if (retryTimer) clearTimeout(retryTimer);
+ stop();
+ };
+ }, [classroomId, loadClassroom, stop, variant]);
+
+ // Auto-resume generation for pending outlines (owner only). The reference
+ // additionally gates on a transport-persistence UI fence and the store's
+ // `isOwner`; neither exists here (single-user, no server persistence), so
+ // the fence is a constant false and ownership is expressed by
+ // `outlineProducer`: a course whose document a server job produced is
+ // server-owned, not client-authored, and therefore not this browser's to
+ // regenerate.
+ useEffect(() => {
+ if (
+ !shouldResumeClassroomGeneration({
+ loading,
+ error,
+ transportPersistenceFenced: false,
+ generationStarted: generationStartedRef.current,
+ })
+ ) {
+ return;
+ }
+ const state = useStageStore.getState();
+ // Producer ownership is document data, not conversation status. A
+ // server-job course never starts a second browser-side generator no matter
+ // which chat is open (or whether any chat is open).
+ if (state.outlineProducer === 'server-job') {
+ generationStartedRef.current = true;
+ log.info('[Classroom] A server-side job owns this course; the browser will not generate.');
+ return;
+ }
+
+ const { outlines, scenes, stage, generationComplete } = state;
+
+ // Check if there are pending outlines. A finished deck is frozen for
+ // editing: deleting a slide leaves its outline orphaned, but that must not
+ // be treated as an interrupted generation and regenerated. Only resume
+ // when generation has not completed.
+ const completedOrders = new Set(scenes.map((s) => s.order));
+ const hasPending = !generationComplete && outlines.some((o) => !completedOrders.has(o.order));
+
+ if (hasPending && stage) {
+ generationStartedRef.current = true;
+
+ // Load generation params from sessionStorage (stored by generation-preview before navigating)
+ const genParamsStr = sessionStorage.getItem('generationParams');
+ const params = genParamsStr ? JSON.parse(genParamsStr) : {};
+
+ // Reconstruct imageMapping for the resumed generation. The mapping may
+ // MIX allocated asset ids and IndexedDB data URLs — a source whose cache
+ // write failed materialized its own images — so the resume mapping merges
+ // both, instead of choosing one transport for the whole set and silently
+ // dropping the other half.
+ const pdfImages = (params.pdfImages || []) as Array<
+ { id: string; assetId?: string; storageId?: string } & Record
+ >;
+ const finishResume = (imageMapping: Record) =>
+ generateRemaining({
+ pdfImages: params.pdfImages,
+ imageMapping,
+ stageInfo: {
+ name: stage.name || '',
+ description: stage.description,
+ style: stage.style,
+ },
+ agents: params.agents,
+ userProfile: params.userProfile,
+ languageDirective: params.languageDirective || stage.languageDirective,
+ });
+
+ const imageMapping: Record = {};
+ for (const img of pdfImages) {
+ if (img.assetId) imageMapping[img.id] = img.assetId;
+ }
+ const storageIds = pdfImages
+ .filter((img) => !img.assetId && img.storageId)
+ .map((img) => img.storageId as string);
+ void (async () => {
+ if (storageIds.length > 0) {
+ Object.assign(imageMapping, await loadImageMapping(storageIds));
+ }
+ finishResume(imageMapping);
+ })();
+ } else if (outlines.length > 0 && stage) {
+ // All scenes are generated, but some media may not have finished.
+ // Resume media generation for any tasks not yet in IndexedDB.
+ // generateMediaForOutlines skips already-completed tasks automatically.
+ generationStartedRef.current = true;
+ // The deck reached the classroom already fully materialized (e.g. a
+ // single-slide course, or a deck whose last slide finished in
+ // generation-preview), so generateRemaining's completion path never
+ // ran. Record completion now so a later edit/delete is not treated as
+ // an interrupted generation. No-op if already complete or not all
+ // outlines have scenes.
+ useStageStore.getState().markGenerationCompleteIfDone();
+ // Resume media only for outlines that still have a scene. On a finished
+ // deck the user may have deleted a slide, leaving an orphaned outline;
+ // generating its media would waste API calls on a slide that is gone.
+ const materializedOrders = new Set(scenes.map((s) => s.order));
+ const materializedOutlines = outlines.filter((o) => materializedOrders.has(o.order));
+ generateMediaForOutlines(materializedOutlines, stage.id).catch((err) => {
+ log.warn('[Classroom] Media generation resume error:', err);
+ });
+ }
+ }, [loading, error, generateRemaining]);
+
+ return (
+
+
+
+ ) : notFound ? (
+ // Checked BEFORE `error`, and it renders no retry: the sources have
+ // all answered, and running the same lookups again cannot change
+ // the answer. One message for "deleted" and for "never existed" —
+ // see the state's declaration.
+
+
+
+
{t('classroom.notFound')}
+
{t('classroom.notFoundDesc')}
+
+ {t('classroom.backToHome')}
+
+
+
+ ) : error ? (
+
+
+
+ {t('common.errorPrefix')}
+ {error}
+
+
+
+
+ ) : (
+
+ )}
+
+
+
+ );
+}
diff --git a/components/edit/ActionsBar/ActionsBar.tsx b/components/edit/ActionsBar/ActionsBar.tsx
index b52bb55..f275246 100644
--- a/components/edit/ActionsBar/ActionsBar.tsx
+++ b/components/edit/ActionsBar/ActionsBar.tsx
@@ -1,9 +1,17 @@
'use client';
/**
- * ActionsBar — Pro-mode "讲解脚本" bottom bar, a horizontal film-editing timeline
+ * ActionsBar — the "narration script" timeline: a horizontal film-editing strip
* that is also a light editor for the scene's playback `actions`.
*
+ * This WAS the whole bottom bar. It is now the body of `EditDock`, which owns
+ * the surface (border, blur, fold) and the global edit bar above it; the
+ * timeline still renders its own header row — the row's controls and the body
+ * share one piece of state — and drives the dock's fold through `useEditDock`.
+ * Nothing about the timeline's own behaviour or geometry changed in the move.
+ * (The height-drag handle was removed per product decision: only the fold moves
+ * the dock's height, so the timeline no longer sizes itself.)
+ *
* The scene's `actions` ARE the timeline: walked left→right, each `speech`
* becomes an editable clip block (one spoken line, numbered) and every non-speech
* cue (spotlight / laser / board) becomes a compact card pinned at its place in
@@ -12,12 +20,13 @@
*
* Editing (persisted via useStageStore.updateScene → actions-edit ops):
* - speech clip text is editable inline (commit on blur);
- * - the header "添加动作" pill opens ActionPicker to insert a new action;
+ * - the header "Add action" pill opens ActionPicker to insert a new action;
* - existing items drag to reorder; each card carries a delete button;
- * - clicking an element-bound cue arms canvas pick mode (useCanvasStore.pickTarget),
- * so the target is chosen by clicking the element directly on the slide.
+ * - clicking an element-bound cue arms canvas pick mode (useCanvasStore.pickTarget
+ * with purpose 'cue'), so the target is chosen by clicking the element directly
+ * on the slide.
*
- * Collapsible; height-resizable from the top edge; reactive to the stage store.
+ * Reactive to the stage store; collapse and height belong to the dock.
*/
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { createPortal } from 'react-dom';
@@ -30,9 +39,11 @@ import {
Flag,
FoldVertical,
GripVertical,
+ Loader2,
Play,
Plus,
RefreshCw,
+ Square,
Trash2,
UnfoldVertical,
Volume2,
@@ -71,11 +82,13 @@ import {
setDiscussionTopicById,
setSpeechTextClearAudioById,
} from './actions-edit';
+import { useEditDock } from '@/components/edit/EditDock/dock-context';
import { ActionPicker } from './ActionPicker';
import type { PickerType } from './picker-options';
import {
audioExists,
audioObjectUrl,
+ discardSpeechAudio,
regenerateSpeechAudio,
resolveLegacySpeechAudioId,
resolveSpeechAudioId,
@@ -87,6 +100,16 @@ const EMPTY_ELEMENTS: { id?: string; type: string; content?: string }[] = [];
// on every reset and keeps a constant identity between batch runs).
const NO_IDS: ReadonlySet = new Set();
+/**
+ * Module-level single-flight controller for TTS preview: at most one
+ * SpeechTtsBar may be loading or playing at any moment, across every speech
+ * clip in the timeline. A bar registers its own `stop` handle when it starts a
+ * preview and clears it in `stopPreview` only when it is still the registered
+ * owner — so a stale stop (a superseded attempt, or an unmounted non-active
+ * bar) never kills the currently active preview.
+ */
+let activePreview: { stop: () => void } | null = null;
+
/**
* Clear the canvas spotlight/laser preview when a cue glyph unmounts while it is
* being hovered — most importantly when the user deletes the cue. React does not
@@ -106,10 +129,6 @@ function useClearCuePreviewOnUnmount() {
*/
const INCOMPLETE_CLIP = 'border-dashed border-amber-400/70';
-const MIN_H = 168;
-const MAX_H = 520;
-const DEFAULT_H = 224;
-const LINE_H = 86; // height when collapsed to just the axis line of node icons (fits the chips)
const AXIS_FROM_TOP = 20; // px from track top to the axis center (nodes hang below it)
// Radix Select forbids an empty-string item value, so the discussion's
@@ -165,7 +184,7 @@ function CueTooltip({ tip }: { tip: TooltipState }) {
}
// Native HTML5 drag snapshots the element's square bounding box, so a round
-// icon chip drags with white corners ("白边"). Suppress the ghost with a 1×1
+// icon chip drags with white corners ("white border"). Suppress the ghost with a 1×1
// transparent image — the violet drop indicator carries the feedback instead.
let blankDragImg: HTMLImageElement | null = null;
function setBlankDragImage(e: React.DragEvent) {
@@ -249,8 +268,11 @@ function MoveButtons({
type TtsStatus = 'none' | 'ready' | 'generating' | 'error';
-/** Audio status + 试听 / 重新生成 row, shown when managed TTS is on. */
-function SpeechTtsBar({
+/** TTS preview lifecycle: idle → loading (awaiting the blob URL) → playing → idle. */
+type PreviewPhase = 'idle' | 'loading' | 'playing';
+
+/** Audio status + preview / regenerate row, shown when managed TTS is on. */
+export function SpeechTtsBar({
actionId,
audioId,
audioUrl,
@@ -272,16 +294,22 @@ function SpeechTtsBar({
text: string;
refreshKey?: number;
regenerating?: boolean;
- onGenerated: (audioId: string) => Promise;
+ /**
+ * Notification that regeneration succeeded. Carries the freshly allocated
+ * audioId so the caller can stamp it on the action: this tree allocates pool
+ * identities (the blob is stored under the returned id), so the id cannot be
+ * re-derived by the caller like the reference's deterministic key.
+ */
+ onGenerated: (audioId: string) => void;
}) {
const { t } = useI18n();
const [status, setStatus] = useState('none');
- // Holds this line in 生成中 across a batch ("全部配音") run and — crucially —
- // until its OWN audio re-check resolves, so it can't briefly flash back to
- // 未配音 in the window between the batch clearing `regenerating` and the async
- // audioExists effect landing. Latched on the rising edge of `regenerating`,
- // cleared inside that re-check effect (which the batch always re-triggers via
- // `refreshKey`).
+ // Holds this line in the generating state across a batch ("Voice all") run
+ // and — crucially — until its OWN audio re-check resolves, so it can't
+ // briefly flash back to not voiced in the window between the batch clearing
+ // `regenerating` and the async audioExists effect landing. Latched on the
+ // rising edge of `regenerating`, cleared inside that re-check effect (which
+ // the batch always re-triggers via `refreshKey`).
const [batchPending, setBatchPending] = useState(false);
const [prevRegenerating, setPrevRegenerating] = useState(regenerating);
if (regenerating !== prevRegenerating) {
@@ -290,6 +318,14 @@ function SpeechTtsBar({
setPrevRegenerating(regenerating);
if (regenerating) setBatchPending(true);
}
+ // TTS preview state machine — local UI state for the preview button, kept
+ // apart from `status`/`effStatus` (audio availability + regeneration), which
+ // the playback lifecycle must not disturb.
+ const [previewPhase, setPreviewPhase] = useState('idle');
+ // Generation token: every `stopPreview` (and every fresh `preview`) bumps it,
+ // so an in-flight `audioObjectUrl` await can tell it was superseded and drop
+ // its result — this is what kills the double-click double-Audio race.
+ const previewTokenRef = useRef(0);
const audioRef = useRef(null);
const objUrlRef = useRef(null);
@@ -302,12 +338,19 @@ function SpeechTtsBar({
}
const stopPreview = useCallback(() => {
+ // Invalidate every in-flight `preview()` await — a newer click, a takeover
+ // by another bar, or an unmount all funnel through here.
+ previewTokenRef.current += 1;
+ // Only the registered owner clears the module-level handle: a stale stop
+ // from a superseded or unmounted bar must not kill the current preview.
+ if (activePreview?.stop === stopPreview) activePreview = null;
audioRef.current?.pause();
audioRef.current = null;
if (objUrlRef.current) {
URL.revokeObjectURL(objUrlRef.current);
objUrlRef.current = null;
}
+ setPreviewPhase('idle');
}, []);
useEffect(() => {
@@ -335,7 +378,7 @@ function SpeechTtsBar({
// pre-batch check that resolves mid-batch must NOT clear it (adding
// regenerating to the deps also cancels such a check at batch start via
// the cleanup below). Runs even if the read threw, so the row can never
- // wedge in 生成中.
+ // wedge in the generating state.
if (alive && !regenerating) setBatchPending(false);
}
})();
@@ -347,17 +390,42 @@ function SpeechTtsBar({
useEffect(() => () => stopPreview(), [stopPreview]);
const preview = async () => {
- stopPreview();
+ // Global single-flight: stop whatever is loading/playing in ANY bar first.
+ // This also bumps the token, so this bar's own previous in-flight attempt
+ // is already invalidated by the time we capture the fresh token below.
+ activePreview?.stop();
+ const token = ++previewTokenRef.current;
+ setPreviewPhase('loading');
+ activePreview = { stop: stopPreview };
// The legacy URL of an unconverted pair is the narration when no pool or
// Dexie id resolved -- or when the resolved id turns out to have no local
// bytes, which is exactly the dangling-id case the URL survives for.
const src = (readAudioId ? await audioObjectUrl(readAudioId) : null) ?? audioUrl ?? null;
- if (!src) return;
+ if (token !== previewTokenRef.current) {
+ // Superseded while loading (a newer click, a takeover, a stop): drop the
+ // result and revoke any blob URL we minted — the winner is in charge.
+ if (src && src.startsWith('blob:')) URL.revokeObjectURL(src);
+ return;
+ }
+ if (!src) {
+ stopPreview();
+ return;
+ }
objUrlRef.current = src;
const a = new Audio(src);
audioRef.current = a;
a.addEventListener('ended', stopPreview);
- void a.play().catch(() => stopPreview());
+ a.addEventListener('error', stopPreview);
+ try {
+ await a.play();
+ // Stopped while play() was settling (e.g. a takeover in the gap): the
+ // stop already paused it, nothing more to do.
+ if (token !== previewTokenRef.current) return;
+ setPreviewPhase('playing');
+ } catch {
+ // Autoplay rejection etc. — treat like any other stop.
+ stopPreview();
+ }
};
const regenerate = async () => {
@@ -371,7 +439,7 @@ function SpeechTtsBar({
);
if (id) {
setReadAudioId(id);
- await onGenerated(id);
+ onGenerated(id);
setStatus('ready');
} else {
setStatus('none');
@@ -390,13 +458,22 @@ function SpeechTtsBar({
},
error: { label: t('edit.tts.statusError'), cls: 'text-rose-500' },
};
- // A batch "全部配音" run drives this line's loading state from the parent
+ // A batch "Voice all" run drives this line's loading state from the parent
// (regenerating) — independent of the local single-line status. `batchPending`
- // extends 生成中 past the prop clearing, until this line's own audio re-check
- // resolves to 已配音 / 未配音, so the batch end shows a clean 生成中 → 已配音
- // transition with no intermediate flash.
+ // extends the generating state past the prop clearing, until this line's own
+ // audio re-check resolves to voiced / not voiced, so the batch end shows a
+ // clean generating → voiced transition with no intermediate flash.
const effStatus: TtsStatus = regenerating || batchPending ? 'generating' : status;
const s = STATUS[effStatus];
+ const previewLabel =
+ previewPhase === 'loading'
+ ? t('edit.tts.cancelPreview')
+ : previewPhase === 'playing'
+ ? t('edit.tts.stopPreview')
+ : t('edit.tts.preview');
+ // idle → Play; loading → spinner (click cancels the load); playing → Stop.
+ const PreviewIcon =
+ previewPhase === 'loading' ? Loader2 : previewPhase === 'playing' ? Square : Play;
return (
@@ -405,13 +482,18 @@ function SpeechTtsBar({
)}
-
+ )}
+
+ {lineMode ? : }
+
+ >
+ );
+ return (
+ <>
+ {/* The timeline's own header row: what it is, what it can insert, how much
+ it holds, and its fold. Geometry unchanged from the standalone bar. */}
+
{header}
{/* the timeline axis (top) — nodes hang below it; hidden when empty
@@ -1287,9 +1323,17 @@ export function ActionsBar({ sceneId }: { sceneId: string }) {
setDragOver(null);
};
const onPick = () =>
- useCanvasStore
- .getState()
- .setPickTarget({ sceneId, actionId: key, cueType: action.type });
+ useCanvasStore.getState().setPickTarget(
+ useStageStore.getState().stage?.id
+ ? {
+ purpose: 'cue',
+ stageId: useStageStore.getState().stage!.id,
+ sceneId,
+ actionId: key,
+ cueType: action.type,
+ }
+ : null,
+ );
const dot = (
setFocusId(null)}
onCommit={(text) => {
- // Editing invalidates the document reference but leaves the old
- // pool entry for the document-truth sweep introduced in part 3.
+ // Editing the text invalidates any cached audio
+ // (the blob is keyed by order+id and the stamped
+ // audioId, not the text), so drop the stamped
+ // fields and delete the blob — the line then
+ // reads as un-voiced until regen.
+ const prevAudioId = (action as { audioId?: string }).audioId;
commit((cur) => setSpeechTextClearAudioById(cur, key, text));
- setTtsRefresh((n) => n + 1);
+ // Re-check status only AFTER the blob is gone, so
+ // the status row can't race the async delete and
+ // briefly still read "voiced".
+ void discardSpeechAudio(sceneOrder, {
+ id: key,
+ audioId: prevAudioId,
+ }).finally(() => setTtsRefresh((n) => n + 1));
}}
- onGenerated={async (assetId) => {
+ onGenerated={(assetId) => {
commit((cur) => setAudioIdById(cur, key, assetId));
- await flushStageSave();
+ // Stage persistence is debounced; flush so the
+ // stamped reference is durable once the row
+ // settles (pool bytes persist first, stamp last).
+ void flushStageSave().catch(() => undefined);
}}
onDelete={() => {
commit((cur) => removeById(cur, key));
@@ -1418,6 +1475,6 @@ export function ActionsBar({ sceneId }: { sceneId: string }) {
onClose={() => setPickerAt(null)}
/>
)}
-
+ >
);
}
diff --git a/components/edit/ActionsBar/actions-edit.ts b/components/edit/ActionsBar/actions-edit.ts
index 9552de8..fa82cb5 100644
--- a/components/edit/ActionsBar/actions-edit.ts
+++ b/components/edit/ActionsBar/actions-edit.ts
@@ -109,8 +109,8 @@ export function setSpeechTextById(actions: Action[], id: string, text: string):
* Edit a speech line's text AND drop its stamped audio fields (index-stale-safe).
* The cached audio blob is keyed by sceneOrder+actionId, not the text, so an
* edit must invalidate it or the stale audio would replay for the new wording —
- * after this the line reads as un-voiced until regenerated. The invalidation
- * marker prevents fallback to a stale legacy derived-id row without deleting it.
+ * after this the line reads as un-voiced until regenerated. (Deleting the blob
+ * itself is done separately via `discardSpeechAudio`.)
*/
export function setSpeechTextClearAudioById(actions: Action[], id: string, text: string): Action[] {
const index = actions.findIndex((a) => a.id === id);
diff --git a/components/edit/ActionsBar/cue-meta.ts b/components/edit/ActionsBar/cue-meta.ts
index 1ac0889..a6e62dd 100644
--- a/components/edit/ActionsBar/cue-meta.ts
+++ b/components/edit/ActionsBar/cue-meta.ts
@@ -20,6 +20,7 @@ import {
Table2,
type LucideIcon,
} from 'lucide-react';
+import { elementRefLabel } from '@/lib/workbench/element-refs';
/** Translator fn (matches useI18n's `t`) — passed in so this module stays hook-free. */
type TFn = (key: string, options?: Record) => string;
@@ -122,23 +123,7 @@ export function cueLabel(type: string, t: TFn): string {
/** Cue types that target a canvas element (so canvas pick mode applies). */
export const ELEMENT_BOUND = new Set(['spotlight', 'laser', 'play_video']);
-const EL_TYPE_KEY: Record = {
- text: 'edit.element.text',
- image: 'edit.element.image',
- shape: 'edit.element.shape',
- line: 'edit.element.line',
- chart: 'edit.element.chart',
- table: 'edit.element.table',
- latex: 'edit.element.latex',
- video: 'edit.element.video',
- audio: 'edit.element.audio',
- code: 'edit.element.code',
-};
-
/** Human label for a slide element (localized type + a short content snippet). */
export function elementLabel(el: { type: string; content?: string }, t: TFn): string {
- const typeLabel = EL_TYPE_KEY[el.type] ? t(EL_TYPE_KEY[el.type]) : el.type;
- const raw = (el.content ?? '').replace(/<[^>]+>/g, '').trim();
- const snip = raw ? ` · ${raw.slice(0, 16)}${raw.length > 16 ? '…' : ''}` : '';
- return `${typeLabel}${snip}`;
+ return elementRefLabel(el, t);
}
diff --git a/components/edit/AgentPanel/AgentPanel.tsx b/components/edit/AgentPanel/AgentPanel.tsx
deleted file mode 100644
index ac99ebc..0000000
--- a/components/edit/AgentPanel/AgentPanel.tsx
+++ /dev/null
@@ -1,594 +0,0 @@
-'use client';
-
-/**
- * MAIC Agent — editor AI sidebar (right rail), "Edit with AI" Cursor-style
- * surface per the OpenMAIC AgentSidebar design board:
- * - user messages are right-aligned solid-violet bubbles (radius 14/14/4/14);
- * - assistant output is full-width markdown with design-language tool cards in
- * chronological order;
- * - the composer is a bordered shell with a violet focus glow, an @-context
- * chip for the active scene, horizontally-scrolling quick-prompt chips, and a
- * square violet send button.
- * Only design aspects with real V0 backing are implemented — the model picker,
- * Agent/Ask mode, checkpoints/Restore, reasoning blocks and per-element @-chips
- * from the board are intentionally omitted (no runtime support yet).
- * Wiring (ExternalStore over the pi AgentEvent SSE stream) lives in
- * use-agent-runtime.
- */
-import { useCallback, useRef, useState } from 'react';
-import {
- AssistantRuntimeProvider,
- ComposerPrimitive,
- MessagePrimitive,
- ThreadPrimitive,
- useComposerRuntime,
- useMessage,
- type AssistantRuntime,
-} from '@assistant-ui/react';
-import {
- ArrowUp,
- AtSign,
- ChevronDown,
- History,
- PanelRightClose,
- PanelRightOpen,
- Sparkles,
- Square,
- SquarePen,
- Trash2,
-} from 'lucide-react';
-import { cn } from '@/lib/utils/cn';
-import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
-import type { AgentEditSessionRecord } from '@/lib/agent/client/agent-edit-session-types';
-import { useI18n } from '@/lib/hooks/use-i18n';
-import { SpeechButton } from '@/components/audio/speech-button';
-import { MarkdownText } from './markdown-text';
-import { ReasoningPart } from './reasoning-part';
-import { RegenerateSceneActionsUI } from './regenerate-tool-ui';
-import { RegenerateSceneUI } from './regenerate-scene-tool-ui';
-import { EditInteractiveHtmlUI } from './edit-interactive-html-tool-ui';
-import { EditElementsUI } from './edit-elements-tool-ui';
-import { ReadSceneContentUI } from './read-tool-ui';
-
-const MIN_WIDTH = 320;
-const MAX_WIDTH = 640;
-const DEFAULT_WIDTH = 384;
-
-/** Capability rows shown in the empty state — read-only tips (not clickable),
- * each a label + example phrasings. One unified list describing what the agent
- * can do across scenes (slide content + narration + interactive-page fixing +
- * per-element edits), shown regardless of the active scene type. */
-const CAPABILITY_KEYS = [
- { label: 'edit.agent.cap.content.label', examples: 'edit.agent.cap.content.examples' },
- { label: 'edit.agent.cap.narration.label', examples: 'edit.agent.cap.narration.examples' },
- { label: 'edit.agent.cap.elements.label', examples: 'edit.agent.cap.elements.examples' },
- { label: 'edit.agent.cap.fixHtml.label', examples: 'edit.agent.cap.fixHtml.examples' },
-];
-
-function UserMessage() {
- return (
-
- {/* Solid brand-violet bubble, right-aligned, with a tail toward the user
- (radius 14/14/4/14) — per the design board's .ae-user. */}
-
-
-
-
- );
-}
-
-function ThinkingIndicator() {
- const { t } = useI18n();
- // Cursor-style shimmer label — the bright band sweeps across the word while we
- // wait for the next API call's first streamed token. Reasoning tokens are never
- // rendered raw (think-blocks stripped upstream); thinking surfaces only here.
- return (
- {t('edit.agent.thinking')}
- );
-}
-
-function AssistantMessage() {
- const { t } = useI18n();
- // Separate primitive selectors — useMessage is backed by useSyncExternalStore
- // (Object.is snapshot compare), so returning a fresh object literal would loop.
- const hasContent = useMessage((m) =>
- m.content.some(
- (p) =>
- (p.type === 'text' && p.text.length > 0) ||
- p.type === 'tool-call' ||
- (p.type === 'reasoning' && p.text.length > 0),
- ),
- );
- // Loading shows only while a NEW API call is pending its first token — not while
- // tokens are streaming. Walk to the last meaningful part: live text → streaming
- // (no loading); a finished tool call (result present) → next turn pending
- // (loading); a still-running tool call → its card already spins (no loading);
- // nothing yet → loading.
- const showLoading = useMessage((m) => {
- if (m.status?.type !== 'running') return false;
- const parts = m.content as Array<{ type: string; text?: string; result?: unknown }>;
- for (let i = parts.length - 1; i >= 0; i--) {
- const p = parts[i];
- if (p.type === 'text' && typeof p.text === 'string' && p.text.length > 0) return false;
- if (p.type === 'tool-call') return p.result !== undefined;
- // A reasoning part shows its own live "thinking…" label (with duration),
- // so the separate shimmer indicator is redundant while reasoning streams.
- if (p.type === 'reasoning' && typeof p.text === 'string' && p.text.length > 0) return false;
- }
- return true;
- });
- const stopped = useMessage((m) => m.status?.type !== 'running');
-
- return (
-
- {hasContent ? (
-
-
-
- ) : null}
- {showLoading ? (
-
- ) : stopped && !hasContent ? (
- {t('edit.agent.stopped')}
- ) : null}
-
- );
-}
-
-/** Mic button that dictates into the composer. Lives inside ComposerPrimitive.Root
- * so it can append the transcription to the composer text via the composer
- * runtime. SpeechButton self-gates on ASR availability (disabled when off). */
-function VoiceInputButton({ disabled }: { readonly disabled?: boolean }) {
- const composer = useComposerRuntime();
- return (
- {
- if (!text) return;
- const cur = composer.getState().text ?? '';
- const sep = cur && !cur.endsWith(' ') ? ' ' : '';
- composer.setText(cur + sep + text);
- }}
- />
- );
-}
-
-interface AgentPanelProps {
- readonly scene?: { id: string; title: string; type?: string };
- readonly runtime: AssistantRuntime;
- readonly clearThread: () => void;
- readonly hasMessages: boolean;
- readonly canSend: boolean;
- readonly sessions: AgentEditSessionRecord[];
- readonly activeSessionId: string | undefined;
- readonly switchSession: (id: string) => Promise;
- readonly deleteSessionAndRefresh: (id: string) => Promise;
- readonly refreshSessions: () => Promise;
- /**
- * When true, renders only the thread body (no aside wrapper, no header, no
- * resize handle, no collapse state). Used when an outer container (e.g.
- * RightRailTabs) owns the rail chrome.
- */
- readonly naked?: boolean;
-}
-
-export function AgentPanel({
- scene,
- runtime,
- clearThread,
- hasMessages,
- canSend,
- sessions,
- activeSessionId,
- switchSession,
- deleteSessionAndRefresh,
- refreshSessions,
- naked,
-}: AgentPanelProps) {
- const { t } = useI18n();
-
- // Interactive scenes expose a different agent capability (fix the page's bugs)
- // than slides (regenerate content/narration), so the empty-state copy and the
- // composer placeholder switch by scene type.
- // Empty-state copy is unified (no slide/interactive split) — the capability
- // list above already covers fixing interactive pages. The composer placeholder
- // still adapts to the active scene type.
- const isInteractive = scene?.type === 'interactive';
- const capabilityKeys = CAPABILITY_KEYS;
- const emptyTitleKey = 'edit.agent.emptyTitle';
- const emptyLeadKey = 'edit.agent.empty.lead';
- const emptyBoundaryKey = 'edit.agent.empty.boundary';
- const placeholderKey = isInteractive
- ? 'edit.agent.interactive.placeholder'
- : 'edit.agent.placeholder';
- const sceneTypeLabel =
- scene?.type && ['slide', 'quiz', 'interactive', 'pbl'].includes(scene.type)
- ? t(`edit.sceneType.${scene.type}`)
- : (scene?.type ?? 'Scene');
- const unsupportedMessage = t('edit.unsupportedScene', { type: sceneTypeLabel });
-
- // Drag-to-resize from the left edge (pointer capture, direct DOM write).
- const railRef = useRef(null);
- const [width, setWidth] = useState(DEFAULT_WIDTH);
- const dragRef = useRef<{
- startX: number;
- startW: number;
- lastW: number;
- pointerId: number;
- } | null>(null);
-
- const onResizeStart = useCallback(
- (e: React.PointerEvent) => {
- const startW = railRef.current?.getBoundingClientRect().width ?? width;
- dragRef.current = { startX: e.clientX, startW, lastW: startW, pointerId: e.pointerId };
- try {
- e.currentTarget.setPointerCapture(e.pointerId);
- } catch {
- /* best effort */
- }
- document.body.style.cursor = 'col-resize';
- },
- [width],
- );
- const onResizeMove = useCallback((e: React.PointerEvent) => {
- const d = dragRef.current;
- if (!d || e.pointerId !== d.pointerId) return;
- const next = Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, d.startW + (d.startX - e.clientX)));
- d.lastW = next;
- if (railRef.current) railRef.current.style.width = `${next}px`;
- }, []);
- const onResizeEnd = useCallback((e: React.PointerEvent) => {
- const d = dragRef.current;
- if (!d || e.pointerId !== d.pointerId) return;
- try {
- e.currentTarget.releasePointerCapture(e.pointerId);
- } catch {
- /* may already be released */
- }
- setWidth(d.lastW);
- dragRef.current = null;
- document.body.style.cursor = '';
- }, []);
-
- const [collapsed, setCollapsed] = useState(false);
-
- // Naked mode: outer container (RightRailTabs) owns the aside wrapper and chrome.
- // Render only the thread body, no aside / header / resize / collapse state.
- if (naked) {
- return (
-
-
-
-
-
-
-
-
-
-
-
-
-
- );
- }
-
- // Collapsed: a slim rail with the brand mark — click anywhere to reopen. The
- // runtime is owned above this panel, so the conversation is preserved.
- if (collapsed) {
- return (
-
- );
- }
-
- return (
-
- );
-}
diff --git a/components/edit/AgentPanel/DESIGN-agentbar-polish.md b/components/edit/AgentPanel/DESIGN-agentbar-polish.md
deleted file mode 100644
index 500a33d..0000000
--- a/components/edit/AgentPanel/DESIGN-agentbar-polish.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# AgentBar polish — capability tips + voice input + unified tool rendering
-
-- Date: 2026-06-21
-- Surface: `components/edit/AgentPanel/*` (the "Edit with AI" editor sidebar)
-- Builds on: the editor-agent feature (read_scene_content / regenerate_scene / regenerate_scene_actions)
-- Status: design approved, pending spec review → implementation plan
-
-## Background
-
-Three issues with the current AgentBar:
-
-1. **Stale, chip-driven guidance.** A row of clickable quick-prompt chips sits
- above the composer (`重新生成讲解旁白 / 让讲解更口语一些 / 加一个生活化类比`),
- and the empty state says "让 AI 重新生成与内容匹配的讲解旁白" — both still
- frame the agent as a *narration regenerator*, which is stale: the agent now
- regenerates the **whole slide** (content + narration) per instruction, reads
- the slide, etc. The user wants the chips removed and replaced with clearer,
- read-only **capability tips**.
-2. **No voice input.** The composer has no dictation affordance.
-3. **Inconsistent tool-call rendering.** Only `regenerate_scene` and
- `regenerate_scene_actions` have registered tool UIs; `read_scene_content`
- renders *nothing*, so a turn that reads the slide shows a blank gap between
- the assistant's "let me look at this page" and its reply.
-
-## Goal
-
-Make the AgentBar communicate the agent's real capabilities clearly, support
-voice input, and render every tool call consistently.
-
-## Scope decisions (locked)
-
-| Decision | Choice |
-|---|---|
-| Capability guidance placement | **Empty state only** (vanishes once a conversation starts) |
-| Guidance interactivity | **Pure read-only text** (no clickable examples — not "recommendations") |
-| Guidance form | **Grouped capability list** — title + lead + 3 labeled rows w/ examples + boundary + "coming soon" closer |
-| Voice input | **Reuse `SpeechButton` + `useASRAvailable`**, in the composer footer |
-| Tool rendering | **Shared `ToolCard` shell**; `read_scene_content` gets a light card; generic fallback for unregistered tools |
-
-Non-goals: no change to agent capabilities/tools; no per-element @-chips; no
-model picker; no streaming-reasoning UI.
-
-## Component changes — `components/edit/AgentPanel/`
-
-### 1. Empty-state capability tips (`AgentPanel.tsx`)
-
-- **Remove** the `QUICK_PROMPT_KEYS` array and the ``
- chip row above the composer (the whole `scrollbar-hide … overflow-x-auto` div).
-- **Replace** the single-line empty hint with a grouped capability list inside
- the existing `` block:
- - Title: `有什么想改的?` (reuse `edit.agent.emptyTitle`)
- - Lead: `告诉我这一页怎么改,我会重做内容并对齐讲解。`
- - Three capability rows — each a bold/foreground **label** + one or two muted,
- quoted **examples** (read-only, NOT buttons):
- - `改内容` — `"精简成 3 个要点"` · `"加个生活化例子"`
- - `改讲解` — `"讲得更口语一些"` · `"对齐我刚改的画布"`
- - `问这页` — `"这页重点是什么?"`
- - Boundary line (muted): `增删 / 排序幻灯片请用左侧导航`
- - Closer (muted, with a sparkle): `更多能力陆续加入中,敬请期待 ✨`
-- Visual: left-aligned rows within the existing centered ~260px container;
- labels `text-foreground`, examples `text-muted-foreground`, small sizes,
- consistent with the rail's existing type scale. Quoted examples may use the
- brand-violet faintly to read as "things you can say".
-
-### 2. Voice input button (`AgentPanel.tsx` composer footer)
-
-- Import `SpeechButton` (`@/components/audio/speech-button`) and render it in the
- composer's bottom action row, **left of** the Send/Stop button.
-- Wire `onTranscription={(text) => appendToComposer(text)}`. The composer uses
- assistant-ui's `ComposerPrimitive.Input` (not local state), so append via the
- composer runtime: `useComposerRuntime().setText(currentText + (currentText && !endsWithSpace ? ' ' : '') + text)`. Confirm the exact assistant-ui API
- (`useComposerRuntime` / `getState().text` / `setText`) against the installed
- version; fall back to a ref on the underlying `