@kindgi/tools 0.0.0-bootstrap.0 → 0.1.1

package/dist/define.js

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import * as addFormatsModule from 'ajv-formats';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { createSpecRegistry, isZodSchema, loadZodConverter, loadZodConverterSync, toJSONSchemaSync, } from '@kindgi/schema';
+import { getToolSpecSynthesizer } from './spec-registry.js';
+import toolSchema from './tool.schema.json' with { type: 'json' };
+import { EFFECT_KINDS, } from './types.js';
+const TOOL_SCHEMA_URI = 'https://kindgi.com/schemas/v1/tool.schema.json';
+/**
+ * Exact semver regex — accepts `MAJOR.MINOR.PATCH[-PRERELEASE]`. Tool
+ * VERSIONS are always exact (a tool row ships a specific semver);
+ * agent bindings reference tools via `{ id, version: <range> }`
+ * where the range grammar is npm-style (parsed by `semver` at
+ * dispatch time).
+ */
+const SEMVER_EXACT_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const addFormatsRaw = addFormatsModule;
+const addFormats = typeof addFormatsRaw === 'function'
+    ? addFormatsRaw
+    : addFormatsRaw.default;
+let cachedRegistry;
+function registry() {
+    if (cachedRegistry !== undefined)
+        return cachedRegistry;
+    const built = createSpecRegistry([toolSchema]);
+    if (built.kind === 'err') {
+        throw new Error(`@kindgi/tools: bundled schema failed to compile: ${built.error.message}`);
+    }
+    cachedRegistry = built.value;
+    return cachedRegistry;
+}
+/**
+ * Sync converter resolver. `@kindgi/schema` handles caching + peer-dep
+ * absence; when zod is installed, this returns the converter on every
+ * call after the first at O(1); when zod is missing, this returns
+ * `undefined` and callers surface a typed `invalid-schema` error.
+ */
+function resolveZodConverterSync() {
+    return loadZodConverterSync();
+}
+/**
+ * Sanity-check that a candidate JSON Schema compiles under Draft 2020-12.
+ * We build a throwaway Ajv per call — cheap for authoring-time, safe under
+ * concurrent defineTool() calls.
+ */
+function compilesAsSchema(schema, where) {
+    const ajv = new Ajv2020({ strict: true, allErrors: true, allowUnionTypes: false });
+    addFormats(ajv);
+    try {
+        ajv.compile(schema);
+        return undefined;
+    }
+    catch (cause) {
+        return {
+            code: 'invalid-schema',
+            message: `Tool ${where} schema does not compile: ${cause instanceof Error ? cause.message : String(cause)}`,
+            where,
+            cause,
+        };
+    }
+}
+/**
+ * Given an `AnySchema` (JSON Schema object OR Zod v4 schema), return the
+ * JSON Schema wire form. Converts synchronously using the pre-loaded Zod
+ * converter — callers must have called `ensureZodConverter()` first if
+ * they might be handed a Zod schema.
+ */
+function resolveWireSchema(schema, where, converter) {
+    if (!isZodSchema(schema)) {
+        return { kind: 'ok', value: { wire: schema } };
+    }
+    // The input side for `input` (a `.default()` field is optional to the
+    // caller), the output side for `output` (the field is always there).
+    const converted = toJSONSchemaSync(schema, converter, where);
+    if (converted.kind === 'err') {
+        return { kind: 'err', error: toSchemaError(converted.error, where) };
+    }
+    return { kind: 'ok', value: { wire: converted.value, zod: schema } };
+}
+function toSchemaError(err, where) {
+    return {
+        code: 'invalid-schema',
+        message: `Tool ${where} Zod schema conversion failed: ${err.message}`,
+        where,
+        cause: err.cause,
+    };
+}
+export function defineTool(spec, options = {}) {
+    // Fast path: JSON-Schema-only authoring never needs the peer dep.
+    const authoredWithZod = isZodSchema(spec.input) || isZodSchema(spec.output);
+    const converter = authoredWithZod ? resolveZodConverterSync() : undefined;
+    return finalizeDefinition(spec, converter, options);
+}
+/**
+ * Async companion to `defineTool` — resolves the Zod peer dependency
+ * via dynamic `import()` instead of Node's `createRequire`. Prefer this
+ * in environments that prohibit `createRequire` (edge runtimes, some
+ * bundler configurations) OR for pack-init code that already lives on
+ * the async path.
+ */
+export async function defineToolAsync(spec, options = {}) {
+    const authoredWithZod = isZodSchema(spec.input) || isZodSchema(spec.output);
+    const converter = authoredWithZod ? await loadZodConverter() : undefined;
+    return finalizeDefinition(spec, converter, options);
+}
+function finalizeDefinition(spec, converter, options) {
+    // `version` is required on every tool manifest.
+    // Deep semver grammar checked here via a lightweight regex; range
+    // parsing (for agent-side `tools[].version` refs) happens elsewhere
+    // via the `semver` library at dispatch time. This regex accepts
+    // exact semvers only — tool VERSIONS are exact (a tool ships a
+    // specific `1.2.3`); ranges live on the agent binding.
+    const specVersion = spec.version;
+    if (typeof specVersion !== 'string' || !SEMVER_EXACT_RE.test(specVersion)) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-tool-definition',
+                message: '`version` is required on every tool manifest and must be an exact semver (e.g., `1.2.3`, `1.2.3-beta.1`). Agent bindings then reference tools via `{ id, version: <range> }`.',
+                issues: [
+                    {
+                        path: '/version',
+                        message: 'version must be a non-empty exact semver string',
+                    },
+                ],
+            },
+        };
+    }
+    // handler / spec mutual-exclusion + spec synthesis.
+    const authorHandler = spec.handler;
+    const declarativeSpec = spec.spec;
+    if (authorHandler !== undefined && declarativeSpec !== undefined) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-tool-definition',
+                message: '`handler` and `spec` are mutually exclusive. Provide an imperative handler OR a declarative spec, not both.',
+                issues: [{ path: '/handler', message: 'handler + spec both set' }],
+            },
+        };
+    }
+    if (authorHandler === undefined && declarativeSpec === undefined) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-tool-definition',
+                message: 'A tool must declare exactly one of `handler` (imperative) or `spec` (declarative).',
+                issues: [{ path: '/handler', message: 'handler + spec both absent' }],
+            },
+        };
+    }
+    let effectiveHandler = authorHandler;
+    if (declarativeSpec !== undefined) {
+        const synth = getToolSpecSynthesizer(declarativeSpec.kind);
+        if (synth === undefined) {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'invalid-tool-definition',
+                    message: `No synthesizer registered for tool spec kind "${declarativeSpec.kind}". Import the package that owns this kind (e.g. \`@kindgi/tools\` for 'http') before calling \`defineTool\`.`,
+                    issues: [{ path: '/spec/kind', message: `unknown kind "${declarativeSpec.kind}"` }],
+                },
+            };
+        }
+        effectiveHandler = synth(declarativeSpec, spec.id, options.synthesizer);
+    }
+    const inputResolved = resolveWireSchema(spec.input, 'input', converter);
+    if (inputResolved.kind === 'err')
+        return { kind: 'err', error: inputResolved.error };
+    const outputResolved = resolveWireSchema(spec.output, 'output', converter);
+    if (outputResolved.kind === 'err')
+        return { kind: 'err', error: outputResolved.error };
+    // Rebuild the spec against the JSON Schema wire form. Downstream code
+    // (invokeTool, manifest projection, MCP publish) reads `.input` /
+    // `.output`; the original Zod objects are stored separately on
+    // `inputZod` / `outputZod`.
+    const wireSpec = {
+        ...spec,
+        input: inputResolved.value.wire,
+        output: outputResolved.value.wire,
+        handler: effectiveHandler,
+    };
+    const manifest = stripHandler(wireSpec);
+    const schemaResult = registry().validate(TOOL_SCHEMA_URI, manifest);
+    if (schemaResult.kind === 'err') {
+        const err = schemaResult.error;
+        if (err.code !== 'validation-error') {
+            throw new Error(`@kindgi/tools: unexpected schema error ${err.code}: ${err.message}`);
+        }
+        return { kind: 'err', error: toDefinitionError(err) };
+    }
+    const badEffect = checkEffectKinds(manifest);
+    if (badEffect)
+        return { kind: 'err', error: badEffect };
+    const badInput = compilesAsSchema(manifest.input, 'input');
+    if (badInput)
+        return { kind: 'err', error: badInput };
+    const badOutput = compilesAsSchema(manifest.output, 'output');
+    if (badOutput)
+        return { kind: 'err', error: badOutput };
+    const tool = {
+        ...wireSpec,
+        ...(inputResolved.value.zod !== undefined && { inputZod: inputResolved.value.zod }),
+        ...(outputResolved.value.zod !== undefined && { outputZod: outputResolved.value.zod }),
+    };
+    return { kind: 'ok', value: tool };
+}
+function stripHandler(spec) {
+    // Structural copy dropping `handler`. `handler` is a function and Ajv rejects
+    // functions during validation, so it MUST be stripped before schema check.
+    const { handler: _handler, inputZod: _iz, outputZod: _oz, ...manifest } = spec;
+    return manifest;
+}
+function toDefinitionError(err) {
+    const issues = err.errors.map((e) => {
+        const ajvErr = e;
+        return {
+            path: typeof ajvErr.instancePath === 'string' ? ajvErr.instancePath : '',
+            message: typeof ajvErr.message === 'string' ? ajvErr.message : 'validation failed',
+        };
+    });
+    return { code: 'invalid-tool-definition', message: err.message, issues };
+}
+function checkEffectKinds(manifest) {
+    const kinds = new Set(EFFECT_KINDS);
+    for (const eff of manifest.effects ?? []) {
+        if (!kinds.has(eff.kind)) {
+            return {
+                code: 'unknown-effect',
+                message: `Tool "${manifest.id}" declares unknown effect kind "${eff.kind}"`,
+                kind: eff.kind,
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate an arbitrary wire manifest against `@kindgi/specs/tool.schema.json`
+ * + the same effect / input-schema / output-schema checks `defineTool`
+ * runs, but without requiring a runtime `handler`. Used by transport
+ * layers (HTTP API, MCP publish) that accept metadata-only tool
+ * registrations — the actual handler is bound server-side via the
+ * runtime registry.
+ *
+ * The returned value has the manifest fields only; there is no
+ * `handler` (metadata-only shape).
+ */
+export function validateToolManifest(manifest) {
+    if (manifest === null || typeof manifest !== 'object') {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-tool-definition',
+                message: 'Tool manifest must be an object',
+                issues: [{ path: '', message: 'must be an object' }],
+            },
+        };
+    }
+    // `defineTool` strips `handler` before schema validation; forward the
+    // wire object unchanged. `handler` isn't in the ToolManifest shape,
+    // so any incidental value on the wire is ignored by validation.
+    const { handler: _ignored, ...candidate } = manifest;
+    const schemaResult = registry().validate(TOOL_SCHEMA_URI, candidate);
+    if (schemaResult.kind === 'err') {
+        const err = schemaResult.error;
+        if (err.code !== 'validation-error') {
+            throw new Error(`@kindgi/tools: unexpected schema error ${err.code}: ${err.message}`);
+        }
+        return { kind: 'err', error: toDefinitionError(err) };
+    }
+    const parsed = candidate;
+    const badEffect = checkEffectKinds(parsed);
+    if (badEffect)
+        return { kind: 'err', error: badEffect };
+    const badInput = compilesAsSchema(parsed.input, 'input');
+    if (badInput)
+        return { kind: 'err', error: badInput };
+    const badOutput = compilesAsSchema(parsed.output, 'output');
+    if (badOutput)
+        return { kind: 'err', error: badOutput };
+    const badUrl = checkHttpUrlTemplate(parsed);
+    if (badUrl)
+        return { kind: 'err', error: badUrl };
+    return { kind: 'ok', value: parsed };
+}
+/**
+ * An HTTP tool's `urlTemplate` fills `{placeholders}` in its path and
+ * query only. In the scheme, host or port, a run's input (or a model's
+ * arguments) would choose where the server sends the request.
+ */
+function checkHttpUrlTemplate(manifest) {
+    const spec = manifest.spec;
+    if (spec?.kind !== 'http')
+        return undefined;
+    const origin = /^(https?):\/\/([^/?#]*)/i.exec(spec.urlTemplate);
+    const message = origin === null
+        ? 'must start with http:// or https:// and a host'
+        : /[{}]/.test(origin[2] ?? '')
+            ? 'fills {placeholders} in its path and query only, never in its host or port'
+            : (origin[2] ?? '') === ''
+                ? 'must name a host'
+                : undefined;
+    if (message === undefined)
+        return undefined;
+    return {
+        code: 'invalid-tool-definition',
+        message: `Tool "${manifest.id}" spec.urlTemplate ${message}`,
+        issues: [{ path: '/spec/urlTemplate', message }],
+    };
+}
+/** Exported for tests and downstream registry building. */
+export function toolIdOf(spec) {
+    return spec.id;
+}
+/** The `$id` of the JSON Schema this loader validates against. */
+export const TOOL_SCHEMA_URI_EXPORTED = TOOL_SCHEMA_URI;
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,113 @@
+import type { ToolId } from '@kindgi/types';
+/**
+ * Errors emitted by @kindgi/tools. Every variant carries a `code` for
+ * pattern matching; messages are human-readable, not API contract.
+ */
+export type ToolError = InvalidToolDefinitionError | InvalidSchemaError | UnknownEffectError | DuplicateToolError | DuplicateToolVersionError | ToolNotFoundError | ToolVersionNotFoundError | InvalidVersionRangeError | ToolVersionUnresolvableError | InputValidationError | OutputValidationError | HandlerError | PreconditionFailedError;
+/** `defineTool` was called with something the schema loader rejects. */
+export interface InvalidToolDefinitionError {
+    readonly code: 'invalid-tool-definition';
+    readonly message: string;
+    readonly issues: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+}
+/** The provided `input` or `output` is not a valid JSON Schema Draft 2020-12. */
+export interface InvalidSchemaError {
+    readonly code: 'invalid-schema';
+    readonly message: string;
+    readonly where: 'input' | 'output';
+    readonly cause: unknown;
+}
+/** An effect kind not in `EFFECT_KINDS` was declared. */
+export interface UnknownEffectError {
+    readonly code: 'unknown-effect';
+    readonly message: string;
+    readonly kind: string;
+}
+/**
+ * ToolRegistry.register was called with an id that already exists AND the
+ * registry doesn't support multiple versions per id. `createToolRegistry`
+ * holds several versions per id and returns `duplicate-tool-version`
+ * instead when the same (id, version) is registered twice.
+ */
+export interface DuplicateToolError {
+    readonly code: 'duplicate-tool';
+    readonly message: string;
+    readonly id: ToolId;
+}
+/** Same `(id, version)` pair was registered twice — versions must be unique. */
+export interface DuplicateToolVersionError {
+    readonly code: 'duplicate-tool-version';
+    readonly message: string;
+    readonly id: ToolId;
+    readonly version: string;
+}
+/** ToolRegistry.get was called with an id that isn't registered. */
+export interface ToolNotFoundError {
+    readonly code: 'tool-not-found';
+    readonly message: string;
+    readonly id: ToolId;
+}
+/** The id exists but the requested exact version doesn't. */
+export interface ToolVersionNotFoundError {
+    readonly code: 'tool-version-not-found';
+    readonly message: string;
+    readonly id: ToolId;
+    readonly version: string;
+}
+/** The provided version range isn't a valid semver range (per npm grammar). */
+export interface InvalidVersionRangeError {
+    readonly code: 'invalid-version-range';
+    readonly message: string;
+    readonly id: ToolId;
+    readonly range: string;
+}
+/**
+ * `resolve(id, range)` found the id but no registered version satisfies
+ * the range. Distinct from `tool-not-found` (no id at all) and from
+ * `invalid-version-range` (grammar error on the range string).
+ */
+export interface ToolVersionUnresolvableError {
+    readonly code: 'tool-version-unresolvable';
+    readonly message: string;
+    readonly id: ToolId;
+    readonly range: string;
+    readonly availableVersions: readonly string[];
+}
+/** invokeTool: the caller's input didn't validate against tool.input. */
+export interface InputValidationError {
+    readonly code: 'input-validation-failed';
+    readonly message: string;
+    readonly toolId: ToolId;
+    readonly errors: readonly unknown[];
+}
+/** invokeTool: the handler returned something that didn't validate against tool.output. */
+export interface OutputValidationError {
+    readonly code: 'output-validation-failed';
+    readonly message: string;
+    readonly toolId: ToolId;
+    readonly errors: readonly unknown[];
+}
+/** invokeTool: the handler threw. */
+export interface HandlerError {
+    readonly code: 'handler-error';
+    readonly message: string;
+    readonly toolId: ToolId;
+    readonly cause: unknown;
+}
+/**
+ * invokeTool: the runtime refused to run the tool — something it declares
+ * wasn't there (a `ToolPreconditionError` from the runtime's handler
+ * wrapper). The tool's own code never ran.
+ */
+export interface PreconditionFailedError {
+    readonly code: 'precondition-failed';
+    readonly message: string;
+    readonly toolId: ToolId;
+    /** The runtime's code for what was missing (`secret-unavailable`, …). */
+    readonly reason: string;
+    readonly cause: unknown;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":""}