quikcue/calvana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🚀

Browse Source
This commit is contained in:
IndyDevDan
2026-02-22 20:19:33 -06:00
commit 32dfe122cb
68 changed files with 8173 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
specs/agent-forge.md Normal file
View File

@@ -0,0 +1,72 @@
# 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.

64
specs/agent-workflow.md Normal file
View File

@@ -0,0 +1,64 @@
# Specification: The Chronicle (agent-workflow)
## 1. Overview
**The Chronicle** is a temporal orchestration extension for the Pi Coding Agent. It enables long-running, state-aware workflows that span multiple sessions and personas. Unlike traditional linear agents, The Chronicle manages a formal **State Machine** where each stage of a project is handled by a specialized agent persona, with the extension acting as a persistent "State Supervisor."
## 2. Core Architecture
### 2.1 The Supervisor Model
The Chronicle operates as a non-working supervisor that delegates tasks to worker agents.
- **The Ledger**: A persistent JSON file (`.pi/chronicle/sessions/<uuid>.json`) that tracks the project state, file snapshots, and transition history.
- **State Isolation**: Each state is executed by a fresh Pi sub-agent process with a specialized system prompt, preventing "persona leakage" and ensuring clean tool contexts.
- **Context Handover**: When transitioning, the Supervisor extracts a "Snapshot" (modified files, key discoveries, pending tasks) and injects it into the next agent's starting context.
### 2.2 Workflow Definition
Workflows are defined in JSON templates:
```json
{
"name": "Feature Implementation",
"states": {
"planning": {
"persona": "Software Architect",
"next": ["implementation"],
"requires_approval": true
},
"implementation": {
"persona": "Senior Engineer",
"next": ["verification", "planning"]
}
}
}
```
## 3. Key Mechanisms
### 3.1 Explicit Transitions
To ensure reliability, transitions are **explicit**. The agent must call a tool to signal completion:
- `workflow_transition(target_state, summary)`: Finalizes the current state, saves the snapshot, and triggers the supervisor to spawn the next agent.
- `workflow_update_snapshot(data)`: Allows agents to "checkpoint" critical findings (e.g., "The API port is 8081, not 8080") that must persist through the entire workflow.
### 3.2 Temporal Persistence
- **Checkpointing**: Every tool call and state change is logged to the Ledger.
- **Recovery**: If a session is interrupted (e.g., power loss, manual exit), the extension can resume exactly where it left off by reading the Ledger and re-priming the sub-agent.
### 3.3 TUI Integration (The Timeline)
A dedicated widget displays the project's journey:
- **Breadcrumbs**: `Planning [✓] -> Implementation [●] -> Verification [ ]`.
- **Metrics**: Displays cumulative token usage and time elapsed per state.
- **Diff View**: Shows which files have been modified since the start of the current state.
## 4. Operational Guardrails
### 4.1 Anti-Looping
If a workflow transitions between the same states more than 3 times (e.g., Planning -> Implementation -> Planning -> Implementation), the Supervisor forces a transition to a `human_intervention` state and blocks further automated moves.
### 4.2 Resource Budgeting
The Supervisor tracks the total cost and token consumption across all sub-agents. It can be configured with hard limits to prevent runaway costs in long-running workflows.
### 4.3 Cleanup
Each state can define a cleanup routine that the Supervisor executes (e.g., killing background processes) before the next agent is spawned.
## 5. Integration
The Chronicle integrates with:
- **agent-team**: To fetch specialized personas for specific states.
- **damage-control**: To enforce safety rules across all worker sub-agents spawned by the Supervisor.

44
specs/damage-control.md Normal file
View File

