@xpert-ai/plugin-sdk 3.18.7 → 3.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/CHANGELOG.md +123 -0
  2. package/MIDDLEWARE_APPS.md +71 -0
  3. package/README.md +57 -0
  4. package/RESOURCE-CARDS-VALIDATION.md +51 -0
  5. package/RESOURCE-CARDS.md +361 -0
  6. package/TOOL-IMAGES.md +85 -0
  7. package/agent-results.cjs.default.js +1 -0
  8. package/agent-results.cjs.js +20 -0
  9. package/agent-results.cjs.mjs +2 -0
  10. package/agent-results.d.ts +1 -0
  11. package/agent-results.esm.js +4 -0
  12. package/index.cjs.js +586 -162
  13. package/index.esm.js +530 -167
  14. package/model-provider.cjs.js +5 -0
  15. package/model-provider.esm.js +5 -1
  16. package/package.json +8 -2
  17. package/results.cjs.js +50 -0
  18. package/results.esm.js +46 -0
  19. package/runtime-capabilities.md +35 -0
  20. package/src/agent-results.d.ts +2 -0
  21. package/src/index.d.ts +5 -0
  22. package/src/lib/agent/handoff/agent-chat.contract.d.ts +6 -1
  23. package/src/lib/agent/handoff/agent-runtime-message.contract.d.ts +319 -0
  24. package/src/lib/agent/handoff/index.d.ts +1 -0
  25. package/src/lib/agent/index.d.ts +2 -0
  26. package/src/lib/agent/middleware/capabilities/assistant-task.d.ts +55 -20
  27. package/src/lib/agent/middleware/index.d.ts +1 -0
  28. package/src/lib/agent/middleware/model-requirements.d.ts +9 -0
  29. package/src/lib/agent/middleware/strategy.interface.d.ts +4 -0
  30. package/src/lib/agent/middleware/types.d.ts +20 -3
  31. package/src/lib/agent/resource-card.d.ts +3 -0
  32. package/src/lib/agent/runtime/activity.d.ts +6 -0
  33. package/src/lib/agent/runtime/capability.d.ts +37 -0
  34. package/src/lib/agent/runtime/cli-model-profile.d.ts +62 -0
  35. package/src/lib/agent/runtime/dispatch.d.ts +517 -0
  36. package/src/lib/agent/runtime/execution-runner.d.ts +66 -0
  37. package/src/lib/agent/runtime/index.d.ts +10 -0
  38. package/src/lib/agent/runtime/model-execution.d.ts +15 -0
  39. package/src/lib/agent/runtime/results.d.ts +335 -0
  40. package/src/lib/agent/runtime/strategy.d.ts +53 -0
  41. package/src/lib/agent/runtime/task-wait.d.ts +35 -0
  42. package/src/lib/agent/runtime/types.d.ts +156 -0
  43. package/src/lib/ai-model/ai-model-provider.interface.d.ts +2 -0
  44. package/src/lib/ai-model/ai-model.d.ts +2 -0
  45. package/src/lib/ai-model/index.d.ts +3 -0
  46. package/src/lib/ai-model/llm.d.ts +4 -2
  47. package/src/lib/ai-model/native-model.d.ts +22 -0
  48. package/src/lib/ai-model/realtime.d.ts +36 -0
  49. package/src/lib/ai-model/token-usage.d.ts +13 -0
  50. package/src/lib/assistant-capability/index.d.ts +42 -0
  51. package/src/lib/connector/runtime-capability.d.ts +2 -0
  52. package/src/lib/connector/strategy.interface.d.ts +8 -0
  53. package/src/lib/core/context/request-context.d.ts +6 -0
  54. package/src/lib/core/strategy-bus.d.ts +0 -3
  55. package/src/lib/evolution/runtime-capability.d.ts +2 -1
  56. package/src/lib/integration/strategy.interface.d.ts +22 -0
  57. package/src/lib/mcp/app.d.ts +14 -1
  58. package/src/lib/project-task/index.d.ts +66 -0
  59. package/src/lib/project-type/index.d.ts +71 -0
  60. package/src/lib/resource-card-provider/index.d.ts +3 -0
  61. package/src/lib/resource-card-provider/provider.decorator.d.ts +4 -0
  62. package/src/lib/resource-card-provider/provider.registry.d.ts +14 -0
  63. package/src/lib/resource-card-provider/types.d.ts +36 -0
  64. package/src/lib/resource-card.d.ts +6 -0
  65. package/src/lib/runtime/capabilities/index.d.ts +1 -0
  66. package/src/lib/runtime/capabilities/knowledge-graph.d.ts +59 -0
  67. package/src/lib/runtime/capabilities/knowledgebase-documents.d.ts +21 -0
  68. package/src/lib/runtime/capabilities/knowledgebase.d.ts +8 -3
  69. package/src/lib/runtime/capabilities/project-access.d.ts +2 -1
  70. package/src/lib/runtime/capabilities/project-provisioning.d.ts +13 -0
  71. package/src/lib/runtime/capabilities/tool-images.d.ts +24 -0
  72. package/src/lib/runtime/runtime-scope.d.ts +7 -1
  73. package/src/lib/sandbox/execution-environment.d.ts +12 -0
  74. package/src/lib/sandbox/execution.d.ts +13 -0
  75. package/src/lib/sandbox/index.d.ts +1 -0
  76. package/src/lib/sandbox/managed-service.d.ts +1 -0
  77. package/src/lib/sandbox/protocol.d.ts +2 -0
  78. package/src/lib/tool-provider/types.d.ts +6 -0
  79. package/src/lib/types.d.ts +2 -1
  80. package/src/lib/workflow/trigger/strategy.interface.d.ts +2 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,128 @@
