refactor(runner): deliver hiring and dependency guidance at the tool boundary

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip committed 2026-10-05 09:28:35 -05:00
1 parent 64cd2194a1
commit eb01d073c3
12 files changed
+48 -21

No files matched your search

@@ -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
@@ -1277,7 +1277,7 @@
"standard",
"skill_test"
],
"description": "Create one native Paperclip Runner teammate for the current company and task. The new agent reports to you, inherits your native runtime, and receives no provider, adapter, environment, or credential configuration from the tool. Reuse an existing teammate when appropriate and follow any approval returned by the API.",
"description": "Create a persistent company teammate; provider helper threads do not create Paperclip agents. Reuse a suitable agent from list_agents first. The hire reports to you and inherits your native runtime; Paperclip supplies provider, adapter, environment and credentials. Follow any returned approval.",
"effect": "write",
"inputSchema": {
"additionalProperties": false,
@@ -1781,7 +1781,7 @@
"standard",
"skill_test"
],
"description": "Replace the active task's first-class blocker set.",
"description": "Replace the active task's blocker set. Preserve existing blocker IDs when adding a dependency. Follow the returned waiting guidance.",
"effect": "write",
"inputSchema": {
"additionalProperties": false,
@@ -1835,6 +1835,10 @@
"type": "array",
"uniqueItems": true
},
"guidance": {
"description": "Conditional next steps after recording dependencies.",
"type": "string"
},
"scheduledWakeIds": {
"description": "Wake identifiers scheduled by the operation.",
"items": {
@@ -2115,7 +2119,7 @@
"standard",
"skill_test"
],
"description": "Create an assigned task. In a conversation, create a project task with no parent; otherwise create a child of the active task. Include initialPlan to persist its plan before execution. Set status to backlog when the user wants to save or plan work without starting it; backlog tasks never wake an agent. Omitted status means todo, subject to blockers.",
"description": "Create a project task from a conversation, or a child from a task. For work or revisions assigned to a teammate, use their assigneeActorId and review their result; keep implementation with them. initialPlan is saved before execution. Use backlog to save work without waking an agent; otherwise todo is subject to blockers.",
"effect": "write",
"inputSchema": {
"additionalProperties": false,
@@ -24,7 +24,7 @@
"prpVersion": 1,
"nativeExecutionVersion": 1,
"catalogVersion": 1,
"catalogSha256": "sha256:1dd4904ba9ae5c2b6bb0cbd4cfef65734d855bb5ed10ed05c70b603b8589bec3",
"catalogSha256": "sha256:d1ba8cd54e3a1648f1b54cc942e7c8405c50133dc6aabdd27f220e8472a1ba68",
"driverContractVersion": 1,
"driverKind": "paperclip-deterministic",
"driverVersion": "1.0.0"
@@ -160,7 +160,7 @@
},
{
"path": "fixtures/evals/native-execution-seeded.json",
"sha256": "b4e488f922dd328a3967b2560951c2377f4c1411fb2c4c9eef7a44195a8f7514",
"sha256": "044d8532b9a51d5ad254618a32f2d9d39227b70110d916e1a05b8072f4ee4e22",
"expectation": "accept",
"compatibilityCase": "canonical"
},
@@ -1,5 +1,8 @@
import { setTaskTitleAction } from "../protocol-actions/set-task-title.js";
import { reassignTaskAction } from "../protocol-actions/reassign-task.js";
import { hireAgentAction } from "../protocol-actions/hire-agent.js";
import { createTaskAction } from "../protocol-actions/create-task.js";
import { setDependenciesAction } from "../protocol-actions/set-dependencies.js";
import type {
PaperclipJsonSchema,
PaperclipSemanticActionDescriptor,
@@ -336,8 +339,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
descriptor({
operationId: "hire_agent",
title: "Hire a native agent",
description:
"Create one native Paperclip Runner teammate for the current company and task. The new agent reports to you, inherits your native runtime, and receives no provider, adapter, environment, or credential configuration from the tool. Reuse an existing teammate when appropriate and follow any approval returned by the API.",
description: hireAgentAction.live.descriptor.description,
placement: "optional",
effect: "write",
requiredClaims: ["delegation:agents:create"],
@@ -455,7 +457,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
descriptor({
operationId: "set_dependencies",
title: "Set task dependencies",
description: "Replace the active task's first-class blocker set.",
description: setDependenciesAction.live.descriptor.description,
placement: "optional",
effect: "write",
requiredClaims: ["dependencies:write"],
@@ -467,7 +469,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
},
["idempotencyKey", "blockedByTaskIds"],
),
outputSchema: operationReceipt,
outputSchema: setDependenciesAction.live.descriptor.outputSchema,
}),
descriptor({
operationId: "list_projects",
@@ -506,7 +508,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
descriptor({
operationId: "create_task",
title: "Create task",
description: "Create an assigned task. In a conversation, create a project task with no parent; otherwise create a child of the active task. Include initialPlan to persist its plan before execution. Set status to backlog when the user wants to save or plan work without starting it; backlog tasks never wake an agent. Omitted status means todo, subject to blockers.",
description: createTaskAction.live.descriptor.description,
placement: "optional",
effect: "write",
requiredClaims: ["delegation:tasks:create"],
@@ -1,8 +1,8 @@
import { createHash } from "node:crypto";
export const NATIVE_RUNTIME_ASSET_SCHEMA = "paperclip.runtime-asset.v1" as const;
export const PAPERCLIP_EXECUTION_PROMPT_REVISION = "paperclip-execution.v5" as const;
export const PAPERCLIP_EXECUTION_PROMPT = "You are running as a Paperclip agent. Complete the assigned task in the provided execution environment. Follow the attached agent instructions and use assigned skills and tools when relevant. Use Paperclip tools for coordination. To hire or reuse a persistent teammate, use list_agents, then search_api for agent-hires and call_api if a hire is needed. Provider helper threads do not create Paperclip agents. When the user assigns work or a revision to a teammate, use create_task with that agent's ID; review their result rather than doing their assigned work yourself. When remaining work depends on a child task, use set_dependencies to add its ID while preserving existing blocker IDs. Complete independent work, then call paperclip_block with the child agent as owner and child completion as the unblock action. End the turn so the child can use the workspace. Do not sleep or poll for child results while holding the workspace. Paperclip resumes the parent when the dependency completes. When the user asks to connect a service, call connections_search before any service tool, even when that tool is already installed. Follow the returned instruction and wait for any required user choice before executing. For other tasks needing a service, use installed tools if available; otherwise use connections_search and follow its instruction. The request appears as a card in the task. Finish independent work before yielding for access; do not poll or request the same connection repeatedly. Paperclip will continue automatically with updated tools after resolution. After a decline, pursue alternatives unless the user explicitly asks to retry. Finish exactly once with `paperclip_finish` or `paperclip_block`." as const;
export const PAPERCLIP_EXECUTION_PROMPT_REVISION = "paperclip-execution.v6" as const;
export const PAPERCLIP_EXECUTION_PROMPT = "You are running as a Paperclip agent. Complete the assigned task in the provided execution environment. Follow the attached agent instructions and use assigned skills and tools when relevant. Use Paperclip company tools for coordination, persistent teammates and assigned work. Record task dependencies before waiting for delegated results; follow the dependency tool's returned guidance. When the user asks to connect a service, call connections_search before any service tool, even when that tool is already installed. Follow the returned instruction and wait for any required user choice before executing. For other tasks needing a service, use installed tools if available; otherwise use connections_search and follow its instruction. The request appears as a card in the task. Finish independent work before yielding for access; do not poll or request the same connection repeatedly. Paperclip will continue automatically with updated tools after resolution. After a decline, pursue alternatives unless the user explicitly asks to retry. Finish exactly once with `paperclip_finish` or `paperclip_block`." as const;
export interface NativeRuntimeAssetReference {
schema: typeof NATIVE_RUNTIME_ASSET_SCHEMA;
@@ -29,7 +29,7 @@ export const createTaskAction = {
},
"documentation": {
"title": "Create task",
"description": "Create a project task from a conversation, or a child from an ordinary task. Persist initialPlan before execution. Set status to backlog when the user wants to save or plan work without starting it; backlog tasks never wake an agent. Omitted status means todo, subject to blockers.",
"description": "Create a project task from a conversation, or a child from a task. For work or revisions assigned to a teammate, use their assigneeActorId and review their result; keep implementation with them. initialPlan is saved before execution. Use backlog to save work without waking an agent; otherwise todo is subject to blockers.",
"note": null
},
"examples": {
@@ -77,7 +77,7 @@ export const createTaskAction = {
"operationId": "create_task",
"version": 1,
"title": "Create task",
"description": "Create a project task from a conversation, or a child from an ordinary task. Persist initialPlan before execution. Set status to backlog when the user wants to save or plan work without starting it; backlog tasks never wake an agent. Omitted status means todo, subject to blockers.",
"description": "Create a project task from a conversation, or a child from a task. For work or revisions assigned to a teammate, use their assigneeActorId and review their result; keep implementation with them. initialPlan is saved before execution. Use backlog to save work without waking an agent; otherwise todo is subject to blockers.",
"exposure": "optional",
"requiredClaims": [
"delegation:tasks:create"
@@ -19,7 +19,7 @@ export const hireAgentAction = {
},
documentation: {
title: "Hire a native agent",
description: "Create a persistent native Runner teammate with an identity and persona. The teammate reports to the caller and inherits the caller's native runtime; provider, adapter, environment, and credential settings are selected by Paperclip and are never caller-supplied here.",
description: "Create a persistent company teammate; provider helper threads do not create Paperclip agents. Reuse a suitable agent from list_agents first. The hire reports to you and inherits your native runtime; Paperclip supplies provider, adapter, environment and credentials. Follow any returned approval.",
note: "Use list_agents first when a suitable teammate may already exist.",
},
examples: {
@@ -40,7 +40,7 @@ export const hireAgentAction = {
operationId: "hire_agent",
version: 1,
title: "Hire a native agent",
description: "Create a persistent native Runner teammate with an identity and persona. The teammate reports to the caller and inherits the caller's native runtime; provider, adapter, environment, and credential settings are selected by Paperclip and are never caller-supplied here. Reuse a suitable teammate from list_agents when possible.",
description: "Create a persistent company teammate; provider helper threads do not create Paperclip agents. Reuse a suitable agent from list_agents first. The hire reports to you and inherits your native runtime; Paperclip supplies provider, adapter, environment and credentials. Follow any returned approval.",
exposure: "optional",
requiredClaims: ["delegation:agents:create"],
allowedModes: ["standard", "skill_test"],
@@ -27,7 +27,7 @@ export const setDependenciesAction = {
},
"documentation": {
"title": "Set task dependencies",
"description": "Replace the active task's first-class blocker set.",
"description": "Replace the active task's blocker set. Preserve existing blocker IDs when adding a dependency. Follow the returned waiting guidance.",
"note": null
},
"examples": {
@@ -72,7 +72,7 @@ export const setDependenciesAction = {
"operationId": "set_dependencies",
"version": 1,
"title": "Set task dependencies",
"description": "Replace the active task's first-class blocker set.",
"description": "Replace the active task's blocker set. Preserve existing blocker IDs when adding a dependency. Follow the returned waiting guidance.",
"exposure": "optional",
"requiredClaims": [
"dependencies:write"
@@ -136,6 +136,10 @@ export const setDependenciesAction = {
"maxItems": 200,
"uniqueItems": true
},
"guidance": {
"type": "string",
"description": "Conditional next steps after recording dependencies."
},
"scheduledWakeIds": {
"type": "array",
"description": "Wake identifiers scheduled by the operation.",
@@ -23,7 +23,7 @@ export function nativeToolContractFingerprintForTarget(
return `sha256:${createHash("sha256")
.update(
JSON.stringify({
schema: "paperclip.native-tool-contract.v14",
schema: "paperclip.native-tool-contract.v15",
executionTargetKind,
advertisementPolicy: {
// Direct provider threads retain declarations from thread/start.
@@ -37,6 +37,7 @@ export function nativeToolContractFingerprintForTarget(
structuredHumanInput:
"always_advertised_run_issue_agent_binding_gated_current_task_description.v2",
semanticCompletion: "finish_accessible_deliverable_evidence.v4",
nativeProcedures: "hiring_delegation_and_dependency_result_guidance.v1",
connectorTools: "assigned_resources_and_pinned_skill_bundle.v1",
...(executionTargetKind === "remote"
? { assignedMcpTools: "codex_server_gateway_prp_relay.v1" }
@@ -1035,7 +1035,7 @@ describe("PaperclipRunnerToolAuthority", () => {
blockedBy: [],
});
await authority.execute({
const dependencyReceipt = await authority.execute({
tool: "set_dependencies",
callId: "wait-for-prerequisite",
arguments: {
@@ -1043,6 +1043,12 @@ describe("PaperclipRunnerToolAuthority", () => {
blockedByTaskIds: [prerequisiteId],
},
});
expect(dependencyReceipt).toMatchObject({ guidance: expect.stringContaining("If remaining work depends on an unfinished child") });
expect(dependencyReceipt).toMatchObject({ guidance: expect.stringContaining("do not sleep or poll") });
await expect(authority.execute({
tool: "set_dependencies", callId: "wait-for-prerequisite-replay",
arguments: { idempotencyKey: "source-waits-for-prerequisite", blockedByTaskIds: [prerequisiteId] },
})).resolves.toEqual(dependencyReceipt);
await expect(
issueService(db).getRelationSummaries(issueId),
).resolves.toMatchObject({
@@ -1070,6 +1076,13 @@ describe("PaperclipRunnerToolAuthority", () => {
});
expect(wakes).toHaveLength(2);
const cleared = await authority.execute({
tool: "set_dependencies", callId: "clear-finished-prerequisite",
arguments: { idempotencyKey: "clear-finished-prerequisite", blockedByTaskIds: [] },
});
expect(cleared).not.toHaveProperty("guidance");
await expect(issueService(db).getRelationSummaries(issueId)).resolves.toMatchObject({ blockedBy: [] });
const nextRunId = "00000000-0000-4000-8000-000000000106";
await db
.update(heartbeatRuns)
@@ -1339,6 +1339,9 @@ export class PaperclipRunnerToolAuthority {
stateRevision: updated.statusVersion,
entityRefs: [updated.id, ...blockedByIssueIds],
scheduledWakeIds: [],
...(blockedByIssueIds.length > 0 ? {
guidance: "If remaining work depends on an unfinished child, complete independent work, then call paperclip_block with the child agent as owner and child completion as the unblock action. End the turn to release the workspace; do not sleep or poll for the child. Paperclip resumes the parent when the dependency completes. If no work remains blocked, continue normally.",
} : {}),
};
});
}