@jskit-ai/agent-docs 0.1.298 → 0.1.300

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

@@ -1274,8 +1274,17 @@ supplied binding never blocks on message sending or unknown delivery.
 An active goal flashes red; a paused goal stays orange. `elapsedSeconds` is the
 accumulated **active running time**, and `sampledAt` is its sample time in epoch
 **milliseconds**. The UI adds time only while active. Omit elapsed time if the
-backend cannot supply it truthfully. The clock hides in a narrow conversation
-pane; the light stays visible and details retain the time. Reduced motion uses
+backend cannot supply it truthfully. Only an active goal's chip shows its clock;
+a `paused`, `blocked`, `usageLimited` or `budgetLimited` goal's chip shows its
+status label (for example "Goal paused") instead, and its details keep the
+elapsed time. A `usageLimited` goal is waiting at its AI account's limit: its
+label names the limit and, from an optional `resetsAt` (epoch **seconds**), when it
+resets ("Waiting: AI usage limit, resets at 05:00", with the day when the reset is
+not today); with `outOfCredit: true` it reads "Out of credit: top up or switch AI
+account". Its details say the goal does not continue by itself and offer Resume
+and Cancel, and Pause when `pauseBlocked` is set. In a narrow conversation pane
+the clock hides and a long label ends in an ellipsis; the light stays visible
+and details retain the time and full label. Reduced motion uses
 a steady red light. Pause follows the command's declared behavior:
 `pauseInterruptsTurn: true` means it stops the current turn and keeps the goal;
 otherwise it prevents further automatic turns while Stop interrupts current work.
@@ -1286,10 +1295,18 @@ adapter. For a low-level adapter, omit `goal` or use `enabled: false` when goals
 are unsupported. The supplied binding hides unsupported controls automatically.
 
 Claude Pause retains the objective and native identity in the existing conversation
-binding before interrupting execution. When another message starts a process, the
-native owner clears the restored checker with Claude's local command and requires
-its exact successful receipt before admitting user input. Ordinary messages and
-process restart keep the goal paused. Explicit Resume reinstalls the objective;
+binding before interrupting execution. It sends nothing to Claude, so it works when
+the account is out of credit. When another message starts a process, the
+native owner clears the restored checker with Claude's local command (no model
+request) and requires its exact successful receipt before admitting user input.
+Ordinary messages and process restart keep the goal paused. Only that retained
+Pause reads `paused`: a Claude goal whose turn ended any other way (an interrupt,
+a process restart) keeps its checker armed, so the next turn continues it and it
+reads `active`. When Claude's own history ends the goal's turn with its usage-limit
+message, the goal reads `usageLimited` with that message's `resetsAt`; its
+credit-balance message reads `usageLimited` with `outOfCredit: true`. A later
+answer returns it to `active`. Hosts that restart goals must not resume a waiting
+goal: Resume after the reset stays the person's choice. Explicit Resume reinstalls the objective;
 Cancel removes the retained goal. A failed native clear leaves the new message
 unsent and retains Pause for recovery. Hosts supplying their own Claude store must
 round-trip the optional `pausedGoal` field with the existing conversation state.

package/guide/agent/framework/side-effects.md

