@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/dist/transport/instructions.js

@@ -0,0 +1,150 @@
+/**
+ * Server-level instructions, returned to the client in the `initialize` response
+ * and surfaced to the model alongside the tool list.
+ *
+ * SEPARATE FROM THE TOOL DESCRIPTION, which answers "what does this tool do and how do I
+ * call it". These answer "how do I USE this server correctly" — when to reach for it, and
+ * how to read an answer. The costly mistakes an agent makes here are interpretation
+ * mistakes, not calling mistakes.
+ *
+ * WHAT MAY BE WRITTEN HERE is a narrow rule (ARCHITECTURE.md §Invariants #6): this server
+ * describes ITSELF and never the platform, so a claim belongs here only if NO DIAGNOSTIC
+ * COULD CARRY IT —
+ *
+ *   - how to read the answer, since no finding explains the envelope;
+ *   - a SILENCE, which by definition no diagnostic can convey, and mistaking silence for
+ *     approval is the failure this server exists to prevent.
+ *
+ * Platform semantics do not belong here: each is measured to fire a real diagnostic
+ * (`transport/instructions-coverage.spec.ts` holds the fixtures) and each diagnostic
+ * carries its check's documentation URL, so prose here would be a staler second copy.
+ *
+ * WRITING RULES: state what to DO, not how the server is built; every claim must be true
+ * of the current build, since overstating coverage converts "I do not know" into false
+ * confidence; keep it short enough to be read in full, because this is spent context on
+ * every session.
+ */
+import { allChecks } from '@platformos/platformos-check-common';
+/**
+ * The coverage line, DERIVED so it cannot describe a build that no longer exists.
+ *
+ * A COUNT, not a roll of check names: an agent does not choose checks, and each finding
+ * already names its own. What the count conveys is scale, which is a decision input before
+ * the first call.
+ */
+function coverage() {
+    return `${allChecks.length} checks`;
+}
+export const SERVER_INSTRUCTIONS = `platformOS code validator.
+
+WHEN TO USE
+Call validate_code BEFORE writing or editing any platformOS Liquid, GraphQL or
+YAML file — it validates an in-memory buffer, so call it with the content you are
+about to write, not after writing. This is the primary quality gate. If you are changing several files as one coherent change,
+send them together in a single call (see the tool's \`files\` parameter): files in
+one call can reference each other, so a partial you are creating alongside its
+caller resolves correctly. Sent one at a time, that same edit is reported broken.
+List each file at most once — a changeset cannot hold two versions of one file, so a
+request that names the same file twice is refused rather than guessed at.
+Skipping this tool is the #1 cause of broken platformOS code.
+
+HOW TO READ THE RESULT
+
+must_fix_before_write
+  true  -> Do NOT write the file. It will not parse, it will raise at runtime, or
+           the deploy converter will reject it — and a converter rejection fails the
+           WHOLE changeset, not just this file.
+  false -> Nothing BLOCKING was found. This is not a statement that the code is
+           correct, only that no known-fatal problem was detected. Keep your own
+           judgement.
+
+status
+  ok | warning | error  -> the file WAS checked; these describe what was found.
+  not_applicable        -> the file was NOT checked at all. This is neither
+                           approval nor refusal — it carries no opinion about the
+                           file. Read not_applicable_reason before deciding:
+    outside_project  - not inside the project this server serves
+    unsupported_type - not a file type platformOS lints
+    misplaced_source - a platformOS source outside every deployed subtree; nothing
+                       checked it and nothing will load it either
+    ignored          - excluded by the project's .platformos-check.yml
+    too_large        - one buffer, or the request as a whole, is above its size
+                       limit. Split the file, or send fewer files per call — the
+                       reason text says which bound was hit
+    timed_out        - validation was abandoned; retrying may work
+    internal_error   - your REQUEST was malformed, or the validator hit a bug; the
+                       reason text says which. A malformed request — both input
+                       forms at once, neither, or one file listed twice — is yours
+                       to fix and worth retrying once fixed.
+
+errors / warnings / infos
+  Each list is ordered by line then column WITHIN ITSELF; the three are not one
+  ordered sequence, so concatenating them does not walk the file in order. Columns
+  count UTF-16 code units, so an emoji advances the column by 2.
+  Note that errors[] can be non-empty while must_fix_before_write is false: some
+  errors are real problems that do not stop the file working (an argument a partial
+  ignores, a missing asset, a missing image dimension). Fix them when you can; they
+  do not block the write.
+  Each finding names the check that produced it, and where see_also is present it links
+  that check's documentation — read it there rather than guessing at the rule.
+  A finding may carry fix (edits that are safe to apply as given) or suggestions
+  (alternatives to choose between). Their start_index / end_index are 0-based offsets
+  into the buffer you sent — NOT the 1-based line/column on the same finding. Apply
+  several edits from the end backwards, or account for the drift.
+
+truncated
+  Present ONLY when a file had so many findings that the lists were shortened to
+  keep the answer a reasonable size; absent means the lists are complete. It gives
+  the true total per affected list, so "returned: 40, total: 900" means 860 more
+  exist. The lists keep the TOP of the file, where a cascade's root cause usually
+  is. status and must_fix_before_write are always computed from ALL findings, never
+  from the shortened list, so a truncated answer is never a softer verdict — fix
+  what is listed and validate again to see the rest.
+
+impact
+  What this change BREAKS in files you are NOT editing — the one thing a per-file lint cannot
+  see, since it only ever looks at the buffers you sent. Each entry names the file and
+  carries the check's own findings: same message, same severity, same documentation link, and
+  the same fixes, exactly as if you had validated that file yourself.
+  It reports only what your change INTRODUCED. A problem that file already had is never
+  listed, however severe — it is not this edit's doing, and it would bury the one that is.
+  A break in someone else's file does NOT set must_fix_before_write: your buffer may be
+  perfectly correct. Fix the callers, or decide not to; that is yours to weigh.
+  status  computed        the dependants were linted with your change and without it
+          not_applicable  nothing can reference this file by name
+          unavailable     could not be run: a failure, a deadline, or a file referenced from
+                          more text than can be examined in time
+          disabled        this server runs with --no-impact, so nothing was attempted
+  unchecked_dependants appears when a file has more dependants than one request will lint.
+  Those were never checked, so an otherwise-clean answer carrying it is a PARTIAL one.
+  NOTHING HERE IS A CLEARANCE. An empty impact means no break was found among the dependants
+  that are VISIBLE, and a dependant can be invisible: {% render partial_name %} picks its
+  target at runtime, so no analysis can resolve it.
+  This server never tells you nothing depends on a file — if you are about to delete or
+  rename one, search the project yourself.
+
+WHAT IS NOT CHECKED
+${coverage()} run against your buffer. Where a finding exists it explains itself and links
+its documentation, so what follows is only the SILENCES — the places where finding nothing is not the same
+as finding it correct, and where no diagnostic can tell you so.
+
+  Argument types are checked only where the platformOS documentation publishes a type.
+  An argument the documentation leaves untyped accepts more than one type and is never
+  reported — which is every argument of every core Liquid filter, because those coerce
+  rather than refuse. {{ 5 | upcase }} renders and is not reported. That silence is the
+  documentation's answer, not a guarantee the value is right.
+
+  A model schema's property TYPE is checked and an unknown one is reported. The rest of a
+  schema's shape is not: an unrecognised top-level key is rejected on deploy and nothing
+  reports it, so silence there is not a claim the key is valid. A duplicated property name
+  IS accepted by the platform.
+
+  Duplicate YAML keys are compared the way the platform's own parser resolves them, so
+  yes: and true: in one mapping are reported as the one key they become. That comparison
+  is NOT exhaustive — a few spellings collide on the platform and are not reported — so
+  silence there does not prove two keys are distinct.
+
+  Coverage is per project: checks can be enabled, disabled or ignored in the project's
+  .platformos-check.yml, so a clean result reflects that project's configuration rather
+  than a fixed universal standard.`;
+//# sourceMappingURL=instructions.js.map

