@kindgi/tools 0.0.0-bootstrap.0 → 0.1.0

package/src/registry.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import semver from 'semver';
+
+import type { Result, TenantId, ToolId } from '@kindgi/types';
+
+import type {
+  DuplicateToolVersionError,
+  InvalidVersionRangeError,
+  ToolError,
+  ToolNotFoundError,
+  ToolVersionNotFoundError,
+  ToolVersionUnresolvableError,
+} from './errors.js';
+import type { AnyTool } from './types.js';
+
+/**
+ * In-process registry mapping (tool id, version) → tool. Multi-version:
+ * a single id may carry multiple compiled implementations at different
+ * exact semver strings; agent bindings reference tools by (id, range)
+ * and dispatch resolves at run start via `resolve(id, range)` (npm-
+ * compatible semver grammar, backed by `semver.maxSatisfying`).
+ *
+ * Not tenant-scoped. Multi-tenant deployments hold one registry per
+ * tenant or encode tenancy into tool ids. Cross-tenant tool sharing goes
+ * through the policy engine, not through registry design.
+ */
+export interface ToolRegistry {
+  /**
+   * Register a tool. Fails with `duplicate-tool-version` if the same
+   * `(id, version)` pair is already registered. Distinct versions of the
+   * same id may coexist — that's the whole point of the versioned model.
+   */
+  register(tool: AnyTool): Result<void, ToolError>;
+  /**
+   * Return the latest active version for an id. "Latest" is defined by
+   * `semver.compare` — the highest exact version present. For callers
+   * that have no version range to resolve. Prefer `resolve(id, range)`
+   * when a range is available.
+   */
+  get(id: ToolId): Result<AnyTool, ToolError>;
+  /** Return a specific `(id, version)` pair. */
+  getVersion(id: ToolId, version: string): Result<AnyTool, ToolError>;
+  /**
+   * Resolve a semver range against the versions registered under `id`.
+   * Uses `semver.maxSatisfying` (npm grammar). Distinct failure modes:
+   *   - `tool-not-found`         → id has no versions at all
+   *   - `invalid-version-range`  → range string is grammatically broken
+   *   - `tool-version-unresolvable` → id is present but no version satisfies
+   */
+  resolve(id: ToolId, range: string): Result<ToolResolution, ToolError>;
+  has(id: ToolId): boolean;
+  hasVersion(id: ToolId, version: string): boolean;
+  /**
+   * Return every registered tool version, sorted by id then by version
+   * descending. Callers that want a per-id latest-only view use
+   * `.get(id)` per id.
+   */
+  list(): readonly AnyTool[];
+  /** Return every id with at least one registered version. */
+  ids(): readonly ToolId[];
+  /** Return every version registered under `id`, sorted descending. */
+  versions(id: ToolId): readonly string[];
+  /**
+   * The registry for one tenant: lookups on the returned registry
+   * (`get`, `getVersion`, `resolve`, `list`, …) answer for `tenantId`
+   * only. Multi-tenant implementations load that tenant's tools (e.g.
+   * from a persistent store, cached) and return a view bound to it —
+   * never shared per-call state, so concurrent turns of different
+   * tenants cannot see each other's tools. A single-tenant registry
+   * (like `createToolRegistry`) returns itself. Callers resolve a
+   * turn's tools through the returned registry.
+   */
+  forTenant(tenantId: TenantId): Promise<ToolRegistry>;
+  /**
+   * Optional cache invalidation. Storage-backed implementations call
+   * this from the write path (`POST /v1/tools`, unregister, reinstate)
+   * so the next `forTenant(tenantId)` re-reads from the persistent
+   * store. Without it, tools published after a tenant was loaded stay
+   * invisible to that tenant's cached view. In-memory implementations
+   * leave it undefined — there is no cache to invalidate.
+   */
+  readonly invalidate?: (tenantId: TenantId) => void;
+}
+
+/** The outcome of a successful `resolve(id, range)` lookup. */
+export interface ToolResolution {
+  readonly tool: AnyTool;
+  /**
+   * The exact version picked by `maxSatisfying`. Callers capture this in
+   * provenance + telemetry so a replay can pin against the same version.
+   */
+  readonly resolvedVersion: string;
+}
+
+/**
+ * Create an empty tool registry. Seeds are registered in order; the seed
+ * throws on duplicate `(id, version)` so accidental clobbers of a
+ * running tool fail loud at boot.
+ */
+export function createToolRegistry(seed: readonly AnyTool[] = []): ToolRegistry {
+  // id → version → tool. Nested map so we can iterate versions per id
+  // cheaply and cache a sorted-version list.
+  const tools = new Map<ToolId, Map<string, AnyTool>>();
+
+  function versionsDesc(id: ToolId): string[] {
+    const versions = tools.get(id);
+    if (versions === undefined) return [];
+    return [...versions.keys()].sort((a, b) => semver.rcompare(a, b));
+  }
+
+  const registry: ToolRegistry = {
+    register(tool: AnyTool): Result<void, ToolError> {
+      let versions = tools.get(tool.id);
+      if (versions === undefined) {
+        versions = new Map();
+        tools.set(tool.id, versions);
+      }
+      if (versions.has(tool.version)) {
+        const dup: DuplicateToolVersionError = {
+          code: 'duplicate-tool-version',
+          message: `Tool "${tool.id}@${tool.version}" is already registered`,
+          id: tool.id,
+          version: tool.version,
+        };
+        return { kind: 'err', error: dup };
+      }
+      versions.set(tool.version, tool);
+      return { kind: 'ok', value: undefined };
+    },
+    get(id: ToolId): Result<AnyTool, ToolError> {
+      const desc = versionsDesc(id);
+      if (desc.length === 0) {
+        const err: ToolNotFoundError = {
+          code: 'tool-not-found',
+          message: `No tool registered with id "${id}"`,
+          id,
+        };
+        return { kind: 'err', error: err };
+      }
+      // desc is sorted desc — desc[0] is highest.
+      const latest = tools.get(id)?.get(desc[0]!);
+      if (latest === undefined) {
+        const err: ToolNotFoundError = {
+          code: 'tool-not-found',
+          message: `No tool registered with id "${id}"`,
+          id,
+        };
+        return { kind: 'err', error: err };
+      }
+      return { kind: 'ok', value: latest };
+    },
+    getVersion(id: ToolId, version: string): Result<AnyTool, ToolError> {
+      const found = tools.get(id)?.get(version);
+      if (found === undefined) {
+        if (tools.get(id) === undefined) {
+          const err: ToolNotFoundError = {
+            code: 'tool-not-found',
+            message: `No tool registered with id "${id}"`,
+            id,
+          };
+          return { kind: 'err', error: err };
+        }
+        const err: ToolVersionNotFoundError = {
+          code: 'tool-version-not-found',
+          message: `Tool "${id}" has no version "${version}" registered`,
+          id,
+          version,
+        };
+        return { kind: 'err', error: err };
+      }
+      return { kind: 'ok', value: found };
+    },
+    resolve(id: ToolId, range: string): Result<ToolResolution, ToolError> {
+      const versions = tools.get(id);
+      if (versions === undefined || versions.size === 0) {
+        const err: ToolNotFoundError = {
+          code: 'tool-not-found',
+          message: `No tool registered with id "${id}"`,
+          id,
+        };
+        return { kind: 'err', error: err };
+      }
+      if (semver.validRange(range) === null) {
+        const err: InvalidVersionRangeError = {
+          code: 'invalid-version-range',
+          message: `Version range "${range}" for tool "${id}" is not a valid semver range`,
+          id,
+          range,
+        };
+        return { kind: 'err', error: err };
+      }
+      const available = [...versions.keys()];
+      const picked = semver.maxSatisfying(available, range);
+      if (picked === null) {
+        const err: ToolVersionUnresolvableError = {
+          code: 'tool-version-unresolvable',
+          message: `Tool "${id}" has no version satisfying "${range}" (available: ${available
+            .sort((a, b) => semver.rcompare(a, b))
+            .join(', ')})`,
+          id,
+          range,
+          availableVersions: available.sort((a, b) => semver.rcompare(a, b)),
+        };
+        return { kind: 'err', error: err };
+      }
+      const tool = versions.get(picked);
+      // maxSatisfying returned a version we just enumerated — guaranteed
+      // to be in the map. The `if (tool === undefined)` branch is a
+      // defensive no-op for the type system.
+      if (tool === undefined) {
+        const err: ToolVersionNotFoundError = {
+          code: 'tool-version-not-found',
+          message: `Tool "${id}" resolved to "${picked}" but the version is missing (internal)`,
+          id,
+          version: picked,
+        };
+        return { kind: 'err', error: err };
+      }
+      return { kind: 'ok', value: { tool, resolvedVersion: picked } };
+    },
+    has(id: ToolId): boolean {
+      const versions = tools.get(id);
+      return versions !== undefined && versions.size > 0;
+    },
+    hasVersion(id: ToolId, version: string): boolean {
+      return tools.get(id)?.has(version) ?? false;
+    },
+    list(): readonly AnyTool[] {
+      const out: AnyTool[] = [];
+      const ids = [...tools.keys()].sort();
+      for (const id of ids) {
+        for (const v of versionsDesc(id)) {
+          const tool = tools.get(id)?.get(v);
+          if (tool !== undefined) out.push(tool);
+        }
+      }
+      return out;
+    },
+    ids(): readonly ToolId[] {
+      const out: ToolId[] = [];
+      for (const [id, versions] of tools) {
+        if (versions.size > 0) out.push(id);
+      }
+      return out;
+    },
+    versions(id: ToolId): readonly string[] {
+      return versionsDesc(id);
+    },
+    async forTenant(): Promise<ToolRegistry> {
+      // Single-tenant: the same registry serves every tenant.
+      return registry;
+    },
+  };
+
+  for (const tool of seed) {
+    const r = registry.register(tool);
+    if (r.kind === 'err') throw new Error(`seed failed: ${r.error.message}`);
+  }
+  return registry;
+}

