@jskit-ai/agent-docs 0.1.269 → 0.1.271

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

@@ -2473,8 +2473,9 @@ accounts) authorizes the same connection again and stops the reply when access i
 gone. A configured `effort` reaches every provider as the AI SDK's standard
 reasoning setting; without one, the engine's default applies (adaptive thinking at
 high effort for Anthropic-format models). The system prompt is the configured
-instructions, then the summary, then the engine's state note with the current UTC
-time.
+instructions, then the summary. The engine's state note with the current UTC time
+follows the conversation as its last message, so the provider's prompt cache keeps
+the whole history from one turn to the next.
 
 An application can set server-owned `limits.maxApiToolProgressCharacters` to a
 positive safe integer to bound the decoded text accompanying confirmed API tool

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

@@ -164,6 +164,41 @@ Workspace scope is valid only when both the runtime and its settings surface
 are workspace-aware. Requests must retain the selected workspace through the
 server action boundary.
 
+### Who may change the instructions
+
+The settings hold the instructions every conversation on the surface follows,
+so changing them needs more than reading them. Any signed-in user may read
+them (a workspace settings surface also needs `workspace.settings.view`, a
+console-owner surface the console owner). Changing them needs:
+
+| Settings surface | Permission that changes the instructions |
+| --- | --- |
+| requires a workspace | `workspace.settings.update` |
+| console-owner access | the console owner |
+| any other | `assistant.settings.update` |
+
+Grant `assistant.settings.update` to the application's administrators through
+the request context's permissions, or name another permission the application
+already grants in server config:
+
+```js
+// config/server.js
+export const config = {
+  assistantServer: {
+    home: {
+      aiIntegrationId: "assistant",
+      settingsUpdatePermission: "app.admin"
+      // or { require: "any", permissions: ["app.admin", "app.owner"] }
+    }
+  }
+};
+```
+
+`settingsUpdatePermission: { require: "authenticated" }` lets every signed-in
+user change the instructions; choose it only deliberately. A malformed value
+stops the server from starting. Anyone else is refused with
+`assistant.runtime.settings.updateForbidden` (403).
+
 ### Existing SQL conversations
 
 The optional database integration uses the common conversation runtime for

package/guide/agent/app-setup/database-layer.md

@@ -45,6 +45,10 @@ also derives its dialect from the installed driver and rejects a conflicting
 The application or hosting environment creates the database and provides its
 credentials. JSKIT never guesses or commits them.
 