package/dist/transport/process-guards.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Process lifetime guards: signals and last-resort error handlers.
+ *
+ * The supervisor is a long-lived stdio process an agent holds open for a whole session, and
+ * under Node's default an unhandled rejection is FATAL — from the agent's side the tool
+ * simply stops existing mid-session, with nothing in the JSON-RPC stream to explain it.
+ *
+ * THE SPLIT is deliberately not symmetric:
+ *
+ *   - `unhandledRejection` — LOG AND KEEP SERVING. A rejected background promise does not
+ *     imply the server's state is corrupt, and staying up beats vanishing.
+ *   - `uncaughtException` — LOG, SHUT DOWN, EXIT NON-ZERO. The process state may genuinely
+ *     be corrupt, so continuing to answer would risk returning wrong diagnostics.
+ *
+ * HARD CONSTRAINT: stdout belongs to the MCP JSON-RPC stream. Everything here logs through
+ * the injected {@link Logger}, which writes to stderr; a stray stdout write would corrupt
+ * the protocol.
+ *
+ * `exit` and `emitter` are injected so the handlers can be driven in a test without
+ * terminating the runner. The returned uninstall function is wired into `shutdown` so a
+ * start/stop/start cycle does not accumulate listeners.
+ */
+import type { Logger } from '../logger.js';
+/** The subset of `process` these guards touch. Narrow, so a test can pass a stub. */
+export interface GuardEmitter {
+    on(event: string, listener: (...args: never[]) => void): unknown;
+    once(event: string, listener: (...args: never[]) => void): unknown;
+    removeListener(event: string, listener: (...args: never[]) => void): unknown;
+}
+export interface ProcessGuardOptions {
+    log: Logger;
+    /** The server's idempotent teardown. Awaited before a fatal exit. */
+    shutdown: (reason?: string) => Promise<void>;
+    /** Defaults to `process.exit`. Injected so tests never terminate the runner. */
+    exit?: (code: number) => void;
+    /** Defaults to `process`. Injected so tests can observe registration. */
+    emitter?: GuardEmitter;
+}
+/**
+ * Install signal handlers and last-resort error guards. Returns an uninstall
+ * function; calling it twice is harmless.
+ */
+export declare function installProcessGuards(options: ProcessGuardOptions): () => void;