package/src/spec-registry.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ToolContext, ToolSpec } from './types.js';
+
+/**
+ * A synthesizer takes a declarative `ToolSpec` variant and returns
+ * the runtime handler that satisfies its semantics. Framework core
+ * ships the `'http'` synthesizer (see `./http.ts` for the impl).
+ * Third-party kinds (SQL, MCP, webhook, ...) register their own via
+ * `registerToolSpecSynthesizer(kind, fn)` at module load.
+ *
+ * The synthesizer receives the fully-validated spec (author-time
+ * validation has already run) and returns a handler with the
+ * standard `(input, ctx) => Promise<output>` signature. Any
+ * per-invoke correctness bits (URL substitution, abort chaining,
+ * secret resolution) live inside the handler the synthesizer
+ * returns.
+ */
+/** What the runtime gives a synthesized handler. */
+export interface ToolSpecSynthesizerOptions {
+  /**
+   * The fetch for requests to the hosts a spec names. The runtime passes
+   * one that refuses the hosts its deployment forbids
+   * (`KINDGI_TENANT_HOST_ACCESS`: the cloud metadata endpoints and the
+   * server's own host). Absent: the global `fetch`.
+   */
+  readonly fetch?: typeof fetch;
+}
+
+export type ToolSpecSynthesizer<TSpec extends ToolSpec = ToolSpec> = (
+  spec: TSpec,
+  toolId: string,
+  options?: ToolSpecSynthesizerOptions,
+) => (input: unknown, ctx: ToolContext) => Promise<unknown>;
+
+// Registry keyed by the spec's `kind` discriminant. Populated by
+// side-effect imports of first-party synthesizer packages (`./http.js`
+// registers `'http'`) or third-party equivalents.
+const registry = new Map<string, ToolSpecSynthesizer>();
+
+/**
+ * Register a synthesizer for a given `spec.kind`. First-party kinds
+ * register at framework load; third-party kinds register when their
+ * package's module runs. Overwriting an existing kind throws — kind
+ * ownership must be explicit to avoid silent shadowing.
+ */
+export function registerToolSpecSynthesizer<TSpec extends ToolSpec>(
+  kind: TSpec['kind'],
+  synthesizer: ToolSpecSynthesizer<TSpec>,
+): void {
+  if (registry.has(kind)) {
+    throw new Error(
+      `ToolSpec synthesizer for kind "${kind}" is already registered. Multiple registrations for the same kind indicate shadowing — unregister first if replacement is intended.`,
+    );
+  }
+  registry.set(kind, synthesizer as ToolSpecSynthesizer);
+}
+
+/**
+ * Look up the synthesizer for a `ToolSpec`. Returns `undefined` when
+ * no synthesizer is registered for the spec's `kind` — callers
+ * (typically `defineTool`) surface this as a clear "no synthesizer
+ * for kind X" error at define time.
+ */
+export function getToolSpecSynthesizer(kind: string): ToolSpecSynthesizer | undefined {
+  return registry.get(kind);
+}
+
+/**
+ * Test-only helper. Removes a registered synthesizer so tests can
+ * verify the "no synthesizer registered" error path without process
+ * teardown. Not exported from the package barrel — call it via
+ * direct import in tests only.
+ */
+export function _unregisterToolSpecSynthesizer(kind: string): void {
+  registry.delete(kind);
+}

