@kindgi/specs 0.1.8-rc.0 → 0.1.9-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/specs",
-  "version": "0.1.8-rc.0",
+  "version": "0.1.9-rc.0",
   "description": "Canonical JSON Schemas (Draft 2020-12) for every Kindgi artifact kind — flow, agent, tool, capability, guardrail, policy, event, run event, memory, provenance, pack, compliance evidence, audit bundle, eval suite, discoverable entity. The wire contracts every SDK, runtime, and external tool validates against. Each schema is importable by name as `@kindgi/specs/<name>.schema.json`.",
   "license": "Apache-2.0",
   "repository": {

package/schemas/compliance-evidence.schema.json

@@ -67,7 +67,10 @@
         "service-account-unregistered",
         "person-added",
         "person-granted",
-        "person-ungranted"
+        "person-ungranted",
+        "trigger-owner-set",
+        "environment-order-set",
+        "deployment-promoted"
       ]
     },
     "timestamp": {

package/schemas/guardrail.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://kindgi.com/schemas/v1/guardrail.schema.json",
   "$comment": "schema-version: 1.1.0",
   "title": "Guardrail",
-  "description": "An assertion about agent behavior. Enforced at runtime (halt / retry / escalate / log-only / compensate per guardrail) AND in CI (blocks builds). Same definition, two enforcement paths — no drift between what tests check and what prod enforces. Zero-LLM checks are default (fast, deterministic); LLM-judge scorers are an opt-in class with explicit cost declaration. Schema-version 1.1.0 matches the `Guardrail` type: `check` is required, a `retry` action needs `maxAttempts`, `kind` and `on-violation` accept any non-empty string (the built-ins are listed as `examples`), and `sandbox` / `limits` / `network` / `needsSpec` are allowed.",
+  "description": "An assertion about agent behavior. Checked at runtime, where in 0.1 only `halt` stops the turn and every other action is recorded, AND in CI (blocks builds). Same definition, two enforcement paths — no drift between what tests check and what prod enforces. Zero-LLM checks are default (fast, deterministic); LLM-judge scorers are an opt-in class with explicit cost declaration. Schema-version 1.1.0 matches the `Guardrail` type: `check` is required, a `retry` object, when given, needs `maxAttempts`, `kind` and `on-violation` accept any non-empty string (the built-ins are listed as `examples`), and `sandbox` / `limits` / `network` / `needsSpec` are allowed.",
   "type": "object",
   "required": ["id", "kind", "check", "action"],
   "additionalProperties": false,
@@ -209,12 +209,12 @@
           "type": "string",
           "minLength": 1,
           "examples": ["halt", "retry", "escalate", "log-only", "compensate"],
-          "description": "What happens when the guardrail fires. Open string: any non-empty name is accepted here, and an action handler registered under that name applies it; when the caller evaluates with an action-handler registry, a name with no handler fails with `unknown-action`. Built-in actions: 'halt' = fail the run. 'retry' = re-execute the step (needs `retry.maxAttempts`). 'escalate' = route to HITL review. 'log-only' = record but don't block. 'compensate' = invoke a compensation action."
+          "description": "What a failed check does to the agent turn. Open string: any non-empty name is accepted here. In 0.1 the runtime acts only on 'halt': the turn fails with `guardrail-violation` and its response is not stored. Any other name is recorded as a violation, as 'log-only' is, and the turn completes. Built-in actions: 'halt' = fail the turn. 'log-only' = record, don't block. 'retry', 'escalate' and 'compensate' are recorded like 'log-only' in 0.1: nothing runs the turn again, escalates or calls a compensating tool."
         },
         "retry": {
           "type": "object",
           "additionalProperties": false,
-          "description": "For on-violation = 'retry'.",
+          "description": "For on-violation = 'retry': the attempts it asks for. In 0.1 nothing acts on it: there's no second attempt.",
           "required": ["maxAttempts"],
           "properties": {
             "maxAttempts": {
@@ -226,11 +226,11 @@
         },
         "escalateTo": {
           "type": "string",
-          "description": "For on-violation = 'escalate': reviewer role or queue id."
+          "description": "For on-violation = 'escalate': a reviewer role or queue id. In 0.1 nothing escalates."
         },
         "compensateWith": {
           "type": "string",
-          "description": "For on-violation = 'compensate': tool id to invoke as compensation."
+          "description": "For on-violation = 'compensate': the compensating tool's id. In 0.1 that tool isn't called."
         }
       }
     },

package/schemas/pack-index.schema.json

@@ -158,6 +158,10 @@
           "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."
         },
+        "needsApprovalWhenUnattended": {
+          "type": "boolean",
+          "description": "Whether a person must say yes to every call of the tool in a run no person started (`tool.schema.json` `needsApprovalWhenUnattended`). Absent means `false`."
+        },
         "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."

package/schemas/tool.schema.json

@@ -68,6 +68,10 @@
       "type": "boolean",
       "description": "Semantic marker: `true` when this tool causes observable side effects (writes state, calls external APIs with mutations, sends messages). Read-only tools set `false`. Absent defaults to `true`. Consumed by the HITL default classifier — a read-only tool passes straight through, a mutating tool asks on first use."
     },
+    "needsApprovalWhenUnattended": {
+      "type": "boolean",
+      "description": "`true` when a person must say yes to every call of this tool in a run no person started (a schedule, a webhook, an event or a service account's key started it). In such a run an agent's call waits for a person's yes whatever the agent's approval rules say, and a flow's tool step that calls it is refused. Absent means `false`. Optional additive field."
+    },
     "limits": {
       "type": "object",
       "additionalProperties": false,