@sapiom/harness 0.1.4 → 0.1.5

package/dist/core/definition-slug-resolver.js

@@ -0,0 +1,81 @@
+/**
+ * Serve-time enrichment: resolves a deployed agent's `definitionSlug` from the
+ * Sapiom Agents API by its `definitionId`. The registry only knows the id (from
+ * `sapiom.json`'s `{ "definitionId": "188" }`) — the slug lives server-side,
+ * keyed by id.
+ *
+ * Resolution is cached in-memory (id→slug is stable once deployed; a slug
+ * never changes for a given id) so repeat calls across requests are free.
+ * Null resolutions are NOT cached: a transient network failure should be
+ * retryable without a server restart.
+ *
+ * Mirrors `@sapiom/tools`'s DEFAULT_BASE_URL for the base URL resolution.
+ */
+/** Returns the agents API base URL, honouring the same env-var precedence as
+ *  @sapiom/tools's DEFAULT_BASE_URL. */
+export function resolveAgentsBaseUrl() {
+    return (process.env.SAPIOM_AGENTS_URL ??
+        process.env.SAPIOM_TOOLS_BASE ??
+        "https://tools.sapiom.ai");
+}
+/**
+ * Creates a resolver that fetches `GET /agents/v1/definitions/<id>` with the
+ * caller's API key and returns the `slug` field from the response.
+ *
+ * Safe to call from any request handler: never throws, returns null on any
+ * failure (network, 4xx, missing field, unparseable body).
+ */
+export function createDefinitionSlugResolver(opts) {
+    const { apiKey, baseUrl = resolveAgentsBaseUrl(), fetchImpl = fetch } = opts;
+    const cache = new Map();
+    // Each id's resolution failure is logged at most once. resolve() runs on
+    // every /api/state and /api/workflows poll and null results are deliberately
+    // not cached (so a transient failure stays retryable), so without this a
+    // persistent failure — e.g. the harness signed into an account that can't
+    // see this agent — would reprint on every poll. One line per id is enough to
+    // diagnose why the snippet panel fell back to the project name.
+    const loggedFailures = new Set();
+    const warnOnce = (definitionId, reason) => {
+        if (loggedFailures.has(definitionId))
+            return;
+        loggedFailures.add(definitionId);
+        console.error(`[harness] could not resolve deployed-agent slug for definitionId=${definitionId} ` +
+            `at ${baseUrl} (${reason}); the snippet panel will fall back to the project name — ` +
+            `check the harness is signed into the account that owns this agent`);
+    };
+    return {
+        async resolve(definitionId) {
+            // Not signed in: expected (a harness launched without auth), not a
+            // failure worth logging — the panel's project-name fallback covers it.
+            if (!apiKey)
+                return null;
+            const cached = cache.get(definitionId);
+            if (cached !== undefined)
+                return cached;
+            try {
+                const url = `${baseUrl}/agents/v1/definitions/${encodeURIComponent(definitionId)}`;
+                const response = await fetchImpl(url, {
+                    headers: { "x-sapiom-api-key": apiKey },
+                });
+                if (!response.ok) {
+                    warnOnce(definitionId, `HTTP ${response.status}`);
+                    return null;
+                }
+                const body = (await response.json());
+                const slug = typeof body.slug === "string" ? body.slug : null;
+                if (slug !== null) {
+                    cache.set(definitionId, slug);
+                }
+                else {
+                    warnOnce(definitionId, "response had no string `slug` field");
+                }
+                return slug;
+            }
+            catch (err) {
+                warnOnce(definitionId, err instanceof Error ? err.message : String(err));
+                return null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=definition-slug-resolver.js.map

package/dist/core/definition-slug-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-slug-resolver.js","sourceRoot":"","sources":["../../src/core/definition-slug-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;wCACwC;AACxC,MAAM,UAAU,oBAAoB;IAClC,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAC7B,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAC7B,yBAAyB,CAC1B,CAAC;AACJ,CAAC;AAMD;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAK5C;IACC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,oBAAoB,EAAE,EAAE,SAAS,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;IAC7E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,yEAAyE;IACzE,6EAA6E;IAC7E,yEAAyE;IACzE,0EAA0E;IAC1E,6EAA6E;IAC7E,gEAAgE;IAChE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IACzC,MAAM,QAAQ,GAAG,CAAC,YAAoB,EAAE,MAAc,EAAQ,EAAE;QAC9D,IAAI,cAAc,CAAC,GAAG,CAAC,YAAY,CAAC;YAAE,OAAO;QAC7C,cAAc,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACjC,OAAO,CAAC,KAAK,CACX,oEAAoE,YAAY,GAAG;YACjF,MAAM,OAAO,KAAK,MAAM,4DAA4D;YACpF,mEAAmE,CACtE,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,YAAoB;YAChC,mEAAmE;YACnE,uEAAuE;YACvE,IAAI,CAAC,MAAM;gBAAE,OAAO,IAAI,CAAC;YAEzB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACvC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YAExC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,GAAG,OAAO,0BAA0B,kBAAkB,CAAC,YAAY,CAAC,EAAE,CAAC;gBACnF,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;oBACpC,OAAO,EAAE,EAAE,kBAAkB,EAAE,MAAM,EAAE;iBACxC,CAAC,CAAC;gBAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACjB,QAAQ,CAAC,YAAY,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;oBAClD,OAAO,IAAI,CAAC;gBACd,CAAC;gBAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA4B,CAAC;gBAChE,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC9D,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;oBAClB,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;gBAChC,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,YAAY,EAAE,qCAAqC,CAAC,CAAC;gBAChE,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,QAAQ,CACN,YAAY,EACZ,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CACjD,CAAC;gBACF,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/execution-detector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Execution detection — mirrors {@link PortDetector} (core/port-detector.ts).
+ *
+ * A run can start two ways in the harness, and this catches both:
+ *  1. The CLI prints `✓ Started execution <executionId>` (`sapiom agents run`).
+ *  2. The coding agent starts the run via the MCP run tool — the common path —
+ *     whose result carries the id as an `executionId` field
+ *     (`"executionId":"<id>"` / `executionId: <id>`).
+ * The detector is fed the SAME tool.call output PortDetector is (server/index.ts
+ * `onNormalizedEvent`, including the tool RESPONSE summary), so an MCP-triggered
+ * run is caught without changing how runs are triggered. It fires `onExecution`
+ * once per distinct (session, executionId); the integrator wires that to
+ * broadcast `{ type: "execution.started", … }` on /ws/events.
+ *
+ * Same streaming-safe design as PortDetector: a match touching the very end of
+ * the buffered text is held back (the id may still be growing in the next
+ * chunk) and finalized by `flush()`, which the integrator calls right after
+ * feeding a discrete, already-complete string (one tool.call field).
+ */
+/**
+ * Pure parser: every execution id announced in a chunk of CLI/tool output, in
+ * order (empty when the chunk announces none). This is the mutation-tested
+ * core — the {@link ExecutionDetector} class only adds streaming buffering and
+ * per-session dedupe on top of it.
+ */
+export declare function parseExecutionIds(text: string): string[];
+/** Where a detected run executes. Only `"prod"` is emitted today: the CLI's
+ *  `Started execution` line is the prod-run announcement; local runs are
+ *  rendered from their final result, not polled (see the design). */
+export type ExecutionTarget = "prod" | "local";
+export interface ExecutionDetectorDeps {
+    onExecution(harnessSessionId: string, executionId: string, target: ExecutionTarget): void;
+}
+/**
+ * Stateful, streaming-safe, and dedupes per (session, executionId) so a run id
+ * that reappears in output only ever fires `onExecution` once for the session's
+ * lifetime. `reset()` clears a session's state on exit so a reused session id
+ * starts clean.
+ */
+export declare class ExecutionDetector {
+    private readonly deps;
+    private readonly buffers;
+    private readonly seen;
+    constructor(deps: ExecutionDetectorDeps);
+    feed(chunk: string, harnessSessionId: string): void;
+    /**
+     * Finalizes whatever's held back for a session, immediately. Call this right
+     * after `feed()` whenever the fed text is a discrete, complete string (one
+     * tool.call field): without it, an id landing at the very end — the common
+     * shape "✓ Started execution exec_123" — would be held pending forever, since
+     * no "next chunk" is coming.
+     */
+    flush(harnessSessionId: string): void;
+    /** Drops buffered/dedupe state for a session — call on session exit so a
+     *  reused session id starts clean. */
+    reset(harnessSessionId: string): void;
+    private tryEmit;
+}
+//# sourceMappingURL=execution-detector.d.ts.map

package/dist/core/execution-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-detector.d.ts","sourceRoot":"","sources":["../../src/core/execution-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMxD;AAED;;qEAEqE;AACrE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,qBAAqB;IACpC,WAAW,CACT,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,eAAe,GACtB,IAAI,CAAC;CACT;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAIhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;gBAE1B,IAAI,EAAE,qBAAqB;IAExD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAsBnD;;;;;;OAMG;IACH,KAAK,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAUrC;0CACsC;IACtC,KAAK,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAKrC,OAAO,CAAC,OAAO;CAUhB"}

package/dist/core/execution-detector.js

@@ -0,0 +1,110 @@
+/**
+ * Execution detection — mirrors {@link PortDetector} (core/port-detector.ts).
+ *
+ * A run can start two ways in the harness, and this catches both:
+ *  1. The CLI prints `✓ Started execution <executionId>` (`sapiom agents run`).
+ *  2. The coding agent starts the run via the MCP run tool — the common path —
+ *     whose result carries the id as an `executionId` field
+ *     (`"executionId":"<id>"` / `executionId: <id>`).
+ * The detector is fed the SAME tool.call output PortDetector is (server/index.ts
+ * `onNormalizedEvent`, including the tool RESPONSE summary), so an MCP-triggered
+ * run is caught without changing how runs are triggered. It fires `onExecution`
+ * once per distinct (session, executionId); the integrator wires that to
+ * broadcast `{ type: "execution.started", … }` on /ws/events.
+ *
+ * Same streaming-safe design as PortDetector: a match touching the very end of
+ * the buffered text is held back (the id may still be growing in the next
+ * chunk) and finalized by `flush()`, which the integrator calls right after
+ * feeding a discrete, already-complete string (one tool.call field).
+ */
+/** Execution ids are the stable handles the executions API mints (e.g.
+ *  `exec_ab12…`). Id-safe characters only, so a trailing space, newline, or
+ *  ANSI reset ends the match rather than being captured into the id. */
+const EXECUTION_ID = String.raw `[A-Za-z0-9_-]+`;
+/** Two anchors, one capture group: the CLI's `Started execution <id>` line, or
+ *  the `executionId` field from the run tool's structured result (quote/colon/
+ *  space/equals between the key and the id). Both are start-time signals tied to
+ *  a real run, so a match always refers to a run the user is actually driving. */
+const EXECUTION_PATTERN_SOURCE = String.raw `(?:Started execution |executionId["'\s:=]+)(${EXECUTION_ID})`;
+/** Long enough to hold either anchor ("Started execution " / `executionId":"`)
+ *  split across a chunk boundary, plus a few id characters either side. */
+const TAIL_SAFETY = 48;
+/**
+ * Pure parser: every execution id announced in a chunk of CLI/tool output, in
+ * order (empty when the chunk announces none). This is the mutation-tested
+ * core — the {@link ExecutionDetector} class only adds streaming buffering and
+ * per-session dedupe on top of it.
+ */
+export function parseExecutionIds(text) {
+    const regex = new RegExp(EXECUTION_PATTERN_SOURCE, "g");
+    const ids = [];
+    let match;
+    while ((match = regex.exec(text)))
+        ids.push(match[1]);
+    return ids;
+}
+/**
+ * Stateful, streaming-safe, and dedupes per (session, executionId) so a run id
+ * that reappears in output only ever fires `onExecution` once for the session's
+ * lifetime. `reset()` clears a session's state on exit so a reused session id
+ * starts clean.
+ */
+export class ExecutionDetector {
+    constructor(deps) {
+        this.deps = deps;
+        this.buffers = new Map();
+        this.seen = new Map();
+    }
+    feed(chunk, harnessSessionId) {
+        const combined = (this.buffers.get(harnessSessionId) ?? "") + chunk;
+        const regex = new RegExp(EXECUTION_PATTERN_SOURCE, "g");
+        let match;
+        let pendingFrom = null;
+        while ((match = regex.exec(combined))) {
+            const end = match.index + match[0].length;
+            if (end === combined.length) {
+                // The id could still be growing (more chars due next chunk) — hold back.
+                pendingFrom = match.index;
+                break;
+            }
+            this.tryEmit(harnessSessionId, match[1]);
+        }
+        const retainFrom = pendingFrom ?? Math.max(0, combined.length - TAIL_SAFETY);
+        this.buffers.set(harnessSessionId, combined.slice(retainFrom));
+    }
+    /**
+     * Finalizes whatever's held back for a session, immediately. Call this right
+     * after `feed()` whenever the fed text is a discrete, complete string (one
+     * tool.call field): without it, an id landing at the very end — the common
+     * shape "✓ Started execution exec_123" — would be held pending forever, since
+     * no "next chunk" is coming.
+     */
+    flush(harnessSessionId) {
+        const pending = this.buffers.get(harnessSessionId);
+        if (!pending)
+            return;
+        // Re-parse the whole pending buffer (vs an inline loop) — same result, and
+        // tryEmit dedupes so a match already emitted by feed() is a harmless no-op.
+        for (const id of parseExecutionIds(pending))
+            this.tryEmit(harnessSessionId, id);
+        this.buffers.delete(harnessSessionId);
+    }
+    /** Drops buffered/dedupe state for a session — call on session exit so a
+     *  reused session id starts clean. */
+    reset(harnessSessionId) {
+        this.buffers.delete(harnessSessionId);
+        this.seen.delete(harnessSessionId);
+    }
+    tryEmit(harnessSessionId, executionId) {
+        let ids = this.seen.get(harnessSessionId);
+        if (!ids) {
+            ids = new Set();
+            this.seen.set(harnessSessionId, ids);
+        }
+        if (ids.has(executionId))
+            return;
+        ids.add(executionId);
+        this.deps.onExecution(harnessSessionId, executionId, "prod");
+    }
+}
+//# sourceMappingURL=execution-detector.js.map

package/dist/core/execution-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-detector.js","sourceRoot":"","sources":["../../src/core/execution-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;wEAEwE;AACxE,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAA,gBAAgB,CAAC;AAChD;;;kFAGkF;AAClF,MAAM,wBAAwB,GAAG,MAAM,CAAC,GAAG,CAAA,+CAA+C,YAAY,GAAG,CAAC;AAE1G;2EAC2E;AAC3E,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;IACxD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,GAAG,CAAC;AACb,CAAC;AAeD;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAI5B,YAA6B,IAA2B;QAA3B,SAAI,GAAJ,IAAI,CAAuB;QAHvC,YAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;QACpC,SAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEI,CAAC;IAE5D,IAAI,CAAC,KAAa,EAAE,gBAAwB;QAC1C,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC;QACpE,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;QAExD,IAAI,KAA6B,CAAC;QAClC,IAAI,WAAW,GAAkB,IAAI,CAAC;QAEtC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACtC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC1C,IAAI,GAAG,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC5B,yEAAyE;gBACzE,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC;gBAC1B,MAAM;YACR,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,UAAU,GACd,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;QAC5D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,gBAAwB;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,2EAA2E;QAC3E,4EAA4E;QAC5E,KAAK,MAAM,EAAE,IAAI,iBAAiB,CAAC,OAAO,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACxC,CAAC;IAED;0CACsC;IACtC,KAAK,CAAC,gBAAwB;QAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,CAAC;IAEO,OAAO,CAAC,gBAAwB,EAAE,WAAmB;QAC3D,IAAI,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,OAAO;QACjC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/core/inject/mcp-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-config.d.ts","sourceRoot":"","sources":["../../../src/core/inject/mcp-config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;iFAC6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CA6BjB"}
+{"version":3,"file":"mcp-config.d.ts","sourceRoot":"","sources":["../../../src/core/inject/mcp-config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;iFAC6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAqCjB"}

package/dist/core/inject/mcp-config.js

@@ -25,7 +25,15 @@ export async function generateMcpConfig(harnessSessionId, options = {}) {
             },
             "sapiom-dev": {
                 command: "npx",
-                args: ["-y", "@sapiom/mcp"],
+                // Pin the dist-tag (`@latest`) rather than the bare name so npx always
+                // resolves the PUBLISHED package from the registry. A bare
+                // `@sapiom/mcp` resolves a LOCAL workspace copy whenever the harness
+                // runs from inside the sapiom-js monorepo (dogfooding/dev) — whose bin
+                // isn't linked, so the server fails to launch ("sapiom-mcp: command
+                // not found" → JSON-RPC -32000). A dist-tag spec forces registry
+                // resolution and is behaviourally identical to what a real user
+                // (outside the monorepo) already gets, so it's a pure robustness fix.
+                args: ["-y", "@sapiom/mcp@latest"],
                 ...(devEnv ? { env: devEnv } : {}),
             },
         },

package/dist/core/inject/mcp-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-config.js","sourceRoot":"","sources":["../../../src/core/inject/mcp-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAoBhD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,gBAAwB,EACxB,UAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACtG,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAChF,MAAM,MAAM,GAAuC,iBAAiB;QAClE,CAAC,CAAC,EAAE,kBAAkB,EAAE,iBAAiB,EAAE;QAC3C,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,MAAM,GAAG;QACb,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,8BAA8B;gBACnC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE;YACD,YAAY,EAAE;gBACZ,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC;gBAC3B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACnC;SACF;KACF,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IACnD,yEAAyE;IACzE,oEAAoE;IACpE,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"mcp-config.js","sourceRoot":"","sources":["../../../src/core/inject/mcp-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAoBhD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,gBAAwB,EACxB,UAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACtG,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAChF,MAAM,MAAM,GAAuC,iBAAiB;QAClE,CAAC,CAAC,EAAE,kBAAkB,EAAE,iBAAiB,EAAE;QAC3C,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,MAAM,GAAG;QACb,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,8BAA8B;gBACnC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE;YACD,YAAY,EAAE;gBACZ,OAAO,EAAE,KAAK;gBACd,uEAAuE;gBACvE,2DAA2D;gBAC3D,qEAAqE;gBACrE,uEAAuE;gBACvE,oEAAoE;gBACpE,iEAAiE;gBACjE,gEAAgE;gBAChE,sEAAsE;gBACtE,IAAI,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC;gBAClC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACnC;SACF;KACF,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IACnD,yEAAyE;IACzE,oEAAoE;IACpE,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/render-run-state.d.ts

@@ -0,0 +1,9 @@
+import type { ExecutionProjection } from "@sapiom/agent-core";
+import type { RunView } from "../shared/types.js";
+/**
+ * Map a decoded {@link ExecutionProjection} to the {@link RunView} the canvas
+ * renders. Order-preserving over `steps`; total (never throws) because the
+ * projection is already the decoded, degradation-tolerant shape.
+ */
+export declare function renderRunState(decoded: ExecutionProjection): RunView;
+//# sourceMappingURL=render-run-state.d.ts.map

package/dist/core/render-run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-run-state.d.ts","sourceRoot":"","sources":["../../src/core/render-run-state.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,mBAAmB,EAEpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAwB,MAAM,oBAAoB,CAAC;AAoHxE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAMpE"}

package/dist/core/render-run-state.js

@@ -0,0 +1,139 @@
+/**
+ * renderRunState — the ONE pure mapper from a decoded {@link ExecutionProjection}
+ * to the canvas's {@link RunView} render state.
+ *
+ * Pure and deterministic: no LLM, no I/O, no clock. Every field is derived from
+ * the decoded projection, so the same function drives the polling path today and
+ * a future WebSocket push (only the data source swaps, never this mapping). Cost
+ * and latency are read straight from the projection and rendered statically — the
+ * LLM is only ever invoked later by an explicit debug-macro press, never to
+ * compute what's shown here.
+ *
+ * Honest absence is preserved end to end: a step with no cost on this read gets
+ * no `costUsd` (not `0`), a still-running step gets no `latencyMs`, and a step
+ * with no logs gets no `logSlice` — matching the SDK's "null cost is honest
+ * absence, never a fabricated $0" contract.
+ */
+import { isExecutionTerminal } from "@sapiom/agent-core";
+/**
+ * Cap on the characters of a step's executor log buffer surfaced in `logSlice`.
+ * The TAIL is kept (most recent lines) because failures surface at the end of a
+ * log. This is a payload guard on the poll response; the debug-macro context
+ * extractor does the final, smaller trim for prompt injection.
+ */
+const LOG_SLICE_MAX = 4000;
+/**
+ * Fold the run's lifecycle status into the four states the UI distinguishes.
+ * Reuses `isExecutionTerminal` (agent-core's single source of truth for "won't
+ * advance on its own") so a newly-added terminal status can never be misdrawn as
+ * still-running: anything non-terminal (running, paused, queued, unknown) is
+ * `running`; the terminal set normalizes `canceled` → `cancelled`.
+ */
+function toRunStatus(raw) {
+    if (!isExecutionTerminal(raw))
+        return "running";
+    if (raw === "completed")
+        return "completed";
+    if (raw === "failed")
+        return "failed";
+    return "cancelled"; // the only remaining terminal statuses: "cancelled" / "canceled"
+}
+/**
+ * Fold a step's raw status into a {@link StepStatus}. Handles the real engine
+ * vocabulary (`succeeded`/`threw` from prod agents surface) plus the earlier
+ * values (`completed`/`failed`/`cancelled`/`canceled`). A cancelled or threw
+ * step folds to `failed` (it did not pass — mirrors run-local.ts); anything
+ * not yet running/passed/failed is `pending` (unstarted, queued, or unknown).
+ */
+function toStepStatus(raw) {
+    if (raw === "completed" || raw === "succeeded")
+        return "passed";
+    if (raw === "failed" ||
+        raw === "threw" ||
+        raw === "cancelled" ||
+        raw === "canceled")
+        return "failed";
+    if (raw === "running")
+        return "running";
+    return "pending";
+}
+/** Captured USD as a number; `undefined` on honest absence (null cost) or an
+ *  unparseable amount — never a fabricated `0`. */
+function toCostUsd(cost) {
+    if (!cost)
+        return undefined;
+    const n = Number(cost.capturedUsd);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** `finishedAt − startedAt` in ms; `undefined` while still running (no finish)
+ *  or when either timestamp is unparseable. A negative delta (clock skew) is
+ *  dropped rather than shown as a misleading negative latency. */
+function toLatencyMs(startedAt, finishedAt) {
+    if (!startedAt || !finishedAt)
+        return undefined;
+    const start = Date.parse(startedAt);
+    const end = Date.parse(finishedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return undefined;
+    const delta = end - start;
+    return delta >= 0 ? delta : undefined;
+}
+/** One executor log entry → a compact line. Accepts the `{ ts, level, msg }`
+ *  wire shape (or `message`), a bare string, or anything else (stringified). */
+function formatLogEntry(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry !== null && typeof entry === "object") {
+        const e = entry;
+        const parts = [e.ts, e.level, e.msg ?? e.message].filter((p) => typeof p === "string" || typeof p === "number");
+        if (parts.length > 0)
+            return parts.map(String).join(" ");
+    }
+    return String(entry);
+}
+/** Format the executor log buffer into a trimmed, tail-preserving slice, or
+ *  `undefined` when there are no usable logs. */
+function toLogSlice(logs) {
+    if (!Array.isArray(logs) || logs.length === 0)
+        return undefined;
+    const text = logs.map(formatLogEntry).join("\n").trim();
+    if (text === "")
+        return undefined;
+    return text.length > LOG_SLICE_MAX
+        ? text.slice(text.length - LOG_SLICE_MAX)
+        : text;
+}
+/** Map one projection step to its render view. Optional fields are assigned only
+ *  when present so absence stays absent (not `undefined`) in the JSON payload. */
+function toStepView(step) {
+    const view = {
+        id: step.spanId ?? `step-${step.stepOrder}-${step.attempt}`,
+        name: step.stepName,
+        status: toStepStatus(step.status),
+    };
+    const costUsd = toCostUsd(step.cost);
+    if (costUsd !== undefined)
+        view.costUsd = costUsd;
+    const latencyMs = toLatencyMs(step.startedAt, step.finishedAt);
+    if (latencyMs !== undefined)
+        view.latencyMs = latencyMs;
+    if (step.error?.message)
+        view.error = step.error.message;
+    const logSlice = toLogSlice(step.logs);
+    if (logSlice !== undefined)
+        view.logSlice = logSlice;
+    return view;
+}
+/**
+ * Map a decoded {@link ExecutionProjection} to the {@link RunView} the canvas
+ * renders. Order-preserving over `steps`; total (never throws) because the
+ * projection is already the decoded, degradation-tolerant shape.
+ */
+export function renderRunState(decoded) {
+    return {
+        executionId: decoded.id,
+        status: toRunStatus(decoded.status),
+        steps: decoded.steps.map(toStepView),
+    };
+}
+//# sourceMappingURL=render-run-state.js.map

package/dist/core/render-run-state.js.map

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

package/dist/core/run-spend.d.ts

@@ -0,0 +1,55 @@
+/**
+ * run-spend — fetches the cost/spend summary for a prod execution from the
+ * core surface and maps it to a {@link RunSpend} the canvas can poll.
+ *
+ * WHY the core surface: the spend endpoint lives at
+ * `GET /v1/workflows/executions/:id/spend` on api.sapiom.ai (the CORE
+ * capability surface), which is distinct from the agents surface
+ * (tools.sapiom.ai) that run-state.ts uses.  The same caveat applies:
+ * env-consistency with the run's environment matters — both surfaces must be
+ * overridden together when pointing at non-prod.
+ *
+ * WHY the key stays server-side: same rationale as run-state.ts — the Sapiom
+ * API key is a harness credential that must never reach the browser.  The
+ * harness server fetches on behalf of the canvas, so the SPA polls a local
+ * `/api/runs/:id/spend` endpoint (no key in the request) rather than calling
+ * the upstream surface directly.
+ */
+import type { RunSpend } from "../shared/types.js";
+/**
+ * Resolve the CORE surface base URL for the spend endpoint.
+ *
+ * The spend endpoint lives on the CORE host (`api.<env>`), distinct from the
+ * agents host run-state.ts uses (`tools.<env>`). Crucially, a run lives in the
+ * agents env, and its spend must be read from the MATCHING core env — otherwise
+ * a prod run's spend queried against dev 401s. So we DERIVE the core host from
+ * the agents host (`tools.<env>` → `api.<env>`) rather than reading
+ * `SAPIOM_API_URL`, which in some setups points at a different env than the
+ * agents surface. An explicit `SAPIOM_CORE_URL` still wins for full control.
+ */
+export declare function resolveCoreBaseUrl(): string;
+export type RunSpendResult = {
+    ok: true;
+    spend: RunSpend;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export interface RunSpendFetcherOpts {
+    apiKey: string | null;
+    baseUrl?: string;
+    /** Injectable fetch implementation — defaults to global fetch. Test seam. */
+    fetchImpl?: typeof fetch;
+}
+export interface RunSpendFetcher {
+    fetch(executionId: string): Promise<RunSpendResult>;
+}
+/**
+ * Create a fetcher that resolves an execution's spend/cost from the core
+ * surface. The fetcher is intentionally non-throwing: all error paths return
+ * a typed {@link RunSpendResult} with `ok: false` so the router can forward
+ * the appropriate HTTP status without a try/catch at the call site.
+ */
+export declare function createRunSpendFetcher(opts: RunSpendFetcherOpts): RunSpendFetcher;
+//# sourceMappingURL=run-spend.d.ts.map

package/dist/core/run-spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-spend.d.ts","sourceRoot":"","sources":["../../src/core/run-spend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAc3C;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,GACxB,eAAe,CAsEjB"}

package/dist/core/run-spend.js

@@ -0,0 +1,109 @@
+/**
+ * run-spend — fetches the cost/spend summary for a prod execution from the
+ * core surface and maps it to a {@link RunSpend} the canvas can poll.
+ *
+ * WHY the core surface: the spend endpoint lives at
+ * `GET /v1/workflows/executions/:id/spend` on api.sapiom.ai (the CORE
+ * capability surface), which is distinct from the agents surface
+ * (tools.sapiom.ai) that run-state.ts uses.  The same caveat applies:
+ * env-consistency with the run's environment matters — both surfaces must be
+ * overridden together when pointing at non-prod.
+ *
+ * WHY the key stays server-side: same rationale as run-state.ts — the Sapiom
+ * API key is a harness credential that must never reach the browser.  The
+ * harness server fetches on behalf of the canvas, so the SPA polls a local
+ * `/api/runs/:id/spend` endpoint (no key in the request) rather than calling
+ * the upstream surface directly.
+ */
+import { resolveAgentsBaseUrl } from "./run-state.js";
+/**
+ * Resolve the CORE surface base URL for the spend endpoint.
+ *
+ * The spend endpoint lives on the CORE host (`api.<env>`), distinct from the
+ * agents host run-state.ts uses (`tools.<env>`). Crucially, a run lives in the
+ * agents env, and its spend must be read from the MATCHING core env — otherwise
+ * a prod run's spend queried against dev 401s. So we DERIVE the core host from
+ * the agents host (`tools.<env>` → `api.<env>`) rather than reading
+ * `SAPIOM_API_URL`, which in some setups points at a different env than the
+ * agents surface. An explicit `SAPIOM_CORE_URL` still wins for full control.
+ */
+export function resolveCoreBaseUrl() {
+    const override = process.env.SAPIOM_CORE_URL;
+    if (override)
+        return override;
+    const agents = resolveAgentsBaseUrl();
+    try {
+        const url = new URL(agents);
+        if (url.hostname.startsWith("tools.")) {
+            url.hostname = `api.${url.hostname.slice("tools.".length)}`;
+            return url.origin;
+        }
+    }
+    catch {
+        // Unparseable agents URL — fall through to the prod default.
+    }
+    return "https://api.sapiom.ai";
+}
+/**
+ * Create a fetcher that resolves an execution's spend/cost from the core
+ * surface. The fetcher is intentionally non-throwing: all error paths return
+ * a typed {@link RunSpendResult} with `ok: false` so the router can forward
+ * the appropriate HTTP status without a try/catch at the call site.
+ */
+export function createRunSpendFetcher(opts) {
+    const { apiKey, baseUrl = resolveCoreBaseUrl(), fetchImpl = fetch } = opts;
+    return {
+        async fetch(executionId) {
+            // No API key — do not touch the network; the harness is not signed in.
+            if (!apiKey) {
+                return {
+                    ok: false,
+                    status: 503,
+                    error: "harness is not signed in to Sapiom",
+                };
+            }
+            let res;
+            try {
+                res = await fetchImpl(`${baseUrl}/v1/workflows/executions/${encodeURIComponent(executionId)}/spend`, { headers: { "x-api-key": apiKey } });
+            }
+            catch {
+                return { ok: false, status: 502, error: "gateway unreachable" };
+            }
+            if (res.status === 404) {
+                return { ok: false, status: 404, error: "spend not found" };
+            }
+            if (!res.ok) {
+                return {
+                    ok: false,
+                    status: 502,
+                    error: `gateway responded ${res.status}`,
+                };
+            }
+            try {
+                const raw = (await res.json());
+                // The response is ExecutionSpendDto — we map the capability sub-object
+                // fields to RunSpend, falling back to top-level totalUsd when needed.
+                const capability = raw.capability;
+                const totalUsd = capability?.totalUsd ??
+                    raw.totalUsd ??
+                    "0";
+                const settleState = capability?.settleState ?? "pending";
+                const rawByStep = capability?.byStep ?? [];
+                const byStep = rawByStep.map((s) => {
+                    const step = s;
+                    return {
+                        name: step.stepName,
+                        totalUsd: step.totalUsd,
+                        entryCount: step.entryCount,
+                    };
+                });
+                const spend = { executionId, totalUsd, settleState, byStep };
+                return { ok: true, spend };
+            }
+            catch {
+                return { ok: false, status: 502, error: "could not decode spend" };
+            }
+        },
+    };
+}
+//# sourceMappingURL=run-spend.js.map

package/dist/core/run-spend.js.map

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