@kindgi/cli 0.1.11-rc.0 → 0.2.0-rc.1

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

@@ -10,14 +10,15 @@ description: >
   `kindgi.config.json` yet and the user asks to "add Kindgi", "make an
   agent", "set up a pack", or when you are orienting in a Java pack
   (`kindgi.config.json` with `"language": "java"`) for the first time.
-  Authoring tools, guardrails, agents and flows is covered by
-  kindgi-java-authoring-tools, kindgi-java-authoring-guardrails,
-  kindgi-java-authoring-agents and kindgi-java-authoring-flows; models by
-  kindgi-authoring-providers.
+  Load it too when upgrading a self-hosted deployment, or when asked for
+  a migration script (there is none). Authoring tools, guardrails, agents
+  and flows is covered by kindgi-java-authoring-tools,
+  kindgi-java-authoring-guardrails, kindgi-java-authoring-agents and
+  kindgi-java-authoring-flows; models by kindgi-authoring-providers.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.3"
-sdk_version: "0.1.11-rc.0"
+version: "0.1.4"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -64,7 +65,7 @@ You need a JDK 17 or later (`JAVA_HOME`). Maven comes with the pack
 (`./mvnw`).
 
 ```sh
-npx --yes @kindgi/cli@0.1 init my-pack --template=java   # or: uvx --from "kindgi-cli>=0.1,<0.2" kindgi init …
+npx --yes @kindgi/cli@0.2 init my-pack --template=java   # or: uvx --from "kindgi-cli>=0.2,<0.3" kindgi init …
 cd my-pack
 ./mvnw test        # the template's tests: the tools, called directly
 ./kindgiw dev      # boots Kindgi locally and runs this pack, recompiling on save
@@ -88,7 +89,7 @@ reported as `file:line:col`, and the last good code keeps serving.
 In the app's directory (where its `pom.xml` is):
 
 ```sh
-npx --yes @kindgi/cli@0.1 init   # --pack-id=<id> if the app's artifactId doesn't make one
+npx --yes @kindgi/cli@0.2 init   # --pack-id=<id> if the app's artifactId doesn't make one
 ./kindgiw dev
 ```
 
@@ -235,7 +236,7 @@ Show it in the app's own UI. **Never:**
   gives no database access.
 - **link users to Kindgi's console**, or any Kindgi UI, for this data.
 
-Docs: https://docs.kindgi.com/v0.1/guides/runs/show-runs-in-your-app/
+Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
 
 ## Build an image
 
@@ -254,6 +255,37 @@ deployed pack service missing a required one isn't ready, and its `/readyz`
 names it; one the pack doesn't declare is dropped before the code loads
 (`kindgi dev` keeps it).
 
+## Upgrading a deployment
+
+There's no migration script, and none to write: a self-hosted runtime brings
+its database up to date when it starts, applying the migrations the database
+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:
+  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.
+
+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`).
+
+Not `./kindgiw upgrade`: that moves the pack's own pins (the CLI's and
+kindgi-pack's), not a deployment's runtime.
+
 ## Two things need the human
 
 - **The pack id and version** in `kindgi.config.json`. The id prefixes every

package/dist/sdk-skills/kindgi-python-authoring-agents/SKILL.md

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.7"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -142,8 +142,8 @@ brief_writer = Agent(
   loosen them. `"separateApprover"` in `hitl` (`True`, or
   `{"overrides": {"<tool id>": True}}`) makes a tool's approval need
   someone other than whoever asked.
