PaperClipAI/packages/paperclip-runner/protocol/schemas/provider-event.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json",
  "title": "Provider-neutral runner activity payload",
  "oneOf": [
    { "$ref": "#/$defs/plan" },
    { "$ref": "#/$defs/planProposal" },
    { "$ref": "#/$defs/toolExecution" },
    { "$ref": "#/$defs/research" },
    { "$ref": "#/$defs/delegation" },
    { "$ref": "#/$defs/modelRoute" },
    { "$ref": "#/$defs/modelVerification" },
    { "$ref": "#/$defs/contextCompacted" },
    { "$ref": "#/$defs/artifactViewed" },
    { "$ref": "#/$defs/artifactGenerated" },
    { "$ref": "#/$defs/reviewMode" },
    { "$ref": "#/$defs/hook" },
    { "$ref": "#/$defs/memoryCitation" },
    { "$ref": "#/$defs/safetyReview" },
    { "$ref": "#/$defs/terminalInput" },
    { "$ref": "#/$defs/wait" },
    { "$ref": "#/$defs/providerNotice" }
  ],
  "$defs": {
    "id": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
    "shortText": { "type": "string", "maxLength": 4000 },
    "nullableShortText": { "type": ["string", "null"], "maxLength": 4000 },
    "safePath": { "type": ["string", "null"], "maxLength": 4096, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).*$" },
    "safeUrl": { "type": ["string", "null"], "maxLength": 8192, "pattern": "^https?://" },
    "plan": {
      "type": "object",
      "description": "A complete provider-authored within-turn checklist snapshot. Consumers replace the prior snapshot with the same planId in PRP sourceSeq order; this is not Paperclip's durable Plan document.",
      "required": ["schema", "planId", "revision", "steps", "complete", "syncStatus"],
      "properties": {
        "schema": { "const": "paperclip.plan.updated.v1" },
        "planId": { "$ref": "#/$defs/id" },
        "revision": { "type": "integer", "minimum": 1 },
        "explanation": { "$ref": "#/$defs/nullableShortText" },
        "steps": { "type": "array", "maxItems": 256, "items": { "type": "object", "required": ["stepId", "body", "status"], "properties": { "stepId": { "$ref": "#/$defs/id" }, "body": { "$ref": "#/$defs/shortText" }, "status": { "enum": ["pending", "in_progress", "completed", "blocked"] } }, "additionalProperties": false } },
        "complete": { "type": "boolean" },
        "syncStatus": { "description": "Legacy compatibility field. Within-turn checklist snapshots use not_applicable.", "enum": ["streaming", "pending", "synchronized", "conflict", "not_applicable"] },
        "documentRevision": { "description": "Legacy compatibility field. Within-turn checklist snapshots use null.", "type": ["integer", "null"], "minimum": 1 }
      },
      "additionalProperties": false
    },
    "planProposal": {
      "type": "object",
      "description": "A provider-authored proposed plan document awaiting human approval (Codex plan item, Claude ExitPlanMode). Paperclip may synchronize a completed proposal into the issue's durable Plan document; it is distinct from the within-turn plan.updated checklist.",
      "required": ["schema", "proposalId", "status", "markdown", "source"],
      "properties": {
        "schema": { "const": "paperclip.plan.proposed.v1" },
        "proposalId": { "$ref": "#/$defs/id" },
        "status": { "enum": ["streaming", "completed"] },
        "markdown": { "type": "string", "maxLength": 60000 },
        "source": { "enum": ["codex_plan_item", "claude_exit_plan_mode"] }
      },
      "additionalProperties": false
    },
    "toolExecution": {
      "type": "object",
      "required": ["schema", "executionId", "transport", "operation", "status", "output", "outputBytes", "outputTruncated", "outputDigest"],
      "properties": {
        "schema": { "const": "paperclip.tool.execution.v1" },
        "executionId": { "$ref": "#/$defs/id" },
        "transport": { "enum": ["process", "mcp", "dynamic", "builtin"] },
        "operation": { "enum": ["read", "search", "list", "execute", "edit", "unknown"] },
        "name": { "$ref": "#/$defs/nullableShortText" },
        "target": { "$ref": "#/$defs/safePath" },
        "namespace": { "type": ["string", "null"], "maxLength": 240 },
        "readOnly": { "type": ["boolean", "null"] },
        "inputUpdated": { "type": "boolean" },
        "status": { "enum": ["running", "completed", "failed", "cancelled", "interrupted"] },
        "durationMs": { "type": ["integer", "null"], "minimum": 0 },
        "exitCode": { "type": ["integer", "null"] },
        "progress": { "$ref": "#/$defs/nullableShortText" },
        "subject": { "$ref": "#/$defs/nullableShortText" },
        "description": { "$ref": "#/$defs/nullableShortText" },
        "blockedReason": { "$ref": "#/$defs/nullableShortText" },
        "output": { "type": ["string", "null"], "maxLength": 65536 },
        "outputBytes": { "type": "integer", "minimum": 0 },
        "outputTruncated": { "type": "boolean" },
        "outputDigest": { "type": ["string", "null"], "pattern": "^sha256:[a-f0-9]{64}$" },
        "parentItemId": { "anyOf": [{ "$ref": "#/$defs/id" }, { "type": "null" }] },
        "fileChanges": {
          "description": "Files changed by this one edit call, each with a bounded patch. Paths are workspace-relative.",
          "type": "array",
          "maxItems": 32,
          "items": {
            "type": "object",
            "required": ["path", "operation", "previousPath", "additions", "deletions", "diff", "diffTruncated"],
            "properties": {
              "path": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$" },
              "operation": { "enum": ["create", "modify", "delete", "rename"] },
              "previousPath": { "$ref": "#/$defs/safePath" },
              "additions": { "type": "integer", "minimum": 0 },
              "deletions": { "type": "integer", "minimum": 0 },
              "diff": { "type": ["string", "null"], "maxLength": 32768 },
              "diffTruncated": { "type": "boolean" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "research": {
      "type": "object",
      "required": ["schema", "researchId", "action", "status", "sources"],
      "properties": {
        "schema": { "const": "paperclip.research.v1" },
        "researchId": { "$ref": "#/$defs/id" },
        "action": { "enum": ["search", "open_page", "find_in_page", "other"] },
        "status": { "enum": ["running", "completed", "failed", "cancelled"] },
        "query": { "$ref": "#/$defs/nullableShortText" },
        "url": { "$ref": "#/$defs/safeUrl" },
        "pattern": { "$ref": "#/$defs/nullableShortText" },
        "sources": { "type": "array", "maxItems": 64, "items": { "type": "object", "required": ["sourceId", "title", "url", "snippet"], "properties": { "sourceId": { "$ref": "#/$defs/id" }, "title": { "$ref": "#/$defs/shortText" }, "url": { "$ref": "#/$defs/safeUrl" }, "snippet": { "$ref": "#/$defs/nullableShortText" } }, "additionalProperties": false } }
      },
      "additionalProperties": false
    },
    "delegation": {
      "type": "object",
      "required": ["schema", "delegationId", "action", "status", "children"],
      "properties": {
        "schema": { "const": "paperclip.delegation.v1" },
        "delegationId": { "$ref": "#/$defs/id" },
        "action": { "enum": ["spawn", "message", "resume", "wait", "close"] },
        "status": { "enum": ["running", "waiting", "completed", "failed", "interrupted", "closed"] },
        "children": { "type": "array", "maxItems": 64, "items": { "type": "object", "required": ["childId", "role", "model", "status", "summary", "activitySummary"], "properties": { "childId": { "$ref": "#/$defs/id" }, "role": { "type": ["string", "null"], "maxLength": 160 }, "model": { "type": ["string", "null"], "maxLength": 240 }, "status": { "enum": ["running", "waiting", "completed", "failed", "interrupted", "closed"] }, "summary": { "$ref": "#/$defs/nullableShortText" }, "activitySummary": { "$ref": "#/$defs/nullableShortText" }, "prompt": { "$ref": "#/$defs/nullableShortText" }, "result": { "$ref": "#/$defs/nullableShortText" } }, "additionalProperties": false } }
      },
      "additionalProperties": false
    },
    "modelRoute": {
      "type": "object",
      "required": ["schema", "routeId", "provider", "requestedModel", "fromModel", "effectiveModel", "reason"],
      "properties": { "schema": { "const": "paperclip.model.route_changed.v1" }, "routeId": { "$ref": "#/$defs/id" }, "provider": { "type": "string", "minLength": 1, "maxLength": 160 }, "requestedModel": { "type": "string", "minLength": 1, "maxLength": 240 }, "fromModel": { "type": ["string", "null"], "maxLength": 240 }, "effectiveModel": { "type": "string", "minLength": 1, "maxLength": 240 }, "reason": { "$ref": "#/$defs/shortText" } },
      "additionalProperties": false
    },
    "modelVerification": {
      "type": "object",
      "required": ["schema", "verificationId", "status", "classes", "buffering", "summary"],
      "properties": { "schema": { "const": "paperclip.model.verification.v1" }, "verificationId": { "$ref": "#/$defs/id" }, "status": { "enum": ["running", "completed", "failed"] }, "classes": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 160 } }, "buffering": { "type": "boolean" }, "summary": { "$ref": "#/$defs/nullableShortText" } },
      "additionalProperties": false
    },
    "contextCompacted": {
      "type": "object",
      "required": ["schema", "compactionId", "reason", "preTokens", "postTokens", "sameSession"],
      "properties": { "schema": { "const": "paperclip.context.compacted.v1" }, "compactionId": { "$ref": "#/$defs/id" }, "reason": { "enum": ["context_window", "manual", "provider", "unknown"] }, "preTokens": { "type": ["integer", "null"], "minimum": 0 }, "postTokens": { "type": ["integer", "null"], "minimum": 0 }, "sameSession": { "type": "boolean" } },
      "additionalProperties": false
    },
    "artifactViewed": {
      "type": "object",
      "required": ["schema", "artifactId", "reference", "mediaType", "title"],
      "properties": { "schema": { "const": "paperclip.artifact.viewed.v1" }, "artifactId": { "$ref": "#/$defs/id" }, "reference": { "$ref": "#/$defs/safePath" }, "mediaType": { "type": ["string", "null"], "maxLength": 160 }, "title": { "$ref": "#/$defs/nullableShortText" } },
      "additionalProperties": false
    },
    "artifactGenerated": {
      "type": "object",
      "required": ["schema", "artifactId", "status", "reference", "mediaType", "registered", "failure"],
      "properties": { "schema": { "const": "paperclip.artifact.generated.v1" }, "artifactId": { "$ref": "#/$defs/id" }, "status": { "enum": ["running", "completed", "failed"] }, "reference": { "$ref": "#/$defs/safePath" }, "mediaType": { "type": ["string", "null"], "maxLength": 160 }, "registered": { "type": "boolean" }, "transparentBackground": { "type": ["boolean", "null"] }, "failure": { "$ref": "#/$defs/nullableShortText" } },
      "additionalProperties": false
    },
    "reviewMode": {
      "type": "object",
      "required": ["schema", "reviewId", "state", "scope"],
      "properties": { "schema": { "const": "paperclip.review.mode_changed.v1" }, "reviewId": { "$ref": "#/$defs/id" }, "state": { "enum": ["entered", "exited"] }, "scope": { "$ref": "#/$defs/nullableShortText" } },
      "additionalProperties": false
    },
    "hook": {
      "type": "object",
      "required": ["schema", "hookId", "event", "scope", "status", "blocking", "durationMs", "summary"],
      "properties": { "schema": { "const": "paperclip.hook.v1" }, "hookId": { "$ref": "#/$defs/id" }, "event": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "enum": ["running", "completed", "failed", "cancelled", "blocked", "stopped"] }, "blocking": { "type": "boolean" }, "durationMs": { "type": ["integer", "null"], "minimum": 0 }, "summary": { "$ref": "#/$defs/nullableShortText" }, "outcome": { "enum": ["running", "passed", "context", "feedback", "blocked", "stopped", "failed"] }, "message": { "$ref": "#/$defs/nullableShortText" }, "source": { "type": ["string", "null"], "maxLength": 160 }, "toolName": { "type": ["string", "null"], "maxLength": 160 } },
      "additionalProperties": false
    },
    "memoryCitation": {
      "type": "object",
      "required": ["schema", "citationId", "messageItemId", "label", "available", "reference"],
      "properties": { "schema": { "const": "paperclip.memory.citation.v1" }, "citationId": { "$ref": "#/$defs/id" }, "messageItemId": { "$ref": "#/$defs/id" }, "label": { "$ref": "#/$defs/shortText" }, "available": { "type": "boolean" }, "reference": { "type": ["string", "null"], "maxLength": 4096 } },
      "additionalProperties": false
    },
    "safetyReview": {
      "type": "object",
      "required": ["schema", "reviewId", "targetExecutionId", "status", "decision", "summary"],
      "properties": { "schema": { "const": "paperclip.safety.review.v1" }, "reviewId": { "$ref": "#/$defs/id" }, "targetExecutionId": { "anyOf": [{ "$ref": "#/$defs/id" }, { "type": "null" }] }, "status": { "enum": ["running", "completed", "failed"] }, "decision": { "enum": ["pending", "allowed", "denied", "user_required", "timed_out", "aborted", "unknown"] }, "summary": { "$ref": "#/$defs/nullableShortText" }, "actionKind": { "enum": ["command", "execve", "writeStdin", "applyPatch", "networkAccess", "mcpToolCall", "requestPermissions", "unknown"] }, "action": { "type": ["string", "null"], "maxLength": 1000 }, "riskLevel": { "enum": ["low", "medium", "high", "critical", null] }, "userConsent": { "enum": ["unknown", "low", "medium", "high", null] }, "rationale": { "$ref": "#/$defs/nullableShortText" }, "decidedBy": { "type": ["string", "null"], "maxLength": 160 } },
      "additionalProperties": false
    },
    "terminalInput": {
      "type": "object",
      "required": ["schema", "executionId", "origin", "inputClass", "byteCount"],
      "properties": { "schema": { "const": "paperclip.terminal.input_sent.v1" }, "executionId": { "$ref": "#/$defs/id" }, "origin": { "enum": ["agent", "user", "system"] }, "inputClass": { "enum": ["text", "control", "eof"] }, "byteCount": { "type": "integer", "minimum": 0 } },
      "additionalProperties": false
    },
    "wait": {
      "type": "object",
      "required": ["schema", "waitId", "reason", "status", "plannedDurationMs", "elapsedDurationMs"],
      "properties": { "schema": { "const": "paperclip.wait.v1" }, "waitId": { "$ref": "#/$defs/id" }, "reason": { "enum": ["timer", "provider", "rate_limit", "unknown"] }, "status": { "enum": ["running", "completed", "interrupted", "cancelled"] }, "plannedDurationMs": { "type": ["integer", "null"], "minimum": 0 }, "elapsedDurationMs": { "type": ["integer", "null"], "minimum": 0 } },
      "additionalProperties": false
    },
    "providerNotice": {
      "type": "object",
      "required": ["schema", "noticeId", "severity", "category", "scope", "recoverable", "userActionable", "summary"],
      "properties": { "schema": { "const": "paperclip.provider.notice.v1" }, "noticeId": { "$ref": "#/$defs/id" }, "severity": { "enum": ["info", "warning", "error"] }, "category": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "enum": ["turn", "session", "environment", "account"] }, "recoverable": { "type": "boolean" }, "userActionable": { "type": "boolean" }, "summary": { "$ref": "#/$defs/shortText" }, "provenance": {"type":"object","required":["method","eventType","sessionId","turnId"],"properties":{"method":{"type":"string","maxLength":160},"eventType":{"type":"string","maxLength":160},"sessionId":{"type":"string","maxLength":240},"turnId":{"type":"string","maxLength":240},"agentId":{"type":"string","maxLength":240},"timestamp":{"type":"string","maxLength":80}},"additionalProperties":false}, "details": {"type":"array","maxItems":64,"items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","minLength":1,"maxLength":160},"value":{"type":"string","maxLength":4000}},"additionalProperties":false}} },
      "additionalProperties": false
    }
  }
}