@kindgi/cli 0.2.0 → 0.3.0-rc.0

package/dist/sdk-skills/kindgi-scala-authoring-guardrails/SKILL.md

@@ -7,18 +7,19 @@ description: >
   `(config, trace)` check returning a `CheckResult` (or a Future of one with
   `checkAsync`), `RunTrace`, config case classes and the values a check runs
   with, actions, severity and scope, munit tests with `evaluate`, and wiring
-  a guardrail onto an agent. In 0.1 only the halt action acts (retry /
-  escalate / compensate are only recorded: nothing runs the turn again), and
-  a check sees only the current turn: its user message and tool results, not
-  earlier turns'. Load this whenever you are authoring or editing code in a
-  Scala pack's guardrails packages (a pack whose `kindgi.config.json` says
-  `"language": "scala"`), defining a check, or wiring a guardrail onto an
-  agent. Scala agents are covered by kindgi-scala-authoring-agents, Scala
-  tools by kindgi-scala-authoring-tools.
+  a guardrail onto an agent. halt fails the turn and retry sends the answer
+  back to the model for a new one (escalate / compensate are only recorded
+  in 0.1), and a check sees only the current turn: its user message and tool
+  results, not earlier turns'. Load this whenever you are authoring or
+  editing code in a Scala pack's guardrails packages (a pack whose
+  `kindgi.config.json` says `"language": "scala"`), defining a check, or
+  wiring a guardrail onto an agent. Scala agents are covered by
+  kindgi-scala-authoring-agents, Scala tools by
+  kindgi-scala-authoring-tools.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.2"
-sdk_version: "0.2.0"
+version: "0.1.4"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -42,6 +43,8 @@ named like its file, in a `guardrails` package. For an agent turn, the
 runtime evaluates every guardrail the agent lists once, on the final answer,
 before it is stored.
 
+`Guardrail[C](…)` has no field for the other points a guardrail can run at (`at`, and a check's `points`), so a Scala guardrail runs at the final answer only; the points are documented at https://docs.kindgi.com/v0.3/guides/guardrails/configure-a-guardrail/#where-in-the-turn-it-runs.
+
 Ask what the rule should catch before writing one. The sample
 `response-not-empty` guardrail is a demonstration, not a template.
 
@@ -50,14 +53,20 @@ Ask what the rule should catch before writing one. The sample
 Read this before you plan a guardrail. Three limits decide what can be
 built:
 
-- **Only `halt` acts.** A failed `halt` guardrail fails the turn with
-  `guardrail-violation`, and the answer is not stored. `retry`, `escalate`
-  and `compensate` are recorded on the turn's violations, as `log-only`
-  is, and the turn completes: nothing runs the turn again, escalates or
-  calls a compensating tool. So "block the reply and make the agent try
-  again" can't be a guardrail. Use `halt`: the error names the guardrail
-  and the check's reason, and the message is sent again (by the person, or
-  by your app when it gets `guardrail-violation`).
+- **`halt` and `retry` act.** A failed `halt` guardrail fails the turn with
+  `guardrail-violation`, and the answer is not stored. A failed `retry`
+  guardrail sends the answer back to the model, with the check's reason in a
+  user message, for a new one; the failed answer isn't stored. When it has
+  failed `retry.maxAttempts` answers (the first one included; 2 when left
+  out), the turn fails with `guardrail-violation` and
+  `details.attempts`. Each new answer is a model call that the agent's
+  `budget.maxSteps` counts. The `halt` and `retry` guardrails judge each
+  answer, a judge's calls included, which `budget.maxCostUsd` doesn't count;
+  the others judge only the answer that's sent. A new answer can call tools
+  again, side-effecting ones included, with approvals as usual. `escalate`
+  and `compensate` are recorded on the turn's violations, as `log-only` is,
+  and the turn completes: nothing escalates or calls a compensating tool. So
+  "block the reply and make the agent try again" is a `retry` guardrail.
 - **A check sees one turn.** The trace holds the current turn only: its
   user message (`trace.userInput`), its tool calls and their results
   (`toolCalls`, `toolResults`) and its answer (`output`). Earlier turns'
