@aglit-ai/sdk 0.1.10 → 0.1.11

package/dist/schema/tools-api.openapi.yaml

@@ -0,0 +1,1665 @@
+# =============================================================================
+# SOURCE FILE - Edit this file directly
+# =============================================================================
+# This OpenAPI spec defines the Tool Builder API schema.
+# It is used to generate TypeScript types in packages/types/src/generated/
+#
+# To regenerate types after editing:
+#   node scripts/sync/sync-tool-interface.js
+#
+# Generated files:
+#   - packages/types/src/generated/tool-builder-input.ts
+#   - packages/desktop-app/src/generated/tool-interface-reference.ts
+#   - packages/desktop-app/api/src/generated/tool-interface-reference.ts
+# =============================================================================
+
+openapi: 3.1.0
+info:
+  title: Aglit Tool Builder API
+  version: 1.0.0
+  description: |
+    API for creating, managing, and executing custom tools in the Aglit desktop app.
+
+    ## Overview
+
+    Tools are reusable automation units that agents can invoke. Each tool lives in
+    `~/.aglit-ai/tools/<tool-id>/` and contains implementation files plus metadata.
+
+    ### Tool Types
+
+    | Type | Entry Point | Use Case |
+    |------|-------------|----------|
+    | `script` | `main.sh` | Shell/CLI automation, orchestration |
+    | `actions` | `main.actions` | Browser and desktop app workflows |
+
+    ### Versioning
+
+    Tool directories are git repositories. Every save commits a new version, enabling
+    rollback via the Versions tab. The backend uses the recorded `commitId` during execution.
+
+    ### Security
+
+    - **Browser tools**: Use `browserProfileId` to control cookies, storage, and sandbox settings
+    - **Shell tools**: Execute through the native terminal backend in the managed VM
+
+    ### Live Streams
+
+    Browser, terminal, and desktop tools automatically start live streams visible in the UI.
+    Responses include `streamId` and `streamUrl` for integration.
+
+  contact:
+    name: Aglit Support
+    url: https://aglit.ai
+  license:
+    name: Proprietary
+    url: https://aglit.ai/terms
+
+servers:
+  - url: http://127.0.0.1:{port}
+    description: |
+      Local desktop app server (SSOT). Runtime uses SERVER_PORT or PORT; update this default if the
+      expected local port changes so generated clients and docs stay in sync. Production default is
+      49117; local dev commonly runs on 49118.
+    variables:
+      port:
+        default: '49117'
+        description: Express server port (set via SERVER_PORT or PORT env var)
+
+tags:
+  - name: Tools
+    description: |
+      CRUD operations for custom tool management.
+
+      Tools are stored in `~/.aglit-ai/tools/<tool-id>/` with implementation files
+      and metadata. Use `/system/write-tool-file` to upload scripts after creating
+      the tool record.
+  - name: Execution
+    description: |
+      Execute tools via JSON-RPC endpoint.
+
+      The same endpoint powers the Tool Test modal and agent invocations.
+      Provide `sessionId` in context to group logs.
+  - name: Files
+    description: |
+      Read and write tool implementation files.
+
+      Files are sandboxed to the tool directory. The backend rejects writes
+      that escape the sandbox.
+
+paths:
+  /user/tools:
+    get:
+      operationId: listTools
+      summary: List all tools
+      description: |
+        Returns first-party and custom tools available to the current user.
+        Use this to discover tool IDs for execution or management.
+      tags: [Tools]
+      responses:
+        '200':
+          description: List of tools
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tools:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ToolSummary'
+                  total:
+                    type: integer
+                    description: Total number of tools
+              example:
+                tools:
+                  - id: "custom-tool-abc123"
+                    name: "S3 Log Archiver"
+                    description: "Archives logs to S3 bucket"
+                    categories: ["Shell", "AWS"]
+                    type: "script"
+                  - id: "p1_browser_session"
+                    name: "Browser Session"
+                    description: "Manage browser sessions and navigation"
+                    categories: ["Browser", "Automation"]
+                    type: "actions"
+                total: 2
+
+    post:
+      operationId: createTool
+      summary: Create a custom tool
+      description: |
+        Creates a new custom tool record. After creation, use `/system/write-tool-file`
+        to upload implementation files to `~/.aglit-ai/tools/<tool-id>/`.
+
+        The tool directory is initialized as a git repository for version tracking.
+      tags: [Tools]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateToolRequest'
+            examples:
+              shellTool:
+                summary: Shell script tool
+                value:
+                  tool:
+                    name: "Log Archiver"
+                    description: "Archives and compresses logs to S3"
+                    categories: ["Shell", "AWS"]
+                    type: "script"
+                    providerId: "custom"
+                    inputSchema:
+                      type: object
+                      properties:
+                        bucket:
+                          type: string
+                          description: S3 bucket name
+                        days:
+                          type: integer
+                          minimum: 1
+                          description: Retention window in days
+                      required: ["bucket"]
+                    outputSchema:
+                      type: object
+                      properties:
+                        filesArchived:
+                          type: integer
+                          description: Number of files archived
+                        totalBytes:
+                          type: integer
+                          description: Total bytes uploaded
+                        archiveUrl:
+                          type: string
+                          description: S3 URL of the archive
+                      required: ["filesArchived", "totalBytes"]
+                    body:
+                      kind: "code"
+                      filePath: "main.sh"
+                      language: "bash"
+                      documentation: "Uploads logs older than N days to S3"
+                  testCases: []
+              browserTool:
+                summary: Browser automation tool
+                value:
+                  tool:
+                    name: "Screenshot Page"
+                    description: "Captures full-page screenshot of a URL"
+                    categories: ["Browser", "Automation"]
+                    type: "actions"
+                    providerId: "custom"
+                    inputSchema:
+                      type: object
+                      properties:
+                        url:
+                          type: string
+                          description: URL to screenshot
+                        fullPage:
+                          type: boolean
+                          default: true
+                          description: Capture full scrollable page
+                      required: ["url"]
+                    outputSchema:
+                      type: object
+                      properties:
+                        windowId:
+                          type: string
+                          description: Browser session ID
+                        screenshotPath:
+                          type: string
+                          description: Path to screenshot file
+                        title:
+                          type: string
+                          description: Page title
+                      required: ["windowId", "screenshotPath"]
+                  testCases: []
+      responses:
+        '200':
+          description: Tool created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolRecord'
+        '400':
+          description: Invalid tool configuration
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /user/tools/{toolId}:
+    parameters:
+      - name: toolId
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Tool identifier
+        example: "{{toolId}}"
+
+    put:
+      operationId: updateTool
+      summary: Update tool metadata and schemas
+      description: |
+        Updates an existing tool's metadata, schemas, or security settings.
+        Creates a new git commit for version tracking.
+
+        Pair with `/system/write-tool-file` when implementation changes.
+      tags: [Tools]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateToolRequest'
+            example:
+              tool:
+                id: "{{toolId}}"
+                name: "Log Archiver v2"
+                description: "Archives, compresses, and encrypts logs to S3"
+                categories: ["Shell", "AWS", "Security"]
+                type: "script"
+                providerId: "custom"
+                inputSchema:
+                  type: object
+                  properties:
+                    bucket:
+                      type: string
+                      description: S3 bucket name
+                    days:
+                      type: integer
+                      minimum: 1
+                      description: Retention window
+                    encrypt:
+                      type: boolean
+                      default: false
+                      description: Enable AES-256 encryption
+                  required: ["bucket"]
+                outputSchema:
+                  type: object
+                  properties:
+                    filesArchived:
+                      type: integer
+                    totalBytes:
+                      type: integer
+                    archiveUrl:
+                      type: string
+                    encrypted:
+                      type: boolean
+                  required: ["filesArchived"]
+                body:
+                  kind: "code"
+                  filePath: "main.sh"
+                  language: "bash"
+                  documentation: "Updated with encryption support"
+              testCases: []
+      responses:
+        '200':
+          description: Tool updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolRecord'
+        '404':
+          description: Tool not found
+
+    delete:
+      operationId: deleteTool
+      summary: Delete tool or version
+      description: |
+        Deletes a tool entirely or removes a specific version.
+
+        - Without `version` query param: Deletes entire tool directory and git history
+        - With `version=N`: Removes only that historical revision
+      tags: [Tools]
+      parameters:
+        - name: version
+          in: query
+          schema:
+            type: integer
+          description: Specific version to delete (omit to delete entire tool)
+      responses:
+        '200':
+          description: Tool or version deleted
+        '404':
+          description: Tool or version not found
+
+  /agents/{agentId}/tools/execute:
+    parameters:
+      - name: agentId
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Agent executing the tool
+        example: "root-agent"
+
+    post:
+      operationId: executeTool
+      summary: Execute a tool via JSON-RPC
+      description: |
+        Executes any available tool (first-party or custom) via JSON-RPC 2.0.
+
+        This is the same endpoint used by the Tool Test modal and agent invocations.
+        The response `result` field contains the tool's output matching its `outputSchema`.
+
+        ### Context
+
+        Provide `sessionId` in the `context` object to group logs and associate
+        the execution with a conversation session.
+
+        ### Environment Variables
+
+        Custom tools receive these environment variables in `main.sh`:
+
+        | Variable | Description |
+        |----------|-------------|
+        | `AGLIT_AGENT_ID` | Agent executing the tool |
+        | `AGLIT_SESSION_ID` | Session ID for log grouping |
+        | `AGLIT_SERVER_PORT` | Express server port |
+        | `AGLIT_API_URL` | Full API base URL |
+        | `AGLIT_TOOL_ID` | Current tool's ID |
+        | `AGLIT_TOOL_DIR` | Path to tool directory |
+      tags: [Execution]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ToolExecutionRequest'
+            examples:
+              shellTool:
+                summary: Execute shell tool
+                value:
+                  jsonrpc: "2.0"
+                  id: "exec-001"
+                  params:
+                    name: "p1_system"
+                    arguments:
+                      action: "speak"
+                      text: "Hello from the API docs"
+                      x_aglit_ai_tool_reason: "Docs demo: speak text"
+                  context:
+                    sessionId: "session-xyz"
+                    agentId: "root-agent"
+                  _meta:
+                    sessionId: "session-xyz"
+                    conversationSessionId: "session-xyz"
+                    stream: false
+              toolInvocationTemplate:
+                summary: Execute any tool (template)
+                value:
+                  jsonrpc: "2.0"
+                  id: "exec-template"
+                  params:
+                    name: "{{toolName}}"
+                    arguments:
+                      x_aglit_ai_tool_reason: "Docs example execution"
+                  context:
+                    sessionId: "docs-session"
+                    agentId: "root-agent"
+                  _meta:
+                    sessionId: "docs-session"
+              terminalApprovalWithImage:
+                summary: Request approval for an opaque terminal deployment with visual context
+                value:
+                  jsonrpc: "2.0"
+                  id: "deploy-mobile"
+                  params:
+                    name: "p1_terminal"
+                    arguments:
+                      action: "type"
+                      text: "pnpm --filter @aglit-ai/mobile-app run deploy:testflight"
+                      submit_command: true
+                      x_aglit_ai_tool_reason: "Deploy the new mobile app to TestFlight"
+                      x_aglit_ai_approval_request: "Can I deploy the new mobile app?"
+                      x_aglit_ai_tool_approval_image: "/session-assets/root-agent/docs-session/proofs/mobile-current.png"
+                  context:
+                    sessionId: "docs-session"
+                    agentId: "root-agent"
+              createChat:
+                summary: Create a chat session via tool execution
+                value:
+                  jsonrpc: "2.0"
+                  id: "exec-create-chat"
+                  params:
+                    name: "p1_system_create_chat"
+                    arguments:
+                      initial_text: "Spin up a chat that triages my PagerDuty incidents."
+                      agent_id: "root-agent"
+                      context: "You are the hidden incident orchestration guide."
+                      x_aglit_ai_tool_reason: "Docs example: create chat"
+                  context:
+                    sessionId: "docs-session"
+                    agentId: "root-agent"
+                  _meta:
+                    sessionId: "docs-session"
+              followUpChat:
+                summary: Send a follow-up message via tool execution
+                value:
+                  jsonrpc: "2.0"
+                  id: "exec-follow-up"
+                  params:
+                    name: "p1_system_send_follow_up_chat"
+                    arguments:
+                      follow_up_text: "Summarize any open incidents."
+                      agent_id: "root-agent"
+                      session_id: "{{sessionId}}"
+                      history_limit: 20
+                      x_aglit_ai_tool_reason: "Docs example: follow-up chat"
+                  context:
+                    sessionId: "docs-session"
+                    agentId: "root-agent"
+                  _meta:
+                    sessionId: "docs-session"
+              browserTool:
+                summary: Execute browser tool
+                value:
+                  jsonrpc: "2.0"
+                  id: "exec-002"
+                  params:
+                    name: "p1_browser_session"
+                    arguments:
+                      operation: "navigate"
+                      url: "https://example.com"
+                      x_aglit_ai_tool_reason: "Load example page"
+                  context:
+                    sessionId: "session-xyz"
+                    agentId: "root-agent"
+                  _meta:
+                    sessionId: "session-xyz"
+                    stream: false
+      responses:
+        '200':
+          description: Tool executed successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolExecutionResponse'
+              examples:
+                shellToolResult:
+                  summary: Shell tool result
+                  value:
+                    jsonrpc: "2.0"
+                    id: "exec-001"
+                    result:
+                      filesArchived: 42
+                      totalBytes: 1048576
+                      archiveUrl: "s3://my-logs-bucket/archive-2024-01-15.tar.gz"
+                browserToolResult:
+                  summary: Browser tool result
+                  value:
+                    jsonrpc: "2.0"
+                    id: "exec-002"
+                    result:
+                      windowId: "browser-session-abc"
+                      url: "https://example.com"
+                      title: "Example Domain"
+                      capturePath: "/path/to/captures/session-xyz"
+                      screenshotPath: "/path/to/captures/session-xyz/screenshot.png"
+                      traceZipPath: "/path/to/captures/session-xyz/trace-001.zip"
+                toolError:
+                  summary: Tool execution error
+                  value:
+                    jsonrpc: "2.0"
+                    id: "exec-001"
+                    error:
+                      code: -32000
+                      message: "Tool execution failed: S3 bucket not found"
+
+  /system/write-tool-file:
+    post:
+      operationId: writeToolFile
+      summary: Write implementation file
+      description: |
+        Writes a file to the tool's directory (`~/.aglit-ai/tools/<tool-id>/`).
+
+        Files are sandboxed - the backend rejects paths that escape the tool directory.
+        Set `makeExecutable: true` for scripts that need execute permission.
+      tags: [Files]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WriteFileRequest'
+            example:
+              toolId: "{{toolId}}"
+              filePath: "main.sh"
+              content: |
+                #!/bin/bash
+                set -euo pipefail
+
+                BUCKET="$1"
+                DAYS="${2:-7}"
+
+                # Archive logs older than N days
+                find /var/log -mtime +$DAYS -type f | while read f; do
+                  aws s3 cp "$f" "s3://$BUCKET/$(basename $f)"
+                done
+
+                echo '{"filesArchived": 42, "totalBytes": 1048576}'
+              makeExecutable: true
+      responses:
+        '200':
+          description: File written successfully
+        '400':
+          description: Invalid path or content
+        '403':
+          description: Path escapes tool directory sandbox
+
+  /system/read-tool-file:
+    post:
+      operationId: readToolFile
+      summary: Read implementation file
+      description: |
+        Reads a file from the tool's directory.
+
+        Use this to fetch existing implementation files for editing.
+      tags: [Files]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReadFileRequest'
+            example:
+              toolId: "custom-tool-abc123"
+              filePath: "main.sh"
+      responses:
+        '200':
+          description: File content
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                    description: File contents
+                  path:
+                    type: string
+                    description: Absolute path to file
+        '404':
+          description: File not found
+
+components:
+  schemas:
+    # ============================================================
+    # Tool Configuration Schemas
+    # ============================================================
+
+    ToolSummary:
+      type: object
+      description: Brief tool information for listing
+      properties:
+        id:
+          type: string
+          description: Unique tool identifier
+        name:
+          type: string
+          description: Display name
+        description:
+          type: string
+          description: Brief description of tool behavior
+        appId:
+          type: string
+          description: Optional app bundle ID this tool targets
+        website:
+          type: string
+          description: Optional website domain this tool targets
+        categories:
+          type: array
+          items:
+            type: string
+          description: Tool categories (Shell, Browser, API, etc.)
+        sampleUtterances:
+          type: array
+          items:
+            type: string
+          description: Example phrases used to improve tool recommendation relevance
+        type:
+          type: string
+          enum: [script, actions]
+          description: Implementation type
+      required: [id, name, type]
+
+    ToolRecord:
+      type: object
+      description: |
+        Complete tool configuration record.
+
+        This is the full tool metadata stored in the system, including
+        input/output schemas, security settings, and implementation details.
+      allOf:
+        - $ref: '#/components/schemas/ToolSummary'
+        - type: object
+          properties:
+            providerId:
+              type: string
+              description: Provider that owns this tool (custom, system, mcp-*)
+            inputSchema:
+              $ref: '#/components/schemas/ToolInputSchema'
+            outputSchema:
+              $ref: '#/components/schemas/ToolOutputSchema'
+            body:
+              $ref: '#/components/schemas/ToolBody'
+            security:
+              $ref: '#/components/schemas/ToolSecurity'
+            commitId:
+              type: string
+              description: Git commit SHA for version tracking
+            createdAt:
+              type: string
+              format: date-time
+            updatedAt:
+              type: string
+              format: date-time
+
+    CreateToolRequest:
+      type: object
+      description: Request body for creating a new tool
+      properties:
+        tool:
+          type: object
+          properties:
+            name:
+              type: string
+              description: Display name for the tool
+            description:
+              type: string
+              description: Detailed explanation of tool behavior
+            appId:
+              type: string
+              description: Optional app bundle ID this tool targets
+            website:
+              type: string
+              description: Optional website domain this tool targets
+            categories:
+              type: array
+              items:
+                type: string
+              minItems: 1
+              description: Tool categories (Shell, Browser, API, etc.)
+            sampleUtterances:
+              type: array
+              items:
+                type: string
+              description: Example phrases used to improve tool recommendation relevance
+            type:
+              type: string
+              enum: [script, actions]
+              description: |
+                Implementation style:
+                - `script`: Shell/Python/Node scripts executed via main.sh
+                - `actions`: Browser or desktop workflows via main.actions
+            providerId:
+              type: string
+              default: custom
+              description: Provider identifier (use "custom" for user-created tools)
+            inputSchema:
+              $ref: '#/components/schemas/ToolInputSchema'
+            outputSchema:
+              $ref: '#/components/schemas/ToolOutputSchema'
+            body:
+              $ref: '#/components/schemas/ToolBody'
+            security:
+              $ref: '#/components/schemas/ToolSecurity'
+          required: [name, description, categories, type, inputSchema, outputSchema]
+        testCases:
+          type: array
+          items:
+            $ref: '#/components/schemas/ToolTestCase'
+          description: Optional test cases for the tool
+      required: [tool]
+
+    UpdateToolRequest:
+      type: object
+      description: Request body for updating an existing tool
+      properties:
+        tool:
+          type: object
+          properties:
+            id:
+              type: string
+              description: Tool identifier (must match path parameter)
+            name:
+              type: string
+            description:
+              type: string
+            appId:
+              type: string
+              description: Optional app bundle ID this tool targets
+            website:
+              type: string
+              description: Optional website domain this tool targets
+            categories:
+              type: array
+              items:
+                type: string
+            sampleUtterances:
+              type: array
+              items:
+                type: string
+            type:
+              type: string
+              enum: [script, actions]
+            providerId:
+              type: string
+            inputSchema:
+              $ref: '#/components/schemas/ToolInputSchema'
+            outputSchema:
+              $ref: '#/components/schemas/ToolOutputSchema'
+            body:
+              $ref: '#/components/schemas/ToolBody'
+            security:
+              $ref: '#/components/schemas/ToolSecurity'
+          required: [id]
+        testCases:
+          type: array
+          items:
+            $ref: '#/components/schemas/ToolTestCase'
+      required: [tool]
+
+    # ============================================================
+    # Schema Definitions
+    # ============================================================
+
+    ToolInputSchema:
+      type: object
+      description: |
+        JSON Schema describing tool input parameters.
+
+        These appear as form fields in the Tool Test modal and are passed
+        as `arguments` during tool invocation.
+      properties:
+        type:
+          type: string
+          const: object
+          description: Input schema root must be object type
+        properties:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/ParameterSchema'
+          description: Map of parameter names to their schemas
+        required:
+          type: array
+          items:
+            type: string
+          description: List of required parameter names
+        additionalProperties:
+          type: boolean
+          default: false
+      required: [type, properties]
+      example:
+        type: object
+        properties:
+          bucket:
+            type: string
+            description: S3 bucket name
+          days:
+            type: integer
+            minimum: 1
+            description: Retention window in days
+        required: ["bucket"]
+
+    ToolOutputSchema:
+      type: object
+      description: |
+        JSON Schema describing the tool's return value.
+
+        Agents use this to parse results and chain outputs into subsequent
+        tool calls. The schema is validated at runtime.
+
+        ### Common Patterns
+
+        | Pattern | Use Case | Example |
+        |---------|----------|---------|
+        | Single value | Transformations | `{ result: string }` |
+        | List result | Search/discovery | `{ items: [], total: number }` |
+        | Resource reference | Sessions | `{ windowId, screenshotPath }` |
+        | Status report | Operations | `{ success, message, duration }` |
+      properties:
+        type:
+          type: string
+          const: object
+          description: Output schema root must be object type
+        description:
+          type: string
+          description: Human-readable description of the output
+        properties:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/ParameterSchema'
+          description: Map of output field names to their schemas
+        required:
+          type: array
+          items:
+            type: string
+          description: Fields always present in output
+      required: [type, properties]
+      example:
+        type: object
+        properties:
+          filesArchived:
+            type: integer
+            description: Number of files archived
+          totalBytes:
+            type: integer
+            description: Total bytes uploaded
+          archiveUrl:
+            type: string
+            description: S3 URL of the archive
+        required: ["filesArchived", "totalBytes"]
+
+    ParameterSchema:
+      type: object
+      description: JSON Schema definition for a single parameter or output field
+      properties:
+        type:
+          type: string
+          enum: [string, number, integer, boolean, array, object]
+          description: JSON type
+        description:
+          type: string
+          description: Human-readable description shown in UI and to agents
+        default:
+          description: Default value if not provided
+        enum:
+          type: array
+          description: Allowed values
+        minimum:
+          type: number
+          description: Minimum value (number/integer)
+        maximum:
+          type: number
+          description: Maximum value (number/integer)
+        minLength:
+          type: integer
+          description: Minimum length (string)
+        maxLength:
+          type: integer
+          description: Maximum length (string)
+        pattern:
+          type: string
+          description: Regex pattern (string)
+        items:
+          $ref: '#/components/schemas/ParameterSchema'
+          description: Schema for array items
+        properties:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/ParameterSchema'
+          description: Nested properties (object)
+        required:
+          type: array
+          items:
+            type: string
+          description: Required properties (object)
+      required: [type]
+
+    # ============================================================
+    # Tool Implementation
+    # ============================================================
+
+    ToolBody:
+      type: object
+      description: Tool implementation details
+      properties:
+        kind:
+          type: string
+          enum: [code]
+          description: Implementation kind (currently only "code" supported)
+        filePath:
+          type: string
+          description: Entry point file relative to tool directory
+          default: main.sh
+          examples:
+            - main.sh
+            - main.py
+            - index.js
+        language:
+          type: string
+          enum: [bash, python, node, sh, zsh]
+          description: Script language
+          default: bash
+        documentation:
+          type: string
+          description: Implementation notes shown in UI
+      required: [kind, filePath, language]
+
+    ToolSecurity:
+      type: object
+      description: |
+        Security configuration for tool execution.
+
+        Browser profiles control browser configuration. Terminal execution uses the managed VM.
+      additionalProperties: false
+      properties:
+        browserProfileId:
+          type: string
+          description: |
+            Browser profile controlling:
+            - Cookie and storage isolation
+            - Security sandbox settings
+            - Default browser preferences
+    ToolTestCase:
+      type: object
+      description: Test case for validating tool behavior
+      properties:
+        name:
+          type: string
+          description: Test case name
+        input:
+          type: object
+          description: Input arguments to pass
+        expectedOutput:
+          type: object
+          description: Expected output (partial match)
+        timeout:
+          type: integer
+          description: Timeout in milliseconds
+
+    # ============================================================
+    # Execution Schemas
+    # ============================================================
+
+    ToolExecutionRequest:
+      type: object
+      description: JSON-RPC 2.0 request for tool execution
+      properties:
+        jsonrpc:
+          type: string
+          const: "2.0"
+        id:
+          type: string
+          description: Request identifier for correlation
+        method:
+          type: string
+          const: tools/call
+        params:
+          type: object
+          properties:
+            name:
+              type: string
+              description: Tool ID to execute
+            arguments:
+              type: object
+              description: |
+                Tool arguments matching the tool's `inputSchema`.
+
+                Include `x_aglit_ai_tool_reason` to annotate why the tool is being called. This field is required for auditability and must clearly state what specific action is being performed. Never use generic phrases like "Using a tool" - always describe the actual purpose.
+              properties:
+                x_aglit_ai_tool_reason:
+                  type: string
+                  description: A concise, specific description of what this tool call will accomplish. Describe the actual action and purpose, not just "Using a tool". Examples - "Searching for Journal pages in Notion", "Navigating to news.yahoo.com to find today's headlines", "Reading the user's calendar events for today".
+                x_aglit_ai_tool_approval_image:
+                  type: string
+                  description: Optional contextual image that should reference a recent, nonblank, existing /session-assets/<agentId>/<sessionId>/... image from the exact executing agent/session. Strongly recommended when it helps the user understand the action, especially in phone notifications, but omission never blocks creation of the approval. When valid, it is shown above the normal approval preview and attached to mobile approval notifications.
+              required: [x_aglit_ai_tool_reason]
+              additionalProperties: true
+          required: [name, arguments]
+        context:
+          type: object
+          description: Execution context
+          properties:
+            sessionId:
+              type: string
+              description: Session ID for log grouping
+            agentId:
+              type: string
+              description: Agent executing the tool
+        _meta:
+          type: object
+          description: Internal metadata
+          properties:
+            sessionId:
+              type: string
+            conversationSessionId:
+              type: string
+            stream:
+              type: boolean
+              description: Enable streaming responses
+      required: [jsonrpc, id, method, params]
+
+    ToolExecutionResponse:
+      type: object
+      description: |
+        JSON-RPC 2.0 response from tool execution.
+
+        The `result` field contains the tool's output matching its `outputSchema`.
+        For errors, the `error` field contains details.
+      properties:
+        jsonrpc:
+          type: string
+          const: "2.0"
+        id:
+          type: string
+          description: Request identifier (echoed from request)
+        result:
+          type: object
+          description: |
+            Tool output matching the tool's `outputSchema`.
+
+            For browser tools, commonly includes:
+            - `windowId`: Session identifier
+            - `url`, `title`: Page information
+            - `screenshotPath`, `capturePath`: Artifact paths
+            - `traceZipPath`: Playwright trace
+
+            For shell tools, contains the JSON output from stdout.
+        error:
+          $ref: '#/components/schemas/JsonRpcError'
+
+    JsonRpcError:
+      type: object
+      description: JSON-RPC 2.0 error object
+      properties:
+        code:
+          type: integer
+          description: Error code (-32000 for tool errors)
+        message:
+          type: string
+          description: Human-readable error message
+        data:
+          type: object
+          description: Additional error details
+
+    # ============================================================
+    # File Operations
+    # ============================================================
+
+    WriteFileRequest:
+      type: object
+      properties:
+        toolId:
+          type: string
+          description: Tool identifier
+        filePath:
+          type: string
+          description: |
+            File path relative to tool directory.
+            Cannot escape the tool directory sandbox.
+        content:
+          type: string
+          description: File content to write
+        makeExecutable:
+          type: boolean
+          default: false
+          description: Set executable permission (for scripts)
+      required: [toolId, filePath, content]
+
+    ReadFileRequest:
+      type: object
+      properties:
+        toolId:
+          type: string
+          description: Tool identifier
+        filePath:
+          type: string
+          description: File path relative to tool directory
+      required: [toolId, filePath]
+
+    ErrorResponse:
+      type: object
+      properties:
+        error:
+          type: string
+          description: Error message
+        code:
+          type: string
+          description: Error code
+        details:
+          type: object
+          description: Additional error details
+
+  # ============================================================
+  # Tool-Type Specific Output Schemas (for reference)
+  # ============================================================
+
+  x-output-schema-patterns:
+    description: |
+      Common output schema patterns for different tool types.
+      Reference these when defining `outputSchema` for custom tools.
+
+    shellToolOutput:
+      description: |
+        Shell tools should output JSON to stdout. Common patterns:
+      examples:
+        - name: File Processing
+          schema:
+            type: object
+            properties:
+              processedFiles:
+                type: integer
+                description: Number of files processed
+              outputPath:
+                type: string
+                description: Path to generated output
+              errors:
+                type: array
+                items:
+                  type: string
+                description: Files that failed
+            required: [processedFiles]
+
+        - name: API Call
+          schema:
+            type: object
+            properties:
+              statusCode:
+                type: integer
+              body:
+                type: object
+              headers:
+                type: object
+            required: [statusCode, body]
+
+        - name: Data Transformation
+          schema:
+            type: object
+            properties:
+              inputRows:
+                type: integer
+              outputRows:
+                type: integer
+              transformations:
+                type: array
+                items:
+                  type: string
+            required: [inputRows, outputRows]
+
+    browserToolOutput:
+      description: |
+        Browser tools return session references and capture artifacts.
+      examples:
+        - name: Navigation
+          schema:
+            type: object
+            properties:
+              windowId:
+                type: string
+                description: Browser session ID for subsequent operations
+              url:
+                type: string
+                description: Current page URL
+              title:
+                type: string
+                description: Page title
+              capturePath:
+                type: string
+                description: Directory with capture files
+              screenshotPath:
+                type: string
+                description: Path to screenshot
+              traceZipPath:
+                type: string
+                description: Playwright trace ZIP (network, DOM, actions)
+              consoleLogsPath:
+                type: string
+                description: Browser console JSON
+            required: [windowId, url]
+
+        - name: JavaScript Execution
+          schema:
+            type: object
+            properties:
+              result:
+                description: Return value from script
+              consoleOutput:
+                type: array
+                items:
+                  type: string
+              error:
+                type: string
+            required: [result]
+
+        - name: Tab Listing
+          schema:
+            type: object
+            properties:
+              tabs:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    index:
+                      type: integer
+                    title:
+                      type: string
+                    url:
+                      type: string
+                    active:
+                      type: boolean
+              activeTabIndex:
+                type: integer
+            required: [tabs]
+
+    desktopAppToolOutput:
+      description: |
+        Desktop app tools return window references and accessibility data.
+      examples:
+        - name: View Application
+          schema:
+            type: object
+            properties:
+              appName:
+                type: string
+              appId:
+                type: string
+                description: Bundle ID (e.g., com.apple.reminders)
+              windows:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    windowId:
+                      type: string
+                    title:
+                      type: string
+                    bounds:
+                      type: object
+                      properties:
+                        x:
+                          type: number
+                        y:
+                          type: number
+                        width:
+                          type: number
+                        height:
+                          type: number
+                    screenshotPath:
+                      type: string
+              accessibilityTree:
+                type: object
+              scriptingInfo:
+                type: object
+            required: [appName, appId, windows]
+
+        - name: Click/Type Action
+          schema:
+            type: object
+            properties:
+              success:
+                type: boolean
+              x:
+                type: number
+              y:
+                type: number
+              screenshotPath:
+                type: string
+            required: [success]
+
+    mcpToolOutput:
+      description: |
+        MCP tools return provider-specific data wrapped in content blocks.
+      examples:
+        - name: Generic Content Blocks
+          schema:
+            type: object
+            properties:
+              content:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [text, image, resource]
+                    text:
+                      type: string
+                    data:
+                      type: string
+                      description: Base64-encoded
+                    mimeType:
+                      type: string
+              isError:
+                type: boolean
+            required: [content]
+
+        - name: Database Query (Notion, Airtable)
+          schema:
+            type: object
+            properties:
+              results:
+                type: array
+                items:
+                  type: object
+              hasMore:
+                type: boolean
+              nextCursor:
+                type: string
+            required: [results]
+
+    fileToolOutput:
+      description: |
+        File tools return operation results and file metadata.
+      examples:
+        - name: File View
+          schema:
+            type: object
+            properties:
+              content:
+                type: string
+                description: File contents (may be truncated)
+              isTruncated:
+                type: boolean
+                description: True if content was truncated
+              totalLines:
+                type: integer
+                description: Total line count
+              filePath:
+                type: string
+                description: Absolute path to file
+              mimeType:
+                type: string
+                description: Detected MIME type
+            required: [content, filePath]
+
+        - name: File Write/Update
+          schema:
+            type: object
+            properties:
+              success:
+                type: boolean
+              filePath:
+                type: string
+              bytesWritten:
+                type: integer
+              diff:
+                type: string
+                description: Unified diff for updates
+            required: [success, filePath]
+
+        - name: Image Analysis
+          schema:
+            type: object
+            properties:
+              analysis:
+                type: string
+                description: AI-generated analysis
+              boundingBoxes:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    label:
+                      type: string
+                    coordinates:
+                      type: object
+              filePath:
+                type: string
+            required: [analysis]
+
+    terminalToolOutput:
+      description: |
+        Terminal tools return session references and command output.
+      examples:
+        - name: Open Terminal
+          schema:
+            type: object
+            properties:
+              windowId:
+                type: string
+                description: Terminal session ID for subsequent operations
+              streamId:
+                type: string
+                description: Live stream ID
+              cwd:
+                type: string
+                description: Current working directory
+            required: [windowId]
+
+        - name: Type Command
+          schema:
+            type: object
+            properties:
+              windowId:
+                type: string
+              output:
+                type: string
+                description: Terminal output after command
+              exitCode:
+                type: integer
+                description: Command exit code (if available)
+            required: [windowId]
+
+        - name: View Terminal
+          schema:
+            type: object
+            properties:
+              windowId:
+                type: string
+              content:
+                type: string
+                description: Current terminal buffer content
+              rows:
+                type: integer
+              cols:
+                type: integer
+            required: [windowId, content]
+
+    appToolOutput:
+      description: |
+        App tools return application state and accessibility data.
+      examples:
+        - name: Calendar/Reminders Query
+          schema:
+            type: object
+            properties:
+              items:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    title:
+                      type: string
+                    date:
+                      type: string
+              count:
+                type: integer
+            required: [items]
+
+        - name: Mail/Messages
+          schema:
+            type: object
+            properties:
+              messages:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    subject:
+                      type: string
+                    sender:
+                      type: string
+                    date:
+                      type: string
+              total:
+                type: integer
+            required: [messages]
+
+        - name: Contacts
+          schema:
+            type: object
+            properties:
+              contacts:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    name:
+                      type: string
+                    email:
+                      type: string
+                    phone:
+                      type: string
+            required: [contacts]
+
+    systemToolOutput:
+      description: |
+        System tools return configuration and management data.
+      examples:
+        - name: List Resources
+          schema:
+            type: object
+            properties:
+              items:
+                type: array
+                items:
+                  type: object
+              total:
+                type: integer
+              hasMore:
+                type: boolean
+            required: [items]
+
+        - name: Create/Update Resource
+          schema:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Created/updated resource ID
+              success:
+                type: boolean
+              message:
+                type: string
+            required: [id, success]
+
+        - name: Todo Management
+          schema:
+            type: object
+            properties:
+              todos:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    content:
+                      type: string
+                    status:
+                      type: string
+                      enum: [pending, in_progress, completed]
+              pending:
+                type: integer
+              completed:
+                type: integer
+            required: [todos]
+
+        - name: Publish Public Chat
+          description: Publish an agent's public chat to make it accessible via a public URL
+          schema:
+            type: object
+            properties:
+              agentId:
+                type: string
+                description: Agent ID
+              publicChatUrl:
+                type: string
+                description: Public chat URL that can be shared
+              tunnelUrl:
+                type: string
+                description: Tunnel URL for the public chat
+              status:
+                type: string
+                enum: [published]
+            required: [agentId, publicChatUrl, status]
+
+        - name: Unpublish Public Chat
+          description: Unpublish an agent's public chat to disable external access
+          schema:
+            type: object
+            properties:
+              agentId:
+                type: string
+                description: Agent ID
+              status:
+                type: string
+                enum: [unpublished]
+            required: [agentId, status]
+
+        - name: Create API Key
+          description: Create a new API key for an agent
+          schema:
+            type: object
+            properties:
+              agentId:
+                type: string
+                description: Agent ID
+              keyId:
+                type: string
+                description: Unique key identifier
+              name:
+                type: string
+                description: Descriptive name for the API key
+              key:
+                type: string
+                description: The API key value (only shown once)
+              createdAt:
+                type: string
+                format: date-time
+                description: When the key was created
+            required: [agentId, keyId, name, key, createdAt]
+
+    codeDebuggerToolOutput:
+      description: |
+        Code debugger tools return debugging state and execution data.
+      examples:
+        - name: Breakpoint Operation
+          schema:
+            type: object
+            properties:
+              breakpointId:
+                type: string
+              file:
+                type: string
+              line:
+                type: integer
+              verified:
+                type: boolean
+            required: [breakpointId]
+
+        - name: Call Stack
+          schema:
+            type: object
+            properties:
+              frames:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: integer
+                    name:
+                      type: string
+                    file:
+                      type: string
+                    line:
+                      type: integer
+                    column:
+                      type: integer
+              threadId:
+                type: integer
+            required: [frames]
+
+        - name: Evaluate Expression
+          schema:
+            type: object
+            properties:
+              result:
+                type: string
+                description: Evaluated value
+              type:
+                type: string
+                description: Value type
+              variablesReference:
+                type: integer
+                description: Reference for nested inspection
+            required: [result]