@kindgi/sdk 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "@kindgi/sdk — the authoring SDK for Kindgi™. Facade over the individual @kindgi/* packages + @kindgi/client. Unifies pack authoring (defineTool / defineCheck / defineAgent / defineFlow) and client callsites (createClient) behind three sub-paths: /define, /client, /types. Re-export facade; zero behavior.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,27 +18,33 @@
   "exports": {
     "./define": {
       "types": "./dist/define.d.ts",
-      "import": "./dist/define.js"
+      "import": "./dist/define.js",
+      "default": "./dist/define.js"
     },
     "./client": {
       "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
     },
     "./types": {
       "types": "./dist/types.d.ts",
-      "import": "./dist/types.js"
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
     },
     "./webhooks": {
       "types": "./dist/webhooks.d.ts",
-      "import": "./dist/webhooks.js"
+      "import": "./dist/webhooks.js",
+      "default": "./dist/webhooks.js"
     },
     "./build": {
       "types": "./dist/build.d.ts",
-      "import": "./dist/build.js"
+      "import": "./dist/build.js",
+      "default": "./dist/build.js"
     },
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
@@ -49,15 +55,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.1",
-    "@kindgi/client": "0.1.1",
-    "@kindgi/crypto": "0.1.1",
-    "@kindgi/flow": "0.1.1",
-    "@kindgi/guardrails": "0.1.1",
-    "@kindgi/handler-runtime": "0.1.1",
-    "@kindgi/schema": "0.1.1",
-    "@kindgi/tools": "0.1.1",
-    "@kindgi/types": "0.1.1"
+    "@kindgi/agents": "0.1.3",
+    "@kindgi/client": "0.1.3",
+    "@kindgi/crypto": "0.1.3",
+    "@kindgi/flow": "0.1.3",
+    "@kindgi/guardrails": "0.1.3",
+    "@kindgi/handler-runtime": "0.1.3",
+    "@kindgi/schema": "0.1.3",
+    "@kindgi/tools": "0.1.3",
+    "@kindgi/types": "0.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0"
@@ -75,7 +81,7 @@
     "vitest": "^2.1.8"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/skills/kindgi-authoring-guardrails/SKILL.md

@@ -107,11 +107,17 @@ How the pack tooling reads this file:
   `configZod`, `configSchema` or `configJsonSchema`, or a top-level
   `configZod` / `configSchema`), and the declaration's `config` — what
   the check runs with. It does not record `description`, `budget` or
-  `judgeCapabilities`.
+  `judgeCapabilities`. It checks `config` (none counts as `{}`) against
+  the config schema: a config that doesn't fit, or a required field with
+  no default left out, is a file error naming where, and `kindgi build`
+  refuses the pack.
 - The **pack service** loads the same module to run the check. It uses
   the module's `evaluate` export, or the `default` / `check` export when
   that is a function or has an `evaluate` method — here, the named
-  `check` export.
+  `check` export. A `defineCheck` check's `evaluate` gets the config its
+  schema resolves: the schema's defaults applied (a guardrail that
+  declares no config gets them all), and a config that doesn't fit
+  refused, naming where.
 
 ## Validating a declaration in-process
 

package/skills/kindgi-authoring-providers/SKILL.md

@@ -22,7 +22,7 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.2"
+version: "0.9.3"
 sdk_version: "0.0.0"
 pack_languages: [node, python]
 sources:
@@ -126,12 +126,46 @@ credential on argv.
 kindgi providers register --preset=anthropic                          # Opus 5.5, Sonnet 5.5, Haiku 4.5
 kindgi providers register --preset=anthropic --models=claude-haiku-4-5  # just one
 ```
-The preset carries the models, context windows and current prices
-(`kindgi providers presets` lists the presets and when their prices were
-checked). In a pack it refuses until the key is in the pack's env files —
+The preset carries the models, context windows, output limits and current
+prices (`kindgi providers presets` lists the presets and when their prices
+were checked); `--max-output-tokens=<n>` sets another output limit. In a pack it refuses until the key is in the pack's env files —
 step 1. That's all for Anthropic; go to step 4. The rest of this path is
 the same registration by hand, for a spec of your own.
 
+**Or declare it in the pack's config**, and `kindgi dev` registers it on
+every boot: in every git worktree (each has its own dev database), after
+`--reset`, and on a teammate's machine. Prefer this for any provider the pack
+needs under `kindgi dev`:
+```ts
+// in kindgi.config.ts
+providers: [
+  { preset: 'anthropic', models: ['claude-haiku-4-5'] },   // key ANTHROPIC_API_KEY, from the env files
+  { preset: 'gemini', project: 'acme-gcp', models: ['gemini-2.5-flash'] },
+  { spec: { /* the provider.json body below */ } },
+],
+```
+```toml
+# in pyproject.toml: one table per provider, same keys
+[[tool.kindgi.providers]]
+preset = "anthropic"
+models = ["claude-haiku-4-5"]
+```
+- A preset entry takes `models`, `project`, `secret` (the key's name, in place
+  of the preset's) and `maxOutputTokens`, spelled the same in `pyproject.toml`;
+  a `spec` entry is a `--spec` body. A
+  key is always a secret's name (`secret_ref`); a credential in
+  `adapter_config` is refused.
+- Each boot prints `Providers from kindgi.config.ts:` with one line each:
+  `registered`, `unchanged`, `registered again (changed in kindgi.config.ts)`,
+  `unregistered (no longer in kindgi.config.ts)`, or ⚠ `not registered: <KEY>
+  is not in .env, .env.local` (set the key, then restart: the config isn't
+  watched).
+- A provider with that id that `kindgi dev` didn't register is left as it is;
+  if its region or models differ, a ⚠ line names the
+  `kindgi providers unregister` that lets the config's version apply.
+- A runtime `kindgi dev` doesn't run (staging, production) still gets its
+  providers with `kindgi providers register`.
+
 **Step 2 (by hand) — write `provider.json`** at the pack root. One connection,
 three models — matches how the Anthropic SDK actually works (the API
 key is per-vendor; the model is per-call):
@@ -438,7 +472,7 @@ outside Google Cloud: put a service-account key (its JSON) in a secret
         "name": "gemini-2.5-pro",
         "contextWindow": 1048576,
         "features": ["tool-use"],
-        "maxOutputTokens": 8192,
+        "maxOutputTokens": 65536,
         "cost": {
           "promptUsdPer1kTokens": 0.00125,
           "completionUsdPer1kTokens": 0.01,
@@ -453,6 +487,7 @@ outside Google Cloud: put a service-account key (its JSON) in a secret
         "name": "gemini-2.5-flash",
         "contextWindow": 1048576,
         "features": ["tool-use"],
+        "maxOutputTokens": 65536,
         "cost": { "promptUsdPer1kTokens": 0.0003, "completionUsdPer1kTokens": 0.0025 }
       }
     ]

package/skills/kindgi-authoring-tools/SKILL.md

@@ -12,7 +12,7 @@ description: >
   authoring agents is covered by kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.3"
+version: "0.4.4"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -88,7 +88,8 @@ const defined = defineTool({
   effects: [],
   mutating: false,
   handler: async (input, ctx) => {
-    // ctx.tenantId, ctx.abortSignal, ctx.secrets (what needsSpec declares) available
+    // ctx.tenantId, ctx.abortSignal, ctx.secrets (what needsSpec declares) available;
+    // in a run, ctx.projectId and ctx.orgId (set from the run, never from the input)
     // Return type MUST match Output schema (validated at invoke time)
     return { found: true, canonicalCite: '...' };
   },
@@ -278,6 +279,17 @@ run start via `semver.maxSatisfying`. No implicit `:latest`.
    ("⚠ The pack imports @prisma/client (in kindgi/tools/…), which
    package.json lists only in devDependencies: …"), and `kindgi build`
    refuses the pack until it moves.
+10. **A tool that needs the app's install scripts in the image.** The
+    image installs with scripts off, so the app's `postinstall` /
+    `prepare` (`prisma generate`, husky) don't run there; `kindgi build`
+    lists them ("✓ The app's own install scripts don't run in the image:
+    …"). A tool that uses Prisma's client then fails the build ("@prisma/client
+    did not initialize yet"). Add `prisma({ schema: 'prisma/schema.prisma' })`
+    (from `@kindgi/sdk/build`; add `config: 'prisma.config.ts'` when the app
+    has one) to `image.extensions` in `kindgi.config.ts`. Other generate
+    steps: `defineBuildExtension({ name, contextFiles, postInstall: [{ bin, args }] })`.
+    Debian packages: `image.systemPackages`. Placeholder env for those steps:
+    `image.buildEnv` (never secrets).
 
 ## References
 

package/skills/kindgi-getting-started/SKILL.md

@@ -14,7 +14,7 @@ description: >
   primitive.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.4"
+version: "0.3.7"
 sdk_version: "0.0.0"
 pack_languages: [node]
 ---
@@ -158,8 +158,82 @@ Most of the setup is automatable, but two require your knowledge:
 - **Real LLM provider credentials** — the built-in dev-echo provider
   returns canned responses (great for the loop test, useless for real
   agents). It is a fallback, so it steps aside once a real provider is
-  registered — `kindgi providers register --preset=anthropic` with the
-  key in `.env`; see `kindgi-authoring-providers`.
+  registered. Declare it in `kindgi.config.ts`
+  (`providers: [{ preset: 'anthropic' }]`, the key in `.env`) and `kindgi dev`
+  registers it on every boot, in every worktree and after `--reset`; or once,
+  by hand: `kindgi providers register --preset=anthropic`. See
+  `kindgi-authoring-providers`.
+
+## Your app and Kindgi's data
+
+When the app keeps something a run did (a ticket a flow triaged, an answer
+an agent gave), its own row stores the run's id, in a column such as
+`kindgi_run_id`. The app starts the run and reads the rest through the API,
+server side, with `createClient()` from `@kindgi/sdk/client`:
+
+```ts
+import { createClient } from '@kindgi/sdk/client';
+
+const kindgi = createClient(); // KINDGI_API_URL + KINDGI_API_TOKEN
+const run = await kindgi.runs.start({
+  flow: 'my-pack.triage-ticket',
+  input: { ticketId },
+  options: { wait: false }, // the run id now; run.finished tells you when it ends
+});
+// save run.id as the ticket's kindgi_run_id
+```
+
+
+- **Status, output, timing:** `kindgi.runs.get(runId)`
+  (`GET /v1/runs/{runId}`); status and timing only: `kindgi.runs.progress(runId)`.
+- **The audit, step by step:** `kindgi.runs.journal(runId)`
+  (`GET /v1/runs/{runId}/journal`).
+- **Where an agent's answer came from:** `kindgi.provenance.get(runId)`
+  (`GET /v1/provenance/{runId}`). A flow run has none of its own: each agent
+  step's `step.completed` entry in the flow's journal names its turn's run
+  (`payload.output.runId`).
+- **What it cost:** `kindgi.cost.usage.query({ rootRunId: runId })`
+  (`GET /v1/cost/records?rootRunId={runId}`): `.items`, one record per model
+  call, with its `model`, `usage` (`promptTokens`, `completionTokens`) and
+  `costUsd` (a number, US dollars), a flow's agent steps included. For one
+  customer's spend, see below.
+- **When a run finished:** the `run.finished` webhook (the run's id, its
+  outcome and its cost in `data.run.usage`; no output, so then `runs.get`),
+  not polling.
+
+**One customer's spend:** give each customer an org, and start their runs in a
+project of that org. Then one call sums their month:
+
+```ts
+import type { Timestamp } from '@kindgi/sdk/types';
+
+// Once per customer. Project slugs are unique across the tenant: put the customer in them.
+const org = await kindgi.orgs.create({ slug: 'acme-customer-one', name: 'Customer one' });
+const project = await kindgi.projects.create({ orgId: org.id, slug: 'acme-customer-one-app', name: 'App' });
+// save org.id and project.id on the customer's row; start their runs with projectId: project.id
+
+const now = new Date();
+const month = await kindgi.cost.usage.summary({
+  scope: { kind: 'org', orgId: org.id },
+  from: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString() as Timestamp,
+  to: now.toISOString() as Timestamp, // exclusive
+  groupBy: ['month'],
+});
+// month.totalUsd; month.groups[i].key ({ month: '2026-10' }), .totalUsd, .tokens
+```
+
+Docs: https://docs.kindgi.com/v0.1/guides/observability/cost-per-run/
+
+Show it in the app's own UI. **Never:**
+
+- **query Kindgi's database**, even on the app's own Postgres server, and
+  never map its tables into the app's ORM. Its schema is private and changes
+  with every release (migrations only go forward), row-level security guards
+  every tenant query, and a runtime Kindgi hosts gives no database access.
+- **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/
 
 ## References
 

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

@@ -103,6 +103,10 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
 - `ctx.run_id` — the run (an agent turn or a flow step) the call belongs to.
 - `ctx.request_id` — this call, e.g. the model's tool-call id; useful
   for logs and idempotency keys.
+- `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
+  it with these instead of trusting it.
 - `ctx.cancellation` — fires when the call's deadline passes or the
   caller disconnects. An `async def` handler is also cancelled at its
   next `await`. A `def` handler keeps running in its thread: check

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