@@ -0,0 +1,70 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/framework/side-effects.md`. Do not edit manually. -->
+
+---
+title: Side effects and test copies
+description: Follow SIDE_EFFECTS so a test copy never sends real email, messages or payments.
+---
+
+# Side effects and test copies
+
+An application reads one environment variable, `SIDE_EFFECTS`:
+
+- `live`: the application acts for real.
+- Anything else, including unset, means `simulate`: the copy is a **test
+  copy**. It sends no real email, SMS, push notification, payment or
+  third-party webhook. It simulates each one, writes it to the log, and every
+  page shows a small "Test copy" banner.
+
+Only the copy that serves real people sets `SIDE_EFFECTS=live`. Development,
+previews, tests and staging leave it unset. The name has no platform prefix on
+purpose: any host can set it. The host sets it; a request never chooses it.
+
+## What JSKIT does
+
+- Every HTML page the server sends, and every page the Vite development server
+  sends, names the setting in a `jskit-side-effects` meta tag. The shell
+  (`@jskit-ai/shell-web`) shows the "Test copy" banner from it, with no
+  application code. The banner never takes a click or a tap.
+- The server logs once at startup whether it acts for real. A production server
+  that simulates logs a warning.
+- Local-password emails (confirmation and password reset) with an installed
+  sender are logged, not sent.
+- Workspace invitations with a provided mailer are logged. The invitation
+  answers `status: "simulated"`, and the inviter copies the link.
+- Accounts-hub email is logged, not sent.
+- Connector operations that act on the world (send an email or message, post,
+  book or cancel, charge, invoice, trigger another system's events) are marked
+  `sideEffect`. They are checked like real ones, then logged, and `invoke`
+  answers `{ simulated: true }`. Reads run for real. `createConnectorsFeature`
+  reads the setting itself; give `createConnectionService` and
+  `createPaymentCheckoutService` `sideEffects: resolveSideEffectsMode(env)`.
+- Payment checkout and the billing portal in the live payment environment are
+  refused with `payment_test_copy`; the sandbox environment works either way.
+
+Supabase sends its own authentication emails from Supabase's servers; JSKIT
+cannot simulate them. Point a test copy at a separate Supabase project.
+
+## The application's own side effects
+
+Code the application writes that reaches the world follows the same rule.
+Decide at the point of the effect: log what would happen and answer as if it
+were done.
+
+```js
+import { sideEffectsAreLive } from "@jskit-ai/kernel/shared/support/sideEffects";
+import { logSimulatedSideEffect } from "@jskit-ai/kernel/server/runtime/sideEffects";
+
+async function sendReminder({ env, logger, mailer }, message) {
+  if (!sideEffectsAreLive(env)) {
+    logSimulatedSideEffect(logger, { kind: "email", summary: `the reminder to ${message.to}`, details: { to: message.to } });
+    return { simulated: true };
+  }
+  return mailer.send(message);
+}
+```
+
+- Read `env` from the `runtime.env` capability, never a request.
+- A configured driver or key (`EMAIL_DRIVER=ses`, a live payment key) does not
+  make a test copy live; only `SIDE_EFFECTS=live` does.
+- Test both modes. A test that proves a real sender against a fake transport
+  sets `SIDE_EFFECTS: "live"` in its environment.

package/guide/agent/index.md

@@ -40,6 +40,8 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 - [Sanity checks](/guide/framework/sanity-checks): JSKIT's own pitfalls, and
   the JSKIT calls that check data access, tests, a refactor, a screen or a
   deployment before calling it done
+- [Side effects and test copies](/guide/framework/side-effects): read before
+  code that sends email, messages or payments, or calls another system
 - [Translating a JSKIT app](/guide/framework/translation)
 - [Complete source pattern library](/patterns/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.298",
+  "version": "0.1.300",
   "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.19",
+    "@jskit-ai/kernel": "0.2.20",
     "json-rest-schema": "^1.0.20"
   },
   "exports": {

package/patterns/minimal-foundation/example/AGENTS.md

@@ -26,6 +26,12 @@ factory or client provider), read the client features guide at
 Simple, direct code comes first: never add a layer, wrapper, registry or tiny
 module only to satisfy a rule. `npm run lint` checks its rules too.
 
+Before writing code that sends email, SMS, push notifications or payments, or
+calls another system, read the side effects guide at
+`https://mobily-enterprises.github.io/jskit-ai/guide/framework/side-effects`.
+Unless `SIDE_EFFECTS` is exactly `live`, the app is a test copy: it simulates
+them and logs them instead.
+
 Before implementation, read the narrow relevant source pattern completely. If
 its owner package is installed, prefer that version-matched package-owned copy.
 Do not install an unrelated runtime package only to read documentation.

package/patterns/minimal-foundation/example/bin/develop.js

@@ -1,4 +1,7 @@
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
 import { startServer } from "../server.js";
 import { DEFAULT_PORT } from "../server/lib/runtimeEnv.js";
 
