mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents run through the native runner. Codex and Claude Code each have their own plan mode, and each produces a proposed-plan document. > - Paperclip already has a planning work mode, an issue `plan` document, and a `request_confirmation` approval gate for plans. > - These parts were not connected. The Codex proposed-plan item was transcript text only. The server path never put Codex into plan mode. Claude was never put into plan mode, and its ExitPlanMode plan was dropped. A planning run could close its task as done with no approval. > - This pull request turns a harness's own proposed plan into the issue's Plan document and the existing approval gate, for Codex and Claude. > - The benefit is that users approve or send back the agent's real plan from the task chat. Approve resumes the agent. Request changes sends the reason back to the agent. ## Linked Issues or Issue Description Refs #19252 **Subsystem affected** Native runner provider events (Codex and ACPX Claude), the runner Codex provider (Rust), server native plan synchronization, and the task chat UI. **Problem or motivation** Codex and Claude both produce a proposed-plan document in their native plan mode. Paperclip did not use it. In live tests on the server path, a Codex planning run was not in Codex plan mode, saved its own `implementation-plan` document, and marked the task done without approval. Claude planning runs were not in Claude plan mode, and the ExitPlanMode plan text never reached Paperclip. **Proposed solution** Add a canonical `plan.proposed` event for a harness's proposed plan. Put Codex and Claude into their native plan mode for planning runs. Save a completed proposal as the issue `plan` document with the existing `request_confirmation` gate. Agents can also propose a plan on a standard task; the work mode stays standard. **Alternatives considered** Reuse `plan.updated`. Its schema is the within-turn checklist and is not the durable Plan document, so a separate event keeps the two clear. Stronger prompt text without native plan mode. Live tests showed that the model kept its own document workflow. **Roadmap alignment** This reuses the issue plan document, planning work mode and approval gate that already exist. It adds one canonical provider event. ## What Changed - `packages/paperclip-runner/protocol/schemas/*`: add the `plan.proposed` event (`paperclip.plan.proposed.v1`: `proposalId`, `status`, `markdown` up to 60k characters, `source`). Regenerate the schema bundle, validators and manifest. - `packages/paperclip-runner/src/provider-events.ts`: map the Codex `plan` item and a `<proposed_plan>` block in a completed Codex message to `plan.proposed`. Add `claudePlanProposalEvent`. - `packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs`: send Codex's native `collaborationMode: plan` on `turn/start` for a read-only (planning) Codex run. Before this change the server path never sent it. - `runner-core/src/acpx_event_payload.rs`: admit `plan.proposed` as ACPX rich display activity. - `drivers/acpx/codex-runtime-adapter.ts`: set Claude Code to native plan mode for a read-only run. Capture Claude's ExitPlanMode plan from its permission request, record it, and decline the native "Ready to code?" prompt. - `drivers/acpx/codex-acpx-driver.ts`, `cli/acpx-runtime-sidecar.ts`: emit the captured proposal as a rich event. Complete that turn instead of reporting it as cancelled. - `backends/codex-native-backend.ts`: per-harness plan-mode instructions, and a short opt-in hint for Claude on standard tasks. - `server/src/services/native-runtime/native-session-executor.ts`: synchronize a completed `plan.proposed` into the `plan` document and a `request_confirmation` in planning and standard mode. Do not change the issue status during the run (that revoked the run's lease). The run finalizer turns the pending confirmation into the review wait. - `server/src/services/heartbeat-run-summary.ts`: keep a `<proposed_plan>` block out of the posted reply. - UI: new `plan_proposal` provider family. The task chat shows a live "Writing plan" card while a proposal streams and a one-line record when it completes. Resolved plan reviews keep a receipt ("Approved Plan v1", "Requested changes to Plan v1: reason"). Plan previews skip section headings. - Storybook: `Tasks and conversations/.../Task chat/Proposed plan approval` shows the journey. - `doc/SPEC-implementation.md`: describe harness-proposed plan approval. ## Verification - `cargo test -p paperclip-runner-core --lib` (new: `read_only_codex_turns_use_native_plan_collaboration_mode`) - `cd packages/paperclip-runner && npx vitest run src/provider-events.test.ts src/drivers/acpx/codex-runtime-adapter.test.ts` - `cd server && npx vitest run src/__tests__/native-plan-proposal-sync.test.ts src/__tests__/heartbeat-run-summary.test.ts` - `cd ui && npx vitest run src/components/transcript/native-run-events.test.ts src/components/task-chat` - Live test on a local worktree instance with real harnesses: - Codex (`gpt-5.6-sol`), planning task: Codex asked one question, then produced a native plan item. The task showed Plan v1 with Approve plan / Request changes and moved to in review. Approve changed the work mode to standard. Codex then implemented the plan and its tests passed. - Codex, Request changes with a reason: Codex woke in planning mode and produced Plan v2 that includes the change. - Claude (`claude-opus-5-5`), planning task: Claude was in plan mode. ExitPlanMode became Plan v1 and the turn completed. Approve resumed Claude in standard mode, and Claude implemented the plan. - Claude, standard task that asks for a plan first: Claude stopped before code changes and asked for plan approval. The work mode stayed standard. - Storybook: open `Proposed plan approval` and check each stage. ## Risks - Codex planning runs now really use Codex plan mode on the server path. Codex can ask a clarifying question before it proposes. This matches Codex plan mode. - Claude planning runs now use Claude plan mode. A declined ExitPlanMode ends the Claude turn; the runner reports it as completed. Claude's tool row for that request records a rejection from Claude's side. - Codex does not stream the proposed plan on the server path yet, so the live card shows a placeholder until the plan completes. - A `<proposed_plan>` block in any completed Codex message on a standard task now asks for approval. This is the documented opt-in path. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with tool use (shell, file edits, browser). Long context. No extended thinking mode was used. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
9.1 KiB
TypeScript
146 lines
9.1 KiB
TypeScript
/**
|
|
* Exhaustive product disposition for Paperclip Runner Protocol surfaces.
|
|
*
|
|
* This is intentionally separate from the renderer: adding a protocol event
|
|
* must be a conscious product decision even when the decision is to fold it
|
|
* into an existing turn or keep it in DevTools. The contract test compares
|
|
* these keys with the canonical JSON schemas.
|
|
*/
|
|
export type TaskProtocolDisposition = "inline" | "folded" | "debug-only";
|
|
|
|
export interface TaskProtocolSurfaceRegistration {
|
|
disposition: TaskProtocolDisposition;
|
|
surface: string;
|
|
story: string | null;
|
|
rationale: string;
|
|
}
|
|
|
|
const inline = (surface: string, story: string, rationale: string): TaskProtocolSurfaceRegistration => ({
|
|
disposition: "inline",
|
|
surface,
|
|
story,
|
|
rationale,
|
|
});
|
|
|
|
const folded = (surface: string, rationale: string): TaskProtocolSurfaceRegistration => ({
|
|
disposition: "folded",
|
|
surface,
|
|
story: null,
|
|
rationale,
|
|
});
|
|
|
|
const debugOnly = (surface: string, rationale: string): TaskProtocolSurfaceRegistration => ({
|
|
disposition: "debug-only",
|
|
surface,
|
|
story: null,
|
|
rationale,
|
|
});
|
|
|
|
const providerEvents = [
|
|
"plan.updated", "plan.proposed",
|
|
"tool.execution.started", "tool.execution.progressed", "tool.execution.completed",
|
|
"research.started", "research.progressed", "research.completed",
|
|
"delegation.started", "delegation.updated", "delegation.completed",
|
|
"model.route.changed", "model.verification.updated", "context.compacted",
|
|
"artifact.viewed", "artifact.generated", "review.mode.changed",
|
|
"hook.started", "hook.completed", "memory.citation.referenced",
|
|
"safety.review.started", "safety.review.completed", "terminal.input.sent",
|
|
"wait.started", "wait.completed", "provider.notice.recorded",
|
|
] as const;
|
|
|
|
const runnerLifecycleEvents = [
|
|
"runner.connected", "runner.reconnected", "runner.reconciled", "runner.disconnected",
|
|
"runner.draining", "runner.backpressure", "runner.suspending", "runner.suspended", "runner.stopped",
|
|
"runtime.phase.changed", "workspace.ready",
|
|
"harness.starting", "harness.ready", "harness.exited",
|
|
"session.starting", "session.started", "session.resuming", "session.resumed",
|
|
"session.reconciled", "session.updated", "session.closed",
|
|
"turn.submitted", "turn.accepted", "turn.started", "turn.completed",
|
|
"run.attached", "run.detached",
|
|
] as const;
|
|
|
|
const diagnosticEvents = [
|
|
"runner.diagnostic", "harness.diagnostic", "session.failed", "turn.failed",
|
|
"turn.interrupted", "turn.cancelled", "item.failed",
|
|
] as const;
|
|
|
|
const itemEvents = ["item.started", "item.delta", "item.completed", "usage.reported"] as const;
|
|
|
|
const mcpLifecycleEvents = [
|
|
"mcp_app.discovered", "mcp_app.resource.resolved", "mcp_app.initializing", "mcp_app.ready",
|
|
"mcp_app.host_context.changed", "mcp_app.failed", "mcp_app.teardown",
|
|
] as const;
|
|
|
|
const interactionLifecycleEvents = [
|
|
"interaction.request.proposed", "interaction.request.materialized", "interaction.request.rejected",
|
|
"interaction.response.progressed", "interaction.response.resolved", "interaction.response.delivered",
|
|
] as const;
|
|
|
|
const governanceEvents = [
|
|
"attention.request.proposed", "attention.request.routed", "attention.request.resolved",
|
|
"attention.request.expired", "attention.request.superseded", "work.assessment.recorded",
|
|
"issue.status.decision.recorded", "issue.status.decision.applied", "issue.status.decision.rejected",
|
|
"issue.status.decision.superseded",
|
|
] as const;
|
|
|
|
export const TASK_PROTOCOL_EVENT_SURFACE_REGISTRY: Readonly<Record<string, TaskProtocolSurfaceRegistration>> = Object.freeze({
|
|
...Object.fromEntries(providerEvents.map((eventType) => [eventType, inline("provider_activity", "Task Page/Runner Protocol/Provider semantics", "Provider-neutral semantic activity is readable in the task turn.")])),
|
|
"workspace.change.updated": inline("workspace_change", "Task Page/Runner Protocol/Workspace changes", "In-progress workspace changes update one diff card."),
|
|
"workspace.diff.recorded": inline("workspace_change", "Task Page/Runner Protocol/Workspace changes", "The runner-verified final diff replaces the in-progress revision."),
|
|
"workspace.file.referenced": inline("workspace_file", "Task Page/Runner Protocol/File references", "Verified references open a bounded preview and the production file viewer."),
|
|
"semantic_tool.input": folded("tool", "Semantic operations reuse the production tool row."),
|
|
"semantic_tool.result": folded("tool", "Semantic operation outcomes update the matching tool row."),
|
|
"semantic_tool.reconciled": folded("tool", "Recovered semantic operation outcomes update the matching tool row without duplicating it."),
|
|
"mcp_app.tool_input": folded("tool", "MCP inputs reuse the production tool row."),
|
|
"mcp_app.tool_result": folded("tool", "MCP outcomes update the matching tool row."),
|
|
"mcp_app.action.requested": folded("interaction", "Action requests materialize as authoritative issue-thread interactions."),
|
|
"mcp_app.action.resolved": folded("interaction", "Action resolution is shown on the authoritative interaction card."),
|
|
"runtime_request.created": inline("runtime_request", "Task Page/Runner Protocol/Runtime requests", "Pending provider runtime requests remain visible and actionable when a resolver is available."),
|
|
"runtime_request.resolved": folded("runtime_request", "Resolution updates the existing request card."),
|
|
"runtime_request.expired": folded("runtime_request", "Expiry updates the existing request card."),
|
|
"runtime_request.cancelled": folded("runtime_request", "Cancellation updates the existing request card."),
|
|
...Object.fromEntries(interactionLifecycleEvents.map((eventType) => [eventType, folded("interaction", "The control-plane interaction record is canonical and owns rendering." )])),
|
|
"run.result.proposed": inline("run_result", "Task Page/Runner Protocol/Results and terminal states", "Structured completion, evidence, verification, blockers, and artifacts remain inspectable."),
|
|
"run.result.accepted": folded("run_result", "Acceptance updates the existing result without duplicating it."),
|
|
"run.result.rejected": folded("run_result", "Rejected results remain part of run governance rather than a second completion card."),
|
|
"run.terminal": inline("run_terminal", "Task Page/Runner Protocol/Results and terminal states", "Terminal outcome and stop reason remain visible."),
|
|
...Object.fromEntries(runnerLifecycleEvents.map((eventType) => [eventType, folded("turn", "Routine lifecycle transitions are summarized by the run turn and composer state.")])),
|
|
...Object.fromEntries(diagnosticEvents.map((eventType) => [eventType, folded("system_notice", "Actionable failure text is folded into the run or system notice.")])),
|
|
...Object.fromEntries(itemEvents.map((eventType) => [eventType, folded("conversation_or_tool", "Item payloads normalize into messages, reasoning, tools, diffs, or usage." )])),
|
|
"runtime.activity.recorded": folded("task_panel", "The activated plugin view appears in the task side panel."),
|
|
"auth.credentials.updated": debugOnly("run_debug", "Credential updates notify the host and remain in run details."),
|
|
"sandbox.metric": debugOnly("run_debug", "Sandbox telemetry is available in run details, not the primary task thread."),
|
|
...Object.fromEntries(mcpLifecycleEvents.map((eventType) => [eventType, debugOnly("run_debug", "MCP application transport lifecycle remains in run details unless it produces an actionable failure.")])),
|
|
...Object.fromEntries(governanceEvents.map((eventType) => [eventType, folded("governance", "Authoritative task status, attention, and interaction records own this state." )])),
|
|
});
|
|
|
|
export const TASK_PROTOCOL_REQUEST_SURFACE_REGISTRY = Object.freeze({
|
|
"runtime.permission": inline("runtime_request", "Task Page/Runner Protocol/Runtime requests", "Permission choices render on the runtime request card."),
|
|
"runtime.input": inline("runtime_request", "Task Page/Runner Protocol/Runtime requests", "Structured runtime input renders on the runtime request card."),
|
|
"issue_thread.request_confirmation": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production confirmation card."),
|
|
"issue_thread.request_checkbox_confirmation": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production bounded checkbox card."),
|
|
"issue_thread.request_item_verdicts": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production per-item verdict card."),
|
|
"issue_thread.ask_user_questions": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production typed question controls."),
|
|
"issue_thread.suggest_tasks": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production task suggestion tree."),
|
|
});
|
|
|
|
export const TASK_PROTOCOL_RESULT_DISPOSITION_REGISTRY = Object.freeze({
|
|
done: "run_result",
|
|
blocked: "run_result",
|
|
needs_review: "run_result",
|
|
yielded: "run_result",
|
|
} as const);
|
|
|
|
export const TASK_PROTOCOL_TURN_TERMINAL_REGISTRY = Object.freeze({
|
|
completed: "run_terminal",
|
|
failed: "run_terminal",
|
|
interrupted: "run_terminal",
|
|
cancelled: "run_terminal",
|
|
} as const);
|
|
|
|
export const TASK_PROTOCOL_RUN_TERMINAL_REGISTRY = Object.freeze({
|
|
succeeded: "run_terminal",
|
|
failed: "run_terminal",
|
|
cancelled: "run_terminal",
|
|
} as const);
|