Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-24 10:13:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge current mainline into Cursor production integration

Browse Source 
Preserve qualified Cursor behavior alongside current completion feedback, runtime pins and qualification fixtures.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip committed 2026-10-05 20:14:03 -05:00
2 parents 45e34b41b7 72ff3a9f27
commit 175ca4b2a3
424 files changed
+29994 -3798
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

DESIGN.md
+27 -3
View File
@@ -43,6 +43,26 @@ action on the left and the primary action on the right. A step owns its whole
footer: do not render Save & exit in a separate parent block below it. Check this
alignment in every step and conditional state, not just the first screen.
## Mobile navigation and text fields
The fixed bottom navigation uses an opaque surface so scrolling content cannot
show through its labels. On touch devices, editable controls use at least the
16px base typography token to prevent Safari's automatic focus zoom. Larger
title sizes remain larger.
The bottom navigation responds to accumulated scrolling, ignoring small
reversals and Safari's edge bounce. It glides out and eases back in with shared
motion tokens; the task composer follows the same motion. Keep page padding
stable while the navigation moves, and honor reduced-motion preferences.
Task conversations reveal their initial comments, interaction cards, plan, and
relevant run history together after positioning the latest message. Keep the
mobile loading surface at a stable viewport height while that history loads;
concealed content must not stretch the document. Background refreshes keep an
already revealed conversation and composer mounted and visible.
Bound the initial wait to 15 seconds. If a request stalls, reveal the available
conversation and composer with a notice that some history is still loading.
## Contextual feedback
Task chat shows execution errors and waits only while they remain relevant.
@@ -72,8 +92,10 @@ rejection and revision remain available. Live tool reviews keep their own approv
Pending questions, confirmations, and other task-thread inputs appear in a separate
card directly above the ordinary composer. The composer stays available for new
messages while the card is open. Dismissing a card leaves a pending indicator that
can reopen it; resolving or skipping the input removes that indicator.
messages while the card is open. Questions use their compact history entry as the
reminder; dismissing one clears the composer and stays effective after reload for
that person and task. Other inputs keep a pending indicator that can reopen them;
resolving or skipping the input removes that indicator.
## Enforcement (what "compliant" means for the extraction run)
@@ -99,6 +121,8 @@ How-to guide for day-to-day UI changes: see `doc/design/CHANGING-THE-UI.md`.
## Motion tokens (Task Chat Redesign)
Mobile task panels fill the viewport within the safe area. Their top toolbar shows the current tab title, an open-tab count and selector, an add action, and an X to return to the feed. The selector lists tabs vertically with wrapping titles, an explicit current-tab check, and visible close controls. Each touch control uses the 44px size token. Desktop tabs keep their horizontal layout. Document links within the current task open through the router and retain the feed's reading position and query cache.
The redesigned task thread (flag `enableTaskChatRedesign`) is the first surface to
tokenize motion. Principles — reasoning only; values live in `ui/src/index.css`:
@@ -123,4 +147,4 @@ tokenize motion. Principles — reasoning only; values live in `ui/src/index.css
block collapses the duration/stagger tokens to zero, cascading to every scoped token,
in addition to each animation's own component-level guard.
Agent Chat keeps pending questions as compact “Unanswered question” entries at their original position in history. A newer user message dismisses the old question form without resolving it. Opening the history entry restores the original form and its draft; submitting later uses the same durable question response path. Actual permission reviews retain their permission checks.
Agent Chat and regular task chats keep pending questions as compact “Unanswered question” entries at their original position in history. Dismissing the form or sending a newer user message clears it from the composer without resolving it. Questions never contribute to composer pending counts or navigation. Opening the history entry restores the original form and its draft; submitting later uses the same durable question response path. Actual permission reviews retain their permission checks.
doc/DATABASE.md
+39 -6
View File
@@ -177,12 +177,14 @@ idempotent actor synchronization operations, not arbitrary transactions. A
persistent outage still fails the request after the bounded retries; each
connection attempt remains subject to the configured database connect timeout.
The dashboard's company lookup, task counts, pending approval count, and
monthly spend each retry these connection errors at most twice. Each callback
is read-only and rebuilds its query for each attempt. A failed read
does not replay completed reads or the budget workflow. Missing companies,
authentication errors, and other database errors propagate without retry.
This does not enable general SQL replay.
The dashboard's company lookup, agent and task counts, pending approval count,
monthly spend, and run activity aggregate each retry these connection errors
at most twice. The heartbeat run list and base issue lookup by UUID or identifier
use the same bounded retries. Each callback is read-only and rebuilds its query
for each attempt. A failed read does not replay completed reads, the budget
workflow, or issue label and watchdog enrichment. Missing resources,
authentication errors, and other database errors retain their usual behavior.
This does not enable general SQL replay or retry a full request.
## Execution identity row locks
@@ -450,6 +452,37 @@ Hosted AWS provider notes live in [SECRETS-AWS-PROVIDER.md](./SECRETS-AWS-PROVID
Migration `0274_agent_chat.sql` adds conversation identity/state and session generation/boundary columns to `issues`, plus idempotent client request IDs and processed session-boundary generations to `issue_comments`. The company/agent/user unique index resolves concurrent first writes to one issue. A check constraint preserves the assigned-agent identity and prevents terminal conversation status. Comment request IDs are unique per issue and user. There is no separate chat/message store. Provider sessions continue to use `agent_task_sessions`; `/new` removes only the matching conversation session, and session writers fence stale generations against the issue row.
## Resource lifecycle events
`resource_lifecycle_events` records content-free lifecycle hooks in the same
transaction as the resource change. Hired agents and new projects emit `create`.
Pending hires emit creation only when `activatePendingApproval` succeeds.
Rejected hires emit termination without creation. Agents created as terminated
emit no creation event. Capture is generic and works on self-hosted and managed
instances; recording an event does not authorize a provider operation.
A partial unique `(company_id, resource_type, resource_id)` index deduplicates
creation. Each actual agent pause, resume, or termination appends another event,
including budget actions and generic status updates. The agent row stays locked
until status and event commit, so concurrent repeat requests emit one hook.
Termination commits API-key revocation in that same transaction.
Hire approval and rejection commit with agent activation or termination, so a
failed event write leaves the decision pending and retryable.
The numeric event ID orders transitions for a resource. Future plugin delivery
must enforce company scope, preserve resource order, and track acknowledgments
per plugin. A global high-water mark can skip transactions that have not yet
committed; it is not a safe delivery cursor. The journal stores only identity,
action, and timestamps, not repository snapshots, credentials, provider config,
or resource health. Company deletion cascades to its events. Resource deletion
retains events, so consumers must revalidate existence and eligibility and load
current authorized repository data. A termination hook does not authorize
removing persistent VM or project data.
The migration creates an empty table. It does not scan or backfill existing
installs. Plugin delivery, retention, retries, and provider integration are
separate work. This change makes no provider calls and adds no plugin read API.
## Legacy controller ownership
Legacy run claims atomically record `controller_boot_id`, a database-clock
doc/DEVELOPING.md
+70
View File
@@ -103,6 +103,12 @@ pnpm build-storybook
These run the `@paperclipai/ui` Storybook on port `6006` and build the static output to `ui/storybook-static/`.
**Composer → New task** includes agent/user/project/task mentions, skill and
routine slash commands, and populated rich chips on desktop and mobile. Agent
mentions use the same avatars in suggestions, inserted chips, and the mocked
creation receipt. The creation stories preserve the original Markdown references;
they do not create real tasks or run agents.
Use **Components → Agent setup prompt** to review the shared setup handoff:
hover/focus logo motion, one-click copying with a prompt preview, animated
confirmation, and manual-copy recovery. Opening the preview copies immediately;
@@ -140,6 +146,47 @@ choices, item verdicts, suggested tasks, tool reviews, runtime questions, and ph
the bottom navigation. The normal message composer remains usable below the
pending card.
Use **Chat & Comments → Task Chat Unanswered Questions → Test Drive** to
try a regular task question: dismiss it, reload, reopen its compact feed entry,
and submit the preserved draft. The composer has no question pending badge.
The demo uses real thread/form components with fixture response callbacks.
The Agent Chat stories share the same component fixture.
Use **Composer → New task** to review task creation through the production
`TaskChatComposer`. The editor, file menu, work modes, assignee/model picker,
and send control are shared with task chat. An inset bar above the composer uses
the queued-message container and holds Project on the left. Its searchable picker
shows project colors. Worktrees sits beside Project when the selected project has
isolation enabled. Choose a new worktree, reuse an eligible worktree from that
project, or keep the shared project workspace. Reuse carries the worktree's source
checkout, including a non-primary checkout. Changing projects clears the
previous worktree choice. Switching from reuse to a new worktree or the project
workspace restores the project default checkout. Task creation uses the selected company and has
no separate heading or settings control.
Fresh tasks start with an empty request and the last task assignee chosen in that
company, including a human. If that assignee is unavailable, the CEO is the
default, or the first eligible agent when the company has no CEO. Explicit launch
assignees and saved drafts keep their selection. Selecting an assignee never
inserts a mention. Clicking the assignee opens its searchable list directly;
model and effort have a separate trigger and appear only for agents whose
harness supports those settings.
Fresh tasks also keep the company's last project (including No project); launch
context and saved drafts take precedence. New projects receive a random palette
color and become the remembered project. The shared composer remembers the last
effort within the company and applies it only when the selected model supports
that level. Explicit task overrides and drafts take precedence. Default model
labels show the configured or known adapter model, otherwise simply Default.
Claude defaults supplied by the server's host environment remain Default unless
the agent explicitly configures the model. Project edits on an existing task
become the remembered project only after the task update succeeds.
Clicking or tapping outside either selector dismisses it and preserves the task
draft and selections. Mobile sheets return focus to the trigger without reopening.
Stories cover empty and prefilled drafts, remembered, human, and unassigned
selections, the direct assignee picker, sub-tasks, planning, files, saving,
retryable failures, creation, light theme, and mobile, plus worktree reuse,
loading, empty, error, and isolation-disabled states. Story submissions use local
fixtures and never start an agent.
Use **Composer → Model and effort picker** to review harness-specific model
choices. Codex uses the curated adapter catalog unless the instance declares
`PAPERCLIP_ADAPTER_MODELS`; general OpenAI API models are not Codex choices.
@@ -1216,6 +1263,29 @@ the updated sandbox image with the matching runner qualification changes.
### Native runner restart recovery
Project discovery through `list_projects` returns up to 50 compact summaries.
It uses `GET /api/companies/:companyId/projects?view=summary&limit=50&cursor=...`;
the cursor is optional. The database reads bounded summary projections. Agent
and run trust boundaries narrow database candidates before per-project access
checks. Projects with their own authorization policy remain candidates because
that policy can contribute scope; every result still passes the full access check.
Only visible projects determine page boundaries and continuations.
The default project-list API response remains unchanged.
Use its `nextCursor` as the next call's `cursor` until it is null; `limit` accepts
1–50. Descriptions include at most 1,000 characters and an explicit truncation
flag. Full project records remain available through the authorized project API.
Workspace configuration is excluded from discovery responses so large projects
cannot overflow the runner's durable tool-result command limit.
When an accepted result survives a shutdown failure, workspace repair uses a
new assessment for the repaired workspace state. Its status decision and
assessment reference commit together. Recovery completes from the saved result
without another provider turn, clears stale successful-run errors, and retains
the original error in `recoveredExecutionFailure`. Exact-state session cleanup
recognizes both the legacy `adapter_failed` and current `provider_transport_failed`
close-failure labels. Process ownership, pending tool outcomes, and checkpoint
verification still control whether that session can be reused.
Paperclip Runner keeps its heartbeat run, native session, logical runner, and
provider session identities across server restarts. A coordinated hot restart
registers a correlated recovery request before it signals the dev supervisor.
doc/PRODUCT.md
+21 -5
View File
@@ -209,10 +209,26 @@ telemetry. See [Announcements](ANNOUNCEMENTS.md).
### Agent chat discovery
With Agent Chat enabled, the Chats sidebar always includes the company's
earliest-created agent, plus personal starred agents and up to four other recent
conversations. First use has the same compact rows as returning use. The compose
icon shares a column with stars and appears on hover or keyboard focus (always on
touch). It opens a company-wide name/role search, independent of sidebar membership.
With Agent Chat enabled, Chat is the first row of the Work section and opens a
secondary sidebar beside the primary nav. It lists every agent you can chat
with: the open conversation first, then your other conversations by recent
activity, then the rest of the roster alphabetically. Terminated agents and
agents you have left are omitted unless you have history with them. Search
filters by name, title, or role; **+** starts or reopens a conversation.
Selecting an agent opens their persistent conversation; it does not reset history
or create a task until the existing first-write flow requires one.
Beside a conversation, the side panel opens on the agent's tasks: one card per
task the agent created, was assigned, commented on, or acted on, newest first,
with the task list's filters and a sort control. The agent's artifacts are a
second card stack available from the panel's **+** menu. Both open in a new tab
so the conversation stays open.
### Combined Inbox + Task List
An opt-in experimental setting (`enableCombinedInboxTasks`, off by default)
folds Inbox into Tasks. The Inbox nav row goes away and its unread badge moves
to Tasks. A Views menu on the task list covers the inbox views (Mine, Unread,
Blocked, Recent, Everything) and the task-status views (All, Active, Backlog,
Done). Bare `/issues` opens the last-used view, defaulting to Mine; links that
carry a task filter open All. Old `/inbox` links redirect to the matching view.
doc/SPEC-implementation.md
+19
View File
@@ -1502,6 +1502,13 @@ Required UX behaviors:
- conflict toasts on atomic checkout failure
- no silent background failures; every failed run visible in UI
Regular task chats and Agent Chat keep unanswered questions as compact,
reopenable entries at their original position in the feed. Dismissing a question
or sending a newer message clears its form from the composer without resolving
the saved question. Questions do not contribute to composer pending counts.
Dismissal persists locally for the person and task across reloads; reopening
restores the original form and draft. Approval and permission gates are unchanged.
## 15. Operational Requirements
## 15.1 Environment
@@ -1899,3 +1906,15 @@ unavailable. Preserve current ownership and newer-work fences. See
endpoints delegate to sources while retaining response shapes.
- GitHub.com, manual refresh only. No upstream editing, polling, webhook sync, commits,
or pull-request creation in this milestone.
### Connection instructions
Connections can store optional, versioned agent instructions independently of
provider and transport. Catalog templates control editor visibility; saved
settings and runtime delivery also support connections without a template.
The server includes instructions only when the connection and at least one
action are available to the run's agent and responsible identity. An immutable
per-turn snapshot participates in session compatibility, so subsequent turns
remove stale instructions after edits or access revocation. See
[Connection instructions](connections/CONNECTION-INSTRUCTIONS.md) for contracts,
UI conventions, custom adapter integration, and initial memory templates.
doc/SPEC.md
+1 -1
View File
@@ -299,7 +299,7 @@ should name the rejected action and the specific restriction.
There is no separate messaging or chat system. Tasks are the communication channel. This keeps all context attached to the work it relates to and creates a natural audit trail.
Experimental Agent Chat presents one persistent task per person and agent as a simplified conversation. Chat has a searchable secondary sidebar with agent avatars; adding an agent starts or reopens their single conversation. It retains the task composer, transcript, tools, attachments, documents, and existing Subtasks panel, with ordinary company visibility. New execution tasks are ordinary project tasks, not children of the conversation. Idle conversations wait for a message without entering execution-task work queues. Agents clarify goals here and create assigned tasks for substantial execution. `/new` resets provider context at an ordered session boundary within the same task while preserving visible history. `enableAgentChat` is disabled by default; the V1 lifecycle and rollout contract is specified in `SPEC-implementation.md`.
Experimental Agent Chat presents one persistent task per person and agent as a simplified conversation. Chat has a searchable secondary sidebar with agent avatars that lists every eligible agent, conversations first; adding an agent starts or reopens their single conversation. It retains the task composer, transcript, tools, attachments, documents, and existing Subtasks panel, with ordinary company visibility. New execution tasks are ordinary project tasks, not children of the conversation. Idle conversations wait for a message without entering execution-task work queues. Agents clarify goals here and create assigned tasks for substantial execution. `/new` resets provider context at an ordered session boundary within the same task while preserving visible history. `enableAgentChat` is disabled by default; the V1 lifecycle and rollout contract is specified in `SPEC-implementation.md`.
### Question recipients
doc/adapter-model-audit-2026-10-02.md
+93
View File
@@ -0,0 +1,93 @@
# Adapter model and harness audit: October 2, 2026
This audit follows the [September 22, 2026 audit](adapter-model-audit-2026-09-22.md).
It covers model selection in the coding-agent adapters and the shared harness
pins in the runner, the provider pack, and the evaluation image. Catalog
entries identify models; provider accounts and installed CLIs determine access.
No agent defaults or saved model selections are migrated.
## Model changes
| Adapter | Changes from the audit |
| --- | --- |
| Codex and the Codex runner catalog | Add GPT-6.1 Sol (`gpt-6.1-sol`). Expose efforts through Ultra and Fast mode, as documented. Keep `gpt-5.6-sol` as the default. |
| Claude on Bedrock | Add Sonnet 5.5 (`us.anthropic.claude-sonnet-5-5`), using the catalog's existing US inference-profile convention. Sonnet 5.5 IDs (direct or Bedrock-qualified) get the documented `xhigh` and `max` efforts and require Claude Code 2.1.284 or later on the CLI lane. |
| OpenCode | Add `openai/gpt-6.1-sol` and `anthropic/claude-sonnet-5-5` to the static fallback used by remote environments. Both IDs are present in the OpenCode model registry. |
| Claude Code (direct) | No change in this audit. [#14993](https://github.com/paperclipai/paperclip/pull/14993) (merged October 5, 2026, superseding #14816) adds Sonnet 5.5 (`claude-sonnet-5-5`, Claude Code 2.1.284 or later) and refreshes the Claude runtime. |
| Grok Build, Gemini CLI, Kimi Code, Cursor | No new verified model IDs. Grok 4.7, Gemini 3.8 Flash, and Kimi K3 remain the newest documented models. |
## Harness changes
| Harness | Before | After |
| --- | --- | --- |
| Codex CLI (shared provider pack) | 0.156.0 | 0.160.0 |
| OpenCode (shared provider pack) | 1.18.32 | 1.18.34 |
| Grok CLI (`@xai-official/grok`) | 1.0.41 | 1.0.46 |
| Gemini CLI | 0.60.0 | 0.62.0 |
| Kimi Code CLI | 2.0.2 | 2.1.1 |
| Cursor CLI | 2026.09.18-9a7762b | 2026.10.01-e373342 |
| GitHub CLI | 2.101.0 | 2.102.0 |
| Claude Agent SDK / Claude Code | 0.3.280 / 2.1.280 | 0.3.286 / 2.1.286 via #14993 (merged); this branch keeps that pin |
| Hermes | 0.19.0 | 0.19.0 (current) |
| ACPX, `claude-agent-acp`, `codex-acp` bridges | 0.13.1 / 0.73.0 / 1.6.2 | Unchanged; separately qualified |
| Pi (`@earendil-works/pi-coding-agent`) | 0.87.1 (fleet image) | Unchanged; Pi 1.0 is qualified upstream in the Pi runner stack |
The remote Codex compatibility window moves to `>=0.149.0 <0.161.0`. The
minimum stays fixed. See
[paperclip-runner-compatibility.md](architecture/paperclip-runner-compatibility.md).
## Sources and verification
- [OpenAI's Codex model guide](https://learn.chatgpt.com/docs/models) lists
GPT-6.1 Sol (`gpt-6.1-sol`) with reasoning efforts from Light to Ultra and
Standard and Fast modes at launch. The bundled Codex 0.160.0 model metadata
also contains `gpt-6.1-sol`. The same page records that `gpt-5.4` and
`gpt-5.4-mini` retired from Codex with ChatGPT sign-in on August 31, 2026,
and that `gpt-5.5` retires from Codex with ChatGPT sign-in on October 14,
2026. Neither retirement applies to the OpenAI API, so the picker keeps
those IDs for API-key users; see "Deferred items".
- [Codex CLI releases](https://github.com/openai/codex/releases) 0.157.0
through 0.160.0 add GPT-6 Sol and Luna metadata, app-server pagination, and
authoritative provider catalogs. The Linux x64 executable digest comes from
the integrity-verified `@openai/codex@0.160.0-linux-x64` archive.
- [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)
documents the Bedrock ID `anthropic.claude-sonnet-5-5` and the September 28,
2026 release. The [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
entry for 2.1.284 adds `claude-sonnet-5-5`, so that version is the CLI minimum. [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview)
lists `xhigh` and `max` effort support for the 5.5 generation.
- [OpenCode releases](https://github.com/anomalyco/opencode/releases)
1.18.33 and 1.18.34 contain fixes only. The OpenCode model registry at
models.dev lists both added provider-qualified IDs.
- Grok CLI 1.0.46 is the `latest` tag on npm. [xAI's model list](https://docs.x.ai/docs/models)
still ends at Grok 4.7. Gemini CLI 0.62.0 and Kimi Code 2.1.1 are the
`latest` tags on npm; [Google's model catalog](https://ai.google.dev/gemini-api/docs/models)
and [Kimi's model page](https://www.kimi.com/code/docs/en/kimi-code/models.html)
list no newer coding models.
- Cursor CLI 2026.10.01-e373342 is the version the official installer
resolves; the pinned archive digest comes from the versioned tarball, and
the extracted binary reports that version. [Cursor's catalog](https://cursor.com/docs/models-and-pricing)
shows new Grok 4.7 500k and Kimi K3 rows without exact CLI IDs, so no
fallback IDs were added.
- [GitHub CLI 2.102.0](https://github.com/cli/cli/releases/tag/v2.102.0)
contains security fixes for download commands. The pinned digest matches the
release `checksums.txt`.
- [Hermes on PyPI](https://pypi.org/project/hermes-agent/) remains at 0.19.0.
## Deferred items
- `gpt-5.4` and `gpt-5.4-mini` stay in the Codex picker because the OpenAI API
still serves them. A later audit can remove them once API retirement is
published or operators confirm no API-key agents depend on them. `gpt-5.5`
needs the same review after October 14, 2026.
- The ACP bridges (ACPX 0.19.4, `claude-agent-acp` 0.85.1, `codex-acp` 2.1.1)
are newer upstream. They carry reviewed patches and qualified executable
digests, so they need a separate qualification campaign rather than a pin
bump. ACPX 0.15.1 and 0.17.0 also change message limits and session
journal records.
- Pi 1.0.0 is published, but the runner's Pi profile and the fleet image stay
on the qualified 0.84.2 / 0.87.1 pins until the Pi 1.0 runner stack lands.
- The native Grok runtime (`native:grok` 1.0.13) is bound by a qualified
profile digest and is not refreshed by this audit.
- Claude Mythos 5.1 remains invitation-only with no public selectable ID.
- Cursor's exact IDs for Grok 4.7 500k, Kimi K3, and GLM 5.3 are not shown
in the documentation and the unauthenticated CLI returns no list.
doc/architecture/paperclip-runner-compatibility.md
+11 -5
View File
@@ -46,15 +46,15 @@ would hide the runtime that executed the task.
## Remote Codex version window
Remote native Codex runs accept stable CLI versions **`>=0.149.0 <0.157.0`**.
The install pin remains `0.156.0`. A sandbox image can therefore use an older
Remote native Codex runs accept stable CLI versions **`>=0.149.0 <0.161.0`**.
The install pin is `0.160.0`. A sandbox image can therefore use an older
compatible Codex without failing startup or installing another copy.
The minimum is fixed at **`0.149.0`** until maintainers deliberately change it.
It is not a rolling one-month support window. The official
[`@openai/codex` publication history](https://registry.npmjs.org/@openai/codex)
records `0.149.0` on 2026-08-20, `0.153.4` on 2026-09-04, and `0.156.0` on
2026-09-22. See also the [Codex changelog](https://learn.chatgpt.com/docs/changelog).
records `0.149.0` on 2026-08-20, `0.153.4` on 2026-09-04, `0.156.0` on
2026-09-22, and `0.160.0` on 2026-10-01. See also the [Codex changelog](https://learn.chatgpt.com/docs/changelog).
This is an explicit compatibility window, not a claim that every Codex minor
release follows a backward-compatible protocol.
@@ -65,7 +65,7 @@ release follows a backward-compatible protocol.
- The same check applies to discovered, explicitly staged, and npm-installed
remote Codex executables, including the final executable after linking.
- For an incompatible image, the existing
`PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC=@openai/codex@0.156.0` configuration
`PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC=@openai/codex@0.160.0` configuration
allows installation of the pinned runtime. Without that configuration,
startup reports the supported range and the remediation.
- Runner binary contracts, required runner capabilities, artifact digests,
@@ -85,6 +85,12 @@ app-server binaries with a local deterministic Responses API fixture. Both
passed initialization, thread creation with a dynamic tool, a tool-call/result
round trip, turn completion, and thread resume. This verifies the tested
protocol path; it is not a live model, Linux sandbox, or exhaustive feature test.
The 2026-10-02 refresh moved the install pin and the upper bound to `0.160.0`
after verifying the integrity-checked Linux x64 `0.160.0` executable digest and
the installed ACP package contract. Codex `0.157.0` through `0.160.0` add the
GPT-6.1 Sol catalog entry and app-server pagination without a documented
app-server protocol break; the Linux CI qualification workflow covers the real
startup and session-resume probes for the new pin.
Version-boundary and remote artifact-preparation regressions are covered by
`codex-runtime-compatibility.test.ts` and `native-session-executor.test.ts`.
doc/connections/CONNECTION-INSTRUCTIONS.md
+120
View File
@@ -0,0 +1,120 @@
# Connection instructions
Connection instructions are an optional, provider-independent capability. A saved
connection can contribute a short paragraph to an authorized agent’s execution
prompt. Memory providers are the first catalog templates; custom and non-memory
connections use exactly the same settings, authorization, and delivery path.
## Catalog and saved settings
A connector can declare `agentInstructions: { id, version, text }` in its
`AppDefinition`. Author reviewed defaults directly in that app's
`packages/shared/src/app-definitions/<slug>.json`, alongside its configuration
and supporting provider `docsUrl`. This field is the source of truth; there is
no separate template registry. Catalog ingestion validates and preserves it,
including edits or removal, when regenerating the other definition fields. Run
`node scripts/ingest-app-definitions.mjs --definitions-only` to verify. Template
text is limited to 2,000 characters. Remote MCP initialization prose is never
adopted as trusted instructions automatically.
Every `ToolConnection` has nullable `agentInstructions`:
```json
{
"enabled": true,
"text": "Use the release handbook before changing a deployment. Cite the checklist.",
"template": { "id": "handbook.usage", "version": 1 }
}
```
The template provenance is optional. Authorized custom instructions can be saved
without a catalog template. `null` means no instructions. Disabling retains text
and tool access. New catalog connections persist the current default enabled;
the initial migration backfills existing connections for the five participating
providers. A reconnect, OAuth return, or catalog refresh retains saved settings.
Catalog version changes do not replace custom text or opt-outs. **Reset to
default** explicitly adopts the current template and preserves the toggle.
Existing connect, finish, and connection PATCH requests accept the same nullable
setting. Mutations use connection configuration permissions and company checks,
and write activity records. Required provider configuration lives in
`config.methodConfig`, independently of instruction text and enabled state.
## UI convention
The editor appears only when explicit template metadata exists. Setup (including
inline setup and OAuth) uses the current flow, without another wizard step. The
Permissions page places **Agent instructions** after agent access and before
Actions. It shows **Tell agents to use {provider}**, visible text, editing,
**Reset to default** after changes, and an amber notice when off. Failed saves
retain the draft. Agent Instructions includes a read-only **From connections**
section with source links and an explanation of task-dependent availability.
Disabled instructions remain inspectable there with an amber notice.
## Runtime delivery and compatibility
The gateway resolves instructions using the stored run’s company, agent, task,
project, active responsible identity, connection grants, and effective action
policy. At least one tool must be available (including tools requiring approval).
The resolver uses persisted settings and the cached catalog; it does not contact
providers. It does not gate delivery on a provider name, memory category, or the
presence of a catalog template.
Prompt assembly checks access to candidate connections’ cached tools directly,
using the same task restrictions and policy decisions as discovery. It does not
enter the discovery queue, so queue saturation neither drops guidance nor replaces
an otherwise compatible session. Revocation is still checked on every turn.
Eligible blocks are sorted by connection ID. Each block identifies its
connection, selected grant, optional template provenance, and declared public
configuration. Secret/password fields are excluded. Missing required public
configuration withholds standing instructions. The snapshot is `{ text, digest }`,
where `digest` is SHA-256 of the complete UTF-8 text. Declared public configuration and
source changes therefore change the digest as well as text edits.
The server replaces caller-supplied runtime instruction fields before executing.
Native Runner receives the snapshot in `runtimeContext.connectionInstructions`
and composes it alongside agent instructions. Legacy adapters receive it through
shared wake-prompt composition on fresh and resumed turns. Session compatibility
includes the snapshot: changing or removing it replaces an incompatible session,
including when live tool refresh would otherwise retain that session. Active
turns retain the snapshot with which they started. Older native snapshots without
this field remain valid. No AGENTS.md or shared harness home is modified.
Custom integration contracts:
- **HTTP adapter:** the JSON request contains top-level `connectionInstructions`
(`{ text, digest }` or `null`), also available on invocation `context`.
This server-owned field overrides `payloadTemplate`. Append its text alongside
agent instructions before invoking a model; do not reuse a session with a
different digest.
- **Process adapter:** `PAPERCLIP_CONNECTION_INSTRUCTIONS_FILE` points to a private
JSON file containing the same snapshot. Read it during the invocation and
append `.text` to your model prompt. It is empty when no instructions apply.
Configured or inherited paths cannot override it. The temporary file is removed
when the process exits, including failure paths.
Instruction guidance grants no new permissions. Approval requirements remain
attached to tool calls, and remembered content does not override the current task.
Provider memory scope follows the provider’s real configuration; Paperclip does
not claim isolation from invented agent IDs or tags.
## Honcho configuration
Honcho requires `config.methodConfig.workspaceId` for new setup. The field is
expanded above instructions, with validation beside it. For tools declaring a
`workspace_id` argument, the existing managed-argument mechanism projects the
configured workspace after caller arguments and removes the field from the
agent-visible schema. Pending approvals compare against the current projected
arguments, so changing the workspace invalidates the old approved invocation.
Existing connections missing a workspace retain their tools and manual workspace
arguments, but receive no standing guidance until configured.
## Verification
`server/src/__tests__/connection-instructions.test.ts` persists a non-memory
fixture, resolves effective access, captures a real process invocation, and checks
shared/native prompt composition. Route tests cover permissions and OAuth draft
preservation. Session tests cover edits/removal and incompatible resumes.
Storybook uses production components backed by stateful mock APIs, including
Notion with and without explicit templates. Model behavior evaluations and new
agent/company memory scope controls are deferred.
doc/connections/CONNECTOR-PLAYBOOK.md
+214 -5
View File
@@ -122,6 +122,7 @@ read/write proof separately and never describe metadata discovery as live proof.
- [Current access defaults](#current-default-access-policy)
- [Golden-path agent tutorial](#golden-path-agent-tutorial)
- [Connection UX and user journeys](#connection-ux-and-user-journeys)
- [Optional agent instructions](#optional-agent-instructions)
- [Chat and email connector UX](./CHAT-CONNECTOR-UX.md)
- [Production validation evidence](#step-9-align-with-production-validation)
- [AppDefinition field reference](#appdefinition-field-reference)
@@ -147,6 +148,59 @@ A complete connector proposal produces:
denied/quarantined call when the method declares one, revoke, and audit
evidence.
## Optional agent instructions
Some connections need standing guidance: tools tell an agent what it *can* do,
while a short paragraph explains when it should use them. Memory is the first
use case. See [Connection instructions](CONNECTION-INSTRUCTIONS.md) for the
generic catalog metadata, saved settings, API, runtime, and integration contracts.
**Design explorations → Connections → Agent instructions** in Storybook uses
production components with mocked APIs.
When adding a template:
- Show the section only when the connector explicitly provides a nonempty
instruction template. Use **Agent instructions** and the checkbox
**Tell agents to use {provider}**, with the exact paragraph visible. No template
means no instructions UI, including no blank editor.
Keep setup in the existing flow and its single footer; add no required test or
extra wizard step. Use the current shared access defaults/disclosure.
- Use a reviewed, versioned provider-specific suggestion. Explain when to recall,
when to save, the allowed context, and what to do if a call fails. Prefer one
short paragraph over a full skill or a pasted tool catalog. Avoid unsupported
promises about hooks, automatic transcript capture, or private memory.
- Default provided instructions on for every participating connector. Let users
edit, **Reset to default** after changes, or disable guidance while retaining
tools. Show a compact amber notice when off. Reconnect and catalog refresh
preserve explicit opt-outs and custom text. Omit suggestion attribution badges
and routine lifecycle/storage helper copy.
- Edit in an optional **Agent instructions** section of the existing **Permissions**
page, between agent access and Actions. Use the actual connection page shell,
credential form, and footers in review stories; include a baseline story for
comparison rather than constructing parallel page chrome. Show recipients
from current assignments and a read-only, source-linked copy on the agent.
Keep action controls and tests in the existing **Permissions** screen.
- Resolve runtime guidance with the same company, agent, task, responsible-user,
and grant checks used for tools. Compose a revisioned block alongside agent
instructions; never permanently edit AGENTS.md or shared harness home files.
Verify fresh and resumed turns, removal, revoked access, and unsupported adapters.
- Keep required provider settings, such as Honcho workspace, expanded near the
top of setup and configuration, above instructions. Put validation beside the
field and block completion while required values are missing. Memory stays an
ordinary connection; do not add a default-memory chooser or agent preference.
Keep provider binding identifiers separate from editable prose. Agent IDs,
tags, and query filters alone are not access-control boundaries. Any promised
isolation needs server enforcement across all relevant tool paths.
- Treat MCP initialization instructions as external provider content. Review
them as template source; do not silently inject arbitrary remote text or let
a provider update overwrite an operator's instructions. Guidance never grants
additional tool permissions.
- Prove both delivery and behavior: deterministic assignment/resume checks, then
a bounded save → **fresh session** recall with synthetic data through the real
run gateway. Record exact model/template/catalog versions, tool receipts,
costs, ingestion timeout, and cleanup. Discovery and a model's “saved” reply
do not prove memory works. See the linked plan for the minimal matrix.
## Use This Document As The Checklist
An agent implementing a connection should be able to begin with only a provider
@@ -158,7 +212,7 @@ The shortest valid implementation usually changes these files:
```text
scripts/ingest-app-definitions.mjs # human-authored definition source
packages/shared/src/app-definitions/<slug>.json # generated definition
packages/shared/src/app-definitions/<slug>.json # definition with app-owned instruction template
packages/shared/src/app-definitions.generated.ts # generated registry
ui/public/brands/apps/<slug>.svg # official, sanitized mark
ui/public/brands/apps/manifest.json # runtime branding paths
@@ -648,7 +702,7 @@ controls and precise labels over explanatory paragraphs. Remove repeated
headings, redundant access summaries, implementation details, and reassurance
that does not help the user decide or act. Keep necessary warnings, meaningful
consequences, and actionable errors. Put optional expert settings under a
collapsed Advanced disclosure. Link to provider-owned administration, such as
collapsed disclosure through **Change**. Link to provider-owned administration, such as
AgentMail allowlists, rather than rebuilding it in Paperclip.
**Keep ongoing interactions in Paperclip tasks.** Connections are where users
@@ -708,7 +762,13 @@ definitions and visible manifest entries to match exactly.
### Phase 5: Author the definition at the durable source
The checked-in provider JSON files are generated. Do not edit one and stop.
Transport/auth fields in the checked-in provider JSON files are generated. Do
not edit those fields and stop. Optional `agentInstructions: { id, version, text }`
templates are authored directly in each app's JSON definition, alongside its
supporting `docsUrl`. Ingestion validates and preserves that field; edit or
remove it there, and increment its version when changing the default. There is
no central instruction-template registry. See
[Connection instructions](./CONNECTION-INSTRUCTIONS.md) for the runtime contract.
1. Add or update the provider in `scripts/ingest-app-definitions.mjs`.
2. Update `packages/shared/src/self-serve-mcp-research.json` when it belongs to
@@ -1511,11 +1571,16 @@ The operator should see Apps, Connections, and Review language. Keep protocol la
Request only the documented scope set the reviewed connection needs; never
adopt every scope returned by discovery. Operators should not have to predict
every future tool during setup. Keep the default view to the minimum inputs
needed for a working connection, fold optional expert controls under one
collapsed **Advanced** disclosure, and enforce execution afterward through
needed for a working connection, fold optional expert controls under the
**Change** link beside the access summary, and enforce execution afterward through
Paperclip's resource boundaries, risk classification, tier defaults, optional
quarantine, and audit.
When a provider supplies its MCP endpoint, keep that URL out of the initial
form. Composio exposes it through **Reuse an existing session** for operators
with a custom session URL; resumed custom endpoints and URL validation errors
keep the field visible. Preserve the endpoint when its disclosure is closed.
### Step 8: Apply Governance Defaults
Governance is automatic because every catalog entry becomes a normal tool-access object:
@@ -2326,3 +2391,147 @@ in-memory provider responses. The `provider-native`, `provider-decline`, and
`provider-second` Product E2E cases exercise native preference, persisted choice,
restart recovery, and an independently observed gateway read. They do not prove
compatibility with the real external providers.
### Public aggregator apps in Connectors
The Connectors catalog combines native definitions with the public Composio and
Arcade app snapshots in `packages/shared/src/aggregator-app-catalog.ts`. Native
definitions always take precedence, including definitions temporarily hidden or
unavailable on the instance. Each remaining app has one card with its provider
logos; Connect opens a provider picker when multiple providers support the app.
An app with one provider goes directly to setup or its saved gateway flow.
Search covers names, aliases, providers,
and saved accounts. The uninstalled catalog uses pages of 50 entries; matching
installed connectors remain above every page. Listing an upstream app never
creates a Paperclip connection or marks that app authorized.
Provider filters include native cards only when they contain accounts managed
by that provider. A matching public catalog entry alone does not include a
native card; its native onboarding remains in Paperclip and All.
Composio app setup offers a dropdown of connected Composio accounts and an option
to connect a new one. The board calls `COMPOSIO_MANAGE_CONNECTIONS` directly to
check the requested toolkit and generate its hosted authorization link. This
creates no task and starts no agent run. An already active app skips new link
creation. After the human signs in, completion checks the toolkit's ACTIVE
account status again. New gateways default to all humans and all agents; app
setup preserves the selected gateway's saved access and tool policies without
adding agent-specific grants. Access remains gateway-wide, not app-level
isolation. Saved credentials are resolved for the acting human and authorization
URLs stay outside audit/result storage. A failed or uncertain add is never
retried automatically; the user can explicitly request a new link.
Composio is authoritative for app accounts and authorization. Paperclip stores
only account observations in `tool_connection_app_snapshots`: IDs, aliases,
statuses, default flags, check times, and failure times. Observations are scoped
to company, saved gateway, viewing human, and credential identity, including
secret versions. Credential replacement or rotation hides the old inventory.
Discovery and app setup never create agent grants or change saved policies.
Apps starts a background check of the entire supported public Composio catalog,
independent of search and pagination. `POST /tool-connections/:id/composio/apps/sync`
returns cached observations and sync progress; `{force:true}` requests a refresh.
`tool_connection_app_syncs` holds a per-credential lease and progress. Repeated
visits and concurrent tabs share the lease. Checks use explicit `action:list`,
batches of 32, a four-minute deadline, and five-minute freshness. Known accounts
are checked first. Polling updates account rows while browsing stays usable.
Manual **Refresh Composio** belongs in the saved Composio account's kebab menu;
it checks that account only. Do not add a catalog-wide refresh button.
Composio gateway setup finishes on its Permissions page. That page lists detected
apps in a bounded, scrollable list and starts a refresh on first load. Its
**Refresh Composio** button shows catalog-check progress and refreshes only that
gateway. The same connected-app list and refresh controls serve Arcade and
Executor gateways when discovery is available. Executor remains available as a
connection, but its catalog filter chip is temporarily hidden.
A complete empty list removes an observed account; EXPIRED accounts show Needs
sign-in. Failed or incomplete evidence retains the last accounts, visibly
unverified, and offers retry. Interrupted jobs can be restarted after the lease
expires. A late response cannot replace a newer check or a changed credential.
The saved Connect MCP OAuth credential supports listing accounts by toolkit;
it is not a consumer user API key or a developer project API key. This discovery
covers the supported public catalog, including toolkit variants. It does not
claim complete enumeration of custom apps outside that catalog. A future
identity-bound inventory endpoint should replace this scan when available.
Never forward an MCP OAuth token to an unrelated REST inventory endpoint.
Imported accounts appear above the paginated catalog with their actual source:
**Via “saved connection name”**, rather than attributing upstream authorization
to the gateway creator. Already connected Composio accounts remain visible even
when Paperclip has a native connector; native Connect offers still take
precedence. Imported account menus offer only **Open in Composio**. Access
controls remain on the saved gateway and apply to all apps on that connection.
The Manage dialog displays provider observations
and links to Composio; it does not offer local rename or upstream removal.
Use `https://dashboard.composio.dev/~/org/connect/apps` for Connect app management.
The organization placeholder resolves to the signed-in user's For You area.
The bare dashboard opens Platform developer projects, which have a separate
account inventory and are the wrong destination for saved Connect MCP accounts.
Remove connection remains available on the saved gateway itself. Its confirmation
states that removing it from Paperclip does not delete accounts in Composio.
Targeted Composio app setup URLs reuse the saved-account chooser when an active
gateway exists. Explicit `new=1`, resume, and reconnect keep their own gateway
setup flow. Existing ACTIVE app accounts are checked without creating another
hosted link or a task. New app authorization remains a direct hosted sign-in
handoff, followed by a fresh account check.
Arcade still offers an agent task draft to verify the requested app and obtain
any provider authorization link. It requires the app's tools in the selected
gateway, a catalog refresh, and any tool authorization. New gateway setup retains
the app name through `targetToolkit`; it creates only the provider gateway.
Composio then returns to direct app setup; Arcade opens the task draft.
Setup entry points preselect an assignable agent: prefer an agent named
**Default agent**, then organizational rank and leadership roles, then creation
date. If there is no named default, use the same rank and age ordering on the
remaining agents. The user can change the selection before continuing.
The board's Create Task action creates a new task even when an open task has the
same title. A request key protects retries of the same submitted draft, and the
success confirmation links to the created task.
Connection setup drafts opt into the dialog's `navigateOnCreate` option, taking
the operator to the created task after submission. Other callers stay on their
current page by default; the option does not add a visible control.
The task asks the assigned agent to perform setup directly without hiring or
delegating, and to provide a browser link and wait when human authorization is
needed. Before provider calls, it checks access for the task's current assignee.
Missing access uses `connection_request` with the saved `connectionId` and exact
indexed `toolNames`, producing an embedded card with the requesting agent's
avatar and a **Grant access** action. The addressed human connection manager
approves the frozen tool set; acceptance adds agent-scoped access and resumes
the task. Composio setup asks for Search Tools as Allowed and Manage Connections
as Ask first. Writes and unknown-risk tools retain per-call approval. Changed or
quarantined tools require a new request. Existing policies, identity selection,
and other agents' access are preserved. The task never grants itself permissions
or requests access for every agent.
The connection's Permissions page lists additional agent access separately
and lets the connection manager remove it without changing the default action
permissions. Removing that grant also disables its Ask-first tools.
A successful agent run or a local gateway fixture does not prove that
the underlying app is authorized; verify against the real provider gateway.
OAuth recovery exposes a validated native sign-in link on both page and dialog
hosts. A blocked window or navigation retains the existing connection and OAuth
session so the link can continue sign-in without creating another gateway.
Composio reuses `composio-search-catalog.json`. Arcade's snapshot records its
official logo and evidence URLs, excluding hidden and coming-soon entries. To
review and refresh only Arcade's claims, run:
```sh
node scripts/update-arcade-app-catalog.mjs --verified-at YYYY-MM-DD
```
Use the date of the public catalog review. The script preserves the prior file
if the source structure or entries fail validation. `--input <saved-html>` allows
reproducing the snapshot from the same official catalog response. Neither public
snapshot proves a user's gateway configuration or app authorization.
### Managed aggregator account inventory
Composio, Arcade, and Executor observations share the existing app snapshot/sync tables and the manager-only `/api/tool-connections/:connectionId/aggregator/apps` list, `/sync`, and `/refresh` endpoints. Legacy Composio endpoints remain supported. These rows are observations, never executable connections or authorization grants. Company, gateway, viewing human, and effective credential version define the cache; fully successful enumeration reconciles removal, while partial failure retains stale observations.
Arcade discovery paginates its [admin account list](https://github.com/ArcadeAI/arcade-go/blob/main/adminuserconnection.go) and [tool requirements](https://github.com/ArcadeAI/arcade-go/blob/main/tool.go), filters to the configured user and exposed gateway tools, and stores only allowlisted account metadata. An existing project key plus `Arcade-User-ID` can be reused. Otherwise optional manager-only sync setup stores a separate user-owned vault key for discovery; it is excluded from gateway invocation credentials and tool access grants. OAuth gateway tokens are not substituted for project keys.
Executor reads its [MCP integration inventory](https://github.com/UsefulSoftwareCo/executor/blob/main/packages/hosts/mcp/src/tool-server.ts) or uses fixed, read-only `connections.list` and `integrations.list` calls in code mode. Its pure `connections.createHandoff` URL builder can supply the upstream console destination. No arbitrary generated code or provider REST endpoint is used. Unknown integrations remain separate, without guessed branding. Last-health `healthy` is connected, `expired` needs sign-in, and unverified or degraded health never earns a green check. Missing inventory support is visible as discovery unavailable. Managers can set a trusted HTTPS console URL for gateways that do not expose a destination, preserving workspace and self-hosted paths.
Apps groups native and imported accounts under canonical app cards, preserving all upstream account identities. Native onboarding wins over aggregator connect offers. Imported account menus only open their upstream provider; deletion and per-app authorization stay upstream. Parent gateway menus own refresh and optional discovery setup. Paperclip policies continue to govern invocation through the gateway.
Acceptance fixtures: `server/src/__tests__/aggregator-app-discovery.test.ts`, `server/src/__tests__/aggregator-app-sync.test.ts`, `ui/src/pages/apps/Browse.test.tsx`, and the production-page/full-stack test drive at `tests/aggregator-accounts/test-drive.ts`. The expected stories and evidence are recorded in `doc/plans/2026-10-05-managed-aggregator-account-user-stories.md`. Fixture runs do not replace live provider proof when working credentials are available.
doc/connections/MEMORY.md
+4 -2
View File
@@ -8,7 +8,9 @@ rotate credentials without re-enabling the toggle.
Generic custom MCP connections retain their existing behavior.
These are ordinary company-scoped tool connections. There is no separate memory
page, automatic conversation upload, prompt injection, or background memory sync.
page, automatic conversation upload, or background memory sync. Reviewed defaults
use the generic [connection instructions](CONNECTION-INSTRUCTIONS.md) capability
to explain when to recall and save; operators can edit or disable them.
Agents explicitly invoke the provider's tools through the existing gateway, and
operators manage access and actions on the regular Permissions screen.
@@ -22,7 +24,7 @@ Official documentation and public endpoint discovery checked September 24, 2026.
| [Zep](https://help.getzep.com/memory-mcp-server) | Remote MCP, `https://api.getzep.com/mcp`, OAuth | Configure Memory MCP and the identity provider in Zep first. A project administrator assigns MCP seats and shared graphs. Sign in with the assigned work identity. An ordinary Zep API key is not the credential for this endpoint. |
| [Supermemory](https://supermemory.ai/docs/supermemory-mcp/mcp) | Remote MCP, `https://mcp.supermemory.ai/mcp`, OAuth | Sign in and select the workspace, read/write access, and optional container tags offered by Supermemory. Developer API keys are separate from hosted MCP sign-in. |
| [Cognee](https://docs.cognee.ai/cognee-cloud/connections/cloud-mcp) | Bundled Cloud API bridge, Cloud API key | Copy the tenant API Base URL and key from Cognee Cloud → API Keys. Requires an active Cloud workspace. The bundled bridge works in public deployments without a local MCP runtime host. |
| [Honcho](https://honcho.dev/docs/v3/guides/integrations/mcp) | Remote MCP, `https://mcp.honcho.dev`, Bearer API key | Create an organization and API key in the Honcho dashboard. Workspace, peer, and session selectors remain explicit provider tool arguments. |
| [Honcho](https://honcho.dev/docs/v3/guides/integrations/mcp) | Remote MCP, `https://mcp.honcho.dev`, Bearer API key | Create an organization and API key in the Honcho dashboard. Configure the required workspace in Paperclip; it is projected into workspace-scoped tool arguments. Peer and session selectors follow provider/task context. |
Zep and Supermemory use user grants, the existing PKCE OAuth broker, and automatic
client registration/discovery. Zep advertises its authorization server at
doc/connections/tool-method-permission-reviews.json
+1 -2
View File
@@ -1105,8 +1105,7 @@
"https://honcho.dev/docs/v3/guides/integrations/mcp"
],
"reviewedAt": "2026-09-30",
"liveProof": "not-run",
"keyPermissions": "Create peers/sessions and save memory under the API key project. Create a key with read and write permissions for these actions; Paperclip cannot increase an existing key\u2019s permissions."
"liveProof": "not-run"
},
{
"app": "hugging-face",
doc/evals.md
+8
View File
@@ -3,6 +3,14 @@
Paperclip has two live eval families with different questions, owners, and
evidence. Choose the family before selecting a model, profile, or case.
The explicit-only [native instruction consolidation comparison](plans/2026-10-03-native-completion-consolidation.md)
uses six Product E2E cells per source variant. It measures the completion
constraint reduction separately from the earlier native tool-description
trial. Provider-free start/resume payload capture is a byte measurement;
behavioral qualification requires the original paired live outcomes and
retained content. Neither source admission nor a scripted pass proves model
behavior.
- **Runner Evals:** real Runner/provider behavior against a seeded mock control
plane. Definitions live in `paperclip-evals/evals/paperclip-runner`; see the
[direct live protocol evals](../packages/paperclip-runner/docs/runner-protocol-live-evals.md).
doc/execution-semantics.md
+21
View File
@@ -452,6 +452,23 @@ Workspace incoherence feeds into the same non-terminal liveness and stranded ass
For runtime-created `git_worktree` execution workspaces, branch coherence is part of workspace coherence. The persisted execution workspace branch is the recorded branch for future dispatch. Reusing that workspace must verify that the worktree is still registered and that `HEAD` is on the recorded branch. Successful run finalization must perform the same check before recording `workspace_finalize=succeeded`. If the run switched to a publishing/PR branch without updating the execution workspace record, finalization may auto-restore the recorded branch only when the worktree is clean, still registered, and the recorded branch points at the current `HEAD`; the repair is recorded as a workspace operation before the successful finalize row. If that safe repair cannot be proven, finalization records a failed workspace finalize and the run fails with bounded evidence for the expected and actual branch. A branch change is sanctioned when a control-plane path updates the execution workspace record before finalization, when publishing work happens in a separate worktree and the managed issue worktree remains on its recorded branch, or when the finalizer performs this clean same-commit restoration.
Sandbox Git restore uses the host branch and commit captured before staging.
If that identity is unchanged, a rebased or amended sandbox history with shared
ancestry replaces the starting tip instead of being merged with it. The ref
update checks the expected old commit; a concurrent change retries through the
normal history integration path. Git holds the HEAD and applicable branch locks
while restore verifies the attached/detached branch identity and commits the ref
transaction. A checkout during integration cannot redirect that write.
The directory merge still preserves host-only
file changes under its existing rules. A changed host branch requires recovery.
An intentional reset to an ancestor exports a full Git bundle so restore keeps
the actual sandbox tip; an empty delta is reserved for an unchanged tip.
Unrelated sandbox history keeps the existing history-preserving graft only when
the recorded host has not advanced; it must not replace concurrent host work.
Warm sandbox reuse must match the current host Git tip and branch as well as the
file snapshot and saved stamp, including managed nested repositories. A history
or branch mismatch restages the host before the next run begins.
### Workspace scan failures before provider startup
Repository discovery distinguishes an ordinary folder from a failed Git read.
@@ -484,6 +501,10 @@ An explicit recovery action is a typed liveness repair path for a source issue.
A terminal native failure can retain a result accepted before checkpoint or cleanup failed. That result is historical evidence, not a live controller. New user input may start a fresh turn after the controller and execution environment have stopped and ordinary admission checks pass. Preserve the failed run, its result, and its recovery budget. Do not commit the old result, infer action outcomes, or replay the failed turn. A message saved while cleanup is pending must be reconsidered after verified cleanup and delivered once. Admission must consume its deferred receipt in the same transaction that creates the new run, including in agent chat, where later messages keep their separate turns. Completing that run must not promote the consumed receipt again. Workspace-export repair retains its separate saved-result recovery path.
When a legacy turn admitted by an explicit user message fails or times out, a bounded transient retry needs its own durable continuation authorization. Initial admission binds the message's exact body digest and revision. Scheduling requires that original binding and revalidates the human author, source task, assignee, and execution ownership, then records the successor's receipt in the same transaction as its run. Historical receipts without a message binding cannot authorize automatic retries and are not backfilled. The parent receipt remains intact. Dispatch checks the exact successor, retry parent, and unchanged message binding again. Deleted or edited input, changed actors or ownership, superseded work, and duplicate successors cannot renew authority. One-run Retry and Interrupt intents retain their separate admission contracts; they are not renewable user-message authority. Other retry policies cannot borrow this receipt: their scheduling fails closed. Successful explicit turns do not create a prose-only missing-comment follow-up with spent authority.
Explicit retry admission checks the local parent adapter controller and verified environment cleanup. The existing queue-first release policy may retain only its own terminal execution claim while that cleanup is pending; finalization and the periodic stale-lock sweep reconsider the same policy after cleanup. Generic terminal-lock cleanup and stale checkout adoption leave these claims for that settlement. New user input, reassignment, and a successor's claim take precedence. Exhausted retries and revoked or missing authorization release the terminal claim without requesting another retry. Pending or failed environment cleanup cannot mint a successor receipt.
A new user message can continue a terminal native run whose process fields were cleared before local stop receipts existed. Admission must verify the exact run, runner, workspace, and provider session in the retained suspended state, with no active provider turn, pending tool call, or undelivered output. Missing or mismatched state keeps the hold. A later recorded process launch also keeps the hold until its stop is verified. Normal assignment, decision, controller, environment cleanup, and active-run gates still apply. The message starts one fresh conversation turn; it does not replay the failed run, reset its recovery budget, or certify unknown action outcomes.
The task thread exposes the guarded Retry action for failed or timed-out conversation runs and native preparation cancelled before provider startup when the never-started proof is verified. The server projects this eligibility on the recovery notice and rechecks it on Retry. Cleanup quarantine retains its inspection path, and non-conversation reconciliation gates remain enforced. Pending decisions, active execution, pause, budget, dependency, and ownership gates remain in force. A refused Retry reports its reason inline and remains available for another attempt.
doc/observability.md
+27
View File
@@ -504,6 +504,33 @@ or `restore_failed`. Unknown values are omitted. Workspace paths and arbitrary
pre-restore result data are not included. A later successful run does not, by
itself, establish that an earlier failed restore recovered the workspace files.
When available, the saved `workspaceRestoreDiagnostic` adds the bounded fields
`workspaceRestorePhase`, `workspaceRestoreStep`, `workspaceRestoreErrorCode`,
`workspaceRestoreHttpStatus`, and `workspaceRestoreExitCode` to `run_execution`.
The phase is `workspace` or `asset`. The failing step is one of `git_export`,
`git_import`, `workspace_transfer`, `workspace_extract`, `directory_merge`,
`git_integration`, `index_reset`, `git_ref_cleanup`, or `asset_restore`.
Nested steps retain the most specific failing operation. Error codes come from
the restore diagnostic allowlist, with unrecognized codes reported as `unknown`;
HTTP statuses are integers from 400 through 599 and process exit codes are
integers from 1 through 255. These fields accompany a known restore failure code
only. They omit error messages, raw command lines, paths, process output, and arbitrary
cause data. Git error wrappers preserve only these safe codes and numbers for
diagnostics, without adding the original error as a cause.
For `git_integration`, optional `workspaceRestoreGitCommand` identifies the fixed
command family: `rev_parse`, `symbolic_ref`, `merge_base`, `merge_tree`,
`commit_tree`, `update_ref`, or `log`. `workspaceRestoreGitFailureKind` is
`merge_conflict`, `invalid_object`, `ref_conflict`, `permission_denied`, or
`unknown`. A merge conflict requires an uninterrupted `merge-tree --write-tree`
exit of 1 with a completed tree ID in stdout; exit 1 alone is ambiguous.
Object and ref classifications require recognized Git diagnostics;
permission denial requires an OS `EACCES` or `EPERM` code. Unrecognized or
localized messages remain `unknown`. Up to 16 KiB of stderr is inspected only
in memory; no arguments, stderr, paths, repository URLs, filenames, or ref names
enter these fields. Handled probes and successful retries emit no diagnostic.
This does not change
restore behavior, retries, timeouts, or recovery policy.
A caught directory-merge lock timeout also records `restoreLockOwnerState`
(`alive`, `dead`, `unknown`, `missing`, or `invalid`), `restoreLockKnownLocalHolder`,
and, when available, `restoreLockOwnerSameProcess`, `restoreLockOwnerPredatesProcess`,
doc/plans/2026-10-02-composio-connection-model.md
+164
View File
@@ -0,0 +1,164 @@
# Composio connections and permissions in Paperclip
October 2, 2026 · Current behavior and proposed product model
**Composio should be the source of truth for its app accounts. Paperclip should show those accounts and control who can use the saved Composio connection.** Connecting Circleback in Composio should not require connecting it again in Paperclip when the saved gateway can already reach that account.
The current integration supports direct app authorization and checking known accounts, but discovery is incomplete. Its Circleback cards also look like independent Paperclip connections even though their permissions belong to the entire Composio gateway. This document explains that distinction and proposes a clearer experience. Recommendations below are proposals; this document does not change product behavior.
## What the saved connection actually represents
The default integration uses Composio Connect at `https://connect.composio.dev/mcp`. Composio describes this as one MCP connection that discovers and executes tools across apps through orchestration tools. It is different from an application creating its own Composio SDK session. [Composio Connect documentation](https://docs.composio.dev/docs/composio-connect)
There are three objects to distinguish:
| Object | Meaning |
| --- | --- |
| Saved Composio connection in Paperclip | An endpoint, credentials, access rules, and tool catalog. We have called this a gateway. Multiple saved Composio connections are possible. |
| Connected app account in Composio | A particular authorized Circleback, Spotify, or other app account. |
| App row in Paperclip | A cached observation of an account available through a saved gateway, plus a convenient setup or management entry point. |
**An observed Circleback row does not create another credential or independent connection in Paperclip.** The public app catalog is another separate thing: it says Composio supports Circleback, without proving that this gateway has an authorized Circleback account.
Composio accounts are scoped. Projects separate resources, and connected accounts belong to an upstream user identity. Dashboard-created accounts use a Composio dashboard user identity, which is different from an application's `user_id`. Matching a person's email or using the same Composio brand is insufficient to establish that two integrations reach the same accounts. [Project isolation](https://docs.composio.dev/reference/api-reference/projects), [Connected account identities](https://docs.composio.dev/reference/api-reference/connected-accounts)
For our existing Connect gateway, the practical question is: **Does listing Circleback through this exact saved credential return the account?** That check is stronger evidence than seeing Circleback somewhere in the Composio dashboard. The current integration has not established a general mapping from Connect OAuth identity to every dashboard project.
## What happens to tools
Paperclip does expose the gateway's tools to permitted agents. It reads the upstream MCP `tools/list`, stores the returned definitions, presents eligible tools through its own runtime, checks policy, and forwards execution to the saved endpoint using server-resolved credentials.
That is a proxy of the upstream tool catalog. It does **not** turn every app in our public catalog into its own set of executable Paperclip tools.
```mermaid
flowchart LR
Agent --> Policy[Paperclip gateway access and tool policy]
Policy --> Tools[Composio MCP tools]
Tools --> Accounts[Composio authorized app accounts]
Accounts --> Circleback[Circleback]
Apps[Paperclip Apps page] --> Check[Read account status through saved gateway]
Check --> Accounts
Check --> Cache[Safe account observations]
Cache --> Apps
```
The live test gateway currently has 11 active Composio catalog entries, including search, schemas, connection management, batch execution, and workbench tools. It does not list a separate Circleback tool set. Circleback execution happens behind those Composio tools. A custom session endpoint could expose a different catalog; the actual upstream definitions determine what Paperclip presents.
Consequently, an account can be available for execution even before the Apps page discovers it. The account snapshot is a display cache, not an execution allowlist.
## What currently works and what is incomplete
These findings come from the current worktree and a read-only check of the local test gateway.
| Capability | Current behavior |
| --- | --- |
| Reuse an already connected app | Setup lists the requested toolkit first. An active account skips creating another authorization link. No agent task is necessary. |
| Authorize an app from Paperclip | The backend requests a hosted Composio authorization link. Completion checks account status again. |
| Recognize a known account | Safe account IDs, aliases, statuses, default flags, and check times are cached. A fresh check confirmed Circleback is active. |
| Discover an app connected independently | The Apps page checks its visible catalog toolkits and previously observed or configured toolkits. A previously unseen app can remain undiscovered until its page or search is checked. |
| Notice external disconnection | Rechecking a known toolkit replaces the observation with the provider's returned account list. Until then, the card can be stale. |
| Rename or remove an app account | Paperclip calls Composio, then lists accounts again to confirm the change. This changes upstream state. |
| Give Circleback its own agent permissions | The row's Permissions action opens the saved Composio gateway's permissions. It is not an independent Circleback permission boundary. |
Refresh happens on page entry, changes to the visible catalog query, and browser focus. The one-minute query freshness setting is **not** a background polling schedule. We have no full inventory reconciliation job or lifecycle webhook integration here.
If a provider check fails, we preserve previous observations and show an error. That avoids interpreting a failed request as a disconnection, but the old green check can still look current. The UI should distinguish **last confirmed connected** from **verified now**.
Two additional presentation gaps matter:
- Native connector precedence currently excludes overlapping aggregator cards altogether. A native Notion offer can therefore hide the fact that Notion is already available through Composio. We should suppress duplicate connection offers while still showing real upstream accounts and their source.
- The aggregator row's “Connected by” identity comes from the saved gateway owner metadata. It does not establish who authorized the app independently in Composio. Preserve the account-row visual style, but use truthful attribution such as **Via “Work Composio”** unless the upstream author is known.
## Who owns which permissions
| Question | Authority |
| --- | --- |
| Is this app account authorized and active? | Composio, backed by the app's authorization. |
| What access did the app's OAuth consent grant? | The app and Composio's authorization configuration. |
| Can this Paperclip human or agent use the saved gateway credential? | Paperclip's grants and access controls. |
| Is this exposed MCP tool allowed, denied, or subject to approval? | Paperclip's tool policy. |
| Can this agent use only Circleback through a broadly enabled Composio executor? | Not established by the Circleback app row or its current Permissions link. |
New gateways now default to all humans and all agents. That makes the gateway available to those actors; it does not override credential requirements, tool policies, or Composio's own account restrictions. App setup preserves the saved gateway's existing rules.
The policy system evaluates the catalog entry being invoked. For example, it sees `COMPOSIO_MULTI_EXECUTE_TOOL`; it does not automatically expand every nested app action into a separate Circleback permission decision. The current integration has no Composio-specific layer that grants or denies downstream toolkit/account operations independently.
An approval for a broad execution tool is therefore an approval for that call and its arguments. It should not be presented as a verified per-app read/write policy. Generic argument rules can constrain particular shapes, but do not by themselves provide comprehensive app isolation across batch execution and workbench paths.
Likewise, an app card's absence, a native app's precedence, or removing a cached observation cannot stop a permitted gateway from reaching an upstream account. A visual catalog choice is not a runtime restriction.
## What connecting or disconnecting elsewhere should mean
The following is the proposed behavior, assuming the account belongs to the identity and scope reachable by the saved gateway.
| Event | Expected Paperclip behavior |
| --- | --- |
| Connect Circleback in Composio | Import it into connected apps automatically. No second OAuth flow or local activation step. |
| Click Connect when Circleback is already active | Verify and show the existing account. Do not create another account. |
| Disconnect Circleback in Composio | Update the account row after reconciliation. Provider execution follows upstream state even while our card is stale. |
| App authorization expires | Show Needs sign-in and offer the provider's reauthorization flow. |
| Composio cannot be reached | Keep the last observation, mark it stale, and show Check again. Do not claim a confirmed disconnection. |
| Add a second account for the same app | Show both accounts. Do not imply that clicking one pins all later agent calls to it unless execution actually enforces that choice. |
| Remove Composio from Paperclip | Remove local access to that saved gateway. Keep upstream app accounts in Composio. |
Composio documents automatic OAuth token refresh and an expired-account event. That gives us one potential sync signal, but does not prove that our Connect credential can subscribe to every creation, deletion, or status event. [Authentication lifecycle](https://docs.composio.dev/docs/authentication)
## The experience I recommend
**Keep one saved connection per Composio account or configured endpoint, show its apps as imported accounts, and manage app authorization in Composio.** This matches the underlying system and keeps our interface small.
1. **Connecting Composio imports its available accounts.** Put them above the catalog using the same divider, check, logo, and account-row layout as other connections, with a Composio badge and quoted gateway name. Label this inventory as connected apps, rather than apps separately installed into Paperclip.
2. **Connect asks which saved Composio account to use, or offers a new one.** Check existing authorization first. If needed, open a provider-generated sign-in link directly and verify the result. No agent picker or task draft.
3. **An app's Manage action shows its accounts and opens Composio management.** Prefer a toolkit/account-specific URL where supported and verified; otherwise link clearly to Composio. Do not promise a deep link that the provider does not expose.
4. **Permissions live on the Composio gateway.** From an imported app row, call the action **Composio permissions** and explain once that changes apply to apps accessible through that gateway. Keep native connector permissions independent.
5. **Manage upstream app removal in Composio for the initial model.** Reserve **Remove connection** in Paperclip for removing the saved gateway locally. If we retain direct upstream removal, name it **Disconnect from Composio** and explicitly say it can affect other clients using that account.
This is a UX recommendation, not a technical inability to remove accounts. Composio Connect supports account creation, listing, renaming, and removal, and our backend already implements those operations. [Connection management capabilities](https://docs.composio.dev/docs/composio-connect)
Removing an account from Composio should also not be described as guaranteed revocation of the target app's OAuth grant. Composio distinguishes removing an account from revoking its authorization at the provider. [Connected account lifecycle](https://docs.composio.dev/reference/api-reference/connected-accounts)
For native overlaps, keep the native Connect offer as requested, but include actual Composio accounts in the connected inventory with their source visible. A Composio account should never silently become a native account.
## How to make discovery complete
The current per-toolkit checks are useful, but cannot support the promise “we automatically import everything you already connected.” Scanning thousands of catalog toolkits is an expensive substitute and can still miss apps absent from our public catalog.
Composio provides a paginated connected-account API with project-key authentication and user/toolkit/status filters. Its SDK also offers paginated session toolkit discovery filtered to connected apps. These are better building blocks for inventory than probing every public catalog entry. [Connected-account API](https://docs.composio.dev/reference/api-reference/connected-accounts/getConnectedAccounts), [Session inventory](https://docs.composio.dev/docs/configuring-sessions)
**The unresolved integration question is whether we can enumerate that same inventory using the identity behind our current Connect OAuth gateway.** We must not assume that credential is a project API key or that a dashboard project's users match it. Listing every account in a project without the correct identity filter would not answer the user's question.
Proposed implementation order:
1. Establish a supported inventory API for the saved credential, including its upstream subject, project/session scope, and shared-account semantics. If Connect cannot provide this, evaluate an explicit project/session integration as a separate setup mode.
2. Reconcile every inventory page on connection completion and refresh; add bounded background reconciliation and supported event notifications. Events trigger another authoritative read rather than becoming a second source of truth.
3. Store only safe metadata, scoped to company, gateway, and resolved credential identity. Preserve last-success time and sync errors. Change credentials or upstream identity without carrying over another identity's connected status.
4. Reconcile removals only after a complete successful listing. Partial pages and failed calls must not delete unseen accounts. Surface unknown custom apps using provider metadata where available.
Until the identity-bound enumeration route is proven, describe the current display as **apps checked through this connection** rather than complete synchronization. The current cache uses a credential-reference fingerprint; that is not proof of the upstream user's identity.
## If we later want independent app permissions
We should decide this separately from inventory. The simpler gateway model is valid, provided the interface is honest about its scope.
Composio SDK sessions can restrict toolkits, tools, and selected connected accounts. A session MCP endpoint can use those restrictions and a direct-tools preset to expose an explicit tool set. That offers a possible route to enforced per-agent scope, but it requires a different integration contract from merely observing accounts behind Connect. [Session configuration](https://docs.composio.dev/docs/configuring-sessions), [Session MCP endpoints](https://docs.composio.dev/docs/sessions-via-mcp)
The other route is a Paperclip executor that validates every downstream tool and account and prevents broader execution paths from bypassing those rules. This is substantial runtime work. Adding a per-app toggle while leaving unrestricted gateway execution available would not establish the promised boundary.
For apps already supported natively, a native connection remains the clearest way to apply that connector's individual access controls.
## Evidence and checks still needed
The local gateway returned 11 active Composio tools, and a fresh read through our app refresh endpoint confirmed an ACTIVE Circleback account. This proves account-status checking for that saved credential. It does not prove all-app enumeration, a successful Circleback business operation, external lifecycle synchronization, or independent Circleback permissions. No real account was disconnected or permission changed for this document.
Before claiming complete sync, demonstrate an app connected independently in the matching Composio scope appearing without searching for it; then externally disconnect a disposable test account and verify both the UI and execution outcome. Also check account isolation, multiple-account selection, provider failures, native overlaps, and gateway removal without upstream account deletion.
Implementation evidence in this worktree:
- `server/src/services/tool-access.ts`: `openComposioGateway`, `setupComposioApp`, `refreshComposioApps`, and `manageComposioAppAccount` implement checks, safe observations, and upstream mutations.
- `server/src/services/tool-gateway.ts`: `policyInputForAgentTool` and remote MCP execution show the tool-policy boundary and forwarding of catalog tool names and arguments.
- `server/src/services/tool-access-policy.ts`: catalog entries and saved connections determine the policy context; no automatic downstream Composio app expansion is implemented.
- `ui/src/pages/apps/Browse.tsx`: native precedence, page-based discovery, connected-account rows, permission links, and owner attribution.
- `packages/db/src/schema/tool_connection_app_snapshots.ts`: cached account observations, separate from connection grants.
- `doc/connections/CONNECTOR-PLAYBOOK.md`: the current aggregator catalog and setup behavior.
The recommendation is to adopt the provider-owned account model now, then prove complete discovery before promising it. Independent app permissions can follow if we choose to build and enforce them.
doc/plans/2026-10-03-composio-account-sync-user-stories.md
+93
View File
@@ -0,0 +1,93 @@
# Composio account sync user stories
October 3, 2026 · Acceptance criteria written before implementation; results recorded after the embedded-browser walkthrough
The user starts on Apps with a saved Composio gateway. Composio owns app accounts and authorization; Paperclip shows provider observations and controls access to the saved gateway. Existing access restrictions must survive every discovery and setup action.
The current Connect MCP credential supports account listing by toolkit, not an authenticated list-all inventory API. Automatic discovery therefore checks the supported Composio catalog in bounded background batches, independently of search and pagination. Custom apps absent from that catalog remain outside this coverage. The UI and final test report must describe that limit.
## Expected journeys
| Story | Expected outcome | Independent evidence |
| --- | --- | --- |
| As a returning user, I see apps already authorized in Composio without searching or reconnecting them. | Apps begins syncing the saved gateway. Accounts discovered anywhere in the supported catalog move above the paginated catalog, with their app logo and Composio source. | Provider fixture has a pre-existing account outside the first catalog page; no add call, task, new gateway, or grant is created. |
| As a user, I reuse an existing app authorization when I click Connect. | Select a saved Composio account, continue, and see its existing app account. No second sign-in link. | Provider calls contain list only for the already active app. |
| As a user, I authorize a missing app directly. | Choose the saved account, open the hosted provider link, complete sign-in, and return to verify. No agent or task picker. | Provider account changes after authorization; completion reads it again. |
| As a user, I see an app I connected independently. | Automatic sync or Refresh discovers it without finding its catalog page. | Change the disposable provider's account state independently; use the production Apps UI to refresh. |
| As a user, I see an app disconnected or expired independently. | A complete account check removes the disconnected account or shows Needs sign-in for the expired one. | Provider returns an empty list or EXPIRED account; the old green Connected state disappears. |
| As a user, I manage Composio app accounts in Composio. | Manage lists the observed accounts and offers Open in Composio. No local rename or remove action that silently changes upstream state. | Open the row menu and management dialog; inspect the external link and confirm zero rename/remove calls. |
| As a user, I understand whose permissions I am editing. | Imported app menus say Composio permissions and open the saved gateway. A short explanation says access applies across this gateway's apps. | Navigation goes to the gateway's existing permission screen; native connectors retain Permissions. |
| As a user, I see native and Composio account sources accurately. | Native Connect remains preferred; an already authorized upstream account remains visible. Attribution says Via the quoted gateway name rather than inventing an upstream author. | Seed a native-overlap app upstream; inspect its card, account row, and source link. |
| As a user, I can recover from a failed check without losing accounts. | Keep prior observations with a visibly unverified status; show a useful retry action. A successful retry restores verified status. | Provider failure followed by success; no account deletion or false disconnected result. |
| As a user with several Composio gateways, I see accounts grouped by their actual source. | Show each source separately and preserve selection in setup/management. | Distinct provider accounts behind two saved gateways; calls use the selected gateway. |
| As a user, I remove the local Composio gateway without deleting its upstream apps. | Confirmation states that Composio accounts remain. Saved gateway access and its imported rows disappear locally. | Use a disposable gateway; provider accounts remain and no upstream remove/revoke-app call occurs. |
| As a user, I can browse and search a large catalog while sync runs. | Installed accounts stay above each catalog page. Sync feedback does not block search, pagination, or cancel. | Search and change pages during sync; inspect persistent accounts and bounded page size. |
## Verification boundaries
Use the embedded browser against the built production UI and real Paperclip server/database. Live checks use the existing Composio test gateway for reads and management navigation. Authorization, expiry, independent disconnection, errors, and local removal use a clearly marked disposable provider fixture so valuable real accounts are preserved.
Fixture results establish Paperclip behavior through the real UI and backend, not real Composio authorization compatibility. Record these separately. A passing unit test or API response alone does not pass a browser journey.
## Results
The implementation and all twelve Paperclip browser journeys passed within the boundaries below. Fresh third-party OAuth consent was simulated through the disposable provider; it is not claimed as a live provider pass. Live reuse and discovery were verified with the saved Composio gateway and independently compared with Composio's own account inventory.
### Live Composio
Tested the built Apps UI at `http://localhost:3104/TES/apps`, using the existing **Composio test gateway**. No real account was removed, renamed, or newly authorized, and no agent permissions were changed.
- Automatic discovery checked all **1,583 catalog toolkit identifiers**, including aliases and native overlaps, with zero failed toolkit checks. Circleback and the independently connected Airtable account appeared above the paginated catalog without searching for them or requesting another sign-in.
- Opening the old `/TES/apps/connect?source=composio&targetToolkit=circleback_mcp` URL selected the saved gateway. Continue reused the active Circleback account, closed setup, and cleared the setup query. Reload did not reopen the dialog. No new task or gateway was created.
- Manage Circleback showed the provider account and its default status, the quoted source connection link, and the explanation that Paperclip permissions apply across this gateway. The source link opened the correct existing permission screen. Native Notion retained **Permissions** and **Remove connection**.
- **Open in Composio** was clicked from Paperclip. Its final destination was the consumer **For You → Connect Apps** screen, rather than Platform developer projects. Selecting Connected showed the same two apps: Airtable and Circleback MCP, both with one active account.
- A subsequent background check failed at 448 of 1,583 identifiers. Previously observed accounts remained visible as unverified. Refresh recovered, and the next complete scan again checked 1,583 identifiers with zero failures. The failure's provider/transport cause was not established; it is not presented as an app disconnection.
### Disposable provider journeys
Used the production React build, company-scoped tool-access routes, service, and real local PostgreSQL database at `http://localhost:3110/COM/apps`. Only outbound responses for two explicitly fictional fixture gateways were controlled through the service's existing remote-request test seam. This was a separate company with a paused agent and no issues.
| Journey | Browser result and corroboration |
| --- | --- |
| Pre-existing apps without search | Circleback accounts behind two gateways, imported Notion, and Zendesk outside the first catalog page appeared automatically. No add request, task, or agent grant was needed. |
| Existing authorization | Live Circleback reuse passed as described above; setup checked the existing account before deciding whether authorization was needed. |
| Missing app authorization | Spotify opened the saved-account dropdown with Work, Personal, and Connect a new account. No agent picker appeared. Continue produced the hosted sign-in link. Premature completion showed a useful “finish connecting” error. After independent fixture activation, completion verified the account and displayed its connected row. The fictional hosted link itself was not opened. |
| Independent connection | Added Spotify and Airtable in provider fixture state, then clicked Refresh. Both appeared without using their native Connect actions. |
| Independent disconnection and expiry | Removed Personal Circleback and Zendesk upstream; expired Work Circleback. After sync, the removed accounts disappeared, Zendesk returned to Connect, and Circleback showed Needs sign-in rather than a green check. |
| Provider-owned management | The imported row menu contained only Open in Composio and Composio permissions. Manage was an observation view with Refresh and the provider link. Recorded provider actions contained no rename or remove operation. |
| Permission ownership | Composio permissions navigated to the actual saved gateway. Its explanation appeared before the human/agent permission controls. No permissions were changed by discovery or setup. |
| Native overlap and source attribution | The Airtable card retained native Connect while displaying its already connected upstream account. Imported Notion remained visible. Imported rows said Via the quoted gateway name; native rows retained Connected by. |
| Failed refresh and recovery | Injected HTTP 503, clicked Refresh, and saw the last known accounts with Not verified and retry. Restored the provider, clicked retry, and saw verified Connected again. |
| Several gateways | Circleback showed two distinct accounts and source links. Management switched between Work and Personal; after Personal's upstream removal it correctly showed no accounts, without displaying Work's account under Personal. |
| Local gateway removal | Cancel preserved the gateway. Confirming Remove archived Work and revoked its local organization grant; Work's imported rows disappeared, while Personal remained. The fixture's upstream account state was byte-for-byte unchanged. No upstream remove or rename action occurred. |
| Search and pagination during sync | Searched Spotify while checking; cleared search; moved to page 2 showing 25–48 of 1,548 connectors; searched meeting apps while checking. Installed accounts remained above the catalog and browsing stayed responsive. |
Additional checks: a single-provider Circleback action skipped the provider picker. After Work's removal the saved-account dropdown offered Personal and Connect a new account. Choosing the latter opened normal gateway setup with organization-wide defaults, a Reuse an existing session disclosure, and one Change link. Cancel created no gateway.
The fixture call log recorded **list** and one **add** action, with a maximum batch size of **32**. Database checks found zero fixture issues, no added agent grants, an archived Work gateway, and an active Personal gateway. The fixture's health check was adjusted to prevent the real server from probing the fictional host; this was fixture setup, not a product fix. After recording these results, the disposable company was archived and its fixture server and browser tab were closed. The live Apps page remains available.
### Issues found and corrected during the walkthrough
1. The legacy targeted setup URL opened a new-gateway wizard despite an existing active gateway. It now uses the saved-account chooser, preserving explicit new/resume/reconnect flows.
2. Successful targeted setup left query parameters that reopened the dialog on reload. Completion and cancel now consume that setup query.
3. The imported account button had a duplicated “account account” accessible label. The label now uses the account's actual name.
4. Gateway permission scope appeared below the controls. It now precedes them so users see the scope before editing.
5. The bare Composio dashboard URL opened Platform developer onboarding. The consumer-management link now uses `https://dashboard.composio.dev/~/org/connect/apps`, verified in the embedded browser without embedding a user-specific organization slug.
### Automated verification
- Focused UI/shared tests: **320 passed** across Browse, AppsConnect, AppDetail, aggregator setup, and catalog mapping.
- Backend Composio setup/sync tests: **21 passed**, including batch size, concurrent leases, incomplete/error evidence, recovery, company access, and credential changes during a check.
- Repository-wide `pnpm -r typecheck`: passed.
- Repository-wide `pnpm build`: passed; the final management-link edit also passed a fresh UI build.
- `pnpm check:token-gates`: passed after the final UI edit.
- Repository-wide `pnpm test:run`: failed in the first general-server phase after **14,825 tests passed**, with timeout failures in access-service startup, project-icon startup, direct-adapter execution, and Git streaming, plus a worker-start timeout for server-info. Later workspace/serialized phases did not run because this command stops on failure.
- Separate rerun of those five files: **32 tests passed** across access-service, project-icon-persistence, heartbeat-direct-adapter-native-isolation, and server-info. The single `workspace-git-snapshot-streaming.test.ts` test still timed out at its 300,000 ms limit. That test and its implementation were not changed by this work. No full-suite pass is claimed; its remaining timeout is recorded rather than hidden or worked around by changing the test.
### Coverage limits
Automatic discovery covers the supported public catalog, not arbitrary custom apps absent from that catalog. It uses the authenticated Connect MCP account-list tool because saved gateway OAuth is not a consumer list-all API key. Observations are isolated by company, human viewer, and credential selection; changed credentials require fresh evidence.
The hosted authorization handoff, premature completion, and post-authorization verification were tested with controlled provider responses. This report does not claim that a new real Spotify OAuth consent flow was completed. No paid runner evaluation, exhaustive mobile/accessibility audit, or new Arcade account synchronization was performed. Existing Arcade setup remains intact.
Paperclip still exposes and governs the saved gateway's outer MCP tool catalog. Imported app rows do not re-publish each underlying service's tools or promise app-level permission isolation inside Composio's gateway.
doc/plans/2026-10-03-connection-instructions-and-memory-evals.md
+363
View File
@@ -0,0 +1,363 @@
# Connection instructions and a small memory smoke suite
Implementation update (2026-10-05): the generic capability is specified in
[Connection instructions](../connections/CONNECTION-INSTRUCTIONS.md). The
Storybooks now use production components. Model evaluations in this original
design plan remain deferred.
Status: original UX proposal. The production implementation now follows the
linked capability contract. Live model evaluations remain deferred.
## Decision
Make **Agent instructions** an optional connection capability. A connection can
provide a short paragraph that tells assigned agents when and how to use it.
Memory is the first use case. Use the same pattern for other services whose
purpose needs standing guidance, without requiring users to install a skill.
The checkbox says **Tell agents to use Honcho** (using the provider name). Show
this section only when the connection explicitly provides a nonempty instruction
template. Default it on, show the exact paragraph, and offer **Reset to default**
only after edits. Turning it off preserves the paragraph and shows an amber notice. On the agent, show a read-only copy
with its source and a link back to the connection.
Compose this into runtime instructions beside the agent's own instructions.
Do not append persistent text to AGENTS.md: that would create duplicate, stale
instructions after editing, reconnecting, changing assignments, or disconnecting.
An optional generated run-local file can be a delivery mechanism for a harness,
but the canonical agent files remain untouched.
## What exists, and what is still unproven
The five experimental catalog entries are ordinary remote MCP connections behind
`enableMemoryConnectors`. `doc/connections/memory-tool-inventory.json` records
authenticated discovery on **2026-09-24**, explicitly not execution of every tool.
| Provider | Captured tools | Smallest useful path in that snapshot |
| --- | ---: | --- |
| Mem0 | 11 | `add_memory` → `get_event_status` if asynchronous → `search_memories` / `get_memory` |
| Honcho | 40 | Resolve workspace/peer/session → `add_messages_to_session` → `search` or `get_session_messages` |
| Supermemory | 16 | `add_memory` → `search_memory`, scoped to the approved space/tag |
| Zep | 12 | `add_memory` / `add_memory_to_graph` → `search_graph` |
| Cognee | 3 | `remember` → `recall`; `forget` for supported cleanup |
These are observed names, not a cross-provider API or a claim that every
operation works. Capture fresh schemas before writing live fixtures. In particular,
Supermemory's `add_memory` is classified as destructive in Paperclip because
its action parameter can delete. Honcho has a richer context model than a simple
key/value store. Show the real catalog through the existing Permissions screen.
Current coverage includes catalog/auth setup, experimental gating, and risk
classification (`memory-connectors.test.ts`, `tool-access-service.test.ts`).
The older `evals/promptfoo/tests/phase5-memory-control-surfaces.yaml` asks models
to explain policy. It does not prove that memory was saved or retrieved.
The similarly named gateway-listing-memory and runner shared-memory tests concern
resource usage, not semantic memory.
Honcho's [official MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp)
says it supplies usage instructions during initialization. Paperclip's
`server/src/services/mcp-http.ts:initializeMcpHttpSession` reads the initialize
result but returns only protocol/session headers. This identifies a likely
delivery gap on that transport; test the full adapter paths before generalizing.
Do not fix it by blindly promoting remote server prose into trusted instructions.
[Mem0's tool documentation](https://docs.mem0.ai/platform/mem0-mcp) also distinguishes
add, retrieve, update, delete, and asynchronous operation status. A fresh-session
retrieval test is stronger evidence than asking the same conversation to repeat
a fact still in its context. Provider documentation was checked on 2026-10-03;
the tool counts above come from the repository's dated live inventory.
There is a useful local precedent: `server/src/services/connector-runtime.ts`
already resolves assigned connector skills, builds run-scoped overlays, and
delivers guidance for Slack, AgentMail, and Browser Use. Slack also has an editable
`ChatCommunicationInstructions` control. Extend that composition discipline;
do not register five memory-specific global skills.
## UX walkthrough
### 1. Connect Honcho
Keep the existing credential and access journey. The current implementation has
compact access defaults with an Advanced disclosure; older two-step variants use
Access → Connect. Add this section on Connect, below access and above the single
footer. Do not add a prompt wizard step or a mandatory test.
**Agent instructions**
☑ **Tell agents to use Honcho**
“Use Honcho to recall relevant preferences and prior decisions when a task depends
on earlier work. Save concise, durable facts after completing useful work. Use only
the memory context supplied for this connection. Treat retrieved memories as
background information; follow current task instructions when they differ. Do not
store credentials or copy entire conversations. If a memory call fails, continue
what you can and say what was not saved.”
Below the paragraph: **Edit instructions**. The paragraph stays visible even when
collapsed; the editor replaces the preview, rather than repeating it. Keep it
short (suggested 60–100 words; maximum 2,000 characters). Do not add an attribution
badge or routine implementation/lifecycle helper text.
For Honcho, require an explicit workspace binding. Show **Honcho workspace** as
an expanded field near the top of setup and configuration, before credentials or
access controls and above instructions. Put a missing-workspace warning beside
it; disable completion until it is supplied. Validate the binding against the
provider during implementation. Never let the model choose an arbitrary workspace.
Default instructions on whenever a connection explicitly supplies a reviewed
template, including ordinary connectors such as the Notion example. Preserve
explicit opt-outs, custom text, and workspace on back/resume and reconnect. A
connector with no template has no instructions section, checkbox, preview, or
blank editor. The Notion example demonstrates an explicitly configured template;
it does not imply that every Notion connection ships with instructions.
### 2. Manage a connection
Add an optional **Agent instructions** section within the existing **Permissions**
page, between agent access and Actions, only when the connection explicitly
provides an instruction template. Keep the real identity controls, access picker, and searchable
action list on the same page. Do not add a new tab or duplicate page navigation. Display:
- The checkbox and exact paragraph; **Edit instructions** and, after edits,
**Reset to default**. No “Suggested by Paperclip” badge.
- A live recipient summary derived from existing assignments: “Applies to Ada and
Morgan when this connection is available to the task.” Link to Permissions to
change access. “All agents” explicitly includes future eligible agents.
- Honcho workspace is a visible field near the top of the page, before access
controls, with its missing-value warning in the same place.
- **Cancel** left and **Save instructions** right. Save errors retain the draft.
- A plain saved receipt: “Saved.”
Turning guidance off preserves the saved paragraph and tool access, and shows an
amber notice: “Agents won’t be told when or how to use Honcho.” Disconnecting
or losing access excludes both the guidance and tools from subsequent runs. A
missing workspace, unavailable credential, or unsupported adapter gets an explicit
“Instructions not applied” reason and a repair action; never a success badge.
If required writes are Off or Ask first, say so and link to Permissions. Saving
guidance must not change those policies or imply that writing is already allowed.
### 3. Inspect an agent
In the existing agent instructions area, add **From connections** beneath the
agent's own files. Each row shows provider, short use summary, On/Off/unavailable,
and its source. Expanding a row shows exactly what will be supplied and the
effective binding for the viewed task context. **Manage in Honcho** returns to the
connection editor. It is read-only here so the source of truth is unmistakable.
Distinguish configured guidance from effective guidance: a personal credential
may be usable only for the responsible user's tasks. Without a task context,
state this condition rather than promising unconditional application.
Memory remains an ordinary connector capability. Do not introduce a default-memory
chooser, memory-specific agent preference, or first-class memory settings area.
Connection instructions compose through the general connector instruction path;
users manage each connection’s instructions and assignments in its configuration.
## Runtime and storage proposal
Implement only after the UX has been reviewed. Suggested contracts:
1. Add optional, versioned `agentGuidance` metadata to the AppDefinition source
and schema: template ID/version, default text, and required context/capabilities. A nonempty
template opts the connector into the UI; instructions start enabled. Regenerate
the catalog from its authoring source; do not hand-edit generated JSON.
2. Store company-scoped connection guidance with `enabled`, text, reviewed
template version, revision, editor identity, and update time. Store provider
context in a typed binding separate from prose; validate access on save and
resolution. Keep public API/shared validators/db/UI contracts synchronized.
3. Reuse the same effective access resolver as tool delivery: company, agent,
task, responsible human, grant, connection health, and action policies all
matter. Agent assignment alone must not imply access to a personal grant.
4. Resolve a stable ordered list of instruction blocks per turn. Include source
connection and revision, the short paragraph, and structured provider context.
Use actual runtime tool aliases and current schemas for any detailed recipes.
Do not paste the entire 40-tool Honcho catalog into the paragraph.
5. Include a guidance digest in session compatibility/input composition. Native
and resumed sessions must observe updates on the next turn. If a harness
cannot replace old context, start a fresh session or display the limitation;
never keep supplying conflicting old and new blocks indefinitely. Active
calls remain governed by current gateway authorization on every invocation.
6. Log edits and assignment changes as normal company activity. Record revision
and binding references in local run evidence. No new first-party Telemetry is
needed. Preview and run composition must share one resolver so they agree.
An enabled paragraph is user-controlled operating guidance, not authorization to
bypass budgets, approvals, current user intent, or company boundaries. Templates
are maintained by Paperclip; provider initialize instructions are external data
that can inform a reviewed template, not an automatic template update. Pin saved
versions; show “Suggested instructions updated” with a diff and deliberate apply.
Never replace custom text during catalog refresh or reconnect.
### Memory context is not an access-control boundary
For the first Honcho slice, bind a dedicated workspace to the connection. Derive
stable peer IDs from company + agent and session IDs from company + task; retries
must reuse them. Decide these values in server code, not in editable prose. Show
the workspace openly near the top of configuration; users should not need to
invent peer IDs. Treat the task's responsible human as a separate subject when needed,
not as interchangeable with the agent's peer.
A peer ID, tag, or query filter may partition retrieval without preventing an
agent holding broad tools from reading another scope. Do not label that “private
memory.” If private
agent memory is promised later, enforce scope arguments server-side, disallow
unscoped/list/bulk operations that bypass the boundary, and test alternate tool
paths. Until then, use isolated provider credentials/workspaces for confidential
scopes. Paperclip company access checks still apply to every connection.
## The smallest useful evaluation
Two separate questions: **does the integration work?** and **does the instruction
make a small model use it appropriately?** Do not ask an LLM judge to score either.
Assert tool calls, arguments, returned records, and a random fact in the answer.
Start with Honcho and Mem0. Each has a different memory shape, and both are already
in the catalog. Expand to the other three once those fixtures are useful.
| Case | Setup / task | Pass evidence |
| --- | --- | --- |
| Discover (no model) | Authenticate disposable test connection and list tools through the actual run gateway | Required read/write tools visible; record schema hashes and policies |
| Save → fresh recall | A: “Remember: release codename is `<random nonce>`.” B: fresh task/session, same memory subject: “What is the release codename?” | Confirmed write receipt; B performs retrieval before answering and includes the nonce from the returned record |
| Implicit recall | Seed a synthetic formatting preference, then ask “Draft my weekly update” without mentioning memory | Guidance-on run retrieves and follows the seeded preference; record guidance-off control separately |
| Skip irrelevant work | “What is 19 × 7?” with memory available | Correct answer, no memory calls or unnecessary writes |
| Failed write / denied access | Return write failure; separately deny the grant | No “saved” claim; useful task continues; no fallback to another user's/company's memory |
| Updated / disabled guidance (no model) | Change text, resume; turn off; unassign; revoke | Correct revision supplied once or absent as applicable; no agent file changes |
The fresh-recall reader receives neither the writer transcript nor its answer,
nonce, runtime session, scratch files, or task summary. Disable other memory
providers and fixture workspace-memory carryover. Give reader a fresh execution
workspace. Only the provider contains the answer; the assertion runner knows the
nonce. Same model instance/conversation is not sufficient isolation.
Run a deterministic gateway round trip before spending model tokens. For async
ingestion, poll a documented status/read path with a bounded deadline (proposed
60 seconds), record “indexing timeout” separately, and never sleep an arbitrary
amount then declare the model wrong. For Honcho, first prove raw message retrieval;
inferred conclusions are a separate, slower capability.
Use the existing Product E2E runner for through-Paperclip evidence; follow
`add-product-e2e-eval` and `paperclip-evals` when implementing. Use a fixture MCP
server in ordinary CI. Account-bound runs are opt-in; the fixture suite proves
Paperclip behavior, not provider availability. Existing promptfoo response-text
tests cannot substitute for the tool loop.
**Model candidates:** start with GPT-5 nano for the baseline, then Gemini 3.1
Flash-Lite as the independent confirmation, if the configured runner provider
supports them. They are inexpensive candidates, not models already proven on
these connectors. Check the [OpenAI model page](https://developers.openai.com/api/docs/models/gpt-5-nano)
and [Google pricing](https://ai.google.dev/gemini-api/docs/pricing) at execution
time, including reasoning-token charges and any routing markup. If unavailable,
select another small tool-capable model from the installed roster and record the
substitution; do not expand this UX work into a new model adapter.
**Cost envelope:** begin with one small tool-capable API model supported
by the runner, then one from another provider for confirmation. Select from the
current installed roster/pricing at execution time, pin exact IDs in the report,
and use a configurable `MEMORY_EVAL_MODEL` rather than “latest.” Do not treat
“free” endpoints as reproducible CI. Initial matrix: 2 providers × 1 model × 4
behavior cases; save/recall uses two isolated sessions per case. One run per cell,
max 6 tool calls/session, 1,000 output tokens/session, concurrency 1. Proposed
hard ceiling: **$1 model spend per matrix**, and **$0.10 per cell**; stop before
dispatch if the reserved worst-case cost exceeds the remaining budget. Count
input tokens/tool schemas too. No automatic retry of failed model cells.
Provider memory/derivation charges are separate: report them when available and
otherwise mark them unknown, never $0. Use designated test accounts, synthetic
facts, and a unique prefix. Cleanup only returned IDs or the known disposable
session/workspace; do not run account-wide delete tools. If cleanup is unsupported
or fails, report retained IDs and the required manual cleanup.
A report needs provider, endpoint/catalog hash, model ID, instruction revision,
effective scope, per-case result, tool transcript/receipt IDs, latency, model
usage/cost, provider cost availability, and cleanup status. Classify configuration,
auth, policy, schema drift, ingestion, model behavior, and cleanup failures
separately. A connected badge or model saying “I remembered” is not evidence.
## Delivery slices and acceptance
1. **This proposal:** interactive Storybook placement, editing/off/error states,
agent preview, ordinary-connector examples with and without instructions, mobile/light views,
and the connector playbook convention. All mutations are local simulation.
2. **First runtime slice:** shared guidance contract, persistence, Honcho binding,
optional UI within existing configuration, one prompt composer for native + local harnesses, meaningful
assignment/revocation/resume tests. Provided templates default on while preserving
explicit opt-outs; missing templates add no UI or runtime text.
3. **Smoke slice:** deterministic gateway checks plus the bounded Honcho/Mem0
model matrix above. Keep Experimental until both have fresh-session evidence;
the other providers stay unverified until individually exercised.
Review in Storybook: **Design explorations → Connections → Agent instructions**.
The specimens render the production app shell, setup flow, and connection detail
page. The instructions block is composed into those pages through optional layout
slots. Credential handling, persistence, bindings, and delivery receipts are simulated. No credentials
or real memory providers are contacted. The plan intentionally does not ship a
new memory service, transcript mirroring, memory browser, or automatic hooks.
## Prototype verification (2026-10-03)
- UI TypeScript check passed after building the shared and plugin SDK type
dependencies in this fresh worktree.
- Full Storybook static build passed. Existing CSS highlight/font-resolution and
chunk-size warnings remain; no build errors.
- All 14 new stories rendered in Chromium without page errors. Browser checks
exercised edit/save/agent preview, disabling while retaining text, failed save
and retry, and setup draft exit/resume.
- Inspected desktop and 390-pixel mobile captures; no horizontal overflow.
- Token gates, palette/character sync checks, and `git diff --check` passed.
In the initial proposal, no production code was changed. Repo-wide server tests/builds and account-bound
memory/model evals were not run for this design-only change. Run the full PR
checks before a PR-ready implementation handoff. This local Codex chat has no
Paperclip issue/run identity, so issue artifact upload and work-product creation
could not be associated with a destination. The plan and stories are retained in
the repository; the built review is available through the local Storybook server.
## Revision: use the actual configuration pages (2026-10-04)
The initial specimens invented a header, tabs, and a wider setup form. Replaced
them with the real `Layout`, `ConnectionSetupFlow`, and `AppDetail`, backed by
Storybook API fixtures. Credential instructions, requirements links, the compact
form width, Back/Connect footer, identity controls, agent access, and the searchable
Actions list now come directly from production components. The new section lives
under Permissions after agent access. Setup adds only the instruction section
above the existing footer. No extra workspace input is added to setup.
`Current connect page` and `Current configuration page` render the same production
pages without the proposed section, for direct comparison. The agent preview is
a dialog over the connection page; it does not impersonate an implemented agent
configuration page. The only production changes are optional composition slots;
normal callers supply no new content and keep their current behavior.
Verification for this revision: UI TypeScript and the full Storybook build pass.
All 242 tests across `AppDetail.test.tsx`, `AppsConnect.test.tsx`, and
`ConnectionSetupFlow.architecture.test.ts` pass. Token gates and whitespace
checks pass. Browser verification covered the actual setup and Permissions pages,
edit/save/preview, disabling while preserving text, failed save and retry, and
the 390-pixel mobile setup/editor (no horizontal overflow). Instruction saves
remain Storybook-only; no runtime memory behavior or provider eval was run.
## Revision: concise provider-owned instructions (2026-10-05)
Apply the same instruction component across setup, settings, reconnect, and agent
preview. Use “Tell agents to use {provider}”, default on for explicitly supplied
templates, an amber off state, and “Reset to default” after changes. Remove the
suggestion badge, storage/lifecycle explanation, and preview disclaimers from
product UI; prototype limitations stay in Storybook documentation. Honcho’s
required workspace stays expanded at the top, with validation beside the field.
Remove the proposed default-memory chooser from both the stories and runtime plan.
The shared setup header no longer shows the generic “Connect now” subtitle.
Remove the Honcho key-permission paragraph from its catalog authoring source and
regenerate the definition so all credential forms pick up the same change. The
shared credential form renders only provider-supplied helper text, without
substituting the removed generic key-permission paragraph.
Verification: 296 targeted tests pass across connection setup/detail, setup
architecture, app definitions, and memory connector risk coverage. After removing
the fallback credential paragraph, all 174 setup/architecture tests pass again.
Browser checks confirm template-present/on and template-absent/hidden states,
reset after saving a custom paragraph, off-state warning and preserved text,
failed save/retry, workspace-required blocking, baseline copy, and the mobile form
at 390 pixels without horizontal overflow. Final UI typecheck, full Storybook
build, token gates, and whitespace checks pass. These remain simulated instruction
and workspace settings; no live provider or model calls were made.
doc/plans/2026-10-03-cursor-production-readiness.md
+29
View File
@@ -25,6 +25,35 @@ spend or enforceable per-run dollar accounting. Native AskQuestion is implemente
defensively but is not advertised or certified. See the
[Cursor capability contract](../architecture/runner-cursor-capabilities.md).
## Merge-readiness refresh — 2026-10-05
The branch incorporates mainline `72ff3a9f2` without replacing the qualified
Cursor CLI, profile v11, patch or explicit model. Mainline's newer Codex, Claude
and OpenCode pins remain intact. Its global sandbox Cursor CLI is separate from
the native provider's verified 2026.09.26 distribution. Mainline completion
feedback keeps current, company-scoped document links and blocker guidance;
Cursor's explicit final-response format still takes precedence. Both regression
suites are retained. The combined Runner fixture catalog contains 492 cases.
The resolved dependency lock for this combined source has SHA-256
`d3c4cffe7d127d99789cf354c5275246526f5396d2a86ce0d387352f68a2394b`.
The image build verifies that digest before installation. The repository lockfile
matches mainline because Actions owns lockfile updates. The artifact and live
qualification identities below remain historical; they are not relabeled as
new builds. A later release must assemble and verify matching packages and images
from its release source. Merging this PR does not publish or deploy that release.
An additional manual trial used the ordinary installed public package on macOS,
the real local Cursor ACP executable and normal encrypted company credentials.
Cursor generated a 1,777-byte counter page, validated it, registered its deliverable
and finished the task through authenticated tools. The task and run reached
`done` and `succeeded`. Independent download matched the workspace bytes and
SHA-256 `0db0ddc7bcd33aed5fe7e74b2551f1c13403d3a6175239f544cab9a45ad0891e`.
The page rendered in the browser and incremented from 0 to 1 to 2 without console
errors. Native approval requests were approved through Paperclip. The reviewer
did not create or edit the page. This trial uses the previously qualified public
package; it is additional live proof, not a new certification identity.
## Qualified release candidate
Cursor admission is enabled in [PR #15075](https://github.com/paperclipai/paperclip/pull/15075).
doc/plans/2026-10-03-native-completion-consolidation.md
+59
View File
@@ -0,0 +1,59 @@
# Native completion constraint consolidation
Date: 2026-10-03. Roadmap item: 2.3. Status: implementation and provider-free calibration; live behavior is unqualified.
## Change and comparison axis
The first slice replaces the repeated final-response procedure in native task constraints with a short requirement to obtain an accepted `paperclip_finish` or `paperclip_block` result and follow that tool's reporting instructions. It removes the extra completion sentence in the Codex/runnerd and direct OpenCode backends. The existing finish/block tool descriptions still own rejection, retry, approval, link/action, explicit wait, and final-response behavior.
The production comparison axis is exactly these three files:
- `packages/paperclip-runner/src/backends/runtime-context.ts`
- `packages/paperclip-runner/src/backends/codex-native-backend.ts`
- `packages/paperclip-runner/src/backends/opencode-native-backend.ts`
Both variants start from master `2a8a99e4a5f69aa803b3f10b982f583e75a87042`. The baseline retains those three original files. The candidate changes only those three production files. All fixture, grader, admission, test and documentation repairs must be common to both variants. The fixed execution prompt, production AGENTS bundle, completion tool descriptions/schemas, operational skills, hiring, connections and delivery guidance stay identical. The prior #14961 trial measured a different change and cannot qualify this one.
## Provider-free measurement
`src/backends/native-instruction-measurement.test.ts` in the Runner package captures actual `thread/start`, `thread/resume` and `turn/start` parameters from the real runnerd facade with a scripted transport. It captures native Codex, ACPX Claude and OpenCode for input v4 and v5: eighteen receipts per variant. Every receipt records exact UTF-8 bytes, character counts and hashes of the instruction string, fixture tool schemas, turn input and their full projection. It checks finish/block descriptions, document/file rules, approval mode and identical start/resume tools and instructions. The fixture uses the actual production AGENTS file and a fixed projection of the core semantic catalog plus the reserved completion tools.
Run from `packages/paperclip-runner`:
```sh
PAPERCLIP_NATIVE_INSTRUCTION_REPORT=/absolute/path/measurement.json pnpm exec vitest run src/backends/native-instruction-measurement.test.ts
```
The receipt declares its source SHA, source file hashes, fixture hash and dirty state. A dirty overlay can aid diagnosis but is rejected for live admission. Temporary workspace paths are normalized to a fixed path for comparison. This is the complete declared Paperclip projection at that boundary, not the production server's full granted catalog or a capture of provider-owned stock prompts. Token counts, billing, provider preprocessing and cognitive consumption remain unknown. The capture distinguishes a resumed full task from the compact user-follow-up continuation envelope. Input v5 sends only new events and contract references for that continuation; its projection must remain identical between variants. Input v4 still wraps the compact message in a task envelope. Scripted resume and continuation capture do not qualify live resume behavior.
## Bounded live comparison
The explicit-only Product E2E suite is `native-instruction-consolidation`. Discovery requires no credentials:
```sh
pnpm test:e2e:runner -- --list --suite native-instruction-consolidation
```
Each source variant declares these original tasks on the same local native profiles:
| Profile | Model | Tasks |
| --- | --- | --- |
| Codex | `gpt-5.6-sol` | assigned-skill document completion; whole-task blocker |
| ACPX Claude | `claude-sonnet-5` | assigned-skill document completion; whole-task blocker |
| OpenCode | `openrouter/deepseek/deepseek-v4-flash-0731` | assigned-skill document completion; whole-task blocker |
Six cells per variant means twelve actual runs for the pair, each with one attempt. Use exact IDs with parallelism one and no automatic retry. Each cell uses the original task deadline and 1,000-cent company and agent hard stops. These budgets bound recorded Paperclip spend; they do not guarantee final provider invoice amounts. Do not run providers until the human authorizes the live scope. Stop to inspect a usable behavior failure; do not reroll it to obtain a pass.
The source gate requires clean committed sources, the declared base ancestry, one complete known source variant, no unrelated paths, the current fixture digest and all eighteen provider-free capture receipts. It rejects missing, duplicated, dirty, stale or paid capture evidence. It verifies the requested immutable source SHA when supplied. A hosted shallow checkout may fetch its exact immutable SHA from the public repository at bounded depths 8, 32 and 128, without provider keys or Git credentials. It verifies exact HEAD after each fetch. The original base-ancestry and changed-path checks must then pass. No immediate-parent substitute is used. The only admitted untracked files are the exact same-run build archive and checksum, after the existing strict hydration verifier checks them.
Admission rebuilds the TypeScript SDK from the current source with a credential-free environment and hashes the complete SDK outputs. Locally it also builds the native runner; hosted execution binds the selected native runner bytes to the verified same-run archive and records that local Rust calibration was not executed there. Preparation and verification preserve the source tree, fixture digest, metadata, build log/output hashes and selected native binary provenance. A mismatched or missing build fails before provider execution.
The human authorized the bounded twelve-run pair on 2026-10-03. This does not authorize retries, broader paid scope, a merge or separate derived-report publication.
The suite uses the original assigned-skill durable-document oracle and strict native completion grading. It retains named call-ID joins, acceptance/termination, final-response order, provider-final persistence, exact blocker owner/action/scope, workspace and issue/agent side effects, default instructions and budget evidence. Unknown or absent evidence cannot pass. No relaxed source-read matcher or provider-call join is introduced.
## Decision and evidence
Freeze both source refs, the common definition hash, models/profiles, permissions, default instructions, input construction, deadlines, budgets and compiled source identity before admission. Preserve every attempt, original grade, failure and usage receipt. Compare all six exact pairs and retained content; report new failures, new passes, unchanged failures, unchanged passes and uncomparable pairs separately. A passing total does not conceal a lost document, incomplete blocker report, extra work or a missing final response.
The reduction remains unqualified until the paired live evidence exists. Passing deterministic checks proves transport/catalog and control-plane behavior under the tested scripted inputs. A single live pair per cell gives bounded evidence, not general equivalence, causation, cost/speed trends, general coding quality, or live continuation coverage. Approval feedback and yielded continuation need their own retained cases before making broader claims. If any behavior worsens, hold this slice and inspect the original evidence before changing source or expanding paid scope.
doc/plans/2026-10-04-native-completion-answer-fix.md
+29
View File
@@ -0,0 +1,29 @@
# Native completion final-answer correction
The completion constraint reduction remains held until the corrected source has live evidence for final-answer quality. Keep the original candidate, historical source and all original grades immutable.
The correction keeps the shortened completion procedure while explicitly requiring a blocker explanation, owner and unblock action in the final reply. The existing document guidance now requires a canonical clickable document link. `write_document` returns a company/task-scoped `documentHref` in its idempotent receipt, derived in the document transaction from the saved key and actual task identity. No completion tool schema/description, fixed prompt, skill, permission or budget policy changes. The accepted completion feedback repeats canonical links only for this run's still-current saved document revisions, reconstructed from company/task-scoped database state rather than supplied URLs. Blocker feedback asks for the cause, owner and unblock action instead of describing completed work. Internal Markdown links retain their query and document/comment anchor when cached issue details resolve. These receipt, feedback and UI repairs add four production paths beyond the original three-file instruction reduction.
Only the manual instruction comparison uses the v3 final-answer observation. The existing `native-completion` suite retains its v2 verdict checks and does not acquire the browser-navigation requirement. A calibration demonstrates the same retained input can pass v2 and fail v3; original report files are never rewritten. The harness definition digest changes truthfully for future invocations. Its additional checks read only the actual run-attributed persisted provider final. A blocker label and action do not substitute for an explicit missing-access explanation. Document links must identify the exact task and one revisioned document at the instance origin; wrong origin, task, document, query, credentials or absent evidence fail. Exact call-ID joins, acceptance/termination, ordering, side-effect and budget checks remain enforced.
After saving the strict native snapshot, each completion cell clicks the rendered final-reply link in the browser. It must open the canonical saved document and show the original content marker in exactly one visible classic document card or document-specific side-panel tab. The navigation check follows the actual configured UI instead of requiring a classic-only element. Retain the navigation receipt and screenshot independently; a valid-looking Markdown URL alone does not qualify navigation.
Calibrate with correct paraphrases and plausible wrong answers, including the action-only omission. Replay the retained observations only as labeled additional diagnostics; never overwrite or regrade the original results. Provider-free measurement v2 captures eighteen shared runnerd RPC projections plus six direct OpenCode HTTP projections across v4/v5 start, resume and continuation. The latter exercises the concrete OpenCode backend using a local fake server. Both boundaries measure Paperclip-supplied payloads, not provider stock prompts or model cognition. No synthetic receipt qualifies live model behavior.
The human's paid-run authorization and subsequent request to fix the omission support one bounded corrective confirmation: the six exact `native-instruction-consolidation` candidate cells, one attempt each, no automatic retries, native Codex `gpt-5.6-sol`, ACPX Claude `claude-sonnet-5`, and OpenCode `openrouter/deepseek/deepseek-v4-flash-0731`, original local deadlines, and 1,000-cent company/agent hard stops. Each production correction must have a new immutable source/definition admission before another bounded confirmation. Preserve stopped campaigns, failed cells and canceled-before-provider cells separately. Never reroll an unchanged frozen failure. No new baseline provider run, broader campaign or merge is part of this correction. Stop and inspect a usable behavior failure.
Report exact source, definition/grader hashes, six outcomes, retained visible replies and document targets, actual run count, cleanup and billing coverage. Passing a single trial does not prove general equivalence, cause, live resume behavior, coding quality, speed or cost trends.
The receipt-only correction at `be604fcbf81ff238ee38774ff6e644bf0d84eb2d` failed its first Claude document cell; five remaining jobs were canceled before paid execution. The next correction at `3a7349ddc60142283c394121882288f2db07b215` passed both Claude and both Codex cases, but OpenCode again omitted the document link; its blocker job was canceled with the paid step skipped. Preserve both genuine failures and all canceled jobs. Browser navigation was not reached in either missing-link failure.
OpenCode's inner driver admitted the finishing report locally without invoking the controller feedback handler. Its proxy also discarded the controller response envelope, including the success flag. The correction forwards the exact terminal call ID, thread, turn, tool and structured result through the existing controller request channel. It waits for the controller before committing the inner result, preserves accepted response text and concrete rejection reasons, and rejects malformed acceptance or a turn that ended during feedback. Dynamic-tool unwrapping stays unchanged. A provider-free test crosses the real runnerd, proxy and fake OpenCode boundary: the first completion is rejected, the provider corrects it in the same turn, the second receives the exact final-response feedback, and only one semantic result is proposed.
This correction changes four additional OpenCode-only production paths. The shared instruction, server receipt/feedback and UI bytes remain identical to 3a7349d. Admit the new source and measure all scripted boundaries again. Confirm only the two affected OpenCode live cases on the new immutable source, one attempt each with the original model, deadlines and budget stops. Keep the four passing Claude/Codex observations explicitly attributed to 3a7349d, backed by the exact provider-path delta and final-head CI. Do not relabel them as live runs on the new head. No new baseline or unchanged-source paid retry is included.
The e171282 confirmation campaign 37257534042 was stopped during build after fresh review identified a controller/inner-session acceptance race. No paid step started and no provider was executed. Provider-free regression reproduces accepted feedback losing its result when idle/error arrives in flight. Completion settlement now holds terminal mapping, explicit interruption and close until the bound decision and tool result finish, and refuses a concurrent terminal submission before invoking the controller. Raw SSE frames remain retained at receipt; normalized terminal settlement follows the finishing decision. Confirm the same two OpenCode cases only on the newly admitted immutable source; preserve e171282's completed failing review and zero-provider campaign.
Fresh c3e0cb303 review identified a real serial-input dependency: an interrupt waits for completion while its controller response queues behind the interrupt. No paid campaign was admitted on this source. The proxy now handles only bound response frames outside the serial command queue; commands retain their order and bootstrap failure gates. EOF rejects existing controller waiters and prevents new unanswered requests, then drains the command queue and closes. A real production-bundled proxy, verified local native launcher and fake OpenCode MCP/SSE server reproduce the deadlock before the fix and verify accepted feedback reaches the provider, interruption completes, exactly one result is proposed and EOF exits. A second EOF-without-feedback case proposes no result. This is zero-provider proxy coverage; the real runnerd boundary remains separately covered. Fixture setup and macOS launcher failures are retained, not relabeled as behavioral failures.
The exact 267aeb3 source passed fresh 5/5 review, but confirmation campaign 37259746983 stopped before provider execution. Its document job entered the harness step, then failed source ancestry hydration before result creation: the fixed eight-commit fetch did not contain the required 2a8a99 base. The remaining blocker cell was canceled. The source was not behaviorally evaluated, and no graded result or cell artifact exists; retain the original failed job log and separate zero-provider receipt.
Hosted hydration now fetches only the immutable public source at bounded depths 8, 32 and 128. It verifies exact HEAD after every fetch and still requires real base ancestry. A missing or unrelated ancestor, changed HEAD, local checkout or non-shallow checkout does not receive a substitute proof. A real twelve-commit shallow-clone regression fails before the change and passes afterward. Production, fixture prompts, model/default/budget policy and behavioral grading bytes stay unchanged from 267aeb3. Admit the new setup source and confirm the same two OpenCode cases once; no provider run or original failure is retried.
doc/plans/2026-10-05-managed-aggregator-account-user-stories.md
+86
View File
@@ -0,0 +1,86 @@
# Managed aggregator accounts — acceptance stories
Date: 2026-10-05
## Expected behavior
1. **Discover existing accounts.** After saving an Arcade or Executor gateway, opening Apps discovers the accounts visible through that gateway. No individual app reconnection, task, extra executable connection, or access grant is required.
2. **Group accounts.** Notion appears once with its native account, a Composio account, two Arcade accounts, and an Executor account. Identical labels remain distinct by provider, gateway, and upstream account identity. Native Connect/Add account remains the onboarding action.
3. **Reconcile upstream changes.** Add or disconnect an upstream account, then use Refresh in only that gateway’s menu. A successful scan updates its accounts; other gateways’ observations remain intact.
4. **Manage upstream.** Imported account menus contain only Open in the provider. Links are HTTPS and contain no credentials. Executor workspace/self-hosted paths remain intact. Upstream deletion and per-app authorization stay upstream; Paperclip policies apply to the executable parent gateway.
5. **Optional Arcade sync.** A gateway using a project key and Arcade user ID reuses those credentials. Otherwise Set up account sync asks for an optional project key and user ID. Its vault credential is used for discovery only; gateway tool invocation still uses its existing credentials.
6. **Honest discovery states.** Unsupported inventory, expired sign-in, partial pages, and stale observations never become successful empty inventories or green checks. Failed scans retain previous accounts and invite refresh/setup.
7. **Isolation and rotation.** Account observations are scoped to company, saved gateway, viewing human, and credential version. Rotating a credential or changing the session endpoint hides prior observations until a successful scan. Account discovery cannot grant access.
8. **Navigate five chips.** Paperclip defaults to native discovery with all installed apps above it. Composio/Arcade scope discovery while retaining all connected account lines on grouped cards. Native cards appear under a provider only if that provider has observed accounts for the app, not merely because its catalog supports the app. Installed shows only installed apps; All includes every source. Executor's chip is temporarily hidden; its gateway and observed accounts remain available. A Paperclip search expands to All and clearing returns to Paperclip; explicit filters stay scoped. Pagination affects discovery only.
9. **Unknown integrations and small screens.** Unknown Executor integrations receive a separate card without guessed branding. Empty results remain actionable. Chips wrap and account rows remain readable at mobile widths.
10. **Inspect a saved gateway.** Composio setup opens its Permissions page. Opening that page starts one refresh, displays progress, and shows detected apps with their logos in a bounded, keyboard-scrollable list. Refresh Composio checks only this saved gateway. Partial failures retain observations as unverified. Account discovery does not change human/agent permissions. The redundant OAuth scope guidance and “Reconnect to update permissions” button are removed; actual authorization-repair controls remain available.
## Reproduction
Run this checkout’s Storybook on port 6200 and the disposable acceptance server:
```sh
node cli/node_modules/tsx/dist/cli.mjs tests/aggregator-accounts/test-drive.ts
```
Open `http://localhost:6200/iframe.html?id=apps-managed-accounts--full-stack-test-drive&viewMode=story`.
This mounts the production Apps page against production tool-access routes and a disposable PostgreSQL database. Only external provider responses are simulated. The upstream controls change fixture inventory; use the gateway menu to refresh and observe the result. Existing app data and other local services are untouched.
The catalog-only stories remain at `Apps/Catalog source selection` and demonstrate the five current chips, pagination, native onboarding precedence, and grouped accounts.
## Evidence and limitations
Verified in the embedded browser on 2026-10-05 against the production Apps component, production routes, and disposable PostgreSQL. External Composio, Arcade, and Executor responses were simulated.
| Story | Result and evidence |
| --- | --- |
| Existing accounts | Passed: saved gateways imported existing accounts without app reconnection. Gateway onboarding tests confirm Arcade returns to Apps without an agent task. |
| Grouping | Passed: one Notion card showed a native account, a Composio account, two accounts from each of two Arcade gateways, and an Executor account. Repeated “Work” labels remained separate. |
| Upstream changes | Passed: adding and disconnecting simulated Arcade accounts followed by its gateway’s Refresh updated only that gateway’s account rows. Other providers and the native account remained. |
| Upstream management | Passed: imported kebabs contained only Open in the provider. Executor’s link retained its workspace path. Browser verification inspected destinations; it did not complete external provider sign-in. |
| Optional Arcade sync | Passed: the browser saved a synthetic discovery key through the real manager-only endpoint and imported the second gateway’s accounts. Database tests also prove existing API-key/user-header reuse and discovery-only vault use. |
| Failure states | Passed: expired authorization and an incomplete page retained last-known accounts without green checks. Unsupported Executor inventory showed unavailable, retained stale accounts, and recovered after refresh. |
| Isolation and rotation | Passed: service tests cover viewing-user/gateway/company isolation, member/agent configuration denial, endpoint changes, and an actual vault credential rotation followed by discovery using the new value. UI/API-client tests prove user switches do not reuse another user’s account cache or pending HTTP response. Manager account responses also use private, no-store HTTP caching. |
| Navigation | Passed: all six chips, Paperclip-to-All search expansion, explicit source scope, clear search, installed pinning, pagination, and empty states. The catalog Storybook interaction also completed without console errors. |
| Unknown apps and mobile | Passed: an unknown Executor integration retained a separate card and unverified status. At 390px the production page’s content width was 382px, with wrapped chips and readable account rows. The viewport override was reset afterwards. |
The initial fixture run ended on the full-stack story. Its upstream controls are explicitly labeled simulated. That run did not exercise native OAuth or live provider dashboards; working Arcade/Executor credentials were unavailable.
### Permissions-page follow-up: real Paperclip test drive
The actual CLI `test-drive` server is running from this checkout at
`http://localhost:3105`, with an isolated PostgreSQL database and the agent key
from `~/.secrets`. The user subsequently connected a real Composio gateway.
The embedded browser verified its Permissions page at
`/AGG/apps/f878eeb0-b1b9-4081-b779-ffecf3b41e7a/permissions`:
- Detected Airtable and Circleback from the live saved Composio session.
- Manual Refresh Composio displayed “Refreshing…” and catalog-check progress,
then completed with both apps visible.
- Navigating away and returning automatically started a refresh without a click.
- The redundant sign-in guidance and update-permissions button are absent.
- The catalog exposes Paperclip, Composio, Arcade, Installed, and All.
- 317 focused AppDetail, AppsConnect, and Browse tests pass, including setup
navigation, first-load refresh, progress/completion, upstream reconciliation,
retained observations after failure, unsupported discovery, and manager-only
visibility. UI typecheck, UI production build, and token gates pass.
This walkthrough did not repeat OAuth sign-in or change upstream accounts. The
post-setup redirect is covered by connection-flow tests. The real gateway had two
observed apps, so overflow with a long real account inventory was not exercised.
The list has a bounded height and keyboard-focusable vertical scroll container.
Refresh and settled-page screenshots are saved as `composio-apps-refreshing.png`
and `composio-permissions-connected-apps.png` in this task's visualization folder.
### Automated checks
- 261 focused UI/provider/API-client tests passed: Browse, AppsConnect, inventory adapters, and HTTP request isolation.
- 8 database/service/authorization tests passed, with no skips in the final run. These reused the disposable browser-test database because the host had exhausted its 32 PostgreSQL shared-memory slots. The optional `PAPERCLIP_AGGREGATOR_TEST_DATABASE_URL` test override accepts only a local, disposable database.
- 9 shared catalog tests passed.
- Final `pnpm -r typecheck`, `pnpm build`, token gates, and `git diff --check` passed.
- `pnpm test:run` was attempted but did not complete successfully. It encountered a timeout in `workspace-git-snapshot-streaming.test.ts`, failures in `heartbeat-run-event-sequencing.test.ts`, and numerous PostgreSQL startup skips; the run ended with exit 130. A separate remote-MCP compatibility run also could not start PostgreSQL. These repository-wide checks are not reported as green.
Local verification logs: `/tmp/paperclip-aggregator-focused-final.log`, `/tmp/paperclip-aggregator-db-final.log`, `/tmp/paperclip-full-typecheck-final.log`, `/tmp/paperclip-full-build-final.log`, `/tmp/paperclip-token-gates-final.log`, and `/tmp/paperclip-full-test.log`.
Desktop and mobile screenshots are saved in the task’s visualization workspace as `managed-aggregator-accounts.png` and `managed-aggregator-accounts-mobile.png`. This is fixture-backed acceptance evidence, not live provider certification or a production release sign-off.
doc/plans/2026-10-05-native-procedure-comparison.json
+5433
View File
File diff suppressed because it is too large. Load diff
doc/plans/2026-10-05-native-procedure-guidance.md
+382
View File
@@ -0,0 +1,382 @@
# Native hiring and dependency guidance
Status: **ship measurement and eval coverage only. Do not ship the procedure
relocation or the unqualified runtime repairs.**
The final PR keeps production agent behavior byte-identical to master
`a65ca0950834a85bb93bcc4b4042ecacdebfef53`. Its changes are limited to the
measurement test, explicit eval selection, correct hiring credential selection,
company/lead budget stops, test-runner configuration, and retained reports.
No production prompt, tool description, tool schema, session catalog, dependency
mutation or status-transition code changes are included in the final diff.
The experiment did not pass the no-regression gate. The first corrected
comparison had baseline 5 PASS / 1 FAIL and candidate 3 PASS / 3 FAIL: two new
failures, no new passes, three unchanged passes and one unchanged failure.
The attempted repair also had two new failures among five comparable pairs.
Moving text out of the fixed prompt did not justify shipping worse outcomes.
Single trials do not establish that the changed instructions caused a failure.
The original candidate reduced the complete standing projection by 460 bytes,
about 0.9%. Restoring important instructions reduced the saving to 125 bytes,
about 0.25%. A later, unqualified dependency guard made the projection 127 bytes
larger than baseline. None of those changes is included in the final production
tree. The final measurement records the unchanged full catalog. Bytes are not
tokens, billing, or proof of upstream loading or truncation.
The [original sanitized comparison](2026-10-05-native-procedure-comparison.json)
and [readiness comparison v4](2026-10-05-native-procedure-readiness-v4.json)
retain exact sources, original grades and evidence hashes. Their old source
revisions remain historical experiments; they do not describe production changes
in this measurement-only PR. No completed behavioral failure was rerolled to
obtain a pass. Earlier infrastructure recovery and missing evidence remain
explicit below. This follows the merged completion slice in #15151.
## Final scope and verification
The server measurement test instantiates the actual standard-mode tool authority
with all advertised tools and input schemas. It captures scripted native start,
resume and continuation payloads across Codex, ACPX Claude and OpenCode and the
OpenCode MCP declaration list. These are provider-free measurements.
The two original Everyday Workflows stories remain explicit-only and keep their
independent artifact and ordering oracles. OpenCode is added only to the local
hiring/reuse and delegation/feedback cells. These stories use one attempt per
cell and actual company and lead-agent budget stops. Managed hiring selects
the credential provider from the chosen profile, including OpenRouter. Existing
Node test files run under Node's test runner instead of being misclassified as
empty Vitest suites.
The final production identity check compares `packages/` and production
`server/` files against the fixed master context. A fresh CI and review must
qualify the final tree. The full local database suite is unavailable while this
host's PostgreSQL shared-memory slots are exhausted; hosted CI provides those
database checks. No new paid campaign is needed to compare unchanged production
bytes. This does not claim that the existing product is free of the failures
observed in the retained trials.
## Unqualified runtime repairs retained for follow-up
The local branch `codex/native-procedure-controller-repairs-unqualified` at
`7e270a3d3` preserves the attempted controller repairs. It is not part of this
PR's final diff and has not passed live qualification. It scopes completion
wakes to each committed transition and rejects silent removal of unfinished
dependencies, with explicit handling for obsolete dependencies. Its regression
tests still require database execution. Source typecheck, catalog generation,
and the non-database measurement/session checks passed locally.
The remaining issues need separate bounded investigation:
- Reopened child completion can reuse a previously consumed parent wake key.
- A parent can discard a still-running required dependency and finish early.
- OpenCode's v4 hiring candidate failed the exact-credential persistence guard
in its local SQLite database. Cleanup removed that database. The credential
identity and exact persistence mechanism are not retained. No cause or fix
is claimed, and no credential check is weakened.
## Readiness comparison v4 — historical failed experiment
Candidate `aba7ec219b588de02cf323b4ebca559a105e6d01` and baseline
`ce31f5efd0d416205c3994c55dd02b645f8b8423` use common master
`a65ca0950834a85bb93bcc4b4042ecacdebfef53`. Candidate
[campaign 37348723829](https://github.com/paperclipai/paperclip/actions/runs/37348723829)
and baseline [campaign 37348764875](https://github.com/paperclipai/paperclip/actions/runs/37348764875)
use trusted workflow `59015846ae02f935411afc620e0867ce812378fb`, distinct
from both measured trees. Eleven result/API/ledger sets and 99 evidence hashes
are retained. Their final ledgers contain 56 started runs, in addition to the
earlier cohorts. All eleven cleanup results passed.
Candidate: 3 PASS / 3 FAIL. Baseline: 3 PASS / 2 FAIL / 1 setup cell without a
behavioral grade. Comparable pairs: two new failures, two new passes and one
unchanged pass. The remaining Codex delegation pair is uncomparable because
baseline Docker setup timed out before its paid step; no behavioral grade or
final result artifact exists for that cell.
| Story and harness | Baseline | Candidate | Observed missing behavior |
|---|---|---|---|
| Codex hiring/reuse | PASS | PASS | None observed by the original oracle |
| Codex delegation/feedback | No behavioral grade | FAIL | Parent remains blocked after the revised child finishes |
| Claude hiring/reuse | FAIL | PASS | Baseline did not deliver the revised ZIP |
| Claude delegation/feedback | PASS | FAIL | Candidate finishes the parent before the child revision |
| OpenCode hiring/reuse | PASS | FAIL | Candidate credential-persistence guard fails |
| OpenCode delegation/feedback | FAIL | PASS | Baseline finishes the parent before the child revision |
The two new passes do not offset the new failures. The `aba7ec2` CI passed on
attempt 2 after five infrastructure-interrupted jobs were recovered and its
fresh review was 5/5; source checks did not clear these behavioral failures.
## Historical experiment scope
The original paid comparison used master
`a386a599983519eb1d399f8b770bfccdb2a74762` as common context. It moved
hiring/reuse and assigned-worker guidance to `hire_agent` and `create_task`,
kept dependency discovery in the fixed prompt, and returned waiting instructions
from `set_dependencies`. It advanced prompt and session-catalog revisions.
Those production changes have been removed from the final PR. Connection
procedures and legacy skill/API instructions remain unchanged.
## Measurement boundary
Capture the actual standard-mode server tool authority with API tools enabled,
a local workspace, and no assigned external apps. Measure fixed instructions,
all advertised tool descriptions and input schemas, and the serialized task
input together. Scripted native start/resume/continuation checks cover Codex,
ACPX Claude and OpenCode; authenticated MCP tools/list checks the OpenCode
bridge separately. Export source identity, file hashes, bytes and tool counts.
These receipts have zero provider calls. Bytes are not model tokens or invoice
costs. This boundary cannot establish the upstream SDK's private instructions,
lazy loading, truncation or cognitive use of returned guidance. The previous
completion-only capture selected a partial catalog and is not a full-tool
baseline. Preserve its historical evidence unchanged.
## Historical matched live comparison plan
Use the existing explicit-only `everyday-workflows` suite with original
`hire-reuse` and `delegate-feedback` requests and independent artifact oracles.
Select only native Codex `gpt-5.6-sol`, ACPX Claude `claude-sonnet-5`, and OpenCode
`openrouter/deepseek/deepseek-v4-flash-0731`, in local environments.
Freeze common measurement, harness and test-runner repairs in both branches
before the candidate production changes. The historical branch keeps the
current production prompt and tool contracts. Record exact measured source
SHAs separately from the trusted master workflow definition and selected
runtime/artifact hashes. Never label a later source revision as the measured
revision without showing its delta.
The plan has six cells per variant, one attempt per cell, a 12-minute cell
deadline, at most 12 story run records per cell, and a 1,000-cent company and
lead-agent hard stop per cell. The original campaign applied the company cap
but mistakenly left the lead budget at 0; the corrected common setup verifies
both actual API payloads. All worker runs count toward the company budget;
individual worker caps are not asserted.
Count every actual run, including notifications and failed attempts. No broad
matrix, automatic retries or baseline rerolls are part of this comparison.
Inspect original grades and retained content for persistent teammate identity,
reuse on revision, worker ownership, independently tested delivered artifacts,
parent review, dependency release, and final ordering. Check per-pair changes;
equal totals are insufficient. Preserve every original failure and missing
evidence. Model-authored tests cannot replace the existing independent oracle.
These two stories do not qualify arbitrary live resume, every existing-blocker
combination, general coding quality, or cost/speed trends. Explicitly report
missing evidence. Do not loosen the original oracle to create a pass.
## Historical complete-catalog measurement
The corrected source `ffe847fabaebbf24bc93924a4b6c8922d46a1fb6` is compared with
baseline `aecfa3b6a5cab110a9b926e93705311bbcf4db47`. Both include the same
measurement fixture and common eval repairs. Exactly 12 source/generated/unit
paths differ; 256 common fixture files have identical bytes.
| Normalized extracted component | Baseline bytes | Corrected candidate bytes | Change |
|---|---:|---:|---:|
| Fixed instructions, start/resume | 1,809 | 1,256 | −553 |
| All 39 tool declarations including schemas | 44,944 | 45,037 | +93 |
| Task input, start/resume | 1,993 | 1,993 | 0 |
| Combined standing projection, start/resume | 48,781 | 48,321 | −460 |
| OpenCode MCP tools/list declarations | 44,249 | 44,342 | +93 |
Scripted Codex, ACPX Claude and OpenCode deliveries give the same comparative
change. The serialization of the extracted components is measured separately
from its path-normalized comparison. The fixture's real temporary paths add
168 bytes to the combined start/resume projection in each variant. Neither
projection is the entire transport request. Returned dependency guidance adds
input when used, so this is not an overall token, latency or cost saving claim.
The measurement produces zero provider calls and does not prove upstream
loading or truncation behavior.
## Original comparison — failures retained
Original sources were candidate `eb01d073c35134bf0d373947b55a79f9e443f8ee` and
baseline `64cd2194a1d058356679b653c181f16404aefc80`, using trusted master workflow
`a386a599983519eb1d399f8b770bfccdb2a74762`. Source identity remains distinct from
workflow identity and the later measurement-only correction.
- [Original candidate campaign](https://github.com/paperclipai/paperclip/actions/runs/37325777217)
- [Original baseline campaign](https://github.com/paperclipai/paperclip/actions/runs/37325870695)
| Profile | Hire/reuse baseline → candidate | Delegate/feedback baseline → candidate |
|---|---|---|
| Codex | PASS → PASS | PASS → FAIL |
| ACPX Claude | PASS → FAIL | PASS → FAIL |
| OpenCode | FAIL → FAIL | FAIL → PASS |
There are three new overall failures, one new pass, one unchanged pass and one
unchanged failure. The candidate did not qualify. Final ledgers match the
result run-ID sets: 25 started baseline runs and 15 candidate runs, zero retry
links. All twelve cell cleanup receipts passed. Missing/zero billing amounts
and unmetered host runtime prevent any claim about actual cost savings.
The candidate Claude hire created Morgan and a child task, then ended with a
waiting message without recording dependencies or using a terminal tool. The
lead failed with `native_finalization_missing`. The corrected v7 prompt keeps
explicit `set_dependencies` and `paperclip_block` discovery. This is a concrete
missing behavior; a single trial does not establish causation.
The candidate Codex delegate failed in Riley's worker turn with the provider
error `Selected model is at capacity` / `serverOverloaded`. Its parent had
received the dependency guidance. Candidate Claude delegation failed opening
an ACPX session (`session_ensure_failed`); its underlying cause is unknown.
Both original grades and classifiers remain unchanged.
Both OpenCode hire cells failed common setup requesting an OpenAI credential
although OpenRouter was selected, before any agent run. Shared setup now uses
the profile's actual credential. A separate nonce/cell-ID bug left original
lead budgets at 0; six nonce-based setup tests now verify company and lead caps
using only the selected provider credential. These common control changes are
why the corrected campaign uses a newly matched baseline.
The baseline OpenCode delegation delivered an artifact passing the independent
oracle but completed the parent before the child's final revision. Candidate
passed both the artifact and ordering checks. Correct output alone did not
qualify that baseline outcome.
## Corrected comparison
- [Candidate ffe847f](https://github.com/paperclipai/paperclip/actions/runs/37331580879)
- [Baseline aecfa3b](https://github.com/paperclipai/paperclip/actions/runs/37331642168)
- [Candidate recovery for two interrupted cells, same ffe847f source](https://github.com/paperclipai/paperclip/actions/runs/37334061104)
These use the same corrected fixtures, original requests and artifact graders,
with one attempt per campaign cell. The original campaign is preserved and is
not relabeled as this revision. The common suite hash is
`acd17b4acbd7051070531f7d7587131139900f54245b992eb7a62faacda8e334`.
| Profile | Hire/reuse baseline → candidate | Delegate/feedback baseline → candidate |
|---|---|---|
| Codex | PASS → PASS | PASS → FAIL (recovery) |
| ACPX Claude | PASS → PASS | PASS → PASS (recovery) |
| OpenCode | PASS → FAIL | FAIL → FAIL |
There are **two new failures, zero new passes, three unchanged passes, one
unchanged failure and zero pending pairs**. Workflow completion is not the
behavioral grade. These are the original result grades; no regrading was done.
### Missing and recovered behavior
**Codex delegation regressed in the observed pair.** The first parent turn
recorded its dependency and blocked correctly. After feedback, the parent
reviewed a stale ZIP and requested a replacement. An API comment operation was
rejected with `API comments cannot change runner execution state`. The child
finished the replacement at 15:45:48.284 UTC. The parent then recorded the
dependency at 15:45:51.801–15:45:59.295 UTC; its receipt scheduled no wake. The
parent blocked and finalized at 15:46:19.909 UTC. The child was Done, but the
parent remained Blocked with no active continuation. All four native runs had
successful run status; that does not make the task outcome successful. This
sequence does not by itself establish a prompt, race or platform root cause.
**OpenCode hiring regressed in the observed pair.** It hired the expected
teammate and produced an initial artifact that passed the independent checks.
It reused the same teammate for the separator revision, then requested further
CLI argument-handling changes. After nine started runs, the story reached the
12-minute deadline with parent and revision work still in progress. Cleanup
cancelled the remaining work. The final revised-ZIP and settled-outcome checks
were not completed; they are not assumed to pass. The baseline passed after
four runs. This single trial does not establish a speed or cost trend.
**OpenCode delegation failed in both variants.** The artifacts passed the
independent output checks, but the parents finished before the final child
revision. Candidate parent/child completion times were 15:33:43.628 /
15:35:03.222 UTC; baseline times were 15:35:21.429 / 15:36:03.043 UTC. Both
parents lacked review of that final revision. Equal FAIL totals conceal neither
this missing behavior nor the passing artifact checks.
**Claude hiring now passes all 45 original checks.** Retained semantic receipts
show dependency recording, returned guidance and an accepted current-track
block with the child agent as owner. The parent later resumed and finished.
This repairs the original missing dependency/finalization observation in this
trial. It does not prove cognitive use of the guidance or every hiring tool
path; API hiring remained available.
### Interruptions and accounting
Candidate Codex and Claude delegation jobs received runner shutdown signals at
15:27:38 UTC and were cancelled at 15:27:50 UTC. Jobs `111838521694` and
`111838521502` retained no result, final ledger or cleanup receipt. Their
behavioral grades and total actual runs/charges are unknown. Eight distinct
run-record IDs were visible in partial logs; this is not a complete started-run
ledger. Preserve the workflow failures and missing evidence.
Only those two missing candidate cells received one bounded recovery each, on
the identical measured source. No completed baseline or other candidate cell
was repeated. The original workflow revision was `a386a599`; recovery used
`a65ca0950834a85bb93bcc4b4042ecacdebfef53` after master advanced. Workflow file
bytes were identical, SHA-256
`eb570267e66043c1196338bb386b07ab8e8e8306ba04b6223f13b73b04fdc8f4`.
The measured source stayed `ffe847f`, distinct from both workflow revisions.
All twelve completed/recovered cells have matching result/final-ledger run
sets and passing cleanup receipts. They contain 27 baseline and 33 candidate
started runs. The original campaign contains 40 more: **100 retained started
runs, plus incompletely known activity from the two interrupted jobs**. Zero
retry links within the completed ledgers do not erase the two infrastructure
recoveries. The audits retain 100 original and 108 corrected JSON evidence
hashes. Actual charges remain unknown because usage and interruption records
are incomplete and host runtime is unmetered. No free-call or savings claim is
made.
ACPX provider execution IDs are not proven mapped to host call IDs. No strict
no-extra-work claim or feedback-consumption inference is made from matching
names, ordering or counts. These evidence limits remain even for a passing
original story grade.
## Historical integration and repository checks
After the paid sources were frozen, the PR merged master
`a65ca0950834a85bb93bcc4b4042ecacdebfef53` as
`ee096aa23fc88a001e7666215bcd338b5863f377`. Three generated contract conflicts
were resolved by normal generation from the combined sources. The paired
provider-free baseline is `ce31f5efd0d416205c3994c55dd02b645f8b8423`.
Their twelve intended differing paths are identical to the paid source delta;
all 256 common fixture files remain byte-identical. **No live campaign measured
the integrated head.** Later documentation-only commits do not change that.
The integrated full-catalog projection is 49,200 → 48,740 normalized bytes at
start/resume and 47,422 → 46,962 during continuation. The 460-byte reduction is
unchanged. Master's project-discovery schema adds 419 bytes to both tool sets.
The actual extracted start/resume projection is 49,368 → 48,908 bytes. All 39
declarations remain present; this still does not measure private vendor prompts,
model tokens, lazy loading or upstream truncation limits.
Before integration, 74 focused tool/session/measurement checks, 1,252 eval-support
Vitest checks, 128 Node checks and the eval TypeScript check passed. Repository
typecheck and build passed before the prompt-only v7 correction. The corrected
source CI then passed typecheck, build, tests and all eight browser shards. An
interrupted canary job was retried once; that is separate from paid eval recovery.
At integrated `ee096aa23`, local measurement/session checks passed 48 tests;
23 authority tests could not start because PostgreSQL initialization failed,
and 21 project-tool tests were skipped by the unsupported database helper.
The integrated baseline passed six measurement tests. The older full local
suite was stopped after source revisions changed during its run. Its failures
remain retained; it is not reported as green.
[Integrated CI server shard 5](https://github.com/paperclipai/paperclip/actions/runs/37335450901/job/111849219339)
failed `workspace-git-snapshot-streaming.test.ts`: the four Git filename lanes
over 32 MiB exceeded the 180-second timeout (707 tests passed, two skipped,
one failed in that shard). The aggregate verify job therefore failed. The cause
has not been established; this is not reclassified as an infrastructure pass.
The [review summary](https://github.com/paperclipai/paperclip/pull/15218#issuecomment-5996723170)
gave integrated `ee096aa23` 5/5 but noted project-discovery authorization work
for actors with sparse visibility. Both inline measurement findings are
resolved; the summary's separate concern is not erased by that count.
At this historical checkpoint the failed behavior comparison required keeping
the candidate draft. The final scope separates measurement from the rejected
reduction. Future behavior changes need their own diagnosis and qualification;
completed paid failures must not be rerolled simply to obtain passing grades.
## Historical behavior-change gates (not met; change removed)
- [x] Freeze common fixtures and both source revisions.
- [x] Export comparable full-catalog delivery projections.
- [x] Pass 74 focused checks, 1,252 eval-support Vitest checks and 128 Node checks.
- [ ] Complete repository typecheck, tests and build.
- [x] Run and inspect the bounded matched campaign, including original failures.
- [ ] Meet the no-regression gate: **failed, two newly failing corrected pairs**.
- [ ] Verify current-head CI, review and conflicts before readiness.
- [x] Preserve original and corrected grades, hashes and incomplete accounting.
No merge is authorized.
doc/plans/2026-10-05-native-procedure-readiness-v4.json
+2019
View File
File diff suppressed because it is too large. Load diff
doc/run-log-events.md
+18
View File
@@ -52,6 +52,13 @@ and incomplete result-delivery command IDs and statuses. If execution and
cleanup both fail, execution retains its original error identity and cleanup is
attached as `cleanupError`.
Semantic settlement also includes up to 20 content-free failure records, with
the call ID, operation ID, stage (`dispatch` or `persist_result`), and cause.
Causes distinguish an oversized command, a full command journal, known storage
errors, dispatcher rejection, and other persistence failures. Exception messages
and tool results are excluded. These diagnostics do not authorize replay of an
operation whose outcome is unknown.
Instruction writes also commit an `agent.instruction_write_attempted` activity
row and a run-scoped `instructionToolAttempts` entry before permitting the
filesystem effect. They retain the call ID, operation ID, and input digest, not
@@ -320,6 +327,17 @@ the enclosing workspace task. The original error and restore safety policy are
unchanged. These lines stay in the instance run log and its configured durable
storage, and are not new first-party telemetry events.
The optional `step` identifies the failed restore operation. For
`phase=workspace` and `step=git_integration`, `gitCommand` identifies one fixed
command family (`rev_parse`, `symbolic_ref`, `merge_base`, `merge_tree`,
`commit_tree`, `update_ref`, or `log`). `gitFailureKind` is `merge_conflict`,
`invalid_object`, `ref_conflict`, `permission_denied`, or `unknown`; it is a
bounded diagnostic clue, not a new recovery or retry decision. Only supported
exit/OS codes and recognized Git messages produce a specific classification.
No command arguments, stderr, filenames, repository URLs, or ref names are saved.
The same closed fields persist in `workspaceRestoreDiagnostic` and are
revalidated before projection into an enabled Sentry failure report.
## Codex resume usage snapshot
The native runner retains a bounded local `harness.diagnostic` event with code
docker/daytona-runner/Dockerfile
+11 -11
View File
@@ -33,7 +33,7 @@ COPY cli/package.json ./cli/package.json
# The complete resolved lock (including transitive integrity hashes) is reviewed.
# Reject registry-time drift BEFORE installing packages or running lifecycle code.
# Refresh this digest together with source/provider dependency changes.
ARG PAPERCLIP_RUNNER_LOCK_SHA256=70af8ab3d7051c85fc1a55c11e9afe8887d9711232e3c6e97666006562217e5f
ARG PAPERCLIP_RUNNER_LOCK_SHA256=d3c4cffe7d127d99789cf354c5275246526f5396d2a86ce0d387352f68a2394b
# pnpm 9 subtracts PNPM_WORKERS from available CPUs; it is not a worker count.
# Subtract all available CPUs to select its minimum (one tarball worker).
RUN export PNPM_WORKERS="$(node -p 'require("node:os").availableParallelism()')" \
@@ -65,9 +65,9 @@ ENV PATH=${PAPERCLIP_RUNNER_PROVIDER_PACK_ROOT}/node_modules/.bin:/usr/local/sha
# Never add a second CLI version to work around a runner compatibility pin.
RUN npm uninstall -g @anthropic-ai/claude-code @openai/codex opencode-ai \
&& npm install -g \
@xai-official/grok@1.0.41 \
@google/gemini-cli@0.60.0 \
@moonshot-ai/kimi-code@2.0.2 \
@xai-official/grok@1.0.46 \
@google/gemini-cli@0.62.0 \
@moonshot-ai/kimi-code@2.1.1 \
&& npm cache clean --force
# Hermes requires Python >=3.11,<3.14; the image's default Python is newer.
@@ -78,8 +78,8 @@ RUN /usr/bin/python3 -m venv /opt/hermes \
&& /opt/hermes/bin/pip install --no-cache-dir hermes-agent==0.19.0 \
&& ln -sf /opt/hermes/bin/hermes /usr/local/bin/hermes
ARG CURSOR_VERSION=2026.09.26-dd393fe
ARG CURSOR_SHA256_AMD64=8085fd120f5c71f4eae7fea26a043718e5644e3071e4fab3220a0e58c51f9593
ARG CURSOR_VERSION=2026.10.01-e373342
ARG CURSOR_SHA256_AMD64=a79726c6e644520e993970be4c45775a6889802b67abe461a677a53219ae28e8
RUN set -eu; \
arch="$(dpkg --print-architecture)"; \
[ "$arch" = "amd64" ] || { echo "FATAL: cursor pin only covers amd64, not $arch" >&2; exit 1; }; \
@@ -93,8 +93,8 @@ RUN set -eu; \
ln -sf /usr/local/bin/cursor-agent /usr/local/bin/agent; \
chmod -R a+rX /opt/cursor
ARG GH_VERSION=2.101.0
ARG GH_SHA256_AMD64=9bca2d1c16825f109907a23307628a2f0698fbf99662b73a5cf0b020293072b8
ARG GH_VERSION=2.102.0
ARG GH_SHA256_AMD64=bb766f710eef8ede859c18578c72c327597cd4c8a85b06001b1f3843c6019386
RUN set -eu; \
arch="$(dpkg --print-architecture)"; \
[ "$arch" = "amd64" ] || { echo "FATAL: gh pin only covers amd64, not $arch" >&2; exit 1; }; \
@@ -148,9 +148,9 @@ RUN /bin/sh -lc 'set -eu; \
for command_name in acpx claude-agent-acp codex-acp; do \
command -v "$command_name" >/dev/null || { echo "FATAL: $command_name not on PATH for daytona user" >&2; exit 1; }; \
done; \
test "$(codex --version)" = "codex-cli 0.156.0"; \
test "$(claude --version)" = "2.1.280 (Claude Code)"; \
test "$(opencode --version)" = "1.18.32"; \
test "$(codex --version)" = "codex-cli 0.160.0"; \
test "$(claude --version)" = "2.1.286 (Claude Code)"; \
test "$(opencode --version)" = "1.18.34"; \
test "$(acpx --version)" = "0.13.1"; \
test "$(claude-agent-acp --version)" = "0.73.0"; \
test "$(codex-acp --version)" = "@agentclientprotocol/codex-acp 1.6.2"'
docker/daytona-runner/README.md
+17 -11
View File
@@ -1,14 +1,14 @@
# Paperclip Daytona runner image
Ordinary provider packs now include pinned Cursor assets for Linux x64; no
`--candidate-providers=cursor` flag is needed. Cursor admission remains disabled
until the [production readiness gates](../../doc/plans/2026-10-03-cursor-production-readiness.md)
pass. The public CLI installation command is `paperclipai runtime setup cursor`;
`--candidate-providers=cursor` flag is needed. Cursor admission is enabled after
the [production readiness gates](../../doc/plans/2026-10-03-cursor-production-readiness.md)
passed. The public CLI installation command is `paperclipai runtime setup cursor`;
it runs explicitly on the execution host and is never an npm installation hook.
This image is the Paperclip Cloud fleet sandbox image plus a source-built
`paperclip-runnerd` and immutable provider pack. The pack contains Node 24.11,
OpenCode 1.18.32, the compiled OpenCode proxy, ACPX 0.13.1 sidecar, qualified ACP
OpenCode 1.18.34, the compiled OpenCode proxy, ACPX 0.13.1 sidecar, qualified ACP
agents, and the production lockfile. Its manifest digests each executable bridge
and binds the pack to the runner source revision, avoiding artifact upload and
npm installation on every fresh lease.
@@ -20,14 +20,20 @@ image that this Dockerfile can extend directly.
## Harness versions
The September 22, 2026 refresh pins Codex 0.156.0, Claude Agent SDK
0.3.280 (Claude Code 2.1.280), and OpenCode 1.18.32 in the shared provider
The October 2026 refreshes pin Codex 0.160.0, Claude Agent SDK
0.3.286 (Claude Code 2.1.286), and OpenCode 1.18.34 in the shared provider
pack. Claude Code 2.1.280 is the minimum for
[Opus 5.5](https://code.claude.com/docs/en/model-config); it also supports
Fable 5.1. Codex uses the current
[GPT-6 Sol and Luna model IDs](https://learn.chatgpt.com/docs/models).
Grok CLI 1.0.41 supports the current
[Grok 4.7](https://docs.x.ai/developers/grok-4-7) model family.
[Opus 5.5](https://code.claude.com/docs/en/model-config) and 2.1.284 is the
minimum for Sonnet 5.5; the pinned runtime also supports Fable 5.1. Codex
0.160.0 ships bundled metadata for the current
[GPT-6.1 Sol, GPT-6 Sol, and GPT-6 Luna model IDs](https://learn.chatgpt.com/docs/models).
The same refresh pins Grok CLI 1.0.46, Gemini CLI 0.62.0, Kimi Code 2.1.1,
Cursor CLI 2026.10.01-e373342, and GitHub CLI 2.102.0 in the sandbox layer.
The native Cursor provider uses its separately verified distribution, pinned to
2026.09.26-dd393fe; it does not use the sandbox layer’s global Cursor executable.
Grok CLI 1.0.46 supports the current
[Grok 4.7](https://docs.x.ai/developers/grok-4-7) model family. Hermes stays
at 0.19.0, the newest release on PyPI.
Keep the patched ACP bridge versions separate from their CLI runtime pins.
Their executable digests do not change when only the runtime dependency
docs/deploy/environment-variables.md
+1 -1
View File
@@ -24,7 +24,7 @@ All environment variables that Paperclip uses for server configuration.
| `PAPERCLIP_RUNNER_CA_BUNDLE_PATH` | (unset) | Optional PEM CA bundle for direct runner WSS. Platform roots remain enabled. There is no insecure TLS bypass. |
| `PAPERCLIP_RUNNER_REMOTE_BINARY_PATH` | (host build) | Host-local path to a `paperclip-runnerd` artifact built for the remote target OS and architecture. Required when Paperclip and the remote sandbox do not share a compatible platform; build metadata and the required transport mode are verified before launch. |
| `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH` | (unset) | Optional host-local path to a Codex executable built for the remote target OS and architecture. For remote Codex-backed runners, Paperclip stages and verifies this executable beside `paperclip-runnerd`. |
| `PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` | (unset) | Optional pinned npm package spec (for example, `@openai/codex@0.156.0`) installed inside each fresh remote lease when its Codex harness is not baked into the sandbox image. Mutually exclusive with `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH`; Paperclip verifies the installed executable before starting `runnerd`. |
| `PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` | (unset) | Optional pinned npm package spec (for example, `@openai/codex@0.160.0`) installed inside each fresh remote lease when its Codex harness is not baked into the sandbox image. Mutually exclusive with `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH`; Paperclip verifies the installed executable before starting `runnerd`. |
| `PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH` | `/opt/paperclip-runner/provider-pack` in Docker; otherwise unset | Host-local path to the immutable provider pack built by `pnpm --filter @paperclipai/paperclip-runner build:provider-pack`. Stamped standard Docker images include the pack; downstream compositions and the `cloud` target inherit it. Unstamped local Docker builds skip pack generation. The pack includes its target-built Node 24.11+ runtime, locked production dependencies, OpenCode proxy/executable, and ACPX sidecar. Remote OpenCode and ACPX fail closed without it. A preinstalled pack is accepted only when its complete digested manifest matches this build-owned pack; otherwise Paperclip stages this pack into the sandbox. |
| `PAPERCLIP_HIDDEN_SETTINGS` | (unset) | Comma-separated settings surfaces to hide from the UI and floor at the API, for operators hosting Paperclip for others (managed cloud, internal shared server). See [Hiding settings surfaces](#hiding-settings-surfaces). |
| `PAPERCLIP_SETTING_DEFAULTS` | (unset) | JSON object replacing the schema default of selected instance settings, for hosting operators. See [Operator setting defaults](#operator-setting-defaults). |
package.json
+3 -3
View File
@@ -73,7 +73,7 @@
"test:runner-recovery": "vitest run server/src/services/native-runtime/native-replacement-evidence.test.ts server/src/services/native-runtime/stopped-codex-turn.test.ts server/src/services/native-runtime/native-safe-replacement.test.ts",
"test:e2e:browser-context": "playwright test --config tests/e2e/playwright-company-context.config.ts",
"test:e2e:runner:browser-support": "playwright test --config tests/runner-e2e/playwright-support.config.ts",
"test:e2e:runner:unit": "vitest run --config tests/runner-e2e/vitest.config.ts",
"test:e2e:runner:unit": "vitest run --config tests/runner-e2e/vitest.config.ts && node --test tests/runner-e2e/native-completion-checks.test.mjs tests/runner-e2e/native-completion-git-source.test.mjs tests/runner-e2e/native-completion-source-contract.test.mjs",
"test:e2e:runner:stock-harness": "node tests/runner-e2e/stock-harness-checks.mjs",
"test:e2e:runner:typecheck": "tsc -p tests/runner-e2e/tsconfig.json",
"test:e2e:runner:report": "node cli/node_modules/tsx/dist/cli.mjs tests/runner-e2e/report.ts",
@@ -121,8 +121,8 @@
"postgres@3.4.9": "patches/postgres@3.4.9.patch"
},
"overrides": {
"@agentclientprotocol/codex-acp@1.6.2>@openai/codex": "0.156.0",
"@agentclientprotocol/claude-agent-acp@0.73.0>@anthropic-ai/claude-agent-sdk": "0.3.280",
"@agentclientprotocol/codex-acp@1.6.2>@openai/codex": "0.160.0",
"@agentclientprotocol/claude-agent-acp@0.73.0>@anthropic-ai/claude-agent-sdk": "0.3.286",
"rollup": ">=4.59.0",
"react": "^19.2.8",
"react-dom": "^19.2.8",
packages/adapter-utils/src/acpx-engine/execute.test.ts
+29
View File
@@ -41,6 +41,8 @@ import { sessionCodec } from "./session-codec.js";
import { runChildProcess } from "../server-utils.js";
import { createPromptContextFixture } from "../test-fixtures/prompt-context.js";
import { setExpensiveWorkspaceGitExecutor } from "../git-workspace-sync.js";
import { createWorkspaceRestoreTeardown } from "../workspace-restore-teardown.js";
import { withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep } from "../workspace-restore-diagnostics.js";
import { resolveReferencedSourceIgnore } from "../sandbox-managed-runtime.js";
import {
getActiveStepContext,
@@ -3703,6 +3705,33 @@ describe("ACPX engine remote managed-home seam (PR 2: per-adapter home seed)", (
expect(path.isAbsolute(remoteAssetDir)).toBe(true);
});
it("retains bounded restore diagnostics through real settlement and result reproduction", async () => {
const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();
const failure = Object.assign(new Error("private-restore-path and command"), { code: 1, stderr: "private-restore-stderr" });
const { result } = await runExecutor(
{ agent: "custom", agentCommand: "node ./fake-acp.js", stateDir, cwd: localCwd },
{
authToken: "real-run-jwt", executionTarget,
prepareRemoteManagedHome: async (input) => {
const stagedRuntime = await input.stage([]);
return {
stagedRuntime,
teardown: createWorkspaceRestoreTeardown({
stagedRuntime: { restoreWorkspace: () => withWorkspaceRestoreDiagnostics("workspace", () =>
withWorkspaceRestoreStep("git_integration", async () => { throw failure; })) },
onLog: async () => {}, startMessage: "Restoring workspace", failurePrefix: "Restore failed",
}),
};
},
},
);
expect(result.resultJson).toMatchObject({
workspaceRestoreFailure: "restore_failed",
workspaceRestoreDiagnostic: { phase: "workspace", step: "git_integration", errorCode: "unknown", exitCode: 1 },
});
expect(JSON.stringify(result)).not.toContain("private-restore-");
});
it("test_remote_seam_teardown_fires_once_on_exit", async () => {
const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();
let teardownCalls = 0;
packages/adapter-utils/src/acpx-engine/execute.ts
+6 -2
View File
@@ -50,6 +50,7 @@ import {
} from "./terminal-session-failure.js";
export type { AcpxTerminalSessionFailure } from "./terminal-session-failure.js";
import type { WorkspaceRestoreFailureCode, WorkspaceRestoreOutcome } from "../workspace-restore-merge.js";
import type { WorkspaceRestoreDiagnostic } from "../workspace-restore-diagnostics.js";
import {
classifyWorkspaceRestoreFailure,
describeWorkspaceRestoreFailure,
@@ -4077,7 +4078,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
// status stay exactly what the turn produced — this is a signal, not an
// outcome change.
let workspaceRestoreFailureField:
| { workspaceRestoreFailure: WorkspaceRestoreFailureCode }
| { workspaceRestoreFailure: WorkspaceRestoreFailureCode; workspaceRestoreDiagnostic?: WorkspaceRestoreDiagnostic }
| Record<string, never> = {};
// The one settlement step name whose error can be the same workspace-
// restore failure the adapter teardown closure already classifies (a
@@ -5410,7 +5411,10 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
await withAdapterExecutionPhase(ctx, "workspace_restore", () => runRuntimeSpan("sandbox.syncBack", async () => {
const restoreOutcome = await syncBackManagedHome(prepared);
if (!restoreOutcome.ok) {
workspaceRestoreFailureField = { workspaceRestoreFailure: restoreOutcome.code };
workspaceRestoreFailureField = {
workspaceRestoreFailure: restoreOutcome.code,
...(restoreOutcome.diagnostic ? { workspaceRestoreDiagnostic: restoreOutcome.diagnostic } : {}),
};
}
}));
}
packages/adapter-utils/src/git-workspace-sync.test.ts
+275 -6
View File
@@ -6,6 +6,7 @@ import { promisify } from "node:util";
import { workspacePaths } from "./workspace-manifest.js";
import { runWorkspaceGitProcess } from "./workspace-git-stream.js";
import { afterEach, describe, expect, it } from "vitest";
import { getWorkspaceRestoreDiagnostic, withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep, withWorkspaceRestoreGitCommand } from "./workspace-restore-diagnostics.js";
import {
buildRemoteGitDeltaBundleScript,
@@ -24,6 +25,7 @@ import {
REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT,
REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES,
runLocalGit,
resetLocalGitIndexToHead,
sanitizeGitRemoteUrl,
setExpensiveWorkspaceGitExecutor,
withShallowGitWorkspaceClone,
@@ -651,7 +653,9 @@ describe("git workspace sync", () => {
const savedEnv = new Map(identityEnvKeys.map((key) => [key, process.env[key]]));
for (const key of identityEnvKeys) delete process.env[key];
try {
await integrateImportedGitHead({ localDir: repo, importedHead });
await integrateImportedGitHead({
localDir: repo, importedHead, baseline: { headCommit: baseHead, branchName: "main" },
});
} finally {
for (const [key, value] of savedEnv) {
if (value === undefined) delete process.env[key];
@@ -670,7 +674,161 @@ describe("git workspace sync", () => {
expect(mergedTree).toContain("imported.txt");
});
it("grafts an imported head onto the current head when histories share no ancestor", async () => {
describe("sandbox history rewrites", () => {
async function rewrittenHistory() {
const repo = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-rewrite-"));
cleanupDirs.push(repo);
await git(repo, ["init"]);
await git(repo, ["checkout", "-b", "host"]);
await git(repo, ["config", "user.name", "Paperclip Test"]);
await git(repo, ["config", "user.email", "test@paperclip.dev"]);
await writeFile(path.join(repo, "tracked.txt"), "base\n");
await git(repo, ["add", "."]);
await git(repo, ["commit", "-m", "base"]);
const ancestor = await git(repo, ["rev-parse", "HEAD"]);
await writeFile(path.join(repo, "tracked.txt"), "original change\n");
await git(repo, ["commit", "-am", "original change"]);
const baseline = { headCommit: await git(repo, ["rev-parse", "HEAD"]), branchName: "host" };
await git(repo, ["checkout", "-b", "sandbox"]);
await writeFile(path.join(repo, "tracked.txt"), "rewritten change\n");
await git(repo, ["commit", "-am", "rewritten change", "--amend"]);
const importedHead = await git(repo, ["rev-parse", "HEAD"]);
await git(repo, ["checkout", "host"]);
return { repo, ancestor, baseline, importedHead };
}
it("accepts rewritten history when the host still matches the starting snapshot", async () => {
const { repo, baseline, importedHead } = await rewrittenHistory();
// The old integration path attempts this conflicting merge even though
// the host has not changed since the run started.
await expect(git(repo, ["merge-tree", "--write-tree", baseline.headCommit, importedHead]))
.rejects.toMatchObject({ code: 1 });
await writeFile(path.join(repo, "local.txt"), "local work\n");
await git(repo, ["add", "local.txt"]);
const indexBefore = await git(repo, ["write-tree"]);
await integrateImportedGitHead({ localDir: repo, importedHead, baseline });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(importedHead);
expect(await git(repo, ["symbolic-ref", "--short", "HEAD"])).toBe("host");
expect(await git(repo, ["write-tree"])).toBe(indexBefore);
expect(await readFile(path.join(repo, "local.txt"), "utf8")).toBe("local work\n");
});
it("restores an intentional reset to an ancestor when the host has not changed", async () => {
const { repo, ancestor, baseline } = await rewrittenHistory();
await integrateImportedGitHead({ localDir: repo, importedHead: ancestor, baseline });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(ancestor);
});
it("does not replace host commits made after the starting snapshot", async () => {
const { repo, baseline, importedHead } = await rewrittenHistory();
await writeFile(path.join(repo, "local.txt"), "concurrent work\n");
await git(repo, ["add", "local.txt"]);
await git(repo, ["commit", "-m", "host advanced"]);
const hostHead = await git(repo, ["rev-parse", "HEAD"]);
await expect(integrateImportedGitHead({ localDir: repo, importedHead, baseline }))
.rejects.toThrow("Failed to merge concurrent remote git histories");
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(hostHead);
expect(await readFile(path.join(repo, "local.txt"), "utf8")).toBe("concurrent work\n");
});
it("does not replace a different host branch at the same starting commit", async () => {
const { repo, baseline, importedHead } = await rewrittenHistory();
const tree = await git(repo, ["rev-parse", `${importedHead}^{tree}`]);
const fastForwardHead = await git(repo, ["commit-tree", tree, "-p", baseline.headCommit, "-m", "sandbox advance"]);
await git(repo, ["checkout", "-b", "other"]);
await expect(integrateImportedGitHead({ localDir: repo, importedHead: fastForwardHead, baseline }))
.rejects.toThrow("branch changed");
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(baseline.headCommit);
expect(await git(repo, ["rev-parse", "host"])).toBe(baseline.headCommit);
});
it("keeps the conservative merge behavior without a starting snapshot", async () => {
const { repo, baseline, importedHead } = await rewrittenHistory();
await expect(integrateImportedGitHead({ localDir: repo, importedHead }))
.rejects.toThrow("Failed to merge concurrent remote git histories");
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(baseline.headCommit);
});
it("refuses unrelated rewritten history after a concurrent host commit", async () => {
const { repo, baseline, importedHead } = await rewrittenHistory();
const tree = await git(repo, ["rev-parse", `${importedHead}^{tree}`]);
const unrelated = await git(repo, ["commit-tree", tree, "-m", "shallow rewrite"]);
await writeFile(path.join(repo, "local.txt"), "concurrent work\n");
await git(repo, ["add", "local.txt"]);
await git(repo, ["commit", "-m", "host advanced"]);
const hostHead = await git(repo, ["rev-parse", "HEAD"]);
await expect(integrateImportedGitHead({ localDir: repo, importedHead: unrelated, baseline }))
.rejects.toThrow("Cannot restore unrelated remote history after the host advanced");
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(hostHead);
});
it("accepts a rewrite of an unchanged detached host without attaching a branch", async () => {
const { repo, baseline, importedHead } = await rewrittenHistory();
await git(repo, ["checkout", "--detach"]);
await integrateImportedGitHead({ localDir: repo, importedHead, baseline: { ...baseline, branchName: null } });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(importedHead);
await expect(git(repo, ["symbolic-ref", "--quiet", "HEAD"])).rejects.toMatchObject({ code: 1 });
});
it.each([false, true])("rejects a checkout during integration (initially detached: %s)", async (detached) => {
const { repo, baseline, importedHead } = await rewrittenHistory();
if (detached) await git(repo, ["checkout", "--detach"]);
const realGit = (await execFile("sh", ["-c", "command -v git"])).stdout.trim();
const bin = path.join(repo, "test-bin");
await mkdir(bin);
const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
// Switch branches after the initial identity read, at the merge-base
// subprocess boundary. Both refs still point to the expected old OID.
await writeFile(path.join(bin, "git"), `#!/bin/sh
if [ "$3" = merge-base ]; then
${quote(realGit)} -C "$2" checkout -B other ${baseline.headCommit} >/dev/null 2>&1 || exit 1
fi
exec ${quote(realGit)} "$@"
`, { mode: 0o755 });
const priorPath = process.env.PATH;
process.env.PATH = `${bin}${path.delimiter}${priorPath ?? ""}`;
try {
await expect(integrateImportedGitHead({
localDir: repo, importedHead, baseline: { ...baseline, branchName: detached ? null : "host" },
})).rejects.toThrow("branch changed");
} finally {
if (priorPath === undefined) delete process.env.PATH;
else process.env.PATH = priorPath;
}
expect(await git(repo, ["symbolic-ref", "--short", "HEAD"])).toBe("other");
expect(await git(repo, ["rev-parse", "host"])).toBe(baseline.headCommit);
expect(await git(repo, ["rev-parse", "other"])).toBe(baseline.headCommit);
expect(await stat(path.join(repo, ".git", "HEAD.lock")).catch(() => null)).toBeNull();
});
it.each([false, true])("holds the HEAD lock through commit (initially detached: %s)", async (detached) => {
const { repo, baseline, importedHead } = await rewrittenHistory();
await git(repo, ["branch", "other"]);
if (detached) await git(repo, ["checkout", "--detach"]);
await writeFile(path.join(repo, ".git", "hooks", "reference-transaction"), `#!/bin/sh
if [ "$1" = prepared ]; then
if git symbolic-ref HEAD refs/heads/other 2>/dev/null; then exit 1; fi
printf blocked > checkout-attempt.txt
fi
exit 0
`, { mode: 0o755 });
await integrateImportedGitHead({
localDir: repo, importedHead, baseline: { ...baseline, branchName: detached ? null : "host" },
});
expect(await readFile(path.join(repo, "checkout-attempt.txt"), "utf8")).toBe("blocked");
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(importedHead);
expect(await git(repo, ["rev-parse", "other"])).toBe(baseline.headCommit);
if (detached) await expect(git(repo, ["symbolic-ref", "--quiet", "HEAD"])).rejects.toMatchObject({ code: 1 });
else expect(await git(repo, ["symbolic-ref", "--short", "HEAD"])).toBe("host");
expect(await stat(path.join(repo, ".git", "HEAD.lock")).catch(() => null)).toBeNull();
});
});
it.each([false, true])("grafts an unrelated imported head with an unchanged host (baseline supplied: %s)", async (withBaseline) => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-graft-"));
cleanupDirs.push(rootDir);
const setupIdentity = ["-c", "user.name=Setup", "-c", "user.email=setup@paperclip.dev"];
@@ -693,7 +851,10 @@ describe("git workspace sync", () => {
const importedTree = await git(repo, ["rev-parse", `${baseHead}^{tree}`]);
const importedHead = await git(repo, [...setupIdentity, "commit-tree", importedTree, "-m", "sandbox rewrite"]);
await integrateImportedGitHead({ localDir: repo, importedHead });
await integrateImportedGitHead({
localDir: repo, importedHead,
baseline: withBaseline ? { headCommit: currentHead, branchName: "main" } : undefined,
});
const parents = (await git(repo, ["rev-list", "--parents", "-1", "HEAD"])).split(" ");
expect(parents.slice(1)).toEqual([currentHead]);
@@ -705,7 +866,7 @@ describe("git workspace sync", () => {
expect(body).toContain("shares no ancestor");
});
it("does not graft when merge-base fails for a reason other than missing ancestry", async () => {
it.each([false, true])("does not graft on a merge-base error other than missing ancestry (baseline supplied: %s)", async (withBaseline) => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-no-graft-"));
cleanupDirs.push(rootDir);
const setupIdentity = ["-c", "user.name=Setup", "-c", "user.email=setup@paperclip.dev"];
@@ -722,11 +883,119 @@ describe("git workspace sync", () => {
// object error (exit 128), not the no-ancestor signal (exit 1). The graft
// must not fire, and the integration keeps its loud failure.
const missingHead = "0123456789abcdef0123456789abcdef01234567";
await expect(integrateImportedGitHead({ localDir: repo, importedHead: missingHead }))
.rejects.toThrow(/Failed to merge concurrent remote git histories/);
const expectedExit = await runLocalGit(repo, ["merge-tree", "--write-tree", currentHead, missingHead])
.catch((error: { code: number }) => error.code);
const error = await withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", () =>
integrateImportedGitHead({
localDir: repo, importedHead: missingHead,
baseline: withBaseline ? { headCommit: currentHead, branchName: "main" } : undefined,
}))).catch((error: unknown) => error);
expect(error).toBeInstanceOf(Error);
expect((error as Error).message).toMatch(/Failed to merge concurrent remote git histories/);
expect(error).not.toHaveProperty("cause");
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "workspace", step: "git_integration", errorCode: "unknown", exitCode: expectedExit,
gitCommand: "merge_tree", gitFailureKind: "invalid_object" });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(currentHead);
});
it("identifies a real merge conflict without changing the host tip or copying Git output", async () => {
const repo = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-conflict-diagnostic-"));
cleanupDirs.push(repo);
await git(repo, ["init", "-b", "host"]);
await git(repo, ["config", "user.name", "Test"]);
await git(repo, ["config", "user.email", "test@paperclip.dev"]);
await writeFile(path.join(repo, "private-filename.txt"), "base\n");
await git(repo, ["add", "."]);
await git(repo, ["commit", "-m", "base"]);
const base = await git(repo, ["rev-parse", "HEAD"]);
await writeFile(path.join(repo, "private-filename.txt"), "host change\n");
await git(repo, ["commit", "-am", "host"]);
const currentHead = await git(repo, ["rev-parse", "HEAD"]);
await git(repo, ["checkout", "-b", "imported", base]);
await writeFile(path.join(repo, "private-filename.txt"), "remote change\n");
await git(repo, ["commit", "-am", "remote"]);
const importedHead = await git(repo, ["rev-parse", "HEAD"]);
await git(repo, ["checkout", "host"]);
const logs: string[] = [];
const error = await withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("directory_merge", () =>
withWorkspaceRestoreStep("git_integration", () => integrateImportedGitHead({ localDir: repo, importedHead }))),
async (line) => { logs.push(line); }).catch(error => error);
expect(error).toBeInstanceOf(Error);
expect(error.message).toContain("Failed to merge concurrent remote git histories");
expect(error).not.toHaveProperty("cause");
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "workspace", step: "git_integration", errorCode: "unknown",
exitCode: 1, gitCommand: "merge_tree", gitFailureKind: "merge_conflict" });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(currentHead);
expect(await readFile(path.join(repo, "private-filename.txt"), "utf8")).toBe("host change\n");
expect(logs).toHaveLength(1);
expect(logs[0]).not.toMatch(/private-filename|host change|remote change/);
for (const privateValue of [repo, currentHead, importedHead]) expect(logs[0]).not.toContain(privateValue);
});
it("labels a failed locked ref transaction without changing its branch or tip", async () => {
const repo = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-transaction-diagnostic-"));
cleanupDirs.push(repo);
await git(repo, ["init", "-b", "private-branch"]);
await git(repo, ["config", "user.name", "Test"]);
await git(repo, ["config", "user.email", "test@paperclip.dev"]);
await git(repo, ["commit", "--allow-empty", "-m", "base"]);
const base = await git(repo, ["rev-parse", "HEAD"]);
await git(repo, ["commit", "--allow-empty", "-m", "advance"]);
const importedHead = await git(repo, ["rev-parse", "HEAD"]);
await git(repo, ["reset", "--hard", base]);
// Git owns this lock. A failed restore must leave it alone and keep its
// existing failure behavior; diagnostic collection grants no cleanup rights.
await writeFile(path.join(repo, ".git", "HEAD.lock"), "private-lock");
const error = await withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", () =>
integrateImportedGitHead({ localDir: repo, importedHead, baseline: { headCommit: base, branchName: "private-branch" } })))
.catch(error => error);
expect(error).toMatchObject({ code: 128 });
const diagnostic = getWorkspaceRestoreDiagnostic(error);
expect(diagnostic).toEqual({ phase: "workspace", step: "git_integration", errorCode: "unknown", exitCode: 128,
gitCommand: "update_ref", gitFailureKind: "unknown" });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(base);
expect(await git(repo, ["symbolic-ref", "--short", "HEAD"])).toBe("private-branch");
expect(await readFile(path.join(repo, ".git", "HEAD.lock"), "utf8")).toBe("private-lock");
for (const privateValue of [repo, base, importedHead, "private-branch"]) expect(JSON.stringify(diagnostic)).not.toContain(privateValue);
});
it("recognizes a real expected-old ref mismatch without copying the ref or commit IDs", async () => {
const repo = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-ref-diagnostic-"));
cleanupDirs.push(repo);
await git(repo, ["init", "-b", "private-branch"]);
await git(repo, ["config", "user.name", "Test"]);
await git(repo, ["config", "user.email", "test@paperclip.dev"]);
await git(repo, ["commit", "--allow-empty", "-m", "base"]);
const base = await git(repo, ["rev-parse", "HEAD"]);
await git(repo, ["commit", "--allow-empty", "-m", "advance"]);
const current = await git(repo, ["rev-parse", "HEAD"]);
const error = await withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", () =>
withWorkspaceRestoreGitCommand("update_ref", () => runLocalGit(repo, ["update-ref", "refs/heads/private-branch", base, base]))))
.catch(error => error);
expect(error).toMatchObject({ code: 128 });
const diagnostic = getWorkspaceRestoreDiagnostic(error);
expect(diagnostic).toEqual({ phase: "workspace", step: "git_integration", errorCode: "unknown", exitCode: 128,
gitCommand: "update_ref", gitFailureKind: "ref_conflict" });
expect(await git(repo, ["rev-parse", "HEAD"])).toBe(current);
for (const privateValue of [repo, base, current, "private-branch"]) expect(JSON.stringify(diagnostic)).not.toContain(privateValue);
});
it("preserves the real Git index reset exit code without attaching its raw error", async () => {
const repo = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-reset-diagnostic-"));
cleanupDirs.push(repo);
await git(repo, ["init"]);
await writeFile(path.join(repo, "tracked.txt"), "base\n", "utf8");
await git(repo, ["add", "tracked.txt"]);
await git(repo, ["-c", "user.name=Setup", "-c", "user.email=setup@paperclip.dev", "commit", "-m", "base"]);
await writeFile(path.join(repo, ".git", "index.lock"), "fixture lock\n", "utf8");
const error = await withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("index_reset", () =>
resetLocalGitIndexToHead({ localDir: repo }))).catch((error: unknown) => error);
expect(error).toBeInstanceOf(Error);
expect((error as Error).message).toContain("Failed to reset local git index");
expect(error).not.toHaveProperty("cause");
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "workspace", step: "index_reset", errorCode: "unknown", exitCode: 128 });
});
describe("readReferencedSourceGitIgnoredPaths", () => {
it("returns null for a directory that is not a Git work tree", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-nogit-"));
packages/adapter-utils/src/git-workspace-sync.ts
+111 -28
View File
@@ -5,6 +5,7 @@ import os from "node:os";
import path from "node:path";
import { createWorkspaceManifest, workspacePaths, WorkspaceNulParser, type WorkspacePaths } from "./workspace-manifest.js";
import { runWorkspaceGitProcess } from "./workspace-git-stream.js";
import { preserveWorkspaceRestoreErrorDiagnostic, withWorkspaceRestoreGitCommand, type WorkspaceRestoreGitCommand } from "./workspace-restore-diagnostics.js";
export interface GitCommandResult {
stdout: string;
@@ -773,6 +774,12 @@ export function buildRemoteGitDeltaBundleScript(input: {
` bundle_base=""`,
"fi",
]),
// An empty bundle means "still at baseSha" to the importer. A reset to an
// older ancestor has no delta commits either, but must carry its new tip.
// Use the full-bundle path so Git advertises that tip instead of losing it.
`if [ -n "$bundle_base" ] && [ "$bundle_base" != ${baseSha} ] && [ "$bundle_base" = "$(git -C ${remoteDir} rev-parse HEAD)" ]; then`,
` bundle_base=""`,
"fi",
`if [ -n "$bundle_base" ]; then`,
` commit_count=$(git -C ${remoteDir} rev-list --count HEAD --not "$bundle_base")`,
"else",
@@ -803,6 +810,14 @@ export function buildRemoteGitDeltaBundleScript(input: {
].filter(Boolean).join("\n");
}
// Labels are fixed at the integration call sites, never derived from Git arguments.
function runIntegrationGit(
command: WorkspaceRestoreGitCommand,
...args: Parameters<typeof runLocalGit>
): Promise<GitCommandResult> {
return withWorkspaceRestoreGitCommand(command, () => runLocalGit(...args));
}
/**
* Preserve imported work whose history does not connect to the local one.
*
@@ -824,11 +839,11 @@ export async function createUnrelatedHistoryGraftCommit(input: {
importedHead: string;
syncLabel: string;
}): Promise<string> {
const importedTree = (await runLocalGit(input.localDir, ["rev-parse", `${input.importedHead}^{tree}`], {
const importedTree = (await runIntegrationGit("rev_parse", input.localDir, ["rev-parse", `${input.importedHead}^{tree}`], {
timeout: 10_000,
maxBuffer: 16 * 1024,
})).stdout.trim();
const importedMessage = (await runLocalGit(input.localDir, ["log", "-1", "--format=%B", input.importedHead], {
const importedMessage = (await runIntegrationGit("log", input.localDir, ["log", "-1", "--format=%B", input.importedHead], {
timeout: 10_000,
maxBuffer: 256 * 1024,
})).stdout;
@@ -837,8 +852,8 @@ export async function createUnrelatedHistoryGraftCommit(input: {
"",
`(${input.syncLabel} graft ${input.importedHead.slice(0, 12)}: imported history shares no ancestor with ${input.currentHead.slice(0, 12)})`,
].join("\n");
const graftCommit = await runLocalGit(
input.localDir,
const graftCommit = await runIntegrationGit(
"commit_tree", input.localDir,
[...GIT_SYNC_COMMIT_IDENTITY_ARGS, "commit-tree", importedTree, "-p", input.currentHead, "-m", message],
{
timeout: 60_000,
@@ -848,9 +863,68 @@ export async function createUnrelatedHistoryGraftCommit(input: {
return graftCommit.stdout.trim();
}
async function updateLocalGitHead(input: {
localDir: string;
newHead: string;
oldHead: string;
branchName: string | null;
}): Promise<void> {
// Prepare the ref transaction before checking the symbolic HEAD identity.
// Git holds HEAD.lock (and the branch lock when attached) until commit/abort,
// so a checkout cannot redirect the write after this check. --no-deref also
// prevents a detached write from following a newly attached branch.
await withWorkspaceRestoreGitCommand("update_ref", () => new Promise<void>((resolve, reject) => {
let identityError: unknown;
let prepared = false;
let output = "";
const child = execFile("git", ["-C", input.localDir, "update-ref", "--stdin"], {
timeout: 15_000,
maxBuffer: 64 * 1024,
}, (error, stdout, stderr) => {
if (identityError) reject(identityError);
else if (error) reject(Object.assign(error, { stdout, stderr }));
else if (!stdout.includes("commit: ok\n")) reject(new Error("Git HEAD transaction did not commit."));
else resolve();
});
// Early Git errors close stdin; the process callback reports the error.
child.stdin!.on("error", () => {});
child.stdout!.on("data", (chunk: string | Buffer) => {
output += chunk.toString();
if (prepared || !output.includes("prepare: ok\n")) return;
prepared = true;
void (async () => {
try {
const branchName = (await runIntegrationGit("symbolic_ref", input.localDir, ["symbolic-ref", "--quiet", "--short", "HEAD"], {
timeout: 10_000,
}).catch((error) => {
if (error.code === 1) return { stdout: "" };
throw error;
})).stdout.trim() || null;
if (branchName !== input.branchName) {
throw new Error("Workspace branch changed while remote work was running.");
}
child.stdin!.end("commit\n");
} catch (error) {
identityError = error;
child.stdin!.end("abort\n");
}
})();
});
child.stdin!.write([
"start",
...(input.branchName === null ? ["option no-deref"] : []),
`update HEAD ${input.newHead} ${input.oldHead}`,
"prepare",
"",
].join("\n"));
}));
}
export async function integrateImportedGitHead(input: {
localDir: string;
importedHead: string;
/** The host Git identity captured before staging this run. */
baseline?: Pick<GitWorkspaceSnapshot, "headCommit" | "branchName">;
}): Promise<void> {
const isConcurrentRefUpdateError = (error: unknown) => {
const message = error instanceof Error ? error.message : String(error);
@@ -859,23 +933,25 @@ export async function integrateImportedGitHead(input: {
for (let attempt = 0; attempt < 5; attempt += 1) {
const snapshot = {
headCommit: (await runLocalGit(input.localDir, ["rev-parse", "HEAD"])).stdout.trim(),
branchName: (await runLocalGit(input.localDir, ["symbolic-ref", "--quiet", "--short", "HEAD"]).catch((error) => {
headCommit: (await runIntegrationGit("rev_parse", input.localDir, ["rev-parse", "HEAD"])).stdout.trim(),
branchName: (await runIntegrationGit("symbolic_ref", input.localDir, ["symbolic-ref", "--quiet", "--short", "HEAD"]).catch((error) => {
if (error.code === 1) return { stdout: "" };
throw error;
})).stdout.trim() || null,
};
if (input.baseline && snapshot.branchName !== input.baseline.branchName) {
throw new Error("Workspace branch changed while remote work was running.");
}
const currentHead = snapshot.headCommit;
if (!currentHead || currentHead === input.importedHead) return;
const headRef = snapshot.branchName ? `refs/heads/${snapshot.branchName}` : "HEAD";
// `git merge-base` exits 1 when the commits share no ancestor — the only
// outcome that authorizes the graft fallback below. Every other failure
// (timeout, missing object, repository error) must keep failing the
// integration instead of silently rewriting the tip.
let noCommonAncestor = false;
const mergeBase = await runLocalGit(input.localDir, ["merge-base", currentHead, input.importedHead], {
const mergeBase = await runIntegrationGit("merge_base", input.localDir, ["merge-base", currentHead, input.importedHead], {
timeout: 10_000,
maxBuffer: 16 * 1024,
}).catch((error: unknown) => {
@@ -884,15 +960,15 @@ export async function integrateImportedGitHead(input: {
});
const mergeBaseHead = mergeBase?.stdout.trim() ?? "";
if (mergeBaseHead === input.importedHead) {
return;
}
if (mergeBaseHead === currentHead) {
// A rebase/amend rewrites the sandbox tip without a concurrent host edit.
// Adopt that history when the host still matches the run's starting tip;
// merging the old and rewritten commits can reintroduce resolved conflicts.
// Keep the expected-old-value check: if the host advances during this write,
// retry against its new tip and use the normal concurrent-history path.
if (mergeBaseHead === currentHead || (mergeBaseHead && currentHead === input.baseline?.headCommit)) {
try {
await runLocalGit(input.localDir, ["update-ref", headRef, input.importedHead, currentHead], {
timeout: 10_000,
maxBuffer: 16 * 1024,
await updateLocalGitHead({
localDir: input.localDir, newHead: input.importedHead, oldHead: currentHead, branchName: snapshot.branchName,
});
return;
} catch (error) {
@@ -901,7 +977,14 @@ export async function integrateImportedGitHead(input: {
}
}
if (mergeBaseHead === input.importedHead) {
return;
}
if (noCommonAncestor) {
if (input.baseline && currentHead !== input.baseline.headCommit) {
throw new Error("Cannot restore unrelated remote history after the host advanced.");
}
// No common ancestor — merging is impossible and failing here would
// discard the imported work. Graft it onto the current head instead;
// see createUnrelatedHistoryGraftCommit.
@@ -912,9 +995,8 @@ export async function integrateImportedGitHead(input: {
syncLabel: "Paperclip remote git sync",
});
try {
await runLocalGit(input.localDir, ["update-ref", headRef, graftCommit, currentHead], {
timeout: 10_000,
maxBuffer: 16 * 1024,
await updateLocalGitHead({
localDir: input.localDir, newHead: graftCommit, oldHead: currentHead, branchName: snapshot.branchName,
});
return;
} catch (error) {
@@ -925,23 +1007,23 @@ export async function integrateImportedGitHead(input: {
let mergedTree;
try {
mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
mergedTree = await runIntegrationGit("merge_tree", input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
timeout: 60_000,
maxBuffer: 256 * 1024,
});
} catch (error) {
const reason = error instanceof Error ? error.message : String(error);
throw new Error(
throw preserveWorkspaceRestoreErrorDiagnostic(new Error(
`Failed to merge concurrent remote git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`,
);
), error);
}
const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
if (!mergedTreeId) {
throw new Error("Failed to compute a merged git tree for workspace restore.");
}
const mergeCommit = await runLocalGit(
input.localDir,
const mergeCommit = await runIntegrationGit(
"commit_tree", input.localDir,
[
...GIT_SYNC_COMMIT_IDENTITY_ARGS,
"commit-tree",
@@ -959,9 +1041,8 @@ export async function integrateImportedGitHead(input: {
},
);
try {
await runLocalGit(input.localDir, ["update-ref", headRef, mergeCommit.stdout.trim(), currentHead], {
timeout: 10_000,
maxBuffer: 16 * 1024,
await updateLocalGitHead({
localDir: input.localDir, newHead: mergeCommit.stdout.trim(), oldHead: currentHead, branchName: snapshot.branchName,
});
return;
} catch (error) {
@@ -990,7 +1071,9 @@ export async function resetLocalGitIndexToHead(input: {
(error as { stdout?: unknown }).stdout,
].filter((value): value is string => typeof value === "string" && value.trim().length > 0).join("\n")
: String(error);
throw new Error(`Failed to reset local git index to HEAD after workspace restore: ${detail}`);
throw preserveWorkspaceRestoreErrorDiagnostic(
new Error(`Failed to reset local git index to HEAD after workspace restore: ${detail}`), error,
);
}
const hasDiff = async (args: string[]) => {
packages/adapter-utils/src/sandbox-managed-runtime.test.ts
+141 -6
View File
@@ -6,6 +6,9 @@ import path from "node:path";
import { execFile as execFileCallback, spawn } from "node:child_process";
import { promisify } from "node:util";
import { afterEach, describe, expect, it, vi } from "vitest";
import * as gitSync from "./git-workspace-sync.js";
import * as restoreMerge from "./workspace-restore-merge.js";
import { getWorkspaceRestoreDiagnostic } from "./workspace-restore-diagnostics.js";
import {
resetLocalGitIndexToHead,
runLocalGit,
@@ -835,6 +838,93 @@ describe("sandbox managed runtime", () => {
},
);
it("restores a sandbox rebase without merging it with unchanged host history", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-rebase-"));
cleanupDirs.push(rootDir);
const host = path.join(rootDir, "host");
const remote = path.join(rootDir, "remote");
await mkdir(host);
await git(host, ["init"]);
await git(host, ["checkout", "-b", "work"]);
await git(host, ["config", "user.name", "Paperclip Test"]);
await git(host, ["config", "user.email", "test@paperclip.dev"]);
await writeFile(path.join(host, "pins.txt"), "base\n");
await writeFile(path.join(host, "notes.txt"), "original notes\n");
await git(host, ["add", "."]);
await git(host, ["commit", "-m", "base"]);
const base = await git(host, ["rev-parse", "HEAD"]);
await writeFile(path.join(host, "pins.txt"), "feature\n");
await git(host, ["commit", "-am", "feature"]);
const startingHead = await git(host, ["rev-parse", "HEAD"]);
await git(host, ["checkout", "-b", "upstream", base]);
await writeFile(path.join(host, "pins.txt"), "upstream\n");
await git(host, ["commit", "-am", "upstream"]);
await git(host, ["checkout", "work"]);
const prepared = await prepareSandboxManagedRuntime({
spec: { transport: "sandbox", provider: "test", sandboxId: "rebase", remoteCwd: remote, timeoutMs: 30_000, apiKey: null },
adapterKey: "test-adapter",
client: makeFilesystemClient(),
workspaceLocalDir: host,
});
await git(remote, ["config", "user.name", "Paperclip Test"]);
await git(remote, ["config", "user.email", "test@paperclip.dev"]);
await git(remote, ["fetch", "--unshallow", host, "+refs/heads/*:refs/remotes/source/*"]);
await expect(git(remote, ["rebase", "refs/remotes/source/upstream"])).rejects.toMatchObject({ code: 1 });
await writeFile(path.join(remote, "pins.txt"), "resolved pins\n");
await git(remote, ["add", "pins.txt"]);
await git(remote, ["-c", "core.editor=true", "rebase", "--continue"]);
const rebasedHead = await git(remote, ["rev-parse", "HEAD"]);
expect(rebasedHead).not.toBe(startingHead);
await writeFile(path.join(host, "notes.txt"), "host edits during the run\n");
await writeFile(path.join(host, "local-only.txt"), "local file\n");
await writeFile(path.join(remote, "output.txt"), "sandbox output\n");
await prepared.restoreWorkspace();
expect(await git(host, ["rev-parse", "HEAD"])).toBe(rebasedHead);
expect(await git(host, ["symbolic-ref", "--short", "HEAD"])).toBe("work");
expect(await readFile(path.join(host, "pins.txt"), "utf8")).toBe("resolved pins\n");
expect(await readFile(path.join(host, "notes.txt"), "utf8")).toBe("host edits during the run\n");
expect(await readFile(path.join(host, "local-only.txt"), "utf8")).toBe("local file\n");
expect(await readFile(path.join(host, "output.txt"), "utf8")).toBe("sandbox output\n");
expect(await git(host, ["diff", "--cached", "--name-only"])).toBe("");
});
it("restores a sandbox reset to an ancestor with the matching clean working tree", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-reset-"));
cleanupDirs.push(rootDir);
const host = path.join(rootDir, "host");
const remote = path.join(rootDir, "remote");
await mkdir(host);
await git(host, ["init"]);
await git(host, ["checkout", "-b", "work"]);
await git(host, ["config", "user.name", "Paperclip Test"]);
await git(host, ["config", "user.email", "test@paperclip.dev"]);
await writeFile(path.join(host, "tracked.txt"), "original\n");
await git(host, ["add", "."]);
await git(host, ["commit", "-m", "original"]);
const ancestor = await git(host, ["rev-parse", "HEAD"]);
await writeFile(path.join(host, "tracked.txt"), "change to discard\n");
await git(host, ["commit", "-am", "later change"]);
const prepared = await prepareSandboxManagedRuntime({
spec: { transport: "sandbox", provider: "test", sandboxId: "reset", remoteCwd: remote, timeoutMs: 30_000, apiKey: null },
adapterKey: "test-adapter",
client: makeFilesystemClient(),
workspaceLocalDir: host,
});
await git(remote, ["fetch", "--unshallow", host, "work"]);
await git(remote, ["reset", "--hard", ancestor]);
await prepared.restoreWorkspace();
expect(await git(host, ["rev-parse", "HEAD"])).toBe(ancestor);
expect(await git(host, ["symbolic-ref", "--short", "HEAD"])).toBe("work");
expect(await readFile(path.join(host, "tracked.txt"), "utf8")).toBe("original\n");
expect(await git(host, ["status", "--porcelain"])).toBe("");
});
it("syncs git-backed workspaces through a shallow standalone clone and keeps .git out of archives", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-git-"));
cleanupDirs.push(rootDir);
@@ -3975,14 +4065,14 @@ describe("sandbox managed runtime outbound coordinator", () => {
]);
}
it("records each failed restore phase without changing stable failure ordering", async () => {
it.each([false, true])("records each failed restore phase in stable order (shared error: %s)", async (sharedError) => {
const { workspaceDir, remoteWorkspaceDir, dirOf } = await makeOutboundDirs(["home", "private-asset"]);
const { control, gate } = makeOutboundControl();
const client = makeGatedOutboundClient(true, gate);
const workspaceError = Object.assign(new Error("private workspace path"), { code: "EACCES" });
control.failWith("workspace", workspaceError);
control.failWith("home", Object.assign(new Error("private credential"), { status: 404 }));
control.failWith("private-asset", new Error("private asset error"));
control.failWith("home", sharedError ? workspaceError : Object.assign(new Error("private credential"), { status: 404 }));
control.failWith("private-asset", sharedError ? workspaceError : new Error("private asset error"));
const prepared = await prepareSandboxManagedRuntime({
spec: makeSpec(remoteWorkspaceDir), adapterKey: "codex", client, workspaceLocalDir: workspaceDir,
assets: [
@@ -3995,11 +4085,14 @@ describe("sandbox managed runtime outbound coordinator", () => {
const diagnostics = lines.filter((line) => line.includes("Workspace restore diagnostic:"));
expect(diagnostics).toHaveLength(3);
expect(diagnostics).toEqual(expect.arrayContaining([
'[paperclip] Workspace restore diagnostic: {"phase":"workspace","errorCode":"EACCES"}\n',
'[paperclip] Workspace restore diagnostic: {"phase":"asset","errorCode":"unknown","httpStatus":404}\n',
'[paperclip] Workspace restore diagnostic: {"phase":"asset","errorCode":"unknown"}\n',
'[paperclip] Workspace restore diagnostic: {"phase":"workspace","step":"workspace_transfer","errorCode":"EACCES"}\n',
sharedError ? '[paperclip] Workspace restore diagnostic: {"phase":"asset","step":"asset_restore","errorCode":"EACCES"}\n'
: '[paperclip] Workspace restore diagnostic: {"phase":"asset","step":"asset_restore","errorCode":"unknown","httpStatus":404}\n',
sharedError ? '[paperclip] Workspace restore diagnostic: {"phase":"asset","step":"asset_restore","errorCode":"EACCES"}\n'
: '[paperclip] Workspace restore diagnostic: {"phase":"asset","step":"asset_restore","errorCode":"unknown"}\n',
]));
expect(diagnostics.join("")).not.toContain("private");
expect(getWorkspaceRestoreDiagnostic(workspaceError)).toEqual({ phase: "workspace", step: "workspace_transfer", errorCode: "EACCES" });
expect(control.settled).toEqual(expect.arrayContaining(["workspace", "home", "private-asset"]));
});
@@ -4355,6 +4448,48 @@ describe("sandbox git-bundle export transport", () => {
.filter((mapping) => path.posix.basename(mapping.sourcePath) === "git-delta.bundle");
}
it.each([
"git_export", "git_import", "workspace_transfer", "workspace_extract",
"directory_merge", "git_integration", "index_reset", "git_ref_cleanup",
] as const)("identifies the actual %s failure during workspace restore", async (step) => {
const { localWorkspaceDir, remoteWorkspaceDir } = await setupGitBackedWorkspace("paperclip-restore-diagnostic-");
const client = makeTransportClient(step !== "workspace_extract", { syncOutOperations: [], readFilePaths: [] });
const prepared = await prepareSandboxManagedRuntime({
spec: gitSpec(remoteWorkspaceDir), adapterKey: "test-adapter", client, workspaceLocalDir: localWorkspaceDir,
});
await commitInSandbox(remoteWorkspaceDir);
const failure = Object.assign(new Error("private-restore-command /private-restore-path"), { code: 7, stderr: "private-restore-stderr" });
if (step === "git_export") client.run = async () => { throw failure; };
if (step === "git_import") vi.spyOn(gitSync, "fetchGitBundleIntoLocalRef").mockRejectedValueOnce(failure);
if (step === "directory_merge") vi.spyOn(restoreMerge, "mergeDirectoryWithBaseline").mockRejectedValueOnce(failure);
if (step === "git_integration") vi.spyOn(gitSync, "integrateImportedGitHead").mockRejectedValueOnce(failure);
if (step === "index_reset") vi.spyOn(gitSync, "resetLocalGitIndexToHead").mockRejectedValueOnce(failure);
if (step === "git_ref_cleanup") vi.spyOn(gitSync, "deleteLocalGitRef").mockRejectedValueOnce(failure);
if (step === "workspace_transfer") {
const syncOut = client.syncOut!;
client.syncOut = async (operations) => {
if (operations.some((operation) => operation.files.some((file) => file.kind === "directory"))) throw failure;
return syncOut(operations);
};
}
if (step === "workspace_extract") {
const readRemote = client.readFile;
client.readFile = async (remotePath, options) => remotePath.endsWith("workspace-download.tar")
? Buffer.from("invalid archive") : readRemote(remotePath, options);
}
const lines: string[] = [];
try {
const thrown = await prepared.restoreWorkspace((line) => { lines.push(line); }).then(() => undefined, (error: unknown) => error);
expect(thrown).toBeInstanceOf(Error);
if (step !== "workspace_extract") expect(thrown).toBe(failure);
expect(getWorkspaceRestoreDiagnostic(thrown)).toMatchObject({ phase: "workspace", step, errorCode: "unknown" });
if (step !== "workspace_extract") expect(getWorkspaceRestoreDiagnostic(thrown)?.exitCode).toBe(7);
const diagnostics = lines.filter((line) => line.includes("Workspace restore diagnostic:"));
expect(diagnostics).toHaveLength(1);
expect(diagnostics[0]).not.toContain("private-restore-");
} finally { vi.restoreAllMocks(); }
});
it("moves the bundle through one native syncOut file mapping, never through readFile", async () => {
const capture: TransportCapture = { syncOutOperations: [], readFilePaths: [] };
const { localWorkspaceDir, remoteWorkspaceDir } = await setupGitBackedWorkspace("paperclip-bundle-native-");
packages/adapter-utils/src/sandbox-managed-runtime.ts
+55 -44
View File
@@ -49,7 +49,10 @@ import {
type SyncOperationTask,
} from "./sync-operation-schedule.js";
import type { RuntimeSpanRunner } from "./acpx-engine/startup-timing.js";
import { withWorkspaceRestoreDiagnostics } from "./workspace-restore-diagnostics.js";
import {
recordWorkspaceRestoreDiagnostic, withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep,
type WorkspaceRestoreDiagnostic,
} from "./workspace-restore-diagnostics.js";
const execFile = promisify(execFileCallback);
const SANDBOX_WORKSPACE_HEAVY_DIR_NAMES = [
@@ -1717,6 +1720,7 @@ export async function prepareSandboxManagedRuntime(input: {
// started task before it returns, so lease teardown never starts while an
// outbound restore task still writes host data.
const outboundTasks: Array<SyncOperationTask<void>> = [];
const outboundDiagnostics: Array<WorkspaceRestoreDiagnostic | undefined> = [];
// The workspace restore task runs only when the run syncs the workspace.
// The task exports the sandbox git history (git-backed workspace), reads
@@ -1780,7 +1784,7 @@ export async function prepareSandboxManagedRuntime(input: {
// the import fails on a missing prerequisite. In that case re-export
// a full, self-contained bundle from the still-live sandbox rather
// than discard the completed run.
const exportAndImport = async (forceFullBundle: boolean): Promise<string> => {
const exportAndImport = async (forceFullBundle: boolean): Promise<string> => withWorkspaceRestoreStep("git_export", async () => {
await input.client.run(
`sh -c ${shellQuote(buildRemoteGitDeltaBundleScript({
remoteDir: workspaceRemoteDir,
@@ -1838,14 +1842,14 @@ export async function prepareSandboxManagedRuntime(input: {
remoteWorkspaceStatus = remoteWorkspaceStatus === "clean" ? "clean" : "dirty";
await input.client.remove(remoteWorkspaceStatusPath).catch(() => undefined);
}
return fetchGitBundleIntoLocalRef({
return withWorkspaceRestoreStep("git_import", () => fetchGitBundleIntoLocalRef({
localDir: input.workspaceLocalDir,
bundlePath: localBundlePath,
exportRef,
importedRef: importedRef!,
baseSha: gitSnapshot.headCommit,
});
};
}));
});
try {
importedHead = await exportAndImport(false);
@@ -1885,19 +1889,19 @@ export async function prepareSandboxManagedRuntime(input: {
"workspace",
{ sink: input.onRuntimeProgress, phase: "restore" },
);
const syncResult = await input.client.syncOut!(operations);
const syncResult = await withWorkspaceRestoreStep("workspace_transfer", () => input.client.syncOut!(operations));
const transferredBytes = sumSyncResultBytes(syncResult);
await workspaceRestore.finish(transferredBytes, transferredBytes);
} else {
const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-download.tar");
await input.client.run(
await withWorkspaceRestoreStep("workspace_transfer", () => input.client.run(
`sh -c ${shellQuote(createRemoteTarballFromDirectoryCommand({
remoteDir: workspaceRemoteDir,
archivePath: remoteWorkspaceTar,
exclude: workspaceRestoreExclude,
}))}`,
{ timeoutMs: input.spec.timeoutMs },
);
));
const workspaceRestore = makeTransferProgress(
restoreSink,
"Restoring",
@@ -1905,52 +1909,57 @@ export async function prepareSandboxManagedRuntime(input: {
"workspace",
{ sink: input.onRuntimeProgress, phase: "restore" },
);
const archiveBytes = await input.client.readFile(remoteWorkspaceTar, workspaceRestore.options);
const archiveBytes = await withWorkspaceRestoreStep("workspace_transfer", () => input.client.readFile(remoteWorkspaceTar, workspaceRestore.options));
const archiveBuffer = toBuffer(archiveBytes);
await workspaceRestore.finish(archiveBuffer.byteLength, archiveBuffer.byteLength);
await input.client.remove(remoteWorkspaceTar).catch(() => undefined);
const localArchivePath = path.join(tempDir, "workspace.tar");
await fs.writeFile(localArchivePath, archiveBuffer);
await extractTarballToDirectory({
archivePath: localArchivePath,
localDir: extractedDir,
await withWorkspaceRestoreStep("workspace_extract", async () => {
await fs.writeFile(localArchivePath, archiveBuffer);
await extractTarballToDirectory({
archivePath: localArchivePath,
localDir: extractedDir,
});
});
}
const gitHeadToIntegrate = importedHead;
const mergeBaseline = repositories.length === 0 ? baselineSnapshot! : await selectDirectorySnapshot(baselineSnapshot!, {
omit: repositories.map((repo) => repo.path), exclude: workspaceRestoreExclude, ignoredPaths: gitSnapshot?.ignoredPaths,
await withWorkspaceRestoreStep("directory_merge", async () => {
const mergeBaseline = repositories.length === 0 ? baselineSnapshot! : await selectDirectorySnapshot(baselineSnapshot!, {
omit: repositories.map((repo) => repo.path), exclude: workspaceRestoreExclude, ignoredPaths: gitSnapshot?.ignoredPaths,
});
try {
await mergeDirectoryWithBaseline({
baseline: mergeBaseline,
sourceDir: extractedDir,
targetDir: input.workspaceLocalDir,
beforeApply: gitHeadToIntegrate
? async () => {
await withWorkspaceRestoreStep("git_integration", () => integrateImportedGitHead({
localDir: input.workspaceLocalDir,
importedHead: gitHeadToIntegrate,
baseline: gitSnapshot ?? undefined,
}));
}
: undefined,
afterApply: gitSnapshot
? async () => {
await withWorkspaceRestoreStep("index_reset", () => resetLocalGitIndexToHead({
localDir: input.workspaceLocalDir,
checkWorkingTreeClean: remoteWorkspaceStatus === "clean",
}));
}
: undefined,
});
} finally { if (mergeBaseline !== baselineSnapshot) await disposeDirectorySnapshot(mergeBaseline); }
});
try {
await mergeDirectoryWithBaseline({
baseline: mergeBaseline,
sourceDir: extractedDir,
targetDir: input.workspaceLocalDir,
beforeApply: gitHeadToIntegrate
? async () => {
await integrateImportedGitHead({
localDir: input.workspaceLocalDir,
importedHead: gitHeadToIntegrate,
});
}
: undefined,
afterApply: gitSnapshot
? async () => {
await resetLocalGitIndexToHead({
localDir: input.workspaceLocalDir,
checkWorkingTreeClean: remoteWorkspaceStatus === "clean",
});
}
: undefined,
});
} finally { if (mergeBaseline !== baselineSnapshot) await disposeDirectorySnapshot(mergeBaseline); }
} finally {
await emitRuntimeStatus(input.onRuntimeProgress, "finalize", "Finalizing workspace");
if (importedRef) {
await deleteLocalGitRef({ localDir: input.workspaceLocalDir, ref: importedRef });
await withWorkspaceRestoreStep("git_ref_cleanup", () => deleteLocalGitRef({ localDir: input.workspaceLocalDir, ref: importedRef! }));
}
}
});
}), restoreSink),
}), restoreSink, (diagnostic) => { outboundDiagnostics[0] = diagnostic; }),
);
}
@@ -1961,18 +1970,19 @@ export async function prepareSandboxManagedRuntime(input: {
if (!asset.restore) continue;
const assetRestore = asset.restore;
const assetKey = asset.key;
const taskIndex = outboundTasks.length;
outboundTasks.push(() =>
withWorkspaceRestoreDiagnostics(
"asset",
() => runStepSpan(`restore.asset.${assetKey}`, async () => {
await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
await assetRestore({
await withWorkspaceRestoreStep("asset_restore", () => assetRestore({
assetDir: path.posix.join(runtimeRootDir, assetKey),
readFile: async (remotePath) => toBuffer(await input.client.readFile(remotePath)),
tempDir,
});
}));
});
}), restoreSink),
}), restoreSink, (diagnostic) => { outboundDiagnostics[taskIndex] = diagnostic; }),
);
}
@@ -1989,8 +1999,9 @@ export async function prepareSandboxManagedRuntime(input: {
// Every outbound restore is a required operation: a rejection is fatal.
// The workspace comes first, then each asset in order. Raise the first
// rejection in stable task order, so two failures raise the earlier one.
for (const result of outboundResults) {
for (const [index, result] of outboundResults.entries()) {
if (result.status === "rejected") {
recordWorkspaceRestoreDiagnostic(result.reason, outboundDiagnostics[index]);
throw result.reason;
}
}
packages/adapter-utils/src/server-utils.ts
+1
View File
@@ -2245,6 +2245,7 @@ export function renderPaperclipWakePrompt(
return joinPromptSections([
renderPaperclipWakePromptBody(value, options),
instructions ? `## Assigned connector skills\n\n${instructions}` : "",
asString(parseObject(parseObject(value).connectionInstructions).text, "").trim(),
]);
}
packages/adapter-utils/src/workspace-restore-diagnostics.test.ts
+216 -1
View File
@@ -1,8 +1,90 @@
import { describe, expect, it, vi } from "vitest";
import { classifyWorkspaceRestoreFailure } from "./workspace-restore-merge.js";
import { withWorkspaceRestoreDiagnostics } from "./workspace-restore-diagnostics.js";
import {
getWorkspaceRestoreDiagnostic, preserveWorkspaceRestoreErrorDiagnostic, recordWorkspaceRestoreDiagnostic,
sanitizeWorkspaceRestoreDiagnostic, withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep, withWorkspaceRestoreGitCommand,
type WorkspaceRestoreDiagnostic,
} from "./workspace-restore-diagnostics.js";
describe("workspace restore diagnostics", () => {
it.each([new Error("shared nested failure"), "shared primitive failure"])("selects an unlabelled nested failure without retaining a later task's step (%s)", async (error) => {
const sink = vi.fn();
const snapshots: Array<WorkspaceRestoreDiagnostic | undefined> = [];
await expect(withWorkspaceRestoreDiagnostics("workspace", async () => {
await Promise.allSettled([
withWorkspaceRestoreDiagnostics("workspace", async () => { throw error; }, sink, (value) => { snapshots[0] = value; }),
withWorkspaceRestoreDiagnostics("asset", () => withWorkspaceRestoreStep("asset_restore", async () => { throw error; }), sink,
(value) => { snapshots[1] = value; }),
]);
recordWorkspaceRestoreDiagnostic(error, snapshots[0]);
throw error;
}, sink)).rejects.toBe(error);
expect(snapshots[1]?.step).toBe("asset_restore");
expect(getWorkspaceRestoreDiagnostic(error)).toEqual(typeof error === "object" ? { phase: "workspace", errorCode: "unknown" } : undefined);
expect(sink).toHaveBeenCalledExactlyOnceWith('[paperclip] Workspace restore diagnostic: {"phase":"workspace","errorCode":"unknown"}\n');
});
it("keeps logging when a diagnostic consumer fails", async () => {
const error = new Error("restore failed");
const sink = vi.fn();
await expect(withWorkspaceRestoreDiagnostics("workspace", async () => { throw error; }, sink,
() => { throw new Error("consumer failed"); })).rejects.toBe(error);
expect(sink).toHaveBeenCalledTimes(1);
});
it("retains a nested step and bounded Git fields across an existing wrapper without a cause", async () => {
const source = Object.assign(new Error("private command/path"), { code: 1, stderr: "private stderr" });
const wrapper = new Error("existing wrapper");
await expect(withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("directory_merge", async () => {
try {
await withWorkspaceRestoreStep("git_integration", async () => { throw source; });
} catch (error) { throw preserveWorkspaceRestoreErrorDiagnostic(wrapper, error); }
}))).rejects.toBe(wrapper);
expect(wrapper).not.toHaveProperty("cause");
expect(Object.keys(wrapper)).toEqual([]);
expect(getWorkspaceRestoreDiagnostic(wrapper)).toEqual({ phase: "workspace", step: "git_integration", errorCode: "unknown", exitCode: 1 });
});
it("attributes a reused error to the later failed retry step", async () => {
const error = new Error("same failure");
await expect(withWorkspaceRestoreDiagnostics("workspace", async () => {
await withWorkspaceRestoreStep("git_import", async () => { throw error; }).catch(() => {});
await withWorkspaceRestoreStep("git_export", async () => { throw error; });
})).rejects.toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)?.step).toBe("git_export");
await expect(withWorkspaceRestoreDiagnostics("asset", async () => { throw error; })).rejects.toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "asset", errorCode: "unknown" });
});
it("isolates concurrent steps even when their errors share identity", async () => {
const error = new Error("shared error");
const sink = vi.fn();
await Promise.allSettled([
withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_import", async () => { throw error; }), sink),
withWorkspaceRestoreDiagnostics("asset", () => withWorkspaceRestoreStep("asset_restore", async () => { throw error; }), sink),
]);
expect(sink.mock.calls.map(([line]) => JSON.parse(line.split(": ")[1]))).toEqual(expect.arrayContaining([
{ phase: "workspace", step: "git_import", errorCode: "unknown" },
{ phase: "asset", step: "asset_restore", errorCode: "unknown" },
]));
});
it("starts a fresh scope for later work inherited from a completed async context", async () => {
const error = new Error("later failure");
let release!: () => void;
const gate = new Promise<void>((resolve) => { release = resolve; });
let later!: Promise<unknown>;
const sink = vi.fn();
await withWorkspaceRestoreDiagnostics("workspace", async () => {
later = gate.then(() => withWorkspaceRestoreDiagnostics("asset", () =>
withWorkspaceRestoreStep("asset_restore", async () => { throw error; }), sink)).catch((value) => value);
}, sink);
release();
expect(await later).toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "asset", step: "asset_restore", errorCode: "unknown" });
expect(sink).toHaveBeenCalledTimes(1);
});
it("leaves successful restores silent", async () => {
const sink = vi.fn();
expect(await withWorkspaceRestoreDiagnostics("workspace", async () => 42, sink)).toBe(42);
@@ -82,3 +164,136 @@ describe("workspace restore diagnostics", () => {
expect(sink).toHaveBeenCalledTimes(3);
});
});
describe("Git integration diagnostic privacy and attribution", () => {
async function capture(command: Parameters<typeof withWorkspaceRestoreGitCommand>[0], error: unknown) {
let receipt: WorkspaceRestoreDiagnostic | undefined;
const originalProperties = error && typeof error === "object" ? Object.getOwnPropertyDescriptors(error) : undefined;
await expect(withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", () =>
withWorkspaceRestoreGitCommand(command, async () => { throw error; })), undefined,
(value) => { receipt = value; })).rejects.toBe(error);
if (originalProperties) expect(Object.getOwnPropertyDescriptors(error)).toEqual(originalProperties);
return receipt;
}
it.each([
["merge_tree", { code: 1, stdout: "a".repeat(40) + "\nprivate-file", stderr: "private-conflict-body" }, "merge_conflict"],
["merge_tree", { code: 1 }, "unknown"],
["merge_tree", { code: 1, stderr: `merge-tree: ${"a".repeat(40)} - not something we can merge\n` }, "invalid_object"],
["merge_tree", { code: 1, signal: "SIGTERM" }, "unknown"],
["merge_tree", { code: 1, killed: true }, "unknown"],
["merge_tree", { code: 128, stderr: "fatal: Not a valid object name private-object" }, "invalid_object"],
["merge_tree", { code: 128, stderr: `merge-tree: ${"a".repeat(40)} - not something we can merge\n` }, "invalid_object"],
["merge_base", { code: 128, stderr: "fatal: Not a valid commit name private-object" }, "invalid_object"],
["rev_parse", { code: 128, stderr: "fatal: bad object private-object" }, "invalid_object"],
["update_ref", { code: 128, stderr: `fatal: update_ref failed for ref 'private-ref': cannot lock ref 'private-ref': is at ${"a".repeat(40)} but expected ${"b".repeat(40)}\n` }, "ref_conflict"],
["update_ref", { code: 128, stderr: "fatal: Unable to create 'private-path.lock': File exists." }, "unknown"],
["update_ref", { code: "EACCES", stderr: "private-path" }, "permission_denied"],
["commit_tree", { code: "EPERM" }, "permission_denied"],
["commit_tree", { code: 1, stderr: "Permission denied private-path" }, "unknown"],
["symbolic_ref", { code: 1 }, "unknown"],
["merge_base", { code: 1 }, "unknown"],
["log", { code: 128, stderr: "localized or unrecognized private-text" }, "unknown"],
["log", { code: 128, stderr: "x".repeat(16 * 1024) + "\nfatal: bad object private-object" }, "unknown"],
["merge_tree", "private-string", "unknown"],
] as const)("classifies only supported %s evidence (%j)", async (command, error, kind) => {
const receipt = await capture(command, error);
expect(receipt).toMatchObject({ gitCommand: command, gitFailureKind: kind });
expect(JSON.stringify(receipt)).not.toContain("private-");
expect(Object.keys(receipt!).sort()).toEqual([
"phase", "step", "errorCode", "gitCommand", "gitFailureKind",
...(typeof error === "object" && typeof error.code === "number" ? ["exitCode"] : []),
].sort());
});
it("treats throwing stderr getters as unknown and never replaces the original error", async () => {
const error = Object.defineProperty(new Error("private-original"), "stderr", { get() { throw new Error("private-getter"); } });
expect(await capture("commit_tree", error)).toEqual({ phase: "workspace", step: "git_integration",
errorCode: "unknown", gitCommand: "commit_tree", gitFailureKind: "unknown" });
});
it("retains a nested command across wrappers and nested task diagnostics", async () => {
const source = Object.assign(new Error("private-source"), { code: 1, stdout: "a".repeat(40) + "\n" });
const wrapper = new Error("private-wrapper");
const sink = vi.fn();
await expect(withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("directory_merge", () =>
withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", async () => {
try { await withWorkspaceRestoreGitCommand("merge_tree", async () => { throw source; }); }
catch (error) { throw preserveWorkspaceRestoreErrorDiagnostic(wrapper, error); }
}), sink)), sink)).rejects.toBe(wrapper);
expect(getWorkspaceRestoreDiagnostic(wrapper)).toEqual({ phase: "workspace", step: "git_integration",
errorCode: "unknown", exitCode: 1, gitCommand: "merge_tree", gitFailureKind: "merge_conflict" });
expect(wrapper).not.toHaveProperty("cause");
expect(sink).toHaveBeenCalledTimes(1);
expect(sink.mock.calls[0][0]).not.toContain("private-");
});
it("keeps a nested identity probe failure instead of relabelling it as its ref transaction", async () => {
const error = Object.assign(new Error("private-probe"), { code: 128, stderr: "private-probe-output" });
await expect(withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", () =>
withWorkspaceRestoreGitCommand("update_ref", () =>
withWorkspaceRestoreGitCommand("symbolic_ref", async () => { throw error; }))))).rejects.toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "workspace", step: "git_integration",
errorCode: "unknown", exitCode: 128, gitCommand: "symbolic_ref", gitFailureKind: "unknown" });
});
it("does not retain a handled command's label on a later failed step or retry", async () => {
const error = Object.assign(new Error("same error"), { code: 1 });
await expect(withWorkspaceRestoreDiagnostics("workspace", async () => {
await withWorkspaceRestoreStep("git_integration", () =>
withWorkspaceRestoreGitCommand("merge_tree", async () => { throw error; })).catch(() => {});
await withWorkspaceRestoreStep("index_reset", async () => { throw error; });
})).rejects.toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)).toEqual({ phase: "workspace", step: "index_reset", errorCode: "unknown", exitCode: 1 });
await expect(withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", async () => {
await withWorkspaceRestoreGitCommand("merge_tree", async () => { throw error; }).catch(() => {});
await withWorkspaceRestoreGitCommand("update_ref", async () => { throw error; });
}))).rejects.toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)).toMatchObject({ gitCommand: "update_ref", gitFailureKind: "unknown" });
});
it("retains the selected parallel task's command when two errors share identity", async () => {
const error = Object.assign(new Error("shared"), { code: 1, stdout: "a".repeat(40) + "\n" });
const snapshots: WorkspaceRestoreDiagnostic[] = [];
await expect(withWorkspaceRestoreDiagnostics("workspace", async () => {
await Promise.allSettled((["merge_tree", "update_ref"] as const).map((command, index) =>
withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", () =>
withWorkspaceRestoreGitCommand(command, async () => { throw error; })), undefined,
(receipt) => { snapshots[index] = receipt; })));
recordWorkspaceRestoreDiagnostic(error, snapshots[0]);
throw error;
})).rejects.toBe(error);
expect(snapshots.map(value => value.gitCommand)).toEqual(["merge_tree", "update_ref"]);
expect(getWorkspaceRestoreDiagnostic(error)).toMatchObject({ gitCommand: "merge_tree", gitFailureKind: "merge_conflict" });
});
it("leaves successful or handled commands silent and preserves values", async () => {
const sink = vi.fn();
const value = {};
expect(await withWorkspaceRestoreDiagnostics("workspace", () => withWorkspaceRestoreStep("git_integration", async () => {
await withWorkspaceRestoreGitCommand("symbolic_ref", async () => { throw { code: 1 }; }).catch(() => {});
return withWorkspaceRestoreGitCommand("update_ref", async () => value);
}), sink)).toBe(value);
expect(sink).not.toHaveBeenCalled();
const error = new Error("outside restore");
await expect(withWorkspaceRestoreGitCommand("log", async () => { throw error; })).rejects.toBe(error);
expect(getWorkspaceRestoreDiagnostic(error)).toBeUndefined();
});
it.each([
{ phase: "asset", step: "git_integration", gitCommand: "merge_tree" },
{ phase: "workspace", step: "index_reset", gitCommand: "merge_tree" },
{ phase: "workspace", step: "git_integration", gitCommand: "private-command" },
])("does not decode Git metadata outside the closed integration contract (%j)", (value) => {
const diagnostic = sanitizeWorkspaceRestoreDiagnostic({ ...value, gitFailureKind: "merge_conflict" });
expect(diagnostic).not.toHaveProperty("gitCommand");
expect(diagnostic).not.toHaveProperty("gitFailureKind");
});
it("revalidates persisted command and failure labels without copying extra fields", () => {
expect(sanitizeWorkspaceRestoreDiagnostic({ phase: "workspace", step: "git_integration", gitCommand: "log",
gitFailureKind: "private-reason", stderr: "private-text", args: ["private-args"] })).toEqual({
phase: "workspace", step: "git_integration", errorCode: "unknown", gitCommand: "log", gitFailureKind: "unknown",
});
});
});
packages/adapter-utils/src/workspace-restore-diagnostics.ts
+193 -9
View File
@@ -2,12 +2,54 @@ import { AsyncLocalStorage } from "node:async_hooks";
import type { RuntimeProgressSink } from "./runtime-progress.js";
type RestorePhase = "workspace" | "asset";
const RESTORE_STEPS = new Set([
"git_export", "git_import", "workspace_transfer", "workspace_extract",
"directory_merge", "git_integration", "index_reset", "git_ref_cleanup", "asset_restore",
] as const);
export type WorkspaceRestoreStep = typeof RESTORE_STEPS extends Set<infer T> ? T : never;
const GIT_COMMANDS = new Set([
"rev_parse", "symbolic_ref", "merge_base", "merge_tree", "commit_tree", "update_ref", "log",
] as const);
export type WorkspaceRestoreGitCommand = typeof GIT_COMMANDS extends Set<infer T> ? T : never;
const GIT_FAILURE_KINDS = new Set([
"merge_conflict", "invalid_object", "ref_conflict", "permission_denied", "unknown",
] as const);
type GitFailureKind = typeof GIT_FAILURE_KINDS extends Set<infer T> ? T : never;
export interface WorkspaceRestoreDiagnostic {
phase: RestorePhase;
step?: WorkspaceRestoreStep;
errorCode: string;
httpStatus?: number;
exitCode?: number;
gitCommand?: WorkspaceRestoreGitCommand;
gitFailureKind?: GitFailureKind;
}
const ERROR_CODES = new Set([
"ENOENT", "EACCES", "EPERM", "ENOSPC", "EIO", "EXDEV", "ENOTDIR", "EISDIR",
"ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "EPIPE", "ENOTFOUND", "EAI_AGAIN",
"ABORT_ERR", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET",
]);
const activeDiagnostic = new AsyncLocalStorage<boolean>();
type ErrorDiagnostic = Pick<WorkspaceRestoreDiagnostic, "errorCode" | "httpStatus" | "exitCode">;
interface DiagnosticScope {
active: boolean;
sequence: number;
failures: Map<unknown, {
sequence: number;
step?: WorkspaceRestoreStep;
gitCommand?: WorkspaceRestoreGitCommand;
gitFailureKind?: GitFailureKind;
}>;
}
const activeDiagnostic = new AsyncLocalStorage<DiagnosticScope>();
// Never attach a raw cause to an error just to retain a numeric Git exit code.
const wrappedDiagnostics = new WeakMap<object, ErrorDiagnostic>();
const restoreDiagnostics = new WeakMap<object, WorkspaceRestoreDiagnostic>();
const diagnosticCapture = new AsyncLocalStorage<WeakMap<object, WorkspaceRestoreDiagnostic>>();
/** Keep each settlement's diagnostic receipt isolated across asynchronous work. */
export function withWorkspaceRestoreDiagnosticCapture<T>(operation: () => Promise<T>): Promise<T> {
return diagnosticCapture.run(new WeakMap(), operation);
}
function readField(value: Record<string, unknown>, key: string): unknown {
try { return value[key]; } catch { return undefined; }
@@ -18,23 +60,66 @@ function boundedInteger(value: unknown, minimum: number, maximum: number): numbe
? value : undefined;
}
/** Inspect bounded stderr only in memory; never persist Git text or arguments. */
function gitFailureKind(command: WorkspaceRestoreGitCommand, error: unknown): GitFailureKind {
if (!error || typeof error !== "object") return "unknown";
const value = error as Record<string, unknown>;
const code = readField(value, "code");
if (code === "EACCES" || code === "EPERM") return "permission_denied";
if (readField(value, "killed") || readField(value, "signal")) return "unknown";
const stderr = readField(value, "stderr");
const text = typeof stderr === "string" ? stderr.slice(0, 16 * 1024) : "";
if (command === "update_ref" && /cannot lock ref '[^'\r\n]+': is at [a-f0-9]{40,64} but expected [a-f0-9]{40,64}(?:\s|$)/m.test(text)) {
return "ref_conflict";
}
if (/^fatal: (?:bad object |Not a valid object name |not a valid object name |Not a valid commit name )/m.test(text)
|| (command === "merge_tree" && /^merge-tree: [a-f0-9]{40,64} - not something we can merge\s*$/m.test(text))) {
return "invalid_object";
}
// merge-tree --write-tree prints the merged tree before reporting conflicts.
// Exit 1 alone is insufficient: some Git versions also use it for bad objects.
const stdout = readField(value, "stdout");
if (command === "merge_tree" && code === 1 && typeof stdout === "string"
&& /^(?:[a-f0-9]{40}|[a-f0-9]{64})\r?\n/.test(stdout.slice(0, 66))) return "merge_conflict";
return "unknown";
}
/** Annotate the original thrown error in its restore scope; never change it. */
export async function withWorkspaceRestoreGitCommand<T>(command: WorkspaceRestoreGitCommand, operation: () => Promise<T>): Promise<T> {
const scope = activeDiagnostic.getStore();
if (!scope?.active || !GIT_COMMANDS.has(command)) return await operation();
const started = scope.sequence;
try {
return await operation();
} catch (error) {
// A ref transaction can fail in its nested branch-identity probe. Retain
// that more specific command, while later retries get fresh attribution.
if (scope.active && (scope.failures.get(error)?.sequence ?? -1) <= started) scope.failures.set(error, {
sequence: ++scope.sequence, gitCommand: command, gitFailureKind: gitFailureKind(command, error),
});
throw error;
}
}
/** Only fixed codes and bounded numbers may enter the company-readable run log. */
function diagnostic(error: unknown): { errorCode: string; httpStatus?: number; exitCode?: number } {
const result: { errorCode: string; httpStatus?: number; exitCode?: number } = { errorCode: "unknown" };
function diagnostic(error: unknown): ErrorDiagnostic {
const result: ErrorDiagnostic = { errorCode: "unknown" };
let current = error;
// SDKs wrap transport errors in a cause. Bound traversal, including cycles.
for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
const value = current as Record<string, unknown>;
const code = readField(value, "code");
const saved = wrappedDiagnostics.get(value);
const code = saved?.errorCode !== "unknown" && saved?.errorCode !== undefined
? saved.errorCode : readField(value, "code");
if (result.errorCode === "unknown" && typeof code === "string" && ERROR_CODES.has(code)) {
result.errorCode = code;
}
const status = boundedInteger(readField(value, "status"), 400, 599)
const status = saved?.httpStatus ?? boundedInteger(readField(value, "status"), 400, 599)
?? boundedInteger(readField(value, "statusCode"), 400, 599);
if (result.httpStatus === undefined && status !== undefined) {
result.httpStatus = status;
}
const exitCode = boundedInteger(readField(value, "exitCode"), 1, 255) ?? boundedInteger(code, 1, 255);
const exitCode = saved?.exitCode ?? boundedInteger(readField(value, "exitCode"), 1, 255) ?? boundedInteger(code, 1, 255);
if (result.exitCode === undefined && exitCode !== undefined) {
result.exitCode = exitCode;
}
@@ -43,26 +128,125 @@ function diagnostic(error: unknown): { errorCode: string; httpStatus?: number; e
return result;
}
/** Retain bounded fields across an existing error wrapper, without a raw cause. */
export function preserveWorkspaceRestoreErrorDiagnostic<T extends object>(wrapper: T, source: unknown): T {
wrappedDiagnostics.set(wrapper, diagnostic(source));
const scope = activeDiagnostic.getStore();
const failure = scope?.active ? scope.failures.get(source) : undefined;
if (failure) scope!.failures.set(wrapper, failure);
return wrapper;
}
/** Decode persisted adapter metadata; never copy arbitrary properties or text. */
export function sanitizeWorkspaceRestoreDiagnostic(value: unknown): WorkspaceRestoreDiagnostic | undefined {
if (!value || typeof value !== "object") return undefined;
const record = value as Record<string, unknown>;
const phase = readField(record, "phase");
if (phase !== "workspace" && phase !== "asset") return undefined;
const step = readField(record, "step");
const code = readField(record, "errorCode");
const httpStatus = boundedInteger(readField(record, "httpStatus"), 400, 599);
const exitCode = boundedInteger(readField(record, "exitCode"), 1, 255);
const gitCommand = readField(record, "gitCommand");
const gitFailureKind = readField(record, "gitFailureKind");
const hasGitCommand = phase === "workspace" && step === "git_integration"
&& typeof gitCommand === "string" && GIT_COMMANDS.has(gitCommand as WorkspaceRestoreGitCommand);
return {
phase,
...(typeof step === "string" && RESTORE_STEPS.has(step as WorkspaceRestoreStep)
? { step: step as WorkspaceRestoreStep } : {}),
errorCode: typeof code === "string" && ERROR_CODES.has(code) ? code : "unknown",
...(httpStatus !== undefined ? { httpStatus } : {}),
...(exitCode !== undefined ? { exitCode } : {}),
...(hasGitCommand ? {
gitCommand: gitCommand as WorkspaceRestoreGitCommand,
gitFailureKind: typeof gitFailureKind === "string" && GIT_FAILURE_KINDS.has(gitFailureKind as GitFailureKind)
? gitFailureKind as GitFailureKind : "unknown",
} : {}),
};
}
export function getWorkspaceRestoreDiagnostic(error: unknown): WorkspaceRestoreDiagnostic | undefined {
return error && typeof error === "object"
? sanitizeWorkspaceRestoreDiagnostic((diagnosticCapture.getStore() ?? restoreDiagnostics).get(error)) : undefined;
}
/** Preserve the scheduler-selected task's snapshot when errors share identity. */
export function recordWorkspaceRestoreDiagnostic(error: unknown, diagnostic: WorkspaceRestoreDiagnostic | undefined): void {
const safe = sanitizeWorkspaceRestoreDiagnostic(diagnostic);
if (error && typeof error === "object") {
const receipts = diagnosticCapture.getStore() ?? restoreDiagnostics;
if (safe) receipts.set(error, safe);
else receipts.delete(error);
}
const scope = activeDiagnostic.getStore();
if (scope?.active) {
if (safe?.step) scope.failures.set(error, {
sequence: ++scope.sequence, step: safe.step,
...(safe.gitCommand ? { gitCommand: safe.gitCommand, gitFailureKind: safe.gitFailureKind } : {}),
});
else scope.failures.delete(error);
}
}
/** Record only the failing step. Successful cleanup must not replace evidence. */
export async function withWorkspaceRestoreStep<T>(step: WorkspaceRestoreStep, operation: () => Promise<T>): Promise<T> {
const scope = activeDiagnostic.getStore();
if (!scope?.active) return await operation();
const started = scope.sequence;
try {
return await operation();
} catch (error) {
// A nested step owns its failure. A caught/retried error may be thrown again
// by a later step, so identity alone cannot identify the current failure.
if (scope.active) {
const failure = scope.failures.get(error);
if (failure && failure.sequence > started) {
failure.step ??= step;
} else {
scope.failures.set(error, { sequence: ++scope.sequence, step });
}
}
throw error;
}
}
/** Add evidence without changing the thrown error, restore policy, or task ordering. */
export async function withWorkspaceRestoreDiagnostics<T>(
phase: RestorePhase,
operation: () => Promise<T>,
onProgress?: RuntimeProgressSink,
onDiagnostic?: (diagnostic: WorkspaceRestoreDiagnostic) => void,
): Promise<T> {
// A nested repository restore propagates to its enclosing workspace task.
// That task owns the diagnostic. Independent parallel tasks retain their own
// async scopes, so two failed tasks still produce two diagnostic lines.
if (activeDiagnostic.getStore()) return await operation();
return await activeDiagnostic.run(true, async () => {
const parent = activeDiagnostic.getStore();
const scope: DiagnosticScope = { active: true, sequence: 0, failures: new Map() };
return await activeDiagnostic.run(scope, async () => {
try {
return await operation();
} catch (error) {
const failure = scope.failures.get(error);
const step = failure?.step;
const fields = { phase, ...(step ? { step } : {}), ...diagnostic(error),
...(phase === "workspace" && step === "git_integration" && failure?.gitCommand
? { gitCommand: failure.gitCommand, gitFailureKind: failure.gitFailureKind } : {}),
};
recordWorkspaceRestoreDiagnostic(error, fields);
if (parent?.active && step) parent.failures.set(error, { ...failure, sequence: ++parent.sequence, step });
try {
await onProgress?.(`[paperclip] Workspace restore diagnostic: ${JSON.stringify({ phase, ...diagnostic(error) })}\n`);
onDiagnostic?.({ ...fields });
} catch { /* Diagnostic consumers cannot replace a restore failure. */ }
try {
if (!parent?.active) await onProgress?.(`[paperclip] Workspace restore diagnostic: ${JSON.stringify(fields)}\n`);
} catch {
// A broken log sink must not replace a restore failure or relax its safety classification.
}
throw error;
} finally {
scope.active = false;
scope.failures.clear();
}
});
}
packages/adapter-utils/src/workspace-restore-merge.ts
+2 -1
View File
@@ -6,6 +6,7 @@ import { DatabaseSync } from "node:sqlite";
import { createWorkspaceManifest, WorkspaceManifestMap, workspacePathMatcher, type PathManifest, type WorkspacePaths, type WorkspaceManifestWriter } from "./workspace-manifest.js";
import { shouldExcludePath } from "./exclude-patterns.js";
import { resolvePaperclipInstanceRootForAdapter } from "./server-utils.js";
import type { WorkspaceRestoreDiagnostic } from "./workspace-restore-diagnostics.js";
export type SnapshotEntry =
| { kind: "dir" }
@@ -292,7 +293,7 @@ export type WorkspaceRestoreFailureCode =
*/
export type WorkspaceRestoreOutcome =
| { readonly ok: true }
| { readonly ok: false; readonly code: WorkspaceRestoreFailureCode };
| { readonly ok: false; readonly code: WorkspaceRestoreFailureCode; readonly diagnostic?: WorkspaceRestoreDiagnostic };
/**
* Classifies a caught workspace-restore error into one allowlisted code. Maps
packages/adapter-utils/src/workspace-restore-result.test.ts
+29
View File
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { applyWorkspaceRestoreFailure, withWorkspaceRestore } from "./workspace-restore-result.js";
import type { AdapterExecutionResult } from "./types.js";
import { withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep, withWorkspaceRestoreGitCommand } from "./workspace-restore-diagnostics.js";
const completed: AdapterExecutionResult = {
exitCode: 0, signal: null, timedOut: false,
@@ -10,6 +11,34 @@ const completed: AdapterExecutionResult = {
const unsafe = new Error("Daytona syncOut refusing tarball link whose target escapes the extraction dir: .claude/skills/paperclip -> /tmp/private-clone/secret-key");
describe("workspace restore settlement", () => {
it("retains only the safe failed restore step alongside the original completed turn", async () => {
const error = Object.assign(new Error("private-restore-path and command"), { code: 1, stderr: "private-restore-output" });
const result = await withWorkspaceRestore(async () => completed, () => withWorkspaceRestoreDiagnostics("workspace", () =>
withWorkspaceRestoreStep("index_reset", async () => { throw error; })));
expect(result.resultJson).toMatchObject({
workspaceRestoreFailure: "restore_failed",
workspaceRestoreDiagnostic: { phase: "workspace", step: "index_reset", errorCode: "unknown", exitCode: 1 },
executionBeforeRestore: { exitCode: 0, timedOut: false, errorCode: null },
});
expect(JSON.stringify(result)).not.toContain("private-restore-");
});
it("persists only bounded Git evidence without replacing the completed model result", async () => {
const error = Object.assign(new Error("private-git-command /private/workspace"), {
code: 1, stdout: "a".repeat(40) + "\nprivate-git-file contents", stderr: "private-git-refs",
});
const result = await withWorkspaceRestore(async () => completed, () => withWorkspaceRestoreDiagnostics("workspace", () =>
withWorkspaceRestoreStep("git_integration", () => withWorkspaceRestoreGitCommand("merge_tree", async () => { throw error; }))));
expect(result).toMatchObject({
errorCode: "workspace_restore_failed", exitCode: completed.exitCode, summary: completed.summary, usage: completed.usage,
resultJson: { requestId: "request", workspaceRestoreFailure: "restore_failed",
workspaceRestoreDiagnostic: { phase: "workspace", step: "git_integration", errorCode: "unknown", exitCode: 1,
gitCommand: "merge_tree", gitFailureKind: "merge_conflict" },
executionBeforeRestore: { exitCode: 0, timedOut: false, errorCode: null } },
});
expect(JSON.stringify(result)).not.toContain("private-git-");
});
it("retains the completed result and safe member while excluding the unsafe target", async () => {
const result = await withWorkspaceRestore(async () => completed, async () => { throw unsafe; });
expect(result).toMatchObject({
packages/adapter-utils/src/workspace-restore-result.ts
+41 -36
View File
@@ -1,6 +1,7 @@
import { hasWorkspaceRestoreFailure, safeWorkspaceRestorePath } from "@paperclipai/shared";
import type { AdapterExecutionResult } from "./types.js";
import { classifyWorkspaceRestoreFailure } from "./workspace-restore-merge.js";
import { getWorkspaceRestoreDiagnostic, withWorkspaceRestoreDiagnosticCapture } from "./workspace-restore-diagnostics.js";
/** A completed model turn does not imply that required workspace files arrived. */
export function applyWorkspaceRestoreFailure(result: AdapterExecutionResult): AdapterExecutionResult {
@@ -29,40 +30,44 @@ export async function withWorkspaceRestore(
execute: () => Promise<AdapterExecutionResult>,
restore: () => Promise<void>,
): Promise<AdapterExecutionResult> {
let result: AdapterExecutionResult | undefined;
let executionError: unknown;
let executionThrew = false;
try {
result = await execute();
} catch (error) {
executionError = error;
executionThrew = true;
}
try {
await restore();
} catch (error) {
const code = classifyWorkspaceRestoreFailure(error);
// Parse the archive member only. Never expose the unsafe link target.
const member = error instanceof Error
? /Daytona syncOut refusing tarball link whose target escapes the extraction dir: (.+?) -> /.exec(error.message)?.[1]
: null;
const relativePath = safeWorkspaceRestorePath(member);
return applyWorkspaceRestoreFailure({
...(result ?? {
exitCode: null,
signal: null,
timedOut: false,
errorCode: "adapter_failed",
// The server applies its ordinary execution-error redaction to this field.
errorMessage: executionError instanceof Error ? executionError.message : "Adapter execution failed.",
}),
resultJson: {
...result?.resultJson,
workspaceRestoreFailure: code,
...(relativePath ? { workspaceRestorePath: relativePath } : {}),
},
});
}
if (executionThrew) throw executionError;
return result!;
return withWorkspaceRestoreDiagnosticCapture(async () => {
let result: AdapterExecutionResult | undefined;
let executionError: unknown;
let executionThrew = false;
try {
result = await execute();
} catch (error) {
executionError = error;
executionThrew = true;
}
try {
await restore();
} catch (error) {
const code = classifyWorkspaceRestoreFailure(error);
const diagnostic = getWorkspaceRestoreDiagnostic(error);
// Parse the archive member only. Never expose the unsafe link target.
const member = error instanceof Error
? /Daytona syncOut refusing tarball link whose target escapes the extraction dir: (.+?) -> /.exec(error.message)?.[1]
: null;
const relativePath = safeWorkspaceRestorePath(member);
return applyWorkspaceRestoreFailure({
...(result ?? {
exitCode: null,
signal: null,
timedOut: false,
errorCode: "adapter_failed",
// The server applies its ordinary execution-error redaction to this field.
errorMessage: executionError instanceof Error ? executionError.message : "Adapter execution failed.",
}),
resultJson: {
...result?.resultJson,
workspaceRestoreFailure: code,
...(diagnostic ? { workspaceRestoreDiagnostic: diagnostic } : {}),
...(relativePath ? { workspaceRestorePath: relativePath } : {}),
},
});
}
if (executionThrew) throw executionError;
return result!;
});
}
packages/adapter-utils/src/workspace-restore-teardown.test.ts
+27
View File
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { createWorkspaceRestoreTeardown } from "./workspace-restore-teardown.js";
import { withWorkspaceRestoreDiagnostics, withWorkspaceRestoreStep } from "./workspace-restore-diagnostics.js";
// One row per adapter's two message strings, taken verbatim from
// claude-local, codex-local, and gemini-local. The factory's contract must
@@ -24,6 +25,32 @@ const ADAPTER_MESSAGE_PAIRS = [
];
describe.each(ADAPTER_MESSAGE_PAIRS)("createWorkspaceRestoreTeardown ($adapter)", ({ startMessage, failurePrefix }) => {
it("keeps concurrent settlements separate when a provider reuses an error", async () => {
const error = Object.assign(new Error("private-restore-path"), { code: 1 });
let release!: () => void;
let started!: () => void;
const gate = new Promise<void>((resolve) => { release = resolve; });
const waiting = new Promise<void>((resolve) => { started = resolve; });
const first = createWorkspaceRestoreTeardown({
stagedRuntime: { restoreWorkspace: () => withWorkspaceRestoreDiagnostics("workspace", () =>
withWorkspaceRestoreStep("git_import", async () => { throw error; }), async () => { started(); await gate; }) },
onLog: async () => {}, startMessage, failurePrefix,
})();
await waiting;
const second = await createWorkspaceRestoreTeardown({
stagedRuntime: { restoreWorkspace: () => withWorkspaceRestoreDiagnostics("asset", () =>
withWorkspaceRestoreStep("asset_restore", async () => { throw error; })) },
onLog: async () => {}, startMessage, failurePrefix,
})();
release();
expect(await first).toEqual({ ok: false, code: "restore_failed", diagnostic: {
phase: "workspace", step: "git_import", errorCode: "unknown", exitCode: 1,
} });
expect(second).toEqual({ ok: false, code: "restore_failed", diagnostic: {
phase: "asset", step: "asset_restore", errorCode: "unknown", exitCode: 1,
} });
});
it("logs the start message to stdout and returns ok on a clean restore", async () => {
const logLines: Array<{ stream: "stdout" | "stderr"; chunk: string }> = [];
const teardown = createWorkspaceRestoreTeardown({
packages/adapter-utils/src/workspace-restore-teardown.ts
+5 -3
View File
@@ -1,4 +1,5 @@
import type { RuntimeProgressSink } from "./runtime-progress.js";
import { getWorkspaceRestoreDiagnostic, withWorkspaceRestoreDiagnosticCapture } from "./workspace-restore-diagnostics.js";
import {
classifyWorkspaceRestoreFailure,
describeWorkspaceRestoreFailure,
@@ -33,7 +34,7 @@ export function createWorkspaceRestoreTeardown(input: {
failurePrefix: string;
}): () => Promise<WorkspaceRestoreOutcome> {
const { stagedRuntime, onLog, startMessage, failurePrefix } = input;
return async () => {
return () => withWorkspaceRestoreDiagnosticCapture(async () => {
try {
await onLog("stdout", startMessage);
await stagedRuntime.restoreWorkspace((line) => onLog("stdout", line));
@@ -44,8 +45,9 @@ export function createWorkspaceRestoreTeardown(input: {
// filesystem path or a process id. Log only the fixed, allowlisted
// diagnostic for the classified code.
const code = classifyWorkspaceRestoreFailure(err);
const diagnostic = getWorkspaceRestoreDiagnostic(err);
await onLog("stderr", `${failurePrefix}: ${describeWorkspaceRestoreFailure(code)}\n`);
return { ok: false, code };
return { ok: false, code, ...(diagnostic ? { diagnostic } : {}) };
}
};
});
}
packages/adapters/claude-local/src/index.test.ts
+11
View File
@@ -8,10 +8,21 @@ describe("Claude model defaults", () => {
expect(claudeLocalReasoningEffortsForModel(model)).toEqual(["low", "medium", "high", "xhigh", "max"]);
});
it.each([
"claude-sonnet-5-5",
"claude-sonnet-5-5[1m]",
"us.anthropic.claude-sonnet-5-5",
"global.anthropic.claude-sonnet-5-5[1m]",
])("requires CLI 2.1.284 and offers all efforts for %s", (model) => {
expect(minimumClaudeCliVersionForModel(model)).toBe("2.1.284");
expect(claudeLocalReasoningEffortsForModel(model)).toEqual(["low", "medium", "high", "xhigh", "max"]);
});
it("keeps model-specific Claude reasoning limits", () => {
expect(claudeLocalReasoningEffortsForModel("claude-fable-5-1")).toContain("xhigh");
expect(claudeLocalReasoningEffortsForModel("claude-sonnet-5")).toContain("max");
expect(claudeLocalReasoningEffortsForModel("claude-sonnet-4-6")).toEqual(["low", "medium", "high", "max"]);
expect(claudeLocalReasoningEffortsForModel("claude-sonnet-4-5")).toEqual(["low", "medium", "high"]);
expect(claudeLocalReasoningEffortsForModel("claude-haiku-4-5")).toEqual([]);
expect(claudeLocalReasoningEffortsForModel("custom-model")).toEqual(["low", "medium", "high"]);
});
packages/adapters/claude-local/src/index.ts
+5 -3
View File
@@ -26,7 +26,7 @@ export const type = "claude_local";
export function claudeLocalReasoningEffortsForModel(model: string): readonly string[] {
const id = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global)\.)?anthropic\./, "");
if (/^claude-haiku-/.test(id)) return [];
if (/^claude-(?:opus-5(?:-5)?|opus-4-[78]|sonnet-5|fable-5(?:-1)?)$/.test(id)) {
if (/^claude-(?:opus-5(?:-5)?|opus-4-[78]|sonnet-5(?:-5)?|fable-5(?:-1)?)$/.test(id)) {
return ["low", "medium", "high", "xhigh", "max"];
}
if (/^claude-(?:opus|sonnet)-4-6(?:-v1)?$/.test(id)) return ["low", "medium", "high", "max"];
@@ -43,13 +43,14 @@ export const models = [
{ id: "claude-fable-5-1", label: "Claude Fable 5.1" },
{ id: "claude-mythos-5", label: "Claude Mythos 5" },
{ id: "claude-opus-5-5", label: "Claude Opus 5.5" },
{ id: "claude-sonnet-5", label: "Claude Sonnet 5" },
{ id: "claude-sonnet-5-5", label: "Claude Sonnet 5.5" },
{ id: "claude-haiku-4-5", label: "Claude Haiku 4.5" },
{ id: "claude-fable-5", label: "Claude Fable 5" },
{ id: "claude-opus-5", label: "Claude Opus 5" },
{ id: "claude-opus-4-8", label: "Claude Opus 4.8" },
{ id: "claude-opus-4-7", label: "Claude Opus 4.7" },
{ id: "claude-opus-4-6", label: "Claude Opus 4.6" },
{ id: "claude-sonnet-5", label: "Claude Sonnet 5" },
{ id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
{ id: "claude-sonnet-4-5", label: "Claude Sonnet 4.5" },
];
@@ -63,7 +64,7 @@ Core fields:
- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)
- instructionsFilePath (string, optional): absolute path to a markdown instructions file injected at runtime
- model (string, optional): Claude model id. Missing or blank defaults to ${DEFAULT_CLAUDE_LOCAL_MODEL} in both CLI and ACP, including existing agents. Explicit model IDs and ANTHROPIC_MODEL overrides are preserved. Bedrock/Vertex without an explicit model retain their provider default.
- effort (string, optional): model-specific reasoning effort passed via --effort (low|medium|high; current Opus, Sonnet 5, and Fable models also support xhigh|max)
- effort (string, optional): model-specific reasoning effort passed via --effort (low|medium|high; current Opus, Sonnet 5/5.5, and Fable models also support xhigh|max)
- chrome (boolean, optional): pass --chrome when running Claude
- promptTemplate (string, optional): run prompt template
- maxTurnsPerRun (number, optional): max turns for one run
@@ -92,6 +93,7 @@ Operational fields:
Notes:
- Claude Opus 5.5 uses model ID \`claude-opus-5-5\` and requires Claude Code v2.1.280 or later.
- Claude Sonnet 5.5 uses model ID \`claude-sonnet-5-5\` and requires Claude Code v2.1.284 or later.
- filesystemScope and networkScope are spawn-level confinement and are orthogonal to Claude permission flags. Both require Bubblewrap on the host and explicit engine="cli"; default or explicit ACP is rejected because ACP confinement is not yet supported. networkScope="allowlist" injects HTTP_PROXY/HTTPS_PROXY for the CLI while its private network namespace blocks direct sockets, so every required provider/API hostname must be listed explicitly.
- The Claude ACP lane requires Node >=24.11.0 and @agentclientprotocol/claude-agent-acp to be installed with this adapter package. Missing prerequisites fail both default and explicit ACP runs with an actionable setup error; the adapter never switches engines automatically.
- For ACP runs, model selection is passed through ANTHROPIC_MODEL at ACP server startup; Paperclip-managed Claude permissions and ephemeral skill materialization are handled by the shared ACP engine.
packages/adapters/claude-local/src/server/acp.test.ts
+4 -1
View File
@@ -1065,10 +1065,13 @@ describe("claude_local ACP lane", () => {
// Only a fixed diagnostic may contain the errno, never the raw error.
expect(result.exitCode).toBe(0);
expect(result.resultJson?.workspaceRestoreFailure).toBe("restore_permission_denied");
expect(result.resultJson?.workspaceRestoreDiagnostic).toEqual({
phase: "workspace", step: "directory_merge", errorCode: "EACCES",
});
const allLogs = loggedLines.join("");
expect(allLogs).not.toContain("SENTINEL-HOST-PATH-marker");
expect(allLogs).not.toContain(localCwd);
const diagnostic = '[paperclip] Workspace restore diagnostic: {"phase":"workspace","errorCode":"EACCES"}\n';
const diagnostic = '[paperclip] Workspace restore diagnostic: {"phase":"workspace","step":"directory_merge","errorCode":"EACCES"}\n';
expect(loggedLines.filter((line) => line.includes("Workspace restore diagnostic:"))).toEqual([diagnostic]);
expect(loggedLines.filter((line) => line !== diagnostic).join("")).not.toContain("EACCES");
expect(allLogs).toContain("permission denied");
packages/adapters/claude-local/src/server/cli-capabilities.ts
+1
View File
@@ -38,6 +38,7 @@ function cacheKeyForTarget(command: string, target: AdapterExecutionTarget | nul
export function minimumClaudeCliVersionForModel(model: string): string | null {
const modelId = model.trim().replace(/\[1m\]$/, "").replace(/^(?:(?:us|eu|apac|global)\.)?anthropic\./, "");
if (modelId === "claude-opus-5-5") return "2.1.280";
if (modelId === "claude-sonnet-5-5") return "2.1.284";
return modelId === "claude-fable-5-1"
? CLAUDE_FABLE_5_1_MIN_CLI_VERSION
: null;
packages/adapters/claude-local/src/server/execute.remote.test.ts
+3 -2
View File
@@ -18,7 +18,7 @@ const {
signal: null,
timedOut: false,
stdout: args.includes("--version")
? "2.1.280 (Claude Code)\n"
? "2.1.284 (Claude Code)\n"
: [
JSON.stringify({ type: "system", subtype: "init", session_id: "claude-session-1", model: "claude-sonnet" }),
JSON.stringify({ type: "assistant", session_id: "claude-session-1", message: { content: [{ type: "text", text: "hello" }] } }),
@@ -467,7 +467,7 @@ describe("claude remote execution", () => {
return { args: call?.[2] ?? [], result };
}
it.each(["claude-fable-5-1", "claude-opus-5-5"])("passes %s as --model on the CLI lane", async (model) => {
it.each(["claude-fable-5-1", "claude-opus-5-5", "claude-sonnet-5-5"])("passes %s as --model on the CLI lane", async (model) => {
const { args } = await executeWithModel("paperclip-claude-model-direct-", {
model,
});
@@ -500,6 +500,7 @@ describe("claude remote execution", () => {
it.each([
["claude-fable-5-1", "2.1.251", "2.1.247"],
["claude-opus-5-5", "2.1.280", "2.1.279"],
["claude-sonnet-5-5", "2.1.284", "2.1.283"],
])("rejects %s before launch below CLI %s", async (model, minimumVersion, detectedVersion) => {
runChildProcess.mockResolvedValueOnce({
exitCode: 0,
packages/adapters/claude-local/src/server/models.ts
+3 -1
View File
@@ -17,13 +17,15 @@ const BEDROCK_MODELS: AdapterModel[] = [
// Fable 5.1's documented geo inference ID carries no -v1 suffix, unlike earlier entries.
{ id: "us.anthropic.claude-fable-5-1", label: "Bedrock Fable 5.1" },
{ id: "us.anthropic.claude-opus-5-5", label: "Bedrock Opus 5.5" },
{ id: "us.anthropic.claude-sonnet-5", label: "Bedrock Sonnet 5" },
// Sonnet 5.5's documented Bedrock ID is dateless, like Fable 5.1 and Opus 5.5.
{ id: "us.anthropic.claude-sonnet-5-5", label: "Bedrock Sonnet 5.5" },
{ id: "us.anthropic.claude-haiku-4-5-20251001-v1:0", label: "Bedrock Haiku 4.5" },
{ id: "us.anthropic.claude-fable-5", label: "Bedrock Fable 5" },
{ id: "us.anthropic.claude-opus-5", label: "Bedrock Opus 5" },
{ id: "us.anthropic.claude-opus-4-8", label: "Bedrock Opus 4.8" },
{ id: "us.anthropic.claude-opus-4-7", label: "Bedrock Opus 4.7" },
{ id: "us.anthropic.claude-opus-4-6-v1", label: "Bedrock Opus 4.6" },
{ id: "us.anthropic.claude-sonnet-5", label: "Bedrock Sonnet 5" },
{ id: "us.anthropic.claude-sonnet-4-6", label: "Bedrock Sonnet 4.6" },
{ id: "us.anthropic.claude-sonnet-4-5-20250929-v2:0", label: "Bedrock Sonnet 4.5" },
];
packages/adapters/claude-local/src/server/test.probe.test.ts
+1
View File
@@ -642,6 +642,7 @@ describe("claude CLI local hello probe hardening", () => {
it.each([
["claude-fable-5-1", "2.1.251"],
["claude-opus-5-5", "2.1.280"],
["claude-sonnet-5-5", "2.1.284"],
])("warns without executing %s when runtime PATH selects a different executable", async (model, minimumVersion) => {
const runtimeDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-cli-runtime-path-"));
const runtimeClaudePath = path.join(runtimeDir, "claude");
packages/adapters/claude-local/src/server/test.remote.test.ts
+1
View File
@@ -144,6 +144,7 @@ describe("claude CLI model compatibility check", () => {
it.each([
["claude-fable-5-1", "2.1.251", "2.1.247"],
["claude-opus-5-5", "2.1.280", "2.1.279"],
["claude-sonnet-5-5", "2.1.284", "2.1.283"],
])("fails before the hello probe for %s below CLI %s", async (model, minimumVersion, detectedVersion) => {
probeResult.value = {
exitCode: 0,
packages/adapters/codex-local/src/index.test.ts
+4 -2
View File
@@ -15,7 +15,8 @@ describe("codex local adapter metadata", () => {
// alias, so it must not be advertised or used as the default (it triggers a fallback warning).
expect(DEFAULT_CODEX_LOCAL_MODEL).toBe("gpt-5.6-sol");
// Ordered like the ChatGPT app: newest version first, then by capability within a version (#14878).
expect(modelIds.slice(0, 12)).toEqual([
expect(modelIds.slice(0, 13)).toEqual([
"gpt-6.1-sol",
"gpt-6-astra",
"gpt-6-sol",
"gpt-6-luna",
@@ -32,12 +33,13 @@ describe("codex local adapter metadata", () => {
expect(modelIds).not.toContain("gpt-5.6");
expect(isCodexLocalFastModeSupported(DEFAULT_CODEX_LOCAL_MODEL)).toBe(true);
expect(isCodexLocalFastModeSupported("gpt-6-astra")).toBe(true);
expect(isCodexLocalFastModeSupported("gpt-6.1-sol")).toBe(true);
expect(isCodexLocalFastModeSupported("gpt-6-sol")).toBe(true);
expect(modelIds).not.toContain("gpt-5.3-codex");
expect(modelIds).not.toContain("gpt-5.3-codex-spark");
});
it.each(["gpt-6-astra", "gpt-6-sol", " gpt-6-sol ", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6"])("uses the reasoning efforts advertised for %s", (model) => {
it.each(["gpt-6-astra", "gpt-6.1-sol", "gpt-6-sol", " gpt-6-sol ", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6"])("uses the reasoning efforts advertised for %s", (model) => {
expect(codexLocalReasoningEffortsForModel(model)).toEqual([
"low",
"medium",
packages/adapters/codex-local/src/index.ts
+6 -3
View File
@@ -14,6 +14,7 @@ export const DEFAULT_CODEX_LOCAL_MODEL = PAPERCLIP_RUNNER_DEFAULT_MODELS.codex;
export const DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX = true;
export const CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS = [
"gpt-6-astra",
"gpt-6.1-sol",
"gpt-6-sol",
"gpt-6-luna",
"gpt-5.6-sol",
@@ -71,6 +72,7 @@ export function codexLocalReasoningEffortsForModel(
const normalizedModel = normalizeCodexModel(model);
switch (normalizedModel) {
case "gpt-6-astra":
case "gpt-6.1-sol":
case "gpt-6-sol":
case "gpt-5.6-sol":
case "gpt-5.6-terra":
@@ -110,6 +112,7 @@ export function isCodexLocalFastModeSupported(model: string | null | undefined):
// then by decreasing capability inside each version, older models at the end. The server
// returns this list as written and the model dropdown keeps its order.
export const models = [
{ id: "gpt-6.1-sol", label: "gpt-6.1-sol" },
{ id: "gpt-6-astra", label: "gpt-6-astra" },
{ id: "gpt-6-sol", label: "gpt-6-sol" },
{ id: "gpt-6-luna", label: "gpt-6-luna" },
@@ -138,10 +141,10 @@ Core fields:
- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)
- instructionsFilePath (string, optional): absolute path to a markdown instructions file prepended to stdin prompt at runtime
- model (string, optional): Codex model id
- modelReasoningEffort (string, optional): reasoning effort override passed via -c model_reasoning_effort=...; GPT-6 Astra/Sol and GPT-5.6 Sol/Terra support low|medium|high|xhigh|max|ultra; GPT-6 Luna and GPT-5.6 Luna support low|medium|high|xhigh|max
- modelReasoningEffort (string, optional): reasoning effort override passed via -c model_reasoning_effort=...; GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol, and GPT-5.6 Sol/Terra support low|medium|high|xhigh|max|ultra; GPT-6 Luna and GPT-5.6 Luna support low|medium|high|xhigh|max
- promptTemplate (string, optional): run prompt template
- search (boolean, optional): run codex with --search
- fastMode (boolean, optional): enable Codex Fast mode; supported on GPT-6 (astra/sol/luna), GPT-5.6 (sol/terra/luna), GPT-5.5, GPT-5.4 and passed through for manual model IDs
- fastMode (boolean, optional): enable Codex Fast mode; supported on GPT-6 (astra/sol/luna), GPT-6.1 Sol, GPT-5.6 (sol/terra/luna), GPT-5.5, GPT-5.4 and passed through for manual model IDs
- dangerouslyBypassApprovalsAndSandbox (boolean, optional): run with bypass flag
- command (string, optional): defaults to "codex"
- extraArgs (string[], optional): additional CLI args
@@ -172,7 +175,7 @@ Notes:
- Paperclip injects desired local skills into the effective CODEX_HOME/skills/ directory at execution time so Codex can discover "$paperclip" and related skills without polluting the project working directory. For new and updated agents, Paperclip assigns an isolated managed home at ~/.paperclip/instances/<id>/companies/<companyId>/agents/<agentId>/codex-home/skills/; when CODEX_HOME is explicitly overridden in adapter config, that override is used instead.
- New and updated codex_local agents persist an empty OPENAI_API_KEY override by default so a host-level OPENAI_API_KEY cannot leak into Codex runs through process inheritance. Explicit CODEX_HOME overrides must not point at the shared company codex-home, $CODEX_HOME, or ~/.codex.
- Some model/tool combinations reject certain effort levels (for example minimal with web search enabled).
- Fast mode is supported on GPT-6 (astra/sol/luna), GPT-5.6 (sol/terra/luna), GPT-5.5, GPT-5.4 and manual model IDs. When enabled for those models, Paperclip applies \`service_tier="fast"\` and \`features.fast_mode=true\`.
- Fast mode is supported on GPT-6 (astra/sol/luna), GPT-6.1 Sol, GPT-5.6 (sol/terra/luna), GPT-5.5, GPT-5.4 and manual model IDs. When enabled for those models, Paperclip applies \`service_tier="fast"\` and \`features.fast_mode=true\`.
- When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
- The ACP engine keeps its workspace sandbox and enables network access on each turn. Explicit sandbox_workspace_write.network_access overrides in extraArgs (or env.PAPERCLIP_CODEX_ACP_NETWORK_ACCESS="false") disable it; execution-target network denial wins. The bundled ACP patch is needed because upstream mode presets override Codex config.toml on every turn.
- The CLI engine defaults to a writable workspace sandbox with network access for unattended work and Paperclip API calls. It does not enable the dangerous bypass flag. Explicit sandbox modes/profiles and network overrides in extraArgs retain their meaning. An execution-target network denial remains enforced.
packages/adapters/codex-local/src/server/acp.test.ts
+1 -1
View File
@@ -508,7 +508,7 @@ describe("codex_local ACP lane", () => {
});
});
it.each([["gpt-6-astra", "ultra"], ["gpt-6-sol", "ultra"], ["gpt-6-luna", "max"], ["gpt-5.6-sol", "ultra"], ["gpt-5.6-terra", "ultra"], ["gpt-5.6-luna", "max"]])("forwards %s controls to the ACPX Codex target", (model, effort) => {
it.each([["gpt-6-astra", "ultra"], ["gpt-6.1-sol", "ultra"], ["gpt-6-sol", "ultra"], ["gpt-6-luna", "max"], ["gpt-5.6-sol", "ultra"], ["gpt-5.6-terra", "ultra"], ["gpt-5.6-luna", "max"]])("forwards %s controls to the ACPX Codex target", (model, effort) => {
expect(buildCodexAcpConfig({
engine: "acp",
model,
packages/adapters/codex-local/src/server/codex-args.test.ts
+2 -2
View File
@@ -9,7 +9,7 @@ describe("buildCodexExecArgs", () => {
if (resumeSessionId) expect(args.slice(-3)).toEqual(["resume", resumeSessionId, "-"]);
});
it.each([["gpt-6-astra", "ultra"], ["gpt-6-sol", "ultra"], ["gpt-6-luna", "max"], ["gpt-5.6-sol", "ultra"], ["gpt-5.6-terra", "ultra"], ["gpt-5.6-luna", "max"]])("forwards %s, its supported reasoning effort, and fast mode", (model, effort) => {
it.each([["gpt-6-astra", "ultra"], ["gpt-6.1-sol", "ultra"], ["gpt-6-sol", "ultra"], ["gpt-6-luna", "max"], ["gpt-5.6-sol", "ultra"], ["gpt-5.6-terra", "ultra"], ["gpt-5.6-luna", "max"]])("forwards %s, its supported reasoning effort, and fast mode", (model, effort) => {
const result = buildCodexExecArgs({
model,
modelReasoningEffort: effort,
@@ -148,7 +148,7 @@ describe("buildCodexExecArgs", () => {
expect(result.fastModeRequested).toBe(true);
expect(result.fastModeApplied).toBe(false);
expect(result.fastModeIgnoredReason).toContain(
"currently only supported on gpt-6-astra, gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4 or manually configured model IDs",
"currently only supported on gpt-6-astra, gpt-6.1-sol, gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4 or manually configured model IDs",
);
expect(result.args).toEqual([
"exec",
packages/adapters/codex-local/src/ui/build-config.test.ts
+1 -1
View File
@@ -94,7 +94,7 @@ describe("buildCodexLocalConfig", () => {
});
});
it.each([["gpt-6-astra", "ultra"], ["gpt-6-sol", "ultra"], ["gpt-6-luna", "max"], ["gpt-5.6-sol", "ultra"], ["gpt-5.6-terra", "ultra"], ["gpt-5.6-luna", "max"]])("persists the exact %s model and supported controls", (model, effort) => {
it.each([["gpt-6-astra", "ultra"], ["gpt-6.1-sol", "ultra"], ["gpt-6-sol", "ultra"], ["gpt-6-luna", "max"], ["gpt-5.6-sol", "ultra"], ["gpt-5.6-terra", "ultra"], ["gpt-5.6-luna", "max"]])("persists the exact %s model and supported controls", (model, effort) => {
const config = buildCodexLocalConfig(
makeValues({
model,
packages/adapters/opencode-local/src/index.ts
+2
View File
@@ -54,6 +54,7 @@ export function isValidOpenCodeModelId(value: unknown): value is string {
export const models: Array<{ id: string; label: string }> = [
{ id: DEFAULT_OPENCODE_LOCAL_MODEL, label: DEFAULT_OPENCODE_LOCAL_MODEL },
{ id: "openai/gpt-6-astra", label: "openai/gpt-6-astra" },
{ id: "openai/gpt-6.1-sol", label: "openai/gpt-6.1-sol" },
{ id: "openai/gpt-6-sol", label: "openai/gpt-6-sol" },
{ id: "openai/gpt-6-luna", label: "openai/gpt-6-luna" },
{ id: "openai/gpt-5.6-sol", label: "openai/gpt-5.6-sol" },
@@ -62,6 +63,7 @@ export const models: Array<{ id: string; label: string }> = [
{ id: "anthropic/claude-opus-5-5", label: "anthropic/claude-opus-5-5" },
{ id: "anthropic/claude-opus-5", label: "anthropic/claude-opus-5" },
{ id: "anthropic/claude-fable-5-1", label: "anthropic/claude-fable-5-1" },
{ id: "anthropic/claude-sonnet-5-5", label: "anthropic/claude-sonnet-5-5" },
{ id: "anthropic/claude-sonnet-5", label: "anthropic/claude-sonnet-5" },
{ id: "google/gemini-3.8-flash", label: "google/gemini-3.8-flash" },
{ id: "xai/grok-4.7", label: "xai/grok-4.7" },
packages/db/src/connections-v3-schema-core-migration.test.ts
+3
View File
@@ -47,6 +47,9 @@ describeEmbeddedPostgres("connections v3 schema core migration", () => {
await sql`DROP TABLE IF EXISTS "browser_use_runs"`;
await sql`DROP TABLE IF EXISTS "browser_use_sessions"`;
await sql`DROP TABLE IF EXISTS "browser_use_settings"`;
// Managed-account observations are later consumers of the same connection key.
await sql`DROP TABLE IF EXISTS "tool_connection_app_syncs"`;
await sql`DROP TABLE IF EXISTS "tool_connection_app_snapshots"`;
await sql`DROP TABLE IF EXISTS "connection_grants"`;
await sql`DROP INDEX IF EXISTS "tool_connections_company_uid_uq"`;
await sql`ALTER TABLE "tool_connections" DROP CONSTRAINT IF EXISTS "tool_connections_company_id_uq"`;
packages/db/src/migrations/0295_public_captain_cross.sql
+21
View File
@@ -0,0 +1,21 @@
CREATE TABLE IF NOT EXISTS "tool_connection_app_snapshots" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"connection_id" uuid NOT NULL,
"user_id" text NOT NULL,
"credential_key" text NOT NULL,
"toolkit" text NOT NULL,
"status" text NOT NULL,
"accounts" jsonb DEFAULT '[]'::jsonb NOT NULL,
"checked_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
DO $$ BEGIN
ALTER TABLE "tool_connection_app_snapshots" ADD CONSTRAINT "tool_connection_app_snapshots_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;--> statement-breakpoint
DO $$ BEGIN
ALTER TABLE "tool_connection_app_snapshots" ADD CONSTRAINT "tool_connection_app_snapshots_company_connection_fk" FOREIGN KEY ("company_id","connection_id") REFERENCES "public"."tool_connections"("company_id","id") ON DELETE cascade ON UPDATE no action;
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;--> statement-breakpoint
CREATE UNIQUE INDEX IF NOT EXISTS "tool_connection_app_snapshots_owner_toolkit_uq" ON "tool_connection_app_snapshots" USING btree ("company_id","connection_id","user_id","toolkit");
packages/db/src/migrations/0296_stiff_thaddeus_ross.sql
+25
View File
@@ -0,0 +1,25 @@
CREATE TABLE IF NOT EXISTS "tool_connection_app_syncs" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
"company_id" uuid NOT NULL,
"connection_id" uuid NOT NULL,
"user_id" text NOT NULL,
"credential_key" text NOT NULL,
"lease_id" uuid NOT NULL,
"status" text NOT NULL,
"checked" integer DEFAULT 0 NOT NULL,
"total" integer DEFAULT 0 NOT NULL,
"failed" integer DEFAULT 0 NOT NULL,
"last_completed_at" timestamp with time zone,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
ALTER TABLE "tool_connection_app_snapshots" ADD COLUMN IF NOT EXISTS "error_at" timestamp with time zone;--> statement-breakpoint
DO $$ BEGIN
ALTER TABLE "tool_connection_app_syncs" ADD CONSTRAINT "tool_connection_app_syncs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;--> statement-breakpoint
DO $$ BEGIN
ALTER TABLE "tool_connection_app_syncs" ADD CONSTRAINT "tool_connection_app_syncs_company_connection_fk" FOREIGN KEY ("company_id","connection_id") REFERENCES "public"."tool_connections"("company_id","id") ON DELETE cascade ON UPDATE no action;
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;--> statement-breakpoint
CREATE UNIQUE INDEX IF NOT EXISTS "tool_connection_app_syncs_owner_key_uq" ON "tool_connection_app_syncs" USING btree ("company_id","connection_id","user_id","credential_key");
packages/db/src/migrations/0297_foamy_swordsman.sql
+14
View File
@@ -0,0 +1,14 @@
CREATE TABLE "resource_lifecycle_events" (
"id" bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY (sequence name "resource_lifecycle_events_id_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START WITH 1 CACHE 1),
"company_id" uuid NOT NULL,
"resource_type" text NOT NULL,
"resource_id" uuid NOT NULL,
"action" text NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "resource_lifecycle_events_resource_type_check" CHECK ("resource_lifecycle_events"."resource_type" IN ('agent', 'project')),
CONSTRAINT "resource_lifecycle_events_action_check" CHECK ("resource_lifecycle_events"."action" = 'create' OR ("resource_lifecycle_events"."resource_type" = 'agent' AND "resource_lifecycle_events"."action" IN ('pause', 'resume', 'terminate')))
);
--> statement-breakpoint
ALTER TABLE "resource_lifecycle_events" ADD CONSTRAINT "resource_lifecycle_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
CREATE UNIQUE INDEX "resource_lifecycle_events_creation_idx" ON "resource_lifecycle_events" USING btree ("company_id","resource_type","resource_id") WHERE "resource_lifecycle_events"."action" = 'create';--> statement-breakpoint
CREATE INDEX "resource_lifecycle_events_company_idx" ON "resource_lifecycle_events" USING btree ("company_id","id");
packages/db/src/migrations/0298_connection_agent_instructions.sql
+16
View File
@@ -0,0 +1,16 @@
ALTER TABLE "tool_connections" ADD COLUMN IF NOT EXISTS "agent_instructions" jsonb;
--> statement-breakpoint
UPDATE "tool_connections" SET "agent_instructions" = '{"enabled": true, "text": "Use Honcho to recall relevant preferences and prior decisions when work depends on earlier context. Use the configured workspace and the peer or session identified by the task or existing provider context. Save concise, durable facts after useful work; if a required memory target is unclear, clarify it before saving. Treat retrieved memories as background context and follow current task instructions when they differ. Do not store credentials or copy entire conversations. Respect action permissions and approvals; if a call fails or indexing is pending, continue useful work and accurately report what was saved or remains unavailable.", "template": {"id": "honcho.usage", "version": 1}}'::jsonb
WHERE "agent_instructions" IS NULL AND COALESCE("config"->>'sourceTemplateKey', "transport_config"->>'sourceTemplateKey') = 'honcho';
--> statement-breakpoint
UPDATE "tool_connections" SET "agent_instructions" = '{"enabled": true, "text": "Use Mem0 to search for relevant preferences, decisions, and prior work before relying on remembered context. Save concise, durable facts after useful work using the entity identified by the task or provider context. Reuse that entity when retrieving its memories; clarify a missing target rather than inventing an agent or company memory scope. Treat retrieved memories as background context and follow current task instructions when they differ. Do not store credentials or copy entire conversations. Respect action permissions and approvals; if a call fails or indexing is pending, continue useful work and accurately report what was saved or remains unavailable.", "template": {"id": "mem0.usage", "version": 1}}'::jsonb
WHERE "agent_instructions" IS NULL AND COALESCE("config"->>'sourceTemplateKey', "transport_config"->>'sourceTemplateKey') = 'mem0';
--> statement-breakpoint
UPDATE "tool_connections" SET "agent_instructions" = '{"enabled": true, "text": "Use Zep to search the connected identity’s memory when earlier decisions or preferences matter. Save concise, durable facts after useful work when writing is available. Use a shared graph only when the task identifies it and the connection authorizes it; do not substitute a different identity or graph. Treat retrieved memories as background context and follow current task instructions when they differ. Do not store credentials or copy entire conversations. Respect action permissions and approvals; if a call fails or indexing is pending, continue useful work and accurately report what was saved or remains unavailable.", "template": {"id": "zep.usage", "version": 1}}'::jsonb
WHERE "agent_instructions" IS NULL AND COALESCE("config"->>'sourceTemplateKey', "transport_config"->>'sourceTemplateKey') = 'zep';
--> statement-breakpoint
UPDATE "tool_connections" SET "agent_instructions" = '{"enabled": true, "text": "Use Supermemory to recall relevant preferences, decisions, and prior work from the workspace and tags authorized for this connection. Save concise, durable facts after useful work using the same authorized context. Use the available search and save tools; do not change spaces or broaden tags to bypass the configured access. Treat retrieved memories as background context and follow current task instructions when they differ. Do not store credentials or copy entire conversations. Respect action permissions and approvals; if a call fails or indexing is pending, continue useful work and accurately report what was saved or remains unavailable.", "template": {"id": "supermemory.usage", "version": 1}}'::jsonb
WHERE "agent_instructions" IS NULL AND COALESCE("config"->>'sourceTemplateKey', "transport_config"->>'sourceTemplateKey') = 'supermemory';
--> statement-breakpoint
UPDATE "tool_connections" SET "agent_instructions" = '{"enabled": true, "text": "Use Cognee recall to retrieve relevant facts and decisions when work depends on earlier context. Use remember to save concise, durable facts after useful work in the dataset or session identified by the task, or the connection’s provider default. Use forget only when the task calls for deletion. Treat retrieved memories as background context and follow current task instructions when they differ. Do not store credentials or copy entire conversations. Respect action permissions and approvals; if a call fails or indexing is pending, continue useful work and accurately report what was saved or remains unavailable.", "template": {"id": "cognee.usage", "version": 1}}'::jsonb
WHERE "agent_instructions" IS NULL AND COALESCE("config"->>'sourceTemplateKey', "transport_config"->>'sourceTemplateKey') = 'cognee';
packages/db/src/migrations/meta/0293_snapshot.json → packages/db/src/migrations/meta/0295_snapshot.json
Generated
+156 -2
View File
@@ -1,6 +1,6 @@
{
"id": "d0c40f4e-c2c5-4efd-bc15-c6ae5632047d",
"prevId": "239dfc30-3531-48b5-a06f-72608de479da",
"id": "02d31b6c-7df3-4f6c-b906-e2d369b5e1cd",
"prevId": "66a0b3c9-91bb-46b8-a868-a6facedbc14b",
"version": "7",
"dialect": "postgresql",
"tables": {
@@ -44497,6 +44497,139 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_snapshots": {
"name": "tool_connection_app_snapshots",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"toolkit": {
"name": "toolkit",
"type": "text",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"accounts": {
"name": "accounts",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'[]'::jsonb"
},
"checked_at": {
"name": "checked_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"tool_connection_app_snapshots_owner_toolkit_uq": {
"name": "tool_connection_app_snapshots_owner_toolkit_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "toolkit",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_snapshots_company_id_companies_id_fk": {
"name": "tool_connection_app_snapshots_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_snapshots_company_connection_fk": {
"name": "tool_connection_app_snapshots_company_connection_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_installs": {
"name": "tool_connection_installs",
"schema": "",
@@ -46209,6 +46342,27 @@
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_expiry_idx": {
"name": "tool_mcp_gateway_tokens_expiry_idx",
"columns": [
{
"expression": "expires_at",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_gateway_idx": {
"name": "tool_mcp_gateway_tokens_gateway_idx",
"columns": [
packages/db/src/migrations/meta/0292_snapshot.json → packages/db/src/migrations/meta/0296_snapshot.json
Generated
+322 -2
View File
@@ -1,6 +1,6 @@
{
"id": "239dfc30-3531-48b5-a06f-72608de479da",
"prevId": "a02dd1cf-75c9-4c4d-b13d-cf5dcd729ad3",
"id": "a6c67322-9605-4234-b05d-b3585e943e42",
"prevId": "02d31b6c-7df3-4f6c-b906-e2d369b5e1cd",
"version": "7",
"dialect": "postgresql",
"tables": {
@@ -31465,6 +31465,13 @@
"primaryKey": false,
"notNull": true
},
"title_needs_generation": {
"name": "title_needs_generation",
"type": "boolean",
"primaryKey": false,
"notNull": true,
"default": false
},
"description": {
"name": "description",
"type": "text",
@@ -44490,6 +44497,298 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_snapshots": {
"name": "tool_connection_app_snapshots",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"toolkit": {
"name": "toolkit",
"type": "text",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"accounts": {
"name": "accounts",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'[]'::jsonb"
},
"checked_at": {
"name": "checked_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"error_at": {
"name": "error_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
}
},
"indexes": {
"tool_connection_app_snapshots_owner_toolkit_uq": {
"name": "tool_connection_app_snapshots_owner_toolkit_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "toolkit",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_snapshots_company_id_companies_id_fk": {
"name": "tool_connection_app_snapshots_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_snapshots_company_connection_fk": {
"name": "tool_connection_app_snapshots_company_connection_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_syncs": {
"name": "tool_connection_app_syncs",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"lease_id": {
"name": "lease_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"checked": {
"name": "checked",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"total": {
"name": "total",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"failed": {
"name": "failed",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"last_completed_at": {
"name": "last_completed_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"tool_connection_app_syncs_owner_key_uq": {
"name": "tool_connection_app_syncs_owner_key_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "credential_key",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_syncs_company_id_companies_id_fk": {
"name": "tool_connection_app_syncs_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_syncs",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_syncs_company_connection_fk": {
"name": "tool_connection_app_syncs_company_connection_fk",
"tableFrom": "tool_connection_app_syncs",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_installs": {
"name": "tool_connection_installs",
"schema": "",
@@ -46202,6 +46501,27 @@
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_expiry_idx": {
"name": "tool_mcp_gateway_tokens_expiry_idx",
"columns": [
{
"expression": "expires_at",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_gateway_idx": {
"name": "tool_mcp_gateway_tokens_gateway_idx",
"columns": [
packages/db/src/migrations/meta/0291_snapshot.json → packages/db/src/migrations/meta/0297_snapshot.json
Generated
+462 -2
View File
@@ -1,6 +1,6 @@
{
"id": "a02dd1cf-75c9-4c4d-b13d-cf5dcd729ad3",
"prevId": "26315a87-4675-4dea-9634-efe5e878cc7d",
"id": "ed75c75c-748b-4420-8a68-ec5b34394e75",
"prevId": "a6c67322-9605-4234-b05d-b3585e943e42",
"version": "7",
"dialect": "postgresql",
"tables": {
@@ -12778,6 +12778,12 @@
"primaryKey": false,
"notNull": false
},
"inspection": {
"name": "inspection",
"type": "jsonb",
"primaryKey": false,
"notNull": false
},
"skill_id": {
"name": "skill_id",
"type": "uuid",
@@ -31459,6 +31465,13 @@
"primaryKey": false,
"notNull": true
},
"title_needs_generation": {
"name": "title_needs_generation",
"type": "boolean",
"primaryKey": false,
"notNull": true,
"default": false
},
"description": {
"name": "description",
"type": "text",
@@ -38905,6 +38918,140 @@
},
"isRLSEnabled": false
},
"public.resource_lifecycle_events": {
"name": "resource_lifecycle_events",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "bigint",
"primaryKey": true,
"notNull": true,
"identity": {
"type": "always",
"name": "resource_lifecycle_events_id_seq",
"schema": "public",
"increment": "1",
"startWith": "1",
"minValue": "1",
"maxValue": "9223372036854775807",
"cache": "1",
"cycle": false
}
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"resource_type": {
"name": "resource_type",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_id": {
"name": "resource_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"action": {
"name": "action",
"type": "text",
"primaryKey": false,
"notNull": true
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"resource_lifecycle_events_creation_idx": {
"name": "resource_lifecycle_events_creation_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_type",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"where": "\"resource_lifecycle_events\".\"action\" = 'create'",
"concurrently": false,
"method": "btree",
"with": {}
},
"resource_lifecycle_events_company_idx": {
"name": "resource_lifecycle_events_company_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"resource_lifecycle_events_company_id_companies_id_fk": {
"name": "resource_lifecycle_events_company_id_companies_id_fk",
"tableFrom": "resource_lifecycle_events",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {
"resource_lifecycle_events_resource_type_check": {
"name": "resource_lifecycle_events_resource_type_check",
"value": "\"resource_lifecycle_events\".\"resource_type\" IN ('agent', 'project')"
},
"resource_lifecycle_events_action_check": {
"name": "resource_lifecycle_events_action_check",
"value": "\"resource_lifecycle_events\".\"action\" = 'create' OR (\"resource_lifecycle_events\".\"resource_type\" = 'agent' AND \"resource_lifecycle_events\".\"action\" IN ('pause', 'resume', 'terminate'))"
}
},
"isRLSEnabled": false
},
"public.routine_documents": {
"name": "routine_documents",
"schema": "",
@@ -44484,6 +44631,298 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_snapshots": {
"name": "tool_connection_app_snapshots",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"toolkit": {
"name": "toolkit",
"type": "text",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"accounts": {
"name": "accounts",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'[]'::jsonb"
},
"checked_at": {
"name": "checked_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"error_at": {
"name": "error_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
}
},
"indexes": {
"tool_connection_app_snapshots_owner_toolkit_uq": {
"name": "tool_connection_app_snapshots_owner_toolkit_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "toolkit",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_snapshots_company_id_companies_id_fk": {
"name": "tool_connection_app_snapshots_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_snapshots_company_connection_fk": {
"name": "tool_connection_app_snapshots_company_connection_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_syncs": {
"name": "tool_connection_app_syncs",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"lease_id": {
"name": "lease_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"checked": {
"name": "checked",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"total": {
"name": "total",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"failed": {
"name": "failed",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"last_completed_at": {
"name": "last_completed_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"tool_connection_app_syncs_owner_key_uq": {
"name": "tool_connection_app_syncs_owner_key_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "credential_key",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_syncs_company_id_companies_id_fk": {
"name": "tool_connection_app_syncs_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_syncs",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_syncs_company_connection_fk": {
"name": "tool_connection_app_syncs_company_connection_fk",
"tableFrom": "tool_connection_app_syncs",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_installs": {
"name": "tool_connection_installs",
"schema": "",
@@ -46196,6 +46635,27 @@
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_expiry_idx": {
"name": "tool_mcp_gateway_tokens_expiry_idx",
"columns": [
{
"expression": "expires_at",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_gateway_idx": {
"name": "tool_mcp_gateway_tokens_gateway_idx",
"columns": [
packages/db/src/migrations/meta/0290_snapshot.json → packages/db/src/migrations/meta/0298_snapshot.json
Generated
+829 -2
View File
@@ -1,6 +1,6 @@
{
"id": "26315a87-4675-4dea-9634-efe5e878cc7d",
"prevId": "3960ae6b-5bf1-4fd7-91db-6a18fc7eaa19",
"id": "792dfb38-10bf-4147-a541-5c52ce0e80b6",
"prevId": "ed75c75c-748b-4420-8a68-ec5b34394e75",
"version": "7",
"dialect": "postgresql",
"tables": {
@@ -12737,6 +12737,373 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.company_skill_source_entries": {
"name": "company_skill_source_entries",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"source_id": {
"name": "source_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"path": {
"name": "path",
"type": "text",
"primaryKey": false,
"notNull": true
},
"name": {
"name": "name",
"type": "text",
"primaryKey": false,
"notNull": true
},
"description": {
"name": "description",
"type": "text",
"primaryKey": false,
"notNull": false
},
"inspection": {
"name": "inspection",
"type": "jsonb",
"primaryKey": false,
"notNull": false
},
"skill_id": {
"name": "skill_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"selection": {
"name": "selection",
"type": "text",
"primaryKey": false,
"notNull": true,
"default": "'new'"
},
"present": {
"name": "present",
"type": "boolean",
"primaryKey": false,
"notNull": true,
"default": true
},
"error": {
"name": "error",
"type": "text",
"primaryKey": false,
"notNull": false
}
},
"indexes": {
"company_skill_source_entries_source_path_idx": {
"name": "company_skill_source_entries_source_path_idx",
"columns": [
{
"expression": "source_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "path",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
},
"company_skill_source_entries_company_skill_idx": {
"name": "company_skill_source_entries_company_skill_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "skill_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"company_skill_source_entries_company_id_companies_id_fk": {
"name": "company_skill_source_entries_company_id_companies_id_fk",
"tableFrom": "company_skill_source_entries",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"company_skill_source_entries_source_id_company_skill_sources_id_fk": {
"name": "company_skill_source_entries_source_id_company_skill_sources_id_fk",
"tableFrom": "company_skill_source_entries",
"tableTo": "company_skill_sources",
"columnsFrom": [
"source_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"company_skill_source_entries_skill_id_company_skills_id_fk": {
"name": "company_skill_source_entries_skill_id_company_skills_id_fk",
"tableFrom": "company_skill_source_entries",
"tableTo": "company_skills",
"columnsFrom": [
"skill_id"
],
"columnsTo": [
"id"
],
"onDelete": "set null",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.company_skill_sources": {
"name": "company_skill_sources",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"repository_id": {
"name": "repository_id",
"type": "text",
"primaryKey": false,
"notNull": false
},
"repository_url": {
"name": "repository_url",
"type": "text",
"primaryKey": false,
"notNull": true
},
"full_name": {
"name": "full_name",
"type": "text",
"primaryKey": false,
"notNull": true
},
"tracking_ref": {
"name": "tracking_ref",
"type": "text",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"excluded_folders": {
"name": "excluded_folders",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'[]'::jsonb"
},
"enabled": {
"name": "enabled",
"type": "boolean",
"primaryKey": false,
"notNull": true,
"default": true
},
"revision": {
"name": "revision",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"last_attempt_at": {
"name": "last_attempt_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"last_success_at": {
"name": "last_success_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"last_scan_commit": {
"name": "last_scan_commit",
"type": "text",
"primaryKey": false,
"notNull": false
},
"last_error": {
"name": "last_error",
"type": "text",
"primaryKey": false,
"notNull": false
},
"lease_token": {
"name": "lease_token",
"type": "uuid",
"primaryKey": false,
"notNull": false
},
"lease_expires_at": {
"name": "lease_expires_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"company_skill_sources_repository_ref_idx": {
"name": "company_skill_sources_repository_ref_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "repository_url",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "tracking_ref",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
},
"company_skill_sources_identity_ref_idx": {
"name": "company_skill_sources_identity_ref_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "repository_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "tracking_ref",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"company_skill_sources_company_id_companies_id_fk": {
"name": "company_skill_sources_company_id_companies_id_fk",
"tableFrom": "company_skill_sources",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"company_skill_sources_connection_id_tool_connections_id_fk": {
"name": "company_skill_sources_connection_id_tool_connections_id_fk",
"tableFrom": "company_skill_sources",
"tableTo": "tool_connections",
"columnsFrom": [
"connection_id"
],
"columnsTo": [
"id"
],
"onDelete": "set null",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.company_skill_comments": {
"name": "company_skill_comments",
"schema": "",
@@ -31098,6 +31465,13 @@
"primaryKey": false,
"notNull": true
},
"title_needs_generation": {
"name": "title_needs_generation",
"type": "boolean",
"primaryKey": false,
"notNull": true,
"default": false
},
"description": {
"name": "description",
"type": "text",
@@ -38544,6 +38918,140 @@
},
"isRLSEnabled": false
},
"public.resource_lifecycle_events": {
"name": "resource_lifecycle_events",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "bigint",
"primaryKey": true,
"notNull": true,
"identity": {
"type": "always",
"name": "resource_lifecycle_events_id_seq",
"schema": "public",
"increment": "1",
"startWith": "1",
"minValue": "1",
"maxValue": "9223372036854775807",
"cache": "1",
"cycle": false
}
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"resource_type": {
"name": "resource_type",
"type": "text",
"primaryKey": false,
"notNull": true
},
"resource_id": {
"name": "resource_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"action": {
"name": "action",
"type": "text",
"primaryKey": false,
"notNull": true
},
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"resource_lifecycle_events_creation_idx": {
"name": "resource_lifecycle_events_creation_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_type",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "resource_id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"where": "\"resource_lifecycle_events\".\"action\" = 'create'",
"concurrently": false,
"method": "btree",
"with": {}
},
"resource_lifecycle_events_company_idx": {
"name": "resource_lifecycle_events_company_idx",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"resource_lifecycle_events_company_id_companies_id_fk": {
"name": "resource_lifecycle_events_company_id_companies_id_fk",
"tableFrom": "resource_lifecycle_events",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {
"resource_lifecycle_events_resource_type_check": {
"name": "resource_lifecycle_events_resource_type_check",
"value": "\"resource_lifecycle_events\".\"resource_type\" IN ('agent', 'project')"
},
"resource_lifecycle_events_action_check": {
"name": "resource_lifecycle_events_action_check",
"value": "\"resource_lifecycle_events\".\"action\" = 'create' OR (\"resource_lifecycle_events\".\"resource_type\" = 'agent' AND \"resource_lifecycle_events\".\"action\" IN ('pause', 'resume', 'terminate'))"
}
},
"isRLSEnabled": false
},
"public.routine_documents": {
"name": "routine_documents",
"schema": "",
@@ -44123,6 +44631,298 @@
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_snapshots": {
"name": "tool_connection_app_snapshots",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"toolkit": {
"name": "toolkit",
"type": "text",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"accounts": {
"name": "accounts",
"type": "jsonb",
"primaryKey": false,
"notNull": true,
"default": "'[]'::jsonb"
},
"checked_at": {
"name": "checked_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
},
"error_at": {
"name": "error_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
}
},
"indexes": {
"tool_connection_app_snapshots_owner_toolkit_uq": {
"name": "tool_connection_app_snapshots_owner_toolkit_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "toolkit",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_snapshots_company_id_companies_id_fk": {
"name": "tool_connection_app_snapshots_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_snapshots_company_connection_fk": {
"name": "tool_connection_app_snapshots_company_connection_fk",
"tableFrom": "tool_connection_app_snapshots",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_app_syncs": {
"name": "tool_connection_app_syncs",
"schema": "",
"columns": {
"id": {
"name": "id",
"type": "uuid",
"primaryKey": true,
"notNull": true,
"default": "gen_random_uuid()"
},
"company_id": {
"name": "company_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"connection_id": {
"name": "connection_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"user_id": {
"name": "user_id",
"type": "text",
"primaryKey": false,
"notNull": true
},
"credential_key": {
"name": "credential_key",
"type": "text",
"primaryKey": false,
"notNull": true
},
"lease_id": {
"name": "lease_id",
"type": "uuid",
"primaryKey": false,
"notNull": true
},
"status": {
"name": "status",
"type": "text",
"primaryKey": false,
"notNull": true
},
"checked": {
"name": "checked",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"total": {
"name": "total",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"failed": {
"name": "failed",
"type": "integer",
"primaryKey": false,
"notNull": true,
"default": 0
},
"last_completed_at": {
"name": "last_completed_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
},
"updated_at": {
"name": "updated_at",
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": true,
"default": "now()"
}
},
"indexes": {
"tool_connection_app_syncs_owner_key_uq": {
"name": "tool_connection_app_syncs_owner_key_uq",
"columns": [
{
"expression": "company_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "connection_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "user_id",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "credential_key",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": true,
"concurrently": false,
"method": "btree",
"with": {}
}
},
"foreignKeys": {
"tool_connection_app_syncs_company_id_companies_id_fk": {
"name": "tool_connection_app_syncs_company_id_companies_id_fk",
"tableFrom": "tool_connection_app_syncs",
"tableTo": "companies",
"columnsFrom": [
"company_id"
],
"columnsTo": [
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
},
"tool_connection_app_syncs_company_connection_fk": {
"name": "tool_connection_app_syncs_company_connection_fk",
"tableFrom": "tool_connection_app_syncs",
"tableTo": "tool_connections",
"columnsFrom": [
"company_id",
"connection_id"
],
"columnsTo": [
"company_id",
"id"
],
"onDelete": "cascade",
"onUpdate": "no action"
}
},
"compositePrimaryKeys": {},
"uniqueConstraints": {},
"policies": {},
"checkConstraints": {},
"isRLSEnabled": false
},
"public.tool_connection_installs": {
"name": "tool_connection_installs",
"schema": "",
@@ -44416,6 +45216,12 @@
"notNull": true,
"default": false
},
"agent_instructions": {
"name": "agent_instructions",
"type": "jsonb",
"primaryKey": false,
"notNull": false
},
"config": {
"name": "config",
"type": "jsonb",
@@ -45835,6 +46641,27 @@
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_expiry_idx": {
"name": "tool_mcp_gateway_tokens_expiry_idx",
"columns": [
{
"expression": "expires_at",
"isExpression": false,
"asc": true,
"nulls": "last"
},
{
"expression": "id",
"isExpression": false,
"asc": true,
"nulls": "last"
}
],
"isUnique": false,
"concurrently": false,
"method": "btree",
"with": {}
},
"tool_mcp_gateway_tokens_gateway_idx": {
"name": "tool_mcp_gateway_tokens_gateway_idx",
"columns": [
packages/db/src/migrations/meta/_journal.json
Generated
+28
View File
@@ -2052,6 +2052,34 @@
"when": 1790891286527,
"tag": "0294_chilly_marvel_apes",
"breakpoints": true
},
{
"idx": 295,
"version": "7",
"when": 1790994114760,
"tag": "0295_public_captain_cross",
"breakpoints": true
},
{
"idx": 296,
"version": "7",
"when": 1791028244412,
"tag": "0296_stiff_thaddeus_ross",
"breakpoints": true
},
{
"idx": 297,
"version": "7",
"when": 1791233758328,
"tag": "0297_foamy_swordsman",
"breakpoints": true
},
{
"idx": 298,
"version": "7",
"when": 1791241297512,
"tag": "0298_connection_agent_instructions",
"breakpoints": true
}
]
}
packages/db/src/schema/index.ts
+3
View File
@@ -200,6 +200,7 @@ export { pluginWebhookDeliveries } from "./plugin_webhooks.js";
export { pluginLogs } from "./plugin_logs.js";
export { runIdentityContexts } from "./run_identity_contexts.js";
export { connectionIntentDeliveries } from "./connection_intent_deliveries.js";
export { resourceLifecycleEvents } from "./resource_lifecycle_events.js";
export { toolActionDeliveries } from "./tool_action_deliveries.js";
export { chatTeamsFileTransfers } from "./chat_teams_file_transfers.js";
@@ -218,3 +219,5 @@ export { browserUseSettings, browserUseSessions, browserUseRuns, browserUseBrows
export * from "./company_skill_sources.js";
export { toolConnectionAppSnapshots } from "./tool_connection_app_snapshots.js";
export { toolConnectionAppSyncs } from "./tool_connection_app_syncs.js";
packages/db/src/schema/resource_lifecycle_events.ts
+18
View File
@@ -0,0 +1,18 @@
import { bigint, check, index, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
import { sql } from "drizzle-orm";
import { companies } from "./companies.js";
/** Content-free lifecycle journal. Consumers must revalidate the resource before provisioning. */
export const resourceLifecycleEvents = pgTable("resource_lifecycle_events", {
id: bigint("id", { mode: "number" }).primaryKey().generatedAlwaysAsIdentity(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
resourceType: text("resource_type").$type<"agent" | "project">().notNull(),
resourceId: uuid("resource_id").notNull(),
action: text("action").$type<"create" | "pause" | "resume" | "terminate">().notNull(),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
}, (table) => ({
resourceIdx: uniqueIndex("resource_lifecycle_events_creation_idx").on(table.companyId, table.resourceType, table.resourceId).where(sql`${table.action} = 'create'`),
companyIdx: index("resource_lifecycle_events_company_idx").on(table.companyId, table.id),
resourceTypeCheck: check("resource_lifecycle_events_resource_type_check", sql`${table.resourceType} IN ('agent', 'project')`),
actionCheck: check("resource_lifecycle_events_action_check", sql`${table.action} = 'create' OR (${table.resourceType} = 'agent' AND ${table.action} IN ('pause', 'resume', 'terminate'))`),
}));
packages/db/src/schema/tool_access.ts
+2
View File
@@ -16,6 +16,7 @@ import {
uuid,
} from "drizzle-orm/pg-core";
import type {
ConnectionAgentInstructions,
ConnectionTokenIssuanceOutcome,
ConnectionTokenIssuancePath,
McpConnectionCredentialRef,
@@ -129,6 +130,7 @@ export const toolConnections = pgTable(
credentialPolicy: text("credential_policy").$type<ToolConnectionCredentialPolicy>().notNull().default("shared"),
status: text("status").$type<ToolConnectionStatus>().notNull().default("draft"),
enabled: boolean("enabled").notNull().default(false),
agentInstructions: jsonb("agent_instructions").$type<ConnectionAgentInstructions>(),
config: jsonb("config").$type<Record<string, unknown>>().notNull().default({}),
transportConfig: jsonb("transport_config").$type<Record<string, unknown>>().notNull().default({}),
credentialRefs: jsonb("credential_refs").$type<McpConnectionCredentialRef[]>().notNull().default([]),
packages/db/src/schema/tool_connection_app_snapshots.ts
+21
View File
@@ -0,0 +1,21 @@
import { foreignKey, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
import type { ComposioAppAccount } from "@paperclipai/shared";
import { companies } from "./companies.js";
import { toolConnections } from "./tool_access.js";
/** Non-secret upstream account observations, scoped to the viewing human's credential. */
export const toolConnectionAppSnapshots = pgTable("tool_connection_app_snapshots", {
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
connectionId: uuid("connection_id").notNull(),
userId: text("user_id").notNull(),
credentialKey: text("credential_key").notNull(),
toolkit: text("toolkit").notNull(),
status: text("status").$type<"connected" | "not_connected">().notNull(),
accounts: jsonb("accounts").$type<ComposioAppAccount[]>().notNull().default([]),
checkedAt: timestamp("checked_at", { withTimezone: true }).notNull().defaultNow(),
errorAt: timestamp("error_at", { withTimezone: true }),
}, t => [
uniqueIndex("tool_connection_app_snapshots_owner_toolkit_uq").on(t.companyId, t.connectionId, t.userId, t.toolkit),
foreignKey({ columns: [t.companyId, t.connectionId], foreignColumns: [toolConnections.companyId, toolConnections.id], name: "tool_connection_app_snapshots_company_connection_fk" }).onDelete("cascade"),
]);
packages/db/src/schema/tool_connection_app_syncs.ts
+22
View File
@@ -0,0 +1,22 @@
import { foreignKey, integer, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
import { companies } from "./companies.js";
import { toolConnections } from "./tool_access.js";
/** One bounded discovery lease per viewing human and saved credential identity. */
export const toolConnectionAppSyncs = pgTable("tool_connection_app_syncs", {
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
connectionId: uuid("connection_id").notNull(),
userId: text("user_id").notNull(),
credentialKey: text("credential_key").notNull(),
leaseId: uuid("lease_id").notNull(),
status: text("status").$type<"syncing" | "ready" | "error" | "unsupported">().notNull(),
checked: integer("checked").notNull().default(0),
total: integer("total").notNull().default(0),
failed: integer("failed").notNull().default(0),
lastCompletedAt: timestamp("last_completed_at", { withTimezone: true }),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
}, table => [
uniqueIndex("tool_connection_app_syncs_owner_key_uq").on(table.companyId, table.connectionId, table.userId, table.credentialKey),
foreignKey({ columns: [table.companyId, table.connectionId], foreignColumns: [toolConnections.companyId, toolConnections.id], name: "tool_connection_app_syncs_company_connection_fk" }).onDelete("cascade"),
]);
packages/paperclip-runner/generated/capability/semantic-tool-contracts.json
+1 -1
View File
@@ -1 +1 @@
[{"annotations":{"exposure":"always","operationId":"get_task_context","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the active task and actor, including the exact approved Markdown revision when this issue has an accepted plan.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"get_task_context","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"get_task_history","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded comments on the active task.","inputSchema":{"additionalProperties":false,"properties":{"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":[],"type":"object"},"name":"get_task_history","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_documents","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"List revisioned documents on the active task.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"list_documents","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"read_document","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the current revision of one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"}},"required":["key"],"type":"object"},"name":"read_document","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_document_revisions","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded revision history for one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"},"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":["key"],"type":"object"},"name":"list_document_revisions","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"report_progress","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append a durable progress comment to the active task.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Multiline progress update.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"report_progress","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"answer_status_question","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append the answer to a status-only wake without changing task disposition.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Concise status answer.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"answer_status_question","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"write_document","requiredClaimLine truncated
[{"annotations":{"exposure":"always","operationId":"get_task_context","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the active task and actor, including the exact approved Markdown revision when this issue has an accepted plan.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"get_task_context","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"get_task_history","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded comments on the active task.","inputSchema":{"additionalProperties":false,"properties":{"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":[],"type":"object"},"name":"get_task_history","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_documents","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"List revisioned documents on the active task.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"list_documents","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"read_document","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the current revision of one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"}},"required":["key"],"type":"object"},"name":"read_document","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_document_revisions","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded revision history for one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"},"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":["key"],"type":"object"},"name":"list_document_revisions","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"report_progress","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append a durable progress comment to the active task.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Multiline progress update.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"report_progress","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"answer_status_question","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append the answer to a status-only wake without changing task disposition.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Concise status answer.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"answer_status_question","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"write_document","requiredClaimLine truncated
packages/paperclip-runner/generated/semantic-action-catalog.json
+14 -2
View File
@@ -1874,11 +1874,23 @@
"planning",
"skill_test"
],
"description": "Inspect available company projects before selecting a project for new work.",
"description": "List company project summaries (IDs, names, status, and up to 1,000 characters of description). Returns up to 50 projects and nextCursor; continue with cursor until it is null. Read a project's API resource for full details.",
"effect": "read",
"inputSchema": {
"additionalProperties": false,
"properties": {},
"properties": {
"cursor": {
"description": "The nextCursor returned by the previous page.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
},
"limit": {
"description": "Page size (default 50).",
"maximum": 50,
"minimum": 1,
"type": "integer"
}
},
"required": [],
"type": "object"
},
packages/paperclip-runner/package.json
+2 -2
View File
@@ -166,11 +166,11 @@
"dependencies": {
"@agentclientprotocol/claude-agent-acp": "0.73.0",
"@agentclientprotocol/codex-acp": "1.6.2",
"@openai/codex": "0.156.0",
"@openai/codex": "0.160.0",
"acpx": "0.13.1",
"ajv": "^8.20.0",
"json-schema-to-ts": "^3.1.1",
"opencode-ai": "1.18.32",
"opencode-ai": "1.18.34",
"react-markdown": "^10.1.0",
"remark-gfm": "^4.0.1",
"smol-toml": "^1.4.2"
packages/paperclip-runner/protocol/fixtures/evals/native-execution-seeded.json
+1 -1
View File
@@ -24,7 +24,7 @@
"prpVersion": 1,
"nativeExecutionVersion": 1,
"catalogVersion": 1,
"catalogSha256": "sha256:1dd4904ba9ae5c2b6bb0cbd4cfef65734d855bb5ed10ed05c70b603b8589bec3",
"catalogSha256": "sha256:d1dbdada74def03f9f1af779b6328d83e44ac35e70e4693d17ff15a9eecfebc7",
"driverContractVersion": 1,
"driverKind": "paperclip-deterministic",
"driverVersion": "1.0.0"
packages/paperclip-runner/protocol/manifest.json
+1 -1
View File
@@ -160,7 +160,7 @@
},
{
"path": "fixtures/evals/native-execution-seeded.json",
"sha256": "b4e488f922dd328a3967b2560951c2377f4c1411fb2c4c9eef7a44195a8f7514",
"sha256": "a53e3d8eae39899111ff1a0110135a9cfafdd12f7843cf6872a3de8fae915a76",
"expectation": "accept",
"compatibilityCase": "canonical"
},
packages/paperclip-runner/runner/crates/runner-core/src/acpx_provider_backend.rs
+4 -4
View File
@@ -190,7 +190,7 @@ impl AcpxProviderDescriptor {
"@agentclientprotocol/claude-agent-acp",
"0.73.0",
Some("@anthropic-ai/claude-agent-sdk"),
Some("0.3.280"),
Some("0.3.286"),
"sha256:9d73d1f0f121fb96cc8badb28c22d5bff02d8582eb2e40360a81c189e1b9422a",
),
"codex" => (
@@ -198,7 +198,7 @@ impl AcpxProviderDescriptor {
"@agentclientprotocol/codex-acp",
"1.6.2",
Some("@openai/codex"),
Some("0.156.0"),
Some("0.160.0"),
"sha256:c4538599d1ab767db5dff50934f13bb5ba313a59d9c4a83e993fac4617ea63d3",
),
"pi" => (
@@ -2330,7 +2330,7 @@ mod tests {
"@agentclientprotocol/claude-agent-acp",
"0.73.0",
json!("@anthropic-ai/claude-agent-sdk"),
json!("0.3.280"),
json!("0.3.286"),
"sha256:9d73d1f0f121fb96cc8badb28c22d5bff02d8582eb2e40360a81c189e1b9422a",
)
} else if agent == "cursor" {
@@ -2348,7 +2348,7 @@ mod tests {
"@agentclientprotocol/codex-acp",
"1.6.2",
json!("@openai/codex"),
json!("0.156.0"),
json!("0.160.0"),
"sha256:c4538599d1ab767db5dff50934f13bb5ba313a59d9c4a83e993fac4617ea63d3",
)
};
packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs
+1 -1
View File
@@ -24,7 +24,7 @@ use crate::qualified_launch::verify_launch_artifact;
use crate::question_response::validate_question_response;
pub const CODEX_APP_SERVER_MAX_FRAME_BYTES: usize = 4 * 1024 * 1024;
const QUALIFIED_OPENCODE_VERSION: &str = "1.18.32";
const QUALIFIED_OPENCODE_VERSION: &str = "1.18.34";
const DEFAULT_PROVIDER_TRACE_MAX_BYTES: usize = 64 * 1024 * 1024;
const MAX_BUFFERED_MESSAGES: usize = 1_024;
const MAX_BUFFERED_MESSAGE_BYTES: usize = 16 * 1024 * 1024;
packages/paperclip-runner/runner/crates/runner-core/src/provider_backend.rs
+2 -2
View File
@@ -4933,7 +4933,7 @@ mod tests {
CodexProviderConfig {
provider: "opencode".to_owned(),
driver: "opencode_server".to_owned(),
provider_version: "1.18.32".to_owned(),
provider_version: "1.18.34".to_owned(),
command: PathBuf::from("node"),
args: Vec::new(),
cwd: std::env::current_dir()
@@ -5295,7 +5295,7 @@ mod tests {
CodexProviderConfig {
provider: "opencode".to_owned(),
driver: "opencode_server".to_owned(),
provider_version: "1.18.32".to_owned(),
provider_version: "1.18.34".to_owned(),
command: PathBuf::from("node"),
args: Vec::new(),
cwd: std::env::current_dir()
packages/paperclip-runner/runner/crates/runner-core/tests/acpx_warm_attachment.rs
+1 -1
View File
@@ -83,7 +83,7 @@ fn checkpoints_the_sidecar_and_rebinds_consecutive_warm_runs_before_accepting_wo
"providerVersion": "0.13.1", "agent": "codex", "model": "gpt-5.6-sol",
"acpxVersion": "0.13.1", "agentServerPackage": "@agentclientprotocol/codex-acp",
"agentServerVersion": "1.6.2", "agentRuntimePackage": "@openai/codex",
"agentRuntimeVersion": "0.156.0", "commandDigest": PROFILE_DIGEST,
"agentRuntimeVersion": "0.160.0", "commandDigest": PROFILE_DIGEST,
"sidecarCommand": sidecar, "sidecarArgs": args, "runtimeDirectory": fixture.0,
"normalizedSessionId": "session-1", "runId": "run-1", "cwd": fixture.0,
"instructions": "Complete the supplied work.",
packages/paperclip-runner/runner/crates/runner-core/tests/native_provider_backend.rs
+3 -3
View File
@@ -182,7 +182,7 @@ fn prepare_payload(directory: &Path, agent: &str) -> Value {
fn prepare_payload_with_mode(directory: &Path, agent: &str, mode: &str) -> Value {
let operations = Vec::new();
let (runtime_package, runtime_version) = if agent == "codex" {
(json!("@openai/codex"), json!("0.156.0"))
(json!("@openai/codex"), json!("0.160.0"))
} else {
(Value::Null, Value::Null)
};
@@ -266,7 +266,7 @@ fn pending_acpx_runtime_request(
provider["agentServerPackage"] = json!("@agentclientprotocol/claude-agent-acp");
provider["agentServerVersion"] = json!("0.73.0");
provider["agentRuntimePackage"] = json!("@anthropic-ai/claude-agent-sdk");
provider["agentRuntimeVersion"] = json!("0.3.280");
provider["agentRuntimeVersion"] = json!("0.3.286");
provider["commandDigest"] = json!(digest);
provider["sidecarArgs"][3] = json!(digest);
} else {
@@ -800,7 +800,7 @@ fn opencode_prepare_payload(directory: &Path) -> Value {
"kind": "opencode",
"provider": "opencode",
"driver": "opencode_server",
"providerVersion": "1.18.32",
"providerVersion": "1.18.34",
"command": directory.join("qualified-opencode-proxy-command"),
"args": [directory.join("qualified-opencode-proxy-script")],
"cwd": directory,
packages/paperclip-runner/scripts/build-provider-pack.mjs
+2 -2
View File
@@ -310,8 +310,8 @@ try {
const payload = {
pins: {
nodeMinimum: minimumNodeVersion.join("."),
codex: "0.156.0",
opencode: "1.18.32",
codex: "0.160.0",
opencode: "1.18.34",
acpx: "0.13.1",
grok: "1.0.13",
claudeAcp: "0.73.0",
packages/paperclip-runner/scripts/materialize-opencode-binary.mjs
+1 -1
View File
@@ -13,7 +13,7 @@ import {
import { dirname, join, resolve } from "node:path";
import { pathToFileURL } from "node:url";
const OPENCODE_VERSION = "1.18.32";
const OPENCODE_VERSION = "1.18.34";
const BASELINE_PACKAGE = "opencode-linux-x64-baseline";
function readPackage(path) {
packages/paperclip-runner/scripts/materialize-opencode-binary.test.mjs
+6 -6
View File
@@ -35,14 +35,14 @@ async function fixture(options = {}) {
join(packageRoot, "package.json"),
JSON.stringify({
name: "opencode-ai",
version: options.packageVersion ?? "1.18.32",
version: options.packageVersion ?? "1.18.34",
}),
),
writeFile(
join(baselineRoot, "package.json"),
JSON.stringify({
name: "opencode-linux-x64-baseline",
version: options.baselineVersion ?? "1.18.32",
version: options.baselineVersion ?? "1.18.34",
}),
),
writeFile(join(packageRoot, "bin", "opencode.exe"), "sentinel\n"),
@@ -50,11 +50,11 @@ async function fixture(options = {}) {
const source = join(baselineRoot, "bin", "opencode");
if (options.symlinkSource) {
const realSource = join(root, "real-opencode");
await writeFile(realSource, "#!/bin/sh\necho 1.18.32\n");
await writeFile(realSource, "#!/bin/sh\necho 1.18.34\n");
await chmod(realSource, 0o755);
await symlink(realSource, source);
} else {
await writeFile(source, "#!/bin/sh\necho 1.18.32\n");
await writeFile(source, "#!/bin/sh\necho 1.18.34\n");
await chmod(source, 0o755);
}
return packageRoot;
@@ -67,7 +67,7 @@ test("materializes the pinned baseline executable with a verified version", asyn
platform: "linux",
architecture: "x64",
});
assert.equal(result.version, "1.18.32");
assert.equal(result.version, "1.18.34");
assert.match(result.sourceDigest, /^[0-9a-f]{64}$/);
});
@@ -80,7 +80,7 @@ test("refuses version, file-type, and platform drift", async () => {
platform: "linux",
architecture: "x64",
}),
/Expected opencode-linux-x64-baseline@1\.18\.32/,
/Expected opencode-linux-x64-baseline@1\.18\.34/,
);
const symlinkSource = await fixture({ symlinkSource: true });
packages/paperclip-runner/scripts/runner-protocol-eval-campaign.test.mjs
+1 -1
View File
@@ -34,7 +34,7 @@ async function fixture() {
provider: "opencode",
driver: "opencode_server",
model: "openrouter/example/model",
opencodeVersion: "1.18.32",
opencodeVersion: "1.18.34",
};
const evalCase = {
schema: "paperclip-runner/eval-case/v1",
packages/paperclip-runner/src/backends/codex-native-backend.ts
+1 -2
View File
@@ -72,7 +72,7 @@ function transportDriverIdentity(input: NativeExecutionInput): {
return {
kind: "opencode_server",
displayName: "OpenCode server",
version: "1.18.32",
version: "1.18.34",
};
case "claude_managed":
return {
@@ -140,7 +140,6 @@ function createTransportBackedNativeSessionBackend(
]
: []),
...nativeTaskConstraints(input),
"Return one semantic completion result.",
];
return new HarnessDriverBackend(
packages/paperclip-runner/src/backends/native-backend-factory.test.ts
+3 -3
View File
@@ -127,7 +127,7 @@ function acpxExecution(
? "@openai/codex"
: "@anthropic-ai/claude-agent-sdk",
agentRuntimeVersion:
agent === "pi" ? "0.84.2" : agent === "codex" ? "0.156.0" : "0.3.280",
agent === "pi" ? "0.84.2" : agent === "codex" ? "0.160.0" : "0.3.286",
commandDigest:
agent === "codex"
? "sha256:c4538599d1ab767db5dff50934f13bb5ba313a59d9c4a83e993fac4617ea63d3"
@@ -292,7 +292,7 @@ describe("native backend factory", () => {
await expect(backend.descriptor()).resolves.toMatchObject({
kind: "runner",
name: "opencode_server",
version: "1.18.32",
version: "1.18.34",
capabilities: {
steering: false,
resume: true,
@@ -445,7 +445,7 @@ describe("native backend factory", () => {
await expect(backend.descriptor()).resolves.toMatchObject({
kind: "runner",
name: "opencode_server",
version: "1.18.32",
version: "1.18.34",
capabilities: {
resume: true,
interruption: true,
packages/paperclip-runner/src/backends/native-backend-factory.ts
+1
View File
@@ -68,6 +68,7 @@ export function createNativeSessionBackend(
);
}
return createOpenCodeNativeSessionBackend(input, {
completionFeedback: options.completionFeedback,
runtimeDirectory: options.opencodeRuntimeDirectory,
environment: options.opencodeEnvironment,
command: options.opencodeCommand,
packages/paperclip-runner/src/backends/native-instruction-measurement.test.ts
+242
View File
@@ -0,0 +1,242 @@
import { createHash } from "node:crypto";
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync, mkdtempSync, copyFileSync, chmodSync } from "node:fs";
import { chmod, lstat, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { afterAll, describe, expect, it } from "vitest";
import { PAPERCLIP_SEMANTIC_ACTION_CATALOG } from "../catalog/semantic-action-catalog.js";
import { buildNativeModelEnvelope, parseNativeExecutionInput, type NativeExecutionInput } from "../contracts/native-execution.js";
import { NATIVE_RUNTIME_ASSET_SCHEMA, PAPERCLIP_EXECUTION_PROMPT, PAPERCLIP_EXECUTION_PROMPT_REVISION, nativeRuntimePromptDigest, canonicalNativeRuntimeContextDigest } from "../contracts/runtime-context.js";
import { PRP_BLOCK_TOOL_DESCRIPTION, PRP_COMPLETION_TOOL_DESCRIPTION } from "../contracts/completion-result.js";
import { FakeCodexTransport, WORKSPACE } from "../drivers/codex/codex-app-server-driver.test-support.js";
import { resolveQualifiedAcpxProfile } from "../drivers/acpx/qualified-profiles.js";
import { createOpenCodeNativeSessionBackend } from "./opencode-native-backend.js";
import { nativeSystemInstructions, nativeTaskConstraints } from "./runtime-context.js";
import { createRunnerdNativeSessionBackend } from "./codex-native-backend.js";
import { inspectNativeCompletionSourceMetadata } from "../../../../tests/runner-e2e/native-completion-git-source.mjs";
// This captures Paperclip's real runnerd RPC boundary with a scripted transport.
// It measures complete Paperclip-supplied instruction/tool/message projections,
// not provider-owned stock prompts, tokenization, billing or model behavior.
const tools = PAPERCLIP_SEMANTIC_ACTION_CATALOG
.filter(tool => tool.placement === "core")
.map(tool => ({ name: tool.operationId, description: tool.description, inputSchema: tool.inputSchema }));
const identity = { companyId: "company", agentId: "agent", issueId: "issue", runId: "run", sessionId: "session" };
const { qualificationModel: _qualificationModel, reportedModelId: _reportedModelId, permissionPolicy: _permissionPolicy, ...profile } = resolveQualifiedAcpxProfile("claude", "claude-sonnet-5");
const providers: NativeExecutionInput["provider"][] = [
{ kind: "codex", model: "gpt-5.6-sol", approvalPolicy: "never" },
{ kind: "acpx", agent: "claude", model: "claude-sonnet-5", permissionMode: "approve-all", profile },
{ kind: "opencode", model: "openrouter/deepseek/deepseek-v4-flash-0731", permissionMode: "allow" },
];
const receipts: unknown[] = [];
const directOpenCodeReceipts: unknown[] = [];
const sha256 = (text: string | Buffer) => createHash("sha256").update(text).digest("hex");
function execution(provider: NativeExecutionInput["provider"], schema: "v4" | "v5"): NativeExecutionInput {
const rootPath = WORKSPACE;
const entry = readFileSync(new URL("../../../../server/src/onboarding-assets/default/AGENTS.md", import.meta.url), "utf8");
writeFileSync(`${rootPath}/AGENTS.md`, entry);
const context = {
prompt: { revision: PAPERCLIP_EXECUTION_PROMPT_REVISION, text: PAPERCLIP_EXECUTION_PROMPT, digest: nativeRuntimePromptDigest() },
instructions: { entryPath: "AGENTS.md", bundle: { schema: NATIVE_RUNTIME_ASSET_SCHEMA, rootPath, digest: sha256(entry), manifestDigest: sha256(entry), fileCount: 1, totalBytes: Buffer.byteLength(entry) } },
skills: [], mcp: { assignmentSetId: "none", digest: "0".repeat(64), bindingId: null },
};
return parseNativeExecutionInput({
schema: `paperclip.native-execution-input.${schema}`,
binding: { companyId: identity.companyId, agentId: identity.agentId, issueId: identity.issueId, runId: identity.runId, executionWorkspaceId: "workspace" },
task: { identifier: "TASK-1", title: "Save the requested document", description: "Save the requested document", prompt: "Save the requested document.", workMode: "standard" },
workspace: { cwd: rootPath, repoUrl: null, repoRef: null, branchName: null },
session: { normalizedSessionId: "session", driverKind: provider.kind === "acpx" ? "acpx_runtime" : provider.kind === "opencode" ? "opencode_server" : "codex_app_server", protocolVersion: 1 },
provider,
executionMode: "default",
planningContext: null,
completionContract: { id: "contract", sha256: `sha256:${"a".repeat(64)}`, schemaVersion: "paperclip.completion-contract.v1", contract: { revision: "1", objective: "Save the requested document", criteria: [{ id: "objective", requirement: "Document saved" }] } },
interactionResponses: [], credentialBindings: [],
runtimeContext: { ...context, aggregateDigest: canonicalNativeRuntimeContextDigest(context) },
});
}
function transport(provider: NativeExecutionInput["provider"]) {
return new FakeCodexTransport("thread-1", "provider-session-1", provider.kind === "acpx" ? {
kind: "acpx", normalizedSessionId: "session", acpxRecordId: "fixture-record", backendSessionId: "fixture-backend",
agentSessionId: "fixture-agent", profileDigest: `sha256:${"a".repeat(64)}`, workspaceDigest: `sha256:${"b".repeat(64)}`,
requestedModel: provider.model, effectiveModel: provider.model, permissionMode: "approve-all",
providerLifetimeFenceCandidates: [60001, 60002, 60003],
} : undefined);
}
function measure(value: unknown) {
// Temporary fixture workspace names must not create false before/after deltas.
const json = JSON.stringify(value).replaceAll(WORKSPACE, "/workspace");
return { utf8Bytes: Buffer.byteLength(json), characters: json.length, sha256: sha256(json) };
}
describe("native instruction payload measurement", () => {
for (const provider of providers) for (const schema of ["v4", "v5"] as const) {
it(`captures ${provider.kind} ${schema} instructions and tools on start, resume and continuation`, async () => {
const input = execution(provider, schema);
const fresh = transport(provider), resumed = transport(provider), continued = transport(provider);
const backend = createRunnerdNativeSessionBackend(input, {
transportFactory: () => fresh, dynamicTools: tools,
environment: { PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
});
const session = await backend.openSession({ identity, workingDirectory: WORKSPACE });
const checkpoint = await session.snapshot();
const envelope = buildNativeModelEnvelope(input);
if ("requestedSkills" in envelope && backend.preparedTaskConstraints) envelope.constraints = [...backend.preparedTaskConstraints];
await session.startTurn({ message: { role: "user", text: JSON.stringify(envelope) } });
await session.close({ reason: "measurement" });
resumed.readResponse = { thread: { id: "thread-1", sessionId: "provider-session-1", cwd: WORKSPACE, turns: [] } };
const resumeBackend = createRunnerdNativeSessionBackend(input, {
transportFactory: () => resumed, dynamicTools: tools,
environment: { PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
});
const recovery = await resumeBackend.recoverSession!(checkpoint, { signal: new AbortController().signal });
expect(recovery.recovered).toBe(true);
await recovery.session!.startTurn({ message: { role: "user", text: JSON.stringify(envelope) } });
await recovery.session!.close({ reason: "measurement" });
continued.readResponse = resumed.readResponse;
const continuationInput = parseNativeExecutionInput({ ...input, continuationPrompt: "User update: retain the existing document and finish." });
const continuationBackend = createRunnerdNativeSessionBackend(continuationInput, {
transportFactory: () => continued, dynamicTools: tools,
environment: { PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
});
const continuationRecovery = await continuationBackend.recoverSession!(checkpoint, { signal: new AbortController().signal });
expect(continuationRecovery.recovered).toBe(true);
const continuationEnvelope = buildNativeModelEnvelope(continuationInput, { resumedSession: true });
expect(continuationEnvelope.schema).toBe("paperclip.native-continuation.v1");
await continuationRecovery.session!.startTurn({ message: { role: "user", text: JSON.stringify(continuationEnvelope) } });
await continuationRecovery.session!.close({ reason: "measurement" });
for (const [phase, captured, method] of [["start", fresh, "thread/start"], ["resume", resumed, "thread/resume"], ["continuation", continued, "thread/resume"]] as const) {
const setup = captured.calls.find(call => call.method === method)!.params;
const turn = captured.calls.find(call => call.method === "turn/start")!.params;
const instructions = setup.developerInstructions ?? setup.baseInstructions;
expect(instructions).toContain(PAPERCLIP_EXECUTION_PROMPT);
expect(instructions).toContain("You are an agent in a Paperclip company.");
const deliveredTools = setup.dynamicTools as Array<{ name: string; description: string }>;
expect(deliveredTools.filter(tool => tool.name === "paperclip_finish")).toEqual([
expect.objectContaining({ description: PRP_COMPLETION_TOOL_DESCRIPTION }),
]);
expect(deliveredTools.filter(tool => tool.name === "paperclip_block")).toEqual([
expect.objectContaining({ description: PRP_BLOCK_TOOL_DESCRIPTION }),
]);
expect(deliveredTools).toHaveLength(tools.length + 2);
if (phase === "continuation") {
expect(JSON.stringify(turn.input)).toContain("User update: retain the existing document and finish.");
const delivered = JSON.parse((turn.input as Array<{ text: string }>)[0]!.text);
expect(schema === "v4" ? JSON.parse(delivered.message) : delivered).toEqual(continuationEnvelope);
if (schema === "v5") {
expect(JSON.stringify(turn.input)).not.toContain("constraints");
expect(JSON.stringify(turn.input)).not.toContain("Document saved");
} else {
// v4's task-mode driver still wraps the compact message in its task envelope.
expect(JSON.stringify(turn.input)).toContain("Obtain one accepted result");
expect(JSON.stringify(turn.input)).toContain("Document saved");
}
expect(JSON.stringify(turn.input)).toContain("objective");
} else {
expect(JSON.stringify(turn.input)).toContain("Obtain one accepted result");
expect(JSON.stringify(turn.input)).toContain("Document saved");
expect(JSON.stringify(turn.input)).toContain("write_document");
expect(JSON.stringify(turn.input)).toContain("register_deliverable");
}
expect(setup.approvalPolicy).toBe("never");
receipts.push({ provider: provider.kind, schema, phase,
instructions: measure(instructions), tools: measure(setup.dynamicTools), input: measure(turn.input),
fullProjection: measure({ instructions, tools: setup.dynamicTools, input: turn.input }),
deliveredToolCount: deliveredTools.length,
});
}
const start = fresh.calls.find(call => call.method === "thread/start")!.params;
const resume = resumed.calls.find(call => call.method === "thread/resume")!.params;
expect(resume.dynamicTools).toEqual(start.dynamicTools);
expect(resume.developerInstructions ?? resume.baseInstructions).toEqual(start.developerInstructions ?? start.baseInstructions);
});
}
});
async function makeWritable(root: string): Promise<void> {
const info = await lstat(root).catch(() => null);
if (!info) return;
await chmod(root, info.isDirectory() ? 0o700 : 0o600);
if (info.isDirectory()) for (const child of await readdir(root)) await makeWritable(join(root, child));
}
describe("direct OpenCode HTTP instruction boundary", () => {
for (const schema of ["v4", "v5"] as const) it(`captures ${schema} start, resume and continuation with a local fake server`, async () => {
const root = mkdtempSync(join(tmpdir(), "native-direct-opencode-"));
const command = join(root, "fake-opencode-server.mjs");
copyFileSync(resolve("test/fixtures/fake-opencode-server.mjs"), command); chmodSync(command, 0o755);
const provider = providers.find(value => value.kind === "opencode")!;
const input = execution(provider, schema);
const options = { command, runtimeDirectory: root, environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-not-a-provider-key" } };
const backend = createOpenCodeNativeSessionBackend(input, options);
const session = await backend.openSession({ identity: { ...identity, sessionId: `direct-${schema}` }, workingDirectory: WORKSPACE });
try {
const checkpoint = await session.snapshot();
const send = async (current: typeof session, phase: string, value: NativeExecutionInput) => {
const envelope = buildNativeModelEnvelope(value, { resumedSession: phase === "continuation" });
if ("requestedSkills" in envelope && backend.preparedTaskConstraints) envelope.constraints = [...backend.preparedTaskConstraints];
await current.startTurn({ message: { role: "user", text: JSON.stringify(envelope) } });
for await (const event of current.events()) { if (event.eventType === "turn.completed") break; if (["turn.failed", "turn.cancelled"].includes(event.eventType)) throw new Error(`Fixture turn failed: ${event.eventType}`); }
const requests = readFileSync(join(root, `direct-${schema}`, "data", "fake-prompt-requests.ndjson"), "utf8").trim().split("\n").map(value => JSON.parse(value));
const request = requests.at(-1)!;
expect(request.providerID).toBe("openrouter"); expect(request.modelID).toBe("deepseek/deepseek-v4-flash-0731");
const text = request.parts[0].text as string;
if (schema === "v4" && phase === "start") {
expect(request.system).toBe(nativeSystemInstructions(input));
expect(JSON.parse(text).task.constraints).toEqual(nativeTaskConstraints(input));
} else {
expect(request.system).toBeUndefined();
expect(JSON.parse(text)).toEqual(envelope);
}
directOpenCodeReceipts.push({ provider: "opencode", schema, phase, request: measure(request),
instructions: request.system === undefined ? null : measure(request.system), input: measure(request.parts),
boundary: "direct OpenCode HTTP prompt_async; local scripted server, zero provider execution" });
};
await send(session, "start", input);
await session.close({ reason: "measurement" });
for (const phase of ["resume", "continuation"] as const) {
const value = phase === "continuation" ? parseNativeExecutionInput({ ...input, continuationPrompt: "User update: retain the existing document and finish." }) : input;
const next = createOpenCodeNativeSessionBackend(value, options);
const recovery = await next.recoverSession!(checkpoint, { signal: new AbortController().signal });
expect(recovery.recovered).toBe(true);
try { await send(recovery.session!, phase, value); } finally { await recovery.session!.close({ reason: "measurement" }); }
}
} finally { await session.close({ reason: "cleanup" }); await makeWritable(root); await rm(root, { recursive: true, force: true }); }
}, 30_000);
});
afterAll(() => {
const output = process.env.PAPERCLIP_NATIVE_INSTRUCTION_REPORT;
if (!output) return;
if (receipts.length !== 18 || directOpenCodeReceipts.length !== 6) throw new Error("Incomplete native instruction measurement; refusing a partial receipt");
const repositoryRoot = new URL("../../../../", import.meta.url);
const sourcePaths = ["runtime-context.ts", "codex-native-backend.ts", "opencode-native-backend.ts"].map(file => `packages/paperclip-runner/src/backends/${file}`);
sourcePaths.push("server/src/services/native-runtime/paperclip-runner-tool-authority.ts",
"server/src/services/native-runtime/native-completion-feedback.ts",
"ui/src/lib/issue-reference.ts", "ui/src/components/MarkdownBody.tsx",
"packages/paperclip-runner/src/backends/native-backend-factory.ts",
"packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts",
"packages/paperclip-runner/src/cli/opencode-app-server-proxy.ts",
"packages/paperclip-runner/src/cli/opencode-proxy-input.ts");
const source = inspectNativeCompletionSourceMetadata({ repositoryRoot: repositoryRoot.pathname,
sourceFiles: sourcePaths,
baseSha: "2a8a99e4a5f69aa803b3f10b982f583e75a87042", variant: "measurement" });
writeFileSync(output, `${JSON.stringify({
schema: "paperclip.native-instruction-measurement.v2",
sourceSha: execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim(),
sourceDirty: !source.immutable,
sourceMetadata: source.sourceMetadata,
sourceHashes: Object.fromEntries(sourcePaths.map(file => [file.split("/").at(-1)!, sha256(readFileSync(new URL(file, repositoryRoot)))])),
fixtureSha256: sha256(readFileSync(new URL(import.meta.url))),
boundary: "scripted runnerd RPC; complete Paperclip instructions, fixture core tool schemas and turn input",
providerCalls: 0, tokenCount: null, vendorStockPrompt: "unavailable", modelBehavior: "not_measured",
receipts, directOpenCodeReceipts,
}, null, 2)}\n`);
});
packages/paperclip-runner/src/backends/opencode-native-backend.ts
+1 -4
View File
@@ -14,10 +14,7 @@ export function createOpenCodeNativeSessionBackend(
throw new Error("OpenCode native backend requires a persisted OpenCode provider/model selection");
}
const preparedContext = input.schema === NATIVE_EXECUTION_INPUT_SCHEMA;
const constraints = [
...nativeTaskConstraints(input),
"Return one semantic completion result through paperclip_finish or paperclip_block.",
];
const constraints = nativeTaskConstraints(input);
return new HarnessDriverBackend(new OpenCodeServerDriver({
...options,
packages/paperclip-runner/src/backends/runtime-context.test.ts
+16 -1
View File
@@ -10,6 +10,10 @@ import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { createCodexTaskEnvelope } from "../contracts/codex.js";
import {
PRP_BLOCK_TOOL_DESCRIPTION,
PRP_COMPLETION_TOOL_DESCRIPTION,
} from "../contracts/completion-result.js";
import {
buildNativeModelEnvelope,
type NativeExecutionInput,
@@ -63,7 +67,17 @@ describe("native runtime context files", () => {
expect(constraints).toContain(
"Obtain one accepted result from paperclip_finish or paperclip_block before writing",
);
expect(constraints).toContain("do not call another tool");
expect(constraints).toContain("before writing the complete user-facing final response.");
expect(constraints).toContain("If blocked, explain why work cannot continue, name the owner and give the unblock action.");
for (const description of [PRP_COMPLETION_TOOL_DESCRIPTION, PRP_BLOCK_TOOL_DESCRIPTION]) {
expect(description).toContain("If rejected, correct the report and retry.");
expect(description).toContain("After acceptance, read the returned outcome");
expect(description).toContain("end the turn without further tool calls");
}
expect(PRP_COMPLETION_TOOL_DESCRIPTION).toContain("do not claim completion while gated");
expect(PRP_COMPLETION_TOOL_DESCRIPTION).toContain("supplied link and action");
expect(PRP_COMPLETION_TOOL_DESCRIPTION).toContain("explicit wait for the next response");
expect(PRP_BLOCK_TOOL_DESCRIPTION).toContain("its owner, and the action needed to unblock it");
expect(constraints).not.toContain(
"final response exactly once before invoking",
);
@@ -76,6 +90,7 @@ describe("native runtime context files", () => {
expect(constraints).toContain("register_deliverable");
expect(constraints).toContain("deliverable:");
expect(constraints).toContain("download link");
expect(constraints).toContain("returned documentHref as a clickable link in your final response");
});
it("marks only authoritative answered-question envelopes as resolved in the outer task", () => {
packages/paperclip-runner/src/backends/runtime-context.ts
+4 -2
View File
@@ -31,8 +31,10 @@ export function nativeSystemInstructions(input: NativeExecutionInput): string {
}
export function nativeTaskConstraints(input: NativeExecutionInput): string[] {
// Keep the discovery/ordering rule in each turn. The completion tools own
// reporting, rejection feedback, approval handling and final-response details.
const finalResponseConstraint =
"Obtain one accepted result from paperclip_finish or paperclip_block before writing the complete user-facing final response. Use paperclip_finish with yielded and a response_wake continuation only when explicitly waiting for the next response. If the tool rejects an incomplete report, correct it and retry. When it succeeds, read its outcome and explain any pending approval with the supplied link and required action. Do not claim the task is done when completion is still gated. Then write the final response exactly once and do not call another tool.";
"Obtain one accepted result from paperclip_finish or paperclip_block before writing the complete user-facing final response. Follow that tool's reporting and final-response instructions. If blocked, explain why work cannot continue, name the owner and give the unblock action.";
const answeredQuestions = Array.isArray(input.interactionResponses)
? input.interactionResponses.flatMap((response, responseIndex) => {
if (
@@ -110,7 +112,7 @@ export function nativeTaskConstraints(input: NativeExecutionInput): string[] {
: `For this turn, the editable agent instruction file is ${input.runtimeContext.instructions.workingCopy.rootPath}/${input.runtimeContext.instructions.workingCopy.entryPath}. This replaces any private working-copy path from a previous turn. Ordinary edits save after the provider stops and only with a durable revision receipt. Use the agent instruction tools for immediate saves. Shared instruction assets and repository instructions are not collected.`,
] : []),
"Use Paperclip semantic tools for coordination and finalization.",
"Save requested plans and Paperclip documents directly with write_document. A saved Paperclip document is already a durable deliverable. Do not create a local file, compute file hashes, or call register_deliverable for it unless the user also requests a downloadable file. Cite the saved document in your completion evidence and final response.",
"Save requested plans and Paperclip documents directly with write_document. A saved Paperclip document is already a durable deliverable. Do not create a local file, compute file hashes, or call register_deliverable for it unless the user also requests a downloadable file. Cite the saved document in your completion evidence and include its returned documentHref as a clickable link in your final response.",
"When the requested result is a file, use register_deliverable before paperclip_finish. Compute its exact byte size and SHA-256, register the workspace-relative file, cite deliverable:<attachmentId> from the receipt as completion evidence, and include /api/attachments/<attachmentId>/content as the download link in your answer. A bare workspace filename is not a delivered result. For repository edits, cite an accessible PR or registered work product. Preserve existing work; do not upload unrelated files. If file publication fails, fix it or report the concrete blocker instead of claiming the file is delivered.",
...(answeredQuestionConstraint ? [answeredQuestionConstraint] : []),
finalResponseConstraint,
packages/paperclip-runner/src/catalog/semantic-action-catalog.ts
+3 -2
View File
@@ -1,3 +1,4 @@
import { listProjectsDescription, listProjectsInputSchema } from "../protocol-actions/list-projects.js";
import { setTaskTitleAction } from "../protocol-actions/set-task-title.js";
import { reassignTaskAction } from "../protocol-actions/reassign-task.js";
import type {
@@ -473,9 +474,9 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
operationId: "list_projects",
title: "List projects",
requiredClaims: ["discovery:projects:read"],
description: "Inspect available company projects before selecting a project for new work.",
description: listProjectsDescription,
placement: "optional",
inputSchema: object({}),
inputSchema: listProjectsInputSchema,
}),
descriptor({
operationId: "list_project_repositories",
packages/paperclip-runner/src/cli/eval-session.ts
+3 -3
View File
@@ -192,9 +192,9 @@ export function evalSessionProviderVersion(
request: EvalSessionRequest,
): string | null {
if (request.provider === "opencode") {
const version = request.opencodeVersion ?? "1.18.32";
if (version !== "1.18.32") {
throw new Error(`OpenCode evals require exact version 1.18.32; received ${version}`);
const version = request.opencodeVersion ?? "1.18.34";
if (version !== "1.18.34") {
throw new Error(`OpenCode evals require exact version 1.18.34; received ${version}`);
}
return version;
}
packages/paperclip-runner/src/cli/opencode-app-server-proxy.ts
+21 -6
View File
@@ -17,7 +17,7 @@ import {
shouldAnnounceOpenCodeProxyTurn,
shouldForwardOpenCodeProxyItem,
} from "./opencode-proxy-events.js";
import { enqueueOpenCodeProxyInput } from "./opencode-proxy-input.js";
import { enqueueOpenCodeProxyInput, openCodeProxyCompletionFeedback } from "./opencode-proxy-input.js";
import {
assertOpenCodeProxyCollaborationMode,
openCodeProxyCollaborationModes,
@@ -40,8 +40,9 @@ type RpcMessage = {
const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
const pending = new Map<
string,
{ resolve(value: unknown): void; reject(error: Error): void }
{ resolve(value: unknown): void; reject(error: Error): void; retainEnvelope: boolean }
>();
let controllerInputClosed = false;
let nextServerRequestId = 1;
let driver: OpenCodeServerDriver | null = null;
let session: HarnessSession | null = null;
@@ -57,11 +58,12 @@ function send(value: unknown): void {
process.stdout.write(`${JSON.stringify(value)}\n`);
}
function requestController(method: string, params: unknown): Promise<unknown> {
function requestController(method: string, params: unknown, retainEnvelope = false): Promise<unknown> {
if (controllerInputClosed) return Promise.reject(new Error("OpenCode controller input is closed"));
const id = `opencode-${nextServerRequestId++}`;
send({ id, method, params });
return new Promise((resolveValue, reject) =>
pending.set(id, { resolve: resolveValue, reject }),
pending.set(id, { resolve: resolveValue, reject, retainEnvelope }),
);
}
@@ -126,6 +128,7 @@ async function open(
),
runtimeContext,
dynamicTools,
completionFeedback: openCodeProxyCompletionFeedback((method, params) => requestController(method, params, true)),
dynamicToolHandler: async (call) =>
requestController("item/tool/call", {
threadId: session?.ids().driverSessionId ?? "opening",
@@ -319,7 +322,7 @@ async function handle(message: RpcMessage): Promise<void> {
else {
const contentItems = record(message.result).contentItems;
waiter.resolve(
Array.isArray(contentItems)
!waiter.retainEnvelope && Array.isArray(contentItems)
? (contentItems[0] ?? message.result)
: message.result,
);
@@ -333,7 +336,7 @@ async function handle(message: RpcMessage): Promise<void> {
case "initialize":
result = {
user: { sessionId: "opencode" },
serverInfo: { name: "opencode", version: "1.18.32" },
serverInfo: { name: "opencode", version: "1.18.34" },
};
break;
case "thread/start":
@@ -410,6 +413,12 @@ input.on("line", (line) => {
process.stderr.write(`Invalid JSON-RPC input: ${String(error)}\n`);
return;
}
if (message.method === undefined && message.id !== undefined) {
// A command may await this bound response. Queueing the response behind
// that command would deadlock completion, interruption and shutdown.
void handle(message).catch(failProxy);
return;
}
pendingInput = enqueueOpenCodeProxyInput(
pendingInput,
async () => {
@@ -460,6 +469,12 @@ function shutdown(exitCode = 0): Promise<void> {
}
input.on("close", () => {
controllerInputClosed = true;
for (const waiter of pending.values())
waiter.reject(new Error("OpenCode controller input closed before its response"));
pending.clear();
// Preserve command order and the bootstrap drain. A queued command cannot
// create a new unanswered controller request after EOF.
void pendingInput.then(() => shutdown());
});
process.on("SIGTERM", () => {
packages/paperclip-runner/src/cli/opencode-proxy-completion.test.ts
+24
View File
@@ -0,0 +1,24 @@
import { describe, expect, it, vi } from "vitest";
import { openCodeProxyCompletionFeedback } from "./opencode-proxy-input.js";
import type { PrpStructuredRunResult } from "../protocol/replay-contract.js";
const result = { reportedWorkDisposition: "done" } as PrpStructuredRunResult;
const call = { tool: "paperclip_finish", callId: "call-finish", threadId: "thread", turnId: "turn" };
describe("OpenCode controller completion feedback", () => {
it.each(["paperclip_finish", "paperclip_block"])("preserves %s identity and exact accepted response text", async tool => {
const feedback = "Include [Saved document](/PAP/issues/PAP-1#document-plan) in your final response.";
const request = vi.fn().mockResolvedValue({ success: true, contentItems: [{ type: "inputText", text: feedback }] });
await expect(openCodeProxyCompletionFeedback(request)(result, { ...call, tool })).resolves.toBe(feedback);
expect(request).toHaveBeenCalledExactlyOnceWith("item/tool/call", { ...call, tool, arguments: result });
});
it("preserves the controller rejection for same-turn correction", async () => {
const request = vi.fn().mockResolvedValue({ success: false, contentItems: [{ type: "inputText", text: "Resolve the pending approval first." }] });
await expect(openCodeProxyCompletionFeedback(request)(result, call)).rejects.toThrow("Resolve the pending approval first.");
});
it.each([null, { accepted: true }, { success: true }, { success: true, contentItems: [{ type: "inputText", text: "" }] }, { success: true, contentItems: [{ type: "image", text: "accepted" }] }])("fails closed for malformed acceptance %j", async response => {
await expect(openCodeProxyCompletionFeedback(vi.fn().mockResolvedValue(response))(result, call)).rejects.toThrow(/Completion controller/);
});
});
packages/paperclip-runner/src/cli/opencode-proxy-input.test.ts
+85
View File
@@ -57,3 +57,88 @@ describe("OpenCode proxy input sequencing", () => {
expect(events).toEqual(["initialize failed"]);
});
});
it.each([true, false])("settles a real proxy interrupt with controller feedback or EOF (feedback: %s)", async respond => {
const { execFileSync, spawn } = await import("node:child_process");
const { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } = await import("node:fs/promises");
const { closeSync, openSync } = await import("node:fs");
const { randomUUID } = await import("node:crypto");
const { tmpdir } = await import("node:os");
const { join, resolve } = await import("node:path");
const { createInterface } = await import("node:readline");
const root = await mkdtemp(join(tmpdir(), "opencode-proxy-interrupt-feedback-"));
const launchRoot = join(root, `.paperclip-verified-executable-${randomUUID().replaceAll("-", "")}`);
await mkdir(launchRoot, { mode: 0o700 });
await chmod(launchRoot, 0o700);
const executable = join(launchRoot, "launch");
const fixture = resolve("test/fixtures/fake-opencode-server.mjs");
execFileSync("cc", ["-x", "c", "-o", executable, "-"], { input: `#include <unistd.h>\n#include <stdlib.h>\nint main(int argc, char **argv) { char **args = calloc(argc + 2, sizeof(char *)); args[0] = ${JSON.stringify(process.execPath)}; args[1] = ${JSON.stringify(fixture)}; for (int i = 1; i < argc; i++) args[i + 1] = argv[i]; execv(args[0], args); return 127; }` });
if (process.platform === "darwin") {
execFileSync("codesign", ["--force", "--sign", "-", executable]);
execFileSync("codesign", ["--verify", "--strict", executable]);
}
await chmod(executable, 0o500);
const proxy = join(root, "proxy.cjs");
await writeFile(proxy, execFileSync(process.execPath, ["--input-type=module", "-e", `import { bundleVerifiedProviderEntrypoints } from "./scripts/build-verified-provider-entrypoints.mjs"; const entries = await bundleVerifiedProviderEntrypoints({ write: false }); process.stdout.write(entries.find(({ entrypoint }) => entrypoint.name === "opencode-app-server-proxy").verifiedResult.outputFiles[0].contents);`], { maxBuffer: 16 * 1024 * 1024 }));
const fd = process.platform === "linux" ? openSync(executable, "r") : undefined;
const runtime = join(root, "runtime");
const child = spawn(process.execPath, [proxy, "--paperclip-trusted-opencode-executable", fd === undefined ? executable : "/proc/self/fd/3"], {
env: { ...process.env, PAPERCLIP_OPENCODE_RUNTIME_DIR: runtime, OPENROUTER_API_KEY: "fixture-key" },
stdio: fd === undefined ? ["pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe", fd],
detached: process.platform !== "win32",
});
if (fd !== undefined) closeSync(fd);
const messages: Array<{ id?: string | number; method?: string; params?: Record<string, unknown>; result?: unknown; error?: unknown }> = [];
const input = createInterface({ input: child.stdout! });
input.on("line", line => messages.push(JSON.parse(line)));
child.stderr!.resume();
let exited = false;
const exit = new Promise<void>(resolve => child.once("exit", () => { exited = true; resolve(); }));
const send = (message: unknown) => child.stdin!.write(`${JSON.stringify(message)}\n`);
const response = async (id: number) => {
await expect.poll(() => messages.find(message => message.id === id), { timeout: 5_000 }).toBeDefined();
const value = messages.find(message => message.id === id)!;
expect(value.error).toBeUndefined();
return value.result;
};
try {
send({ id: 1, method: "initialize", params: {} });
await response(1);
send({ id: 2, method: "thread/start", params: { cwd: root, model: "openrouter/deepseek/deepseek-v4-flash-0731", completionContract: { revision: "proxy-v1", criterionIds: ["objective"] }, conversationMode: "prepared" } });
await response(2);
send({ id: 3, method: "turn/start", params: { input: [{ type: "text", text: JSON.stringify({ schema: "paperclip.native-model-envelope.v3", task: { prompt: "completion-feedback" }, completionContract: { revision: "proxy-v1", criteria: [{ id: "objective", requirement: "Complete the fixture." }] } }) }] } });
await response(3);
await expect.poll(() => messages.find(message => message.method === "item/tool/call"), { timeout: 5_000 }).toBeDefined();
const call = messages.find(message => message.method === "item/tool/call")!;
expect(call.params!.tool).toBe("paperclip_finish");
const feedback = "Accepted. Include [Saved document](/PAP/issues/PAP-1#document-plan).";
// The interrupt is ahead of the response on stdin. Commands stay serial,
// but their awaited response must not queue behind the command itself.
send({ id: 4, method: "turn/interrupt", params: { turnId: call.params!.turnId } });
if (respond) {
send({ id: call.id, result: { success: true, contentItems: [{ type: "inputText", text: feedback }] } });
} else {
child.stdin!.end();
}
expect(await response(4)).toBe(true);
if (respond) {
const sessions = (await readdir(runtime, { withFileTypes: true })).filter(entry => entry.isDirectory());
await expect.poll(async () => JSON.parse(await readFile(join(runtime, sessions[0]!.name, "data/fake-completion-feedback.json"), "utf8"))).toMatchObject([
{ result: { content: [{ text: expect.stringContaining(feedback) }] } },
]);
child.stdin!.end();
}
await expect.poll(() => exited, { timeout: 5_000 }).toBe(true);
await exit;
expect(messages.filter(message => message.method === "paperclip/runResult")).toHaveLength(respond ? 1 : 0);
} finally {
child.kill("SIGTERM");
if (!exited) {
await Promise.race([exit, new Promise(resolve => setTimeout(resolve, 1_000))]);
if (!exited && child.pid) process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGKILL");
await exit;
}
input.close();
await rm(root, { recursive: true, force: true });
}
}, 30_000);
packages/paperclip-runner/src/cli/opencode-proxy-input.ts
+24
View File
@@ -1 +1,25 @@
export { enqueueSerialInput as enqueueOpenCodeProxyInput } from "./serial-input-queue.js";
import type { OpenCodeCompletionFeedback } from "../drivers/opencode/opencode-server-driver.js";
/** Preserve the exact call binding and the controller's acceptance/rejection. */
export function openCodeProxyCompletionFeedback(
request: (method: string, params: Record<string, unknown>) => Promise<unknown>,
): OpenCodeCompletionFeedback {
return async (result, call) => {
const response = await request("item/tool/call", { ...call, arguments: result });
if (!response || typeof response !== "object" || Array.isArray(response))
throw new Error("Completion controller returned an invalid response");
const value = response as Record<string, unknown>;
const items = Array.isArray(value.contentItems) ? value.contentItems : [];
const feedback = items.flatMap(item => {
if (!item || typeof item !== "object" || Array.isArray(item)) return [];
const entry = item as Record<string, unknown>;
return entry.type === "inputText" && typeof entry.text === "string" ? [entry.text] : [];
}).join("\n");
if (value.success === false) throw new Error(feedback || "Completion report rejected by the controller");
if (value.success !== true || !feedback.trim())
throw new Error("Completion controller omitted accepted feedback");
return feedback;
};
}
Loaded 100 of 424 files, more files were not shown because too many files have changed in this diff. Show more