@@ -43,10 +46,13 @@ process.once("SIGTERM", () => requestShutdown("SIGTERM"));
 try {
   apiServer = await startServer({ host: LOOPBACK_HOST, port: 0 });
   const apiPort = /** @type {import("node:net").AddressInfo} */ (apiServer.server.address()).port;
-  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  // Vite runs directly under node rather than through `npm run dev`: npm exits on SIGTERM without stopping
+  // the script it started, which left Vite serving the port after this launcher stopped.
+  const vitePackageFile = createRequire(import.meta.url).resolve("vite/package.json");
+  const viteCli = path.join(path.dirname(vitePackageFile), JSON.parse(readFileSync(vitePackageFile, "utf8")).bin.vite);
   viteProcess = spawn(
-    npmCommand,
-    ["run", "dev", "--", "--host", previewHost, "--port", String(previewPort), "--strictPort"],
+    process.execPath,
+    [viteCli, "--host", previewHost, "--port", String(previewPort), "--strictPort"],
     {
       cwd: process.cwd(),
       env: {

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.2.19",
+    "@jskit-ai/kernel": "0.2.20",
     "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
@@ -44,13 +44,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.19",
+    "@jskit-ai/http-runtime": "0.2.20",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.250",
-    "@jskit-ai/jskit-catalog": "0.2.50",
+    "@jskit-ai/jskit-catalog": "0.2.52",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/AGENTS.md

@@ -26,6 +26,12 @@ factory or client provider), read the client features guide at
 Simple, direct code comes first: never add a layer, wrapper, registry or tiny
 module only to satisfy a rule. `npm run lint` checks its rules too.
 
+Before writing code that sends email, SMS, push notifications or payments, or
+calls another system, read the side effects guide at
+`https://mobily-enterprises.github.io/jskit-ai/guide/framework/side-effects`.
+Unless `SIDE_EFFECTS` is exactly `live`, the app is a test copy: it simulates
+them and logs them instead.
+
 Before implementation, read the narrow relevant source pattern completely. If
 its owner package is installed, prefer that version-matched package-owned copy.
 Do not install an unrelated runtime package only to read documentation.

package/patterns/shell-foundation/example/bin/develop.js

@@ -1,4 +1,7 @@
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
 import { startServer } from "../server.js";
 import { DEFAULT_PORT } from "../server/lib/runtimeEnv.js";
 
@@ -43,10 +46,13 @@ process.once("SIGTERM", () => requestShutdown("SIGTERM"));
 try {
   apiServer = await startServer({ host: LOOPBACK_HOST, port: 0 });
   const apiPort = /** @type {import("node:net").AddressInfo} */ (apiServer.server.address()).port;
-  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  // Vite runs directly under node rather than through `npm run dev`: npm exits on SIGTERM without stopping
+  // the script it started, which left Vite serving the port after this launcher stopped.
+  const vitePackageFile = createRequire(import.meta.url).resolve("vite/package.json");
+  const viteCli = path.join(path.dirname(vitePackageFile), JSON.parse(readFileSync(vitePackageFile, "utf8")).bin.vite);
   viteProcess = spawn(
-    npmCommand,
-    ["run", "dev", "--", "--host", previewHost, "--port", String(previewPort), "--strictPort"],
+    process.execPath,
+    [viteCli, "--host", previewHost, "--port", String(previewPort), "--strictPort"],
     {
       cwd: process.cwd(),
       env: {

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.2.19",
+    "@jskit-ai/kernel": "0.2.20",
     "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
@@ -44,14 +44,14 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.19",
-    "@jskit-ai/shell-web": "0.2.25",
+    "@jskit-ai/http-runtime": "0.2.20",
+    "@jskit-ai/shell-web": "0.2.26",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.250",
-    "@jskit-ai/jskit-catalog": "0.2.50",
+    "@jskit-ai/jskit-catalog": "0.2.52",
     "@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.19"
+    "@jskit-ai/kernel": "0.2.20"
   },
   "jskit": {
     "kind": "runtime",

package/reference/autogen/KERNEL_MAP.md

@@ -170,6 +170,17 @@ Exports
 Local functions
 - `normalizePlacementRenderers(value = {})`
 
+### `support/sideEffects.js`
+Exports
+- `SIDE_EFFECTS_ENV_KEY`
+- `SIDE_EFFECTS_LIVE`
+- `SIDE_EFFECTS_META_NAME`
+- `SIDE_EFFECTS_SIMULATE`
+- `pageSideEffectsMode(documentObject = globalThis.document)`
+- `resolveSideEffectsMode(env)`
+- `sideEffectsAreLive(env)`
+- `withSideEffectsMeta(html, mode)`
+
 ### `support/silentLogger.js`
 Exports
 - `silentLogger`