THU-MAIC/OpenMAIC v1.3.0

OpenMAIC v1.3.0 — Knowledge base and Pro workbench upgrade

on GitHub

1.3.0 has two themes. The knowledge base shipped in the release candidate (see 1.3.0-rc.1): every upload stays in its owner's knowledge base until it is deleted, is organized in folders and parsed once, and the composer and the agent can use it. The Pro workbench upgrade is new in this release: a request shows a preview of the agent's work before the first page exists, and classroom tabs switch between Learn and Edit. These notes collect what is new in 1.3.0 beyond 1.3.0-rc.1. Coming from 1.2.x:

• Read Breaking Changes under 1.3.0-rc.1: the built-in Veo video provider is removed, and the knowledge base sets release conditions.
  • Stop every old instance before this version accepts writes; do not run a mixed-version rolling deployment, and finish the rollout well within ASSET_COLLECTION_GRACE_MS.
  • Do not roll back below this release.
  • Set MATERIALS_POOL_BACKFILL=1 only after every old instance has stopped, then restart.
  • A host that provisions ASSET_PG_SCHEMA, AGENT_SESSION_PG_SCHEMA or AGENT_SESSION_MATERIAL_PG_SCHEMA through its own migrations must first add the tables and columns listed under Material library upgrade reference in that section.
• Coming from 1.2.0, also read the breaking change under 1.2.1: classroom chat always runs on Pi and needs a Classroom model with tool calling.
• Upgrade the render-service image together with the app: it now runs tini as PID 1, which keeps long-running preview containers from failing every browser launch.
• Agent narration calls are now queued one at a time per provider connection (see Behavior Changes).

Highlights

• Pro workbench upgrade. On deployments with the Pro workbench (NEXT_PUBLIC_PRO_WORKBENCH_ENABLED). Classic mode, the classic home page and the Pro entry point are unchanged. #2066
  • Request preview. Until a conversation's first page exists, a tab in the right pane shows what the agent is doing (understanding the request, researching, asking a question, assembling the roster with the classic agent reveal, generating), then hands off to the course in Learn mode. Questions from the agent are answered inside the preview. The tab opens on a request's first tool call or question, never for a talk-only turn, and rests with "the course will appear here" when a request ends without a page. The preview now opens the course even when a course read started before the first page landed answers after the run has finished; previously it could stay on "Opening the classroom" until the course card was clicked. #2053 #2077
  • Learn and Edit in classroom tabs. A classroom tab switches between learning and editing, remembered per course in this browser; editing is unavailable while a classic run is still generating the course. #1996
  • Course-building guidance. A plain-language request for a new course reads the stage-design skill without a / command. The agent still confirms its plan (unless the user already said to go ahead or the request is fully specified) and synthesizes narration right after each page. #1982
• Knowledge-base follow-ups since rc.1 (details under Bug Fixes).
  • Images from MinerU gateways that return image URLs are downloaded and kept with the extraction, and the extracted text points to the stored figures instead of the provider's links, which can expire. #2076 #2078 #2079 #2080
  • A PDF refused for too many pages shows "Too many pages" with the page count and the limit, instead of a generic parse failure. #2085
  • A conversation whose personal Skill was deleted continues with the next message instead of failing, keeping its course and history. #2086
• Agent page previews work again. render_scene_preview sends the render service a self-contained page, so pages with media or hosted interactive libraries render again, and the agent sees the render service's reason when it refuses a page. The render-service image runs tini as PID 1 so exited Chromium processes are reaped, and failed previews log a fixed error code. #2082 #2036 #2038
• Homepage on phones. The homepage and its dialogs adapt to phones: a compact composer and course-options dialog, a searchable library drawer, and touch-friendly course and folder actions, sharing form, upload, generation and library state with desktop. #2005 (by @xuyuanwei678)

Behavior Changes

• Agent: generate_tts calls are limited per provider connection (one managed connection, or one provider, base URL and key), one at a time by default, so parallel calls no longer run into the provider's rate limits. Set OPENMAIC_AGENT_TTS_CONCURRENCY to a positive integer to allow more; the limit is per process. Failed lines are retried like classroom narration and reported with their reason. #1983 #1975 (by @Frank-zhu2000)
• Whiteboard: the Native teacher agent's wb_draw_shape draws every shape from an SVG path and viewBox, with rotation, transparent fill and optional stroke; the rectangle, circle and triangle presets and the shape field are removed from the tool. Stored shapes and Legacy preset playback are unchanged. #1965 #1853 (by @cosarah)

