Tool System

-- System.Agents.Media.Types
data MediaType
    = MediaImage ImageType
    | MediaAudio AudioType
    | MediaVideo VideoType
    | MediaApplication ApplicationType
    | MediaText TextSubtype

data ImageType = ImagePNG | ImageJPEG | ImageGIF | ImageWebP | ImageSVG
data AudioType = AudioMPEG | AudioWAV | AudioOGG | AudioMP3 | AudioAAC | AudioFLAC
data VideoType = VideoMP4 | VideoWebM | VideoOGG | VideoAVI | VideoMOV
data ApplicationType = AppPDF | AppJSON | AppXML | AppOctetStream | AppZip
data TextSubtype = TextPlain | TextHTML | TextCSS | TextCSV | TextMarkdown

data MediaAttachment = MediaAttachment
    { mediaMimeType :: Text        -- e.g., "image/png"
    , mediaBase64Data :: Text      -- Base64-encoded content
    , mediaFilename :: Maybe Text  -- Optional filename
    }

data ContentPart
    = TextPart Text
    | MediaPart MediaAttachment

#!/bin/bash

if [ "$1" == "describe" ]; then
    echo '{
        "slug": "generate_chart",
        "description": "Generates a chart image",
        "args": [...],
        "output-media-type": "image/png"
    }'
    exit 0
fi

# Generate and output PNG image to stdout
./generate-chart "$@"

data CallResult call
    = -- | Successful execution with optional media type hint
      BlobToolSuccess call ByteString (Maybe MediaType)
    | -- ... other constructors

data UserToolResponse
    = TextResponse Text                    -- Plain UTF-8 text
    | JsonResponse Aeson.Value             -- Structured JSON data
    | MediaResponse MediaAttachment        -- Single binary media
    | MixedResponse [ContentPart]          -- Multi-modal content

data ToolRegistration = ToolRegistration
    { innerTool :: Tool ()
    , declareTool :: OpenAI.Tool
    , findTool :: OpenAI.ToolCall -> Maybe (Tool OpenAI.ToolCall)
    }

#!/bin/bash

if [ "$1" == "describe" ]; then
    echo '{
        "slug": "my-tool",
        "description": "What this tool does",
        "args": [
            {
                "name": "input",
                "description": "Input parameter",
                "type": "string",
                "backing_type": "string",
                "arity": "single",
                "mode": "dashdashspace"
            }
        ],
        "empty-result": {"tag": "AddMessage", "contents": "No results"}
    }'
    exit 0
fi

# Main execution
input="$1"
echo "Result for: $input"

data ScriptInfo = ScriptInfo
    { scriptArgs :: [ScriptArg]
    , scriptSlug :: Text
    , scriptDescription :: Text
    , scriptEmptyResultBehavior :: Maybe EmptyResultBehavior
    , scriptOutputMediaType :: Maybe Text  -- NEW: Media type for binary output
    }

data ScriptArg = ScriptArg
    { argName :: Text
    , argDescription :: Text
    , argType :: Text
    , argBackingType :: Text
    , argArity :: Text  -- "single", "optional", "multiple"
    , argMode :: Text   -- "dashdashspace", "space", etc.
    }

data Toolbox = Toolbox
    { tools :: BackgroundVal [ToolRegistration]
    , triggerReload :: STM Bool
    }

initializeBackroundToolbox :: 
    Tracer IO Trace -> 
    FilePath -> 
    IO (Either ToolboxError Toolbox)

data McpServerDescription
    = McpSimpleBinary McpSimpleBinaryConfiguration
    
data McpSimpleBinaryConfiguration = McpSimpleBinaryConfiguration
    { name :: Text
    , executable :: FilePath
    , args :: [Text]
    }

data Runtime = Runtime
    { procHandle :: ProcessHandle
    , stdinHandle :: Handle
    , stdoutHandle :: Handle
    , toolsList :: TVar [ToolDescription]
    , callResults :: TVar (Map CallId Value)
    }

// Tool list request
{"jsonrpc": "2.0", "method": "tools/list", "id": 1}

// Tool list response
{"jsonrpc": "2.0", "result": 
  {"tools": [
    {"name": "read_file", 
     "description": "Read a file", 
     "inputSchema": {...}}
  ]}, 
  "id": 1}

// Tool call
{"jsonrpc": "2.0", 
 "method": "tools/call", 
 "params": {"name": "read_file", "arguments": {"path": "/tmp/foo"}},
 "id": 2}

{
  "mcpServers": [...],
  "openApiToolboxes": [
    {
      "tag": "OpenAPIServer",
      "contents": {
        "SpecUrl": "https://api.example.com/openapi.json",
        "BaseUrl": "https://api.example.com",
        "Headers": {"X-API-Version": "v1"},
        "Token": "${API_TOKEN}"
      }
    }
  ]
}

-- Load and parse OpenAPI spec
convertOpenAPIToTools :: OpenAPISpec -> [OpenAPITool]

-- Convert operation to tool
convertOperation :: Path -> Method -> Operation -> OpenAPITool

-- Build tool parameters from OpenAPI parameters
buildToolParameters :: Operation -> ToolParameters

-- Convert to OpenAI tool format
toOpenAITool :: OpenAPITool -> OpenAI.Tool

resolveSchema :: Schema -> Components -> Schema
dereferenceSpec :: OpenAPISpec -> OpenAPISpec

