craftdriver 1.6.0 → 1.8.0

package/dist/cli/locatorCandidates.js

@@ -0,0 +1,190 @@
+import { CraftdriverError, ErrorCode } from '../lib/errors.js';
+import { parseSelector, describeSelector } from './selector.js';
+import { PAGE_SEMANTICS_JS } from './pageSemantics.js';
+/** Ordered best-first; the cap keeps output bounded for agent contexts. */
+const MAX_CANDIDATES = 8;
+const MAX_NAME = 80;
+/**
+ * Ids and names that are obviously build- or framework-generated. A CSS
+ * selector built on one of these looks durable and is not, which is worse
+ * than offering no CSS candidate at all.
+ */
+function looksGenerated(value) {
+    return (/^[0-9]/.test(value) ||
+        /[0-9a-f]{8,}/i.test(value) ||
+        /^(:r|ember\d|mui-|radix-|headlessui-|react-aria-)/.test(value) ||
+        /\d{4,}/.test(value));
+}
+/**
+ * Whether a page-derived string can be used verbatim in an exact-match
+ * locator. Long values are rejected rather than truncated: `By.role` and
+ * friends match exactly, so an elided value resolves to nothing while
+ * looking like a usable candidate.
+ */
+function usableAsExactMatch(value) {
+    return value.length > 0 && value.length <= MAX_NAME;
+}
+export async function locatorCandidates(browser, by, limit = 5) {
+    const els = await browser.findAll(by);
+    if (els.length === 0) {
+        throw new CraftdriverError(ErrorCode.NO_MATCH, `locators: no element matches ${describeSelector(by)}`, { detail: { selector: describeSelector(by) } });
+    }
+    // Mark the target, then read its evidence from page scope. The mark is
+    // what lets validation prove a candidate resolved back to *this* node.
+    const nonce = `p${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+    await els[0].evaluate((node, stamp) => {
+        node
+            .setAttribute('data-craftdriver-probe', stamp);
+    }, nonce);
+    try {
+        const page = await browser.activePage();
+        const raw = await page.evaluate(jsEvidence(nonce));
+        if (!raw || typeof raw !== 'object') {
+            return { target: describeSelector(by), candidates: [], best: null, note: 'element not readable' };
+        }
+        const evidence = raw;
+        const proposed = propose(evidence);
+        const validated = [];
+        for (const candidate of proposed.slice(0, MAX_CANDIDATES)) {
+            validated.push(await validate(browser, candidate, nonce));
+            if (validated.filter((c) => c.status === 'unique').length >= limit)
+                break;
+        }
+        const best = validated.find((c) => c.status === 'unique') ?? null;
+        return {
+            target: describeSelector(by),
+            candidates: validated.slice(0, Math.max(limit, 1) + 2),
+            best: best ? best.selector : null,
+            ...(best
+                ? {}
+                : {
+                    note: 'no durable locator resolved uniquely; add a data-testid to this element ' +
+                        'rather than committing a positional selector',
+                }),
+        };
+    }
+    finally {
+        // Never leave the probe attribute on the page — it would show up in
+        // the agent's next snapshot and in any DOM the user inspects.
+        await els[0]
+            .evaluate((node) => {
+            node
+                .removeAttribute('data-craftdriver-probe');
+        })
+            .catch(() => undefined);
+    }
+}
+/**
+ * Page-side evidence extraction. Runs as a string body (the build has no
+ * DOM lib) and reads only what the live document actually offers.
+ * `nonce` is generated here and JSON-encoded, so it cannot break out.
+ *
+ * Role and name come from the shared extractor, so a candidate can never
+ * describe the element differently from the snapshot the agent just read.
+ * `role` is deliberately the ARIA role or nothing: proposing `role=` for an
+ * element that has no ARIA role produces a locator that resolves to zero
+ * elements, which is worse than offering no role candidate at all.
+ */
+function jsEvidence(nonce) {
+    return `
+${PAGE_SEMANTICS_JS}
+const el = document.querySelector('[data-craftdriver-probe=' + ${JSON.stringify(JSON.stringify(nonce))} + ']');
+if (!el) return null;
+const tag = el.tagName.toLowerCase();
+const name = accName(el);
+const text = (el.textContent || '').trim().replace(/\\s+/g, ' ');
+return {
+  role: ariaRole(el),
+  name: name || null,
+  label: associatedLabel(el),
+  testid: el.getAttribute('data-testid') || el.getAttribute('data-test-id'),
+  text: text || null,
+  id: el.id || null,
+  nameAttr: el.getAttribute('name'),
+  tag: tag,
+  nonce: ${JSON.stringify(nonce)}
+};
+`;
+}
+/** Build candidates in durability order. */
+function propose(e) {
+    const out = [];
+    // 1. Role + accessible name — survives restyling and DOM reshuffles.
+    //
+    // Never truncate a value destined for an exact-match locator: an
+    // ellipsis guarantees it resolves to nothing. Skip instead, and let a
+    // later candidate carry the element. `]` would also break the
+    // `role=x[name=y]` grammar, which has no escape for it.
+    if (e.role && e.name && usableAsExactMatch(e.name) && !e.name.includes(']')) {
+        out.push({
+            kind: 'role',
+            selector: `role=${e.role}[name=${e.name}]`,
+            code: `By.role(${JSON.stringify(e.role)}, { name: ${JSON.stringify(e.name)} })`,
+        });
+    }
+    // 2. Associated label — the thing a user actually reads for form fields.
+    if (e.label && usableAsExactMatch(e.label)) {
+        out.push({
+            kind: 'label',
+            selector: `label=${e.label}`,
+            code: `By.labelText(${JSON.stringify(e.label)})`,
+        });
+    }
+    // 3. Test id — durable by contract when the app ships one.
+    if (e.testid) {
+        out.push({
+            kind: 'testid',
+            selector: `testid=${e.testid}`,
+            code: `By.testId(${JSON.stringify(e.testid)})`,
+        });
+    }
+    // 4. Text — durable only where it is unique, which validation decides.
+    if (e.text && usableAsExactMatch(e.text)) {
+        out.push({
+            kind: 'text',
+            selector: `text=${e.text}`,
+            code: `By.text(${JSON.stringify(e.text)})`,
+        });
+    }
+    // 5. Minimal CSS, last, and only when it is not obviously generated.
+    //
+    // The id also has to survive being written bare into a selector: `.`,
+    // `:` and friends are CSS syntax, so `#user.email` silently means
+    // "id user AND class email", and a quote breaks the generated code.
+    if (e.id && !looksGenerated(e.id) && /^[A-Za-z][A-Za-z0-9_-]*$/.test(e.id)) {
+        out.push({
+            kind: 'css',
+            selector: `#${e.id}`,
+            code: `By.css(${JSON.stringify('#' + e.id)})`,
+        });
+    }
+    if (e.nameAttr && !looksGenerated(e.nameAttr)) {
+        const css = `${e.tag}[name=${JSON.stringify(e.nameAttr)}]`;
+        out.push({ kind: 'css', selector: `css=${css}`, code: `By.css(${JSON.stringify(css)})` });
+    }
+    return out;
+}
+/**
+ * Re-resolve a candidate against the live document.
+ *
+ * Uniqueness alone is not enough — a selector can match exactly one
+ * element that is not the one the agent asked about. The probe attribute
+ * settles identity.
+ */
+async function validate(browser, candidate, nonce) {
+    try {
+        const els = await browser.findAll(parseSelector(candidate.selector));
+        if (els.length === 0)
+            return { ...candidate, status: 'missing', matches: 0 };
+        if (els.length > 1)
+            return { ...candidate, status: 'ambiguous', matches: els.length };
+        const hit = await els[0].getAttribute('data-craftdriver-probe').catch(() => null);
+        return hit === nonce
+            ? { ...candidate, status: 'unique', matches: 1 }
+            : { ...candidate, status: 'ambiguous', matches: 1 };
+    }
+    catch {
+        return { ...candidate, status: 'missing', matches: 0 };
+    }
+}
+//# sourceMappingURL=locatorCandidates.js.map

