@plurnk/plurnk-contracts 1.8.0 → 1.9.0

package/dist/conformance/agui-v1.json

@@ -0,0 +1,541 @@
+{
+    "schemaVersion": 1,
+    "transport": [
+        {
+            "name": "comments-crlf-split-multiline",
+            "chunks": [
+                ": heartbeat\r\nid: ignored\r\ndata: {\"type\":\"CUSTOM\",\r\ndata: \"name\":\"plurnk.notice\",\"value\":{\"source\":\"engine\",\"kind\":\"fixture\",\"level\":\"info\"}}\r",
+                "\n\r\n"
+            ],
+            "eof": false,
+            "expect": {
+                "events": [
+                    {
+                        "type": "CUSTOM",
+                        "name": "plurnk.notice",
+                        "value": { "source": "engine", "kind": "fixture", "level": "info" }
+                    }
+                ]
+            }
+        },
+        {
+            "name": "split-frame-and-eof-dispatch",
+            "chunks": [
+                "data: {\"type\":\"RUN_STARTED\",\"threadId\":\"fixture\",\"runId\":\"run",
+                "\"}\n\ndata: {\"type\":\"RUN_FINISHED\",\"threadId\":\"fixture\",\"runId\":\"run\",\"outcome\":{\"type\":\"success\"}}"
+            ],
+            "eof": true,
+            "expect": {
+                "events": [
+                    { "type": "RUN_STARTED", "threadId": "fixture", "runId": "run" },
+                    {
+                        "type": "RUN_FINISHED",
+                        "threadId": "fixture",
+                        "runId": "run",
+                        "outcome": { "type": "success" }
+                    }
+                ]
+            }
+        },
+        {
+            "name": "malformed-json",
+            "chunks": ["data: not-json\n\n"],
+            "eof": false,
+            "expect": { "error": "invalid-json" }
+        },
+        {
+            "name": "cr-only-lines",
+            "chunks": [
+                ": comment\rdata: {\"type\":\"RUN_STARTED\",\"threadId\":\"fixture\",\"runId\":\"cr\"}\r\r: tail\n"
+            ],
+            "eof": false,
+            "expect": {
+                "events": [
+                    { "type": "RUN_STARTED", "threadId": "fixture", "runId": "cr" }
+                ]
+            }
+        }
+    ],
+    "lifecycles": [
+        {
+            "name": "ordinary-run",
+            "events": [
+                { "type": "RUN_STARTED", "threadId": "fixture", "runId": "run" },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.row",
+                    "value": {
+                        "id": 1,
+                        "worker_id": 7,
+                        "origin": "model",
+                        "op": "PLAN",
+                        "coordinate": "1.1.1",
+                        "tx": { "body": "Work." }
+                    }
+                },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.terminated",
+                    "value": {
+                        "workspaceId": 1,
+                        "workerId": 7,
+                        "loopId": 1,
+                        "result": { "status": 200 },
+                        "hitMaxTurns": false,
+                        "turnIds": [1],
+                        "attributions": [],
+                        "usage": {
+                            "accounting": { "requests": [], "usage": null, "costUsd": null },
+                            "curationWeight": null,
+                            "curationBudget": null,
+                            "contextTokens": null,
+                            "contextCapacity": null,
+                            "meta": {}
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "run",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": ["log/entry", "loop/terminated"],
+                "status": 200
+            }
+        },
+        {
+            "name": "action-success",
+            "events": [
+                { "type": "RUN_STARTED", "threadId": "fixture", "runId": "action" },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.action.result",
+                    "value": {
+                        "kind": "workspace.list",
+                        "ok": true,
+                        "result": { "workspaces": [] }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "action",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": [],
+                "action": { "kind": "workspace.list", "ok": true }
+            }
+        },
+        {
+            "name": "action-problem",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.action.result",
+                    "value": {
+                        "kind": "workspace.rename",
+                        "ok": false,
+                        "problem": {
+                            "type": "https://problems.plurnk.xyz/daemon/workspace/name-conflict",
+                            "title": "Name conflict",
+                            "status": 409,
+                            "detail": "The workspace name is already in use."
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "action-problem",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": [],
+                "action": { "kind": "workspace.rename", "ok": false, "status": 409 }
+            }
+        },
+        {
+            "name": "loop-injection",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.action.result",
+                    "value": {
+                        "kind": "loop.inject",
+                        "ok": true,
+                        "result": {
+                            "status": 100,
+                            "action": "injected_next_turn",
+                            "loopId": 9,
+                            "turnSeq": 2
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "inject",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": [],
+                "status": 100,
+                "action": { "kind": "loop.inject", "ok": true, "status": 100 }
+            }
+        },
+        {
+            "name": "proposal-interrupt",
+            "events": [
+                {
+                    "type": "TOOL_CALL_START",
+                    "toolCallId": "prop:42",
+                    "toolCallName": "request_approval"
+                },
+                {
+                    "type": "TOOL_CALL_ARGS",
+                    "toolCallId": "prop:42",
+                    "delta": "{\"op\":\"EDIT\",\"target\":{\"scheme\":\"file\",\"pathname\":\"example.txt\"},\"body\":\"change\",\"attrs\":{},\"flags\":{}}"
+                },
+                { "type": "TOOL_CALL_END", "toolCallId": "prop:42" },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "proposal",
+                    "outcome": {
+                        "type": "interrupt",
+                        "interrupts": [
+                            {
+                                "id": "prop:42",
+                                "reason": "tool_call",
+                                "toolCallId": "prop:42"
+                            }
+                        ]
+                    }
+                }
+            ],
+            "expect": {
+                "completion": "interrupt",
+                "families": ["loop/proposal"],
+                "interrupt": "proposal"
+            }
+        },
+        {
+            "name": "interaction-interrupt",
+            "events": [
+                {
+                    "type": "TOOL_CALL_START",
+                    "toolCallId": "int:43",
+                    "toolCallName": "request_user_input"
+                },
+                {
+                    "type": "TOOL_CALL_ARGS",
+                    "toolCallId": "int:43",
+                    "delta": "{\"question\":\"Proceed?\"}"
+                },
+                { "type": "TOOL_CALL_END", "toolCallId": "int:43" },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "interaction",
+                    "outcome": {
+                        "type": "interrupt",
+                        "interrupts": [
+                            {
+                                "id": "int:43",
+                                "reason": "tool_call",
+                                "toolCallId": "int:43",
+                                "message": "Answer the question.",
+                                "responseSchema": {
+                                    "type": "object",
+                                    "required": ["answer"],
+                                    "properties": { "answer": { "type": "string" } }
+                                }
+                            }
+                        ]
+                    }
+                }
+            ],
+            "expect": {
+                "completion": "interrupt",
+                "families": ["loop/interaction"],
+                "interrupt": "interaction"
+            }
+        },
+        {
+            "name": "reasoning-stream",
+            "events": [
+                {
+                    "type": "REASONING_START",
+                    "messageId": "model-call-11/reasoning"
+                },
+                {
+                    "type": "REASONING_MESSAGE_START",
+                    "messageId": "model-call-11/reasoning",
+                    "role": "reasoning"
+                },
+                {
+                    "type": "REASONING_MESSAGE_CONTENT",
+                    "messageId": "model-call-11/reasoning",
+                    "delta": "checked "
+                },
+                {
+                    "type": "REASONING_MESSAGE_CONTENT",
+                    "messageId": "model-call-11/reasoning",
+                    "delta": "the evidence"
+                },
+                {
+                    "type": "REASONING_MESSAGE_END",
+                    "messageId": "model-call-11/reasoning"
+                },
+                {
+                    "type": "REASONING_END",
+                    "messageId": "model-call-11/reasoning"
+                },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.terminated",
+                    "value": {
+                        "workspaceId": 1,
+                        "workerId": 7,
+                        "loopId": 1,
+                        "result": { "status": 200 },
+                        "hitMaxTurns": false,
+                        "turnIds": [1],
+                        "attributions": [],
+                        "usage": {
+                            "accounting": { "requests": [], "usage": null, "costUsd": null },
+                            "curationWeight": null,
+                            "curationBudget": null,
+                            "contextTokens": null,
+                            "contextCapacity": null,
+                            "meta": {}
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "reasoning",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": ["reasoning/event", "loop/terminated"],
+                "status": 200
+            }
+        },
+        {
+            "name": "notice-and-stream",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.notice",
+                    "value": { "source": "engine", "kind": "fixture", "level": "info" }
+                },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.stream",
+                    "value": {
+                        "entryId": 8,
+                        "workerId": 7,
+                        "target": "sh:///1/1/8",
+                        "scheme": "sh",
+                        "channel": "stdout",
+                        "state": "active",
+                        "contentLength": 4
+                    }
+                },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.stream",
+                    "value": {
+                        "entryId": 8,
+                        "workerId": 7,
+                        "target": "sh:///1/1/8",
+                        "subscriptionId": 3,
+                        "scheme": "sh",
+                        "result": { "status": 200 },
+                        "summary": "completed",
+                        "wakeAction": "no-loop"
+                    }
+                },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.terminated",
+                    "value": {
+                        "workspaceId": 1,
+                        "workerId": 7,
+                        "loopId": 1,
+                        "result": { "status": 200 },
+                        "hitMaxTurns": false,
+                        "turnIds": [1],
+                        "attributions": [],
+                        "usage": {
+                            "accounting": { "requests": [], "usage": null, "costUsd": null },
+                            "curationWeight": null,
+                            "curationBudget": null,
+                            "contextTokens": null,
+                            "contextCapacity": null,
+                            "meta": {}
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "stream",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": ["notice/event", "stream/event", "stream/concluded", "loop/terminated"],
+                "status": 200
+            }
+        },
+        {
+            "name": "problem-run",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.problem",
+                    "value": {
+                        "type": "https://problems.plurnk.xyz/fixture/conflict",
+                        "title": "Fixture conflict",
+                        "status": 409,
+                        "detail": "The fixture deliberately conflicts."
+                    }
+                },
+                {
+                    "type": "RUN_ERROR",
+                    "message": "The fixture deliberately conflicts.",
+                    "code": "https://problems.plurnk.xyz/fixture/conflict"
+                }
+            ],
+            "expect": {
+                "completion": "error",
+                "families": ["problem/event"],
+                "status": 409
+            }
+        },
+        {
+            "name": "branch-batch",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.branch_batch",
+                    "value": {
+                        "batchId": 4,
+                        "state": "completed",
+                        "completed": 2,
+                        "total": 2
+                    }
+                },
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.terminated",
+                    "value": {
+                        "workspaceId": 1,
+                        "workerId": 7,
+                        "loopId": 1,
+                        "result": { "status": 200 },
+                        "hitMaxTurns": false,
+                        "turnIds": [1],
+                        "attributions": [],
+                        "usage": {
+                            "accounting": { "requests": [], "usage": null, "costUsd": null },
+                            "curationWeight": null,
+                            "curationBudget": null,
+                            "contextTokens": null,
+                            "contextCapacity": null,
+                            "meta": {}
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "branch",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": ["workspace/branch-batch", "loop/terminated"],
+                "status": 200
+            }
+        },
+        {
+            "name": "cancelled-run",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.terminated",
+                    "value": {
+                        "workspaceId": 1,
+                        "workerId": 7,
+                        "loopId": 1,
+                        "result": {
+                            "status": 499,
+                            "problem": {
+                                "type": "https://problems.plurnk.xyz/lifecycle/cancel/loop-cancelled",
+                                "title": "Loop cancelled",
+                                "status": 499,
+                                "detail": "The loop was cancelled."
+                            }
+                        },
+                        "hitMaxTurns": false,
+                        "turnIds": [1],
+                        "attributions": [],
+                        "usage": {
+                            "accounting": { "requests": [], "usage": null, "costUsd": null },
+                            "curationWeight": null,
+                            "curationBudget": null,
+                            "contextTokens": null,
+                            "contextCapacity": null,
+                            "meta": {}
+                        }
+                    }
+                },
+                {
+                    "type": "RUN_FINISHED",
+                    "threadId": "fixture",
+                    "runId": "cancel",
+                    "outcome": { "type": "success" }
+                }
+            ],
+            "expect": {
+                "completion": "success",
+                "families": ["loop/terminated"],
+                "status": 499
+            }
+        },
+        {
+            "name": "dead-stream",
+            "events": [
+                {
+                    "type": "CUSTOM",
+                    "name": "plurnk.row",
+                    "value": { "id": 1, "worker_id": 7, "origin": "model", "op": "PLAN" }
+                }
+            ],
+            "expect": {
+                "completion": "dead-stream",
+                "families": ["log/entry"],
+                "status": 502
+            }
+        }
+    ]
+}