-- Original: "pets.getById"
-- Normalized: "pets_getById"

-- Original: "/users/{id}/posts"
-- Normalized: "_users__id__posts"

data NameMapping = NameMapping
    { nmOriginal :: Text
    , nmNormalized :: Text
    }

{
  "postgrestToolboxes": [
    {
      "tag": "PostgRESTServer",
      "contents": {
        "SpecUrl": "http://localhost:3000/",
        "BaseUrl": "http://localhost:3000"
      }
    }
  ]
}

{
  "filters": {
    "column_name": "filter_value"
  },
  "subset": {
    "limit": 10,
    "offset": 0,
    "columns": "id,name,email"
  },
  "ranking": {
    "order": "created_at.desc"
  },
  "body": {
    "name": "New Item",
    "value": 42
  }
}

{
  "builtinToolboxes": [
    {
      "tag": "SqliteToolbox",
      "contents": {
        "Name": "analytics",
        "Description": "Analytics database",
        "Versioning": {"tag": "SqliteReadOnly", "path": "./analytics.db"}
      }
    }
  ]
}

{
  "sql": "SELECT * FROM users WHERE active = 1 LIMIT 10"
}

data FileSandboxConfig = FileSandboxConfig
    { fsbPredicate :: PathPredicate     -- Defines allowed file paths
    , fsbMaxFileSize :: Maybe Integer   -- Max file size in bytes (Nothing = no limit)
    , fsbName :: Maybe Text             -- Human-readable name for the sandbox
    }

defaultFileSandboxConfig :: FileSandboxConfig
defaultFileSandboxConfig = FileSandboxConfig
    { fsbPredicate = AlwaysDeny          -- Deny all access by default
    , fsbMaxFileSize = Just (50 * 1024 * 1024)  -- 50MB default limit
    , fsbName = Nothing
    }

{
  "tag": "OpenAIAgentDescription",
  "contents": {
    "slug": "coder",
    "fileSandboxes": {
      "project": {
        "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "./src"},
        "fsbMaxFileSize": 10485760
      },
      "scratch": {
        "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "/tmp/scratch"}
      }
    },
    "builtinToolboxes": [
      {"tag": "DeveloperToolbox", "contents": {
        "Name": "dev", "Description": "Development tools",
        "Capabilities": ["read-file-range", "patch-file"],
        "FileSandbox": {"ref": "project"}}},
      {"tag": "LuaToolbox", "contents": {
        "Name": "lua", "Description": "Lua orchestration",
        "MaxMemoryMB": 256, "MaxExecutionTimeSeconds": 300,
        "AllowedTools": [], "AllowedHosts": [],
        "FileSandbox": {"ref": "project"}}},
      {"tag": "SystemToolbox", "contents": {
        "Name": "system", "Description": "System context",
        "Capabilities": ["attach-file"],
        "FileSandbox": {"ref": "scratch"}}}
    ]
  }
}

data PathPredicate
    = FileExactly FilePath              -- Exact file match
    | DirectoryExactly FilePath         -- Exact directory match (contents not included)
    | DirectoryRecursive FilePath       -- Directory and all subdirectories
    | DirectoryShallow FilePath         -- Directory contents only (not subdirectories)
    | FilePattern String                -- Glob pattern on filename (*, ? wildcards)
    | FileExtension [String]            -- File extension whitelist (no leading dot)
    | FileSizeLessThan Integer          -- Maximum file size in bytes
    | ChildOf FilePath                  -- Path within a parent directory
    | And PathPredicate PathPredicate   -- Logical AND
    | Or PathPredicate PathPredicate    -- Logical OR
    | Not PathPredicate                 -- Logical NOT
    | Any [PathPredicate]               -- OR of all predicates
    | All [PathPredicate]               -- AND of all predicates
    | AlwaysAllow                       -- Allow all (use sparingly)
    | AlwaysDeny                        -- Deny all (secure default)

{
  "fsbPredicate": {
    "tag": "Any",
    "contents": [
      {"tag": "DirectoryRecursive", "contents": "./src"},
      {"tag": "FileExactly", "contents": "./package.yaml"},
      {"tag": "FileExactly", "contents": "./README.md"}
    ]
  }
}

{
  "fsbPredicate": {
    "tag": "And",
    "contents": [
      {"tag": "DirectoryRecursive", "contents": "./src"},
      {"tag": "FileExtension", "contents": ["hs", "lhs"]},
      {"tag": "FileSizeLessThan", "contents": 1048576}
    ]
  }
}

{
  "fsbPredicate": {
    "tag": "And",
    "contents": [
      {"tag": "DirectoryRecursive", "contents": "./my-project"},
      {"tag": "Not", "contents": {"tag": "DirectoryRecursive", "contents": "./my-project/dist"}}
    ]
  }
}

{
  "fsbPredicate": {
    "tag": "Any",
    "contents": [
      {"tag": "FilePattern", "contents": "*.md"},
      {"tag": "FilePattern", "contents": "test-*.json"}
    ]
  }
}

{
  "builtinToolboxes": [
    {
      "tag": "SystemToolbox",
      "contents": {
        "Name": "system",
        "Description": "System context and information",
        "Capabilities": ["date", "operating-system", "running-user", "hostname", "attach-file", "list-directory", "execute-command"],
        "EnvVarFilter": null,
        "FileSandbox": {
          "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "./project"},
          "fsbMaxFileSize": 52428800,
          "fsbName": "system-sandbox"
        },
        "CommandFilter": "/path/to/approval-script.sh"
      }
    }
  ]
}

