THU-MAIC/OpenMAIC v1.4.0

OpenMAIC v1.4.0 — Project-based learning PBL v3

on GitHub

1.4.0 is about project-based learning: PBL v3 is a new way into vibe coding where learners build the project and come away understanding how it works. Concepts become hands-on tasks that the learner gets running, an AI tutor works through requirements, design and implementation with them, each milestone gives feedback and the finished project a personal learning report, and work and progress are kept for the next visit. PBL v3 runs on a new shared sandbox and stays off until a sandbox provider is configured; no new setting is required otherwise. The upgrade is one-way; read Breaking Changes before upgrading.

Breaking Changes

• The upgrade is one-way: stop every 1.3.x instance first, and plan rollback as a database restore. @openmaic/storage 0.39.2 adds asset migration v4 (retained document assets). A 1.4.0 instance applies it when persistence starts: on the first request or, at the latest, on its first schema check about 30 s after boot. #1979 #2151
  • Once v4 is applied, an older release refuses to start against the database (SchemaVersionAheadError). Roll back by restoring the previous database state, not by restarting the old version.
  • 1.3.x checks the schema only at startup, so an instance already running does not exit when 1.4.0 migrates the database. It keeps serving until its next restart, which is refused, and its classroom saves delete the retained references 1.4.0 records. Do not run the two side by side.
  • v4 replaces the check constraint on document_asset_refs. ADD CONSTRAINT validates every row under an exclusive lock, so reads and writes of that table wait until it finishes. Allow for this on large tables.
  • A host that provisions ASSET_PG_SCHEMA through its own migrations must first apply v4: document_asset_refs_scope_check becomes CHECK (scope IN ('stage', 'scene', 'retained')). ASSET_PG_SCHEMA itself does not include this; it is in ASSET_PG_MIGRATIONS.
  • Upgrading directly from 1.3.0 also carries the conditions of 1.3.1.
• From 1.4.0 on, older replicas exit when a newer release migrates the database. Every Node server now checks the recorded schema versions about every 30 s. When the database is newer than it knows, the server drains for up to 30 s and exits with code 1, and a restart of that version is refused at boot. A later mixed-version rolling deployment will see its old replicas exit shortly after the first new one migrates, so plan rollouts around it. This monitor does not exist in 1.3.x, so it first applies to upgrades from 1.4.0 onward. #2151
• Databases that ran a pre-release integration/shared-sandbox build need repair. Those builds recorded asset v2 as retained-document-assets, while this release has material_roots as v2 and the retained assets as v4. Repair the migration records or recreate the database. Databases upgraded from a released version are not affected. #2151
• Qwen voice cloning: authorize the new CosyVoice target before upgrading. Managed deployments must add cosyvoice-v3.5-plus (or their configured clone target) alongside qwen3-tts-flash in the provider model allowlist in TTS_QWEN_MODELS or openmaic.yml. For example, use TTS_QWEN_MODELS=qwen3-tts-flash,cosyvoice-v3.5-plus: setting only the clone target replaces the implicit catalog-model authorization and makes catalog voices return HTTP 403. An allowlist containing only the retired qwen3-tts-vc-2026-01-22 does not authorize the new target and will return HTTP 403. Normalizing the old target override does not change the allowlist. Existing incompatible voices must also be cloned again from suitable reference audio. #1941

Behavior Changes

• Host hooks: beforeAssetAllocate now also runs for PBL package installs (POST /api/pbl/v3/packages). That endpoint is deliberately not gated on sandbox access, because classroom import and export depend on it: a caller without sandbox access can still store a validated package under their asset quota, and a host can refuse this through the hook. #2158
• Classroom export: a runnable PBL v3 course exports as .maic.zip format version 2 with its project embedded, and older installations reject that archive before writing anything. Ordinary and PBL v1/v2 classrooms stay on format version 1. #1979 (by @cosarah)
• Agent tools: image, speech, video, web search and web fetch tools are offered only when their capability is usable, and the prompt describes only the tools offered. #2118 #2040 #2102 (by @bhushan4work)
• Classroom chat: a Native child turn is no longer cut off by the fixed 5-request and 60-second caps, so multi-step tasks such as complex whiteboard work can finish. Per-request timeouts and cancellation still apply. See Known issues. #2017 #2006 (by @bhushan4work)
• Classroom: a course with its own roster always shows that roster. A preset chosen on the home page no longer overrides it; the preset is kept for generation and for courses without a roster. #2136

Features

