kandev/docs/specs/canvases/requirements/agent-authored-web-apps.md

id, title, status, system, owners, created, last_updated

id	title	status	system	owners	created	last_updated
canvases-agent-authored-web-apps	Agent-authored web-app canvases	draft	canvases	canvases	2026-08-26	2026-09-23

Agent-authored web-app canvases Requirements

Overview

A canvas is a custom web application that an agent creates for one task. A user can promote a useful task canvas to its workspace. A workspace canvas appears in workspace navigation. An owner-authorized task canvas can already use its workspace's data while the user reviews it in the originating task.

The Canvases system owns the canvas scope, source lineage, release selection, promotion, editing flow, and discovery. The Plugins system owns the web-application runtime and its data contract.

Terminology

• Task canvas: A canvas that belongs to one task and appears only in that task. Its placement does not determine its approved data scope.
• Workspace canvas: A canvas that belongs to one workspace and appears in workspace navigation. Agent-authored canvases reach this scope by promotion; distribution also defines reviewed package installs.
• Draft: Editable canvas source in an authorized agent workspace.
• Release: An immutable package that passed validation.
• Promotion: A user action that changes a task canvas to workspace placement.

Requirements

REQ-CANVASES-AGENT-WEB-APPS-001: Agent-created task canvas

Intent: A task agent creates a purpose-built interface without requiring a person to assemble predefined blocks.

User story: As a user, I want a task agent to create a custom interface for the task, so that the interface matches the work.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-001.1: When a user requests a canvas from a task, the active task agent shall create the canvas draft in that task context.
• AC-CANVASES-AGENT-WEB-APPS-001.2: When the agent publishes a first release, the open task shall show its ready or permission-review canvas host without a browser reload or manual panel action.
• AC-CANVASES-AGENT-WEB-APPS-001.3: When an agent session creates a canvas, the canvas shall belong to the trusted task and workspace from that session.
• AC-CANVASES-AGENT-WEB-APPS-001.4: Agent input shall not select another task, workspace, user, or canvas owner.
• AC-CANVASES-AGENT-WEB-APPS-001.5: The task interface shall not offer a blank manual canvas builder or predefined block editor.
• AC-CANVASES-AGENT-WEB-APPS-001.6: When a task agent creates or edits a canvas, it shall be able to read the version-matched Kandev canvas-authoring skill without adding that skill to the task workspace.
• AC-CANVASES-AGENT-WEB-APPS-001.7: When the canvas feature is disabled, Kandev shall not expose canvas tools, routes, events, background work, or user interface entries.
• AC-CANVASES-AGENT-WEB-APPS-001.8: The authoring guidance shall provide a complete core workflow and exact file inventory with at most one required skill-read operation.
• AC-CANVASES-AGENT-WEB-APPS-001.9: Local, container, and remote task agents shall use the same authoring contract without access to a Kandev host file path.
• AC-CANVASES-AGENT-WEB-APPS-001.10: Canvas-capable task instructions shall identify the create, skill-read, and publish operations, including discovery guidance when those tools are not immediately callable.
• AC-CANVASES-AGENT-WEB-APPS-001.11: Authoring instructions shall require creation in Kandev, edits inside the assigned source directory, and a publish result before a completion claim.
• AC-CANVASES-AGENT-WEB-APPS-001.12: Authoring instructions shall distinguish an active release, a release awaiting permission review, and an unsuccessful publish. Local files or a successful build shall not imply publication.
• AC-CANVASES-AGENT-WEB-APPS-001.13: When a user returns after publication, the task shall show eligible task canvases not previously presented in that browser tab. This shall also work after reload or a missed publication event. Eligible canvases have an active valid release or await permission review. Draft-only, archived, disabled, removed, invalid, foreign-task, and workspace canvases shall not open automatically.
• AC-CANVASES-AGENT-WEB-APPS-001.14: Desktop shall add new canvas panels to the main editor group and focus one new panel. Existing panels shall retain their placement. Repeated discovery shall not duplicate panels or steal focus.
• AC-CANVASES-AGENT-WEB-APPS-001.15: Closing a presented canvas shall prevent automatic reopening in that browser tab, including after reload or publication of another release. Manual reopening shall remain available.
• AC-CANVASES-AGENT-WEB-APPS-001.16: On phones, automatic presentation shall open one focused canvas route. Returning to the task shall not redirect to that canvas again. Other eligible canvases shall remain accessible through the existing picker.