Features

• @openmaic/generation exports renderScenePrompt('slide-content', { imageElementEnabled, generatedImageEnabled, generatedVideoEnabled }), which returns the slide content system prompt without running generation. Slide generation builds its system prompt through the same code, so the two cannot drift. @openmaic/generation 0.3.26. #2010
• Google TTS: add Gemini 3.8 Flash-Lite (the new default) and Flash TTS ahead of the preview models' retirement. Preserve complete WAV responses instead of wrapping them in a second header; retain PCM conversion and explicit model selections. #2035 #2033 (by @YizukiAme)
• Interactive scenes: <audio> and <video> in the current interactive page are coordinated with narration, in the classroom and the standalone HTML player. Playing page media pauses narration, and starting or resuming narration pauses the page's media. WebAudio and nested or external documents are not covered. #1921 #1846 (by @Ethereal49)
• Render service: every 5xx /preview log line carries a fixed errorCode (deadline_exceeded, chromium_unconfigured, browser_launch_failed, browser_crashed, browser_timeout, scene_not_found, empty_image, resource_mode_unsupported or internal) and is written at ERROR; the message itself is not logged. HTTP responses are unchanged. #2038

Bug Fixes

• Workbench: the first switch from Learn to Edit no longer waits for the editor to download. The classroom pane loads the editor while the browser is idle (or when the pointer or focus reaches Edit) on courses you can edit, and the switch no longer waits for the font picker's stylesheets, which load in the background. A slide set in a picker font may briefly show the fallback face before it swaps in. #2074
• Workbench: opening /workspace no longer shows a blank page for a moment after the server-rendered page has painted. #2058
• Workbench: switching conversations while a request is in flight no longer lets that request change the active conversation. A late session creation, send failure, upload or STOP stays with the conversation it came from, and the composer of the newly opened conversation waits until that conversation is attached before it sends, so a quick send can no longer reach the previous conversation. #2054 #2057
• Workbench: Backspace in a partly typed /skill handle deletes one character; only a handle that names an installed skill is deleted as a whole. #2061 #2042 (by @Frank-zhu2000)
• Providers: a DeepSeek thinking model behind an OpenAI-compatible provider the catalog does not know rejected the follow-up to a leading /skill handle with "The reasoning_content in the thinking mode must be passed back to the API". The request is now sent again once with an empty reasoning_content on the tool-call turns that lack it; requests to other providers are unchanged. #2068 #2041 (with @bhushan4work)
• Agent: a conversation whose personal Skill has been deleted recovers on the next message. The stale binding is removed only after confirming the Skill belonged to the session owner, the course and history stay, and a replayed turn cannot pick up a new Skill of the same name. @openmaic/storage 0.38.1, no schema change. #2086 #2083 (by @sophietao20-star)
• Agent page preview (render_scene_preview) works again on pages with media or hosted interactive libraries. The tool now sends the render service a self-contained copy of the page: the session owner's course assets become data: URLs, the deployment-hosted interactive libraries (Tailwind, Chart.js, KaTeX, Three.js) are inlined from the app's own files, and media it cannot inline (remote URLs, missing assets, or bytes past a 24 MiB request budget) are drawn as a labeled placeholder and listed for the agent. The stored course is not changed. When the render service refuses a page, the agent now sees its reason instead of only the HTTP status. #2082
• Render service: the container ran Node as PID 1, which does not reap exited processes, so every Chromium launch left zombie processes behind until the container hit its pid limit and every launch failed (Failed to launch the browser process: Code: 133). The image now runs tini as PID 1. #2036
• Agent: course tools are easier to address and read. patch_stage validates only the elements and fields a patch changes, so older stored data no longer blocks unrelated edits, and its errors name the exact property; read_stage returns pointers that work as-is with set and str_replace; render_scene_preview accepts a page order or a /scenes/… path; and narration results report the voice used and where it came from. The system prompt and the course skills ask the agent to describe results in terms of the course instead of internal identifiers, claim only what tool results show and carry a request through to the end. #2000 #1999 #1998
• Agent: the system prompt no longer lists the attached materials, so attaching a material or finishing its extraction no longer invalidates the provider's prompt cache for the rest of the conversation. list_materials and the attachment note still tell the agent what is attached. #2027 #1858 (by @Frank-zhu2000)
• MinerU gateways that return image URLs instead of base64: slide images taken from a PDF's figures were stored as a few bytes of garbage, because the parser wrapped each URL as a base64 data URL and the server decoded it. The parser now keeps the URL, and the server downloads the image when it stores the extraction (uploaded materials and the knowledge base) under the provider-result URL policy (HTTPS and public addresses only) with per-image, total-size and time limits. An image that cannot be downloaded is left out and counted (imagesSkipped) without failing the extraction. A stored extraction that still holds image URLs is not reused for a new upload of the same file, and a course generated from it downloads the images then. Base64 decoding of extracted images and provider data URLs now refuses a payload that is not base64. #2076
• MinerU extracted images: a self-hosted MinerU that returns JPEG 2000 images (a boxed JP2 file or a raw codestream) as bare base64 now has them stored with the extraction instead of dropped as neither bytes nor a URL (the prebuilt image library cannot decode JPEG 2000, so knowledge-base images and vision input still leave them out), and each bare base64 image is now labelled with its real type (image/jpeg, image/jp2, ...) instead of always image/png. A ready extraction that left images out only because of a limit (the image count, the stored result's size, an image too large) is now reused for a new upload of the same file, because those images would be left out again; only an extraction with images that failed to download, answered something other than an image (often a temporary sign-in, firewall or rate-limit page), timed out or ran out of time is extracted again. Extractions stored by earlier versions are not reused when they left out any image, as before. The knowledge base keeps its cache entry in the same cases. #2079 #2080
• Knowledge base: a MinerU gateway that hosts images names them by URL in its markdown (![](https://…), <img src="https://…">). Those references now point to the stored figure, as images/<file> references already did, instead of the provider's link, which can expire. Other external image links in the text are left as written. #2078
• Knowledge base: a PDF that a MinerU gateway refuses for its page count (pdf_too_many_pages) now shows "Too many pages" and explains it, with the page count and the limit when the gateway states them, instead of a generic parse failure. The refusal is not retried and not handed to another parser, and Parse again is no longer the first action for it. Other self-hosted MinerU errors are reported by status only (MinerU API error (500)), whether the deployment or the caller configured the service: the parse response and stored extraction errors never include the service's response body, which goes to the server log only. Error bodies are read only up to 64 KB. #2085 #2087
• MinerU: table and display-equation crops keep their page number, size and (for tables) caption, instead of all reading as page 0 without a description. #2002
• Knowledge base: the picker shows why a material failed and the media-duration limit, material tool errors follow the run's interface language, conversation-only sources no longer suggest a missing "Parse again" control, and the course rail's move-out hint appears only when a course is carried out of a folder. #1923
• A slide image whose box has a different shape from the image is now fitted inside the box the model laid out, centered, like object-fit: contain. Previously the box kept its width and changed its height, so a box flatter than its image grew downward and covered the text below it. Boxes within 10% of the image's ratio, and images with unknown dimensions, are unchanged. @openmaic/generation 0.3.25. #2004
• Narration: generated speech is prompted to keep Greek letters and named constants as symbols, because that text is also the caption (classroom, standalone HTML player, and narration export). Write π, not the homophone 派, and the same for θ, α, β, λ, ω, Σ, and the constant e. @openmaic/generation 0.3.28. #2021 #1906 (by @Frank-zhu2000)
• Ark Agent Plan chat models resolve catalog metadata again, so reference images, context windows and max output are no longer dropped. The request still sends the plan's own model id. Ids that match an existing row reuse it (deepseek-v4-pro, glm-5.3, kimi-k3, kimi-k2.7-code, and Coding Plan k3). Seed 2.1 Pro, Seed 2.1 Lite, Seed 2.0 Mini, deepseek-v4-flash, minimax-m3, kimi-k2.8-preview and ark-code-latest resolve for the Agent Plan and stay off the dated Doubao preset; ark-code-latest is a router with tool calling, no image input and no single window. kimi-k2.8-preview omits max output because that documented ceiling equals the context window and callers send it as max_tokens. Kimi Coding Plan ids stay off the open-platform Kimi preset. The rest of MiniMax's M2 chat ids and TokenDance's own model ids resolve model info as well. #2022 #1947 #1942 (by @Frank-zhu2000)
• Speech recognition: OpenAI-compatible transcription models that reject verbose_json now receive plain JSON requests. Qwen3 ASR recordings are uploaded as WAV from both the composer and the settings preview, with a matching multipart filename. Known OpenAI transcription models retain their existing SDK path and provider requests retain the guarded transport. #2032 (by @xuyuanwei678)
• Speech: new users' speech languages follow the interface. An unset cloud transcription language uses automatic detection when the provider supports it, browser recognition uses the interface language, and browser speech keeps the interface's Chinese region (zh-TW under Traditional Chinese) for previews, narration and discussion replies. Saved languages and explicitly selected voices keep their priority. #1935 #1548 (by @VictorMaxWang)
• Export: a slide formula with an upright symbol (\Delta, \mathrm{…}, a literal Δ) no longer makes the exported PPTX unreadable in PowerPoint. #1987 #1986 (by @vincentke1117)
• Editor: the legacy canvas editor keeps inline formulas as formulas when the text around them is edited, instead of flattening them to plain text on save; they still show their LaTeX source while editing there. #2018 #1868 (by @Frank-zhu2000)
• Editor: a page whose narration is cached in the browser no longer flashes the missing-narration marker on its thumbnail while the cache is checked. #1985 (by @Oliveryfaso)
• Playback: a stored whiteboard action that is rejected (for example an unsupported shape) is logged and skipped, in playback and when seeking, so later actions still run and playback can finish instead of freezing. #2014 #2013 (by @cosarah)
• Whiteboard: clicking or panning empty canvas clears selected text or code. #2025 #2023 (by @hichipli)

Packages

• @openmaic/generation 0.3.28 (was 0.3.24; 0.3.25–0.3.27 were published along the way) and @openmaic/storage 0.38.1 (was 0.38.0). Unchanged from rc.1: @openmaic/dsl 0.12.0, @openmaic/renderer 0.2.0, @openmaic/editor 0.0.12, @openmaic/geometry 0.1.0 and @openmaic/importer 0.3.1.

Known issues

• Qwen voice cloning still calls a retired model, so registering or synthesizing a cloned voice fails. The move to CosyVoice is in review in #1949. #1941
• Course issues ship their first phase only: thumbnail markers, all at warning level. An issues list and a single "Fix with agent" entry point are planned in #1900.
• On deployments protected by ACCESS_CODE, the composer's attach button, drag-and-drop and image paste can stay unavailable after the access code is entered on a fresh page load, until the page is reloaded. A fix is in review in #1974.
• The workbench agent is offered generate_tts and generate_image even when the deployment has no usable speech or image provider; the calls fail when made. #2040
• When one request creates several courses and their first pages are ready at the same moment, the request preview can open a tab for only one of them. #2070
• If an agent run is interrupted right after a page is saved but before the tool result is recorded, continuing the conversation regenerates that page. #2020

Other Changes

• Tests and CI: the required check runs as parallel jobs with a cached package build, merge-queue entries run CI, the main image is built on pull requests only when its inputs change, end-to-end builds no longer reuse an older commit's Next.js cache, a weekly flaky-test report and reminders for pull requests stuck on conflicts or approval are added, and several slow or racy suites are stabilized. #2046 #2045 #2047 #2051 #2049 #2048 #1994 #2043 #2050 #2056 #2072 #2081
• Packages are published to npm through trusted publishing (OIDC) instead of a long-lived NPM_TOKEN. #2063
• Docs: AGENTS.md sets out the automated review rules, and CONTRIBUTING.md gains a Review Threads section. #2039

Upgrading from 1.2.x? The full knowledge-base storage and schema reference is in the 1.3.0-rc.1 release notes and CHANGELOG.md.