@kindgi/cli 0.1.4 → 0.1.5

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

@@ -12,8 +12,8 @@ description: >
   authoring agents is covered by kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.4"
-sdk_version: "0.1.4"
+version: "0.4.5"
+sdk_version: "0.1.5"
 pack_languages: [node]
 sources:
   - packages/tools/src/types.ts
@@ -115,6 +115,16 @@ The handler gets the **parsed** input, typed `z.infer` of `input` (Zod's output
 
 The output side is the reverse: the advertised output schema requires every field, defaulted ones included. Return them all.
 
+### Logging from the handler
+
+`ctx.log` is a logger bound to the call: its records carry the run's ids, the tool's id and the trace id. It has `info`, `warn`, `error`, `debug` and `trace`, each `(message, fields?)`. The pack service sets it; a context your own code builds (a test's) may not, so write `ctx.log?.`:
+
+```ts
+ctx.log?.info('refund issued', { orderId, amountCents });
+```
+
+Put values in `fields`, never in the message. Log ids, 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, not only by the person the data is about. Docs: https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
+
 ### Configuration and secrets
 
 A secret that belongs to the tenant — an API key a customer gives you — is declared, and read from `ctx.secrets`:
@@ -132,6 +142,32 @@ const defined = defineTool({
 
 The runtime resolves every declared secret on every call, for the call's tenant, in its env (`KINDGI_ENV`; in `kindgi dev`, `local`: the pack's `.env` and `.env.local`). It checks each value against its schema, and fails the call, naming the secret, when one is missing or doesn't match. Every declared secret is required, so in a runtime call `ctx.secrets` holds them all; it's optional in the type because a unit test builds its own context and passes `secrets: { CITATOR_KEY: '…' }`.
 
+A value that differs per tenant, org or project but isn't secret (a base URL, a region, an account id) is an **env value**: declared in `needsSpec.env`, read from `ctx.env`:
+
+```ts
+const defined = defineTool({
+  // …id, description, version, input, output, effects…
+  needsSpec: {
+    env: {
+      ORDERS_BASE_URL: { type: 'string', pattern: '^https://' },
+      ORDERS_REGION: { type: 'string', enum: ['eu', 'us'], default: 'eu' },
+    },
+  },
+  handler: async ({ orderId }, ctx) => ({
+    url: `${ctx.env?.ORDERS_BASE_URL}/${ctx.env?.ORDERS_REGION}/orders/${orderId}`,
+  }),
+});
+```
+
+- **Which value a call gets:** its project's, else its org's, else the tenant's, in the runtime's env; a schema `default` makes a name optional. The values a call used are recorded with it, so a retry or a resume sees the same ones.
+- **Setting them:** `kindgi env set ORDERS_REGION us --scope=project:<project-id> --env=local` (or `--scope=tenant`, for every project). Changing a value that's already set takes `--force`.
+- **A declared value nobody set** stops the call before the tool runs. For a tool `acme-orders.needs-account` that declares `ACME_ACCOUNT_ID`, the message reads:
+  ```text
+  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 (`needsSpec.secrets`), never an env value.
+- **In a unit test:** pass `env: { … }` in the context `invokeTool` gets.
+
 Everything else comes from the process environment: `process.env.CITATOR_URL`. The pack service runs with the pack's env files in `kindgi dev`, and with the container's environment in an image. Declare the names your code reads in `kindgi.config.ts`, `env: { required: ['CITATOR_URL'], optional: [...] }`: a deployment injects exactly those, a pack service missing a required one isn't ready and says which, and `kindgi dev` warns about it. Values per environment go in `environments.<name>.env`, secrets only as references.
 
 ## Declarative HTTP spec
@@ -176,6 +212,15 @@ export default defined.value;
 
 So declare `mutating: false` on every tool that only reads, and never on one that writes.
 
+A tool that writes also says what it writes, in `effects`, beside `mutating: true`:
+
+```ts
+  effects: [{ kind: 'writes', resource: 'acme:refunds' }],
+  mutating: true,
+```
+
+The kinds are `reads`, `writes`, `deletes`, `network`, `spawns-run`, `emits-event`, `external-side-effect` and `sensitive-data-egress` (`EFFECT_KINDS` in `@kindgi/tools`); `defineTool` refuses any other. `resource` is free text naming what the tool touches. A read-only tool keeps `effects: []`.
+
 ## Tool id convention
 
 `<pack-id>.<tool-name>` — kebab-case, dot-namespaced. The `<pack-id>`
@@ -210,6 +255,25 @@ range at run start. Compatible tool updates (patch, minor) reach the
 agent without editing agent source; breaking updates (major) require
 the agent-author to opt in.
 
+## Testing a tool
+
+Put a tool's tests beside it, `tools/<tool>/index.test.ts`. Discovery skips `*.test.*` and `*.spec.*` files (`.ts`, `.js`, `.mjs`, `.cjs`), so the indexer never loads a test as a primitive: don't move tests elsewhere to keep them out. `invokeTool(tool, input, ctx)` from `@kindgi/sdk/define` calls the tool the way Kindgi does, schemas included, and returns a `Result`. Its `ctx` needs a `tenantId` and an `abortSignal` (`ToolContext` in `@kindgi/tools`); the rest is optional. vitest doesn't typecheck, so a context missing them still passes the test: run `tsc --noEmit` too.
+
+```ts
+import { invokeTool } from '@kindgi/sdk/define';
+import type { TenantId } from '@kindgi/sdk/types';
+
+const ctx = { tenantId: 'test' as TenantId, abortSignal: new AbortController().signal };
+// add `env: { STORE_URL: '…' }` for a tool that reads a declared env value
+const result = await invokeTool(lookupOrder, { orderId: 'ord_1001' }, ctx);
+```
+
+`kindgi test` runs the pack's tests with vitest (`vitest run`; `--watch` keeps watching).
+
+## Shared code
+
+Code several tools share (schemas, a client, helpers) goes outside `tools/`, for example in `lib/` beside it. Discovery loads every `.ts`, `.js` and `.mjs` file under `tools/` (tests aside) as a primitive, so a helper there fails the index. Don't put it in the app's own source either: import the app's functions from where they are, and keep what's Kindgi's in the pack's folder.
+
 ## Wiring the tool onto an agent
 
 Agents reference tools via `ToolRef[]`, NOT `string[]`. Each entry is

package/dist/sdk-skills/kindgi-framework-feedback/SKILL.md

@@ -14,9 +14,9 @@ description: >
   diagnostic output into durable input for framework improvement.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.0"
-sdk_version: "0.1.4"
-pack_languages: [node, python]
+version: "0.4.2"
+sdk_version: "0.1.5"
+pack_languages: [node, python, java, scala]
 ---
 
 # Capturing framework feedback
@@ -25,7 +25,8 @@ pack_languages: [node, python]
 > (`@kindgi/cli`), not a global command. Run it through the project's
 > package manager — `pnpm exec kindgi …`, `npx --no kindgi …` (npm),
 > `yarn kindgi …` or `bun run kindgi …`. A Python pack (`[tool.kindgi]` in
-> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`.
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`. A Java
+> or Scala pack (`kindgi.config.json`) runs the CLI it pins: `./kindgiw …`.
 > Commands below are written `kindgi …` for brevity.
 
 You just spent time diagnosing a Kindgi-framework issue. That diagnostic

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.3.8"
-sdk_version: "0.1.4"
+sdk_version: "0.1.5"
 pack_languages: [node]
 ---
 

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

@@ -0,0 +1,220 @@
+---
+name: kindgi-java-authoring-agents
+description: >
+  Covers writing agents for a Kindgi pack in Java (`com.kindgi:kindgi-pack`):
+  `Agent.define(id)` as a `public static final` field, wiring tools (`Tool`
+  objects or an id with a version range) and guardrails, capabilities and
+  model choice (preferredProvider / preferredModel), conversation policy,
+  turn budgets, prompt parameters, a typed answer from a record, and
+  tool-error retries, all as data. Load this whenever you are authoring or
+  editing code in a Java pack's agents packages (a pack whose
+  `kindgi.config.json` says `"language": "java"`), defining an agent, or
+  when the user asks to add, change or refactor one. Java tools are covered
+  by kindgi-java-authoring-tools, Java guardrails by
+  kindgi-java-authoring-guardrails, connecting a real model by
+  kindgi-authoring-providers.
+type: core
+library: "kindgi-pack (Java)"
+version: "0.1.0"
+sdk_version: "0.1.5"
+pack_languages: [java]
+sources:
+  - sdks/java/kindgi-pack/README.md
+  - sdks/java/kindgi-pack/src/main/java/com/kindgi/pack/Agent.java
+  - packages/specs/schemas/agent.schema.json
+  - packages/specs/schemas/pack-index.schema.json
+---
+
+# Authoring Kindgi agents in Java
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), and `./kindgiw` runs that version, so every
+> `kindgi <command>` below runs as `./kindgiw <command>`. Maven runs as
+> `./mvnw`.
+>
+> Java support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+An **agent** is a versioned, model-driven orchestrator. It's made of:
+- instructions (a prompt template);
+- the tools it may call;
+- the capabilities its model needs;
+- guardrails that gate its answer;
+- optionally, a conversation policy.
+
+In a Java pack it is **data**: a `public static final Agent` field of a class
+in an `agents` package. The model runs in the Kindgi runtime, not in your
+JVM. Your Java code runs only inside the agent's tools and guardrail checks.
+
+## Ask before building
+
+"Add an agent" is a conversation opener, not a ticket. Before writing a
+file, ask:
+
+- **What should the agent do?** The purpose drives everything else.
+- **Which tools does it need?** New ones, or existing ones?
+- **Multi-turn or one-shot?** History changes the shape.
+- **Any rules it must respect?** Those become guardrails.
+
+The pack's sample agent proves the runtime works end to end. It is not the
+shape to imitate unless the user asks for that.
+
+## An agent
+
+```java
+// src/main/java/acme/agents/BriefWriter.java
+package acme.agents;
+
+import acme.guardrails.ResponseNotEmpty;
+import acme.tools.Echo;
+import com.kindgi.pack.Agent;
+import java.util.List;
+import java.util.Map;
+
+/** acme.brief-writer: drafts a brief's argument from the case facts. */
+public final class BriefWriter {
+  /** The typed answer: the final message must be JSON of this shape. */
+  public record Brief(String argument, List<String> citations) {}
+
+  public static final Agent AGENT = Agent.define("acme.brief-writer")
+      .version("0.1.0")
+      .name("Brief Writer")
+      .description("Drafts appellate briefs from a case file; cites precedents.")
+      .instructions("You are drafting a brief in {{ jurisdiction }}. The user gives the case facts; you write "
+          + "a Section IV argument citing at least two precedents. Check every cite with the echo tool "
+          + "before using it. Never invent one.")
+      .capability(Map.of("needs", List.of(Map.of("feature", "tool-use"))))
+      .tool(Echo.TOOL)
+      .guardrail(ResponseNotEmpty.GUARDRAIL)
+      .set("parameters", List.of(Map.of("name", "jurisdiction", "type", "string", "required", true)))
+      .set("conversationPolicy", Map.of("historyLimit", 20))
+      .set("budget", Map.of("maxSteps", 8, "maxCostUsd", 0.5, "maxWallMs", 60_000))
+      .set("toolErrors", Map.of("maxRetries", 1, "retryOn", List.of("invalid-arguments", "unknown-tool")))
+      .output(Brief.class)
+      .build();
+
+  private BriefWriter() {}
+}
+```
+
+- Tools and guardrails are the pack's own fields, imported like any class:
+  `.tool(Echo.TOOL)`, `.guardrail(ResponseNotEmpty.GUARDRAIL)`.
+- **`build()` needs a version, a name and instructions.** Anything missing
+  is an error where the agent is defined, and the indexer reports it with
+  the file.
+- **Every other field is `set(field, value)`, keyed as on the wire:** the
+  field and its maps are camelCase (`conversationPolicy`, `maxSteps`,
+  `historyLimit`), as `agent.schema.json` names them. The indexer checks
+  each agent against the pack index's schema, and `kindgi dev` reports a
+  mistake with its file.
+- A class may hold several agents, each in its own `static final` field.
+
+## Field by field
+
+- **`id`:** `<pack-id>.<agent-name>`, kebab-case, dot-namespaced.
+- **`version`:** an exact semver. Conversations pin the version they started
+  on.
+- **`name`, `description`**, and `set("tags", List.of(…))`: for people and
+  listings. The model never sees the description.
+- **`instructions`:** a LiquidJS template. `{{ variable }}` comes from
+  `parameters` or the runtime's own variables (`today`, `now`, `agent.*`,
+  `conversation.*`). It's rendered strictly: an unknown variable fails the
+  turn. Write it as a brief for a capable colleague: what to do, which tools
+  to prefer, what to refuse, the quality bar. Name a tool by what it does
+  ("the verify-citation tool"), never by its dotted id. The model sees ids in
+  its provider's form (`acme__verify-citation` for Anthropic and
+  OpenAI-compatible models), and a dotted id in the instructions can make it
+  call a name it wasn't given. `instructions(Map.of("prompt", …, "version", …))`
+  references a registered prompt block instead.
+- **`capability(Map)`:** what the model must support, such as
+  `Map.of("needs", List.of(Map.of("feature", "tool-use")))`. Call it once per
+  capability. The turn routes its first capability to pick a provider and
+  model; with none declared, the turn fails.
+- **`tool(Tool)`:** pins that tool's version (its own, or the pack's).
+  **`tool(id, range)`** is a tool of another pack, with a semver **range**
+  (`"^1.0.0"`); the highest active matching version is picked at turn
+  start. An agent with no tools is chat-only.
+- **`guardrail(Guardrail)`** or **`guardrail(id)`:** evaluated once per turn
+  on the final answer, before it is stored. An id with no registered
+  guardrail fails the turn.
+- **`set("parameters", List.of(Map.of("name", …, "type", …, "required", …)))`:**
+  inputs the caller supplies per run. They fill `{{ … }}` in the
+  instructions.
+- **`set("preferredProvider", "anthropic")`, `set("preferredModel", "claude-haiku-4-5")`:**
+  soft hints. The router prefers them when they satisfy the capabilities.
+  To *require* a model, put it in the capability:
+  `Map.of("needs", List.of(Map.of("feature", "tool-use"), Map.of("models", Map.of("allow", List.of("claude-haiku-4-5")))))`.
+- **`set("conversationPolicy", …)`:** `historyLimit` caps the prior messages
+  loaded, and `hitl` configures approval gates. Absent, the turn loads the
+  full history with no gates. A tenant's `hitl` policy can tighten the gates
+  (a shorter timeout, a higher reviewer role, stricter per tool), never
+  loosen them.
+- **`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.
+- **`output(Type.class)`:** a typed answer, with its schema derived from the
+  record. 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 fails (`output-schema-violation`). For `maxRepairs` or a schema of
+  your own, use `set("output", Map.of("schema", …, "maxRepairs", 2))`. The
+  parsed answer is the turn result's `output`. In a flow it is
+  `nodeOutputs.<step>.output.<field>`.
+- **`set("toolErrors", …)`:** `maxRetries` and `retryOn`. A failed tool call
+  goes back to the model as the call's result, so it can fix the call. The
+  default kinds are `invalid-arguments` and `unknown-tool` (nothing ran). Add
+  `tool-error` only when retrying the tool is safe. Each retry costs a step.
+
+## Which model answers
+
+Agents run on a registered model provider: the router picks one whose
+models satisfy the capabilities. `kindgi dev` gives a new pack `dev-echo`, a
+**fallback** that answers only while no other provider fits. It calls the
+first tool and replies "⚠ dev-echo isn't a real model: …", then "Tool
+responded: …". The turn carries the `fallback-provider` and
+`dev-echo-not-a-model` warnings. dev-echo can't fill in any other tool
+input, and can't give a typed answer: an agent with `output` fails with
+`output-schema-violation` until a real model is registered. To register one,
+see `kindgi-authoring-providers` (`./kindgiw providers register --preset=anthropic`,
+or `"providers": [{"preset": "anthropic"}]` in `kindgi.config.json`).
+
+## Iterating
+
+Save the file: `kindgi dev` recompiles, re-indexes, and the next run uses
+it, with no restart. Bump `version` when you break what callers rely on (a
+removed parameter, an incompatible output), not on every save.
+
+Run an agent from another terminal in the pack directory:
+
+```sh
+./kindgiw runs start --agent=acme.brief-writer --input='{"userMessage":"…","parameters":{"jurisdiction":"US"}}'
+```
+
+or from a Java app with the client (`kindgi-java-getting-started`).
+
+## Common mistakes
+
+1. **Building an agent without asking what it should do.** Copying the
+   sample's shape answers the wrong question.
+2. **No `capability(…)`.** The turn can't pick a model.
+3. **Java names inside the maps.** `set("budget", Map.of("max_steps", 4))`
+   isn't a budget: the keys are the wire's camelCase (`maxSteps`,
+   `historyLimit`, `maxRetries`).
+4. **An unregistered guardrail id.** Pass the `Guardrail` field, or make sure
+   the id is one the tenant has.
+5. **`{{ variable }}` not in `parameters`.** The turn fails when the
+   instructions render.
+6. **An agent that isn't a `static final` field.** Only static fields are
+   indexed.
+7. **A tight `maxWallMs` with a real model.** 15 s aborts real turns under
+   load; 60 s is a safer start.
+8. **Expecting dev-echo to give a typed answer.** It can't: register a real
+   model first.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or kindgi-pack (the index dropping a field, a
+misleading error, the router picking the wrong model) and not in the pack's
+code, load `kindgi-framework-feedback` and file it with
+`./kindgiw feedback write`.