@molecule/api-ai-tools 1.11.1 → 1.13.0

package/dist/playwright-report.js

@@ -0,0 +1,406 @@
+/**
+ * The standard Playwright machine report, kept beside a run's log instead of inferred from it.
+ *
+ * The execution wrapper already puts a background suite on Playwright's `list` reporter and
+ * preserves a file reporter the executor named ({@link ./utilities.js} `withPlaywrightRunReport`,
+ * `streamingBackgroundCommand`). That log is text: which failure a trace, a route or a locator
+ * belongs to has to be reconstructed from printed headings, and a mis-join reads one failing
+ * test's evidence as another's (xr-molecule-flash-m411). Playwright already writes the answer down
+ * itself — its built-in `json` reporter records every test's own identity (project, file, line,
+ * column, title path, status, retries) and every attachment the runner saved for THAT test, path
+ * included.
+ *
+ * So the wrapper adds the `json` reporter to a run it already rewrites, sends its output to a
+ * per-run file with the reporter's own `PLAYWRIGHT_JSON_OUTPUT_FILE` option, and this module turns
+ * that file into a small, bounded record on the tool result ({@link PlaywrightRunReport}). The
+ * whole file stays where it was written, so full evidence has a path; the record carries only what
+ * a diagnosis needs.
+ *
+ * Honesty rules, which every reader below follows:
+ *
+ * - A missing, empty, truncated or wrongly shaped file is NOT "the run failed nothing": it is
+ *   `missing` / `malformed`, and a record that parsed but is not a whole run (`errors` present, no
+ *   `suites`) is `partial`. Only a record with the runner's own stats and suite tree is `complete`.
+ * - The record never carries a pass/fail verdict and must never be read as one. Suite selection,
+ *   retries, budgets and the platform's own proof decisions stay exactly where they were.
+ * - Nothing here parses console output, and nothing reads a report the executor asked for itself
+ *   (a `json` reporter already named on the command, or a `PLAYWRIGHT_JSON_OUTPUT_FILE` the command
+ *   sets): the executor's own artifact is theirs.
+ *
+ * @module
+ */
+import { posix } from 'path';
+/**
+ * The environment variable Playwright's built-in `json` reporter takes its output path from
+ * (`resolveOutputFile("JSON", …)`), resolved against the runner's own working directory. An
+ * absolute path is used here, so the file lands in the run's scratch area whatever directory the
+ * suite runs from.
+ */
+export const PLAYWRIGHT_REPORT_ENV = 'PLAYWRIGHT_JSON_OUTPUT_FILE';
+/** The file name a background task's report is written to, beside its own log. */
+export const PLAYWRIGHT_REPORT_SUFFIX = '.playwright.json';
+/**
+ * How big a report may be before this module refuses to summarize it. The file stays readable at
+ * its path; the record only says so. A whole 139-test suite's report is well under a megabyte; a
+ * report past this is not one a tool result should carry.
+ */
+export const MAX_REPORT_PARSE_CHARS = 8_000_000;
+/** How many failing tests a record lists before the rest are counted in `omittedFailures`. */
+export const MAX_REPORTED_FAILURES = 12;
+/** How many attachments one failing test keeps in the record (`trace` first). */
+export const MAX_REPORTED_ATTACHMENTS = 4;
+/** How much of one failure's own error text the record keeps. */
+export const MAX_REPORTED_ERROR_CHARS = 400;
+/** How much of one printed path the record keeps. */
+const MAX_REPORTED_PATH_CHARS = 300;
+/** How much of one title the record keeps. */
+const MAX_REPORTED_TITLE_CHARS = 300;
+/**
+ * The terminal formatting Playwright bakes into an error message — `expect` diffs are written for a
+ * terminal, so the report's own `error.message` carries SGR sequences. Stripped here, before the
+ * consumer's redactor, so a result never carries `[2m`/`[22m` fragments as if they were text.
+ */
+// eslint-disable-next-line no-control-regex -- an escape sequence IS a control character
+const ANSI_SEQUENCE = /\u001B\[[0-9;?]*[A-Za-z]/g;
+/** One plain record out of unknown JSON, or null when the value is not an object. */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A finite number from unknown JSON, or null. */
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** A non-empty string from unknown JSON, or null. */
+function asString(value) {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+/** A string cut to {@link MAX_REPORTED_PATH_CHARS}. */
+function boundedPath(value) {
+    return value.length > MAX_REPORTED_PATH_CHARS
+        ? `${value.slice(0, MAX_REPORTED_PATH_CHARS)}…`
+        : value;
+}
+/** A string cut to {@link MAX_REPORTED_TITLE_CHARS}. */
+function boundedTitle(value) {
+    return value.length > MAX_REPORTED_TITLE_CHARS
+        ? `${value.slice(0, MAX_REPORTED_TITLE_CHARS)}…`
+        : value;
+}
+/**
+ * The report statuses for which the report's own per-test identities and attachments may be used.
+ *
+ * `partial` is included because a partial report's suite tree, where it parsed, is still the
+ * runner's own record of which test owns which attachment; `malformed` and `missing` are not,
+ * because nothing about them is runner data.
+ *
+ * @param status - One record's {@link PlaywrightReportStatus}.
+ * @returns True when the record's tests and attachments are the runner's own.
+ */
+export function reportCarriesIdentities(status) {
+    return status === 'complete' || status === 'partial';
+}
+/**
+ * The attachments a stored record actually carries.
+ *
+ * A record read back from a transcript is not guaranteed to be the shape this module wrote — a
+ * damaged, truncated or hand-edited one can carry a null entry, a non-array field or an attachment
+ * without a path. Every reader goes through here so a damaged record answers "no artifact", never a
+ * thrown error and never another test's trace.
+ *
+ * @param test - One entry of {@link PlaywrightRunReport.failures}, as stored.
+ * @returns Its well-shaped attachments, in the record's own order.
+ */
+function storedAttachments(test) {
+    const raw = test?.attachments;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const attachment = asRecord(entry);
+        if (attachment === null)
+            continue;
+        const path = asString(attachment.path);
+        if (path === null)
+            continue;
+        out.push({
+            name: asString(attachment.name) ?? '',
+            contentType: asString(attachment.contentType),
+            path,
+        });
+    }
+    return out;
+}
+/**
+ * The attachment paths a stored test record carries, `trace` first.
+ *
+ * @param test - One entry of {@link PlaywrightRunReport.failures}, as stored.
+ * @returns Every saved path the record can prove, in its own order.
+ */
+export function reportTestAttachmentPaths(test) {
+    return storedAttachments(test).map((attachment) => attachment.path);
+}
+/**
+ * The directory a test result's own artifacts were saved in, or null when the report names none.
+ *
+ * Playwright writes one directory per test attempt under the run's `outputDir`, and every artifact
+ * of that attempt — `trace.zip` included — sits in it. The directory is therefore the exact
+ * ownership mark for a trace: two tests' traces are never in one another's directory. A damaged
+ * record whose attachment entries carry no path answers null, so nothing is claimed from it.
+ *
+ * @param test - One entry of {@link PlaywrightRunReport.failures}, as stored.
+ * @returns The posix-normalized directory, or null.
+ */
+export function reportTestArtifactDir(test) {
+    const attachment = storedAttachments(test).find((one) => one.path !== '');
+    return attachment === undefined ? null : posix.dirname(attachment.path);
+}
+/** The attachments of one attempt, `trace` first and bounded. */
+function attachmentsOf(result) {
+    const raw = Array.isArray(result.attachments) ? result.attachments : [];
+    const out = [];
+    for (const entry of raw) {
+        const attachment = asRecord(entry);
+        if (attachment === null)
+            continue;
+        const path = asString(attachment.path);
+        if (path === null)
+            continue;
+        out.push({
+            name: asString(attachment.name) ?? '',
+            contentType: asString(attachment.contentType),
+            path: boundedPath(path),
+        });
+    }
+    // `trace` first: it is the artifact a failure diagnosis reads, and the `body` Playwright may
+    // inline is deliberately dropped — it is base64 evidence the file path already carries.
+    out.sort((left, right) => Number(right.name === 'trace') - Number(left.name === 'trace'));
+    return out.slice(0, MAX_REPORTED_ATTACHMENTS);
+}
+/**
+ * The attempt whose evidence describes the test's failure: the LAST attempt that did not pass.
+ *
+ * A retried test reports one result per attempt. A flaky test's final attempt passed, but the
+ * failure it is reported for happened in the earlier one, and that is where the trace was kept
+ * (`retain-on-failure`).
+ *
+ * @param results - One test's `results` array, in attempt order.
+ * @returns The chosen attempt and its index, or null when there is none.
+ */
+function evidenceAttempt(results) {
+    let chosen = null;
+    for (let index = 0; index < results.length; index += 1) {
+        const result = asRecord(results[index]);
+        const status = result === null ? null : asString(result.status);
+        if (result === null || status === null)
+            continue;
+        if (status !== 'passed' && status !== 'skipped')
+            chosen = { result, index };
+    }
+    if (chosen !== null)
+        return chosen;
+    const last = asRecord(results[results.length - 1]);
+    return last === null ? null : { result: last, index: results.length - 1 };
+}
+/** One test's own error text, bounded and sanitized, or null. */
+function errorOf(result, sanitize) {
+    const errors = Array.isArray(result.errors) ? result.errors : [];
+    const first = asRecord(errors[0]);
+    const message = (first === null ? null : asString(first.message)) ?? null;
+    const direct = asRecord(result.error);
+    const text = message ?? (direct === null ? null : asString(direct.message));
+    if (text === null)
+        return null;
+    const plain = text.replace(ANSI_SEQUENCE, '');
+    const bounded = plain.length > MAX_REPORTED_ERROR_CHARS ? `${plain.slice(0, MAX_REPORTED_ERROR_CHARS)}…` : plain;
+    return sanitize(bounded);
+}
+/** Whether one test entry should be listed: a failure, a retried failure, or an interruption. */
+function isFailingTest(status, results) {
+    if (status === 'unexpected' || status === 'flaky')
+        return true;
+    return results.some((entry) => {
+        const result = asRecord(entry);
+        const resultStatus = result === null ? null : asString(result.status);
+        return (resultStatus === 'failed' || resultStatus === 'timedOut' || resultStatus === 'interrupted');
+    });
+}
+/**
+ * Every test entry under one suite, with the suite titles that lead to it.
+ *
+ * @param suite - One suite of the report's tree.
+ * @param prefix - The titles of the suites above it.
+ * @param out - Where the entries collect.
+ * @param fileSuite - True for a top-level entry, whose title is the file path rather than a
+ *   `describe` block: it is not part of a test's title path.
+ */
+function specsIn(suite, prefix, out, fileSuite = false) {
+    const title = fileSuite ? null : asString(suite.title);
+    const titlePath = title === null ? [...prefix] : [...prefix, title];
+    const specs = Array.isArray(suite.specs) ? suite.specs : [];
+    for (const entry of specs) {
+        const spec = asRecord(entry);
+        if (spec !== null)
+            out.push({ spec, titlePath });
+    }
+    const children = Array.isArray(suite.suites) ? suite.suites : [];
+    for (const entry of children) {
+        const child = asRecord(entry);
+        if (child !== null)
+            specsIn(child, titlePath, out);
+    }
+}
+/** One record for a report this module could not parse, with the reason. */
+function unusable(status, path, reason) {
+    return { status, path, reason, stats: null, failures: [], omittedFailures: 0 };
+}
+/**
+ * Summarize one Playwright `json` report into the bounded record a tool result carries.
+ *
+ * Pure text in, record out: the caller reads the file (and decides whether it may), so this is
+ * testable against genuine reports and against malformed controls alike.
+ *
+ * @param text - The report file's text, exactly as written.
+ * @param options - Where the file is, and the consumer's redactor for error text.
+ * @param options.path - The report file's path, carried on the record for full evidence.
+ * @param options.sanitize - Redactor applied to error text (defaults to the identity).
+ * @returns The bounded record; never a verdict.
+ */
+export function summarizePlaywrightReport(text, options) {
+    const path = options.path;
+    const sanitize = options.sanitize ?? ((value) => value);
+    if (text.trim() === '')
+        return unusable('malformed', path, 'the report file is empty');
+    if (text.length > MAX_REPORT_PARSE_CHARS)
+        return unusable('partial', path, `the report is larger than ${MAX_REPORT_PARSE_CHARS} characters and was not summarized`);
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch (_error) {
+        // A truncated or non-JSON file is not runner data at all: say malformed, never zero failures.
+        return unusable('malformed', path, 'the report file is not valid JSON (it may be truncated)');
+    }
+    const report = asRecord(root);
+    if (report === null)
+        return unusable('malformed', path, 'the report is not a JSON object');
+    const rawStats = asRecord(report.stats);
+    const expected = rawStats === null ? null : asNumber(rawStats.expected);
+    const skipped = rawStats === null ? null : asNumber(rawStats.skipped);
+    const unexpected = rawStats === null ? null : asNumber(rawStats.unexpected);
+    const flaky = rawStats === null ? null : asNumber(rawStats.flaky);
+    const durationMs = rawStats === null ? null : asNumber(rawStats.duration);
+    const stats = expected === null ||
+        skipped === null ||
+        unexpected === null ||
+        flaky === null ||
+        durationMs === null
+        ? null
+        : { expected, skipped, unexpected, flaky, durationMs };
+    const suites = Array.isArray(report.suites) ? report.suites : null;
+    const errors = Array.isArray(report.errors) ? report.errors.length : 0;
+    if (suites === null)
+        return unusable('partial', path, 'the report carries no suite tree (the run was cut short)');
+    // Every spec under every project, with the describe titles that lead to it. The report's
+    // top-level entries are FILE suites — their title is the file path the spec's own `file` already
+    // carries — so that level is not part of a test's title path.
+    const specs = [];
+    for (const entry of suites) {
+        const suite = asRecord(entry);
+        if (suite !== null)
+            specsIn(suite, [], specs, true);
+    }
+    const failures = [];
+    for (const { spec, titlePath } of specs) {
+        const specTitle = asString(spec.title) ?? '';
+        const file = asString(spec.file) ?? '';
+        const line = asNumber(spec.line) ?? 0;
+        const column = asNumber(spec.column) ?? 0;
+        const specId = asString(spec.id);
+        const tests = Array.isArray(spec.tests) ? spec.tests : [];
+        for (const entry of tests) {
+            const test = asRecord(entry);
+            if (test === null)
+                continue;
+            const status = asString(test.status) ?? '';
+            const results = Array.isArray(test.results) ? test.results : [];
+            if (!isFailingTest(status, results))
+                continue;
+            const evidence = evidenceAttempt(results);
+            const titles = [...titlePath, specTitle].filter((part) => part !== '');
+            failures.push({
+                id: specId,
+                project: asString(test.projectName),
+                file: boundedPath(file),
+                line,
+                column,
+                titlePath: titles.map(boundedTitle),
+                title: boundedTitle(specTitle),
+                status,
+                attempts: results.length,
+                retry: evidence === null ? 0 : (asNumber(evidence.result.retry) ?? evidence.index),
+                durationMs: evidence === null ? 0 : (asNumber(evidence.result.duration) ?? 0),
+                error: evidence === null ? null : errorOf(evidence.result, sanitize),
+                attachments: evidence === null ? [] : attachmentsOf(evidence.result),
+            });
+        }
+    }
+    const omittedFailures = Math.max(0, failures.length - MAX_REPORTED_FAILURES);
+    // The runner's tally and its own tree must agree. A record whose stats name more failures than
+    // the tree lists is not a whole record — a truncated write, a merged or hand-edited file — and
+    // must not be read as complete just because both fields parsed. The bound this module applies is
+    // counted in `omittedFailures`, so it is compared against the list BEFORE the cap.
+    const namedFailures = stats === null ? null : stats.unexpected + stats.flaky;
+    const treeShort = namedFailures !== null && failures.length < namedFailures;
+    // Playwright's own global errors mean the run did not walk everything it planned to (a config
+    // error, a worker crash): the per-test entries that did parse are still the runner's own.
+    const status = stats === null || errors > 0 || treeShort ? 'partial' : 'complete';
+    const reason = stats === null
+        ? 'the report carries no run stats'
+        : errors > 0
+            ? `the run reported ${errors} error(s) of its own`
+            : treeShort
+                ? `the run’s stats name ${namedFailures} failing test(s) but its tree lists ${failures.length}`
+                : undefined;
+    return {
+        status,
+        path,
+        ...(reason === undefined ? {} : { reason }),
+        stats,
+        failures: failures.slice(0, MAX_REPORTED_FAILURES),
+        omittedFailures,
+    };
+}
+/**
+ * The report path a command was launched with, when it is the one this platform sets.
+ *
+ * Read back from the launched script (and from a completed task's own command) so a record written
+ * before an API restart is still found: the path is the task's own id derived by
+ * {@link playwrightReportPathFor}, never a path parsed out of the executor's command.
+ *
+ * @param command - The command as it was launched.
+ * @param expectedPath - The one path this task's report may be at.
+ * @returns True when the command sets {@link PLAYWRIGHT_REPORT_ENV} to that exact path.
+ */
+export function commandWritesReportTo(command, expectedPath) {
+    const quoted = new RegExp(`(?:^|[\\s;])${PLAYWRIGHT_REPORT_ENV}=(['"]?)${escapeRegExp(expectedPath)}\\1(?:[\\s;]|$)`);
+    return quoted.test(command);
+}
+/**
+ * The report file a background task's own scratch files live beside.
+ *
+ * Derived from the task id, never from the command: the id is unique per launch, so two runs can
+ * never read one another's report, and the path survives a process restart the same way the task's
+ * log and exit file do.
+ *
+ * @param taskId - The `mol-bg-…` handle the launch returned.
+ * @returns The report file's absolute path.
+ */
+export function playwrightReportPathFor(taskId) {
+    return `/tmp/${taskId}${PLAYWRIGHT_REPORT_SUFFIX}`;
+}
+/** A string with every regular-expression metacharacter escaped. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA8V1C,CAAA"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAwW1C,CAAA"}

package/dist/schemas.js

@@ -71,6 +71,10 @@ export const TOOL_SCHEMAS = {
         parameters: {
             type: 'object',
             properties: {
+                intentional_redaction_placeholder: {
+                    type: 'boolean',
+                    description: 'Set true only when intentionally authoring a literal [REDACTED] placeholder. Default false: newly copied output placeholders are refused. This never disables secret-output masking.',
+                },
                 path: {
                     type: 'string',
                     description: 'Path to the file to write.',
@@ -89,6 +93,10 @@ export const TOOL_SCHEMAS = {
         parameters: {
             type: 'object',
             properties: {
+                intentional_redaction_placeholder: {
+                    type: 'boolean',
+                    description: 'Set true only when intentionally authoring a literal [REDACTED] placeholder. Default false: newly copied output placeholders are refused. This never disables secret-output masking.',
+                },
                 path: {
                     type: 'string',
                     description: 'Path to the file to edit.',

package/dist/server-command.d.ts

@@ -26,14 +26,18 @@ export declare const BACKGROUNDED: RegExp;
  * A program that SERVES: the scaffold's entry (`server.ts`/`server.js`), a package manager's
  * `start`/`dev`/`serve`/`preview` script, a Vite dev or preview server, `next start|dev`, or a
  * Python WSGI server. Matched against a command segment's own text, and against a script's SOURCE
- * when the command only names the script file.
+ * when the command only names the script file — but NEVER against an inline program's code
+ * (`node -e …`, `python3 -c …`), where this text is the user's program rather than a file being
+ * run: `require('…/node_modules/vite')` imports a module, it does not start a dev server
+ * (xr-molecule-flash-m391 +13:13, refused as "node starts a server" for exactly that line).
  */
 export declare const SERVER_PROGRAM: RegExp;
 /**
  * Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
  *
  * The over-budget reader's shape: at that point the command has already run, and only its text is
- * left to say whether "run a smaller unit" was ever the right advice.
+ * left to say whether "run a smaller unit" was ever the right advice. Inline/stdin programs
+ * remain unclassified and use the normal bounded command runner.
  *
  * @param command - The command as the executor sent it.
  * @returns True when a foreground statement of the command starts a server.
@@ -46,7 +50,9 @@ export interface ForegroundServer {
 }
 /**
  * A FOREGROUND command that starts a server, including one that only names a script whose SOURCE
- * imports the app's server and calls its `create()`/`listen()`.
+ * imports the app's server and calls its `create()`/`listen()`. Inline/stdin programs
+ * (`node -e …`, `python3 -c …`) use normal bounded execution: interpreting arbitrary
+ * program text is outside this filename/script preflight's contract.
  *
  * The script read is best-effort: a path the backend will not answer for is a command this reading
  * cannot classify, never a refusal. A backgrounded launch, a test runner and a test file are all

package/dist/server-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-command.d.ts","sourceRoot":"","sources":["../src/server-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,sBAAsB,EAAyB,MAAM,oBAAoB,CAAA;AAKvF;;;GAGG;AACH,eAAO,MAAM,YAAY,QAA6C,CAAA;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QACmP,CAAA;AAmF9Q;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI5D;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC5C,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmBlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC5C,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAiBxC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAO5F;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAG0B,CAAA"}
+{"version":3,"file":"server-command.d.ts","sourceRoot":"","sources":["../src/server-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,sBAAsB,EAAyB,MAAM,oBAAoB,CAAA;AAKvF;;;GAGG;AACH,eAAO,MAAM,YAAY,QAA6C,CAAA;AAEtE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,QACmP,CAAA;AA8G9Q;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI5D;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC5C,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmBlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC5C,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAiBxC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAO5F;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAG0B,CAAA"}

package/dist/server-command.js

@@ -28,7 +28,10 @@ export const BACKGROUNDED = /(?:^|[^&>])&(?!&|>)|\b(?:nohup|setsid)\b/;
  * A program that SERVES: the scaffold's entry (`server.ts`/`server.js`), a package manager's
  * `start`/`dev`/`serve`/`preview` script, a Vite dev or preview server, `next start|dev`, or a
  * Python WSGI server. Matched against a command segment's own text, and against a script's SOURCE
- * when the command only names the script file.
+ * when the command only names the script file — but NEVER against an inline program's code
+ * (`node -e …`, `python3 -c …`), where this text is the user's program rather than a file being
+ * run: `require('…/node_modules/vite')` imports a module, it does not start a dev server
+ * (xr-molecule-flash-m391 +13:13, refused as "node starts a server" for exactly that line).
  */
 export const SERVER_PROGRAM = /\bserver\.[cm]?[jt]s\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:start|dev|serve|preview)\b|\bvite\s+(?:preview|dev|serve)\b|\bvite(?![.\w-])(?!\s+(?:build|optimize)\b)|\bnext\s+(?:start|dev)\b|\b(?:uvicorn|gunicorn)\b|\bflask\s+run\b|\bpython\d?\s+-m\s+http\.server\b/;
 /** Programs that run a script FILE, so the file's own source decides whether it serves. */