-- Tool accepts:
{
  "capability": "attach-file",
  "filepath": "/path/to/image.png"
}

-- Returns:
-- MediaAttachment with base64-encoded content

// Input:
{
  "capability": "list-directory",
  "path": "./src",
  "recursive": false,
  "include_hidden": false
}

// Output:
{
  "path": "./src",
  "entries": [
    {"name": "Main.hs", "type": "file", "size": 1234, "modified": "2024-01-15T10:30:00Z"},
    {"name": "Utils", "type": "directory", "size": 0, "modified": "2024-01-14T08:00:00Z"}
  ],
  "total": 2
}

// Input:
{
  "capability": "execute-command",
  "command": "ls -la"
}

// Output:
{
  "command": "ls -la",
  "exitCode": 0,
  "stdout": "...",
  "stderr": "",
  "duration": 0.123
}

// Allowed:
{"acceptance": "allowed", "note": "Safe command"}

// Refused:
{"acceptance": "refused", "note": "Command contains dangerous operations"}

{
  "tag": "SystemToolbox",
  "contents": {
    "Name": "system",
    "Description": "System information and session memory",
    "Capabilities": [
      "date",
      "hostname",
      "list-sessions",
      "search-sessions",
      "read-session",
      "get-session-stats"
    ],
    "SessionIntrospectionScope": "subtree",
    "SessionIntrospectionMaxResults": 50,
    "SessionIntrospectionIncludeToolOutputs": false
  }
}

{
  "capability": "list-sessions"
}

{
  "sessions": [
    {
      "sessionId": "uuid",
      "conversationId": "uuid",
      "modificationTime": "2024-01-15T10:30:00Z",
      "turnCount": 15,
      "isParent": false,
      "isChild": true,
      "isLocked": false,
      "status": "idle"
    }
  ],
  "totalAccessible": 42
}

{
  "capability": "search-sessions",
  "query": "error handling pattern"
}

{
  "query": "error handling pattern",
  "results": [
    {
      "sessionId": "uuid",
      "conversationId": "uuid",
      "turnCount": 15,
      "preview": "...context around match...",
      "matchType": "content"
    }
  ],
  "totalMatches": 5,
  "scope": "subtree"
}

{
  "capability": "read-session",
  "session_id": "target-session-uuid",
  "take_n": 10,
  "include_thinking": false,
  "include_tool_responses": true
}

{
  "sessionId": "target-session-uuid",
  "conversationId": "uuid",
  "totalTurns": 25,
  "returnedTurns": 10,
  "content": "Turn 1: [User] ...\nTurn 2: [LLM] ...",
  "format": "condensed-text",
  "scope": "subtree",
  "access": "granted"
}

{
  "capability": "get-session-stats"
}

{
  "totalSessions": 42,
  "totalTurnsAcrossAllSessions": 850,
  "scope": "subtree",
  "note": "Use SessionPrint.calculateStatistics for detailed per-session stats"
}

{
  "capability": "date"
}

{
  "capability": "date",
  "data": {
    "utc": "2024-01-15T10:30:00.123456Z",
    "local": "2024-01-15T11:30:00.123456",
    "timezone": "CET",
    "timezoneOffset": "+0100"
  },
  "executionTime": 0.001
}

{
  "builtinToolboxes": [
    {
      "tag": "DeveloperToolbox",
      "contents": {
        "Name": "dev",
        "Description": "Development utilities",
        "Capabilities": ["show-spec", "validate-agent", "create-agent", "create-tool", "read-file-range", "write-file-range", "patch-file"],
        "FileSandbox": {
          "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "./src"},
          "fsbMaxFileSize": null,
          "fsbName": "developer-sandbox"
        }
      }
    }
  ]
}

{
  "FileSandbox": {
    "fsbPredicate": {
      "tag": "Any",
      "contents": [
        {"tag": "DirectoryRecursive", "contents": "./src"},
        {"tag": "DirectoryRecursive", "contents": "./test"},
        {"tag": "FileExactly", "contents": "./package.yaml"}
      ]
    },
    "fsbMaxFileSize": 10485760
  }
}

{
  "capability": "show-spec",
  "spec_name": "bash-tools"
}

{
  "capability": "read-file-range",
  "path": "/path/to/file",
  "ranges": "1-10,20-30",
  "session_id": "sess-abc",
  "metadata_only": false
}

{
  "path": "/path/to/file",
  "content": "1\tdef hello():\n2\t    print('Hello, World!')\n3\t    return True\n",
  "linesRead": 3,
  "totalLineCount": 50,
  "totalFileSize": 1234,
  "rangesParsed": ["1-3"],
  "snapshotRef": "a1b2c3d4..."
}

{
  "path": "/path/to/file",
  "content": "",
  "linesRead": 0,
  "totalLineCount": 50,
  "totalFileSize": 1234,
  "rangesParsed": [],
  "snapshotRef": "a1b2c3d4...",
  "metadataOnly": true
}

{
  "capability": "read-file-range",
  "path": "./src/File.hs",
  "session_id": "sess-abc"
}