@@ -151,11 +160,12 @@ object Citations {
   builder refuses a check with neither.
   - In an agent turn, a failed `halt` guardrail fails the turn
     (`guardrail-violation`), and the answer is not stored.
+  - A failed `retry` guardrail sends the answer back for a new one, up to
+    its `maxAttempts` answers (above).
   - Any other action reports the failure in the turn result's `violations`,
     and the turn completes.
-  - In 0.1 the runtime acts only on `halt`: `retry`, `escalate` and
-    `compensate` are recorded on the violation, with no second attempt,
-    escalation or compensating call.
+  - `escalate` and `compensate` are recorded on the violation, with no
+    escalation or compensating call in 0.1.
 - **`severity`:** `info`, `warn`, `error` (default) or `critical`. It's
   independent of the action: dashboards group by severity, and execution
   follows the action.
@@ -218,8 +228,9 @@ no registered guardrail fails the turn before the model is called
 2. **`set("config", …)` keyed by Scala names that differ from the wire.**
    It's keyed by the case class's Jackson names.
 3. **No `onViolation` or `action`.** The builder refuses the check.
-4. **Expecting another attempt.** `halt` stops the turn, and in 0.1 `retry`
-   doesn't run the turn again: it's only recorded.
+4. **Expecting `halt` to try again.** `halt` stops the turn; `retry` asks
+   the model for a new answer, and fails the turn once its `maxAttempts`
+   answers have failed.
 5. **Calling a model from the check.** That isn't available: keep checks
    pure.
 6. **Throwing for a broken rule.** Return `CheckResult.fail(…)`. An

package/dist/sdk-skills/kindgi-scala-authoring-tools/SKILL.md

@@ -15,8 +15,8 @@ description: >
   kindgi-scala-getting-started.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.4"
-sdk_version: "0.2.0"
+version: "0.1.5"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -156,7 +156,7 @@ object Citator {
   it writes to (`Option(ctx.idempotencyKey).foreach(k => request.header("Idempotency-Key", k))`)
   or looks for it there first: a refund never goes out twice. A UUID; `null`
   outside a run and from a runtime before 0.1.6. Docs:
-  https://docs.kindgi.com/v0.2/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  https://docs.kindgi.com/v0.3/guides/tools/write-a-tool/#make-a-side-effect-happen-once
 - `ctx.projectId`, `ctx.orgId`: the run's project, and its org (`null` when
   it has none). The runtime sets them from the run, never from the input.
   To check an id the input names, compare it with these.
@@ -229,7 +229,7 @@ val tool: Tool[Input, Output] = Tool[Input, Output]("my-pack.send-mail")
 - **Unattended runs:** in a run no person started, a tool that uses a `"person"` connection waits for that person's yes, reads included: `.readOnly` doesn't lift it. The agent's own approval settings can't lift it; only a trigger's `toolsAllowedUnattended` can, which a project admin sets, as for `needsApprovalWhenUnattended` (below). In a run a new mail started, the mail is a stranger's text, so two more calls wait: a call of a tool that isn't `.readOnly`, and, when the trigger reads the company's mailbox, a read with the company's connection to that app. The mail trigger's `toolsAllowedUnattended` lifts these too.
 - **In a unit test:** `com.kindgi.pack.ToolContext.forTest(java.util.Map.of("mail", new ToolConnection("c-1", "google", "Google", "test", new ConnectionAccount("1", "ana@acme.com"), null)))`; the last argument, when the token expires, can be `null`. `ctx.connections` is empty when the tool declares none.
 
-Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
+Docs: https://docs.kindgi.com/v0.3/guides/connections/use-a-connection/
 
 ## Errors and output
 
@@ -245,10 +245,16 @@ Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
 **`readOnly`** declares a tool that changes nothing outside itself (a lookup,
 a search, a calculation): it's `mutating(false)`. A dry run
 (`./kindgiw runs start --dry-run`) runs it. Leave it off for anything that
-writes, sends, charges or deletes: such a tool stops a dry run. It's also
-the tool's approval default: an agent that turns approval gates on
+writes, sends, charges or deletes: such a tool stops a dry run. It's also the
+tool's approval default: an agent that turns approval gates on
 (`conversationPolicy.hitl`) asks before any tool that isn't read-only on its
-first use.
+first use. And it decides what runs together: when a model step asks for
+several calls at once, an agent runs calls to read-only tools (no changing
+effect either) that come one after another at the same time, up to 8 of them,
+and any other call on its own, in the order the model asked (an agent with
+`set("parallelToolCalls", false)` runs every call on its own). A call that may
+wait, for another system's answer or for the person who started the run to
+connect an app, runs on its own too.
 
 In a run a new mail started, a call of a tool that isn't read-only waits
 for a person's yes, unless the mail trigger's `toolsAllowedUnattended`
@@ -322,7 +328,7 @@ In a run a person started (signed in, or with their own API key), the agent's ru
     .needsApprovalWhenUnattended(true)
 ```
 
-Docs: https://docs.kindgi.com/v0.2/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+Docs: https://docs.kindgi.com/v0.3/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
 
 ## Results that are text from outside: `resultIsOutsideData`
 
@@ -420,7 +426,7 @@ changes (a removed field, a narrower type), not on every save.
     folder, `~/.aws`) or any `.env*` file, and gets `EPERM` there. A tool that
     needs a path names it in `kindgi.config.json`: `"dev": {"sandbox": {"allowRead": ["~/.aws"]}}`.
     Never set `KINDGI_DEV_SANDBOX=off` or `dev.sandbox: false` to get past it
-    (https://docs.kindgi.com/v0.2/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.3/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem
 

package/dist/sdk-skills/kindgi-scala-getting-started/SKILL.md

@@ -17,8 +17,8 @@ description: >
   kindgi-scala-authoring-flows; models by kindgi-authoring-providers.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.4"
-sdk_version: "0.2.0"
+version: "0.1.6"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -252,7 +252,7 @@ Show it in the app's own UI. **Never:**
   runtime Kindgi hosts gives no database access.
 - **link users to Kindgi's console**, or any Kindgi UI, for this data.
 
-Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
+Docs: https://docs.kindgi.com/v0.3/guides/runs/show-runs-in-your-app/
 
 ## Build an image
 
@@ -279,22 +279,22 @@ doesn't have yet, then serving. Migrations only go forward: an upgrade
 starts with a backup of the database, and going back means restoring it and
 running the older version on it.
 
-- **On Cloud Run, a small dev deployment** (`network_mode = "none"`, on
-  runtime 0.1.8 or later): the Cloud Run module's `./upgrade.sh`, as of the
-  `@kindgi/sdk@<version>` tag of the release you're upgrading to, since it
-  knows the steps up to its own release. Run `./upgrade.sh --dry-run` first:
-  it changes nothing, and lists what a real run would change. Its plan also
-  reads every `*.auto.tfvars.json` in the module's folder (the pack's env),
-  and `yes` applies exactly the saved plan it showed. The module README's
-  Upgrading section has the rest:
+- **On Cloud Run, a deployment of the module** (on runtime 0.1.8 or later,
+  in any `network_mode`; before the `@kindgi/sdk@0.3.0` tag, `"none"` only):
+  the module's `./upgrade.sh`, as of the `@kindgi/sdk@<version>` tag of the
+  release you're upgrading to, since it knows the steps up to its own
+  release. It takes a `--var-file` for each file the deployment's variables
+  are in. Run `./upgrade.sh --dry-run` first: it changes nothing, and lists
+  what a real run would change. A real run's `yes` applies exactly the
+  saved plan it showed. The module README's Upgrading section has the rest:
   https://github.com/kindgi/kindgi-sdk/tree/main/deploy/gcp-cloud-run#upgrading
 - **Any other Cloud Run deployment:** by hand, staging first, as the Cloud
   Run page's "Upgrade by hand" section says:
-  https://docs.kindgi.com/v0.2/deploy/self-hosted/cloud-run/#upgrade-by-hand
-- **On Azure Container Apps:** the "Operate it" section of its page,
-  https://docs.kindgi.com/v0.2/deploy/self-hosted/azure-container-apps/#operate-it.
-- **Otherwise:** the operate page's upgrade steps,
-  https://docs.kindgi.com/v0.2/deploy/self-hosted/operate/#upgrade-the-runtime.
+  https://docs.kindgi.com/v0.3/deploy/self-hosted/cloud-run/#upgrade-by-hand
+- **On Azure Container Apps:** the "Operate it" section of its page:
+  https://docs.kindgi.com/v0.3/deploy/self-hosted/azure-container-apps/#operate-it
+- **Otherwise:** the operate page's upgrade steps:
+  https://docs.kindgi.com/v0.3/deploy/self-hosted/operate/#upgrade-the-runtime
 
 An upgrade changes a running deployment: give the person the commands to run
 in their own terminal (`./upgrade.sh` waits for them to type `yes`).

package/dist/sdk-skills/kindgi-using/SKILL.md

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.1.2"
-sdk_version: "0.2.0"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node, python, java, scala]
 ---
 
@@ -266,13 +266,13 @@ say there were none.
 
 ## More
 
-- Runs: https://docs.kindgi.com/v0.2/guides/runs/list-runs/ and
-  https://docs.kindgi.com/v0.2/guides/runs/read-the-journal/
-- Approvals: https://docs.kindgi.com/v0.2/guides/approvals/decide-an-approval/
-- Connections: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
-- Memory: https://docs.kindgi.com/v0.2/guides/agents/give-an-agent-memory/
-- Schedules: https://docs.kindgi.com/v0.2/guides/runs/run-on-a-schedule/
-- Mail triggers: https://docs.kindgi.com/v0.2/guides/runs/start-runs-from-new-mail/
-- People and keys: https://docs.kindgi.com/v0.2/deploy/people-and-keys/
-- Cost: https://docs.kindgi.com/v0.2/guides/observability/cost-per-run/
-- Rating answers: https://docs.kindgi.com/v0.2/guides/evals/judge-a-runs-output/
+- Runs: https://docs.kindgi.com/v0.3/guides/runs/list-runs/ and
+  https://docs.kindgi.com/v0.3/guides/runs/read-the-journal/
+- Approvals: https://docs.kindgi.com/v0.3/guides/approvals/decide-an-approval/
+- Connections: https://docs.kindgi.com/v0.3/guides/connections/use-a-connection/
+- Memory: https://docs.kindgi.com/v0.3/guides/agents/give-an-agent-memory/
+- Schedules: https://docs.kindgi.com/v0.3/guides/runs/run-on-a-schedule/
+- Mail triggers: https://docs.kindgi.com/v0.3/guides/runs/start-runs-from-new-mail/
+- People and keys: https://docs.kindgi.com/v0.3/deploy/people-and-keys/
+- Cost: https://docs.kindgi.com/v0.3/guides/observability/cost-per-run/
+- Rating answers: https://docs.kindgi.com/v0.3/guides/evals/judge-a-runs-output/

package/dist/templates/sample/README.md.tmpl

@@ -2,10 +2,10 @@
 
 A sample Kindgi pack — scaffolded by `kindgi init --template=sample`.
 
-Two tools (`echo`, `greet`), one guardrail (`response-not-empty`), one
-agent that uses both tools + the guardrail, and one flow that stitches
-the two tools into a workflow. It is compile-time-valid and ready to
-run with `kindgi dev`.
+Three tools (`echo`, `greet`, `fetch-httpbin`), one guardrail
+(`response-not-empty`), one agent that uses `echo` and `greet` + the
+guardrail, and one flow that runs the `greet` tool, then the agent. It is
+compile-time-valid and ready to run with `kindgi dev`.
 
 ## Layout
 
@@ -16,11 +16,12 @@ run with `kindgi dev`.
 ├── tsconfig.json
 ├── tools/
 │   ├── echo/index.ts                         # defineTool — Zod-authored echo
-│   └── greet/index.ts                        # defineTool — Zod-authored greeting
+│   ├── greet/index.ts                        # defineTool — Zod-authored greeting
+│   └── fetch-httpbin/index.ts                # defineTool — declarative HTTP call
 ├── guardrails/
 │   └── response-not-empty/index.ts           # defineCheck — response has content
 ├── agents/
-│   └── echo-agent/index.ts                   # defineAgent — uses both tools + guardrail
+│   └── echo-agent/index.ts                   # defineAgent — uses echo + greet + guardrail
 └── flows/
     └── echo-flow/index.ts                    # Flow — greet tool → echo agent step → declared output
 ```
@@ -68,7 +69,7 @@ agent, and other providers: the `kindgi-authoring-providers` skill.
 | Tool | `tools/greet/index.ts` | Second Zod-authored tool — takes a name, returns a greeting. |
 | Tool | `tools/fetch-httpbin/index.ts` | `defineTool({spec: {kind: 'http'}})` — declarative HTTP call, no imperative handler code. Hits httpbin.org so it works without credentials. |
 | Guardrail | `guardrails/response-not-empty/index.ts` | `defineCheck` — zero-LLM check that a response payload is non-empty. |
-| Agent | `agents/echo-agent/index.ts` | `defineAgent` — pulls in the local tools + the guardrail; uses `capabilities` for model routing. |
+| Agent | `agents/echo-agent/index.ts` | `defineAgent` — pulls in `echo` and `greet` + the guardrail; uses `capabilities` for model routing. |
 | Flow | `flows/echo-flow/index.ts` | `defineFlow` — a tool step fed from the run input, an agent step, a declared `output`. Run: `kindgi runs start --flow={{PACK_ID}}.echo-flow --input='{"name":"Ada"}'`. |
 
 ## Extend

package/dist/templates/sample/agents/echo-agent/index.ts.tmpl

@@ -1,4 +1,4 @@
-// {{PACK_ID}}.echo-agent — pulls in both tools + the response-not-empty
+// {{PACK_ID}}.echo-agent — pulls in the echo and greet tools + the response-not-empty
 // guardrail. The agent shape is pure metadata; every field is either a
 // primitive or a reference to a registered substrate object.
 

package/dist/templates/sample/kindgi.config.ts.tmpl

@@ -4,7 +4,7 @@ const config = {
   pack: {
     id: '{{PACK_ID}}',
     version: '{{PACK_VERSION}}',
-    description: 'A sample Kindgi pack — two tools, one guardrail, one agent, one flow.',
+    description: 'A sample Kindgi pack — three tools, one guardrail, one agent, one flow.',
   },
   discovery: {
     tools: 'tools/**/*.ts',

package/dist/templates/sample/package.json.tmpl

@@ -2,7 +2,7 @@
   "name": "{{PACK_NAME}}",
   "version": "{{PACK_VERSION}}",
   "private": true,
-  "description": "Kindgi pack — scaffolded by `kindgi init --template=sample`. Two tools, one guardrail, one agent, one flow.",
+  "description": "Kindgi pack — scaffolded by `kindgi init --template=sample`. Three tools, one guardrail, one agent, one flow.",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/dist/templates/woocommerce/README.md.tmpl

@@ -204,9 +204,15 @@ Ask the store agent something:
 
 ## One project and one pack per client
 
-This pack is one client's: every id in it starts with `{{PACK_ID}}.`. For
-another client, make another copy, so its ids start with that client's
-name:
+This pack is one client's: every id in it starts with `{{PACK_ID}}.`. A
+copy for another client runs only where each deployment runs as a service
+of its own. A runtime with one pack service runs only the pack that service
+was given, so don't make a copy there: a copy deploys, and its tools fail
+when called. Deploying this pack into a second project answers a `409`
+that names what such a runtime can do.
+
+Where each deployment runs as a service of its own, make a copy for each
+other client, so its ids start with that client's name:
 
 ```sh
 {{KINDGI}} init <client> --template=woocommerce

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/cli",
-  "version": "0.2.0",
+  "version": "0.3.0-rc.0",
   "description": "Command-line interface for Kindgi™. Create a pack, run it on your machine (`kindgi dev`), build, sign and deploy it, and work with a running Kindgi API from the terminal.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,18 +37,18 @@
     "provenance": true
   },
   "dependencies": {
-    "@kindgi/agents": "0.2.0",
-    "@kindgi/client": "0.2.0",
-    "@kindgi/dotenv-file": "0.2.0",
-    "@kindgi/crypto": "0.2.0",
-    "@kindgi/env-schema": "0.2.0",
-    "@kindgi/flow": "0.2.0",
-    "@kindgi/handler-runtime": "0.2.0",
-    "@kindgi/log": "0.2.0",
-    "@kindgi/secrets-dotenv": "0.2.0",
-    "@kindgi/platform": "0.2.0",
-    "@kindgi/sdk": "0.2.0",
-    "@kindgi/types": "0.2.0",
+    "@kindgi/agents": "0.3.0-rc.0",
+    "@kindgi/client": "0.3.0-rc.0",
+    "@kindgi/dotenv-file": "0.3.0-rc.0",
+    "@kindgi/crypto": "0.3.0-rc.0",
+    "@kindgi/env-schema": "0.3.0-rc.0",
+    "@kindgi/flow": "0.3.0-rc.0",
+    "@kindgi/handler-runtime": "0.3.0-rc.0",
+    "@kindgi/log": "0.3.0-rc.0",
+    "@kindgi/secrets-dotenv": "0.3.0-rc.0",
+    "@kindgi/platform": "0.3.0-rc.0",
+    "@kindgi/sdk": "0.3.0-rc.0",
+    "@kindgi/types": "0.3.0-rc.0",
     "esbuild": "^0.24.0",
     "semver": "^7.8.5",
     "smol-toml": "^1.9.0",