@kindgi/tools 0.0.0-bootstrap.0 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,508 @@
+import type { ZodLikeSchema } from '@kindgi/schema';
+import type { TenantId, ToolId, UserId } from '@kindgi/types';
+/**
+ * JSON Schema for a tool's input/output. Author-supplied, Draft 2020-12.
+ * Kept as `unknown` here — the loader validates that the provided value is
+ * a legal Ajv schema at `defineTool` time.
+ */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+/** Closed set of effect kinds Kindgi recognises. Matches @kindgi/specs/tool.schema.json. */
+export declare const EFFECT_KINDS: readonly ["reads", "writes", "deletes", "network", "spawns-run", "emits-event", "external-side-effect", "sensitive-data-egress"];
+export type EffectKind = (typeof EFFECT_KINDS)[number];
+/**
+ * A declared side-effect. Enables policy enforcement (can this tool run in
+ * this tenant?), safe parallelization (are two invocations conflicting?),
+ * and causal provenance annotation.
+ */
+export interface Effect {
+    readonly kind: EffectKind;
+    /**
+     * Resource identifier the effect targets — for example `memory:facts`,
+     * `blob:*`, `external:api.example.com`. Opaque to this package; the
+     * policy engine interprets it when enforcing tenant policy.
+     */
+    readonly resource?: string;
+    readonly notes?: string;
+}
+/**
+ * A typed context requirement — a named slot the tool expects the runtime
+ * to supply. The name matches an entry in the tenant's provider registry
+ * (`tenant`, `db`, `memory:facts`, `blob`, etc.). Not enforced by this
+ * package; declarative metadata for capability + policy layers.
+ */
+export interface Need {
+    readonly name: string;
+    readonly optional?: boolean;
+}
+/**
+ * The transport-neutral context a tool receives at invocation. Whether the
+ * tool is called from a kernel run (in-process) or over MCP (remote), the
+ * caller synthesises a `ToolContext` and passes it in.
+ *
+ * Deliberately narrow — kernel-specific things like the journal or
+ * NodeContext helpers stay on the kernel side of the bridge.
+ */
+export interface ToolContext {
+    /**
+     * Tenant scope for the invocation. Every tool call is tenant-scoped;
+     * cross-tenant access is denied by policy at the kernel layer.
+     * Handlers use this to key persistence (per-tenant DBs, per-tenant
+     * blob buckets) and to route capability calls (secrets scoped to
+     * this tenant only).
+     */
+    readonly tenantId: TenantId;
+    /**
+     * The acting principal, if the runtime can identify one. Optional
+     * because some invocations (scheduled background jobs) are system-run.
+     */
+    readonly principal?: UserId;
+    /**
+     * The kernel run the call belongs to, when a run invokes the tool — an
+     * agent turn or a flow step. Stable across every call the run makes.
+     */
+    readonly runId?: string;
+    /**
+     * Correlation id for this individual call (the model's tool-call id,
+     * an MCP request id, a webhook id). Opaque to tools; useful for logs,
+     * provenance and idempotency.
+     */
+    readonly requestId?: string;
+    /**
+     * Signal that fires when the caller wants the tool to abort — kernel
+     * cancel/failure teardown, MCP client disconnect, HTTP request cancel.
+     * Cooperative handlers should observe this and exit early.
+     */
+    readonly abortSignal: AbortSignal;
+    /**
+     * Optional secret resolver. HTTP tools built via
+     * `defineTool({spec: {kind: 'http', ...}})` uses this at invoke time to resolve its
+     * declared `secret_ref`s to plaintext credentials. Absent → HTTP
+     * tools that declare a `secret_ref` throw with a clear
+     * "resolveSecret not wired" error; tools that don't need secrets
+     * (dev-echo, in-process handlers) ignore it.
+     *
+     * Caller responsibility: the dispatch site (the agent turn's
+     * `dispatch-tools` step in `@kindgi/agents`, a flow node that runs
+     * the tool, an MCP server) populates this from the deployment's
+     * `SecretBinding` scoped to the invoking tenant.
+     */
+    readonly resolveSecret?: (ref: ToolSecretRef) => Promise<string>;
+    /**
+     * The secrets this tool declares in `needsSpec.secrets`, by name,
+     * resolved by the runtime for this call: for the call's tenant, in the
+     * env the runtime serves (`KINDGI_ENV`; in `kindgi dev`, `local` — the
+     * pack's `.env` and `.env.local`). Every declared name is present: one
+     * the runtime can't resolve, or whose value doesn't match its schema,
+     * fails the call before the handler runs. Absent when the tool
+     * declares none, and wherever nothing resolves them — a unit test
+     * passes its own.
+     */
+    readonly secrets?: Readonly<Record<string, string>>;
+}
+/**
+ * Pointer to a tenant-scoped secret used by a declarative tool
+ * (e.g. `{kind: 'http'}` with a bearer secretRef). Same shape as
+ * `ProviderSecretRef` in `@kindgi/api` — both are `{envName, name}`
+ * references resolved via the deployment's `SecretBinding`. Kept
+ * local to `@kindgi/tools` so the tools package doesn't take an
+ * api-layer dep.
+ */
+export interface ToolSecretRef {
+    readonly envName: string;
+    readonly name: string;
+}
+/**
+ * Isolation posture the runtime enforces around the handler. Three tiers:
+ *   - `'none'`              — no isolation. First-party framework handlers
+ *                             only; registration rejects tenant-authored
+ *                             tools declaring `'none'`.
+ *   - `'context-isolated'`  — same-process `node:vm` context. NOT a
+ *                             security boundary; prevents accidental state
+ *                             bleed.
+ *   - `'strict'`            — real container / MicroVM isolation. Required
+ *                             for anything running untrusted code.
+ *
+ * Sandbox declaration + capability manifest = the handler's declared
+ * capability contract.
+ */
+export type SandboxMode = 'none' | 'context-isolated' | 'strict';
+/**
+ * Runtime resource caps enforced by the sandbox layer at dispatch. Wall-
+ * clock (`wallMs`) intentionally NOT here — it belongs on the incoming
+ * edge as `EdgePolicy.timeoutMs`.
+ */
+export interface RuntimeLimits {
+    readonly memMB: number;
+    readonly cpuMs: number;
+}
+/**
+ * Network egress policy for the sandboxed handler. Discriminated on
+ * `kind`; `allowlist` carries the explicit host list, the other two are
+ * unary.
+ */
+export type NetworkPolicy = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'allowlist';
+    readonly hosts: readonly string[];
+} | {
+    readonly kind: 'unrestricted';
+};
+/**
+ * Typed dependency declarations for handler code, carried on the
+ * manifest as `needsSpec`. Each slot is optional; a handler that
+ * consumes none of a slot omits it entirely.
+ *
+ * In this shape (the serialisable projection carried in `index.json`
+ * and over the wire) values in `env` / `secrets` / `config` are JSON
+ * Schemas. An authoring tool that accepts Zod converts with
+ * `z.toJSONSchema()` before the manifest is built.
+ *
+ * `capabilities` names capability-router features (e.g. `'embedding'`);
+ * `bindings` names deployment-plugged binding keys (e.g. `'blob'`).
+ *
+ * The manifest field is `needsSpec` because `needs` holds the flat
+ * `Need[]` list of named context slots; both fields exist side by side.
+ */
+export interface TypedNeeds {
+    readonly env?: Readonly<Record<string, JsonSchema>>;
+    readonly secrets?: Readonly<Record<string, JsonSchema>>;
+    readonly config?: Readonly<Record<string, JsonSchema>>;
+    readonly capabilities?: readonly string[];
+    readonly bindings?: readonly string[];
+}
+/**
+ * Handler-artifact pointer. Discriminated on `kind`:
+ *
+ * - `'oci'`         — production. Populated by the deploy pipeline
+ *                     once the image is built
+ *                     + signed. `modulePath` resolves inside the pinned
+ *                     `imageRef`. `artifactVersion` is the auto-assigned
+ *                     `YYYYMMDD.N` version pinning one deploy (distinct
+ *                     from `ToolManifest.version` — semver, pack-authored).
+ * - `'filesystem'`  — dev-mode. Populated by local development tooling
+ *                     at registration time. `modulePath` is an
+ *                     absolute host filesystem path pointing at the
+ *                     pack's on-disk handler file. Production
+ *                     deployments SHOULD reject this variant — the
+ *                     substrate is dev-only.
+ *
+ * Absent on framework-owned in-process manifests.
+ */
+export type CodeArtifactRef = {
+    readonly kind: 'oci';
+    readonly imageRef: string;
+    readonly modulePath: string;
+    readonly artifactVersion: string;
+} | {
+    readonly kind: 'filesystem';
+    readonly modulePath: string;
+};
+/**
+ * The serialisable projection of a tool — everything except the runtime
+ * handler binding. Matches `@kindgi/specs/tool.schema.json` and round-trips over
+ * the wire. This is what MCP and cross-runtime discovery consume.
+ *
+ * ## Additive extensions
+ *
+ * `sandbox`, `limits`, `network`, `needsSpec`, `codeArtifactRef` are
+ * optional extensions that the dispatch, SDK and deploy layers
+ * populate + honor. Registrations that don't set them leave them
+ * undefined; consumers that don't know about them ignore the fields.
+ */
+export interface ToolManifest {
+    /**
+     * Globally-unique tool identifier. Convention: `<pack-id>.<tool-name>`
+     * (kebab-case, dot-namespaced) — e.g. `acme.verify-citation`,
+     * `demo.echo`. The `<pack-id>` prefix scopes the tool to its pack;
+     * `<tool-name>` names the operation. Enforced as a `ToolId` brand;
+     * `defineTool` refuses ids that don't match the convention.
+     */
+    readonly id: ToolId;
+    /**
+     * Human-readable one-liner describing what the tool does. Surfaced
+     * to the model as part of the tool definition (`ModelToolDefinition.description`)
+     * — the model uses it to decide when to call. Write it for the
+     * model: what the tool DOES, what it RETURNS, and when to prefer
+     * it over other tools. Skip implementation details.
+     */
+    readonly description: string;
+    /**
+     * Semver — REQUIRED. Every tool registered in a Kindgi deployment
+     * ships versioned; an agent's `tools[].version` is a semver range
+     * matched against these versions at dispatch time via
+     * `semver.maxSatisfying`. Enforced by
+     * `defineTool(...)` at the API boundary.
+     */
+    readonly version: string;
+    /**
+     * JSON Schema Draft 2020-12 for the tool's input. Handed to the
+     * model as the tool's parameter schema so it can generate valid
+     * calls. `invokeTool` validates every incoming input against this
+     * before invoking the handler — invalid input surfaces as a
+     * `bad-input` error, never reaches the handler.
+     *
+     * Zod authors: pass a Zod v4 schema to `defineTool({input: zSchema})`;
+     * the framework converts to JSON Schema at author time and preserves
+     * the Zod schema on `tool.inputZod` for TS-side inference.
+     */
+    readonly input: JsonSchema;
+    /**
+     * JSON Schema Draft 2020-12 for the tool's output. `invokeTool`
+     * validates the handler's return value against this before surfacing
+     * it — a handler that returns off-schema fails with
+     * `bad-output`. Same Zod-conversion story as `input`.
+     *
+     * Prefer explicit schemas over `type: 'object', additionalProperties: true`
+     * — the model uses the output schema to interpret tool results
+     * downstream.
+     */
+    readonly output: JsonSchema;
+    /**
+     * Named context slots the tool depends on (e.g. `tenant`, `run`,
+     * `blob`, `memory:facts`). Framework-level dependencies the tool
+     * expects the runtime to inject via `ToolContext`. Declarative: not
+     * checked when a flow is loaded. `needsSpec` is the typed,
+     * discriminated form (env / secrets / config / capabilities /
+     * bindings).
+     */
+    readonly needs?: readonly Need[];
+    /**
+     * Declared side-effects the tool causes — an `EFFECT_KINDS` kind
+     * (`writes`, `network`, `external-side-effect`, …), optionally with
+     * the `resource` it targets. Consumed by policy + audit machinery for
+     * effect-based gating (e.g. "block any tool with an
+     * `external-side-effect` in a dry-run"). Distinct from `mutating` —
+     * `effects` names WHICH effects; `mutating` is a coarser boolean.
+     */
+    readonly effects?: readonly Effect[];
+    /**
+     * How the tool is dispatched at invoke time. `'native'` (default)
+     * uses the framework's in-process dispatch; `'mcp'` routes through
+     * the Model Context Protocol endpoint declared at `mcpEndpoint`;
+     * `'auto'` picks native if a handler exists, else mcp. Most
+     * pack-authored tools omit this and default to native.
+     */
+    readonly transport?: 'auto' | 'native' | 'mcp';
+    /**
+     * MCP server URL for `transport: 'mcp'` tools. Ignored when
+     * transport is native. See the Model Context Protocol spec for the
+     * expected endpoint shape.
+     */
+    readonly mcpEndpoint?: string;
+    /**
+     * Free-form key/value metadata that rides along with the manifest.
+     * Not interpreted by the framework — passthrough for pack-authored
+     * annotations (e.g. `{owner: 'team-legal', ticket: 'PROJ-123'}`).
+     * Surfaced in `GET /v1/tools/:id` responses for tooling.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * Semantic marker: `true` when this tool causes observable side
+     * effects (writes state, calls external APIs with mutations, sends
+     * messages, etc.). Read-only tools (queries, computations, retrievals)
+     * set `false`. Absent = defaults to `true` (safer — the framework's
+     * `never_ask / ask_on_first_use / always_ask` policy defaults hinge
+     * on this flag; mistakenly marking a mutating tool as read-only would
+     * bypass HITL, while the reverse only adds friction).
+     *
+     * Consumed by `@kindgi/agents` as the per-tool HITL default when an
+     * agent's `conversationPolicy.hitl.tools` sets neither an override
+     * nor a `default` for the tool — a read-only tool passes straight
+     * through, a mutating tool asks on first use.
+     */
+    readonly mutating?: boolean;
+    /** Isolation posture — see `SandboxMode`. */
+    readonly sandbox?: SandboxMode;
+    /** Memory + CPU caps enforced by the sandbox at dispatch. */
+    readonly limits?: RuntimeLimits;
+    /** Network egress policy the sandbox honors. */
+    readonly network?: NetworkPolicy;
+    /**
+     * Discriminated typed-dependency declarations (env / secrets / config /
+     * capabilities / bindings). See `TypedNeeds` for the shape.
+     */
+    readonly needsSpec?: TypedNeeds;
+    /**
+     * Signed pointer at the deploy-time OCI image + module path carrying
+     * the handler bytes. Absent for in-process manifests.
+     */
+    readonly codeArtifactRef?: CodeArtifactRef;
+    /**
+     * Declarative handler specification. When present, the runtime
+     * `Tool.handler` is synthesized from this spec — the manifest
+     * carries everything needed for a first-party framework
+     * synthesizer to build the fetch/query/dispatch call at register
+     * time. Author writes the spec; framework owns the correctness
+     * bits (timeouts, aborts, secret resolution, retries).
+     *
+     * Discriminated on `spec.kind`. The framework ships `'http'` (see
+     * `HttpToolSpec`) as the first-party kind; other kinds plug in via
+     * `registerToolSpecSynthesizer`.
+     *
+     * `spec` and `handler` are MUTUALLY EXCLUSIVE at `defineTool` time
+     * — a tool is either declarative or imperative. Mixed usage
+     * fails to compile.
+     *
+     * The full JSON-serializable manifest (spec included) is what
+     * `POST /v1/tools` accepts — declarative tools can be registered
+     * from configuration without shipping code.
+     */
+    readonly spec?: ToolSpec;
+}
+/**
+ * Union of all declarative handler specifications the framework
+ * synthesizes into runtime handlers. Discriminated on `kind`; `'http'`
+ * is the only kind in this union. Adding a kind does not change the
+ * `defineTool({ spec })` author surface.
+ */
+export type ToolSpec = HttpToolSpec;
+/**
+ * Declarative HTTP-invocation spec. All fields serialize cleanly to
+ * JSON — no runtime closures. Credentials appear ONLY as
+ * `secret_ref` pointers; the actual plaintext is resolved at invoke
+ * time via `ToolContext.resolveSecret`.
+ */
+export interface HttpToolSpec {
+    /**
+     * Discriminant. Every declarative tool spec self-identifies via
+     * `kind` so the framework's synthesizer registry can route to the
+     * right handler builder.
+     */
+    readonly kind: 'http';
+    /**
+     * HTTP method. `GET` and `DELETE` typically carry no body;
+     * `POST`, `PUT`, `PATCH` typically do. The default body shape is
+     * `json-input` (see `requestBody`).
+     */
+    readonly method: HttpMethod;
+    /**
+     * URL template with `{param}` placeholders substituted from the
+     * tool's input at invoke time. Example:
+     * `https://api.github.com/repos/{owner}/{repo}/issues/{number}`.
+     * Every placeholder must correspond to an input property; missing
+     * substitutions surface as a `handler-error` at invoke time.
+     */
+    readonly urlTemplate: string;
+    /**
+     * Static or templated headers. Values may include `{param}`
+     * placeholders substituted from the tool's input (e.g.
+     * `X-Trace-Id: {requestId}`). For credentialed headers use
+     * `authorization` — it keeps secret references out of `headers`.
+     */
+    readonly headers?: readonly HttpHeaderSpec[];
+    /**
+     * Optional authentication injected as a header on the outbound
+     * request. Union kinds:
+     *   - `bearer`  — writes `Authorization: Bearer <secret>` where
+     *                 `<secret>` is the plaintext of `secret_ref`.
+     *   - `header`  — writes `<headerName>: <secret>` verbatim (for
+     *                 vendors that use a non-`Authorization` header,
+     *                 e.g. `X-API-Key`).
+     */
+    readonly authorization?: HttpAuthSpec;
+    /**
+     * Request-body specification for methods that carry a body
+     * (`POST`, `PUT`, `PATCH`, `DELETE`). Absent → no body sent.
+     *
+     * The default body strategy is `{kind: 'json-input'}` — the tool's
+     * INPUT (after URL-template substitution consumes its keys) is
+     * JSON-serialized as the body. `input-passthrough` sends the raw
+     * input object (JSON body) without URL-consuming any keys, so
+     * keys used in the URL template appear redundantly in the body
+     * too. Choose based on the target API's expected shape.
+     */
+    readonly requestBody?: HttpRequestBodySpec;
+    /**
+     * Wall-clock timeout in milliseconds. Enforced via AbortController.
+     * Defaults to 30_000 (30s) when absent — matches typical vendor
+     * SLOs.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * When the response body should be parsed as JSON before returning
+     * to the invoker. Default: `true`. Set `false` for adapters that
+     * hand-parse (rare) or for text-only endpoints.
+     */
+    readonly parseJson?: boolean;
+    /**
+     * Acceptable status-code range. Responses outside this range are
+     * treated as `handler-error` with the response text as the message.
+     * Default: `[200, 299]` (any 2xx).
+     */
+    readonly successStatus?: {
+        readonly min: number;
+        readonly max: number;
+    };
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface HttpHeaderSpec {
+    readonly name: string;
+    readonly value: string;
+}
+export type HttpAuthSpec = {
+    readonly kind: 'bearer';
+    readonly secretRef: ToolSecretRef;
+} | {
+    readonly kind: 'header';
+    readonly headerName: string;
+    readonly secretRef: ToolSecretRef;
+};
+export type HttpRequestBodySpec = {
+    readonly kind: 'json-input';
+} | {
+    readonly kind: 'input-passthrough';
+} | {
+    readonly kind: 'text';
+    readonly template: string;
+};
+/**
+ * The runtime object: manifest + local handler. Only exists in-process;
+ * `handler` is stripped when the tool is projected to a manifest for
+ * serialisation, MCP exposure, or discovery.
+ *
+ * Type parameters are caller-asserted — the runtime validates against
+ * `input` / `output` JSON Schema, not the TS type — but let authors write
+ * typed handlers when they know the shape.
+ */
+export interface Tool<TInput = unknown, TOutput = unknown> extends ToolManifest {
+    /**
+     * The runtime handler — the function `invokeTool` actually calls.
+     * Types are caller-asserted (matches the `defineTool` generics);
+     * the runtime validates against `input` / `output` JSON Schema at
+     * every invocation, not the TS type.
+     */
+    readonly handler: (input: TInput, ctx: ToolContext) => Promise<TOutput>;
+    /**
+     * The original Zod schema, preserved when the tool was authored with a
+     * Zod v4 schema at the `input` slot. Present iff the author passed a
+     * Zod schema to `defineTool`; otherwise `undefined`. Wire form is
+     * always the converted JSON Schema on `input` — this field exists so
+     * TS callers can `z.infer<typeof tool.inputZod>` for static types.
+     *
+     * Explicitly `ZodLikeSchema | undefined` (not a bare optional marker):
+     * the more specific `DefinedTool<TInSchema, TOutSchema>` returned by
+     * `defineTool` narrows this to the exact Zod schema type when Zod is
+     * used, and to `undefined` when JSON Schema is used. Consumers reading
+     * a heterogeneous `AnyTool` see the union and narrow with `!== undefined`.
+     */
+    readonly inputZod?: ZodLikeSchema | undefined;
+    /** Symmetric to `inputZod` for the `output` slot. */
+    readonly outputZod?: ZodLikeSchema | undefined;
+}
+/**
+ * Type-erased alias for cross-boundary storage (registries, arrays of mixed
+ * tools). Handlers are contravariant in their input type, so a
+ * `Tool<{ text: string }, ...>` is not assignable to `Tool<unknown, unknown>`
+ * — this alias uses `unknown` on both sides so heterogeneous collections
+ * type-check without lying about the runtime shape.
+ */
+export type AnyTool = Tool<any, any>;
+/** MCP-compatible tool manifest. Narrower shape than `ToolManifest`. */
+export interface McpToolManifest {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** Closed set of effect kinds Kindgi recognises. Matches @kindgi/specs/tool.schema.json. */
+export const EFFECT_KINDS = [
+    'reads',
+    'writes',
+    'deletes',
+    'network',
+    'spawns-run',
+    'emits-event',
+    'external-side-effect',
+    'sensitive-data-egress',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAYjC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO;IACP,QAAQ;IACR,SAAS;IACT,SAAS;IACT,YAAY;IACZ,aAAa;IACb,sBAAsB;IACtB,uBAAuB;CACf,CAAC"}

package/package.json

@@ -1,7 +1,67 @@
 {
   "name": "@kindgi/tools",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "Tool authoring shape + registry + invocation for Kindgi. A tool is a typed, effect-declared unit of work — the same definition runs in-process for one flow, over MCP for another. Pure — no kernel dependency; the kernel bridges tools to node handlers separately.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/tools"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/tools#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "SPEC.md",
+    "type-manifest.json"
+  ],
+  "dependencies": {
+    "@kindgi/schema": "0.1.0",
+    "@kindgi/types": "0.1.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "semver": "^7.6.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@kindgi/specs": "0.1.0",
+    "@types/node": "^22.10.5",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^4.6.5"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}