@blastlauncher/protocol 0.0.0-stage → 3.0.0-alpha.1

package/dist/framing.js

@@ -0,0 +1,115 @@
+/** 8 MiB, per docs/decisions/0001: lines have a size cap. */
+export const DEFAULT_MAX_LINE_BYTES = 8 * 1024 * 1024;
+/** One message as one JSON line, ready to write to the stream. */
+export function encodeMessage(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+const NEWLINE = 0x0a;
+const HIGH_SURROGATE_START = 0xd800;
+const HIGH_SURROGATE_END = 0xdbff;
+export function createLineDecoder(options) {
+    const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+    if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes < 1) {
+        throw new RangeError("maxLineBytes must be a positive integer");
+    }
+    const encoder = new TextEncoder();
+    // `fatal` turns a truncated or overlong sequence into a protocol error rather
+    // than silently writing U+FFFD into the message.
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let buffer = new Uint8Array(0);
+    // A string chunk can end between the halves of a surrogate pair; the high
+    // half waits here so the pair is encoded as one character.
+    let heldHighSurrogate = "";
+    let stopped = false;
+    function stop(error) {
+        stopped = true;
+        options.onError(error);
+    }
+    function append(bytes) {
+        const joined = new Uint8Array(buffer.length + bytes.length);
+        joined.set(buffer);
+        joined.set(bytes, buffer.length);
+        buffer = joined;
+    }
+    function emitLine(line) {
+        if (line.length > maxLineBytes) {
+            stop(`line exceeds ${maxLineBytes} bytes`);
+            return;
+        }
+        let text;
+        try {
+            text = decoder.decode(line);
+        }
+        catch {
+            stop("line is not valid UTF-8");
+            return;
+        }
+        // Whitespace-only lines are framing noise, not messages.
+        if (text.trim() === "")
+            return;
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch (error) {
+            stop(`invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        options.onLine(value);
+    }
+    function drain() {
+        let start = 0;
+        for (;;) {
+            const index = buffer.indexOf(NEWLINE, start);
+            if (index === -1)
+                break;
+            emitLine(buffer.subarray(start, index));
+            if (stopped)
+                return;
+            start = index + 1;
+        }
+        if (start > 0)
+            buffer = buffer.slice(start);
+        // Checked before the terminator arrives so one bad line cannot grow the
+        // buffer without bound.
+        if (buffer.length > maxLineBytes)
+            stop(`line exceeds ${maxLineBytes} bytes`);
+    }
+    function encodeChunk(text) {
+        let value = heldHighSurrogate + text;
+        heldHighSurrogate = "";
+        const last = value.charCodeAt(value.length - 1);
+        if (last >= HIGH_SURROGATE_START && last <= HIGH_SURROGATE_END) {
+            heldHighSurrogate = value.slice(-1);
+            value = value.slice(0, -1);
+        }
+        return encoder.encode(value);
+    }
+    return {
+        push(chunk) {
+            if (stopped)
+                return;
+            // Copy the caller's bytes: the buffer outlives the call.
+            const bytes = typeof chunk === "string" ? encodeChunk(chunk) : new Uint8Array(chunk);
+            if (bytes.length === 0)
+                return;
+            append(bytes);
+            drain();
+        },
+        end() {
+            if (stopped)
+                return;
+            if (heldHighSurrogate !== "") {
+                append(encoder.encode(heldHighSurrogate));
+                heldHighSurrogate = "";
+            }
+            const leftover = buffer;
+            buffer = new Uint8Array(0);
+            if (leftover.length === 0) {
+                stopped = true;
+                return;
+            }
+            stop(`unterminated line: ${leftover.length} bytes without a newline`);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./capabilities.js";
+export * from "./framing.js";
+export * from "./messages.js";
+export * from "./provider.js";
+export * from "./provider-codec.js";
+export * from "./embedder.js";
+export * from "./embedder-schema.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public surface: everything a host or a runtime needs to speak the protocol.
+export * from "./capabilities.js";
+export * from "./framing.js";
+export * from "./messages.js";
+export * from "./provider.js";
+export * from "./provider-codec.js";
+export * from "./embedder.js";
+export * from "./embedder-schema.js";

package/dist/messages.d.ts

@@ -0,0 +1,153 @@
+import type { ModelStreamPart, RegisteredModel } from "./provider.js";
+export declare const PROTOCOL_VERSION = 1;
+/** A value that survives `JSON.stringify` -> `JSON.parse` unchanged. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A callback prop on the wire; the host answers with an `event` message. */
+export type HandlerRef = {
+    $handler: string;
+};
+export type SceneNode = {
+    id: string;
+    type: string;
+    props: Record<string, JsonValue | HandlerRef>;
+    children: SceneNode[];
+};
+/** How the host expects the command to run. */
+export type CommandMode = "view" | "no-view" | "menu-bar" | "model-provider";
+export type InitCommand = {
+    extension: string;
+    name: string;
+    entry: string;
+    mode: CommandMode;
+    /** Manifest argument values, keyed by argument name (decision 0001). */
+    arguments?: Record<string, string>;
+    /** The `launchCommand({ context })` payload of this launch, if any. */
+    launchContext?: Record<string, JsonValue>;
+    /** Search text supplied when invoking a fallback command. */
+    fallbackText?: string;
+    /** A stored `Form` draft for this command, read by the host before launch. */
+    draftValues?: Record<string, JsonValue>;
+};
+export type InitEnvironment = {
+    availableAPIs?: ("AI" | "BrowserExtension")[];
+    extensionName: string;
+    commandName: string;
+    /** The manifest's `owner`, falling back to `author` (Raycast's `ownerOrAuthorName`). */
+    ownerOrAuthorName: string;
+    assetsPath: string;
+    supportPath: string;
+    isDevelopment: boolean;
+    /** The active theme; a headless host has no UI, so the default is `"dark"`. */
+    appearance: "light" | "dark";
+    textSize: "medium" | "large";
+};
+export type InitMessage = {
+    type: "init";
+    protocol: number;
+    command: InitCommand;
+    preferences: Record<string, JsonValue>;
+    environment: InitEnvironment;
+};
+export type EventMessage = {
+    type: "event";
+    node: string;
+    handler: string;
+    args: JsonValue[];
+};
+export type ErrorInfo = {
+    code: string;
+    message: string;
+};
+export type CapabilityResultMessage = {
+    type: "capability.result";
+    id: string;
+    ok: true;
+    value: JsonValue;
+} | {
+    type: "capability.result";
+    id: string;
+    ok: false;
+    error: ErrorInfo;
+};
+export type ShutdownMessage = {
+    type: "shutdown";
+};
+/** Messages the host sends to the runtime. */
+export type ProviderRequest = {
+    type: "provider.getModels";
+    id: string;
+} | {
+    type: "provider.stream";
+    id: string;
+    model: RegisteredModel;
+    request: Record<string, JsonValue>;
+} | {
+    type: "provider.abort";
+    id: string;
+};
+export type ProviderResponse = {
+    type: "provider.models";
+    id: string;
+    models: RegisteredModel[];
+} | {
+    type: "provider.part";
+    id: string;
+    part: ModelStreamPart;
+} | {
+    type: "provider.end";
+    id: string;
+} | {
+    type: "provider.error";
+    id: string;
+    error: ErrorInfo;
+};
+export type HostMessage = InitMessage | EventMessage | CapabilityResultMessage | {
+    type: "capability.progress";
+    id: string;
+    value: JsonValue;
+} | ShutdownMessage | ProviderRequest;
+export type ReadyMessage = {
+    type: "ready";
+    protocol: number;
+};
+export type SceneMessage = {
+    type: "scene";
+    revision: number;
+    root: SceneNode | null;
+};
+export type CapabilityRequestMessage = {
+    type: "capability.request";
+    id: string;
+    name: string;
+    params: JsonValue;
+};
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogMessage = {
+    type: "log";
+    level: LogLevel;
+    message: string;
+};
+export type ErrorMessage = {
+    type: "error";
+    code: string;
+    message: string;
+    fatal: boolean;
+};
+/** Messages the runtime sends to the host. */
+export type RuntimeMessage = ProviderResponse | ReadyMessage | SceneMessage | CapabilityRequestMessage | {
+    type: "capability.cancel";
+    id: string;
+} | LogMessage | ErrorMessage;
+export type ParseResult<T> = {
+    ok: true;
+    message: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** Validates an untyped value as a host -> runtime message. */
+export declare function parseHostMessage(value: unknown): ParseResult<HostMessage>;
+/** Validates an untyped value as a runtime -> host message. */
+export declare function parseRuntimeMessage(value: unknown): ParseResult<RuntimeMessage>;