@nodetool-ai/websocket 0.7.0-rc.23 → 0.8.2

package/dist/drain.js

@@ -0,0 +1,68 @@
+/**
+ * Process-wide drain state.
+ *
+ * A chat turn already survives a dropped socket ({@link ChatTurnSession}), but
+ * not a restart: the process goes away with the turn's unwritten transcript
+ * rows and its unflushed spans. Fly allows at most 300 s between SIGTERM and
+ * the kill, and a turn can run for half an hour, so the deploy drains a machine
+ * *before* it signals it — SIGUSR2 sets this flag, and the machine then takes
+ * no new work while the turns already in flight finish here.
+ *
+ * Draining changes four things: `/health` answers 503, so the proxy routes new
+ * clients to the other machine; a new `/ws` handshake is refused with 503; an
+ * idle connection is closed with 1012 (service restart) and one holding a turn
+ * or run is closed when that settles; and `chat_message` / `run_job` are
+ * refused before anything is persisted. SIGTERM sets the same flag as a
+ * fallback and then aborts what is left.
+ *
+ * One flag, one process, no un-drain: a machine that has started draining is on
+ * its way out.
+ */
+import { createLogger } from "@nodetool-ai/config";
+const log = createLogger("nodetool.websocket.drain");
+let draining = false;
+const listeners = new Set();
+/** True once this process has entered the drain. */
+export function isDraining() {
+    return draining;
+}
+/** Enter the drain. Idempotent — a second call notifies nobody. */
+export function startDrain() {
+    if (draining)
+        return;
+    draining = true;
+    log.info("Draining: taking no new work");
+    for (const listener of [...listeners]) {
+        runListener(listener);
+    }
+}
+/**
+ * React to the drain. A listener registered while already draining runs at
+ * once: a connection accepted in the window before the refusal took effect has
+ * to close itself the same way one that predates the drain does. Returns the
+ * unsubscribe.
+ */
+export function onDrain(listener) {
+    listeners.add(listener);
+    if (draining)
+        runListener(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+function runListener(listener) {
+    try {
+        listener();
+    }
+    catch (err) {
+        log.warn("Drain listener failed", {
+            error: err instanceof Error ? err.message : String(err)
+        });
+    }
+}
+/** Test-only: return the process to the not-draining state. */
+export function _resetDrainForTest() {
+    draining = false;
+    listeners.clear();
+}
+//# sourceMappingURL=drain.js.map

package/dist/drain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.js","sourceRoot":"","sources":["../src/drain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,GAAG,GAAG,YAAY,CAAC,0BAA0B,CAAC,CAAC;AAErD,IAAI,QAAQ,GAAG,KAAK,CAAC;AACrB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;AAExC,oDAAoD;AACpD,MAAM,UAAU,UAAU;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,UAAU;IACxB,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAChB,GAAG,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IACzC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;QACtC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,QAAoB;IAC1C,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,QAAQ;QAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,QAAoB;IACvC,IAAI,CAAC;QACH,QAAQ,EAAE,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,uBAAuB,EAAE;YAChC,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB;IAChC,QAAQ,GAAG,KAAK,CAAC;IACjB,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}

package/dist/e2e-server.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * E2E harness backend — runs the real NodeTool HTTP+WebSocket backend with an
+ * in-memory SQLite database, tailored for the web E2E test runner
+ * (`web/e2e-runner.html`). It is fully hermetic: every external provider is
+ * faked so the shipped templates run in CI with no API keys and no network.
+ *
+ * Faking strategy:
+ *   - LLM/agent providers: every registered provider id is re-registered with a
+ *     FakeProvider (a ScriptedProvider with no required credentials), so
+ *     `getProvider`/`isProviderConfigured` and the runner's resolveProvider all
+ *     return a configured fake regardless of how a node resolves its provider.
+ *   - External / media-generating nodes (fal, replicate, search, http, image /
+ *     video / audio generation, …): resolved to a fake executor that returns
+ *     type-correct placeholder outputs derived from the node's output metadata,
+ *     so downstream nodes and output nodes still receive well-formed values.
+ *   - Pure-compute nodes (text, control, data, math, …) run for real.
+ *   - Unknown node types (e.g. the `test.Input` placeholder) pass through.
+ *
+ * Usage (via the Playwright globalSetup — not normally invoked directly):
+ *   tsx packages/websocket/src/e2e-server.ts
+ *
+ * Environment:
+ *   PORT / HOST                bind config (default 127.0.0.1:7777)
+ *   SECRETS_MASTER_KEY         base64 master key (a test default is used if unset)
+ *   NODETOOL_E2E_EXAMPLES_DIR  examples dir served at /api/examples (optional)
+ *   NODETOOL_TRACE_FILE        JSONL trace output path (optional)
+ */
+export {};
+//# sourceMappingURL=e2e-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"e2e-server.d.ts","sourceRoot":"","sources":["../src/e2e-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/e2e-server.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * E2E harness backend — runs the real NodeTool HTTP+WebSocket backend with an
+ * in-memory SQLite database, tailored for the web E2E test runner
+ * (`web/e2e-runner.html`). It is fully hermetic: every external provider is
+ * faked so the shipped templates run in CI with no API keys and no network.
+ *
+ * Faking strategy:
+ *   - LLM/agent providers: every registered provider id is re-registered with a
+ *     FakeProvider (a ScriptedProvider with no required credentials), so
+ *     `getProvider`/`isProviderConfigured` and the runner's resolveProvider all
+ *     return a configured fake regardless of how a node resolves its provider.
+ *   - External / media-generating nodes (fal, replicate, search, http, image /
+ *     video / audio generation, …): resolved to a fake executor that returns
+ *     type-correct placeholder outputs derived from the node's output metadata,
+ *     so downstream nodes and output nodes still receive well-formed values.
+ *   - Pure-compute nodes (text, control, data, math, …) run for real.
+ *   - Unknown node types (e.g. the `test.Input` placeholder) pass through.
+ *
+ * Usage (via the Playwright globalSetup — not normally invoked directly):
+ *   tsx packages/websocket/src/e2e-server.ts
+ *
+ * Environment:
+ *   PORT / HOST                bind config (default 127.0.0.1:7777)
+ *   SECRETS_MASTER_KEY         base64 master key (a test default is used if unset)
+ *   NODETOOL_E2E_EXAMPLES_DIR  examples dir served at /api/examples (optional)
+ *   NODETOOL_TRACE_FILE        JSONL trace output path (optional)
+ */
+import { initTestDb } from "@nodetool-ai/models";
+import { initMasterKey } from "@nodetool-ai/security";
+import { createFakeExecutorResolver, fakeAllProviders, resolveFakeProvider } from "./fake-runtime.js";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { createTestUiServer } from "./test-ui-server.js";
+import { refreshSandboxCatalog } from "./sandbox-catalog.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env.PORT ?? 7777);
+const HOST = process.env.HOST ?? "127.0.0.1";
+// Base64-encoded 32-byte placeholder key used only for E2E tests.
+const E2E_TEST_MASTER_KEY_B64 = "RTJFX1RFU1RfS0VZX0RPX05PVF9VU0VfSU5fUFJPRCE=";
+async function main() {
+    if (process.env.NODE_ENV === "production" &&
+        !process.env.SECRETS_MASTER_KEY) {
+        throw new Error("[e2e-server] SECRETS_MASTER_KEY must be set when NODE_ENV=production");
+    }
+    process.env.SECRETS_MASTER_KEY =
+        process.env.SECRETS_MASTER_KEY ?? E2E_TEST_MASTER_KEY_B64;
+    const traceFile = process.env.NODETOOL_TRACE_FILE;
+    if (traceFile || process.env.NODETOOL_TRACE_STDOUT) {
+        const { initTelemetry } = await import("@nodetool-ai/runtime");
+        const telemetryOptions = {
+            serviceName: "nodetool-e2e",
+            silent: true
+        };
+        if (traceFile) {
+            telemetryOptions.traceFile = traceFile;
+        }
+        await initTelemetry(telemetryOptions);
+    }
+    initTestDb();
+    await initMasterKey();
+    fakeAllProviders();
+    // The shipped sandbox packs, so a Code node in an example workflow can
+    // import one. `createTestUiServer` registers built-in nodes without loading
+    // packs, which leaves no catalog on the process — and a Code node that
+    // imports one then fails with "Sandbox packages are not available in this
+    // process" rather than running the way it does on the real server.
+    await refreshSandboxCatalog();
+    let registry = null;
+    const examplesDir = resolveExamplesDir();
+    const serverOptions = {
+        port: PORT,
+        host: HOST,
+        passthroughUnknownNodes: true,
+        configureRegistry: (r) => {
+            registry = r;
+            // Providers self-register on import; re-fake after registry setup in case
+            // any provider registration happened during node registration.
+            fakeAllProviders();
+        },
+        resolveExecutor: createFakeExecutorResolver(() => registry),
+        resolveProvider: resolveFakeProvider
+    };
+    if (examplesDir) {
+        serverOptions.examplesDir = examplesDir;
+    }
+    const srv = createTestUiServer(serverOptions);
+    await srv.listen();
+    console.log(`[e2e-server] Ready on http://${HOST}:${PORT} (${srv.info.metadataCount} nodes registered)` +
+        (examplesDir ? ` examples=${examplesDir}` : ""));
+    // Human-readable readiness marker; the Playwright globalSetup gates on the
+    // backend accepting TCP connections (waitForPort), not on this line.
+    process.stdout.write("[e2e-server] READY\n");
+}
+function resolveExamplesDir() {
+    const fromEnv = process.env.NODETOOL_E2E_EXAMPLES_DIR;
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    const repoRoot = resolve(__dirname, "..", "..", "..");
+    const candidates = [
+        resolve(repoRoot, "packages", "base-nodes", "nodetool", "examples", "nodetool-base"),
+        resolve(repoRoot, "examples", "workflows")
+    ];
+    return candidates.find((dir) => existsSync(dir));
+}
+main().catch((error) => {
+    console.error("[e2e-server] Failed to start:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=e2e-server.js.map

package/dist/e2e-server.js.map

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

package/dist/error-traces.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Server-side error tracing: capture, retention and opt-in sync.
+ *
+ * Capture: {@link captureError} turns a thrown value into a redacted row in
+ * `nodetool_error_traces` (see `@nodetool-ai/models` `recordErrorTrace`). It
+ * is fire-and-forget and never throws, so an error handler can call it
+ * without making its own failure worse.
+ *
+ * Retention: traces older than `NODETOOL_ERROR_TRACE_RETENTION_DAYS` (default
+ * 30) are pruned at startup and once a day.
+ *
+ * Sync: off unless both `NODETOOL_ERROR_TRACE_SYNC_URL` and
+ * `NODETOOL_ERROR_TRACE_SYNC_TOKEN` are set. Then locally captured traces are
+ * pushed every few minutes to that NodeTool server's `errorTraces.ingest`
+ * procedure, authenticated by the access token. The receiving server stores
+ * them under the token's user and redacts them again; on the hosted service
+ * that database is Supabase. A local install never holds database
+ * credentials for the cloud.
+ *
+ * Capture can be switched off entirely with `NODETOOL_ERROR_TRACES=0`.
+ */
+import { type ErrorTraceSeverity, type ErrorTraceSource } from "@nodetool-ai/models";
+type Env = Record<string, string | undefined>;
+/** False when `NODETOOL_ERROR_TRACES` is `0`, `false` or `off`. */
+export declare function isErrorTracingEnabled(env?: Env): boolean;
+export interface CaptureErrorOptions {
+    source: ErrorTraceSource;
+    userId?: string | null;
+    severity?: ErrorTraceSeverity;
+    /** Identifiers only; keys outside `ERROR_TRACE_CONTEXT_KEYS` are dropped. */
+    context?: Record<string, unknown>;
+}
+/** Record a redacted trace for `error`. Fire-and-forget; never throws. */
+export declare function captureError(error: unknown, opts: CaptureErrorOptions): void;
+export interface ErrorTraceSyncConfig {
+    /** Base URL of the receiving NodeTool server, e.g. https://api.nodetool.ai */
+    url: string;
+    /** A NodeTool access token for the account the traces belong to. */
+    token: string;
+}
+/** The sync target from the environment, or null when sync is off. */
+export declare function errorTraceSyncConfig(env?: Env): ErrorTraceSyncConfig | null;
+export interface SyncResult {
+    pushed: number;
+    /** Set when a batch was refused; the traces stay unsynced for a retry. */
+    error?: string;
+}
+/**
+ * Push unsynced local traces in batches until none remain or a batch fails.
+ * `fetchImpl` is injectable for tests.
+ */
+export declare function syncErrorTraces(config: ErrorTraceSyncConfig, fetchImpl?: typeof fetch): Promise<SyncResult>;
+/** Start pruning, and syncing when configured. Returns a stop function. */
+export declare function startErrorTraceMaintenance(env?: Env): () => void;
+export {};
+//# sourceMappingURL=error-traces.d.ts.map

package/dist/error-traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-traces.d.ts","sourceRoot":"","sources":["../src/error-traces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EASL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAK7B,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,GAAiB,GAAG,OAAO,CAGrE;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAmB5E;AAID,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,GAAiB,GAAG,oBAAoB,GAAG,IAAI,CAmBxF;AAgBD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,UAAU,CAAC,CA2BrB;AAYD,2EAA2E;AAC3E,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,IAAI,CAyC7E"}

package/dist/error-traces.js

@@ -0,0 +1,179 @@
+/**
+ * Server-side error tracing: capture, retention and opt-in sync.
+ *
+ * Capture: {@link captureError} turns a thrown value into a redacted row in
+ * `nodetool_error_traces` (see `@nodetool-ai/models` `recordErrorTrace`). It
+ * is fire-and-forget and never throws, so an error handler can call it
+ * without making its own failure worse.
+ *
+ * Retention: traces older than `NODETOOL_ERROR_TRACE_RETENTION_DAYS` (default
+ * 30) are pruned at startup and once a day.
+ *
+ * Sync: off unless both `NODETOOL_ERROR_TRACE_SYNC_URL` and
+ * `NODETOOL_ERROR_TRACE_SYNC_TOKEN` are set. Then locally captured traces are
+ * pushed every few minutes to that NodeTool server's `errorTraces.ingest`
+ * procedure, authenticated by the access token. The receiving server stores
+ * them under the token's user and redacts them again; on the hosted service
+ * that database is Supabase. A local install never holds database
+ * credentials for the cloud.
+ *
+ * Capture can be switched off entirely with `NODETOOL_ERROR_TRACES=0`.
+ */
+import { createLogger } from "@nodetool-ai/config";
+import { DEFAULT_ERROR_TRACE_RETENTION_DAYS, MAX_ERROR_TRACE_INGEST_BATCH, describeThrown, listUnsyncedErrorTraces, markErrorTracesSynced, pruneErrorTraces, recordErrorTrace } from "@nodetool-ai/models";
+import { getVersion } from "./routes/health.js";
+const log = createLogger("nodetool.websocket.error-traces");
+/** False when `NODETOOL_ERROR_TRACES` is `0`, `false` or `off`. */
+export function isErrorTracingEnabled(env = process.env) {
+    const value = env["NODETOOL_ERROR_TRACES"]?.trim().toLowerCase();
+    return value !== "0" && value !== "false" && value !== "off";
+}
+/** Record a redacted trace for `error`. Fire-and-forget; never throws. */
+export function captureError(error, opts) {
+    if (!isErrorTracingEnabled())
+        return;
+    try {
+        const { errorType, message, stack } = describeThrown(error);
+        void recordErrorTrace({
+            source: opts.source,
+            severity: opts.severity,
+            userId: opts.userId ?? null,
+            errorType,
+            message,
+            stack,
+            context: { runtime: "node", ...opts.context },
+            appVersion: getVersion(),
+            platform: process.platform
+        });
+    }
+    catch (captureFailure) {
+        // Capturing must never become a second failure inside an error handler.
+        log.warn("Error trace capture failed", { error: String(captureFailure) });
+    }
+}
+/** The sync target from the environment, or null when sync is off. */
+export function errorTraceSyncConfig(env = process.env) {
+    const url = env["NODETOOL_ERROR_TRACE_SYNC_URL"]?.trim();
+    const token = env["NODETOOL_ERROR_TRACE_SYNC_TOKEN"]?.trim();
+    if (!url || !token)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        log.warn("NODETOOL_ERROR_TRACE_SYNC_URL is not a URL; error trace sync is off");
+        return null;
+    }
+    // The token is a bearer credential; plain HTTP would expose it, except to
+    // a server on this machine.
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopback)) {
+        log.warn("NODETOOL_ERROR_TRACE_SYNC_URL must use https; error trace sync is off");
+        return null;
+    }
+    return { url: parsed.origin, token };
+}
+function toWire(trace) {
+    return {
+        source: trace.source,
+        severity: trace.severity,
+        error_type: trace.error_type,
+        message: trace.message,
+        stack: trace.stack,
+        context: trace.context,
+        app_version: trace.app_version,
+        platform: trace.platform,
+        created_at: trace.created_at
+    };
+}
+/**
+ * Push unsynced local traces in batches until none remain or a batch fails.
+ * `fetchImpl` is injectable for tests.
+ */
+export async function syncErrorTraces(config, fetchImpl = fetch) {
+    let pushed = 0;
+    for (;;) {
+        const batch = await listUnsyncedErrorTraces(MAX_ERROR_TRACE_INGEST_BATCH);
+        if (batch.length === 0)
+            return { pushed };
+        let response;
+        try {
+            response = await fetchImpl(`${config.url}/trpc/errorTraces.ingest`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${config.token}`
+                },
+                body: JSON.stringify({ traces: batch.map(toWire) }),
+                redirect: "error",
+                signal: AbortSignal.timeout(15_000)
+            });
+        }
+        catch (error) {
+            return { pushed, error: error instanceof Error ? error.message : String(error) };
+        }
+        if (!response.ok) {
+            return { pushed, error: `sync target answered HTTP ${response.status}` };
+        }
+        await markErrorTracesSynced(batch.map((trace) => trace.id));
+        pushed += batch.length;
+        if (batch.length < MAX_ERROR_TRACE_INGEST_BATCH)
+            return { pushed };
+    }
+}
+// ── Maintenance loop ─────────────────────────────────────────────────
+const DAY_MS = 24 * 60 * 60 * 1000;
+const SYNC_INTERVAL_MS = 5 * 60 * 1000;
+function retentionDays(env) {
+    const raw = Number(env["NODETOOL_ERROR_TRACE_RETENTION_DAYS"]);
+    return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_ERROR_TRACE_RETENTION_DAYS;
+}
+/** Start pruning, and syncing when configured. Returns a stop function. */
+export function startErrorTraceMaintenance(env = process.env) {
+    const prune = () => {
+        void pruneErrorTraces(retentionDays(env))
+            .then((removed) => {
+            if (removed > 0)
+                log.info("Pruned expired error traces", { removed });
+        })
+            .catch((error) => {
+            log.warn("Error trace pruning failed", { error: String(error) });
+        });
+    };
+    prune();
+    const timers = [setInterval(prune, DAY_MS)];
+    const config = errorTraceSyncConfig(env);
+    if (config) {
+        log.info("Error trace sync is on", { target: config.url });
+        let running = false;
+        const sync = () => {
+            if (running)
+                return;
+            running = true;
+            void syncErrorTraces(config)
+                .then((result) => {
+                if (result.error) {
+                    log.warn("Error trace sync stopped early", { ...result });
+                }
+                else if (result.pushed > 0) {
+                    log.info("Synced error traces", { pushed: result.pushed });
+                }
+            })
+                .catch((error) => {
+                log.warn("Error trace sync failed", { error: String(error) });
+            })
+                .finally(() => {
+                running = false;
+            });
+        };
+        timers.push(setInterval(sync, SYNC_INTERVAL_MS));
+    }
+    for (const timer of timers)
+        timer.unref?.();
+    return () => {
+        for (const timer of timers)
+            clearInterval(timer);
+    };
+}
+//# sourceMappingURL=error-traces.js.map

package/dist/error-traces.js.map

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

package/dist/example-workflows.d.ts

@@ -0,0 +1,20 @@
+interface ExampleWorkflowLoadOptions {
+    examplesDir?: string;
+    /** Fallback thumbnail directory when the sibling of examplesDir has no JPGs. */
+    examplesAssetsFallbackDir?: string;
+    metadataRoots?: string[];
+    metadataMaxDepth?: number;
+}
+/**
+ * Resolve the directory containing gallery thumbnail JPGs/PNGs for an examples dir.
+ * Prefer the sibling `assets/<package>` layout; fall back to bundled assets when
+ * examples are mounted elsewhere (common in Docker compose overrides).
+ */
+export declare function deriveExampleAssetsDir(examplesDir: string, fallbackAssetsDir?: string | null): string;
+/** Resolve a display name, slug, or filename to an on-disk example JSON path. */
+export declare function resolveExampleJsonPath(examplesDir: string, exampleRef: string): string | null;
+/** Load a full example workflow JSON (including graph) for workflow creation. */
+export declare function loadExampleGraph(packageName: string, exampleRef: string, options?: ExampleWorkflowLoadOptions): Record<string, unknown> | null;
+export declare function defaultExamplePackageName(options: ExampleWorkflowLoadOptions): string | null;
+export {};
+//# sourceMappingURL=example-workflows.d.ts.map

package/dist/example-workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-workflows.d.ts","sourceRoot":"","sources":["../src/example-workflows.ts"],"names":[],"mappings":"AAKA,UAAU,0BAA0B;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAaD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,MAAM,CAiBR;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAkDf;AAyCD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAahC;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,MAAM,GAAG,IAAI,CAKf"}

package/dist/example-workflows.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import nodePath from "node:path";
+import { loadPythonPackageMetadata } from "@nodetool-ai/node-sdk";
+import { isString } from "./lib/wire-values.js";
+function directoryHasGalleryThumbnails(dir) {
+    if (!existsSync(dir)) {
+        return false;
+    }
+    try {
+        return readdirSync(dir).some((file) => /\.(jpg|jpeg|png)$/i.test(file));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the directory containing gallery thumbnail JPGs/PNGs for an examples dir.
+ * Prefer the sibling `assets/<package>` layout; fall back to bundled assets when
+ * examples are mounted elsewhere (common in Docker compose overrides).
+ */
+export function deriveExampleAssetsDir(examplesDir, fallbackAssetsDir) {
+    const derived = nodePath.join(nodePath.dirname(nodePath.dirname(examplesDir)), "assets", nodePath.basename(examplesDir));
+    if (directoryHasGalleryThumbnails(derived)) {
+        return derived;
+    }
+    if (fallbackAssetsDir &&
+        existsSync(fallbackAssetsDir) &&
+        directoryHasGalleryThumbnails(fallbackAssetsDir)) {
+        return fallbackAssetsDir;
+    }
+    return derived;
+}
+/** Resolve a display name, slug, or filename to an on-disk example JSON path. */
+export function resolveExampleJsonPath(examplesDir, exampleRef) {
+    const ref = exampleRef.trim();
+    if (!ref) {
+        return null;
+    }
+    const directCandidates = ref.toLowerCase().endsWith(".json")
+        ? [nodePath.join(examplesDir, nodePath.basename(ref))]
+        : [
+            nodePath.join(examplesDir, `${ref}.json`),
+            nodePath.join(examplesDir, ref)
+        ];
+    for (const candidate of directCandidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    let files;
+    try {
+        files = readdirSync(examplesDir).filter((file) => file.toLowerCase().endsWith(".json"));
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (file === ref || file === `${ref}.json`) {
+            return nodePath.join(examplesDir, file);
+        }
+    }
+    for (const file of files) {
+        try {
+            const raw = readFileSync(nodePath.join(examplesDir, file), "utf8");
+            const parsed = JSON.parse(raw);
+            if (isString(parsed.name) && parsed.name === ref) {
+                return nodePath.join(examplesDir, file);
+            }
+            if (isString(parsed.id) && parsed.id === ref) {
+                return nodePath.join(examplesDir, file);
+            }
+        }
+        catch {
+            // skip invalid example files
+        }
+    }
+    return null;
+}
+function loadExampleGraphFromDir(examplesDir, exampleRef) {
+    const examplePath = resolveExampleJsonPath(examplesDir, exampleRef);
+    if (!examplePath) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(examplePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function loadExampleGraphFromPythonPackage(packageName, exampleRef, options) {
+    const loaded = loadPythonPackageMetadata({
+        roots: options.metadataRoots,
+        maxDepth: options.metadataMaxDepth
+    });
+    const pkg = loaded.packages.find((p) => p.name === packageName);
+    if (!pkg?.sourceFolder) {
+        return null;
+    }
+    const examplesDir = nodePath.join(pkg.sourceFolder, "nodetool", "examples", packageName);
+    return loadExampleGraphFromDir(examplesDir, exampleRef);
+}
+/** Load a full example workflow JSON (including graph) for workflow creation. */
+export function loadExampleGraph(packageName, exampleRef, options = {}) {
+    if (options.examplesDir && existsSync(options.examplesDir)) {
+        const fromDir = loadExampleGraphFromDir(options.examplesDir, exampleRef);
+        if (fromDir) {
+            return fromDir;
+        }
+    }
+    if (packageName) {
+        return loadExampleGraphFromPythonPackage(packageName, exampleRef, options);
+    }
+    return null;
+}
+export function defaultExamplePackageName(options) {
+    if (options.examplesDir && existsSync(options.examplesDir)) {
+        return nodePath.basename(options.examplesDir);
+    }
+    return null;
+}
+//# sourceMappingURL=example-workflows.js.map

package/dist/example-workflows.js.map

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