@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/traces/otlp.js

@@ -0,0 +1,84 @@
+/**
+ * OTLP/HTTP JSON (R7.2): the encoder of a batch of spans as `resourceSpans`, and the poster that
+ * delivers one to the collector's `/v1/traces`. Hand-built JSON, no OpenTelemetry SDK: the spans
+ * are mapped from records (`map.ts`), not timed from live code.
+ *
+ * Delivery never holds the log back: a `429`, a `5xx` or a lost connection is tried again three
+ * times with backoff, then the batch is dropped and logged (`trace_export_dropped`); any other
+ * answer drops it at once. Either way `post` resolves, and the projector acknowledges the rows,
+ * so a dead collector makes Postgres keep no WAL. The trace route (R7.5) re-reads any turn.
+ */
+import { RUNTIME_VERSION } from "../version.js";
+import { GENAI_SEMCONV } from "./map.js";
+export const DEFAULT_SERVICE_NAME = "nylorun";
+/** The instrumentation scope of every span. */
+const SCOPE = { name: "@nylorun/runtime", version: RUNTIME_VERSION };
+/** A batch of spans as an OTLP `ExportTraceServiceRequest` in JSON. */
+export function resourceSpans(resource, spans) {
+    const attributes = [];
+    for (const [key, value] of Object.entries(resource.attributes ?? {}))
+        if (key !== "service.name")
+            attributes.push({ key, value: { stringValue: value } });
+    attributes.unshift({ key: "service.name", value: { stringValue: resource.serviceName } });
+    attributes.push({ key: "nylorun.semconv.genai", value: { stringValue: GENAI_SEMCONV } });
+    return {
+        resourceSpans: [{ resource: { attributes }, scopeSpans: [{ scope: SCOPE, spans: [...spans] }] }],
+    };
+}
+export function createOtlpPoster(options) {
+    const send = options.fetch ?? fetch;
+    const retries = options.retries ?? 3;
+    const backoffMs = options.backoffMs ?? 500;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const log = options.log ?? (() => { });
+    return async (spans, signal) => {
+        if (spans.length === 0)
+            return "posted";
+        const body = JSON.stringify(resourceSpans(options.resource, spans));
+        let reason = "";
+        for (let attempt = 0; attempt <= retries; attempt += 1) {
+            if (attempt > 0 && !(await pause(backoffMs * 2 ** (attempt - 1), signal)))
+                break;
+            let status;
+            try {
+                const response = await send(options.url, {
+                    method: "POST",
+                    headers: { ...options.headers, "content-type": "application/json" },
+                    body,
+                    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+                });
+                status = response.status;
+                await response.body?.cancel().catch(() => undefined);
+            }
+            catch (error) {
+                reason = error instanceof Error ? error.message : String(error);
+                if (signal?.aborted)
+                    break;
+                continue;
+            }
+            if (status >= 200 && status < 300)
+                return "posted";
+            reason = `HTTP ${status}`;
+            if (status !== 429 && status < 500)
+                break;
+        }
+        log("trace_export_dropped", { spans: spans.length, reason });
+        return "dropped";
+    };
+}
+/** Waits `ms`; false when `signal` aborted first. */
+function pause(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/traces/projector.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The trace projector (R7.2, Q1): a second reader of the session log, beside the stream relay. It
+ * reads committed `session_events` from its own replication slot (`nylorun_trace_export`, on the
+ * relay's publication), maps each row to at most one span (`map.ts`), and posts them as OTLP to the
+ * operator's collector. It holds no state that changes a span, so a replay of its slot posts the
+ * same spans with the same ids. It never reads S2 (D48), and no turn waits for it.
+ *
+ * - **One process at a time.** The slot is the leader election, as for the relay: every process
+ *   running core runs a projector, and one reads.
+ * - **Batches** of up to 512 spans, or what came within 2 s, posted one at a time
+ *   (`otlp.ts`: retried, then dropped and logged).
+ * - **Acknowledged in commit order** once a transaction's spans are posted or dropped, so a dead
+ *   collector makes Postgres keep no WAL. A transaction with no span is acknowledged with the
+ *   rest. While the collector is slow, more than `maxQueuedSpans` waiting are dropped.
+ * - **Turns.** A bounded cache keeps each turn's trace (`turnTraceOf`) from its `command.message`;
+ *   a turn not in it (after a restart mid turn, or one evicted) reads its `command.message` once.
+ */
+import type { LiveEvent } from "@nylorun/core/contracts";
+import type { ChangeSource } from "../streams/relay/types.js";
+import type { TraceKey } from "./ids.js";
+import { type TraceContent } from "./map.js";
+import type { OtlpPoster } from "./otlp.js";
+/** The projector's replication slot. */
+export declare const TRACE_SLOT = "nylorun_trace_export";
+export interface TraceProjectorOptions {
+    readonly source: ChangeSource;
+    readonly post: OtlpPoster;
+    /** The Tenant's trace key (`traces/key.ts`). */
+    readonly key: () => Promise<TraceKey>;
+    /** The `command.message` that started turn `turnId`, or undefined when the log has none. */
+    readonly turnMessage: (sessionId: string, turnId: string) => Promise<LiveEvent | undefined>;
+    readonly content: TraceContent;
+    /** Spans per post. Default 512. */
+    readonly maxBatch?: number;
+    /** How long a span waits for its batch to fill. Default 2 s. */
+    readonly maxDelayMs?: number;
+    /** Spans waiting while a post is out, past which the waiting ones are dropped. Default 8192. */
+    readonly maxQueuedSpans?: number;
+    /** Turns whose trace is kept. Default 1024. */
+    readonly turnCacheSize?: number;
+    readonly log?: (message: string, fields?: Record<string, unknown>) => void;
+}
+export interface TraceProjector {
+    start(): void;
+    stop(): Promise<void>;
+    /** This process reads the slot, and what it has not acknowledged. */
+    status(): {
+        active: boolean;
+        pendingTxs: number;
+        pendingSpans: number;
+        confirmed: string | null;
+    };
+    /** Resolves once everything received is posted or dropped and acknowledged (tests, shutdown). */
+    idle(): Promise<void>;
+    /** How far the slot is behind, in bytes, when known. */
+    lag(): Promise<number | undefined>;
+}
+export declare function createTraceProjector(options: TraceProjectorOptions): TraceProjector;

package/dist/traces/projector.js

@@ -0,0 +1,200 @@
+import { spanOf, turnTraceOf } from "./map.js";
+/** The projector's replication slot. */
+export const TRACE_SLOT = "nylorun_trace_export";
+export function createTraceProjector(options) {
+    const { source, post } = options;
+    const log = options.log ?? (() => { });
+    const maxBatch = options.maxBatch ?? 512;
+    const maxDelayMs = options.maxDelayMs ?? 2000;
+    const maxQueued = options.maxQueuedSpans ?? 8192;
+    const cacheSize = options.turnCacheSize ?? 1024;
+    const turns = new Map();
+    const stopping = new AbortController();
+    /** Mapped transactions not yet posted, in commit order. */
+    let waiting = [];
+    let waitingSpans = 0;
+    /** Received transactions still being mapped, in commit order. */
+    let mapping = Promise.resolve();
+    let mappingCount = 0;
+    let posting;
+    let timer;
+    let active = false;
+    let confirmed = null;
+    /** Moves on with every loss of the source: work of an earlier activation is discarded. */
+    let activation = 0;
+    let idleWaiters = [];
+    function remember(key, trace) {
+        turns.delete(key);
+        turns.set(key, trace);
+        if (turns.size > cacheSize)
+            turns.delete(turns.keys().next().value);
+        return trace;
+    }
+    async function turnOf(row, settings) {
+        const turnId = row.turnId;
+        const cacheKey = `${row.sessionId}\u0000${turnId}`;
+        const ids = { tenantId: row.tenantId, sessionId: row.sessionId, turnId };
+        if (row.type === "command.message")
+            return remember(cacheKey, turnTraceOf(settings, ids, row));
+        const known = turns.get(cacheKey);
+        if (known)
+            return remember(cacheKey, known);
+        return remember(cacheKey, turnTraceOf(settings, ids, await options.turnMessage(row.sessionId, turnId)));
+    }
+    async function spansOf(tx) {
+        const spans = [];
+        if (tx.rows.length === 0)
+            return spans;
+        const settings = { key: await options.key(), content: options.content };
+        for (const record of tx.rows) {
+            const row = record.body;
+            if (!row || typeof row !== "object" || row.turnId == null)
+                continue;
+            const span = spanOf(row, await turnOf(row, settings), settings);
+            if (span)
+                spans.push(span);
+        }
+        return spans;
+    }
+    function onTx(tx) {
+        const of = activation;
+        mappingCount += 1;
+        mapping = mapping.then(async () => {
+            try {
+                let spans;
+                for (;;) {
+                    try {
+                        spans = await spansOf(tx);
+                        break;
+                    }
+                    catch (error) {
+                        // The key or a turn's message could not be read (Postgres away): try again, in order.
+                        if (of !== activation || stopping.signal.aborted)
+                            return;
+                        log("trace_projector_retry", { message: error instanceof Error ? error.message : String(error) });
+                        await new Promise((resolve) => setTimeout(resolve, 1000));
+                    }
+                }
+                if (of !== activation)
+                    return;
+                waiting.push({ endLsn: tx.endLsn, spans });
+                waitingSpans += spans.length;
+                if (posting && waitingSpans > maxQueued) {
+                    // The collector is slower than the log: drop what waits, keep its place to acknowledge.
+                    log("trace_export_dropped", { spans: waitingSpans, reason: "queue full" });
+                    for (const pending of waiting)
+                        pending.spans = [];
+                    waitingSpans = 0;
+                }
+                schedule();
+            }
+            finally {
+                mappingCount -= 1;
+                settle();
+            }
+        });
+    }
+    function schedule() {
+        if (posting || waiting.length === 0)
+            return;
+        // Nothing to post: acknowledge at once.
+        if (waitingSpans === 0 || waitingSpans >= maxBatch || stopping.signal.aborted)
+            return void flush();
+        timer ??= setTimeout(() => {
+            timer = undefined;
+            flush();
+        }, maxDelayMs);
+    }
+    function flush() {
+        if (posting || waiting.length === 0)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = undefined;
+        const of = activation;
+        const batch = waiting;
+        waiting = [];
+        waitingSpans = 0;
+        posting = (async () => {
+            const spans = batch.flatMap((tx) => tx.spans);
+            // A post a shutdown cut short is not the collector's failure: those rows go again.
+            let cut = false;
+            for (let at = 0; at < spans.length; at += maxBatch)
+                if ((await post(spans.slice(at, at + maxBatch), stopping.signal)) === "dropped" && stopping.signal.aborted)
+                    cut = true;
+            // Posted or dropped: the rows are done. A source lost meanwhile replays them anyway.
+            if (of === activation && !cut) {
+                confirmed = batch.at(-1).endLsn;
+                source.acknowledge(confirmed);
+            }
+        })().finally(() => {
+            posting = undefined;
+            schedule();
+            settle();
+        });
+    }
+    function settle() {
+        if (posting || mappingCount > 0 || waiting.length > 0)
+            return;
+        const waiters = idleWaiters;
+        idleWaiters = [];
+        for (const wake of waiters)
+            wake();
+    }
+    return {
+        start() {
+            source.start({
+                onActive({ fresh }) {
+                    active = true;
+                    log("trace projector active", { fresh });
+                    // A fresh slot has nothing to reconcile: it exports from now on.
+                    if (fresh)
+                        void source.reconciled().catch(() => undefined);
+                },
+                onTx,
+                onKeepalive(lsn) {
+                    // Caught up: let the slot move past WAL that holds none of our rows.
+                    if (posting || mappingCount > 0 || waiting.length > 0)
+                        return undefined;
+                    confirmed = lsn;
+                    return lsn;
+                },
+                onInactive(error) {
+                    active = false;
+                    activation += 1;
+                    // The slot replays everything not acknowledged; what waits is dropped.
+                    waiting = [];
+                    waitingSpans = 0;
+                    if (timer)
+                        clearTimeout(timer);
+                    timer = undefined;
+                    settle();
+                    if (error)
+                        log("trace projector lost its source; retrying", {
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                },
+            });
+        },
+        async stop() {
+            // Post what is mapped (each post gives up at once), then stop reading.
+            stopping.abort();
+            await mapping.catch(() => undefined);
+            flush();
+            await posting?.catch(() => undefined);
+            await source.stop();
+        },
+        status: () => ({
+            active,
+            pendingTxs: waiting.length + mappingCount,
+            pendingSpans: waitingSpans,
+            confirmed,
+        }),
+        idle() {
+            if (!posting && mappingCount === 0 && waiting.length === 0)
+                return Promise.resolve();
+            return new Promise((resolve) => idleWaiters.push(resolve));
+        },
+        lag: async () => (await source.lag?.()) ?? undefined,
+    };
+}

package/dist/traces/read.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The trace route's spans (R7.5): a turn's log rows mapped by the same `spanOf` the projector
+ * posts with, under the installation's resource and content opt-ins, so the route and the
+ * exporter agree span for span.
+ */
+import type { LiveEvent } from "@nylorun/core/contracts";
+import type { TenantContext } from "../tenant/context.js";
+import { type OtlpSpan } from "./map.js";
+/** Turn `turnId`'s spans as an OTLP `ExportTraceServiceRequest`, from its rows in log order. */
+export declare function turnTrace(ctx: TenantContext, sessionId: string, turnId: string, events: readonly LiveEvent[]): Promise<{
+    resourceSpans: {
+        resource: {
+            attributes: import("./map.js").OtlpKeyValue[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            spans: OtlpSpan[];
+        }[];
+    }[];
+}>;

package/dist/traces/read.js

@@ -0,0 +1,16 @@
+import { traceKey } from "./key.js";
+import { spanOf, turnTraceOf } from "./map.js";
+import { DEFAULT_SERVICE_NAME, resourceSpans } from "./otlp.js";
+/** Turn `turnId`'s spans as an OTLP `ExportTraceServiceRequest`, from its rows in log order. */
+export async function turnTrace(ctx, sessionId, turnId, events) {
+    const settings = { key: await traceKey(ctx.store), content: ctx.traces?.content ?? new Set() };
+    const message = events.find((event) => event.type === "command.message");
+    const turn = turnTraceOf(settings, { tenantId: ctx.store.tenantId, sessionId, turnId }, message);
+    const spans = [];
+    for (const event of events) {
+        const span = spanOf(event, turn, settings);
+        if (span)
+            spans.push(span);
+    }
+    return resourceSpans(ctx.traces?.resource ?? { serviceName: DEFAULT_SERVICE_NAME }, spans);
+}

package/dist/vault/coverage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What an agent asks of a session's vaults (`POST /v1/tenant/credential-coverage`): each remote
+ * MCP server and each HTTP tool with a `credential`, of the agent, the agents it uses as tools and
+ * the agents of a flow. `VaultService.coverage` decides what a session would send for each, as
+ * `authorize` decides it for a call.
+ */
+import { type AgentManifest, type WorkflowManifest } from "@nylorun/core/define";
+/** One URL a manifest names that a vault credential may be bound to. */
+export interface CredentialNeed {
+    readonly kind: "mcp" | "http";
+    /** The declaring agent; absent for the manifest's own agent. */
+    readonly agentId?: string;
+    /** A flow's HTTP stage or HTTP verifier: its stage key. */
+    readonly stage?: string;
+    /** The MCP server's name, or the HTTP tool's (or stage's) name. */
+    readonly name: string;
+    /** What a credential selection names: the server's name, or the HTTP tool's `credential`. */
+    readonly serverName: string;
+    /** The URL as the manifest names it. */
+    readonly url: string;
+}
+/**
+ * The manifest's needs: its own agent's, then each agent it uses as a tool, then a flow's
+ * stages and agents (nested flow agents under their stage keys). Repeats are dropped.
+ */
+export declare function credentialNeeds(manifest: AgentManifest | WorkflowManifest): CredentialNeed[];

package/dist/vault/coverage.js

@@ -0,0 +1,62 @@
+/**
+ * What an agent asks of a session's vaults (`POST /v1/tenant/credential-coverage`): each remote
+ * MCP server and each HTTP tool with a `credential`, of the agent, the agents it uses as tools and
+ * the agents of a flow. `VaultService.coverage` decides what a session would send for each, as
+ * `authorize` decides it for a call.
+ */
+import { delegatesOf, flowDelegatesOf, forEachFlowNode, isWorkflowManifest, } from "@nylorun/core/define";
+/**
+ * The manifest's needs: its own agent's, then each agent it uses as a tool, then a flow's
+ * stages and agents (nested flow agents under their stage keys). Repeats are dropped.
+ */
+export function credentialNeeds(manifest) {
+    const needs = new Map();
+    const add = (need) => {
+        const key = JSON.stringify([need.kind, need.agentId, need.stage, need.name, need.serverName, need.url]);
+        if (!needs.has(key))
+            needs.set(key, need);
+    };
+    const owner = (agentId) => (agentId === undefined ? {} : { agentId });
+    const agent = (manifest, agentId) => {
+        for (const tool of manifest.tools ?? [])
+            if (tool.http?.credential !== undefined)
+                add({
+                    kind: "http",
+                    ...owner(agentId),
+                    name: tool.name,
+                    serverName: tool.http.credential,
+                    url: tool.http.url,
+                });
+        for (const server of Object.values(manifest.mcpServers ?? {}))
+            add({ kind: "mcp", ...owner(agentId), name: server.name, serverName: server.name, url: server.url });
+        for (const child of delegatesOf(manifest))
+            agent(child.manifest, child.manifest.id);
+        for (const child of flowDelegatesOf(manifest))
+            flow(child.manifest, child.manifest.id);
+    };
+    const flow = (manifest, prefix) => {
+        forEachFlowNode(manifest.root, ({ node, key }) => {
+            const http = "http" in node ? node.http : "tool" in node ? node.tool.http : undefined;
+            if (http?.credential === undefined)
+                return;
+            add({
+                kind: "http",
+                stage: key,
+                name: "tool" in node ? node.tool.name : key,
+                serverName: http.credential,
+                url: http.url,
+            });
+        }, { prefix });
+        for (const [id, embedded] of Object.entries(manifest.agents)) {
+            if (isWorkflowManifest(embedded))
+                flow(embedded, prefix ? `${prefix}/${id}` : id);
+            else
+                agent(embedded, id);
+        }
+    };
+    if (isWorkflowManifest(manifest))
+        flow(manifest, "");
+    else
+        agent(manifest);
+    return [...needs.values()];
+}

package/dist/vault/error.d.ts

@@ -1,4 +1,14 @@
 export declare class VaultError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** The rejection's code and details, when the answer carries one (`credential_conflict`). */
+    readonly rejection: {
+        readonly code?: string;
+        readonly details?: Record<string, unknown>;
+    };
+    constructor(status: number, message: string, 
+    /** The rejection's code and details, when the answer carries one (`credential_conflict`). */
+    rejection?: {
+        readonly code?: string;
+        readonly details?: Record<string, unknown>;
+    });
 }

package/dist/vault/error.js

@@ -1,7 +1,11 @@
 export class VaultError extends Error {
     status;
-    constructor(status, message) {
+    rejection;
+    constructor(status, message, 
+    /** The rejection's code and details, when the answer carries one (`credential_conflict`). */
+    rejection = {}) {
         super(message);
         this.status = status;
+        this.rejection = rejection;
     }
 }

package/dist/vault/host-model.d.ts

@@ -17,7 +17,10 @@ export declare class HostModelVault {
     private readonly store;
     private readonly kek;
     constructor(options: HostModelVaultOptions);
-    /** Reads the active host model secret. Decrypts after the read commits. */
+    /**
+     * Reads the active host model secret, with the inputs the operator added to catalog models
+     * (protocol 12). Decrypts after the read commits.
+     */
     readHostModel(): Promise<HostModelSecret | undefined>;
     /** Replaces the active host model's secret, keeping its binding. */
     updateHostCredential(credential: {

package/dist/vault/host-model.js

@@ -1,3 +1,4 @@
+import { readAddedInputs } from "../tenant/model-setting.js";
 import { encryptSecret } from "./crypto.js";
 import { VaultError } from "./error.js";
 import { activeHostCredentialRow, HOST_VAULT_ID, hostModelAad, modelBinding, readHostPayload, } from "./service.js";
@@ -8,9 +9,15 @@ export class HostModelVault {
         this.store = options.store;
         this.kek = options.kek;
     }
-    /** Reads the active host model secret. Decrypts after the read commits. */
+    /**
+     * Reads the active host model secret, with the inputs the operator added to catalog models
+     * (protocol 12). Decrypts after the read commits.
+     */
     async readHostModel() {
-        const row = await this.store.tx((t) => activeHostCredentialRow(t));
+        const { row, addedInputs } = await this.store.tx(async (t) => ({
+            row: await activeHostCredentialRow(t),
+            addedInputs: await readAddedInputs(t),
+        }));
         if (!row)
             return undefined;
         const binding = modelBinding(row);
@@ -27,6 +34,7 @@ export class HostModelVault {
             model: binding.model,
             ...(binding.baseUrl ? { baseUrl: binding.baseUrl } : {}),
             ...(binding.settings ? { settings: binding.settings } : {}),
+            addedInputs,
             authType: binding.authType,
             credential,
         };