@tomradex/plugin-sdk 0.2.16 → 0.2.19

package/dist/contract.d.ts

@@ -3,6 +3,7 @@ import type { ImApi } from "./im.js";
 import type { TerminalsApi } from "./terminals.js";
 import type { WebSearchApi } from "./web-search.js";
 import type { ModelsApi } from "./models.js";
+import type { LocalAgentOptions, LocalAgentSpec } from "./local-agents.js";
 import type { Author, Board, CreateItemInput, FieldDef, FieldOption, FieldType, FilterClause, Item, ListItemsFilter, OplogEntity, OplogEntry, OplogOp, Patch, Project, SortKey, View } from "@tomradex/domain";
 /**
  * The plugin contract. Everything a plugin reaches returns a Promise, and every
@@ -448,6 +449,12 @@ export interface AgentApi {
      * hears their sessions and, in one Tomrade started, may answer: see `CLI_HOOK_COVERAGE` for which.
      */
     cliHook(spec: CliHookSpec): Promise<Disposer>;
+    /**
+     * SDK 0.2.17: a coding agent installed on this machine, run by Tomrade's own
+     * conductor — its CLI found, its sessions driven over ACP or handed a ticket
+     * in a terminal, its connection to Tomrade kept, its sign-in lent to the worker.
+     */
+    localAgent<O extends LocalAgentOptions>(spec: LocalAgentSpec<O>): Promise<Disposer>;
 }
 export type { CliHookEvent } from "./cli-hooks.js";
 /** SDK 0.2.15: what a CLI agent's hook says happened, whichever agent sent it. */

package/dist/exports.js

@@ -55,7 +55,9 @@ export const SDK_EXPORTS = {
     wordsFor: "0.2.9",
     RowSchema: "0.2.13",
     CLI_HOOK_COVERAGE: "0.2.15",
-    CLI_HOOK_EVENTS: "0.2.15"
+    CLI_HOOK_EVENTS: "0.2.15",
+    NotSignedIn: "0.2.17",
+    PERMISSION_CHOICES: "0.2.17"
 };
 /** The oldest contract `range` accepts, up to this SDK's own; null when it accepts none of them. */
 export function lowestContract(range) {

package/dist/im.d.ts

@@ -185,6 +185,28 @@ export interface ImAdapterSession {
         id: string;
         name?: string;
     };
+    /**
+     * SDK 0.2.19. Topics the bot opens itself, when `topics`: one per ticket
+     * being worked in a group conversation. Messages people write in one arrive
+     * with its `topicId`.
+     */
+    topics?: {
+        open(command: {
+            operationId: string;
+            address: ImAddress;
+            title: string;
+        }): Promise<{
+            topicId: string;
+        }>;
+        /** Renames it, and closes it out of the way or opens it again. */
+        update(command: {
+            address: ImAddress & {
+                topicId: string;
+            };
+            title: string;
+            closed: boolean;
+        }): Promise<void>;
+    };
     close(): void | Promise<void>;
 }
 /** SDK 0.2.5. One value a person copies from the platform's developer console. */