package/dist/schema/A2aAgentDefinition.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/A2aAgentDefinition.json",
+    "title": "A2aAgentDefinition",
+    "description": "One outbound A2A agent as the Worker Functionality coordinator persists it: the local alias, the remote base URL whose standard Agent Card is authoritative, and optional local connection facts. Secrets stay symbolic environment references.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["name", "url"],
+    "properties": {
+        "name": {
+            "description": "The local alias: the `a2a://<name>` authority.",
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "url": {
+            "description": "The remote agent's absolute HTTP(S) base URL; its Agent Card is discovered at the standard well-known path unless `cardPath` names another.",
+            "type": "string",
+            "pattern": "^https?://"
+        },
+        "cardPath": {
+            "description": "An absolute URL pathname replacing the standard Agent Card path.",
+            "type": "string",
+            "pattern": "^/[^?#]*$"
+        },
+        "headers": {
+            "description": "Extra request headers; values may be symbolic `${NAME}` environment references.",
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+        },
+        "authorization": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["type", "token"],
+            "properties": {
+                "type": { "const": "bearer" },
+                "token": {
+                    "description": "A symbolic `${NAME}` environment reference; the secret is never persisted.",
+                    "type": "string",
+                    "pattern": "^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+                }
+            }
+        }
+    }
+}

