@kindgi/specs 0.0.0-bootstrap.0 → 0.1.1

package/schemas/pack-index.schema.json

@@ -0,0 +1,277 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/pack-index.schema.json",
+  "$comment": "schema-version: 1.4.0",
+  "title": "Pack index",
+  "description": "The `index.json` a pack build emits: the pack's tools, guardrails, agents and flows as data, plus where each tool handler and guardrail check lives. A runtime registers the pack's primitives from it, and a pack service loads the modules it names and resolves every call by id. Any indexer (the TypeScript `kindgi-index`, the Python `python -m kindgi.pack index`) emits this shape. Determinism: every list is sorted by `id` (code-unit order), keys are sorted at every level, the file is UTF-8 JSON indented by two spaces with a trailing newline, and integral numbers carry no fraction, so the same source indexes to the same bytes. Consumers refuse an envelope `v` they don't recognize.",
+  "type": "object",
+  "required": [
+    "v",
+    "packId",
+    "packVersion",
+    "artifactVersion",
+    "publishedAt",
+    "tools",
+    "guardrails",
+    "agents",
+    "flows"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "const": 1,
+      "description": "Envelope version. Additive fields on an existing entry shape don't bump it."
+    },
+    "packId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The pack's id (`pack.id` in the pack config)."
+    },
+    "packVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The pack's version (`pack.version` in the pack config)."
+    },
+    "artifactVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "This build of the pack. A pack build pins it; a local indexer defaults to `YYYYMMDD.N` (UTC date, N counting up from the previous index of the same day)."
+    },
+    "publishedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the index was built — ISO 8601 UTC with milliseconds (`2026-09-20T14:32:07.104Z`). A pack build pins it for reproducible output."
+    },
+    "tools": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/tool" },
+      "description": "Tools with handler code, sorted by `id`."
+    },
+    "guardrails": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/guardrail" },
+      "description": "Guardrails whose check is pack code, sorted by `id`."
+    },
+    "agents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/agent" },
+      "description": "Agents, sorted by `id`."
+    },
+    "flows": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/flow" },
+      "description": "Flows, sorted by `id`."
+    },
+    "env": {
+      "type": "object",
+      "required": ["required", "optional"],
+      "additionalProperties": false,
+      "description": "The process environment the pack's code reads (`env` in `kindgi.config`; `[tool.kindgi.env]` in `pyproject.toml`). Absent when the pack declares none. A deployment injects exactly these names. With a `required` name unset or empty, the pack service isn't ready (unless its env check is `warn`); `/readyz` and `/v1/info` name it. Not `needsSpec.env`: that is per-call context.",
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/envName" },
+          "uniqueItems": true,
+          "description": "Names the pack service needs, set and non-empty, to be ready. Sorted."
+        },
+        "optional": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/envName" },
+          "uniqueItems": true,
+          "description": "Names the pack reads when present. Sorted. Never also in `required`."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "envName": {
+      "type": "string",
+      "pattern": "^(?!KINDGI_)[A-Za-z_][A-Za-z0-9_]*$",
+      "description": "A process environment variable name. `KINDGI_*` names configure Kindgi and are never a pack's."
+    },
+    "modulePath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The source file the primitive was declared in, relative to the pack root: forward slashes, no leading `./` (`tools/echo/index.ts`, `tools/ledger.py`). A pack service resolves it against its module root; a build may point it at a bundle instead. Several entries may share one module (a Python module can declare several tools)."
+    },
+    "jsonSchema": {
+      "type": "object",
+      "description": "A JSON Schema (Draft 2020-12) in wire form. Open: any JSON Schema keyword is allowed, so this node carries no `additionalProperties` restriction."
+    },
+    "openObject": {
+      "type": "object",
+      "description": "An object whose shape is defined by the primitive's own schema (`tool.schema.json`, `guardrail.schema.json`, `agent.schema.json`, `flow.schema.json`); the index carries it as declared."
+    },
+    "tool": {
+      "type": "object",
+      "required": ["id", "input", "output", "modulePath"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Tool id — what a pack service resolves an `invoke` by."
+        },
+        "description": {
+          "type": "string",
+          "description": "What the tool does — the model reads it."
+        },
+        "version": {
+          "type": "string",
+          "description": "The tool's version. A caller that names a version gets `tool-version-mismatch` when it differs."
+        },
+        "input": {
+          "$ref": "#/$defs/jsonSchema",
+          "description": "JSON Schema the input must satisfy; the pack service validates before running the handler."
+        },
+        "output": {
+          "$ref": "#/$defs/jsonSchema",
+          "description": "JSON Schema the handler's return value must satisfy; the pack service validates it."
+        },
+        "effects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/openObject" },
+          "description": "Declared side effects (`tool.schema.json` `effects`)."
+        },
+        "needs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/openObject" },
+          "description": "Declared needs (`tool.schema.json` `needs`)."
+        },
+        "needsSpec": {
+          "$ref": "#/$defs/openObject",
+          "description": "Typed needs (`tool.schema.json` `needsSpec`)."
+        },
+        "sandbox": {
+          "type": "string",
+          "description": "Isolation posture (`tool.schema.json` `sandbox`)."
+        },
+        "limits": {
+          "$ref": "#/$defs/openObject",
+          "description": "Resource limits (`tool.schema.json` `limits`)."
+        },
+        "network": {
+          "$ref": "#/$defs/openObject",
+          "description": "Network policy (`tool.schema.json` `network`)."
+        },
+        "mutating": {
+          "type": "boolean",
+          "description": "Whether the tool may change something (`tool.schema.json` `mutating`). `false` makes it read-only: it runs in a dry run, and per-tool approval gates don't ask before it by default. Absent means it may."
+        },
+        "spec": {
+          "$ref": "#/$defs/openObject",
+          "description": "A declarative tool's spec (`tool.schema.json` `spec`, e.g. `kind: 'http'`). A runtime runs a tool that has one itself, resolving its `secretRef`s, rather than calling the pack service."
+        },
+        "modulePath": { "$ref": "#/$defs/modulePath" }
+      }
+    },
+    "guardrail": {
+      "type": "object",
+      "required": ["id", "kind", "action", "checkModulePath"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "description": "Guardrail id." },
+        "name": { "type": "string", "description": "Human-readable name." },
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "description": "How the guardrail is checked (`guardrail.schema.json` `kind`)."
+        },
+        "action": {
+          "$ref": "#/$defs/openObject",
+          "description": "What a violation does (`guardrail.schema.json` `action`, with `on-violation`)."
+        },
+        "severity": {
+          "type": "string",
+          "description": "Severity (`guardrail.schema.json` `severity`)."
+        },
+        "scope": {
+          "$ref": "#/$defs/openObject",
+          "description": "When the guardrail applies (`guardrail.schema.json` `scope`)."
+        },
+        "checkModulePath": { "$ref": "#/$defs/modulePath" },
+        "checkId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The check's id — what a pack service resolves a `check-invoke` by. Absent: the guardrail's `id`."
+        },
+        "configSchema": {
+          "$ref": "#/$defs/jsonSchema",
+          "description": "JSON Schema of the check's config."
+        },
+        "config": {
+          "$ref": "#/$defs/openObject",
+          "description": "What the check is configured with (`guardrail.schema.json` `config`)."
+        },
+        "sandbox": { "type": "string", "description": "Isolation posture." },
+        "limits": { "$ref": "#/$defs/openObject", "description": "Resource limits." },
+        "network": { "$ref": "#/$defs/openObject", "description": "Network policy." }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "required": ["id", "version", "name", "instructions", "capabilities", "tools", "modulePath"],
+      "additionalProperties": false,
+      "description": "An agent as declared (`agent.schema.json`); the runtime validates it in full when it registers the pack.",
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "instructions": { "type": "string" },
+        "capabilities": { "type": "array" },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "version"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "version": { "type": "string", "description": "Semver range." }
+            }
+          }
+        },
+        "retrieval": { "type": "array" },
+        "guardrails": { "type": "array", "items": { "type": "string" } },
+        "budget": { "$ref": "#/$defs/openObject" },
+        "parameters": { "type": "array" },
+        "preferredProvider": { "type": "string" },
+        "preferredModel": { "type": "string" },
+        "description": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "conversationPolicy": { "$ref": "#/$defs/openObject" },
+        "output": {
+          "$ref": "#/$defs/openObject",
+          "description": "Typed output (`{ schema, name?, maxRepairs? }`), its schema already JSON Schema."
+        },
+        "toolErrors": {
+          "$ref": "#/$defs/openObject",
+          "description": "How the agent's turns retry failed tool calls (`{ maxRetries?, retryOn? }`, `agent.schema.json` `toolErrors`)."
+        },
+        "modulePath": { "$ref": "#/$defs/modulePath" }
+      }
+    },
+    "flow": {
+      "type": "object",
+      "required": ["id", "version", "nodes", "edges", "kernelPayloadVersion", "modulePath"],
+      "additionalProperties": false,
+      "description": "A flow as declared (`flow.schema.json`), plus the kernel payload version.",
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "nodes": { "type": "array" },
+        "edges": { "type": "array" },
+        "maxParallelism": { "type": "integer", "minimum": 1 },
+        "metadata": { "$ref": "#/$defs/openObject" },
+        "output": { "$ref": "#/$defs/openObject" },
+        "kernelPayloadVersion": {
+          "const": 1,
+          "description": "Version of the flow payload inside the index, independent of the envelope `v`."
+        },
+        "modulePath": { "$ref": "#/$defs/modulePath" }
+      }
+    }
+  }
+}

