@jskit-ai/agent-docs 0.1.298 → 0.1.299

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/package.json

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

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

@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.250",
-    "@jskit-ai/jskit-catalog": "0.2.50",
+    "@jskit-ai/jskit-catalog": "0.2.51",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.250",
-    "@jskit-ai/jskit-catalog": "0.2.50",
+    "@jskit-ai/jskit-catalog": "0.2.51",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/reference/autogen/PATTERN_INDEX.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.298`
+- Owner: `@jskit-ai/agent-docs@0.1.299`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.298`
+- Owner: `@jskit-ai/agent-docs@0.1.299`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.2.43`
+- Owner: `@jskit-ai/assistant-runtime@0.2.44`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/assistant/assistant-surface/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/assistant/assistant-surface/example/)
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -356,7 +356,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `aggregate`, `feature`, `handle`, `orchestration`, `owns`, `package`, `provider`, `repository`, `routes`, `server`, `table resource`
-- Owner: `@jskit-ai/agent-docs@0.1.298`
+- Owner: `@jskit-ai/agent-docs@0.1.299`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`

package/reference/autogen/packages/assistant-core.md

@@ -463,7 +463,7 @@ Local functions
 Exports
 - `waitForClaudeConversationTurn(conversation, input = {}, { signal, defaultTimeoutMs = 180_000, maximumTimeoutMs = Infinity, createError = claudeTurnFailure, interruptedMessage = "Claude was interrupted when the application disconnected." } = {})`
 - `runClaudeRenewalTurn(conversation, { clientMessageId, prompt, outputSchema, expectedThreadId, forbiddenThreadId, requireFreshHistory = false, timeoutMs = 180_000 }, { createError = claudeTurnFailure, unreadableCode = "assistant_claude_turn_unreadable", failedCode = "assistant_claude_turn_failed", acceptedField = "inputAccepted" } = {})`
-- `createClaudeConversationGoals({ conversationId, readHistory, readState, interrupt, send, readRetainedGoal, saveRetainedGoal })`
+- `createClaudeConversationGoals({ conversationId, readHistory, interrupt, send, readRetainedGoal, saveRetainedGoal })`
 - `createClaudeConversationOwner({ configRoot, store, preparation, process, onEvent, createError = claudeTurnFailure, disconnectedMessage = "Claude was interrupted when the application disconnected." })`
 - `type ClaudeConversationEntry`
 - `type ClaudeConversationStore`

package/skills/jskit/references/pattern-index.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.298`
+- Owner: `@jskit-ai/agent-docs@0.1.299`
 - Read: [PATTERN.md](patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.298`
+- Owner: `@jskit-ai/agent-docs@0.1.299`
 - Read: [PATTERN.md](patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.2.43`
+- Owner: `@jskit-ai/assistant-runtime@0.2.44`
 - Read: [PATTERN.md](patterns/assistant/assistant-surface/PATTERN.md)
 - Examples: [example/](patterns/assistant/assistant-surface/example/)
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -356,7 +356,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `aggregate`, `feature`, `handle`, `orchestration`, `owns`, `package`, `provider`, `repository`, `routes`, `server`, `table resource`
-- Owner: `@jskit-ai/agent-docs@0.1.298`
+- Owner: `@jskit-ai/agent-docs@0.1.299`
 - Read: [PATTERN.md](patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`

package/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/minimal-foundation/example/package.json

@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.250",
-    "@jskit-ai/jskit-catalog": "0.2.50",
+    "@jskit-ai/jskit-catalog": "0.2.51",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/shell-foundation/example/package.json

@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.250",
-    "@jskit-ai/jskit-catalog": "0.2.50",
+    "@jskit-ai/jskit-catalog": "0.2.51",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",