# Add a Host-owned Agentic Artifact interaction loop ## Traceability - Spec ID: studio-agentic-artifact-interaction - Status: Implemented - Architecture input: `docs/adrs/studio-artifact-runtime-and-providers.md` - Depends on: `studio-external-artifact-provider-runtime`, `studio-artifact-view-host-lifecycle`, and Homology Artifact Surface v1 ## Intent Extend Harness Studio from a read-only Artifact viewer into a bounded shared work surface where a human and a Provider-supplied Agent capability can observe the same exact Artifact revision, address one semantic target, record steering, review a content-addressed proposal preview, and settle that proposal through a Host-owned approval gate. The Host remains the authority for routing, same-origin access, proposal lifetime, and the single decision entrypoint. The selected Provider remains the authority for format-specific addressing, proposal construction, mutation, validation, CAS, and authoritative readback. The opaque hosted iframe remains a renderer only and cannot approve or directly invoke mutation. This is an additive `artifact-interaction-v1` extension to the external Artifact Provider contract. Existing Provider v1 contributions remain read-only and unchanged when they do not declare the extension. ## Acceptance Scenarios - **AC-1:** The public Provider contract defines an optional, versioned interaction runtime with browser-safe workspace, target, proposal, preview, decision, receipt, diagnostic, and evidence projections. Registry resolution preserves the exact selected implementation and includes its identity in the Surface binding identity and catalog revision. Contributions without the extension behave exactly as before. - **AC-2:** `GET interaction`, `POST proposals`, `GET proposal preview`, and `POST decisions` routes resolve the same opaque Artifact id, exact source revision, Provider fingerprint, and contribution selected by the catalog. Requests are same-origin, bounded, strict, and path-free. Proposal state is bounded and expires; changing the selected Provider or Artifact revision invalidates it. - **AC-3:** Preparing a proposal records one selected semantic address and one steering instruction without mutating source state. The response shows Agent intent, proposed actions, expected revision, digest, validation claims, and a content-addressed preview served by the Host. A preview digest mismatch fails closed. - **AC-4:** Only the Host decision route may call Provider mutation. Approval is bound to proposal id, proposal digest, expected revision, decision id, and human actor. Reject performs zero source writes. A stale source returns `stale` and does not overwrite newer work. Replaying an identical decision returns the same terminal receipt and does not execute twice; a conflicting decision fails closed. - **AC-5:** An applied receipt is emitted only after Provider-owned CAS, authoritative readback, and passed verification. The receipt exposes before and after revisions, status, bounded diagnostics, evidence references, and affected semantic addresses. Studio refreshes the catalog and rendered Artifact to the authoritative revision after apply. - **AC-6:** The Artifact workspace exposes a docked Collaboration pane for interaction-capable Artifacts. It makes selected target, steering, proposal changes, preview, decision state, and receipt visible. Before proposal there is one primary `Prepare change` action; after proposal there is one primary `Approve once` action with secondary `Reject`. Loading, stale, failed, rejected, and applied states remain explicit and keyboard/focus accessible. - **AC-7:** The first real Provider bridge is Draw.io. It lists stable `drawio://` page/cell addresses and maps the bounded steering form `Rename to