Admit Agentic JSON Canvas intents without execution

Traceability

• Spec ID: agentic-json-canvas-intents
• Status: Implemented
• Builds on: studio-artifact-surface-selection

Intent

Allow an exact, Provider-hosted Agentic JSON Canvas to submit a bounded intent for Host-owned semantic selection or steering. Studio must revalidate the current frame, Artifact revision, Host-minted binding, Provider runtime, and intent identity before recording either effect. Steering is an observable draft only: it is never prepared, executed, approved, or forwarded to an Agent by this flow. An operator-configured Provider may additionally resolve a projection-local element to one exact domain-native target. Studio keeps the Canvas source and native destination identities separate and requires explicit human adoption before opening the destination Collaboration workflow.

Acceptance Scenarios

• AC-1: The public Artifact Provider contract exposes an optional, intent-only runtime and a versioned hosted envelope/outcome. The Host mints the route, actor, timestamp, selection id, and steering id; none is accepted from the iframe.
• AC-2: Studio exposes an exact-revision POST admission route only when the selected contribution supplies the optional runtime. The route re-resolves the active Provider and Host binding, rejects stale or malformed identities, and fresh-resolves the target before returning a selection or steering outcome.
• AC-3: Replaying one canonical intent id returns the retained outcome with replayed: true. Reusing that id with different content fails closed, and retained admissions are bounded.
• AC-4: ExternalHostedArtifactView forwards an envelope only from its current iframe and only for the current Artifact revision and binding. A response that arrives after navigation or rebinding cannot alter the new surface.
• AC-5: An admitted selection updates the existing shared selection. An admitted steering outcome records and displays a draft labelled “Recorded, not executed”; it may prefill the Collaboration textarea but must not invoke Provider preparation, decisions, Agent runs, or source mutation.
• AC-6: Focused server and client tests cover current-window acceptance, stale identity, unrelated windows, unknown targets, replay, conflicting replay, Provider change, response races, and zero proposal/decision/Agent-run effects.
• AC-7: The changed Studio surface uses existing semantic CSS tokens and is verified at 1440×900, 1024×768, and 390×844 with keyboard focus, no document-level horizontal overflow, and no captured browser console/page errors.
• AC-8: A Provider-native outcome carries both the projection-local source target and an exact destination Artifact claim. The Host requires a portable destination label, resolves its current Artifact id/revision/renderer binding, inspects the exact interaction workspace, matches the complete native target, then re-resolves source and destination identities before recording.
• AC-9: A native steering outcome first renders as Recorded, not executed with source, target, Artifact, and draft evidence. Only the trusted Use draft in Collaboration control opens the destination workspace. It starts no proposal, decision, Agent run, or mutation; a generic Canvas instruction may be compiled into native Provider grammar only by the existing configured Agent path.
• AC-10: A native outcome atomically carries sourceTarget, destination, and a Host-minted originRef. The reference is accepted only for the exact retained outcome, current Artifact authority, destination binding, native target, and unedited draft. It is correlation evidence, not execution authority.
• AC-11: Explicit adoption mints a digest-bound Host provenance record outside Provider proposal IR. Direct Provider proposals, ACP evidence and proposals, decision responses, and canonical decision replay carry the same provenance. A stale source or destination blocks a new decision before the Provider mutation gate.

Non-goals

• Adding a json-render-specific schema or action catalog to Better Harness.
• Treating an intent as approval, a proposal, a transition receipt, or mutation authority.
• Automatically preparing a Provider proposal or starting an Agent after steering.
• Persisting steering drafts across Studio restarts, multi-user presence, arbitrary/model-authored cross-Artifact mappings, or a universal Artifact IR.
• Providing atomic source/destination locking, treating originRef as a secret capability, or inserting Studio provenance into Provider-native proposal digests.

Plan and Tasks

