aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: release v0.2.3

Browse Source
This commit is contained in:
Dotta
2026-03-03 15:39:13 -06:00
parent 925680f736
commit 28bf5e9e9b
69 changed files with 80 additions and 4145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
docs/adapters/claude-local.md
View File

@@ -1,57 +0,0 @@
---
title: Claude Local
summary: Claude Code local adapter setup and configuration
---
The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing.
## Prerequisites
- Claude Code CLI installed (`claude` command available)
- `ANTHROPIC_API_KEY` set in the environment or agent config
## Configuration Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
| `model` | string | No | Claude model to use (e.g. `claude-opus-4-6`) |
| `promptTemplate` | string | No | Prompt used for all runs |
| `env` | object | No | Environment variables (supports secret refs) |
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
| `graceSec` | number | No | Grace period before force-kill |
| `maxTurnsPerRun` | number | No | Max agentic turns per heartbeat |
| `dangerouslySkipPermissions` | boolean | No | Skip permission prompts (dev only) |
## Prompt Templates
Templates support `{{variable}}` substitution:
| Variable | Value |
|----------|-------|
| `{{agentId}}` | Agent's ID |
| `{{companyId}}` | Company ID |
| `{{runId}}` | Current run ID |
| `{{agent.name}}` | Agent's name |
| `{{company.name}}` | Company name |
## Session Persistence
The adapter persists Claude Code session IDs between heartbeats. On the next wake, it resumes the existing conversation so the agent retains full context.
Session resume is cwd-aware: if the agent's working directory changed since the last run, a fresh session starts instead.
If resume fails with an unknown session error, the adapter automatically retries with a fresh session.
## Skills Injection
The adapter creates a temporary directory with symlinks to Paperclip skills and passes it via `--add-dir`. This makes skills discoverable without polluting the agent's working directory.
## Environment Test
Use the "Test Environment" button in the UI to validate the adapter config. It checks:
- Claude CLI is installed and accessible
- Working directory is absolute and available (auto-created if missing and permitted)
- API key/auth mode hints (`ANTHROPIC_API_KEY` vs subscription login)
- A live hello probe (`claude --print - --output-format stream-json --verbose` with prompt `Respond with hello.`) to verify CLI readiness

40
docs/adapters/codex-local.md
View File

@@ -1,40 +0,0 @@
---
title: Codex Local
summary: OpenAI Codex local adapter setup and configuration
---
The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session persistence via `previous_response_id` chaining and skills injection through the global Codex skills directory.
## Prerequisites
- Codex CLI installed (`codex` command available)
- `OPENAI_API_KEY` set in the environment or agent config
## Configuration Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
| `model` | string | No | Model to use |
| `promptTemplate` | string | No | Prompt used for all runs |
| `env` | object | No | Environment variables (supports secret refs) |
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
| `graceSec` | number | No | Grace period before force-kill |
| `dangerouslyBypassApprovalsAndSandbox` | boolean | No | Skip safety checks (dev only) |
## Session Persistence
Codex uses `previous_response_id` for session continuity. The adapter serializes and restores this across heartbeats, allowing the agent to maintain conversation context.
## Skills Injection
The adapter symlinks Paperclip skills into the global Codex skills directory (`~/.codex/skills`). Existing user skills are not overwritten.
## Environment Test
The environment test checks:
- Codex CLI is installed and accessible
- Working directory is absolute and available (auto-created if missing and permitted)
- Authentication signal (`OPENAI_API_KEY` presence)
- A live hello probe (`codex exec --json -` with prompt `Respond with hello.`) to verify the CLI can actually run

103
docs/adapters/creating-an-adapter.md
View File

@@ -1,103 +0,0 @@
---
title: Creating an Adapter
summary: Guide to building a custom adapter
---
Build a custom adapter to connect Paperclip to any agent runtime.
## Package Structure
```
packages/adapters/<name>/
package.json
tsconfig.json
src/
index.ts # Shared metadata
server/
index.ts # Server exports
execute.ts # Core execution logic
parse.ts # Output parsing
test.ts # Environment diagnostics
ui/
index.ts # UI exports
parse-stdout.ts # Transcript parser
build-config.ts # Config builder
cli/
index.ts # CLI exports
format-event.ts # Terminal formatter
```
## Step 1: Root Metadata
`src/index.ts` is imported by all three consumers. Keep it dependency-free.
```ts
export const type = "my_agent"; // snake_case, globally unique
export const label = "My Agent (local)";
export const models = [
{ id: "model-a", label: "Model A" },
];
export const agentConfigurationDoc = `# my_agent configuration
Use when: ...
Don't use when: ...
Core fields: ...
`;
```
## Step 2: Server Execute
`src/server/execute.ts` is the core. It receives an `AdapterExecutionContext` and returns an `AdapterExecutionResult`.
Key responsibilities:
1. Read config using safe helpers (`asString`, `asNumber`, etc.)
2. Build environment with `buildPaperclipEnv(agent)` plus context vars
3. Resolve session state from `runtime.sessionParams`
4. Render prompt with `renderTemplate(template, data)`
5. Spawn the process with `runChildProcess()` or call via `fetch()`
6. Parse output for usage, costs, session state, errors
7. Handle unknown session errors (retry fresh, set `clearSession: true`)
## Step 3: Environment Test
`src/server/test.ts` validates the adapter config before running.
Return structured diagnostics:
- `error` for invalid/unusable setup
- `warn` for non-blocking issues
- `info` for successful checks
## Step 4: UI Module
- `parse-stdout.ts` — converts stdout lines to `TranscriptEntry[]` for the run viewer
- `build-config.ts` — converts form values to `adapterConfig` JSON
- Config fields React component in `ui/src/adapters/<name>/config-fields.tsx`
## Step 5: CLI Module
`format-event.ts` — pretty-prints stdout for `paperclipai run --watch` using `picocolors`.
## Step 6: Register
Add the adapter to all three registries:
1. `server/src/adapters/registry.ts`
2. `ui/src/adapters/registry.ts`
3. `cli/src/adapters/registry.ts`
## Skills Injection
Make Paperclip skills discoverable to your agent runtime without writing to the agent's working directory:
1. **Best: tmpdir + flag** — create tmpdir, symlink skills, pass via CLI flag, clean up after
2. **Acceptable: global config dir** — symlink to the runtime's global plugins directory
3. **Acceptable: env var** — point a skills path env var at the repo's `skills/` directory
4. **Last resort: prompt injection** — include skill content in the prompt template
## Security
- Treat agent output as untrusted (parse defensively, never execute)
- Inject secrets via environment variables, not prompts
- Configure network access controls if the runtime supports them
- Always enforce timeout and grace period

