From 4bb42005ea41db13400adf8d1d9c4b0571917677 Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 01:06:27 -0500 Subject: [PATCH 1/4] docs: fix SPEC accuracy for adapters and backend - align adapter list with current built-in adapters - update backend framework references to Express - remove outdated V1 not-supported template export claim - clarify work artifact boundaries with issue documents Co-Authored-By: Paperclip --- doc/SPEC.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/SPEC.md b/doc/SPEC.md index 82315bce..671431bb 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -186,17 +186,21 @@ The heartbeat is a protocol, not a runtime. Paperclip defines how to initiate an ### Execution Adapters -Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Initial adapters: +Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Built-in adapters include: -| Adapter | Mechanism | Example | -| -------------------- | ----------------------- | --------------------------------------------- | -| `process` | Execute a child process | `python run_agent.py --agent-id {id}` | -| `http` | Send an HTTP request | `POST https://openclaw.example.com/hook/{id}` | -| `openclaw_gateway` | OpenClaw gateway API | Managed OpenClaw agent via gateway | -| `gemini_local` | Gemini CLI process | Local Gemini CLI with sandbox and approval | -| `hermes_local` | Hermes agent process | Local Hermes agent | +| Adapter | Mechanism | Example | +| ---------------- | -------------------------- | -------------------------------------------------- | +| `process` | Execute a child process | `python run_agent.py --agent-id {id}` | +| `http` | Send an HTTP request | `POST https://openclaw.example.com/hook/{id}` | +| `claude_local` | Local Claude Code process | Claude Code heartbeat worker | +| `codex_local` | Local Codex process | Codex CLI heartbeat worker | +| `opencode_local` | Local OpenCode process | OpenCode heartbeat worker | +| `pi_local` | Local Pi process | Pi CLI heartbeat worker | +| `cursor` | Cursor API/CLI bridge | Cursor-integrated heartbeat worker | +| `openclaw_gateway` | OpenClaw gateway API | Managed OpenClaw agent via gateway | +| `hermes_local` | Local Hermes process | Hermes agent heartbeat worker | -The `process` and `http` adapters ship as defaults. Additional adapters have been added for specific agent runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture). +The `process` and `http` adapters ship as generic defaults. Additional built-in adapters cover common local coding runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture). ### Adapter Interface @@ -376,7 +380,7 @@ Flow: | Layer | Technology | | -------- | ------------------------------------------------------------ | | Frontend | React + Vite | -| Backend | TypeScript + Hono (REST API, not tRPC — need non-TS clients) | +| Backend | TypeScript + Express (REST API, not tRPC — need non-TS clients) | | Database | PostgreSQL (see [doc/DATABASE.md](./doc/DATABASE.md) for details — PGlite embedded for dev, Docker or hosted Supabase for production) | | Auth | [Better Auth](https://www.better-auth.com/) | @@ -406,7 +410,7 @@ No separate "agent API" vs. "board API." Same endpoints, different authorization ### Work Artifacts -Paperclip does **not** manage work artifacts (code repos, file systems, deployments, documents). That's entirely the agent's domain. Paperclip tracks tasks and costs. Where and how work gets done is outside scope. +Paperclip does **not** manage full delivery infrastructure (code repos, deployments, production runtime). It tracks task-linked artifacts (for example issue documents and attachments), while implementation and deployment remain the agent's domain. ### Open Questions @@ -476,15 +480,14 @@ Each is a distinct page/route: - [ ] **Default agent** — basic Claude Code/Codex loop with Paperclip skill - [ ] **Default CEO** — strategic planning, delegation, board communication - [ ] **Paperclip skill (SKILL.md)** — teaches agents to interact with the API -- [ ] **REST API** — full API for agent interaction (Hono) +- [ ] **REST API** — full API for agent interaction (Express) - [ ] **Web UI** — React/Vite: org chart, task board, dashboard, cost views - [ ] **Agent auth** — connection string generation with URL + key + instructions - [ ] **One-command dev setup** — embedded PGlite, everything local -- [ ] **Multiple Adapter types** (HTTP Adapter, OpenClaw Adapter) +- [ ] **Multiple Adapter types** (HTTP, OpenClaw gateway, and local coding adapters) ### Not V1 -- Template export/import - Knowledge base - a future plugin - Advanced governance models (hiring budgets, multi-member boards) - Revenue/expense tracking beyond token costs - a future plugin From e186449f942fb471196983c3b62066cfc306c048 Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 06:48:58 -0500 Subject: [PATCH 2/4] docs: update adapter list and repo map accuracy - Add missing adapters (opencode_local, hermes_local, cursor, pi_local, openclaw_gateway) to agents-runtime.md - Document bootstrapPromptTemplate in prompt templates section - Update AGENTS.md repo map with packages/adapters, adapter-utils, plugins - Fix troubleshooting section to reference all local CLI adapters Co-Authored-By: Paperclip --- AGENTS.md | 3 +++ docs/agents-runtime.md | 22 ++++++++++++++-------- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dad6684f..bdfa3e5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,9 @@ Before making changes, read in this order: - `ui/`: React + Vite board UI - `packages/db/`: Drizzle schema, migrations, DB clients - `packages/shared/`: shared types, constants, validators, API path constants +- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.) +- `packages/adapter-utils/`: shared adapter utilities +- `packages/plugins/`: plugin system packages - `doc/`: operational and product docs ## 4. Dev Setup (Auto DB) diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md index bda72729..ba9bb122 100644 --- a/docs/agents-runtime.md +++ b/docs/agents-runtime.md @@ -1,7 +1,7 @@ # Agent Runtime Guide -Status: User-facing guide -Last updated: 2026-02-17 +Status: User-facing guide +Last updated: 2026-03-26 Audience: Operators setting up and running agents in Paperclip ## 1. What this system does @@ -32,14 +32,19 @@ If an agent is already running, new wakeups are merged (coalesced) instead of la ## 3.1 Adapter choice -Common choices: +Built-in adapters: - `claude_local`: runs your local `claude` CLI - `codex_local`: runs your local `codex` CLI +- `opencode_local`: runs your local `opencode` CLI +- `hermes_local`: runs your local `hermes` CLI +- `cursor`: runs Cursor in background mode +- `pi_local`: runs an embedded Pi agent locally +- `openclaw_gateway`: connects to an OpenClaw gateway endpoint - `process`: generic shell command adapter - `http`: calls an external HTTP endpoint -For `claude_local` and `codex_local`, Paperclip assumes the CLI is already installed and authenticated on the host machine. +For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine. ## 3.2 Runtime behavior @@ -66,6 +71,7 @@ For local adapters, set: You can set: - `promptTemplate`: used for every run (first run and resumed sessions) +- `bootstrapPromptTemplate`: used only on the first run of a new session (before the agent has any prior context) Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values. @@ -133,7 +139,7 @@ If the connection drops, the UI reconnects automatically. If runs fail repeatedly: -1. Check adapter command availability (`claude`/`codex` installed and logged in). +1. Check adapter command availability (e.g. `claude`/`codex`/`opencode`/`hermes` installed and logged in). 2. Verify `cwd` exists and is accessible. 3. Inspect run error + stderr excerpt, then full log. 4. Confirm timeout is not too low. @@ -166,9 +172,9 @@ Start with least privilege where possible, and avoid exposing secrets in broad r ## 10. Minimal setup checklist -1. Choose adapter (`claude_local` or `codex_local`). -2. Set `cwd` to the target workspace. -3. Add bootstrap + normal prompt templates. +1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). +2. Set `cwd` to the target workspace (for local adapters). +3. Optionally add prompt templates (`promptTemplate` and/or `bootstrapPromptTemplate`). 4. Configure heartbeat policy (timer and/or assignment wakeups). 5. Trigger a manual wakeup. 6. Confirm run succeeds and session/token usage is recorded. From 0a32e3838ada7075bb02ccb17117d49dc89b85be Mon Sep 17 00:00:00 2001 From: dotta Date: Thu, 26 Mar 2026 07:22:24 -0500 Subject: [PATCH 3/4] fix: render mention autocomplete via portal to prevent overflow clipping The mention suggestion dropdown was getting clipped when typing at the end of a long description inside modals/dialogs because parent containers had overflow-y-auto. Render it via createPortal to document.body with fixed positioning and z-index 9999 so it always appears above all UI. Co-Authored-By: Paperclip --- ui/src/components/MarkdownEditor.tsx | 88 +++++++++++++++------------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/ui/src/components/MarkdownEditor.tsx b/ui/src/components/MarkdownEditor.tsx index 342a74de..68469761 100644 --- a/ui/src/components/MarkdownEditor.tsx +++ b/ui/src/components/MarkdownEditor.tsx @@ -8,6 +8,7 @@ import { useState, type DragEvent, } from "react"; +import { createPortal } from "react-dom"; import { CodeMirrorEditor, MDXEditor, @@ -82,6 +83,9 @@ interface MentionState { query: string; top: number; left: number; + /** Viewport-relative coords for portal positioning */ + viewportTop: number; + viewportLeft: number; textNode: Text; atPos: number; endPos: number; @@ -155,6 +159,8 @@ function detectMention(container: HTMLElement): MentionState | null { query, top: rect.bottom - containerRect.top, left: rect.left - containerRect.left, + viewportTop: rect.bottom, + viewportLeft: rect.left, textNode: textNode as Text, atPos, endPos: offset, @@ -554,46 +560,48 @@ export const MarkdownEditor = forwardRef plugins={plugins} /> - {/* Mention dropdown */} - {mentionActive && filteredMentions.length > 0 && ( -
- {filteredMentions.map((option, i) => ( - - ))} -
- )} + {/* Mention dropdown — rendered via portal so it isn't clipped by overflow containers */} + {mentionActive && filteredMentions.length > 0 && + createPortal( +
+ {filteredMentions.map((option, i) => ( + + ))} +
, + document.body, + )} {isDragOver && canDropImage && (
Date: Thu, 26 Mar 2026 07:23:09 -0500 Subject: [PATCH 4/4] docs: update SPEC work artifacts and deprecate bootstrapPromptTemplate - SPEC: reflect that Paperclip now manages task-linked documents and attachments (issue documents, file attachments) instead of claiming it does not manage work artifacts - agents-runtime: remove bootstrapPromptTemplate from recommended config, add deprecation notice, update minimal setup checklist Co-Authored-By: Paperclip --- doc/SPEC.md | 4 ++-- docs/agents-runtime.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/SPEC.md b/doc/SPEC.md index 671431bb..6a7039ca 100644 --- a/doc/SPEC.md +++ b/doc/SPEC.md @@ -410,7 +410,7 @@ No separate "agent API" vs. "board API." Same endpoints, different authorization ### Work Artifacts -Paperclip does **not** manage full delivery infrastructure (code repos, deployments, production runtime). It tracks task-linked artifacts (for example issue documents and attachments), while implementation and deployment remain the agent's domain. +Paperclip manages task-linked work artifacts: issue documents (rich-text plans, specs, notes attached to issues) and file attachments. Agents read and write these through the API as part of normal task execution. Full delivery infrastructure (code repos, deployments, production runtime) remains the agent's domain — Paperclip orchestrates the work, not the build pipeline. ### Open Questions @@ -512,7 +512,7 @@ Things Paperclip explicitly does **not** do: - **Not a SaaS** — single-tenant, self-hosted - **Not opinionated about Agent implementation** — any language, any framework, any runtime - **Not automatically self-healing** — surfaces problems, doesn't silently fix them -- **Does not manage work artifacts** — no repo management, no deployment, no file systems +- **Does not manage delivery infrastructure** — no repo management, no deployment, no file systems (but does manage task-linked documents and attachments) - **Does not auto-reassign work** — stale tasks are surfaced, not silently redistributed - **Does not track external revenue/expenses** — that's a future plugin. Token/LLM cost budgeting is core. diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md index ba9bb122..f3672723 100644 --- a/docs/agents-runtime.md +++ b/docs/agents-runtime.md @@ -71,10 +71,11 @@ For local adapters, set: You can set: - `promptTemplate`: used for every run (first run and resumed sessions) -- `bootstrapPromptTemplate`: used only on the first run of a new session (before the agent has any prior context) Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values. +> **Note:** `bootstrapPromptTemplate` is deprecated and should not be used for new agents. Existing configs that use it will continue to work but should be migrated to the managed instructions bundle system. + ## 4. Session resume behavior Paperclip stores session IDs for resumable adapters. @@ -174,7 +175,7 @@ Start with least privilege where possible, and avoid exposing secrets in broad r 1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). 2. Set `cwd` to the target workspace (for local adapters). -3. Optionally add prompt templates (`promptTemplate` and/or `bootstrapPromptTemplate`). +3. Optionally add a prompt template (`promptTemplate`) or use the managed instructions bundle. 4. Configure heartbeat policy (timer and/or assignment wakeups). 5. Trigger a manual wakeup. 6. Confirm run succeeds and session/token usage is recorded.