@plurnk/plurnk-contracts 1.7.0 → 1.9.0

package/dist/schema/FunctionalityDefinitionState.json

@@ -0,0 +1,33 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityDefinitionState.json",
+    "title": "FunctionalityDefinitionState",
+    "description": "One managed definition as a Worker sees it: its origin, desired enabledness, and current preparation outcome. Credentials never appear.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["alias", "origin", "state"],
+    "properties": {
+        "alias": { "type": "string", "minLength": 1 },
+        "origin": { "enum": ["service", "worker"] },
+        "state": {
+            "description": "disabled: available, model-invisible. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.",
+            "enum": ["disabled", "active", "unavailable", "authorization-required"]
+        },
+        "definition": { "type": "object" },
+        "detail": {
+            "description": "Family-owned presentation facts about an active definition (a server's protocol version and tool names, an agent card summary). Never credentials, never authority.",
+            "type": "object"
+        },
+        "problem": { "$ref": "https://schemas.plurnk.xyz/v0/ProblemDetails.json" },
+        "authorization": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["url"],
+            "properties": { "url": { "type": "string", "minLength": 1 } }
+        }
+    },
+    "allOf": [
+        { "if": { "properties": { "state": { "const": "unavailable" } } }, "then": { "required": ["problem"] } },
+        { "if": { "properties": { "state": { "const": "authorization-required" } } }, "then": { "required": ["authorization"] } }
+    ]
+}

package/dist/schema/FunctionalityDiscoverQuery.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityDiscoverQuery.json",
+    "title": "FunctionalityDiscoverQuery",
+    "description": "A family-neutral discovery request: a search term or an explicit source such as a URL, path, registry reference, or package.",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "query": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "configuration": {
+            "description": "Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_MCP_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.",
+            "type": "object"
+        }
+    }
+}

package/dist/schema/FunctionalityDiscoverResult.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityDiscoverResult.json",
+    "title": "FunctionalityDiscoverResult",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["family", "candidates"],
+    "properties": {
+        "family": { "type": "string", "minLength": 1 },
+        "candidates": {
+            "type": "array",
+            "items": { "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityCandidate.json" }
+        }
+    }
+}

package/dist/schema/FunctionalityListResult.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityListResult.json",
+    "title": "FunctionalityListResult",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["family", "definitions"],
+    "properties": {
+        "family": { "type": "string", "minLength": 1 },
+        "definitions": {
+            "type": "array",
+            "items": { "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityDefinitionState.json" }
+        }
+    }
+}

package/dist/schema/FunctionalityMutationResult.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityMutationResult.json",
+    "description": "The outcome of add, enable, disable, or remove: the committed state of the one affected alias. 201 added, 200 settled, 202 awaiting a protocol continuation.",
+    "title": "FunctionalityMutationResult",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["status", "family", "alias"],
+    "properties": {
+        "status": { "type": "integer", "enum": [200, 201, 202] },
+        "family": { "type": "string", "minLength": 1 },
+        "alias": { "type": "string", "minLength": 1 },
+        "definition": { "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityDefinitionState.json" },
+        "removed": { "const": true }
+    }
+}

package/dist/schema/LineMarker.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/LineMarker.json",
+    "$id": "https://schemas.plurnk.xyz/v0/LineMarker.json",
     "title": "LineMarker",
     "description": "The ordered numeric components parsed from a `<scope>` slot. AstBuilder converts each lexical number to a JavaScript number; the operation owner assigns arity and meaning, including text coordinates, result positions, timing, mutation anchors, and an optional leading semantic threshold.",
     "type": "object",

package/dist/schema/LoopFlags.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/LoopFlags.json",
+    "$id": "https://schemas.plurnk.xyz/v0/LoopFlags.json",
     "title": "LoopFlags",
     "description": "The complete effective policy posture of one model loop. Persisted partial objects are expanded to this shape by the runtime owner before use or projection.",
     "type": "object",

package/dist/schema/MatcherBody.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/MatcherBody.json",
+    "$id": "https://schemas.plurnk.xyz/v0/MatcherBody.json",
     "title": "MatcherBody",
     "description": "Parsed body of a FIND/OPEN/FOLD statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` semantic, `@` graph, else glob). The regex variant carries pattern and flags split out of the `/pattern/flags` literal; every variant remains JSON-serializable.",
     "oneOf": [

package/dist/schema/McpConfigurationOverlay.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/McpConfigurationOverlay.json",
+    "title": "McpConfigurationOverlay",
+    "type": "object",
+    "propertyNames": {
+        "allOf": [
+            {
+                "pattern": "^PLURNK_MCP_[A-Za-z0-9_.+-]+$"
+            },
+            {
+                "not": {
+                    "enum": [
+                        "PLURNK_MCP_CONNECT_TIMEOUT",
+                        "PLURNK_MCP_REQUEST_TIMEOUT",
+                        "PLURNK_MCP_ENABLED"
+                    ]
+                }
+            }
+        ]
+    },
+    "additionalProperties": {
+        "type": "string"
+    }
+}