@@ -66,6 +69,26 @@ const SERVE_SCRIPTS = /^(?:start|dev|serve|preview)$/;
 const TEST_RUNNERS = /^(?:hurl|jest|mocha|playwright|vitest)$/;
 /** A script's SOURCE that binds a listener even when it does not name a server file. */
 const STARTS_LISTENING = /\b(?:server|app)\.listen\s*\(/;
+/** Node inline-program flags; the shell parser already separated their arguments. */
+const NODE_INLINE_FLAG = /^(?:-[A-Za-z]*[ep]|--(?:eval|print)(?:=|$))/;
+/** Python inline programs use -c, including combined interpreter flags. */
+const PYTHON_INLINE_FLAG = /^-[A-Za-z]*c$/;
+/**
+ * Inline/stdin programs have no server filename to classify. Their source is arbitrary
+ * code; the normal bounded command runner, rather than another partial JS/Python
+ * parser, owns their execution. Named script and package-server checks remain below.
+ * @param segment - One parsed shell statement.
+ * @returns Whether the interpreter reads an inline/stdin program.
+ */
+function isInlineProgram(segment) {
+    const flag = /^python(?:3(?:\.\d+)?)?$/.test(segment.program)
+        ? PYTHON_INLINE_FLAG
+        : NODE_INLINE_FLAG;
+    return segment.args.some((word) => {
+        const arg = bare(word);
+        return arg === '-' || flag.test(arg);
+    });
+}
 /** A word with its shell quotes taken off (`'src/server.ts'` → `src/server.ts`). */
 function bare(word) {
     const match = /^(['"])(.*)\1$/s.exec(word);
@@ -75,6 +98,8 @@ function bare(word) {
  * Whether one parsed statement starts a server: a package manager's serving script, or a program
  * that IS a server, named in command position (so `cat server.ts` is a read, not a launch).
  *
+ * Inline/stdin programs use normal bounded execution: their code is not a server filename.
+ *
  * @param segment - One statement of the command.
  * @returns True when the statement starts a server that does not exit.
  */
@@ -87,7 +112,11 @@ function runsServerProgram(segment) {
         if (script !== undefined && SERVE_SCRIPTS.test(script))
             return true;
     }
-    return SERVER_PROGRAMS.has(segment.program) && SERVER_PROGRAM.test(segment.text);
+    if (!SERVER_PROGRAMS.has(segment.program))
+        return false;
+    if (isInlineProgram(segment))
+        return false;
+    return SERVER_PROGRAM.test(segment.text);
 }
 /**
  * The script file a runner statement executes, when it names one.
@@ -98,6 +127,9 @@ function runsServerProgram(segment) {
 function scriptPath(segment) {
     if (!SCRIPT_RUNNERS.has(segment.program))
         return null;
+    // An inline program (`node -e …`) is code, not a file to read.
+    if (isInlineProgram(segment))
+        return null;
     for (const arg of segment.args) {
         const word = bare(arg);
         if (word.startsWith('-'))
@@ -111,7 +143,8 @@ function scriptPath(segment) {
  * Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
  *
  * The over-budget reader's shape: at that point the command has already run, and only its text is
- * left to say whether "run a smaller unit" was ever the right advice.
+ * left to say whether "run a smaller unit" was ever the right advice. Inline/stdin programs
+ * remain unclassified and use the normal bounded command runner.
  *
  * @param command - The command as the executor sent it.
  * @returns True when a foreground statement of the command starts a server.
@@ -124,7 +157,9 @@ export function startsServerProgram(command) {
 }
 /**
  * A FOREGROUND command that starts a server, including one that only names a script whose SOURCE
- * imports the app's server and calls its `create()`/`listen()`.
+ * imports the app's server and calls its `create()`/`listen()`. Inline/stdin programs
+ * (`node -e …`, `python3 -c …`) use normal bounded execution: interpreting arbitrary
+ * program text is outside this filename/script preflight's contract.
  *
  * The script read is best-effort: a path the backend will not answer for is a command this reading
  * cannot classify, never a refusal. A backgrounded launch, a test runner and a test file are all

package/dist/tool-catalog.d.ts

@@ -0,0 +1,32 @@
+import type { AITool } from '@molecule/api-ai';
+/** Options for exposing a small tool set while retaining access to other allowed tools. */
+export interface DeferredToolCatalogOptions {
+    /** The caller's current permission/mode-filtered tools. Discovery never grants access. */
+    available: () => readonly AITool[];
+    /** Tools that should be offered without a discovery call. */
+    initialNames: ReadonlySet<string>;
+    /** Previously loaded names, in load order; useful across turns and compaction. */
+    loadedNames?: readonly string[];
+    /** Persist names after a successful load. No tool content is passed to this callback. */
+    onLoad?: (names: string[]) => void;
+}
+/** A provider-independent deferred catalog. The caller still executes and authorizes tools. */
+export interface DeferredToolCatalog {
+    loader: AITool;
+    /** Initial tools, loader, then requested tools in stable load order. */
+    select: () => AITool[];
+}
+/**
+ * Offer common tools and let the model load other schemas by exact name.
+ *
+ * This is ordinary allowlist selection, not semantic routing or authorization.
+ * Pass tools already filtered by the current mode and permissions. Loading never
+ * executes a tool; the caller must keep its normal execution-time guards. Loaded
+ * schemas append in request order and stay available, avoiding an LRU that changes
+ * the schema prefix on every request. Only names need persistence across turns.
+ *
+ * @param options - Allowed tools, initial selection and optional durable load state.
+ * @returns A loader tool and the current provider-facing selection.
+ */
+export declare function createDeferredToolCatalog(options: DeferredToolCatalogOptions): DeferredToolCatalog;
+//# sourceMappingURL=tool-catalog.d.ts.map

package/dist/tool-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-catalog.d.ts","sourceRoot":"","sources":["../src/tool-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAE9C,2FAA2F;AAC3F,MAAM,WAAW,0BAA0B;IACzC,0FAA0F;IAC1F,SAAS,EAAE,MAAM,SAAS,MAAM,EAAE,CAAA;IAClC,6DAA6D;IAC7D,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACjC,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,yFAAyF;IACzF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;CACnC;AAED,+FAA+F;AAC/F,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,MAAM,EAAE,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAsErB"}