Arcane OS SDK developer reference

This reference answers developer questions in this order:

1. What can the application or tool do?
2. What should I import or call?
3. What does a successful result look like?
4. Where does it run?
5. Only when needed: which transport, host, provider, or kernel boundary implements it?

The default path is capability-first. Transport and implementation detail is kept in the protocol and host architecture guide, and every high-level page links to the relevant deep section instead of repeating it.

Start with one working request

Install the SDK in your application:

npm install --save-exact arcane-os@0.5.17

For your first AI call, follow the TWiN Cloud quick start. For on-device speech, follow the browser speech quick start and the complete browser AI demo. Each guide names the application configuration you supply and shows the public call, response, cancellation, and error handling. Browser module imports use the SDK's materialized import map; installing npm alone does not make bare module names resolve in a browser.

Reference map

Version scope and source ownership

This repository contains explicitly versioned surfaces with different owners:

The SDK runtime source and Core reference have different owners. A browser module comes from the selected SDK runtime tree. A native build selects one explicit Arcane OS checkout and Core, then checks the declared protocol, version, features, capabilities, methods, and provider contract needed by that build. A matching protocol name or higher version alone does not promise functional compatibility.

See the Core reference source notes for the imported inventory and the distinction between a documentation snapshot and the selected runtime.

Installed documentation and release identity

This reference accompanies arcane-os@0.5.17. The installed package includes the maintained docs/ tree and examples/wasm-ai-demo/ source alongside README and CHANGELOG. Open node_modules/arcane-os/docs/reference/README.md for the matching local reference. The generated website and test suites remain repository surfaces.

Read the installed version and current registry channel separately:

npm list arcane-os
npm view arcane-os@latest version

The changelog records changes by version; the GitHub releases identify the corresponding published package source. A newer website does not change the version installed in your application.

Historical 0.3.4 publication record

The following records describe that earlier release only. They do not identify the current registry channel or the package covered by this reference.

MDN-style page contract

Public reference entries follow the established Arcane documentation model:

• one canonical, mechanically readable inventory owns each public name;
• every public member or module has one guide entry headed by its exact name;
• each guide leads with an overview and the shortest safe working example;
• parameters, return values, errors, side effects, cancellation, and events are stated when they apply;
• availability is summarized near the call, while transport mechanics are folded into or deep-linked from the entry;
• normalized results are distinguished from provider- or platform-native envelopes;
• examples do not trigger destructive, privileged, expensive, or external actions merely by being copied.

Public runtime inventory

The package exposes 202 semantic JavaScript records across 18 JavaScript entrypoints, plus eight JSON Schemas and package metadata. Ten entrypoints are Node.js control-plane surfaces, arcane-os/event-manager, arcane-os/logging, arcane-os/mail, arcane-os/preference-store, and arcane-os/speech-playback plus arcane-os/speech-text run in Node and browsers, and arcane-os/ai/browser-wasm plus arcane-os/ai/browser-speech are browser-only. The machine-readable package inventory and SDK member reference are checked bidirectionally against every declared JavaScript export.

The seven update-check records are explicit on-demand checks; they do not poll, download, install, or self-update.

The synchronized browser payload exposes:

• 83 JavaScript module artifacts under runtime/arcane/modules/, including ESM modules, classic vendor globals, one worker protocol, and one Node-oriented mail transport;
• 14 shared entity modules under runtime/arcane/entities/;
• 39 reusable HTML-import components under runtime/arcane/components/;
• seven shared CSS artifacts, images, optional physical-workspace security files where present, and the vendored strong-type dependency.

The module and component catalogs enumerate every shipped artifact, including vendor support files that are not ESM imports. The selected runtime directories and their current source inventories remain authoritative; the catalogs explain what those artifacts let a developer do.

Normalized AI

Portable applications start with the provider-neutral runtime rather than an Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:

There is no automatic local-to-cloud, browser-to-Core, provider-to-provider, or storage fallback. Tool calls remain structural data until application-owned policy and code decide whether to execute them. App prompts, model defaults, profiles, tools, business policy, and private data remain app-owned.

An explicitly selected but unloaded model is not “ready.” chat.html keeps Send disabled and exposes a visible keyboard-operable LLM Start/Try again or Cancel loading control. speech.html and voice-transcription.html keep their recording operations unavailable and share the equivalent Start transcription/Try again/Cancel loading control for STT. Applications can override requestAIActivation(intent) or requestSTTActivation(intent), or cancel the corresponding activation-request event. Imports and state observation emit no lifecycle intent, and default startTranscription=false does not request an STT startup load or begin an automatic model download. It does not unload a role started independently. Reported availability never creates ready STT/TTS state without an admitted, loaded provider. Shared STT cancel/destroy propagates an owned signal, and TTS Mute/Unmute updates the shared lifecycle owner. The selected local TTS provider/model catalog owns its default voice; a saved OpenAI-route voice is not forwarded to Core or browser speech.

Authority and feature detection

The presence of a JavaScript function is not permission to use it. Native applications should inspect Arcane.capabilities.list() where available and then call the relevant status method. Android callers with system.read obtain the nested capability snapshot through Arcane.platform.status().

Do not infer local-AI readiness from Arcane.runtime.current().managedLocalAI, infer authorization from a transport name, or treat an Ollama model inventory as package admission. Each method rechecks native policy at invocation time.

Source and licensing

• SDK runtime source
• AGPL license
• Commercial-license notice
• Third-party and distribution notice