@@ -221,6 +243,8 @@ export interface ImCapabilities {
     maxFileBytes: number;
     /** SDK 0.2.5. Replies can go into a thread under the triggering message. */
     threads?: boolean;
+    /** SDK 0.2.19. The bot opens a topic per ticket in a group, through `session.topics`. */
+    topics?: boolean;
     reactions?: boolean;
     typing?: boolean;
     /** `native`: session.stream. `edit`: throttled edits of one message. `none`: only the final message. */
@@ -254,6 +278,7 @@ export declare const ImCapabilitiesSchema: z.ZodObject<{
     maxTextLength: z.ZodNumber;
     maxFileBytes: z.ZodNumber;
     threads: z.ZodOptional<z.ZodBoolean>;
+    topics: z.ZodOptional<z.ZodBoolean>;
     reactions: z.ZodOptional<z.ZodBoolean>;
     typing: z.ZodOptional<z.ZodBoolean>;
     stream: z.ZodOptional<z.ZodEnum<{

package/dist/im.js

@@ -10,6 +10,7 @@ export const ImCapabilitiesSchema = z.object({
     maxTextLength: z.number().int().min(128),
     maxFileBytes: z.number().int().min(0),
     threads: z.boolean().optional(),
+    topics: z.boolean().optional(),
     reactions: z.boolean().optional(),
     typing: z.boolean().optional(),
     stream: z.enum(["native", "edit", "none"]).optional(),
@@ -28,6 +29,7 @@ export function resolveImCapabilities(caps) {
     return {
         ...parsed,
         threads: parsed.threads ?? false,
+        topics: parsed.topics ?? false,
         reactions: parsed.reactions ?? false,
         typing: parsed.typing ?? false,
         stream: parsed.stream ?? "none",

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./im.js";
 export * from "./web-search.js";
 export * from "./models.js";
 export * from "./terminals.js";
+export * from "./local-agents.js";
 export { CLI_HOOK_COVERAGE, CLI_HOOK_EVENTS } from "./cli-hooks.js";
 export * from "./im-markdown.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./im.js";
 export * from "./web-search.js";
 export * from "./models.js";
 export * from "./terminals.js";
+export * from "./local-agents.js";
 export { CLI_HOOK_COVERAGE, CLI_HOOK_EVENTS } from "./cli-hooks.js";
 export * from "./im-markdown.js";
 //# sourceMappingURL=index.js.map

package/dist/local-agents.d.ts

@@ -0,0 +1,282 @@
+import type { z } from "zod";
+type Maybe<T> = T | Promise<T>;
+/** SDK 0.2.17. How much an agent may do without asking, as Tomrade settles it for one turn. */
+export type LocalAgentPolicy = "full-access" | "ask" | "read-only";
+/** SDK 0.2.17. What a "not ready" means: what the person has to do about it. */
+export type LocalAgentNeed = "install" | "repair" | "sign-in" | "model" | "service";
+/** SDK 0.2.17. The permission modes Tomrade knows, for `acp.permissionModes`. */
+export declare const PERMISSION_CHOICES: {
+    readonly "full-access": {
+        readonly value: "full-access";
+        readonly label: "Full access";
+    };
+    readonly ask: {
+        readonly value: "ask";
+        readonly label: "Ask permissions";
+    };
+    readonly "read-only": {
+        readonly value: "read-only";
+        readonly label: "Read only";
+    };
+    readonly local: {
+        readonly value: "local";
+        readonly label: "Local rules";
+    };
+};
+/** SDK 0.2.17. Thrown from `lend.ask` when the CLI said, in its own words, that it is not signed in. */
+export declare class NotSignedIn extends Error {
+    constructor(message: string);
+}
+export interface LocalAgentChoice {
+    value: string;
+    label?: string;
+}
+/** What the agent offered the last time a session opened, for the Model and Effort picks. Kept across restarts. */
+export interface LocalAgentCatalog {
+    models: LocalAgentChoice[];
+    efforts: LocalAgentChoice[];
+}
+export interface LocalAgentPick {
+    key: string;
+    title: string;
+    choices: LocalAgentChoice[];
+    /** Choices are suggestions only: settings may hold any string. */
+    freeText?: boolean;
+}
+/**
+ * SDK 0.2.18. An installer script the app runs for the person: `script` (a
+ * POSIX shell installer) as `curl -fsSL <url> | bash`, `powershell` as
+ * `irm <url> | iex`. Plugin code names only the address.
+ */
+export type LocalAgentInstaller = {
+    script: string;
+} | {
+    powershell: string;
+};
+/** How the agent is installed and signed in, for setup screens. */
+export interface LocalAgentSetup {
+    /** Install commands, the recommended one first; an installer script by its address (SDK 0.2.18). */
+    install: (string | LocalAgentInstaller)[];
+    signIn?: string;
+    /** Signing in starts the agent itself, which then asks; otherwise the command signs in and returns. */
+    signInRuns?: boolean;
+    docs?: string;
+    suggested?: boolean;
+}
+/** The machine a CLI is looked for on, for `cli.bundled`. */
+export interface LocalCliHost {
+    platform: string;
+    env: Record<string, string | undefined>;
+    home: string;
+    /** Where Windows' installed-apps list says apps whose display name matches were installed; none elsewhere. */
+    installs(displayName: RegExp): Promise<string[]>;
+}
+/** A copy of the CLI inside a desktop app. */
+export interface BundledCli {
+    file: string;
+    /** The app's binary that runs `file` as Node; absent when `file` is the app's own launcher, run as it is. */
+    runtime?: string;
+}
+/** A desktop app of the same agent that lacks the CLI, named when the CLI is missing but the app is there. */
+export interface LocalAgentDesktopApp {
+    title: string;
+    /** macOS bundle names, looked for in /Applications and ~/Applications. */
+    mac?: string[];
+    /** Windows install folders, relative to %LOCALAPPDATA% or Program Files. */
+    windows?: string[];
+    paths?: string[];
+}
+export interface LocalCliRunOptions {
+    cwd?: string;
+    /** Laid over Tomrade's own environment; `undefined` removes a variable. */
+    env?: Record<string, string | undefined>;
+    stdin?: string;
+    signal?: AbortSignal;
+    /** Stopped after this long, and answered with `error.killed`. */
+    timeoutMs?: number;
+}
+export interface LocalCliResult {
+    code: number | null;
+    stdout: string;
+    /** Its last few thousand characters. */
+    stderr: string;
+    /** Set when there was no exit to report: it did not start, or it was stopped. */
+    error?: {
+        message: string;
+        killed?: boolean;
+        code?: string | number | null;
+    };
+}
+/**
+ * SDK 0.2.17. The agent's CLI as Tomrade found it — the path the person chose
+ * in Settings, else PATH, a login shell's PATH, npm's prefix, WSL or a bundled
+ * app — started the way Tomrade starts its own agents (no console window, its
+ * process tree stopped on Windows).
+ */
+export interface LocalCli {
+    readonly name: string;
+    /** Runs it to its end: all of stdout, the tail of stderr. */
+    run(args: string[], opts?: LocalCliRunOptions): Promise<LocalCliResult>;
+    /** Runs it with stdout read as JSON lines, each line that parses handed to `onLine`. */
+    jsonl(args: string[], opts: LocalCliRunOptions & {
+        onLine(line: Record<string, unknown>): void;
+    }): Promise<{
+        code: number | null;
+        stderr: string;
+    }>;
+}
+/** Tomrade's MCP server, for the agent's own configuration; null while it is not running. */
+export interface LocalAgentMcp {
+    url: string | null;
+    /** Where the agent's hooks post its session's events. */
+    eventUrl: string | null;
+}
+export interface LocalAgentIo<O> {
+    cli: LocalCli;
+    mcp: LocalAgentMcp;
+    /** The person's settings for this agent (`engines.<id>`), read through `options`. */
+    options: O;
+}
+/** How a connection to Tomrade looks from the agent's side, as the Assistant settings show it. */
+export interface McpLinkState {
+    /** `stale`: a `tomrade` server is configured, but at another address. */
+    state: "connected" | "missing" | "stale" | "unavailable";
+    url: string | null;
+    configuredUrl: string | null;
+    file: string | null;
+    /** Commands that do the same by hand. */
+    manual: {
+        connect: string;
+        disconnect: string;
+    };
+    error?: string;
+}
+/**
+ * The agent's own user-level connection to Tomrade, so sessions a person
+ * starts reach it too: managed by the plugin, or by the agent's own
+ * `mcp add` / `mcp remove`, which Tomrade runs.
+ */
+export type LocalAgentMcpLink<O> = {
+    status(io: LocalAgentIo<O>): Maybe<McpLinkState>;
+    connect(io: LocalAgentIo<O>): Maybe<McpLinkState>;
+    disconnect(io: LocalAgentIo<O>): Maybe<McpLinkState>;
+} | {
+    cli: {
+        /** Where the agent keeps it. */
+        file(): string;
+        /** The address its `tomrade` entry names; null when there is none; throws when the file cannot be read. */
+        configuredUrl(): string | null;
+        add(url: string): string[];
+        remove(): string[];
+    };
+};
+/** One worker call: the instructions and the conversation as text. */
+export interface LentRequest {
+    system: string;
+    transcript: string;
+}
+export interface LentAnswer {
+    text: string;
+    /** All of the input, what the cache read included. */
+    inputTokens: number;
+    cacheReadTokens?: number;
+    outputTokens: number;
+}
+export interface LocalAgentOptions {
+    command?: string;
+    model?: string;
+    effort?: string;
+}
+/** How Tomrade talks to an agent that speaks the Agent Client Protocol on stdio. */
+export interface LocalAgentAcp<O> {
+    permissionModes: {
+        default: string;
+        choices: {
+            value: string;
+            label: string;
+        }[];
+    };
+    /** What starts its ACP server on stdio — for a turn, and for the short session that reads its model list. */
+    args(options: O): string[];
+    env?(options: O): Record<string, string>;
+    /** The agent's own session mode for a policy; Tomrade answers whatever it still asks. */
+    mode?(policy: LocalAgentPolicy): string | undefined;
+    /** "always": it registers HTTP MCP servers without advertising that it can. */
+    httpMcp?: "advertised" | "always";
+    /** How a stored session reopens; "never": a cold turn opens a new session with the conversation recapped. */
+    reopen?: "resume" | "load" | "never";
+    /** A tool call's own name, for an agent whose updates carry none but put it in the call's id. */
+    callName?(toolCallId: string): string | undefined;
+    /** Where tokens are reported: the prompt's answer for the turn, a running session total, or per request in a usage update. */
+    usage?: "turn" | "session" | ((update: Record<string, any>) => {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    } | null);
+    /** The prompt's `inputTokens` leaves out what `cachedReadTokens` and `cachedWriteTokens` count. */
+    cacheApart?: boolean;
+    /** How it takes a message sent while a turn runs: its own `session/steer` method, or a `/steer` prompt alongside. */
+    steer?: "method" | "slash";
+    /** Effort levels to offer before a session has advertised its own. */
+    efforts?: string[];
+    /** The agent's own words for a turn it ended on "refusal". */
+    failure?(response: Record<string, any>): string | undefined;
+    /** Its CLI can also be handed a ticket in a terminal. */
+    terminal?: boolean;
+    /** In a terminal it reaches Tomrade only through its user-level connection (`mcpLink`). */
+    terminalViaLink?: boolean;
+}
+/**
+ * SDK 0.2.17. A coding agent installed on this machine, run by Tomrade: over
+ * ACP inside the app when `acp` is given, else only in a terminal the person
+ * sees (handed the ticket, heard over MCP). Settings live under `engines.<id>`.
+ */
+export interface LocalAgentSpec<O extends LocalAgentOptions = LocalAgentOptions> {
+    /** The engine's id, carrying the namespace. */
+    id: string;
+    title: string;
+    cli: {
+        name: string;
+        /** Copies inside desktop apps, tried after PATH. */
+        bundled?(host: LocalCliHost): Maybe<BundledCli[]>;
+        desktopApp?: LocalAgentDesktopApp;
+    };
+    /** The English tail of "not found — …"; `{install}` stands for the first of `setup.install` (SDK 0.2.18). */
+    install: string;
+    setup?: LocalAgentSetup;
+    /** The agent's settings (`engines.<id>`), drawn by the settings UI; an ACP agent needs one with `command`. */
+    options?: z.ZodType<O>;
+    /** What gets a signed-out agent going, said after its own error. */
+    signIn?: string;
+    /** A run that tells whether the agent can work yet; it may also fill in the catalog's models. */
+    probe?: {
+        args: string[];
+        says(output: string, catalog: LocalAgentCatalog): boolean | null;
+        reason: string;
+        need?: LocalAgentNeed;
+    };
+    /** Whether it is signed in, read without running it; null: no clear answer, taken as yes. */
+    signedIn?: {
+        ask(): Maybe<boolean | null>;
+        reason: string;
+    };
+    /** The agent's own logs and setup facts, for the troubleshooter. */
+    diagnostics?: {
+        logs?(): string[];
+        facts?(catalog: LocalAgentCatalog): Record<string, string>;
+    };
+    acp?: LocalAgentAcp<O>;
+    /** A terminal-only agent's picks (an ACP agent's come from its sessions). */
+    picks?: LocalAgentPick[];
+    mcpLink?: LocalAgentMcpLink<O>;
+    /** Its sign-in lent to Tomrade's worker for one-shot calls, in Automatic order by `rank` (lowest first). */
+    lend?: {
+        rank?: number;
+        ask(request: LentRequest, io: LocalAgentIo<O> & {
+            signal?: AbortSignal;
+        }): Promise<LentAnswer>;
+    };
+}
+export {};
+//# sourceMappingURL=local-agents.d.ts.map

package/dist/local-agents.js

@@ -0,0 +1,15 @@
+/** SDK 0.2.17. The permission modes Tomrade knows, for `acp.permissionModes`. */
+export const PERMISSION_CHOICES = {
+    "full-access": { value: "full-access", label: "Full access" },
+    ask: { value: "ask", label: "Ask permissions" },
+    "read-only": { value: "read-only", label: "Read only" },
+    local: { value: "local", label: "Local rules" }
+};
+/** SDK 0.2.17. Thrown from `lend.ask` when the CLI said, in its own words, that it is not signed in. */
+export class NotSignedIn extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotSignedIn";
+    }
+}
+//# sourceMappingURL=local-agents.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.16";
+export declare const SDK_CONTRACT = "0.2.19";
 export declare const PLUGIN_ID: RegExp;
 export declare const NAMESPACE: RegExp;
 /** The app's own names, and the official publisher's. */
@@ -40,6 +40,7 @@ export declare const ContributesSchema: z.ZodObject<{
     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>>>;
+    localAgents: 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
@@ -162,6 +163,7 @@ export declare const ManifestSchema: z.ZodObject<{
         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>>>;
+        localAgents: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
     authoredBy: z.ZodDefault<z.ZodEnum<{
         agent: "agent";

package/dist/manifest.js

@@ -2,7 +2,7 @@ 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.16";
+export const SDK_CONTRACT = "0.2.19";
 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. */
@@ -44,7 +44,9 @@ export const ContributesSchema = z
     /** 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([])
+    modelProviders: z.array(z.string()).default([]),
+    /** SDK 0.2.17: the local agents it registers. */
+    localAgents: z.array(z.string()).default([])
 })
     .partial();
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomradex/plugin-sdk",
-  "version": "0.2.16",
+  "version": "0.2.19",
   "type": "module",
   "author": "Haoyuan Tang",
   "engines": {
@@ -29,7 +29,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tomradex/domain": "0.2.16",
+    "@tomradex/domain": "0.2.19",
     "zod": "^4.4.3"
   }
 }