+The running database provider registers a `database` health check that runs
+`select 1` within two seconds. The foundations' `GET /api/health` answers `503`
+while it fails; see [Health endpoint](./initial-scaffolding.md#health-endpoint).
+
 ## Migration configuration
 
 Use the fixed-dialect pattern owned by the selected driver. The important

package/guide/agent/app-setup/existing-application-migration.md

@@ -183,6 +183,9 @@ The JSKIT host defaults to plain output and full write responses; standard
 document repositories explicitly request JSON:API output and full create/patch
 responses. A plain collection is still `{ data: [...], meta?, links? }`; use
 `extractJsonRestCollectionRows()` when a custom repository needs its rows.
+A query without a page returns only the resource's first 20 rows; a
+server-side read that needs every row uses `queryAllJsonRestCollectionRows()`
+([every row](/guide/framework/typed-features#every-row)).
 
 ```js
 await jsonRestApi.resources.books.patch({

package/guide/agent/app-setup/initial-scaffolding.md

@@ -100,6 +100,82 @@ loading. Do not replace them with generic spinners. Keep failures local when a
 resource cannot render; use shared toast/snackbar feedback for transient user
 commands so errors do not push the working page down.
 
+## Health endpoint
+
+Both foundations register `GET /api/health` after `createInstalledRuntime` and
+answer from the installed runtime's `health.check()`: `200` with
+`{ ok: true, checks, app }` when every check the installed packages register
+passes, and `503` with `ok: false` when one fails. `@jskit-ai/database-runtime`
+registers a `database` check that runs `select 1`. Each check has two seconds;
+a failure is logged on the server and the response only names which checks
+passed, so the route can stay public for load balancers and uptime monitors.
+Requests that arrive while a check runs share it. An application that adopted
+an older foundation, where the route answered `ok: true` before the runtime was
+created, moves the route after `createInstalledRuntime` in the same way.
+
+A package adds its own check through the optional `runtime.health`
+capability: `optional: { health: "runtime.health" }`, then
+`health?.register("queue", () => queue.ping())` in `setup()`. The check resolves
+when healthy and rejects or hangs when not.
+
+## Security headers
+
+`createInstalledRuntime` adds security headers to every response its Fastify
+server sends, including error and not-found responses. A route that sets one of
+these headers itself keeps its own value.
+
+| Header | When | Default |
+| --- | --- | --- |
+| `X-Content-Type-Options: nosniff` | always | on |
+| `Referrer-Policy` | always | `strict-origin-when-cross-origin` |
+| `Strict-Transport-Security` | production | `max-age=31536000` |
+| `Content-Security-Policy: frame-ancestors` | production | `'self'` |
+| `Content-Security-Policy-Report-Only` | production | the content policy below |
+
+Production means `NODE_ENV=production`. A host that starts the server with a
+plain `npm start` runs it in development; its Serve command must set the
+variable, for example `env NODE_ENV=production npm start`. Development sends only
+nosniff and the Referrer-Policy, so an editor's preview, such as Vibe64's, can
+frame the application and inject its bridge script.
+
+The content policy allows JSKIT's client: the application's own scripts and
+WebAssembly, inline styles (Vuetify and the loading shell use them), images
+from the application, `data:`, `blob:` and any HTTPS source, fonts and media
+from the application and `data:`, same-origin requests and sockets, and no
+plugins, foreign base URLs or foreign form posts. It is reported, not enforced,
+by default: browsers log violations in the console without blocking anything,
+because an application's own additions, such as a sign-in provider, an
+analytics script or a map, are not known to JSKIT. Enforce it once the
+application's pages run without violations. Framing is always enforced, since
+browsers ignore `frame-ancestors` in a report-only policy.
+
+Change the defaults in `config/server.js`:
+
+```js
+export const config = {
+  securityHeaders: {
+    // Another site that frames production, such as the editor that previews it.
+    frameAncestors: ["'self'", "https://editor.example.com"],
+    contentSecurityPolicy: {
+      mode: "enforce", // "report-only" (default), "enforce" or "off"
+      directives: {
+        "connect-src": ["'self'", "https://auth.example.com"],
+        "form-action": false // false leaves a directive out
+      }
+    }
+  }
+};
+```
+
+`noSniff: false`, `referrerPolicy: false`, `strictTransportSecurity: false` and
+`frameAncestors: false` leave that header out; `referrerPolicy` and
+`strictTransportSecurity` also take their own header value. A directive's
+sources replace JSKIT's for that directive; framing is set only through
+`frameAncestors`. An invalid value stops the server from starting. A server
+composed without `createInstalledRuntime` calls
+`registerSecurityHeaders(fastify, { config, env })` from
+`@jskit-ai/kernel/server/http` before it registers any plugin.
+
 ## Verification
 
 Pattern contract tests keep both examples concrete, parseable, npm-published,

package/guide/agent/framework/typed-features.md

@@ -683,6 +683,47 @@ const trx = resolveTransaction(options);
 const trx = options?.trx || options?.transaction || null;
 ```
 
+### Every row
+
+**A server-side resource query that needs every row it matches reads them
+with `queryAllJsonRestCollectionRows(resource, params, context)`
+(`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`). A query without a
+page means "the first 20 rows".**
+
+- json-rest-api answers a query that names no page with the resource's
+  default page, 20 rows, and says nothing about the rest. The CRUD
+  repository's `queryDocuments(query)` without a `limit` is the same first
+  page.
+- The helper reads cursor pages of the resource's maximum size
+  (`queryMaxLimit`, 100 unless the resource sets it) in id order until none
+  follows, keeping the call's transaction and context, so no row is skipped
+  or repeated. It sets the page and sort itself; sort the rows it returns.
+- A lookup by a unique key (an id, a slug, a token hash, a unique pair such
+  as workspace and user) matches at most one row and may read `rows[0]` of a
+  plain query. A read of the newest or first few rows names its own `sort`
+  and `page`.
+- HTTP list routes keep the caller's page: their default and maximum page
+  sizes are public behaviour, not a server-side limit to raise.
+
+Why: a list read without a page looks complete until the 21st row, then
+silently drops the rest from every person picker, scope and delivery built on it.
+
+```js
+// good
+const rows = await queryAllJsonRestCollectionRows(api.resources.workspaceMemberships, {
+  queryParams: { filters: { workspace: workspaceId, status: "active" }, include: ["user"] },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, options.context);
+
+// bad: the first 20 members only
+const rows = extractJsonRestCollectionRows(await api.resources.workspaceMemberships.query({
+  queryParams: { filters: { workspace: workspaceId, status: "active" }, include: ["user"] },
+  transaction: resolveTransaction(options),
+  format: "plain"
+}, createJsonRestContext(options.context)));
+```
+
 ### Routes
 
 **A route does HTTP work only (status, cookies, redirects) and runs an action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.269",
+  "version": "0.1.271",
   "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.2.7",
+    "@jskit-ai/kernel": "0.2.8",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/PATTERN.md

@@ -146,7 +146,9 @@ verification, not only against Vite development mode.
 After adapting the example, install the declared packages once and run
 `npm run develop` for the live application. Then run the application's lint,
 server tests, client tests, production build, and focused browser smoke.
-Confirm `/api/health` and the first product route.
+Confirm `/api/health` and the first product route. The health route answers
+from the installed runtime's `health.check()` after `createInstalledRuntime`, so
+it returns `503` while a registered check, such as the database's, fails.
 
 ## Avoid
 

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

@@ -34,22 +34,22 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.7",
+    "@jskit-ai/kernel": "0.2.8",
     "@tanstack/vue-query": "^5.101.0",
-    "fastify": "^5.8.5",
+    "fastify": "^5.12.7",
     "pino": "^10.3.1",
     "json-rest-schema": "^1.0.17",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.7",
+    "@jskit-ai/http-runtime": "0.2.8",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.21",
+    "@jskit-ai/jskit-catalog": "0.2.23",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/minimal-foundation/example/server.js

@@ -102,12 +102,6 @@ async function createServer({ runtimeEnv }) {
     }
   });
 
-  app.get("/api/health", async () => {
-    return {
-      ok: true,
-      app: "reading-room"
-    };
-  });
   const appRoot = path.resolve(process.cwd());
   const distRoot = path.resolve(appRoot, "dist");
   const hasWebBuild = existsSync(path.resolve(distRoot, SPA_INDEX_FILE));
@@ -124,6 +118,15 @@ async function createServer({ runtimeEnv }) {
     fastify: app
   });
 