package/dist/transport/process-guards.js

@@ -0,0 +1,63 @@
+/** Signals that mean "stop cleanly"; both exit 0. */
+const TERMINATION_SIGNALS = ['SIGINT', 'SIGTERM'];
+/**
+ * Render a thrown/rejected value for the log.
+ *
+ * A rejection reason is NOT necessarily an Error — `Promise.reject('nope')` and
+ * `Promise.reject()` are both legal — so this never assumes `.stack` exists.
+ */
+function describe(value) {
+    if (value instanceof Error)
+        return value.stack ?? `${value.name}: ${value.message}`;
+    // `String(Symbol())` throws; `String(undefined)` does not. Be total.
+    try {
+        return String(value);
+    }
+    catch {
+        return Object.prototype.toString.call(value);
+    }
+}
+/**
+ * Install signal handlers and last-resort error guards. Returns an uninstall
+ * function; calling it twice is harmless.
+ */
+export function installProcessGuards(options) {
+    const { log, shutdown } = options;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const emitter = options.emitter ?? process;
+    const registered = [];
+    const onSignal = (signal) => () => {
+        void shutdown(signal).finally(() => exit(0));
+    };
+    // `once`: a second SIGINT while shutting down should not re-enter teardown.
+    for (const signal of TERMINATION_SIGNALS) {
+        const listener = onSignal(signal);
+        emitter.once(signal, listener);
+        registered.push({ event: signal, listener });
+    }
+    // `on`, not `once`: unhandled rejections are survivable and may recur, and each one must
+    // be reported.
+    const onUnhandledRejection = ((reason) => {
+        log(`unhandled promise rejection (server continues): ${describe(reason)}. ` +
+            `This is a bug — a background task rejected with nobody awaiting it.`);
+    });
+    emitter.on('unhandledRejection', onUnhandledRejection);
+    registered.push({ event: 'unhandledRejection', listener: onUnhandledRejection });
+    const onUncaughtException = ((error) => {
+        log(`uncaught exception, shutting down: ${describe(error)}`);
+        // Non-zero: a supervisor that died must not look like a clean exit to whatever
+        // supervises IT. `finally` so a failing shutdown still exits.
+        void shutdown('uncaught exception').finally(() => exit(1));
+    });
+    emitter.on('uncaughtException', onUncaughtException);
+    registered.push({ event: 'uncaughtException', listener: onUncaughtException });
+    let uninstalled = false;
+    return () => {
+        if (uninstalled)
+            return;
+        uninstalled = true;
+        for (const { event, listener } of registered)
+            emitter.removeListener(event, listener);
+    };
+}
+//# sourceMappingURL=process-guards.js.map

