Omair Saleh
2fb612b1df
- Static site: /manifesto, /live, /hire pages - Ship-log Pi extension: calvana_ship, calvana_oops, calvana_deploy tools - Docker + nginx deploy to calvana.quikcue.com - Terminal-ish dark aesthetic, mobile responsive - Auto-updating /live page from extension state
73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
# 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:
|
|
```typescript
|
|
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.
|