-- **`budget`** — per turn: `maxSteps` (model calls, default 8),
-  `maxCostUsd`, `maxWallMs` (default 120 000). Steps or cost exceeded
+- **`budget`** — per turn: `maxSteps` (model calls, default 8, at most
+  32), `maxCostUsd`, `maxWallMs` (default 120 000). Steps or cost exceeded
   fails the turn (`budget-exceeded`); out of wall time aborts it. Leave
   room for real models: a turn with tool calls can take tens of seconds.
 - **`output`** — a typed answer: a pydantic model class (or any type
@@ -182,7 +182,7 @@ brief_writer = Agent(
   one person, or instruction-like text, waits for a person's approval.
   Use a model with reliable tool calling. `{"instructionTypes":
   ["acme.policy"]}` makes a retrieved, verified fact of those types an
-  instruction. See https://docs.kindgi.com/v0.1/guides/agents/give-an-agent-memory/.
+  instruction. See https://docs.kindgi.com/v0.2/guides/agents/give-an-agent-memory/.
 
 **In a run a webhook or an event started**, the turn's message is data:
 it arrives inside an `<event note="kindgi event: data, not

package/dist/sdk-skills/kindgi-python-authoring-flows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.2"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.5"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -14,8 +14,8 @@ description: >
   kindgi-python-getting-started.
 type: core
 library: "kindgi (Python)"
-version: "0.1.5"
-sdk_version: "0.1.11-rc.0"
+version: "0.1.6"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -95,8 +95,10 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   field's path (a bad output as `output-validation-failed`); the agent's
   `tool_errors` policy decides whether the model gets to fix the call.
 - **Problems in the declaration** (a missing docstring, an
-  unannotated parameter, a non-object input) raise `DefinitionError`
-  where the tool is declared; the indexer reports it with the file.
+  unannotated parameter, a non-object input, or an input or output
+  schema the runtime's compile refuses, such as one with a keyword it
+  doesn't know) raise `DefinitionError` where the tool is declared; the
+  indexer reports it with the file.
 
 ## `ToolContext`
 
@@ -112,7 +114,7 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   system it writes to (an `Idempotency-Key` header, a client reference, a
   unique column) or looks for it there first: a refund never goes out
   twice. A UUID; `None` outside a run and from a runtime before 0.1.6.
-  Docs: https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  Docs: https://docs.kindgi.com/v0.2/guides/tools/write-a-tool/#make-a-side-effect-happen-once
 - `ctx.project_id`, `ctx.org_id` — the run's project, and that project's
   org (`None` when it has none). The runtime sets them from the run, never
   from the input: to check an org or project id the input names, compare
@@ -136,7 +138,7 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   amounts and outcomes, never what a person typed (a refund's reason, a
   message, an address): the log is read by whoever operates the runtime.
   `ToolContext.for_test(…)` logs nothing unless you pass it `log=`. Docs:
-  https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
+  https://docs.kindgi.com/v0.2/guides/tools/write-a-tool/#log-from-a-tool
 
 ## Configuration and secrets
 
@@ -189,7 +191,7 @@ def find_order(lookup: Lookup, ctx: ToolContext) -> Found:
   precondition-failed: Tool "acme-orders.needs-account" was not run: env-value-missing: tool "acme-orders.needs-account" needs env value "ACME_ACCOUNT_ID" in env "local", and none is set for project e889c1f5-eae7-45dc-8669-5bd029a5d85c, its org, or the tenant. Set it: kindgi env set ACME_ACCOUNT_ID <value> --scope=project:e889c1f5-eae7-45dc-8669-5bd029a5d85c --env=local (or --scope=tenant, for every project)
   ```
 - **Not secret:** env values are recorded with each run that uses them and shown in its journal. A credential is a secret, never an env value.
-- **In a test:** `ToolContext.for_test(env={"ORDERS_BASE_URL": "…"})`.
+- **In a test:** `ToolContext.for_test(tool=find_order, env={"ORDERS_BASE_URL": "…"})` decides them as a run does: a schema `default` fills a name the test doesn't set, each value is checked, and a missing or invalid one raises `ValueError`.
 
 Everything else comes from the process environment: `os.environ["CITATOR_URL"]`.
 The pack service runs with the pack's environment — in `kindgi dev`
@@ -207,6 +209,38 @@ the pack service drops every other variable before your code loads
 unset once deployed. `KINDGI_*` names are Kindgi's own settings: a pack
 can't declare one.
 
+### Connections to other apps
+
+A tool that acts in another app as a person or as the company (sending mail, opening an issue) declares a **connection**, never a secret holding someone's token, and reads the call's short-lived token from `ctx.connections` (runtime 0.2.0 or later):
+
+```python
+import httpx
+
+from kindgi import ConnectionRejected, ToolContext, tool
+
+
+@tool(
+    id="my-pack.send-mail",
+    needs_spec={"connections": {"mail": {"app": "google", "permissions": ["gmail.send"], "as": "person"}}},
+)
+def send_mail(message: Message, ctx: ToolContext) -> Sent:
+    """Sends a message from the person's mailbox."""
+    mail = ctx.connections["mail"]
+    res = httpx.get(url, headers={"authorization": f"Bearer {mail.access_token}"})
+    if res.status_code == 401:
+        raise ConnectionRejected("mail")
+    # …
+```
+
+- **Whose connection:** `"as": "person"` is the connection of the person the run acts as (whoever started it, or the owner of the schedule or webhook that did); `"as": "company"` is the company's. The runtime picks it from the run, never from the input or the model. A run that acts as nobody (a service account's, an event's) fails a `"person"` call with `connection-needs-a-person`.
+- **The token:** `access_token` is current for this call only. Never keep, print, log or return it; it never reaches the journal. `account.label` says whose account it is (`ana@acme.com`).
+- **A 401 from the app:** `raise ConnectionRejected("mail")`, with the connection's name (a second argument can say what the app answered, never the token), or raise your own error `from` it. The runtime renews the token once and runs the call again; refused again, the call fails with `connection-rejected`.
+- **An HTTP tool** sends the token with no code: `authorization={"kind": "connection", "connection": "mail"}`.
+- **Unattended runs:** in a run no person started, a tool that uses a `"person"` connection waits for that person's yes, reads included: `mutating=False` 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 `needs_approval_when_unattended` (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 `mutating=False`, 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:** `ToolContext.for_test(connections={"mail": ToolConnection(connection_id="c-1", app="google", app_name="Google", access_token="test", account=ConnectionAccount(id="1", label="ana@acme.com"))})`, all from `kindgi`. `ctx.connections` is empty when the tool declares none.
+
+Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
+
 ## Errors and output
 
 - Raise an exception for a failure: the call fails with
@@ -229,6 +263,10 @@ approval gates on (`conversation_policy={"hitl": {"tools": {...}}}`)
 and has neither an override for the tool nor a `default` doesn't ask
 before a read-only tool, and asks before any other on first use.
 
+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`
+lists it.
+
 ```python
 @tool(id="acme.find-citations", mutating=False)
 def find_citations(query: CitationQuery) -> Citations:
@@ -244,10 +282,11 @@ policy and review; declare what the tool really does.
 
 ## A person's yes when no one is watching: `needs_approval_when_unattended`
 
-`needs_approval_when_unattended=True` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, an event or a service account's key started. In such a run:
+`needs_approval_when_unattended=True` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, a new mail, an event or a service account's key started. In such a run:
 
 - **An agent's call waits** for a person's yes, whatever the agent's `conversation_policy` says in `hitl["tools"]`. The agent's rules can't lift it: agents are reused, and the tool's author knows what it does.
 - **A flow's tool step that calls it is refused.** Put the tool behind an agent step instead, whose call waits.
+- **A trigger can lift both, for its own runs only.** A project admin names the tool in a webhook trigger's, a schedule's or a mail trigger's `toolsAllowedUnattended` (`--allow-unattended=<tool-id>` on `kindgi webhooks`, `kindgi schedules` and `kindgi mail-triggers`). In that trigger's runs, the tool is then as in a run a person started. The tenant's approval rules still apply.
 
 In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Left out, it counts as `False`. Declare it on a tool that moves money or changes something people rely on:
 
@@ -262,7 +301,11 @@ def refund(request: RefundRequest) -> Refunded:
     """Refunds an order."""
 ```
 
-Docs: https://docs.kindgi.com/v0.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+Docs: https://docs.kindgi.com/v0.2/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
+## Results that are text from outside: `result_is_outside_data`
+
+`result_is_outside_data=True` says the tool's results are text from outside that nobody checked, such as a mail someone sent or a page a search found. An agent reads each result of the tool as data, not instructions, in that turn and in every later turn's history. It changes what the model is told, not what the tool may do: pair it with approvals for anything an agent could do with what it read. Absent means `false`.
 
 ## HTTP tools — one request, no code
 
@@ -394,7 +437,7 @@ 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 `pyproject.toml`: `[tool.kindgi.dev.sandbox]` `allowRead = ["~/.aws"]`.
     Never set `KINDGI_DEV_SANDBOX=off` or `dev.sandbox: false` to get past it
-    (https://docs.kindgi.com/v0.1/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.2/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem
 

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

@@ -9,13 +9,15 @@ description: >
   project has no `[tool.kindgi]` table yet and the user asks to "add
   Kindgi", "make an agent", "set up a pack", or when you are orienting
   in a Python pack (pyproject.toml with `[tool.kindgi]`) for the first
-  time. Authoring tools, guardrails and agents is covered by
-  kindgi-python-authoring-tools, kindgi-python-authoring-guardrails and
-  kindgi-python-authoring-agents; models by kindgi-authoring-providers.
+  time. Load it too when upgrading a self-hosted deployment, or when
+  asked for a migration script (there is none). Authoring tools, guardrails
+  and agents is covered by kindgi-python-authoring-tools,
+  kindgi-python-authoring-guardrails and kindgi-python-authoring-agents;
+  models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.9"
-sdk_version: "0.1.11-rc.0"
+version: "0.1.10"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/README.md
@@ -54,7 +56,7 @@ primitive; `test_*.py`, `*_test.py` and `conftest.py` are skipped.
 ## Scaffold a new pack
 
 ```sh
-uvx --from "kindgi-cli>=0.1,<0.2" kindgi init my-pack --template=python
+uvx --from "kindgi-cli>=0.2,<0.3" kindgi init my-pack --template=python
 cd my-pack
 uv sync            # .venv with the kindgi package and the kindgi CLI
 uv run pytest
@@ -77,7 +79,7 @@ and don't stop theirs.
 In the app's directory (where its `pyproject.toml` is):
 
 ```sh
-uv add --dev "kindgi-cli>=0.1,<0.2"   # the CLI (Poetry: poetry add --group dev …)
+uv add --dev "kindgi-cli>=0.2,<0.3"   # the CLI (Poetry: poetry add --group dev …)
 uv run kindgi init     # --pack-id=<id> if the app's name doesn't make one
 uv sync                # or what it prints for Poetry / pip
 uv run kindgi dev
@@ -205,8 +207,9 @@ for event in client.runs.follow(run.id):  # to the run's end, reconnecting
     print(event.kind)
 ```
 
-`AsyncKindgi` is the asyncio twin. `kindgi dev` prints the URL and the
-token; `.kindgirc.json` in the pack holds them for the CLI.
+`AsyncKindgi` is the asyncio twin. With `kindgi dev`, the URL and the
+token are `apiUrl` and `token` in the pack's `.kindgirc.json`, which the
+CLI reads too; the banner shows only the token's last four characters.
 
 ## Your app and Kindgi's data
 
@@ -255,7 +258,7 @@ month = client.cost.aggregate(
 # month.total_usd; month.groups[i].key ({"month": "2026-10"}), .total_usd, .tokens
 ```
 
-Docs: https://docs.kindgi.com/v0.1/guides/observability/cost-per-run/
+Docs: https://docs.kindgi.com/v0.2/guides/observability/cost-per-run/
 
 Show it in the app's own UI. **Never:**
 
@@ -267,7 +270,7 @@ Show it in the app's own UI. **Never:**
 - **link users to Kindgi's console** or any Kindgi UI for this data.
 
 To keep a copy (reporting, search), pull it through the API into the app's
-own tables. Docs: https://docs.kindgi.com/v0.1/guides/runs/show-runs-in-your-app/
+own tables. Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
 
 ## Build an image
 
@@ -301,6 +304,34 @@ optional = ["SENTRY_DSN"]
 A `[tool.uv] required-version` that excludes the image's uv stops the
 build before anything uploads, with the range to use.
 
+## Upgrading a deployment
+
+There's no migration script, and none to write: a self-hosted runtime brings
+its database up to date when it starts, applying the migrations the database
+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:
+  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.
+
+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`).
+
 ## Two things need the human
 
 - **The pack id and version** in `[tool.kindgi.pack]`. The id prefixes

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.4"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -150,10 +150,10 @@ object BriefWriter {
   `Map("overrides" -> Map("<tool id>" -> true))`) makes a tool's approval
   need someone other than whoever asked.
 - **`set("budget", …)`:** per turn. `maxSteps` counts model calls (default
-  8); `maxCostUsd`; `maxWallMs` (default 120 000). Exceeding the steps or the
-  cost fails the turn (`budget-exceeded`); running out of wall time aborts
-  it. Leave room for real models: a turn with tool calls can take tens of
-  seconds.
+  8, at most 32); `maxCostUsd`; `maxWallMs` (default 120 000). Exceeding
+  the steps or the cost fails the turn (`budget-exceeded`); running out of
+  wall time aborts it. Leave room for real models: a turn with tool calls
+  can take tens of seconds.
 - **`output[T]`:** a typed answer, with its schema derived from the case
   class. The final answer must be JSON matching it. A wrong one goes back to
   the model with the problems (`maxRepairs`, default 1), and then the turn

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.2"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md

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

