evOo-local/packages/adapters/src/builtin-tools.ts

import type { ConnectorTool } from "@rakazo/adapter-kit";
import {
  BotSecretDestination,
  BotSecretName,
  MODEL_TIERS,
  SecretAskPurpose,
  SecretHttpRequest,
  USER_FACT_CATEGORIES,
} from "@rakazo/contracts";
import { z } from "zod";

export const SUBAGENT_MODEL_TIER_DESCRIPTION =
  "Optional model tier: fast for quick simple work, code for programming, standard otherwise. Uses the model this space maps to the tier, or your own model when it maps none. Ignored when model_provider and model_id are set.";

export const DELEGATION_TOOL_NAMES = new Set([
  "run_subagent",
  "spawn_bot",
  "create_project",
  "archive_bot",
  "delete_bot",
  "handoff_to_bot",
  "message_bot",
  "delegate_task",
]);

export const builtinAgentTools: ConnectorTool[] = [
  {
    name: "computer_observe",
    description:
      "Capture the current screen of this bot's computer. Returns frame metadata and an image. Observe before coordinate-based actions and whenever another actor may have changed the desktop.",
    inputSchema: { type: "object", properties: {} },
  },
  {
    name: "computer_act",
    description:
      "Perform up to 24 ordered desktop actions on this bot's computer and return the resulting screen. Batch only predictable actions; stop before an outcome you need to inspect. Action kinds: click, move, down, up, type, key, scroll, wait.",
    inputSchema: {
      type: "object",
      properties: {
        actions: {
          type: "array",
          items: {
            type: "object",
            properties: {
              kind: {
                type: "string",
                enum: ["click", "move", "down", "up", "type", "key", "scroll", "wait"],
              },
              x: { type: "number" },
              y: { type: "number" },
              button: { type: "string", enum: ["left", "right"] },
              double: { type: "boolean" },
              text: { type: "string" },
              key: { type: "string" },
              modifiers: { type: "array", items: { type: "string" } },
              direction: { type: "string", enum: ["up", "down"] },
              amount: { type: "number" },
              ms: { type: "number" },
            },
            required: ["kind"],
          },
        },
        observe: { type: "boolean" },
        settle_ms: { type: "number" },
      },
      required: ["actions"],
    },
  },

  {
    name: "browser_navigate",
    description:
      'Open a URL in the page browser on this bot\'s computer and return the document title. Prefer this over pixel clicks for web pages. If the result includes fallback:"computer_act", use computer_act on the desktop browser instead.',
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "http(s) URL to open." },
      },
      required: ["url"],
    },
  },
  {
    name: "browser_snapshot",
    description:
      "Capture an accessibility-style snapshot of the current page with element refs (e1, e2, …). Use refs with browser_act. Prefer this over computer_observe for web pages. If fallback is computer_act, use the desktop tools instead.",
    inputSchema: { type: "object", properties: {} },
    readOnly: true,
  },
  {
    name: "browser_act",
    description:
      'Click or fill page elements by ref from browser_snapshot (kinds: click, fill, type). Prefer this over computer_act for web pages. If the result includes fallback:"computer_act", use computer_act instead.',
    inputSchema: {
      type: "object",
      properties: {
        actions: {
          type: "array",
          items: {
            type: "object",
            properties: {
              kind: { type: "string", enum: ["click", "fill", "type"] },
              ref: { type: "string", description: "Element ref from browser_snapshot." },
              text: { type: "string", description: "Text for fill or type." },
            },
            required: ["kind", "ref"],
          },
        },
      },
      required: ["actions"],
    },
  },
  {
    name: "list_files",
    description:
      "List files and directories in this bot's home. On a Team Computer, relative paths use the bot folder; use shared/... for shared work or bots/... to inspect the Team root.",
    inputSchema: {
      type: "object",
      properties: { path: { type: "string" } },
    },
  },
  {
    name: "read_file",
    description:
      "Read a UTF-8 text file from this bot's home. On a Team Computer, relative paths use the bot folder and shared/... accesses shared work. Open visual or binary files with open_path instead.",
    inputSchema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
    },
  },
  {
    name: "write_file",
    description:
      "Write a UTF-8 file into this bot's home. On a Team Computer, relative paths use the bot folder; use shared/... only for work other bots should share.",
    inputSchema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" },
      },
      required: ["path", "content"],
    },
  },
  {
    name: "attach_file",
    description:
      "Attach a workspace file from this bot's home to the chat thread as an image or common file. The file stays in place; users can open it from the message.",
    inputSchema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
    },
  },
  {
    name: "shell",
    description:
      "Run a command inside this bot's computer. cwd defaults to the bot's folder on a Team Computer and the workspace root on a Private Computer.",
    inputSchema: {
      type: "object",
      properties: {
        command: { type: "string" },
        cwd: { type: "string" },
      },
      required: ["command"],
    },
  },
  {
    name: "open_path",
    description:
      "Open a workspace file or an http(s) URL in its default graphical application on this bot's computer and return the resulting screen.",
    inputSchema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
    },
  },
  {
    name: "launch_app",
    description:
      "Launch an installed graphical application on this bot's computer, optionally with a URI, and return the resulting screen.",
    inputSchema: {
      type: "object",
      properties: {
        application: { type: "string" },
        uri: { type: "string" },
      },
      required: ["application"],
    },
  },
  {
    name: "request_takeover",
    description:
      "Ask the user to take over the computer screen for passwords, 2FA, CAPTCHA, payment, passkeys, or other protected input. Never ask the user to paste protected values in chat.",
    inputSchema: {
      type: "object",
      properties: { reason: { type: "string" } },
      required: ["reason"],
    },
  },
  {
    name: "ask_user",
    description:
      "Ask the user one short multiple-choice question with tappable options, then wait for their selection. Use this instead of asking them to type when two to four concise choices are enough.",
    inputSchema: {
      type: "object",
      properties: {
        question: { type: "string", maxLength: 240 },
        options: {
          type: "array",
          items: { type: "string", minLength: 1, maxLength: 80 },
          minItems: 2,
          maxItems: 4,
          uniqueItems: true,
        },
      },
      required: ["question", "options"],
    },
  },
  {
    name: "message_user",
    description:
      "Post a short progress update to the user in this chat immediately. Does not end your turn. Use sparingly during long work for high-signal beats (what you are checking, then a result). Do not dump tool logs, thinking, or a play-by-play of every call. HARD LIMIT: cut off silently at 500 characters, so never put your final answer, a report, or any long-form content here \u2014 it will arrive mangled and the user will never see the rest. Always write your complete final answer in your normal reply, not here.",
    inputSchema: {
      type: "object",
      properties: {
        message: {
          type: "string",
          maxLength: 500,
          description:
            "Short user-visible update, not the final answer \u2014 longer text is silently truncated.",
        },
      },
      required: ["message"],
    },
  },
  {
    name: "request_secret",
    description:
      "Collect a credential in a masked field. Supply credential to save a named API credential for this bot and user at one HTTPS origin, or connectionId for a one-use connector code. Existing named credentials are reused unless replace is true. For website logins, CAPTCHA, passkeys, or anything that needs the live desktop, call request_takeover instead.",
    // Exactly one destination: credential XOR connectionId. Sibling optionals
    // looked schema-valid to models but the executor rejects both and neither.
    inputSchema: {
      oneOf: [
        {
          type: "object",
          properties: {
            label: { type: "string" },
            purpose: { type: "string", enum: SecretAskPurpose.options },
            credential: z.toJSONSchema(BotSecretDestination),
            replace: {
              type: "boolean",
              description: "Ask the user to replace an existing credential value.",
            },
          },
          required: ["label", "purpose", "credential"],
          additionalProperties: false,
        },
        {
          type: "object",
          properties: {
            label: { type: "string" },
            purpose: { type: "string", enum: SecretAskPurpose.options },
            connectionId: { type: "string" },
          },
          required: ["label", "purpose", "connectionId"],
          additionalProperties: false,
        },
      ],
    },
  },
  {
    name: "list_secrets",
    description:
      "List saved credential names and destinations available to this bot and user. Values are never returned.",
    inputSchema: { type: "object", properties: {} },
  },
  {
    name: "secret_request",
    description:
      "Make an authenticated HTTPS request using a saved credential name. The backend injects authentication only at its saved origin. Redirects are rejected; response echoes of the credential are redacted. Use normal request URLs and bodies without secret placeholders.",
    inputSchema: z.toJSONSchema(SecretHttpRequest, { io: "input" }),
  },
  {
    name: "forget_secret",
    description:
      "Remove a saved credential for this bot and user, preventing future requests from using it.",
    inputSchema: z.toJSONSchema(z.object({ name: BotSecretName })),
  },
  {
    name: "render_plot",
    description:
      'Render a chart from tabular data as a PNG and attach it to the chat. Backed by Observable Plot: bar, line, area, scatter, histogram, heatmap, box plot, facets, and more via a declarative JSON spec. Call with {"charts": true} FIRST to list every chart type with a complete runnable example spec ({"charts": "<keyword>"} searches), then copy the closest example and substitute your rows and columns. {"help": true} returns the full guide. Pass rows inline as data, or data_path for a .csv/.tsv/.json file in your home.',
    inputSchema: {
      type: "object",
      properties: {
        charts: {
          description:
            'true lists all chart types with runnable example specs; a keyword string (e.g. "distribution", "share", "trend") searches them.',
        },
        help: {
          type: "boolean",
          description: "Return the full render_plot skill guide instead of rendering.",
        },
        spec: {
          type: "object",
          description:
            "Declarative Observable Plot spec: {title?, width?, height?, x?, y?, color?, fx?, fy?, marks: [{type, options, transform?, data?}]}.",
        },
        data: {
          type: "array",
          description: "Rows as objects, shared by marks without their own data.",
        },
        data_path: {
          type: "string",
          description:
            "Workspace path of a .csv, .tsv, or .json rows file to load instead of inline data.",
        },
        path: {
          type: "string",
          description: "Output PNG path in this bot's home. Default charts/plot-<n>.png.",
        },
        attach: {
          type: "boolean",
          description: "Attach the rendered PNG to the chat (default true).",
        },
      },
    },
  },
  {
    name: "add_mcp_server",
    description:
      "Connect an MCP tool server to this Space when the user asks you to add one and provides the details (URL or command, optional token/headers/env). The server is created immediately and assigned to you. If it needs browser OAuth authorization, an approval card appears in the chat for the user to complete — tell them to click Authorize. Do not invent endpoints; only use details the user provided.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: 'Display name, e.g. "Brex".' },
        transport: {
          type: "string",
          enum: ["streamable_http", "sse", "stdio"],
          description:
            "streamable_http for modern HTTP servers, sse for legacy HTTP servers, stdio for local commands.",
        },
        endpoint: {
          type: "string",
          description: "HTTPS URL of the remote MCP server (required unless transport is stdio).",
        },
        command: {
          type: "string",
          description:
            "Executable path for stdio transport (required for stdio). Must be allowlisted by the deployment.",
        },
        args: {
          type: "array",
          items: { type: "string" },
          description:
            "Arguments for the stdio command. A single space-separated string also works.",
        },
        env: {
          type: "object",
          description: 'Environment variables for stdio transport, e.g. {"API_KEY": "..."}.',
        },
        headers: {
          type: "object",
          description: 'HTTP headers for remote transports, e.g. {"Authorization": "Bearer ..."}.',
        },
        secret: {
          type: "string",
          description: "Static access token, equivalent to an Authorization: Bearer header.",
        },
        assign_to_self: {
          type: "boolean",
          description:
            "Assign the server to you so its tools are usable in this conversation (default true).",
        },
      },
      required: ["name", "transport"],
    },
  },
  {
    name: "remember",
    description: "Store a durable fact in this bot's explicit memory.",
    inputSchema: {
      type: "object",
      properties: {
        content: { type: "string" },
        path: { type: "string" },
      },
      required: ["content"],
    },
  },
  {
    name: "update_user_profile",
    description:
      "Save what you learned about the user so all of their bots can use it: short facts and profile settings. Save only what the user said or clearly confirmed, never guesses. Health and values facts stay hidden from bots until the user confirms them.",
    inputSchema: {
      type: "object",
      properties: {
        facts: {
          type: "array",
          maxItems: 20,
          items: {
            type: "object",
            properties: {
              category: { type: "string", enum: [...USER_FACT_CATEGORIES] },
              value: {
                type: "string",
                description: 'One short statement, e.g. "Works night shifts as a nurse".',
              },
            },
            required: ["category", "value"],
          },
        },
        time_zone: { type: "string", description: "IANA time zone, e.g. Europe/Vienna." },
        language: {
          type: "string",
          description: "Language the user wants replies in, as a BCP-47 tag, e.g. de.",
        },
        communication_style: {
          type: "string",
          description: 'How the user wants to be talked to, e.g. "brief and informal".',
        },
      },
    },
  },
  {
    name: "web_search",
    description:
      "Search the public web. Returns titles, URLs, and snippets. Use when you need current information or links; follow with web_fetch to read a page. Does not need a computer.",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query." },
        maxResults: {
          type: "number",
          description: "Max results to return (default 5, max 10).",
        },
      },
      required: ["query"],
    },
    readOnly: true,
  },
  {
    name: "web_fetch",
    description:
      "Fetch a public http(s) page and return readable text (title + content). Read-only; no JavaScript. Use after web_search when you need the page itself.",
    inputSchema: {
      type: "object",
      properties: {
        url: { type: "string", description: "Page URL (http or https)." },
        maxChars: {
          type: "number",
          description: "Max characters of body text (default 8000).",
        },
      },
      required: ["url"],
    },
    readOnly: true,
  },
  {
    name: "cloud_agent_launch",
    description:
      "Launch a remote cloud coding agent on a connected repository. Returns immediately with a tracking id and status; the agent link appears when launched. Opens a PR when openPr is true. Not the bot computer.",
    inputSchema: {
      type: "object",
      properties: {
        prompt: { type: "string", description: "Task for the remote agent." },
        repository: {
          type: "string",
          description: "Git repository URL (optional for no-repo agents).",
        },
        openPr: {
          type: "boolean",
          description: "Open a pull request when the run finishes.",
        },
        images: {
          type: "array",
          description: "Optional images (data+mimeType or url).",
          items: { type: "object" },
        },
      },
      required: ["prompt"],
    },
  },
  {
    name: "cloud_agent_status",
    description: "Get status, branch, and PR url for a cloud coding agent.",
    inputSchema: {
      type: "object",
      properties: {
        id: { type: "string", description: "Cloud agent id from launch." },
      },
      required: ["id"],
    },
    readOnly: true,
  },
  {
    name: "cloud_agent_reply",
    description: "Send a follow-up prompt to an existing cloud coding agent.",
    inputSchema: {
      type: "object",
      properties: {
        id: { type: "string", description: "Cloud agent id." },
        prompt: { type: "string", description: "Follow-up instruction." },
        images: {
          type: "array",
          description: "Optional images (data+mimeType or url).",
          items: { type: "object" },
        },
      },
      required: ["id", "prompt"],
    },
  },
  {
    name: "cloud_agent_cancel",
    description: "Cancel the active run on a cloud coding agent.",
    inputSchema: {
      type: "object",
      properties: {
        id: { type: "string", description: "Cloud agent id." },
      },
      required: ["id"],
    },
  },
  // Semantic-memory tools: exposed by selectMemoryTools() only when a
  // A Space memory provider is configured (which hides `remember`).
  {
    name: "save_memory",
    description:
      "Store a durable fact in this bot's semantic memory (preferences, decisions, recurring context). Use for anything worth recalling in future conversations.",
    inputSchema: {
      type: "object",
      properties: {
        content: { type: "string" },
      },
      required: ["content"],
    },
  },
  {
    name: "recall_memory",
    description: "Semantically search this bot's durable memory for facts relevant to a query.",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string" },
      },
      required: ["query"],
    },
  },
  {
    name: "forget_memory",
    description:
      "Forget a durable semantic memory by id (from recall citations). Providers without forget support return an error.",
    inputSchema: {
      type: "object",
      properties: {
        id: { type: "string", description: "Memory id from a prior recall citation." },
        entity: {
          type: "string",
          description:
            "Optional entity/namespace from the recall citation when the provider scopes deletes.",
        },
        reason: { type: "string", description: "Optional reason recorded with the forget." },
      },
      required: ["id"],
    },
  },
  {
    name: "scratchpad_list",
    description:
      "List this bot's scratchpad / open-work items (todos and parked work). By default omits completed items.",
    inputSchema: {
      type: "object",
      properties: {
        includeDone: {
          type: "boolean",
          description: "When true, include completed items.",
        },
      },
    },
  },
  {
    name: "scratchpad_add",
    description:
      "Add an open-work item to this bot's scratchpad. Use for todos or parked work that should outlive this turn. Not a reminder or schedule.",
    inputSchema: {
      type: "object",
      properties: {
        title: { type: "string", description: "Short title for the item." },
        status: {
          type: "string",
          enum: ["open", "parked", "done"],
          description: "Defaults to open.",
        },
        notes: { type: "string", description: "Optional notes." },
      },
      required: ["title"],
    },
  },
  {
    name: "scratchpad_update",
    description: "Update a scratchpad item's title, status, or notes.",
    inputSchema: {
      type: "object",
      properties: {
        itemId: { type: "string" },
        title: { type: "string" },
        status: { type: "string", enum: ["open", "parked", "done"] },
        notes: { type: "string" },
      },
      required: ["itemId"],
    },
  },
  {
    name: "scratchpad_complete",
    description: "Mark a scratchpad item done.",
    inputSchema: {
      type: "object",
      properties: {
        itemId: { type: "string" },
      },
      required: ["itemId"],
    },
  },
  {
    name: "scratchpad_remove",
    description: "Permanently remove a scratchpad item.",
    inputSchema: {
      type: "object",
      properties: {
        itemId: { type: "string" },
      },
      required: ["itemId"],
    },
  },
  {
    name: "schedule_create",
    description:
      'Create a reminder or recurring job for this bot. Use for "remind me in 10 minutes" or "every morning send a joke". Repeats: cron or every/unit (min 1 minute). One-shot: runAt, delayMinutes, or delaySeconds.',
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Short label shown in Routines." },
        prompt: {
          type: "string",
          description:
            "Concrete steps for when the schedule fires: name the connected plugin tools to call (e.g. GITHUB_LIST_RELEASES for owner/repo), what to extract, and how to report. Prefer plugin tools over computer browser or web search for app data.",
        },
        cron: { type: "string", description: "5-field cron for repeating schedules." },
        every: { type: "number", description: "Repeat interval amount for repeating schedules." },
        unit: {
          type: "string",
          enum: ["minutes", "hours", "days"],
          description: "Unit for every (minimum 1 minute).",
        },
        runAt: {
          type: "string",
          description: "ISO datetime for a one-shot schedule.",
        },
        delayMinutes: {
          type: "number",
          description: "Minutes from now for a one-shot schedule.",
        },
        delaySeconds: {
          type: "number",
          description: "Seconds from now for a one-shot schedule (may be under one minute).",
        },
        timezone: {
          type: "string",
          description: "IANA timezone (default: the user's time zone, else UTC).",
        },
      },
      required: ["name", "prompt"],
    },
  },
  {
    name: "schedule_list",
    description: "List this bot's active and inactive schedules (routines).",
    inputSchema: { type: "object", properties: {} },
  },
  {
    name: "schedule_cancel",
    description: "Cancel a schedule by routineId or exact name.",
    inputSchema: {
      type: "object",
      properties: {
        routineId: { type: "string" },
        name: { type: "string" },
      },
    },
  },
  {
    name: "skill_read",
    description:
      "Load a Claude Agent Skill (SKILL.md recipe) by exact name. Call this when a catalog skill matches the user's request, then follow it immediately.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Exact skill name from the catalog." },
      },
      required: ["name"],
    },
  },
  {
    name: "skill_create",
    description:
      "Create a reusable Claude Agent Skill (generic how-to SKILL.md) shared across assistants. The Pi runtime already understands this format; we persist and inject them. Use when a multi-step task is worth repeating or the user asks to save a skill. Do not include account names, channels, or inboxes — those belong in a routine.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Short skill name." },
        description: {
          type: "string",
          description: "When to use this skill (shown in the / picker and used for auto-use).",
        },
        body: {
          type: "string",
          description: "Markdown steps and guidance after the frontmatter.",
        },
        content: {
          type: "string",
          description:
            "Optional full SKILL.md (frontmatter + body) instead of name/description/body.",
        },
      },
    },
  },
  {
    name: "skill_update",
    description:
      "Update a user-created skill by name or id. Builtin and plugin skills are read-only.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Current exact skill name." },
        skillId: { type: "string" },
        newName: { type: "string" },
        description: { type: "string" },
        body: { type: "string" },
        content: { type: "string", description: "Optional full replacement SKILL.md." },
      },
    },
  },
  {
    name: "skill_delete",
    description:
      "Delete a user-created skill by name or id. Builtin and plugin skills cannot be deleted.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string" },
        skillId: { type: "string" },
      },
    },
  },
  {
    name: "run_subagent",
    description:
      "Run a short-lived helper inside this turn only. It is not a bot: no list entry, no thread, no computer of its own, and it disappears when this turn ends. Never call this because the user asked to create a bot — that is spawn_bot, and spawn_bot alone.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Short label shown in the thread, e.g. scout or reviewer.",
        },
        task: { type: "string", description: "The work the helper should complete." },
        instructions: {
          type: "string",
          description: "Optional extra system instructions for the helper.",
        },
        model_provider: {
          type: "string",
          description: "Optional connected model provider. Set together with model_id.",
        },
        model_id: {
          type: "string",
          description: "Optional connected model ID. Set together with model_provider.",
        },
        model_tier: {
          type: "string",
          enum: [...MODEL_TIERS],
          description: SUBAGENT_MODEL_TIER_DESCRIPTION,
        },
      },
      required: ["name", "task"],
    },
  },
  {
    name: "create_project",
    description:
      "Create a project group when the user asks for a new project or team workspace. Projects are shared chats for 2–6 agents. Always include yourself plus the relevant teammates in bot_ids. Creating the project is the whole action unless the user also asked to start work in it.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          minLength: 1,
          maxLength: 80,
          description: 'Short project name, e.g. "Website Redesign".',
        },
        bot_ids: {
          type: "array",
          items: { type: "string" },
          minItems: 1,
          description:
            "Agent ids to invite. You are added automatically; include at least one other teammate.",
        },
      },
      required: ["name", "bot_ids"],
    },
  },
  {
    name: "create_space",
    description:
      "Propose a new space in the current organization when the user asks for a separate data boundary. A space can contain many bots and groups, but its chats, files, memory, tools, and integrations stay isolated from other spaces. This always shows the user a confirmation card before creation. Creating the space is the whole action; do not create bots in it unless the user asks later.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          minLength: 1,
          maxLength: 60,
          description: 'Short display name, e.g. "Customer support".',
        },
      },
      required: ["name"],
    },
  },
  {
    name: "spawn_bot",
    description:
      "Create a full, regular bot — the same kind the user creates from the + button. It gets its own thread, computer, and memory, and appears as a peer in the bot list. Do not also call run_subagent. Creating the bot is the whole action. Only set prompt if the user asked that new bot to start work immediately.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string" },
        title: { type: "string" },
        instructions: { type: "string" },
        prompt: {
          type: "string",
          description: "Optional first task to run in the new bot's thread.",
        },
        computer_mode: {
          type: "string",
          enum: ["team", "dedicated"],
          description:
            "Optional. team shares one screen with other Team bots; dedicated (Private) gets its own. Defaults to team.",
        },
      },
      required: ["name"],
    },
  },
  {
    name: "update_bot",
    description:
      "Update this bot's own profile fields that the user sees in chat: name (header and list label), title (short role line), description, speaking voice, and whether replies are read aloud. Call this when the user asks you to rename yourself, change your title/description, pick a different voice (e.g. Eva, Bernd), or turn speaking on/off. Do not claim you updated the profile without calling this tool.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Display name shown in the chat header and bot list.",
        },
        title: {
          type: "string",
          description: "Short role or headline shown in bot settings.",
        },
        description: {
          type: "string",
          description: "Longer blurb describing what this bot does.",
        },
        voice_id: {
          type: "string",
          description:
            "Voice id from the connected provider (e.g. df_eva, dm_bernd). Match the user's requested voice name.",
        },
        auto_speak: {
          type: "boolean",
          description: "When true, read replies aloud. When false, stay silent.",
        },
      },
    },
  },
  {
    name: "archive_bot",
    description:
      "Archive a bot this bot created. Archiving stops its work and routines, hides it from the active list, and preserves its conversation, memory, and files for the user to restore or delete later. confirm_name must exactly match its name. This cannot archive you, bots the user created, or bots another bot created.",
    inputSchema: {
      type: "object",
      properties: {
        confirm_name: { type: "string", description: "Exact current name of the bot to archive." },
        bot_id: {
          type: "string",
          description:
            "Optional bot id. If omitted, the unique bot this bot created with confirm_name is archived.",
        },
      },
      required: ["confirm_name"],
    },
  },
  {
    name: "message_bot",
    description:
      'Send a useful update, question, or result to another of the user\'s bots. You must call this tool to actually deliver it — writing the message in your own reply text (e.g. "[to Comms] ...") does not send anything and the recipient never sees it. Delivery is async and does not end your turn. Continue independent work; do not poll or send ack-only messages. Later updates only if they add something new.',
    inputSchema: {
      type: "object",
      properties: {
        bot_id: { type: "string", description: "Target bot id from your teammate list." },
        confirm_name: {
          type: "string",
          description: "Exact name of the target bot when bot_id is omitted.",
        },
        message: { type: "string", description: "What to send." },
        intent: {
          type: "string",
          enum: ["request", "result", "question", "status", "fyi"],
          description: "What the recipient should do with this message. Defaults to request.",
        },
      },
      required: ["message"],
    },
  },
  {
    name: "handoff_to_bot",
    description:
      "In a group chat only: transfer a genuinely distinct next stage to another current member. Appends a visible handoff and starts that bot asynchronously. Do not hand a stage back merely to report or repeat the same work; post results in the shared thread. Never paste this tool as JSON in chat — invoke it directly.",
    inputSchema: {
      type: "object",
      properties: {
        bot_id: { type: "string", description: "Target member bot id." },
        confirm_name: {
          type: "string",
          description: "Exact name of the target member when bot_id is omitted.",
        },
        message: { type: "string", description: "What the receiving bot should do next." },
      },
      required: ["message"],
    },
  },
  {
    name: "delegate_task",
    description:
      "Main agent only: hand a distinct piece of work to one of the user's specialists as a tracked task. A task card appears in the main conversation; a specialist from this space joins it and works there where the user can follow, one from another space works in its own chat. You are woken in the main conversation with the result to close the task with the user. Does not end your turn; do not poll.",
    inputSchema: {
      type: "object",
      properties: {
        bot: { type: "string", description: "Specialist name or id." },
        title: {
          type: "string",
          maxLength: 120,
          description: "Short task title shown on the card.",
        },
        brief: {
          type: "string",
          description:
            "Everything the specialist needs: goal, context, constraints, and what to return.",
        },
        deadline: {
          type: "string",
          description: "Optional ISO 8601 date-time the result is needed by.",
        },
      },
      required: ["bot", "title", "brief"],
    },
  },
];

