From 04621578de4c310f805ef7bddcbba378540beadd Mon Sep 17 00:00:00 2001 From: wyuc Date: Thu, 27 Aug 2026 19:26:25 +0800 Subject: [PATCH] =?UTF-8?q?release:=20OpenMAIC=201.0.0=20=E2=80=94=20the?= =?UTF-8?q?=20agent=20workbench=20(#1228)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(storage): add an agent-session store with PG backend and layered contracts (#1163) * feat(storage): add agent-session store with PG backend and layered contracts * test(storage): avoid BigInt literals for pre-ES2020 root typecheck * fix(storage): close agent-session store review findings * docs(storage): align hook ordering and contention-probe claims with the code * ci: run on the agent-workbench integration branch * chore(storage): bump to 0.5.0 for the agent-session store * fix(storage): carry replay compaction across page boundaries * feat(agent): add the driver model contract and stage route dialect (#1165) * feat(agent): add the driver model contract and stage route dialect * fix(agent): validate route context windows and clarify dialect precedence * feat(agent): adapt the agent-session store and runtime foundations (#1167) * feat(agent): adapt the agent-session store and runtime foundations * feat(agent): resolve request owner identity via an anonymous cookie * docs(agent): document the opt-in compaction default and harden edge cases * feat(agent): add the background session runner (#1169) * feat(agent): add the background session runner * feat(agent): wire the runner into startup behind feature flags * fix(agent): stop clean interruptions from consuming the attempt budget * fix(storage): charge the attempt budget for abandoned leases but not clean parks * docs(storage): document the attempt-charging contract and decouple its tests * feat(agent): add agent session and owner event streams (#1170) * feat(agent): add agent session and owner event streams * fix(agent): close the session-existence oracle and document the owner seam * feat(agent): add agent session lifecycle routes (#1171) * feat(agent): add agent session lifecycle routes * fix(agent): validate session-create input and preserve the owner cookie on errors * refactor(storage): drop the unused active-stage API from the agent-session contract (#1174) * refactor(storage): drop the unused active-stage API from the agent-session contract Tools address stages explicitly on every call, so the store keeps no mutable session-level stage pointer. Removes resolveActiveStage and setActiveStage from the store interface, their PG implementations, the active_stage_changed lifecycle event, the session_active_stage owner event variant, and the contract tests pinning them. The active_stage_id column and the DDL check constraint stay untouched for schema compatibility. * chore(storage): bump @openmaic/storage to 0.7.0 for the contract removal * docs: document the agent runtime configuration surface (#1176) * fix(agent): repair orphaned and late tool results across interruption boundaries (#1180) * fix(agent): repair orphaned and late tool results across interruption boundaries A crash, shutdown, or provider failure can leave the durable transcript with tool calls that have no result, or with results ordered illegally for the provider. Three failure modes were fixed: - Orphaned tool calls: a run that died between an assistant tool-call frame and its result left a dangling call in the entry tree. Resume no longer synthesizes and persists receipts for it: interrupted results are a read-time provider view owned by a shared read-boundary repair, which returns the original array for a healthy transcript and never mutates the tree. - Late parallel results: a parallel tool can finish while pi unwinds an aborted assistant frame, leaving result(A), assistant(aborted), result(B) in durable order. Strict providers reject non-contiguous results, so the read-boundary repair moves existing results next to their owning assistant frame (in call order), omits incomplete unwind frames, and synthesizes receipts only for genuinely missing calls. - Interrupted calls at the write boundary: a call still in flight when the run winds down (shutdown, lease loss, cancellation, provider failure) had no receipt at all. The runner now tracks in-flight calls from their assistant frames and, before the terminal flush, appends an interrupted-result receipt for each still-orphaned call through the same attempt-fenced write chain, so a lease-stealing zombie never writes and the next claim sees a provider-safe transcript. * test(agent): pin the runner wiring for interruption-boundary tool repair * feat(agent): add neutral tool foundation libraries (#1184) * feat(agent): register a web_search tool on the session runner (#1185) * feat(storage): add a per-session URL trust gate (#1186) * feat(agent): add the skills system (#1189) * feat(agent): add the skills system (builtin directories and durable user skills) * fix(storage): serialize the user-skill quota check-and-insert per owner Two concurrent creates at the 50-skill boundary both counted 49 rows and both inserted (READ COMMITTED, no lock), overshooting the quota contract. The create transaction now takes a per-owner pg_advisory_xact_lock first, and the same-name idempotency check runs before the count check so an at-least-once retry of the create that committed as the owner's 50th row still returns its durable receipt instead of a quota error. The 23505 backstop is retained for writes that do not take the lock. * fix(agent): share unstorable-character validation and align skill lookup * feat(agent): add session materials and a fetch_url tool behind the URL trust gate (#1190) * feat(agent): add session materials and a fetch_url tool behind the URL trust gate * fix(agent): harden session material fetching * feat(storage): add an ownership scope to stage documents (#1191) * feat(agent): add material read and search tools (#1192) * feat(agent): add stage read and patch tools (#1194) * feat(agent): add page generation and deck editing tools (#1198) * test(storage): keep the PG contract suite order-independent (#1200) * fix(agent): revoke deleted-session URL authority and reject private ISATAP endpoints (#1199) * fix(storage): revoke deleted session URL authority * fix(ssrf): reject private ISATAP endpoints in strict fetches * chore(storage): bump to 0.11.1 for the session-URL authority fix * feat(agent): add roster and voice registration tools (#1201) * feat(agent): add folder organisation tools (#1202) * feat(api): add stage and material HTTP routes (#1203) * feat(workbench): add the client data layer (#1204) * feat(workbench): add the client data layer * docs(workbench): write the ported comments in English * chore(edit): remove the in-editor agent panel (#1210) * chore(edit): remove the in-editor agent panel * style: apply prettier formatting * fix(agent): report the runtime as unusable without a database (#1207) * fix(agent): report the runtime as unusable without a database * style: apply prettier formatting * feat(agent): add image, video and pptx import tools (#1211) * feat(workbench): add the agent chat surface (#1205) * feat(workbench): add the agent chat surface * docs(workbench): write the ported comments in English * fix(workbench): label the folder and rename tools on the timeline * fix(workbench): label the roster and voice tools on the timeline The reconciliation test iterates every tool the runner registers and requires a display label of its own. The roster and voice-clone tools (list_voices, set_roster, clip_audio, register_voice) reached the integration base with the roster/voice-registration tools but never gained presentation rows, so they fell through to the default branch and rendered their wire names. Port their rows from the reference implementation (labels and i18n keys verbatim) and extend the reconciliation allowlist with ROSTER_TOOL_NAMES and VOICE_CLONE_TOOL_NAMES, so a future tool cannot enter the product without a label. * feat(agent): add the material extraction lifecycle (#1212) * feat(storage): add material extraction lifecycle * feat(agent): execute queued material extraction * style: apply prettier formatting * style: satisfy prefer-const in the extraction runner * test: give material fixtures the extraction lifecycle fields The media-tools slice and the extraction lifecycle slice were each green in isolation but never compiled together: the lifecycle made derivedFrom and extraction required on AgentSessionMaterial while the media-tool fixtures predate them. * chore: remove stray task notes * fix(workbench): label the extraction lifecycle tools on the timeline * feat(workbench): add the workspace shell (#1206) * feat(workbench): add the workspace shell * docs(workbench): write the ported comments in English * i18n(workbench): align workspace keys across locales * fix(workbench): adopt the landed data layer and label the extraction tools - replace the sibling-slice seam stubs with the real data-layer modules - drop ambient declarations now shadowed by landed files - port timeline labels for the extraction lifecycle tools from the reference - align the new i18n keys across all locales * ci: retrigger * feat(api): folder routes, stage-meta viewer surfaces, and the material upload contract (#1215) * fix(storage): restore capability-based stage access * fix(api): bind document access to request owner * fix(agent): restore three-state stage access on the tool layer Port probeStageAccess and the three-state StageAccess (owned / foreign / missing / tombstoned) and gate every stageId-bearing stage tool on an owned probe, mirroring the reference per tool: - move_to_folder, rename_stage, read_stage_outline refuse a non-owned stage with the single not-yours message before touching the store. - The course/DSL toolset and the roster toolset are wrapped by withOwnerStageAuthorization: read_stage, patch_stage, grep_stage and every writer refuse a foreign stage with the same message and refusal shape. - Scene preview keeps its own probe and its own refusal text, and is registered beside the course toolset (never double-gated). - The runner injects one probe factory at the three call sites. Tests: the dsl cross-owner test premise (a foreign stage is readable by id) encoded an invented capability-read policy that the reference does not have at the tool layer; it now asserts foreign read/patch/grep are all refused while the owner still reads. Curriculum cross-owner assertions were already the reference's and now pass with the probes in place. * docs: correct per-file test counts in the fidelity report * test: fix type errors in stage-access fidelity test * test: adapt media-tool and gate suites to the owner-scoped store seam * feat(api): add owner-scoped course-folder HTTP routes Port the reference implementation's /api/folders family (list, create, rename, delete with ungroup/remove modes, and folder membership) onto the owner-bound document store, replacing its provider-based auth with the existing withRequestOwnerId / owner-scoped store seams. The storage package's folder store grows the pieces the routes need: DocumentFolder.order (schema column + max+1 assignment + ordering), renameFolder, deleteFolder(mode) with captured member ids, and setStageFolder(stageId, folderId | null) with idempotent un-filing. FolderNameError moves into folder-name-validation.ts (stage-storage re-exports it, keeping import sites intact). Every route gates on the configured agent runtime (plain 404 when off or unconfigured), keeps the reference's machine codes and envelopes, and is covered by gate tests plus a behavior suite. * feat(api): add stage-meta viewer surfaces for the classroom Port the reference implementation's viewer-facing stage state — can-edit / collected / published / generation-complete — on top of the stage-access base (stage_meta + tombstones). stage_meta gains published_at and generation_complete columns plus a stage_bookmarks table; the reference's deployment-specific origin/claimed_at columns are stripped. New gated routes: GET /api/stage-meta/[stageId] (per-viewer facts, 404 for absent/tombstoned, never returns the owner id), GET /api/stages/[id]/status, POST generation-complete / publish / unpublish (owner-only), POST /api/bookmarks. The resolver lives in lib/server/stage-access.ts. Wiring: a fetchStageMeta client with the reference's three-outcome contract, stage-store isOwner/isBookmarked/readOnly fields (upstream single-user defaults, no-op until the sidecar answers) plus setViewerAccess, the classroom apply path computing readOnly = !(isOwner || isBookmarked), the Stage editability gate, and a sidecar probe after each classroom load. A sidecar 'absent' answer keeps the editable default here because the classroom also serves local-only courses; server writes stay owner-enforced. * feat(api): port the reference material upload contract Rewrite POST /api/materials to the reference implementation's upload shape so the workbench uploader (uploadWorkbenchMaterial, which posts no session id and expects a flat 201 view) works unchanged: owner-scoped upload with mime normalization/validation (415), per-class size caps checked on the declared content-length and the streamed body (413), empty body (400), quota (429), sha256 reserve->store->finalize lifecycle with abandon on failure, flat { materialId, originalName, bytes, mime, extraction } 201, and an x-request-id echo. Adds the owner-scoped material library (owner_material table + quota + 24h lazy sweep, bytes in the host's asset registry as the neutral replacement for the reference's object-storage byte path) and the material cap configuration. The session-scoped GET list is left as-is; the reference's owner-material extraction worker is not ported (the branch's session-material extraction lifecycle already covers extraction). Gate tests now cover all 23 persistence routes across the three runtime env states; the materials behavior suite pins the new contract. * feat(media): add an optional local ffmpeg media extractor (#1213) Adds a local ffmpeg/ffprobe pipeline as a second media extraction provider behind the extractor registry, ported faithfully from the reference implementation: duration probing, keyframe-safe chunking, per-chunk ASR with timeout and deadline budgets, and timestamped transcript assembly. - Availability probing feeds the registry's candidate selection: the provider simply is not a candidate when ffmpeg/ffprobe are absent. - With neither ffmpeg nor a cloud provider configured, extraction fails with an actionable message naming both enablement paths. - Media materials route through the same extraction lifecycle and lease fence as documents; no parallel queue. - Tests inject the executable resolver so the missing-ffmpeg path is the default-tested one; the real pipeline test is skip-if-unavailable. - @openmaic/storage 0.13.0 -> 0.14.0 (media routing in the material lifecycle surface). * feat(storage): per-scene monotonic revisions via database triggers (#1214) * feat(storage): per-scene monotonic revisions via database triggers Restore the reference implementation's freshness granularity: a per-scene monotonic revision maintained by database triggers, so every writer (HTTP routes, agent tools, jobs, manual SQL) bumps it without application cooperation. - Companion revision tables + trigger functions in the storage package's idempotent schema bootstrap, with the lock-order invariant, pg_notify wakeup and the suppression switch for batch writers. - ensureDocumentSchema gained a dollar-quote-aware statement splitter. - The freshness and manifest routes serve per-scene revisions. - Mutation-verified: dropping the triggers turns the revision tests red. - @openmaic/storage 0.13.0 -> 0.14.0. * fix: forward the freshness manifest through the owner-bound store * feat(workbench): add the Pro entry points and preserve the mode-transition semantics (#1208) * feat(workbench): add the Pro entry points * feat(workbench): preserve Pro mode transition semantics * fix(workbench): drop ambient declarations shadowed by landed slices * fix(workbench): drop ambient declarations shadowed by the landed shell * feat: port workspace shell sibling modules Port the 16 leaf modules the Pro workspace shell imports but that were only ambient-declared, replacing the compile-time bridge with real implementations adapted from the sibling-slice reference: pure workbench helpers (session title, rail tab, course-chat bootstrap, created-course tabs, course-tabs memory, workspace navigation, pane navigation, pro-edit sizing, existing-course minting, first-message session), the neutral brand context and course-rename server API, the server-action session delete, the home discovery hook, the classroom pane host with its load-policy leaf, the theme toggle and floating-layer owner, plus the floating-layer-owner wiring the dialog/dropdown/tooltip portals stamp. Also add the workbench-shell locale copy for all 12 locales, port the reference tests for the ported modules, and drop types/workbench-sibling-slices.d.ts now that every declaration has a real implementation. * docs: keep ported comments in English and deployment-neutral * docs: announce 1.0.0 and refresh the feature overview (#1216) * docs: announce 1.0.0 and refresh the feature overview * docs: finalize 1.0.0 README after feature merge * fix(agent): control-plane routes answer 404, not 500, without a database The agent control-plane routes gated only on the runtime flag, so an enabled-but-unconfigured deployment (flag on, DATABASE_URL empty) answered 500 from a store that cannot connect. Gate them on the configured check instead, matching the stage/material routes: the whole surface is cleanly absent until both the flag and the database are present. The status probe keeps reporting both bits. * test: mock both runtime gate exports in the control-plane route suites * fix(agent): abort in-flight TTS on cancel and bound each provider request with a timeout (#1217) The generate_tts / scene-tts path checked the runner's AbortSignal between actions but never created the provider HTTP requests with it, so a session cancel left a hung synthesis fetch in flight until a restart repaired the tool result. Thread the signal end-to-end: TTSModelConfig carries an optional signal, generateTTS combines it with a per-request timeout (TTS_REQUEST_TIMEOUT_MS, default 30s, ported from the reference runtime's TTS bounds) via AbortSignal.any, and every provider fetch (openai, azure, glm, qwen incl. voice-clone + audio download, voxcpm, minimax, doubao, elevenlabs, lemonade) is created with that signal. A timeout now fails the tool call with TTSRequestTimeoutError (a clear retryable error) instead of wedging the session; a caller cancel propagates as the interruption so the runner settles the session as cancelled without a restart. Tests: hung-provider simulation rejects at the timeout with the retryable error; abort mid-flight aborts the captured request signal and surfaces the interrupted shape; removing the signal wiring makes the abort tests fail (red), restoring them turns green. * fix(workbench): PG-mode home listing via owner stages; keep the interrupted terminal course card (#1218) Finding 1: with server persistence on, listStages resolved to the generic GET /api/persistence/documents listing, which the capability model deliberately answers 403 FORBIDDEN_DOCUMENTS for (reads by id, listings owner-only). The home/workspace library now lists through the owner-scoped GET /api/stages surface (same anonymous-owner cookie the workbench uses) when server persistence is enabled; the server-side 403 is untouched. Finding 2: a run interrupted (session_interrupted) and repaired (session_resumed) that ends cancelled before agent_end stranded its pending classroom sightings, so the timeline's terminal card lost the course the answer produced. session_end (cancelled) now flushes the pending sightings into the same course card set agent_end paints, before the stopped caption. * chore(workbench): remove the bookmark concept and the saved-courses drawer (#1219) * chore(classroom): remove the bookmark ('collected') concept entirely The stage-meta viewer port introduced a bookmark surface (stage_bookmarks table, POST /api/bookmarks, the isBookmarked sidecar field, and a readOnly rule that let a saved course stay editable). The product has no such concept, so remove it as a closure: - delete the /api/bookmarks route and the stage_bookmarks table plus its query helpers from the persistence bootstrap - drop isBookmarked from GET /api/stage-meta/[stageId] - simplify the classroom read-only rule to readOnly = !isOwner across the sidecar client, ownership signal, classroom load, stage store and the classroom page - keep publish/unpublish, generation-complete, isOwner and isPublic exactly as they were - update the gate and stage-meta route suites and the README mentions The workspace rail's Bookmark glyphs and comments describe the upstream saved-courses (favorites) section, which is driven by isOwner and renders no collect affordance; they are kept as unrelated homonyms. * chore(workbench): remove the saved-courses drawer UI The first pass removed the bookmark data model but kept the rail's "Saved courses" drawer, judging it a separate surface driven by `isOwner === false`. The home/workspace listing is owner-scoped, so that flag can never occur: `allSaved` is permanently empty and the drawer (plus the collapsed-rail Bookmark mini-button) is a dead affordance. Remove it: the SavedDrawer component and its mount, the savedOpen / savedSection state, the allSaved / matchedSaved derivations, the 'saved' variant of the course-list renderers, the mini Bookmark glyph, the drawer-only CSS, and the drawer's i18n keys from all 12 locales. The courses tab is now exactly one folders tree. The authored/favorites split in workspace-tree.ts goes with it; the tree module no longer reads `isOwner`. The discovery course type keeps the field — the shell still reads it for read-only gating. Upstream has no collect concept; the drawer could only ever render empty here. The reference implementation HAS this drawer (its favorites come from its account system), so this removal is a deliberate upstream product decision, not a fidelity bug. * fix(workbench): restore the attach entry, add the rail settings entry, pin all three entry points (#1221) * fix(workbench): restore the composer attach entry by gating it on the live runtime The AttachButton's rollout probe read a `materialsEnabled` field that this branch's /api/agent/runtime never answers (the materials routes gate on the runtime itself, like the stages), so the gate could never pass and the attach button never rendered — the Pro launch and chat composers showed only the @-mention and enhance glyphs. Substitute the field with the runtime's `enabled` value, which IS the upload action's precondition: POST /api/materials answers 404 whenever it is false, so the render condition now equals the action precondition (no dead button). The button's label (`proMode.attach`) is a user-visible string that becomes visible again; port the reference implementation's own translations verbatim into the 11 locales that still carried the Chinese copy. * feat(workbench): add the settings entry to the rail's bottom-left cluster The reference's rail foot carries a cluster of utilities (its saved-courses drawer, the language switcher, the display toggle). This branch removed the drawer — it could only ever render empty here — and the product decision is to fill that freed spot with the settings entry. Add a settings trigger to the foot cluster (expanded rail, beside the language and display toggles, and on the collapsed strip) and mount the model/provider SettingsDialog in the rail, wired to the trigger. It is the same dialog the classic home opens from its header pill; the workspace had no settings entry of its own, so nothing is duplicated within a surface. * test(workbench): pin the restored upload, attach, and settings entry points Covers the three restored entry points: - the courses-tab upload control: rendered beside the course name filter, wired to the discovery hook's ZIP import trigger, disabled while an import runs, and gated by the same condition as its action (the courses tab); - the composer attach control: an actual render of AttachButton under both probe answers (visible when the runtime says the upload path is live, hidden otherwise), its mounts in the launch and chat composers, the branch's runtime-field substitution in the probe, and the reference's own `proMode.attach` copy in all 12 locales; - the settings entry: the trigger in the rail's foot cluster (expanded and collapsed), beside the language and display toggles, opening the SettingsDialog the rail mounts. * chore(config): the Pro workbench flag implies the MAIC Editor gate (#1223) A workbench build without the editor toggle has no way to edit a course: enabling NEXT_PUBLIC_PRO_WORKBENCH_ENABLED while forgetting NEXT_PUBLIC_MAIC_EDITOR_ENABLED produced exactly that split-brain bundle. The workbench IS Pro mode, so its flag now implies the editor gate; the standalone flag remains for deployments that want the classroom editor without the workbench. Documents both flags in .env.example. * fix(agent): wake SSE tails and the runner on durable deltas (streaming fidelity) (#1222) The Pro workbench chat did not stream: the session/owner SSE routes polled the durable event log on a 5s/30s clock with no wakeup, so message_update deltas (written at 150ms cadence) reached the browser in poll-sized blocks and the thinking strip only mounted after the whole reasoning text had accumulated. Port the reference's LISTEN/NOTIFY delta path: - storage: add in-transaction wake hooks (onSessionEventAppended, onOwnerEventAppended, onCancelRequested) so a host queues pg_notify in the same transaction as the durable append; align readEventsAfterForReplay to rank the bounded page so the first delta after the cursor is always kept (the live tail can never starve). Bump @openmaic/storage to 0.18.0. - app: port the process-wide event-notify bus (dedicated LISTEN client, self-check probe, reconnect backoff; notify through the storage transaction surface), wire the store hooks, subscribe both SSE routes before the initial read with the reference's initializing gate, and give the runner one {kind:'session'} subscription whose wake runs the cancel check and the message drain. Polls stay as the lossy-NOTIFY backstop. - lifecycle: start/stop the bus from instrumentation. Tests: storage hook + compaction contract; route wakeup latency; runner wakeup wiring with a fake agent; bus unit tests; PG contracts proving a real append wakes the routes and a live SSE route forwards a message_update on the wakeup, and that a rolled-back append never wakes. Also fix the pre-existing park-attempt-budget PG test TRUNCATE (missing CASCADE against newer FK tables). * fix(storage): asset writes self-deadlocked against pooled PostgreSQL (#1225) * fix(storage): refuse the non-transactional byte-write deadlock configuration A byte store whose plain write() runs on its own pooled connection cannot be invoked from inside a registry write transaction: after the transaction has claimed the blob-row lock, that write blocks on the lock the transaction just took while the transaction waits on the write - a self-deadlock PostgreSQL cannot detect (one side is idle in transaction). There is no lock-safe ordering for such a writer: bytes must be written after the row claim (writing before it lets the collector delete the bytes while the upsert waits), and any second-connection write after the claim is the deadlock. The configuration is therefore detected and refused: - AssetByteStore gains writesOutsideRegistryDatabase?: true, declaring that the layer's plain byte operations cannot contend for the registry's row locks. - PgAssetStore refuses put()/replace() up front (and defends coordinatedWrite) when the byte store has no writeWith and does not declare the flag, throwing a clear configuration error before any row is claimed. - The collector mirrors the guard on its delete path (deleteWith or a declared out-of-registry layer, else a configuration error). - The object store declares the flag (its out-of-transaction write remains legitimate); the in-registry PostgreSQL byte column provides writeWith / deleteWith instead. - Write transactions (put/replace/remove) set SET LOCAL lock_timeout = 30s so any future lock-contention variant fails loudly instead of hanging. Bumps @openmaic/storage to 0.18.0. * fix(persistence): forward the transactional byte methods through the lazy asset byte-store wrapper The no-bucket case of lazyAssetByteStore returned a bare { write, read, delete } and dropped writeWith/readWith even though the underlying PgAssetByteStore has them. The registry's hasTransactionalWriter duck check then failed and put() fell back to the byte store's own pooled connection, which blocks forever on the blob-row lock the registry transaction just took when the bytes live in the same PostgreSQL - the production self-deadlock. The no-bucket layer is statically PgAssetByteStore, so its transaction-pinned methods are forwarded eagerly (typed against the real signatures via PgForwardedByteStore). The bucket case keeps its lazy-probing semantics: no transactional writer exists there, the signed-URL method stays absent or lazy exactly as documented, and the wrapper now declares writesOutsideRegistryDatabase so the registry may run the plain write inside its transaction. New tests pin the wrapper's transactional capability red-to-green and assert put()/resolve() route byte traffic through the transaction-pinned queryable. * fix(home): cap the generate-prep ingest drain at 3s so Generate never waits the full server budget The classic home flow's Generate click drained in-flight ingests for the full 15s server budget. Cap the wait at GENERATE_DRAIN_CAP_MS (3000ms, documented as a UX bound) and reuse the existing timeout fallback: sources that miss the cap proceed on the legacy byte path and each late-resolving id is released. * chore(storage): bump to 0.19.0 over the concurrently landed 0.18.0 * fix(agent): bound every tool call with a timeout; never resurrect a cancelled session (#1226) * fix(agent): bound every tool call with a global timeout and settle it on cancel A tool await that neither resolves nor rejects wedges the session forever: the lease keeps heartbeating and the driver never reaches its next cancel checkpoint. Race every tool execution (in buildAgent) against a hard budget (OPENMAIC_AGENT_TOOL_TIMEOUT_MS, default 10 min, per-tool overrides for known long runners) and against the caller's AbortSignal, so even a signal-ignoring await cannot keep a cancelled session running. On timeout the call rejects with AgentToolTimeoutError; the agent loop turns the rejection into a structured error tool-result the agent can retry or proceed from, and the abort signal is delivered to the tool's in-flight work through a derived controller. Zombie-tool updates after settlement are dropped. * fix(storage): never re-lease a cancel-requested session; settle it as cancelled on claim The claim scan treated a session with cancel_requested_at set as a normal claim candidate: after a restart it re-leased the same session for attempt N+1 and resumed generating despite the pending cancel. claimNextSession now settles such candidates as cancelled under the claim lock (status cancelled, attempt reset, lease and cancel request cleared, terminal session_end event and owner projection) instead of leasing them, then keeps scanning. Bump @openmaic/storage to 0.18.0. * docs: takeaway-style 1.0.0 announcement with bilingual guide links The 1.0.0 head is now a short takeaway block — badge links to the official user guides (English and Chinese), five one-line highlights, and pointers into Features and the workbench setup section — instead of six dense paragraphs. The detailed provider-neutrality and freshness notes move into the Features workbench section, phrased database- neutrally (the announcement no longer names a specific database). Release date corrected to August 27. * fix(workbench): restore editor chrome, mode transition, streaming, materials, mentions, folders (#1229) * fix(workbench): wire workspace folder routes * fix(editor): restore reference workbench chrome * fix(workbench): persist composer materials and course refs * fix(workbench): preserve live reasoning frames * fix(persistence): back off failed streaming saves * chore(workbench): retire stale slice seams * test(editor): cover element pin layer * chore(storage): bump to 0.21.0 for the user-message ref/material fields * chore(editor): translate ported code comments to English * fix(agent): fence durable tool writes and consume cancel requests atomically (#1230) * fix(agent): enforce provider force-off in agent tools and scrub vendor identity from tool results (#1231) * fix(materials): serialize per-owner quota reservations and make crashed uploads reclaimable (#1232) * fix(editor): resolve dock-bar i18n keys, remove dock height drag, wire element referencing (#1233) * fix(workbench): send the opening session message exactly once with refs intact (#1234) * feat(editor): port timeline TTS preview single-flight and voice-all state latching (#1235) * fix(media): restore the reference classic media chain (#1236) * fix(import): adapt imported PPTX canvas size so decks render without overflow (#1237) * fix(editor): complete element referencing — renderer DOM contract and GenUI picking aligned with the reference (#1238) * test(providers): reconcile the provider-config vendor-token debt count after the main merge The integration line's AK/SK fallback for the managed document provider adds occurrences that main's allowlist snapshot predates. Same mixed-composition debt category the group already documents; no new vendor behavior. * test(providers): reconcile vendor-token debt counts with the integration line The main-merge brought main's neutrality-guard snapshot next to integration features it predates (media-extractor fallback chain, local voice-profile deletion semantics, the enabled-TTS helper). Same debt categories the guard already documents; counts updated to the guard's own tally and two grouped entries added. No new vendor behavior. * fix(agent): carry reasoning through the completions dialect so the thinking strip renders (#1239) * feat(skills): add Feynman and spiral curriculum methods (#1240) * feat(agent): port missing reference tools and skills (parity audit) (#1241) * feat(media): retire asset-registry wiring; media and materials follow the reference byte model (#1242) * fix(classroom): center adapted canvases in the stage and send back navigation home during generation (#1243) * feat(settings): skill management with real list, download, delete, and upload (#1244) * feat(settings): skill management section with real list, detail, and zip download * feat(skills): owner skill delete and upload across storage, API, and settings * fixup! feat(settings): skill management section with real list, detail, and zip download chore: neutralize a reference note in the settings header comment * fix(media): persist origin-independent classroom-media references from the agent runtime (#1245) * feat(editor): float the insert toolbar in the outer frame with collapse (#1246) The insert strip was bounded to the slide card, so it could only ever sit on top of slide content: the card's overflow clipped it and it could not be parked in the padding beside the slide. Move it into the studio frame the element picker's panel already roams (CanvasOverlayPortal + the frame selector), so both canvas overlays share one bounding container and their handles behave the same. While picking, the strip rises over the picker and goes inert, which is the z-order CANVAS_OVERLAY_Z already documents. Add a fold beside the grip: the chevron collapses the strip to that grip row and back, with the buttons unmounted rather than hidden. The fold is session-local state owned by EditShell, next to the drag offset, so a surface swap keeps it; nothing is persisted. Expanding a strip parked at the bottom edge re-clamps through the same bounds rule the keyboard move uses. Co-authored-by: Claude Fable 5 * fix(workbench): align the chat timeline's left edge with the composer (#1247) * fix(agent): fence session claims while an ask_user question is outstanding (#1248) * fix(agent): settle-time rescue tracks real delivery instead of a count offset (#1249) * fix(persistence): migrate owner_material to oss_key and drop legacy asset_id (#1250) * docs(readme): surface the 1.0.0 user guide badges at the top (#1253) * fix(workbench): show newly created folders in the sidebar without reload (#1254) * docs(readme): add the release version prefix and drop the opt-in framing * fix(workbench): single-source the chat gutter so timeline and composer share a left edge (#1255) The transcript and the composer each established their own column: their own `px-*` gutter and their own `mx-auto w-full max-w-*` centering wrapper. Equal padding values were never enough, because the two columns are centered inside different containing blocks — the transcript's is a scroll container, whose content box is narrower than the composer footer's by the scrollbar's width: transcript text left = pad + (pane - 2*pad - scrollbar - measure) / 2 composer box left = pad + (pane - 2*pad - measure) / 2 The padding cancels out of the difference and what remains is `-scrollbar/2` at every padding value, so the transcript sat half a scrollbar to the left of the composer and tuning the two paddings against each other could not move it. The column is now established once, by the nearest common ancestor of both (`chatColumn`), and the scroll viewport and the composer footer are siblings inside it that add no horizontal inset of their own. The cap carries the gutter on top of the 760px reading measure, so the text column keeps its width. The handed-over question row drops the padding that indented it past the agent's prose; framed rows keep their own inner padding, which is what a card's border sitting on the column edge means. Co-authored-by: Claude Fable 5 * fix(workbench): lock pane-embedded classroom to edit mode (#1256) The workspace right pane painted the full learning chrome — speed control, play button, learner avatars, mic bar — for a course the agent had just created, then flipped to edit once the first scene landed. resolveStageChromeMode treated playback as the DEFAULT branch for a hosted classroom, so every shortfall fell into it: a course whose tab opens at stage_link time has no scenes yet, so currentSceneId is null and isHostedSceneEditable is false. A folded pane parked the playback root behind the fold and cross-faded it out over the pane on unfold, and a failed editor chunk dropped into playback permanently. Lock it at the pane instead of defaulting per entry path: - WorkbenchPanelProvider — the single element that mounts a classroom into the workspace — publishes editPinned (visible && !playback). Every entry path passes through it, so none of them decides. - The hosted resolution can no longer degrade to playback. Start Learning (workbenchLearning, new input, split out from pane visibility) is the one door; everything else resolves between the neutral loading shell and edit. - Stage's chrome dispatch is exhaustive on chromeMode, so the playback root is no longer the else-branch of a condition about the current scene. No flicker: chromeMode is resolved during render, and preloadEditor now answers synchronously (isEditorPreloaded) so a remount with the chunk already registered paints edit on the first frame. A failed import is no longer cached forever, so the lock cannot strand the pane. Standalone classrooms keep their stored mode unchanged. --------- Co-authored-by: Claude Fable 5 --- .env.example | 77 +- .github/workflows/ci.yml | 3 +- README-zh.md | 6 + README.md | 139 +- app/api/agent/edit/route.ts | 210 -- app/api/agent/owner-events/route.ts | 323 ++ app/api/agent/runtime/route.ts | 25 + app/api/agent/sessions/[id]/cancel/route.ts | 45 + app/api/agent/sessions/[id]/events/route.ts | 300 ++ app/api/agent/sessions/[id]/messages/route.ts | 122 + app/api/agent/sessions/[id]/route.ts | 25 + app/api/agent/sessions/route.ts | 196 ++ app/api/agent/sessions/status/route.ts | 20 + app/api/agent/skills/[id]/route.ts | 50 + app/api/agent/skills/route.ts | 101 + app/api/extract-document/route.ts | 21 +- app/api/folders/[id]/route.ts | 121 + app/api/folders/members/route.ts | 73 + app/api/folders/route.ts | 117 + app/api/generate/scene-content/route.ts | 3 +- app/api/materials/[id]/route.ts | 44 + app/api/materials/route.ts | 416 +++ app/api/persistence/[...path]/route.ts | 120 +- app/api/skills/[id]/route.ts | 49 + app/api/stage-meta/[stageId]/route.ts | 80 + app/api/stages/[id]/freshness/route.ts | 152 + .../stages/[id]/generation-complete/route.ts | 60 + app/api/stages/[id]/manifest/route.ts | 38 + app/api/stages/[id]/publish/route.ts | 68 + app/api/stages/[id]/route.ts | 189 ++ app/api/stages/[id]/scenes/route.ts | 81 + app/api/stages/[id]/status/route.ts | 45 + app/api/stages/[id]/unpublish/route.ts | 56 + app/api/stages/route.ts | 116 + app/classroom/[id]/page.tsx | 33 + app/generation-preview/page.tsx | 288 +- app/globals.css | 2 + app/layout.tsx | 2 + app/page.tsx | 306 +- app/workbench/new/client.tsx | 139 + app/workbench/new/page.tsx | 21 + app/workspace/page.tsx | 42 + components/ai-elements/prompt-input.tsx | 7 +- components/canvas/canvas-area.tsx | 52 +- components/classroom/ClassroomSurface.tsx | 391 +++ components/edit/ActionsBar/ActionsBar.tsx | 391 ++- components/edit/ActionsBar/actions-edit.ts | 4 +- components/edit/ActionsBar/cue-meta.ts | 19 +- components/edit/AgentPanel/AgentPanel.tsx | 594 ---- .../edit/AgentPanel/DESIGN-agentbar-polish.md | 146 - .../edit/AgentPanel/edit-elements-tool-ui.tsx | 97 - .../edit-interactive-html-tool-ui.tsx | 81 - components/edit/AgentPanel/edit-tool-state.ts | 50 - components/edit/AgentPanel/markdown-text.tsx | 25 - components/edit/AgentPanel/read-tool-ui.tsx | 60 - components/edit/AgentPanel/reasoning-part.tsx | 123 - .../AgentPanel/regenerate-scene-tool-ui.tsx | 91 - .../edit/AgentPanel/regenerate-tool-ui.tsx | 85 - components/edit/AgentPanel/restore-button.tsx | 52 - components/edit/AgentPanel/tool-card.tsx | 114 - .../edit/AgentsView/AgentRosterPanel.tsx | 400 ++- components/edit/AgentsView/AvatarPicker.tsx | 11 +- components/edit/AgentsView/RosterDialog.tsx | 97 + components/edit/AgentsView/useAgentRoster.ts | 30 +- components/edit/ContainBox.tsx | 172 + components/edit/EditChromeRoot.tsx | 96 +- components/edit/EditDock/DockEditBar.tsx | 84 + components/edit/EditDock/EditDock.tsx | 113 + .../edit/EditDock/ElementRefLassoButton.tsx | 153 + components/edit/EditDock/dock-context.tsx | 44 + components/edit/EditShell/CanvasPager.tsx | 129 + components/edit/EditShell/CommandBar.tsx | 15 +- components/edit/EditShell/EditShell.tsx | 135 +- .../edit/EditShell/FloatingInsertToolbar.tsx | 221 +- components/edit/PlaybackChromeRoot.tsx | 31 +- components/edit/RightRailTabs.tsx | 306 -- .../edit/SlideNavRail/InsertionZone.tsx | 132 +- components/edit/SlideNavRail/SlideNavRail.tsx | 312 +- components/edit/agent-panel-visibility.ts | 13 - components/edit/scene-timeline.ts | 3 +- .../surfaces/slide/CanvasOverlayPortal.tsx | 251 ++ .../edit/surfaces/slide/ElementPickLayer.tsx | 593 ++-- .../surfaces/slide/ElementRefPinLayer.tsx | 157 + .../surfaces/slide/RendererEditorCanvas.tsx | 2 + .../edit/surfaces/slide/SlideCanvas.tsx | 2 + .../edit/surfaces/slide/SlideSurface.tsx | 4 +- .../edit/surfaces/slide/element-hit-test.ts | 109 + .../surfaces/slide/renderer-element-dom.ts | 14 +- components/header.tsx | 64 +- .../scene-renderers/InteractiveIframeHost.tsx | 156 +- .../scene-renderers/interactive-renderer.tsx | 4 +- components/settings/index.tsx | 24 + components/settings/skill-settings.tsx | 519 +++ components/site-header/theme-toggle.tsx | 66 + .../Editor/Canvas/EditableElement.tsx | 7 +- .../Editor/Canvas/hooks/useViewportSize.ts | 24 +- .../slide-renderer/Editor/Canvas/index.tsx | 13 +- .../Editor/LaserPointerOverlay.tsx | 3 +- .../Editor/RendererScreenCanvas.tsx | 3 +- .../slide-renderer/Editor/ScreenCanvas.tsx | 2 + .../slide-renderer/Editor/ScreenElement.tsx | 4 +- .../Editor/SpotlightOverlay.tsx | 5 +- components/slide-renderer/element-dom.ts | 22 + components/stage.tsx | 340 +- components/stage/header-controls.tsx | 33 +- components/ui/dialog.tsx | 5 +- components/ui/dropdown-menu.tsx | 15 +- components/ui/floating-layer-owner.tsx | 98 + components/ui/tooltip.tsx | 3 + components/workbench/ProBadge.tsx | 83 + components/workbench/ProLaunchPanel.tsx | 508 +++ components/workbench/ProSwapWatcher.tsx | 25 + components/workbench/WorkbenchChat.tsx | 1068 +++++++ .../workbench/WorkbenchReturnControl.tsx | 29 + components/workbench/WorkspaceEntry.tsx | 6 + components/workbench/chat/action-cluster.tsx | 67 + components/workbench/chat/autoscroll.ts | 134 + components/workbench/chat/chat-styles.ts | 419 +++ components/workbench/chat/chat-timeline.tsx | 351 +++ components/workbench/chat/composer-escape.ts | 70 + .../workbench/chat/composer-send-state.ts | 91 + components/workbench/chat/course-link.tsx | 164 + components/workbench/chat/empty-state.tsx | 59 + components/workbench/chat/format.ts | 20 + .../workbench/chat/question-card-state.ts | 186 ++ components/workbench/chat/question-card.tsx | 167 + .../workbench/chat/question-form-state.ts | 360 +++ components/workbench/chat/question-form.tsx | 224 ++ components/workbench/chat/status-dot.tsx | 53 + components/workbench/chat/system-node.tsx | 100 + components/workbench/chat/system-notice.ts | 108 + components/workbench/chat/text-block.tsx | 79 + .../workbench/chat/thinking-bar-state.ts | 76 + components/workbench/chat/thinking-block.tsx | 81 + components/workbench/chat/tool-card.tsx | 270 ++ components/workbench/chat/tool-group-state.ts | 79 + components/workbench/chat/tool-group.tsx | 142 + .../workbench/chat/tool-presentation.ts | 1002 ++++++ components/workbench/chat/tool-progress.ts | 116 + components/workbench/chat/user-bubble.tsx | 95 + components/workbench/chat/waiting-bar.tsx | 31 + components/workbench/chat/workbench-chat.css | 446 +++ components/workbench/compose-extras.tsx | 594 ++++ components/workbench/composer-input.tsx | 261 ++ components/workbench/composer-pill.tsx | 190 ++ components/workbench/course-mention-menu.tsx | 245 ++ components/workbench/course-ref-pills.tsx | 52 + components/workbench/element-ref-pills.tsx | 131 + components/workbench/pro-swap.css | 268 ++ .../workbench/use-skill-handle-backspace.ts | 46 + components/workbench/workspace-shell.css | 1987 ++++++++++++ .../workbench/workspace/PaneFoldButton.tsx | 74 + components/workbench/workspace/PaneTab.tsx | 44 + .../workbench/workspace/ResizeHandle.tsx | 125 + .../workbench/workspace/WorkspaceChatPane.tsx | 264 ++ .../workspace/WorkspaceClassroomPane.tsx | 173 + .../workspace/WorkspaceCourseTabs.tsx | 259 ++ .../workbench/workspace/WorkspaceHome.tsx | 200 ++ .../workbench/workspace/WorkspaceRail.tsx | 2298 ++++++++++++++ .../workbench/workspace/WorkspaceShell.tsx | 1222 ++++++++ .../workbench/workspace/pro-popover-scope.css | 205 ++ .../workbench/workspace/use-tree-drag.ts | 220 ++ .../workspace/workspace-folder-seam.ts | 68 + instrumentation.ts | 71 +- lib/action/engine.ts | 2 +- lib/agent-runtime/lifecycle.ts | 109 + lib/agent-runtime/stage-writer-tools.ts | 38 + lib/agent/DESIGN-regenerate-scene.md | 214 -- lib/agent/client/DESIGN-thread-persistence.md | 121 - lib/agent/client/agent-edit-session-types.ts | 35 - lib/agent/client/agent-history.ts | 74 - lib/agent/client/agent-thread-store.ts | 160 - lib/agent/client/apply-edit-elements.ts | 342 -- lib/agent/client/apply-slide-content.ts | 23 - lib/agent/client/edit-elements-result.ts | 50 - lib/agent/client/merge-assistant-parts.ts | 66 - lib/agent/client/regen-snapshots.ts | 95 - lib/agent/client/serialize-thread.ts | 183 -- lib/agent/client/thinking-timers.ts | 73 - lib/agent/client/to-pi-parts.ts | 52 - lib/agent/client/use-agent-runtime.ts | 701 ----- lib/agent/runtime/build-agent.ts | 49 +- lib/agent/runtime/stream-fn.ts | 12 +- lib/agent/runtime/tool-timeout.ts | 202 ++ .../tools/edit-elements-content-contract.ts | 10 - lib/agent/tools/edit-elements-gate.ts | 2318 -------------- lib/agent/tools/edit-elements-patch.ts | 526 ---- lib/agent/tools/edit-elements.ts | 201 -- lib/agent/tools/edit-interactive-html.ts | 153 - lib/agent/tools/read-scene-content.ts | 413 --- lib/agent/tools/regenerate-scene-actions.ts | 266 -- lib/agent/tools/regenerate-scene.ts | 298 -- lib/agent/tools/registry.ts | 50 - lib/ai/providers.ts | 47 +- lib/audio/constants.ts | 5 + lib/audio/qwen-voice-clone-registration.ts | 7 + lib/audio/regenerate-speech-tts.ts | 32 +- lib/audio/tts-providers.ts | 160 +- lib/audio/types.ts | 23 + lib/audio/voice-catalog.ts | 137 + lib/audio/voice-registration.ts | 7 + lib/audio/voxcpm-registration.ts | 7 + lib/brand/brand-config.ts | 34 + lib/brand/brand-context.tsx | 45 + lib/classroom/load-classroom.ts | 134 +- lib/classroom/progressive-load-policy.ts | 20 + lib/classroom/stage-meta-client.ts | 68 + lib/classroom/stage-ownership-signal.ts | 65 + lib/config/feature-flags.ts | 29 +- lib/document-store/migration.ts | 74 +- lib/document-store/persistence-types.ts | 37 + lib/document-store/plain-json-store.ts | 19 +- lib/document-store/validators.ts | 54 +- lib/document/extract-media.ts | 3 +- lib/document/extract-source.ts | 219 -- lib/document/extraction-cache.ts | 1474 --------- lib/document/extraction-materialization.ts | 97 - lib/document/extractors/images.ts | 49 + lib/document/extractors/local-media.ts | 835 +++++ lib/document/extractors/manifest.ts | 14 + lib/document/extractors/media-registry.ts | 44 +- lib/document/extractors/media.ts | 15 + lib/document/extractors/pdf.ts | 1 + lib/document/mime.ts | 13 + lib/document/types.ts | 4 + lib/edit/contain-box.ts | 80 + lib/edit/deleted-scene-recycle.ts | 41 + lib/edit/preload-editor.ts | 28 +- lib/edit/scene-defaults.ts | 50 + lib/edit/scene-pager.ts | 46 + lib/edit/slide-edit-elements.ts | 21 + lib/edit/stage-mode.ts | 94 + lib/edit/visible-client-rect.ts | 50 + lib/export/classroom-zip-utils.ts | 6 +- lib/export/proxied-fetch.ts | 43 +- lib/export/use-export-classroom.ts | 70 +- lib/hooks/use-audio-recorder.ts | 5 +- lib/hooks/use-browser-asr.ts | 7 +- lib/hooks/use-home-discovery.tsx | 302 ++ lib/hooks/use-scene-generator.ts | 80 +- lib/i18n/config.ts | 29 +- lib/i18n/locales/ar-SA.json | 190 +- lib/i18n/locales/de-DE.json | 190 +- lib/i18n/locales/en-US.json | 190 +- lib/i18n/locales/es-MX.json | 190 +- lib/i18n/locales/fr-FR.json | 190 +- lib/i18n/locales/ja-JP.json | 190 +- lib/i18n/locales/ko-KR.json | 190 +- lib/i18n/locales/pt-BR.json | 190 +- lib/i18n/locales/ru-RU.json | 190 +- lib/i18n/locales/vi-VN.json | 190 +- lib/i18n/locales/zh-CN.json | 190 +- lib/i18n/locales/zh-TW.json | 190 +- lib/i18n/workbench-locales/ar-SA.json | 289 ++ lib/i18n/workbench-locales/de-DE.json | 289 ++ lib/i18n/workbench-locales/es-MX.json | 289 ++ lib/i18n/workbench-locales/fr-FR.json | 289 ++ lib/i18n/workbench-locales/ja-JP.json | 289 ++ lib/i18n/workbench-locales/ko-KR.json | 289 ++ lib/i18n/workbench-locales/pt-BR.json | 289 ++ lib/i18n/workbench-locales/ru-RU.json | 289 ++ lib/i18n/workbench-locales/vi-VN.json | 289 ++ lib/i18n/workbench-locales/zh-TW.json | 289 ++ lib/i18n/workbench.ts | 729 +++++ lib/import/use-import-classroom.ts | 43 +- lib/interactive/logical-viewport.ts | 29 + lib/live/server-api.ts | 54 + lib/materials/library.ts | 597 ---- lib/media/asset-pool.ts | 17 +- lib/media/convert-inline-image-assets.ts | 576 ---- lib/media/convert-legacy-asset-refs.ts | 978 ------ lib/media/fetch-media-url.ts | 59 +- lib/media/image-providers.ts | 21 + lib/media/media-orchestrator.ts | 913 +----- lib/media/proxy-media-cache.ts | 390 +++ lib/media/reclaim-stage-assets.ts | 14 +- lib/media/types.ts | 8 + lib/pdf/pdf-providers.ts | 16 +- lib/pdf/types.ts | 2 + lib/persistence/bootstrap.ts | 24 +- lib/persistence/document-access.ts | 99 + lib/persistence/owner-bound-document-store.ts | 247 ++ lib/persistence/owner-materials.ts | 406 +++ lib/persistence/resolve-server-asset.ts | 13 +- lib/persistence/server-provider.ts | 6 + lib/persistence/stage-meta.ts | 163 + lib/playback/engine.ts | 2 +- .../agent-runtime/agent-driver-model.ts | 90 + lib/server/agent-runtime/ask-user.ts | 126 + lib/server/agent-runtime/config.ts | 56 + lib/server/agent-runtime/course-edit/apply.ts | 666 ++++ .../course-edit/element-schema.ts | 694 ++++ .../course-edit/media-byte-omission.ts | 384 +++ lib/server/agent-runtime/course-edit/tools.ts | 249 ++ .../agent-runtime/course-outline-union.ts | 187 ++ lib/server/agent-runtime/course-stage.ts | 25 + lib/server/agent-runtime/course-tools.ts | 317 ++ lib/server/agent-runtime/create-skill.ts | 82 + lib/server/agent-runtime/curriculum-tools.ts | 594 ++++ lib/server/agent-runtime/dsl-tools.ts | 991 ++++++ .../agent-runtime/entry-tree-storage.ts | 238 ++ lib/server/agent-runtime/event-notify-bus.ts | 427 +++ lib/server/agent-runtime/fetch-url.ts | 686 ++++ lib/server/agent-runtime/generate-image.ts | 372 +++ lib/server/agent-runtime/generate-video.ts | 366 +++ .../agent-runtime/generation-ai-call.ts | 42 + .../agent-runtime/generation-content.ts | 33 + lib/server/agent-runtime/generation-tools.ts | 553 ++++ .../agent-runtime/import-pptx-worker.mjs | 130 + lib/server/agent-runtime/import-pptx.ts | 561 ++++ lib/server/agent-runtime/limits.ts | 9 + lib/server/agent-runtime/material-media.ts | 79 + lib/server/agent-runtime/material-tools.ts | 611 ++++ lib/server/agent-runtime/media-tool-result.ts | 32 + lib/server/agent-runtime/mutation-fence.ts | 25 + lib/server/agent-runtime/node-xhr.ts | 133 + .../agent-runtime/owner-scoped-documents.ts | 49 + lib/server/agent-runtime/owner.ts | 65 + .../agent-runtime/personal-history-tools.ts | 592 ++++ lib/server/agent-runtime/pptx-mime.ts | 11 + lib/server/agent-runtime/resume.ts | 167 + lib/server/agent-runtime/roster-tools.ts | 389 +++ lib/server/agent-runtime/route-response.ts | 43 + lib/server/agent-runtime/runner-contract.ts | 16 + lib/server/agent-runtime/runner.ts | 1903 +++++++++++ lib/server/agent-runtime/scene-preview.ts | 101 + lib/server/agent-runtime/scene-tts.ts | 130 + lib/server/agent-runtime/session-materials.ts | 403 +++ lib/server/agent-runtime/session-urls.ts | 51 + lib/server/agent-runtime/skill-edit-tools.ts | 386 +++ lib/server/agent-runtime/skill-preload.ts | 439 +++ lib/server/agent-runtime/skills.ts | 862 +++++ lib/server/agent-runtime/stage-limits.ts | 9 + lib/server/agent-runtime/store.ts | 110 + .../agent-runtime/tool-call-integrity.ts | 236 ++ lib/server/agent-runtime/user-messages.ts | 46 + lib/server/agent-runtime/user-skill-store.ts | 81 + lib/server/agent-runtime/user-skills.ts | 84 + lib/server/agent-runtime/voice-clone-tools.ts | 441 +++ lib/server/agent-runtime/web-search.ts | 100 + lib/server/agent-runtime/with-owner.ts | 24 + lib/server/bounded-download.ts | 94 + lib/server/classroom-media-bytes.ts | 53 + lib/server/config-validation.ts | 23 +- lib/server/folder-name-errors.ts | 56 + lib/server/folder-persistence.ts | 91 + lib/server/image-sizing.ts | 59 + lib/server/material-extraction/errors.ts | 63 + lib/server/material-extraction/extract.ts | 262 ++ lib/server/material-extraction/runner.ts | 92 + lib/server/materials/bytes.ts | 66 + lib/server/media-origin.ts | 80 + lib/server/model-routes.ts | 54 +- lib/server/provider-config.ts | 43 + lib/server/skill-export.ts | 140 + lib/server/ssrf-guard.ts | 67 + lib/server/stage-access.ts | 134 + lib/store/canvas.ts | 14 +- lib/store/course-refs.ts | 115 + lib/store/draft-generation.ts | 46 + lib/store/element-refs.ts | 238 ++ lib/store/interactive-iframe-pool.ts | 19 +- lib/store/media-generation.ts | 16 +- lib/store/stage.ts | 68 +- lib/store/sync-canvas-viewport.ts | 59 + lib/types/action.ts | 5 + lib/types/settings.ts | 3 +- lib/utils/database.ts | 15 +- lib/utils/folder-name-validation.ts | 19 + lib/utils/iframe.ts | 179 +- lib/utils/stage-storage.ts | 223 +- lib/workbench/agent-skills.ts | 196 ++ lib/workbench/classroom-back-control.ts | 27 + lib/workbench/classroom-exit.ts | 60 + lib/workbench/classroom-header-controls.ts | 26 + lib/workbench/composer-image-transfer.ts | 62 + lib/workbench/composer-keys.ts | 64 + lib/workbench/composer-menus.ts | 60 + lib/workbench/composer-skills.ts | 218 ++ lib/workbench/composer-tokens.ts | 74 + lib/workbench/course-chat-bootstrap.ts | 139 + lib/workbench/course-discovery-sync.ts | 148 + lib/workbench/course-link.ts | 56 + lib/workbench/course-mention.ts | 133 + lib/workbench/course-ref-send-result.ts | 29 + lib/workbench/course-refs.ts | 161 + lib/workbench/created-course-tabs.ts | 49 + lib/workbench/element-ref-send-result.ts | 26 + lib/workbench/element-refs.ts | 482 +++ lib/workbench/entry-gate.ts | 6 + lib/workbench/existing-course.ts | 30 + lib/workbench/first-message-session.ts | 71 + lib/workbench/material-upload-policy.ts | 70 + lib/workbench/material-upload-scheduling.ts | 156 + lib/workbench/owner-session-client.ts | 347 ++ lib/workbench/panel-context.tsx | 162 + lib/workbench/pro-home-data.ts | 233 ++ lib/workbench/pro-playback-exit.ts | 34 + lib/workbench/pro-swap.ts | 152 + lib/workbench/run-courses.ts | 134 + lib/workbench/session-store.ts | 2157 +++++++++++++ lib/workbench/session-title.ts | 94 + lib/workbench/skill-load.ts | 35 + lib/workbench/stage-freshness.ts | 208 ++ lib/workbench/tts-stage-sync.ts | 40 + lib/workbench/use-workbench-pro-edit.ts | 23 + lib/workbench/use-workbench-session.ts | 656 ++++ .../use-workspace-pane-navigation.ts | 62 + lib/workbench/workspace-actions.ts | 39 + lib/workbench/workspace-course-tabs.ts | 84 + lib/workbench/workspace-navigation.ts | 70 + lib/workbench/workspace-order.ts | 156 + lib/workbench/workspace-paging.ts | 128 + lib/workbench/workspace-panes.ts | 406 +++ lib/workbench/workspace-rail-tab.ts | 45 + lib/workbench/workspace-session-memory.ts | 64 + lib/workbench/workspace-tree.ts | 89 + middleware.ts | 17 +- next.config.ts | 7 + package.json | 16 +- .../transformParsedToSlides.viewport.test.ts | 121 + packages/@openmaic/storage/README.md | 9 + packages/@openmaic/storage/package.json | 14 +- .../@openmaic/storage/src/agent-session/pg.ts | 1567 ++++++++++ .../storage/src/agent-session/types.ts | 583 ++++ packages/@openmaic/storage/src/document/pg.ts | 560 +++- .../@openmaic/storage/src/document/types.ts | 101 + packages/@openmaic/storage/src/index.ts | 117 +- packages/@openmaic/storage/src/material/pg.ts | 470 +++ .../@openmaic/storage/src/material/types.ts | 206 ++ packages/@openmaic/storage/src/skill/pg.ts | 366 +++ packages/@openmaic/storage/src/skill/types.ts | 581 ++++ .../agent-session-concurrency-contract.ts | 173 + .../storage/test/agent-session-contract.ts | 547 ++++ .../test/agent-session-material-contract.ts | 149 + .../test/agent-session-url-contract.ts | 148 + .../test/pg-agent-session-contract-helpers.ts | 74 + .../test/pg-agent-session-material.pg.test.ts | 105 + .../test/pg-agent-session-material.test.ts | 254 ++ .../test/pg-agent-session-store.pg.test.ts | 124 + .../test/pg-agent-session-store.test.ts | 413 +++ .../test/pg-document-contract-helpers.ts | 65 + .../storage/test/pg-document-store.pg.test.ts | 14 +- .../storage/test/pg-document-store.test.ts | 270 +- .../storage/test/pg-scene-revision.pg.test.ts | 276 ++ .../storage/test/pg-schema-contract.test.ts | 362 ++- .../storage/test/user-skill-store.test.ts | 341 ++ pnpm-lock.yaml | 384 ++- scripts/assert-pg-contract-suites.mjs | 7 +- .../build-personal-skill/SKILL.md | 29 + .../agent-runtime/curriculum-planner/SKILL.md | 212 ++ .../agent-runtime/deep-interactive/SKILL.md | 57 + .../deep-interactive/outline-constraints.json | 9 + skills/agent-runtime/deep-research/SKILL.md | 157 + .../deep-research/outline-constraints.json | 5 + .../agent-runtime/feynman-learning/SKILL.md | 152 + .../k12-core-literacy-planning/SKILL.md | 185 ++ .../references/core-literacy.md | 69 + .../references/subjects/humanities.md | 41 + .../references/subjects/languages.md | 43 + .../references/subjects/mathematics.md | 38 + .../references/subjects/science.md | 38 + .../agent-runtime/learning-to-learn/SKILL.md | 65 + skills/agent-runtime/lecture-style/SKILL.md | 119 + .../lecture-style/outline-constraints.json | 10 + skills/agent-runtime/page-clone/SKILL.md | 188 ++ skills/agent-runtime/pptx-import/SKILL.md | 200 ++ .../pptx-import/outline-constraints.json | 5 + skills/agent-runtime/pro-editing/SKILL.md | 173 + .../pro-editing/outline-constraints.json | 3 + skills/agent-runtime/slide-craft/SKILL.md | 295 ++ skills/agent-runtime/slide-dsl/SKILL.md | 892 ++++++ .../social-emotional-learning/SKILL.md | 53 + .../agent-runtime/spiral-curriculum/SKILL.md | 178 ++ skills/agent-runtime/stage-design/SKILL.md | 82 + skills/agent-runtime/stage-dsl/SKILL.md | 190 ++ .../stage-dsl/references/actions.md | 413 +++ .../agent-runtime/stage-dsl/references/pbl.md | 456 +++ .../stage-dsl/references/quiz.md | 372 +++ .../stage-dsl/references/widget.md | 423 +++ skills/agent-runtime/style-clone/SKILL.md | 320 ++ .../style-clone/outline-constraints.json | 5 + .../teacher-style-clone/SKILL.md | 83 + .../outline-constraints.json | 5 + .../understanding-by-design/SKILL.md | 70 + skills/agent-runtime/vocational/SKILL.md | 67 + .../vocational/outline-constraints.json | 12 + skills/agent-runtime/workshop-style/SKILL.md | 120 + .../workshop-style/outline-constraints.json | 12 + tests/agent-runtime/_fake-document-store.ts | 220 ++ tests/agent-runtime/_stage-fixtures.ts | 65 + .../agent-runtime/agent-driver-model.test.ts | 265 ++ .../ask-user-claim-interleaving.test.ts | 109 + tests/agent-runtime/attempt-cap.test.ts | 82 + tests/agent-runtime/cancel-route.test.ts | 67 + .../course-outline-union.test.ts | 239 ++ tests/agent-runtime/course-stage.test.ts | 28 + tests/agent-runtime/create-skill.test.ts | 76 + tests/agent-runtime/curriculum-tools.test.ts | 803 +++++ tests/agent-runtime/dsl-tools.test.ts | 1442 +++++++++ .../element-ref-message-adapter.test.ts | 46 + .../agent-runtime/entry-tree-storage.test.ts | 176 ++ tests/agent-runtime/event-log-slim.test.ts | 159 + tests/agent-runtime/event-notify-bus.test.ts | 193 ++ tests/agent-runtime/event-notify.pg.test.ts | 173 + tests/agent-runtime/fetch-url-tool.test.ts | 245 ++ tests/agent-runtime/fetch-url.test.ts | 326 ++ tests/agent-runtime/folders-routes.test.ts | 261 ++ tests/agent-runtime/generate-image.test.ts | 339 ++ .../generate-media-force-off.test.ts | 149 + tests/agent-runtime/generate-video.test.ts | 377 +++ .../agent-runtime/generation-content.test.ts | 36 + tests/agent-runtime/generation-media.test.ts | 118 + tests/agent-runtime/generation-tools.test.ts | 298 ++ tests/agent-runtime/import-pptx.test.ts | 730 +++++ .../material-detail-route.test.ts | 118 + .../agent-runtime/material-extraction.test.ts | 306 ++ tests/agent-runtime/material-tools.test.ts | 665 ++++ tests/agent-runtime/materials-route.test.ts | 323 ++ tests/agent-runtime/messages-route.test.ts | 162 + .../agent-runtime/owner-events-route.test.ts | 541 ++++ tests/agent-runtime/owner.test.ts | 76 + .../park-attempt-budget.pg.test.ts | 124 + .../persistence-routes-gate.test.ts | 462 +++ .../personal-history-runner-wiring.test.ts | 14 + .../personal-history-tools.test.ts | 268 ++ tests/agent-runtime/resume.test.ts | 323 ++ tests/agent-runtime/roster-tools.test.ts | 500 +++ tests/agent-runtime/run-start.test.ts | 266 ++ tests/agent-runtime/runner-contract.test.ts | 18 + .../agent-runtime/runner-event-order.test.ts | 105 + .../runner-skills-registration.test.ts | 396 +++ .../runner-tool-call-integrity.test.ts | 382 +++ .../runner-tool-timeout-cancel.test.ts | 344 ++ .../runner-voice-registration.test.ts | 472 +++ tests/agent-runtime/runner-wakeup.test.ts | 417 +++ .../runner-web-search-registration.test.ts | 513 +++ tests/agent-runtime/runtime-probe.test.ts | 48 + tests/agent-runtime/scene-tts.test.ts | 69 + .../session-detail-route.test.ts | 55 + .../session-events-live.pg.test.ts | 141 + .../session-events-route.test.ts | 331 ++ tests/agent-runtime/session-materials.test.ts | 215 ++ .../session-status-route.test.ts | 53 + tests/agent-runtime/session-urls.test.ts | 98 + tests/agent-runtime/sessions-route.test.ts | 272 ++ .../agent-runtime/skill-detail-route.test.ts | 100 + tests/agent-runtime/skill-edit-tools.test.ts | 1639 ++++++++++ .../skill-handle-inference.test.ts | 99 + tests/agent-runtime/skill-preload.test.ts | 683 ++++ tests/agent-runtime/skills-route.test.ts | 122 + tests/agent-runtime/skills.test.ts | 1257 ++++++++ .../agent-runtime/stage-detail-route.test.ts | 243 ++ .../stage-freshness-route.test.ts | 139 + .../stage-manifest-route.test.ts | 100 + tests/agent-runtime/stage-meta-routes.test.ts | 204 ++ .../agent-runtime/stage-scenes-route.test.ts | 97 + .../stage-writer-registry.test.ts | 82 + tests/agent-runtime/stages-route.test.ts | 219 ++ .../agent-runtime/tool-call-integrity.test.ts | 308 ++ tests/agent-runtime/tts-abort-timeout.test.ts | 156 + .../agent-runtime/user-skills-runtime.test.ts | 70 + .../user-skills-validation.test.ts | 48 + tests/agent-runtime/voice-clone-tools.test.ts | 517 +++ tests/agent-runtime/web-search.test.ts | 163 + tests/ai/openai-provider.test.ts | 53 + tests/ai/openai-sdk-integration.test.ts | 70 +- tests/audio/narrator-pin-fallback.test.ts | 4 +- tests/audio/voice-catalog.test.ts | 135 + .../fetch-classroom-from-api.test.ts | 501 --- .../classroom/progressive-load-policy.test.ts | 43 + tests/config/feature-flags.test.ts | 61 + tests/document-store/migration.test.ts | 35 +- tests/document/extract-source.test.ts | 383 --- tests/document/extraction-cache.test.ts | 2394 -------------- .../extraction-materialization.test.ts | 113 - tests/document/local-media-extractor.test.ts | 168 + .../material-library-manifest.test.ts | 167 - tests/edit/agent-panel-visibility.test.ts | 28 - tests/edit/canvas-fit-scale-wiring.test.ts | 31 + tests/edit/contain-box.test.ts | 76 + tests/edit/edit-dock-chrome.test.ts | 46 + tests/edit/edit-dock-lifecycle.test.ts | 322 ++ tests/edit/edit-tool-state.test.ts | 95 - tests/edit/element-ref-lasso.test.ts | 287 ++ tests/edit/insert-toolbar-float.test.ts | 376 +++ tests/edit/stage-mode.test.ts | 81 +- .../slide/element-pick-layer-purposes.test.ts | 1019 ++++++ .../element-pick-layer-renderer-dom.test.ts | 41 +- .../renderer-editor-architecture.test.ts | 13 - .../slide/renderer-element-dom.test.ts | 19 + .../slide/slide-canvas-renderer-flag.test.ts | 3 + tests/edit/visible-client-rect.test.ts | 24 + .../export-classroom-conversion.test.ts | 670 ---- tests/export/proxied-fetch.test.ts | 64 +- tests/fixtures/fetch-url/chinese-article.html | 25 + .../scene-content-asset-id-vision.test.ts | 16 +- tests/hooks/use-scene-generator-retry.test.ts | 45 +- tests/i18n/edit-chrome-keys.test.ts | 201 ++ tests/import/import-media-assets.test.ts | 8 +- .../client/agent-edit-session-types.test.ts | 41 - tests/lib/agent/client/agent-history.test.ts | 60 - .../agent/client/agent-thread-store.test.ts | 178 -- .../agent/client/apply-edit-elements.test.ts | 722 ----- .../agent/client/apply-slide-content.test.ts | 68 - .../agent/client/edit-elements-result.test.ts | 48 - .../client/merge-assistant-parts.test.ts | 44 - .../lib/agent/client/regen-snapshots.test.ts | 113 - .../lib/agent/client/serialize-thread.test.ts | 222 -- .../lib/agent/client/thinking-timers.test.ts | 38 - tests/lib/agent/client/to-pi-parts.test.ts | 37 - tests/lib/agent/client/tool-card.test.ts | 37 - .../agent/client/use-agent-runtime.test.ts | 114 - .../agent/runtime/agent-tool-timeout.test.ts | 132 + tests/lib/agent/runtime/build-agent.test.ts | 37 - .../runtime/editor-transport-consumer.test.ts | 180 -- tests/lib/agent/runtime/tool-timeout.test.ts | 216 ++ .../agent/tools/build-image-resources.test.ts | 116 - .../agent/tools/edit-elements-gate.test.ts | 2778 ----------------- .../agent/tools/edit-elements-patch.test.ts | 578 ---- tests/lib/agent/tools/edit-elements.test.ts | 133 - .../agent/tools/edit-interactive-html.test.ts | 113 - .../agent/tools/read-scene-content.test.ts | 300 -- .../tools/regenerate-scene-actions.test.ts | 237 -- .../lib/agent/tools/regenerate-scene.test.ts | 209 -- tests/lib/agent/tools/registry.test.ts | 32 - tests/lib/brand/brand-config.test.ts | 16 + tests/lib/utils/iframe-element-picker.test.ts | 94 + tests/materials/library.test.ts | 652 ---- tests/media/asset-pool.test.ts | 6 +- tests/media/classroom-media-bytes.test.ts | 89 + ...convert-inline-image-assets-wiring.test.ts | 586 ---- .../media/convert-inline-image-assets.test.ts | 941 ------ .../convert-legacy-asset-refs-wiring.test.ts | 349 --- tests/media/convert-legacy-asset-refs.test.ts | 1413 --------- tests/media/media-orchestrator.test.ts | 1755 ++--------- tests/media/min-pixel-floor.test.ts | 48 + tests/media/proxy-media-cache.test.ts | 690 ++++ tests/media/reclamation-matrix.test.ts | 6 +- tests/media/use-asset-url.test.ts | 13 +- tests/persistence/bootstrap.test.ts | 21 +- tests/persistence/material-bytes.test.ts | 43 + tests/persistence/owner-materials.pg.test.ts | 134 + tests/persistence/owner-materials.test.ts | 340 ++ tests/persistence/route.test.ts | 12 + .../persistence/stage-access-fidelity.test.ts | 179 ++ .../provider-neutrality-guard.test.ts | 27 +- tests/runtime/database-chat-cutover.test.ts | 4 +- .../genui-logical-viewport.test.ts | 37 + .../interactive-iframe-picker.test.ts | 87 + tests/server/bounded-download.test.ts | 82 + tests/server/config-validation.test.ts | 39 + tests/server/image-sizing.test.ts | 63 + tests/server/media-origin.test.ts | 64 + tests/server/model-routes.test.ts | 160 + tests/server/provider-config.test.ts | 27 + tests/server/resolve-model.test.ts | 18 + tests/server/skill-export.test.ts | 92 + tests/server/ssrf-guard.test.ts | 130 + tests/settings/skill-settings-locales.test.ts | 73 + tests/settings/skill-settings.test.ts | 351 +++ tests/store/interactive-iframe-pool.test.ts | 11 + .../stage-incremental-persistence.test.ts | 36 +- tests/store/sync-canvas-viewport.test.ts | 42 + tests/utils/stage-storage-deletion.test.ts | 9 +- tests/workbench/agent-end-gap.test.ts | 59 + tests/workbench/agent-skills.test.ts | 116 + tests/workbench/chat-gutter.test.ts | 201 ++ tests/workbench/chat-timeline.test.ts | 365 +++ tests/workbench/classroom-exit-wiring.test.ts | 19 + tests/workbench/classroom-exit.test.ts | 74 + .../classroom-pane-edit-lock.test.ts | 197 ++ tests/workbench/composer-escape.test.ts | 42 + tests/workbench/composer-menus.test.ts | 178 ++ tests/workbench/composer-send-state.test.ts | 141 + tests/workbench/composer-skills.test.ts | 278 ++ tests/workbench/course-chat-bootstrap.test.ts | 102 + tests/workbench/course-discovery-sync.test.ts | 318 ++ tests/workbench/course-link.test.ts | 26 + tests/workbench/course-ref-send.test.ts | 107 + tests/workbench/course-refs.test.ts | 151 + tests/workbench/created-course-tabs.test.ts | 80 + .../draft-conversation-reset.test.ts | 302 ++ .../element-ref-owner-lifecycle.test.ts | 124 + tests/workbench/element-ref-send.test.ts | 129 + tests/workbench/element-refs.test.ts | 300 ++ tests/workbench/empty-state.test.ts | 77 + tests/workbench/entry-gate.test.ts | 50 + tests/workbench/entry-points-restore.test.ts | 239 ++ tests/workbench/entry-routes.test.ts | 51 + tests/workbench/existing-course.test.ts | 124 + tests/workbench/home-discovery-reload.test.ts | 155 + .../launch-course-refs-client.test.ts | 82 + .../launch-course-refs-receipt.test.ts | 110 + tests/workbench/material-client.test.ts | 116 + .../material-upload-scheduling.test.ts | 127 + tests/workbench/owner-session-client.test.ts | 707 +++++ .../workbench/pg-mode-folder-listing.test.ts | 343 ++ tests/workbench/pg-mode-home-listing.test.ts | 214 ++ tests/workbench/pro-badge-switch.test.ts | 58 + tests/workbench/pro-home-data.test.ts | 294 ++ tests/workbench/pro-swap.test.ts | 170 + tests/workbench/question-card.test.ts | 342 ++ tests/workbench/question-form.test.ts | 443 +++ tests/workbench/replay-compact.test.ts | 80 + tests/workbench/run-courses.test.ts | 154 + tests/workbench/seed-slash-query.test.ts | 57 + tests/workbench/session-cancel-client.test.ts | 98 + .../session-events-subscription.test.ts | 71 + tests/workbench/session-fold.test.ts | 2307 ++++++++++++++ tests/workbench/session-title.test.ts | 175 ++ tests/workbench/skill-load-card-fold.test.ts | 153 + tests/workbench/stage-freshness-fetch.test.ts | 143 + tests/workbench/stage-freshness-sync.test.ts | 867 +++++ tests/workbench/stage-rename-client.test.ts | 68 + tests/workbench/system-notice.test.ts | 175 ++ tests/workbench/thinking-bar-state.test.ts | 20 + tests/workbench/thinking-stream-seam.test.ts | 118 + tests/workbench/tool-card.test.ts | 172 + tests/workbench/tool-group-state.test.ts | 124 + tests/workbench/tool-presentation.test.ts | 497 +++ tests/workbench/tool-progress.test.ts | 77 + tests/workbench/tts-stage-sync.test.ts | 80 + tests/workbench/use-tree-drag.test.ts | 142 + tests/workbench/workbench-i18n.test.ts | 212 ++ .../workspace-course-chat-bootstrap.test.ts | 766 +++++ .../workspace-course-persistence.test.ts | 68 + tests/workbench/workspace-course-tabs.test.ts | 76 + tests/workbench/workspace-folder-seam.test.ts | 62 + tests/workbench/workspace-navigation.test.ts | 81 + tests/workbench/workspace-order.test.ts | 128 + tests/workbench/workspace-paging.test.ts | 117 + tests/workbench/workspace-pane-folds.test.ts | 320 ++ .../workspace-pane-head-alignment.test.ts | 69 + .../workspace-pane-navigation.test.ts | 103 + tests/workbench/workspace-panes.test.ts | 464 +++ .../workbench/workspace-rail-overflow.test.ts | 207 ++ .../workspace-rail-session-rename.test.ts | 211 ++ tests/workbench/workspace-rail-tab.test.ts | 42 + .../workspace-session-memory.test.ts | 55 + .../workspace-transient-sidebar.test.ts | 35 + tests/workbench/workspace-tree.test.ts | 76 + types/web-extraction-vendors.d.ts | 26 + types/web-speech.d.ts | 14 + 744 files changed, 117751 insertions(+), 31981 deletions(-) delete mode 100644 app/api/agent/edit/route.ts create mode 100644 app/api/agent/owner-events/route.ts create mode 100644 app/api/agent/runtime/route.ts create mode 100644 app/api/agent/sessions/[id]/cancel/route.ts create mode 100644 app/api/agent/sessions/[id]/events/route.ts create mode 100644 app/api/agent/sessions/[id]/messages/route.ts create mode 100644 app/api/agent/sessions/[id]/route.ts create mode 100644 app/api/agent/sessions/route.ts create mode 100644 app/api/agent/sessions/status/route.ts create mode 100644 app/api/agent/skills/[id]/route.ts create mode 100644 app/api/agent/skills/route.ts create mode 100644 app/api/folders/[id]/route.ts create mode 100644 app/api/folders/members/route.ts create mode 100644 app/api/folders/route.ts create mode 100644 app/api/materials/[id]/route.ts create mode 100644 app/api/materials/route.ts create mode 100644 app/api/skills/[id]/route.ts create mode 100644 app/api/stage-meta/[stageId]/route.ts create mode 100644 app/api/stages/[id]/freshness/route.ts create mode 100644 app/api/stages/[id]/generation-complete/route.ts create mode 100644 app/api/stages/[id]/manifest/route.ts create mode 100644 app/api/stages/[id]/publish/route.ts create mode 100644 app/api/stages/[id]/route.ts create mode 100644 app/api/stages/[id]/scenes/route.ts create mode 100644 app/api/stages/[id]/status/route.ts create mode 100644 app/api/stages/[id]/unpublish/route.ts create mode 100644 app/api/stages/route.ts create mode 100644 app/workbench/new/client.tsx create mode 100644 app/workbench/new/page.tsx create mode 100644 app/workspace/page.tsx create mode 100644 components/classroom/ClassroomSurface.tsx delete mode 100644 components/edit/AgentPanel/AgentPanel.tsx delete mode 100644 components/edit/AgentPanel/DESIGN-agentbar-polish.md delete mode 100644 components/edit/AgentPanel/edit-elements-tool-ui.tsx delete mode 100644 components/edit/AgentPanel/edit-interactive-html-tool-ui.tsx delete mode 100644 components/edit/AgentPanel/edit-tool-state.ts delete mode 100644 components/edit/AgentPanel/markdown-text.tsx delete mode 100644 components/edit/AgentPanel/read-tool-ui.tsx delete mode 100644 components/edit/AgentPanel/reasoning-part.tsx delete mode 100644 components/edit/AgentPanel/regenerate-scene-tool-ui.tsx delete mode 100644 components/edit/AgentPanel/regenerate-tool-ui.tsx delete mode 100644 components/edit/AgentPanel/restore-button.tsx delete mode 100644 components/edit/AgentPanel/tool-card.tsx create mode 100644 components/edit/AgentsView/RosterDialog.tsx create mode 100644 components/edit/ContainBox.tsx create mode 100644 components/edit/EditDock/DockEditBar.tsx create mode 100644 components/edit/EditDock/EditDock.tsx create mode 100644 components/edit/EditDock/ElementRefLassoButton.tsx create mode 100644 components/edit/EditDock/dock-context.tsx create mode 100644 components/edit/EditShell/CanvasPager.tsx delete mode 100644 components/edit/RightRailTabs.tsx delete mode 100644 components/edit/agent-panel-visibility.ts create mode 100644 components/edit/surfaces/slide/CanvasOverlayPortal.tsx create mode 100644 components/edit/surfaces/slide/ElementRefPinLayer.tsx create mode 100644 components/edit/surfaces/slide/element-hit-test.ts create mode 100644 components/settings/skill-settings.tsx create mode 100644 components/site-header/theme-toggle.tsx create mode 100644 components/slide-renderer/element-dom.ts create mode 100644 components/ui/floating-layer-owner.tsx create mode 100644 components/workbench/ProBadge.tsx create mode 100644 components/workbench/ProLaunchPanel.tsx create mode 100644 components/workbench/ProSwapWatcher.tsx create mode 100644 components/workbench/WorkbenchChat.tsx create mode 100644 components/workbench/WorkbenchReturnControl.tsx create mode 100644 components/workbench/WorkspaceEntry.tsx create mode 100644 components/workbench/chat/action-cluster.tsx create mode 100644 components/workbench/chat/autoscroll.ts create mode 100644 components/workbench/chat/chat-styles.ts create mode 100644 components/workbench/chat/chat-timeline.tsx create mode 100644 components/workbench/chat/composer-escape.ts create mode 100644 components/workbench/chat/composer-send-state.ts create mode 100644 components/workbench/chat/course-link.tsx create mode 100644 components/workbench/chat/empty-state.tsx create mode 100644 components/workbench/chat/format.ts create mode 100644 components/workbench/chat/question-card-state.ts create mode 100644 components/workbench/chat/question-card.tsx create mode 100644 components/workbench/chat/question-form-state.ts create mode 100644 components/workbench/chat/question-form.tsx create mode 100644 components/workbench/chat/status-dot.tsx create mode 100644 components/workbench/chat/system-node.tsx create mode 100644 components/workbench/chat/system-notice.ts create mode 100644 components/workbench/chat/text-block.tsx create mode 100644 components/workbench/chat/thinking-bar-state.ts create mode 100644 components/workbench/chat/thinking-block.tsx create mode 100644 components/workbench/chat/tool-card.tsx create mode 100644 components/workbench/chat/tool-group-state.ts create mode 100644 components/workbench/chat/tool-group.tsx create mode 100644 components/workbench/chat/tool-presentation.ts create mode 100644 components/workbench/chat/tool-progress.ts create mode 100644 components/workbench/chat/user-bubble.tsx create mode 100644 components/workbench/chat/waiting-bar.tsx create mode 100644 components/workbench/chat/workbench-chat.css create mode 100644 components/workbench/compose-extras.tsx create mode 100644 components/workbench/composer-input.tsx create mode 100644 components/workbench/composer-pill.tsx create mode 100644 components/workbench/course-mention-menu.tsx create mode 100644 components/workbench/course-ref-pills.tsx create mode 100644 components/workbench/element-ref-pills.tsx create mode 100644 components/workbench/pro-swap.css create mode 100644 components/workbench/use-skill-handle-backspace.ts create mode 100644 components/workbench/workspace-shell.css create mode 100644 components/workbench/workspace/PaneFoldButton.tsx create mode 100644 components/workbench/workspace/PaneTab.tsx create mode 100644 components/workbench/workspace/ResizeHandle.tsx create mode 100644 components/workbench/workspace/WorkspaceChatPane.tsx create mode 100644 components/workbench/workspace/WorkspaceClassroomPane.tsx create mode 100644 components/workbench/workspace/WorkspaceCourseTabs.tsx create mode 100644 components/workbench/workspace/WorkspaceHome.tsx create mode 100644 components/workbench/workspace/WorkspaceRail.tsx create mode 100644 components/workbench/workspace/WorkspaceShell.tsx create mode 100644 components/workbench/workspace/pro-popover-scope.css create mode 100644 components/workbench/workspace/use-tree-drag.ts create mode 100644 components/workbench/workspace/workspace-folder-seam.ts create mode 100644 lib/agent-runtime/lifecycle.ts create mode 100644 lib/agent-runtime/stage-writer-tools.ts delete mode 100644 lib/agent/DESIGN-regenerate-scene.md delete mode 100644 lib/agent/client/DESIGN-thread-persistence.md delete mode 100644 lib/agent/client/agent-edit-session-types.ts delete mode 100644 lib/agent/client/agent-history.ts delete mode 100644 lib/agent/client/agent-thread-store.ts delete mode 100644 lib/agent/client/apply-edit-elements.ts delete mode 100644 lib/agent/client/apply-slide-content.ts delete mode 100644 lib/agent/client/edit-elements-result.ts delete mode 100644 lib/agent/client/merge-assistant-parts.ts delete mode 100644 lib/agent/client/regen-snapshots.ts delete mode 100644 lib/agent/client/serialize-thread.ts delete mode 100644 lib/agent/client/thinking-timers.ts delete mode 100644 lib/agent/client/to-pi-parts.ts delete mode 100644 lib/agent/client/use-agent-runtime.ts create mode 100644 lib/agent/runtime/tool-timeout.ts delete mode 100644 lib/agent/tools/edit-elements-content-contract.ts delete mode 100644 lib/agent/tools/edit-elements-gate.ts delete mode 100644 lib/agent/tools/edit-elements-patch.ts delete mode 100644 lib/agent/tools/edit-elements.ts delete mode 100644 lib/agent/tools/edit-interactive-html.ts delete mode 100644 lib/agent/tools/read-scene-content.ts delete mode 100644 lib/agent/tools/regenerate-scene-actions.ts delete mode 100644 lib/agent/tools/regenerate-scene.ts delete mode 100644 lib/agent/tools/registry.ts create mode 100644 lib/audio/voice-catalog.ts create mode 100644 lib/brand/brand-config.ts create mode 100644 lib/brand/brand-context.tsx create mode 100644 lib/classroom/progressive-load-policy.ts create mode 100644 lib/classroom/stage-meta-client.ts create mode 100644 lib/classroom/stage-ownership-signal.ts delete mode 100644 lib/document/extract-source.ts delete mode 100644 lib/document/extraction-cache.ts delete mode 100644 lib/document/extraction-materialization.ts create mode 100644 lib/document/extractors/images.ts create mode 100644 lib/document/extractors/local-media.ts create mode 100644 lib/edit/contain-box.ts create mode 100644 lib/edit/deleted-scene-recycle.ts create mode 100644 lib/edit/scene-defaults.ts create mode 100644 lib/edit/scene-pager.ts create mode 100644 lib/edit/visible-client-rect.ts create mode 100644 lib/hooks/use-home-discovery.tsx create mode 100644 lib/i18n/workbench-locales/ar-SA.json create mode 100644 lib/i18n/workbench-locales/de-DE.json create mode 100644 lib/i18n/workbench-locales/es-MX.json create mode 100644 lib/i18n/workbench-locales/fr-FR.json create mode 100644 lib/i18n/workbench-locales/ja-JP.json create mode 100644 lib/i18n/workbench-locales/ko-KR.json create mode 100644 lib/i18n/workbench-locales/pt-BR.json create mode 100644 lib/i18n/workbench-locales/ru-RU.json create mode 100644 lib/i18n/workbench-locales/vi-VN.json create mode 100644 lib/i18n/workbench-locales/zh-TW.json create mode 100644 lib/i18n/workbench.ts create mode 100644 lib/interactive/logical-viewport.ts create mode 100644 lib/live/server-api.ts delete mode 100644 lib/materials/library.ts delete mode 100644 lib/media/convert-inline-image-assets.ts delete mode 100644 lib/media/convert-legacy-asset-refs.ts create mode 100644 lib/media/proxy-media-cache.ts create mode 100644 lib/persistence/document-access.ts create mode 100644 lib/persistence/owner-bound-document-store.ts create mode 100644 lib/persistence/owner-materials.ts create mode 100644 lib/persistence/stage-meta.ts create mode 100644 lib/server/agent-runtime/agent-driver-model.ts create mode 100644 lib/server/agent-runtime/ask-user.ts create mode 100644 lib/server/agent-runtime/config.ts create mode 100644 lib/server/agent-runtime/course-edit/apply.ts create mode 100644 lib/server/agent-runtime/course-edit/element-schema.ts create mode 100644 lib/server/agent-runtime/course-edit/media-byte-omission.ts create mode 100644 lib/server/agent-runtime/course-edit/tools.ts create mode 100644 lib/server/agent-runtime/course-outline-union.ts create mode 100644 lib/server/agent-runtime/course-stage.ts create mode 100644 lib/server/agent-runtime/course-tools.ts create mode 100644 lib/server/agent-runtime/create-skill.ts create mode 100644 lib/server/agent-runtime/curriculum-tools.ts create mode 100644 lib/server/agent-runtime/dsl-tools.ts create mode 100644 lib/server/agent-runtime/entry-tree-storage.ts create mode 100644 lib/server/agent-runtime/event-notify-bus.ts create mode 100644 lib/server/agent-runtime/fetch-url.ts create mode 100644 lib/server/agent-runtime/generate-image.ts create mode 100644 lib/server/agent-runtime/generate-video.ts create mode 100644 lib/server/agent-runtime/generation-ai-call.ts create mode 100644 lib/server/agent-runtime/generation-content.ts create mode 100644 lib/server/agent-runtime/generation-tools.ts create mode 100644 lib/server/agent-runtime/import-pptx-worker.mjs create mode 100644 lib/server/agent-runtime/import-pptx.ts create mode 100644 lib/server/agent-runtime/limits.ts create mode 100644 lib/server/agent-runtime/material-media.ts create mode 100644 lib/server/agent-runtime/material-tools.ts create mode 100644 lib/server/agent-runtime/media-tool-result.ts create mode 100644 lib/server/agent-runtime/mutation-fence.ts create mode 100644 lib/server/agent-runtime/node-xhr.ts create mode 100644 lib/server/agent-runtime/owner-scoped-documents.ts create mode 100644 lib/server/agent-runtime/owner.ts create mode 100644 lib/server/agent-runtime/personal-history-tools.ts create mode 100644 lib/server/agent-runtime/pptx-mime.ts create mode 100644 lib/server/agent-runtime/resume.ts create mode 100644 lib/server/agent-runtime/roster-tools.ts create mode 100644 lib/server/agent-runtime/route-response.ts create mode 100644 lib/server/agent-runtime/runner-contract.ts create mode 100644 lib/server/agent-runtime/runner.ts create mode 100644 lib/server/agent-runtime/scene-preview.ts create mode 100644 lib/server/agent-runtime/scene-tts.ts create mode 100644 lib/server/agent-runtime/session-materials.ts create mode 100644 lib/server/agent-runtime/session-urls.ts create mode 100644 lib/server/agent-runtime/skill-edit-tools.ts create mode 100644 lib/server/agent-runtime/skill-preload.ts create mode 100644 lib/server/agent-runtime/skills.ts create mode 100644 lib/server/agent-runtime/stage-limits.ts create mode 100644 lib/server/agent-runtime/store.ts create mode 100644 lib/server/agent-runtime/tool-call-integrity.ts create mode 100644 lib/server/agent-runtime/user-messages.ts create mode 100644 lib/server/agent-runtime/user-skill-store.ts create mode 100644 lib/server/agent-runtime/user-skills.ts create mode 100644 lib/server/agent-runtime/voice-clone-tools.ts create mode 100644 lib/server/agent-runtime/web-search.ts create mode 100644 lib/server/agent-runtime/with-owner.ts create mode 100644 lib/server/bounded-download.ts create mode 100644 lib/server/classroom-media-bytes.ts create mode 100644 lib/server/folder-name-errors.ts create mode 100644 lib/server/folder-persistence.ts create mode 100644 lib/server/image-sizing.ts create mode 100644 lib/server/material-extraction/errors.ts create mode 100644 lib/server/material-extraction/extract.ts create mode 100644 lib/server/material-extraction/runner.ts create mode 100644 lib/server/materials/bytes.ts create mode 100644 lib/server/media-origin.ts create mode 100644 lib/server/skill-export.ts create mode 100644 lib/server/stage-access.ts create mode 100644 lib/store/course-refs.ts create mode 100644 lib/store/draft-generation.ts create mode 100644 lib/store/element-refs.ts create mode 100644 lib/store/sync-canvas-viewport.ts create mode 100644 lib/workbench/agent-skills.ts create mode 100644 lib/workbench/classroom-back-control.ts create mode 100644 lib/workbench/classroom-exit.ts create mode 100644 lib/workbench/classroom-header-controls.ts create mode 100644 lib/workbench/composer-image-transfer.ts create mode 100644 lib/workbench/composer-keys.ts create mode 100644 lib/workbench/composer-menus.ts create mode 100644 lib/workbench/composer-skills.ts create mode 100644 lib/workbench/composer-tokens.ts create mode 100644 lib/workbench/course-chat-bootstrap.ts create mode 100644 lib/workbench/course-discovery-sync.ts create mode 100644 lib/workbench/course-link.ts create mode 100644 lib/workbench/course-mention.ts create mode 100644 lib/workbench/course-ref-send-result.ts create mode 100644 lib/workbench/course-refs.ts create mode 100644 lib/workbench/created-course-tabs.ts create mode 100644 lib/workbench/element-ref-send-result.ts create mode 100644 lib/workbench/element-refs.ts create mode 100644 lib/workbench/entry-gate.ts create mode 100644 lib/workbench/existing-course.ts create mode 100644 lib/workbench/first-message-session.ts create mode 100644 lib/workbench/material-upload-policy.ts create mode 100644 lib/workbench/material-upload-scheduling.ts create mode 100644 lib/workbench/owner-session-client.ts create mode 100644 lib/workbench/panel-context.tsx create mode 100644 lib/workbench/pro-home-data.ts create mode 100644 lib/workbench/pro-playback-exit.ts create mode 100644 lib/workbench/pro-swap.ts create mode 100644 lib/workbench/run-courses.ts create mode 100644 lib/workbench/session-store.ts create mode 100644 lib/workbench/session-title.ts create mode 100644 lib/workbench/skill-load.ts create mode 100644 lib/workbench/stage-freshness.ts create mode 100644 lib/workbench/tts-stage-sync.ts create mode 100644 lib/workbench/use-workbench-pro-edit.ts create mode 100644 lib/workbench/use-workbench-session.ts create mode 100644 lib/workbench/use-workspace-pane-navigation.ts create mode 100644 lib/workbench/workspace-actions.ts create mode 100644 lib/workbench/workspace-course-tabs.ts create mode 100644 lib/workbench/workspace-navigation.ts create mode 100644 lib/workbench/workspace-order.ts create mode 100644 lib/workbench/workspace-paging.ts create mode 100644 lib/workbench/workspace-panes.ts create mode 100644 lib/workbench/workspace-rail-tab.ts create mode 100644 lib/workbench/workspace-session-memory.ts create mode 100644 lib/workbench/workspace-tree.ts create mode 100644 packages/@openmaic/importer/test/transformParsedToSlides.viewport.test.ts create mode 100644 packages/@openmaic/storage/src/agent-session/pg.ts create mode 100644 packages/@openmaic/storage/src/agent-session/types.ts create mode 100644 packages/@openmaic/storage/src/material/pg.ts create mode 100644 packages/@openmaic/storage/src/material/types.ts create mode 100644 packages/@openmaic/storage/src/skill/pg.ts create mode 100644 packages/@openmaic/storage/src/skill/types.ts create mode 100644 packages/@openmaic/storage/test/agent-session-concurrency-contract.ts create mode 100644 packages/@openmaic/storage/test/agent-session-contract.ts create mode 100644 packages/@openmaic/storage/test/agent-session-material-contract.ts create mode 100644 packages/@openmaic/storage/test/agent-session-url-contract.ts create mode 100644 packages/@openmaic/storage/test/pg-agent-session-contract-helpers.ts create mode 100644 packages/@openmaic/storage/test/pg-agent-session-material.pg.test.ts create mode 100644 packages/@openmaic/storage/test/pg-agent-session-material.test.ts create mode 100644 packages/@openmaic/storage/test/pg-agent-session-store.pg.test.ts create mode 100644 packages/@openmaic/storage/test/pg-agent-session-store.test.ts create mode 100644 packages/@openmaic/storage/test/pg-document-contract-helpers.ts create mode 100644 packages/@openmaic/storage/test/pg-scene-revision.pg.test.ts create mode 100644 packages/@openmaic/storage/test/user-skill-store.test.ts create mode 100644 skills/agent-runtime/build-personal-skill/SKILL.md create mode 100644 skills/agent-runtime/curriculum-planner/SKILL.md create mode 100644 skills/agent-runtime/deep-interactive/SKILL.md create mode 100644 skills/agent-runtime/deep-interactive/outline-constraints.json create mode 100644 skills/agent-runtime/deep-research/SKILL.md create mode 100644 skills/agent-runtime/deep-research/outline-constraints.json create mode 100644 skills/agent-runtime/feynman-learning/SKILL.md create mode 100644 skills/agent-runtime/k12-core-literacy-planning/SKILL.md create mode 100644 skills/agent-runtime/k12-core-literacy-planning/references/core-literacy.md create mode 100644 skills/agent-runtime/k12-core-literacy-planning/references/subjects/humanities.md create mode 100644 skills/agent-runtime/k12-core-literacy-planning/references/subjects/languages.md create mode 100644 skills/agent-runtime/k12-core-literacy-planning/references/subjects/mathematics.md create mode 100644 skills/agent-runtime/k12-core-literacy-planning/references/subjects/science.md create mode 100644 skills/agent-runtime/learning-to-learn/SKILL.md create mode 100644 skills/agent-runtime/lecture-style/SKILL.md create mode 100644 skills/agent-runtime/lecture-style/outline-constraints.json create mode 100644 skills/agent-runtime/page-clone/SKILL.md create mode 100644 skills/agent-runtime/pptx-import/SKILL.md create mode 100644 skills/agent-runtime/pptx-import/outline-constraints.json create mode 100644 skills/agent-runtime/pro-editing/SKILL.md create mode 100644 skills/agent-runtime/pro-editing/outline-constraints.json create mode 100644 skills/agent-runtime/slide-craft/SKILL.md create mode 100644 skills/agent-runtime/slide-dsl/SKILL.md create mode 100644 skills/agent-runtime/social-emotional-learning/SKILL.md create mode 100644 skills/agent-runtime/spiral-curriculum/SKILL.md create mode 100644 skills/agent-runtime/stage-design/SKILL.md create mode 100644 skills/agent-runtime/stage-dsl/SKILL.md create mode 100644 skills/agent-runtime/stage-dsl/references/actions.md create mode 100644 skills/agent-runtime/stage-dsl/references/pbl.md create mode 100644 skills/agent-runtime/stage-dsl/references/quiz.md create mode 100644 skills/agent-runtime/stage-dsl/references/widget.md create mode 100644 skills/agent-runtime/style-clone/SKILL.md create mode 100644 skills/agent-runtime/style-clone/outline-constraints.json create mode 100644 skills/agent-runtime/teacher-style-clone/SKILL.md create mode 100644 skills/agent-runtime/teacher-style-clone/outline-constraints.json create mode 100644 skills/agent-runtime/understanding-by-design/SKILL.md create mode 100644 skills/agent-runtime/vocational/SKILL.md create mode 100644 skills/agent-runtime/vocational/outline-constraints.json create mode 100644 skills/agent-runtime/workshop-style/SKILL.md create mode 100644 skills/agent-runtime/workshop-style/outline-constraints.json create mode 100644 tests/agent-runtime/_fake-document-store.ts create mode 100644 tests/agent-runtime/_stage-fixtures.ts create mode 100644 tests/agent-runtime/agent-driver-model.test.ts create mode 100644 tests/agent-runtime/ask-user-claim-interleaving.test.ts create mode 100644 tests/agent-runtime/attempt-cap.test.ts create mode 100644 tests/agent-runtime/cancel-route.test.ts create mode 100644 tests/agent-runtime/course-outline-union.test.ts create mode 100644 tests/agent-runtime/course-stage.test.ts create mode 100644 tests/agent-runtime/create-skill.test.ts create mode 100644 tests/agent-runtime/curriculum-tools.test.ts create mode 100644 tests/agent-runtime/dsl-tools.test.ts create mode 100644 tests/agent-runtime/element-ref-message-adapter.test.ts create mode 100644 tests/agent-runtime/entry-tree-storage.test.ts create mode 100644 tests/agent-runtime/event-log-slim.test.ts create mode 100644 tests/agent-runtime/event-notify-bus.test.ts create mode 100644 tests/agent-runtime/event-notify.pg.test.ts create mode 100644 tests/agent-runtime/fetch-url-tool.test.ts create mode 100644 tests/agent-runtime/fetch-url.test.ts create mode 100644 tests/agent-runtime/folders-routes.test.ts create mode 100644 tests/agent-runtime/generate-image.test.ts create mode 100644 tests/agent-runtime/generate-media-force-off.test.ts create mode 100644 tests/agent-runtime/generate-video.test.ts create mode 100644 tests/agent-runtime/generation-content.test.ts create mode 100644 tests/agent-runtime/generation-media.test.ts create mode 100644 tests/agent-runtime/generation-tools.test.ts create mode 100644 tests/agent-runtime/import-pptx.test.ts create mode 100644 tests/agent-runtime/material-detail-route.test.ts create mode 100644 tests/agent-runtime/material-extraction.test.ts create mode 100644 tests/agent-runtime/material-tools.test.ts create mode 100644 tests/agent-runtime/materials-route.test.ts create mode 100644 tests/agent-runtime/messages-route.test.ts create mode 100644 tests/agent-runtime/owner-events-route.test.ts create mode 100644 tests/agent-runtime/owner.test.ts create mode 100644 tests/agent-runtime/park-attempt-budget.pg.test.ts create mode 100644 tests/agent-runtime/persistence-routes-gate.test.ts create mode 100644 tests/agent-runtime/personal-history-runner-wiring.test.ts create mode 100644 tests/agent-runtime/personal-history-tools.test.ts create mode 100644 tests/agent-runtime/resume.test.ts create mode 100644 tests/agent-runtime/roster-tools.test.ts create mode 100644 tests/agent-runtime/run-start.test.ts create mode 100644 tests/agent-runtime/runner-contract.test.ts create mode 100644 tests/agent-runtime/runner-event-order.test.ts create mode 100644 tests/agent-runtime/runner-skills-registration.test.ts create mode 100644 tests/agent-runtime/runner-tool-call-integrity.test.ts create mode 100644 tests/agent-runtime/runner-tool-timeout-cancel.test.ts create mode 100644 tests/agent-runtime/runner-voice-registration.test.ts create mode 100644 tests/agent-runtime/runner-wakeup.test.ts create mode 100644 tests/agent-runtime/runner-web-search-registration.test.ts create mode 100644 tests/agent-runtime/runtime-probe.test.ts create mode 100644 tests/agent-runtime/scene-tts.test.ts create mode 100644 tests/agent-runtime/session-detail-route.test.ts create mode 100644 tests/agent-runtime/session-events-live.pg.test.ts create mode 100644 tests/agent-runtime/session-events-route.test.ts create mode 100644 tests/agent-runtime/session-materials.test.ts create mode 100644 tests/agent-runtime/session-status-route.test.ts create mode 100644 tests/agent-runtime/session-urls.test.ts create mode 100644 tests/agent-runtime/sessions-route.test.ts create mode 100644 tests/agent-runtime/skill-detail-route.test.ts create mode 100644 tests/agent-runtime/skill-edit-tools.test.ts create mode 100644 tests/agent-runtime/skill-handle-inference.test.ts create mode 100644 tests/agent-runtime/skill-preload.test.ts create mode 100644 tests/agent-runtime/skills-route.test.ts create mode 100644 tests/agent-runtime/skills.test.ts create mode 100644 tests/agent-runtime/stage-detail-route.test.ts create mode 100644 tests/agent-runtime/stage-freshness-route.test.ts create mode 100644 tests/agent-runtime/stage-manifest-route.test.ts create mode 100644 tests/agent-runtime/stage-meta-routes.test.ts create mode 100644 tests/agent-runtime/stage-scenes-route.test.ts create mode 100644 tests/agent-runtime/stage-writer-registry.test.ts create mode 100644 tests/agent-runtime/stages-route.test.ts create mode 100644 tests/agent-runtime/tool-call-integrity.test.ts create mode 100644 tests/agent-runtime/tts-abort-timeout.test.ts create mode 100644 tests/agent-runtime/user-skills-runtime.test.ts create mode 100644 tests/agent-runtime/user-skills-validation.test.ts create mode 100644 tests/agent-runtime/voice-clone-tools.test.ts create mode 100644 tests/agent-runtime/web-search.test.ts create mode 100644 tests/audio/voice-catalog.test.ts delete mode 100644 tests/classroom/fetch-classroom-from-api.test.ts create mode 100644 tests/classroom/progressive-load-policy.test.ts delete mode 100644 tests/document/extract-source.test.ts delete mode 100644 tests/document/extraction-cache.test.ts delete mode 100644 tests/document/extraction-materialization.test.ts create mode 100644 tests/document/local-media-extractor.test.ts delete mode 100644 tests/document/material-library-manifest.test.ts delete mode 100644 tests/edit/agent-panel-visibility.test.ts create mode 100644 tests/edit/canvas-fit-scale-wiring.test.ts create mode 100644 tests/edit/contain-box.test.ts create mode 100644 tests/edit/edit-dock-chrome.test.ts create mode 100644 tests/edit/edit-dock-lifecycle.test.ts delete mode 100644 tests/edit/edit-tool-state.test.ts create mode 100644 tests/edit/element-ref-lasso.test.ts create mode 100644 tests/edit/insert-toolbar-float.test.ts create mode 100644 tests/edit/surfaces/slide/element-pick-layer-purposes.test.ts create mode 100644 tests/edit/visible-client-rect.test.ts delete mode 100644 tests/export/export-classroom-conversion.test.ts create mode 100644 tests/fixtures/fetch-url/chinese-article.html create mode 100644 tests/i18n/edit-chrome-keys.test.ts delete mode 100644 tests/lib/agent/client/agent-edit-session-types.test.ts delete mode 100644 tests/lib/agent/client/agent-history.test.ts delete mode 100644 tests/lib/agent/client/agent-thread-store.test.ts delete mode 100644 tests/lib/agent/client/apply-edit-elements.test.ts delete mode 100644 tests/lib/agent/client/apply-slide-content.test.ts delete mode 100644 tests/lib/agent/client/edit-elements-result.test.ts delete mode 100644 tests/lib/agent/client/merge-assistant-parts.test.ts delete mode 100644 tests/lib/agent/client/regen-snapshots.test.ts delete mode 100644 tests/lib/agent/client/serialize-thread.test.ts delete mode 100644 tests/lib/agent/client/thinking-timers.test.ts delete mode 100644 tests/lib/agent/client/to-pi-parts.test.ts delete mode 100644 tests/lib/agent/client/tool-card.test.ts delete mode 100644 tests/lib/agent/client/use-agent-runtime.test.ts create mode 100644 tests/lib/agent/runtime/agent-tool-timeout.test.ts delete mode 100644 tests/lib/agent/runtime/build-agent.test.ts delete mode 100644 tests/lib/agent/runtime/editor-transport-consumer.test.ts create mode 100644 tests/lib/agent/runtime/tool-timeout.test.ts delete mode 100644 tests/lib/agent/tools/build-image-resources.test.ts delete mode 100644 tests/lib/agent/tools/edit-elements-gate.test.ts delete mode 100644 tests/lib/agent/tools/edit-elements-patch.test.ts delete mode 100644 tests/lib/agent/tools/edit-elements.test.ts delete mode 100644 tests/lib/agent/tools/edit-interactive-html.test.ts delete mode 100644 tests/lib/agent/tools/read-scene-content.test.ts delete mode 100644 tests/lib/agent/tools/regenerate-scene-actions.test.ts delete mode 100644 tests/lib/agent/tools/regenerate-scene.test.ts delete mode 100644 tests/lib/agent/tools/registry.test.ts create mode 100644 tests/lib/brand/brand-config.test.ts create mode 100644 tests/lib/utils/iframe-element-picker.test.ts delete mode 100644 tests/materials/library.test.ts create mode 100644 tests/media/classroom-media-bytes.test.ts delete mode 100644 tests/media/convert-inline-image-assets-wiring.test.ts delete mode 100644 tests/media/convert-inline-image-assets.test.ts delete mode 100644 tests/media/convert-legacy-asset-refs-wiring.test.ts delete mode 100644 tests/media/convert-legacy-asset-refs.test.ts create mode 100644 tests/media/min-pixel-floor.test.ts create mode 100644 tests/media/proxy-media-cache.test.ts create mode 100644 tests/persistence/material-bytes.test.ts create mode 100644 tests/persistence/owner-materials.pg.test.ts create mode 100644 tests/persistence/owner-materials.test.ts create mode 100644 tests/persistence/stage-access-fidelity.test.ts create mode 100644 tests/scene-renderers/genui-logical-viewport.test.ts create mode 100644 tests/scene-renderers/interactive-iframe-picker.test.ts create mode 100644 tests/server/bounded-download.test.ts create mode 100644 tests/server/image-sizing.test.ts create mode 100644 tests/server/media-origin.test.ts create mode 100644 tests/server/skill-export.test.ts create mode 100644 tests/settings/skill-settings-locales.test.ts create mode 100644 tests/settings/skill-settings.test.ts create mode 100644 tests/store/sync-canvas-viewport.test.ts create mode 100644 tests/workbench/agent-end-gap.test.ts create mode 100644 tests/workbench/agent-skills.test.ts create mode 100644 tests/workbench/chat-gutter.test.ts create mode 100644 tests/workbench/chat-timeline.test.ts create mode 100644 tests/workbench/classroom-exit-wiring.test.ts create mode 100644 tests/workbench/classroom-exit.test.ts create mode 100644 tests/workbench/classroom-pane-edit-lock.test.ts create mode 100644 tests/workbench/composer-escape.test.ts create mode 100644 tests/workbench/composer-menus.test.ts create mode 100644 tests/workbench/composer-send-state.test.ts create mode 100644 tests/workbench/composer-skills.test.ts create mode 100644 tests/workbench/course-chat-bootstrap.test.ts create mode 100644 tests/workbench/course-discovery-sync.test.ts create mode 100644 tests/workbench/course-link.test.ts create mode 100644 tests/workbench/course-ref-send.test.ts create mode 100644 tests/workbench/course-refs.test.ts create mode 100644 tests/workbench/created-course-tabs.test.ts create mode 100644 tests/workbench/draft-conversation-reset.test.ts create mode 100644 tests/workbench/element-ref-owner-lifecycle.test.ts create mode 100644 tests/workbench/element-ref-send.test.ts create mode 100644 tests/workbench/element-refs.test.ts create mode 100644 tests/workbench/empty-state.test.ts create mode 100644 tests/workbench/entry-gate.test.ts create mode 100644 tests/workbench/entry-points-restore.test.ts create mode 100644 tests/workbench/entry-routes.test.ts create mode 100644 tests/workbench/existing-course.test.ts create mode 100644 tests/workbench/home-discovery-reload.test.ts create mode 100644 tests/workbench/launch-course-refs-client.test.ts create mode 100644 tests/workbench/launch-course-refs-receipt.test.ts create mode 100644 tests/workbench/material-client.test.ts create mode 100644 tests/workbench/material-upload-scheduling.test.ts create mode 100644 tests/workbench/owner-session-client.test.ts create mode 100644 tests/workbench/pg-mode-folder-listing.test.ts create mode 100644 tests/workbench/pg-mode-home-listing.test.ts create mode 100644 tests/workbench/pro-badge-switch.test.ts create mode 100644 tests/workbench/pro-home-data.test.ts create mode 100644 tests/workbench/pro-swap.test.ts create mode 100644 tests/workbench/question-card.test.ts create mode 100644 tests/workbench/question-form.test.ts create mode 100644 tests/workbench/replay-compact.test.ts create mode 100644 tests/workbench/run-courses.test.ts create mode 100644 tests/workbench/seed-slash-query.test.ts create mode 100644 tests/workbench/session-cancel-client.test.ts create mode 100644 tests/workbench/session-events-subscription.test.ts create mode 100644 tests/workbench/session-fold.test.ts create mode 100644 tests/workbench/session-title.test.ts create mode 100644 tests/workbench/skill-load-card-fold.test.ts create mode 100644 tests/workbench/stage-freshness-fetch.test.ts create mode 100644 tests/workbench/stage-freshness-sync.test.ts create mode 100644 tests/workbench/stage-rename-client.test.ts create mode 100644 tests/workbench/system-notice.test.ts create mode 100644 tests/workbench/thinking-bar-state.test.ts create mode 100644 tests/workbench/thinking-stream-seam.test.ts create mode 100644 tests/workbench/tool-card.test.ts create mode 100644 tests/workbench/tool-group-state.test.ts create mode 100644 tests/workbench/tool-presentation.test.ts create mode 100644 tests/workbench/tool-progress.test.ts create mode 100644 tests/workbench/tts-stage-sync.test.ts create mode 100644 tests/workbench/use-tree-drag.test.ts create mode 100644 tests/workbench/workbench-i18n.test.ts create mode 100644 tests/workbench/workspace-course-chat-bootstrap.test.ts create mode 100644 tests/workbench/workspace-course-persistence.test.ts create mode 100644 tests/workbench/workspace-course-tabs.test.ts create mode 100644 tests/workbench/workspace-folder-seam.test.ts create mode 100644 tests/workbench/workspace-navigation.test.ts create mode 100644 tests/workbench/workspace-order.test.ts create mode 100644 tests/workbench/workspace-paging.test.ts create mode 100644 tests/workbench/workspace-pane-folds.test.ts create mode 100644 tests/workbench/workspace-pane-head-alignment.test.ts create mode 100644 tests/workbench/workspace-pane-navigation.test.ts create mode 100644 tests/workbench/workspace-panes.test.ts create mode 100644 tests/workbench/workspace-rail-overflow.test.ts create mode 100644 tests/workbench/workspace-rail-session-rename.test.ts create mode 100644 tests/workbench/workspace-rail-tab.test.ts create mode 100644 tests/workbench/workspace-session-memory.test.ts create mode 100644 tests/workbench/workspace-transient-sidebar.test.ts create mode 100644 tests/workbench/workspace-tree.test.ts create mode 100644 types/web-extraction-vendors.d.ts create mode 100644 types/web-speech.d.ts 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 @@ 一键生成沉浸式多智能体互动课堂。

+

+ v1.0.0 体验指南(中文) +    + v1.0.0 User Guide (English) +

+

Paper License: MIT 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

+

+ v1.0.0 User Guide (English) +    + v1.0.0 体验指南(中文) +

+

Paper License: MIT @@ -21,7 +27,7 @@
Discord   - Feishu + Feishu Community
Next.js React @@ -31,14 +37,27 @@

- English | 简体中文 + English | Simplified Chinese
Live Demo · Quick Start · Lemonade · FunASR · Features · Use Cases · OpenClaw

+## 🎉 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({
); } + +function StageViewport({ + workbench, + interactive, + className, + onClick, + children, +}: { + readonly workbench: boolean; + readonly interactive: boolean; + readonly className?: string; + readonly onClick?: (event: React.MouseEvent) => void; + readonly children: ReactNode; +}) { + if (interactive) { + return ( +
+ {children} +
+ ); + } + if (!workbench) { + return ( +
+ {children} +
+ ); + } + return ( + +
+ {children} +
+
+ ); +} 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 ( + + +
+ {loading || (variant === 'pane' && !error && loadedClassroomId !== classroomId) ? ( +
+
+ +

{t('common.loadingClassroom')}

+
+
+ ) : 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 && ( -
{ + const slot = discussionPresent ? actions.length - 1 : actions.length; + setPickerAt({ slot, rect: e.currentTarget.getBoundingClientRect() }); + }} + className="ml-1.5 inline-flex shrink-0 items-center gap-1 rounded-full border border-primary/25 bg-primary/10 px-2.5 py-0.5 text-[11px] font-medium text-primary transition-colors hover:bg-primary/15" > -
-
+ + {t('edit.timeline.addAction')} + + )} -
+ {!lineMode && ttsActive && ( + )} - {!lineMode && ( + + {t('edit.timeline.counts', { speech: speechCount, cue: cueCount })} + + {/* pan the timeline viewport left/right */} + {!lineMode && ( +
- )} - - {!lineMode && ttsActive && ( - )} - - - {t('edit.timeline.counts', { speech: speechCount, cue: cueCount })} - - {/* pan the timeline viewport left/right */} - {!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 ( - - - - - - - - - - -
-

- {t(emptyTitleKey)} -

-

- {t(emptyLeadKey)} -

-
- {capabilityKeys.map(({ label, examples }) => ( -
- {t(label)} - - {t(examples)} - -
- ))} -
-

- {t(emptyBoundaryKey)} -

-

- - {t('edit.agent.empty.comingSoon')} -

-
-
- - -
- - - - - -
- {!canSend ? ( -

- {unsupportedMessage} -

- ) : null} - - {scene?.title ? ( -
- - - {scene.title} - -
- ) : null} - -
-
- - - - - - - - - -
-
-
-
-
-
- ); - } - - // 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 `