@xpert-ai/plugin-sdk 3.19.0 → 3.21.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # @xpert-ai/plugin-sdk
 
+## 3.21.0
+
+### Minor Changes
+
+- c9f9379: Group Knowledge capabilities under `rag/capability` and expose resumable upload sessions through `Documents.uploads`. Support idempotent document imports without automatic processing, plus filename and folder-path search with MIME type filters so unprocessed images remain discoverable.
+
+  Allow organizations to read public tenant libraries while requiring super administrators to explicitly select tenant scope before managing them. Keep document processing behind write-access checks without switching the caller's request scope. Release the SDK and host implementation together for the new upload API.
+
+### Patch Changes
+
+- f76a9c9: Let organization administrators import the official Agent plugins from one Git snapshot with a single button. Reuse existing package versions, isolate package failures, and display import results without granting workspace access. Expose the shared import command for system setup.
+- 82b8db4: Preserve the ENOENT error code when scoped workspace file operations encounter missing files or an uninitialized root. Document the in-process runtime file contract so plugins can distinguish missing files from other failures without interpreting localized messages. Keep path boundaries and HTTP error responses unchanged.
+- Updated dependencies [eecb9fa]
+- Updated dependencies [f76a9c9]
+- Updated dependencies [eecb9fa]
+- Updated dependencies [c5e19d5]
+- Updated dependencies [4b7a346]
+- Updated dependencies [4fff330]
+  - @xpert-ai/contracts@3.21.0
+
+## 3.20.0
+
+### Minor Changes
+
+- a01cd48: Add the realtime voice model capability, model protocol adapter contract, and Bosi voice sessions. Assistant creation and settings can select an independently authorized realtime model and voice. The host relays bounded PCM audio over an authenticated, single-use-ticket WebSocket and dispatches durable Assistant tasks independently of call lifetime. Create the voice tables and timing columns through the platform's existing TypeORM entity synchronization (the schema-sync job in externally managed deployments), and configure allowed renderer origins before enabling calls. No separate realtime voice SQL migration is required.
+
+  Introduce host-owned message envelopes with explicit source, target, correlation, and presentation for voice and future Assistant/Agent messages. Persist them in a dedicated typed `ChatMessage.messageEnvelope` JSONB column. Retain runtime execution, retry and branch history while applying consistent public-history filtering and protecting provenance from client edits. Apply the message-envelope migration before deployment.
+
+- bf33018: Expose optional version-pinned CLI background transports and V2 execution receipts that separate business cwd from managed execution records. Preserve V1 receipts and support bounded runtime reads.
+- f5add6a: Remove the ModelExecution per-request input cap and the byte/token comparison from
+  Chat, native and bridged CLI requests. Read and discard legacy maxInputTokens in
+  persisted policies and grants. Reserve estimated request tokens plus output against
+  cumulative budgets; settle using provider usage facts as before.
+
+  Expose the selected model's catalog context window to CLI profiles instead of deriving
+  it from tenant input limits. Custom CLI profiles must migrate from limits.maxInputTokens
+  to optional model.contextWindow. Upgrade the host and profiles together and start a new
+  execution to regenerate CLI configuration.
+
+  Remove the extra output cap and fixed Qwen/CodeBuddy turn caps. Use optional catalog
+  output metadata for CLI configuration, make execution token budgets explicit opt-ins,
+  and distinguish rate/concurrency errors from budget exhaustion. Honor active response
+  streams using an inactivity timer, and do not recover live grants as lost workers solely
+  because their calls are old. Republished Assistant versions no longer invalidate an
+  otherwise authorized execution.
+
+- c941907: Define versioned Project Task execution specifications, implementation/review purposes, evidence references and distinct invocation receipts. Add host-validated Runtime message provenance, reply metadata, progress observations and shared event/consumption identities.
+
+  This is the contract stage only. Durable Project Task dispatch, outbox/inbox consumers and automatic result delivery are not enabled by these declarations. Deploy compatible contracts, SDK and host before producing the new Runtime envelopes.
+
+  Use the published `@xpert-ai/chatkit-types` 0.11.1 package and declare the contracts package's Zod peer dependency. Host UI package upgrades follow with the live conversation integration.
+
+- 00b626e: Separate Project Task creation from execution and add authorized Runtime discovery, explicit idempotent task dispatch, specification snapshots and task details. Persist attempts and pinned dispatch intents before launching through the existing Invocation runtime; serialize Project execution admission and preserve native handoff behavior.
+
+  Support the built-in Project general agent as an explicit caller/reply identity. Computer invocations from this caller require a binding with an explicit `modelSource` referring to an accessible Assistant in the Project workspace; that Assistant supplies model policy, not caller identity or task ownership.
+
+  Apply `20261006-project-task-runtime.sql` before deploying the host. This stage supports durable dispatch identity and explicit retry/inspection, but does not enable autonomous recovery scanning, reliable result messages, automatic continuation or acceptance workflows.
+
+  Replace the legacy ProjectToolset and its creation command with the built-in `project-tasks` Middleware Plugin. Project general agents load it from the registry; Assistants can configure it through ordinary Plugin nodes and tool preferences. Preserve the six tool names while validating host-owned project/caller scope, localizing tool display metadata, and retaining Invocation status ownership.
+
+- 00db21e: Add optional ResourceCardProvider registration and batched, read-only card resolution to the plugin SDK. Dispatch live conversation card updates through a single host handler with scoped provider lookup, resource identity validation and isolated deadlines. Migrate project task cards to this provider path while keeping unregistered types as saved snapshots. Keep initial project card construction and refreshed presentation together in ProjectTaskCardProvider.
+
+### Patch Changes
+
+- 1df94f0: Add version-qualified background CLI profiles for Claude Code 2.1.63, CodeBuddy
+  2.161.1 and Kimi Code 2.1.1. Support an optional literal argv prompt argument in
+  the SDK JSONL transport contract. Configure isolated settings and explicit
+  permission modes; Kimi advertises only allow because its prompt mode forces
+  automatic approval. Keep revisions unchanged for unrelated tools.
+
+  Execution still requires a matching host transport and Agent Runtime adapter.
+
+- bf33018: Make managed background Coding CLI permissions configurable through the existing
+  tenant model execution policy, defaulting to allow with per-tool restricted
+  overrides. Pin the selected mode in runner receipts and keep evidence-only review
+  restrictions. Advertise supported modes in CLI profiles; leave interactive and
+  managed shell sessions unchanged.
+- d4dba33: Add the Conversation Map data and action services with authorized Assistant-family pagination, visible message search, branch-aware summaries, and typed branch titles. Reuse existing conversation creation, rename, branch, and navigation services, and return the existing side chat on request retries even after its source starts another run.
+- 01fd502: Add the on-demand Conversation Map Workbench View with shared shadcn controls, React Flow layouts, searchable conversation and branch navigation, and host-backed display preferences. Include compact directory rows, content-sized cards, accessible action tooltips, and reproducible source builds.
+
+  Use `agent.workbench` as the canonical Assistant Workbench slot. Normalize legacy `agent.workbench.fixed` and `agent.workbench.main` requests and plugin declarations at the host boundary, preserving authorization and opening preferences without duplicate views.
+
+- deff039: Add persisted conversation Resource Cards, the public emitResourceCard helper and optional transactional Project creation receipts. Cards use typed Workbench navigation without changing file Artifacts. Scheduler creation now emits a receipt and offers an on-demand, authorized detail/edit/history View. ChatKit and Xpert SDK companion releases are required for the UI; publish public contracts/SDK before consuming plugins.
+
+  Opening an Assistant Project target with a View now opens a separately scoped host tab, retaining the current conversation, composer and ChatKit mount. The target Project is authorized independently, and its View scope survives refresh and browser history. Explicit Project selection without a View retains its existing workspace-switch behavior.
+
+- b66bdcc: Add optional invocation activity capture and an independent Coding Execution View. Persist scoped, resumable public CLI activity and private bounded output archives; unify direct runtime cards and project execution navigation without coupling collection to task acceptance.
+- b86bba1: Add execution-scoped model grants, protocol bridges, CLI launchers, budget enforcement, attributed usage settlement and audited reconciliation. Expose the native model SDK and scoped host runner capability, and accept CLI prompt-cache hints without forwarding provider credentials to execution environments.
+
+  Add typed Agent execution results, authorized file delivery and bounded task observation. Preserve background execution during logout, centralize conversation file access, retain explicit Assistant middleware configuration, and allow validated text-only receipts from image-capable tools. Include the API and Web releases required by these shared contracts and runtime changes.
+
+- c0dd14c: Add provider-registered business task types with localized labels and controlled Lucide icon tokens. Persist taskType in the existing type column, preserve legacy values, and resolve presentation independently of hierarchy, status and assignee. Project Tasks list, tree, Gantt, board and detail views share one icon renderer. No database migration is required.
+- 3142346: Support explicit file/archive delivery in project task delegation, pin selections in durable dispatch intents and reject changed selections on replay. Share the delivery schema through contracts while preserving SDK exports. Reject wildcard paths before delegation and retain evidence-only review confinement.
+- 3185f56: Add explicit, revision-bound Project Task acceptance and rework decisions. Bind decisions to the current implementation, specification, and result or Artifact versions; keep retries idempotent and reject completion through generic task updates. Once independent review is requested, acceptance requires the latest valid passing review for that implementation.
+
+  Expose runtime progress, delivery and consumption, review reports, decision history, and authorized human controls in Tasks & Timeline. OS provides the shared review protocol and validation; the current review dispatch gate requires the Computer OpenCode executor supplied by Pro. This batch does not include Computer execution, live conversation streams, or message cards.
+
+  Apply `20261006-project-task-decisions.sql` after the task association and reliable reply migrations. Validation covers local tests and isolated PostgreSQL; it does not represent live model or CLI acceptance.
+
+- 55ec356: Add typed ModelRequest.requirements and mergeModelRequirements for per-call capability requirements, initially supporting ModelFeature.VISION. The host validates and snapshots middleware contributions, unions requirements across the call chain, and checks each invoked model including fallbacks. Required capabilities cannot silently degrade or substitute a static response. Calls without requirements retain existing behavior. Generic multimodal ToolNode support remains deferred.
+- fffb0f4: Add the scoped `ToolImagesRuntimeCapability` for immutable tool image references and temporary verified model input. Bind storage and Artifact access to the current host conversation, enforce complete tool rounds and checksum validation, and keep image bytes out of tool messages and checkpoints. Legacy image-tool history is sanitized only in outbound request copies.
+- d81dbe2: Allow Workbench Views to opt into conversation context updates while staying mounted, and connect exact branch and message navigation to ChatKit.
+- a131790: Add optional message anchors and originating-view preservation to Workbench conversation navigation contracts. The navigation resolver accepts an exact thread and message, validates thread ownership and visible user/assistant message membership, and retains the default thread behavior for older requests. Validate optional anchors at the HTTP boundary before resolving access.
+- Updated dependencies [d18aa7f]
+- Updated dependencies [b86bba1]
+- Updated dependencies [a01cd48]
+- Updated dependencies [bf33018]
+- Updated dependencies [aa33949]
+- Updated dependencies [d4dba33]
+- Updated dependencies [01fd502]
+- Updated dependencies [deff039]
+- Updated dependencies [b66bdcc]
+- Updated dependencies [b86bba1]
+- Updated dependencies [f5add6a]
+- Updated dependencies [c941907]
+- Updated dependencies [c0dd14c]
+- Updated dependencies [00b626e]
+- Updated dependencies [3142346]
+- Updated dependencies [3185f56]
+- Updated dependencies [98a7367]
+- Updated dependencies [d81dbe2]
+- Updated dependencies [a131790]
+  - @xpert-ai/contracts@3.20.0
+
 ## 3.19.0
 
 ### Minor Changes