package/dist/transport/process-guards.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport/process-guards.spec.js

@@ -0,0 +1,200 @@
+import { EventEmitter } from 'node:events';
+import { describe, expect, it, vi } from 'vitest';
+import { installProcessGuards } from './process-guards.js';
+/**
+ * TASK-16. Under Node's default an unhandled rejection is FATAL, so one rejected
+ * promise on a background path used to take the whole stdio server down — the
+ * agent losing the tool mid-session with nothing in the JSON-RPC stream to explain
+ * it. These pin the asymmetry that makes the guards correct:
+ *
+ *   - a rejection is survivable  -> log, KEEP SERVING
+ *   - an uncaught exception is not -> log, shut down, exit NON-ZERO
+ *
+ * `exit` and the emitter are injected throughout, so nothing here can terminate
+ * the test runner.
+ */
+const harness = () => {
+    const logs = [];
+    const exits = [];
+    const shutdowns = [];
+    const emitter = new EventEmitter();
+    const uninstall = installProcessGuards({
+        log: (message) => logs.push(message),
+        shutdown: async (reason) => {
+            shutdowns.push(reason);
+        },
+        exit: (code) => exits.push(code),
+        emitter: emitter,
+    });
+    return { logs, exits, shutdowns, emitter, uninstall };
+};
+/** The handlers finish their work in a `.finally`, so yield the microtask queue. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+describe('Unit: installProcessGuards — unhandled rejections are survivable', () => {
+    it('logs an Error rejection WITH its stack and does not exit', async () => {
+        const { logs, exits, shutdowns, emitter } = harness();
+        const error = new Error('background task failed');
+        emitter.emit('unhandledRejection', error);
+        await settle();
+        expect(logs).toHaveLength(1);
+        // The stack is what makes this diagnosable at all — the whole point of not
+        // just dying silently.
+        expect(logs[0]).toContain(error.stack);
+        expect(logs[0]).toContain('server continues');
+        // Survivable: no teardown, no exit.
+        expect(exits).toEqual([]);
+        expect(shutdowns).toEqual([]);
+    });
+    it('reports EVERY rejection, not just the first', async () => {
+        // Registered with `on`, not `once`: a `once` here would silence every
+        // rejection after the first, which is the opposite of the intent.
+        const { logs, emitter } = harness();
+        emitter.emit('unhandledRejection', new Error('first'));
+        emitter.emit('unhandledRejection', new Error('second'));
+        emitter.emit('unhandledRejection', new Error('third'));
+        await settle();
+        expect(logs).toHaveLength(3);
+    });
+    it.each([
+        ['a string', 'plain string reason', 'plain string reason'],
+        ['undefined', undefined, 'undefined'],
+        ['null', null, 'null'],
+        ['a number', 42, '42'],
+        ['a plain object', { code: 'E' }, '[object Object]'],
+    ])('survives a non-Error rejection value: %s', async (_label, reason, rendered) => {
+        // `Promise.reject('nope')` and `Promise.reject()` are both legal, so the guard
+        // must never assume `.stack`. A guard that throws while reporting a failure is
+        // worse than no guard.
+        const { logs, exits, emitter } = harness();
+        expect(() => emitter.emit('unhandledRejection', reason)).not.toThrow();
+        await settle();
+        expect(logs).toHaveLength(1);
+        expect(logs[0]).toContain(rendered);
+        expect(exits).toEqual([]);
+    });
+    it('survives a Symbol reason, which `String()` refuses to render', async () => {
+        // `String(Symbol())` THROWS. The renderer falls back rather than letting the
+        // guard become the crash.
+        const { logs, exits, emitter } = harness();
+        expect(() => emitter.emit('unhandledRejection', Symbol('nope'))).not.toThrow();
+        await settle();
+        expect(logs).toHaveLength(1);
+        expect(exits).toEqual([]);
+    });
+});
+describe('Unit: installProcessGuards — an uncaught exception is fatal', () => {
+    it('logs, shuts down gracefully, and exits NON-ZERO', async () => {
+        const { logs, exits, shutdowns, emitter } = harness();
+        const error = new Error('invariant broken');
+        emitter.emit('uncaughtException', error);
+        await settle();
+        expect(logs).toEqual([`uncaught exception, shutting down: ${error.stack}`]);
+        // Through the ordinary teardown, so a graph build in flight is still reaped.
+        expect(shutdowns).toEqual(['uncaught exception']);
+        // Non-zero: a supervisor that died must not look like a clean exit to whatever
+        // supervises IT.
+        expect(exits).toEqual([1]);
+    });
+    it('still exits when shutdown itself fails', async () => {
+        // The process state has already been declared unsound; a failing teardown must
+        // not wedge it open.
+        const logs = [];
+        const exits = [];
+        const emitter = new EventEmitter();
+        installProcessGuards({
+            log: (m) => logs.push(m),
+            shutdown: async () => {
+                throw new Error('teardown exploded');
+            },
+            exit: (code) => exits.push(code),
+            emitter: emitter,
+        });
+        emitter.emit('uncaughtException', new Error('boom'));
+        await settle();
+        expect(exits).toEqual([1]);
+    });
+});
+describe('Unit: installProcessGuards — termination signals', () => {
+    it.each(['SIGINT', 'SIGTERM'])('%s shuts down and exits ZERO', async (signal) => {
+        const { exits, shutdowns, emitter } = harness();
+        emitter.emit(signal);
+        await settle();
+        expect(shutdowns).toEqual([signal]);
+        // Zero: an operator asking us to stop is not a failure.
+        expect(exits).toEqual([0]);
+    });
+    it('handles a signal only once, so a second SIGINT does not re-enter teardown', async () => {
+        const { shutdowns, emitter } = harness();
+        emitter.emit('SIGINT');
+        emitter.emit('SIGINT');
+        await settle();
+        expect(shutdowns).toEqual(['SIGINT']);
+    });
+});
+describe('Unit: installProcessGuards — registration hygiene', () => {
+    it('registers exactly one listener per event', () => {
+        const emitter = new EventEmitter();
+        installProcessGuards({
+            log: () => { },
+            shutdown: async () => { },
+            exit: () => { },
+            emitter: emitter,
+        });
+        expect(['SIGINT', 'SIGTERM', 'unhandledRejection', 'uncaughtException'].map((event) => emitter.listenerCount(event))).toEqual([1, 1, 1, 1]);
+    });
+    it('uninstall removes every listener, so start/stop/start does not accumulate', () => {
+        const emitter = new EventEmitter();
+        const install = () => installProcessGuards({
+            log: () => { },
+            shutdown: async () => { },
+            exit: () => { },
+            emitter: emitter,
+        });
+        const first = install();
+        first();
+        // Second lifecycle: counts must be back to one each, not two.
+        const second = install();
+        expect(['SIGINT', 'SIGTERM', 'unhandledRejection', 'uncaughtException'].map((event) => emitter.listenerCount(event))).toEqual([1, 1, 1, 1]);
+        second();
+        expect(['SIGINT', 'SIGTERM', 'unhandledRejection', 'uncaughtException'].map((event) => emitter.listenerCount(event))).toEqual([0, 0, 0, 0]);
+    });
+    it('uninstall is idempotent', () => {
+        const emitter = new EventEmitter();
+        const uninstall = installProcessGuards({
+            log: () => { },
+            shutdown: async () => { },
+            exit: () => { },
+            emitter: emitter,
+        });
+        uninstall();
+        expect(() => uninstall()).not.toThrow();
+        expect(emitter.listenerCount('unhandledRejection')).toEqual(0);
+    });
+    it('an uninstalled guard no longer reacts', async () => {
+        const { logs, exits, emitter, uninstall } = harness();
+        uninstall();
+        emitter.emit('unhandledRejection', new Error('ignored'));
+        emitter.emit('uncaughtException', new Error('ignored'));
+        await settle();
+        expect([logs, exits]).toEqual([[], []]);
+    });
+});
+describe('Unit: installProcessGuards — stdout is never touched', () => {
+    it('logs only through the injected logger, never to the JSON-RPC stream', async () => {
+        // stdout belongs to MCP JSON-RPC. A stray write there corrupts the protocol,
+        // which is a WORSE failure than the crash being handled.
+        const stdoutWrite = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+        try {
+            const { logs, emitter } = harness();
+            emitter.emit('unhandledRejection', new Error('noisy'));
+            emitter.emit('uncaughtException', new Error('fatal'));
+            await settle();
+            expect(stdoutWrite).not.toHaveBeenCalled();
+            expect(logs).toHaveLength(2);
+        }
+        finally {
+            stdoutWrite.mockRestore();
+        }
+    });
+});
+//# sourceMappingURL=process-guards.spec.js.map

package/dist/transport/server.d.ts

@@ -7,8 +7,8 @@
  * user-facing surface.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type SupervisorContext } from '../context.js';
 import { type Logger } from '../logger.js';
-import { type SupervisorContext } from './validate-code.js';
 export interface ServerOptions {
     /** Absolute project root that buffers are validated against. */
     projectDir: string;
@@ -16,6 +16,11 @@ export interface ServerOptions {
     log?: Logger;
     /** Advertised server version. */
     version?: string;
+    /**
+     * Whether cross-file impact runs. Defaults to ON — only an explicit `false`, from
+     * `--no-impact` or `POS_SUPERVISOR_NO_IMPACT`, turns it off.
+     */
+    impactEnabled?: boolean;
 }
 export interface ServerHandle {
     server: McpServer;

package/dist/transport/server.js

@@ -9,13 +9,25 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createLogger } from '../logger.js';
+import { installProcessGuards } from './process-guards.js';
+import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { registerValidateCode } from './validate-code.js';
 const SERVER_NAME = 'platformos-mcp-supervisor';
 const DEFAULT_VERSION = '0.0.1';
 export async function startServer(opts) {
     const log = opts.log ?? createLogger(SERVER_NAME);
-    const context = { projectDir: opts.projectDir, log };
-    const server = new McpServer({ name: SERVER_NAME, version: opts.version ?? DEFAULT_VERSION });
+    // NOTHING IS BUILT OR WARMED HERE, by design. check-node owns one lazy `App` per project
+    // at process level and reconciles it per call, and impact is derived per request from
+    // the project's text (`impact/project-scan.ts`) — so there is no graph to build at boot,
+    // nothing to keep fresh, and no "still computing" answer.
+    const context = {
+        projectDir: opts.projectDir,
+        log,
+        impactEnabled: opts.impactEnabled,
+    };
+    // `instructions` reaches the model with the tool list; without them an agent has only the
+    // tool description to go on and invents a reading of the result (see instructions.ts).
+    const server = new McpServer({ name: SERVER_NAME, version: opts.version ?? DEFAULT_VERSION }, { instructions: SERVER_INSTRUCTIONS });
     registerValidateCode(server, context);
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -27,16 +39,15 @@ export async function startServer(opts) {
         closed = true;
         if (reason)
             log(`shutting down (${reason})`);
+        // Drop the process listeners as part of teardown, so a start/stop/start cycle
+        // in one process does not accumulate them.
+        uninstallGuards();
         await server.close();
     };
-    installSignalHandlers(shutdown);
+    // Signals plus the last-resort error guards: without them a single unhandled
+    // rejection on a background path is fatal under Node's default, and the agent
+    // loses the tool mid-session with nothing in the JSON-RPC stream to explain it.
+    const uninstallGuards = installProcessGuards({ log, shutdown });
     return { server, context, shutdown };
 }
-function installSignalHandlers(shutdown) {
-    for (const signal of ['SIGINT', 'SIGTERM']) {
-        process.once(signal, () => {
-            void shutdown(signal).finally(() => process.exit(0));
-        });
-    }
-}
 //# sourceMappingURL=server.js.map

package/dist/transport/validate-code.d.ts

@@ -1,26 +1,61 @@
 /**
- * Registration of the `validate_code` MCP tool.
+ * Registration of the `validate_code` MCP tool — the supervisor's entire surface.
  *
- * Current slice: the handler runs the real lint (`check()` via the check-node
- * seam) and returns the detection results mapped into `ValidateCodeResult`.
- * The ergonomic stages (enrich → advise → richer result assembly) are layered
- * in by later tasks; the handler shape stays the same.
+ * ONE TOOL, TWO INPUT SHAPES. Validating one file and validating a coordinated multi-file
+ * change are the same operation on a different number of buffers, so they are one tool:
+ *
+ *   validate_code({ file_path, content })   -> a single result
+ *   validate_code({ files: [...] })         -> one result per file + a batch gate
+ *
+ * There is no `many` flag — which form was sent is evident from the arguments.
+ *
+ * PASSING SEVERAL FILES IS MORE ACCURATE, not just faster: with every buffer overlaid at
+ * once a partial created alongside its caller resolves, where one at a time it is reported
+ * missing. The description says so, because that is why an agent should reach for it.
+ *
+ * This module owns only the MCP surface: schema, description, registration, and mapping
+ * input shape to output shape. All logic lives in `validate/`.
  */
 import { type ZodRawShape } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { Logger } from '../logger.js';
-/** Per-server context threaded into the handler. */
-export interface SupervisorContext {
-    /** Absolute project root the buffer is validated against. */
-    projectDir: string;
-    log: Logger;
-}
+import type { SupervisorContext } from '../context.js';
+import type { ValidateCodeParams, ValidateCodeResult, ValidateFilesResult } from '../result/types.js';
+import { type ValidateAdapters } from '../validate/validate-buffers.js';
+import { MAX_BATCH_BYTES, MAX_BATCH_FILES } from '../validate/batch-bounds.js';
 /**
  * zod raw shape for the tool input (validated by the MCP SDK before dispatch).
  *
- * Typed as `ZodRawShape` (not the inferred literal shape) so the SDK's
- * `registerTool` does not perform excessively deep type instantiation over the
- * schema; the handler casts the validated args to `ValidateCodeParams`.
+ * Both forms are optional at the schema level and the handler requires exactly one,
+ * because a zod union of two object shapes defeats the SDK's JSON-Schema conversion
+ * — it emits `anyOf`, which several MCP clients do not surface to the model at all.
+ * Two optional fields with a documented rule converts cleanly and reads clearly.
+ *
+ * WHAT THE MODEL SEES IS THE CONVERSION, NOT THIS. Everything an agent knows about
+ * the arguments arrives as the JSON Schema this shape converts to, so a constraint
+ * that does not convert may as well not be advertised at all. Prefer a zod builtin
+ * over a `.refine` wherever one expresses the rule; `transport/validate-code.spec.ts`
+ * pins the emitted document end to end.
+ *
+ * Typed as `ZodRawShape` (not the inferred literal shape) so `registerTool` does not
+ * instantiate excessively deeply over the schema (TS2589 under zod 3.25).
  */
 export declare const VALIDATE_CODE_INPUT: ZodRawShape;
+/**
+ * The agent-facing prose, exported so tests can pin claims that must not rot. The
+ * description is the agent's whole understanding of this tool; a stale sentence
+ * here misleads silently.
+ */
+export declare const TOOL_TEXT: {
+    readonly VALIDATE_CODE_DESCRIPTION: string;
+};
 export declare function registerValidateCode(server: McpServer, ctx: SupervisorContext): void;
+/**
+ * The tool handler: normalize the input shape, validate, and shape the response to
+ * match what was asked.
+ *
+ * Returns the flat single-file result for the single form and the per-file envelope
+ * for the batch form — the response mirrors the request, so a caller never parses a
+ * shape it did not ask for.
+ */
+export declare function runValidateCode(ctx: SupervisorContext, params: ValidateCodeParams, overrides?: Partial<ValidateAdapters>): Promise<ValidateCodeResult | ValidateFilesResult>;
+export { MAX_BATCH_BYTES, MAX_BATCH_FILES };