REQ-CANVASES-AGENT-WEB-APPS-002: Durable source and releases

Intent: A published canvas remains available after the agent workspace and browser session end.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-002.1: After a browser reload and a backend restart, the canvas shall load the same active release.
• AC-CANVASES-AGENT-WEB-APPS-002.2: When an agent publishes an invalid draft, the system shall preserve the current active release and show the validation errors.
• AC-CANVASES-AGENT-WEB-APPS-002.3: When an agent publishes a valid draft, the system shall activate one immutable release and preserve one prior valid release for rollback.
• AC-CANVASES-AGENT-WEB-APPS-002.4: When a user rolls back a release, the canvas shall activate the retained prior release without changing its scope or identity.
• AC-CANVASES-AGENT-WEB-APPS-002.5: When a task is removed, the system shall remove its unpromoted canvases and preserve canvases that were promoted.
• AC-CANVASES-AGENT-WEB-APPS-002.6: When a workspace is removed, the system shall remove all of its canvases, grants, state, runtime tokens, releases, and retained artifacts.

REQ-CANVASES-AGENT-WEB-APPS-003: User-controlled promotion

Intent: A useful task canvas becomes available in workspace navigation only after a user reviews its placement and permissions.

User story: As a user, I want to promote a useful task canvas, so that I can open it from the workspace sidebar.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-003.1: When a user starts promotion, the system shall show the requested data, write, event, state, and network permissions before confirmation.
• AC-CANVASES-AGENT-WEB-APPS-003.2: When the user confirms promotion, the same canvas identity and active release shall change to workspace placement. A release that already has workspace data access shall keep that access.
• AC-CANVASES-AGENT-WEB-APPS-003.3: When promotion completes, the canvas shall appear in navigation for that workspace only.
• AC-CANVASES-AGENT-WEB-APPS-003.4: An agent shall not promote, demote, or directly grant permissions to a canvas. Owner-authorized first publication shall follow local creation authority.
• AC-CANVASES-AGENT-WEB-APPS-003.5: Except for owner-authorized first publication, a release that requests new permissions shall await user review. Any current release shall remain active until the user approves the new set.

REQ-CANVASES-AGENT-WEB-APPS-004: Agent-assisted workspace editing

Intent: A person changes a workspace canvas by describing the change to an agent instead of editing source in Kandev.

User story: As a user, I want an agent to edit a workspace canvas, so that I do not need to maintain its source manually.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-004.1: When a user selects Edit canvas, the system shall launch a Quick Chat agent with a draft of the active source.
• AC-CANVASES-AGENT-WEB-APPS-004.2: The edit agent shall receive the canvas identity, current manifest, current source, validation rules, and existing permission grants.
• AC-CANVASES-AGENT-WEB-APPS-004.3: Agent edits shall not change the active release until the publish operation succeeds.
• AC-CANVASES-AGENT-WEB-APPS-004.4: When a Quick Chat edit session expires, the active and prior releases shall remain available.
• AC-CANVASES-AGENT-WEB-APPS-004.5: When the edit adds permissions, the system shall use the permission review in AC-CANVASES-AGENT-WEB-APPS-003.5.

REQ-CANVASES-AGENT-WEB-APPS-005: Task and workspace discovery

Intent: Users find a canvas at the scope where it is useful.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-005.1: A task shall list its task canvases and workspace canvases that apply to the task workspace.
• AC-CANVASES-AGENT-WEB-APPS-005.2: The desktop sidebar shall list active workspace canvases in a Canvases section that starts folded. Opening a canvas route shall not expand the section.
• AC-CANVASES-AGENT-WEB-APPS-005.3: The sidebar shall not list task-only, archived, disabled, invalid, or pending-permission canvases.
• AC-CANVASES-AGENT-WEB-APPS-005.4: When a user opens a canvas from a task, the desktop task workbench shall show it in a canvas panel.
• AC-CANVASES-AGENT-WEB-APPS-005.5: When a user opens a workspace canvas from navigation, the system shall show the same active release on its direct route.
• AC-CANVASES-AGENT-WEB-APPS-005.6: Host controls for Edit, Promote, Permissions, Releases, Archive, and Remove shall remain outside canvas code.
• AC-CANVASES-AGENT-WEB-APPS-005.7: When a user explicitly expands or folds the Canvases sidebar section, Kandev shall retain that preference.
• AC-CANVASES-AGENT-WEB-APPS-005.8: When canvases are enabled, workspace settings shall show a Canvases tab and shall include the active canvas count in workspace summaries that have room for it.
• AC-CANVASES-AGENT-WEB-APPS-005.9: A narrow workspace summary shall keep the Canvases tab available without compressing the summary tiles into unreadable labels.

