@namzu/sdk 2.0.0 → 3.0.0

package/dist/registry/Registry.test.js

@@ -2,7 +2,7 @@
  * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
  *
  *   - `register(id, item)` silently overwrites an existing entry —
- *     NO duplicate-error is thrown (Codex #1 verified the design
+ *     NO duplicate-error is thrown (review verified the design
  *     §2.3 "typed DuplicateRegistrationError" claim was fiction).
  *   - `get(id)` returns `undefined` for an unknown id (NOT a typed
  *     error). `getAll`, `listIds`, `has`, `size` reflect the current

package/dist/registry/connector/definitions.test.d.ts

@@ -7,7 +7,7 @@
  *   - `listByType(connectionType)` filters by `connectionType`.
  *   - As a global (non-tenant-scoped) registry, ConnectorRegistry is
  *     shared across tenants; tenant isolation lives in
- *     `TenantConnectorManager` per Codex #5.
+ *     `TenantConnectorManager`.
  */
 export {};
 //# sourceMappingURL=definitions.test.d.ts.map

package/dist/registry/connector/definitions.test.js

@@ -7,7 +7,7 @@
  *   - `listByType(connectionType)` filters by `connectionType`.
  *   - As a global (non-tenant-scoped) registry, ConnectorRegistry is
  *     shared across tenants; tenant isolation lives in
- *     `TenantConnectorManager` per Codex #5.
+ *     `TenantConnectorManager`.
  */
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';

package/dist/registry/tool/__tests__/schema.test.d.ts

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

package/dist/registry/tool/__tests__/schema.test.d.ts.map

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

package/dist/registry/tool/__tests__/schema.test.js

@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { mcpJsonSchemaToZod } from '../../../connector/mcp/adapter.js';
+import { ToolRegistry } from '../execute.js';
+import { renderToolSchema } from '../schema.js';
+/**
+ * The tools block renders at position 0 of every request — inside the
+ * prompt-cache prefix — so its exact bytes are a contract, not an
+ * implementation detail. These tests pin them.
+ */
+function tool(name, inputSchema) {
+    return {
+        name,
+        description: `${name} tool`,
+        inputSchema: inputSchema,
+        execute: () => Promise.resolve({ success: true, output: 'ok' }),
+    };
+}
+describe('renderToolSchema', () => {
+    it('drops `$schema`, which no provider reads', () => {
+        // It rode in the tools block once per tool, per request, forever.
+        const raw = renderToolSchema(z.object({ path: z.string() }));
+        expect(raw).not.toHaveProperty('$schema');
+    });
+    it('pins the wire shape of an ordinary tool schema', () => {
+        expect(renderToolSchema(z.object({
+            path: z.string().describe('File to read'),
+            limit: z.number().int().optional(),
+        }))).toEqual({
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File to read' },
+                limit: { type: 'integer' },
+            },
+            required: ['path'],
+            additionalProperties: false,
+        });
+    });
+    it('closes nested objects and array items too', () => {
+        // `additionalProperties: false` at the root only constrains the top
+        // level; a model can invent keys inside a nested object otherwise.
+        const json = renderToolSchema(z.object({ edits: z.array(z.object({ from: z.string(), to: z.string() })) }));
+        expect(json).toMatchObject({
+            additionalProperties: false,
+            properties: {
+                edits: { type: 'array', items: { additionalProperties: false } },
+            },
+        });
+    });
+    it('returns the identical object for the same schema — byte-stable across iterations', () => {
+        // `toLLMTools` runs once per iteration. A re-render that reordered a
+        // single key would invalidate the whole cached prefix for the run.
+        const schema = z.object({ a: z.string() });
+        const first = renderToolSchema(schema);
+        const second = renderToolSchema(schema);
+        expect(second).toBe(first);
+    });
+    it('is frozen, so a caller cannot poison the cache', () => {
+        // The symptom of a mutated cache entry would be a silently
+        // invalidated prompt cache, not an error. Freezing makes it a throw.
+        const rendered = renderToolSchema(z.object({ a: z.string() }));
+        expect(() => {
+            rendered.injected = true;
+        }).toThrow();
+        expect(Object.isFrozen(rendered.properties)).toBe(true);
+    });
+    it('renders the same object through the registry, iteration after iteration', () => {
+        const registry = new ToolRegistry();
+        registry.register(tool('read_file', z.object({ path: z.string() })));
+        const a = registry.toLLMTools()[0]?.function.parameters;
+        const b = registry.toLLMTools()[0]?.function.parameters;
+        expect(a).toBe(b);
+        expect(a).not.toHaveProperty('$schema');
+    });
+});
+describe('MCP schema round trip', () => {
+    const render = (schema) => renderToolSchema(mcpJsonSchemaToZod(schema));
+    it('preserves a nested object instead of flattening it to "any keys"', () => {
+        // This is what the model is shown for a bridged tool. Collapsing it
+        // to `z.record(z.unknown())` left the model guessing at a shape the
+        // server had spelled out precisely.
+        const rendered = render({
+            type: 'object',
+            properties: {
+                filter: {
+                    type: 'object',
+                    properties: { status: { type: 'string' }, limit: { type: 'integer' } },
+                    required: ['status'],
+                },
+            },
+            required: ['filter'],
+        });
+        expect(rendered).toMatchObject({
+            properties: {
+                filter: {
+                    type: 'object',
+                    properties: { status: { type: 'string' }, limit: { type: 'integer' } },
+                    required: ['status'],
+                },
+            },
+        });
+    });
+    it('preserves array item types instead of "array of anything"', () => {
+        const rendered = render({
+            type: 'object',
+            properties: { ids: { type: 'array', items: { type: 'string' } } },
+        });
+        expect(rendered).toMatchObject({
+            properties: { ids: { type: 'array', items: { type: 'string' } } },
+        });
+    });
+    it('preserves enums, descriptions and defaults', () => {
+        const rendered = render({
+            type: 'object',
+            properties: {
+                mode: { type: 'string', enum: ['fast', 'thorough'], description: 'Search depth' },
+            },
+        });
+        expect(rendered).toMatchObject({
+            properties: {
+                mode: { type: 'string', enum: ['fast', 'thorough'], description: 'Search depth' },
+            },
+        });
+    });
+    it('models a nullable field rather than erasing its type', () => {
+        const zod = mcpJsonSchemaToZod({
+            type: 'object',
+            properties: { cursor: { type: ['string', 'null'] } },
+            required: ['cursor'],
+        });
+        expect(zod.safeParse({ cursor: null }).success).toBe(true);
+        expect(zod.safeParse({ cursor: 'abc' }).success).toBe(true);
+        expect(zod.safeParse({ cursor: 7 }).success).toBe(false);
+    });
+    it('resolves anyOf to a union', () => {
+        const zod = mcpJsonSchemaToZod({
+            type: 'object',
+            properties: { id: { anyOf: [{ type: 'string' }, { type: 'integer' }] } },
+            required: ['id'],
+        });
+        expect(zod.safeParse({ id: 'x' }).success).toBe(true);
+        expect(zod.safeParse({ id: 3 }).success).toBe(true);
+        expect(zod.safeParse({ id: true }).success).toBe(false);
+    });
+    it('tells the model it may NOT invent arguments the server never declared', () => {
+        // The old default was `.passthrough()`, rendering
+        // `additionalProperties: true`.
+        const rendered = render({
+            type: 'object',
+            properties: { q: { type: 'string' } },
+        });
+        expect(rendered).toMatchObject({ additionalProperties: false });
+    });
+    it('still honors a server that explicitly opens its schema', () => {
+        const rendered = render({
+            type: 'object',
+            properties: { q: { type: 'string' } },
+            additionalProperties: true,
+        });
+        expect(rendered).toMatchObject({ additionalProperties: true });
+    });
+    it('validates a nested payload the old converter would have waved through', () => {
+        const zod = mcpJsonSchemaToZod({
+            type: 'object',
+            properties: {
+                filter: { type: 'object', properties: { limit: { type: 'integer' } }, required: ['limit'] },
+            },
+            required: ['filter'],
+        });
+        expect(zod.safeParse({ filter: { limit: 10 } }).success).toBe(true);
+        // `z.record(z.unknown())` accepted both of these.
+        expect(zod.safeParse({ filter: { limit: 'ten' } }).success).toBe(false);
+        expect(zod.safeParse({ filter: {} }).success).toBe(false);
+    });
+});
+//# sourceMappingURL=schema.test.js.map

