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

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Yukai Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @blastlauncher/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Blast's engine package.
+Emitted ESM and TypeScript declarations for Node.js 24.20+.
+See https://github.com/BlastLauncher/blast for documentation.

package/dist/ai.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityRequestMessage } from "@blastlauncher/protocol";
+import { type CapabilityContext } from "./broker.js";
+import type { StartOptions } from "./session.js";
+/** Own-extension providers share the command's lifetime and need no capability grant. */
+export declare function createAIRouter(options: StartOptions): {
+    broker(request: CapabilityRequestMessage, context?: CapabilityContext): Promise<import("@blastlauncher/protocol").CapabilityResultMessage>;
+    shutdown(): Promise<void>;
+};

package/dist/ai.js

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { bundleModelProvider } from "./bundle.js";
+import { startModelProvider } from "./provider.js";
+import { createBroker } from "./broker.js";
+/** Own-extension providers share the command's lifetime and need no capability grant. */
+export function createAIRouter(options) {
+    const sessionId = randomUUID();
+    let loading;
+    let directory;
+    let models;
+    const provider = () => (loading ??= (async () => {
+        const bundled = await bundleModelProvider({
+            extensionDir: options.modelProviderDir,
+            ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+        });
+        directory = dirname(bundled.entry);
+        const { environment: _environment, ...inherited } = options;
+        return startModelProvider({
+            ...inherited,
+            ...bundled,
+            ...(options.environment
+                ? { environment: { ...options.environment, commandName: bundled.commandName } }
+                : {}),
+        });
+    })());
+    const broker = createBroker({
+        "ai.models.refresh": async () => {
+            if (options.modelProviderDir)
+                models = await (await provider()).getModels();
+        },
+        "ai.ask": async (params, context = { signal: new AbortController().signal, progress() { } }) => {
+            const { model, prompt, creativity } = params;
+            const session = await provider();
+            models ??= await session.getModels();
+            if (context.signal.aborted)
+                throw new DOMException("The operation was aborted", "AbortError");
+            const selected = models.find((item) => item.id === model.id);
+            if (!selected)
+                throw new Error(`Unknown model ${model.id}`);
+            const temperature = typeof creativity === "number"
+                ? Math.max(0, Math.min(2, creativity))
+                : creativity === undefined
+                    ? undefined
+                    : { none: 0, low: 0.5, medium: 1, high: 1.5, maximum: 2 }[creativity];
+            let text = "";
+            for await (const part of session.stream(selected, {
+                messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
+                ...(temperature === undefined ? {} : { temperature }),
+                providerOptions: {
+                    raycast: {
+                        locale: "en",
+                        currentDate: new Date().toISOString(),
+                        sessionId,
+                    },
+                },
+            }, { signal: context.signal })) {
+                if (part.type === "error")
+                    throw new Error(String(part.error));
+                const chunk = part.type === "text-delta"
+                    ? (part.textDelta ?? part.text)
+                    : part.type === "text"
+                        ? part.text
+                        : undefined;
+                if (chunk !== undefined) {
+                    text += chunk;
+                    context.progress(chunk);
+                }
+            }
+            return text;
+        },
+    });
+    return {
+        broker(request, context) {
+            const model = request.params?.model;
+            return request.name === "ai.models.refresh" ||
+                (options.modelProviderDir &&
+                    request.name === "ai.ask" &&
+                    model !== null &&
+                    typeof model === "object")
+                ? broker(request, context)
+                : options.broker(request, context);
+        },
+        async shutdown() {
+            try {
+                await (await loading)?.shutdown({ timeoutMs: 250 });
+            }
+            catch {
+                /* Startup failures still own a bundle directory. */
+            }
+            finally {
+                if (directory)
+                    await rm(directory, { recursive: true, force: true });
+            }
+        },
+    };
+}

package/dist/broker.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityRequestMessage, CapabilityResultMessage, JsonValue } from "@blastlauncher/protocol";
+export type CapabilityContext = {
+    signal: AbortSignal;
+    progress(value: JsonValue): void;
+};
+export type CapabilityHandler = (params: JsonValue, context?: CapabilityContext) => JsonValue | void | Promise<JsonValue | void>;
+export type Broker = (request: CapabilityRequestMessage, context?: CapabilityContext) => Promise<CapabilityResultMessage>;
+export declare function createBroker(handlers?: Record<string, CapabilityHandler>): Broker;

package/dist/broker.js