package/schemas/pack-protocol.schema.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/pack-protocol.schema.json",
+  "$comment": "schema-version: 2.2.0",
+  "title": "Pack protocol",
+  "description": "Pack protocol v2 — the messages a runtime exchanges with a pack service to run pack code (tool handlers and guardrail checks). One request, one response. Transport (HTTP): `POST /v1/invoke` takes a request and answers 200 with a response; `GET /v1/info` (token) answers `info`; `GET /healthz` (no token) answers 200 while the process is up; `GET /readyz` (no token) answers 200 once every module the index names has loaded and the service isn't draining. Headers: `kindgi-pack-token` (required on `/v1/invoke` and `/v1/info`; `Authorization` is deliberately not used, since platforms like Cloud Run put their own identity token there), `kindgi-timeout-ms` (relative deadline; default 120000), `kindgi-run-id`, `kindgi-request-id`, `kindgi-protocol`; the answer to an invoke carries `kindgi-duration-ms` and `kindgi-artifact-version`. Every outcome of running pack code is a response message with status 200 — a validation failure, a throw, an unknown tool, `deadline-exceeded`, `cancelled` (the caller closed the connection). Non-2xx statuses are transport-level only: 401 (bad token), 404, 405, 413 (body over 10 MiB), 415 (not `application/json`), 503 with `Retry-After` (not ready, draining, or at the concurrency cap — the call provably did not run), 500 (the service itself failed). Process contract: a pack service reads `--index`, `--module-root` and `--host` arguments, `KINDGI_PACK_SERVICE_TOKEN`, `PORT` (`0` picks a free port) and `KINDGI_PACK_SERVICE_MAX_CONCURRENCY`; it removes `KINDGI_PACK_SERVICE_TOKEN` from its process environment before it loads pack code, which never sees it; it loads every module before listening and exits 1 with a `{\"kind\":\"boot-failed\",\"problems\":[…]}` JSON line on stderr when one fails; once listening it writes `{\"kind\":\"listening\",\"port\":N,…}` on stderr; SIGTERM drains in-flight calls (up to 8 s; `/readyz` and new invokes answer 503 meanwhile) and exits 0.",
+  "oneOf": [
+    { "$ref": "#/$defs/request" },
+    { "$ref": "#/$defs/response" },
+    { "$ref": "#/$defs/info" }
+  ],
+  "$defs": {
+    "version": {
+      "const": 2,
+      "description": "Protocol version of every message."
+    },
+    "request": {
+      "oneOf": [{ "$ref": "#/$defs/toolInvoke" }, { "$ref": "#/$defs/checkInvoke" }]
+    },
+    "response": {
+      "oneOf": [
+        { "$ref": "#/$defs/toolResult" },
+        { "$ref": "#/$defs/checkResult" },
+        { "$ref": "#/$defs/error" }
+      ]
+    },
+    "callContext": {
+      "type": "object",
+      "required": ["tenantId", "runId"],
+      "additionalProperties": false,
+      "description": "Per-call context a handler receives. Serializable only: a pack service adds its own cancellation (an abort signal, a cancellation token) on top.",
+      "properties": {
+        "tenantId": { "type": "string", "description": "Tenant the call runs for." },
+        "runId": { "type": "string", "description": "The kernel run the call belongs to." },
+        "requestId": {
+          "type": "string",
+          "description": "The individual call — e.g. the model's tool-call id."
+        },
+        "env": {
+          "type": "object",
+          "description": "Resolved environment values for the call (open)."
+        },
+        "secrets": { "type": "object", "description": "Resolved secrets for the call (open)." },
+        "config": { "type": "object", "description": "Resolved configuration for the call (open)." }
+      }
+    },
+    "toolInvoke": {
+      "type": "object",
+      "required": ["v", "kind", "tool", "input", "ctx"],
+      "additionalProperties": false,
+      "description": "Run a tool handler. The pack service validates `input` against the indexed input schema, runs the handler, validates its return value against the indexed output schema.",
+      "properties": {
+        "v": { "$ref": "#/$defs/version" },
+        "kind": { "const": "invoke" },
+        "tool": {
+          "type": "object",
+          "required": ["id"],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Tool id, resolved from the pack service's own index."
+            },
+            "version": {
+              "type": "string",
+              "description": "When set, the pack service refuses a different indexed version (`tool-version-mismatch`)."
+            }
+          }
+        },
+        "input": { "description": "The tool's input (any JSON)." },
+        "ctx": { "$ref": "#/$defs/callContext" }
+      }
+    },
+    "checkInvoke": {
+      "type": "object",
+      "required": ["v", "kind", "check", "config", "trace"],
+      "additionalProperties": false,
+      "description": "Run a guardrail check: `evaluate(config, trace)`.",
+      "properties": {
+        "v": { "$ref": "#/$defs/version" },
+        "kind": { "const": "check-invoke" },
+        "check": {
+          "type": "object",
+          "required": ["id"],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Check id (the indexed guardrail's `checkId`, else its `id`)."
+            }
+          }
+        },
+        "config": { "type": "object", "description": "The guardrail's config (open)." },
+        "trace": {
+          "description": "The run trace the check evaluates (`RunTrace` in `@kindgi/guardrails`)."
+        }
+      }
+    },
+    "toolResult": {
+      "type": "object",
+      "required": ["v", "kind", "output"],
+      "additionalProperties": false,
+      "properties": {
+        "v": { "$ref": "#/$defs/version" },
+        "kind": { "const": "result" },
+        "output": {
+          "description": "The handler's return value, valid against the tool's output schema."
+        }
+      }
+    },
+    "checkResult": {
+      "type": "object",
+      "required": ["v", "kind", "result"],
+      "additionalProperties": false,
+      "properties": {
+        "v": { "$ref": "#/$defs/version" },
+        "kind": { "const": "check-result" },
+        "result": {
+          "type": "object",
+          "required": ["passed"],
+          "description": "`CheckResult` — open beyond the listed fields.",
+          "properties": {
+            "passed": { "type": "boolean" },
+            "reason": { "type": "string" },
+            "judgeResponse": { "type": "string" },
+            "attributes": { "type": "object" }
+          }
+        }
+      }
+    },
+    "errorCode": {
+      "enum": [
+        "input-validation-failed",
+        "output-validation-failed",
+        "handler-import-failed",
+        "handler-shape-invalid",
+        "handler-throw",
+        "check-shape-invalid",
+        "malformed-message",
+        "unknown-protocol-version",
+        "unexpected-message-kind",
+        "tool-not-in-pack",
+        "check-not-in-pack",
+        "tool-version-mismatch",
+        "deadline-exceeded",
+        "cancelled"
+      ],
+      "description": "Why running pack code didn't produce a result."
+    },
+    "issue": {
+      "type": "object",
+      "required": ["instancePath", "message"],
+      "description": "One validation issue, Ajv-shaped. `keyword` names the failing JSON Schema keyword; it is absent when the failure came from a model's own validation (a Zod refinement, a pydantic validator) rather than a schema keyword. Open: an implementation may add fields.",
+      "properties": {
+        "instancePath": {
+          "type": "string",
+          "description": "JSON Pointer to the failing value (`\"\"` for the root, `/items/0/name`)."
+        },
+        "schemaPath": {
+          "type": "string",
+          "description": "URI fragment of the failing schema keyword (`#/properties/name/type`)."
+        },
+        "keyword": {
+          "type": "string",
+          "description": "The failing keyword (`type`, `required`, `additionalProperties`, …)."
+        },
+        "params": {
+          "type": "object",
+          "description": "Keyword parameters, as Ajv reports them: `required` → `{ missingProperty }`, `additionalProperties` → `{ additionalProperty }`, `type` → `{ type }`, `enum` → `{ allowedValues }`, limits → `{ limit }`, `pattern` → `{ pattern }`, `format` → `{ format }`."
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable message (`must have required property 'name'`)."
+        }
+      }
+    },
+    "error": {
+      "type": "object",
+      "required": ["v", "kind", "code", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "v": { "$ref": "#/$defs/version" },
+        "kind": { "const": "error" },
+        "code": { "$ref": "#/$defs/errorCode" },
+        "message": { "type": "string" },
+        "toolId": { "type": "string", "description": "Present when the error is about a tool." },
+        "checkId": { "type": "string", "description": "Present when the error is about a check." },
+        "cause": {
+          "description": "The serialized throw for `handler-throw` / `handler-import-failed` (`{ name, message, stack }` for an error object)."
+        },
+        "issues": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/issue" },
+          "description": "Present for `input-validation-failed` / `output-validation-failed`."
+        }
+      }
+    },
+    "info": {
+      "type": "object",
+      "required": ["protocol", "packId", "packVersion", "artifactVersion", "tools", "checks"],
+      "additionalProperties": false,
+      "description": "The answer to `GET /v1/info`.",
+      "properties": {
+        "protocol": { "$ref": "#/$defs/version" },
+        "packId": { "type": "string" },
+        "packVersion": { "type": "string" },
+        "artifactVersion": { "type": "string" },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id"],
+            "additionalProperties": false,
+            "properties": { "id": { "type": "string" }, "version": { "type": "string" } }
+          }
+        },
+        "checks": { "type": "array", "items": { "type": "string" } },
+        "missingEnv": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The index's required env names this process lacks (unset or empty), sorted. Empty when none is missing. Under the `strict` env check the service isn't ready while any is listed."
+        }
+      }
+    }
+  }
+}