@jskit-ai/agent-docs 0.1.205 → 0.1.207

package/guide/agent/app-extras/assistant-conversation.md

@@ -1485,8 +1485,37 @@ does not abort that newer input. Owned executor failure stops its still-current
 native turn; Stop and disposal drain and close
 only its private bridge under the original owner. Unconfigured bound and scoped
 conversations retain their original behavior. These source tests do not establish
-an application's composition or installed/native acceptance. Bound Claude
-application-tool dispatch remains unavailable.
+an application's composition or installed/native acceptance.
+
+An opted-in supplied Claude conversation uses its original retained owner/store
+and SDK MCP control pipe. The owner exposes `applicationToolsSupported: true`;
+that capability does not authorize an application action. Its configured command
+is attached before native process configuration. The host must expose the same
+application SDK declaration through `process.configure` using the owner's tool
+schemas, without selecting standalone execution-release or isolated policy.
+Original native ACK, canonical admission/publication and the common accepted
+request callback precede tool effects. Each call matches the exact recorded
+native tool-use ID, name, arguments and originating accepted message. Optional
+supplied-owner checks at the same executor boundary refuse retired input before
+execution and report only a still-current owned executor failure through the
+original Stop/drain path. Already invoked old work cannot fail a later accepted
+input. The common ordered tool-work catch attributes a failure only to its
+still-current Claude request; prior action error receipts and once-only execution remain
+unchanged. This successor-query exception is specific to Claude. Codex retains
+its active-turn failure guard across steering: an unconfirmed application effect
+cannot be reported as a successful turn, even if an answer has arrived.
+The original retained-turn reader's opt-in current mode requires the exact
+live process, account, command and native tuple; its default retained/history
+projection is unchanged. Stop and completion join existing tool work; clearing custody leaves the original supplied
+process/storage lifecycle intact. Unconfigured supplied conversations keep their
+original behavior.
+
+`claudeCodeArguments({ applicationTools: true })` adds the existing SDK MCP config
+also for normal Claude execution. It does not change native source tools or
+permission defaults; existing tool-free and isolated branches are unchanged.
+Applications still supply exact action authorization, native instruction/account
+configuration and checkpoints. Source/component proofs do not establish a host's
+installed or real CLI/application acceptance.
 
 Such a server integration may open a handle with `representation: "native"` when
 its existing command contract requires the original result. The option belongs
@@ -1776,6 +1805,13 @@ selecting that segment's engine; recovery never revives a rewound turn. Neither
 inspection nor reopening sends the message again. If native process cleanup fails,
 the handle reports unavailable and rejects new work; `cancel()` retries that exact
 owned cleanup rather than starting another process.
+Claude streaming startup can fail after the host admits an execution but before
+it returns a stream. The adapter preserves that execution identity and the host's
+actual cleanup proof; a rejected startup never supplies a successful stop proof.
+Unconfirmed cleanup retains the identity through the existing native binding for
+Stop/recovery. If binding publication also fails, the original startup failure and
+in-memory custody remain, with the persistence error in `bindingError`; durable
+restart recovery is not established until that binding can be saved.
 An optional `limits.timeoutMs` deadline aborts work and waits for owned cleanup;
 a failed cleanup is still reported as unavailable rather than as a successful stop.
 
@@ -2838,6 +2874,19 @@ An exact native acknowledgement ends its ACK deadline before the admission
 writer runs; a slow write remains awaited, and a rejected write rejects admission.
 A missing acknowledgement remains uncertain. Native failure-result text stays
 in the turn's error rather than becoming an assistant answer.
+The retained owner also exposes
+`readFinalAssistantResult(contextKey, conversationId, turnId)` for a trusted host
+that returns its canonical turn from a successful complete-message publication.
+This synchronous lookup clones the current native receipt; it does not acquire
+a conversation, read history, resume, or resend work. It requires the exact
+current context, conversation, turn, accepted input, process, execution and account,
+and successful native settlement after pending commands and background tasks.
+The receipt becomes readable before the original before-state checkpoint; a
+failed publication or checkpoint invalidates it. Default event sinks and saved
+completion metadata cannot supply this proof. New input, steering, account
+changes, interruption and cleanup invalidate it. Pending or failed native Stop
+cannot revive an older receipt. This optional getter preserves existing storage,
+checkpoint and cleanup behavior; the host still owns question or grading policy.
 The turn owner preserves the production receiver's block lifecycle: deltas are
 temporary, block-stop removes them, and completed snapshots use their native
 UUIDs. It does not group distinct history snapshots into a synthetic reply.

package/guide/agent/app-setup/multi-homing.md

@@ -39,6 +39,35 @@ before an operation discloses records or record existence.
 membership semantics exactly; do not synthesize memberships to compensate for
 a policy/runtime mismatch.
 
