Implement custom inline tool integration for SDK

[Mossaka]

Description

Add support for defining custom tools inline with application logic, rather than requiring external MCP servers. This enables workflow-specific tools with direct access to GitHub Actions environment.

Part of Epic

#10154 - Copilot SDK Integration for Advanced Agentic Workflows

Problem Statement

CLI Limitation:

• Tools must be external MCP servers
• Cannot define tools inline
• No dynamic tool registration during execution
• Tool callbacks run in separate processes

SDK Opportunity:

// Define custom tools inline
const session = await client.createSession({
  tools: [{
    name: "deploy_to_staging",
    description: "Deploy changes to staging environment",
    parameters: { /* JSON schema */ },
    execute: async (params) => {
      // Custom logic with access to workflow context
      const result = await deployService.deploy(params);
      return { success: true, url: result.url };
    }
  }]
});

Use Cases

1. GitHub API Operations - Inline wrappers around gh CLI or Octokit
2. Deployment Actions - Direct integration with deployment services
3. File System Operations - Workspace-aware file manipulation
4. Custom Validation - Workflow-specific validation logic
5. Secret Access - Secure access to GitHub Actions secrets

Design Requirements

1. Tool Definition Format

engine:
  id: copilot
  mode: sdk
  tools:
    inline:
      - name: create_deployment
        description: "Create deployment to specified environment"
        parameters:
          type: object
          properties:
            environment:
              type: string
              enum: [staging, production]
            ref:
              type: string
          required: [environment]
        implementation: |
          // JavaScript/TypeScript code
          const { environment, ref } = params;
          const result = await exec(`gh api ...`);
          return { deployment_id: result.id };

2. Security Model

• Sandboxing - Tool code runs in isolated context
• Permission Declaration - Tools declare required permissions
• Input Validation - Parameters validated against JSON schema
• Output Sanitization - Tool output sanitized before returning to model
• Audit Logging - All tool invocations logged

3. Integration with Existing Tools

Inline tools should coexist with MCP tools:

tools:
  github:                    # Existing MCP tool
    allowed: [issue_read]
  inline:                    # New inline tools
    - name: custom_validator
      # ...

Implementation Tasks

• Design frontmatter syntax for inline tool definitions
• Implement tool registration in SDK engine
• Add parameter validation using JSON schema
• Implement security sandboxing
• Add audit logging for tool invocations
• Create example inline tools library
• Update documentation with best practices

Example Inline Tools

1. Safe Output Helper:

{
  name: "create_issue_output",
  description: "Queue issue creation as safe output",
  execute: async (params) => {
    await writeSafeOutput('create-issue', params);
    return { queued: true };
  }
}

2. Context Reader:

{
  name: "read_pr_context",
  description: "Read sanitized PR context",
  execute: async (params) => {
    const context = process.env.PR_CONTEXT;
    return JSON.parse(context);
  }
}

3. Deployment Trigger:

{
  name: "trigger_deployment",
  description: "Trigger deployment workflow",
  execute: async (params) => {
    await exec(`gh workflow run deploy.yml -f env=${params.env}`);
    return { status: "triggered" };
  }
}

Success Criteria

• Frontmatter syntax for inline tools
• Runtime tool registration working
• Security sandboxing implemented
• At least 5 example inline tools
• Documentation with security guidelines
• Integration tests

Security Considerations

1. Code Injection - Validate tool code before execution
2. Secret Exposure - Never pass secrets to model directly
3. Privilege Escalation - Limit tool capabilities
4. Resource Exhaustion - Timeout and resource limits
5. Data Exfiltration - Output sanitization

References

• MCP tool specification for compatibility
• GitHub Actions secrets handling
• Sandboxing best practices

---

Priority: High - Key differentiator vs CLI
Estimated Effort: 7-10 days
Dependencies: #10155 (POC), #10156 (session design)
Skills Required: TypeScript, security, Go