calvana/specs/agent-forge.md

Specification: Agent Forge (Evolutionary Tooling)

1. Overview

Agent Forge is an evolutionary extension for the Pi Coding Agent. It enables the agent to expand its own capabilities by dynamically generating, validating, and loading new TypeScript tools on demand. Instead of a static set of capabilities, Agent Forge turns the agent into a meta-developer that builds its own infrastructure.

2. Core Architecture

2.1 The Toolbox

All evolved tools are stored in the extensions/ directory with a specific naming pattern:

• extensions/forge-<name>.ts: The executable TypeScript logic.
• extensions/forge-<name>.json: Metadata, including the tool's description and TypeBox parameters schema.
• extensions/forge-registry.json: A central manifest for fast tool discovery during the before_agent_start hook.

2.2 The Proxy Model

Unlike agent-team which spawns new processes, Agent Forge uses a Hybrid Proxy Model:

1. Dynamic Loading: Uses jiti (Pi's internal runtime) to load forged tools into the existing process.
2. Context Sharing: Forged tools have direct access to the ExtensionAPI, allowing them to interact with the UI, notify the user, and use the existing toolset (read/write/bash).
3. Zero Overhead: Execution is instantaneous as it happens within the same Node.js/Bun runtime.

3. Core Tools

3.1 forge_tool

• Purpose: Generates a new tool or updates an existing one.
• Inputs: name, description, parametersSchema, and logic (the TypeScript body).
• Process:
  1. Wraps logic in a standard tool template.
  2. Writes .ts and .json files to extensions/.
  3. Pre-flight Check: Attempts to load the tool via jiti. If it fails (syntax error), it reports the error to the agent for "Self-Healing".
  4. Updates forge-registry.json.

3.2 use_forge_tool

• Purpose: Executes a previously forged tool.
• Process:
  1. Resolves the tool from the registry.
  2. Dynamically imports the .ts file.
  3. Passes arguments to the tool's execute function.
  4. Handles runtime errors gracefully, offering to "debug" the tool if it crashes.

3.3 list_forge

• Purpose: Lists all available evolved tools and their descriptions.

4. Safety & Self-Healing

• Sandboxing: Forged tools are restricted to a "Core Library" of imports (fs, path, child_process, typebox).
• Versioning: Each forge_tool call creates a .bak of the previous version.
• Self-Healing: If use_forge_tool or forge_tool's pre-flight check fails, the agent is provided with the stack trace and the source code to perform an immediate fix.

5. UI Integration

• Forge Widget: A dedicated dashboard element showing:
  • Evolved Tools: Count of active tools.
  • Last Action: "Forged 'sql-explorer' 2m ago" or "Executing 'log-parser'...".
  • Health: Indicator of any tools currently in a "broken" state.
• Status Bar: Displays the "Forge Tier" (based on number of successful tools).

6. Template Structure

Every forged tool follows this mandatory structure:

import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { Type } from "@sinclair/typebox";

export const metadata = {
  name: "custom_tool",
  description: "...",
  parameters: Type.Object({ ... })
};

export async function execute(params: any, pi: ExtensionAPI, ctx: any) {
  // Logic goes here
}

7. Integration with Agent-Team

Agent Forge can act as a "specialist" within an agent-team. The "Engineer" agent in a team can use Agent Forge to build tools for the "Analyst" or "Builder" agents, creating a collaborative ecosystem of meta-programming.