feat: preview task canvases with workspace data (#3887)
This commit is contained in:
Carlos Florêncio
@@ -10,8 +10,8 @@ last_updated: 2026-09-10
|
||||
# Canvases
|
||||
|
||||
Canvases own agent-authored task applications and their promotion to workspace
|
||||
applications. The system owns canvas scope, source lineage, release selection,
|
||||
editing sessions, discovery, and portable canvas distribution.
|
||||
applications. The system owns canvas placement and data scope, source lineage,
|
||||
release selection, editing sessions, discovery, and portable canvas distribution.
|
||||
|
||||
The Plugins system owns the web-application runtime, permissions,
|
||||
Kandev data access, state, events, and package validation. The task system
|
||||
@@ -20,18 +20,21 @@ remains authoritative for task data and permissions.
|
||||
## Requirements
|
||||
|
||||
- [Agent-authored web-app canvases](requirements/agent-authored-web-apps.md)
|
||||
- [Task canvas workspace data preview](requirements/task-canvas-workspace-preview.md)
|
||||
- [Canvas marketplace and sharing](requirements/marketplace-sharing.md)
|
||||
- [Deprecated collaborative canvases](requirements/collaborative-canvases.md)
|
||||
|
||||
## System design
|
||||
|
||||
- [Agent-authored web-app canvases](system-design/agent-authored-web-apps.md)
|
||||
- [Task canvas workspace data preview](system-design/task-canvas-workspace-preview.md)
|
||||
- [Canvas marketplace and sharing](system-design/marketplace-sharing.md)
|
||||
- [Superseded collaborative canvases](system-design/collaborative-canvases.md)
|
||||
|
||||
## Related context
|
||||
|
||||
- [Runtime and permission fix plan](../../plans/canvas-runtime-permission-fixes/plan.md)
|
||||
- [Task canvas workspace data preview plan](../../plans/task-canvas-workspace-preview/plan.md)
|
||||
- [Agent MCP discovery guidance](../agents/system-design/mcp-tool-discovery-guidance.md)
|
||||
- [MCP discovery and canvas prompt plan](../../plans/mcp-discovery-canvas-prompts/plan.md)
|
||||
- [GitHub Copilot App Canvas reference](../../copilot-canvas-reference.md)
|
||||
|
||||
@@ -6,7 +6,7 @@ system: canvases
|
||||
owners:
|
||||
- canvases
|
||||
created: 2026-08-26
|
||||
last_updated: 2026-09-21
|
||||
last_updated: 2026-09-23
|
||||
---
|
||||
|
||||
# Agent-authored web-app canvases Requirements
|
||||
@@ -15,7 +15,8 @@ last_updated: 2026-09-21
|
||||
|
||||
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 and can use workspace-scoped data.
|
||||
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
|
||||
@@ -24,13 +25,13 @@ runtime and its data contract.
|
||||
## Terminology
|
||||
|
||||
- **Task canvas:** A canvas that belongs to one task and appears only in that
|
||||
task.
|
||||
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](marketplace-sharing.md) 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 scope.
|
||||
- **Promotion:** A user action that changes a task canvas to workspace placement.
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -120,8 +121,8 @@ browser session end.
|
||||
|
||||
### REQ-CANVASES-AGENT-WEB-APPS-003: User-controlled promotion
|
||||
|
||||
**Intent:** A useful task canvas becomes a workspace application only after a
|
||||
user reviews its scope and permissions.
|
||||
**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.
|
||||
@@ -132,7 +133,8 @@ can open it from the workspace sidebar.
|
||||
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 scope.
|
||||
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
|
||||
@@ -342,6 +344,7 @@ including missing references, lookup failures, and passthrough exclusions.
|
||||
|
||||
- [Canvas runtime and task-entry recovery](../../../plans/canvas-runtime-entry-recovery/plan.md)
|
||||
- [Direct canvas creation and saved prompt](../../../plans/canvas-direct-creation/plan.md)
|
||||
- [Task canvas workspace data preview](../../../plans/task-canvas-workspace-preview/plan.md)
|
||||
|
||||
## Out of scope
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ system: canvases
|
||||
owners:
|
||||
- canvases
|
||||
created: 2026-09-10
|
||||
last_updated: 2026-09-10
|
||||
last_updated: 2026-09-23
|
||||
---
|
||||
|
||||
# Owner-authorized canvas creation
|
||||
@@ -39,10 +39,11 @@ imported code and later changes cannot claim that creation authority.
|
||||
- **AC-CANVASES-LOCAL-CREATION-001.1:** The first valid release of an
|
||||
owner-authorized task canvas shall activate without a separate permission
|
||||
approval. Its grants shall contain only its declared, supported permissions.
|
||||
- **AC-CANVASES-LOCAL-CREATION-001.2:** Initial grants shall remain within the
|
||||
task scope and current owner access. They can cover supported data reads,
|
||||
writes, events, instance state, and exact HTTPS external origins. They shall
|
||||
not enable remote scripts, managed backend execution, or workspace access.
|
||||
- **AC-CANVASES-LOCAL-CREATION-001.2:** Initial grants shall contain only the
|
||||
declared supported data reads, writes, events, instance state, and exact HTTPS
|
||||
external origins. For a new owner-authorized canvas, those grants shall cover
|
||||
the current workspace while the canvas remains in its task. They shall not
|
||||
enable another workspace, remote scripts, or managed backend execution.
|
||||
- **AC-CANVASES-LOCAL-CREATION-001.3:** Agent fields, package metadata, display
|
||||
titles, and ownership of an imported package shall not establish local
|
||||
creation authority. Missing or mismatched trusted identity shall deny it.
|
||||
@@ -71,3 +72,4 @@ a marketplace, import UI, collaborator role, or ongoing blanket approval.
|
||||
## Implementation plans
|
||||
|
||||
- [Canvas runtime and permission fixes](../../../plans/canvas-runtime-permission-fixes/plan.md)
|
||||
- [Task canvas workspace data preview](../../../plans/task-canvas-workspace-preview/plan.md)
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
id: canvases-task-canvas-workspace-preview
|
||||
title: Task canvas workspace data preview
|
||||
status: draft
|
||||
system: canvases
|
||||
owners:
|
||||
- canvases
|
||||
created: 2026-09-23
|
||||
last_updated: 2026-09-23
|
||||
---
|
||||
|
||||
# Task canvas workspace data preview Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
A user creates a canvas from a task and reviews the live application there
|
||||
before deciding whether to add it to workspace navigation. Its task placement
|
||||
must not reduce the data available to an owner-authorized first release.
|
||||
Canvases owns the creation and promotion lifecycle; the Plugins system owns the
|
||||
runtime data contract and grant enforcement.
|
||||
|
||||
## Terminology
|
||||
|
||||
- **Placement scope:** Where Kandev presents a canvas and which task owns its
|
||||
unpromoted lifecycle.
|
||||
- **Data scope:** The largest Kandev data boundary admitted by a release's
|
||||
declared and granted capabilities. Data scope never overrides the viewing
|
||||
user's current authorization.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-CANVASES-WORKSPACE-PREVIEW-001: Representative task canvas preview
|
||||
|
||||
**Intent:** A locally requested canvas works with the current workspace's live
|
||||
data before the user chooses to promote it.
|
||||
|
||||
**User story:** As a user creating a canvas from a task, I want to see all tasks
|
||||
in my current workspace, so that I can judge the canvas before promotion.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.1:** After the first valid release of an
|
||||
owner-authorized task canvas activates, its declared task read capability
|
||||
shall list and read all currently authorized tasks in the canvas's workspace,
|
||||
including tasks added after publication. Refresh and pagination shall reach
|
||||
the full result set. A task in another workspace shall remain unavailable.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.2:** Before promotion, every supported
|
||||
capability declared by that first release shall operate across the same
|
||||
workspace where the capability has a workspace data meaning. Undeclared or
|
||||
unsupported capabilities shall remain unavailable, and every operation shall
|
||||
obey current user authorization.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.3:** The canvas shall remain discoverable
|
||||
only in its originating task until a user promotes it. Task removal shall
|
||||
retain its existing cleanup behavior. Promotion shall still require user
|
||||
confirmation, but it shall not be required to preview workspace data.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.4:** The canvas context and host review
|
||||
shall distinguish task placement from workspace data access. Promotion review
|
||||
shall identify whether it changes data access or only placement.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.5:** An existing task canvas with
|
||||
task-only data access shall keep that access after upgrade until a current
|
||||
workspace owner explicitly enables workspace data access. The review shall
|
||||
name the active release and its declared permissions. Confirmation shall
|
||||
widen only those declared grants without promoting or republishing the
|
||||
canvas; cancellation shall change nothing.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.6:** A stale review, changed owner,
|
||||
revoked grant, missing task or workspace, or failed permission check shall
|
||||
deny the access change without widening data exposure. A new release that
|
||||
adds a capability after first publication shall still await permission
|
||||
review.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.7:** Desktop and phone users shall be
|
||||
able to inspect the data scope and complete the existing-canvas access review
|
||||
from the task canvas host. The phone flow shall remain usable with one
|
||||
vertical scroll region, safe-area clearance, and touch controls.
|
||||
- **AC-CANVASES-WORKSPACE-PREVIEW-001.8:** A canvas built under this contract
|
||||
shall receive only workspace data authorized for its own workspace. Its
|
||||
runtime token, manifest, or agent input shall not select a different
|
||||
workspace or expand its capabilities.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Data from other workspaces or installation-wide grants.
|
||||
- Blanket grants for capabilities a release does not declare.
|
||||
- New canvas plugin capability types or arbitrary backend execution.
|
||||
- Automatic widening of existing published releases.
|
||||
|
||||
## Implementation plans
|
||||
|
||||
- [Task canvas workspace data preview](../../../plans/task-canvas-workspace-preview/plan.md)
|
||||
@@ -6,7 +6,7 @@ system: canvases
|
||||
owners:
|
||||
- canvases
|
||||
created: 2026-08-26
|
||||
last_updated: 2026-09-21
|
||||
last_updated: 2026-09-23
|
||||
requirements:
|
||||
- REQ-CANVASES-AGENT-WEB-APPS-001
|
||||
- REQ-CANVASES-AGENT-WEB-APPS-002
|
||||
@@ -110,9 +110,11 @@ Use a small lifecycle record instead of declarative canvas blocks.
|
||||
- nullable `archived_at`
|
||||
- `created_at` and `updated_at`
|
||||
|
||||
The plugin instance owns `scope_kind`, active release, status, and grants. The
|
||||
canvas service is the only service that changes the task or workspace scope of
|
||||
a canvas instance.
|
||||
The plugin instance owns placement `scope_kind`, effective data scope, active
|
||||
release, status, and grants. The canvas service is the only service that
|
||||
changes task or workspace placement or authorizes a canvas data-scope change.
|
||||
The [workspace preview design](task-canvas-workspace-preview.md) separates
|
||||
these scopes for locally requested task canvases.
|
||||
|
||||
The canvas and plugin instance have a one-to-one relationship. Canvas removal
|
||||
removes the plugin instance, runtime tokens, grants, state, pending releases,
|
||||
@@ -366,13 +368,14 @@ The promotion dialog shows:
|
||||
- each event subject
|
||||
- shared state access
|
||||
- each exact external network origin
|
||||
- the change from task scope to workspace scope
|
||||
- the change from task placement to workspace placement, with any data-scope
|
||||
difference identified separately
|
||||
- the new workspace navigation placement
|
||||
|
||||
The user can cancel without a state change. Confirmation creates the approved
|
||||
workspace grants and changes the plugin instance scope in one transaction. The
|
||||
canvas keeps its ID, plugin instance, active release, state, and release
|
||||
history.
|
||||
The user can cancel without a state change. Confirmation creates any needed
|
||||
workspace grants and changes the plugin instance placement scope in one
|
||||
transaction. The canvas keeps its ID, plugin instance, active release, state,
|
||||
and release history.
|
||||
|
||||
Promotion publishes one lifecycle event after commit. The task and workspace
|
||||
navigation projections then refresh.
|
||||
@@ -641,8 +644,10 @@ connection. An edit Quick Chat session also verifies its trusted target canvas
|
||||
metadata.
|
||||
|
||||
Task canvases cannot appear in another task. Workspace canvases can serve task
|
||||
surfaces only inside their workspace. Promotion does not grant access to tasks,
|
||||
repositories, sessions, or external services by itself.
|
||||
surfaces only inside their workspace. A task canvas can use approved workspace
|
||||
data before promotion under the [workspace preview contract](task-canvas-workspace-preview.md).
|
||||
Promotion does not grant undeclared access to tasks, repositories, sessions,
|
||||
or external services.
|
||||
|
||||
The plugin runtime repeats resource authorization for each request. Canvas
|
||||
authorization does not replace task or workspace authorization.
|
||||
|
||||
@@ -152,7 +152,8 @@ The definition in `config/prompts/create-canvas.md` contains this guidance:
|
||||
> Call `publish_canvas_kandev` and address any validation errors.
|
||||
> Report the canvas identity and whether its release is active, awaits permission review, or was unsuccessful.
|
||||
> If publication is unsuccessful, report the failure and do not claim that the canvas is published.
|
||||
> If workspace access requires promotion, explain the user action that is still required.
|
||||
> A new owner-authorized task canvas can use its declared supported permissions across the current workspace before promotion.
|
||||
> Promotion adds workspace navigation. Do not claim that promotion is required to preview workspace task data.
|
||||
> A local build alone does not publish a canvas inside Kandev.
|
||||
> If the tools remain unavailable, report the limitation instead of claiming that workspace files are a Kandev canvas.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ system: canvases
|
||||
owners:
|
||||
- canvases
|
||||
created: 2026-09-10
|
||||
last_updated: 2026-09-10
|
||||
last_updated: 2026-09-23
|
||||
requirements:
|
||||
- REQ-CANVASES-LOCAL-CREATION-001
|
||||
---
|
||||
@@ -20,7 +20,8 @@ owns grant storage, release activation, and runtime enforcement. This design
|
||||
implements `REQ-CANVASES-LOCAL-CREATION-001`; the authority, transaction, and
|
||||
compatibility sections map to criteria .1-.3, .4-.5, and .6-.7 respectively.
|
||||
|
||||
See [the creation authority decision](../../../decisions/2026-09-10-canvas-creation-authority.md)
|
||||
See [the creation authority decision](../../../decisions/2026-09-10-canvas-creation-authority.md),
|
||||
[its workspace-data amendment](../../../decisions/2026-09-23-task-canvas-workspace-data.md),
|
||||
and [plugin grants](../../plugins/system-design/isolated-web-app-contributions.md#instance-grants).
|
||||
|
||||
## Trusted creation authority
|
||||
@@ -40,7 +41,7 @@ Add a canvas-owned `canvas_creation_authority` table through
|
||||
| `canvas_id` | Primary key, references the canvas lifecycle identity |
|
||||
| `owner_user_id` | Trusted workspace owner at creation |
|
||||
| `creating_session_id` | Trusted source session |
|
||||
| `policy_version` | Integer 1 for the initial-publication policy |
|
||||
| `policy_version` | Integer 1 for historical task-data grants; version 2 for new workspace-data grants |
|
||||
| `consumed_at` | Empty until the first release transaction consumes it |
|
||||
|
||||
Create the row in the canvas/instance creation transaction. No agent-facing
|
||||
@@ -52,7 +53,9 @@ Existing databases acquire the empty table; do not backfill authority.
|
||||
At publication require every predicate: a nonzero captured `PublishAuthority`,
|
||||
local-canvas instance source, task scope, matching task and workspace, matching
|
||||
creating session, unchanged current owner, pending instance, no active or
|
||||
persisted release, no previous grant changes, and unconsumed policy version 1.
|
||||
persisted release, no previous grant changes, and an unconsumed supported
|
||||
policy version. New authority uses version 2; historical version-1 authority
|
||||
keeps its task data ceiling and is never upgraded by publication alone.
|
||||
Check the full instance snapshot again inside the transaction. Re-read the
|
||||
current task/workspace ownership through the same transaction and serialize
|
||||
against ownership changes; the adapter's earlier lookup alone is insufficient.
|
||||
@@ -64,10 +67,12 @@ The trusted adapter supplies the freshly resolved owner; caller-controlled
|
||||
## Grant derivation and transaction
|
||||
|
||||
Derive grants from `ManifestPermissions` and the existing static web-app
|
||||
capability vocabulary. Restrict Kandev resource access to the recorded task,
|
||||
using normal runtime authorization. Normalize each declared external origin
|
||||
through `NormalizeNetworkOrigins`; initial external grants count as delegated
|
||||
owner approval, with that owner as `ApprovedBy`. This is deliberate: a locally
|
||||
capability vocabulary. Version-2 authority binds the approved data scope to
|
||||
the recorded workspace while the canvas remains task-placed. Historical
|
||||
version-1 authority retains task data scope. See the
|
||||
[workspace preview design](task-canvas-workspace-preview.md). Normalize each
|
||||
declared external origin through `NormalizeNetworkOrigins`; initial external
|
||||
grants count as delegated owner approval, with that owner as `ApprovedBy`. A locally
|
||||
requested app can contact its declared HTTPS service on its first run.
|
||||
Unsupported capabilities and backend/native contributions cannot gain access
|
||||
through this path. Do not add a generic manifest-controlled auto-approve flag.
|
||||
@@ -96,8 +101,9 @@ schema replay and backup enumeration must include this table.
|
||||
## API and compatibility
|
||||
|
||||
Return an additive `initial_permission_policy` field in the create response:
|
||||
version 1, eligibility, scope `task`, supported permission kinds, and the exact
|
||||
HTTPS-origin constraint. This is descriptive output, never a publish input.
|
||||
the policy version, eligibility, placement `task`, data scope, supported
|
||||
permission kinds, and exact HTTPS-origin constraint. This is descriptive
|
||||
output, never a publish input.
|
||||
It must not claim a permission ceiling that the backend does not enforce.
|
||||
Keep the existing `activated` and `permission_required` publish result fields.
|
||||
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
id: canvases-task-canvas-workspace-preview-design
|
||||
title: Task canvas workspace data preview design
|
||||
status: draft
|
||||
system: canvases
|
||||
owners:
|
||||
- canvases
|
||||
created: 2026-09-23
|
||||
last_updated: 2026-09-23
|
||||
requirements:
|
||||
- REQ-CANVASES-WORKSPACE-PREVIEW-001
|
||||
---
|
||||
|
||||
# Task canvas workspace data preview System Design
|
||||
|
||||
## Boundary and mapping
|
||||
|
||||
Canvases owns when a locally requested task canvas gains workspace data scope,
|
||||
how an older canvas can opt in, and when promotion changes placement. Plugins
|
||||
persists the instance's effective data scope and enforces it through the shared
|
||||
web-app runtime. Task services remain authoritative for data and current user
|
||||
access. This design implements `REQ-CANVASES-WORKSPACE-PREVIEW-001`.
|
||||
|
||||
| Criteria | Design sections |
|
||||
| --- | --- |
|
||||
| `AC-CANVASES-WORKSPACE-PREVIEW-001.1`, `.2`, `.8` | Data scope and runtime enforcement |
|
||||
| `AC-CANVASES-WORKSPACE-PREVIEW-001.3`, `.4` | Lifecycle and presentation |
|
||||
| `AC-CANVASES-WORKSPACE-PREVIEW-001.5`, `.6`, `.7` | Existing canvas upgrade and host flow |
|
||||
|
||||
See [the workspace preview decision](../../../decisions/2026-09-23-task-canvas-workspace-data.md)
|
||||
and [the existing creation authority](local-creation-authority.md).
|
||||
|
||||
## Data scope and persistence
|
||||
|
||||
Keep `plugin_instances.scope_kind` as the placement/lifecycle scope. Add a
|
||||
nullable `data_scope_kind` to `plugin_instances`; null means the existing
|
||||
`scope_kind` so older rows and non-canvas plugins retain their behavior. A
|
||||
non-null value is valid only when it equals the placement scope, or when a
|
||||
`local_canvas` task instance uses `workspace` data scope with its existing
|
||||
trusted `workspace_id` and `task_id`. Reject `instance` and foreign workspace
|
||||
data scope for canvases. Do not accept the field from agent, manifest, or
|
||||
browser input. Store it through SQLite and PostgreSQL schema paths, backup,
|
||||
snapshot, and instance row mapping.
|
||||
|
||||
At trusted canvas creation, record workspace data scope only for a new task
|
||||
canvas with owner-authorized creation provenance. The task remains the canvas
|
||||
owner and the plugin instance's placement scope. The first valid release
|
||||
derives grants from exactly its declared supported capabilities with a
|
||||
`workspace` ceiling, then consumes creation authority and activates in the
|
||||
existing transaction. Raise `CreationAuthorityPolicyVersion` for newly issued
|
||||
authority; consumed version-1 rows remain historical evidence and are never
|
||||
reissued. If provenance or current owner checks fail, publication follows the
|
||||
normal permission-review path and cannot infer a workspace grant.
|
||||
|
||||
All grant-fit, release activation, and runtime-binding validation for a web
|
||||
app use its effective data scope. A grant ceiling cannot be interpreted as
|
||||
covering a wider data scope merely because it covers the placement scope. A
|
||||
later declaration increase still creates a pending release. Revocation bumps
|
||||
the existing grant generation and invalidates runtime tokens.
|
||||
|
||||
## Runtime enforcement
|
||||
|
||||
`webapp.CapabilityBinding` carries both placement `ScopeKind` and effective
|
||||
`DataScopeKind`. Issue both from the persisted instance, and compare both with
|
||||
the current instance on every token validation. Existing bindings with an
|
||||
empty data scope resolve to placement scope. The relative
|
||||
`./_kandev/v1/context` response retains `scope_kind` for placement and adds
|
||||
`data_scope_kind` for authors to label the available data accurately.
|
||||
|
||||
Use the effective data scope for the web-app task list, single-task read,
|
||||
task update, message dispatch, workflow list and steps, task dependency edge
|
||||
projection, and subscribed task events. A workspace data scope binds all
|
||||
queries and mutations to the instance's trusted `workspace_id`, including
|
||||
explicit `workspace_id` filters. It does not derive workspace IDs from the
|
||||
request or allow `ScopeInstance`. The task-list route uses its existing
|
||||
pagination path instead of the bound-task shortcut. Each operation still
|
||||
checks the declared capability, effective grant, and current user/domain
|
||||
authorization. Other plugin instances continue to use their existing scope
|
||||
rules.
|
||||
|
||||
Never use the ordinary authenticated Kandev HTTP API as an implicit escape
|
||||
from the canvas protocol. The [same-origin trust decision](../../../decisions/2026-09-19-trusted-same-origin-canvases.md)
|
||||
acknowledges that browser code can call those APIs, but the documented canvas
|
||||
contract and capability-only runtime must remain coherent.
|
||||
|
||||
## Lifecycle and presentation
|
||||
|
||||
`canvas_lifecycle_metadata.task_id` and the instance's placement scope retain
|
||||
task discovery and deletion semantics. Workspace data scope does not add the
|
||||
canvas to workspace navigation. Promotion remains a reviewed human action:
|
||||
it changes placement to workspace, clears task placement, preserves the active
|
||||
release, and leaves workspace data scope intact. The review states that data
|
||||
access is already workspace-wide when that is true. A task-only legacy canvas
|
||||
still has its existing promotion behavior, including grant expansion.
|
||||
|
||||
Project `data_scope_kind` alongside `scope_kind` in the canvas and runtime
|
||||
responses. The task host exposes a compact data-scope label in its existing
|
||||
header/action surface. Releases and permissions and promotion review explain
|
||||
placement separately from data access. The bundled authoring guidance and
|
||||
public canvas documentation tell authors to read both context fields and to
|
||||
declare only capabilities they use. Revise the saved `create-canvas` prompt's
|
||||
promotion guidance so it describes workspace navigation rather than saying
|
||||
that workspace data always requires promotion. No generated package rewrite
|
||||
is needed.
|
||||
|
||||
## Existing canvas upgrade
|
||||
|
||||
Do not silently widen a retained release. An active task canvas with task-only
|
||||
data scope offers **Enable workspace data** in the existing host action menu.
|
||||
The backend returns a review snapshot of the active release, permission
|
||||
digest, grant generation, current/target data scope, and exact declared
|
||||
permissions. Only a currently authorized workspace owner may confirm it.
|
||||
|
||||
Confirmation rechecks the canvas's task and workspace identity, owner, active
|
||||
release, permission digest, and grant generation inside one transaction. It
|
||||
upserts workspace-ceiling grants only for that release's declared permissions,
|
||||
sets `data_scope_kind=workspace`, increments grant generation, and publishes a
|
||||
single lifecycle refresh after commit. It neither promotes the canvas nor
|
||||
republishes the artifact. On stale review or any failed check it changes
|
||||
nothing. A canceled review has no write. Imported or legacy packages receive
|
||||
no automatic exemption.
|
||||
|
||||
Use the existing canvas HTTP controller's preview/confirm pattern with
|
||||
`GET /api/v1/canvases/{id}/workspace-data-preview` and
|
||||
`POST /api/v1/canvases/{id}/workspace-data`. The request carries the same
|
||||
release ID, permission digest, and grant generation preconditions as promotion.
|
||||
Return an updated canvas projection after success. Keep the action unavailable
|
||||
for pending, archived, removed, already workspace-data, or foreign canvases.
|
||||
|
||||
## Desktop and phone host flow
|
||||
|
||||
Desktop keeps the current canvas panel and action toolbar. The data-scope
|
||||
label sits with existing host metadata, and a legacy canvas exposes the upgrade
|
||||
action from its current actions. Phone keeps the focused canvas route and
|
||||
secondary-action drawer; the same upgrade opens the existing full-height
|
||||
review surface. The header and actions remain fixed while one body region
|
||||
scrolls, with safe-area clearance and touch targets. Both presentations share
|
||||
one review state and backend snapshot; neither relies on canvas-authored UI.
|
||||
|
||||
## Failure and observability
|
||||
|
||||
Denied or stale access review returns the existing safe error style and leaves
|
||||
the active release and old scope usable. A missing task or workspace makes
|
||||
its runtime binding stale. Scope or grant changes invalidate old tokens; the
|
||||
host reloads the runtime through its existing recovery path. Record bounded
|
||||
scope-transition result counters and IDs already allowed for canvas lifecycle
|
||||
logging. Do not log package source, permission bodies, tokens, or task data.
|
||||
|
||||
## Verification strategy
|
||||
|
||||
- Instance-store tests cover null fallback, invalid combinations, transaction
|
||||
rollback, snapshot/backup mapping, and grant-generation invalidation.
|
||||
- Canvas service tests cover version-2 owner authority, exact declarations,
|
||||
legacy review, stale snapshots, owner drift, and promotion without data
|
||||
expansion.
|
||||
- Web-app protocol tests cover list pagination, task read/write, workflow,
|
||||
message, event, dependency projection, foreign-workspace denial, and old
|
||||
task-scoped behavior.
|
||||
- Desktop and mobile Playwright exercise an owner-created task canvas with at
|
||||
least two tasks, refresh before promotion, and an older canvas's explicit
|
||||
access upgrade. The mobile route and review remain touch-usable.
|
||||
|
||||
## Related designs
|
||||
|
||||
- [Canvas lifecycle and promotion](agent-authored-web-apps.md)
|
||||
- [Owner-authorized first publication](local-creation-authority.md)
|
||||
- [Plugin web-app runtime](../../plugins/system-design/isolated-web-app-contributions.md)
|
||||
- [Plugin canvas data-scope runtime](../../plugins/system-design/canvas-workspace-data-scope.md)
|
||||
Reference in New Issue
Block a user