@tomradex/plugin-sdk 0.0.0-stage → 0.2.16

package/dist/models.d.ts

@@ -0,0 +1,219 @@
+import type { Disposer, Localized, ModelMessage, ModelTool } from "./contract.js";
+type Maybe<T> = T | Promise<T>;
+/** What a model reads besides text. */
+export type ModelInput = "image" | "audio" | "video" | "pdf";
+/** What a model can answer with besides text. */
+export type ModelOutput = "image" | "audio";
+/** SDK 0.2.16. One assistant turn a profile on the provider is asked for. */
+export interface ModelChatRequest {
+    system: string;
+    messages: ModelMessage[];
+    tools?: ModelTool[];
+    toolChoice?: "auto" | "none" | {
+        name: string;
+    };
+    maxTokens?: number;
+    temperature?: number;
+    /** Reasoning effort ("low", "medium", "high"…) where the model has the knob; ignore it otherwise. */
+    effort?: string;
+    /** Answer with a single JSON document. */
+    json?: boolean;
+    /** Search the web yourself; asked only of a model whose capabilities say `nativeWebSearch`. */
+    webSearch?: boolean;
+    /** Media the reply should carry; asked only of a model whose capabilities list it in `mediaOutput`. */
+    mediaOutput?: ModelOutput[];
+}
+/** What a turn streams, in order, ending with `stop`. A `native` block comes back in later requests as the provider's own record (server-side tool calls, signatures). */
+export type ModelChatEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "media";
+    media: {
+        mime: string;
+        base64: string;
+        name: string;
+    };
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: unknown;
+} | {
+    type: "native";
+    provider: string;
+    data: unknown;
+}
+/** `inputTokens` counts every prompt token read, cached ones included. */
+ | {
+    type: "usage";
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/** The request failed before anything streamed and is sent again after `delayMs`. */
+ | {
+    type: "retry";
+    attempt: number;
+    max: number;
+    reason: string;
+    delayMs: number;
+} | {
+    type: "stop";
+    reason: "end" | "tool_use" | "max_tokens" | "refusal";
+};
+export interface ModelChatCapabilities {
+    /** MIME types it reads (`image/png`, `application/pdf`…). */
+    mediaInput?: string[];
+    mediaOutput?: string[];
+    tools: boolean;
+    streaming: boolean;
+    json: boolean;
+    /** It searches the web on its own when a request sets `webSearch`. */
+    nativeWebSearch?: boolean;
+}
+/** One model as Tomrade's conversations, worker and tools talk to it. Throw with what the provider said when a request fails. */
+export interface ModelChat {
+    capabilities: ModelChatCapabilities;
+    chat(request: ModelChatRequest, signal?: AbortSignal): AsyncIterable<ModelChatEvent>;
+}
+/** A saved model profile naming the provider. */
+export interface ModelProfileInfo {
+    id: string;
+    title: string;
+    provider: string;
+    /** Absent: the provider's default address. */
+    baseURL?: string;
+    apiKey: string;
+    model: string;
+    inputModalities?: ModelInput[];
+    outputModalities?: ModelOutput[];
+}
+/** A well-known service the provider serves, offered in the model setup. */
+export interface ModelPresetSpec {
+    /** Namespaced like every id a plugin registers. */
+    id: string;
+    title: string;
+    /** Absent: the provider's own address. */
+    baseURL?: string;
+    /** The model to start with; otherwise the newest listed one matching `prefer`, then the first listed. */
+    model?: string;
+    prefer?: RegExp[];
+    /** Where people get a key. */
+    keyPage?: string;
+    /** The variable people export the key as, which Tomrade looks for on this computer. */
+    env?: string;
+    /** What its keys look like, so a pasted key picks this preset. */
+    keyShapes?: RegExp[];
+    /** Runs on this computer and needs no key. */
+    local?: boolean;
+    /** One line under the preset in the setup. */
+    hint?: Localized;
+}
+export interface ModelMedia {
+    inputModalities: ModelInput[];
+    outputModalities: ModelOutput[];
+}
+/** The models an endpoint lists (null: it has no listing), or why the key or address does not work. */
+export type ModelListing = {
+    ok: true;
+    models: string[] | null;
+    capabilities?: Record<string, ModelMedia>;
+} | {
+    ok: false;
+    status?: number;
+    detail: string;
+};
+/**
+ * A sign-in the provider allows third-party apps instead of pasting a key: an
+ * OAuth flow that ends in a key (OpenRouter's PKCE), or credentials already on
+ * this computer. Never a consumer subscription its terms keep to the vendor's own apps.
+ */
+export interface ModelSignIn {
+    /** The button, such as "Sign in with OpenRouter". */
+    title: Localized;
+    /** Runs the sign-in; `open` shows a page in the person's browser. What it answers is kept as the profile's key. */
+    run(helpers: {
+        open(url: string): void;
+        signal: AbortSignal;
+    }): Promise<{
+        apiKey: string;
+    }>;
+}
+/** SDK 0.2.16. One way to talk to models, as the app's own providers are: what a profile's `provider` names. */
+export interface ModelProviderSpec {
+    /** Namespaced like every id a plugin registers; profiles store it. */
+    id: string;
+    title: Localized;
+    /** False for an endpoint that works without a key, such as a local one. Default true. */
+    keyRequired?: boolean;
+    /** Where a profile without its own address talks; `editable: false` leaves the address out of the form. */
+    baseURL: {
+        default: string;
+        editable?: boolean;
+    };
+    /** False for an endpoint that only makes images. Default true. */
+    chat?: boolean;
+    presets?: ModelPresetSpec[];
+    /** Doubles as the key check when a profile is saved. */
+    list(endpoint: {
+        baseURL?: string;
+        apiKey: string;
+    }, signal: AbortSignal): Maybe<ModelListing>;
+    /** Of what the endpoint lists, the models a profile can use, best first. Default: all of them, as listed. */
+    usable?(listed: string[]): string[];
+    /** What its models read besides text when a profile stores nothing. */
+    defaultInput?: ModelInput[];
+    /** A model's media: what its listing entry says, else what the provider knows; undefined keeps a profile's stored values. */
+    capabilities?(model: string, listed?: ModelMedia): ModelMedia | undefined;
+    signIn?: ModelSignIn;
+    /** Called synchronously when a profile on it is first used, and again once the profile changes. */
+    build(profile: ModelProfileInfo): ModelChat;
+}
+/** A model on the app's own OpenAI-compatible adapter. */
+export interface CompatibleModelOptions {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    inputModalities?: ModelInput[];
+    outputModalities?: ModelOutput[];
+    /**
+     * The model searches the web on its own when a request asks: `"chat"` on chat/completions, with
+     * the vendor's own flag set by `body`; `"responses"` on the Responses API. Absent, it does not.
+     */
+    webSearch?: "chat" | "responses";
+    /** The last word on each chat/completions body (a copy of the request beside it): a vendor's own fields. Throw to fail the request. */
+    body?(json: Record<string, unknown>, request: ModelChatRequest): Record<string, unknown>;
+    /** The last word on each Responses body, where a searching request goes with `webSearch: "responses"`: the vendor's effort scale, its limits. Throw to fail the request. */
+    responses?(json: Record<string, unknown>, request: ModelChatRequest): Record<string, unknown>;
+    /**
+     * The headers of each request in place of `Authorization: Bearer <apiKey>`: a vendor's own key
+     * header, a token that expires, a signature over `url` and the exact `body` sent. Asked again
+     * before every try, retries included. Throw to fail the request.
+     */
+    headers?(request: {
+        url: string;
+        body: string;
+    }): Maybe<Record<string, string>>;
+}
+export interface ModelsApi {
+    /** Serves the profiles naming `provider.id` and offers its presets until disposed or the plugin unloads. */
+    registerProvider(provider: ModelProviderSpec): Promise<Disposer>;
+    /**
+     * Synchronous, like `build`: a model on the app's own OpenAI-compatible adapter — streaming, tool
+     * calls, retries, media, the token-field quirks — for a vendor that serves chat/completions.
+     */
+    compatible(options: CompatibleModelOptions): ModelChat;
+    /**
+     * The app's own listing of a chat/completions endpoint (`GET /models`), media read from it; one
+     * without a listing answers `models: null`. `headers` go in place of the bearer key.
+     */
+    listCompatible(endpoint: {
+        baseURL: string;
+        apiKey: string;
+        headers?: Record<string, string>;
+    }, signal?: AbortSignal): Promise<ModelListing>;
+}
+export {};
+//# sourceMappingURL=models.d.ts.map

package/dist/models.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=models.js.map

package/dist/semver.d.ts

@@ -0,0 +1,9 @@
+type Version = [number, number, number];
+export declare function parseVersion(text: string): Version | null;
+export declare const isVersion: (text: string) => boolean;
+export declare function compareVersions(a: string, b: string): number;
+/** The subset of npm ranges plugins need: `^`, `~`, comparisons, `*`, spaces for AND and `||` for OR. */
+export declare function satisfies(version: string, range: string): boolean;
+export declare const isRange: (range: string) => boolean;
+export {};
+//# sourceMappingURL=semver.d.ts.map

package/dist/semver.js

@@ -0,0 +1,67 @@
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseVersion(text) {
+    const m = VERSION.exec(text.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+export const isVersion = (text) => parseVersion(text) !== null;
+export function compareVersions(a, b) {
+    const x = parseVersion(a);
+    const y = parseVersion(b);
+    if (!x || !y)
+        throw new Error(`not a version: ${!x ? a : b}`);
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    return 0;
+}
+function comparator(version, token) {
+    const cmp = (v) => {
+        for (let i = 0; i < 3; i++)
+            if (version[i] !== v[i])
+                return version[i] - v[i];
+        return 0;
+    };
+    if (token === "*" || token === "x")
+        return true;
+    const op = /^(\^|~|>=|<=|>|<|=)?(.+)$/.exec(token);
+    if (!op)
+        return false;
+    const base = parseVersion(op[2]);
+    if (!base)
+        return false;
+    switch (op[1]) {
+        case "^": {
+            if (cmp(base) < 0)
+                return false;
+            if (base[0] > 0)
+                return version[0] === base[0];
+            if (base[1] > 0)
+                return version[0] === 0 && version[1] === base[1];
+            return version[0] === 0 && version[1] === 0 && version[2] === base[2];
+        }
+        case "~":
+            return cmp(base) >= 0 && version[0] === base[0] && version[1] === base[1];
+        case ">=":
+            return cmp(base) >= 0;
+        case "<=":
+            return cmp(base) <= 0;
+        case ">":
+            return cmp(base) > 0;
+        case "<":
+            return cmp(base) < 0;
+        default:
+            return cmp(base) === 0;
+    }
+}
+/** The subset of npm ranges plugins need: `^`, `~`, comparisons, `*`, spaces for AND and `||` for OR. */
+export function satisfies(version, range) {
+    const v = parseVersion(version);
+    if (!v)
+        return false;
+    return range.split("||").some((part) => {
+        const tokens = part.trim().split(/\s+/).filter(Boolean);
+        return tokens.length > 0 && tokens.every((token) => comparator(v, token));
+    });
+}
+export const isRange = (range) => range.split("||").every((part) => part.trim().split(/\s+/).filter(Boolean).every((t) => t === "*" || t === "x" || /^(\^|~|>=|<=|>|<|=)?\d+\.\d+\.\d+/.test(t)));
+//# sourceMappingURL=semver.js.map

package/dist/terminals.d.ts

@@ -0,0 +1,72 @@
+import type { Disposer } from "./contract.js";
+/** SDK 0.2.10. Whether herdr can hand over a live terminal, and the command that fixes it when it cannot. */
+export type TerminalBridgeState = {
+    state: "ready";
+    version: string;
+} | {
+    state: "unsupported";
+} | {
+    state: "notInstalled";
+} | {
+    state: "notRunning";
+    version: string;
+} | {
+    state: "tooOld";
+    version: string;
+    need: string;
+    fix: string;
+} | {
+    state: "stale";
+    version: string;
+    server: string;
+    fix: string;
+};
+/** One picture of the terminal: ANSI bytes that paint it — the whole viewport when `full`, else only the cells that changed. */
+export interface TerminalFrame {
+    seq: number;
+    width: number;
+    height: number;
+    full: boolean;
+    bytes: Uint8Array;
+}
+/** A live terminal of a herdr pane. The frames repaint the viewport only: scrolling back is asked for with `scroll`. */
+export interface TerminalHandle {
+    readonly paneId: string;
+    readonly mode: "control" | "observe";
+    onFrame(listener: (frame: TerminalFrame) => void): Disposer;
+    /** Once, when the stream ends: herdr's reason, or what it said when it would not attach. */
+    onClose(listener: (reason: string | null) => void): Disposer;
+    /** Keys and pastes; a controller's only — an observer's input is dropped. */
+    input(data: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    scroll(scroll: {
+        direction: "up" | "down";
+        lines: number;
+        column?: number;
+        row?: number;
+        modifiers?: number;
+    }): void;
+    mouse(mouse: {
+        action: "down" | "up" | "drag" | "move";
+        button?: "left" | "middle" | "right" | "none";
+        column: number;
+        row: number;
+        modifiers?: number;
+    }): void;
+    /** Detach: the pane keeps running in herdr. Also done for every terminal the plugin left open when it unloads. */
+    close(): void;
+}
+/**
+ * SDK 0.2.10. Terminals of the herdr panes code sessions run in, through the
+ * app: a plugin neither reaches herdr's socket nor starts its CLI itself.
+ */
+export interface TerminalsApi {
+    state(): Promise<TerminalBridgeState>;
+    /** `control` (the default) takes input and size from any other owner; `observe` watches beside others. Rejects when `state()` is not ready. */
+    open(paneId: string, opts: {
+        mode?: "control" | "observe";
+        cols: number;
+        rows: number;
+    }): Promise<TerminalHandle>;
+}
+//# sourceMappingURL=terminals.d.ts.map

package/dist/terminals.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=terminals.js.map

package/dist/web-search.d.ts

@@ -0,0 +1,54 @@
+import type { Disposer } from "./contract.js";
+type Maybe<T> = T | Promise<T>;
+/** SDK 0.2.9. What the agent's `web_search` asks for; defaults are filled in before a provider sees it. */
+export interface WebSearchRequest {
+    query: string;
+    maxResults: number;
+    topic: "general" | "news";
+    timeRange?: "day" | "week" | "month" | "year";
+    includeDomains?: string[];
+    excludeDomains?: string[];
+}
+export interface WebSearchHit {
+    title: string;
+    url: string;
+    /** An excerpt, not the page. */
+    content: string;
+    published?: string;
+}
+export interface WebReadRequest {
+    urls: string[];
+    /** Keep only the passages relevant to this. */
+    query?: string;
+}
+export interface WebReadResponse {
+    pages: {
+        url: string;
+        content: string;
+    }[];
+    failed: {
+        url: string;
+        error: string;
+    }[];
+}
+/** One search backend, as the app's own providers are: the first registered one that is available answers. */
+export interface WebSearchProviderSpec {
+    /** Namespaced like every id a plugin registers. */
+    id: string;
+    title: string;
+    /** Why it cannot answer yet (no API key, say), or null when it can. Called often and synchronously: keep it cheap. The agent reads it as the tool's error. */
+    unavailable(): string | null;
+    search(request: WebSearchRequest, signal: AbortSignal): Maybe<{
+        results: WebSearchHit[];
+    }>;
+    /** Pages as Markdown. Without it, `web_fetch` is left to another provider. */
+    read?(request: WebReadRequest, signal: AbortSignal): Maybe<WebReadResponse>;
+    /** The settings pane where the person sets it up: the plugin's own section id, or an app pane such as "assistant" (models). */
+    settings?: string;
+}
+export interface WebSearchApi {
+    /** Answers the agent's `web_search` (and `web_fetch`, with `read`) until disposed or the plugin unloads. */
+    register(provider: WebSearchProviderSpec): Promise<Disposer>;
+}
+export {};
+//# sourceMappingURL=web-search.d.ts.map

package/dist/web-search.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=web-search.js.map

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@tomradex/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.16",
+  "type": "module",
+  "author": "Haoyuan Tang",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "description": "The Tomrade plugin contract: definePlugin, the async PluginContext every extension receives, and the manifest schema",
+  "keywords": [
+    "tomrade",
+    "tomrade-plugin",
+    "plugin",
+    "sdk"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@tomradex/domain": "0.2.16",
+    "zod": "^4.4.3"
+  }
+}