package/dist/registry/tool/__tests__/schema.test.js.map

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

package/dist/registry/tool/__tests__/tool-name-validation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-name-validation.test.d.ts.map

package/dist/registry/tool/__tests__/tool-name-validation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-validation.test.d.ts","sourceRoot":"","sources":["../../../../src/registry/tool/__tests__/tool-name-validation.test.ts"],"names":[],"mappings":""}

package/dist/registry/tool/__tests__/tool-name-validation.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { PLUGIN_NAMESPACE_SEPARATOR } from '../../../constants/plugin/index.js';
+import { ToolRegistry, assertToolName } from '../execute.js';
+/**
+ * A tool name reaches the provider verbatim, and the major message APIs
+ * accept `[a-zA-Z0-9_-]` only. Nothing checked it: names were derived by
+ * concatenation at three separate construction sites, and the plugin
+ * bridge's separator was a colon — so EVERY plugin-contributed tool name
+ * was illegal, unconditionally.
+ *
+ * The rejection is a 400 on the whole request rather than on that tool,
+ * and those tools are registered deferred, so it fired the moment one was
+ * activated with nothing naming the culprit.
+ */
+const tool = (name) => ({
+    name,
+    description: 'x',
+    inputSchema: z.object({}),
+    execute: async () => ({ success: true, output: 'ok' }),
+});
+describe('what a name may be', () => {
+    it.each(['read', 'read_file', 'read-file', 'mcp__srv__read', 'a'.repeat(64)])('accepts %s', (name) => {
+        expect(() => assertToolName(name)).not.toThrow();
+    });
+    it.each([
+        ['a colon', 'plugin:tool'],
+        ['a space', 'read file'],
+        ['a dot', 'fs.read'],
+        ['a slash', 'fs/read'],
+        ['an empty name', ''],
+    ])('refuses %s', (_why, name) => {
+        expect(() => assertToolName(name)).toThrow(/cannot be sent to a provider/);
+    });
+    it('refuses a name over the length limit and says so', () => {
+        expect(() => assertToolName('a'.repeat(65))).toThrow(/65 characters, over the 64/);
+    });
+    it('names the offending tool', () => {
+        // A 400 on the whole request names nothing; this has to.
+        expect(() => assertToolName('bad:name')).toThrow(/"bad:name"/);
+    });
+});
+describe('the registry', () => {
+    it('refuses at registration rather than at request time', () => {
+        const registry = new ToolRegistry();
+        // Failing here costs the run nothing and can still be attributed.
+        expect(() => registry.register(tool('plugin:tool'))).toThrow(/cannot be sent to a provider/);
+    });
+    it('still registers a legal name', () => {
+        const registry = new ToolRegistry();
+        registry.register(tool('read_file'));
+        expect(registry.listNames()).toContain('read_file');
+    });
+    it('checks the id when one is passed separately', () => {
+        const registry = new ToolRegistry();
+        expect(() => registry.register('bad:id', tool('fine'))).toThrow(/cannot be sent to a provider/);
+    });
+});
+describe('the plugin namespace separator', () => {
+    it('is itself legal, so plugin tools can register at all', () => {
+        // It was a colon, which made every plugin-contributed tool name
+        // illegal — the check above would refuse all of them.
+        expect(() => assertToolName(`plugin${PLUGIN_NAMESPACE_SEPARATOR}tool`)).not.toThrow();
+    });
+    it('produces a legal name for a bridged remote tool', () => {
+        const name = `fs-plugin${PLUGIN_NAMESPACE_SEPARATOR}mcp__fs__read_file`;
+        expect(() => assertToolName(name)).not.toThrow();
+    });
+});
+//# sourceMappingURL=tool-name-validation.test.js.map