package/dist/cli/locatorCandidates.js.map

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

package/dist/cli/mcp/artifacts.d.ts

@@ -1,12 +1,39 @@
+import { CraftdriverError } from '../../lib/errors.js';
 export interface ArtifactWriteResult {
     path: string;
     bytes: number;
 }
+/**
+ * Quota for one session's spill directory.
+ *
+ * The store is written to automatically, on every oversized result, for the
+ * whole life of a long-running session — and nothing deletes it. Without a
+ * quota a loop that snapshots a large page fills the disk silently, which is
+ * a worse failure than a refused spill: the caller falls back to an inline
+ * preview and the session keeps working.
+ */
+export declare const MAX_ARTIFACTS = 500;
+export declare const MAX_TOTAL_BYTES: number;
+/** Raised when a write would exceed the session's artifact quota. */
+export declare class ArtifactQuotaError extends CraftdriverError {
+    constructor(message: string);
+}
+export interface ArtifactStoreLimits {
+    /** Test/embedding override; production uses {@link MAX_ARTIFACTS}. */
+    maxArtifacts?: number;
+    /** Test/embedding override; production uses {@link MAX_TOTAL_BYTES}. */
+    maxTotalBytes?: number;
+}
 export declare class ArtifactStore {
     private dir;
     private ready;
     private counter;
-    constructor(rootOverride?: string);
+    private artifactCount;
+    private totalBytes;
+    private reservations;
+    private readonly maxArtifacts;
+    private readonly maxTotalBytes;
+    constructor(rootOverride?: string, limits?: ArtifactStoreLimits);
     /** Absolute path to the artifact directory (may not exist yet). */
     get directory(): string;
     private ensure;
@@ -16,12 +43,23 @@ export declare class ArtifactStore {
      * `screenshot.png` or `eval.json`.
      */
     write(nameHint: string, data: Buffer | string): Promise<ArtifactWriteResult>;
+    private assertWithinQuota;
     /**
      * Allocate a path for an artifact the caller will write itself (e.g.
      * pass to `browser.screenshot({ path })`). Doesn't touch the disk
      * beyond `mkdir -p` of the directory.
      */
     allocate(nameHint: string): Promise<string>;
+    /**
+     * Account for a file written to a path returned by {@link allocate}.
+     *
+     * Screenshots are written by the browser, so their size is known only after
+     * capture. If the actual file would cross the quota, remove that one file and
+     * fail the tool call rather than letting the supposedly bounded store grow.
+     */
+    commitAllocated(path: string): Promise<ArtifactWriteResult>;
+    /** Release a failed allocation and remove any partial file. Idempotent. */
+    releaseAllocated(path: string): Promise<void>;
 }
 /**
  * Spill threshold in bytes. Content blocks longer than this are

package/dist/cli/mcp/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/artifacts.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,OAAO,CAAK;gBAER,YAAY,CAAC,EAAE,MAAM;IAQjC,mEAAmE;IACnE,IAAI,SAAS,IAAI,MAAM,CAEtB;YAEa,MAAM;IAOpB;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAUlF;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAMlD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAI/E"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/artifacts.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,gBAAgB,EAAa,MAAM,qBAAqB,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,eAAe,QAAoB,CAAC;AAEjD,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,OAAO,EAAE,MAAM;CAM5B;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,mBAAwB;IAUnE,mEAAmE;IACnE,IAAI,SAAS,IAAI,MAAM,CAEtB;YAEa,MAAM;IAOpB;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAoBlF,OAAO,CAAC,iBAAiB;IAazB;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBjD;;;;;;OAMG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsBjE,2EAA2E;IACrE,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAKpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAI/E"}

package/dist/cli/mcp/artifacts.js

@@ -24,19 +24,47 @@
  * reclaims them eventually. Override the root if you need a custom
  * cleanup policy.
  */
-import { mkdir, writeFile } from 'fs/promises';
+import { chmod, mkdir, rm, stat, writeFile } from 'fs/promises';
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
+import { CraftdriverError, ErrorCode } from '../../lib/errors.js';
+/**
+ * Quota for one session's spill directory.
+ *
+ * The store is written to automatically, on every oversized result, for the
+ * whole life of a long-running session — and nothing deletes it. Without a
+ * quota a loop that snapshots a large page fills the disk silently, which is
+ * a worse failure than a refused spill: the caller falls back to an inline
+ * preview and the session keeps working.
+ */
+export const MAX_ARTIFACTS = 500;
+export const MAX_TOTAL_BYTES = 256 * 1024 * 1024;
+/** Raised when a write would exceed the session's artifact quota. */
+export class ArtifactQuotaError extends CraftdriverError {
+    constructor(message) {
+        super(ErrorCode.STATE_INVALID, message, {
+            hint: 'start a fresh MCP session, or clean the configured artifact root',
+        });
+        this.name = 'ArtifactQuotaError';
+    }
+}
 export class ArtifactStore {
     dir;
     ready = null;
     counter = 0;
-    constructor(rootOverride) {
+    artifactCount = 0;
+    totalBytes = 0;
+    reservations = new Set();
+    maxArtifacts;
+    maxTotalBytes;
+    constructor(rootOverride, limits = {}) {
         const root = rootOverride
             ?? process.env.CRAFTDRIVER_MCP_ARTIFACTS_DIR
             ?? tmpdir();
         const stamp = `${process.pid}-${Date.now().toString(36)}`;
         this.dir = resolve(root, `craftdriver-mcp-${stamp}`);
+        this.maxArtifacts = limits.maxArtifacts ?? MAX_ARTIFACTS;
+        this.maxTotalBytes = limits.maxTotalBytes ?? MAX_TOTAL_BYTES;
     }
     /** Absolute path to the artifact directory (may not exist yet). */
     get directory() {
@@ -44,7 +72,7 @@ export class ArtifactStore {
     }
     async ensure() {
         if (!this.ready) {
-            this.ready = mkdir(this.dir, { recursive: true }).then(() => undefined);
+            this.ready = mkdir(this.dir, { recursive: true, mode: 0o700 }).then(() => undefined);
         }
         await this.ready;
     }
@@ -54,13 +82,32 @@ export class ArtifactStore {
      * `screenshot.png` or `eval.json`.
      */
     async write(nameHint, data) {
-        await this.ensure();
+        const buf = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+        this.assertWithinQuota(buf.length);
         this.counter += 1;
+        this.artifactCount += 1;
+        this.totalBytes += buf.length;
         const seq = this.counter.toString().padStart(4, '0');
         const path = join(this.dir, `${seq}-${nameHint}`);
-        const buf = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
-        await writeFile(path, buf);
-        return { path, bytes: buf.length };
+        try {
+            await this.ensure();
+            await writeFile(path, buf, { mode: 0o600 });
+            return { path, bytes: buf.length };
+        }
+        catch (error) {
+            this.artifactCount -= 1;
+            this.totalBytes -= buf.length;
+            await rm(path, { force: true }).catch(() => { });
+            throw error;
+        }
+    }
+    assertWithinQuota(incoming) {
+        if (this.artifactCount >= this.maxArtifacts) {
+            throw new ArtifactQuotaError(`artifact store is full (${this.maxArtifacts} files in ${this.dir})`);
+        }
+        if (this.totalBytes + incoming > this.maxTotalBytes) {
+            throw new ArtifactQuotaError(`artifact store would exceed ${this.maxTotalBytes} bytes (${this.dir})`);
+        }
     }
     /**
      * Allocate a path for an artifact the caller will write itself (e.g.
@@ -68,10 +115,58 @@ export class ArtifactStore {
      * beyond `mkdir -p` of the directory.
      */
     async allocate(nameHint) {
-        await this.ensure();
+        // Reserve the count synchronously, before awaiting mkdir, so concurrent
+        // allocations cannot all observe the same free slot.
+        this.assertWithinQuota(0);
         this.counter += 1;
+        this.artifactCount += 1;
         const seq = this.counter.toString().padStart(4, '0');
-        return join(this.dir, `${seq}-${nameHint}`);
+        const path = join(this.dir, `${seq}-${nameHint}`);
+        this.reservations.add(path);
+        try {
+            await this.ensure();
+            return path;
+        }
+        catch (error) {
+            this.reservations.delete(path);
+            this.artifactCount -= 1;
+            throw error;
+        }
+    }
+    /**
+     * Account for a file written to a path returned by {@link allocate}.
+     *
+     * Screenshots are written by the browser, so their size is known only after
+     * capture. If the actual file would cross the quota, remove that one file and
+     * fail the tool call rather than letting the supposedly bounded store grow.
+     */
+    async commitAllocated(path) {
+        if (!this.reservations.has(path)) {
+            throw new Error(`artifact path was not allocated by this store: ${path}`);
+        }
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                throw new Error(`allocated artifact is not a regular file: ${path}`);
+            if (this.totalBytes + info.size > this.maxTotalBytes) {
+                throw new ArtifactQuotaError(`artifact store would exceed ${this.maxTotalBytes} bytes (${this.dir})`);
+            }
+            await chmod(path, 0o600);
+            this.totalBytes += info.size;
+            this.reservations.delete(path);
+            return { path, bytes: info.size };
+        }
+        catch (error) {
+            await this.releaseAllocated(path);
+            throw error;
+        }
+    }
+    /** Release a failed allocation and remove any partial file. Idempotent. */
+    async releaseAllocated(path) {
+        if (!this.reservations.delete(path))
+            return;
+        this.artifactCount -= 1;
+        await rm(path, { force: true }).catch(() => { });
     }
 }
 /**

package/dist/cli/mcp/artifacts.js.map

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

package/dist/cli/mcp/bounds.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Total response bounds for MCP tool results.
+ *
+ * Spilling a large `content` block to an artifact bounds what the *model*
+ * reads, but not what crosses the wire: the same value was still attached in
+ * full as `structuredContent`, so a 50 KB eval produced a 50,571-byte response
+ * with a 514-byte preview in front of it. Bounding one half of the payload
+ * while duplicating the other in full is worse than not bounding at all,
+ * because it looks bounded.
+ *
+ * So the cap here is on the **complete serialized response**, and the rules
+ * are:
+ *
+ * - **Never duplicate a large value.** If the preview already describes it,
+ *   `structuredContent` carries metadata and a bounded preview, not the value.
+ * - **Truncation is always visible.** `truncated`, `totalBytes` and the
+ *   retained byte count are part of the payload, so an agent can tell a short
+ *   answer from a shortened one.
+ * - **Never emit invalid UTF-8.** Cutting at a byte offset can split a
+ *   multi-byte sequence or a surrogate pair and produce a replacement
+ *   character — or an unparseable frame. Truncation happens on code-point
+ *   boundaries.
+ */
+/** Cap on one complete serialized `tools/call` result. */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+export declare function resolveMaxResponseBytes(env?: NodeJS.ProcessEnv): number;
+export { utf8Bytes, truncateUtf8 } from '../bounds.js';
+export interface BoundedStructured {
+    truncated: true;
+    /** Bytes the full value would have occupied. */
+    totalBytes: number;
+    /** Bytes actually retained in `preview`. */
+    previewBytes: number;
+    preview: string;
+}
+/**
+ * Replace an oversized structured value with a bounded, self-describing
+ * preview.
+ */
+export declare function boundStructured(value: unknown, budgetBytes: number): BoundedStructured;
+/**
+ * The minimum shape this needs. Kept structural and generic so the caller's
+ * richer `ContentBlock`/`ToolCallResult` types pass through unchanged rather
+ * than being widened to a local copy.
+ */
+interface BoundableResult {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: unknown;
+}
+/**
+ * Bound a complete tool result to `maxBytes` of serialized JSON.
+ *
+ * Order matters. `structuredContent` is reduced first because `content` is
+ * what the agent actually reads and has usually already been spilled to an
+ * artifact with a path in it — dropping that first would take away the pointer
+ * to the full data while keeping the bulk. Only if the result is still over
+ * budget are content blocks trimmed, newest-last, each keeping a marker so a
+ * shortened block never reads as a complete one.
+ */
+export declare function boundToolResult<T extends BoundableResult>(result: T, maxBytes: number): T;
+//# sourceMappingURL=bounds.d.ts.map

package/dist/cli/mcp/bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounds.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/bounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAEpD,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAOpF;AAKD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAcvD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,IAAI,CAAC;IAChB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,iBAAiB,CActF;AAED;;;;GAIG;AACH,UAAU,eAAe;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CA0CzF"}

package/dist/cli/mcp/bounds.js

@@ -0,0 +1,124 @@
+/**
+ * Total response bounds for MCP tool results.
+ *
+ * Spilling a large `content` block to an artifact bounds what the *model*
+ * reads, but not what crosses the wire: the same value was still attached in
+ * full as `structuredContent`, so a 50 KB eval produced a 50,571-byte response
+ * with a 514-byte preview in front of it. Bounding one half of the payload
+ * while duplicating the other in full is worse than not bounding at all,
+ * because it looks bounded.
+ *
+ * So the cap here is on the **complete serialized response**, and the rules
+ * are:
+ *
+ * - **Never duplicate a large value.** If the preview already describes it,
+ *   `structuredContent` carries metadata and a bounded preview, not the value.
+ * - **Truncation is always visible.** `truncated`, `totalBytes` and the
+ *   retained byte count are part of the payload, so an agent can tell a short
+ *   answer from a shortened one.
+ * - **Never emit invalid UTF-8.** Cutting at a byte offset can split a
+ *   multi-byte sequence or a surrogate pair and produce a replacement
+ *   character — or an unparseable frame. Truncation happens on code-point
+ *   boundaries.
+ */
+import { utf8Bytes, truncateUtf8 } from '../bounds.js';
+/** Cap on one complete serialized `tools/call` result. */
+export const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024;
+export function resolveMaxResponseBytes(env = process.env) {
+    const raw = env.CRAFTDRIVER_MCP_MAX_RESPONSE_BYTES;
+    if (!raw)
+        return DEFAULT_MAX_RESPONSE_BYTES;
+    const n = Number.parseInt(raw, 10);
+    // A cap below the smallest useful envelope would make every response a
+    // truncation notice, so ignore nonsense rather than honouring it.
+    return Number.isFinite(n) && n >= 1024 ? n : DEFAULT_MAX_RESPONSE_BYTES;
+}
+// The byte-counting and code-point-safe truncation primitives are shared with
+// the transport-neutral bound in `../bounds.js`; re-exported here so the MCP
+// module stays the single import for callers working on its envelope.
+export { utf8Bytes, truncateUtf8 } from '../bounds.js';
+/** Serialized size of a value as it would appear in the response. */
+function serializedBytes(value) {
+    if (value === undefined)
+        return 0;
+    try {
+        return utf8Bytes(JSON.stringify(value) ?? '');
+    }
+    catch {
+        // Circular or otherwise unserializable: treat as over budget so the
+        // caller replaces it rather than throwing while building a response.
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/**
+ * Replace an oversized structured value with a bounded, self-describing
+ * preview.
+ */
+export function boundStructured(value, budgetBytes) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        serialized = String(value);
+    }
+    const preview = truncateUtf8(serialized, Math.max(budgetBytes, 0));
+    return {
+        truncated: true,
+        totalBytes: utf8Bytes(serialized),
+        previewBytes: utf8Bytes(preview),
+        preview,
+    };
+}
+/**
+ * Bound a complete tool result to `maxBytes` of serialized JSON.
+ *
+ * Order matters. `structuredContent` is reduced first because `content` is
+ * what the agent actually reads and has usually already been spilled to an
+ * artifact with a path in it — dropping that first would take away the pointer
+ * to the full data while keeping the bulk. Only if the result is still over
+ * budget are content blocks trimmed, newest-last, each keeping a marker so a
+ * shortened block never reads as a complete one.
+ */
+export function boundToolResult(result, maxBytes) {
+    if (serializedBytes(result) <= maxBytes)
+        return result;
+    const bounded = { ...result };
+    if (bounded.structuredContent !== undefined) {
+        // Leave room for the content blocks and the envelope; a quarter of the
+        // budget is enough for a preview to be useful without crowding out the
+        // text the agent reads.
+        const structuredBudget = Math.floor(maxBytes / 4);
+        bounded.structuredContent = boundStructured(bounded.structuredContent, structuredBudget);
+    }
+    if (serializedBytes(bounded) <= maxBytes)
+        return bounded;
+    // Still over: trim the text blocks. Work from the last block backwards, so
+    // the primary result survives longer than a trailing snapshot diff.
+    const blocks = bounded.content.map((block) => ({ ...block }));
+    const marker = '\n… (truncated)';
+    const over = () => serializedBytes({ ...bounded, content: blocks }) - maxBytes;
+    for (let i = blocks.length - 1; i >= 0; i--) {
+        if (over() <= 0)
+            break;
+        const block = blocks[i];
+        if (typeof block.text !== 'string')
+            continue;
+        const original = block.text;
+        let keep = Math.max(0, utf8Bytes(original) - over() - utf8Bytes(marker));
+        // Converge rather than assuming one pass lands under the cap: JSON
+        // escaping makes the serialized size exceed the raw byte count (a newline
+        // is one byte but two characters once escaped), so a single subtraction
+        // reliably overshoots by a little.
+        for (let guard = 0; guard < 8; guard++) {
+            block.text = keep > 0 ? truncateUtf8(original, keep) + marker : marker;
+            const excess = over();
+            if (excess <= 0 || keep === 0)
+                break;
+            keep = Math.max(0, keep - excess);
+        }
+    }
+    bounded.content = blocks;
+    return bounded;
+}
+//# sourceMappingURL=bounds.js.map

package/dist/cli/mcp/bounds.js.map

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