Pack index

@kindgi/specs/pack-index.schema.json, schema version 1.4.0.

The index.json a pack build emits: the pack's tools, guardrails, agents and flows as data, plus where each tool handler and guardrail check lives. A runtime registers the pack's primitives from it, and a pack service loads the modules it names and resolves every call by id. Any indexer (the TypeScript kindgi-index, the Python python -m kindgi.pack index) emits this shape. Determinism: every list is sorted by id (code-unit order), keys are sorted at every level, the file is UTF-8 JSON indented by two spaces with a trailing newline, and integral numbers carry no fraction, so the same source indexes to the same bytes. Consumers refuse an envelope v they don't recognize.

• v (1, required): Envelope version. Additive fields on an existing entry shape don't bump it.
• packId (string, required): The pack's id (pack.id in the pack config).
• packVersion (string, required): The pack's version (pack.version in the pack config).
• artifactVersion (string, required): This build of the pack. A pack build pins it; a local indexer defaults to YYYYMMDD.N (UTC date, N counting up from the previous index of the same day).
• publishedAt (string (date-time), required): When the index was built — ISO 8601 UTC with milliseconds (2026-09-20T14:32:07.104Z). A pack build pins it for reproducible output.
• tools (array of tool, required): Tools with handler code, sorted by id.
• guardrails (array of guardrail, required): Guardrails whose check is pack code, sorted by id.
• agents (array of agent, required): Agents, sorted by id.
• flows (array of flow, required): Flows, sorted by id.
• env (object): The process environment the pack's code reads (env in kindgi.config; [tool.kindgi.env] in pyproject.toml). Absent when the pack declares none. A deployment injects exactly these names. With a required name unset or empty, the pack service isn't ready (unless its env check is warn); /readyz and /v1/info name it. Not needsSpec.env: that is per-call context.
  • required (array of envName, required): Names the pack service needs, set and non-empty, to be ready. Sorted.
  • optional (array of envName, required): Names the pack reads when present. Sorted. Never also in required.

Definitions

envName

A process environment variable name. KINDGI_* names configure Kindgi and are never a pack's.

Type: string

modulePath

The source file the primitive was declared in, relative to the pack root: forward slashes, no leading ./ (tools/echo/index.ts, tools/ledger.py). A pack service resolves it against its module root; a build may point it at a bundle instead. Several entries may share one module (a Python module can declare several tools).

Type: string

jsonSchema

A JSON Schema (Draft 2020-12) in wire form. Open: any JSON Schema keyword is allowed, so this node carries no additionalProperties restriction.

Type: object

openObject

An object whose shape is defined by the primitive's own schema (tool.schema.json, guardrail.schema.json, agent.schema.json, flow.schema.json); the index carries it as declared.

Type: object

tool

• id (string, required): Tool id — what a pack service resolves an invoke by.
• description (string): What the tool does — the model reads it.
• version (string): The tool's version. A caller that names a version gets tool-version-mismatch when it differs.
• input (jsonSchema, required): JSON Schema the input must satisfy; the pack service validates before running the handler.
• output (jsonSchema, required): JSON Schema the handler's return value must satisfy; the pack service validates it.
• effects (array of openObject): Declared side effects (tool.schema.json effects).
• needs (array of openObject): Declared needs (tool.schema.json needs).
• needsSpec (openObject): Typed needs (tool.schema.json needsSpec).
• sandbox (string): Isolation posture (tool.schema.json sandbox).
• limits (openObject): Resource limits (tool.schema.json limits).
• network (openObject): Network policy (tool.schema.json network).
• mutating (boolean): Whether the tool may change something (tool.schema.json mutating). false makes it read-only: it runs in a dry run, and per-tool approval gates don't ask before it by default. Absent means it may.
• spec (openObject): A declarative tool's spec (tool.schema.json spec, e.g. kind: 'http'). A runtime runs a tool that has one itself, resolving its secretRefs, rather than calling the pack service.
• modulePath (modulePath, required)

guardrail

• id (string, required): Guardrail id.
• name (string): Human-readable name.
• kind (string, required): How the guardrail is checked (guardrail.schema.json kind).
• action (openObject, required): What a violation does (guardrail.schema.json action, with on-violation).
• severity (string): Severity (guardrail.schema.json severity).
• scope (openObject): When the guardrail applies (guardrail.schema.json scope).
• checkModulePath (modulePath, required)
• checkId (string): The check's id — what a pack service resolves a check-invoke by. Absent: the guardrail's id.
• configSchema (jsonSchema): JSON Schema of the check's config.
• config (openObject): What the check is configured with (guardrail.schema.json config).
• sandbox (string): Isolation posture.
• limits (openObject): Resource limits.
• network (openObject): Network policy.

agent

An agent as declared (agent.schema.json); the runtime validates it in full when it registers the pack.

• id (string, required)
• version (string, required)
• name (string, required)
• instructions (string, required)
• capabilities (array of any, required)
• tools (array of object, required)
  • id (string, required)
  • version (string, required): Semver range.
• retrieval (array of any)
• guardrails (array of string)
• budget (openObject)
• parameters (array of any)
• preferredProvider (string)
• preferredModel (string)
• description (string)
• tags (array of string)
• conversationPolicy (openObject)
• output (openObject): Typed output ({ schema, name?, maxRepairs? }), its schema already JSON Schema.
• toolErrors (openObject): How the agent's turns retry failed tool calls ({ maxRetries?, retryOn? }, agent.schema.json toolErrors).
• modulePath (modulePath, required)

flow

A flow as declared (flow.schema.json), plus the kernel payload version.

• id (string, required)
• version (string, required)
• name (string)
• description (string)
• nodes (array of any, required)
• edges (array of any, required)
• maxParallelism (integer)
• metadata (openObject)
• output (openObject)
• kernelPayloadVersion (1, required): Version of the flow payload inside the index, independent of the envelope v.
• modulePath (modulePath, required)