1
1
  # @xpert-ai/plugin-sdk
2
2
 
3
+ ## 3.20.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+
9
+ 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.
10
+
11
+ - 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.
12
+ - f5add6a: Remove the ModelExecution per-request input cap and the byte/token comparison from
13
+ Chat, native and bridged CLI requests. Read and discard legacy maxInputTokens in
14
+ persisted policies and grants. Reserve estimated request tokens plus output against
15
+ cumulative budgets; settle using provider usage facts as before.
16
+
17
+ Expose the selected model's catalog context window to CLI profiles instead of deriving
18
+ it from tenant input limits. Custom CLI profiles must migrate from limits.maxInputTokens
19
+ to optional model.contextWindow. Upgrade the host and profiles together and start a new
20
+ execution to regenerate CLI configuration.
21
+
22
+ Remove the extra output cap and fixed Qwen/CodeBuddy turn caps. Use optional catalog
23
+ output metadata for CLI configuration, make execution token budgets explicit opt-ins,
24
+ and distinguish rate/concurrency errors from budget exhaustion. Honor active response
25
+ streams using an inactivity timer, and do not recover live grants as lost workers solely
26
+ because their calls are old. Republished Assistant versions no longer invalidate an
27
+ otherwise authorized execution.
28
+
29
+ - 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.
30
+
31
+ 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.
32
+
33
+ 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.
34
+
35
+ - 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.
36
+
37
+ 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.
38
+
39
+ 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.
40
+
41
+ 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.
42
+
43
+ - 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.
44
+
45
+ ### Patch Changes
46
+
47
+ - 1df94f0: Add version-qualified background CLI profiles for Claude Code 2.1.63, CodeBuddy
48
+ 2.161.1 and Kimi Code 2.1.1. Support an optional literal argv prompt argument in
49
+ the SDK JSONL transport contract. Configure isolated settings and explicit
50
+ permission modes; Kimi advertises only allow because its prompt mode forces
51
+ automatic approval. Keep revisions unchanged for unrelated tools.
52
+
53
+ Execution still requires a matching host transport and Agent Runtime adapter.
54
+
55
+ - bf33018: Make managed background Coding CLI permissions configurable through the existing
56
+ tenant model execution policy, defaulting to allow with per-tool restricted
57
+ overrides. Pin the selected mode in runner receipts and keep evidence-only review
58
+ restrictions. Advertise supported modes in CLI profiles; leave interactive and
59
+ managed shell sessions unchanged.
60
+ - 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.
61
+ - 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.
62
+
63
+ 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.
64
+
65
+ - 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.
66
+
67
+ 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.
68
+
69
+ - 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.
70
+ - 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.
71
+
72
+ 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.
73
+
74
+ - 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.
75
+ - 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.
76
+ - 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.
77
+
78
+ 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.
79
+
80
+ 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.
81
+
82
+ - 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.
83
+ - 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.
84
+ - d81dbe2: Allow Workbench Views to opt into conversation context updates while staying mounted, and connect exact branch and message navigation to ChatKit.
85
+ - 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.
86
+ - Updated dependencies [d18aa7f]
87
+ - Updated dependencies [b86bba1]
88
+ - Updated dependencies [a01cd48]
89
+ - Updated dependencies [bf33018]
90
+ - Updated dependencies [aa33949]
91
+ - Updated dependencies [d4dba33]
92
+ - Updated dependencies [01fd502]
93
+ - Updated dependencies [deff039]
94
+ - Updated dependencies [b66bdcc]
95
+ - Updated dependencies [b86bba1]
96
+ - Updated dependencies [f5add6a]
97
+ - Updated dependencies [c941907]
98
+ - Updated dependencies [c0dd14c]
99
+ - Updated dependencies [00b626e]
100
+ - Updated dependencies [3142346]
101
+ - Updated dependencies [3185f56]
102
+ - Updated dependencies [98a7367]
103
+ - Updated dependencies [d81dbe2]
104
+ - Updated dependencies [a131790]
105
+ - @xpert-ai/contracts@3.20.0
106
+
107
+ ## 3.19.0
108
+
109
+ ### Minor Changes
110
+
111
+ - 99d09ec: Release a coordinated minor update across all Xpert workspace packages, including the API, Web and Bosi applications, shared SDK and contracts, backend and UI libraries, bundled plugins, sandbox runtimes and documentation.
112
+
113
+ ### Patch Changes
114
+
115
+ - 8a78318: Add explicit application Project types, provider-backed domain bindings, and typed Project provisioning/access contracts. App plugins using ProjectTypeProvider require these releases (3.19.0 or newer) and the matching host Project type endpoints/schema migration.
116
+ - Updated dependencies [8a78318]
117
+ - Updated dependencies [1e44173]
118
+ - Updated dependencies [c953822]
119
+ - Updated dependencies [b7983c8]
120
+ - Updated dependencies [08f66e7]
121
+ - Updated dependencies [b62543f]
122
+ - Updated dependencies [5f26e05]
123
+ - Updated dependencies [99d09ec]
124
+ - @xpert-ai/contracts@3.19.0
125
+
3
126
  ## 3.18.7
