@ericsanchezok/synergy-util 3.0.22 → 3.0.23

package/dist/activity.js

@@ -41,7 +41,9 @@ export const ActivityDerivedMetadataSchema = z.object({
         .optional(),
 });
 const TOOL_CATEGORIES = {
-    websearch: "web",
+    computer_apps: "generic",
+    computer_observe: "generic",
+    computer_action: "generic",
     webfetch: "web",
     browser_navigation: "browser",
     browser_snapshot: "browser",
@@ -63,8 +65,6 @@ const TOOL_CATEGORIES = {
     browser_assets: "browser",
     browser_annotate: "browser",
     browser_view: "browser",
-    arxiv_search: "search",
-    arxiv_download: "search",
     grep: "search",
     file_search: "search",
     scan_files: "search",
@@ -154,6 +154,7 @@ const TOOL_CATEGORIES = {
     worktree_enter: "config",
     worktree_leave: "config",
     worktree_list: "config",
+    agent_config: "config",
     connect: "network",
     inspire_status: "config",
     inspire_config: "config",
@@ -178,6 +179,7 @@ const TOOL_CATEGORIES = {
     github_deliver_fix: "communication",
     openai_image_gen: "communication",
     openai_image_edit: "communication",
+    speak: "communication",
     render: "analyze",
     attach: "communication",
     response_card: "communication",
@@ -224,6 +226,7 @@ const PATTERN_FALLBACKS = [
 ];
 const ACTIVITY_FAMILIES = new Set(ACTIVITY_FAMILY_ORDER);
 const EXTERNAL_ACTION_TOOLS = new Set([
+    "computer_action",
     "email_send",
     "email_mark_read",
     "session_send",
@@ -249,6 +252,7 @@ const PRODUCTION_COMMUNICATION_TOOLS = new Set([
     "response_card",
     "openai_image_gen",
     "openai_image_edit",
+    "speak",
     "generate_image",
     "edit_image",
 ]);
@@ -266,6 +270,17 @@ const COORDINATION_RECEIPT_TOOLS = new Set([
     "blueprint_loop_stop",
 ]);
 const ACTIVITY_PRESENTATION_BOUNDARY_TOOLS = new Set(["render"]);
+// Built-in remote MCP search families stay visible as individual cards in
+// the activity timeline instead of being folded into grouped summary rows.
+// Their renderers are presentation boundaries with per-query structure the
+// user should be able to inspect after the turn (the same reason `render`
+// is a boundary above).
+const ACTIVITY_PRESENTATION_BOUNDARY_PREFIXES = ["mcp__anysearch__", "mcp__scholight__"];
+function isPresentationBoundaryTool(tool) {
+    if (ACTIVITY_PRESENTATION_BOUNDARY_TOOLS.has(tool))
+        return true;
+    return ACTIVITY_PRESENTATION_BOUNDARY_PREFIXES.some((prefix) => tool.startsWith(prefix));
+}
 function record(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return {};
@@ -292,7 +307,7 @@ function firstString(...values) {
     }
 }
 export function isActivityGroupableTool(tool, metadata = {}) {
-    if (ACTIVITY_PRESENTATION_BOUNDARY_TOOLS.has(tool))
+    if (isPresentationBoundaryTool(tool))
         return false;
     const policy = toolDisplayPolicy(metadata);
     return !policy.toolCardHidden && !policy.mediaGeneration;

package/dist/capability.d.ts

@@ -10,7 +10,7 @@ export interface SynergyCapabilityDefinition {
     nonBypassable?: boolean;
 }
 export declare const SYNERGY_CAPABILITY_DETAILS: Record<string, SynergyCapabilityDefinition>;
-export declare const SYNERGY_PROFILE_CAPABILITIES: readonly ["file_read", "file_write", "shell_read", "shell", "shell_branch_mutation", "shell_remote_execute", "shell_remote_publish", "shell_remote_write", "shell_destructive", "shell_hardline", "file_external_read", "file_external_write", "network_read", "network_request", "mcp_invoke", "mcp_spawn", "session_data", "workspace_data", "config:read", "config:write", "secrets", "task", "prompt_transform", "compaction_transform", "tool_execution_hook", "permission_hook", "event_hook", "config_hook", "identity_act", "communication_email", "channel_outbound", "platform_control", "protected_op", "session_state", "browser_interact", "browser_inspect", "browser_eval_readonly", "browser_eval_trusted", "browser_clipboard", "browser_upload", "browser_coordinate", "browser_download", "browser_emulation"];
+export declare const SYNERGY_PROFILE_CAPABILITIES: readonly ["file_read", "file_write", "shell_read", "shell", "shell_branch_mutation", "shell_remote_execute", "shell_remote_publish", "shell_remote_write", "shell_destructive", "shell_hardline", "file_external_read", "file_external_write", "network_read", "network_request", "mcp_invoke", "mcp_spawn", "session_data", "workspace_data", "config:read", "config:write", "secrets", "task", "prompt_transform", "compaction_transform", "tool_execution_hook", "permission_hook", "event_hook", "config_hook", "identity_act", "communication_email", "channel_outbound", "platform_control", "protected_op", "session_state", "browser_interact", "computer_observe", "computer_interact", "browser_inspect", "browser_eval_readonly", "browser_eval_trusted", "browser_clipboard", "browser_upload", "browser_coordinate", "browser_download", "browser_emulation"];
 export declare const SYNERGY_PERMISSION_CAPABILITY: Record<string, string>;
 export declare function permissionCapability(permission: string): string;
 export declare function capabilityNonBypassable(capability: string): boolean;

package/dist/capability.js

@@ -13,6 +13,20 @@ export const SYNERGY_CAPABILITY_CATEGORIES = [
     "platform",
 ];
 export const SYNERGY_CAPABILITY_DETAILS = {
+    computer_observe: {
+        category: "platform",
+        severity: "high",
+        title: "Observe desktop applications",
+        description: "Can enumerate native applications and read screenshots and accessibility information in Full Access mode.",
+        nonBypassable: true,
+    },
+    computer_interact: {
+        category: "platform",
+        severity: "high",
+        title: "Control desktop applications",
+        description: "Can operate observed native application windows using background input in Full Access mode.",
+        nonBypassable: true,
+    },
     shell_read: {
         category: "runtime",
         severity: "low",
@@ -334,6 +348,8 @@ export const SYNERGY_PROFILE_CAPABILITIES = [
     "protected_op",
     "session_state",
     "browser_interact",
+    "computer_observe",
+    "computer_interact",
     "browser_inspect",
     "browser_eval_readonly",
     "browser_eval_trusted",
@@ -360,9 +376,6 @@ export const SYNERGY_PERMISSION_CAPABILITY = {
     bash: "shell",
     external_directory: "file_external_read",
     webfetch: "network_read",
-    websearch: "network_read",
-    arxiv_search: "network_read",
-    arxiv_download: "network_read",
     download: "network_read",
     network_request: "network_request",
     scan_document: "file_read",
@@ -396,6 +409,7 @@ export const SYNERGY_PERMISSION_CAPABILITY = {
     doom_loop: "session_state",
     worktree_enter: "file_write",
     worktree_leave: "file_write",
+    agent_config: "config:write",
     session_data: "session_data",
     workspace_data: "workspace_data",
     "config:read": "config:read",

package/dist/model-limit.d.ts

@@ -30,6 +30,8 @@ export declare namespace ModelLimit {
      * footprint is their sum.
      */
     function actualInput(tokens: TokenUsage): number;
+    function totalTokens(tokens: TokenUsage): number;
+    function nonReasoningOutput(tokens: TokenUsage): number;
     /**
      * Compute how many tokens are available for input within a model's context.
      *

package/dist/model-limit.js

@@ -20,6 +20,14 @@ export var ModelLimit;
         return tokens.input + tokens.cache.read + tokens.cache.write;
     }
     ModelLimit.actualInput = actualInput;
+    function totalTokens(tokens) {
+        return actualInput(tokens) + tokens.output;
+    }
+    ModelLimit.totalTokens = totalTokens;
+    function nonReasoningOutput(tokens) {
+        return Math.max(0, tokens.output - tokens.reasoning);
+    }
+    ModelLimit.nonReasoningOutput = nonReasoningOutput;
     /**
      * Compute how many tokens are available for input within a model's context.
      *

package/dist/plugin-ids.d.ts

@@ -0,0 +1,13 @@
+export declare namespace PluginToolId {
+    function format(pluginId: string, toolId: string): string;
+    function parse(id: string): {
+        pluginId: string;
+        toolId: string;
+    } | undefined;
+    function is(id: string): boolean;
+}
+export declare namespace PluginId {
+    function isValid(id: string): boolean;
+    function normalize(id: string): string;
+    function mcpServerKey(pluginId: string, serverKey: string): string;
+}

package/dist/plugin-ids.js

@@ -0,0 +1,33 @@
+export var PluginToolId;
+(function (PluginToolId) {
+    function format(pluginId, toolId) {
+        return `plugin__${pluginId}__${toolId}`;
+    }
+    PluginToolId.format = format;
+    function parse(id) {
+        const match = id.match(/^plugin__([^_]+(?:_[^_]+)*?)__([^_].*)$/);
+        if (!match)
+            return undefined;
+        return { pluginId: match[1], toolId: match[2] };
+    }
+    PluginToolId.parse = parse;
+    function is(id) {
+        return id.startsWith("plugin__");
+    }
+    PluginToolId.is = is;
+})(PluginToolId || (PluginToolId = {}));
+export var PluginId;
+(function (PluginId) {
+    function isValid(id) {
+        return /^[a-z][a-z0-9_-]*$/i.test(id);
+    }
+    PluginId.isValid = isValid;
+    function normalize(id) {
+        return id.trim().toLowerCase();
+    }
+    PluginId.normalize = normalize;
+    function mcpServerKey(pluginId, serverKey) {
+        return `${pluginId}::${serverKey}`;
+    }
+    PluginId.mcpServerKey = mcpServerKey;
+})(PluginId || (PluginId = {}));

package/dist/process-identity.js

@@ -72,8 +72,10 @@ async function queryProcessStartIdentity(pid) {
     // recycled within that second is not detected. That failure is fail-safe:
     // the stale lock waits out the acquire timeout instead of a live owner
     // being displaced.
-    const result = await execFileAsync("ps", ["-p", String(pid), "-o", "lstart="]).catch(() => ({ stdout: "" }));
-    const startedAt = Date.parse(result.stdout.trim());
+    const result = await execFileAsync("ps", ["-p", String(pid), "-o", "lstart="], {
+        env: { ...process.env, TZ: "UTC", LC_ALL: "C" },
+    }).catch(() => ({ stdout: "" }));
+    const startedAt = Date.parse(result.stdout.trim() + " UTC");
     return Number.isNaN(startedAt) ? undefined : `unix:${startedAt}`;
 }
 async function linuxBootId() {

package/dist/provider-auth.d.ts

@@ -0,0 +1,89 @@
+export type AuthImportResult = ({
+    type: "success";
+    provider?: string;
+} & ({
+    refresh: string;
+    access: string;
+    expires: number;
+} | {
+    key: string;
+})) | {
+    type: "failed";
+    message?: string;
+};
+export type AuthOuathResult = {
+    url: string;
+    instructions: string;
+} & ({
+    method: "auto";
+    callback(): Promise<({
+        type: "success";
+        provider?: string;
+    } & ({
+        refresh: string;
+        access: string;
+        expires: number;
+    } | {
+        key: string;
+    })) | {
+        type: "failed";
+    }>;
+} | {
+    method: "code";
+    callback(code: string): Promise<({
+        type: "success";
+        provider?: string;
+    } & ({
+        refresh: string;
+        access: string;
+        expires: number;
+    } | {
+        key: string;
+    })) | {
+        type: "failed";
+    }>;
+});
+export type AuthPrompt = {
+    type: "text";
+    key: string;
+    message: string;
+    placeholder?: string;
+    validate?: (value: string) => string | undefined;
+    condition?: (inputs: Record<string, string>) => boolean;
+} | {
+    type: "select";
+    key: string;
+    message: string;
+    options: Array<{
+        label: string;
+        value: string;
+        hint?: string;
+    }>;
+    condition?: (inputs: Record<string, string>) => boolean;
+};
+export type AuthHook<Auth, Provider> = {
+    provider: string;
+    loader?: (auth: () => Promise<Auth>, provider: Provider) => Promise<Record<string, unknown>>;
+    methods: Array<{
+        type: "oauth";
+        label: string;
+        prompts?: AuthPrompt[];
+        authorize(inputs?: Record<string, string>): Promise<AuthOuathResult>;
+    } | {
+        type: "api";
+        label: string;
+        prompts?: AuthPrompt[];
+        authorize?(inputs?: Record<string, string>): Promise<{
+            type: "success";
+            key: string;
+            provider?: string;
+        } | {
+            type: "failed";
+        }>;
+    } | {
+        type: "import";
+        label: string;
+        prompts?: AuthPrompt[];
+        import(inputs?: Record<string, string>): Promise<AuthImportResult>;
+    }>;
+};

package/dist/provider-auth.js

@@ -0,0 +1 @@
+export {};

package/dist/pty-keys.d.ts

@@ -0,0 +1,5 @@
+export interface KeyEncodingResult {
+    data: string;
+    warnings: string[];
+}
+export declare function encodeKeySequence(keys: string[]): KeyEncodingResult;

package/dist/pty-keys.js

@@ -0,0 +1,127 @@
+const ESC = "\x1b";
+const CR = "\r";
+const TAB = "\t";
+const BACKSPACE = "\x7f";
+const namedKeyMap = new Map([
+    ["enter", CR],
+    ["return", CR],
+    ["tab", TAB],
+    ["escape", ESC],
+    ["esc", ESC],
+    ["space", " "],
+    ["bspace", BACKSPACE],
+    ["backspace", BACKSPACE],
+    ["up", `${ESC}[A`],
+    ["down", `${ESC}[B`],
+    ["right", `${ESC}[C`],
+    ["left", `${ESC}[D`],
+    ["home", `${ESC}[1~`],
+    ["end", `${ESC}[4~`],
+    ["pageup", `${ESC}[5~`],
+    ["pagedown", `${ESC}[6~`],
+    ["insert", `${ESC}[2~`],
+    ["delete", `${ESC}[3~`],
+    ["f1", `${ESC}OP`],
+    ["f2", `${ESC}OQ`],
+    ["f3", `${ESC}OR`],
+    ["f4", `${ESC}OS`],
+    ["f5", `${ESC}[15~`],
+    ["f6", `${ESC}[17~`],
+    ["f7", `${ESC}[18~`],
+    ["f8", `${ESC}[19~`],
+    ["f9", `${ESC}[20~`],
+    ["f10", `${ESC}[21~`],
+    ["f11", `${ESC}[23~`],
+    ["f12", `${ESC}[24~`],
+]);
+export function encodeKeySequence(keys) {
+    const warnings = [];
+    let data = "";
+    for (const token of keys) {
+        data += encodeKeyToken(token, warnings);
+    }
+    return { data, warnings };
+}
+function encodeKeyToken(raw, warnings) {
+    const token = raw.trim();
+    if (!token)
+        return "";
+    // Handle ^X notation for Ctrl
+    if (token.length === 2 && token.startsWith("^")) {
+        const ctrl = toCtrlChar(token[1]);
+        if (ctrl)
+            return ctrl;
+    }
+    const parsed = parseModifiers(token);
+    const base = parsed.base;
+    const baseLower = base.toLowerCase();
+    // Handle Shift+Tab
+    if (baseLower === "tab" && parsed.mods.shift) {
+        return `${ESC}[Z`;
+    }
+    // Check named keys
+    const baseSeq = namedKeyMap.get(baseLower);
+    if (baseSeq) {
+        if (parsed.mods.alt) {
+            return `${ESC}${baseSeq}`;
+        }
+        return baseSeq;
+    }
+    // Single character with modifiers
+    if (base.length === 1) {
+        return applyCharModifiers(base, parsed.mods);
+    }
+    if (parsed.hasModifiers) {
+        warnings.push(`Unknown key "${base}" for modifiers; sending literal.`);
+    }
+    return base;
+}
+function parseModifiers(token) {
+    const mods = { ctrl: false, alt: false, shift: false };
+    let rest = token;
+    let sawModifiers = false;
+    while (rest.length > 2 && rest[1] === "-") {
+        const mod = rest[0].toLowerCase();
+        if (mod === "c") {
+            mods.ctrl = true;
+        }
+        else if (mod === "m") {
+            mods.alt = true;
+        }
+        else if (mod === "s") {
+            mods.shift = true;
+        }
+        else {
+            break;
+        }
+        sawModifiers = true;
+        rest = rest.slice(2);
+    }
+    return { mods, base: rest, hasModifiers: sawModifiers };
+}
+function applyCharModifiers(char, mods) {
+    let value = char;
+    if (mods.shift && value.length === 1 && /[a-z]/.test(value)) {
+        value = value.toUpperCase();
+    }
+    if (mods.ctrl) {
+        const ctrl = toCtrlChar(value);
+        if (ctrl)
+            value = ctrl;
+    }
+    if (mods.alt) {
+        value = `${ESC}${value}`;
+    }
+    return value;
+}
+function toCtrlChar(char) {
+    if (char.length !== 1)
+        return null;
+    if (char === "?")
+        return "\x7f";
+    const code = char.toUpperCase().charCodeAt(0);
+    if (code >= 64 && code <= 95) {
+        return String.fromCharCode(code & 0x1f);
+    }
+    return null;
+}

package/dist/runtime-startup.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const RUNTIME_STARTUP_PREFIX = "SYNERGY_STARTUP_V1 ";
+export declare const RUNTIME_STARTUP_MAX_LINE_LENGTH = 1024;
+export declare const RuntimeStartupProgress: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    phase: z.ZodLiteral<"starting">;
+}, z.core.$strict>, z.ZodObject<{
+    phase: z.ZodLiteral<"recovery">;
+    current: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    phase: z.ZodLiteral<"migration">;
+    step: z.ZodNumber;
+    current: z.ZodNumber;
+    total: z.ZodNumber;
+}, z.core.$strict>], "phase">;
+export type RuntimeStartupProgress = z.infer<typeof RuntimeStartupProgress>;
+export declare function runtimeStartupLine(progress: RuntimeStartupProgress): string;

package/dist/runtime-startup.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const RUNTIME_STARTUP_PREFIX = "SYNERGY_STARTUP_V1 ";
+export const RUNTIME_STARTUP_MAX_LINE_LENGTH = 1024;
+const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const RuntimeStartupProgress = z.discriminatedUnion("phase", [
+    z.object({ phase: z.literal("starting") }).strict(),
+    z.object({ phase: z.literal("recovery"), current: count }).strict(),
+    z
+        .object({
+        phase: z.literal("migration"),
+        step: count.positive(),
+        current: count,
+        total: count,
+    })
+        .strict()
+        .refine((value) => value.current <= value.total),
+]);
+export function runtimeStartupLine(progress) {
+    return RUNTIME_STARTUP_PREFIX + JSON.stringify(RuntimeStartupProgress.parse(progress)) + "\n";
+}

package/dist/setting-condition.d.ts

@@ -0,0 +1,4 @@
+export interface SettingCondition {
+    setting: string;
+    equals: string | number | boolean;
+}

package/dist/setting-condition.js

@@ -0,0 +1 @@
+export {};

package/dist/shell.d.ts

@@ -0,0 +1,109 @@
+export type ShellFunction = (input: Uint8Array) => Uint8Array;
+export type ShellExpression = {
+    toString(): string;
+} | Array<ShellExpression> | string | {
+    raw: string;
+} | ReadableStream;
+export interface BunShell {
+    (strings: TemplateStringsArray, ...expressions: ShellExpression[]): BunShellPromise;
+    /**
+     * Perform bash-like brace expansion on the given pattern.
+     * @param pattern - Brace pattern to expand
+     */
+    braces(pattern: string): string[];
+    /**
+     * Escape strings for input into shell commands.
+     */
+    escape(input: string): string;
+    /**
+     * Change the default environment variables for shells created by this instance.
+     */
+    env(newEnv?: Record<string, string | undefined>): BunShell;
+    /**
+     * Default working directory to use for shells created by this instance.
+     */
+    cwd(newCwd?: string): BunShell;
+    /**
+     * Configure the shell to not throw an exception on non-zero exit codes.
+     */
+    nothrow(): BunShell;
+    /**
+     * Configure whether or not the shell should throw an exception on non-zero exit codes.
+     */
+    throws(shouldThrow: boolean): BunShell;
+}
+export interface BunShellPromise extends Promise<BunShellOutput> {
+    readonly stdin: WritableStream;
+    /**
+     * Change the current working directory of the shell.
+     */
+    cwd(newCwd: string): this;
+    /**
+     * Set environment variables for the shell.
+     */
+    env(newEnv: Record<string, string> | undefined): this;
+    /**
+     * By default, the shell will write to the current process's stdout and stderr, as well as buffering that output.
+     * This configures the shell to only buffer the output.
+     */
+    quiet(): this;
+    /**
+     * Read from stdout as a string, line by line
+     * Automatically calls quiet() to disable echoing to stdout.
+     */
+    lines(): AsyncIterable<string>;
+    /**
+     * Read from stdout as a string.
+     * Automatically calls quiet() to disable echoing to stdout.
+     */
+    text(encoding?: BufferEncoding): Promise<string>;
+    /**
+     * Read from stdout as a JSON object
+     * Automatically calls quiet()
+     */
+    json(): Promise<any>;
+    /**
+     * Read from stdout as an ArrayBuffer
+     * Automatically calls quiet()
+     */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Read from stdout as a Blob
+     * Automatically calls quiet()
+     */
+    blob(): Promise<Blob>;
+    /**
+     * Configure the shell to not throw an exception on non-zero exit codes.
+     */
+    nothrow(): this;
+    /**
+     * Configure whether or not the shell should throw an exception on non-zero exit codes.
+     */
+    throws(shouldThrow: boolean): this;
+}
+export interface BunShellOutput {
+    readonly stdout: Buffer;
+    readonly stderr: Buffer;
+    readonly exitCode: number;
+    /**
+     * Read from stdout as a string
+     */
+    text(encoding?: BufferEncoding): string;
+    /**
+     * Read from stdout as a JSON object
+     */
+    json(): any;
+    /**
+     * Read from stdout as an ArrayBuffer
+     */
+    arrayBuffer(): ArrayBuffer;
+    /**
+     * Read from stdout as an Uint8Array
+     */
+    bytes(): Uint8Array;
+    /**
+     * Read from stdout as a Blob
+     */
+    blob(): Blob;
+}
+export type BunShellError = Error & BunShellOutput;

package/dist/shell.js

@@ -0,0 +1 @@
+export {};

package/dist/tool-display.d.ts

@@ -0,0 +1,13 @@
+export interface ToolMediaDisplay {
+    type: "image" | "video" | "audio";
+    actionLabel?: string;
+    pendingTitle?: string;
+    pendingDescription?: string;
+    aspectRatio?: "1:1" | "4:3" | "16:9" | "auto";
+    size?: "small" | "medium" | "large";
+}
+export interface ToolDisplay {
+    kind?: "default" | "media-generation";
+    toolCard?: "visible" | "hidden";
+    media?: ToolMediaDisplay;
+}

package/dist/tool-display.js

@@ -0,0 +1 @@
+export {};

package/dist/tool.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import type { ToolDisplay } from "./tool-display.js";
+import type { BunShell } from "./shell.js";
+export type { ToolDisplay, ToolMediaDisplay } from "./tool-display.js";
+export type ToolContext = {
+    sessionID: string;
+    messageID: string;
+    agent: string;
+    abort: AbortSignal;
+    directory?: string;
+    /** Request permission from the user before proceeding */
+    ask?(input: {
+        permission: string;
+        patterns: string[];
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    /** Run shell commands through Synergy's current workspace shell boundary. */
+    $?: BunShell;
+    /** Run a Synergy delegated subagent task from inside this tool. */
+    task?: ToolTaskService;
+    /** Invoke another visible/explicitly-allowed Synergy tool from inside this tool. */
+    tools?: ToolInvokeService;
+};
+export type ToolTaskVisibility = "visible" | "hidden";
+export type ToolTaskOutput = {
+    mode?: "summary";
+} | {
+    mode: "final_response";
+} | {
+    mode: "structured";
+    schema: Record<string, unknown>;
+    maxRepairTurns?: 0 | 1 | 2 | 3;
+};
+export type ToolTaskRunOutput = {
+    mode: "summary";
+    value: string;
+} | {
+    mode: "final_response";
+    value: string;
+} | {
+    mode: "structured";
+    value: unknown;
+};
+export interface ToolTaskRunInput {
+    subagent: string;
+    description: string;
+    prompt: string;
+    tools?: Record<string, boolean>;
+    visibility?: ToolTaskVisibility;
+    timeoutMs?: number;
+    output?: ToolTaskOutput;
+    category?: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+}
+export interface ToolTaskRunResult {
+    taskId: string;
+    sessionId: string;
+    status: "completed" | "error" | "cancelled" | "timeout";
+    output?: ToolTaskRunOutput;
+    error?: string;
+}
+export interface ToolTaskService {
+    run(input: ToolTaskRunInput): Promise<ToolTaskRunResult>;
+}
+export interface ToolInvokeInput {
+    tool: string;
+    args?: unknown;
+    timeoutMs?: number;
+}
+export interface ToolInvokeService {
+    invoke(input: ToolInvokeInput): Promise<ToolResult>;
+}
+export type ToolResultMetadata = Record<string, any> & {
+    display?: ToolDisplay;
+};
+export type PluginToolAttachment = {
+    type: "attachment";
+    id: string;
+    sessionID: string;
+    messageID: string;
+    mime: string;
+    filename?: string;
+    url: string;
+    localPath?: string;
+    presentation?: {
+        hidden?: boolean;
+        renderer?: "image" | "video" | "audio" | "thumbnail" | "file";
+        size?: "original" | "small" | "medium" | "large";
+        crop?: boolean;
+    };
+    model?: {
+        mode: "summary";
+        summary?: string;
+    } | {
+        mode: "content";
+        text?: string;
+    } | {
+        mode: "provider-file";
+        summary?: string;
+    } | {
+        mode: "none";
+    };
+    metadata?: Record<string, any>;
+};
+export interface ToolResult {
+    title?: string;
+    output: string;
+    metadata?: ToolResultMetadata;
+    attachments?: PluginToolAttachment[];
+}
+export type PluginToolResult = ToolResult;
+export type ToolExposure = {
+    mode: "resident";
+} | {
+    mode: "group";
+    group: string;
+    title?: string;
+    description?: string;
+    whenToExpand?: string;
+} | {
+    mode: "search";
+    title?: string;
+    keywords?: string[];
+} | {
+    mode: "internal";
+};
+export declare function tool<Args extends z.ZodRawShape>(input: {
+    description: string;
+    exposure?: ToolExposure;
+    display?: ToolDisplay;
+    args: Args;
+    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string | ToolResult>;
+}): {
+    description: string;
+    exposure?: ToolExposure;
+    display?: ToolDisplay;
+    args: Args;
+    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string | ToolResult>;
+};
+export declare namespace tool {
+    var schema: typeof z;
+}
+export type ToolDefinition = ReturnType<typeof tool>;

package/dist/tool.js

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export function tool(input) {
+    return input;
+}
+tool.schema = z;

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@ericsanchezok/synergy-util",
-  "version": "3.0.22",
+  "version": "3.0.23",
   "type": "module",
   "license": "MIT",
   "exports": {
     "./*": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js"
+    },
+    "./pty-keys": {
+      "types": "./dist/pty-keys.d.ts",
+      "import": "./dist/pty-keys.js"
     }
   },
   "scripts": {