arcane-os 0.5.10 → 0.5.12

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

@@ -0,0 +1,156 @@
+# 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).
+
+## Install and import
+
+Create an application and start its source server:
+
+```bash
+npx arcane-os@0.5.12 new hello-twin --path ./hello-twin --target browser
+cd hello-twin
+npm install
+npm run dev
+```
+
+Keep the generated Arcane theme and import map. Place the JavaScript below in
+`apps/hello-twin/modules/App.js`. Run it in the served browser page, not Node.
+This first example is for the new application created above. An existing
+application must complete the saved-preference migration below before importing
+`arcane/AI` or any module that imports it.
+
+## Supply the key at runtime and display the response
+
+`applicationRuntime` is the **one application-supplied placeholder** in this
+example. It represents the authenticated host/application configuration that
+supplies a `twinKey` at runtime. Replace the placeholder with your existing
+configuration source; do not put a real key in this module, Git, or diagnostics.
+The SDK also reads `globalThis.arcane.config.twinCloud.accessKey` when present.
+
+```javascript
+import arcaneThemeReady from 'arcane/ThemeBootstrap';
+
+await arcaneThemeReady;
+// In an upgrade bootstrap, the existing preference owner's migration must
+// already be complete before this dynamic import evaluates AI.js.
+const { default: AI } = await import('arcane/AI');
+const applicationRuntime = globalThis.applicationRuntime;
+const ai = new AI();
+ai.twinKey = applicationRuntime.twinKey;
+
+const button = document.createElement('button');
+button.textContent = 'Ask TWiN';
+const output = document.createElement('pre');
+output.style.whiteSpace = 'pre-wrap';
+document.body.append(button, output);
+
+button.addEventListener('click', async function askTwin() {
+  button.disabled = true;
+  output.textContent = 'Thinking';
+  try {
+    const response = await ai.fetchRequest({
+      messages: [{ role: 'user', content: 'Say hello in one sentence.' }]
+    });
+    output.textContent = JSON.stringify(response, null, 2);
+  } catch (error) {
+    output.textContent = `${error.code ?? 'ERROR'}\n${error.message}`;
+  } finally {
+    button.disabled = false;
+  }
+});
+```
+
+The example displays the complete returned response so its actual fields are
+visible. It makes one `fetchRequest()` per click. A normal `new AI()` selects
+TWiN Cloud and its default model, `openai-gpt-oss-120b`; assigning `twinKey`
+reconciles that remote route's readiness. No browser speech model is loaded by
+this request. `ai.license` remains an alias of `ai.twinKey` for existing callers.
+
+For an application-owned cancellation control, pass a fresh
+`AbortController`'s `signal` to `fetchRequest({messages,signal})` and call that
+controller's `abort()` when the operation is cancelled or its page detaches.
+`streamRequest()` is the corresponding object-form streaming API. See the
+[AI module reference](../runtime-modules.md#aijs) for its complete options.
+
+## Migrate saved preference tuples before using them
+
+The six tuple slots consumed by `ai.setAI(...tuple)` are:
+
+| Slot | Meaning | Migration |
+| --- | --- | --- |
+| 0 | LLM provider | Exact uppercase `OPENAI` becomes `TWIN`. |
+| 1 | STT provider | Preserve. |
+| 2 | TTS provider | Preserve. |
+| 3 | LLM model or default-model sentinel | Exact uppercase `OPENAI` becomes `TWIN`. |
+| 4 | TTS model | Preserve. |
+| 5 | STT model | Preserve. |
+
+Use this narrow transformation in the application's existing preference loader:
+
+```javascript
+function migrateSavedAISelection(savedTuple) {
+  return savedTuple.map(function migrateProviderOrDefault(value, slot) {
+    return (slot === 0 || slot === 3) && value === 'OPENAI' ? 'TWIN' : value;
+  });
+}
+
+const savedTuple = [
+  'OPENAI', 'LOCAL_SPEACH', 'LOCAL_SPEACH',
+  'OPENAI', 'LOCAL_SPEACH', 'LOCAL_SPEACH'
+];
+const migratedTuple = migrateSavedAISelection(savedTuple);
+console.log(migratedTuple);
+// ['TWIN', 'LOCAL_SPEACH', 'LOCAL_SPEACH', 'TWIN', 'LOCAL_SPEACH', 'LOCAL_SPEACH']
+```
+
+In the application's upgrade bootstrap, read saved settings, run this
+transformation, and complete the write through the **existing application
+preference owner before importing `AI.js` or any module that imports it**.
+Ensure that owner also exposes the migrated tuple to the current page before
+continuing. Use the application's actual storage/readiness operations; the SDK
+does not supply a new migration storage API.
+
+This ordering matters during module evaluation: `AI.js` installs its
+user-readiness handler immediately. If `window.user.ready` is already true, it
+can immediately read that user's preference tuple and construct `window.ai`.
+Waiting until a later `setAI()`, provider-startup call, or button click is too
+late. A static `import AI from 'arcane/AI'` evaluates before the surrounding
+module body, even if its text appears below migration code. Keep AI and its
+importing modules out of the bootstrap's static import graph, finish the
+existing owner's migration, then cross the dynamic-import boundary:
+
+```javascript
+// Place these lines after the application's existing preference migration
+// has finished writing and exposing migratedTuple, not before that operation.
+const { default: AI } = await import('arcane/AI');
+const ai = new AI(...migratedTuple);
+```
+
+Here `migratedTuple` is the result of the exact transformation shown above,
+using the real saved tuple in the application's bootstrap. Configure browser
+speech only after this initialization. Migration belongs to upgrade startup;
+do not inject it into an in-flight request. For later changes to an already
+valid active selection, `await ai.transitionAI(...migratedTuple)` remains the
+asynchronous lifecycle; it unloads roles and disposes SDK-owned browser speech,
+so configure desired speech afterward. It is not a substitute for migration
+before the first AI import.
+
+The SDK deliberately has no built-in `OPENAI` alias and performs no saved-data
+migration. This guide does not instruct a rewrite of chat history or unrelated
+settings. Preserve every tuple value except those two exact sentinel matches.
+In particular, do not change:
+
+- `openai-gpt-oss-120b` or `openai-gpt-oss-20b`: actual upstream model IDs;
+- OpenAI-compatible chat-completion wire terminology; or
+- Core's separate `provider:'openai'` behavior and public native contract.
+
+TWiN's default-model sentinel `TWIN` resolves to `openai-gpt-oss-120b`.
+An explicitly saved `openai-gpt-oss-20b` in slot 3 stays that exact model.
+
+## Related
+
+- [Browser speech quick start and streaming](browser-speech.md)
+- [Normalized AI and readiness](../README.md#normalized-ai)
+- [Core AI contracts](../core/arcane-ai-contracts.md)

package/docs/reference/arcane-ollama.md

@@ -0,0 +1,288 @@
+# Arcane Ollama
+
+Arcane Ollama lets an admitted application use local Ollama without knowing the
+service port, service account, model directory, host process, or native
+transport. Application code imports one browser module and calls one API:
+
+```javascript
+import ollama from '/arcane/modules/Ollama.js';
+
+const reply = await ollama.chatText({
+    model: 'arcane:latest',
+    messages: [{role: 'user', content: 'Summarize this record.'}]
+});
+
+console.log(reply);
+```
+
+The module never connects directly to `localhost:11434`. It delegates to the
+capability-gated `globalThis.Arcane.ollama` bridge. Core binds application
+identity, checks the exact method and package-owned model policy, admits native
+resources, and calls the managed ArcaneOllama service.
+
+This npm package exposes the synchronized browser client only. It does not
+bundle, install, start, or grant an Arcane Core or ArcaneOllama service. Every
+native call therefore requires a separately installed, compatible Arcane host,
+an app-scoped admitted Core session, the required capabilities, and a service
+that is ready under native policy. Import success alone proves none of those
+conditions.
+
+## What developers can do
+
+| Capability | Preferred call | Result style |
+| --- | --- | --- |
+| Check whether the admitted service answers | `ollama.readiness()` | Arcane-normalized frozen readiness snapshot |
+| Generate text | `ollama.generateText(request)` | Arcane helper string |
+| Chat and return only assistant text | `ollama.chatText(request)` | Arcane helper string |
+| Use full generation/chat/tool/provider fields | `ollama.generate()` / `ollama.chat()` | Bounded Ollama provider-native envelope |
+| Create embeddings | `ollama.embed()` | Bounded Ollama provider-native envelope |
+| Read raw version/model/running/show inventory | `version()`, `models()`, `list()`, `running()`, `show()` | Provider-native diagnostic envelope |
+| Unload one model | `ollama.unload(model)` | Translates to generate with `prompt: ""` and `keep_alive: 0` |
+| Read managed selection/runtime/service settings | `selection()`, `settings()`, `serviceSettings()` | Arcane-managed snapshot; some service fields are platform-dependent |
+| Change managed selection/runtime/service settings | `select()`, `saveSettings()`, `saveServiceSettings()` | Arcane-managed result plus operation receipt |
+| Run admitted raw model mutations | `pull()`, `push()`, `create()`, `copy()`, `delete()` | Policy-bound provider-native result; several calls are intentionally denied to ordinary apps |
+| Create an Arcane-managed brain alias | `createBrain()` | Arcane-managed model/default result plus operation receipt |
+
+## Fast start
+
+### 1. Feature-detect the module
+
+```javascript
+import ollama from '/arcane/modules/Ollama.js';
+
+const readiness = await ollama.readiness();
+
+if (!readiness.ready) {
+    console.info('Local AI is unavailable:', readiness.errorCode);
+}
+```
+
+`readiness()` catches a failed `version()` call and returns a frozen object:
+
+```text
+{ ready: boolean, version: string|null, errorCode: string|null }
+```
+
+It is a connectivity convenience, not model admission or inference readiness.
+Use `Arcane.localAI.status()` when the application needs the package-filtered
+runnable model catalog.
+
+### 2. Read admitted models
+
+```javascript
+const access = await globalThis.Arcane.capabilities.list();
+
+if (!access.methods.includes('localAI.status')) {
+    throw new Error('This application is not admitted for local AI.');
+}
+
+const status = await globalThis.Arcane.localAI.status();
+console.table(status.models.ollama);
+```
+
+Populate product UI from this filtered catalog. `ollama.models()` is the raw
+diagnostic inventory for admitted Settings, Shell, or Terminal journeys; it is
+not the application's package-admitted model list.
+
+### 3. Stream a chat response
+
+```javascript
+let text = '';
+
+const final = await ollama.chat({
+    model: 'arcane:latest',
+    messages: [{role: 'user', content: 'Explain the evidence.'}]
+}, {
+    onChunk(chunk) {
+        text += chunk.message?.content ?? '';
+    },
+    signal: AbortSignal.timeout(60_000)
+});
+
+console.log(text, final.done);
+```
+
+Arcane correlates chunks to the originating request. The final promise resolves
+with Ollama's final bounded chunk/envelope.
+
+## Complete module API
+
+`/arcane/modules/Ollama.js` exports the `Ollama` class, a frozen `ollama`
+singleton, and that singleton as the default export. It also installs the
+non-writable `globalThis.arcaneOllama` convenience and emits
+`arcane-ollama-ready`. The pinned class defines exactly 24 public methods: the
+20 bridge delegates below and the four normalized helpers that follow.
+
+### Raw bridge methods
+
+| Module method | Delegation | Capability/use | Detailed Core guide |
+| --- | --- | --- | --- |
+| `version()` | `Arcane.ollama.version()` | Raw service version diagnostic. | [version](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaversion) |
+| `models()` | `Arcane.ollama.models()` | Raw installed-model diagnostic. | [models](core/reference/arcane-api/ai-and-ollama.md#arcaneollamamodels) |
+| `list()` | Calls `Arcane.ollama.models()` | Module alias for `models()`; it does not call the bridge's separate `list` alias. | [list](core/reference/arcane-api/ai-and-ollama.md#arcaneollamalist) |
+| `running()` | `Arcane.ollama.running()` | Raw resident-model diagnostic. | [running](core/reference/arcane-api/ai-and-ollama.md#arcaneollamarunning) |
+| `show(model, options)` | `Arcane.ollama.show(...)` | Raw bounded model metadata. | [show](core/reference/arcane-api/ai-and-ollama.md#arcaneollamashow) |
+| `generate(request, options)` | `Arcane.ollama.generate(...)` | Admitted generation; optional chunk callback/signal/timeout. | [generate](core/reference/arcane-api/ai-and-ollama.md#arcaneollamagenerate) |
+| `chat(request, options)` | `Arcane.ollama.chat(...)` | Admitted chat/tools; optional chunk callback/signal/timeout. | [chat](core/reference/arcane-api/ai-and-ollama.md#arcaneollamachat) |
+| `embed(request)` | `Arcane.ollama.embed(...)` | Admitted embeddings. | [embed](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaembed) |
+| `pull(model, options, streamOptions)` | `Arcane.ollama.pull(...)` | Managed/policy-bound pull; denied to ordinary raw app flow. | [pull](core/reference/arcane-api/ai-and-ollama.md#arcaneollamapull) |
+| `push(model, options, streamOptions)` | `Arcane.ollama.push(...)` | Raw push is policy-restricted/denied where documented. | [push](core/reference/arcane-api/ai-and-ollama.md#arcaneollamapush) |
+| `create(request, options)` | `Arcane.ollama.create(...)` | Exact package-owned verified definition only. | [create](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacreate) |
+| `copy(source, destination)` | `Arcane.ollama.copy(...)` | Intentionally denied to applications; managed selection owns aliases. | [copy](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacopy) |
+| `delete(model)` | `Arcane.ollama.delete(...)` | Destructive exact package-owned verified model deletion. | [delete](core/reference/arcane-api/ai-and-ollama.md#arcaneollamadelete) |
+| `selection()` | `Arcane.ollama.selection()` | Reads managed model preference/effective state. | [selection](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaselection) |
+| `select(preference)` | `Arcane.ollama.select(...)` | Runs managed size-selection/download/alias workflow. | [select](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaselect) |
+| `settings()` | `Arcane.ollama.settings()` | Reads managed runtime/provider settings. | [settings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasettings) |
+| `saveSettings(settings)` | `Arcane.ollama.saveSettings(...)` | Saves runtime-owned default/load/context settings. | [saveSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasavesettings) |
+| `createBrain(definition)` | `Arcane.ollama.createBrain(...)` | Creates a managed `arcane-<slug>:latest` alias. | [createBrain](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacreatebrain) |
+| `serviceSettings()` | `Arcane.ollama.serviceSettings()` | Reads host-level Ollama service configuration/support. | [serviceSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaservicesettings) |
+| `saveServiceSettings(settings)` | `Arcane.ollama.saveServiceSettings(...)` | Applies privileged machine-wide service settings/restart. | [saveServiceSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasaveservicesettings) |
+
+### Normalized helper methods
+
+## `ollama.readiness()`
+
+### Overview
+
+Calls `version()` and converts success/failure into a frozen readiness snapshot.
+It never throws for service unavailability.
+
+### Return value
+
+`{ready:true, version, errorCode:null}` on success, or
+`{ready:false, version:null, errorCode}` on failure. A string version and an
+object `{version}` are both accepted.
+
+### Example
+
+```javascript
+const {ready, version, errorCode} = await ollama.readiness();
+console.log(ready ? version : errorCode);
+```
+
+## `ollama.generateText()`
+
+### Overview
+
+Calls `generate()` and coerces the final envelope's `response` field to a
+string with `String(response?.response || '')`. Valid Ollama responses document
+`response` as a string. If an out-of-contract response supplies a truthy
+nonstring, the helper stringifies it; a missing, null, undefined, or other
+falsy nonstring value becomes an empty string.
+
+### Example
+
+```javascript
+const text = await ollama.generateText({
+    model: 'arcane:latest',
+    prompt: 'Write one sentence.'
+});
+```
+
+## `ollama.chatText()`
+
+### Overview
+
+Calls `chat()` and coerces the final envelope's `message.content` field to a
+string with `String(response?.message?.content || '')`. Valid Ollama responses
+document `message.content` as a string. If an out-of-contract response supplies
+a truthy nonstring, the helper stringifies it; a missing, null, undefined, or
+other falsy nonstring value becomes an empty string. Use `chat()` when tool
+calls, metrics, context, or optional provider fields matter.
+
+### Example
+
+```javascript
+const text = await ollama.chatText({
+    model: 'arcane:latest',
+    messages: [{role: 'user', content: 'Hello'}]
+});
+```
+
+## `ollama.unload()`
+
+### Overview
+
+Translates `unload(model)` to:
+
+```javascript
+ollama.generate({model, prompt: '', keep_alive: 0});
+```
+
+It returns the raw final generation envelope. It is a convenience request, not
+a proof that no other admitted client reloaded the model concurrently.
+
+### Example
+
+```javascript
+async function unloadAfterTheUserChooses(model) {
+    return ollama.unload(model);
+}
+```
+
+## Availability matrix
+
+| Host | Inference | Raw inventory | Managed model/settings mutation | Notes |
+| --- | --- | --- | --- | --- |
+| Microsoft NT desktop Core | Yes when `ai.inference` is admitted | Settings/Shell/Terminal with `ai.models.read` | Admitted Settings/Shell journeys with management capabilities and privilege where required | Full managed ArcaneOllama service path. |
+| Linux desktop Core | Yes when admitted | Admitted diagnostics | Managed workflows where implemented; administrator-owned service settings can return manual/unsupported guidance | Same application API, different host/service implementation. |
+| Android WebView | Narrow admitted chat/inference projection for configured user-managed loopback | No general desktop raw inventory | No desktop model/service management | `managedLocalAI` remains false; listener reachability is not management authority. |
+| Development HTTP bridge | Only when connected to an admitted Core-backed development host | Host/method dependent | Host/method dependent; never production authority | Development transport, not a standalone-browser upgrade. |
+| Standalone browser | No Arcane Ollama | No | No | `ARCANE_OLLAMA_UNAVAILABLE`. |
+| TWiN Cloud | Not through `Arcane.ollama` | No | No | Use an explicitly selected `AI.js` cloud profile; no automatic fallback. |
+
+## Capabilities and policy
+
+- `ai.inference` admits package-filtered local generation, chat, and embeddings.
+- `ai.models.read` admits raw model diagnostics only to authorized system apps.
+- `ai.models.manage` admits policy-bound managed model lifecycle operations.
+- `ai.settings.manage` admits Settings-owned runtime/service configuration.
+- `ai.models.unverified.inference` is an explicit inference-only exception for
+  already installed, hardware-admitted unverified models when the package says
+  `verified_only:false`; it does not admit model mutation.
+
+The method allowlist is necessary but not sufficient. Exact package-owned model
+definitions, reserved aliases, native resources, platform support, installed
+state, and exclusive mutation policy remain authoritative.
+
+## Raw versus normalized behavior
+
+The module intentionally has two levels:
+
+| Boundary | Normalized by Arcane | Intentionally preserved |
+| --- | --- | --- |
+| Missing bridge | Throws coded `ARCANE_OLLAMA_UNAVAILABLE`. | Nothing reaches a provider. |
+| Core call | Promise settlement, capability/policy errors, request limits, diagnostics, stream ids/chunks. | Bounded Ollama success fields and optional provider detail. |
+| `readiness()` | Frozen Boolean/version/error-code snapshot. | Provider error detail is reduced to `errorCode`. |
+| `generateText()` / `chatText()` | Uses `String(value || '')`: documented string values pass through, truthy nonstrings stringify, and falsy nonstrings become empty. | Tool calls, timings, context, and other fields are discarded. |
+| `unload()` | Stable translation to `keep_alive:0`. | Final generation envelope remains provider-native. |
+
+## Streaming, cancellation, and uncertain mutation state
+
+`generate`, `chat`, `pull`, `push`, and `create` accept stream controls through
+the bridge forms documented on their detailed pages. Core cooperatively cancels
+admitted inference methods where documented. For pull, push, create, selection,
+settings, or service mutation, abort/timeout/page teardown can stop renderer
+observation without proving host work rolled back.
+
+After an uncertain model mutation, refresh the relevant raw inventory,
+`selection()`, `settings()`, `serviceSettings()`, or `localAI.status()` before
+retrying. Do not stack a second mutation merely because the renderer timed out.
+
+## Behavioral testing
+
+The SDK behavior suite uses an explicit fake `Arcane.ollama` to prove:
+
+- every wrapper forwards the exact argument objects and provider-native result;
+- stream options and signals are not rewritten;
+- bridge absence throws `ARCANE_OLLAMA_UNAVAILABLE` before provider work;
+- `readiness()` returns frozen success/failure snapshots;
+- `generateText()` and `chatText()` use the pinned `String(value || '')`
+  behavior: truthy nonstrings stringify and falsy nonstrings become empty;
+- `unload()` sends exactly `{model, prompt: "", keep_alive: 0}`.
+
+Those tests prove the shipped renderer module. Live Core dispatch, cancellation,
+ArcaneOllama health, real model pulls, GPU admission, service restart, and
+rollback remain Arcane OS host/integration evidence.
+
+Deep implementation path: [Arcane Ollama protocol](protocols.md#arcane-ollama-protocol-path).