+  // Healthy when every check the installed packages register passes, such as the database's.
+  app.get("/api/health", async (request, reply) => {
+    const health = await runtime.health.check();
+    return reply.code(health.ok ? 200 : 503).send({
+      ...health,
+      app: "reading-room"
+    });
+  });
+
   registerSurfaceRequestConstraint({
     fastify: app,
     surfaceRuntime,

package/patterns/minimal-foundation/example/tests/server/smoke.test.js

@@ -3,15 +3,14 @@ import test from "node:test";
 import { createServer } from "../../server.js";
 import { resolveRuntimeEnv } from "../../server/lib/runtimeEnv.js";
 
-test("GET /api/health returns built-in health response", async () => {
+test("GET /api/health reports the installed runtime's health checks", async (context) => {
   const app = await createServer({ runtimeEnv: resolveRuntimeEnv() });
+  context.after(() => app.close());
   const response = await app.inject({
     method: "GET",
     url: "/api/health"
   });
 
   assert.equal(response.statusCode, 200);
-  assert.equal(response.json().ok, true);
-
-  await app.close();
+  assert.deepEqual(response.json(), { ok: true, checks: {}, app: "reading-room" });
 });

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

@@ -34,24 +34,24 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.7",
+    "@jskit-ai/kernel": "0.2.8",
     "@tanstack/vue-query": "^5.101.0",
-    "fastify": "^5.8.5",
+    "fastify": "^5.12.7",
     "pino": "^10.3.1",
     "json-rest-schema": "^1.0.17",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.7",
+    "@jskit-ai/http-runtime": "0.2.8",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.2.8",
+    "@jskit-ai/shell-web": "0.2.9",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.21",
+    "@jskit-ai/jskit-catalog": "0.2.23",
     "@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.2.7"
+    "@jskit-ai/kernel": "0.2.8"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/shell-foundation/example/server.js

@@ -102,12 +102,6 @@ async function createServer({ runtimeEnv }) {
     }
   });
 
-  app.get("/api/health", async () => {
-    return {
-      ok: true,
-      app: "reading-room"
-    };
-  });
   const appRoot = path.resolve(process.cwd());
   const distRoot = path.resolve(appRoot, "dist");
   const hasWebBuild = existsSync(path.resolve(distRoot, SPA_INDEX_FILE));
@@ -124,6 +118,15 @@ async function createServer({ runtimeEnv }) {
     fastify: app
   });
 
+  // Healthy when every check the installed packages register passes, such as the database's.
+  app.get("/api/health", async (request, reply) => {
+    const health = await runtime.health.check();
+    return reply.code(health.ok ? 200 : 503).send({
+      ...health,
+      app: "reading-room"
+    });
+  });
+
   registerSurfaceRequestConstraint({
     fastify: app,
     surfaceRuntime,

package/patterns/shell-foundation/example/tests/server/smoke.test.js

@@ -3,15 +3,14 @@ import test from "node:test";
 import { createServer } from "../../server.js";
 import { resolveRuntimeEnv } from "../../server/lib/runtimeEnv.js";
 
-test("GET /api/health returns built-in health response", async () => {
+test("GET /api/health reports the installed runtime's health checks", async (context) => {
   const app = await createServer({ runtimeEnv: resolveRuntimeEnv() });
+  context.after(() => app.close());
   const response = await app.inject({
     method: "GET",
     url: "/api/health"
   });
 
   assert.equal(response.statusCode, 200);
-  assert.equal(response.json().ok, true);
-
-  await app.close();
+  assert.deepEqual(response.json(), { ok: true, checks: {}, app: "reading-room" });
 });