@plurnk/plurnk-contracts 1.6.1 → 1.8.0

package/dist/schema/ClientStatement.json

@@ -15,6 +15,9 @@
                 { "type": "null" }
             ]
         },
+        "AnnotationOrNull": {
+            "type": ["string", "null"]
+        },
         "PathOrNull": {
             "oneOf": [
                 { "$ref": "https://schemas.plurnk.dev/v0/ParsedPath.json" },
@@ -44,11 +47,12 @@
         },
         "LookStatement": {
             "type": "object",
-            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "required": ["op", "delimiter", "annotation", "signal", "target", "lineMarker", "body", "position"],
             "additionalProperties": false,
             "properties": {
                 "op": { "const": "LOOK" },
-                "suffix": { "type": "string" },
+                "delimiter": { "type": "string" },
+                "annotation": { "$ref": "#/$defs/AnnotationOrNull" },
                 "signal": { "$ref": "#/$defs/TagSignal" },
                 "target": { "$ref": "#/$defs/PathOrNull" },
                 "lineMarker": { "$ref": "#/$defs/TextLineMarkerOrNull" },
@@ -58,11 +62,12 @@
         },
         "BuffStatement": {
             "type": "object",
-            "required": ["op", "suffix", "signal", "target", "lineMarker", "body", "position"],
+            "required": ["op", "delimiter", "annotation", "signal", "target", "lineMarker", "body", "position"],
             "additionalProperties": false,
             "properties": {
                 "op": { "const": "BUFF" },
-                "suffix": { "type": "string" },
+                "delimiter": { "type": "string" },
+                "annotation": { "$ref": "#/$defs/AnnotationOrNull" },
                 "signal": { "$ref": "#/$defs/TagSignal" },
                 "target": { "$ref": "#/$defs/PathOrNull" },
                 "lineMarker": { "$ref": "#/$defs/LineMarkerOrNull" },

package/dist/schema/McpConfigurationOverlay.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/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

@@ -0,0 +1,155 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/McpServerDefinition.json",
+    "title": "McpServerDefinition",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["name", "transport"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "transport": {
+            "enum": ["stdio", "http"]
+        },
+        "command": {
+            "type": "string",
+            "minLength": 1
+        },
+        "args": {
+            "type": "array",
+            "items": { "type": "string" }
+        },
+        "cwd": {
+            "type": "string",
+            "minLength": 1
+        },
+        "env": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+        },
+        "url": {
+            "type": "string",
+            "format": "uri",
+            "pattern": "^https?://"
+        },
+        "headers": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+        },
+        "authorization": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "token"],
+                    "properties": {
+                        "type": { "const": "bearer" },
+                        "token": { "$ref": "#/$defs/environmentReference" }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "redirectUrl", "clientMetadataUrl"],
+                    "properties": {
+                        "type": { "const": "oauth" },
+                        "redirectUrl": { "type": "string", "format": "uri" },
+                        "clientMetadataUrl": {
+                            "type": "string",
+                            "format": "uri",
+                            "pattern": "^https://.+/.+"
+                        },
+                        "scope": { "type": "string", "minLength": 1 }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "redirectUrl", "clientId", "clientSecret"],
+                    "properties": {
+                        "type": { "const": "oauth" },
+                        "redirectUrl": { "type": "string", "format": "uri" },
+                        "clientId": { "type": "string", "minLength": 1 },
+                        "clientSecret": { "$ref": "#/$defs/environmentReference" },
+                        "scope": { "type": "string", "minLength": 1 }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "redirectUrl"],
+                    "properties": {
+                        "type": { "const": "oauth" },
+                        "redirectUrl": { "type": "string", "format": "uri" },
+                        "scope": { "type": "string", "minLength": 1 }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "clientId", "clientSecret"],
+                    "properties": {
+                        "type": { "const": "client-credentials" },
+                        "clientId": { "type": "string", "minLength": 1 },
+                        "clientSecret": { "$ref": "#/$defs/environmentReference" },
+                        "scope": { "type": "string", "minLength": 1 },
+                        "issuer": { "type": "string", "minLength": 1 }
+                    }
+                }
+            ]
+        },
+        "tools": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+        },
+        "read": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+        }
+    },
+    "$defs": {
+        "environmentReference": {
+            "type": "string",
+            "pattern": "^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+        }
+    },
+    "allOf": [
+        {
+            "if": {
+                "properties": { "transport": { "const": "stdio" } },
+                "required": ["transport"]
+            },
+            "then": {
+                "required": ["command"],
+                "not": {
+                    "anyOf": [
+                        { "required": ["url"] },
+                        { "required": ["headers"] },
+                        { "required": ["authorization"] }
+                    ]
+                }
+            }
+        },
+        {
+            "if": {
+                "properties": { "transport": { "const": "http" } },
+                "required": ["transport"]
+            },
+            "then": {
+                "required": ["url"],
+                "not": {
+                    "anyOf": [
+                        { "required": ["command"] },
+                        { "required": ["args"] },
+                        { "required": ["cwd"] },
+                        { "required": ["env"] }
+                    ]
+                }
+            }
+        }
+    ]
+}

package/dist/schema/McpServerOptions.json

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