package/dist/schema/McpServerDefinition.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/McpServerDefinition.json",
+    "$id": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json",
     "title": "McpServerDefinition",
     "type": "object",
     "additionalProperties": false,
@@ -94,7 +94,8 @@
                         "type": { "const": "client-credentials" },
                         "clientId": { "type": "string", "minLength": 1 },
                         "clientSecret": { "$ref": "#/$defs/environmentReference" },
-                        "scope": { "type": "string", "minLength": 1 }
+                        "scope": { "type": "string", "minLength": 1 },
+                        "issuer": { "type": "string", "minLength": 1 }
                     }
                 }
             ]

package/dist/schema/McpServerOptions.json

@@ -0,0 +1,36 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/McpServerOptions.json",
+    "title": "McpServerOptions",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "args": {
+            "title": "McpServerArguments",
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/args"
+        },
+        "cwd": {
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/cwd"
+        },
+        "env": {
+            "title": "McpServerEnvironment",
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/env"
+        },
+        "headers": {
+            "title": "McpServerHeaders",
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/headers"
+        },
+        "authorization": {
+            "title": "McpServerAuthorization",
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/authorization"
+        },
+        "tools": {
+            "title": "McpServerToolNames",
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/tools"
+        },
+        "read": {
+            "title": "McpServerReadTools",
+            "$ref": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json#/properties/read"
+        }
+    }
+}

package/dist/schema/ModelCatalogPage.json

@@ -0,0 +1,122 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/ModelCatalogPage.json",
+    "title": "ModelCatalogPage",
+    "description": "One deterministic bounded page from the release-pinned model catalog.",
+    "type": "object",
+    "required": ["items", "offset", "total"],
+    "additionalProperties": false,
+    "properties": {
+        "items": {
+            "type": "array",
+            "maxItems": 100,
+            "items": {
+                "$ref": "#/$defs/model"
+            }
+        },
+        "offset": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+        },
+        "total": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+        },
+        "nextOffset": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+        }
+    },
+    "$defs": {
+        "model": {
+            "title": "ModelCatalogEntry",
+            "type": "object",
+            "required": [
+                "selector",
+                "provider",
+                "providerName",
+                "model",
+                "modelName",
+                "limits",
+                "capabilities",
+                "readiness"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "selector": {
+                    "type": "string",
+                    "minLength": 3
+                },
+                "provider": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "providerName": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "model": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "modelName": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "limits": {
+                    "$ref": "#/$defs/limits"
+                },
+                "capabilities": {
+                    "$ref": "#/$defs/capabilities"
+                },
+                "readiness": {
+                    "$ref": "https://schemas.plurnk.xyz/v0/ModelReadiness.json"
+                }
+            }
+        },
+        "limits": {
+            "title": "ModelCatalogLimits",
+            "type": "object",
+            "required": ["contextTokens"],
+            "additionalProperties": false,
+            "properties": {
+                "contextTokens": {
+                    "type": "integer",
+                    "minimum": 1
+                },
+                "inputTokens": {
+                    "type": "integer",
+                    "minimum": 1
+                },
+                "outputTokens": {
+                    "type": "integer",
+                    "minimum": 1
+                }
+            }
+        },
+        "capabilities": {
+            "title": "ModelCatalogCapabilities",
+            "type": "object",
+            "required": ["attachment", "reasoning", "toolCall", "inputModalities", "outputModalities"],
+            "additionalProperties": false,
+            "properties": {
+                "attachment": { "type": "boolean" },
+                "reasoning": { "type": "boolean" },
+                "toolCall": { "type": "boolean" },
+                "structuredOutput": { "type": "boolean" },
+                "temperature": { "type": "boolean" },
+                "inputModalities": {
+                    "type": "array",
+                    "items": { "type": "string", "minLength": 1 }
+                },
+                "outputModalities": {
+                    "type": "array",
+                    "items": { "type": "string", "minLength": 1 }
+                }
+            }
+        }
+    }
+}

package/dist/schema/ModelCatalogQuery.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/ModelCatalogQuery.json",
+    "title": "ModelCatalogQuery",
+    "description": "A bounded query over the release-pinned Models.dev catalog.",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "provider": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128
+        },
+        "search": {
+            "type": "string",
+            "maxLength": 256
+        },
+        "availability": {
+            "enum": ["configured", "all"]
+        },
+        "offset": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+        },
+        "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100
+        }
+    }
+}

package/dist/schema/ModelReadiness.json

