mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-24 18:19:05 +02:00
Dotta
4eb32d7532
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents collaborate through discovery, delegation, dependencies, and governed approvals > - These optional operations need stable contracts before any run may discover them > - The core action contracts are already isolated in the lower stack > - This pull request adds the 13 collaboration and governance action definitions > - It does not grant claims or bind production services > - The benefit is a reviewable contract layer for later run-scoped authorization ## Linked Issues or Issue Description **Subsystem affected** packages/paperclip-runner protocol action contracts **Problem or motivation** Optional collaboration operations need one provider-neutral definition for policy metadata, documentation, live and scenario schemas, and canonical examples. **Proposed solution** Add one immutable module for each discovery, delegation, dependency, and governance action. Add a collaboration aggregate and validate all examples with JSON Schema. **Alternatives considered** These contracts could land with executable authorization. That would make contract review depend on runtime policy and server service bindings. **Roadmap alignment** This supports the existing experimental Paperclip Runner rollout. It does not make any optional operation discoverable or invocable. ## What Changed - Add 13 collaboration and governance action definitions. - Add immutable policy, schema, documentation, and example data. - Add a collaboration-only aggregate. - Validate every action example against its declared schema. ## Verification - `pnpm --filter @paperclipai/paperclip-runner test:typescript` - `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript` - `pnpm -r typecheck` - `pnpm build` - The branch changes 15 files relative to its declared base. ## Risks Low production risk. The declarations do not grant claims or contain executable service bindings. Tests require optional placement, immutable metadata, stable identities, and schema-valid examples. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, `gpt-5`, with agentic reasoning, tool use, and code execution. ## 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 linked an existing public issue or described the issue in-PR - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id - [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
290 lines
7.5 KiB
TypeScript
290 lines
7.5 KiB
TypeScript
/** Canonical definition and documentation for `create_task`. */
|
|
export const createTaskAction = {
|
|
"id": "create_task",
|
|
"canonical": {
|
|
"operationId": "create_task",
|
|
"surfaces": [
|
|
"scenario",
|
|
"live"
|
|
],
|
|
"placement": "optional_agent_tool",
|
|
"optionalGroup": "delegation_dependencies",
|
|
"requiredClaims": [
|
|
"delegation:tasks:create"
|
|
],
|
|
"taskModes": [
|
|
"standard",
|
|
"skill_test"
|
|
],
|
|
"sideEffectClass": "company_write",
|
|
"idempotency": "required",
|
|
"disabledByDefault": false,
|
|
"realBindingStatus": "live_codex",
|
|
"realServiceBinding": "issues.createChild",
|
|
"prpEvidence": "semantic-operation item event plus company-entity state diff and audit record",
|
|
"prpBindingStatus": "bound",
|
|
"legacyAliases": [
|
|
"mcp:paperclipCreateIssue"
|
|
]
|
|
},
|
|
"documentation": {
|
|
"title": "Create child task",
|
|
"description": "Create one durable standard child under the active task.",
|
|
"note": null
|
|
},
|
|
"examples": {
|
|
"call": {
|
|
"operationId": "create_task",
|
|
"input": {
|
|
"idempotencyKey": "example",
|
|
"title": "example"
|
|
}
|
|
},
|
|
"success": {
|
|
"ok": true,
|
|
"operationId": "create_task",
|
|
"result": {
|
|
"commandId": "example",
|
|
"disposition": "applied",
|
|
"stateRevision": 1,
|
|
"entityRefs": [
|
|
"example"
|
|
],
|
|
"scheduledWakeIds": [
|
|
"example"
|
|
],
|
|
"task": {
|
|
"id": "example",
|
|
"identifier": "EX-2",
|
|
"parentId": "example-parent",
|
|
"status": "todo",
|
|
"assigneeActorId": "example-agent"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"live": {
|
|
"order": 22,
|
|
"descriptor": {
|
|
"schema": "paperclip.semantic-tool.v1",
|
|
"operationId": "create_task",
|
|
"version": 1,
|
|
"title": "Create child task",
|
|
"description": "Create one durable standard child under the active task. Use only when a real ownership, parallelism, dependency, review, or lifecycle boundary justifies delegation.",
|
|
"exposure": "optional",
|
|
"requiredClaims": [
|
|
"delegation:tasks:create"
|
|
],
|
|
"allowedModes": [
|
|
"standard",
|
|
"skill_test"
|
|
],
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"idempotencyKey": {
|
|
"type": "string",
|
|
"description": "Caller-stable retry key.",
|
|
"minLength": 1,
|
|
"maxLength": 240
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Child task title.",
|
|
"minLength": 1,
|
|
"maxLength": 500
|
|
},
|
|
"description": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Child task description.",
|
|
"maxLength": 20000
|
|
},
|
|
"assigneeActorId": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Optional agent assignee. Omit to assign the current agent.",
|
|
"maxLength": 20000
|
|
},
|
|
"priority": {
|
|
"enum": [
|
|
"critical",
|
|
"high",
|
|
"medium",
|
|
"low"
|
|
]
|
|
},
|
|
"blockedByTaskIds": {
|
|
"type": "array",
|
|
"description": "Initial blocker task ids.",
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"maxItems": 200,
|
|
"uniqueItems": true
|
|
}
|
|
},
|
|
"required": [
|
|
"idempotencyKey",
|
|
"title"
|
|
],
|
|
"additionalProperties": false
|
|
},
|
|
"outputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"commandId": {
|
|
"type": "string",
|
|
"description": "Stable mock command identifier.",
|
|
"minLength": 1,
|
|
"maxLength": 200
|
|
},
|
|
"disposition": {
|
|
"enum": [
|
|
"applied",
|
|
"duplicate"
|
|
]
|
|
},
|
|
"stateRevision": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
},
|
|
"entityRefs": {
|
|
"type": "array",
|
|
"description": "Mock entities affected by the operation.",
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"maxItems": 200,
|
|
"uniqueItems": true
|
|
},
|
|
"scheduledWakeIds": {
|
|
"type": "array",
|
|
"description": "Wake identifiers scheduled by the operation.",
|
|
"items": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"maxItems": 200,
|
|
"uniqueItems": true
|
|
},
|
|
"task": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": { "type": "string", "minLength": 1 },
|
|
"identifier": { "type": ["string", "null"] },
|
|
"parentId": { "type": "string", "minLength": 1 },
|
|
"status": { "type": "string", "minLength": 1 },
|
|
"assigneeActorId": { "type": ["string", "null"] }
|
|
},
|
|
"required": ["id", "identifier", "parentId", "status", "assigneeActorId"],
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"required": [
|
|
"commandId",
|
|
"disposition",
|
|
"stateRevision",
|
|
"entityRefs",
|
|
"scheduledWakeIds",
|
|
"task"
|
|
],
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
},
|
|
"scenario": {
|
|
"order": 18,
|
|
"descriptor": {
|
|
"operationId": "create_task",
|
|
"version": 1,
|
|
"title": "Create Task",
|
|
"description": "Create Task through the Capability delegation dependencies capability set.",
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"title": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"assigneeActorId": {
|
|
"type": "string"
|
|
},
|
|
"priority": {
|
|
"type": "string"
|
|
},
|
|
"blockedByTaskIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"title"
|
|
],
|
|
"additionalProperties": false
|
|
},
|
|
"outputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"paperclip.capability.tool-result.v1"
|
|
]
|
|
},
|
|
"ok": {
|
|
"type": "boolean"
|
|
},
|
|
"operationId": {
|
|
"const": "create_task"
|
|
},
|
|
"operationResultId": {
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"value": {},
|
|
"commandResult": {},
|
|
"authorization": {}
|
|
},
|
|
"required": [
|
|
"schema",
|
|
"ok",
|
|
"operationId",
|
|
"operationResultId",
|
|
"value",
|
|
"commandResult",
|
|
"authorization"
|
|
],
|
|
"additionalProperties": false
|
|
},
|
|
"disposition": "optional_agent_tool",
|
|
"optionalGroup": "delegation_dependencies",
|
|
"requiredClaims": [
|
|
"delegation:tasks:create"
|
|
],
|
|
"taskModes": [
|
|
"standard",
|
|
"skill_test"
|
|
],
|
|
"sideEffectClass": "company_write",
|
|
"idempotency": "required",
|
|
"redaction": [],
|
|
"mockCommandMapping": {
|
|
"kind": "semantic_command",
|
|
"commandKind": "create_task"
|
|
}
|
|
}
|
|
}
|
|
} as const;
|