REQ-CANVASES-AGENT-WEB-APPS-006: Responsive host surface

Intent: Desktop and phone users can open, manage, promote, and edit the same canvas through native Kandev navigation.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-006.1: On a phone, a task shall open one focused canvas in a full-height route instead of Dockview.

• AC-CANVASES-AGENT-WEB-APPS-006.2: On a phone, workspace canvases shall appear as labeled entries in the mobile navigation for the active workspace.

• AC-CANVASES-AGENT-WEB-APPS-006.3: On a phone, a canvas picker and secondary host actions shall use an inset bottom drawer.

• AC-CANVASES-AGENT-WEB-APPS-006.4: Host controls shall use safe-area padding, one vertical scroll owner, and touch targets of at least 44 CSS pixels.

• AC-CANVASES-AGENT-WEB-APPS-006.5: The host page shall have no horizontal overflow at supported phone widths.

• AC-CANVASES-AGENT-WEB-APPS-006.6: The application viewport shall receive the available size without a compressed desktop workbench.

• AC-CANVASES-AGENT-WEB-APPS-006.7: Release, permission, and promotion controls shall explain their effect through pointer and keyboard help on desktop and visible descriptions on touch surfaces.

• AC-CANVASES-AGENT-WEB-APPS-006.8: Release review shall keep its primary actions visible outside the scrolling content. On desktop, the surface shall use the available viewport; on phones, it shall provide a focused full-height view with one content scroll region and safe-area clearance.

• AC-CANVASES-AGENT-WEB-APPS-006.9: A two-permission review shall expose both permissions and its actions without scrolling at 1280 by 720 CSS pixels. Longer reviews shall keep actions reachable at 390 by 844 CSS pixels.

• AC-CANVASES-AGENT-WEB-APPS-006.10: An embedded canvas shall have one host action toolbar aligned with other task panels under the shared panel toolbar contract. A standalone canvas shall retain one page navigation/action header.

• AC-CANVASES-AGENT-WEB-APPS-006.11: Neither presentation shall add a separate status-only toolbar. Loading and blocking errors shall appear once in the body, with recovery actions. Ready shall show the application and an accessible status announcement. Nonblocking offline state may appear inline in the existing header while retaining the application.

REQ-CANVASES-AGENT-WEB-APPS-007: Visible runtime and release state

Intent: A user can understand whether the canvas is loading, offline, blocked by permissions, invalid, or using a prior release.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-007.1: The host shall show distinct loading, ready, offline, permission-review, invalid-release, and unavailable states.
• AC-CANVASES-AGENT-WEB-APPS-007.2: When live events disconnect, the canvas shall keep its last rendered content and show the connection state.
• AC-CANVASES-AGENT-WEB-APPS-007.3: When a canvas release becomes invalid or unavailable, the host shall show recovery actions without executing that release.
• AC-CANVASES-AGENT-WEB-APPS-007.4: A release history shall identify the active release, author kind, creation time, validation result, and permission change without showing source content in logs.
• AC-CANVASES-AGENT-WEB-APPS-007.5: A runtime URL or iframe load event alone shall not display Ready. Until the current frame acknowledges startup, the host shall display Loading. After 15 seconds without acknowledgement, it shall show an unavailable state with Retry and Releases actions.
• AC-CANVASES-AGENT-WEB-APPS-007.6: Retry, release replacement, token renewal, and canvas navigation shall ignore acknowledgements from previous frame attempts. An unavailable frame shall not cover recovery controls.
• AC-CANVASES-AGENT-WEB-APPS-007.7: Release and promotion review shall show readable release dates, status, and source labels. Internal release, task, and session identifiers shall not appear as visible labels or fallback copy. Missing sources shall have a readable unavailable label.
• AC-CANVASES-AGENT-WEB-APPS-007.8: Review shall describe each permission once in plain language, identify newly requested access, and show exact external origins. Ordinary permission review shall not appear as a validation failure. Active and retained valid releases shall have distinct labels.