{
  "capability": "write-file-range",
  "path": "/path/to/file",
  "ranges": "1-2,5-6",
  "contentBlocks": ["new content for lines 1-2", "new content for lines 5-6"],
  "session_id": "sess-abc",
  "expected_snapshot_ref": "a1b2c3d4...",
  "commit": true
}

{
  "capability": "write-file-range",
  "path": "./src/File.hs",
  "ranges": "1-10",
  "contentBlocks": ["new content"],
  "expected_snapshot_ref": "a1b2c3d4...",
  "commit": true
}

{
  "path": "/path/to/file",
  "rangesModified": 2,
  "linesWritten": 6,
  "beforeSnapshotRef": "a1b2c3d4...",
  "afterSnapshotRef": "e5f6g7h8...",
  "sessionId": "sess-abc",
  "sessionNetDelta": 2,
  "sessionCommitted": true,
  "sessionStatus": "committed"
}

{
  "capability": "patch-file",
  "path": "/path/to/file",
  "patch": "--- a/src/File.hs\n+++ b/src/File.hs\n@@ -10,5 +10,6 @@ import Foo\n+import Data.Text (Text)\n@@ -100,5 +101,5 @@ func1 x =\n-  oldBody\n+  newBody",
  "expected_snapshot_ref": "a1b2c3d4..."
}

{
  "error": "Context mismatch at line 100",
  "expected": ["import Foo", "import Bar"],
  "actual": ["import Foo", "import Baz"],
  "message": "Context doesn't match"
}

{
  "path": "/path/to/file",
  "hunksApplied": 2,
  "hunksRejected": 0,
  "linesChanged": 3,
  "beforeSnapshotRef": "a1b2c3d4...",
  "afterSnapshotRef": "e5f6g7h8..."
}

{
  "error": "Context mismatch at line 100: Context doesn't match",
  "expected": ["context line 1", "context line 2"],
  "actual": ["different line 1", "different line 2"]
}

-- | Range specification for file operations.
data RangeSpec
    = Lines (Int, Int)  -- ^ 1-based, inclusive line range (start, end)
    | Head              -- ^ Before line 1 (prepend)
    | Tail              -- ^ After last line (append)
    deriving (Show, Eq)

-- | Result of a read file range operation.
data ReadFileRangeResult = ReadFileRangeResult
    { readFilePath :: FilePath
    , readFileContent :: Text
    , readFileLinesRead :: Int
    , readFileTotalLines :: Int
    , readFileTotalSize :: Int
    , readFileRangesParsed :: [Text]
    , readFileSnapshotRef :: Maybe SnapshotRef
    , readFileSessionId :: Maybe Text
    , readFileMetadataOnly :: Bool
    }

-- | Result of a write file range operation.
data WriteFileRangeResult = WriteFileRangeResult
    { writeFilePath :: FilePath
    , writeFileRangesModified :: Int
    , writeFileLinesWritten :: Int
    , writeFileBeforeSnapshotRef :: Maybe SnapshotRef
    , writeFileAfterSnapshotRef :: Maybe SnapshotRef
    , writeFileSessionId :: Maybe Text
    , writeFileSessionNetDelta :: Maybe Int
    , writeFileSessionCommitted :: Bool
    , writeFileSessionStatus :: Text  -- "staged" or "committed"
    }

-- | Result of a patch file operation.
data PatchResult = PatchResult
    { patchFilePath :: FilePath
    , patchHunksApplied :: Int
    , patchHunksRejected :: Int
    , patchLinesChanged :: Int
    , patchBeforeSnapshotRef :: Maybe SnapshotRef
    , patchAfterSnapshotRef :: Maybe SnapshotRef
    }

-- | Patch error with rich context.
data PatchError
    = PatchParseError Text
    | PatchContextMismatch
        { patchMismatchLine :: Int
        , patchMismatchMessage :: Text
        , patchMismatchExpected :: [Text]
        , patchMismatchActual :: [Text]
        }
    | PatchHunkOverlap Int Int
    | PatchFileNotFound FilePath
    | PatchInvalidLineNumber Int

-- | Snapshot reference (MD5 hash of content).
newtype SnapshotRef = SnapshotRef { unSnapshotRef :: Text }
    deriving (Show, Eq, Ord)

-- | Snapshot with metadata.
data Snapshot = Snapshot
    { snapshotContent :: ByteString
    , snapshotCreatedAt :: UTCTime
    }

-- | Create snapshot from content.
makeSnapshot :: ByteString -> Snapshot

-- | Get reference for a snapshot.
snapshotRef :: Snapshot -> SnapshotRef

#!/bin/bash
# my-tool - A bash tool for agents-exe

set -euo pipefail

case "${1:-}" in
  describe)
    cat <<'DESCRIBE_EOF'
{
  "slug": "my-tool",
  "description": "Tool my-tool - describe what this tool does",
  "args": [],
  "empty-result": {
    "tag": "AddMessage",
    "contents": "--no output--"
  }
}
DESCRIBE_EOF
    ;;
  run)
    # TODO: Implement tool logic
    echo "Tool my-tool executed"
    ;;
  *)
    echo "Usage: my-tool <describe|run>" >&2
    exit 1
    ;;
esac

#!/usr/bin/env python3
import json
import sys
import os

