@kindgi/specs 0.0.0-bootstrap.0 → 0.1.1

package/schemas/agent.schema.json

@@ -0,0 +1,238 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/agent.schema.json",
+  "$comment": "schema-version: 1.3.0",
+  "title": "Agent",
+  "description": "An agent definition. Declarative composition of instructions + capabilities + tools + memory retrieval + guardrails + conversation policy. The same definition is durable across restarts and versioned like flows — provenance references agents by (id, version).",
+  "type": "object",
+  "required": [
+    "id",
+    "version",
+    "name",
+    "instructions",
+    "capabilities",
+    "tools",
+    "retrieval",
+    "guardrails"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Agent identifier. Convention: '<pack>.<agent>' (e.g. 'acme.citation-verifier')."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
+      "description": "Semver identifying this iteration of the agent. Different versions are different agents for audit purposes."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable display name."
+    },
+    "description": {
+      "type": "string",
+      "description": "Prose describing what the agent does. Shown in catalog + provenance metadata."
+    },
+    "instructions": {
+      "type": "string",
+      "minLength": 1,
+      "description": "System-prompt rendered at the top of every turn. LiquidJS template — {{ variable }} substitution, {% if %} / {% for %} control flow, {{ value | filter }} filters. Every referenced variable must be a declared PromptParameter or a framework auto-var (today, now, agent.*, conversation.*). Rendered with strictVariables — unresolved refs are hard errors."
+    },
+    "parameters": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PromptParameter" },
+      "description": "Typed parameters supplied at invoke time. UI reads this to build a configuration form; runtime validates required parameters are provided before the model call."
+    },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "description": "One Capability declaration — see capability.schema.json."
+      },
+      "description": "Capability declarations consumed by the router at turn time. One entry per resource kind the agent needs (e.g. LLM inference, embedding, gpu-compute). The router matches each entry by its kind (`Capability.kind`, default `llm-inference`) and its requirements; the array shape lets new kinds arrive without a schema break."
+    },
+    "tools": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ToolRef" },
+      "description": "Tools the agent may invoke, as `{ id, version }` references; an empty array makes the agent chat-only. At run start each reference resolves to the highest registered version that satisfies its range; an unresolvable reference fails the turn. Schema-version 1.1.0 replaced the bare-string tool ids of 1.0.0, which `defineAgent` already rejected."
+    },
+    "retrieval": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/RetrievalIntent" },
+      "description": "Fact-retrieval intents run before every turn to ground the model's context."
+    },
+    "guardrails": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Guardrail ids the agent is subject to. Resolved at turn start against the guardrails bound for the run (an unknown id fails the turn); evaluated on each turn's final response, before it is stored."
+    },
+    "preferredProvider": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Preferred model provider id. Soft hint: the router prefers this provider when it satisfies the agent's capabilities and tenant policy, and otherwise routes normally."
+    },
+    "preferredModel": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Preferred model name within the selected provider. Soft hint, combined with preferredProvider."
+    },
+    "conversationPolicy": { "$ref": "#/$defs/ConversationPolicy" },
+    "budget": { "$ref": "#/$defs/TurnBudget" },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Free-form filter tags for the catalog. Not consumed by execution."
+    },
+    "output": { "$ref": "#/$defs/AgentOutputSpec" },
+    "toolErrors": { "$ref": "#/$defs/ToolErrorsSpec" }
+  },
+  "$defs": {
+    "ToolErrorsSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What the turn does when a tool call fails (schema-version 1.3.0): the failure goes back to the model as the call's result, so it can correct the call, up to `maxRetries` times per turn, for the kinds in `retryOn`. Default: one retry, for `invalid-arguments` and `unknown-tool`. A tenant `tool-errors` policy can lower it.",
+      "properties": {
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "description": "Failed calls sent back to the model per turn. Default 1."
+        },
+        "retryOn": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "enum": ["invalid-arguments", "unknown-tool", "tool-error"] },
+          "description": "Which failures are sent back: arguments that don't fit the input schema, a tool the agent doesn't have, a tool that ran and failed. Default `invalid-arguments`, `unknown-tool`."
+        }
+      }
+    },
+    "AgentOutputSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema"],
+      "description": "A typed result (schema-version 1.2.0): the final answer must be JSON matching `schema`. An invalid answer is sent back to the model with the problems listed, up to `maxRepairs` times; then the turn fails with `output-schema-violation`.",
+      "properties": {
+        "schema": {
+          "type": "object",
+          "description": "JSON Schema (draft 2020-12) the final answer must match."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A name for the output, shown to the model and in errors. Default `output`."
+        },
+        "maxRepairs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many times the model is asked to repair an invalid answer. Default 1."
+        }
+      }
+    },
+    "ToolRef": {
+      "type": "object",
+      "required": ["id", "version"],
+      "additionalProperties": false,
+      "description": "A typed tool reference: a tool id plus a semver range. Bare-string ids are not accepted — every reference names both.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "description": "Tool id (e.g. 'acme.verify-citation'). Must not be blank."
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "description": "npm-style semver range: '1.2.3' pins exactly, '^1.2.3' allows compatible updates, '~1.2.3' patch updates only, '>=1.0.0 <2.0.0' an explicit range. Must not be blank; the range grammar is checked when the reference resolves at run start."
+        }
+      }
+    },
+    "PromptParameter": {
+      "type": "object",
+      "required": ["name", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Variable name referenced in the instructions template. Must NOT collide with reserved auto-var namespaces: today, now, agent, conversation."
+        },
+        "description": {
+          "type": "string",
+          "description": "UI-facing description of what the caller should supply."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "date"]
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Default true. Set false to allow the parameter to be omitted."
+        },
+        "default": {
+          "description": "Value used when the caller omits this parameter. Must match the declared type."
+        }
+      }
+    },
+    "RetrievalIntent": {
+      "type": "object",
+      "required": ["types", "scope"],
+      "additionalProperties": false,
+      "properties": {
+        "types": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "scope": {
+          "type": "string",
+          "enum": ["same-conversation", "same-project", "tenant"]
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Cap on facts per turn. Default 10."
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["keyword", "semantic", "both"]
+        }
+      }
+    },
+    "ConversationPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "historyLimit": { "type": "integer", "minimum": 1 },
+        "autoCloseAfterInactiveSeconds": { "type": "integer", "minimum": 1 },
+        "hitlAfterTurns": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "TurnBudget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxSteps": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum model→tool→model iterations per turn. Default 8."
+        },
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Maximum USD spend per turn."
+        },
+        "maxWallMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Wall-clock cap in ms. Default 120000."
+        }
+      }
+    }
+  }
+}