@@ -0,0 +1,47 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/ModelReadiness.json",
+    "title": "ModelReadiness",
+    "description": "Local configuration evidence that a catalog provider is ready to attempt a request, without probing or validating credentials.",
+    "type": "object",
+    "required": ["ready", "causes"],
+    "additionalProperties": false,
+    "properties": {
+        "ready": {
+            "type": "boolean"
+        },
+        "causes": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/cause"
+            }
+        }
+    },
+    "$defs": {
+        "cause": {
+            "title": "ModelReadinessCause",
+            "type": "object",
+            "required": ["kind", "alternatives"],
+            "additionalProperties": false,
+            "properties": {
+                "kind": {
+                    "enum": ["credential", "configuration"]
+                },
+                "alternatives": {
+                    "description": "Alternative environment-variable sets. Every name in one inner array is required; satisfying any inner array resolves this cause.",
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "array",
+                        "minItems": 1,
+                        "uniqueItems": true,
+                        "items": {
+                            "type": "string",
+                            "pattern": "^[A-Z0-9_]+$"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

package/dist/schema/ModelRoute.json

@@ -0,0 +1,23 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/ModelRoute.json",
+    "title": "ModelRoute",
+    "description": "A client-visible resolved provider/model identity. Alias is present only when a declared alias supplied the route; provider configuration remains private to the daemon.",
+    "type": "object",
+    "required": ["provider", "model"],
+    "additionalProperties": false,
+    "properties": {
+        "alias": {
+            "type": "string",
+            "minLength": 1
+        },
+        "provider": {
+            "type": "string",
+            "minLength": 1
+        },
+        "model": {
+            "type": "string",
+            "minLength": 1
+        }
+    }
+}

package/dist/schema/Notice.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Notice.json",
+    "$id": "https://schemas.plurnk.xyz/v0/Notice.json",
     "title": "Notice",
     "description": "A transient, nonterminal observation for clients and the next model packet. A Notice is never operation-failure truth and cannot determine durable history, lifecycle, scheduling, or recovery. Producers use the open `source` + `kind` discriminator; clients render the producer-owned `level` without inferring semantics from kind names.",
     "type": "object",

package/dist/schema/OperationResult.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/OperationResult.json",
+    "$id": "https://schemas.plurnk.xyz/v0/OperationResult.json",
     "title": "OperationResult",
     "description": "Universal PLURNK operation result. Producer-owned metadata is open, but failures always carry one RFC 9457 Problem Details object and never a parallel error field.",
     "type": "object",
@@ -13,10 +13,10 @@
             "maximum": 599
         },
         "problem": {
-            "$ref": "https://schemas.plurnk.dev/v0/ProblemDetails.json"
+            "$ref": "https://schemas.plurnk.xyz/v0/ProblemDetails.json"
         },
         "range": {
-            "$ref": "https://schemas.plurnk.dev/v0/RangeExtent.json"
+            "$ref": "https://schemas.plurnk.xyz/v0/RangeExtent.json"
         },
         "error": false
     },

package/dist/schema/ParsedPath.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/ParsedPath.json",
+    "$id": "https://schemas.plurnk.xyz/v0/ParsedPath.json",
     "title": "ParsedPath",
     "description": "A parsed target slot from a plurnk statement. Discriminated on `kind`: a bare local path or a WHATWG-decomposed URL. Targets carry an exact address or a path glob; content matching belongs in the statement body.",
     "oneOf": [

package/dist/schema/Plan.json

@@ -0,0 +1,52 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/Plan.json",
+    "$comment": "Plurnk's model-native Plan is a bare array of ACP PlanEntry-shaped values with an additional durable-memory status. ACP projection is separately owned by AcpPlan.json.",
+    "title": "Plan",
+    "description": "Plurnk's complete model-native working-memory Plan entries.",
+    "type": "array",
+    "items": { "$ref": "#/$defs/PlanEntry" },
+    "$defs": {
+        "PlanEntry": {
+            "description": "One finding, task, or goal in the model's working-memory 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/PlanEntryPriority"
+                },
+                "status": {
+                    "description": "The current execution status of this task.",
+                    "$ref": "#/$defs/PlanEntryStatus"
+                },
+                "_meta": {
+                    "description": "Opaque entry metadata preserved through standards projection.",
+                    "type": ["object", "null"],
+                    "additionalProperties": true
+                }
+            },
+            "required": ["content", "priority", "status"]
+        },
+        "PlanEntryPriority": {
+            "description": "ACP v1 priority levels.",
+            "oneOf": [
+                { "type": "string", "const": "high" },
+                { "type": "string", "const": "medium" },
+                { "type": "string", "const": "low" }
+            ]
+        },
+        "PlanEntryStatus": {
+            "description": "ACP v1 plan-entry lifecycle states.",
+            "oneOf": [
+                { "type": "string", "const": "pending" },
+                { "type": "string", "const": "in_progress" },
+                { "type": "string", "const": "completed" },
+                { "type": "string", "const": "memory" }
+            ]
+        }
+    }
+}