@@ -18,7 +18,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.2"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md

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.3"
-sdk_version: "0.1.11-rc.0"
+version: "0.1.4"
+sdk_version: "0.2.0-rc.1"
 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.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  https://docs.kindgi.com/v0.2/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.
@@ -203,6 +203,34 @@ dropped before your code loads (`kindgi dev` keeps them), so an undeclared
 one works locally and is unset once deployed. `KINDGI_*` names are Kindgi's
 own: a pack can't declare one.
 
+### Connections to other apps
+
+A tool that acts in another app as a person or as the company (sending mail, opening an issue) declares a **connection**, never a secret holding someone's token, and reads the call's short-lived token from `ctx.connections` (runtime 0.2.0 or later):
+
+```scala
+val tool: Tool[Input, Output] = Tool[Input, Output]("my-pack.send-mail")
+  // …description, version, effects…
+  .set("needsSpec", Map("connections" -> Map(
+    "mail" -> Map("app" -> "google", "permissions" -> List("gmail.send"), "as" -> "person"))))
+  .handler { (in, ctx) =>
+    val mail = ctx.connections.get("mail")
+    val res = http.send(
+      HttpRequest.newBuilder(uri).header("authorization", s"Bearer ${mail.accessToken}").build(),
+      HttpResponse.BodyHandlers.ofString())
+    if (res.statusCode == 401) throw new ConnectionRejectedException("mail")
+    // …
+  }
+```
+
+- **Whose connection:** `"as" -> "person"` is the connection of the person the run acts as (whoever started it, or the owner of the schedule or webhook that did); `"as" -> "company"` is the company's. The runtime picks it from the run, never from the input or the model. A run that acts as nobody (a service account's, an event's) fails a `"person"` call with `connection-needs-a-person`.
+- **The token:** `accessToken` is current for this call only. Never keep, print, log or return it; it never reaches the journal. `account.label` says whose account it is (`ana@acme.com`). `ToolConnection`, `ConnectionAccount` and `ConnectionRejectedException` come with `com.kindgi.pack.scaladsl._`.
+- **A 401 from the app:** `throw new ConnectionRejectedException("mail")`, with the connection's name (a second argument can say what the app answered, never the token), or your own exception with it as the cause. The runtime renews the token once and runs the call again; refused again, the call fails with `connection-rejected`.
+- **An HTTP tool** sends the token with no code: `.authorization(new HttpAuthSpec.Connection("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/
+
 ## Errors and output
 
 - Throw for a failure, or fail the `Future`: the call fails with
@@ -222,6 +250,10 @@ 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.
 
+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`
+lists it.
+
 `effect(kind, resource)` declares a side effect, such as
 `.effect("writes", "db:ledger")`. A dry run also stops at a tool with a
 `writes`, `deletes`, `spawns-run`, `emits-event` or `external-side-effect`