1. Add Provider-neutral intent runtime, envelope, outcome, descriptor, and admission-input contracts to @qoder-ai/harness/artifacts.
2. Include intent runtime identity in the Host binding digest and mint an exact-revision intentUri in the Artifact catalog.
3. Add a separate admission route with strict parsing, fresh Provider/runtime resolution, Host-owned metadata, bounded idempotency, and stable public error codes.
4. Forward current-frame envelopes through the generic external-hosted mount, revalidate async outcomes, and connect accepted effects to shared selection plus a non-executing steering draft.
5. Add focused contract, server, component, negative, replay, and responsive browser tests without changing proposal, decision, or Agent-run routes.
6. Admit an optional Provider-owned native target claim, revalidate its exact destination workspace in the Host, and expose a separate trusted adoption gate that reuses the existing destination Collaboration workflow.
7. Bind explicit adoption to a Host-owned, canonical provenance record retained alongside the native proposal and returned unchanged through Agent evidence, decision settlement, and replay.

Test and Risk Evidence

• AC-1–AC-3, AC-10–AC-11: Node 24.15.0 npm test --workspace @qoder-ai/harness passed 20 files / 173 tests. npm test --workspace @qoder-ai/harness-studio passed 63 files / 507 tests. The focused intent, registry, and interaction suites passed 3 files / 43 tests, including canonical replay, stale source/binding/authority, unsafe JSON, Provider timeout/rejection, atomic native outcome fields, forged origin references, exact provenance digesting, and strict client decoding.
• AC-4–AC-5, AC-9–AC-11: external-artifact-host.spec.mjs passed 2/2. The original three-viewport flow exercised iframe postMessage → Host POST → native-target record → explicit Use draft in Collaboration → destination prefill and asserted zero proposal, decision, or Agent-run requests. The P3 flow then required a second explicit Prepare with Provider, forwarded the exact originRef, displayed Canvas provenance on the proposal and rejected receipt, and observed no Agent run or source/destination mutation.
• AC-6: the canonical replay fixture observed admit=1, inspect=0, prepare=0, decide=0 and identical source bytes before/after. The native path inspected only the exact destination workspace; escaped labels, missing targets, and changed revisions failed closed before preparation or decision.
• AC-7: the focused Playwright run covered 1440×900, 1024×768, and 390×844 with document overflow assertions and no captured console/page errors. Screenshots at test-results/.../external-artifact-intent-\{wide,compact,narrow\}.png retain the Canvas source, native target, destination, draft, and trusted adoption control. A separate real in-app Browser review observed client/scroll widths of 1440/1440, 1024/1024, and 390/390 with zero warnings or errors; the narrow layout kept the adopted draft and Agent control visible under the Preview tab.
• AC-8–AC-9: the cross-repository real Host smoke returned 201 for select and steer from Canvas revision 603a8d2c…d22ab3 / binding 73708778…d72d2df9, normalized json-render://element/plan-card to exact Draw.io revision bb301843…e133031e / binding fb2f5699…b660a8fe, and recorded both as not-executed with zero Canvas source mutations. The existing governed Draw.io flow then rejected once without mutation and approved once with authoritative readback bb301843…e133031e → 5fae91d3…cfdd26c, verification passed, one evidence item, replay success, and catalog convergence.
• AC-10–AC-11: direct Provider and real ACP fixtures carried one identical Host provenance record through proposal, Agent evidence, decision, and canonical replay. Forged origins and edited message/native grammar failed before Provider preparation; source drift after preparation failed before Provider decision. An independently recomputed canonical digest matched the retained record, and proposal settlement remained governed by proposal TTL rather than the shorter-lived intent lookup.
• Focused oxlint --deny-warnings passed for every changed TypeScript, TSX, test, and browser file. Harness and Studio builds passed as part of their full package test commands. Dry-run packs were 150378/647711 B/143 entries for @qoder-ai/harness and 7059704/38408933 B/1156 entries for Studio. Homology's Provider suite passed 7 files / 46 tests; root build and 4-worker Vitest passed 266 files / 2327 tests with 1 skipped. Package naming reported 91 packages, 89 workspaces, 2 exceptions, 12 families, 107 scripts, 2863 tracked files, 239 allowlisted files, and zero machine-local path hits. Both repositories' git diff --check passed.
• Risk: an opaque iframe may race navigation while admission is pending. The client must compare Artifact id, revision, binding, and request generation again before applying the result; the server remains authoritative even when the browser drops a stale response.