• Project-based learning PBL v3. Runnable programming projects open in the normal classroom with an IDE, a terminal and four AI teaching roles. #1951 #1963 #1964 #1988 #2003 #2142 (by @Irisdai517)
  • Learn by doing. Each milestone goes through teaching, decisions, a plan, code, tests, a quiz and a recap, with the learner editing and running real code in a hosted workspace. Declared applications open in the workbench beside the IDE. #2060 #2069 #2090 (by @Irisdai517)
  • AI tutor throughout. The tutor discusses requirements, reviews the plan and the code with the learner, and answers questions at any point. #2044 #2073 #2107 (by @Irisdai517)
  • Staged feedback. Tests and quizzes give feedback at each milestone, and a finished project gets a personal learning report built from what actually happened, with shareable achievement images. #2106 #2131 (by @Irisdai517)
  • Progress is kept. Learning progress lives in PostgreSQL and workspaces are checkpointed, with periodic backups of newer edits, even while an application runs. Idle compute is released after 30 minutes by default (OPENMAIC_PBL_IDLE_TIMEOUT_MS) and the workspace is restored on return. #2011 #2052 (by @cosarah) #2055 (by @Irisdai517) #2160
  • Portable projects. A .maic.zip carries the project, so a course runs on another installation. #1979 (by @cosarah)
  • How to enable. It stays off without a sandbox provider: /pbl-v3 returns 404 and no sandbox is allocated. It needs PostgreSQL, OPENMAIC_AGENT_RUNTIME_ENABLED=true with an agent model, a sandbox section in openmaic.yml whose template includes Python 3, and durable checkpoint storage (S3 or a compatible byte store). Users need explicit single-user mode or the sandbox:use permission. Learner applications also need the preview gateway (pnpm sandbox:preview). Then open /pbl-v3 and choose the Python or Java sample, or import a package. See the PBL v3 guide.
• Shared sandbox (experimental). An E2B-compatible provider gives Agent sessions and PBL owner-scoped files, commands and terminals, with durable checkpoints, an isolated HTTP/WebSocket preview gateway and per-owner and installation limits. Installation administrators manage it under Settings → Sandbox, and lock: [sandbox] makes that page read-only. See the sandbox README. #1922 (by @Irisdai517)
• Audio: add Xiaomi MiMo TTS (mimo-v2.5-tts) and ASR (mimo-v2.5-asr) providers, configured with TTS_XIAOMI_* and ASR_XIAOMI_*. #1976 (by @AbelWangYaBo, based on #1432 by @Jamartin-create)

Bug Fixes

• PBL v3: a standalone preview stays usable through plan and code approval, formal tests and quiz entry. Access renews while the page is open, within the sandbox lease; slow startup no longer holds the learning lock; and formal tests for these projects run on a private source copy verified against the captured digest. #2163 (by @Irisdai517)
• Provider errors: an explicit insufficient_balance_error now counts as a quota refusal, so a configured model fallback takes over. #2163 (by @Irisdai517)
• Qwen voice cloning: migrate enrollment and synthesis to CosyVoice (cosyvoice-v3.5-plus by default, Beijing DashScope). Saved voices stay visible; incompatible voices require re-uploading a suitable reference recording and re-cloning, with no automatic sample migration. Managed deployments must authorize the new target alongside qwen3-tts-flash in TTS_QWEN_MODELS or openmaic.yml. An empty or exact retired TTS_QWEN_VOICE_CLONE_MODEL=qwen3-tts-vc-2026-01-22 value selects the default; other overrides remain unchanged. #1941 #1949 (by @YizukiAme)
• Classroom playback resumes the remaining reading time after a narration clip fails to play, instead of getting stuck on the failed audio element. Failed clips release their playback state without interrupting a newer narration line. Pausing while a clip is still loading does not discard that narration; resume plays it. #2109 #2110 (by @Duang777)
• Text to speech: a provider timeout no longer tells the agent to retry the same call, which caused retry loops on slow self-hosted TTS. The message now suggests splitting the text or raising TTS_REQUEST_TIMEOUT_MS, which is now documented. #2149 #2116 (by @Cham1229)
• Generation: a [ inside a string before the "outlines" key (such as E[X]) no longer makes the outline parser find nothing and pause the run on the step timeout. #2133 #2132 (by @maxmalkin)
• Workbench: when several first pages are ready at the same moment, the request preview opens a tab for each course and only the first takes focus. #2075 #2070 (by @bhushan4work)
• Editor: imported shape labels keep their insets through editing and saving in the legacy Pro editor, so labels no longer shift between playback and editing. #2024 #1956 (by @hichipli)
• PBL v2: shortening learner text for evaluator prompts no longer cuts an emoji in half. #2124 #2147 (by @kevin9327)
• Settings: usage totals just under a unit boundary show in the next unit (1.00M tokens, not 1000.0K tokens). #2126 (by @kevin9327)

Packages

• @openmaic/dsl 0.13.0 (was 0.12.0) and @openmaic/storage 0.39.2 (was 0.39.1). Other packages are unchanged from 1.3.1.

Known issues

• PBL v3 runs the installed samples and imported packages. Generating a PBL v3 project is not available yet; generated PBL scenes stay on the existing runtime.
• New sandbox and PBL strings are mostly English in non-Chinese locales (about three quarters of the new keys), and about a third are English in zh-TW.
• Workspace backups have limits. An application that constantly writes archived files never gets a periodic copy, and application-only writes after a backup wait for the next edit, launch or idle release. Retired archives count toward the owner's checkpoint quota for at least an hour, so large workspaces edited continuously can reach it. #2160
• Previews are refused on a domain sharing the application's registrable domain. OPENMAIC_SANDBOX_PREVIEW_ALLOW_SAME_SITE=true lifts this for deployments that have no other option, at a risk: same-site previews can write parent-domain cookies and send same-site requests to the application. It is off by default and same-origin previews stay refused. #2098
• A Director still has nothing that stops it retrying a child that keeps failing, and with #2017 a Native child has no per-turn deadline or request cap either. The request keeps calling the model until it is cancelled. #2122
• 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.
• 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

• Agent: upgrade Pi to 0.80.3; no configuration change. #1950 (by @Irisdai517)