@tomradex/plugin-sdk 0.2.0 → 0.2.16

package/dist/language.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { type Dictionaries } from "@tomradex/domain";
+import type { Locale } from "./contract.js";
+export { languageCoverage, pickLanguage, slotsOf, type Dictionaries, type LanguageCoverage } from "@tomradex/domain";
+/**
+ * A plugin's own words in the app's language (`ctx.settings.locale()`): the
+ * closest language it has, picked as Tomrade picks its own (zh-TW finds
+ * zh-Hant, never zh), and English when it has none of that language.
+ */
+export declare function wordsFor<T>(locale: Locale, words: {
+    en: T;
+} & Partial<Record<Locale, T>>): T;
+/**
+ * A language pack: data only. The manifest names each language a plugin adds
+ * and the JSON file holding its words; nothing in it runs, and every string
+ * is shown as plain text in place of the English it translates.
+ */
+/** The largest pack file Tomrade reads, and the longest single template. */
+export declare const LANGUAGE_PACK_LIMITS: {
+    fileBytes: number;
+    templateChars: number;
+    languages: number;
+};
+export declare const LanguageEntrySchema: z.ZodObject<{
+    tag: z.ZodString;
+    name: z.ZodString;
+    file: z.ZodString;
+}, z.core.$strip>;
+export type LanguageEntry = z.output<typeof LanguageEntrySchema>;
+/**
+ * What a pack file holds: `ui` translates the interface's dictionaries,
+ * `backend` the backend's books, each `namespace → key → template`, keyed as
+ * English is. A template names its values as `{{slot}}`, exactly the slots
+ * English's does; an entry that does not, or a key English lacks, reads English.
+ */
+export declare const LanguagePackFileSchema: z.ZodObject<{
+    ui: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
+    backend: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strict>;
+export interface LanguagePack {
+    tag: string;
+    name: string;
+    ui: Dictionaries;
+    backend: Dictionaries;
+}
+/** A pack file's text checked against the format; throws with the first problem. */
+export declare function parseLanguagePack(entry: LanguageEntry, text: string): LanguagePack;
+//# sourceMappingURL=language.d.ts.map

package/dist/language.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { canonicalTag, pickLanguage } from "@tomradex/domain";
+export { languageCoverage, pickLanguage, slotsOf } from "@tomradex/domain";
+/**
+ * A plugin's own words in the app's language (`ctx.settings.locale()`): the
+ * closest language it has, picked as Tomrade picks its own (zh-TW finds
+ * zh-Hant, never zh), and English when it has none of that language.
+ */
+export function wordsFor(locale, words) {
+    return words[pickLanguage(locale, Object.keys(words)) ?? "en"] ?? words.en;
+}
+/**
+ * A language pack: data only. The manifest names each language a plugin adds
+ * and the JSON file holding its words; nothing in it runs, and every string
+ * is shown as plain text in place of the English it translates.
+ */
+/** The largest pack file Tomrade reads, and the longest single template. */
+export const LANGUAGE_PACK_LIMITS = { fileBytes: 2 * 1024 * 1024, templateChars: 4_000, languages: 16 };
+export const LanguageEntrySchema = z.object({
+    /** A BCP 47 tag: "pt-BR", "ko", "zh-Hant". */
+    tag: z
+        .string()
+        .refine((t) => canonicalTag(t) === t, "a canonical BCP 47 language tag such as \"pt-BR\" or \"ko\"")
+        .refine((t) => t !== "en", "English is what every pack translates; it cannot be replaced"),
+    /** The language's name in itself, as Settings → Language lists it: "Português (Brasil)". */
+    name: z.string().trim().min(1).max(60),
+    /** The pack's words, a JSON file inside the plugin: "languages/pt-BR.json". */
+    file: z
+        .string()
+        .regex(/^[A-Za-z0-9_-][A-Za-z0-9._/-]*\.json$/, "a relative path to a .json file inside the plugin")
+        .refine((f) => !f.split("/").includes(".."), "the file must stay inside the plugin")
+});
+const Words = z.record(z.string().min(1), z.record(z.string().min(1), z.string().max(LANGUAGE_PACK_LIMITS.templateChars)));
+/**
+ * What a pack file holds: `ui` translates the interface's dictionaries,
+ * `backend` the backend's books, each `namespace → key → template`, keyed as
+ * English is. A template names its values as `{{slot}}`, exactly the slots
+ * English's does; an entry that does not, or a key English lacks, reads English.
+ */
+export const LanguagePackFileSchema = z
+    .object({
+    ui: Words.default({}),
+    backend: Words.default({})
+})
+    .strict();
+/** A pack file's text checked against the format; throws with the first problem. */
+export function parseLanguagePack(entry, text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${entry.file} is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const parsed = LanguagePackFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(`${entry.file} ${issue.path.join(".") || "(root)"}: ${issue.message}`);
+    }
+    return { tag: entry.tag, name: entry.name, ui: parsed.data.ui, backend: parsed.data.backend };
+}
+//# sourceMappingURL=language.js.map

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 /** The contract this SDK describes. A plugin's `engines.sdk` range is checked against the host's. */
-export declare const SDK_CONTRACT = "0.2.0";
+export declare const SDK_CONTRACT = "0.2.16";
 export declare const PLUGIN_ID: RegExp;
 export declare const NAMESPACE: RegExp;
 /** The app's own names, and the official publisher's. */