@@ -0,0 +1,30 @@
+export function createBroker(handlers = {}) {
+    const grants = new Map(Object.entries(handlers));
+    return async ({ id, name, params }, context = { signal: new AbortController().signal, progress() { } }) => {
+        const handler = grants.get(name);
+        if (!handler) {
+            return {
+                type: "capability.result",
+                id,
+                ok: false,
+                error: { code: "denied", message: `Capability denied: ${name}` },
+            };
+        }
+        try {
+            return {
+                type: "capability.result",
+                id,
+                ok: true,
+                value: (await handler(params, context)) ?? null,
+            };
+        }
+        catch (error) {
+            return {
+                type: "capability.result",
+                id,
+                ok: false,
+                error: { code: "failed", message: error instanceof Error ? error.message : String(error) },
+            };
+        }
+    };
+}

package/dist/bundle.d.ts

@@ -0,0 +1,93 @@
+import type { CommandMode } from "@blastlauncher/protocol";
+import { symlink } from "node:fs/promises";
+import { type SharedDependencyLoader } from "./dependencies.js";
+export declare class MissingDependencyError extends Error {
+    readonly code = "MISSING_DEPENDENCY";
+    readonly packages: string[];
+    constructor(packages: Iterable<string>);
+}
+export declare class NativeModuleError extends Error {
+    readonly code = "NATIVE_MODULE";
+    readonly modules: string[];
+    constructor(modules: Iterable<string>);
+}
+export declare class BundleTimeoutError extends Error {
+    readonly code = "BUNDLE_TIMEOUT";
+    readonly extension: string;
+    readonly command: string;
+    readonly timeoutMs: number;
+    constructor(extension: string, command: string, timeoutMs: number);
+}
+export declare class BundleContainmentError extends Error {
+    readonly code = "BUNDLE_OUTSIDE_ROOT";
+    readonly specifier: string;
+    constructor(specifier: string);
+}
+export type BundleOptions = {
+    extensionDir: string;
+    command: string;
+    /** Bundling deadline in milliseconds; defaults to 60_000, 0 disables it. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Override optional-package loading, e.g. for an isolated embedder. */
+    sharedDependencies?: SharedDependencyLoader;
+    outDir?: string;
+    dataDir?: string;
+    /** `false` keeps resolution allowlist-only, as corpus reports need (decision 0008). */
+    installedDependencies?: boolean;
+};
+/** One `commands[].arguments` entry from an extension manifest. */
+export type CommandArgument = {
+    name: string;
+    type: string;
+    /** A required argument must be supplied before the command starts. */
+    required?: boolean;
+    placeholder?: string;
+};
+export type BundledCommand = {
+    /** Elapsed bundling time, including dependency resolution and assets. */
+    bundleMs: number;
+    modelProviderDir?: string;
+    entry: string;
+    extensionName: string;
+    commandName: string;
+    /** The manifest's `owner`, else `author`; defaults to `""` for bare entries. */
+    ownerOrAuthorName?: string;
+    mode: CommandMode;
+    /** The manifest's argument declarations, in declaration order. */
+    arguments: CommandArgument[];
+    /**
+     * The declared default of every manifest preference (extension-wide, then
+     * the command's own overriding it). A caller's explicit values win over
+     * these when the session starts.
+     */
+    preferenceDefaults?: Record<string, string | number | boolean>;
+    /** `<outDir>/assets`, resolving to the extension's real assets when it has any. */
+    assetsPath?: string;
+    /** Shared packages whose supplied major disagrees with the manifest. */
+    dependencyWarnings?: string[];
+};
+export type Preference = {
+    name: string;
+    type: string;
+    title: string;
+    description?: string;
+    required: boolean;
+    data: {
+        title: string;
+        value: string;
+    }[];
+    default?: string | number | boolean;
+};
+/** Shared manifest parsing for bundling defaults and client preference forms. */
+export declare function parsePreferences(value: unknown, at?: string): Preference[];
+/**
+ * The build directory mirrors Raycast's layout: `assets/` sits next to the
+ * bundle, so `environment.assetsPath` and `path.join(__dirname, "assets", …)`
+ * both resolve to the extension's real assets. The link is a symlink; where
+ * the platform refuses symlinks, a read-only copy with a size cap is used.
+ * Nothing is ever written to the extension directory.
+ */
+export declare function linkAssets(outDir: string, extensionDir: string, link?: typeof symlink): Promise<void>;
+export declare function bundleModelProvider(options: Omit<BundleOptions, "command">): Promise<BundledCommand>;
+export declare function bundleCommand(options: BundleOptions): Promise<BundledCommand>;