REQ-CANVASES-AGENT-WEB-APPS-008: Bounded agent authoring

Intent: A task agent cannot fill canvas storage through repeated create or publish operations.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-008.1: A task shall have at most 10 non-removed task canvases. A workspace shall have at most 100 non-removed canvases across task and workspace scopes.
• AC-CANVASES-AGENT-WEB-APPS-008.2: One agent session shall make at most 10 canvas publish attempts in five minutes, and one canvas shall have at most one publish operation in progress.
• AC-CANVASES-AGENT-WEB-APPS-008.3: A create, publish, archive, or restore limit error shall return a stable code and preserve the active release.
• AC-CANVASES-AGENT-WEB-APPS-008.4: Archived canvases shall count toward canvas and storage limits until a user removes them.

REQ-CANVASES-AGENT-WEB-APPS-009: Guided canvas task launch

Intent: A user starts canvas authoring through a normal task without configuring repository state that the canvas does not need.

User story: As a user, I want a guided canvas task, so that I can choose an agent and review the canvas in the same task.

Acceptance criteria

• AC-CANVASES-AGENT-WEB-APPS-009.1: When canvases are enabled, selecting Set up a canvas in the empty desktop sidebar shall open task creation directly without changing the current route. Workspace Canvases settings shall retain its Create canvas action and the sidebar its settings shortcut.
• AC-CANVASES-AGENT-WEB-APPS-009.2: The action shall open the standard task creation flow with a localized canvas title and prompt, no repository, an empty scratch path, and an eligible local executor preference.
• AC-CANVASES-AGENT-WEB-APPS-009.3: The user shall be able to change the workflow and agent profile before task creation.
• AC-CANVASES-AGENT-WEB-APPS-009.4: After task creation, Kandev shall open the normal task details surface where the user can interact with the agent and review the canvas.
• AC-CANVASES-AGENT-WEB-APPS-009.5: On a phone, workspace Canvases settings shall expose the same task creation flow without a canvas-only form.
• AC-CANVASES-AGENT-WEB-APPS-009.6: The localized preset shall contain a short editable request for a coordinator view listing existing tasks, followed by a blank line and the exact reference @create-canvas. Detailed authoring instructions shall be available as that saved prompt.
• AC-CANVASES-AGENT-WEB-APPS-009.7: On desktop and phone, the user shall be able to read and edit the preset before submission. The submitted task shall retain those edits.
• AC-CANVASES-AGENT-WEB-APPS-009.8: The shipped saved prompt shall direct agents through tool discovery, draft creation, one core skill read, assigned-directory editing, and publication. It shall require authorized live data and accurate release, permission-review, and promotion reporting.
• AC-CANVASES-AGENT-WEB-APPS-009.9: When a structured task starts with @create-canvas, the agent shall receive the saved definition as hidden context. The task description shall retain the user's short request and reference. Create without starting shall defer expansion until launch.
• AC-CANVASES-AGENT-WEB-APPS-009.10: Users shall be able to customize create-canvas through Settings > Prompts. Startup shall preserve an existing same-name prompt and user edits. Removing the reference shall remove its expansion from the next submitted request.
• AC-CANVASES-AGENT-WEB-APPS-009.11: Desktop and phone users shall be able to edit the goal, cancel, retry a failed submission, and start the task. Failure shall preserve edits; cancellation shall create no task or canvas. The phone action shall remain reachable without horizontal page overflow.

Saved-prompt resolution follows Saved Prompt Delivery, including missing references, lookup failures, and passthrough exclusions.

Implementation plans

• Canvas runtime and task-entry recovery
• Direct canvas creation and saved prompt
• Task canvas workspace data preview

Out of scope

• A manual visual application builder.
• A direct source-code editor in Kandev.
• Canvas invitations, collaborator roles, or multi-user live editing.
• Demotion from workspace scope to task scope.
• Marketplace and cross-instance distribution are owned by the separate marketplace and sharing requirements.
• Automatic permission increases after owner-authorized first publication or automatic publication of a release that requests new permissions.
• General top-bar, sidebar-widget, or arbitrary-slot plugin contributions.
• A custom server-side runtime for agent-generated backend code.