@@ -229,15 +261,58 @@ effect. `set(field, value)` sets the index entry's other fields (`needs`,
 `needsSpec`, `sandbox`, `limits`, `network`), with Scala maps and lists. They
 are recorded for policy and review, so declare what the tool really does.
 
-There is no HTTP-tool form (TypeScript's `kind: 'http'`). A tool that calls
-an HTTP API is a handler with `java.net.http.HttpClient`, as above.
+A tool that calls an HTTP API can be a handler with `java.net.http.HttpClient`,
+as above, or the request declared as data with no handler — see **HTTP tool (as
+data)** below.
+
+## HTTP tool (as data)
+
+A tool that calls an HTTP API can be the request itself, declared as data,
+instead of a handler: `.http(spec)` in place of `.handler(...)`. The Kindgi
+runtime makes the request from the spec — the SDK only builds and validates it,
+so calling such a tool in this JVM throws. The spec types are Java's, from
+`com.kindgi.pack.http`:
+
+```scala
+import com.kindgi.pack.scaladsl._
+import com.kindgi.pack.http._
+
+object FetchOrder {
+  final case class Input(orderId: String)
+  final case class Output(id: String, status: String, total: Double)
+
+  val tool: Tool[Input, Output] = Tool[Input, Output]("shop.fetch-order")
+    .description("Fetch an order by id from the storefront API.")
+    .version("0.1.0")
+    .readOnly
+    .http(
+      HttpToolSpec.builder()
+        .method(HttpMethod.GET)
+        .urlTemplate("https://api.shop.example/orders/{orderId}")
+        .authorization(new HttpAuthSpec.Bearer(new ToolSecretRef("production", "shop-api-token")))
+        .successStatus(200, 299)
+        .build())
+}
+```
+
+Every `{placeholder}` in the URL — in the path and query only, never in the
+host or port — is a field of the input, and so is one in a
+`HttpRequestBodySpec.Text` body; `.http(...)` throws if it isn't. Authorization
+is a `secretRef` (`HttpAuthSpec.Bearer` or `HttpAuthSpec.Header`), named for the
+runtime to resolve, never a literal credential. A request body is
+`HttpRequestBodySpec.JsonInput` (the input as JSON), `InputPassthrough` or
+`Text`. `timeoutMs` (default 30 seconds) covers the whole call, the response
+read included, and a run's cancel does too; a response body over 10 MiB,
+measured decompressed, fails the call — so point a tool at an endpoint that
+pages or filters, not one that returns everything.
 
 ## A person's yes when no one is watching: `needsApprovalWhenUnattended`
 
-`needsApprovalWhenUnattended(true)` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, an event or a service account's key started. In such a run:
+`needsApprovalWhenUnattended(true)` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, a new mail, an event or a service account's key started. In such a run:
 
 - **An agent's call waits** for a person's yes, whatever the agent's `conversationPolicy.hitl.tools` says. The agent's rules can't lift it: agents are reused, and the tool's author knows what it does.
 - **A flow's tool step that calls it is refused.** Put the tool behind an agent step instead, whose call waits.
+- **A trigger can lift both, for its own runs only.** A project admin names the tool in a webhook trigger's, a schedule's or a mail trigger's `toolsAllowedUnattended` (`--allow-unattended=<tool-id>` on `kindgi webhooks`, `kindgi schedules` and `kindgi mail-triggers`). In that trigger's runs, the tool is then as in a run a person started. The tenant's approval rules still apply.
 
 In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Left unset, it counts as `false`. Declare it on a tool that moves money or changes something people rely on:
 
@@ -247,13 +322,21 @@ 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.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+Docs: https://docs.kindgi.com/v0.2/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
+## Results that are text from outside: `resultIsOutsideData`
+
+`resultIsOutsideData(true)` says the tool's results are text from outside that nobody checked, such as a mail someone sent or a page a search found. An agent reads each result of the tool as data, not instructions, in that turn and in every later turn's history. It changes what the model is told, not what the tool may do: pair it with approvals for anything an agent could do with what it read. Absent means `false`.
 
 ## Testing
 
 `tool.call(input, ctx)` runs the handler with the input as given (no schema
 check). `ToolContext.forTest()` is a context with a test tenant and run and
-nothing else. A handler that reads the environment and calls a service is
+nothing else. `ToolContext.forTest(tool, env, secrets)` adds the env values
+the tool declares in `needsSpec`, decided as a run decides them (a schema
+`default` fills a name the test doesn't set, each value is checked, and a
+missing or invalid one throws `IllegalArgumentException`), and the secrets as
+given. A handler that reads the environment and calls a service is
 tested through the method it calls, with a stub server:
 
 ```scala
@@ -337,7 +420,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.1/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.2/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem