@orboto/mcp 0.178.0

package/dist/input-schema.js

@@ -0,0 +1,293 @@
+/**
+ * ORB-1692 - strict tool inputs + the aliases agents actually send.
+ *
+ * Measured across 32 transcripts: 55.6% of all MCP errors were "Required"
+ * validation failures where the agent guessed a plausible-but-wrong
+ * parameter name (`body` for `text`, `parentKey` for `parentTicketKey`,
+ * ...). Worse, zod strips unknown keys by default, so a wrong key on an
+ * otherwise-valid call VANISHED silently - `create_ticket` with
+ * `parentKey` created ORB-1684 with no parent and no warning.
+ *
+ * Fix, applied centrally at registration (with-metrics `reg()`):
+ *  1. every tool input becomes `.strict()` - an unknown key errors,
+ *     naming the offender;
+ *  2. the measured aliases resolve silently to the canonical field via a
+ *     GUARDED global rename: `alias -> canonical` fires only when the
+ *     canonical field exists in that tool's shape, the alias does not,
+ *     and the caller did not also send the canonical - so a tool whose
+ *     REAL field is `body` (agent-instruction blocks) is never touched;
+ *  3. `orboto_update_ticket` folds flat patch fields into `patch` when no
+ *     `patch` was sent - agents routinely write `{ticketKey, description}`.
+ *
+ * ORB-1817 - "we do not force keys that make no sense - key and query are
+ * sensible names" (operator). Extends the alias table with the sensible
+ * spellings a caller actually reaches for (`key`, `query`, `projectId`,
+ * ...) plus one DYNAMIC alias - `id` resolves to the tool's own single
+ * id-shaped parameter (`ticketKey` / `docId` / `milestone` / `commentId`)
+ * only when exactly one of those exists in that tool's shape - and adds a
+ * teaching error: when a call still can't be resolved, the thrown message
+ * is a structured JSON block naming every parameter the tool accepts plus
+ * a Levenshtein<=2 guess for each unrecognized key (same distance the mjs
+ * wrapper's `suggestFlag` uses for `--flag` typos). The failure is also
+ * logged through the same `/admin/mcp/instrument` path a handler error
+ * uses - see the module doc on `mcp-instrument.ts` for why that needs a
+ * dedicated leaf module instead of importing from with-metrics.ts.
+ *
+ * SDK mechanics: `registerTool` accepts either a raw shape or a zod
+ * schema. A top-level `z.preprocess(...)` has no `.shape`, which would
+ * make the SDK advertise an EMPTY input schema in tools/list. Stamping
+ * the inner object's `.shape` onto the effects schema keeps the
+ * advertisement byte-identical to the strict object (verified: the SDK's
+ * `normalizeObjectSchema` only checks `.shape !== undefined`, and its
+ * json-schema emitter unwraps effects with pipeStrategy "input").
+ *
+ * ORB-1817 - the preprocess callback is also where the teaching error is
+ * thrown (verified against @modelcontextprotocol/sdk 1.29's zod-compat +
+ * server/mcp.js): a `preprocess` effect calls `effect.transform(data,
+ * checkCtx)` BEFORE the inner schema ever parses, and unlike `refine` /
+ * `transform`, a synchronous throw from inside it is NOT caught by zod -
+ * it propagates out of `ZodEffects._parse`, out of the SDK's
+ * `safeParseAsync` (converted to a rejected promise, since that's an
+ * `async function`), and lands in the SDK's own `CallToolRequestSchema`
+ * handler's outer try/catch, which for a plain (non-McpError) `Error`
+ * returns `{isError: true, content: [{type: 'text', text: error.message}]}`
+ * with NO extra wrapping. That is what lets us hand back exactly our
+ * structured JSON with nothing else attached - `.superRefine()` cannot do
+ * this (it never even runs once the base object parse has already failed,
+ * which is the common case: a missing-required or unrecognized-key input).
+ */
+import { z } from 'zod';
+import { postLogEntry, redactSecrets } from './mcp-instrument.js';
+/**
+ * alias -> canonical. Applied to every tool, guarded by the tool's own
+ * shape (see module doc). Sourced from the ORB-1692 / ORB-1817 measurement
+ * tables - extend it when a NEW misfire class shows up in the
+ * mcp_call_log, not speculatively.
+ */
+export const GLOBAL_INPUT_ALIASES = {
+    body: 'text',
+    parentKey: 'parentTicketKey',
+    dependsOnTicketKey: 'dependsOnKey',
+    docKey: 'docId',
+    status: 'statusCategory',
+    milestoneKey: 'milestone',
+    ticket: 'ticketKey',
+    project: 'projectKey',
+    // ORB-1817 - measured 2026-09-03: both cost one retry in the same
+    // session. "key" and "query" are what a reasonable caller types.
+    key: 'ticketKey',
+    query: 'oql',
+    projectId: 'projectKey',
+    milestoneId: 'milestone',
+    comment: 'text',
+    message: 'text',
+    // Bulk tools all take `ticketKeys` (plural) - singular-sounding `keys`
+    // is the natural typo/guess.
+    keys: 'ticketKeys',
+    max: 'limit',
+    page: 'cursor',
+};
+/** ORB-1817 - `id` has no single canonical target across tools (it's
+ *  `ticketKey` on a ticket tool, `docId` on a doc tool, ...), so it can't
+ *  be a static GLOBAL_INPUT_ALIASES entry. Resolved dynamically: only
+ *  when the tool's shape has EXACTLY ONE of these, and only when the
+ *  caller didn't already send it explicitly. Two or zero matches leave
+ *  `id` alone so the strict error - now the teaching error - explains why. */
+const ID_LIKE_CANONICALS = ['ticketKey', 'docId', 'milestone', 'commentId'];
+/** The flat fields orboto_update_ticket folds into `patch` (ORB-1692 #3). */
+const UPDATE_TICKET_PATCH_KEYS = [
+    'title', 'description', 'customerSummary', 'type', 'priority',
+    'deliveryMode', 'dueDate', 'startDate', 'isPrivate', 'estimatedTimeMinutes',
+];
+function applyAliases(toolName, shape, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    let out = value;
+    for (const [alias, canonical] of Object.entries(GLOBAL_INPUT_ALIASES)) {
+        if (alias in out &&
+            !(canonical in out) &&
+            canonical in shape &&
+            !(alias in shape)) {
+            const { [alias]: aliased, ...rest } = out;
+            out = { ...rest, [canonical]: aliased };
+        }
+    }
+    // ORB-1817 - `id` -> the tool's single id-shaped parameter.
+    if ('id' in out && !('id' in shape)) {
+        const candidates = ID_LIKE_CANONICALS.filter((c) => c in shape && !(c in out));
+        if (candidates.length === 1) {
+            const canonical = candidates[0];
+            const { id, ...rest } = out;
+            out = { ...rest, [canonical]: id };
+        }
+    }
+    // update_ticket: flat fields become an implicit patch. Only when the
+    // caller sent no patch at all - a partial patch plus flat extras stays
+    // an error (ambiguous intent must not be guessed).
+    if (toolName === 'orboto_update_ticket' && !('patch' in out)) {
+        const patch = {};
+        const rest = {};
+        let folded = false;
+        for (const [k, v] of Object.entries(out)) {
+            if (UPDATE_TICKET_PATCH_KEYS.includes(k)) {
+                patch[k] = v;
+                folded = true;
+            }
+            else {
+                rest[k] = v;
+            }
+        }
+        if (folded)
+            out = { ...rest, patch };
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// ORB-1817 - teaching error: structured `expected` block + closest-name
+// guess, built when the strict + alias-resolved value STILL doesn't parse.
+// ---------------------------------------------------------------------------
+/** Levenshtein-1/2 match, same algorithm skills/orboto/scripts/orboto.mjs
+ *  uses for `--flag` typos (`suggestFlag` / `levenshtein`) - keep them in
+ *  sync if the distance metric ever changes. */
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (!m)
+        return n;
+    if (!n)
+        return m;
+    const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+    for (let j = 1; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+function closestName(typed, candidates, maxDistance = 2) {
+    const near = candidates.filter((c) => levenshtein(typed, c) <= maxDistance);
+    return near.sort((a, b) => levenshtein(typed, a) - levenshtein(typed, b))[0];
+}
+/** Peel ZodOptional / ZodDefault / ZodNullable to name the underlying
+ *  type; everything else maps to a short lowercase type name so the
+ *  block stays compact (this is for a tool-calling model, not a schema
+ *  viewer). */
+function describeZodType(schema) {
+    const def = schema._def;
+    switch (def.typeName) {
+        case 'ZodOptional':
+        case 'ZodDefault':
+        case 'ZodNullable':
+            return def.innerType ? describeZodType(def.innerType) : 'unknown';
+        case 'ZodString': return 'string';
+        case 'ZodNumber': return 'number';
+        case 'ZodBoolean': return 'boolean';
+        case 'ZodArray': return 'array';
+        case 'ZodObject': return 'object';
+        case 'ZodEnum': return `enum(${(def.values ?? []).join('|')})`;
+        case 'ZodUnion': return 'union';
+        default: return def.typeName.replace(/^Zod/, '').toLowerCase() || 'unknown';
+    }
+}
+function describeShape(shape) {
+    return Object.entries(shape)
+        .map(([name, schema]) => ({
+        name,
+        type: describeZodType(schema),
+        required: !schema.isOptional(),
+        description: schema.description,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Build the teaching-error message: ONE structured JSON block, not prose.
+ * `code: -32602` mirrors the JSON-RPC "invalid params" code the SDK would
+ * otherwise bury inside its own generic zod-issue dump.
+ */
+function buildTeachingError(toolName, shape, issues) {
+    const validNames = Object.keys(shape);
+    const unrecognized = [];
+    const missing = [];
+    for (const issue of issues) {
+        if (issue.code === 'unrecognized_keys')
+            unrecognized.push(...issue.keys);
+        if (issue.code === 'invalid_type' && issue.received === 'undefined' && issue.path.length === 1) {
+            missing.push(String(issue.path[0]));
+        }
+    }
+    const didYouMean = {};
+    for (const key of unrecognized) {
+        const guess = closestName(key, validNames);
+        if (guess)
+            didYouMean[key] = guess;
+    }
+    const summary = unrecognized.length > 0
+        ? `Unrecognized parameter(s) for ${toolName}: ${unrecognized.join(', ')}.`
+        : missing.length > 0
+            ? `Missing required parameter(s) for ${toolName}: ${missing.join(', ')}.`
+            : `Invalid arguments for ${toolName}.`;
+    return JSON.stringify({
+        code: -32602,
+        error: summary,
+        expected: {
+            tool: toolName,
+            parameters: describeShape(shape),
+        },
+        unrecognized: unrecognized.length ? unrecognized : undefined,
+        missing: missing.length ? missing : undefined,
+        didYouMean: Object.keys(didYouMean).length ? didYouMean : undefined,
+    });
+}
+/**
+ * Wrap a raw tool shape into the strict + alias-resolving schema the SDK
+ * validates against. Returns a schema whose `.shape` is stamped so
+ * tools/list advertisement stays identical to the plain object form.
+ *
+ * `client` + `clientHint` are optional (tests construct schemas without
+ * them) - when present, a validation failure that survives aliasing is
+ * logged through the SAME `/admin/mcp/instrument` path a handler error
+ * uses (ORB-1817 Part C), because the SDK validates input BEFORE
+ * with-metrics.ts's handler wrapper ever runs - this preprocess step is
+ * the only place that ever sees the failure.
+ */
+export function buildStrictInputSchema(toolName, shape, client, clientHint) {
+    const inner = z.object(shape).strict();
+    const effects = z.preprocess((value) => {
+        const start = Date.now();
+        const aliased = applyAliases(toolName, shape, value);
+        const parsed = inner.safeParse(aliased);
+        if (parsed.success)
+            return aliased;
+        const message = buildTeachingError(toolName, shape, parsed.error.issues);
+        if (client) {
+            void postLogEntry(client, {
+                toolName,
+                durationMs: Date.now() - start,
+                success: false,
+                statusCode: -32602,
+                errorMessage: redactSecrets(message).slice(0, 500),
+                clientHint,
+            });
+        }
+        // See the module doc: thrown here (inside a "preprocess" effect, not
+        // a refinement/transform), this is NOT caught by zod - it becomes the
+        // exact isError text the caller sees.
+        throw new Error(message);
+    }, inner);
+    // SDK contract (see module doc): .shape must exist for advertisement.
+    effects.shape = inner.shape;
+    return effects;
+}
+/** True when the value is a raw shape (plain record of zod schemas), not a schema instance. */
+export function isRawShape(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (value._def !== undefined)
+        return false;
+    const entries = Object.values(value);
+    return entries.length > 0 && entries.every((v) => typeof v === 'object' && v !== null && v._def !== undefined);
+}

package/dist/input-schema.test.js

@@ -0,0 +1,198 @@
+/**
+ * ORB-1692 / ORB-1817 - strict inputs + measured aliases + the teaching
+ * error.
+ *
+ * Table-driven against the REAL tool configs: each alias from the
+ * measurement table must resolve to the canonical field, unknown keys
+ * must error naming the offender, and the ORB-1684 silent-drop case
+ * (create_ticket with parentKey) must never come back.
+ *
+ * ORB-1817 - a call that still can't be resolved after aliasing now
+ * THROWS (from every parse entry point, `.safeParse()` included - see
+ * the module doc on `buildStrictInputSchema` for why: the teaching error
+ * is thrown from inside a zod "preprocess" effect, which runs before the
+ * sync/async branch even exists). That's an intentional behaviour change
+ * from plain zod (whose `.safeParse()` never throws) - every test below
+ * that used to check `parsed.success === false` now checks the throw.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { buildStrictInputSchema, isRawShape, GLOBAL_INPUT_ALIASES } from './input-schema.js';
+import { commentToolConfig, updateTicketToolConfig, addTicketDependencyToolConfig, moveTicketToolConfig, createTicketToolConfig, updateCommentToolConfig, } from './tools/ticket-writes.js';
+import { setParentToolConfig } from './tools/set-parent.js';
+import { getMilestoneToolConfig } from './tools/milestones.js';
+import { getTicketToolConfig } from './tools/get-ticket.js';
+import { listTicketsToolConfig } from './tools/list-tickets.js';
+import { getDocToolConfig } from './tools/docs.js';
+import { queryToolConfig } from './tools/query.js';
+import { bulkMoveTicketsToolConfig } from './tools/bulk-writes.js';
+function schemaFor(toolName, config) {
+    return buildStrictInputSchema(toolName, config.inputSchema);
+}
+/** Parse and return the thrown message's parsed JSON body (ORB-1817: an
+ *  invalid call throws instead of returning `{success:false}`). */
+function throwsWith(schema, value) {
+    let caught;
+    try {
+        schema.safeParse(value);
+    }
+    catch (err) {
+        caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    return JSON.parse(caught.message);
+}
+describe('measured aliases resolve to the canonical field', () => {
+    const CASES = [
+        { tool: 'orboto_comment', config: commentToolConfig, send: { ticketKey: 'ORB-1', body: 'hi' }, expectKey: 'text', expectValue: 'hi' },
+        { tool: 'orboto_add_ticket_dependency', config: addTicketDependencyToolConfig, send: { ticketKey: 'ORB-1', dependsOnTicketKey: 'ORB-2' }, expectKey: 'dependsOnKey', expectValue: 'ORB-2' },
+        { tool: 'orboto_get_doc', config: getDocToolConfig, send: { docKey: 'ORB-D12' }, expectKey: 'docId', expectValue: 'ORB-D12' },
+        { tool: 'orboto_move_ticket', config: moveTicketToolConfig, send: { ticketKey: 'ORB-1', status: 'done' }, expectKey: 'statusCategory', expectValue: 'done' },
+        { tool: 'orboto_set_parent', config: setParentToolConfig, send: { ticketKey: 'ORB-1', parentKey: 'ORB-9' }, expectKey: 'parentTicketKey', expectValue: 'ORB-9' },
+        { tool: 'orboto_get_milestone', config: getMilestoneToolConfig, send: { projectKey: 'ORB', milestoneKey: 'ORB-M3' }, expectKey: 'milestone', expectValue: 'ORB-M3' },
+        { tool: 'orboto_get_ticket', config: getTicketToolConfig, send: { ticket: 'ORB-1' }, expectKey: 'ticketKey', expectValue: 'ORB-1' },
+        { tool: 'orboto_list_tickets', config: listTicketsToolConfig, send: { project: 'ORB' }, expectKey: 'projectKey', expectValue: 'ORB' },
+    ];
+    for (const c of CASES) {
+        it(`${c.tool}: ${Object.keys(c.send).join('+')} -> ${c.expectKey}`, () => {
+            const parsed = schemaFor(c.tool, c.config).safeParse(c.send);
+            expect(parsed.success, JSON.stringify('error' in parsed ? parsed.error : '')).toBe(true);
+            if (parsed.success) {
+                const data = parsed.data;
+                expect(data[c.expectKey]).toBe(c.expectValue);
+                expect(Object.keys(c.send).find((k) => GLOBAL_INPUT_ALIASES[k]) in data).toBe(false);
+            }
+        });
+    }
+});
+describe('the ORB-1684 regression: silent drops are dead', () => {
+    it('create_ticket with parentKey sets parentTicketKey - never vanishes', () => {
+        const parsed = schemaFor('orboto_create_ticket', createTicketToolConfig)
+            .safeParse({ projectKey: 'ORB', title: 'x', parentKey: 'ORB-1691' });
+        expect(parsed.success).toBe(true);
+        if (parsed.success) {
+            expect(parsed.data.parentTicketKey).toBe('ORB-1691');
+        }
+    });
+    it('an unknown key errors and names the offender', () => {
+        const body = throwsWith(schemaFor('orboto_create_ticket', createTicketToolConfig), { projectKey: 'ORB', title: 'x', bogusField: 1 });
+        expect(body.unrecognized).toEqual(['bogusField']);
+    });
+});
+describe('update_ticket: flat fields fold into patch', () => {
+    it('{ticketKey, description} becomes {ticketKey, patch:{description}}', () => {
+        const parsed = schemaFor('orboto_update_ticket', updateTicketToolConfig)
+            .safeParse({ ticketKey: 'ORB-1', description: 'new text', priority: 'high' });
+        expect(parsed.success).toBe(true);
+        if (parsed.success) {
+            const data = parsed.data;
+            expect(data.patch).toEqual({ description: 'new text', priority: 'high' });
+        }
+    });
+    it('an explicit patch wins - flat extras next to a patch stay an error', () => {
+        const body = throwsWith(schemaFor('orboto_update_ticket', updateTicketToolConfig), { ticketKey: 'ORB-1', patch: { title: 'a' }, description: 'b' });
+        expect(body.unrecognized).toEqual(['description']);
+    });
+});
+describe('alias guard: canonical-field collisions are never renamed', () => {
+    it('a tool whose REAL field is `body` keeps it', () => {
+        const shape = { id: z.string(), body: z.string() };
+        const parsed = buildStrictInputSchema('orboto_update_agent_instruction', shape)
+            .safeParse({ id: 'x', body: 'the rule text' });
+        expect(parsed.success).toBe(true);
+        if (parsed.success) {
+            expect(parsed.data.body).toBe('the rule text');
+        }
+    });
+    it('alias is ignored when the caller also sent the canonical field', () => {
+        // both present: no rename happens, so `body` is an unknown key -> error
+        const body = throwsWith(schemaFor('orboto_comment', commentToolConfig), { ticketKey: 'ORB-1', text: 'real', body: 'stray' });
+        expect(body.unrecognized).toEqual(['body']);
+    });
+});
+describe('ORB-1817: extended alias table', () => {
+    const CASES = [
+        { tool: 'orboto_get_ticket', config: getTicketToolConfig, send: { key: 'ORB-1' }, expectKey: 'ticketKey', expectValue: 'ORB-1' },
+        { tool: 'orboto_query', config: queryToolConfig, send: { query: 'project = ORB' }, expectKey: 'oql', expectValue: 'project = ORB' },
+        { tool: 'orboto_get_milestone', config: getMilestoneToolConfig, send: { projectKey: 'ORB', milestoneId: 'ORB-M3' }, expectKey: 'milestone', expectValue: 'ORB-M3' },
+        { tool: 'orboto_list_tickets', config: listTicketsToolConfig, send: { projectId: 'ORB' }, expectKey: 'projectKey', expectValue: 'ORB' },
+        { tool: 'orboto_comment', config: commentToolConfig, send: { ticketKey: 'ORB-1', comment: 'hi' }, expectKey: 'text', expectValue: 'hi' },
+        { tool: 'orboto_comment', config: commentToolConfig, send: { ticketKey: 'ORB-1', message: 'hi' }, expectKey: 'text', expectValue: 'hi' },
+        { tool: 'orboto_bulk_move_tickets', config: bulkMoveTicketsToolConfig, send: { keys: ['ORB-1', 'ORB-2'], statusCategory: 'done' }, expectKey: 'ticketKeys', expectValue: ['ORB-1', 'ORB-2'] },
+        { tool: 'orboto_query', config: queryToolConfig, send: { oql: 'project = ORB', max: 10 }, expectKey: 'limit', expectValue: 10 },
+        { tool: 'orboto_query', config: queryToolConfig, send: { oql: 'project = ORB', page: 'c1' }, expectKey: 'cursor', expectValue: 'c1' },
+        // `id` -> the tool's single id-shaped parameter (ticketKey here).
+        { tool: 'orboto_get_ticket', config: getTicketToolConfig, send: { id: 'ORB-1' }, expectKey: 'ticketKey', expectValue: 'ORB-1' },
+        { tool: 'orboto_get_doc', config: getDocToolConfig, send: { id: 'ORB-D12' }, expectKey: 'docId', expectValue: 'ORB-D12' },
+    ];
+    for (const c of CASES) {
+        it(`${c.tool}: ${Object.keys(c.send).join('+')} -> ${c.expectKey}`, () => {
+            const parsed = schemaFor(c.tool, c.config).safeParse(c.send);
+            expect(parsed.success, JSON.stringify('error' in parsed ? parsed.error : '')).toBe(true);
+            if (parsed.success) {
+                const data = parsed.data;
+                expect(data[c.expectKey]).toEqual(c.expectValue);
+            }
+        });
+    }
+    it('`id` is left alone (and errors) when the tool has more than one id-shaped parameter', () => {
+        // orboto_update_comment has BOTH ticketKey and commentId - ambiguous.
+        const body = throwsWith(schemaFor('orboto_update_comment', updateCommentToolConfig), { id: 'ORB-1', text: 'hi' });
+        expect(body.unrecognized).toEqual(['id']);
+    });
+});
+describe('ORB-1817: teaching error', () => {
+    it('names every parameter the tool accepts', () => {
+        const body = throwsWith(schemaFor('orboto_get_ticket', getTicketToolConfig), { bogus: 1 });
+        expect(body.code).toBe(-32602);
+        const expected = body.expected;
+        expect(expected.tool).toBe('orboto_get_ticket');
+        expect(expected.parameters.map((p) => p.name)).toContain('ticketKey');
+        const ticketKeyParam = expected.parameters.find((p) => p.name === 'ticketKey');
+        expect(ticketKeyParam?.required).toBe(true);
+    });
+    it('suggests the closest valid name for a typo (Levenshtein <= 2)', () => {
+        const body = throwsWith(schemaFor('orboto_get_ticket', getTicketToolConfig), { ticketKye: 'ORB-1' });
+        expect(body.didYouMean).toEqual({ ticketKye: 'ticketKey' });
+    });
+    it('names missing required parameters when nothing is unrecognized', () => {
+        const body = throwsWith(schemaFor('orboto_add_ticket_dependency', addTicketDependencyToolConfig), { ticketKey: 'ORB-1' });
+        expect(body.missing).toEqual(['dependsOnKey']);
+        expect(body.unrecognized).toBeUndefined();
+    });
+});
+describe('ORB-1817: validation failures are instrumented (Part C)', () => {
+    it('a bad input logs through the same /admin/mcp/instrument path a handler error uses', () => {
+        const post = vi.fn().mockResolvedValue(undefined);
+        const fakeClient = { post };
+        const schema = buildStrictInputSchema('orboto_get_ticket', getTicketToolConfig.inputSchema, fakeClient, 'test-client');
+        expect(() => schema.safeParse({ bogus: 1 })).toThrow();
+        expect(post).toHaveBeenCalledTimes(1);
+        expect(post).toHaveBeenCalledWith('/admin/mcp/instrument', expect.objectContaining({
+            toolName: 'orboto_get_ticket',
+            success: false,
+            statusCode: -32602,
+            clientHint: 'test-client',
+        }));
+    });
+    it('a valid input never logs', () => {
+        const post = vi.fn().mockResolvedValue(undefined);
+        const fakeClient = { post };
+        const schema = buildStrictInputSchema('orboto_get_ticket', getTicketToolConfig.inputSchema, fakeClient, 'test-client');
+        schema.safeParse({ ticketKey: 'ORB-1' });
+        expect(post).not.toHaveBeenCalled();
+    });
+});
+describe('SDK advertisement contract', () => {
+    it('the wrapped schema keeps .shape (tools/list must not go empty)', () => {
+        const s = schemaFor('orboto_comment', commentToolConfig);
+        expect(s.shape).toBeDefined();
+        expect(Object.keys(s.shape ?? {})).toContain('text');
+    });
+    it('isRawShape tells shapes from schema instances', () => {
+        expect(isRawShape(commentToolConfig.inputSchema)).toBe(true);
+        expect(isRawShape(z.object({ a: z.string() }))).toBe(false);
+        expect(isRawShape({})).toBe(false);
+        expect(isRawShape(undefined)).toBe(false);
+    });
+});

package/dist/instructions-budget.test.js

@@ -0,0 +1,34 @@
+/**
+ * ORB-1177 - the instructions block stays under a length budget so the
+ * client can't silently truncate it mid-rule; the head always survives
+ * and the rules are cut at a whole-line boundary with a pointer to the
+ * cap-independent full set.
+ */
+import { describe, it, expect } from 'vitest';
+import { assembleInstructions } from './server.js';
+const HEADING = 'Working rules for this workspace:\n';
+describe('assembleInstructions (ORB-1177)', () => {
+    it('passes through unchanged when under budget', () => {
+        const out = assembleInstructions('HEAD', 'rule one\nrule two', 1000);
+        expect(out).toBe(`HEAD\n\n${HEADING}rule one\nrule two`);
+    });
+    it('caps at the budget, keeps the head, cuts rules on a line boundary, points to the full set', () => {
+        const head = 'HEAD-ABC';
+        const lines = Array.from({ length: 300 }, (_, i) => `rule-line-${i}-padding-padding-padding-padding`);
+        const rules = lines.join('\n');
+        const budget = 600;
+        const out = assembleInstructions(head, rules, budget);
+        expect(out.length).toBeLessThanOrEqual(budget);
+        expect(out.startsWith(`${head}\n\n${HEADING}`)).toBe(true);
+        expect(out).toContain('orboto://rules');
+        expect(out).toContain('orboto_session_start');
+        expect(out).toContain('truncated');
+        // Every kept rule line is a COMPLETE original line (no mid-line cut).
+        const body = out.slice(`${head}\n\n${HEADING}`.length).split('\n\n[... rules truncated')[0];
+        const kept = body.length ? body.split('\n') : [];
+        for (const line of kept)
+            expect(lines).toContain(line);
+        // And it actually kept fewer than all lines (proves truncation happened).
+        expect(kept.length).toBeLessThan(lines.length);
+    });
+});