/** Agent-connection tools, exposed only when the messaging surface is enabled. */
export const agentConnectionTools: ConnectorTool[] = [
  {
    name: "connect_agent",
    description:
      "Request a standing connection to another person's agent by their owner's chat address. The other owner must approve before either agent can message the other. Only for agents whose owner messaged the deployment's chat line.",
    inputSchema: {
      type: "object",
      properties: {
        address: {
          type: "string",
          description:
            "The owner's address on the chat surface: an E.164 phone number (e.g. +15551234567) or platform user id.",
        },
      },
      required: ["address"],
    },
  },
  {
    name: "respond_agent_connection",
    description:
      "Approve or decline the newest pending agent connection request addressed to you. Use only on your owner's explicit instruction.",
    inputSchema: {
      type: "object",
      properties: {
        accept: { type: "boolean", description: "true to approve, false to decline." },
      },
      required: ["accept"],
    },
  },
  {
    name: "message_agent",
    description:
      "Send a useful update, question, or result to another person's agent over an approved connection. Delivery is async and does not end your turn. Continue independent work; do not poll or send ack-only messages.",
    inputSchema: {
      type: "object",
      properties: {
        address: {
          type: "string",
          description:
            "Chat address (phone number or platform user id) of the connected agent's owner.",
        },
        message: { type: "string", description: "What to send." },
      },
      required: ["address", "message"],
    },
  },
];