@agentproto/corpus-cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/specs/resources/aip-14/draft/TOOL.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/docs/aip-14/TOOL.schema.json",
+  "title": "TOOL.md frontmatter — agenttool/v1 (abstract agent contract)",
+  "description": "Validates the YAML frontmatter portion of an AIP-14 TOOL.md manifest. Implementation-specific fields (code/run/runner/secrets/network/entry) are NOT part of this schema — they live on the AIP-30 PROVIDER schema.",
+  "type": "object",
+  "required": ["name", "id", "description", "version", "inputs", "outputs"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "Human-readable display name."
+    },
+    "id": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 80,
+      "pattern": "^[a-z0-9][a-z0-9.\\-]*[a-z0-9]$",
+      "description": "Machine identifier. Lowercase, digits, dashes, dots. Dots denote namespace."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "description": "One-paragraph purpose, written for the LLM caller."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:[-+][\\w.\\-]+)?$",
+      "description": "Spec version of THIS file. Bump on breaking change to inputs/outputs/side-effect profile."
+    },
+    "inputs": {
+      "description": "Defined by AIP-16 — the IO `inputs` block.",
+      "$ref": "https://agentproto.sh/docs/aip-16/IO.schema.json#/$defs/inputs"
+    },
+    "outputs": {
+      "description": "Defined by AIP-16 — the IO `outputs` block.",
+      "$ref": "https://agentproto.sh/docs/aip-16/IO.schema.json#/$defs/outputs"
+    },
+    "idempotent": {
+      "type": "boolean",
+      "default": false,
+      "description": "Logical idempotency at contract level. Network-level retry safety belongs to PROVIDER's retry_override."
+    },
+    "mutates": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z]+:[^\\s]+$",
+        "description": "Format: <class>:<scope>. Examples: network:*, workspace:/path, database:invoices."
+      },
+      "default": []
+    },
+    "requires": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "network": { "type": "array", "items": { "type": "string" } },
+        "secrets": { "type": "array", "items": { "type": "string" } },
+        "tools":   { "type": "array", "items": { "type": "string" } }
+      },
+      "description": "Capability requirements for governance gating per AIP-7. Providers MAY add to this set; MUST NOT remove from it."
+    },
+    "approval": {
+      "anyOf": [
+        { "enum": ["auto", "always", "on-mutate"] },
+        { "type": "string", "pattern": "^policy:[A-Za-z0-9_./-]+$" }
+      ],
+      "default": "auto",
+      "description": "Approval class. 'auto' | 'always' | 'on-mutate' | 'policy:<ref>'. Contract-level — providers can't downgrade."
+    },
+    "risk_level": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 3,
+      "default": 0,
+      "description": "0=read-only, 1=scoped writes, 2=external side effects, 3=irreversible."
+    },
+    "cost_class": {
+      "enum": ["trivial", "metered", "expensive"],
+      "default": "trivial",
+      "description": "Baseline. Providers MAY override via cost_override.cost_class."
+    },
+    "timeout_ms": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 30000,
+      "description": "Hard wall-clock contract ceiling. Providers MAY narrow via timeout_override_ms; MUST NOT widen."
+    },
+    "retry": {
+      "type": "object",
+      "required": ["max_attempts", "backoff"],
+      "additionalProperties": false,
+      "properties": {
+        "max_attempts": { "type": "integer", "minimum": 1, "maximum": 20 },
+        "backoff":      { "enum": ["fixed", "exponential"] },
+        "initial_ms":   { "type": "integer", "minimum": 0 }
+      },
+      "description": "Baseline retry policy. Providers MAY override via retry_override."
+    },
+    "default_implementation": {
+      "type": ["string", "null"],
+      "pattern": "^[a-z0-9][a-z0-9.\\-]{1,79}$",
+      "description": "Optional provider.id to use when the resolver has no other signal. Null = pick by resolver policy."
+    },
+    "driver_constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "forbid": {
+          "type": "array",
+          "items": { "enum": ["cli", "http", "mcp", "sdk", "builtin"] },
+          "uniqueItems": true,
+          "description": "Provider kinds the contract refuses (e.g. ['http'] for self-hosted-only tools)."
+        },
+        "require_kind": {
+          "type": "array",
+          "items": { "enum": ["cli", "http", "mcp", "sdk", "builtin"] },
+          "uniqueItems": true,
+          "description": "Whitelist of allowed provider kinds. Empty = all kinds permitted (subject to forbid)."
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+      "uniqueItems": true,
+      "default": []
+    },
+    "examples": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "input"],
+        "additionalProperties": false,
+        "properties": {
+          "name":   { "type": "string" },
+          "input":  {},
+          "output": {},
+          "note":   { "type": "string" }
+        }
+      },
+      "default": [],
+      "description": "Provider-agnostic examples. Every conformant provider MUST satisfy these. Provider-specific edge cases live on the PROVIDER's own examples."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {}
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "approval": { "const": "auto" } }
+      },
+      "then": {
+        "properties": {
+          "mutates": {
+            "type": "array",
+            "maxItems": 0
+          }
+        }
+      }
+    }
+  ]
+}