51
docs/adapters/http.md
View File

@@ -1,51 +0,0 @@
---
title: HTTP Adapter
summary: HTTP webhook adapter
---
The `http` adapter sends a webhook request to an external agent service. The agent runs externally and Paperclip just triggers it.
## When to Use
- Agent runs as an external service (cloud function, dedicated server)
- Fire-and-forget invocation model
- Integration with third-party agent platforms
## When Not to Use
- If the agent runs locally on the same machine (use `process`, `claude_local`, or `codex_local`)
- If you need stdout capture and real-time run viewing
## Configuration
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Webhook URL to POST to |
| `headers` | object | No | Additional HTTP headers |
| `timeoutSec` | number | No | Request timeout |
## How It Works
1. Paperclip sends a POST request to the configured URL
2. The request body includes the execution context (agent ID, task info, wake reason)
3. The external agent processes the request and calls back to the Paperclip API
4. Response from the webhook is captured as the run result
## Request Body
The webhook receives a JSON payload with:
```json
{
"runId": "...",
"agentId": "...",
"companyId": "...",
"context": {
"taskId": "...",
"wakeReason": "...",
"commentId": "..."
}
}
```
The external agent uses `PAPERCLIP_API_URL` and an API key to call back to Paperclip.

58
docs/adapters/overview.md
View File

@@ -1,58 +0,0 @@
---
title: Adapters Overview
summary: What adapters are and how they connect agents to Paperclip
---
Adapters are the bridge between Paperclip's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.
## How Adapters Work
When a heartbeat fires, Paperclip:
1. Looks up the agent's `adapterType` and `adapterConfig`
2. Calls the adapter's `execute()` function with the execution context
3. The adapter spawns or calls the agent runtime
4. The adapter captures stdout, parses usage/cost data, and returns a structured result
## Built-in Adapters
| Adapter | Type Key | Description |
|---------|----------|-------------|
| [Claude Local](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally |
| [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
## Adapter Architecture
Each adapter is a package with three modules:
```
packages/adapters/<name>/
src/
index.ts # Shared metadata (type, label, models)
server/
execute.ts # Core execution logic
parse.ts # Output parsing
test.ts # Environment diagnostics
ui/
parse-stdout.ts # Stdout -> transcript entries for run viewer
build-config.ts # Form values -> adapterConfig JSON
cli/
format-event.ts # Terminal output for `paperclipai run --watch`
```
Three registries consume these modules:
| Registry | What it does |
|----------|-------------|
| **Server** | Executes agents, captures results |
| **UI** | Renders run transcripts, provides config forms |
| **CLI** | Formats terminal output for live watching |
## Choosing an Adapter
- **Need a coding agent?** Use `claude_local` or `codex_local`
- **Need to run a script or command?** Use `process`
- **Need to call an external service?** Use `http`
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)

50
docs/adapters/process.md
View File

@@ -1,50 +0,0 @@
---
title: Process Adapter
summary: Generic shell process adapter
---
The `process` adapter executes arbitrary shell commands. Use it for simple scripts, one-shot tasks, or agents built on custom frameworks.
## When to Use
- Running a Python script that calls the Paperclip API
- Executing a custom agent loop
- Any runtime that can be invoked as a shell command
## When Not to Use
- If you need session persistence across runs (use `claude_local` or `codex_local`)
- If the agent needs conversational context between heartbeats
## Configuration
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | Shell command to execute |
| `cwd` | string | No | Working directory |
| `env` | object | No | Environment variables |
| `timeoutSec` | number | No | Process timeout |
## How It Works
1. Paperclip spawns the configured command as a child process
2. Standard Paperclip environment variables are injected (`PAPERCLIP_AGENT_ID`, `PAPERCLIP_API_KEY`, etc.)
3. The process runs to completion
4. Exit code determines success/failure
## Example
An agent that runs a Python script:
```json
{
"adapterType": "process",
"adapterConfig": {
"command": "python3 /path/to/agent.py",
"cwd": "/path/to/workspace",
"timeoutSec": 300
}
}
```
The script can use the injected environment variables to authenticate with the Paperclip API and perform work.