+## Role display labels
+
+Set optional `label` strings in the existing `roleCatalog.roles` definitions,
+usually exported by `config/roles.js` and composed into application config.
+For example, the package-owned `workspaces/workspace-server` example labels
+`admin` as **Administrator** and `member` as **Team member**. Any application
+role id can have its own label.
+
+Labels are trimmed; missing, blank or non-string labels use the previous
+display fallback. Labels do not inherit. They survive catalogue creation,
+cloning and descriptor listing, and the Members, Invitations and Workspace
+Settings API response schemas preserve them. Descriptors have optional
+`label`; pending/resolved invitation and workspace-list records have optional
+`roleLabel` beside `roleSid`.
+
+On **Members**, both the invitation **Role** selector and each member's role
+selector display configured labels. Choose a label, enter the invite email
+and select **Send invite**, or choose a member's new role. Requests and stored
+memberships still use role ids. Reloading shows the selected role's label.
+Pending invitation captions, workspace role captions and the default
+invitation email use configured labels too. Custom email renderers receive
+optional `roleLabel` in addition to `roleSid`.
+
+Add labels without changing existing permissions, inheritance, assignability
+or `workspace.defaultInviteRole`. This supports application-specific and
+Training roles without renaming them. `owner` is never assignable. An
+application whose default invitation role is `worker` keeps that default even
+if its display label is **Member**. No database migration is needed.
+
 ## Transactional invitation participation
 
 Use `workspaces.core` to connect application records during the built-in

package/guide/agent/framework/crud-operations.md

@@ -47,6 +47,168 @@ Add resource service methods with `decorateService`; expose commands such as
 services and hooks orchestrate. Use a transactional outbox for durable
 external work.
 