package/dist/schema/AcpPlan.json

@@ -0,0 +1,63 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/AcpPlan.json",
+    "$comment": "ACP v1 Plan, pinned to schema-v1.21.0 / 272bf799f35a258c6a4107a0410ed361e83683d3.",
+    "title": "AcpPlan",
+    "description": "The standards-facing ACP v1 execution plan.",
+    "type": "object",
+    "properties": {
+        "entries": {
+            "description": "The complete list of current plan entries.",
+            "type": "array",
+            "items": { "$ref": "#/$defs/AcpPlanEntry" }
+        },
+        "_meta": {
+            "description": "Metadata reserved by ACP. Consumers must not assume meanings for its keys.",
+            "type": ["object", "null"],
+            "additionalProperties": true
+        }
+    },
+    "required": ["entries"],
+    "$defs": {
+        "AcpPlanEntry": {
+            "description": "One task or goal in an ACP execution plan.",
+            "type": "object",
+            "properties": {
+                "content": {
+                    "description": "Human-readable description of what this task aims to accomplish.",
+                    "type": "string"
+                },
+                "priority": {
+                    "description": "The relative importance of this task.",
+                    "$ref": "#/$defs/AcpPlanEntryPriority"
+                },
+                "status": {
+                    "description": "The current execution status of this task.",
+                    "$ref": "#/$defs/AcpPlanEntryStatus"
+                },
+                "_meta": {
+                    "description": "Metadata reserved by ACP. Consumers must not assume meanings for its keys.",
+                    "type": ["object", "null"],
+                    "additionalProperties": true
+                }
+            },
+            "required": ["content", "priority", "status"]
+        },
+        "AcpPlanEntryPriority": {
+            "description": "ACP v1 priority levels.",
+            "oneOf": [
+                { "type": "string", "const": "high" },
+                { "type": "string", "const": "medium" },
+                { "type": "string", "const": "low" }
+            ]
+        },
+        "AcpPlanEntryStatus": {
+            "description": "ACP v1 plan-entry lifecycle states.",
+            "oneOf": [
+                { "type": "string", "const": "pending" },
+                { "type": "string", "const": "in_progress" },
+                { "type": "string", "const": "completed" }
+            ]
+        }
+    }
+}