@kindgi/tools 0.0.0-bootstrap.0 → 0.1.1

package/dist/registry.d.ts

@@ -0,0 +1,87 @@
+import type { Result, TenantId, ToolId } from '@kindgi/types';
+import type { ToolError } 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 declare function createToolRegistry(seed?: readonly AnyTool[]): ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE9D,OAAO,KAAK,EAGV,SAAS,EAIV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACpE;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IACtE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD;;;;OAIG;IACH,IAAI,IAAI,SAAS,OAAO,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,GAAG,IAAI,SAAS,MAAM,EAAE,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACrD;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CACpD;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,SAAS,OAAO,EAAO,GAAG,YAAY,CAgK9E"}

package/dist/registry.js

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import semver from 'semver';
+/**
+ * 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 = []) {
+    // id → version → tool. Nested map so we can iterate versions per id
+    // cheaply and cache a sorted-version list.
+    const tools = new Map();
+    function versionsDesc(id) {
+        const versions = tools.get(id);
+        if (versions === undefined)
+            return [];
+        return [...versions.keys()].sort((a, b) => semver.rcompare(a, b));
+    }
+    const registry = {
+        register(tool) {
+            let versions = tools.get(tool.id);
+            if (versions === undefined) {
+                versions = new Map();
+                tools.set(tool.id, versions);
+            }
+            if (versions.has(tool.version)) {
+                const dup = {
+                    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) {
+            const desc = versionsDesc(id);
+            if (desc.length === 0) {
+                const err = {
+                    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 = {
+                    code: 'tool-not-found',
+                    message: `No tool registered with id "${id}"`,
+                    id,
+                };
+                return { kind: 'err', error: err };
+            }
+            return { kind: 'ok', value: latest };
+        },
+        getVersion(id, version) {
+            const found = tools.get(id)?.get(version);
+            if (found === undefined) {
+                if (tools.get(id) === undefined) {
+                    const err = {
+                        code: 'tool-not-found',
+                        message: `No tool registered with id "${id}"`,
+                        id,
+                    };
+                    return { kind: 'err', error: err };
+                }
+                const err = {
+                    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, range) {
+            const versions = tools.get(id);
+            if (versions === undefined || versions.size === 0) {
+                const err = {
+                    code: 'tool-not-found',
+                    message: `No tool registered with id "${id}"`,
+                    id,
+                };
+                return { kind: 'err', error: err };
+            }
+            if (semver.validRange(range) === null) {
+                const err = {
+                    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 = {
+                    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 = {
+                    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) {
+            const versions = tools.get(id);
+            return versions !== undefined && versions.size > 0;
+        },
+        hasVersion(id, version) {
+            return tools.get(id)?.has(version) ?? false;
+        },
+        list() {
+            const out = [];
+            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() {
+            const out = [];
+            for (const [id, versions] of tools) {
+                if (versions.size > 0)
+                    out.push(id);
+            }
+            return out;
+        },
+        versions(id) {
+            return versionsDesc(id);
+        },
+        async forTenant() {
+            // 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;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/spec-registry.d.ts

@@ -0,0 +1,48 @@
+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>;
+/**
+ * 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 declare function registerToolSpecSynthesizer<TSpec extends ToolSpec>(kind: TSpec['kind'], synthesizer: ToolSpecSynthesizer<TSpec>): void;
+/**
+ * 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 declare function getToolSpecSynthesizer(kind: string): ToolSpecSynthesizer | undefined;
+/**
+ * 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 declare function _unregisterToolSpecSynthesizer(kind: string): void;
+//# sourceMappingURL=spec-registry.d.ts.map

package/dist/spec-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-registry.d.ts","sourceRoot":"","sources":["../src/spec-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,MAAM,MAAM,mBAAmB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,IAAI,CACnE,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,0BAA0B,KACjC,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAO5D;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,SAAS,QAAQ,EAChE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EACnB,WAAW,EAAE,mBAAmB,CAAC,KAAK,CAAC,GACtC,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjE"}

package/dist/spec-registry.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+// 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();
+/**
+ * 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(kind, synthesizer) {
+    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);
+}
+/**
+ * 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) {
+    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) {
+    registry.delete(kind);
+}
+//# sourceMappingURL=spec-registry.js.map

package/dist/spec-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-registry.js","sourceRoot":"","sources":["../src/spec-registry.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAmCjC,iEAAiE;AACjE,uEAAuE;AACvE,kDAAkD;AAClD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;AAExD;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAmB,EACnB,WAAuC;IAEvC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,kCAAkC,IAAI,qIAAqI,CAC5K,CAAC;IACJ,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,WAAkC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAAC,IAAY;IACzD,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}