@@ -0,0 +1,44 @@
# Specification: Damage-Control Extension
## 1. Overview
**Damage-Control** is a safety and observability extension for the Pi Coding Agent. It enforces security patterns and "Rules of Engagement" by auditing tool calls in real-time. It intercepts potentially dangerous operations and enforces path-based access controls.
## 2. Core Architecture
- **Rule Engine**: Loads `.pi/damage-control-rules.yaml` on `session_start`. If missing, it defaults to an empty rule set.
- **Interception Hook**: Uses `pi.on("tool_call", handler)` to evaluate every tool call before execution.
- **Path Resolver**: Utility to expand tildes (`~`) and resolve relative paths against the current working directory (`cwd`) for accurate matching.
## 3. Tool Interception Logic
The extension uses `isToolCallEventType(toolName, event)` for type-safe narrowing of events.
### A. Bash Tool (`bash`)
- **Input Field**: `event.input.command`.
- **Destructive Patterns**: Match `bashToolPatterns` regex against the raw command string.
- **Path Matching**: Best-effort heuristic. Match `zeroAccessPaths`, `readOnlyPaths`, and `noDeletePaths` as substrings/regex patterns within the command string.
- **Modification Detection**: Block any bash command referencing `readOnlyPaths` patterns to prevent redirects (`>`), in-place edits (`sed -i`), or moves/deletes.
### B. File Tools (`read`, `write`, `edit`, `grep`, `find`, `ls`)
- **Input Field**: `event.input.path`.
- **Default Path**: For `grep`, `find`, and `ls`, if `path` is undefined, treat it as `ctx.cwd` for matching.
- **Access Control**:
- **Zero Access**: Block if path matches any `zeroAccessPaths` pattern.
- **Grep Glob**: Check the `glob` field of `grep` (`event.input.glob`) against `zeroAccessPaths`.
- **Read Only**: Block `write` or `edit` calls if path matches `readOnlyPaths`.
- **No Delete**: Block `bash` calls involving `rm` or similar on `noDeletePaths`.
## 4. Intervention & UI
- **Status Indicator**: Use `ctx.ui.setStatus()` to show an indicator of active safety rules (e.g., "🛡️ Damage-Control Active: 142 Rules").
- **Violation Feedback**: When a violation is blocked or confirmed, update the status temporarily to show the last event (e.g., "⚠️ Last Violation: git reset --hard").
- **Blocking**: Return `{ block: true, reason: "Security Policy Violation: [Reason]" }`.
- **User Confirmation (`ask: true`)**:
- For rules with `ask: true`, the handler must `await ctx.ui.confirm(title, message, { timeout: 30000 })`.
- Return `{ block: !confirmed, reason: "User denied execution" }`.
- **Notifications**: Use `ctx.ui.notify()` to alert the user when a rule is triggered.
## 5. Logging & Persistence
- Every interception (block or confirm) is logged using `pi.appendEntry("damage-control-log", { tool, input, rule, action })`. This ensures the security audit is part of the permanent session history.
## 6. Implementation Notes
- **Path Resolution**: Must match against both raw input (e.g., `src/main.ts`) and absolute resolved paths. Handle `ctx.cwd` fallback for optional paths.
- **Tilde Expansion**: Manually expand `~` to `process.env.HOME` or `os.homedir()`.
- **Graceful Fallback**: If YAML parsing fails, notify the user and continue with no active rules rather than crashing the extension.

138
specs/pi-pi.md Normal file
View File