+## Choose ownership, API access and client access independently
+
+These controls answer different questions:
+
+| Control | Purpose | Public records | Owner-scoped records |
+| --- | --- | --- | --- |
+| Resource `autofilter` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
+| Resource `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
+| Feature `ownershipFilter` | Server route/action ownership scope | `"public"` | `"user"` |
+| Client `access` | Whether to require bootstrap permissions | Default `"auto"` with no permission requirements | Default `"auto"`; declare permissions when required |
+
+`access` accepts `auto`, `always`, or `never`, not `public`. With `auto`, a
+screen with no permission requirements does not require a permissions bootstrap.
+`always` does require it. Do not add authentication or workspace machinery to
+compensate for an unnecessary `always` override. Server access and ownership
+remain authoritative.
+
+The Books source patterns demonstrate user ownership. For an intentionally
+public create/list resource, use the same patterns with this resource contract:
+
+```js
+const bookResource = defineCrudResource({
+  namespace: "books",
+  tableName: "books",
+  apiAccess: "public",
+  autofilter: "public",
+  crudOperations: ["list", "view", "create"],
+  schema: {
+    title: {
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: 255,
+      operations: {
+        output: { required: true },
+        create: { required: true }
+      }
+    }
+  }
+});
+```
+
+Import `defineCrudResource` from
+`@jskit-ai/resource-crud-core/shared/crudResource`. Its app-owned migration
+creates `books` with an integer primary key `id` and non-null `title`; omit
+`userId` and its foreign key for this public variant. `list` requires `view`
+in the shared resource contract, even when the UI has no detail page. A create
+response uses the resource output contract. Keep operation names such as
+`list`, `view` and `create`; do not invent output-operation aliases.
+
+Bind `defineCrudJsonApiFeature()` with this resource, `ownershipFilter:
+"public"`, `relativePath: "/books"` and the application's configured public
+surface. Keep the existing package/provider and migration registration from
+`crud/json-api-resource-package`.
+
+For the list, keep `BookListPage.vue` thin: use `resourceNamespace: "books"`
+in `useCrudListScreen()` on the configured public surface, remove unsupported
+edit/delete actions and optional author/notes filters, and point **New** to
+the create route. For the new page, use the title field only and set:
+
+```js
+addEditOptions: {
+  apiSuffix: "/books",
+  ownershipFilter: "public",
+  queryKeyFactory: (surfaceId = "") => ["crud", "books", surfaceId, "new"],
+  readEnabled: false,
+  writeMethod: "POST",
+  listUrlTemplate: "/books"
+},
+saveSuccess: {
+  invalidateQueryKey: ["crud", "books"],
+  navigateToView: false,
+  listUrlTemplate: "/books"
+}
+```
+
+List/view screen wrappers derive request scope from the configured surface;
+they do not expose an `ownershipFilter` option. Use a surface without workspace
+route parameters for this public example. Form options and lower-level request
+composables accept `ownershipFilter` explicitly.
+
+New/Edit form runtimes require `queryKeyFactory` even with reads disabled.
+For editing, include the reactive record id; for workspace-scoped resources,
+include the route scope too. List/view screen wrappers derive standard keys
+from `resourceNamespace`. Leave `access` at its default when no permissions
+are declared. Verify create, list, blank-name rejection and reload persistence
+without signing in for this public variant; owner-scoped variants additionally
+need cross-owner denial tests.
+
+## Save navigation
+
+`useCrudAddEditScreen()` accepts `saveSuccess` at the top level. After saving,
+the default behaviour invalidates `saveSuccess.invalidateQueryKey`, navigates
+to a configured record-view URL when one resolves, and otherwise falls back to
+the list URL. For a create-and-list app, use `navigateToView: false` and the
+configured `listUrlTemplate`, as in the public example above. The list URL may
+also come from `addEditOptions.listUrlTemplate`.
+
+To keep the saved form open, set both `saveSuccess.navigateToView` and
+`saveSuccess.navigateToList` to `false`. `addEditOptions.onSaveSuccess` replaces
+the default success handling, including query invalidation and navigation;
+reserve it for custom success behaviour. Returning to the list needs only the
+documented `saveSuccess` options, not a custom router callback or inspection of
+the shared form implementation.
+
+## Browser routes and responsive lists
+
+`newUrlTemplate`, `viewUrlTemplate`, `editUrlTemplate`, `listUrlTemplate`, and
+`cancelTo` describe browser routes, not surface-relative API suffixes. Include
+the configured surface prefix: if a public library lives at `/library`, its new
+page is `/library/new` and its list is `/library`, not `/new` and `/`. For links
+without record placeholders, `paths.page()` can resolve the configured surface;
+for record placeholders use the current CRUD runtime's `resolveParams()`.
+Request-scope inference does not add missing prefixes to browser links.
+
+`CrudListScreen` uses `createLabel` for its toolbar, empty-state and compact
+create actions. Its card and table layouts coexist in the DOM, with CSS choosing
+the visible layout. Browser assertions on record text must select the visible
+match, for example `page.getByText(title, { exact: true }).filter({ visible: true })`.
+When the same create action appears in more than one visible location, choose
+one visible action deliberately; do not relax the expected label to accept an
+unrelated fallback.
+
+## Direct API tests use JSON:API documents
+
+JSKIT's CRUD screens and HTTP client apply the resource's JSON:API transport
+automatically. Direct Playwright `request` calls and other raw HTTP clients must
+supply that transport themselves. An ordinary JSON body such as `{ title }`
+with `Content-Type: application/json` does not test field validation on a
+JSON:API route; it is rejected as an unsupported media type (HTTP 415).
+
+Use the application's actual API base and scope, not its page URL. For the
+public Books resource above, with API base `/api` and transport type `books`:
+
+```js
+const headers = {
+  "Content-Type": "application/vnd.api+json",
+  Accept: "application/vnd.api+json"
+};
+const response = await request.post("/api/books", {
+  headers,
+  data: {
+    data: {
+      type: "books",
+      attributes: { title: "Kindred" }
+    }
+  }
+});
+expect(response.status()).toBe(201);
+const document = await response.json();
+expect(document.data.attributes.title).toBe("Kindred");
+```
+
+Keep the same headers and `data.type/attributes` envelope when testing invalid
+field values; for this contract, an empty `title` or one over 255 characters
+should return HTTP 400. Raw responses contain fields under `data.attributes`,
+while the shared client simplifies resource responses. A collection response
+has an array in `data`. Match `data.type` to the configured resource transport;
+retain the application's existing identity and CSRF fixture for protected APIs.
+Prefer the shared resource client for application requests rather than copying
+this raw test encoding into page code.
+
 ## Record deletion
 
 Deletion requires an explicit shared `DELETE` operation and confirmation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.205",
+  "version": "0.1.207",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.233",
+    "@jskit-ai/kernel": "0.1.235",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.233",
+    "@jskit-ai/kernel": "0.1.235",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,13 +42,13 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.231",
+    "@jskit-ai/http-runtime": "0.1.233",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.230",
-    "@jskit-ai/jskit-catalog": "0.1.258",
+    "@jskit-ai/config-eslint": "0.1.232",
+    "@jskit-ai/jskit-catalog": "0.1.260",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.233",
+    "@jskit-ai/kernel": "0.1.235",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,15 +42,15 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.231",
+    "@jskit-ai/http-runtime": "0.1.233",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.237",
+    "@jskit-ai/shell-web": "0.1.239",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.230",
-    "@jskit-ai/jskit-catalog": "0.1.258",
+    "@jskit-ai/config-eslint": "0.1.232",
+    "@jskit-ai/jskit-catalog": "0.1.260",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.233"
+    "@jskit-ai/kernel": "0.1.235"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/ui-testing.md

@@ -21,6 +21,13 @@ Rules:
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
 - Vibe64 supplies an authenticated context through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
 - Do not install a browser when the environment provides a managed browser runner.
+- Shared CRUD lists retain both card and table markup and hide the inactive
+  layout with CSS. Select visible record text with
+  `page.getByText(title, { exact: true }).filter({ visible: true })`; asserting on
+  an unfiltered text locator can fail with a strict-mode duplicate after saving.
+  Keep the expected text and persistence assertion. If repeated create controls
+  perform the same action, select one visible control deliberately rather than
+  accepting a different label to make a test pass.
 
 ## Keep startup incremental