0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-08 11:13:44 +02:00

Files

T

DottaandPaperclip 7944ed3d97 fix(runner): preserve hire runtime safety and first-activity timing (#13852 )

## Thinking Path

> - Paperclip is the open source control plane for companies of AI
agents.
> - Native runner agents need governed tools, durable runtime state, and
useful execution evidence.
> - A first activity trace waited 53.467 seconds even though tool
activity took 6.274 seconds; provider input arrived before the server
API call executed.
> - Native agents also need a safe way to hire teammates without asking
the model to rebuild runtime configuration.
> - This pull request separates the observed ACP input-stream window
from the actual server `tool.execute` span and adds a server-owned
native hire contract.
> - The benefit is clearer latency evidence and safer native teammates
with existing approval, auth, and company boundaries preserved.

## Linked Issues or Issue Description

Related Daytona provenance work is in
[#13814](https://github.com/paperclipai/paperclip/pull/13814). No
duplicate public PR was found for this combined timing and native-hire
change.

**What existing behavior does this improve?**

Native runner agents can use governed tools and request hires. The
server did not expose a safe native hire operation that reused the
caller's validated runtime settings. First-activity traces also mixed
provider input timing with server tool execution timing.

**Current behavior**

A native hire must construct a separate runner configuration. Full
configuration copying could expose paths, instructions, secrets, or
sessions. Timing evidence could make a provider or MCP identity join
appear proven when the trace did not contain that join.

**Proposed behavior**

The native `hire_agent` operation accepts identity and persona inputs.
The server sends `adapterType: "paperclip_runner"` with
`inheritRuntimeFrom: "caller"`, then copies only validated provider,
model, permission, lifecycle, and bounded execution settings. It
inherits and validates the default environment, derives the managed AI
binding through existing normalization, preserves approval and
permissions, and creates fresh child instructions. Caller secrets,
paths, prompts, and sessions are excluded.

Provider events now include the optional boolean `inputUpdated`, with
Rust forwarding support. Timing evidence separately records the ACP
input-stream window and the actual server `tool.execute` activity. It
does not claim a provider or MCP join without matching evidence.

**Reason and benefit**

Native agents can hire teammates that start with the caller's approved
execution policy. Operators retain company boundaries, auth rules,
approval gates, and requalification. Reviewers can distinguish provider
streaming time from server API execution time when diagnosing
first-activity delays.

**Breaking changes**

None for existing hires or tool calls. `inheritRuntimeFrom` is optional
and only applies to same-company native agent callers. Conflicting
explicit runtime settings are rejected. The provider event field is
optional for existing producers.

## What Changed

- Added the native `hire_agent` protocol action, catalog entry, API
contract, and runner authority checks.
- Added `inheritRuntimeFrom: "caller"` validation and a closed native
runtime inheritance allowlist.
- Preserved managed AI binding normalization, default-environment
validation, approval snapshots, permissions, requalification, and fresh
child instructions.
- Added provider `inputUpdated` schema support and Rust forwarding.
- Added first-activity and server tool timing evidence with conservative
identity-join handling.
- Added route, authority, provider-event, sidecar, API, catalog, and
Rust-focused tests.
- Kept private Honeycomb links, raw traces, and local result paths out
of this description.

## Verification

Focused checks passed:

- 458 timing/session checks.
- 61 native hire inheritance checks.
- 20 hire authority checks.
- 1,741 API checks.
- 106 catalog checks.
- 54 provider sidecar checks.
- 12 Rust provider checks.

Live R2 and R3 each passed 45 checks across 6 runs (361,135 ms for R2).
R1 stopped at missing Docker image setup. The final trace is available
at
https://ui.honeycomb.io/paperclip/environments/test/datasets/paperclip/result/BiMypLNvmiB?tab=traces.
Latest-head CI passed all required build, typecheck, Rust, static,
Vitest, serialized-server, workspace, chat, and E2E jobs. The focused
local checks listed above passed; the broad local suite was not run
before the live evaluation, while CI provides the full repository
verification.

## Risks

- Timing fields describe separate observed windows. They do not prove a
provider or MCP owner without a valid trace join.
- The inheritance allowlist must stay synchronized with native runner
configuration fields.
- Approval snapshots include resolved safe inherited settings and should
be reviewed when native configuration fields change.
- The focused local suite is narrower than the full repository suite;
latest-head CI covers the broader repository checks.

> Roadmap review: `ROADMAP.md` places this work within Paperclip's
bring-your-own-agent direction. It extends existing native runner hiring
and observability behavior.

## Model Used

OpenAI GPT-6 (exact serving model ID is not exposed), with extended
reasoning and repository tool use; GPT-5.6 Luna assisted with focused
implementation and verification work.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-09-22 23:16:11 -05:00

29 KiB

Raw Blame History

Capability Capability Contract

This generated contract is a self-contained derivative of the Paperclip skill, its seven references, the Paperclip Evals corpus, and the legacy MCP tool surface. It does not import or contact the Paperclip control plane.

The skill/reference inventory and eval cases are the only normative behavior sources. Paperclip does not use the legacy MCP calls as a production capability surface; all MCP names below are traceability aliases folded into normative eval rows. Their disposition, grants, assertions, and evidence contract are inherited from the target row rather than classified independently.

Baseline Counts

Skill/reference headings: 155
Eval cases: 106 across 16 groups
Total normative rows: 261
Legacy MCP aliases folded into normative rows: 42

Eval group	Cases
hb	5
co	6
st	8
cm	6
se	4
su	4
bl	5
dp	3
ix	9
ap	6
ar	4
er	9
rf	22
mh	4
rs	3
wk	8

Regeneration

pnpm --dir packages/paperclip-runner generate:capability-inventory imports the canonical baselines and rewrites every generated file.
pnpm --dir packages/paperclip-runner check:capability-inventory validates counts, uniqueness, normative dispositions, one-to-one MCP folds, required fields, and generated-file drift without requiring the external eval repository.

Skill / Reference Rows

Legacy MCP Alias Index

This is a compatibility/traceability index, not a tool catalog. “Inherited disposition” is shown only to make the normative target easy to audit.

Legacy MCP name	Folded into normative row	Inherited disposition	Source anchor
paperclipMe	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:290
paperclipInboxLite	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:296
paperclipListAgents	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:302
paperclipListSkills	eval:rf-cskill-audit-01	optional_agent_tool	packages/mcp-server/src/tools.ts:308
paperclipGetAgent	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:314
paperclipListIssues	eval:se-q-filters-01	optional_agent_tool	packages/mcp-server/src/tools.ts:323
paperclipGetIssue	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:338
paperclipGetHeartbeatContext	eval:hb-context-01	control_plane_owned	packages/mcp-server/src/tools.ts:344
paperclipListComments	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:353
paperclipGetComment	eval:hb-wake-comment-01	control_plane_owned	packages/mcp-server/src/tools.ts:366
paperclipListIssueApprovals	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:373
paperclipListDocuments	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:379
paperclipGetDocument	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:385
paperclipListDocumentRevisions	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:392
paperclipListProjects	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:402
paperclipGetProject	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:408
paperclipGetIssueWorkspaceRuntime	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:417
paperclipControlIssueWorkspaceServices	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:423
paperclipWaitForIssueWorkspaceService	eval:rf-iws-target-restart-01	optional_agent_tool	packages/mcp-server/src/tools.ts:440
paperclipListGoals	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:466
paperclipGetGoal	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:472
paperclipListApprovals	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:478
paperclipCreateApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:487
paperclipGetApproval	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:496
paperclipGetApprovalIssues	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:502
paperclipListApprovalComments	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:508
paperclipCreateIssue	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:514
paperclipUpdateIssue	eval:st-done-comment-01	always_agent_tool	packages/mcp-server/src/tools.ts:521
paperclipCheckoutIssue	eval:co-body-contract-01	control_plane_owned	packages/mcp-server/src/tools.ts:528
paperclipReleaseIssue	eval:er-release-01	control_plane_owned	packages/mcp-server/src/tools.ts:540
paperclipAddComment	eval:cm-multiline-01	always_agent_tool	packages/mcp-server/src/tools.ts:546
paperclipSuggestTasks	eval:ix-suggest-tasks-01	always_agent_tool	packages/mcp-server/src/tools.ts:553
paperclipAskUserQuestions	eval:ix-questions-01	always_agent_tool	packages/mcp-server/src/tools.ts:565
paperclipRequestConfirmation	eval:ix-confirmation-plan-01	always_agent_tool	packages/mcp-server/src/tools.ts:577
paperclipRequestCheckboxConfirmation	eval:ix-checkbox-01	always_agent_tool	packages/mcp-server/src/tools.ts:589
paperclipUpsertIssueDocument	eval:dp-plan-doc-01	always_agent_tool	packages/mcp-server/src/tools.ts:601
paperclipRestoreIssueDocumentRevision	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:612
paperclipLinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:627
paperclipUnlinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:636
paperclipApprovalDecision	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:646
paperclipAddApprovalComment	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:668
paperclipApiRequest	eval:rf-api-404-report-01	optional_agent_tool	packages/mcp-server/src/tools.ts:677

Capability	Primary disposition	Source anchor
skill:skills/paperclip/SKILL.md:paperclip-skill:10	optional_agent_tool	skills/paperclip/SKILL.md:10
skill:skills/paperclip/SKILL.md:terminology:14	optional_agent_tool	skills/paperclip/SKILL.md:14
skill:skills/paperclip/SKILL.md:authentication:18	control_plane_owned	skills/paperclip/SKILL.md:18
skill:skills/paperclip/SKILL.md:conversation-tasks:30	optional_agent_tool	skills/paperclip/SKILL.md:30
skill:skills/paperclip/SKILL.md:server-verified-external-chat-turns:47	control_plane_owned	skills/paperclip/SKILL.md:47
skill:skills/paperclip/SKILL.md:the-heartbeat-procedure:87	optional_agent_tool	skills/paperclip/SKILL.md:87
skill:skills/paperclip/SKILL.md:generated-artifacts-and-work-products:159	always_agent_tool	skills/paperclip/SKILL.md:159
skill:skills/paperclip/SKILL.md:status-quick-guide:207	control_plane_owned	skills/paperclip/SKILL.md:207
skill:skills/paperclip/SKILL.md:monitors-and-watchers-say-only-what-you-actually-scheduled:217	optional_agent_tool	skills/paperclip/SKILL.md:217
skill:skills/paperclip/SKILL.md:delegating-review-tasks:230	always_agent_tool	skills/paperclip/SKILL.md:230
skill:skills/paperclip/SKILL.md:managing-a-user-s-inbox:241	control_plane_owned	skills/paperclip/SKILL.md:241
skill:skills/paperclip/SKILL.md:issue-dependencies-blockers:249	control_plane_owned	skills/paperclip/SKILL.md:249
skill:skills/paperclip/SKILL.md:requesting-board-approval:274	optional_agent_tool	skills/paperclip/SKILL.md:274
skill:skills/paperclip/SKILL.md:issue-thread-interactions:295	optional_agent_tool	skills/paperclip/SKILL.md:295
skill:skills/paperclip/SKILL.md:standalone-decisions:324	optional_agent_tool	skills/paperclip/SKILL.md:324
skill:skills/paperclip/SKILL.md:mcp-tool-approval-gates:428	optional_agent_tool	skills/paperclip/SKILL.md:428
skill:skills/paperclip/SKILL.md:niche-workflow-pointers:470	optional_agent_tool	skills/paperclip/SKILL.md:470
skill:skills/paperclip/SKILL.md:cases:480	optional_agent_tool	skills/paperclip/SKILL.md:480
skill:skills/paperclip/SKILL.md:company-skills-workflow:485	optional_agent_tool	skills/paperclip/SKILL.md:485
skill:skills/paperclip/SKILL.md:routines:496	optional_agent_tool	skills/paperclip/SKILL.md:496
skill:skills/paperclip/SKILL.md:issue-workspace-runtime-controls:507	optional_agent_tool	skills/paperclip/SKILL.md:507
skill:skills/paperclip/SKILL.md:proposing-credentials-safely:514	optional_agent_tool	skills/paperclip/SKILL.md:514
skill:skills/paperclip/SKILL.md:reading-granted-secrets:521	optional_agent_tool	skills/paperclip/SKILL.md:521
skill:skills/paperclip/SKILL.md:critical-rules:547	optional_agent_tool	skills/paperclip/SKILL.md:547
skill:skills/paperclip/SKILL.md:comment-style-required:571	always_agent_tool	skills/paperclip/SKILL.md:571
skill:skills/paperclip/SKILL.md:update:603	optional_agent_tool	skills/paperclip/SKILL.md:603
skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:613	optional_agent_tool	skills/paperclip/SKILL.md:613
skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:646	optional_agent_tool	skills/paperclip/SKILL.md:646
skill:skills/paperclip/SKILL.md:searching-issues:675	optional_agent_tool	skills/paperclip/SKILL.md:675
skill:skills/paperclip/SKILL.md:full-reference:685	optional_agent_tool	skills/paperclip/SKILL.md:685
skill:skills/paperclip/references/artifacts.md:generated-artifacts-and-work-products:1	always_agent_tool	skills/paperclip/references/artifacts.md:1
skill:skills/paperclip/references/artifacts.md:workspace-only-file-references:15	optional_agent_tool	skills/paperclip/references/artifacts.md:15
skill:skills/paperclip/references/cases.md:cases:1	optional_agent_tool	skills/paperclip/references/cases.md:1
skill:skills/paperclip/references/cases.md:core-model:12	optional_agent_tool	skills/paperclip/references/cases.md:12
skill:skills/paperclip/references/cases.md:upsert-semantics:29	optional_agent_tool	skills/paperclip/references/cases.md:29
skill:skills/paperclip/references/cases.md:read-and-search:67	optional_agent_tool	skills/paperclip/references/cases.md:67
skill:skills/paperclip/references/cases.md:documents:90	always_agent_tool	skills/paperclip/references/cases.md:90
skill:skills/paperclip/references/cases.md:fields:118	optional_agent_tool	skills/paperclip/references/cases.md:118
skill:skills/paperclip/references/cases.md:issue-links:151	optional_agent_tool	skills/paperclip/references/cases.md:151
skill:skills/paperclip/references/cases.md:child-cases:176	optional_agent_tool	skills/paperclip/references/cases.md:176

29 KiB Raw Blame History