arcane-os 0.29.1 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.30.0
+
+- Add the public `arcane-os/ai/twin-cloud` subpath with stateless `fetchRequest`
+  for Node and browser callers. Supply the TWiN key, model, messages, optional
+  structured-output schema and cancellation signal explicitly. The result is
+  the complete parsed provider completion, with no browser startup, saved
+  conversation, hidden model default or output cap.
+- Share the existing TWiN HTTP, structured JSON, overload retry and cancellation
+  implementation with the browser AI owner while preserving its public methods
+  and lifecycle. Only overload responses with HTTP 429 use the existing
+  three-second retry; other failures retain their complete provider response.
+
 ## 0.29.1
 
 - Preserve complete long and non-ASCII filenames in application release bundles

package/README.md

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

package/browser-runtime/ai/twin-cloud.mjs

@@ -0,0 +1,230 @@
+import Is from 'strong-type';
+import {arcaneLogging} from '../logging.mjs';
+
+const is = new Is(false);
+const twinChatURL = 'https://inference.do-ai.run/v1/chat/completions';
+
+/** A stateless TWiN request; browser AI shares the HTTP and format owners below. */
+export async function fetchRequest({
+    twinKey,
+    model,
+    messages = [],
+    structuredOutput = false,
+    tools = [],
+    toolChoice = 'auto',
+    parallelToolCalls,
+    reasoningEffort,
+    signal = null,
+    id = Date.now(),
+    onRequest = function observeTWiNRequest(){},
+    onResponse = function observeTWiNResponse(){}
+} = {}){
+    if(signal?.aborted){
+        throw normalizeAIRequestAbort(signal.reason);
+    }
+    if(!is.string(twinKey) || !twinKey){
+        const error = new Error('AI provider is not configured.');
+        error.code = 'AI_PROVIDER_NOT_CONFIGURED';
+        throw error;
+    }
+    if(!is.string(model) || !model){
+        throw new TypeError('TWiN fetchRequest requires an explicit model.');
+    }
+
+    const request = {model, messages, stream:false};
+    const format = structuredOutputFormat(structuredOutput);
+    if(format){
+        request.response_format = openAIResponseFormat(format);
+    }
+    if(tools.length){
+        request.tools = tools;
+        request.tool_choice = toolChoice;
+        if(parallelToolCalls !== undefined){
+            request.parallel_tool_calls = parallelToolCalls;
+        }
+    }
+    if(reasoningEffort){
+        request.reasoning_effort = reasoningEffort;
+    }
+
+    try{
+        await onRequest(
+            request,
+            id,
+            {operation:'fetch', transport:'http', destination:twinChatURL}
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const response = await fetchJSONResponse(
+            twinChatURL,
+            {
+                method:'POST',
+                credentials:'omit',
+                headers:{
+                    'Content-Type':'application/json',
+                    Authorization:`Bearer ${twinKey}`
+                },
+                body:JSON.stringify(request),
+                ...(signal ? {signal} : {})
+            }
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        await onResponse(response, id, false);
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        return response;
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}
+
+export function isAIRequestAbort(error, signal){
+    return signal?.aborted
+        || error?.name === 'AbortError'
+        || error?.code === 'ARCANE_REQUEST_ABORTED'
+        || error?.code === 'ARCANE_AI_REQUEST_ABORTED'
+        || error?.code === 'AI_REQUEST_ABORTED';
+}
+
+export function normalizeAIRequestAbort(error){
+    if(error?.code === 'ARCANE_AI_REQUEST_ABORTED'){
+        return error;
+    }
+    const normalized = new Error('The AI request was cancelled.', {cause:error});
+    normalized.name = 'AbortError';
+    normalized.code = 'ARCANE_AI_REQUEST_ABORTED';
+    return normalized;
+}
+
+export function structuredOutputFormat(value = false){
+    if(value === false || value === null || value === undefined){
+        return null;
+    }
+    if(value === true || value === 'json'){
+        return 'json';
+    }
+    if(
+        is.object(value)
+        && !is.array(value)
+        && (
+            Object.getPrototypeOf(value) === Object.prototype
+            || Object.getPrototypeOf(value) === null
+        )
+    ){
+        return value;
+    }
+    const error = new TypeError(
+        'AI structured output must be enabled with true, json, or a JSON Schema object.'
+    );
+    error.code = 'AI_STRUCTURED_OUTPUT_INVALID';
+    throw error;
+}
+
+export function openAIResponseFormat(format){
+    if(format === 'json'){
+        return {type:'json_object'};
+    }
+    if(format){
+        return {
+            type:'json_schema',
+            json_schema:{name:'structured_response', strict:true, schema:format}
+        };
+    }
+    return null;
+}
+
+/** Shared with browser streaming; consume no successful body at this boundary. */
+export async function fetchHTTPResponse(url, options){
+    const {signal} = options;
+    const retryDelayMs = 3000;
+    try{
+        while(true){
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            const response = await fetch(url, options);
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            if(response.ok){
+                return response;
+            }
+            const contentType = response.headers.get('content-type') || '';
+            const error = contentType.includes('application/json')
+                ? await response.json()
+                : await response.text();
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            const message = is.string(error)
+                ? error
+                : error?.error?.message ?? error?.message;
+            if(
+                response.status !== 429
+                || !is.string(message)
+                || !message.toLowerCase().includes('overload')
+            ){
+                throw error;
+            }
+            arcaneLogging.warn(
+                `${message}\nRetrying in ${retryDelayMs / 1000} seconds`,
+                error
+            );
+            await new Promise(function waitForOverloadRetry(resolve, reject){
+                function finishRetryDelay(){
+                    signal?.removeEventListener('abort', cancelRetryDelay);
+                    resolve();
+                }
+                function cancelRetryDelay(){
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', cancelRetryDelay);
+                    reject(normalizeAIRequestAbort(signal.reason));
+                }
+                const timer = setTimeout(finishRetryDelay, retryDelayMs);
+                signal?.addEventListener('abort', cancelRetryDelay, {once:true});
+                if(signal?.aborted){
+                    cancelRetryDelay();
+                }
+            });
+        }
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}
+
+/** Return the entire parsed completion without selecting or rewriting choices. */
+export async function fetchJSONResponse(url, options){
+    const {signal} = options;
+    try{
+        const response = await fetchHTTPResponse(url, options);
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const contentType = response.headers.get('content-type') || '';
+        if(!contentType.includes('application/json')){
+            throw new TypeError(
+                `AI request returned ${contentType || 'an unknown content type'} instead of JSON.`
+            );
+        }
+        const completion = await response.json();
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        return completion;
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}

package/docs/reference/ai/twin-cloud.md

@@ -1,8 +1,125 @@
 # TWiN Cloud: one request
 
-TWiN Cloud is the high-level `AI.js` default remote LLM service, named `TWIN`.
-Speech stays on device and does not use the TWiN access key. This guide uses the
-same managed browser imports as the [browser speech quick start](browser-speech.md).
+Use `fetchRequest` from `arcane-os/ai/twin-cloud` for a complete TWiN Cloud
+request in Node or a browser with an explicit key and model. It imports no
+browser profile, DOM, user singleton, or storage, and starts no work on import.
+The existing browser `AI.js` interface remains available for applications that
+already use its provider selection, lifecycle, and speech. TWiN Cloud is that
+interface's default remote LLM service, named `TWIN`; speech stays on device
+and does not use the TWiN access key.
+
+## Node: explicit key, model, and structured result
+
+Install the published `arcane-os` package in the Node project. Keep the key in
+the application's existing server configuration, outside source control and
+diagnostics. In this example, `server-config.json` is that caller-owned local
+configuration file with a `twinKey` property; add its exact path to `.gitignore`
+before creating it. The SDK does not discover or write this file.
+
+```javascript
+import serverConfig from './server-config.json' with {type: 'json'};
+import {fetchRequest} from 'arcane-os/ai/twin-cloud';
+
+const response = await fetchRequest({
+    twinKey: serverConfig.twinKey,
+    model: 'openai-gpt-oss-20b',
+    messages: [{
+        role: 'user',
+        content: 'Explain why the moon-powered toaster keeps burning breakfast. Return HTML and plain text.'
+    }],
+    structuredOutput: {
+        type: 'object',
+        properties: {
+            html: {type: 'string'},
+            text: {type: 'string'}
+        },
+        required: ['html', 'text'],
+        additionalProperties: false
+    }
+});
+
+console.log(response);
+```
+
+`model` is required and remains exactly the supplied identifier. This function
+does not select the browser profile's default model. The example's prompt and
+`html`/`text` schema are caller-owned data, not SDK business logic. Changing
+those fields changes the requested result without changing the SDK.
+
+The resolved value is the complete parsed provider JSON, including every
+choice and provider field. The SDK does not extract only the first message,
+parse its content into a second object, or replace the response with an
+application-specific record. The supplied schema becomes
+`response_format: {type:'json_schema', json_schema:{name:'structured_response',
+strict:true, schema:...}}`. `structuredOutput:true` or `'json'` instead selects
+`response_format:{type:'json_object'}`; omission leaves structured output off.
+
+## Shared request behavior
+
+The focused API accepts complete `messages`, optional `tools`, `toolChoice`,
+`parallelToolCalls`, and `reasoningEffort` in addition to the explicit
+`twinKey` and `model`. Tool options use the existing chat-completion wire fields
+`tools`, `tool_choice`, and `parallel_tool_calls` when `tools` is nonempty.
+A supplied nonempty `reasoningEffort` uses the provider's `reasoning_effort`
+field; omission preserves its default. No output limit is added by this API.
+The function neither executes tools nor adds provider-response envelope
+validation.
+
+Optional `id`, `onRequest(request,id,metadata)`, and
+`onResponse(response,id,false)` follow the complete-response `AI.fetchRequest`
+callback shape. The request callback runs before dispatch; the response
+callback receives the complete parsed result before it is returned. Omitted
+`id` uses `Date.now()`; request metadata is
+`{operation:'fetch',transport:'http',destination:'https://inference.do-ai.run/v1/chat/completions'}`.
+The key is
+transport authentication, not part of either callback's message payload. Keep
+credentials out of application logging as well.
+
+Only HTTP `429` with a message containing `overload` (case-insensitive) repeats automatically,
+after `3000` milliseconds. Another overload repeats the same complete request;
+other HTTP failures do not become an automatic retry loop. Pass a fresh
+`AbortController`'s `signal` and call `abort()` to cancel. Cancellation during
+the request, response-body read, retry wait, or callback settlement prevents
+successful result delivery and rejects with `ARCANE_AI_REQUEST_ABORTED`.
+Other HTTP failures throw the complete parsed JSON error body or text body.
+A missing key uses `AI_PROVIDER_NOT_CONFIGURED`, a missing explicit model
+throws `TypeError`, and an unsupported `structuredOutput` input uses
+`AI_STRUCTURED_OUTPUT_INVALID`.
+
+The SDK retains no request or response history between calls and uses no
+DBOPFS, chat entity, or memory extraction. Each call's `messages` are its
+complete caller-supplied context. The caller decides whether and how to keep
+the result; this stateless transport adds no saved conversation or migration.
+
+Browser applications can use this same focused import through their generated
+managed import map. Browser Fetch and CORS behavior still apply. Importing it
+does not instantiate `AI`, read saved preferences, configure speech, or change
+the existing `arcane-os/ai` browser entry.
+
+### Shared low-level integration helpers
+
+The same module also exports the helpers used by browser `AI.js`. Ordinary
+callers use `fetchRequest`; these exports let SDK transport integration share
+the existing implementation rather than maintain another retry or body reader.
+
+| Export | Contract |
+| --- | --- |
+| `fetchHTTPResponse(url,options)` | Uses the caller's Fetch options, overload retry and cancellation; returns a successful `Response` with its body unconsumed. |
+| `fetchJSONResponse(url,options)` | Uses that HTTP owner, requires `application/json`, and returns the complete parsed body without selecting choices. |
+| `structuredOutputFormat(value=false)` | Maps false/null/undefined to null, true/`'json'` to `'json'`, and preserves a supplied plain JSON Schema object. Other inputs use `AI_STRUCTURED_OUTPUT_INVALID`. |
+| `openAIResponseFormat(format)` | Maps the normalized value to `json_object`, strict `json_schema` named `structured_response`, or null. |
+| `isAIRequestAbort(error,signal)` | Recognizes an aborted signal, `AbortError`, or the existing Arcane AI/request cancellation codes. |
+| `normalizeAIRequestAbort(error)` | Preserves an existing `ARCANE_AI_REQUEST_ABORTED` error or creates that `AbortError` with the original value as its cause. |
+
+These helpers start no work on import. HTTP helpers require explicit URL and
+options; they do not add a key, model, browser state, or retained conversation.
+Overload warnings use the shared console logger and preserve the complete
+provider error.
+
+## Existing browser AI interface
+
+The following browser example uses the same managed imports as the
+[browser speech quick start](browser-speech.md).
 
 ## Install and import
 

package/docs/reference/availability-and-normalization.md

@@ -78,6 +78,7 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
+| Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Shared structured-output mapping, overload-only HTTP 429 retry after 3000 ms, and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
 | Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | The helper keeps audio on device: Whisper owns STT and Kokoro owns TTS. It automatically cleans only the outbound speech-input copy and normalizes application-facing audio/text behavior while browser and native request/response plumbing differs below that boundary. |
 | Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
 | Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |
@@ -240,6 +241,14 @@ snapshot.
 
 ### Provider-native within an Arcane boundary
 
+[`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) accepts an explicit `twinKey` and
+`model`, with the same named `fetchRequest` import in Node and managed browsers.
+It preserves complete provider response JSON while mapping the supplied
+structured-output, tool, and reasoning options to the TWiN wire contract.
+The SDK adds no output cap or persisted context. Cancellation applies during
+request, body read, overload retry wait, and callback settlement. The existing
+profile-backed browser `AI.js` entry and its lifecycle remain separate.
+
 Direct `Arcane.ollama.chat()`, `generate()`, `show()`, `embed()`, and lifecycle
 methods return complete Ollama-compatible envelopes. Arcane still owns error
 normalization, chunk correlation, and host transport, but it does

package/docs/reference/inventory/package-api.json

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 210,
+  "memberCount": 217,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -3395,6 +3395,104 @@
       "availability": "Node and browser",
       "protocol": "Shared user.developer preference",
       "normalization": "Returns null until target.user.ready is true, then whether target.user.developer is exactly true; returns false if preference access throws"
+    },
+    {
+      "id": "twin-cloud:fetchRequest",
+      "name": "fetchRequest",
+      "displayName": "fetchRequest()",
+      "kind": "function",
+      "signature": "async fetchRequest(options={})",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "TWiN Cloud requests",
+      "summary": "Sends one complete TWiN Cloud request with an explicit caller-owned key and model.",
+      "availability": "Node and Browser; remote HTTPS provider",
+      "protocol": "TWiN Cloud complete-response chat",
+      "normalization": "Preserves complete messages and parsed provider JSON; maps explicit structured-output, tool, and reasoning options; shares overload-only HTTP 429 retry after 3000 ms and cancellation; retains no browser profile, storage, or request history"
+    },
+    {
+      "id": "twin-cloud:fetchHTTPResponse",
+      "name": "fetchHTTPResponse",
+      "displayName": "fetchHTTPResponse()",
+      "kind": "function",
+      "signature": "async fetchHTTPResponse(url,options)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Returns a successful unconsumed Fetch Response through the shared AI HTTP owner.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI HTTP transport",
+      "normalization": "Preserves caller Fetch options and complete error bodies; repeats only overload HTTP 429 after 3000 ms; signal cancellation uses ARCANE_AI_REQUEST_ABORTED"
+    },
+    {
+      "id": "twin-cloud:fetchJSONResponse",
+      "name": "fetchJSONResponse",
+      "displayName": "fetchJSONResponse()",
+      "kind": "function",
+      "signature": "async fetchJSONResponse(url,options)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Reads the complete successful provider JSON through the shared HTTP owner.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI HTTP transport",
+      "normalization": "Requires application/json, retains every parsed field without envelope validation, and checks cancellation before delivery"
+    },
+    {
+      "id": "twin-cloud:structuredOutputFormat",
+      "name": "structuredOutputFormat",
+      "displayName": "structuredOutputFormat()",
+      "kind": "function",
+      "signature": "structuredOutputFormat(value=false)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Normalizes the existing structured-output option while preserving a supplied schema.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI structured-output options",
+      "normalization": "False/null/undefined return null, true/json return json, a plain schema object is returned unchanged, and other inputs use AI_STRUCTURED_OUTPUT_INVALID"
+    },
+    {
+      "id": "twin-cloud:openAIResponseFormat",
+      "name": "openAIResponseFormat",
+      "displayName": "openAIResponseFormat()",
+      "kind": "function",
+      "signature": "openAIResponseFormat(format)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Maps normalized structured-output settings to chat-completion response_format.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI structured-output options",
+      "normalization": "Returns json_object, strict json_schema named structured_response with the original schema, or null; does not validate schema contents"
+    },
+    {
+      "id": "twin-cloud:isAIRequestAbort",
+      "name": "isAIRequestAbort",
+      "displayName": "isAIRequestAbort()",
+      "kind": "function",
+      "signature": "isAIRequestAbort(error,signal)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Recognizes an aborted signal or an existing AI request cancellation error.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI cancellation",
+      "normalization": "Returns a boolean for AbortError or ARCANE_REQUEST_ABORTED, ARCANE_AI_REQUEST_ABORTED, and AI_REQUEST_ABORTED; changes no operation"
+    },
+    {
+      "id": "twin-cloud:normalizeAIRequestAbort",
+      "name": "normalizeAIRequestAbort",
+      "displayName": "normalizeAIRequestAbort()",
+      "kind": "function",
+      "signature": "normalizeAIRequestAbort(error)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Returns the common AI AbortError while preserving the original cause.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI cancellation",
+      "normalization": "Preserves an existing ARCANE_AI_REQUEST_ABORTED value or returns an AbortError with that code and the supplied cause"
     }
   ]
 }

package/docs/reference/sdk-api.md

@@ -3,7 +3,7 @@
 The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`,
 `arcane-os/preference-store`, `arcane-os/speech-playback`,
-`arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, and `arcane-os/browser-device` entrypoints, and the browser-only
+`arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, `arcane-os/ai/twin-cloud`, and `arcane-os/browser-device` entrypoints, and the browser-only
 `arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
 The `arcane-os/modules/<filename>` and `arcane-os/entities/<filename>` paths
 resolve directly to the existing runtime files, with their actual extension.
@@ -66,6 +66,7 @@ runtime layouts.
 | `arcane-os/pwa` | Nonblocking PWA registration, worker updates, native installation state and a dismissible installation component. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
 | `arcane-os/ai/tool-text-stream` | Shared selected tool-argument text observer for provider integration. |
+| `arcane-os/ai/twin-cloud` | Complete TWiN Cloud requests from Node or a browser with an explicit key/model and shared retry/cancellation behavior. |
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
 
@@ -121,6 +122,13 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 
 | Member | Kind | Import | Group | Availability |
 | --- | --- | --- | --- | --- |
+| `fetchRequest()` | function | `arcane-os/ai/twin-cloud` | TWiN Cloud requests | Node and Browser; remote HTTPS provider |
+| `fetchHTTPResponse()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `fetchJSONResponse()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `structuredOutputFormat()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `openAIResponseFormat()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `isAIRequestAbort()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `normalizeAIRequestAbort()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
 | `APP_BUNDLE_DESCRIPTOR_NAME` | constant | `arcane-os` | Packaging and release bundles | Node |
 | `APP_BUNDLE_EXTENSION` | constant | `arcane-os` | Packaging and release bundles | Node |
 | `APP_BUNDLE_FORMAT` | constant | `arcane-os` | Packaging and release bundles | Node |
@@ -7636,6 +7644,265 @@ import {readArcaneDeveloperMode} from 'arcane-os/logging';
 const developerMode=readArcaneDeveloperMode();
 ```
 
+## fetchRequest()
+
+### Overview
+
+Makes one complete TWiN Cloud request with explicit caller-owned credentials
+and model selection. This named function is independent of the browser
+`AI` instance method with the same name.
+
+### Signature and result
+
+```text
+async fetchRequest(options={})
+```
+
+Import the named function from `arcane-os/ai/twin-cloud`. Supply `twinKey`,
+`model`, and complete `messages`. The function requires the explicit model;
+it reads no browser preference or default-model selection. Optional
+`structuredOutput:true` or `'json'` sends `response_format:{type:'json_object'}`.
+A supplied JSON Schema sends `response_format:{type:'json_schema',
+json_schema:{name:'structured_response',strict:true,schema:...}}`. Omission
+leaves structured output off. Optional `tools`, `toolChoice`,
+`parallelToolCalls`, and `reasoningEffort` map to their existing TWiN wire
+fields. Tool fields are sent when `tools` is nonempty; a nonempty
+`reasoningEffort` is forwarded without selecting a default. No default output
+cap, tool execution, or provider-response envelope validation is added.
+
+The return value is the entire parsed provider JSON, not only one choice or
+message. Optional callbacks are `onRequest(request,id,metadata)` before
+dispatch and `onResponse(response,id,false)` before successful return;
+`id` defaults to `Date.now()` and may be supplied by the caller. Request metadata
+is `{operation:'fetch',transport:'http',destination:'https://inference.do-ai.run/v1/chat/completions'}`.
+Both callbacks are awaited, and callback
+failures propagate. Credentials are supplied to transport rather than added to
+the message or response callback payload.
+
+### Availability and normalization
+
+**Node and Browser; Cloud transport.** Uses standard Fetch and cancellation,
+without DOM, browser profiles, user singletons, or storage initialization.
+Import starts no request. HTTP `429` whose message contains `overload`
+(case-insensitive) waits
+`3000` milliseconds and retries the complete request; other HTTP failures
+throw their complete parsed JSON or text bodies. A missing key throws
+`AI_PROVIDER_NOT_CONFIGURED`; a missing model throws `TypeError`. `signal`
+cancellation during transport, body reading, retry waiting,
+or callback settlement prevents successful return and uses
+`ARCANE_AI_REQUEST_ABORTED`. No request history, DBOPFS write, or recurring
+model context is retained. The caller owns persistence and key configuration.
+See [TWiN Cloud](ai/twin-cloud.md) for a complete Node JSON-schema example and
+the unchanged browser AI interface.
+
+### Example
+
+```javascript
+import serverConfig from './server-config.json' with {type: 'json'};
+import {fetchRequest} from 'arcane-os/ai/twin-cloud';
+
+const response = await fetchRequest({
+    twinKey: serverConfig.twinKey,
+    model: 'openai-gpt-oss-20b',
+    messages: [{role: 'user', content: 'Describe a moon-powered toaster.'}]
+});
+
+console.log(response);
+```
+
+`server-config.json` is an application-owned, ignored configuration file;
+never commit its key or print it in diagnostics. The SDK does not read it.
+
+## fetchHTTPResponse()
+
+### Overview
+
+Shared low-level HTTP owner used by browser AI and the focused TWiN API.
+Ordinary TWiN callers use `fetchRequest()` instead.
+
+### Signature and result
+
+```text
+async fetchHTTPResponse(url,options)
+```
+
+Returns the successful Fetch `Response` without consuming its body. Both URL
+and Fetch options are caller-supplied; this helper adds no key, model, or
+request envelope. Non-success responses are read completely as JSON when the
+content type contains `application/json`, otherwise as text. Only status 429
+with an overload message repeats after 3000 ms; other error bodies are thrown.
+
+### Availability and normalization
+
+**Node and Browser.** Exported from `arcane-os/ai/twin-cloud` for shared SDK
+integration. `options.signal` cancels Fetch and the overload wait and is checked
+after response/error-body reads. Cancellation uses
+`ARCANE_AI_REQUEST_ABORTED`. Overload warnings use the existing shared logger.
+
+### Example
+
+```javascript
+import {fetchHTTPResponse} from 'arcane-os/ai/twin-cloud';
+
+// The integration supplies its selected endpoint and complete Fetch options.
+const response = await fetchHTTPResponse(endpoint, requestOptions);
+```
+
+## fetchJSONResponse()
+
+### Overview
+
+Shared complete JSON-body reader built on `fetchHTTPResponse()`.
+
+### Signature and result
+
+```text
+async fetchJSONResponse(url,options)
+```
+
+Returns the full parsed JSON value. A successful response whose content type
+does not contain `application/json` throws `TypeError`; JSON parser failures
+propagate. The helper does not select choices or validate a provider envelope.
+
+### Availability and normalization
+
+**Node and Browser.** Exported from `arcane-os/ai/twin-cloud` for shared SDK
+integration; it retains the HTTP owner's retry/cancellation behavior and checks
+cancellation again after parsing. Ordinary callers use `fetchRequest()`.
+
+### Example
+
+```javascript
+import {fetchJSONResponse} from 'arcane-os/ai/twin-cloud';
+
+// The integration supplies its selected endpoint and complete Fetch options.
+const completion = await fetchJSONResponse(endpoint, requestOptions);
+```
+
+## structuredOutputFormat()
+
+### Overview
+
+Normalizes the existing AI structured-output option without rewriting a schema.
+
+### Signature and result
+
+```text
+structuredOutputFormat(value=false)
+```
+
+False, null, and undefined return null. True and `'json'` return `'json'`.
+A plain object with `Object.prototype` or a null prototype is returned
+unchanged. Other values throw `AI_STRUCTURED_OUTPUT_INVALID`.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`; performs no network or storage operation.
+
+### Example
+
+```javascript
+import {structuredOutputFormat} from 'arcane-os/ai/twin-cloud';
+
+const format = structuredOutputFormat({
+    type: 'object',
+    properties: {text: {type: 'string'}}
+});
+```
+
+## openAIResponseFormat()
+
+### Overview
+
+Maps a normalized structured-output choice to chat-completion wire fields.
+
+### Signature and result
+
+```text
+openAIResponseFormat(format)
+```
+
+`'json'` becomes `{type:'json_object'}`; a supplied schema becomes
+`{type:'json_schema',json_schema:{name:'structured_response',strict:true,schema:format}}`.
+A disabled format returns null. Use `structuredOutputFormat()` first to
+normalize the public option; this mapper does not validate schema contents.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`, shared with browser AI and performing no I/O.
+
+### Example
+
+```javascript
+import {structuredOutputFormat, openAIResponseFormat} from 'arcane-os/ai/twin-cloud';
+
+const responseFormat = openAIResponseFormat(structuredOutputFormat(true));
+// {type: 'json_object'}
+```
+
+## isAIRequestAbort()
+
+### Overview
+
+Recognizes the existing AI request cancellation forms.
+
+### Signature and result
+
+```text
+isAIRequestAbort(error,signal)
+```
+
+Returns a boolean: true when the signal is aborted, the error name is
+`AbortError`, or its code is `ARCANE_REQUEST_ABORTED`,
+`ARCANE_AI_REQUEST_ABORTED`, or `AI_REQUEST_ABORTED`.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`; it neither changes nor aborts the supplied operation.
+
+### Example
+
+```javascript
+import {isAIRequestAbort} from 'arcane-os/ai/twin-cloud';
+
+const controller = new AbortController();
+controller.abort();
+const cancelled = isAIRequestAbort(undefined, controller.signal);
+```
+
+## normalizeAIRequestAbort()
+
+### Overview
+
+Keeps cancellation under the shared AI error code while preserving its cause.
+
+### Signature and result
+
+```text
+normalizeAIRequestAbort(error)
+```
+
+An existing `ARCANE_AI_REQUEST_ABORTED` error is returned unchanged. Otherwise
+the result is an Error named `AbortError`, with code
+`ARCANE_AI_REQUEST_ABORTED`, message `The AI request was cancelled.`, and the
+supplied value as its cause. The helper returns the error; it does not throw it.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`; creates no request, storage, or user state.
+
+### Example
+
+```javascript
+import {normalizeAIRequestAbort} from 'arcane-os/ai/twin-cloud';
+
+const cancelled = normalizeAIRequestAbort(new DOMException('Cancelled', 'AbortError'));
+```
+
 ## Data export subpaths
 
 The package also exposes eight JSON Schemas (including `arcane-os/schemas/event-stack.json`) and its package manifest. These are data contracts, not callable JavaScript members. See [schema contracts](../architecture.md) and the files under `schemas/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -38,6 +38,7 @@
     "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
     "./ai/tool-text-stream": "./browser-runtime/ai/tool-text-stream.mjs",
+    "./ai/twin-cloud": "./browser-runtime/ai/twin-cloud.mjs",
     "./ai/browser-speech": "./browser-runtime/ai/browser-speech.mjs",
     "./mail": "./src/mail-api.mjs",
     "./testing": "./src/testing.mjs",
@@ -85,7 +86,7 @@
     "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:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.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/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.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/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.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/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.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: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",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/modules/AI.js

@@ -16,6 +16,14 @@ import {
 } from './AIProviderRuntime.js';
 import {normalizeOllamaModelIdentifier} from './OllamaModelIdentifier.js';
 import {arcaneLogging} from 'arcane-os/logging';
+import {
+    fetchHTTPResponse,
+    fetchJSONResponse,
+    isAIRequestAbort,
+    normalizeAIRequestAbort,
+    structuredOutputFormat as normalizeStructuredOutput,
+    openAIResponseFormat
+} from 'arcane-os/ai/twin-cloud';
 import {MarkdownSpeech,stripSpeechFormatting} from 'arcane-os/speech-text';
 import {prepareSpeech} from './PreparedSpeech.js';
 import {createToolTextObserver} from 'arcane-os/ai/tool-text-stream';
@@ -121,24 +129,6 @@ function aiInitializationError(code,reason,message){
     return error;
 }
 
-function isAIRequestAbort(error,signal){
-    return signal?.aborted
-        ||error?.name==='AbortError'
-        ||error?.code==='ARCANE_REQUEST_ABORTED'
-        ||error?.code==='ARCANE_AI_REQUEST_ABORTED'
-        ||error?.code==='AI_REQUEST_ABORTED';
-}
-
-function normalizeAIRequestAbort(error){
-    if(error?.code==='ARCANE_AI_REQUEST_ABORTED'){
-        return error;
-    }
-    const normalized=new Error('The AI request was cancelled.',{cause:error});
-    normalized.name='AbortError';
-    normalized.code='ARCANE_AI_REQUEST_ABORTED';
-    return normalized;
-}
-
 function normalizeAIReasoningEffort(value){
     if(value===undefined||value===null||value===''){
         return '';
@@ -3776,69 +3766,6 @@ class AI {
         return true;
     }
 
-    async #fetchHTTPResponse(url,options){
-        const {signal}=options;
-        const retryDelayMs=3000;
-        try{
-            while(true){
-                if(signal?.aborted){
-                    throw normalizeAIRequestAbort(signal.reason);
-                }
-                const response=await fetch(url,options);
-                if(signal?.aborted){
-                    throw normalizeAIRequestAbort(signal.reason);
-                }
-                if(response.ok){
-                    return response;
-                }
-
-                const contentType=response.headers.get('content-type')||'';
-                const error=contentType.includes('application/json')
-                    ?await response.json()
-                    :await response.text();
-                if(signal?.aborted){
-                    throw normalizeAIRequestAbort(signal.reason);
-                }
-                const message=is.string(error)
-                    ?error
-                    :error?.error?.message??error?.message;
-                if(
-                    response.status!==429
-                    ||!is.string(message)
-                    ||!message.toLowerCase().includes('overload')
-                ){
-                    throw error;
-                }
-
-                arcaneLogging.warn(
-                    `${message}\nRetrying in ${retryDelayMs / 1000} seconds`,
-                    error
-                );
-                await new Promise(function waitForOverloadRetry(resolve,reject){
-                    function finishRetryDelay(){
-                        signal?.removeEventListener('abort',cancelRetryDelay);
-                        resolve();
-                    }
-                    function cancelRetryDelay(){
-                        clearTimeout(timer);
-                        signal.removeEventListener('abort',cancelRetryDelay);
-                        reject(normalizeAIRequestAbort(signal.reason));
-                    }
-                    const timer=setTimeout(finishRetryDelay,retryDelayMs);
-                    signal?.addEventListener('abort',cancelRetryDelay,{once:true});
-                    if(signal?.aborted){
-                        cancelRetryDelay();
-                    }
-                });
-            }
-        }catch(error){
-            if(isAIRequestAbort(error,signal)){
-                throw normalizeAIRequestAbort(error);
-            }
-            throw error;
-        }
-    }
-
     #nativeOllama(){
         const client=globalThis.Arcane?.ollama;
 
@@ -4171,48 +4098,6 @@ class AI {
         ];
     }
 
-    #structuredOutputFormat(value=false){
-        if(value===false||value===null||value===undefined){
-            return null;
-        }
-        if(value===true||value==='json'){
-            return 'json';
-        }
-        if(
-            is.object(value)
-            &&!is.array(value)
-            &&(
-                Object.getPrototypeOf(value)===Object.prototype
-                ||Object.getPrototypeOf(value)===null
-            )
-        ){
-            return value;
-        }
-
-        const error=new TypeError(
-            'AI structured output must be enabled with true, json, or a JSON Schema object.'
-        );
-        error.code='AI_STRUCTURED_OUTPUT_INVALID';
-        throw error;
-    }
-
-    #openAIResponseFormat(structuredOutputFormat){
-        if(structuredOutputFormat==='json'){
-            return {type:'json_object'};
-        }
-        if(structuredOutputFormat){
-            return {
-                type:'json_schema',
-                json_schema:{
-                    name:'structured_response',
-                    strict:true,
-                    schema:structuredOutputFormat
-                }
-            };
-        }
-        return null;
-    }
-
     async #reportRequest(requestHandler,request,id,metadata){
         if(!is.function(requestHandler)){
             throw new TypeError('AI onRequest callback must be a function.');
@@ -4762,7 +4647,7 @@ class AI {
             if(signal?.aborted){
                 throw normalizeAIRequestAbort();
             }
-            const structuredOutputFormat=this.#structuredOutputFormat(
+            const structuredOutputFormat=normalizeStructuredOutput(
                 structuredOutput
             );
 
@@ -4776,7 +4661,7 @@ class AI {
         }
 
         if(structuredOutputFormat){
-            request.response_format=this.#openAIResponseFormat(
+            request.response_format=openAIResponseFormat(
                 structuredOutputFormat
             );
         }
@@ -4970,7 +4855,7 @@ class AI {
             destination:this.url
         });
         const body = JSON.stringify(request);
-        const response=await this.#fetchHTTPResponse(
+        const response=await fetchHTTPResponse(
             this.url,
             {
                 method:'POST',
@@ -5622,7 +5507,7 @@ class AI {
         if(signal?.aborted){
             throw normalizeAIRequestAbort();
         }
-        const structuredOutputFormat=this.#structuredOutputFormat(structuredOutput);
+        const structuredOutputFormat=normalizeStructuredOutput(structuredOutput);
 
         const normalizedReasoningEffort=normalizeAIReasoningEffort(
             reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
@@ -5634,7 +5519,7 @@ class AI {
         }
 
         if(structuredOutputFormat){
-            request.response_format=this.#openAIResponseFormat(
+            request.response_format=openAIResponseFormat(
                 structuredOutputFormat
             );
         }
@@ -5718,7 +5603,7 @@ class AI {
             destination:this.url
         });
         const body = JSON.stringify(request);
-        const response=await this.#fetchHTTPResponse(
+        const responseJSON=await fetchJSONResponse(
             this.url,
             {
                 method:'POST',
@@ -5729,36 +5614,11 @@ class AI {
             }
         );
 
-        const contentType=response.headers.get('content-type')||'';
-
-        if(!contentType.includes('application/json')){
-            throw new TypeError(
-                `AI request returned ${contentType||'an unknown content type'} instead of JSON.`
-            );
-        }
-
-        let responseJSON;
-        try{
-            responseJSON=await response.json();
-        }catch(error){
-            if(isAIRequestAbort(error,signal)){
-                throw normalizeAIRequestAbort(error);
-            }
-            throw error;
-        }
         if(signal?.aborted){
             throw normalizeAIRequestAbort();
         }
-
-        if(!response.id){
-            response.id=id;
-        }
-
-        //console.log(responseJSON);
-        //async
         normalizeAICompletionToolCalls(responseJSON);
         await responseHandler(responseJSON,id,false);
-        //sync
         return responseJSON;
     }
 

package/src/import-map.mjs

@@ -47,6 +47,7 @@ const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/speech-text','sdk/speech-text.mjs'],
     ['arcane-os/ai/browser-wasm',SDK_BROWSER_AI_ENTRY],
     ['arcane-os/ai/tool-text-stream','sdk/ai/tool-text-stream.mjs'],
+    ['arcane-os/ai/twin-cloud','sdk/ai/twin-cloud.mjs'],
     ['arcane-os/ai/browser-speech',SDK_BROWSER_SPEECH_ENTRY]
 ]);
 function fail(message,code='ARCANE_IMPORT_MAP_INVALID'){