@@ -0,0 +1,138 @@
# Pi Pi — Meta Agent Spec
## Purpose
A Pi extension that builds Pi agents. The "Pi Pi" agent is a meta-agent — it knows how to create extensions, themes, skills, settings, prompt templates, and TUI components by querying a team of domain-specific research agents in parallel.
## Architecture
```
User Request: "Build me a Pi agent that does X"
│
▼
┌──────────────────────────────────┐
│ Primary Agent ("Pi Pi") │
│ Tools: read,write,edit,bash, │
│ grep,find,ls, │
│ query_expert │
│ Role: WRITER — gathers info │
│ from experts, then builds │
└──────┬───────────────────────────┘
│ query_expert (parallel)
├──────────────────────────┐──────────────────────┐──────────────────────┐──────────────────────┐
▼ ▼ ▼ ▼ ▼
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ext-expert │ │ theme-expert │ │ skill-expert │ │ config-expert│ │ tui-expert │
│ Extensions │ │ Themes │ │ Skills │ │ Settings │ │ TUI/UI │
│ Tools, cmds │ │ JSON format │ │ SKILL.md │ │ Providers │ │ Components │
│ Events, API │ │ Color tokens │ │ Frontmatter │ │ Models │ │ Rendering │
│ │ │ Hot reload │ │ Directories │ │ Packages │ │ Keyboard │
│ read-only │ │ read-only │ │ read-only │ │ read-only │ │ read-only │
└─────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
```
## Flow
1. User asks the primary Pi Pi agent to build something
2. Primary agent identifies which domains are relevant
3. Primary dispatches `query_expert` calls in PARALLEL to all relevant experts
4. Each expert:
a. Uses `/skill:firecrawl` to scrape fresh Pi documentation for their domain
b. Searches the local codebase for existing patterns and examples
c. Returns structured research findings
5. Primary agent receives ALL expert responses
6. Primary agent synthesizes the information and WRITES the actual files
## Expert Agents
### ext-expert (Extensions)
- **Domain**: Pi extensions — custom tools, events, commands, shortcuts, flags, state management, custom rendering, overriding tools
- **Doc URL**: `https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/extensions.md`
- **Tools**: read,grep,find,ls,bash
- **First action**: Fetch fresh extensions.md via firecrawl
### theme-expert (Themes)
- **Domain**: Pi themes — JSON format, 51 color tokens, vars, hex/256-color values, hot reload
- **Doc URL**: `https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/themes.md`
- **Tools**: read,grep,find,ls,bash
- **First action**: Fetch fresh themes.md via firecrawl
### skill-expert (Skills)
- **Domain**: Pi skills — SKILL.md format, frontmatter, directories, validation, /skill:name commands
- **Doc URL**: `https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/skills.md`
- **Tools**: read,grep,find,ls,bash
- **First action**: Fetch fresh skills.md via firecrawl
### config-expert (Settings & Providers)
- **Domain**: Pi settings, providers, models, packages, keybindings — settings.json, models.json, packages, enabledModels
- **Doc URLs**: settings.md, providers.md, models.md, packages.md, keybindings.md
- **Tools**: read,grep,find,ls,bash
- **First action**: Fetch fresh settings.md + providers.md via firecrawl
### tui-expert (TUI Components)
- **Domain**: Pi TUI — Component interface, Text, Box, Container, Markdown, Image, keyboard input, custom components, overlays, theming, SelectList, SettingsList, BorderedLoader, widgets, footers, editors
- **Doc URL**: `https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/tui.md`
- **Tools**: read,grep,find,ls,bash
- **First action**: Fetch fresh tui.md via firecrawl
## Extension Structure
File: `extensions/pi-pi.ts`
### Differences from agent-team.ts
| Feature | agent-team | pi-pi |
|---------|-----------|-------|
| Primary tools | dispatch_agent ONLY | read,write,edit,bash,grep,find,ls + query_expert |
| Subagent tools | varies per agent | read,grep,find,ls,bash (read-only + bash for firecrawl) |
| Dispatch model | Sequential | Parallel (LLM calls query_expert N times) |
| Subagent sessions | Persistent | Ephemeral (--no-session) |
| System prompt | Generic dispatcher | Specialized meta-agent builder |
| First prompt | None | Each expert fetches fresh docs on first query |
### Tool: query_expert
```typescript
pi.registerTool({
name: "query_expert",
label: "Query Expert",
description: "Query a domain expert for Pi documentation and patterns. Experts research in parallel. Use multiple query_expert calls in one response for parallel research.",
parameters: Type.Object({
expert: Type.String({ description: "Expert name: ext-expert, theme-expert, skill-expert, config-expert, tui-expert" }),
question: Type.String({ description: "What to research — be specific about what you need to build" }),
}),
})
```
### Widget
Grid of expert cards showing:
- Expert name and status (idle/researching/done/error)
- Current question being researched
- Elapsed time
### Justfile Entry
```just
ext-pi-pi:
pi -e extensions/pi-pi.ts
```
## Agent Definition Files
Located in `.pi/agents/`:
- `ext-expert.md`
- `theme-expert.md`
- `skill-expert.md`
- `config-expert.md`
- `tui-expert.md`
Teams entry in `.pi/agents/teams.yaml`:
```yaml
pi-pi:
- ext-expert
- theme-expert
- skill-expert
- config-expert
- tui-expert
```