@corenel/harness 0.2.0 → 0.4.0

package/dist/tools/files.js

@@ -15,26 +15,177 @@ function ensureWritable(path) {
         throw new Error(`${PROMPD_INSTALL_DIR}/ install dirs are read-only (managed by package install). Refusing to modify "${path}". Install or remove packages instead of editing them directly.`);
     }
 }
-function flatten(nodes, out = []) {
-    for (const n of nodes) {
-        out.push(`${n.kind === 'directory' ? '[dir] ' : ''}${n.path}${n.kind === 'file' && n.size != null ? ` (${n.size}b)` : ''}`);
-        if (n.children?.length)
-            flatten(n.children, out);
+function describe(n) {
+    return `${n.kind === 'directory' ? '[dir] ' : ''}${n.path}${n.kind === 'file' && n.size != null ? ` (${n.size}b)` : ''}`;
+}
+/** Every node in the ALREADY-MATERIALIZED tree, in BFS (level) order: every
+ * depth-0 node before ANY depth-1 node, every depth-1 before any depth-2, and
+ * so on. Used only to decide WHICH nodes survive the cap (see
+ * `selectByBreadthFirstCap` below) — never to render, because that reordering
+ * has its own cost (see the doc comment there). Also doubles as the total
+ * node count.
+ *
+ * IMPORTANT — what `maxDepth` does and does not save: `roots` here is the
+ * full result of `FileService.list()`, which has ALREADY recursed the whole
+ * subtree by the time this function ever sees it — `FileService.list(dir?:
+ * string)` (`packages/protocol/files.ts`) has no depth parameter, and none of
+ * its implementations (`packages/tools-node/fileService.ts`,
+ * `src/services/files/DirectoryHandleFileService.ts`,
+ * `src/services/files/SidecarFileService.ts`) stop early. So `maxDepth`
+ * bounds what is COLLECTED FROM that in-memory listing into `out` (and
+ * therefore what is returned to the model) — it does NOT reduce the
+ * `fs.readdir`/`fs.stat`/IPC cost of producing `roots` in the first place.
+ * That deeper fix belongs in the `FileService.list` port and its
+ * implementations, not here. Omit `maxDepth` for the unlimited,
+ * today's-behavior case. */
+function bfsNodes(roots, maxDepth = Infinity) {
+    const out = [];
+    let level = roots;
+    let depth = 1;
+    while (level.length) {
+        const next = [];
+        for (const n of level) {
+            out.push(n);
+            if (n.kind === 'directory' && n.children?.length && depth < maxDepth)
+                next.push(...n.children);
+        }
+        level = next;
+        depth++;
+    }
+    return out;
+}
+/** Cap on entries a single `list_files` call returns. A stranger typing `ls` in
+ * a large repo (no `dir`) got the WHOLE tree back — 4,369 entries in one real
+ * run, an 87K-token prompt on the very next model call. A few hundred entries
+ * is plenty to orient in a repo (see any file's immediate siblings, spot the
+ * top-level layout) without paying for the whole thing; 300 is that number —
+ * generous enough that an ordinary project's top few levels fit whole, small
+ * enough that a monorepo's `node_modules`-scale sprawl can't leak through
+ * uncapped. Every host (browser, node CLI, sidecar) shares this file, so the
+ * cap applies uniformly rather than per-host. */
+export const LIST_FILES_MAX_ENTRIES = 300;
+/** WHICH nodes survive: the first `LIST_FILES_MAX_ENTRIES` in BFS order —
+ * see `bfsNodes`'s comment for why breadth-first is what makes a global count
+ * cap keep the top of the tree instead of one arbitrary deep branch. Returns
+ * the surviving set plus the true total (for the marker). */
+function selectByBreadthFirstCap(roots, maxDepth) {
+    const bfs = bfsNodes(roots, maxDepth);
+    return { keep: new Set(bfs.slice(0, LIST_FILES_MAX_ENTRIES)), total: bfs.length };
+}
+/** Render the surviving nodes in ORIGINAL TREE ORDER (depth-first pre-order —
+ * the natural, readable shape: a directory immediately followed by its own
+ * contents), not the BFS order used to select them.
+ *
+ * BFS decides WHICH 300 entries survive; it must not also decide how they are
+ * DISPLAYED. In a small repo that was never truncated, every node survives
+ * (`keep` has everything), and rendering in BFS order would still separate
+ * every directory from its own contents — level by level instead of subtree
+ * by subtree — which is a strictly worse read for the overwhelmingly common
+ * case (no truncation at all) to fix a problem that only exists when
+ * truncation happens. So: select breadth-first, render depth-first, over the
+ * SAME `keep` set — a directory's children only appear here if the directory
+ * itself survived (BFS always keeps a parent before any of its children, so
+ * that's automatic, not a race), and only the children that themselves
+ * survived. */
+function describeInTreeOrder(roots, keep, maxDepth = Infinity, depth = 1, out = []) {
+    for (const n of roots) {
+        if (!keep.has(n))
+            continue;
+        out.push(describe(n));
+        if (n.kind === 'directory' && n.children?.length && depth < maxDepth) {
+            describeInTreeOrder(n.children, keep, maxDepth, depth + 1, out);
+        }
     }
     return out;
 }
+/** The unmistakable trailing marker — never let the model believe a
+ * truncated listing is the whole tree.
+ *
+ * `total` (and therefore `omitted`) is always the count of entries within the
+ * scope this call actually collected FROM — i.e. `bfsNodes`'s output length,
+ * which a depth limit already shrank before this is ever called (see
+ * `bfsNodes`'s doc comment — the underlying `FileService.list` still walked
+ * the full subtree; `maxDepth` only bounds what was collected from that
+ * result). So when `depth` is given, `total` here is the count within that
+ * depth, not the size of the whole tree, and the two truncation reasons — a
+ * depth limit excluding lower levels, vs. the entry cap additionally cutting
+ * within the collected scope — are DIFFERENT signals the model needs to tell
+ * apart to decide what to do next.
+ *
+ * Written as plain consecutive sentences, not a parenthetical nested inside
+ * the count — a model parses "340 total (not the whole tree (because...))"
+ * less reliably than separate sentences saying the same things in order. And
+ * when `depth` is in force, the right remedy is a LARGER `depth` (to see
+ * deeper), never "limit how many levels" (it's already limited) — telling the
+ * model to narrow further when it already narrowed is the wrong direction. */
+function truncationMarker(total, maxDepth) {
+    const omitted = total - LIST_FILES_MAX_ENTRIES;
+    const omittedEntries = `${omitted} more entr${omitted === 1 ? 'y' : 'ies'} omitted`;
+    if (maxDepth != null && Number.isFinite(maxDepth)) {
+        return `… truncated: ${omittedEntries}. ${total} entries were collected within depth ${maxDepth}; ` +
+            'deeper levels were not counted, so this is not the size of the whole tree. ' +
+            'Pass `dir` to narrow by subdirectory, or a larger `depth` to go deeper.';
+    }
+    return `… truncated: ${omittedEntries} (${total} total). ` +
+        'Pass `dir` to list a specific subdirectory (narrower breadth), or `depth` to limit how many levels deep the listing goes (narrower depth), instead of the whole tree.';
+}
+/** Normalizes model-supplied `depth` into a safe, meaningful bound, or
+ * `undefined` for "unlimited" (today's behavior — full recursive listing,
+ * still subject to the entry cap). Never throws: `depth` is model output and
+ * may be anything.
+ *
+ * Rules:
+ *  - missing / null / not coercible to a finite number -> `undefined`
+ *    (unlimited) — the safest fallback, since it reproduces the behavior
+ *    every existing caller already relies on.
+ *  - a numeric string ("2") is accepted the same as a number.
+ *  - non-finite (`NaN`, `Infinity`) -> `undefined` (unlimited).
+ *  - fractional values are floored (2.7 -> 2): depth is a count of whole
+ *    levels, there is no such thing as "2.7 levels deep".
+ *  - anything below 1 (0, negative) is clamped up to 1 — the shallowest
+ *    depth that still means something ("immediate children only"), rather
+ *    than being rejected or treated as unlimited.
+ *  - very large values (1e9) are accepted as-is; they behave as
+ *    "effectively unlimited" and are still bounded by `LIST_FILES_MAX_ENTRIES`
+ *    like the unlimited case, so there's no separate ceiling to enforce. */
+function normalizeDepth(args) {
+    const v = args['depth'];
+    if (v == null)
+        return undefined;
+    const n = typeof v === 'number' ? v : typeof v === 'string' ? Number(v) : NaN;
+    if (!Number.isFinite(n))
+        return undefined;
+    const floored = Math.floor(n);
+    return floored < 1 ? 1 : floored;
+}
 export const listFilesTool = {
     name: 'list_files',
     description: 'List files and directories in the workspace (the open folder or the virtual workspace). ' +
-        'Optionally pass `dir` to list a subdirectory. Returns paths relative to the workspace root.',
+        'Start shallow and drill in: pass `depth` to limit how many levels deep the listing goes ' +
+        '(vertical narrowing — `depth: 1` returns just the immediate children of the target, a quick ' +
+        'orientation call) and/or `dir` to list a specific subdirectory instead of the whole tree ' +
+        '(horizontal narrowing). Omit `depth` for a full recursive listing. Returns paths relative to ' +
+        'the workspace root.',
     parameters: {
         type: 'object',
-        properties: { dir: { type: 'string', description: 'Subdirectory to list (optional; omit for the root).' } },
+        properties: {
+            dir: { type: 'string', description: 'Subdirectory to list (optional; omit for the root).' },
+            depth: {
+                type: 'number',
+                description: 'How many levels deep to list (optional; omit for the full recursive tree). ' +
+                    '1 = immediate children of `dir` (or the root) only, 2 = two levels, and so on. ' +
+                    'Values below 1 (0, negative) are treated as 1, not rejected.',
+            },
+        },
     },
     async run(args, ctx) {
         const files = requireFiles(ctx);
         const nodes = await files.list(str(args, 'dir') || undefined);
-        const lines = flatten(nodes);
+        const maxDepth = normalizeDepth(args);
+        const { keep, total } = selectByBreadthFirstCap(nodes, maxDepth);
+        const lines = describeInTreeOrder(nodes, keep, maxDepth);
+        if (total > LIST_FILES_MAX_ENTRIES)
+            lines.push(truncationMarker(total, maxDepth));
         return lines.length ? lines.join('\n') : '(empty)';
     },
 };

package/dist/tools/files.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.js","sourceRoot":"","sources":["../../tools/files.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../tools/files.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAExE,SAAS,GAAG,CAAC,IAA6B,EAAE,GAAW;IACrD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,YAAY,CAAC,GAAgB;IACpC,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACnE,OAAO,GAAG,CAAC,KAAK,CAAC;AACnB,CAAC;AAED;sFACsF;AACtF,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,GAAG,kBAAkB,kFAAkF,IAAI,iEAAiE,CAAC,CAAC;IAChM,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,CAAW;IAC3B,OAAO,GAAG,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC3H,CAAC;AAED;;;;;;;;;;;;;;;;;;;4BAmB4B;AAC5B,SAAS,QAAQ,CAAC,KAAiB,EAAE,WAAmB,QAAQ;IAC9D,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,IAAI,KAAK,GAAe,KAAK,CAAC;IAC9B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,GAAe,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACZ,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,GAAG,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QACjG,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;QACb,KAAK,EAAE,CAAC;IACV,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;iDAQiD;AACjD,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;6DAG6D;AAC7D,SAAS,uBAAuB,CAAC,KAAiB,EAAE,QAAiB;IACnE,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;;;eAce;AACf,SAAS,mBAAmB,CAC1B,KAAiB,EACjB,IAAmB,EACnB,WAAmB,QAAQ,EAC3B,KAAK,GAAG,CAAC,EACT,MAAgB,EAAE;IAElB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC3B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;YACrE,mBAAmB,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;8EAmB8E;AAC9E,SAAS,gBAAgB,CAAC,KAAa,EAAE,QAAiB;IACxD,MAAM,OAAO,GAAG,KAAK,GAAG,sBAAsB,CAAC;IAC/C,MAAM,cAAc,GAAG,GAAG,OAAO,aAAa,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC;IACpF,IAAI,QAAQ,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClD,OAAO,gBAAgB,cAAc,KAAK,KAAK,wCAAwC,QAAQ,IAAI;YACjG,6EAA6E;YAC7E,yEAAyE,CAAC;IAC9E,CAAC;IACD,OAAO,gBAAgB,cAAc,KAAK,KAAK,WAAW;QACxD,uKAAuK,CAAC;AAC5K,CAAC;AAED;;;;;;;;;;;;;;;;;;4EAkB4E;AAC5E,SAAS,cAAc,CAAC,IAA6B;IACnD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9B,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACnC,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,0FAA0F;QAC1F,0FAA0F;QAC1F,8FAA8F;QAC9F,2FAA2F;QAC3F,+FAA+F;QAC/F,qBAAqB;IACvB,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qDAAqD,EAAE;YAC3F,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6EAA6E;oBAC7E,iFAAiF;oBACjF,8DAA8D;aACjE;SACF;KACF;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,CAAC;QAC9D,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,KAAK,GAAG,sBAAsB;YAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QAClF,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrD,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,uGAAuG;IACpH,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE,EAAE;QAC7F,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,qFAAqF;IAClG,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,EAAE;QACvE,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC;YAAE,OAAO,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC5E,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,wFAAwF;IACrG,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE,EAAE;QAC7E,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IACvD,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,IAAI;IACb,WAAW,EACT,6EAA6E;QAC7E,2FAA2F;IAC7F,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;YAC5D,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE;SACnE;QACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;KAC9B;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAC9C,OAAO,SAAS,IAAI,GAAG,CAAC;IAC1B,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,+FAA+F;IAC5G,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE;YACvD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6BAA6B,EAAE;SACxE;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QAC/C,OAAO,WAAW,IAAI,GAAG,CAAC;IAC5B,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,4DAA4D;IACzE,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,EAAE;QACxE,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,WAAW,IAAI,GAAG,CAAC;IAC5B,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,IAAI;IACb,WAAW,EAAE,4DAA4D;IACzE,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE;YACtD,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE;SACjD;QACD,QAAQ,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC;KACzB;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3B,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,cAAc,CAAC,EAAE,CAAC,CAAC;QACnB,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7B,OAAO,WAAW,IAAI,OAAO,EAAE,GAAG,CAAC;IACrC,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAgB;IACpC,aAAa;IACb,YAAY;IACZ,YAAY;IACZ,eAAe;IACf,aAAa;IACb,cAAc;IACd,cAAc;IACd,cAAc;CACf,CAAC"}

package/dist/tools/http.js

@@ -1,4 +1,4 @@
-import { outboundUrlError, safeFetch } from './urlGuard';
+import { outboundUrlError, safeFetch } from './urlGuard.js';
 function str(args, key) {
     const v = args[key];
     return typeof v === 'string' ? v : v == null ? '' : String(v);

package/dist/tools/namespaces.d.ts

@@ -1,4 +1,4 @@
-export type ToolNamespace = 'fs' | 'prompd' | 'web' | 'memory' | 'agent' | 'shell' | 'system' | 'mcp' | 'skill' | 'other';
+export type ToolNamespace = 'fs' | 'sidecar' | 'prompd' | 'web' | 'memory' | 'agent' | 'shell' | 'system' | 'mcp' | 'skill' | 'other';
 /** Display order + labels for the namespaces (capabilities panel grouping). */
 export declare const NAMESPACE_LABELS: {
     ns: ToolNamespace;

package/dist/tools/namespaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"namespaces.d.ts","sourceRoot":"","sources":["../../tools/namespaces.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,aAAa,GACrB,IAAI,GACJ,QAAQ,GACR,KAAK,GACL,QAAQ,GACR,OAAO,GACP,OAAO,GACP,QAAQ,GACR,KAAK,GACL,OAAO,GACP,OAAO,CAAC;AAEZ,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE;IAAE,EAAE,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAWlE,CAAC;AAcF,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAUpE;AAED;;;4CAG4C;AAC5C,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAQxD;AAED;6EAC6E;AAC7E,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,EAAE,CAE9D;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI1F;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"namespaces.d.ts","sourceRoot":"","sources":["../../tools/namespaces.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,aAAa,GACrB,IAAI,GASJ,SAAS,GACT,QAAQ,GACR,KAAK,GACL,QAAQ,GACR,OAAO,GACP,OAAO,GACP,QAAQ,GACR,KAAK,GACL,OAAO,GACP,OAAO,CAAC;AAEZ,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE;IAAE,EAAE,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAYlE,CAAC;AAiCF,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAUpE;AAED;;;4CAG4C;AAC5C,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAsBxD;AAED;6EAC6E;AAC7E,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,EAAE,CAE9D;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI1F;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAEvD"}

package/dist/tools/namespaces.js

@@ -10,10 +10,11 @@
  *
  * Policy globs may target a whole namespace (fs:*) or one tool (fs:write_file),
  * and legacy bare-name globs (write_file) still match for back-compat. */
-import { matchesAnyGlob } from '../guardrail/glob';
+import { matchesAnyGlob } from '../guardrail/glob.js';
 /** Display order + labels for the namespaces (capabilities panel grouping). */
 export const NAMESPACE_LABELS = [
     { ns: 'fs', label: 'Files' },
+    { ns: 'sidecar', label: 'This machine' },
     { ns: 'prompd', label: 'Prompd' },
     { ns: 'web', label: 'Web' },
     { ns: 'memory', label: 'Memory' },
@@ -33,7 +34,26 @@ const BUILTIN_NAMESPACES = {
     web_search: 'web',
     save_memory: 'memory', recall_memory: 'memory', recall_result: 'memory',
     kv_get: 'memory', kv_set: 'memory', search_sessions: 'memory',
-    ask_user: 'agent', spawn_agent: 'agent', spawn_agents: 'agent', todo_write: 'agent',
+    ask_user: 'agent', spawn_agent: 'agent', spawn_agents: 'agent', call_agent: 'agent', todo_write: 'agent',
+    // Named here as a backstop; the sidecar's own decls also carry `namespace`,
+    // and an explicit field always wins (resolveNamespace). Both say the same
+    // thing so a sidecar that predates this still lands in the right namespace.
+    sidecar_fs_read_file: 'sidecar', sidecar_fs_write_file: 'sidecar',
+    sidecar_fs_read_bytes: 'sidecar', sidecar_fs_list_dir: 'sidecar',
+    sidecar_fs_delete: 'sidecar', sidecar_shell_exec: 'sidecar',
+    // Host-side orchestration tools. They are not in allTools() - they reach the
+    // agent as remote decls (workerFactory) - but they are still governed by the
+    // policy, so they need a canonical address like everything else.
+    create_strategy: 'agent', edit_strategy: 'agent', view_strategy: 'agent', run_strategy: 'agent',
+    list_strategies: 'agent', list_saved_strategies: 'agent',
+    // Long-lived process control (proc_start/proc_stop/proc_list, see tools/procs.ts).
+    // `shell` is its own subject, deliberately distinct from the one-shot exec's
+    // `sidecar:shell_exec`: a process that stays running is a different risk from
+    // one that returns, and one address lets an operator ban (or allow) both
+    // start and stop together. proc_list is a read - it namespaces as `sidecar`
+    // (like the other machine-state reads) so it is NOT swept up by a `shell:*`
+    // deny; listing what is running carries none of spawn/kill's risk.
+    proc_start: 'shell', proc_stop: 'shell', proc_list: 'sidecar',
 };
 /** Resolve a tool's namespace: explicit field > built-in table > wire prefix > 'other'. */
 export function resolveNamespace(tool) {
@@ -62,6 +82,24 @@ export function toolAddress(tool) {
         if (m)
             leaf = leaf.slice(m[0].length);
     }
+    // `sidecar_fs_write_file` -> `sidecar:write_file`. The wire name carries the
+    // prefix because the MODEL sees a flat list and needs to tell the two apart;
+    // the address carries it in the namespace instead, so it is not said twice.
+    // `sidecar_fs_` before `sidecar_` — the longer prefix has to win.
+    if (ns === 'sidecar') {
+        for (const p of ['sidecar_fs_', 'sidecar_']) {
+            if (leaf.startsWith(p)) {
+                leaf = leaf.slice(p.length);
+                break;
+            }
+        }
+    }
+    // proc_start and proc_stop are two ends of the SAME governed capability
+    // (starting a long-lived process, and ending one) — they share the one
+    // address `shell:spawn` on purpose, so a policy rule can only ever gate both
+    // together, never start-without-stop or the reverse.
+    if (ns === 'shell' && (leaf === 'proc_start' || leaf === 'proc_stop'))
+        leaf = 'spawn';
     return `${ns}:${leaf}`;
 }
 /** Candidate strings a policy glob may target for this tool: its address and its

package/dist/tools/namespaces.js.map

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

package/dist/tools/procs.d.ts

@@ -0,0 +1,18 @@
+import type { AgentTool, SidecarProcs } from '@corenel/protocol';
+export interface ProcToolsOptions {
+    /** Identifies the run/session starting processes through these tools. Stamped
+     * onto every ProcInfo.label this factory produces (agentLabel()) so a dock
+     * listing can show provenance even after a reload. Optional — omitting it
+     * still marks the process as agent-started, just without a session name. */
+    session?: string;
+    /** Cap on concurrent agent-started RUNNING processes (see AGENT_TAG /
+     * isAgentStarted) — independent of, and smaller than, the daemon's own
+     * MAX_RUNNING. Default DEFAULT_AGENT_BUDGET. */
+    agentBudget?: number;
+}
+/** Build the proc_start / proc_stop / proc_list tools over a live SidecarProcs.
+ * `procs` is expected to be a real, already-constructed process table (node
+ * child_process-backed in production, a fake in tests) — this file never
+ * constructs one itself. */
+export declare function procTools(procs: SidecarProcs, opts?: ProcToolsOptions): AgentTool[];
+//# sourceMappingURL=procs.d.ts.map

package/dist/tools/procs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"procs.d.ts","sourceRoot":"","sources":["../../tools/procs.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAoC,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA0JnG,MAAM,WAAW,gBAAgB;IAC/B;;;gFAG4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;oDAEgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;4BAG4B;AAC5B,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,GAAE,gBAAqB,GAAG,SAAS,EAAE,CA2JvF"}

package/dist/tools/procs.js

@@ -0,0 +1,281 @@
+const DEFAULT_SETTLE_MS = 10000;
+const MIN_SETTLE_MS = 100;
+const MAX_SETTLE_MS = 120000;
+/** How many processes THIS factory will let the agent have running at once,
+ * counted within the daemon's own MAX_RUNNING=8. Deliberately smaller than the
+ * daemon's cap: the operator may want to run their own dev server, build watch,
+ * and log tail alongside whatever the agent starts, and an agent that can eat
+ * every slot locks them out of their own dock. This protects the OPERATOR, not
+ * the agent — it is not a courtesy limit the agent could reasonably ask to
+ * raise. */
+const DEFAULT_AGENT_BUDGET = 3;
+/** Every process this file starts is labelled with this marker (plus the
+ * session, when known) so a listing can tell "the agent started this" from "a
+ * human started this" from ProcInfo.label alone — durable across reloads and
+ * reconnects, because the label lives on the daemon-owned ProcInfo, not in this
+ * factory's own memory. */
+const AGENT_TAG = 'agent';
+function agentLabel(session, userLabel) {
+    const tag = session ? `${AGENT_TAG}:${session}` : AGENT_TAG;
+    return userLabel ? `${userLabel} [${tag}]` : `[${tag}]`;
+}
+/** True if a ProcInfo's label carries this file's agent marker — used to count
+ * agent-started processes from the daemon's OWN table (procs.list()), not from
+ * a Set this factory keeps in memory, so the budget holds even across a reload
+ * that drops this factory and rebuilds it. */
+function isAgentStarted(info) {
+    return /\[agent(:[^\]]*)?\]/.test(info.label ?? '');
+}
+function str(args, key) {
+    const v = args[key];
+    return typeof v === 'string' && v.length ? v : undefined;
+}
+function clamp(n, min, max) {
+    if (!Number.isFinite(n))
+        return min;
+    return Math.min(Math.max(n, min), max);
+}
+/** Beyond this many characters, `renderTail`'s output is truncated -- same
+ * budget and reasoning as shellTool's MAX_OUTPUT (packages/cli/src/shellTool.ts):
+ * the retention ring this reads from is bounded at up to 200_000 chars
+ * (packages/sidecar/src/procs.ts / packages/cli/src/sidecarProcs.ts), which is
+ * still large enough for one `proc_start` result to blow the model's context
+ * window on its own. `corenel run`'s tool context wires no `recall`, so
+ * offload cannot rescue this the way it can a `tool-result` that goes through
+ * compression -- the cap has to be applied here. */
+const RENDER_TAIL_MAX = 30000;
+/** Render the buffered tail for a process. `truncated` must show up as WORDS —
+ * a tail that looks complete when it is not is the failure that matters, so
+ * this is never left to a caller to notice on its own. Keeps the LAST
+ * RENDER_TAIL_MAX characters (not the first): for a process still starting up,
+ * the most recent output is the one that says whether it's ready. */
+function renderTail(procs, procId) {
+    const { chunks, truncated } = procs.backlog(procId, 0);
+    const body = chunks.map((c) => (c.stream === 'err' ? `[stderr] ${c.text}` : c.text)).join('');
+    const capped = body.length > RENDER_TAIL_MAX;
+    const shown = capped ? body.slice(body.length - RENDER_TAIL_MAX) : body;
+    const notes = [];
+    if (truncated)
+        notes.push('[some earlier output was dropped from the buffer and is not shown here]');
+    if (capped) {
+        notes.push(`[showing only the last ${RENDER_TAIL_MAX} of ${body.length} characters -- earlier output in ` +
+            'this result was cut to avoid blowing the context window]');
+    }
+    const note = notes.length ? `\n${notes.join('\n')}` : '';
+    return (shown ? `Output so far:\n${shown}` : 'No output yet.') + note;
+}
+function describeInfo(info) {
+    return `${info.procId} (pid ${info.pid ?? 'unknown'}): ${info.command}${info.label ? ` [${info.label}]` : ''}`;
+}
+/** Race the three ways `proc_start` can resolve. Whichever happens first wins;
+ * the other two paths are torn down (unsubscribed / timer cleared) so only one
+ * result is ever produced. */
+function watchStart(procs, procId, waitFor, settleMs, onChunk) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let lastSeenSeq = 0;
+        let buffer = '';
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            unsub();
+            resolve(outcome);
+        };
+        const handleChunk = (c) => {
+            if (c.seq <= lastSeenSeq)
+                return; // already seen (backlog catch-up vs. live)
+            lastSeenSeq = c.seq;
+            // Check settled BEFORE streaming: once this call has resolved, nothing
+            // reads ctx.stream for it anymore, so a chunk delivered afterwards
+            // (synchronous backlog catch-up can call finish() partway through, per
+            // the caller's own comment above) must not be pushed at all, not pushed
+            // and then ignored for wait_for matching.
+            if (settled)
+                return;
+            onChunk(c);
+            if (!waitFor)
+                return;
+            buffer += c.text;
+            if (buffer.includes(waitFor)) {
+                const info = procs.get(procId);
+                if (info)
+                    finish({ kind: 'matched', info });
+            }
+        };
+        // `timer` and `unsub` must both be assigned BEFORE anything that can call
+        // `finish` synchronously (the backlog catch-up below can: a command that
+        // fails instantly, or prints its wait_for text, before this promise's
+        // caller ever gets control back) — finish() reads both.
+        const timer = setTimeout(() => {
+            const info = procs.get(procId);
+            if (info)
+                finish({ kind: 'settled', info });
+        }, settleMs);
+        const unsub = procs.subscribe((ev) => {
+            if (ev.procId !== procId)
+                return;
+            if (ev.kind === 'out')
+                handleChunk(ev.chunk);
+            else
+                finish({ kind: 'exited', info: ev.info });
+        });
+        // Catch up on anything already buffered/settled BEFORE we subscribed — the
+        // daemon's spawn() has an await in it (root confinement), so output (or
+        // even exit, for a command that fails instantly) can land before this
+        // function's caller ever gets control back.
+        for (const c of procs.backlog(procId, 0).chunks)
+            handleChunk(c);
+        if (!settled) {
+            const cur = procs.get(procId);
+            if (cur && !cur.running)
+                finish({ kind: 'exited', info: cur });
+        }
+    });
+}
+/** Build the proc_start / proc_stop / proc_list tools over a live SidecarProcs.
+ * `procs` is expected to be a real, already-constructed process table (node
+ * child_process-backed in production, a fake in tests) — this file never
+ * constructs one itself. */
+export function procTools(procs, opts = {}) {
+    const budget = opts.agentBudget ?? DEFAULT_AGENT_BUDGET;
+    const agentRunningCount = () => procs.list().filter((p) => p.running && isAgentStarted(p)).length;
+    const procStart = {
+        name: 'proc_start',
+        means: 'start a long-running command (a dev server, a watcher, a build) and watch its output',
+        description: 'Start a long-lived command (e.g. "npm run start") and watch it come up. Unlike a one-shot ' +
+            'shell exec, this does not wait for the command to finish — it resolves once EITHER wait_for ' +
+            'matches a substring of the output, OR settle_ms elapses with the process still running, OR the ' +
+            'process exits early. The result text always says explicitly which of those happened and whether ' +
+            'the process is still running. The process keeps running (and its output keeps being pushed live) ' +
+            'after this call resolves; use proc_list to see it again and proc_stop to end it.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'the shell command line to run' },
+                cwd: { type: 'string', description: 'working directory relative to the chosen root (default ".")' },
+                root: { type: 'string', description: 'which pre-approved root to resolve cwd against' },
+                label: { type: 'string', description: 'a short human-readable label for this process' },
+                wait_for: {
+                    type: 'string',
+                    description: 'a plain SUBSTRING (never a regex) to watch for in the combined output, e.g. "Local: http://". ' +
+                        'When it appears, the call resolves immediately instead of waiting out settle_ms.',
+                },
+                settle_ms: {
+                    type: 'number',
+                    description: `how long to wait, in ms, before resolving anyway if wait_for never matches and the process hasn't exited (default ${DEFAULT_SETTLE_MS}, max ${MAX_SETTLE_MS})`,
+                },
+            },
+            required: ['command'],
+        },
+        namespace: 'shell',
+        mutates: true,
+        permission: 'ask',
+        async run(args, ctx) {
+            const command = str(args, 'command')?.trim();
+            if (!command)
+                return 'Error: no command given';
+            const waitFor = str(args, 'wait_for');
+            const settleMs = clamp(Number(args.settle_ms) || DEFAULT_SETTLE_MS, MIN_SETTLE_MS, MAX_SETTLE_MS);
+            const running = agentRunningCount();
+            if (running >= budget) {
+                return (`Error: refusing to start another process — this agent already has ${running} of its ` +
+                    `${budget} allowed concurrent processes running. Stop one with proc_stop first, or ask the ` +
+                    'operator to start it themselves.');
+            }
+            const cwd = str(args, 'cwd');
+            const root = str(args, 'root');
+            let info;
+            try {
+                info = await procs.spawn({
+                    command,
+                    ...(cwd ? { cwd } : {}),
+                    ...(root ? { root } : {}),
+                    label: agentLabel(opts.session, str(args, 'label')),
+                });
+            }
+            catch (e) {
+                return `Error: could not start the process: ${e instanceof Error ? e.message : String(e)}`;
+            }
+            const outcome = await watchStart(procs, info.procId, waitFor, settleMs, (c) => ctx.stream?.(c.text));
+            const tail = renderTail(procs, info.procId);
+            if (outcome.kind === 'matched') {
+                return (`Started ${describeInfo(outcome.info)}\n` +
+                    `STILL RUNNING — matched wait_for ${JSON.stringify(waitFor)} in its output.\n\n${tail}`);
+            }
+            if (outcome.kind === 'settled') {
+                const waitNote = waitFor ? ` (wait_for ${JSON.stringify(waitFor)} has NOT appeared yet)` : '';
+                return (`Started ${describeInfo(outcome.info)}\n` +
+                    `STILL RUNNING after ${settleMs}ms with no exit${waitNote}.\n\n${tail}`);
+            }
+            // outcome.kind === 'exited'
+            const { info: endInfo } = outcome;
+            const status = `exit code ${endInfo.exitCode ?? 'unknown'}${endInfo.signal ? ` (signal ${endInfo.signal})` : ''}`;
+            return (`Started ${describeInfo(endInfo)}\n` +
+                `ALREADY EXITED before it finished starting — it is NOT running. ${status}.\n\n${tail}`);
+        },
+    };
+    const procStop = {
+        name: 'proc_stop',
+        means: 'stop a process this agent (or the operator) started',
+        description: 'Stop a running process by its proc_id (from proc_start or proc_list). Idempotent — stopping an ' +
+            'already-stopped or unknown process is reported, not treated as an error.',
+        parameters: {
+            type: 'object',
+            properties: { proc_id: { type: 'string', description: 'the procId to stop' } },
+            required: ['proc_id'],
+        },
+        namespace: 'shell',
+        mutates: true,
+        permission: 'ask',
+        async run(args) {
+            const procId = str(args, 'proc_id');
+            if (!procId)
+                return 'Error: no proc_id given';
+            const before = procs.get(procId);
+            if (!before)
+                return `${procId}: no such process (it may already have been evicted after exiting).`;
+            if (!before.running) {
+                const status = `exit code ${before.exitCode ?? 'unknown'}${before.signal ? ` (signal ${before.signal})` : ''}`;
+                return `${describeInfo(before)} was already stopped (${status}).`;
+            }
+            try {
+                procs.kill(procId);
+            }
+            catch (e) {
+                return `Error: could not stop ${procId}: ${e instanceof Error ? e.message : String(e)}`;
+            }
+            return `Stopping ${describeInfo(before)} (SIGTERM sent; it will be force-killed if it doesn't exit).`;
+        },
+    };
+    const procList = {
+        name: 'proc_list',
+        means: 'see every process running or recently run on this machine',
+        description: 'List the processes visible through this connection, running or recently exited — including ones ' +
+            'started before this conversation, or in an earlier turn whose proc_id has since fallen out of ' +
+            'context. A process started elsewhere (by the operator, or another client) AFTER this connection ' +
+            'was established may not appear here until it reconnects — if an expected process (e.g. a dev ' +
+            'server you did not start) is missing, that does not mean it is not running; ask before starting ' +
+            'a second one on the same port. Each entry says whether it was started by an agent or by the ' +
+            'operator directly.',
+        parameters: { type: 'object', properties: {} },
+        namespace: 'sidecar',
+        async run() {
+            const all = procs.list();
+            if (!all.length)
+                return 'No processes.';
+            return all
+                .map((p) => {
+                const who = isAgentStarted(p) ? 'agent-started' : 'operator-started';
+                const state = p.running
+                    ? 'running'
+                    : `exited (code ${p.exitCode ?? 'unknown'}${p.signal ? `, signal ${p.signal}` : ''})`;
+                return `${describeInfo(p)} — ${who}, ${state}`;
+            })
+                .join('\n');
+        },
+    };
+    return [procStart, procStop, procList];
+}
+//# sourceMappingURL=procs.js.map