@jskit-ai/agent-docs 0.1.270 → 0.1.272

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/authentication.md

@@ -66,6 +66,150 @@ Protected server operations declare an auth policy; they do not trust a hidden
 button or a page-local session check. Other packages extend auth through the
 public extension capability rather than replacing the auth service.
 
+## Sign-in protection
+
+Two limits slow down password guessing, and both are on by default.
+
+**Per client address.** Every auth route that can be abused by repetition
+declares a `rateLimit`, which the kernel enforces for each client address. A
+request over it is refused with status 429, the code `kernel.http.rateLimited`
+(`params.count` is the seconds to wait) and a `Retry-After` header. The
+defaults, per minute: `login`, `register`, `registerConfirm`,
+`loginOtpRequest` and `loginOtpVerify` 10; `registerConfirmationResend` and
+`passwordForgot` 5;
+`oauthStart`, `oauthComplete`, `passwordRecovery` and `passwordReset` 20;
+`devLoginAs` 30. Change one in the application's server configuration;
+`false` removes it:
+
+```js
+// config/server.js
+config.auth = {
+  ...config.auth,
+  rateLimits: {
+    login: { max: 5, timeWindow: "1 minute" },
+    oauthStart: false
+  }
+};
+```
+
+A route name auth does not have, or a value that is neither
+`{ max, timeWindow }` nor `false`, stops startup. `timeWindow` is milliseconds
+or text such as `"30 seconds"` or `"1 hour"`.
+
+The address is Fastify's `request.ip`. Behind a reverse proxy every request
+comes from the proxy, so all clients would share one count: create Fastify with
+`trustProxy` set to the proxy's address (for example
+`Fastify({ trustProxy: "127.0.0.1" })`), and never to `true` when clients can
+also reach the server directly.
+
+**Per account (local auth).** After 5 failed sign-ins in a row for one email,
+that email must wait 30 seconds before its next attempt; each further failure
+doubles the wait, up to an hour (NIST SP 800-63B's example). While it waits,
+sign-in is refused, even with the right password, with status 429, the code
+`auth.local.login.locked` (`params.count` minutes, `params.retryAfterSeconds`)
+and `Retry-After`. Emails without an account are counted the same way, so the
+wait says nothing about which accounts exist. A successful sign-in forgets the
+failures, and so does a day without one. Waits are temporary and password
+recovery is never blocked: completing a password reset ends the wait, so an
+attacker who keeps an account waiting cannot keep its owner out. The failures
+are kept in the file store (`sign-in-failures.passwd`) or, with
+`@jskit-ai/auth-provider-local-db-core`, in the `auth_local_sign_in_failures`
+table (run `npm run db:migrate`).
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `AUTH_LOCAL_SIGN_IN_FAILURES_BEFORE_WAIT` | `5` | Failed sign-ins in a row before the account waits, 1 to 100. |
+| `AUTH_LOCAL_SIGN_IN_FIRST_WAIT_SECONDS` | `30` | The first wait. |
+| `AUTH_LOCAL_SIGN_IN_MAX_WAIT_SECONDS` | `3600` | The longest wait, at least the first. |
+| `AUTH_LOCAL_PASSWORD_MIN_LENGTH` | `8` | The shortest password local auth accepts, 8 to 64. |
+
+NIST SP 800-63B-4 asks for at least 15 characters when a password is the only
+sign-in factor, and at least 8 when it is used with another factor; set
+`AUTH_LOCAL_PASSWORD_MIN_LENGTH=15` for password-only sign-in. Passwords up to
+128 characters are accepted.
+
+The login page shows either refusal, translated, with the wait.
+
+## Email confirmation (local auth)
+
+Local auth confirms the email address of each account it registers by
+password, in every environment, unless `AUTH_LOCAL_EMAIL_CONFIRMATION=false`.
+Registering keeps the registration waiting, with no account, profile or
+session, and answers `requiresEmailConfirmation: true`; the sign-in page then
+shows "Confirm your email", with a button to send a new link and a field for
+the link or its code. Opening the link (`/auth/login?confirmation_token=...`)
+creates the account and signs the person in. The `auth.local.user.registered`
+hook runs then, not on registering. Signing in with the right password while the registration waits
+is refused with status 403 and `auth.login.emailUnconfirmed`, and the sign-in
+page shows how to confirm; a wrong password is an ordinary failed sign-in.
+
+A link's code is random, kept only as a hash, works once and expires after a
+day. Registering the same email again, or asking for a new link, replaces it,
+so a waiting registration never keeps the email from its owner. Asking for a
+new link answers the same whether or not a registration waits.
+
+The link is emailed by the optional `auth.local.confirmation-sender`
+capability, an async function accepting `{ email, confirmationUrl }`, built
+like the recovery sender below; with it, `APP_PUBLIC_URL` is required and the
+link is never returned or logged. In development without one, the link is in
+the registration's answer (`confirmationUrl`) and the log, and the sign-in page
+shows it with a button that confirms it. In production (`NODE_ENV=production`)
+without one, the server refuses to start, naming both ways out: install a
+sender, or set `AUTH_LOCAL_EMAIL_CONFIRMATION=false`. For direct library
+composition, pass the sender as `confirmationSender` to
+`createLocalAuthService()`, with `emailConfirmationSender: true` in
+`resolveLocalAuthConfig()`; without one, pass
+`createLoggedConfirmationSender(logger)`.
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `AUTH_LOCAL_EMAIL_CONFIRMATION` | on | `false` registers and signs in at once, without confirming the email. |
+
+Accounts that exist already are confirmed: only registrations made after the
+upgrade wait. Waiting registrations are kept in the file store
+(`registrations.passwd`) or, with `@jskit-ai/auth-provider-local-db-core`, in
+the `auth_local_registrations` table (run `npm run db:migrate`). A custom
+`auth.local.backend` implements the `registrations` collection. Tests that
+register and expect a session either confirm with the answer's
+`confirmationUrl` or set `AUTH_LOCAL_EMAIL_CONFIRMATION=false`.
+
+## The first account in production (local auth)
+
+The first account to register becomes the application's owner, so on a
+production server (`NODE_ENV=production`) whose local auth has no account yet,
+registering needs a one-time setup code that only the server's operator can
+read. Development needs no code.
+
+Each start of such a server makes a new code, such as
+`7KQ2M-X9D4F-0RWHN-3TBZC`, and keeps only its hash. It writes the code:
+
+- in the log, as one warning: `Local auth has no account yet: register the
+  first account with this setup code.`, with the fields
+  `firstAccountSetupCode` (the code) and `firstAccountSetupCodeFile`;
+- in the file `first-account-setup-code` in `AUTH_LOCAL_STORE_DIR` (default
+  `.jskit/auth`), mode 600, for a hosting tool to read. A store directory that
+  cannot be written leaves only the log line.
+
+While it waits, the sign-in page's registration form shows a "Setup code"
+field (capability `features.firstAccountSetupCode`), and the register body
+takes `setupCode`; letter case, spaces and dashes do not matter. A missing code
+is refused with 403 `auth.local.setup.codeRequired`, a wrong one with 403
+`auth.local.setup.codeInvalid`. An OAuth sign-in cannot create that first
+account. The registration then follows the ordinary rules, email confirmation
+included, and confirming it signs the owner in. The code admits registrations
+until an account exists; then it stops working and its file is deleted, and
+registration needs no code again. Restarting before then makes a new code and
+the old one stops working: the latest log line and the file always agree, and
+nothing but a hash is kept for checking it. Run one server while the first
+account is set up, since each server makes its own code.
+
+A hosting tool that shows the code to the operator itself supplies it in
+`AUTH_LOCAL_SETUP_CODE`, at least 20 letters and digits, for example a
+generated production secret. The server then asks for that code at every start
+and on every server, writes no `first-account-setup-code` file, and logs only
+that the code is in `AUTH_LOCAL_SETUP_CODE`, never the code itself. Outside
+production the variable is ignored.
+
 ## Application-owned recovery email
 
 Local auth owns recovery tokens, expiry and recovery-scoped sessions. The
@@ -128,6 +272,11 @@ URL. Without a sender, production recovery is disabled; explicit development
 output remains available for local testing. A sender failure never falls back
 to development output. The generic recovery delivery capability is `email`.
 
+Production is `NODE_ENV=production`; anything else, unset included, is
+development, so the host that serves the application sets it. A production
+server with `AUTH_LOCAL_RECOVERY_DEV_OUTPUT` set refuses to start and names the
+setting to remove, rather than ignoring it.
+
 ### Pre-release migration
 
 This is a V0 breaking change. There is one runtime path, with no old SMTP reader

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/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

@@ -735,6 +735,11 @@ for anything that reads or writes the domain.**
   `request.executeAction({ actionId: ACTION_X, input })` returns.
 - A route that bypasses actions (a provider's callback) gets its own named
   registrar. Summaries are sentences.
+- A route that repetition can abuse (sign-in, codes, sending email) declares
+  `rateLimit: { max, timeWindow }`, which the kernel enforces per client
+  address and refuses with 429, `kernel.http.rateLimited` and `Retry-After`.
+  A limit worth changing per application is read from its config, as
+  `config.auth.rateLimits` is.
 
 Why: an action is the one place a domain operation's policy, input and
 events are declared.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.270",
+  "version": "0.1.272",
   "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.9",
     "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.9",
     "@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.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.22",
+    "@jskit-ai/jskit-catalog": "0.2.24",
     "@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.9",
     "@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.9",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.2.8",
+    "@jskit-ai/shell-web": "0.2.10",
     "@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.22",
+    "@jskit-ai/jskit-catalog": "0.2.24",
     "@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.9"
   },
   "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" });
 });