@@ -9,12 +9,20 @@ export declare const OFFICIAL_PUBLISHER = "tomrade";
 export declare const PermissionsSchema: z.ZodDefault<z.ZodObject<{
     network: z.ZodDefault<z.ZodArray<z.ZodString>>;
     fs: z.ZodDefault<z.ZodEnum<{
+        none: "none";
         project: "project";
-        plugin: "plugin";
         any: "any";
-        none: "none";
+        plugin: "plugin";
     }>>;
     exec: z.ZodDefault<z.ZodBoolean>;
+    window: z.ZodDefault<z.ZodBoolean>;
+    why: z.ZodOptional<z.ZodObject<{
+        network: z.ZodOptional<z.ZodString>;
+        fs: z.ZodOptional<z.ZodString>;
+        exec: z.ZodOptional<z.ZodString>;
+        window: z.ZodOptional<z.ZodString>;
+        full: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>>;
 export declare const ContributesSchema: z.ZodObject<{
     tools: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
@@ -23,11 +31,30 @@ export declare const ContributesSchema: z.ZodObject<{
     statusItems: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     sections: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     graphs: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    sidebarModules: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     playbooks: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     settings: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     surfaces: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     tables: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    imAdapters: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    webSearchProviders: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    agentHooks: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    modelProviders: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+/**
+ * One row a full-mode plugin lays over Tomrade's composition, merged by id like a
+ * `tomrade.patch.yml` row: an app row's id switches it off, replaces its plugin or
+ * changes its config; a new id (carrying the namespace) adds a row. A relative
+ * `name` is a file inside the package.
+ */
+export declare const RowSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodUnknown>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+export type ManifestRow = z.output<typeof RowSchema>;
 export declare const ManifestSchema: z.ZodObject<{
     id: z.ZodString;
     namespace: z.ZodOptional<z.ZodString>;
@@ -43,18 +70,43 @@ export declare const ManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
     engines: z.ZodObject<{
         sdk: z.ZodString;
+        tomrade: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    main: z.ZodDefault<z.ZodString>;
+    context: z.ZodDefault<z.ZodEnum<{
+        full: "full";
+        sdk: "sdk";
+    }>>;
+    rows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodUnknown>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    main: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     icon: z.ZodOptional<z.ZodString>;
+    languages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        tag: z.ZodString;
+        name: z.ZodString;
+        file: z.ZodString;
+    }, z.core.$strip>>>;
     permissions: z.ZodDefault<z.ZodObject<{
         network: z.ZodDefault<z.ZodArray<z.ZodString>>;
         fs: z.ZodDefault<z.ZodEnum<{
+            none: "none";
             project: "project";
-            plugin: "plugin";
             any: "any";
-            none: "none";
+            plugin: "plugin";
         }>>;
         exec: z.ZodDefault<z.ZodBoolean>;
+        window: z.ZodDefault<z.ZodBoolean>;
+        why: z.ZodOptional<z.ZodObject<{
+            network: z.ZodOptional<z.ZodString>;
+            fs: z.ZodOptional<z.ZodString>;
+            exec: z.ZodOptional<z.ZodString>;
+            window: z.ZodOptional<z.ZodString>;
+            full: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     inject: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         items: "items";
@@ -68,7 +120,12 @@ export declare const ManifestSchema: z.ZodObject<{
         contributions: "contributions";
         agent: "agent";
         surfaces: "surfaces";
+        alerts: "alerts";
         oplog: "oplog";
+        im: "im";
+        webSearch: "webSearch";
+        terminals: "terminals";
+        models: "models";
     }>>>;
     optional: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         items: "items";
@@ -82,7 +139,12 @@ export declare const ManifestSchema: z.ZodObject<{
         contributions: "contributions";
         agent: "agent";
         surfaces: "surfaces";
+        alerts: "alerts";
         oplog: "oplog";
+        im: "im";
+        webSearch: "webSearch";
+        terminals: "terminals";
+        models: "models";
     }>>>;
     contributes: z.ZodDefault<z.ZodObject<{
         tools: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
@@ -91,10 +153,15 @@ export declare const ManifestSchema: z.ZodObject<{
         statusItems: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         sections: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         graphs: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        sidebarModules: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         playbooks: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         settings: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         surfaces: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         tables: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        imAdapters: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        webSearchProviders: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        agentHooks: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        modelProviders: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
     authoredBy: z.ZodDefault<z.ZodEnum<{
         agent: "agent";
@@ -120,14 +187,15 @@ export declare function assertOwned(namespace: string, id: string, kind: string)
 export type RiskLevel = "low" | "elevated" | "high";
 export interface Risk {
     level: RiskLevel;
-    /** Stable keys the UI words: `exec`, `fs-any`, `network-any`, `network`, `fs-project`, `db`. */
+    /** Stable keys the UI words: `full`, `rows`, `exec`, `fs-any`, `network-any`, `network`, `fs-project`, `db`, `models`, `window`. */
     reasons: string[];
 }
 /**
- * High risk is labelled, not refused: running programs, reading anywhere on
- * disk, or talking to any host. Elevated is what a person should still see.
+ * High risk is labelled, not refused: running with Tomrade's whole context or
+ * changing its own rows, running programs, reading anywhere on disk, or talking
+ * to any host. Elevated is what a person should still see.
  */
-export declare function riskOf(manifest: Pick<Manifest, "permissions" | "inject" | "optional">): Risk;
+export declare function riskOf(manifest: Pick<Manifest, "permissions" | "inject" | "optional"> & Partial<Pick<Manifest, "context" | "rows">>): Risk;
 /** OSI-approved licenses the store accepts without a second look. */
 export declare const OSI_LICENSES: Set<string>;
 export declare const isOpenSource: (license: string) => boolean;

package/dist/manifest.js

@@ -1,16 +1,17 @@
 import { z } from "zod";
+import { LANGUAGE_PACK_LIMITS, LanguageEntrySchema } from "./language.js";
 import { isRange, isVersion } from "./semver.js";
 /** The contract this SDK describes. A plugin's `engines.sdk` range is checked against the host's. */
-export const SDK_CONTRACT = "0.2.0";
+export const SDK_CONTRACT = "0.2.16";
 export const PLUGIN_ID = /^[a-z0-9][a-z0-9-]{0,38}\/[a-z0-9][a-z0-9-]{0,63}$/;
 export const NAMESPACE = /^[a-z][a-z0-9_]{1,31}$/;
 /** The app's own names, and the official publisher's. */
 export const RESERVED_NAMESPACES = new Set([
-    "agent", "archify", "boards", "code_link", "contributions", "core", "db", "deps", "deps_graph", "fields", "files", "hub", "ipc", "items",
-    "llm", "mcp", "oplog", "pet", "plugin", "plugins", "projects", "repos", "settings", "storage", "surfaces", "system", "tomrade", "tools", "views", "write"
+    "agent", "alerts", "archify", "boards", "code_link", "contributions", "core", "db", "deps", "deps_graph", "fields", "files", "hub", "im", "ipc", "items",
+    "llm", "mcp", "oplog", "pet", "plugin", "plugins", "pomodoro", "projects", "repos", "settings", "storage", "surfaces", "system", "tomrade", "tools", "views", "write"
 ]);
 export const OFFICIAL_PUBLISHER = "tomrade";
-const SERVICE = z.enum(["items", "fields", "boards", "views", "projects", "db", "settings", "tools", "contributions", "agent", "surfaces", "oplog"]);
+const SERVICE = z.enum(["items", "fields", "boards", "views", "projects", "db", "settings", "tools", "contributions", "agent", "surfaces", "alerts", "oplog", "im", "webSearch", "terminals", "models"]);
 export const PermissionsSchema = z
     .object({
     /** Hosts the plugin talks to; `*` means any. */
@@ -18,9 +19,13 @@ export const PermissionsSchema = z
     /** `plugin`: its own data directory. `project`: the project folders. `any`: anywhere on disk. */
     fs: z.enum(["none", "plugin", "project", "any"]).default("none"),
     /** Starts other programs. */
-    exec: z.boolean().default(false)
+    exec: z.boolean().default(false),
+    /** SDK 0.2.11: opens working windows of its own (a surface of kind "window"), which take keys like any app window. */
+    window: z.boolean().default(false),
+    /** Why the plugin needs a wide permission, in a sentence a person installing it can judge. Official plugins must say. */
+    why: z.object({ network: z.string().min(1), fs: z.string().min(1), exec: z.string().min(1), window: z.string().min(1), full: z.string().min(1) }).partial().optional()
 })
-    .default({ network: [], fs: "none", exec: false });
+    .default({ network: [], fs: "none", exec: false, window: false });
 export const ContributesSchema = z
     .object({
     tools: z.array(z.string()).default([]),
@@ -29,12 +34,34 @@ export const ContributesSchema = z
     statusItems: z.array(z.string()).default([]),
     sections: z.array(z.string()).default([]),
     graphs: z.array(z.string()).default([]),
+    sidebarModules: z.array(z.string()).default([]),
     playbooks: z.array(z.string()).default([]),
     settings: z.array(z.string()).default([]),
     surfaces: z.array(z.string()).default([]),
-    tables: z.array(z.string()).default([])
+    tables: z.array(z.string()).default([]),
+    imAdapters: z.array(z.string()).default([]),
+    webSearchProviders: z.array(z.string()).default([]),
+    /** SDK 0.2.15: the CLI agent hook events it hears. */
+    agentHooks: z.array(z.string()).default([]),
+    /** SDK 0.2.16: the model providers it registers. */
+    modelProviders: z.array(z.string()).default([])
 })
     .partial();
+/**
+ * One row a full-mode plugin lays over Tomrade's composition, merged by id like a
+ * `tomrade.patch.yml` row: an app row's id switches it off, replaces its plugin or
+ * changes its config; a new id (carrying the namespace) adds a row. A relative
+ * `name` is a file inside the package.
+ */
+export const RowSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    config: z.unknown().optional(),
+    disabled: z.boolean().optional()
+})
+    .refine((row) => row.name !== undefined || row.config !== undefined || row.disabled !== undefined, "a row changes something: name, config or disabled");
 export const ManifestSchema = z.object({
     id: z.string().regex(PLUGIN_ID, "publisher/name, lowercase letters, digits and dashes"),
     namespace: z.string().regex(NAMESPACE, "lowercase letters, digits and underscores, 2–32 long, starting with a letter").optional(),
@@ -46,9 +73,23 @@ export const ManifestSchema = z.object({
     repository: z.url().optional(),
     homepage: z.url().optional(),
     author: z.object({ name: z.string().min(1), url: z.url().optional() }).optional(),
-    engines: z.object({ sdk: z.string().refine(isRange, "a version range such as ^0.2.0") }),
-    main: z.string().default("dist/index.js"),
+    engines: z.object({
+        sdk: z.string().refine(isRange, "a version range such as ^0.2.0"),
+        /** SDK 0.2.13: the Tomrade versions a full-mode plugin works with; it reaches internals the SDK range does not cover. */
+        tomrade: z.string().refine(isRange, "a version range such as >=0.13.0 <0.14.0").optional()
+    }),
+    /**
+     * SDK 0.2.13: what `main` receives. `"sdk"` is a `definePlugin` plugin behind the async facade;
+     * `"full"` is a plain cordis plugin given Tomrade's whole Context, as the app's own modules are.
+     */
+    context: z.enum(["sdk", "full"]).default("sdk"),
+    /** SDK 0.2.13, full mode only: rows laid over Tomrade's own, as `tomrade.patch.yml` rows are. */
+    rows: z.array(RowSchema).default([]),
+    /** The built code; `null` for a plugin that is data only, such as a language pack. */
+    main: z.string().nullable().default("dist/index.js"),
     icon: z.string().optional(),
+    /** Languages the plugin adds, each a JSON file of words (SDK 0.2.8). */
+    languages: z.array(LanguageEntrySchema).max(LANGUAGE_PACK_LIMITS.languages).default([]),
     permissions: PermissionsSchema,
     /** Stamped by `tomrade-plugin build` from the exported plugin. */
     inject: z.array(SERVICE).default([]),
@@ -66,6 +107,26 @@ export function parseManifest(raw) {
         throw new Error(`${manifest.id}: the name part does not make a valid namespace ("${ns}"); set "namespace" in ${MANIFEST_FILE}`);
     if (RESERVED_NAMESPACES.has(ns) && publisherOf(manifest.id) !== OFFICIAL_PUBLISHER)
         throw new Error(`${manifest.id}: namespace "${ns}" is reserved`);
+    if (manifest.main === null && !manifest.languages.length)
+        throw new Error(`${manifest.id}: "main" is null, so the plugin has no code; it must add a language under "languages"`);
+    if (manifest.context === "full") {
+        if (manifest.main === null)
+            throw new Error(`${manifest.id}: a full-mode plugin needs "main", the cordis plugin it runs`);
+        if (!manifest.engines.tomrade)
+            throw new Error(`${manifest.id}: a full-mode plugin names the Tomrade versions it works with in "engines.tomrade"`);
+        if (manifest.languages.length)
+            throw new Error(`${manifest.id}: a full-mode plugin adds its languages from its own code (ctx.settings.addLanguage), not under "languages"`);
+    }
+    else if (manifest.rows.length)
+        throw new Error(`${manifest.id}: "rows" change Tomrade's own composition, which takes "context": "full"`);
+    const ids = manifest.rows.map((r) => r.id);
+    const repeated = ids.find((id, i) => ids.indexOf(id) !== i);
+    if (repeated)
+        throw new Error(`${manifest.id}: the row "${repeated}" is listed twice`);
+    const tags = manifest.languages.map((l) => l.tag);
+    const twice = tags.find((t, i) => tags.indexOf(t) !== i);
+    if (twice)
+        throw new Error(`${manifest.id}: the language "${twice}" is listed twice`);
     return manifest;
 }
 export const publisherOf = (id) => id.split("/")[0];
@@ -78,16 +139,22 @@ export function assertOwned(namespace, id, kind) {
         throw new Error(`${kind} "${id}" must be named "${namespace}" or start with "${namespace}." "${namespace}-" or "${namespace}_"`);
 }
 /**
- * High risk is labelled, not refused: running programs, reading anywhere on
- * disk, or talking to any host. Elevated is what a person should still see.
+ * High risk is labelled, not refused: running with Tomrade's whole context or
+ * changing its own rows, running programs, reading anywhere on disk, or talking
+ * to any host. Elevated is what a person should still see.
  */
 export function riskOf(manifest) {
     const p = manifest.permissions;
-    const high = [p.exec && "exec", p.fs === "any" && "fs-any", p.network.includes("*") && "network-any"].filter(Boolean);
+    const full = manifest.context === "full";
+    const high = [full && "full", full && manifest.rows?.length && "rows", p.exec && "exec", p.fs === "any" && "fs-any", p.network.includes("*") && "network-any"].filter(Boolean);
     const elevated = [
         p.network.length && !p.network.includes("*") && "network",
         p.fs === "project" && "fs-project",
-        [...manifest.inject, ...manifest.optional].includes("db") && "db"
+        [...manifest.inject, ...manifest.optional].includes("db") && "db",
+        // A model provider reads the conversations of the profiles on it, and their keys.
+        [...manifest.inject, ...manifest.optional].includes("models") && "models",
+        // A window that takes keys could pass itself off as another app's: worth a look before installing.
+        p.window && "window"
     ].filter(Boolean);
     return { level: high.length ? "high" : elevated.length ? "elevated" : "low", reasons: [...high, ...elevated] };
 }

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