def describe():
    return {
        "slug": "my-tool",
        "description": "Tool my-tool - describe what this tool does",
        "args": [],
        "empty-result": {
            "tag": "AddMessage",
            "contents": "--no output--"
        }
    }

def run():
    # TODO: Implement tool logic
    print("Tool my-tool executed")

def main():
    if len(sys.argv) < 2:
        print(f"Usage: {sys.argv[0]} <describe|run>", file=sys.stderr)
        return 1
    
    command = sys.argv[1]
    if command == "describe":
        print(json.dumps(describe()))
        return 0
    elif command == "run":
        run()
        return 0
    else:
        print(f"Unknown command: {command}", file=sys.stderr)
        return 1

if __name__ == "__main__":
    sys.exit(main())

{
  "tag": "OpenAIAgentDescription",
  "contents": {
    "slug": "local_lrmlua",
    "flavor": "KimiV1",
    "modelUrl": "https://api.moonshot.ai/v1",
    "apiKeyId": "kimi",
    "modelName": "kimi-k2.5",
    "announce": "The main agent, capable of reasoning.",
    "systemPrompt": [
      "You are a helpful software agent trying to solve user requests"
    ],
    "extraAgents": [
      {
        "slug": "local_lrmlua",
        "path": "kimi-10.lrmlua.json"
      }
    ],
    "bashToolboxes": [
      {
        "tag": "SingleTool",
        "contents": {"Path": "./tools/askuser/ask-user.bash"}
      }
    ],
    "builtinToolboxes": [
      {
        "tag": "LuaToolbox",
        "contents": {
          "Name": "lua",
          "Description": "Sandboxed Lua interpreter",
          "MaxMemoryMB": 256,
          "MaxExecutionTimeSeconds": 300,
          "AllowedTools": [
            "bash_ask_user",
            "io_prompt_agent_local_lrmlua",
            "sqlite_shared_working_memory_query"
          ],
          "AllowedHosts": [
            "localhost",
            "127.0.0.1"
          ],
          "FileSandbox": {
            "fsbPredicate": {
              "tag": "Any",
              "contents": [
                {"tag": "DirectoryRecursive", "contents": "./repro-cases"},
                {"tag": "FileExactly", "contents": "./README.md"}
              ]
            },
            "fsbMaxFileSize": 10485760,
            "fsbName": "lua-fs-sandbox"
          }
        }
      },
      {
        "tag": "SqliteToolbox",
        "contents": {
          "Name": "shared_working_memory",
          "Description": "A base to help you coordinate large works.",
          "Versioning": {"tag": "SqliteReadWrite", "path": "./dev-memory.db"}
        }
      }
    ]
  }
}

// Old (removed, ignored)
{
  "allowedPaths": ["./data", "./scripts"]
}

// New
{
  "FileSandbox": {
    "fsbPredicate": {
      "tag": "Any",
      "contents": [
        {"tag": "DirectoryRecursive", "contents": "./data"},
        {"tag": "DirectoryRecursive", "contents": "./scripts"}
      ]
    }
  }
}

-- These operations are validated against the fileSandbox
local content = fs.read("./data/file.txt")      -- Must be in sandbox
fs.write("./output/result.txt", "data")          -- Must be in sandbox
local files = fs.list("./scripts")               -- Must be in sandbox
local exists = fs.exists("./README.md")          -- Must be in sandbox

-- Modules are pre-loaded as globals and available via require()

-- Read a file (validated against fileSandbox)
local content = fs.read("./repro-cases/input.json")
if not content then
    return {error = "Failed to read file"}
end

-- Call the recursive agent for complex reasoning
local reasoning_result = tools.call("io_prompt_agent_local_lrmlua", {
    what = "Analyze this codebase structure and identify potential refactoring opportunities"
})

-- Process the result
if reasoning_result.status == "ok" then
    local analysis = json.decode(reasoning_result.result_txt)
    
    -- Query the shared working memory
    local db_result = tools.call("sqlite_shared_working_memory_query", {
        sql = "INSERT INTO analysis_results (content) VALUES ('" .. analysis.summary .. "')"
    })
    
    -- Write results (validated against fileSandbox)
    fs.write("./repro-cases/output.json", json.encode(analysis))
    
    return {
        success = true,
        analysis = analysis,
        stored = db_result.status == "ok"
    }
else
    return {
        success = false,
        error = reasoning_result.error
    }
end

{
  "script": "return json.encode({status='ok'})",
  "timeout": 60
}

data ScriptError
    = LuaRuntimeError [Aeson.Value]      -- Syntax or runtime error
    | TimeoutError Int                   -- Script exceeded time limit
    | MemoryError Int                    -- Script exceeded memory limit
    | SandboxError Text                  -- Attempted sandbox violation
    | ToolInvocationError Text           -- Error calling another tool
    | InitializationError Text           -- Failed to initialize Lua state

---
name: pdf-processing
description: Extract and manipulate PDF files
license: MIT
compatibility: Linux, macOS
metadata:
  author: team-pdf
  version: "1.0"
---

# PDF Processing

This skill provides tools for working with PDF documents.

## Usage

Enable the skill, then use the available script tools...

-- | Validated skill name (1-64 chars, lowercase, digits, hyphens)
newtype SkillName = SkillName { unSkillName :: Text }

