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.
The OpenAI wordmark stood in for Codex; this is the icon Codex actually ships,
white plate and gradient mark, so it reads the same in the picker as it does in
the dock.
Both belong to the same element, so placed independently they landed on top of
each other. One pass now places both: the composer takes the side it prefers,
the answer takes the other, and where only one side has room the answer stacks
beyond the composer rather than across it. The bubble's tail keeps tracking the
element either way.
Not every instruction is an edit. "Why is this off-centre?" comes back as an
answer, and an answer that only lands in a run list is an answer nobody reads.
A finished run with something to say now surfaces as a bubble on the canvas,
its tail tracking the element's centre so a bubble pushed along by the canvas
edge still points back at what it answered. It can be expanded, dismissed for
good, or carried straight into a follow-up.
Also makes the element name in a run row read as the control it is — a target
glyph, a resting fill and a pointer — instead of looking like the caption
beside it.
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.
Three modules were each re-implementing the same four concerns — reaching a
Storage that can throw, parsing JSON that may be anything, deciding what a bad
value means, and writing without letting a quota error escape — with their own
try/catch and their own answer to each. createJsonStore owns the first, second
and fourth; a caller supplies only its key, its fallback, and how to read its
own shape.
UI preferences, agent drafts and render settings now sit on it. Validation
stays with each caller, since only it knows which fields are meaningful.
The agent edits files, the watcher reloads the preview, and the reload took the
composer's React state with it — an instruction being written while an earlier
run landed disappeared mid-sentence. Drafts are now stored per element, so a
reload (or a trip to another element and back) returns the words, and
submitting clears them.
The composer and the ask handle sat at z-20 inside the canvas overlay, but the
overlay's own decorations climb to z-40 — so the motion path and its keyframe
diamonds drew straight through the pill. Both now sit above them, through one
named constant rather than a number picked per component.
The composer, run tray, both context menus and the ask handle each carried
their own copy of the same surface (layered shadow, hairline ring, blur) and
row treatment, which is how the menus and the tray drifted apart in the first
place. They now share components/ui/floatingSurface.
Also reworks the ask affordance: a mark at rest that widens into "Ask ⌘K" on
hover, in CSS, instead of the native OS tooltip that covered the element it
pointed at.
Selection chrome on a 3D-transformed element: rect + angle cannot describe a
keystoned projection, so the overlay drew a rotated box beside the element and
the crop frame landed somewhere else entirely. A projection that is not a
rotated rectangle now reports its axis-aligned bounds and says so, and crop —
which only exists in the element's own plane — stands down.
Auto-opening the composer on every selection put a panel on the canvas whether
or not the user wanted to ask for anything. The entry point is now a small
harness mark pinned to the selection: it sits where the eye already is, opens
the composer on click, and names the ⌘K shortcut in its tooltip — discoverable
without taking the canvas.
Also gives the run tray an inline z-index. It carried a utility class that lost
to the timeline ruler and the panels, so the ruler drew straight through the
tray's rows.
Selecting an element now opens the composer on it — the selection was already
the ask, and waiting for a second gesture on the thing just clicked was a step
for nothing. A multi-selection carries through: the prompt names every
co-selected element and widens its guardrail to "change every one of them", and
the field says how many it is talking about.
The harness and model lists are capped and scroll on their own instead of
growing the composer, and they declare they own their wheel so the canvas
underneath stays put.
Adds usage telemetry for the whole surface — composer opened, run submitted,
harness and model chosen, custom harness added — carrying the harness, model
and element count, never the instruction text.
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.
Every agent affordance now names the harness that will actually run — the
context menus, the inspector footer and the empty state read one effective
value, so a picked Codex can never sit behind a menu still offering Claude
Code. ⌘K opens the composer on the current selection.
The marks are the vendors' own: OpenClaw's pixel lobster and the Nous Research
portrait Hermes ships, alongside Claude's and OpenAI's.
The run tray moved off the canvas — it floats over the shell, drags anywhere,
and remembers where it was parked. Harness pick, tray position and collapsed
state all live in the studio preferences file rather than being re-chosen every
session.
Context menu rows were rebuilt as inset items so a hover fill covers the whole
row instead of leaving gutters at the edges.
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.
The header repeated the selected element, which the field's own placeholder
already says. It now names the agent that will run the instruction (Claude
Code, Codex, …), falling back to the element when no harness is installed.
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.
Replace the full-screen Ask agent modal with a composer anchored to the
selected element: no backdrop, the composition stays visible while the agent
edits it, and the box stays open between runs so the next instruction is one
keystroke away. Status (working / finished / failed) reports in the composer
itself instead of a toast, and the canvas right-click menu gets the same
entry as the timeline clip menu.
Drops the never-set anchor-point plumbing and the modal's context-preview
builder along with the modal.
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.
Three R3 findings.
The redactor's segment classes were ASCII `\w`, so `/数据/客户/秘密视频.mp4` and
`/data/客户/secret.mp4` went out verbatim — and the generic redactor also feeds
CLI telemetry and producer observation messages, where no known-path list
compensates. Segments are now defined by their delimiters instead of an
alphabet, which is correct for every script by construction rather than
requiring Unicode classes to be kept correct. The bare-relative lookbehind had
the same ASCII assumption and let a match start mid-token, redacting
`客户/秘密/视频.mp4` to `客户[path]`; it is now a token boundary, and
bare-relative runs before absolute so it claims the whole token.
sanitizeProbeFailure cast the rejection reason to Error and read `.message`.
An injected probe can reject with anything, so `Promise.reject("failed")` gave
`undefined` and threw inside the redactor — converting a returned failure
result into a rejected promise. Normalized at the boundary, and
redactKnownPaths no longer throws on a non-string.
The contract only admitted .ts/.js/.mjs/.cjs, so it missed shipped shell and
Python callers. frame_strip.sh passed a user-controlled path as ffprobe's last
positional with no terminator; render-and-composite.sh had four more. Both
fixed, and the sweep now covers .py/.sh. Python list argvs are bracket
literals so they get the same position check; shell command lines get a
separate presence check, because checking position there needs a shell parser
— stated as the weaker guarantee it is rather than implied to be equal.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rames' first item on #2976. The clause named one page while the tree has 48
accordions across eight files: 20 in the verified-example gallery it means, and
28 under per-page `## Variants` headings — which the component table two lines
above routes to `Tabs`.
That contradiction matters more than usual because this file instructs agents.
The next one asked to bring the docs in line reads 28 compliant blocks as
violations and converts them.
Named by pattern now, with the reason the Tabs row does not reach them: Variants
blocks hold long alternative prompts a reader picks one of to read in full, not
parallel ways to perform the same step. Pre-existing and untouched by this PR —
the fix is the sentence, not the tree.
Both P1s from Miguel's review on #2976.
**The weekly changelog command has a fourth output, and it is public.**
`changelog-process.mdx` listed three internal drafts. `outputWeeklyDraft` also
calls `prependDocsUpdate` on `--write` (`scripts/changelog-weekly.ts:236`),
which writes straight into `docs/weekly-updates.mdx`. A contributor following
the page would review three files and push a fourth unread. Now called out as a
warning, with the re-run behaviour, since that is what makes editing the entry
afterwards safe.
The same paragraph also said Weekly updates is "unlisted in the sidebar". That
was true when written and I made it false myself, putting the page back under
Explore in #2978 after Rames found it orphaned. Corrected rather than reverted —
the page belongs in the sidebar.
**Bare `hyperframes lint` cannot validate a registry item.** Both
`contributing.mdx` and `contributing/catalog.mdx` told contributors to run it.
The CLI resolves a project by looking for `index.html`
(`packages/cli/src/utils/project.ts`), and registry items ship as `<name>.html`
or `demo.html`, so it fails with "No composition found". This is not
theoretical: `scripts/lint-registry-items.mjs` exists precisely for this shape
and its header records two `gsap_non_transform_motion` errors that reached main
unlinted because of it.
Both pages now document `bun run lint:registry-items`, and the Catalog page
shows the install-into-a-scratch-project route for the full `check` gate rather
than claiming a bare `check` covers a registry item.
Verified by running the documented command, not just by reading the script.
Three things the quality layer asserted but the pages did not support.
changelog-process said "do not recreate docs/weekly-updates.mdx; that empty
public page was retired" while the page exists with a real curated feed. It
describes the page as it is: unlisted, reachable by URL and RSS, with versioned
notes still in the Changelog.
The Related-topics rule read as universal, but three different endings are in
use and each is right for its shape — Related topics on task pages, a single
Next line through the Prompt Guide's numbered sequence, and nothing on
reference and concept pages. The rule now says that, and every section matches
it; color-grading gained the Next line it was missing and no longer points at a
page this stack retired.
The vocabulary previews were 18 DocsVideo players in three unlabelled grids, so
a reader saw several near-identical clips with no way to tell smooth from
snappy. They are now native muted loops with visible captions, which is what
AGENTS.md asks for small preview loops in the first place.
Rames' non-blocking note on #2975. The paths filter listed the renderer but not
scripts/registry-target-paths.mjs, which it imports — so a future change to the
path-traversal defence alone would never re-run the only job that exercises it.
That is the same shape as the bug the module exists to prevent: the check is
present, the thing that would catch a regression in it is not wired to run.
Miguel's second P1 on #2975, and he is right that my first fix only closed half
of it. `resolve()` and `relative()` are string operations and do not follow
links. Registry items are copied in recursively with symlinks preserved, so a
PR shipping `escape -> /tmp/outside` and declaring `target: "escape/pwned.txt"`
passed the lexical check, `mkdirSync` followed the link, and `cpSync` wrote
outside the project.
Reproduced before fixing: the old predicate returned one allowed copy and the
file appeared outside the project. Both directions were exposed — a symlinked
`path` reads a runner file in just as readily.
Containment is now filesystem-aware. No existing component of a candidate may
be a symlink, and the candidate's real location — resolved through its deepest
existing ancestor — has to sit under the project's own real path. A symlink is
refused rather than followed, even one pointing back inside the project:
nothing in the registry needs one, and following it would mean trusting the
target not to change between the check and the copy.
The tests are real fixtures now instead of string cases, because a purely
lexical suite is exactly what stayed green through the bypass. Twelve of them,
covering a symlinked target directory, a symlinked source file, a deeper path
through a symlinked component, an inward-pointing symlink, plus the lexical and
absolute cases from before.
Miguel's P1 on #2975, and it is real. `catalog-previews.yml` triggers on
`pull_request` for anything under `registry/blocks/**` or
`registry/components/**`, so `registry-item.json` arrives from the pull request
and is untrusted. `mirrorRegistryTargets` joined `files[].path` and
`files[].target` under the temp project and called `cpSync` on the result, and
`join()` walks out of its first argument. A `path` of `../../../../etc/passwd`
reads an arbitrary runner file into the project — which the job then uploads as
an artifact — and a `target` of the same shape writes an arbitrary runner path.
Both sides are now resolved and rejected when `relative(projectDir, candidate)`
is absolute or starts with `..`. Traversal that lands back inside the project
still works, so `nested/../demo.html` is unaffected.
Containment lives in `scripts/registry-target-paths.mjs` rather than inline,
because the traversal cases have to be testable and importing
`generate-catalog-previews.ts` drags in the producer. `existsSync` is injected
so the decision cannot depend on whether the target happens to exist on the
runner. Eight tests, covering traversal on each field separately, absolute
paths on each field, the sibling directory that shares the project's prefix,
and traversal that returns inside.
Verified end to end on a real tree, not only in unit tests: a manifest asking
to read `../secret.txt` and write `../pwned.txt` produces neither file, while
the legitimate entry still copies.
I introduced the wrapper when I extracted this block for a complexity finding
earlier in the stack, and did not look at what it was joining.
Inlining the registry-target mirroring pushed prepareProjectDir to cyclomatic
24, the one complexity finding fallow attributes to this branch — the other
eight are inherited and out of scope here.
Same behaviour, expressed as a filter chain in its own named function, so
prepareProjectDir returns to what it was and the new helper stays flat.
Rames' residual on #2974. I softened the body sentence last round and left the
frontmatter saying "All exported types from @hyperframes/sdk". Mintlify renders
description as both the page subtitle and the meta description, so the page went
on promising complete coverage in the two places a reader meets first — and the
one a search engine quotes.
Pre-existing on main, and he did not hold the stamp for it, but leaving it makes
the body fix cosmetic.
Miguel's three P2s and Rames' one finding on #2974, all verified in source
before changing anything.
**`render --json` is not a progress stream.** It prints exactly one
`batch-complete` document at the end (`batchRender.ts:408-418`), asserted as a
single `console.log` in `batchRender.test.ts`. Described as a final result now.
**The iframe drag example never captured the pointer.** `event.target` comes
from `iframe.contentDocument`, so `instanceof Element` against this window's
constructor is always false for a cross-realm node and `setPointerCapture()`
never ran — a pointer leaving the frame then loses `pointerup` and drag state
sticks. Structural feature detection instead, with the reason in a comment so it
does not get "simplified" back.
**The preview adapter example did not compile under strict TypeScript.** `comp`
was captured by the callback before definite assignment (TS2454). Optional, with
`comp?.dispatch(op)`.
**`ORIGIN_APPLY_PATCHES` was imported in a fence that did not use it and used in
fences that did not import it.** Imports do not cross fences, so both examples
were wrong in opposite directions. Rames found the pair in
`open-composition.mdx`; the same shape is in `composition.mdx:630`, which he did
not name. All three fences are self-contained now.
**And `types.mdx` claimed coverage it does not have.** It promised "every type
exported from `@hyperframes/sdk`" while omitting 13 of 42. Eleven are documented
on sibling pages, so the sentence now points at those instead of overclaiming.
The two with no home anywhere — `CompositionVariableType` and
`VariableUsageScan`, both re-exported from the barrel — have entries. The second
is worth having written down: `scanIncomplete` means `usedIds` is a lower bound,
so an id missing from it is unknown rather than unused.
CodeQL flagged js/redos on the all-literal argv matcher. It was right: the
`(?:"[^"]*"\s*,?\s*)+` form nests a quantifier inside a quantifier with an
optional separator, so whitespace can be matched two ways and a long
non-matching argv backtracks exponentially.
Replaced with a linear scan — find the spawn head, slice to the closing
bracket, and check the entries — plus small named helpers. Same behaviour: an
all-literal argv is treated as taking no input, an argv with a bare identifier
still has to be understood (verified by adding one and watching the guard fail).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CI runs the PR merged with main, so it saw a caller my branch predated:
`spawnSync("ffprobe", ["-version"])` in engine/src/utils/ffprobe.test.ts. That
is a capability check with no runtime path, so there is nothing to terminate,
but the unclassified guard flagged it as a caller it could not parse.
An argv whose entries are all string literals carries no input by
construction. Those are dropped before the check; an argv with a bare
identifier still has to be understood, verified by adding one and watching the
guard fail.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The contract test only walked packages/*/src and only .ts, so it could not see
the shipped agent tools under skills/**, which are .mjs/.cjs. 19 call sites
there and in package tests were still missing `--` immediately before the
input while the suite reported the bug class closed — a dash-prefixed filename
is parsed as an option and fails the same way.
Sweeps packages/, skills/ and scripts/ now, including .mjs/.cjs and test
files (dither.test.mjs was one of the broken sites). Excludes only the
contract test itself, which documents the contract with example argvs
including a deliberately misordered one.
Two guards were fixed while widening: the terminator must never be inserted
after `-i`, which consumes the next token (a blind pass hit an ffmpeg input
and a base64 -i), and comment prose describing a spawn is not a spawn.
Also routes every audioPadTrim probe failure through one sanitizer at the
boundary. runFfprobeJson scrubbed its own stderr, but
defaultProbeVideoFrameInfo threw `no video stream in ${videoPath}` raw into
the public PadTrimAudioResult.error, and an injected probe can throw anything.
The redaction unit tests all passed with the caller wiring deleted; the new
public-path regressions fail without it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The generic scrub still missed a relative path with no `./` prefix:
`customer/acme-secret/video.mp4` and `assets/bgm.mp3` reached telemetry
completely unredacted, because the absolute rule needs a leading slash and
the `./` rule needs the dot. Adds a rule for them that still leaves `N/A`,
`24/1` and `48000/1001` alone.
Shape matching is a net with holes by construction, so audioPadTrim now
also redacts the exact path it put in the argv, plus its basename, before
the generic scrub runs. It built the argv, so it does not have to guess.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
redactTelemetryString enumerated roots — /Users, /home, /opt, /tmp and a
handful more — so a project on /data, /Volumes, an NFS mount or any root a
user invented reached telemetry verbatim. Relative paths and bare basenames
were never redacted at all, and audioPadTrim routes raw ffprobe stderr
through this on every probe failure.
Now redacts by shape: absolute paths under any root (two or more segments,
so N/A and a 24/1 frame rate are not mistaken for one), relative paths
including dash-prefixed ones, and bare basenames with an asset extension.
URLs still keep their host and drop only the query.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>