package/src/tool.schema.json

@@ -0,0 +1,297 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/tool.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Tool",
+  "description": "A tool definition. Authored once; the runtime picks transport (native in-process for tools built into the runtime, MCP over the wire for cross-process / cross-org / third-party tools). Every tool declares its typed I/O, its context needs (typed DI), and its side-effects — enabling policy enforcement and parallel scheduling by the kernel.",
+  "type": "object",
+  "required": ["id", "description", "version", "input", "output"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique tool identifier. Convention: '<pack>.<tool>' (e.g. 'acme.verify-citation') or a bare id for tools built into Kindgi."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human- and LLM-readable description of what this tool does. Load-bearing: this is what the LLM sees when deciding to call the tool."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "input": {
+      "type": "object",
+      "description": "JSON Schema for the tool input. MUST validate under Draft 2020-12."
+    },
+    "output": {
+      "type": "object",
+      "description": "JSON Schema for the tool output. MUST validate under Draft 2020-12."
+    },
+    "needs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Need"
+      },
+      "description": "Typed context requirements — named slots (e.g. `tenant`, `run`, `blob`, `memory:facts`) the runtime injects via `ToolContext`. Declarative: not checked when a flow is loaded. `needsSpec` is the typed, discriminated form."
+    },
+    "effects": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Effect"
+      },
+      "description": "Declared side-effects. Enables policy enforcement (can this tool run in this tenant?), safe parallelization (are two calls conflicting?), and causal provenance."
+    },
+    "transport": {
+      "type": "string",
+      "enum": ["auto", "native", "mcp"],
+      "default": "auto",
+      "description": "Transport hint. 'auto' (default) lets the runtime pick native when possible, MCP otherwise. 'native' requires in-process execution. 'mcp' requires MCP execution. Deployment-time concern; authoring is unchanged."
+    },
+    "mcpEndpoint": {
+      "type": "string",
+      "description": "If transport = 'mcp' (or resolved to MCP by 'auto'), the MCP endpoint URI. Format: 'mcp+stdio://<command>', 'mcp+http://<url>', 'mcp+sse://<url>'."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Free-form annotations (author, docs URL, tags). Not interpreted by the kernel."
+    },
+    "sandbox": {
+      "type": "string",
+      "enum": ["none", "context-isolated", "strict"],
+      "description": "Isolation posture the runtime enforces around the handler. Optional additive field."
+    },
+    "mutating": {
+      "type": "boolean",
+      "description": "Semantic marker: `true` when this tool causes observable side effects (writes state, calls external APIs with mutations, sends messages). Read-only tools set `false`. Absent defaults to `true`. Consumed by the HITL default classifier — a read-only tool passes straight through, a mutating tool asks on first use."
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Sandbox-enforced resource caps at dispatch. Optional additive field.",
+      "properties": {
+        "memMB": { "type": "integer", "minimum": 1 },
+        "cpuMs": { "type": "integer", "minimum": 1 }
+      },
+      "required": ["memMB", "cpuMs"]
+    },
+    "network": {
+      "type": "object",
+      "description": "Network egress policy. Optional additive field. Discriminated on `kind`.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "kind": { "type": "string", "enum": ["none", "unrestricted"] } },
+          "required": ["kind"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "type": "string", "const": "allowlist" },
+            "hosts": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+          },
+          "required": ["kind", "hosts"]
+        }
+      ]
+    },
+    "needsSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed discriminated needs (env / secrets / config / capabilities / bindings). Optional additive field.",
+      "properties": {
+        "env": { "type": "object", "additionalProperties": { "type": "object" } },
+        "secrets": { "type": "object", "additionalProperties": { "type": "object" } },
+        "config": { "type": "object", "additionalProperties": { "type": "object" } },
+        "capabilities": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "bindings": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "codeArtifactRef": {
+      "description": "Handler-artifact pointer. Discriminated on `kind`: `oci` is the deploy-pipeline shape (image + module path + artifactVersion); `filesystem` is the local-development shape — absolute host path at the pack's on-disk handler file. Production servers SHOULD reject `filesystem`.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "oci" },
+            "imageRef": { "type": "string", "minLength": 1 },
+            "modulePath": { "type": "string", "minLength": 1 },
+            "artifactVersion": { "type": "string", "minLength": 1 }
+          },
+          "required": ["kind", "imageRef", "modulePath", "artifactVersion"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "filesystem" },
+            "modulePath": { "type": "string", "minLength": 1 }
+          },
+          "required": ["kind", "modulePath"]
+        }
+      ]
+    },
+    "spec": {
+      "description": "Declarative handler spec. Discriminated on `kind`; the framework's synthesizer registry maps kind → runtime handler. Mutually exclusive with an imperative handler at author time.",
+      "oneOf": [{ "$ref": "#/$defs/HttpToolSpec" }]
+    }
+  },
+  "$defs": {
+    "Need": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The named context slot (e.g. 'tenant', 'db', 'run', 'provenance', 'memory:facts', 'blob')."
+        },
+        "optional": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
+    "Effect": {
+      "type": "object",
+      "required": ["kind"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "reads",
+            "writes",
+            "deletes",
+            "network",
+            "spawns-run",
+            "emits-event",
+            "external-side-effect",
+            "sensitive-data-egress"
+          ]
+        },
+        "resource": {
+          "type": "string",
+          "description": "Resource identifier (e.g. 'memory:facts', 'blob:*', 'external:api.example.com'). Used by the policy engine to authorize the effect."
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "ToolSecretRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["envName", "name"],
+      "properties": {
+        "envName": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 }
+      }
+    },
+    "HttpHeaderSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "value"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "value": { "type": "string" }
+      }
+    },
+    "HttpAuthSpec": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "secretRef"],
+          "properties": {
+            "kind": { "const": "bearer" },
+            "secretRef": { "$ref": "#/$defs/ToolSecretRef" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "headerName", "secretRef"],
+          "properties": {
+            "kind": { "const": "header" },
+            "headerName": { "type": "string", "minLength": 1 },
+            "secretRef": { "$ref": "#/$defs/ToolSecretRef" }
+          }
+        }
+      ]
+    },
+    "HttpRequestBodySpec": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": { "kind": { "const": "json-input" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": { "kind": { "const": "input-passthrough" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "template"],
+          "properties": {
+            "kind": { "const": "text" },
+            "template": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "HttpToolSpec": {
+      "type": "object",
+      "description": "Declarative HTTP-invocation spec. Attached to `ToolManifest.spec` under the discriminant `kind: 'http'`. The runtime `Tool.handler` is synthesized by the 'http' spec synthesizer to perform URL-template substitution, secret-ref resolution via `ToolContext.resolveSecret`, and the outbound fetch. All fields serialize cleanly to JSON.",
+      "additionalProperties": false,
+      "required": ["kind", "method", "urlTemplate"],
+      "properties": {
+        "kind": { "const": "http" },
+        "method": {
+          "type": "string",
+          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]
+        },
+        "urlTemplate": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL template with `{param}` placeholders substituted from the tool's input at invoke time."
+        },
+        "headers": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/HttpHeaderSpec" }
+        },
+        "authorization": { "$ref": "#/$defs/HttpAuthSpec" },
+        "requestBody": { "$ref": "#/$defs/HttpRequestBodySpec" },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Wall-clock timeout in ms. Default 30000."
+        },
+        "parseJson": {
+          "type": "boolean",
+          "description": "When true (default), the response body is parsed as JSON before returning to the invoker."
+        },
+        "successStatus": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["min", "max"],
+          "properties": {
+            "min": { "type": "integer", "minimum": 100, "maximum": 599 },
+            "max": { "type": "integer", "minimum": 100, "maximum": 599 }
+          }
+        }
+      }
+    }
+  }
+}