package/README.md

@@ -156,3 +156,58 @@ their behavior; user identity and Artifact scope checks still apply.
 
 These additions require matching host contracts/runtime support and an SDK build
 containing these interfaces. They are not part of the published SDK 3.18.3 baseline.
+
+## Conversation resource receipts
+
+See [RESOURCE-CARDS.md](./RESOURCE-CARDS.md) for the public protocol, tool/middleware emitter, transactional Project provider example, and coordinated release order.
+
+## Project task business types
+
+Task providers can register business types without changing task hierarchy, status or ownership:
+
+```ts
+import { ProjectTaskProvider, type IProjectTaskProvider, type ProjectTaskTypeDefinition } from '@xpert-ai/plugin-sdk'
+
+@ProjectTaskProvider('example.tasks')
+export class ExampleTasks implements IProjectTaskProvider {
+  readonly key = 'example.tasks'
+  readonly taskTypes = [
+    {
+      key: 'example.tasks.illustration',
+      presentation: {
+        label: { en_US: 'Construction images', zh_Hans: '施工配图' },
+        icon: 'Images'
+      }
+    }
+  ] satisfies ProjectTaskTypeDefinition[]
+
+  async snapshot() {
+    return {
+      revision: '1',
+      tasks: [
+        {
+          key: 'chapter-images',
+          title: 'Prepare construction images',
+          kind: 'task' as const,
+          taskType: 'example.tasks.illustration',
+          status: 'todo' as const,
+          predecessorKeys: [],
+          executions: []
+        }
+      ]
+    }
+  }
+}
+```
+
+Each `taskType` must reference a unique registration prefixed by the owning provider key and a dot. Presentation accepts an `I18nObject` label and a `ProjectTaskIconName` token. Supported icons are `FileText`, `FileScan`, `FileSearch`, `ListChecks`, `ListTree`, `ShieldCheck`, `FilePenLine`, `Workflow`, `Images`, `FolderInput` and `FileOutput`; providers cannot register SVG, HTML, scripts or remote icon URLs.
+
+The host persists this key in the existing task `type` column and resolves presentation from the same provider on graph reads. Omit `taskType` to retain legacy persisted values, or pass `null` to clear it. Existing unknown types retain their identity and receive a structural fallback icon. New projections referencing unregistered types are rejected with a provider diagnostic. Registration changes are reflected on the next graph read without rewriting history.
+
+`kind` still means `task`, `summary` or `milestone`. A task with children keeps its business icon; the separate expand/collapse control represents hierarchy. List, tree, Gantt, board and detail views share the same icon renderer, while status indicators and Assistant avatars retain their own meanings. Titles and execution prompts never determine a task's business type.
+
+Deploy matching contracts, SDK and host support before a plugin starts emitting `taskType`. This is an additive public contract and requires no database migration or historical task rewrite.
+
+## Tool image references
+
+See [TOOL-IMAGES.md](./TOOL-IMAGES.md) for `ToolImagesRuntimeCapability`, reference-only tool results, temporary visual model inputs, execution scope, and recovery rules. Never persist the messages returned by `prepareModelInput`.