package/dist/registry/tool/__tests__/tool-name-validation.test.js.map

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

package/dist/registry/tool/execute.d.ts

@@ -1,6 +1,43 @@
 import type { LLMToolSchema, ToolAvailability, ToolContext, ToolDefinition, ToolExecutionResult, ToolRegistryConfig } from '../../types/tool/index.js';
 import { ManagedRegistry } from '../ManagedRegistry.js';
 export type { ToolExecutionResult };
+/**
+ * What a tool name may be, everywhere it comes from.
+ *
+ * A tool name reaches the provider verbatim, and the major message APIs
+ * accept `[a-zA-Z0-9_-]` up to 64 characters. Nothing checked it: names
+ * were derived by concatenation at three separate construction sites —
+ * the remote-tool bridge, the plugin bridge, the CLI bridge — and any of
+ * them could produce something the wire rejects.
+ *
+ * The rejection is a 400 on the WHOLE request rather than on that tool,
+ * and the tools most likely to carry a bad name are registered deferred,
+ * so it fired the moment one was activated with nothing naming the
+ * culprit. Failing at registration instead names the tool, at the moment
+ * something can still be done about it, and costs the run nothing.
+ *
+ * One driver already ratified passing names through untouched, on the
+ * grounds that a confusing name is "a naming problem to fix in the
+ * registry, not something to paper over" — which is precisely why the
+ * registry has to be the one that checks.
+ */
+export declare const TOOL_NAME_PATTERN: RegExp;
+export declare function assertToolName(name: string): void;
+/**
+ * Append a tool's declared return shape to its description.
+ *
+ * No provider's tool wire format has a slot for an output schema, so the
+ * description is the only channel that reaches the model. A remote server
+ * that publishes one had it dropped at the type boundary and the model was
+ * left inferring the return shape from prose — or from the first result it
+ * happened to see, which is worse, because a tool that returns an empty
+ * list once teaches the wrong lesson permanently.
+ *
+ * Rendered from JSON Schema verbatim rather than round-tripped through
+ * anything: this is shown, never validated, so there is nothing to gain by
+ * rebuilding it and fidelity to lose.
+ */
+export declare function describeWithOutput(description: string, outputSchema: Record<string, unknown> | undefined): string;
 export declare class ToolRegistry extends ManagedRegistry<ToolDefinition> {
     private availability;
     private tierConfig?;

package/dist/registry/tool/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/registry/tool/execute.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAElB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,YAAY,EAAE,mBAAmB,EAAE,CAAA;AAmCnC,qBAAa,YAAa,SAAQ,eAAe,CAAC,cAAc,CAAC;IAChE,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,UAAU,CAAC,CAAgB;gBAEvB,MAAM,CAAC,EAAE,kBAAkB;IAS9B,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAChD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI;IACrE,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI;IA2BjF,OAAO,CAAC,WAAW;IAkBV,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK/B,KAAK,IAAI,IAAI;IAKtB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ/B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ5B,UAAU,IAAI,IAAI;IASlB,YAAY,IAAI,OAAO;IAOvB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB;IAI/C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAkC/C,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAelD,cAAc,IAAI,MAAM,GAAG,IAAI;IAK/B,SAAS,IAAI,MAAM,EAAE;IAIrB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM;IAuC7C,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE;IA2BjD,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE;IAIlD,OAAO,CACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,CAAC;IA+I/B,OAAO,CAAC,iBAAiB;CAIzB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAO9E"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/registry/tool/execute.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAElB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGvD,YAAY,EAAE,mBAAmB,EAAE,CAAA;AAmCnC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,QAA0B,CAAA;AAExD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CACjC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,MAAM,CAGR;AAED,qBAAa,YAAa,SAAQ,eAAe,CAAC,cAAc,CAAC;IAChE,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,UAAU,CAAC,CAAgB;gBAEvB,MAAM,CAAC,EAAE,kBAAkB;IAK9B,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAChD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI;IACrE,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI;IA2BjF,OAAO,CAAC,WAAW;IAuBV,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK/B,KAAK,IAAI,IAAI;IAKtB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ/B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAQ5B,UAAU,IAAI,IAAI;IASlB,YAAY,IAAI,OAAO;IAOvB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB;IAI/C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAkC/C,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAelD,cAAc,IAAI,MAAM,GAAG,IAAI;IAK/B,SAAS,IAAI,MAAM,EAAE;IAIrB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM;IAuC7C,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE;IAwBjD,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE;IAIlD,OAAO,CACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,CAAC;IAoK/B,OAAO,CAAC,iBAAiB;CAIzB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAO9E"}