package/schemas/audit-bundle.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/audit-bundle.schema.json",
+  "$comment": "schema-version: 1.0.0",
+  "title": "HITL audit bundle",
+  "description": "A signed export bundling one or more HITL approvals + their decisions + references to the provenance DAGs those approvals concern. Produced by the Kindgi runtime's HITL audit export. Ed25519-signed with the same key material used for provenance signing. Verifiable outside the runtime by an external auditor with only the public key.",
+  "type": "object",
+  "required": [
+    "id",
+    "tenantId",
+    "generatedAt",
+    "approvals",
+    "decisions",
+    "provenanceRefs",
+    "signature"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique bundle identifier (UUID). Stable across re-reads."
+    },
+    "tenantId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Sovereignty boundary. All included approvals + decisions belong to this tenant."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC timestamp when the bundle was materialized."
+    },
+    "approvals": {
+      "type": "array",
+      "description": "The approval records included in this bundle. Ordering is not guaranteed; consumers must key by `id`.",
+      "items": { "$ref": "#/$defs/approval" }
+    },
+    "decisions": {
+      "type": "array",
+      "description": "The decision records for approvals in this bundle. Some approvals may not yet have a decision (bundle exported mid-flight); a consumer joins by `approvalId`.",
+      "items": { "$ref": "#/$defs/reviewDecision" }
+    },
+    "provenanceRefs": {
+      "type": "array",
+      "description": "Back-references to the provenance DAGs the approvals concern. Only present when an approval carried a `provenanceRef`. Consumers fetch the DAGs from the provenance API separately — they are NOT embedded here to keep bundles small.",
+      "items": {
+        "type": "object",
+        "required": ["runId"],
+        "additionalProperties": false,
+        "properties": {
+          "runId": { "type": "string", "minLength": 1 },
+          "provenanceId": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "signature": {
+      "$ref": "#/$defs/signature"
+    }
+  },
+  "$defs": {
+    "approval": {
+      "type": "object",
+      "required": [
+        "id",
+        "tenantId",
+        "subjectKind",
+        "subjectRef",
+        "requiredRole",
+        "status",
+        "createdAt",
+        "updatedAt"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "tenantId": { "type": "string", "minLength": 1 },
+        "projectId": { "type": "string", "minLength": 1 },
+        "subjectKind": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Free-form kind identifier (e.g. 'agent-turn:session-hitl-gate', 'supervisor:fix-proposal', 'pack:install'). Callers namespace their kinds."
+        },
+        "subjectRef": {
+          "type": "object",
+          "description": "Polymorphic payload describing what needs approval. Shape depends on `subjectKind`.",
+          "additionalProperties": true
+        },
+        "requiredRole": { "$ref": "#/$defs/reviewerRole" },
+        "status": { "$ref": "#/$defs/approvalStatus" },
+        "assignedTo": { "type": "string", "minLength": 1 },
+        "batchKey": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "context": { "type": "object", "additionalProperties": true },
+        "provenanceRef": {
+          "type": "object",
+          "required": ["runId"],
+          "additionalProperties": false,
+          "properties": {
+            "runId": { "type": "string", "minLength": 1 },
+            "provenanceId": { "type": "string", "minLength": 1 }
+          }
+        },
+        "waitTokenId": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "reviewDecision": {
+      "type": "object",
+      "required": [
+        "id",
+        "tenantId",
+        "approvalId",
+        "reviewerId",
+        "decision",
+        "reviewerRoleAtDecision",
+        "decidedAt"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "tenantId": { "type": "string", "minLength": 1 },
+        "approvalId": { "type": "string", "minLength": 1 },
+        "reviewerId": { "type": "string", "minLength": 1 },
+        "decision": {
+          "type": "string",
+          "enum": ["approve", "reject", "escalate", "withdraw"]
+        },
+        "rationale": { "type": "string" },
+        "evidence": { "type": "object", "additionalProperties": true },
+        "reviewerRoleAtDecision": {
+          "$ref": "#/$defs/reviewerRole",
+          "description": "Snapshot of the reviewer's role at the moment of decision. A subsequent role rotation does not rewrite this audit record."
+        },
+        "decidedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "reviewerRole": {
+      "type": "string",
+      "enum": ["standard", "senior", "admin"],
+      "description": "Reviewer role class. Ordered by escalation authority: standard < senior < admin. `requiredRole` on an approval is the minimum; a higher-ranked reviewer can always decide a lower-tier approval."
+    },
+    "approvalStatus": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "assigned",
+        "in_review",
+        "approved",
+        "rejected",
+        "escalated",
+        "expired",
+        "withdrawn"
+      ]
+    },
+    "signature": {
+      "type": "object",
+      "required": ["algorithm", "keyId", "value", "signedAt"],
+      "additionalProperties": false,
+      "description": "Ed25519 signature over the canonical JSON projection of the bundle (all fields except this signature). Same algorithm and canonicalization as signed provenance exports.",
+      "properties": {
+        "algorithm": { "type": "string", "enum": ["ed25519"] },
+        "keyId": { "type": "string", "minLength": 1 },
+        "value": { "type": "string", "pattern": "^[A-Za-z0-9+/]+={0,2}$" },
+        "signedAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/schemas/capability.schema.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/capability.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Capability declaration",
+  "description": "An agent's model requirements as declarative constraints. The model router matches capabilities against registered providers, respecting per-tenant policy. `defineCapability` validates a declaration against this schema; a declaration that no registered provider satisfies fails at routing time with `capability-unsatisfiable`.",
+  "type": "object",
+  "required": ["needs"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "type": "string",
+      "minLength": 1,
+      "default": "llm-inference",
+      "examples": ["llm-inference", "embedding", "gpu-compute", "sandbox-exec", "browser-session"],
+      "description": "Resource kind this capability requests. Open string: `examples` lists the well-known kinds, and adapters can declare their own. Absent means `llm-inference`. The router only considers providers whose `capabilityKind` equals it (a provider that declares none counts as `llm-inference`). Added in schema-version 1.1.0."
+    },
+    "needs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/Requirement"
+      }
+    },
+    "prefer": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Preference"
+      },
+      "description": "Soft preferences: the router picks the highest-scoring model that also satisfies all 'needs'."
+    },
+    "budget": {
+      "$ref": "#/$defs/Budget",
+      "description": "Per-invocation budget. Declarative: carried with the declaration but not enforced by the runtime (per-turn spend is capped by the agent's `budget.maxCostUsd`)."
+    }
+  },
+  "$defs": {
+    "Requirement": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/FeatureRequirement"
+        },
+        {
+          "$ref": "#/$defs/ContextRequirement"
+        },
+        {
+          "$ref": "#/$defs/CostRequirement"
+        },
+        {
+          "$ref": "#/$defs/RegionRequirement"
+        },
+        {
+          "$ref": "#/$defs/LatencyRequirement"
+        },
+        {
+          "$ref": "#/$defs/ProviderRequirement"
+        },
+        {
+          "$ref": "#/$defs/ModelRequirement"
+        }
+      ]
+    },
+    "FeatureRequirement": {
+      "type": "object",
+      "required": ["feature"],
+      "additionalProperties": false,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "enum": [
+            "structured-output",
+            "vision",
+            "audio-input",
+            "audio-output",
+            "tool-use",
+            "parallel-tool-use",
+            "thinking",
+            "long-context",
+            "code-execution",
+            "web-search",
+            "file-search",
+            "streaming",
+            "batch"
+          ]
+        }
+      }
+    },
+    "ContextRequirement": {
+      "type": "object",
+      "required": ["contextWindow"],
+      "additionalProperties": false,
+      "properties": {
+        "contextWindow": {
+          "type": "object",
+          "required": ["op", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": [">=", ">", "=", "<=", "<"]
+            },
+            "value": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        }
+      }
+    },
+    "CostRequirement": {
+      "type": "object",
+      "required": ["costPerCall"],
+      "additionalProperties": false,
+      "properties": {
+        "costPerCall": {
+          "type": "object",
+          "required": ["op", "usd"],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": [">=", ">", "=", "<=", "<"]
+            },
+            "usd": {
+              "type": "number",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "RegionRequirement": {
+      "type": "object",
+      "required": ["region"],
+      "additionalProperties": false,
+      "properties": {
+        "region": {
+          "type": "string",
+          "description": "Geographic region constraint (e.g. 'eu-only', 'us-only', 'us-gov'). Enforced by the router against each provider's declared region; a tenant policy's `regionAllow` can constrain it further."
+        }
+      }
+    },
+    "LatencyRequirement": {
+      "type": "object",
+      "required": ["p95LatencyMs"],
+      "additionalProperties": false,
+      "properties": {
+        "p95LatencyMs": {
+          "type": "object",
+          "required": ["op", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": ["<=", "<"]
+            },
+            "value": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "ProviderRequirement": {
+      "type": "object",
+      "required": ["providers"],
+      "additionalProperties": false,
+      "description": "Hard constraint on allowed providers (allowlist) or disallowed providers (denylist). Tenant policy can narrow the set further.",
+      "properties": {
+        "providers": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allow": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "deny": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "ModelRequirement": {
+      "type": "object",
+      "required": ["models"],
+      "additionalProperties": false,
+      "description": "Hard constraint on allowed models (allowlist) or disallowed models (denylist), matched against each provider's model names (`ModelInfo.name`). Can be combined with a providers requirement. Tenant policy can narrow the set further. Added in schema-version 1.1.0.",
+      "properties": {
+        "models": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allow": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "deny": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "Preference": {
+      "type": "object",
+      "required": ["feature", "weight"],
+      "additionalProperties": false,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "description": "A capability feature or a soft attribute (e.g. 'lower-cost', 'lower-latency', 'higher-accuracy')."
+        },
+        "weight": {
+          "type": "number"
+        }
+      }
+    },
+    "Budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxDurationMs": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}