package/RESOURCE-CARDS-VALIDATION.md

@@ -0,0 +1,51 @@
+# Resource Card validation — 2026-09-30
+
+## Implemented behavior
+
+- Additive Resource Card protocol, allowlisted targets, stable per-reply deduplication, server-bound identities, streaming/history content, separate reply-bottom rendering and click-only Workbench navigation.
+- Immediate best-effort scheduler receipt persistence; display errors are logged without changing an already successful creation result.
+- Feature-gated scheduler detail View: authorized data/actions, edit/save, pause/resume, execution history and navigation. The View uses existing task services and built Remote Component assets.
+- Optional public Project provider receipts, transactional pending metadata and atomic first-reply delivery. Bid uses platform Project IDs and keeps manual creation/business navigation independent.
+
+## Checks completed
+
+- ChatKit UI: the full suite passed (131 files / 1,240 tests). After navigation restoration and stream tests were added, the focused protocol/card/Workbench/navigation suites passed (57 tests) and the stream/replay suite passed (3 tests).
+- Backend: 20 resource-card/scheduler/delivery tests passed. Existing chat handler plus Project creation/provider suites passed (83 tests), including new receipt assertions. Cloud navigation authorization tests passed (8 tests).
+- Bid: Project provider/creation tests passed (12 tests), plugin build passed, `verify:dist` passed, backend typecheck passed. These consume the sibling built public contracts and plugin-sdk through the existing workspace overrides.
+- Xpert SDK: package build and View Host client tests passed (9 tests).
+- Type checks: ChatKit UI, platform server-ai, Cloud and scheduler Remote Component passed. The broader server regression also passed against the newly built local ChatKit declarations; TypeORM's recursive JSON update boundary was narrowed without weakening the public method contract.
+- Builds: ChatKit types/UI app and library, Xpert SDK, contracts, plugin-sdk and Bid passed. Scheduler and existing project-task Remote Component generated assets passed byte-for-byte freshness checks using `build.mjs --check`.
+- Platform's temporary parser copy and ChatKit parser produce identical normalized JavaScript.
+- All four repositories passed `git diff --check`.
+
+## Browser evidence
+
+`chatkit-js/packages/chatkit-ui/resource-card-preview` builds the actual card renderer, command executor, Xpert SDK client and iframe bridge. It loads verified production scheduler/project-task assets. **The API data and Project session in this fixture are simulated.**
+
+Playwright verified explicit click and keyboard Enter; scheduler edit/save, pause/resume, execution navigation; successive task selections and retained per-task unsaved drafts; browser Back/Forward and refresh; platform Project target opening the existing task timeline. Screenshots were visually inspected for Chinese/light, English/dark, a 430px panel and long titles:
+
+- `chatkit-js/output/playwright/resource-card-zh-light.png`
+- `chatkit-js/output/playwright/resource-card-en-dark.png`
+- `chatkit-js/output/playwright/resource-card-narrow.png`
+- `chatkit-js/output/playwright/resource-card-project.png`
+
+## Runtime/release boundary
+
+The selected local Xpert source environment passed the environment inspector: API readiness at port 3000, Cloud at port 4200, correct checkout provenance, Bid workspace allowlisted. This proves environment health only.
+
+No npm release or production deployment occurred. The platform's installed ChatKit catalog remains 0.7.0; a packaged release must upgrade it to the release containing these companion changes. Bid declares the upcoming contracts/plugin-sdk 3.19.0 baseline and uses local workspace overrides for validation.
+
+On 2026-09-30, at the user's request, Bid 0.4.97 was rebuilt, packed and refreshed in the local Default tenant. The API was restarted from the current Xpert source, and authenticated checks confirmed the plugin was loaded, the Bid View manifest/data and Remote Component entry were available, and the Project middleware tool schemas resolved. The 12 Project tests, `verify:dist`, contracts/plugin-sdk builds and local environment inspector passed. Cloud on port 4200 serves the new card navigation code and uses the existing ChatKit source server on port 5173, where the new card renderer and public parser helpers are available. This is a source development deployment; the host SDK metadata remains 3.18.7 and therefore emits a compatibility warning against Bid's forthcoming 3.19.0 release baseline.
+
+The package and secret-free deployment/runtime receipts are under `/Users/lilinhao/tiwen/.xpert-local-environment/bid-resource-cards-20260930/`. The user test entry is `http://localhost:4200/chat/x/bid-studio-5cb148df/c`.
+
+A real authenticated Agent creating resources through the running platform and PostgreSQL, then navigating in that same deployed Cloud build, has **not** been accepted end to end; the user will perform that acceptance. Transaction/concurrency/rollback tests use repository doubles; the browser evidence above uses fixture APIs. The authenticated deployment smoke checks prove availability of the loaded plugin and its endpoints, not acceptance of the full conversation flow.
+
+## Project card navigation regression — 2026-09-30
+
+The original host path treated an `assistant.project` card with a View as a workspace switch. That cleared the active conversation and first-send Project adoption, dropped the thread from the route, and changed the ChatKit mount binding. Project Views now own an independently authorized `projectScope` on their host tabs. The `viewProject` query parameter restores the View without changing the conversation route; card authorization resolves manifests in the persisted card's target Project scope.
+
+- Seven focused Cloud suites passed: 178 tests covering card authorization, independent Project tabs, first-send adoption, retained conversation/control/mount, runtime scope propagation, stale requests, URL recovery and Back/Forward. Cloud application typecheck and `git diff --check` passed.
+- Actual source environment: authenticated Cloud 4200 + ChatKit 5173 + API 3000 loaded an existing Bid conversation and restored its scoped `platform.project-tasks__timeline` View with the original thread and history present. The real Remote Component loaded the target Project's task panel. Screenshot: `/Users/lilinhao/tiwen/.xpert-local-environment/bid-resource-cards-20260930/project-view-conversation-retained.png`.
+- Browser automation could not reliably activate controls inside the ChatKit iframe (`Click target is no longer available` / unavailable keyboard focus root). The real card-click-and-draft-retention path is therefore **not claimed as browser-verified**; it is covered by the host regression tests and remains a manual acceptance check. No new Agent request or business object was created during this verification.
+- This fix is in Cloud host navigation and is loaded by the local source development server. Bid does not require repacking for this change. No npm publication or production deployment occurred.