package/dist/specs/resources/aip-15/draft/WORKFLOW.schema.json

@@ -0,0 +1,356 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-15/WORKFLOW.schema.json",
+  "title": "WORKFLOW.md frontmatter (AIP-15)",
+  "description": "Validates the YAML frontmatter portion of an AIP-15 WORKFLOW.md manifest.",
+  "type": "object",
+  "required": [
+    "name",
+    "id",
+    "description",
+    "version",
+    "inputs",
+    "outputs",
+    "steps"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "minLength": 1, "maxLength": 80 },
+    "id": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 64,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+    },
+    "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:[-+][a-zA-Z0-9.-]+)?$"
+    },
+    "entry": { "type": "string" },
+    "inputs": {
+      "description": "Defined by AIP-16 — the IO `inputs` block.",
+      "$ref": "https://agentproto.sh/schemas/aip-16/IO.schema.json#/$defs/inputs"
+    },
+    "outputs": {
+      "description": "Defined by AIP-16 — the IO `outputs` block.",
+      "$ref": "https://agentproto.sh/schemas/aip-16/IO.schema.json#/$defs/outputs"
+    },
+    "result": {
+      "description": "Optional value expression mapping step results to the workflow output, using the same reference grammar as a step's `inputs` ($input.*, $steps.<id>.*, literals). Omitted ⇒ the output is the final step's result. Its shape SHOULD satisfy `outputs`.",
+      "type": ["object", "string"]
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/step" }
+    },
+    "start": { "type": "string" },
+    "suspendable": { "type": "boolean" },
+    "triggers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/trigger" },
+      "default": []
+    },
+    "requires": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "network": { "type": "array", "items": { "type": "string" } },
+        "fs.read": { "type": "array", "items": { "type": "string" } },
+        "fs.write": { "type": "array", "items": { "type": "string" } },
+        "env": { "type": "array", "items": { "type": "string" } },
+        "secrets": { "type": "array", "items": { "type": "string" } },
+        "tools": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "approval": { "$ref": "#/$defs/approval", "default": "per-step" },
+    "risk_level": { "type": "integer", "minimum": 0, "maximum": 3 },
+    "timeout_ms": { "type": "integer", "minimum": 1, "default": 600000 },
+    "max_steps": { "type": "integer", "minimum": 1, "default": 100 },
+    "retry": { "$ref": "#/$defs/retry" },
+    "cost_class": {
+      "enum": ["trivial", "metered", "expensive"],
+      "default": "metered"
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+      "default": []
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {}
+    },
+    "inputsFiles": {
+      "description": "Defined by AIP-16 — the IO `inputsFiles` block.",
+      "$ref": "https://agentproto.sh/schemas/aip-16/IO.schema.json#/$defs/inputsFiles"
+    },
+    "outputsFiles": {
+      "description": "Defined by AIP-16 — the IO `outputsFiles` block.",
+      "$ref": "https://agentproto.sh/schemas/aip-16/IO.schema.json#/$defs/outputsFiles"
+    },
+    "runtime": {
+      "description": "Defined by AIP-17 — the runner block.",
+      "$ref": "https://agentproto.sh/schemas/aip-17/RUNNER.schema.json#/$defs/runner"
+    }
+  },
+  "$defs": {
+    "jsonSchema": {
+      "description": "Any JSON Schema draft 2020-12 document. Validation deferred to a meta-validator.",
+      "type": "object"
+    },
+    "approval": {
+      "anyOf": [
+        { "enum": ["auto", "always", "on-mutate", "per-step"] },
+        { "type": "string", "pattern": "^policy:[A-Za-z0-9_./-]+$" }
+      ]
+    },
+    "retry": {
+      "type": "object",
+      "required": ["max_attempts", "backoff"],
+      "additionalProperties": false,
+      "properties": {
+        "max_attempts": { "type": "integer", "minimum": 1, "maximum": 20 },
+        "backoff": { "enum": ["fixed", "exponential"] },
+        "initial_ms": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "trigger": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind", "cron"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "schedule" },
+            "cron": { "type": "string" },
+            "timezone": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "path"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "webhook" },
+            "path": { "type": "string", "pattern": "^/" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind", "name"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "event" },
+            "name": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "manual" },
+            "label": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "stepCommon": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "minLength": 2,
+          "maxLength": 64
+        },
+        "name": { "type": "string", "maxLength": 80 },
+        "description": { "type": "string", "maxLength": 1000 },
+        "kind": {
+          "enum": [
+            "tool",
+            "branch",
+            "parallel",
+            "suspend",
+            "approval",
+            "map",
+            "loop",
+            "subworkflow"
+          ]
+        },
+        "inputs": { "type": "object" },
+        "outputs": { "$ref": "#/$defs/jsonSchema" },
+        "next": { "type": "string" },
+        "approval": { "$ref": "#/$defs/approval" },
+        "risk_level": { "type": "integer", "minimum": 0, "maximum": 3 },
+        "timeout_ms": { "type": "integer", "minimum": 1 },
+        "retry": { "$ref": "#/$defs/retry" },
+        "compensation": { "type": "string" }
+      }
+    },
+    "step": {
+      "allOf": [
+        { "$ref": "#/$defs/stepCommon" },
+        {
+          "oneOf": [
+            { "$ref": "#/$defs/stepTool" },
+            { "$ref": "#/$defs/stepBranch" },
+            { "$ref": "#/$defs/stepParallel" },
+            { "$ref": "#/$defs/stepSuspend" },
+            { "$ref": "#/$defs/stepApproval" },
+            { "$ref": "#/$defs/stepMap" },
+            { "$ref": "#/$defs/stepLoop" },
+            { "$ref": "#/$defs/stepSubworkflow" }
+          ]
+        }
+      ]
+    },
+    "stepTool": {
+      "type": "object",
+      "required": ["kind", "tool"],
+      "properties": {
+        "kind": { "const": "tool" },
+        "tool": {
+          "anyOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "required": ["entry"],
+              "properties": {
+                "entry": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "stepBranch": {
+      "type": "object",
+      "required": ["kind", "branches"],
+      "properties": {
+        "kind": { "const": "branch" },
+        "branches": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["when", "next"],
+            "properties": {
+              "when": { "type": "string" },
+              "next": { "type": "string" }
+            }
+          }
+        },
+        "default": { "type": "string" }
+      }
+    },
+    "stepParallel": {
+      "type": "object",
+      "required": ["kind", "branches"],
+      "properties": {
+        "kind": { "const": "parallel" },
+        "branches": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "required": ["id", "steps"],
+            "properties": {
+              "id": { "type": "string" },
+              "steps": { "type": "array", "items": { "$ref": "#/$defs/step" } },
+              "next": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "stepSuspend": {
+      "type": "object",
+      "required": ["kind", "resume"],
+      "properties": {
+        "kind": { "const": "suspend" },
+        "resume": {
+          "type": "object",
+          "required": ["on"],
+          "properties": {
+            "on": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            },
+            "timeout_ms": { "type": "integer", "minimum": 1 },
+            "on_timeout": { "type": "string" }
+          }
+        }
+      }
+    },
+    "stepApproval": {
+      "type": "object",
+      "required": ["kind", "prompt", "approvers"],
+      "properties": {
+        "kind": { "const": "approval" },
+        "prompt": { "type": "string" },
+        "artifacts": { "type": "array", "items": { "type": "string" } },
+        "approvers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "anyOf": [
+              {
+                "required": ["role"],
+                "properties": { "role": { "type": "string" } }
+              },
+              {
+                "required": ["userId"],
+                "properties": { "userId": { "type": "string" } }
+              }
+            ]
+          }
+        },
+        "timeout_ms": { "type": "integer", "minimum": 1 },
+        "on_approve": {
+          "type": "object",
+          "properties": { "next": { "type": "string" } }
+        },
+        "on_reject": {
+          "type": "object",
+          "properties": { "next": { "type": "string" } }
+        },
+        "on_timeout": { "type": "string" }
+      }
+    },
+    "stepMap": {
+      "type": "object",
+      "required": ["kind", "over", "steps"],
+      "properties": {
+        "kind": { "const": "map" },
+        "over": { "type": "string" },
+        "parallelism": { "type": "integer", "minimum": 0 },
+        "steps": { "type": "array", "items": { "$ref": "#/$defs/step" } }
+      }
+    },
+    "stepLoop": {
+      "type": "object",
+      "required": ["kind", "while", "max_iterations", "steps"],
+      "properties": {
+        "kind": { "const": "loop" },
+        "while": { "type": "string" },
+        "max_iterations": { "type": "integer", "minimum": 1, "maximum": 1000 },
+        "steps": { "type": "array", "items": { "$ref": "#/$defs/step" } }
+      }
+    },
+    "stepSubworkflow": {
+      "type": "object",
+      "required": ["kind", "workflow"],
+      "properties": {
+        "kind": { "const": "subworkflow" },
+        "workflow": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/specs/resources/aip-16/draft/IO.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-16/IO.schema.json",
+  "title": "IO blocks (AIP-16)",
+  "description": "Composable JSON Schema definitions for the four input/output blocks reused across manifest formats: inputs, outputs, inputsFiles, outputsFiles. Other AIPs reference these by $ref into their own schemas.",
+  "type": "object",
+  "$defs": {
+    "inputs": {
+      "description": "Structured arguments. Validated by the host before the body runs.",
+      "$ref": "#/$defs/jsonSchema"
+    },
+    "outputs": {
+      "description": "Structured success-case return. Errors are out-of-band per the importing manifest's error model.",
+      "$ref": "#/$defs/jsonSchema"
+    },
+    "inputsFiles": {
+      "description": "File-contract IN. Map of <key> → file entry. Host stages workspace:<path> into <fsRoot>/<key> before the run.",
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/fileContractEntry" },
+      "default": {}
+    },
+    "outputsFiles": {
+      "description": "File-contract OUT. Map of <key> → file entry. Host syncs <fsRoot>/<key> back to workspace:<path> after the run.",
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/fileContractEntry" },
+      "default": {}
+    },
+    "fileContractEntry": {
+      "description": "A single declared file in inputsFiles/outputsFiles.",
+      "type": "object",
+      "required": ["path"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "description": "Workspace-relative path. outputsFiles entries MAY use the tokens <runId>, <workflowId>, <toolId>, <isoDate> for per-run path interpolation.",
+          "type": "string",
+          "minLength": 1
+        },
+        "mode": {
+          "description": "Convention only — not enforced by the contract. `ro` for inputs is the typical default; `rw` for outputs.",
+          "enum": ["ro", "rw"]
+        },
+        "contentType": {
+          "description": "Informational MIME type. Hosts MAY surface in audit logs / UIs.",
+          "type": "string"
+        }
+      }
+    },
+    "jsonSchema": {
+      "description": "Any JSON Schema draft 2020-12 document. Validation deferred to a meta-validator.",
+      "type": "object"
+    },
+    "reservedFsRootField": {
+      "description": "Importing manifests SHOULD include this key in their `inputs` schema's `properties` when they declare inputsFiles/outputsFiles. Hosts inject the absolute scratch-root path here before the body runs.",
+      "type": "object",
+      "properties": {
+        "_workflowFsRoot": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/dist/specs/resources/aip-17/draft/RUNNER.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-17/RUNNER.schema.json",
+  "title": "Runner block (AIP-17)",
+  "description": "Composable JSON Schema definition for the `runner` block — process boundary, optional container image, declarative dependency needs, and resource limits. Other AIPs reference this by $ref into their own schemas.",
+  "type": "object",
+  "$defs": {
+    "runner": {
+      "description": "Process boundary that hosts the body. Engine + optional image + declarative needs + resource limits.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "description": "Where the process runs. `subprocess` (default): host-local Node `--permission` child. `sandbox`: real container via the host's SandboxProviderAdapter. `in-process`: dynamic import inside the host process; reserved for trusted/vendor code, silently downgraded to `subprocess` for untrusted origins.",
+          "enum": ["subprocess", "sandbox", "in-process"],
+          "default": "subprocess"
+        },
+        "image": {
+          "description": "Sandbox template id from the host registry. Only meaningful for `engine: sandbox`. When omitted, the host auto-picks via `needs`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "needs": {
+          "description": "Declarative dependency requirements. Hosts use these to auto-pick an image, install missing deps at cold-start, and surface them in trust UIs.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "language": {
+              "description": "Primary language runtime.",
+              "enum": ["node", "python", "multi"]
+            },
+            "native": {
+              "description": "OS-level package names. Default convention: Debian/Ubuntu apt names.",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "default": []
+            },
+            "npm": {
+              "description": "Additional npm packages installed via `npm install` after lockfile-driven `npm ci`.",
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^@?[^@]+@?.*$"
+              },
+              "default": []
+            },
+            "pip": {
+              "description": "Additional pip packages installed via `pip install --user`.",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "default": []
+            }
+          }
+        },
+        "limits": {
+          "description": "Resource caps. Advisory but enforceable when the isolation primitive supports it.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "memory_mb": {
+              "description": "Hard memory cap in MiB.",
+              "type": "integer",
+              "minimum": 1
+            },
+            "timeout_ms": {
+              "description": "Hard wall-clock cap in ms.",
+              "type": "integer",
+              "minimum": 1
+            },
+            "cpu_ms": {
+              "description": "CPU-time cap in ms. Hosts that can't enforce it ignore this field.",
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}