@sapiom/harness 0.8.8 → 0.9.0

package/dist/core/agent-project-discovery.js

@@ -8,7 +8,142 @@ import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import { AGENT_PROJECT_MARKER } from "../shared/types.js";
-export const AGENT_PROJECT_SCAN_MAX_DEPTH = 3;
+/**
+ * How deep a scan looks for agent projects beneath a chosen root.
+ *
+ * This was 3, which predated the project-rooted rail: it assumed the root the
+ * user opened was more or less the agent's own folder. Under a chosen project
+ * root, depth is normal — `<root>/backend/src/agents/<agent>` is four segments
+ * down and `<root>/apps/<app>/src/features/<x>/agents/<agent>` is six. At 3
+ * those agents are not found at all and file under "No workspace"; on a
+ * measured root that was well over a third of the rail.
+ *
+ * 8 leaves headroom above the deepest realistic layout without becoming a walk
+ * of the user's home directory. It is NOT what keeps the scan cheap — see
+ * AGENT_PROJECT_SCAN_MAX_NODES. What depth still buys is (a) a pathological
+ * deep chain terminating in 8 steps rather than by exhausting a node budget,
+ * and (b) a *deterministic* outer envelope, which reconciliation needs: the
+ * registry may only forget a project it can prove it would have looked for.
+ */
+export const AGENT_PROJECT_SCAN_MAX_DEPTH = 8;
+/**
+ * The bound that actually governs scan cost: how many directories one walk may
+ * enter. Depth alone cannot do this job, and the numbers are why.
+ *
+ * Measured on this machine (macOS/APFS) against real roots on a real install,
+ * per directory entered = one marker `lstat` + one `readdir`, warm cache
+ * ~22-25 us/dir at every depth:
+ *
+ *   root                    depth 3         depth 8            unbounded
+ *   a single repo             119 dirs         242 dirs   7 ms    242 dirs
+ *   ~/sapiom/sapiom-js        758 dirs       9,016 dirs 196 ms  9,195 dirs
+ *   ~/sapiom/Sapiom         1,298 dirs      35,489 dirs 847 ms 47,544 dirs
+ *
+ * So raising the depth cap alone makes a 32 ms scan an 847 ms one on a root a
+ * user would plausibly open, and the watcher below pays that synchronously on
+ * a debounce. Cost is linear and predictable in directories entered, so that
+ * is what we bound.
+ *
+ * Pruning harder by NAME was the other candidate and does not pay: extending
+ * the ignored-directory list with the usual suspects (`.venv`, `target`,
+ * `vendor`, `coverage`, `.turbo`, `__pycache__`, `out`, ...) removed 0.5-11% of
+ * the dirs on the roots above. What is actually there is source directories
+ * and, on the biggest root, 42,163 of 47,544 dirs in git worktree copies of the
+ * repo itself.
+ *
+ * That second half IS now reachable, and not by name: see
+ * {@link isForeignRepositoryRoot}. A walk that stops at a foreign checkout does
+ * not enter those 42,163 directories at all, which is why the node budget is no
+ * longer what ends a scan of a real root — the repository is. The budget stays
+ * as the backstop for a tree that is genuinely one enormous checkout.
+ *
+ * **The tradeoff, stated plainly:** past the budget a scan is incomplete, and
+ * an agent below the cut is not discovered on that pass. The walk is therefore
+ * breadth-first, so the budget degrades by *depth* — every level below the cut
+ * is complete, which is exactly the guarantee the old fixed cap gave, just at a
+ * depth chosen by the tree's real width instead of guessed in advance. Callers
+ * learn how far they may trust the result from
+ * {@link AgentProjectScanBudget.envelopeDepth}; nothing beyond it is reconciled
+ * away as missing.
+ *
+ * 10,000 dirs ~= 240 ms warm for the async registry scan, which runs when a
+ * session is created or the user asks — and covers a real monorepo project root
+ * outright (sapiom-js: 9,016).
+ */
+export const AGENT_PROJECT_SCAN_MAX_NODES = 10000;
+/**
+ * The watcher fingerprint's budget, deliberately tighter than the scan's.
+ *
+ * `snapshotWorkspaceWorkflows` is synchronous and re-runs on a 250 ms debounce
+ * after any file change under the session's cwd, so its cost lands on the event
+ * loop while the user is typing. 2,500 dirs ~= 60 ms warm, which is the same
+ * order as what depth-3 cost on the widest real root measured (1,298 dirs /
+ * 32 ms): the watcher gets the full depth on an ordinary project and gets no
+ * slower on a huge one. A truncated fingerprint means a *deep* structural
+ * change may not arm a rescan until some shallower event does; discovery depth
+ * itself is the registry scan's budget, not this one.
+ */
+export const AGENT_PROJECT_WATCH_MAX_NODES = 2500;
+/**
+ * The entry name that marks a directory as its own repository checkout: a
+ * `.git` DIRECTORY in an ordinary clone, a `.git` FILE in a git worktree or a
+ * submodule. Both forms are one entry called `.git`, which is all this policy
+ * needs to know.
+ */
+export const REPOSITORY_MARKER = ".git";
+/**
+ * Whether a directory we just listed is the root of a repository other than
+ * the one the scan started in — the boundary a walk does not cross.
+ *
+ * **Why breadth, not depth, was the real bound.** The scan that produced this
+ * install's 88-row registry was rooted one level too high, at `~/sapiom`. From
+ * there the walk crossed into twelve sibling checkouts nobody had opened, and
+ * kept going until the node budget cut it off:
+ *
+ * Measured on that install (macOS/APFS, warm cache) at the shipped 10,000-node
+ * budget. Each cell is agents registered / distinct names among them /
+ * directories entered / wall clock:
+ *
+ *   root                      today                          with the boundary
+ *   ~/sapiom/wf-demo-testing   10 / 10,     17 dirs,   0 ms   10 / 10,    17 dirs,   0 ms
+ *   ~/sapiom                   88 / 65, 10,000 dirs, 239 ms   68 / 64,   408 dirs,   8 ms
+ *                              TRUNCATED at depth 5           complete
+ *   ~/sapiom/sapiom-js         25 /  2,  9,016 dirs, 233 ms    2 /  2,   444 dirs,   8 ms
+ *   ~/sapiom/Sapiom             0 /  0, 10,000 dirs, 200 ms    0 /  0, 5,408 dirs, 107 ms
+ *                              TRUNCATED at depth 5           complete
+ *
+ * The `sapiom-js` row is the whole argument in one line. Of the 25 agents a
+ * scan of that repo used to register, 24 were the SAME agent — one e2e fixture
+ * — reachable once per git worktree under `.trees/`. Two were real. Read the
+ * name counts down the column: the rule barely changes how many *distinct*
+ * agents a scan finds, and collapses how many *rows* it writes.
+ *
+ * Letting the node budget off its leash widens the gap rather than closing it:
+ * uncapped, `~/sapiom` is 141 agents across 83,969 directories in 6.8 s — and
+ * still only 73 distinct names. Depth was never what was wrong.
+ *
+ * **The cost, stated plainly.** Across that pair, 5 distinct agents are lost at
+ * `~/sapiom` (73 names uncapped vs 68 bounded), and `~/sapiom/Sapiom` loses the
+ * single agent it has. Every one of them lives inside a checkout below the scan
+ * root, and every one is registered the moment that checkout is itself the root
+ * — opened as a project, hosting a session, or named to
+ * `POST /api/workflows/scan`. That is the trade the user asked for in as many
+ * words: "It's okay if we don't fully scan."
+ *
+ * It also costs nothing to evaluate: the walk has already listed the directory
+ * to find its subdirectories, so the check reads a `Dirent[]` already in hand —
+ * no extra syscall.
+ *
+ * **What it deliberately does NOT do.** A nested checkout that IS an agent (its
+ * own `sapiom.json` at the top) is still registered: the marker is inspected
+ * before the boundary is considered, and a marker stops the walk anyway. Only
+ * a checkout that merely *contains* agents is left alone. So `~/agents/foo`
+ * (one repo per agent) is found; `~/src/some-other-monorepo/**` is not, unless
+ * the user points a scan at that monorepo.
+ */
+export function isForeignRepositoryRoot(entries) {
+    return entries.some((entry) => entry.name === REPOSITORY_MARKER);
+}
 const IGNORED_DIR_NAMES = new Set([
     "node_modules",
     ".git",
@@ -107,4 +242,171 @@ export async function inspectAgentProjectMarker(dir) {
         return { status: markerReadErrorStatus(error) };
     }
 }
+/**
+ * One walk's traversal allowance, and its report on what it managed to cover.
+ *
+ * A budget is single-use: it accumulates `visited` as the walk runs, so pass a
+ * fresh one per walk (the walkers below default to one). Callers that care
+ * about cost or completeness construct it themselves and read it afterwards —
+ * that is also how the perf benchmark measures nodes visited without the
+ * scanner growing a second, parallel counting path.
+ */
+export class AgentProjectScanBudget {
+    constructor(limits = {}) {
+        /** Directories entered (marker inspected), root included. */
+        this.visited = 0;
+        /** The depth at which `maxNodes` stopped the walk, or null if it never did. */
+        this.truncatedAtDepth = null;
+        /**
+         * Foreign repository roots the walk stopped at rather than entering.
+         *
+         * Rides on the budget for the same reason `visited` does: a caller holding the
+         * budget can read what the walk actually did without every intermediate
+         * signature having to forward it. Load-bearing for the UI — a scan of a
+         * non-repo folder full of clones finds nothing, and only this list can tell
+         * "there is nothing here" apart from "I did not look in there".
+         */
+        this.repositoryBoundaries = [];
+        this.maxDepth = limits.maxDepth ?? AGENT_PROJECT_SCAN_MAX_DEPTH;
+        this.maxNodes = limits.maxNodes ?? AGENT_PROJECT_SCAN_MAX_NODES;
+    }
+    get truncated() {
+        return this.truncatedAtDepth !== null;
+    }
+    /**
+     * The deepest level this walk enumerated *in full* — how deep its results may
+     * be trusted as complete, and therefore how deep a caller may reconcile a
+     * previously-known project away as gone. `maxDepth` for a walk that finished;
+     * one level above the cut for a walk the node budget stopped, because that
+     * level is the only incomplete one (the walk is breadth-first).
+     */
+    get envelopeDepth() {
+        return this.truncatedAtDepth === null
+            ? this.maxDepth
+            : this.truncatedAtDepth - 1;
+    }
+    /** Charges one directory. False (and records the cut) once spent. */
+    admit(depth) {
+        if (this.visited >= this.maxNodes) {
+            if (this.truncatedAtDepth === null)
+                this.truncatedAtDepth = depth;
+            return false;
+        }
+        this.visited += 1;
+        return true;
+    }
+}
+/**
+ * Subdirectories worth descending into, in a stable order.
+ *
+ * Two properties matter beyond the ignore filter:
+ *
+ *   - `entry.isDirectory()` reads the raw dirent type, so a symlink — even one
+ *     pointing at a directory — reports false and is never descended into.
+ *     That, not the depth cap, is what makes a symlink *cycle* terminate; the
+ *     cap only ever hid the fact. It is asserted directly in the tests.
+ *   - Sorted, so a walk the node budget truncates truncates at the same place
+ *     twice. `readdir` order is filesystem-dependent, and the watcher compares
+ *     one fingerprint against the next: an order-dependent cut would read as a
+ *     structural change on every check and rescan the workspace forever.
+ */
+function scanSubdirNames(entries) {
+    return entries
+        .filter((entry) => entry.isDirectory() && !isAgentProjectScanIgnoredDir(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+}
+function isConfirmedMissingDir(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * The boundary decision, shared by the sync and async walks so they cannot
+ * disagree about which directories a scan of a given root covers.
+ *
+ * Depth 0 is exempt: the root is the tree the user asked for, and a scan of a
+ * repository must of course cover that repository. Everything below it is only
+ * entered while it belongs to the same checkout.
+ */
+function stopsAtRepositoryBoundary(visitor, entries, dir, depth, options) {
+    if (options.crossRepositoryBoundaries)
+        return false;
+    if (depth === 0 || !isForeignRepositoryRoot(entries))
+        return false;
+    visitor.onRepositoryBoundary?.(dir, depth);
+    return true;
+}
+/**
+ * Breadth-first, depth- and node-bounded traversal beneath `root` — the one
+ * traversal policy the registry and the workspace watcher both run, so they
+ * cannot disagree about which directories a scan of a given root covers.
+ *
+ * Breadth-first is load-bearing rather than incidental: it is what makes the
+ * node budget degrade by depth (see AGENT_PROJECT_SCAN_MAX_NODES). Every level
+ * shallower than `budget.envelopeDepth` is complete no matter where the budget
+ * ran out, which keeps the generalized bound a superset of the fixed depth cap
+ * it replaces.
+ *
+ * Returns the budget so a caller can read `visited` / `envelopeDepth` off it.
+ */
+export function walkAgentProjectTree(root, visitor, budget = new AgentProjectScanBudget(), options = {}) {
+    let frontier = [path.resolve(root)];
+    for (let depth = 0; depth <= budget.maxDepth && frontier.length > 0; depth += 1) {
+        const next = [];
+        for (const dir of frontier) {
+            if (!budget.admit(depth))
+                return budget;
+            if (visitor.onDirectory(dir, depth) === "stop")
+                continue;
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (!isConfirmedMissingDir(error))
+                    visitor.onUnreadable?.(dir, depth);
+                continue;
+            }
+            if (stopsAtRepositoryBoundary(visitor, entries, dir, depth, options))
+                continue;
+            for (const name of scanSubdirNames(entries))
+                next.push(path.join(dir, name));
+        }
+        frontier = next;
+    }
+    return budget;
+}
+/**
+ * Async twin of {@link walkAgentProjectTree}, for callers that must not block
+ * the event loop on a wide tree. Same order, same bounds, same decisions — so
+ * the two produce identical results on the same tree with the same budget,
+ * which the watcher's sync/async fingerprint pair depends on.
+ */
+export async function walkAgentProjectTreeAsync(root, visitor, budget = new AgentProjectScanBudget(), options = {}) {
+    let frontier = [path.resolve(root)];
+    for (let depth = 0; depth <= budget.maxDepth && frontier.length > 0; depth += 1) {
+        const next = [];
+        for (const dir of frontier) {
+            if (!budget.admit(depth))
+                return budget;
+            if ((await visitor.onDirectory(dir, depth)) === "stop")
+                continue;
+            let entries;
+            try {
+                entries = await fsp.readdir(dir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (!isConfirmedMissingDir(error))
+                    visitor.onUnreadable?.(dir, depth);
+                continue;
+            }
+            if (stopsAtRepositoryBoundary(visitor, entries, dir, depth, options))
+                continue;
+            for (const name of scanSubdirNames(entries))
+                next.push(path.join(dir, name));
+        }
+        frontier = next;
+    }
+    return budget;
+}
 //# sourceMappingURL=agent-project-discovery.js.map

package/dist/core/agent-project-discovery.js.map

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

package/dist/core/canvas-interconnections.d.ts

@@ -1,3 +1,5 @@
+import type { AgentInvocationMode } from "../shared/system-graph.js";
+export type { AgentInvocationMode } from "../shared/system-graph.js";
 /**
  * Lists the workflow's own `.ts`/`.tsx` sources (skipping node_modules and
  * friends), bounded to MAX_FILES_PER_WORKFLOW. Shared with the extraction
@@ -13,6 +15,30 @@ export interface DetectedLaunch {
      *  (e.g. a launch in a shared helper). */
     fromStepId: string | null;
 }
+/** Internal source evidence. It never crosses the system-graph HTTP boundary. */
+export interface SourceEvidence {
+    /** POSIX path relative to the caller's source root. */
+    file: string;
+    /** One-based source location of the supported call expression. */
+    line: number;
+    column: number;
+}
+export interface DetectedAgentInvocation {
+    /** The direct literal `definition` target. */
+    slug: string;
+    mode: AgentInvocationMode;
+    fromStepId: string | null;
+    evidence: SourceEvidence;
+}
+export interface AgentInvocationDetectionWarning {
+    code: "dynamic-target";
+    mode: AgentInvocationMode;
+    evidence: SourceEvidence;
+}
+export interface AgentInvocationScanResult {
+    invocations: DetectedAgentInvocation[];
+    warnings: AgentInvocationDetectionWarning[];
+}
 export interface DetectedCapability {
     /** The dotted capability id (e.g. "web.search", "email.messages.send"). */
     capability: string;
@@ -21,6 +47,8 @@ export interface DetectedCapability {
 }
 export interface WorkflowSourceScan {
     launches: DetectedLaunch[];
+    invocations: DetectedAgentInvocation[];
+    invocationWarnings: AgentInvocationDetectionWarning[];
     capabilities: DetectedCapability[];
 }
 /**
@@ -35,6 +63,9 @@ export interface WorkflowSourceScan {
  * so the shared pass halves the I/O on the hot path.
  */
 export declare function scanWorkflowSources(root: string, knownStepIds: ReadonlySet<string>): Promise<WorkflowSourceScan>;
+/** Direct agent invocations plus deterministic warnings for supported calls
+ * whose target is not a direct literal. */
+export declare function detectAgentInvocations(root: string, knownStepIds: ReadonlySet<string>): Promise<AgentInvocationScanResult>;
 /** Just the launches from {@link scanWorkflowSources}. */
 export declare function detectWorkflowLaunches(root: string, knownStepIds: ReadonlySet<string>): Promise<DetectedLaunch[]>;
 /** Just the capabilities from {@link scanWorkflowSources}. */

package/dist/core/canvas-interconnections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-interconnections.d.ts","sourceRoot":"","sources":["../../src/core/canvas-interconnections.ts"],"names":[],"mappings":"AAwDA;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBrE;AAsFD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb;;8CAE0C;IAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;AAED,0DAA0D;AAC1D,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,cAAc,EAAE,CAAC,CAE3B;AAED,8DAA8D;AAC9D,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAE/B"}
+{"version":3,"file":"canvas-interconnections.d.ts","sourceRoot":"","sources":["../../src/core/canvas-interconnections.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AA4CrE;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBrE;AA8FD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb;;8CAE0C;IAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,uBAAuB,EAAE,CAAC;IACvC,QAAQ,EAAE,+BAA+B,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,WAAW,EAAE,uBAAuB,EAAE,CAAC;IACvC,kBAAkB,EAAE,+BAA+B,EAAE,CAAC;IACtD,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAsUD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,kBAAkB,CAAC,CA6C7B;AAED;2CAC2C;AAC3C,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,yBAAyB,CAAC,CAMpC;AAED,0DAA0D;AAC1D,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,cAAc,EAAE,CAAC,CAE3B;AAED,8DAA8D;AAC9D,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAE/B"}