Implement Sourcegraph Toolbox PowerShell port into PSAI

[Copilot]

This PR implements a Sourcegraph Toolbox-style toolbox system for PSAI, enabling dynamic discovery and loading of tool collections for AI agents. The implementation is provided as a spike in /spikes/PSToolboxAI and demonstrates the pattern described in issue #108.

Overview

The Sourcegraph Toolbox pattern provides a way to organize and dynamically load collections of related tools that AI agents can use. This implementation follows the environment-based discovery approach described in the Sourcegraph Toolbox documentation, adapted for PowerShell and integrated with PSAI's existing agent infrastructure.

Key Features

Environment-Based Discovery

• Tools are discovered via $env:PSAI_TOOLBOX_PATH environment variable (supports multiple paths)
• Falls back to default path if environment variable not set
• Scans directories recursively for toolbox scripts

Dynamic Tool Registration

• Tool scripts define functions with Global: scope for accessibility
• Registration functions call PSAI's Register-Tool to create OpenAI-compatible tool specifications
• Tools return JSON strings for LLM compatibility

Seamless Integration

• Works with existing New-Agent -Tools parameter
• Compatible with Get-AgentResponse and Invoke-InteractiveCLI
• Follows established patterns from CalculatorTool and TavilyTool

Implementation

The module provides three main functions:

Get-PSAIToolboxPath - Discovers toolbox directories from environment or returns default path

Get-PSAIToolbox - Loads tool scripts, calls registration functions, and returns tool specifications

New-PSAIToolboxAgent - Convenience function combining tool discovery and agent creation

Included Toolboxes

Three sample toolboxes demonstrate the pattern:

FileSystem Toolbox (tmp/tools/filesystem/)

• Get-DirectoryListing - List files and directories with filtering
• Read-FileContent - Read file contents with encoding support
• Test-FileExists - Check file/directory existence

DateTime Toolbox (tmp/tools/datetime/)

• Get-CurrentDateTime - Get current time in multiple formats (ISO8601, Unix, etc.)
• Format-DateTime - Convert date/time strings between formats
• Get-DateDifference - Calculate time differences in various units

Text Toolbox (tmp/tools/text/)

• Get-TextStatistics - Analyze text (word count, character count, sentence count, etc.)
• Convert-TextCase - Convert case (upper, lower, title, sentence)
• Search-TextPattern - Search text using regex patterns

Usage Example

# Import modules
Import-Module PSAI
Import-Module ./spikes/PSToolboxAI/PSToolboxAI.psd1

# Basic usage - discover and use tools
$tools = Get-PSAIToolbox
$agent = New-Agent -Tools $tools -ShowToolCalls
$agent | Get-AgentResponse "What files are in the current directory?"

# Convenience function
$agent = New-PSAIToolboxAgent -Instructions "You are a helpful assistant" -ShowToolCalls
$agent | Invoke-InteractiveCLI

# Custom toolbox paths
$env:PSAI_TOOLBOX_PATH = "C:\MyTools;C:\SharedTools"
$agent = New-PSAIToolboxAgent -ShowToolCalls

Creating Custom Toolboxes

Tool scripts follow a simple pattern:

# Define tool functions with Global scope
function Global:My-ToolFunction {
    [CmdletBinding()]
    param([string]$Input)
    
    $result = @{ output = "Processed: $Input" }
    return ($result | ConvertTo-Json -Compress)
}

# Registration function (matches script filename)
function MyToolbox {
    $tools = @(Register-Tool -FunctionName My-ToolFunction)
    return $tools
}

Testing

A comprehensive test suite validates:

• ✅ Module loading (PSAI and PSToolboxAI)
• ✅ Toolbox path discovery
• ✅ Tool discovery (9 tools successfully registered)
• ✅ Function availability (all 9 functions accessible)
• ✅ Function execution (DateTime, Text, FileSystem tools)
• ✅ Agent creation with tools

Run tests with: pwsh -File spikes/PSToolboxAI/test-toolbox.ps1

Documentation

• README.md - User-facing documentation with usage examples and toolbox creation guide
• IMPLEMENTATION_NOTES.md - Technical documentation covering design decisions, challenges, and solutions
• Examples/ - Two example scripts demonstrating different usage patterns

Technical Notes

Function Scope: Tool functions use Global: scope (following the pattern in TavilyTool.psm1) to ensure they're accessible to Register-Tool.

JSON Output: All tool functions return JSON strings as required by OpenAI's function calling API.

No Breaking Changes: This is a new spike module that doesn't modify existing PSAI code.

Future Enhancements

The spike establishes patterns that enable:

• Tool caching for improved performance
• Tool versioning support
• Remote toolbox loading from URLs
• Tool validation and dependencies
• Community toolbox marketplace

Files Added

• PSToolboxAI.psd1 - Module manifest
• PSToolboxAI.psm1 - Module loader
• Public/PSToolboxAI.ps1 - Core functions (240 lines)
• tmp/tools/*/ - Three toolboxes with 9 tools (525 lines)
• Examples/ - Usage examples (2 scripts)
• test-toolbox.ps1 - Test suite (196 lines)
• README.md - User documentation (280 lines)
• IMPLEMENTATION_NOTES.md - Technical documentation (275 lines)

Closes #108

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Implement Sourcegraph Toolbox PowerShell port into PSAI</issue_title>
<issue_description>It was pretty straightforward. Doing dir listings to get files.

For the Sourcegraph Toolbox, setting the $env var and in my ps1 files seeing if it is set and returning the Json from Register-Tool and setting that up via the New-Agent -Tools - worked like a charm.

Expected Output

Review the "Reference links" and other internet sources about these offerings of Sourcegraph Toolbox

• Review the current implementation of PSAI

The code is and tools are in:

• The spike is in /spikes/PSToolboxAI. It is a PowerShell module,
• The /spikes/PSToolboxAI/Public/PSToolBoxAI.ps1 has the working implementation
• The tools are in spikes\PSToolboxAI\tmp\tools in the subdirectories

Reference links

Sourcegraph Toolbox links:

• Toolboxes - https://ampcode.com/manual#toolboxes
• https://ampcode.com/manual/appendix#toolboxes-reference</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #108

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.