-- | Complete skill with metadata, instructions, scripts, and references
data Skill = Skill
    { skillMetadata :: SkillMetadata
    , skillInstructions :: Text
    , skillPath :: FilePath
    , skillScripts :: [ScriptInfo]
    , skillReferences :: [ReferenceInfo]
    }

-- | Metadata from SKILL.md frontmatter
data SkillMetadata = SkillMetadata
    { smName :: SkillName
    , smDescription :: Text
    , smLicense :: Maybe Text
    , smCompatibility :: Maybe Text
    , smMetadata :: Map Text Text
    }

-- | Script following the describe/run protocol
data ScriptInfo = ScriptInfo
    { siName :: ScriptName
    , siPath :: FilePath
    , siDescription :: Maybe Text
    , siArgs :: [ScriptArgInfo]
    }

-- | Session state tracking which skills and scripts are enabled
newtype SkillsSessionState = SkillsSessionState
    { sssActiveSkills :: Map SkillName SkillScriptsState
    }

-- | Script state within a skill
type SkillScriptsState = Map ScriptName ScriptState
data ScriptState = Enabled | Disabled

-- | Monoid instance for folding over session turns
instance Monoid SkillsSessionState where
    mempty = SkillsSessionState Map.empty
    -- Later state overrides earlier state

-- | Compute all available skill tools from session state
computeSkillTools :: SkillsStore -> Session -> [ToolRegistration]
computeSkillTools store session =
    let state = foldSession session
        -- Always available
        metaTools = concatMap makeMetaTools (allSkills store)
        -- Available only when enabled
        scriptTools = 
            concatMap (makeScriptToolsForSkill state store) 
                      (sssActiveSkills state)
     in listTool ++ metaTools ++ scriptTools

-- Tool naming convention
skill2LLMName :: Text -> SkillName -> ToolName
-- skill_describe_pdf-processing
-- skill_enable_pdf-processing
-- skill_pdf-processing_extract-text

data SkillSource
    = SkillDirectory FilePath           -- Local directory
    | SkillGitRepo GitUrl (Maybe Subdirectory)  -- Git repository

{
  "skillSources": [
    { "tag": "SkillDirectory", "contents": "./skills" },
    { "tag": "SkillGitRepo", 
      "contents": { 
        "url": "https://github.com/org/skills-repo",
        "subdir": "pdf-tools"
      }
    }
  ],
  "autoEnableSkills": ["core-utils"]
}

-- | Single validation error with context
data ValidationError = ValidationError
    { errorPath :: Text       -- JSON path (e.g., "user.name")
    , errorMessage :: Text    -- Human-readable description
    }

-- | Validation configuration
data ValidationConfig = ValidationConfig
    { allowExtraProperties :: Bool
    , strictMode :: Bool
    }

-- | Validate tool input against its schema
validateToolInput :: 
    [ParamProperty] ->  -- Tool schema
    Aeson.Value ->      -- Input value
    [ValidationError]   -- Empty if valid

-- Example usage:
let errors = validateToolInput toolSchema inputValue
case errors of
    [] -> proceedWithToolCall
    errs -> returnValidationErrors errs

# Validate a tool call payload
echo '{"filepath": "/path/to/file"}' | \
    agents-exe check-tool-call --tool ./tools/read-file.sh

# Example output (invalid):
# Tool call validation failed for 'read-file' with 2 errors:
# 1. filepath: Required property missing
# 2. content: Required property missing
#
# Please correct these issues and try again.

formatValidationErrors :: Text -> [ValidationError] -> Text
-- Produces:
-- Tool call validation failed for 'tool-name' with 2 errors:
--
-- 1. filters.status: Invalid enum value: pending. Allowed: active, inactive
-- 2. user.age: Expected number but got string
--
-- Please correct these issues and try again.

-- | Tool portal callback type
type ToolPortal = ToolCall -> IO ToolResult

-- | Portal execution errors
data PortalError
    = PortalToolNotFound Text
    | PortalToolNotAllowed Text [Text]
    | PortalInvalidArguments Text
    | PortalExecutionError Text

import System.Agents.ToolPortal

-- Create portal from registered tools
let portal = makeToolPortal tracer registrations

-- Create context with portal
let ctx = mkPortalContext
        sessId convId turnId mAgentId mSession
        callStack maxDepth (Just portal) allowedTools

local tools = require("tools")

-- Call another tool
local result = tools.call("read_file", {
    filepath = "/path/to/file"
})

-- Access result
print(result.data)
print(result.duration)

data ToolResult = ToolResult
    { resultData :: Aeson.Value
    , resultDuration :: NominalDiffTime
    , resultTraceId :: Text
    }

type IOToolBuilder = AgentSlug -> AgentId -> ToolRegistration

exampleTool :: IOToolBuilder
exampleTool slug agentId = ToolRegistration
    { innerTool = ...
    , declareTool = OpenAI.Tool
        { toolName = "example"
        , toolDescription = "An example tool"
        , toolParamProperties = [...]
        }
    , findTool = \call -> ...
    }

ioTool ::
    (Aeson.FromJSON llmArg) =>
    IOTools.IOScript llmArg ByteString ->
    Tool ()

data IOScript arg result = IOScript
    { description :: IOScriptDescription
    , ioRun :: ToolExecutionContext -> arg -> IO result
    }

