arcane-os 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.44.0
+
+- Add stateless `generateImages` through `arcane-os/ai/twin-cloud` with
+  caller-selected FAL Flux Schnell or Stable Diffusion 3.5 Large. Preserve
+  complete prompts and provider parameters, and return every image as a Blob
+  in provider order with declared media metadata.
+- Expose semantic progress and complete diagnostic callbacks, asynchronous
+  job polling, and cancellation across credentials, callbacks, requests,
+  response bodies and media downloads. Submit a paid generation request once;
+  never automatically replay an ambiguous submission.
+- Keep image model selection, credentials, display and storage with the
+  application. No global model default, saved-history migration, durable media
+  storage or change to existing chat and speech behavior is introduced.
+
 ## 0.43.0
 
 - Add reusable rendered printing through `createPrintView`, preserving the

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.43.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.44.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

@@ -105,6 +105,240 @@ export function normalizeAIRequestAbort(error){
     return normalized;
 }
 
+/** Stateless image generation; model selection and provider parameters belong to the caller. */
+export async function generateImages({
+    model,
+    prompt,
+    parameters = {},
+    twinKey,
+    getApiKey,
+    signal = null,
+    id = Date.now(),
+    onRequest = function observeImageRequest(){},
+    onResponse = function observeImageResponse(){},
+    onProgress = function observeImageProgress(){}
+} = {}) {
+    if (signal?.aborted) throw normalizeAIRequestAbort(signal.reason);
+    const asynchronous = model === 'fal-ai/flux/schnell';
+    if (!asynchronous && model !== 'stable-diffusion-3.5-large') {
+        const error = new TypeError('TWiN generateImages requires a supported explicit image model.');
+        error.code = 'ARCANE_AI_IMAGE_MODEL_UNSUPPORTED';
+        throw error;
+    }
+    if (!is.string(prompt)) throw new TypeError('TWiN generateImages requires a prompt string.');
+    if (!parameters || !is.object(parameters) || is.array(parameters)) {
+        throw new TypeError('Image parameters must be an object of additional provider fields.');
+    }
+    if (Object.hasOwn(parameters, 'prompt') || (!asynchronous && Object.hasOwn(parameters, 'model'))) {
+        throw new TypeError('Supply the image prompt and model through their named arguments.');
+    }
+    const destination = asynchronous
+        ? 'https://inference.do-ai.run/v1/async-invoke'
+        : 'https://inference.do-ai.run/v1/images/generations';
+    const request = asynchronous
+        ? {model_id: model, input: {...parameters, prompt}}
+        : {...parameters, model, prompt};
+    // Observe the complete request without allowing a later callback to rewrite its payload.
+    const body = JSON.stringify(request);
+    const outputFormat = parameters.output_format;
+    const controller = new AbortController();
+    const operationSignal = controller.signal;
+    function cancelImageRequest() {controller.abort(signal.reason);}
+    signal?.addEventListener('abort', cancelImageRequest, {once: true});
+    if (signal?.aborted) cancelImageRequest();
+
+    function progress(stage, requestId) {
+        return settleImageOperation(
+            function publishImageProgress() {
+                return onProgress({stage, model, id, ...(requestId === undefined ? {} : {requestId})});
+            },
+            operationSignal
+        );
+    }
+
+    async function inference(url, options) {
+        const response = await settleImageOperation(
+            function requestImageInference() {return fetch(url, {...options, credentials: 'omit', signal: operationSignal});},
+            operationSignal
+        );
+        const result = await settleImageOperation(
+            function readImageInference() {
+                if (response.ok || response.headers.get('content-type')?.includes('application/json')) {
+                    return response.json();
+                }
+                return response.text();
+            },
+            operationSignal
+        );
+        if (!response.ok) throw result;
+        const retryAfter = response.headers.get('retry-after');
+        const seconds = retryAfter?.trim() ? Number(retryAfter) : NaN;
+        const date = retryAfter?.trim() ? Date.parse(retryAfter) : NaN;
+        const delay = is.finite(seconds) && seconds >= 0 ? seconds * 1000
+            : is.finite(date) ? Math.max(0, date - Date.now()) : 1000;
+        return {result, delay};
+    }
+
+    try {
+        await progress('credentials');
+        const key = twinKey === undefined && is.function(getApiKey)
+            ? await settleImageOperation(getApiKey, operationSignal) : twinKey;
+        if (!is.string(key) || !key) {
+            const error = new Error('AI provider is not configured.');
+            error.code = 'AI_PROVIDER_NOT_CONFIGURED';
+            throw error;
+        }
+        const headers = {'Content-Type': 'application/json', Authorization: `Bearer ${key}`};
+        await settleImageOperation(
+            function observeImageSubmission() {
+                return onRequest(request, id, {operation: 'images', transport: 'http', destination});
+            },
+            operationSignal
+        );
+        await progress('requesting');
+        // A lost POST response can represent an accepted paid job. Never replay it.
+        let response = await inference(destination, {method: 'POST', headers, body});
+        let result = response.result;
+        if (asynchronous) {
+            const requestId = result?.request_id;
+            while (result?.status === 'QUEUED' || result?.status === 'IN_PROGRESS') {
+                if (!is.string(requestId) || !requestId) {
+                    throw imageResultError('Image generation returned a pending job without a request_id.', result);
+                }
+                await progress(result.status === 'QUEUED' ? 'queued' : 'generating', requestId);
+                await waitForImageStatus(response.delay, operationSignal);
+                response = await inference(
+                    `${destination}/${encodeURIComponent(requestId)}/status`,
+                    {method: 'GET', headers}
+                );
+                result = response.result;
+            }
+            if (result?.status === 'FAILED') {
+                throw imageResultError('TWiN Cloud image generation failed.', result);
+            }
+            if (result?.status !== 'COMPLETED' && result?.status !== 'COMPLETE') {
+                throw imageResultError('TWiN Cloud returned an unsupported image job status.', result);
+            }
+            if (!is.array(result.output?.images)) {
+                if (!is.string(requestId) || !requestId) {
+                    throw imageResultError('Image generation returned no result or request_id.', result);
+                }
+                response = await inference(`${destination}/${encodeURIComponent(requestId)}`, {method: 'GET', headers});
+                result = response.result;
+                if (result?.status !== 'COMPLETED' && result?.status !== 'COMPLETE') {
+                    throw imageResultError('TWiN Cloud image generation did not return a completed result.', result);
+                }
+            }
+        }
+        const returnedImages = asynchronous ? result?.output?.images : result?.data;
+        if (!is.array(returnedImages)) {
+            throw imageResultError('TWiN Cloud returned no image collection.', result);
+        }
+        const images = returnedImages.map(function retainImageDescriptor(image) {return {...image};});
+        const format = result.output_format ?? outputFormat;
+        const requestId = asynchronous ? result.request_id : undefined;
+        await settleImageOperation(
+            function observeImageResult() {return onResponse(result, id, false);},
+            operationSignal
+        );
+        await progress('downloading', requestId);
+        const completed = await Promise.all(images.map(async function materializeImage(image) {
+            let blob;
+            const mediaType = image.content_type
+                ?? ({png: 'image/png', jpeg: 'image/jpeg', jpg: 'image/jpeg', webp: 'image/webp'}[format])
+                ?? 'application/octet-stream';
+            if (is.string(image.b64_json)) {
+                blob = await settleImageOperation(function decodeImageBase64() {
+                    return new Blob([Uint8Array.from(atob(image.b64_json), function imageCode(character) {
+                        return character.charCodeAt(0);
+                    })], {type: mediaType});
+                }, operationSignal);
+            } else if (is.string(image.url) && image.url) {
+                // Media URLs have their own delivery authority. Never forward the inference key.
+                const download = await settleImageOperation(function downloadGeneratedImage() {
+                    return fetch(image.url, {credentials: 'omit', signal: operationSignal});
+                }, operationSignal);
+                if (!download.ok) {
+                    throw await settleImageOperation(function readImageDownloadError() {
+                        return download.headers.get('content-type')?.includes('application/json')
+                            ? download.json() : download.text();
+                    }, operationSignal);
+                }
+                blob = await settleImageOperation(function readGeneratedImage() {return download.blob();}, operationSignal);
+                if (!blob.type) blob = new Blob([blob], {type: mediaType});
+            } else {
+                throw imageResultError('TWiN Cloud returned an image without data or a URL.', image);
+            }
+            return {
+                blob,
+                mediaType: blob.type || mediaType,
+                ...(image.width === undefined ? {} : {width: image.width}),
+                ...(image.height === undefined ? {} : {height: image.height})
+            };
+        }));
+        await progress('complete', requestId);
+        if (operationSignal.aborted) throw normalizeAIRequestAbort(operationSignal.reason);
+        return {images: completed};
+    } catch (error) {
+        if (isAIRequestAbort(error, operationSignal)) throw normalizeAIRequestAbort(error);
+        throw error;
+    } finally {
+        signal?.removeEventListener('abort', cancelImageRequest);
+        controller.abort('Image operation settled.');
+    }
+}
+
+function imageResultError(message, result) {
+    const error = new Error(message, {cause: result});
+    error.code = 'ARCANE_AI_INVALID_PROVIDER_RESULT';
+    return error;
+}
+
+/** Abort a wait even when a credential, callback, or host Fetch ignores the signal. */
+function settleImageOperation(operation, signal) {
+    return new Promise(function settleCloudImageOperation(resolve, reject) {
+        let settled = false;
+        function finish(error, value, failed) {
+            if (settled) return;
+            settled = true;
+            signal.removeEventListener('abort', cancelled);
+            if (failed) reject(error);
+            else resolve(value);
+        }
+        function cancelled() {finish(normalizeAIRequestAbort(signal.reason), undefined, true);}
+        signal.addEventListener('abort', cancelled, {once: true});
+        if (signal.aborted) {
+            cancelled();
+            return;
+        }
+        try {
+            Promise.resolve(operation()).then(
+                function accepted(value) {finish(undefined, value, false);},
+                function rejected(error) {finish(error, undefined, true);}
+            );
+        } catch (error) {
+            finish(error, undefined, true);
+        }
+    });
+}
+
+async function waitForImageStatus(delay, signal) {
+    let remaining = delay;
+    do {
+        // Split only at the host timer range; retain the provider's entire delay.
+        const milliseconds = Math.min(remaining, 2147483647);
+        let timer;
+        try {
+            await settleImageOperation(function waitForImagePoll() {
+                return new Promise(function scheduleImagePoll(finish) {timer = setTimeout(finish, milliseconds);});
+            }, signal);
+        } finally {
+            clearTimeout(timer);
+        }
+        remaining -= milliseconds;
+    } while (remaining > 0);
+}
+
 export function structuredOutputFormat(value = false){
     if(value === false || value === null || value === undefined){
         return null;

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

@@ -136,6 +136,130 @@ options; they do not add a key, model, browser state, or retained conversation.
 Retry warnings and observer failures use the shared console logger and preserve
 the complete original error.
 
+## Generate images with an application-selected model
+
+`generateImages` is a separate stateless operation on the same public import.
+The application owns the selected model, labels, prompt, provider parameters,
+credential source, display, and any saved image. It does not instantiate the
+browser AI singleton or change chat, speech, model preferences, or history.
+
+```javascript
+import {generateImages} from 'arcane-os/ai/twin-cloud';
+
+const controller = new AbortController();
+const {images} = await generateImages({
+    model: 'stable-diffusion-3.5-large',
+    prompt: 'A moon-powered toaster launches croissants over purple craters.',
+    parameters: {n: 2, size: '1024x1024', output_format: 'png'},
+    getApiKey: applicationRuntime.getTwinKey,
+    signal: controller.signal,
+    onProgress({stage}) {
+        console.log(stage);
+    }
+});
+
+for (const image of images) {
+    await applicationRuntime.saveGeneratedImage(image.blob, image.mediaType);
+}
+```
+
+`applicationRuntime.getTwinKey` and `saveGeneratedImage` are caller-owned
+functions in this example, not SDK APIs. Pass the credential function with any
+required receiver already bound. Use `twinKey` instead when the application
+already has its key. `getApiKey()` may return a key or a promise and is called
+only when `twinKey` is `undefined`. An explicitly supplied empty key fails with
+`AI_PROVIDER_NOT_CONFIGURED`; it does not select another credential source.
+The example's model and parameters are application choices, not SDK defaults.
+
+```javascript
+generateImages({
+    model,
+    prompt,
+    parameters,
+    twinKey,
+    getApiKey,
+    signal,
+    id,
+    onRequest,
+    onResponse,
+    onProgress
+})
+// Promise<{images: [{blob, mediaType, width?, height?}]}>
+```
+
+`parameters` defaults to `{}`, `signal` to `null`, and `id` to `Date.now()`.
+All diagnostic and progress callbacks are optional.
+
+The SDK owns the route for these exact supported identifiers:
+
+| Explicit model | Submission and result |
+| --- | --- |
+| `fal-ai/flux/schnell` | POST `/v1/async-invoke` with `{model_id:model,input:{...parameters,prompt}}`; pending jobs use GET `/v1/async-invoke/{request_id}/status`, then GET `/v1/async-invoke/{request_id}` when the completed status lacks `output.images`. |
+| `stable-diffusion-3.5-large` | POST `/v1/images/generations` with `{...parameters,model,prompt}`; images come from the completed response's `data` array. |
+
+Both routes use `https://inference.do-ai.run`. Missing or unsupported model
+identifiers reject with `ARCANE_AI_IMAGE_MODEL_UNSUPPORTED`; there is no SDK
+image model default. The prompt must be a string and is sent unchanged,
+including whitespace. `parameters` is an object of additional provider fields;
+the SDK neither supplies nor changes image counts, dimensions, quality, seeds,
+or output limits. Supply the prompt only through `prompt`, and the synchronous
+model only through `model`; duplicate reserved fields in `parameters` throw
+`TypeError` instead of silently replacing one input. Provider-supported
+parameter names and values remain that selected model's contract.
+
+Every returned image is materialized in provider order. Base64 image data
+becomes a `Blob`; returned URLs are fetched concurrently without an inference
+Authorization header or browser credentials. The output's `mediaType` uses the
+downloaded Blob's declared type, provider `content_type`, or a declared
+`output_format` of `png`, `jpeg`/`jpg`, or `webp`. With no declared type or known
+format, it is `application/octet-stream`; the SDK does not guess dimensions or
+image metadata. `width` and `height` are included only when the provider supplies
+them. The SDK saves nothing and creates no object URLs; the caller owns any
+storage and the lifetime of display URLs it creates.
+
+`onRequest(request,id,metadata)` runs once before submission with the complete
+provider request. Metadata is `{operation:'images',transport:'http',destination}`.
+`onResponse(response,id,false)` runs once with the complete final provider JSON
+after successful generation and before image materialization. Intermediate
+poll replies do not call it. These are explicit diagnostic callbacks: keep raw
+protocol outside ordinary user status and durable chat history. Credentials are
+transport-only and are absent from these payloads. The request and image
+descriptors are captured before their diagnostic callbacks so observer edits do
+not rewrite the operation's content.
+
+`onProgress({stage,model,id,requestId?})` reports semantic stages: `credentials`,
+`requesting`, `queued`, `generating`, `downloading`, and `complete`. Pending
+stages can repeat; immediately completed jobs skip them. Async job stages
+include `requestId` when present. Progress contains no image data or protocol
+body. All three callbacks may return a promise; their settlement is awaited
+and their failure rejects the operation. `onResponse` means generation returned
+a final result, not that media downloads have finished. The resolved promise
+delivers all materialized images; a failed download rejects instead of returning
+an incomplete collection.
+
+The image operation submits once and performs no automatic retry, including
+after a network loss, HTTP `429`, body-read failure, or callback failure. A lost
+POST response may correspond to an accepted paid job. This image-specific rule
+does not alter chat or speech retry behavior. While a FAL job is `QUEUED` or
+`IN_PROGRESS`, polling uses the provider's `Retry-After` delay when supplied,
+otherwise one second. Completed jobs accept `COMPLETED` and the guide's
+`COMPLETE` spelling. Failed or unusable job results reject with
+`ARCANE_AI_INVALID_PROVIDER_RESULT` and the complete result in `error.cause`.
+HTTP failures throw their complete parsed JSON or text body; transport,
+decoding, and callback failures remain their original errors.
+
+Calling `controller.abort()` cancels local credential/callback waits, requests,
+body reads, polling timers, and downloads. It rejects with
+`ARCANE_AI_REQUEST_ABORTED` and ignores later settlement from an operation that
+does not honor the signal. A callback already running remains caller-owned;
+the SDK invokes no subsequent callbacks after cancellation. Local cancellation
+does not claim to cancel a remote paid job. Dispose the controller with the
+owning page or operation; no global startup wait is required.
+
+The route and response contracts follow DigitalOcean's official
+[FAL inference guide](https://docs.digitalocean.com/products/inference/how-to/use-fal-models/)
+and [multimodal inference guide](https://docs.digitalocean.com/products/inference/how-to/use-multimodal-inference/).
+
 ## Existing browser AI interface
 
 The following browser example uses the same managed imports as the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -86,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/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-input.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: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-input.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-images.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",
     "check": "node tools/check-source.mjs && npm test",