package/RESOURCE-CARDS.md

@@ -0,0 +1,361 @@
+# Conversation Resource Cards
+
+A Resource Card is a persisted receipt for a business resource. File Artifacts remain the content/version/sharing model. Creating a scheduler or Project does not create an empty Artifact. A card may include `resource.artifactId` when it represents an existing file Artifact.
+
+## Ownership and lifecycle
+
+| Layer                        | Responsibility                                                                                                                |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Domain service / Runtime     | Commit business changes and execution facts; own authorization, decisions and revisions.                                      |
+| Plugin ResourceCard Provider | Construct the initial card and resolve its current, authorized presentation using the same formatter.                         |
+| Tool / middleware            | Emit the card after the business commit, using the active RunnableConfig.                                                     |
+| Host                         | Persist and bind the card to the actual reply; discover providers, batch refreshes, validate identities and isolate failures. |
+| ChatKit / Workbench          | Render and reconcile generic cards; authorize navigation through the registered View.                                         |
+
+`createCard()` is a plugin-owned typed method, not an additional SDK interface or
+registry operation. Only `resolveMany()` is standardized, and registering a
+Provider remains optional. A static card does not need a Provider. Providers
+format and read facts; they do not become the owner of business state.
+
+```mermaid
+flowchart LR
+  D[Committed domain result] --> P[Provider.createCard]
+  P --> E[emitResourceCard]
+  E --> M[Host binds and persists message card]
+  M --> C[ChatKit generic card]
+  A[Thread activity subscription] --> H[Host refresh command / registry]
+  H --> R[Provider.resolveMany]
+  R -. reuses formatter .-> P
+  R --> S[Host validates read projection]
+  S --> C
+```
+
+## Emit after a successful tool mutation
+
+```ts
+import { emitResourceCard } from '@xpert-ai/plugin-sdk'
+
+const task = await tasks.create(input)
+try {
+  await emitResourceCard(
+    {
+      resource: { namespace: 'platform', type: 'scheduled-task', id: task.id },
+      title: task.name,
+      description: `${task.scheduleDescription} · ${task.timeZone || 'UTC'}`,
+      icon: { type: 'emoji', value: '◷' },
+      open: {
+        target: 'workbench.view',
+        viewKey: 'platform.scheduler__detail',
+        selectionId: task.id
+      }
+    },
+    runnableConfig
+  )
+} catch (error) {
+  logger.warn('Task created; resource receipt delivery failed', error)
+}
+return task
+```
+
+Tools, middleware and plugin code can use the same helper inside an active Agent run. Pass its RunnableConfig to preserve callback context. The helper dispatches `ON_CHAT_EVENT`; the host binds the actual reply and execution, normalizes to a `MESSAGE` event and persists `type: 'resource_card'` content before forwarding. Emitters cannot choose message ownership. A presentation failure must not report a committed business mutation as failed or trigger another creation.
+
+`resource.namespace + resource.type + resource.id` identifies the receipt **within a single reply**. Re-emitting replaces its snapshot at the same position. Other replies keep their own snapshots. The canonical part ID is produced by `resourceCardId`; callers should not concatenate an ID themselves. Text extraction and model history exclude these parts. Branches retain the content with their owning messages, and history loading never triggers navigation.
+
+Targets are an allowlisted JSON protocol:
+
+- `workbench.view`: required `viewKey`, optional `selectionId`, optional `parameters` containing scalars or scalar arrays.
+- `assistant.project`: additionally requires the **platform Project ID** in `projectId`, and a `viewKey`.
+- `workbench.file`: required `viewKey`, `fileKey` and `targetId`; opens a file preview with an original-file download action. Optional `previewFile` supplies a separate preview reference.
+
+Targets cannot contain URLs, scripts or arbitrary client commands. Icons use the existing sanitized SVG, emoji or font renderer. Navigation and resource queries still pass through the host's View availability and access checks. An unavailable Workbench, missing View or denied/deleted resource produces feedback instead of an automatic fallback.
+
+By default the card title/description is a snapshot. Opening loads current business state. Types that register the optional ResourceCard Provider below opt in to live refresh while a conversation is observed. Explicit scheduler-card navigation remembers the selected task per conversation and supports browser refresh/back/forward.
+
+## Optional live resource state
+
+Plugins can opt exact resource types into live refresh with `ResourceCardProvider`
+and `IResourceCardProvider`. Existing emitters need no change. Register the class
+in the plugin module's `providers`; the host discovers it through the existing
+StrategyBus lifecycle. Do not register a CQRS handler or a registry in the plugin.
+
+```ts
+import { Injectable } from '@nestjs/common'
+import type { ConversationResourceCard } from '@xpert-ai/contracts'
+import {
+  ResourceCardProvider,
+  type IResourceCardProvider,
+  type ResourceCardContext,
+  type ResourceCardReadRequest,
+  type ResourceCardResolution
+} from '@xpert-ai/plugin-sdk'
+
+@Injectable()
+@ResourceCardProvider({ namespace: 'my-plugin', type: 'report' })
+export class ReportCardProvider implements IResourceCardProvider {
+  constructor(private readonly reports: ReportsService) {}
+
+  createCard(report: { id: string; title: string; description: string }): ConversationResourceCard {
+    return {
+      resource: { namespace: 'my-plugin', type: 'report', id: report.id },
+      title: report.title,
+      description: report.description,
+      open: { target: 'workbench.view', viewKey: 'my-plugin__reports', selectionId: report.id }
+    }
+  }
+
+  async resolveMany(
+    context: ResourceCardContext,
+    requests: readonly ResourceCardReadRequest[]
+  ): Promise<ResourceCardResolution[]> {
+    // ReportsService is the plugin's domain service. This read must enforce
+    // tenant, organization, user and resource access and honor context.signal.
+    const summaries = await this.reports.readAuthorizedSummaries(context, [
+      ...new Set(requests.map(({ card }) => card.resource.id))
+    ])
+    return requests.map(({ key, card }) => {
+      const summary = summaries.get(card.resource.id)
+      return summary === undefined
+        ? { key, status: 'unavailable', reason: 'forbidden' }
+        : {
+            key,
+            status: 'resolved',
+            card: this.createCard({ id: card.resource.id, title: card.title, description: summary })
+          }
+    })
+  }
+}
+```
+
+The decorator accepts multiple `{ namespace, type }` arguments. Each pair belongs
+to one provider owner across installation scopes; another plugin cannot shadow
+it. Same-plugin instances follow the existing organization, tenant, system and
+builtin scope resolution. Refresh/uninstall removes that installation's routes.
+
+Keep initial card construction in the same provider (for example, a typed
+`createCard()` method), and reuse it from both tool receipts and `resolveMany()`.
+Creation inputs belong to the plugin; the SDK only standardizes the optional
+refresh contract. Tools remain responsible for emitting the returned card with
+`emitResourceCard(provider.createCard(committedResult), runnableConfig)` after
+the business commit, and isolating emission failures as in the first example.
+
+The host calls `resolveMany` once per matched provider per snapshot, only for
+cards already present in the authorized conversation. Context identity comes
+from the host; `projectId` is optional. Requests include persisted message and
+execution bindings for resources that require those association checks. Echo
+`key` unchanged and return one result per request, including repeated resources
+in different messages. Missing resources return `not_found`; denied resources
+return `forbidden`. Do not return private diagnostics in presentation data.
+
+Providers only read durable business state. Do not start jobs, decide acceptance,
+write message history or poll a Computer CLI for each viewer. Use batched reads.
+The host applies a two-second deadline and abort signal per provider, validates
+returned card/resource identities, and supplies the original message bindings.
+Invalid, missing, duplicated or failed responses receive a generic refresh
+failure description; unavailable results receive a localized unavailable
+message. Other providers and run discovery continue. Ignore late results and
+honor the abort signal in cancellable I/O; the host cannot forcibly stop plugin
+code or an uncancellable database call.
+
+Live projections are viewer-specific and do not rewrite stored receipts or
+create new cards. Removing the provider falls back to the saved receipt; clicking
+still uses the View's access checks. Card navigation and result payloads keep the
+existing ChatKit protocol. The updated ChatKit UI displays all committed cards
+during streaming, without business-namespace-specific presentation branches.
+
+The host has one `RefreshConversationResourceCardsCommand` handler in the message
+module. `ThreadActivityService` supplies references; the handler dispatches
+through `ResourceCardProviderRegistry`. The built-in Project Task Provider uses
+this same path and retains its task, invocation and pinned-review checks.
+
+## Implemented scope and release boundary
+
+The optional Provider path covers creation, persisted message binding, scoped
+registration/replacement/removal, authorized batched refresh, failure isolation
+and generic ChatKit display/navigation. `ProjectTaskCardProvider` is the built-in
+implementation: delegation and refresh both call its `createCard()`; task
+creation emits only a tool step, and each implementation/review attempt emits
+its own execution card. Runtime success is distinct from business acceptance.
+
+This is not a custom React/component extension API. A plugin supplies the shared
+card data and a registered View target. Independent execution viewers remain
+separate features. Activity currently polls full snapshots; there is no generic
+card outbox, pagination or reconstruction of missing historical receipts.
+Transactional first-conversation Project receipts below have their own durable
+attachment mechanism; ordinary `emitResourceCard` does not inherit it.
+
+Deploy the updated host/plugin SDK and matching ChatKit app assets together.
+Local builds or copied app assets do not publish npm packages. After deployment,
+reload the host once, then test a fresh delegation without refreshing during
+execution: one card appears, its status updates, and the resumed Agent reply
+streams automatically. Test Provider registration/refresh/removal with a
+non-project fixture separately; a Project Task run alone does not prove an
+external plugin's installation lifecycle.
+
+## Composable content and image groups
+
+Use the optional `content` array to compose ordered presentation blocks inside one resource card. Each block can have a `title`:
+
+| Kind            | Items                         | Presentation                                                        |
+| --------------- | ----------------------------- | ------------------------------------------------------------------- |
+| `image-gallery` | `images: ResourceCardImage[]` | One responsive row initially; More expands the remaining images.    |
+| `file-list`     | `files: ResourceCardFile[]`   | File titles, optional descriptions and authorized download actions. |
+| `fields`        | `fields: ResourceCardField[]` | Read-only label/value pairs.                                        |
+
+For example, add this `content` property to the card passed to `emitResourceCard`:
+
+```ts
+content: [
+  { kind: 'fields', fields: [{ label: '状态', value: '已完成' }] },
+  {
+    kind: 'image-gallery',
+    title: '施工配图',
+    images: [
+      {
+        id: 'site-layout',
+        title: '施工现场平面布置图',
+        alt: '施工分区、出入口和运输路线',
+        file: {
+          viewKey: 'bid.view-provider__bid.studio',
+          fileKey: 'bid-project-image',
+          targetId: `${projectId}:${assetVersionId}`
+        }
+      }
+    ]
+  }
+]
+```
+
+New producers emit `content`, not top-level `images`. The reader converts historical top-level `images` only when `content` is absent. Image and file IDs must be unique within their block. The parser accepts up to 32 blocks and 100 items per block; these are transport bounds, not business image quotas. Invalid or unknown blocks are skipped independently.
+
+Reference committed, immutable file versions. The View must declare the file key and implement its authorized resolver. Image previews require the `preview` purpose; download actions require `download`. Do not store signed URLs, private file paths, credentials or base64 pixels in a card.
+
+ChatKit resolves visible thumbnails through the SDK View file-access session/grant API, reads authorized bytes and releases the session. Collapsed images are loaded only after expansion. Clicking an image opens a file preview with its own URL lifetime and an original-file download action. Failed previews can be retried without rerunning the business tool.
+
+Committed cards appear as soon as their events arrive, including while the Assistant reply is streaming. Later events upsert the same card instead of adding duplicates. Cards render independently of text message bubbles and remain available in history.
+
+The stream mapper binds an external Assistant's actual execution from runtime metadata; the root reply owns persistence. External Assistant transcripts retain cards for that execution and its descendants without counting them as tools or process steps. Plugins cannot supply either owner identity in the card payload.
+
+For Bid, `bid_submit_role_task` emits one group only after the illustration task is accepted, including native writing and queued post-writing tasks. Repeated submissions upsert the same group in the current reply. Unaccepted candidates and omitted needs are excluded. An emission failure never changes the accepted submission result.
+
+This extension requires coordinated ChatKit types/UI and host contracts/SDK/server updates before deploying a consuming plugin. Source tests do not upgrade installed packages.
+
+## File preview and original download
+
+Use `workbench.file` for an exported document's Open action. It opens the file preview rather than the business View:
+
+```ts
+open: {
+  target: 'workbench.file',
+  viewKey: 'bid.view-provider__bid.studio',
+  fileKey: 'bid-export-docx',
+  targetId: exportVersionId,
+  previewFile: {
+    viewKey: 'bid.view-provider__bid.studio',
+    fileKey: 'bid-export-preview-pdf',
+    targetId: exportVersionId
+  }
+}
+```
+
+`previewFile` is optional and uses the same `{ viewKey, fileKey, targetId }` reference shape. It can point to a derived PDF for a DOCX original. The preview and original download are authorized independently; Download always resolves the original reference. An unavailable preview can be retried without disabling Download. A resource card itself never grants file access.
+
+Workbench navigation and file access are separate capabilities. If tabs are unavailable, a host can still provide authorized inline images and downloads. Leaving the runtime scope cancels pending file access and closes scoped file previews.
+
+## Transactional first-conversation Project receipts
+
+Implement the public `IProjectTypeProvider.createForConversation` interface and return optional `resourceCards` along with the managed state:
+
+```ts
+async createForConversation(context, input) {
+  const bid = await input.transaction.save(makeBid({
+    platformProjectId: input.projectId,
+    title: input.name
+  }))
+  return {
+    name: bid.title,
+    status: 'active',
+    viewKey: 'bid__projects', // Existing business entry remains independent.
+    selectionId: bid.id,
+    resourceCards: [{
+      resource: { namespace: 'platform', type: 'project', id: input.projectId },
+      title: bid.title,
+      open: {
+        target: 'assistant.project',
+        projectId: input.projectId,
+        viewKey: 'platform.project-tasks__timeline'
+      }
+    }]
+  }
+}
+```
+
+The host validates the target against `input.projectId`. It stores pending receipts in `Project.settings.conversationBootstrap` in the same transaction as the business write and conversation binding. `ProjectResourceCardService` locks the Project, then atomically updates the first Assistant message and `resourceCardMessageId`. Streaming begins after commit. A failed attachment leaves a pending receipt; competing first sends claim it once. Manual Project creation has no conversation receipt.
+
+Do not emit directly inside the creation transaction: an event would escape a rollback. Plugins returning no receipts keep existing behavior.
+
+## Scheduler example
+
+`SchedulerAgentMiddleware` declares the `scheduler` Feature. `SchedulerDetailViewProvider` contributes the on-demand `platform.scheduler__detail` View using the built Remote Component assets. Its selection is the stable task ID. Data/actions call existing task access, update, pause and resume services; execution navigation verifies the conversation belongs to that task. Existing cron parsing and other scheduler tools are unchanged.
+
+While the detail View stays open, switching tasks retains each unsaved form draft in memory. Saving commits through the existing service; drafts are not background-saved or polled.
+
+Build assets with:
+
+```sh
+corepack pnpm exec tsc -p packages/server-ai/src/xpert-task/remote-components/scheduler-detail/tsconfig.json --noEmit
+node packages/server-ai/src/xpert-task/remote-components/scheduler-detail/build.mjs
+node packages/server-ai/src/xpert-task/remote-components/scheduler-detail/build.mjs --check
+corepack pnpm remote-view:preview --config packages/server-ai/src/xpert-task/remote-components/scheduler-detail/preview.config.mjs --port 4325
+```
+
+The preview explicitly uses fixture data, not a live scheduler.
+
+## Coordinated dependency rollout
+
+1. Build/release ChatKit types and Xpert SDK message contracts.
+2. Build/release ChatKit UI and wrappers together. Verify the iframe assets contain `resource_card` handling.
+3. Update the platform's single ChatKit catalog and relevant dependency lockfiles to those published versions, then build/release platform contracts and plugin-sdk against them.
+4. Build Bid against that public plugin-sdk (no local decorator/interface shim), run `verify:dist`, then deploy the matching host and plugin.
+
+This change prepares changesets; it does not publish packages or deploy production. Platform contracts re-export the protocol from `@xpert-ai/chatkit-types`; plugin-sdk re-exports those contracts. Building local source does not publish packages or update the platform's pinned dependencies. Verify the installed release supports `content` blocks and `workbench.file` before deploying consumers. Local Bid workspace overrides may resolve sibling builds; do not describe a source alias or preview as a deployed package upgrade.
+
+Existing message JSON is additive and needs no migration, new Artifact table or historical backfill.
+
+## Agent task results
+
+Browser views import result schemas and types from `@xpert-ai/plugin-sdk/agent-results`.
+This public entry only exports portable result contracts and Zod validation; the SDK root also exports server dependencies.
+Do not reach into another package's `src` directory or import the server SDK root from a browser bundle.
+
+`emitResourceCard(card, runnableConfig)` emits the existing ChatKit `resource_card` contract. It does not create an Artifact or grant access to one. Emit after the referenced business object has been committed.
+
+```ts
+await emitResourceCard(
+  {
+    resource: { namespace: 'my-plugin', type: 'report', id: report.id },
+    title: report.title,
+    open: { target: 'workbench.view', viewKey: 'my-plugin__reports', selectionId: report.id }
+  },
+  config
+)
+```
+
+Use stable namespace/type/id values. Repeated observations update the same card in the current reply. The host supplies `messageId` and `executionId`, persists the card, and excludes it from model/transcript text. Callers cannot choose another reply. The registered View must recheck authorization on every read and file download. Do not put credentials, arbitrary URLs, commands, or private paths in navigation parameters.
+
+Task results use the provider-neutral `AgentResultItem` union: analysis, changes, tests, and explicitly declared file deliverables. File delivery defaults to `none`; `files` exports only the declared files and `archive` packages only an explicit selection. Export failure is recorded separately from task execution. A card for an exported artifact refers to the committed artifact and opens the authorized task results View.
+
+New artifact references must include the committed `versionId`. The task-results View will not download older references without a pinned version: falling back to the current artifact version could deliver unrelated later content. Such task results remain readable.
+
+Middleware using the host task-results View declares `AGENT_TASK_RESULTS_FEATURE` in `meta.features`. The View uses `AGENT_WORKBENCH_SLOT`, opens on demand, and declares support for selection and parameter queries. Other plugins should register their own governed View and feature; emitting a card alone does not activate a View.
+
+Local rollout requires the matching ChatKit types/UI with resource-card support, then host contracts/SDK/server, then consuming plugins. Building a local SDK does not publish a new registry package.
+
+`api:build` builds the task-results browser bundle before copying its assets. For a source-run API, first run `corepack pnpm nx run api:build-agent-results`. Generated `app.js` and `app.css` are ignored; commit the source and build configuration only.
+
+## Coding invocation cards and activity
+
+The built-in `platform.agent-invocation/execution` provider owns direct Coding invocation card creation and refresh. Runtime middleware requests the card through the optional `AgentInvocationApi.getResourceCard()` after start. Project dispatch keeps its existing `platform.project-tasks/execution` identity and does not emit a second generic card.
+
+The card opens `platform.coding-execution__execution` with the exact invocation ID. Public CLI activity is written through the optional Runtime `context.activity` recorder and queried by the View provider. Resource-card refresh contains only presentation/state/target updates; it does not transport command output or invoke a CLI. Final summary cards are suppressed only when a Coding execution card already covers the run; independently delivered files retain their own cards.
+
+See [Coding Execution View](../server-ai/src/agent-invocation/execution-view/README.md) for the capability, authorization, storage, retention and navigation contract.