An ACP agent reports its models when a session opens, which is the only
answer that reflects the user's own account — the same reason Studio asks
Codex over its app-server rather than filtering a catalog. The existing
rules are unchanged from there: models.dev supplies prices, the harness
owns what each model accepts, and cheapest still wins by default.
ACP has no separate effort knob. The Codex adapter writes the level into
the id (gpt-5.6-sol[high]), so those are folded into one model that
offers levels instead of six models that differ by one word, and the
chosen level is written back the same way via session/set_model. An agent
with plain ids simply has no levels, which is already how Claude Code is
treated.
Asking now needs the whole harness rather than its kind: two ACP adapters
are both "custom" and are two different answers, so the model list, the
default model and the default effort all take how the agent is started.
Verified against @agentclientprotocol/codex-acp: four models with their
real level lists, the account's own default marked, set_model accepted.
Over ACP an agent can ask permission before it writes or runs something.
A run that asks parks as `awaiting-permission` carrying the agent's own
question and its own options, keeps holding its element, and resumes the
moment the answer is forwarded. Studio only ever forwards an option the
agent itself offered; anything else is refused with a 409.
The wait is bounded, because a run that has stopped to ask is holding an
element while it does. Running out never means yes: the agent's own
refusal is used when it offered one, and the run fails naming the tool
when it did not.
Real agents ask about a tool call by id and put the title in the update
that announced it, so titles are remembered and the question is shown in
the agent's words rather than as "exec-282be8b3".
Both transports now share one cleanup path instead of two copies.
Verified against @agentclientprotocol/codex-acp in read-only mode: the
agent asked, the question parsed with its refusal option, answering
"Allow Once" ended the turn and the file was edited.
A preset that declares `transport: "acp"` is driven by the protocol
instead of by parsing stdout: the session id comes from `session/new`,
the activity line and the answer come from `session/update`, and the turn
ends with a stop reason rather than an exit code that has to be guessed
at. Everything downstream is unchanged — the same overlay contract, the
same activity shape, the same run log — because it is the same product
behaviour over a different wire. The native path is untouched.
An agent that fails answers with something as terse as "Internal error"
and explains itself on stderr, so stderr is kept and the last line of it
is what the run reports.
Verified against @agentclientprotocol/codex-acp: a real edit ran with
live activity, changed the file, and logged a well-formed line.
Studio's existing transport spawns a CLI and reads whatever it prints, so
every harness needs its own parser and an agent that wants to ask a
question has nobody to ask. ACP is the published standard for this
boundary: JSON-RPC over stdio, capabilities negotiated up front.
This is the connection half only: open a stream, complete the handshake,
clean the process up. A dead agent reports its exit code rather than the
transport's bare "connection closed", and a silent one fails on a
deadline naming the command instead of hanging.
Verified against @agentclientprotocol/codex-acp: the handshake returns
protocolVersion 1, loadSession, and three auth methods.
Effort levels come from the same catalog the models do — a model advertises
what it accepts, and Studio offers exactly that. Anthropic reasons on a token
budget rather than a level, so a Claude Code run carries no effort at all
instead of a knob that does nothing.
The chip sits to the right of the model, because it is the same decision: how
much thinking to buy. A run takes the lowest level the model offers unless the
user picks otherwise, the choice is remembered per harness, and each run in the
tray shows the effort it actually used.
Also drops the OS tooltips from the harness and model chips — they covered the
element they described — and portals the composer and ask handle out of the
canvas overlay. That overlay is a z-10 stacking context whose sibling motion
path sits at z-40, so nothing inside it could ever come out on top, however
high its own z-index was; the keyframe diamonds kept drawing through the pill.
The model was buried at the bottom of the harness menu, where it read as a
detail of the harness rather than the other half of "who will do this". It is
now its own chip to the right of the harness, with its own list.
Harnesses are no longer limited to the four Studio ships presets for: the
picker can register one, with the same fields a preset carries — command, args
before the stdin prompt, its own mark, and the flag it takes a model on. They
live in <project>/.hyperframes/agents.json, so the choice travels with the work
instead of being an environment variable one machine knows about.
Harness selection is by id now rather than kind, since two custom harnesses can
share the "custom" kind.
The selection route validated its payload with ~75 lines of isRecord /
hasString / isFiniteNumber helpers sitting next to a hand-written interface
describing the same shape — two definitions that could drift, and the pattern
the agent routes were copied from. Both are now one zod schema with the public
types inferred from it, so the validator and the type cannot disagree. The
Google Fonts metadata parse follows.
Net -115 lines, same behaviour: the existing selection route tests pass
unchanged.
Models come from the models.dev catalog — the same community index other agent
tools read — filtered to the provider each harness authenticates against and to
models that can actually call tools. Nothing about a model is hardcoded here: a
model released next week shows up without a change to Studio, and the catalog's
own pricing decides the default, which is the cheapest model that can drive a
run rather than whatever the harness would reach for.
The composer's picker gained a model list (cheapest first, with input price),
the choice is remembered per harness in the studio preferences, and each run in
the tray shows the model it actually used.
Payloads that cross a boundary — request bodies, the run log, the catalog — are
now zod schemas with inferred types instead of hand-written `unknown` readers
and casts.
The dot repeated what the row already said. A run in flight now carries a
progress rail instead — sweeping while the agent works, still while it waits —
and a waiting run says where it sits ("Next up", "#3 in line") rather than
just "Queued".
History written before runs recorded their harness fell back to the neutral
mark; the harness is now recovered from the logged label, so past Claude Code
runs stop rendering as an anonymous spark.
The composer header is now a picker: every harness Studio knows is listed with
whether it is installed, so a queue can mix Claude Code, Codex, Hermes and
OpenClaw instead of taking whatever was auto-detected. Each carries its own
vendor mark, and the tray stacks one mark per harness in play (only when more
than one is).
Each run also carries its session id and the coordinates of the element it
edited: clicking the element name seeks back to that moment and re-selects it.
Fixes a wheel over the run list panning the canvas underneath instead of
scrolling the list — floating overlays now declare that they own their own
scrolling, which the preview checks before it pans or zooms.
The queue was a promise chain, so a waiting run could only be watched. It is
now an explicit list: queued runs can be moved sooner or later, dropped before
they start, and a run already going can be stopped (the tray reveals those
controls on hover).
Every settled run is appended to <project>/.hyperframes/agent-runs.jsonl —
when it ran, which element, the instruction, how long it took and what the
agent reported back. Studio reads that log when a project is first listed, so
the history survives a server restart instead of living only in memory.
Runs become server-owned jobs instead of one blocking request. Submitting
clears the field immediately, so several instructions can be fired at
different elements in a row; per project they execute one at a time, since two
agents rewriting the same composition would clobber each other.
A tray on the canvas lists every run with what the agent is doing right now
(Claude Code runs in stream-json so each tool call surfaces as it happens),
its target, elapsed time and final message. The list is read from the server,
so a page reload lands back on the work still in flight.
Adds Hermes and OpenClaw presets alongside Claude Code and Codex, each with
its own mark, and HYPERFRAMES_AGENT_ICON to point any other harness at a real
icon file.
The composer can cover the element it edits, so its header is now a drag
handle. The header also shows which harness is running: the server reports a
kind alongside the label (claude / codex, sniffed from a custom
HYPERFRAMES_AGENT_CMD and defaulting to claude when inconclusive) so the mark
is never blank.
The Ask agent modal could only copy a prompt to the clipboard. Studio now
hands that same prompt to whichever harness CLI is installed (claude, codex,
or HYPERFRAMES_AGENT_CMD), runs it in the project dir, and lets the existing
file watcher reload the preview. Timeline clips get the same entry point via
their context menu, resolved back to the live DOM element so the prompt
carries full element context.
The previous commit claimed "all nine now terminate their options". That
was false: `producer/src/utils/audioRegression.ts:307` still passed the
path bare, and it is production source used by the regression harness.
A repo-wide audit found two more in studio-server
(`mediaValidation.ts`, `mediaMetadata.ts`) — their current callers pass
absolute paths, so they were defence-in-depth rather than live bugs, but
the exhaustiveness claim should be true rather than narrowed.
Eleven sites total, all terminated.
Adds a SOURCE-level contract test, which is the gap that let this
happen twice. #2740 fixed one of ten sites and shipped a regression
asserting the argv of that single site, so CI reported the class closed
while nine invocations still parsed `-intro.mp4` as an option. A
per-site unit test has the same blind spot for site twelve; scanning the
tree does not. The test also asserts its own coverage list has not
shrunk.
Verification: engine 1300, lint 511, core 1431, studio-server 398, cli
init/webmAlphaCheck/whisper 146, producer utils 51, audioPadTrim 18.
Removing any single terminator fails the contract test by name.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Extends the studio-preview fix to the render path and the asset-discovery
utilities, which share the same resolver and had the same defect.
`rewriteAssetPath` takes an optional `assetExists` probe. A plain relative ref
authored in a sub-composition (`_shared.css`, `clip.mp4`) is re-pointed at the
composition's own directory when that sibling exists on disk; project-root refs
with no sibling (the registry's `assets/logo.png` convention) stay as authored.
Callers that can see the filesystem supply the probe, so the module stays free
of node:fs.
Also fixes a second defect in the inliner: `<head>` <link> hrefs and external
script srcs are hoisted into the root document but never went through the
rewrite at all, so even the documented `../` form escaped the project and 404'd
at render time.
Wired into the preview bundler, the producer compiler, the studio preview
builder, the HEVC preview lint, the project lint's asset scans, publish proxy
baking, and media-treatment source resolution.
Fixes#2956
## What
A composition in a subdirectory that references a **sibling** file (`<link rel="stylesheet" href="_shared.css">`, not `../_shared.css`) is now resolved against the composition's own directory when building the standalone sub-composition preview page.
## Why
The preview page borrows the project-root `<base href="/api/projects/:id/preview/">`, but the path rewriter only rewrote `../`-prefixed paths. So `design/styleframes/frame-01.html` referencing `_shared.css` was served unrewritten and the browser requested `/preview/_shared.css` → **404**.
With its stylesheet missing, the frame renders unstyled: `body` has no background, and the thumbnail generator's transparent-body fallback paints it `#1c2028`. Result: dark navy thumbnail with unreadable dark text on every styleframe in the Board view.
The report attributed this to project scale (~21 sibling files). It is not scale-related: a 2-file project reproduces identically, and the same file moved to the project root renders correctly. The trigger is **composition-in-a-subdirectory + relative sibling asset ref**.
Reproduced before the fix (single `curl` against the thumbnail endpoint, plus a direct headless capture of the preview URL):
```
HTTP 404 http://localhost:5190/api/projects/big/preview/_shared.css
body bg: rgb(28, 32, 40)
```
## How
`resolvePreviewAssetPath` in `packages/studio-server/src/helpers/subComposition.ts`, applied through the single rewrite pass all three dispatch branches (template / full-doc / fragment) already share, so `src`, `href`, inline `style` urls, and `<style>` blocks all get the same rule:
1. `../` paths keep resolving against the composition dir (unchanged, shared with the producer's inliner so preview and render agree).
2. Any other relative path is re-pointed at the composition's directory **only when that sibling file exists on disk**.
The disk check is what keeps the two conventions apart: registry blocks are installed into a subdirectory but reference project-root assets (`assets/logo.png`), which are already correct under the root base and have no sibling on disk, so they are left untouched.
Not changed: the `#1c2028` transparent-body fallback in the thumbnail generator. It is correct for genuinely transparent compositions; the illegibility was a downstream symptom of the 404.
## Test plan
- [x] Unit tests added/updated — two tests in `subComposition.test.ts`: a red-first regression guard for the sibling `<link>` / `<img>` / `url()` case, and a guard that project-root-relative refs with no sibling on disk stay untouched.
- [x] Manual testing performed — reproduced the dark thumbnail on a generated project (21-file and 2-file variants both reproduce), then confirmed the same URL renders the white-to-lavender gradient with legible text after the fix, with no 404 in the network log.
- [x] `packages/studio-server` suite green: 29 files / 402 tests. Lint, format, typecheck clean.
- [ ] Documentation updated — n/a
- A long-lived preview cached its telemetry posture in two places
(readConfig and shouldTrack). Running `telemetry disable` in another
terminal left it resolving canaries and injecting the CLI id for hours.
Both caches are now dropped together at a request boundary.
- Studio minted and shipped a telemetry id for every render regardless of
the browser profile's opt-out, and the server emitted the outcome under
CLI policy, which cannot see localStorage or DNT. The browser now sends
an explicit telemetryOptOut, distinct from an old client's omission.
- Any non-empty HYPERFRAMES_PREVIEW_HOST disabled the DNS-rebinding guard,
so even a loopback bind accepted a hostile Host. The guard now holds for
loopback binds and, on a LAN bind, admits only names this machine
answers on.
- sunsetAfter had no reader of the current date. A scheduled workflow runs
scripts/check-canary-sunset.ts weekly, so a failure lands on the
rollout's owner rather than on an unrelated PR author.
- The install-state seed memo outlived `rm -rf ~/.hyperframes`,
resurrecting a cleared cohort. Removed; it only saved a read on a
readConfig cache miss.
Docs updated for the Host rule and the 100% exclusion carve-out.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* refactor(lint): route asset-src skips through a shared isUnresolvedAssetPlaceholder predicate
Follow-up to the templating-token fix. The __UPPER__ + templating-token skip was
copy-pasted across the asset-src sites and had drifted: two non-lint sites carried only
the __UPPER__ half, and htmlCompiler's comment still claimed it "matches lint's skip"
after lint's skip became a superset. Extract one isUnresolvedAssetPlaceholder(rawSrc) in
@hyperframes/parsers/asset-resolution (both placeholder shapes, checked on the raw value)
and route every site through it: the four project.ts lint sites, hevcPreviewLint, and the
two previously-missed post-substitution sites (studio-server mediaCodecMap, producer
htmlCompiler). Remote/inline handling stays per-site (audio uses a narrower check).
Behavior-preserving for the lint sites (full suite green); the two non-lint sites are
post-substitution so they don't false-positive today, but now share one definition and
can't drift again. Adds unit tests for the predicate.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(parsers): refresh hasUnresolvedTemplatingToken aside for the shared predicate
The parenthetical said the __UPPER__ shape keeps its own inline check at each call
site; this branch folded it into isUnresolvedAssetPlaceholder, so point there instead.
Addresses review nit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## What
Allow Studio Preview to serve an asset reached through a project-local symlink whose target is in a shared directory outside the project, including browser-hostile video assets that need an authoring proxy.
## Why
Preview rejected these assets with a 404 while the renderer accepted the same path. The initial static-route fix still failed for HEVC, ProRes, AV1, and VP9 assets because the proxy transcoder rejected the external target.
## How
Use lexical project-root containment for the read-only static asset route and proxy source request. The transcoder canonicalizes the target for ffmpeg and includes that identity in its cache key, while keeping the proxy cache inside the project. Composition source paths retain canonical containment because preview can persist their data-hf-id values.
## Test plan
- [x] Unit tests added/updated
- [x] `bun run --cwd packages/studio-server test` (397 tests)
- [x] Studio Server typecheck, oxlint, and oxfmt
- [x] External-symlinked hostile-video proxy route regression
- [x] Static-route traversal regression
- [ ] Documentation updated (not applicable)