arcane-os 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.42.0
+
+- Accept the optional boolean `responseToUsersPromptComplete` in conversation
+  closing-report arguments, preserving both `true` and `false` and leaving the
+  normalized record unchanged when the field is omitted.
+- Add `createConversationClosingReportTool({responseToUsersPromptComplete:
+  {required:true,description}})` so applications can require the completion
+  flag and supply its complete description. Omitting the option preserves the
+  existing schema; an optional declaration defaults `required` to `false`.
+  Applications continue to own tool execution,
+  continuation, terminal closeout and storage; the SDK adds no runner or
+  automatic follow-up behavior and performs no saved-history migration.
+
 ## 0.41.0
 
 - Add `createTwinCloudTTSProvider` through `arcane-os/ai/browser-speech`,

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.41.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.42.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/reference/inventory/runtime-modules.json

@@ -489,8 +489,8 @@
       "summary": "Defines the closing-report tool, instruction, result normalizer, call classifier, and formatter.",
       "availability": "Cross-host",
       "protocol": "In-process only",
-      "normalization": "Required user-facing message remains distinct from the complete final_message; normalized results expose message, finalMessage, and rememberedActions.",
-      "surface": "Seven constants/helpers for closing reports; the sole-call schema requires message and final_message. formatConversationClosingReportText(value) exposes the existing &, <, and > escaping for any string, including whitespace-only chunks, and the complete report formatter reuses it."
+      "normalization": "Required user-facing message remains distinct from the complete final_message; normalized results expose message, finalMessage, and rememberedActions. Optional responseToUsersPromptComplete is preserved only when supplied as a boolean, with no coercion or default; it is transient app-owned control metadata outside saved history.",
+      "surface": "Seven constants/helpers for closing reports; the sole-call schema requires message and final_message. createConversationClosingReportTool optionally accepts responseToUsersPromptComplete:{required:false,description:<nonblank app-owned string>} to declare the boolean, or required:true to require it; omission preserves the existing schema. The normalizer remains independent of factory options and orchestration remains app-owned. formatConversationClosingReportText(value) exposes the existing &, <, and > escaping for any string, including whitespace-only chunks, and the complete report formatter reuses it."
     },
     {
       "file": "runtime/arcane/modules/ConversationTimebox.js",

package/docs/reference/runtime-modules.md

@@ -1933,6 +1933,35 @@ replaces `&`, `<`, and `>` with `&amp;`, `&lt;`, and `&gt;` respectively. It
 preserves all other text and does not trim, validate a report, render, or persist
 anything. Use the same operation for live text chunks and complete final text.
 
+An application may opt into completion metadata when creating the tool:
+
+```javascript
+import {createConversationClosingReportTool} from 'arcane-os/conversation-closing-report';
+
+const tool=createConversationClosingReportTool({
+    responseToUsersPromptComplete:{
+        required:true,
+        description:"Use true only when this response's messages and successful tool actions complete the whole current user request. Use false if any answer or action still needs a model response, whether or not this tool returns data."
+    }
+});
+```
+
+The option declares a boolean `responseToUsersPromptComplete` argument. Its
+`description` must be a nonblank string and is preserved completely;
+`required` defaults to `false`. Omitting the option preserves the existing
+schema, including its required fields. This changes only the declaration, not
+the closeout instruction or sole-call classifier.
+
+`normalizeConversationClosingReport()` accepts that optional boolean in an
+object or JSON string and preserves `true` or `false` in the returned record
+under the same key. Omission leaves the key absent; other supplied types raise
+`CONVERSATION_CLOSING_REPORT_INVALID` without coercion. The normalizer does not
+consume factory options or enforce an application's required setting. The
+application owns completion decisions, sibling-call handling, and continuation.
+The flag is transient control metadata, not conversation content or a saved
+history field. These helpers perform no persistence or orchestration, and the
+formatter still returns only the formatted `finalMessage`.
+
 Exact exports: `CONVERSATION_CLOSING_REPORT_TOOL_NAME`, `classifyConversationClosingReportCalls`, `conversationClosingReportInstruction`, `createConversationClosingReportTool`, `formatConversationClosingReport`, `formatConversationClosingReportText`, `normalizeConversationClosingReport`.
 
 ### Availability and normalization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -85,7 +85,7 @@
   "scripts": {
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
-    "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
+    "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
     "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",

package/runtime/arcane/modules/ConversationClosingReport.js

@@ -11,7 +11,8 @@ const TOOL_NAME_PATTERN=/^[a-z][a-z0-9_]*$/;
 const REPORT_FIELDS=new Set([
     'message',
     'final_message',
-    'remembered_actions'
+    'remembered_actions',
+    'responseToUsersPromptComplete'
 ]);
 
 function invalid(message){
@@ -88,11 +89,14 @@ function completeValue(value){
 /**
  * Creates a provider-neutral terminal tool for one user-facing conversation
  * closeout. The tool performs no inference, persistence, rendering, task
- * execution, navigation, or external delivery.
+ * execution, navigation, or external delivery. An optional
+ * responseToUsersPromptComplete declaration adds app-owned completion metadata;
+ * its description is required and its required setting defaults to false.
  */
 export function createConversationClosingReportTool({
     name=DEFAULT_TOOL_NAME,
-    description='Prepare a complete closing report when the user clearly ends a conversation.'
+    description='Prepare a complete closing report when the user clearly ends a conversation.',
+    responseToUsersPromptComplete
 }={}){
     if(!is.string(name)||!TOOL_NAME_PATTERN.test(name)){
         throw invalid('The closing-report tool name is invalid.');
@@ -101,7 +105,7 @@ export function createConversationClosingReportTool({
         throw invalid('The closing-report tool description is invalid.');
     }
 
-    return completeValue({
+    const tool={
         type:'function',
         function:{
             name,
@@ -145,7 +149,33 @@ export function createConversationClosingReportTool({
                 required:['message','final_message']
             }
         }
-    });
+    };
+
+    if(responseToUsersPromptComplete!==undefined){
+        if(!isPlainRecord(responseToUsersPromptComplete)){
+            throw invalid('responseToUsersPromptComplete options must be an object.');
+        }
+        const {
+            required=false,
+            description:completionDescription
+        }=responseToUsersPromptComplete;
+        if(!is.boolean(required)){
+            throw invalid('responseToUsersPromptComplete.required must be a boolean.');
+        }
+        tool.function.parameters.properties.responseToUsersPromptComplete={
+            type:'boolean',
+            description:normalizedText(
+                completionDescription,
+                'responseToUsersPromptComplete.description',
+                {required:true}
+            )
+        };
+        if(required){
+            tool.function.parameters.required.push('responseToUsersPromptComplete');
+        }
+    }
+
+    return completeValue(tool);
 }
 
 /**
@@ -181,13 +211,22 @@ export function normalizeConversationClosingReport(value){
         throw invalid(`Unexpected closing-report field: ${unexpectedField}.`);
     }
 
-    return completeValue({
+    const report={
         message:normalizedText(source.message,'message',{required:true}),
         finalMessage:normalizedFinalMessage(source.final_message),
         rememberedActions:normalizeRememberedConversationActions(
             source.remembered_actions||[]
         )
-    });
+    };
+
+    if(Object.hasOwn(source,'responseToUsersPromptComplete')){
+        if(!is.boolean(source.responseToUsersPromptComplete)){
+            throw invalid('responseToUsersPromptComplete must be a boolean.');
+        }
+        report.responseToUsersPromptComplete=source.responseToUsersPromptComplete;
+    }
+
+    return completeValue(report);
 }
 
 /**
@@ -233,13 +272,17 @@ export function classifyConversationClosingReportCalls(calls={}, {
 }
 
 export function formatConversationClosingReport(value){
-    const normalizedInput=isPlainRecord(value)&&value.finalMessage!==undefined
-        ?{
+    let normalizedInput=value;
+    if(isPlainRecord(value)&&value.finalMessage!==undefined){
+        normalizedInput={
             message:value.message,
             final_message:value.finalMessage,
             remembered_actions:value.rememberedActions,
+        };
+        if(Object.hasOwn(value,'responseToUsersPromptComplete')){
+            normalizedInput.responseToUsersPromptComplete=value.responseToUsersPromptComplete;
         }
-        :value;
+    }
     return formatConversationClosingReportText(
         normalizeConversationClosingReport(normalizedInput).finalMessage
     );