data ToolExecutionContext = ToolExecutionContext
    { ctxSessionId :: SessionId
    , ctxConversationId :: ConversationId
    , ctxTurnId :: TurnId
    , ctxAgentId :: Maybe AgentId
    , ctxFullSession :: Maybe Session
    , ctxCallStack :: [CallStackEntry]
    , ctxMaxDepth :: Maybe Int
    , ctxToolPortal :: Maybe ToolPortal
    , ctxAllowedTools :: [Text]
    }

data CallStackEntry = CallStackEntry
    { callAgentSlug :: AgentSlug
    , callConversationId :: ConversationId
    , callDepth :: Int
    }

pushAgentContext :: 
    AgentSlug -> 
    ConversationId -> 
    ToolExecutionContext -> 
    Either RecursionError ToolExecutionContext

data ToolExecutionContext = ToolExecutionContext
    { -- ... existing fields ...
    , ctxWorld :: Maybe World
    -- ^ OS World for ECS operations. Enables subcall conversations
    -- to be tracked as first-class entities in the OS.
    , ctxEventQueue :: Maybe (TQueue OSEvent)
    -- ^ Event queue for OS event emission. Enables the TUI to receive
    -- notifications about subcall lifecycle (start, progress, completion).
    , ctxParentConversation :: Maybe ConversationId
    -- ^ Parent conversation ID for nested agent calls.
    }

-- | Create a nested context for subcall execution.
mkSubcallContext ::
    ToolExecutionContext ->
    Maybe World ->
    Maybe (TQueue OSEvent) ->
    ConversationId ->
    ToolExecutionContext

-- | Get the subcall depth (0 for root conversations).
getSubcallDepth :: ToolExecutionContext -> Int

-- | Check if this context is for a subcall.
isSubcallContext :: ToolExecutionContext -> Bool

data CallResult call
    = BlobToolSuccess call ByteString (Maybe MediaType)
    | JsonToolSuccess call Aeson.Value
    | ToolSkipped call
    | BashToolError call BashError
    | IOToolError call IOToolError
    | McpToolError call Text
    | OpenAPIToolError call String
    | PostgRESToolError call String
    | SqliteToolError call SqliteError
    | SystemToolError call SystemInfoError
    | DeveloperToolError call ValidationError
    | McpToolResult call McpToolResult
    | OpenAPIToolResult call OpenAI.ToolResult
    | PostgRESToolResult call OpenAI.ToolResult
    | SqliteToolResult call SqliteQueryResult
    | SystemToolResult call SystemQueryResult
    | DeveloperToolResult call ValidationResult
    | DeveloperToolSpecResult call Text
    | DeveloperToolAgentValidationResult call AgentValidationResult
    | DeveloperToolCreateResult call CreateResult
    | DeveloperToolReadFileRangeResult call ReadFileRangeResult
    | DeveloperToolWriteFileRangeResult call WriteFileRangeResult
    | DeveloperToolPatchResult call PatchResult
    | LuaToolResult call Aeson.Value
    | LuaToolError call Text

data ParamProperty = ParamProperty
    { propertyKey :: Text
    , propertyType :: ParamType
    , propertyDescription :: Text
    , propertyRequired :: Bool
    }

data ParamType
    = NullParamType
    | StringParamType
    | BoolParamType
    | NumberParamType
    | EnumParamType [Text]
    | OpaqueParamType Text
    | MultipleParamType Text
    | ObjectParamType [ParamProperty]

{
  "type": "object",
  "properties": {
    "filename": {
      "type": "string",
      "description": "Name of the file to read"
    },
    "lines": {
      "type": "integer",
      "description": "Number of lines to read"
    }
  },
  "required": ["filename"]
}

newRuntime :: ... -> IO (Either String Runtime)
newRuntime ... = do
    -- Bash tools from tool directory
    bashTools <- BashToolbox.initializeBackroundToolbox ...
    
    -- IO tools from code
    let ioTools = [mk slug uid | mk <- mkIoTools]
    
    -- MCP tools from configured servers
    mcpTools <- mapM initializeMcpToolbox mcpConfigs
    
    -- OpenAPI tools from specs
    openApiTools <- mapM loadOpenApiTools openApiConfigs
    
    -- PostgREST tools
    postgrestTools <- mapM loadPostgRESTools prConfigs
    
    -- SQLite tools from builtin toolboxes
    sqliteTools <- readSqliteToolsRegistrations tracer sqliteToolboxes
    
    -- System tools from builtin toolboxes
    systemTools <- readSystemToolsRegistrations tracer systemToolboxes
    
    -- Developer tools from builtin toolboxes
    devTools <- readDeveloperToolsRegistrations tracer devToolboxes
    
    -- Lua tools from builtin toolboxes
    luaTools <- readLuaToolsRegistrations tracer luaToolboxes
    
    -- Skills tools from skill sources
    skillsStore <- loadSkillsFromSources skillSources
    let skillsTools = computeSkillTools skillsStore session
    
    -- Combine all
    let allTools = ioTools ++ bashTools ++ mcpTools ++ openApiTools ++ 
                   postgrestTools ++ sqliteTools ++ systemTools ++ 
                   devTools ++ luaTools ++ skillsTools

data ToolboxError
    = ToolboxDirectoryNotFound FilePath
    | ScriptParseError FilePath String
    | ScriptExecutionError FilePath Int String

data McpError
    = ProcessStartError Text
    | ProtocolError Text
    | ToolCallError Text