4
127
 
5
128
  ### Patch Changes
@@ -0,0 +1,71 @@
1
+ # MCP Apps in Agent middleware
2
+
3
+ An `AgentMiddleware` can return `apps` alongside `tools`. It does not need a remote
4
+ MCP server or a published Toolset. The host renders the bundled HTML using its
5
+ existing MCP App sandbox and RPC bridge.
6
+
7
+ ChatKit accesses resources, RPC, approvals and teardown through `/api/ai/mcp-apps`,
8
+ using the AI module's `ApiKeyOrClientSecretAuthGuard`. The ordinary management
9
+ routes keep the platform's standard authorization. Use an SDK version whose
10
+ `client.mcp.apps` targets this AI endpoint.
11
+
12
+ ```ts
13
+ return {
14
+ name: 'ProjectSettings',
15
+ tools: [configure, readSettings, saveSettings],
16
+ apps: {
17
+ definitions: [{ key: 'settings', entry: 'dist/mcp-apps/settings.html' }],
18
+ tools: {
19
+ configure: { resourceKey: 'settings', visibility: ['model', 'app'] },
20
+ read_settings: { visibility: ['app'], approval: 'none' },
21
+ save_settings: { visibility: ['app'], approval: 'none' }
22
+ }
23
+ }
24
+ }
25
+ ```
26
+
27
+ Keys in `apps.tools` must match actual tool names. App-only tools are excluded
28
+ from the model's tool list. `approval: 'none'` is a trusted plugin declaration for
29
+ operations whose own services enforce scope, revision and validation. Omit it
30
+ to retain host approval. App access never grants access to another middleware.
31
+ For decorated providers, use `@XpertToolProvider({ apps: [...] })` and
32
+ `@XpertTool({ middleware: true, app: { ... } })` with the same binding contract.
33
+
34
+ To pause after a successful tool, configure the Assistant:
35
+
36
+ ```yaml
37
+ team:
38
+ agentConfig:
39
+ interruptAfter: [configure]
40
+ ```
41
+
42
+ The completed tool result is checkpointed before a separate gate calls
43
+ LangGraph `interrupt`. Resume targets the gate, so tool side effects are not
44
+ replayed. Ordinary tools display a Continue control; an App sends a standard
45
+ `ui/message` after saving. The host supplies the original tool-call and execution
46
+ identity, and ChatKit uses the existing `action: resume` protocol. No `ui/resume`
47
+ extension is required. The App's message is added once at user priority on resume,
48
+ so the Agent can distinguish the confirmed input from the pre-pause tool result.
49
+ Inline images, audio and binary resources are retained in this message (25 MiB
50
+ combined); arbitrary file paths and remote attachment URLs are rejected. ChatKit
51
+ acknowledges continuation only after the run response supplies `Content-Location`,
52
+ not when the local thread is resolved. Cross-origin hosts must expose that header.
53
+ Error ToolMessages skip this gate so the Agent can repair
54
+ the failure. Prefer calling interactive tools alone rather than mixing them with
55
+ unrelated parallel work.
56
+
57
+ The runtime re-resolves middleware bindings and enabled tools for each App RPC.
58
+ UI teardown retains paused native form snapshots for 7 days; it does not cancel
59
+ the Agent. Business settings must still be persisted by domain services before
60
+ continuation. This requires the host capability `platform.middleware.mcp-apps`
61
+ and the corresponding ChatKit continuation support; it adds no ORM dependency
62
+ to the SDK.
63
+
64
+ On hosts with schema synchronization disabled, apply
65
+ `packages/server-ai/src/mcp-app-runtime/migrations/20260928-middleware-app-audit.sql`
66
+ before enabling native middleware Apps. Their audit rows retain provider identity
67
+ in `source` and leave `toolsetId` null. Interactive ChatKit user sessions are
68
+ accepted only for their bound Assistant; existing user JWT access remains valid.
69
+ An App produced by an external Assistant is also accessible when its persisted
70
+ execution parent chain terminates at the session's entry Assistant in the same
71
+ thread. Each execution remains subject to the normal access check.
package/README.md CHANGED
@@ -115,6 +115,8 @@ For completed operations, `prepareToolResult(() => project(result), () => minima
115
115
 
116
116
  For a host-native MCP App, declare each static HTML bundle once in the Provider's `apps` array, then bind a Tool with `mcp.app.resourceKey` and include `app` visibility. The App key must exist in the same Provider and its entry must be a relative `.html` path inside the packaged plugin. The host publishes the bundle as a `ui://` resource; plugins must not create a stdio server or put CSP/credentials in Tool results.