@@ -14,7 +14,7 @@ description: >
   kindgi-python-authoring-agents; models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
+version: "0.1.5"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -26,7 +26,7 @@ sources:
 # Getting started with Kindgi in Python
 
 > **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI (a Node 22+ program) is the one on `PATH`. Python
+> `kindgi` CLI (a Node 22.12+ program) is the one on `PATH`. Python
 > commands run in the pack's environment: `uv run …`.
 
 ## What a pack is
@@ -129,8 +129,16 @@ kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prom
 kindgi providers register --preset=anthropic
 ```
 
-It takes over at the next turn. Details and other providers:
-`kindgi-authoring-providers`.
+It takes over at the next turn. That registration is in this project's dev
+database only. To have `kindgi dev` register it on every boot, in every
+worktree and after `--reset`, declare it in `pyproject.toml` instead:
+
+```toml
+[[tool.kindgi.providers]]
+preset = "anthropic"   # its key, ANTHROPIC_API_KEY, from the env files
+```
+
+Details and other providers: `kindgi-authoring-providers`.
 
 `uv run python -m kindgi.pack index --pack-dir .` prints what Kindgi
 sees (the index); `kindgi dev` reports a broken file with its path and
@@ -182,6 +190,67 @@ for event in client.runs.stream(str(run.id)):
 `AsyncKindgi` is the asyncio twin. `kindgi dev` prints the URL and the
 token; `.kindgirc.json` in the pack holds them for the CLI.
 
+## Your app and Kindgi's data
+
+When the app keeps something a run did (a ticket a flow triaged, an answer
+an agent gave), its own row stores the run's id, in a column such as
+`kindgi_run_id` (`run = client.runs.start(flow=…, input=…, options={"wait": False})`,
+then `run.id`). The app reads the rest through the API, server side, with
+`Kindgi()` from `kindgi.client`:
+
+- **Status, output, timing:** `client.runs.get(run_id)`
+  (`GET /v1/runs/{runId}`); status and timing only: `client.runs.progress(run_id)`.
+- **The audit, step by step:** `client.runs.journal(run_id).data`
+  (`GET /v1/runs/{runId}/journal`).
+- **Where an agent's answer came from:** `client.provenance.get(run_id)`
+  (`GET /v1/provenance/{runId}`). A flow run has none of its own: each agent
+  step's `step.completed` entry in the flow's journal names its turn's run
+  (`entry.payload["output"]["runId"]`).
+- **What it cost:** `client.cost.records.list(root_run_id=run_id).data`
+  (`GET /v1/cost/records?rootRunId={runId}`): one record per model call,
+  with its `model`, `usage` (`prompt_tokens`, `completion_tokens`) and
+  `cost_usd` (a float, US dollars), a flow's agent steps included. For one
+  customer's spend, see below.
+- **When a run finished:** the `run.finished` webhook (the run's id, its
+  outcome and its cost in `data.run.usage`; no output, so then `runs.get`),
+  not polling.
+
+**One customer's spend:** give each customer an org, and start their runs in a
+project of that org. Then one call sums their month:
+
+```python
+from datetime import datetime, timezone
+
+# Once per customer. Project slugs are unique across the tenant: put the customer in them.
+org = client.orgs.create(slug="acme-customer-one", name="Customer one")
+project = client.projects.create(org_id=str(org.id), slug="acme-customer-one-app", name="App")
+# save org.id and project.id on the customer's row; start their runs with project_id=project.id
+
+now = datetime.now(timezone.utc)
+month = client.cost.aggregate(
+    group_by="month",
+    scope_kind="org",
+    scope_id=str(org.id),
+    from_=now.replace(day=1, hour=0, minute=0, second=0, microsecond=0).isoformat(),
+    to=now.isoformat(),  # exclusive
+)
+# 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/
+
+Show it in the app's own UI. **Never:**
+
+- **query Kindgi's database**, even on the app's own Postgres server, and
+  never map its tables into the app's ORM (SQLAlchemy, Django models). Its
+  schema is private and changes with every release (migrations only go
+  forward), row-level security guards every tenant query, and a runtime
+  Kindgi hosts gives no database access.
+- **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/
+
 ## Build an image
 
 `kindgi build --env=<name>` (an `[tool.kindgi.environments.<name>]`