data OpenAPIError
    = SpecParseError String
    | SchemaResolutionError Text
    | ReferenceError RefPath

data QueryError
    = CapabilityNotEnabledError Text
    | SystemInfoError Text
    | FileNotFoundError FilePath
    | FileTooLargeError FilePath Int
    | UnsupportedFileTypeError FilePath Text
    | SessionStoreNotConfiguredError
    | SessionNotFoundError Text
    | InvalidSessionIdError Text
    | SessionAccessDeniedError Text SessionIntrospectionScope
    | MissingParameterError Text
    | CommandRefusedError Text
    | InvalidFilterOutputError Text

data DeveloperToolError
    = CapabilityNotEnabledError Text
    | ValidationError Text
    | FileExistsError FilePath
    | InvalidTemplateError Text
    | InvalidRangeError Text
    | RangeOutOfBoundsError Text
    | PermissionError Text
    | PatchValidationError PatchError
    | SessionNotFoundError Text
    | SessionExpiredError Text
    | SessionAlreadyCommittedError Text
    | RangeOverlapError Text

data PatchError
    = PatchParseError Text
    | PatchContextMismatch
        { patchMismatchLine :: Int
        , patchMismatchMessage :: Text
        , patchMismatchExpected :: [Text]
        , patchMismatchActual :: [Text]
        }
    | PatchHunkOverlap Int Int
    | PatchFileNotFound FilePath
    | PatchInvalidLineNumber Int

data ValidationError = ValidationError
    { errorPath :: Text
    , errorMessage :: Text
    }

data PortalError
    = PortalToolNotFound Text
    | PortalToolNotAllowed Text [Text]
    | PortalInvalidArguments Text
    | PortalExecutionError Text

{
  "slug": "file-agent",
  "apiKeyId": "openai",
  "flavor": "openai",
  "modelUrl": "https://api.openai.com/v1",
  "modelName": "gpt-4o",
  "announce": "A file management assistant with vision",
  "systemPrompt": ["You help users manage and analyze files."],
  "toolDirectory": "tools",
  "bashToolboxes": [
    {"tag": "FileSystemDirectory", "contents": {"Path": "./extra-tools"}}
  ],
  "mcpServers": [
    {
      "tag": "McpSimpleBinary",
      "contents": {
        "name": "filesystem",
        "executable": "/usr/bin/mcp-filesystem",
        "args": ["--root", "/home/user"]
      }
    }
  ],
  "openApiToolboxes": [
    {
      "tag": "OpenAPIServer",
      "contents": {
        "SpecUrl": "https://api.github.com/openapi.json",
        "BaseUrl": "https://api.github.com",
        "Token": "${GITHUB_TOKEN}"
      }
    }
  ],
  "postgrestToolboxes": [
    {
      "tag": "PostgRESTServer",
      "contents": {
        "SpecUrl": "http://localhost:3000/",
        "BaseUrl": "http://localhost:3000"
      }
    }
  ],
  "builtinToolboxes": [
    {
      "tag": "SqliteToolbox",
      "contents": {
        "Name": "analytics",
        "Description": "Analytics database",
        "Versioning": {"tag": "SqliteReadOnly", "path": "./analytics.db"}
      }
    },
    {
      "tag": "SystemToolbox",
      "contents": {
        "Name": "system",
        "Description": "System context and session memory",
        "Capabilities": ["date", "hostname", "working-directory", "attach-file", "list-directory", "execute-command", "list-sessions", "search-sessions"],
        "EnvVarFilter": null,
        "SessionIntrospectionScope": "subtree",
        "SessionIntrospectionMaxResults": 50,
        "SessionIntrospectionIncludeToolOutputs": false,
        "FileSandbox": {
          "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "./project"},
          "fsbMaxFileSize": 52428800,
          "fsbName": "system-sandbox"
        },
        "CommandFilter": "/path/to/approval-script.sh"
      }
    },
    {
      "tag": "DeveloperToolbox",
      "contents": {
        "Name": "dev",
        "Description": "Development utilities",
        "Capabilities": ["show-spec", "validate-agent", "create-agent", "create-tool", "read-file-range", "write-file-range", "patch-file"],
        "FileSandbox": {
          "fsbPredicate": {
            "tag": "Any",
            "contents": [
              {"tag": "DirectoryRecursive", "contents": "./src"},
              {"tag": "DirectoryRecursive", "contents": "./test"},
              {"tag": "FileExactly", "contents": "./package.yaml"}
            ]
          },
          "fsbMaxFileSize": 10485760,
          "fsbName": "developer-sandbox"
        }
      }
    },
    {
      "tag": "LuaToolbox",
      "contents": {
        "Name": "lua",
        "Description": "Lua scripting tools",
        "MaxMemoryMB": 256,
        "MaxExecutionTimeSeconds": 300,
        "AllowedTools": ["bash_read_file", "sqlite_analytics_query", "system_system_attach_file"],
        "AllowedHosts": ["localhost"],
        "FileSandbox": {
          "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "./scripts"},
          "fsbMaxFileSize": 10485760,
          "fsbName": "lua-sandbox"
        }
      }
    }
  ],
  "skillSources": [
    { "tag": "SkillDirectory", "contents": "./skills" }
  ],
  "autoEnableSkills": ["core-utils"],
  "extraAgents": [
    {"slug": "helper", "path": "./helper.json"}
  ]
}