117
117
 
118
+ Agent middleware can also expose these Apps without a published Toolset. See [middleware Apps and post-tool continuation](./MIDDLEWARE_APPS.md) for `app` bindings and `interruptAfter` checkpoints.
119
+
118
120
  The host owns the public MCP endpoint identity. It combines the plugin's stable `artifactNamespace`, the Provider key, and an opaque scope hash; client names and product-specific identifiers do not belong in the slug. A tenant- or system-level plugin has one tenant-scoped Publication and capability snapshot, while each organization receives an independent access grant and organization-bound credential. An organization-level plugin receives a dedicated organization-scoped Publication.
119
121
 
120
122
  ## View extensions
@@ -154,3 +156,58 @@ their behavior; user identity and Artifact scope checks still apply.
154
156
 
155
157
  These additions require matching host contracts/runtime support and an SDK build
156
158
  containing these interfaces. They are not part of the published SDK 3.18.3 baseline.
159
+
160
+ ## Conversation resource receipts
161
+
162
+ See [RESOURCE-CARDS.md](./RESOURCE-CARDS.md) for the public protocol, tool/middleware emitter, transactional Project provider example, and coordinated release order.
163
+
164
+ ## Project task business types
165
+
166
+ Task providers can register business types without changing task hierarchy, status or ownership:
167
+
168
+ ```ts
169
+ import { ProjectTaskProvider, type IProjectTaskProvider, type ProjectTaskTypeDefinition } from '@xpert-ai/plugin-sdk'
170
+
171
+ @ProjectTaskProvider('example.tasks')
172
+ export class ExampleTasks implements IProjectTaskProvider {
173
+ readonly key = 'example.tasks'
174
+ readonly taskTypes = [
175
+ {
176
+ key: 'example.tasks.illustration',
177
+ presentation: {
178
+ label: { en_US: 'Construction images', zh_Hans: '施工配图' },
179
+ icon: 'Images'
180
+ }
181
+ }
182
+ ] satisfies ProjectTaskTypeDefinition[]
183
+
184
+ async snapshot() {
185
+ return {
186
+ revision: '1',
187
+ tasks: [
188
+ {
189
+ key: 'chapter-images',
190
+ title: 'Prepare construction images',
191
+ kind: 'task' as const,
192
+ taskType: 'example.tasks.illustration',
193
+ status: 'todo' as const,
194
+ predecessorKeys: [],
195
+ executions: []
196
+ }
197
+ ]
198
+ }
199
+ }
200
+ }
201
+ ```
202
+
203
+ 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.
204
+
205
+ 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.
206
+
207
+ `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.
208
+
209
+ 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.
210
+
211
+ ## Tool image references
212
+
213
+ 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`.
@@ -0,0 +1,51 @@
1
+ # Resource Card validation — 2026-09-30
2
+
3
+ ## Implemented behavior
4
+
5
+ - 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.
6
+ - Immediate best-effort scheduler receipt persistence; display errors are logged without changing an already successful creation result.
7
+ - 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.
8
+ - 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.
9
+
10
+ ## Checks completed
11
+
12
+ - 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).
13
+ - 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).
14
+ - 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.
15
+ - Xpert SDK: package build and View Host client tests passed (9 tests).
16
+ - 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.
17
+ - 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`.
18
+ - Platform's temporary parser copy and ChatKit parser produce identical normalized JavaScript.
19
+ - All four repositories passed `git diff --check`.
20
+
21
+ ## Browser evidence
22
+
23
+ `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.**
24
+
25
+ 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:
26
+
27
+ - `chatkit-js/output/playwright/resource-card-zh-light.png`
28
+ - `chatkit-js/output/playwright/resource-card-en-dark.png`
29
+ - `chatkit-js/output/playwright/resource-card-narrow.png`
30
+ - `chatkit-js/output/playwright/resource-card-project.png`
31
+
32
+ ## Runtime/release boundary
33
+
34
+ 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.
35
+
36
+ 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.
37
+
38
+ 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.
39
+
40
+ 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`.
41
+
42
+ 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.
43
+
44
+ ## Project card navigation regression — 2026-09-30
45
+
46
+ 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.
47
+
48
+ - 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.
49
+ - 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`.
50
+ - 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.
51
+ - 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.