package/dist/registry/tool/execute.js

@@ -1,9 +1,10 @@
-import { SpanStatusCode } from '@opentelemetry/api';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';
 import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js';
+import { recordToolCall } from '../../telemetry/metrics.js';
 import { getTracer } from '../../telemetry/runtime-accessors.js';
 import { toErrorMessage } from '../../utils/error.js';
 import { ManagedRegistry } from '../ManagedRegistry.js';
+import { renderToolSchema } from './schema.js';
 // Tokens too generic to identify a tool by name — ignored when matching a
 // batched `search_tools` query so they can't activate the whole catalog
 // (every bridged tool name shares the `clawtool` prefix, for instance).
@@ -30,20 +31,64 @@ const SEARCH_STOP_TOKENS = new Set([
 // Weighted-scoring weights mirroring ToolCatalog.searchTools (the richer,
 // otherwise-unused catalog scorer): exact name 12, name substring 8,
 // description 5 — extended here with argument-name indexing (3), following
-// Anthropic's tool-search practice of searching argument names too.
+// argument names are searched too, not only the tool's own name.
 const SEARCH_WEIGHT_NAME_EXACT = 12;
 const SEARCH_WEIGHT_NAME_PARTIAL = 8;
 const SEARCH_WEIGHT_DESCRIPTION = 5;
 const SEARCH_WEIGHT_ARGUMENT = 3;
+/**
+ * What a tool name may be, everywhere it comes from.
+ *
+ * A tool name reaches the provider verbatim, and the major message APIs
+ * accept `[a-zA-Z0-9_-]` up to 64 characters. Nothing checked it: names
+ * were derived by concatenation at three separate construction sites —
+ * the remote-tool bridge, the plugin bridge, the CLI bridge — and any of
+ * them could produce something the wire rejects.
+ *
+ * The rejection is a 400 on the WHOLE request rather than on that tool,
+ * and the tools most likely to carry a bad name are registered deferred,
+ * so it fired the moment one was activated with nothing naming the
+ * culprit. Failing at registration instead names the tool, at the moment
+ * something can still be done about it, and costs the run nothing.
+ *
+ * One driver already ratified passing names through untouched, on the
+ * grounds that a confusing name is "a naming problem to fix in the
+ * registry, not something to paper over" — which is precisely why the
+ * registry has to be the one that checks.
+ */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+export function assertToolName(name) {
+    if (TOOL_NAME_PATTERN.test(name))
+        return;
+    const reason = name.length > 64
+        ? `it is ${name.length} characters, over the 64-character limit`
+        : 'it contains characters outside [a-zA-Z0-9_-]';
+    throw new Error(`Tool name "${name}" cannot be sent to a provider: ${reason}. Providers reject the whole request for one bad name, so this is refused at registration where it can still be attributed.`);
+}
+/**
+ * Append a tool's declared return shape to its description.
+ *
+ * No provider's tool wire format has a slot for an output schema, so the
+ * description is the only channel that reaches the model. A remote server
+ * that publishes one had it dropped at the type boundary and the model was
+ * left inferring the return shape from prose — or from the first result it
+ * happened to see, which is worse, because a tool that returns an empty
+ * list once teaches the wrong lesson permanently.
+ *
+ * Rendered from JSON Schema verbatim rather than round-tripped through
+ * anything: this is shown, never validated, so there is nothing to gain by
+ * rebuilding it and fidelity to lose.
+ */
+export function describeWithOutput(description, outputSchema) {
+    if (outputSchema === undefined)
+        return description;
+    return `${description}\n\nReturns (JSON Schema): ${JSON.stringify(outputSchema)}`;
+}
 export class ToolRegistry extends ManagedRegistry {
     availability = new Map();
     tierConfig;
     constructor(config) {
-        super({
-            componentName: 'ToolRegistry',
-            idField: 'name',
-            logger: config?.logger,
-        });
+        super({ componentName: 'ToolRegistry', idField: 'name', logger: config?.logger });
         this.tierConfig = config?.tierConfig;
     }
     register(idOrToolOrTools, maybeTool) {
@@ -66,6 +111,11 @@ export class ToolRegistry extends ManagedRegistry {
         this.registerOne(tool.name, tool, state);
     }
     registerOne(id, tool, state) {
+        assertToolName(id);
+        // A model-facing schema is what the constraint is applied TO, so
+        // asking for enforcement without one is a request that cannot be
+        // honoured. Refusing at registration puts the error where the author
+        // can fix it rather than at the first request.
         if (tool.enforceModelInput && !tool.modelInputSchema) {
             throw new Error(`Tool "${id}" enables enforceModelInput but does not define modelInputSchema. Constrained input generation requires an explicit provider-safe model schema.`);
         }
@@ -240,12 +290,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
                 type: 'function',
                 function: {
                     name: tool.name,
-                    description,
+                    description: describeWithOutput(description, tool.outputSchema),
                     parameters: (tool.modelInputSchema ? structuredClone(tool.modelInputSchema) : undefined) ??
-                        zodToJsonSchema(tool.inputSchema, {
-                            target: 'jsonSchema7',
-                            $refStrategy: 'none',
-                        }),
+                        renderToolSchema(tool.inputSchema),
                 },
             };
         });
@@ -255,7 +302,16 @@ Executable tool names, descriptions, and JSON input schemas are attached through
     }
     async execute(toolName, rawInput, context) {
         const tracer = getTracer();
-        return tracer.startActiveSpan(toolSpanName(toolName), async (span) => {
+        // Explicit parent, not the ambient context. Every span-owning body
+        // upstream is an async generator, and a generator resumes on its
+        // consumer's async context — so by the time a tool executes, whatever
+        // `startActiveSpan` established upstream is long gone and this span
+        // would emit as a root. `context.parentSpan` is threaded through
+        // `ToolContext`, which already reaches here.
+        const parentCtx = context.parentSpan
+            ? trace.setSpan(otelContext.active(), context.parentSpan)
+            : otelContext.active();
+        return tracer.startActiveSpan(toolSpanName(toolName), {}, parentCtx, async (span) => {
             span.setAttributes({
                 [GENAI.TOOL_NAME]: toolName,
                 [GENAI.TOOL_TYPE]: 'function',
@@ -304,7 +360,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
                     .join('; ');
                 // Distinguish "model sent an empty/no-arg call" from
                 // "model sent partial args" — the first is most often a
-                // streaming hiccup or a definition-test ping (Anthropic
+                // streaming hiccup or a definition-test ping (a provider
                 // occasionally pings tool surfaces with `{}` while the
                 // schema is still loading), the second is a genuine
                 // programming mistake by the model. The model self-
@@ -319,6 +375,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
                         !Array.isArray(rawInput) &&
                         Object.keys(rawInput).length === 0);
                 const requiredHint = describeRequiredInput(tool.inputSchema);
+                // A conditional schema's required shape cannot be reconstructed
+                // from JSON Schema's top-level `required`, so the author gets to
+                // say what a valid retry looks like.
                 const recoveryHint = tool.validationErrorHint?.trim()
                     ? ` ${tool.validationErrorHint.trim()}`
                     : '';
@@ -344,11 +403,14 @@ Executable tool names, descriptions, and JSON input schemas are attached through
             const finalInput = parseResult.data;
             try {
                 this.log.debug(`Executing tool: ${toolName}`);
+                const startedAt = Date.now();
                 const result = await tool.execute(finalInput, context);
+                const durationMs = Date.now() - startedAt;
                 this.log.debug(`Tool completed: ${toolName}`, {
                     success: result.success,
                 });
                 span.setAttribute(NAMZU.TOOL_SUCCESS, result.success);
+                recordToolCall(toolName, result.success, result.success ? undefined : result.error, durationMs);
                 if (!result.success && result.error) {
                     span.setAttribute(NAMZU.TOOL_ERROR, result.error);
                     span.setStatus({ code: SpanStatusCode.ERROR, message: result.error });
@@ -409,17 +471,25 @@ export function toolDiscoveryHint(description, maxLength = 100) {
  */
 function listArgumentNames(tool) {
     try {
-        const json = tool.modelInputSchema ??
-            zodToJsonSchema(tool.inputSchema, {
-                target: 'jsonSchema7',
-                $refStrategy: 'none',
-            });
+        // The model-facing schema when there is one: that is what the model
+        // was shown, so it is what a search over "which tool takes this
+        // argument" has to match against.
+        const json = tool.modelInputSchema ?? renderToolSchema(tool.inputSchema);
         return [...collectSchemaPropertyNames(json)].map((key) => key.toLowerCase());
     }
     catch {
         return [];
     }
 }
+/**
+ * Every property name a schema can accept, including the ones that only
+ * appear inside a branch.
+ *
+ * A conditional schema puts its real arguments under `anyOf`/`oneOf`, so
+ * reading the top-level `properties` alone finds nothing and the tool is
+ * unfindable by the very argument it takes. `seen` guards a schema that
+ * refers back to itself.
+ */
 function collectSchemaPropertyNames(schema, names = new Set(), seen = new Set()) {
     if (!schema || typeof schema !== 'object' || Array.isArray(schema))
         return names;
@@ -455,7 +525,7 @@ function collectSchemaPropertyNames(schema, names = new Set(), seen = new Set())
  */
 function describeRequiredInput(schema) {
     try {
-        const json = zodToJsonSchema(schema);
+        const json = renderToolSchema(schema);
         const required = json.required ?? [];
         if (required.length === 0)
             return 'No required parameters known.';