nexus-ai-pro 2.0.0 → 2.2.0

package/dist-cjs/router/auto-router.js

@@ -3,38 +3,140 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutoRouter = void 0;
 exports.routeDirectModel = routeDirectModel;
 const registry_js_1 = require("../models/registry.js");
+const PLAN_LIMIT = 16;
+const BOOLEAN_CAPABILITIES = ['streaming', 'toolCalling', 'structuredOutputs', 'jsonMode', 'reasoning'];
 class AutoRouter {
+    plans = new Map();
+    patterns = new Map();
+    registryIds = new WeakMap();
     route(ctx) {
-        const strategy = ctx.config.routing?.strategy || 'quality';
-        const candidates = this.withoutOpenCircuits(this.getCandidates(ctx), ctx).map((candidate) => ({
-            ...candidate,
-            score: this.score(candidate.model, strategy, ctx.config, ctx.providers.get(candidate.providerName)?.info?.isLocal === true) +
-                candidate.weight +
-                this.healthScore(candidate.providerName, ctx),
-            reason: `auto route by ${strategy} score`,
-        }));
-        candidates.sort((a, b) => b.score - a.score);
-        const winner = candidates[0];
+        const plan = this.plan(ctx);
+        const ranked = this.rank(plan, ctx);
+        const winner = ranked[0];
         if (!winner) {
             throw new Error('No configured providers are available for routing');
         }
         return {
             providerName: winner.providerName,
             model: winner.model,
-            reason: `${winner.reason}: ${winner.model}`,
-            fallbacks: candidates.slice(1).map((c) => ({ providerName: c.providerName, model: c.model })),
+            reason: `auto route by ${plan.strategy} score: ${winner.model}`,
+            fallbacks: ranked.slice(1).map((candidate) => candidate.attempt),
         };
     }
-    withoutOpenCircuits(candidates, ctx) {
-        if (!ctx.openCircuits?.length)
-            return candidates;
-        const open = new Set(ctx.openCircuits);
-        const remaining = candidates.filter((candidate) => !open.has(candidate.providerName));
-        return remaining.length > 0 ? remaining : candidates;
+    get planCount() {
+        return this.plans.size;
+    }
+    plan(ctx) {
+        const key = this.planKey(ctx);
+        const cached = this.plans.get(key);
+        if (cached) {
+            this.plans.delete(key);
+            this.plans.set(key, cached);
+            return cached;
+        }
+        const plan = this.buildPlan(ctx);
+        this.plans.set(key, plan);
+        if (this.plans.size > PLAN_LIMIT)
+            this.plans.delete(this.plans.keys().next().value);
+        return plan;
+    }
+    planKey(ctx) {
+        const routing = ctx.config.routing;
+        const models = ctx.config.models;
+        const providers = [];
+        for (const [name, provider] of ctx.providers)
+            providers.push(`${name}${provider.info?.isLocal === true ? '+local' : ''}`);
+        return JSON.stringify([
+            routing?.strategy ?? 'quality',
+            routing?.candidateModels ?? null,
+            routing?.modelPreferences ?? null,
+            routing?.allowModels ?? null,
+            routing?.denyModels ?? null,
+            normalizedRequirements(routing?.requiredCapabilities),
+            models?.includeDefaults ?? null,
+            models?.aliases ?? null,
+            models?.registry ? this.registryId(models.registry) : 0,
+            providers,
+        ]);
     }
-    getCandidates(ctx) {
+    registryId(registry) {
+        let id = this.registryIds.get(registry);
+        if (id === undefined) {
+            id = this.registryIds.get(this.registryIds) ?? 1;
+            this.registryIds.set(registry, id);
+            this.registryIds.set(this.registryIds, id + 1);
+        }
+        return id;
+    }
+    buildPlan(ctx) {
+        const strategy = ctx.config.routing?.strategy || 'quality';
+        const registry = (0, registry_js_1.getModelRegistry)(ctx.config);
+        const requirements = compileRequirements(ctx.config.routing?.requiredCapabilities);
+        const candidates = this.getCandidates(ctx, registry, requirements);
+        const planned = candidates.map((candidate, index) => ({
+            providerName: candidate.providerName,
+            model: candidate.model,
+            base: this.score(candidate.model, strategy, registry, ctx.providers.get(candidate.providerName)?.info?.isLocal === true) + candidate.weight,
+            index,
+            attempt: Object.freeze({ providerName: candidate.providerName, model: candidate.model }),
+        }));
+        const ranked = [...planned].sort(byScore);
+        const byProvider = new Map();
+        for (const candidate of ranked) {
+            const list = byProvider.get(candidate.providerName);
+            if (list)
+                list.push(candidate);
+            else
+                byProvider.set(candidate.providerName, [candidate]);
+        }
+        return { strategy, ranked, byProvider };
+    }
+    rank(plan, ctx) {
+        let excluded;
+        if (ctx.openCircuits?.length) {
+            const open = new Set(ctx.openCircuits);
+            if (plan.ranked.some((candidate) => !open.has(candidate.providerName)))
+                excluded = open;
+        }
+        const offsets = this.healthOffsets(ctx);
+        if (!offsets) {
+            return excluded ? plan.ranked.filter((candidate) => !excluded.has(candidate.providerName)) : plan.ranked;
+        }
+        const lists = [];
+        let total = 0;
+        for (const [providerName, list] of plan.byProvider) {
+            if (excluded?.has(providerName))
+                continue;
+            lists.push({ list, offset: offsets.get(providerName) ?? 0, at: 0 });
+            total += list.length;
+        }
+        const merged = new Array(total);
+        for (let position = 0; position < total; position += 1) {
+            let best = -1;
+            let bestScore = Number.NEGATIVE_INFINITY;
+            let bestIndex = Number.POSITIVE_INFINITY;
+            for (let which = 0; which < lists.length; which += 1) {
+                const head = lists[which];
+                const candidate = head.list[head.at];
+                if (!candidate)
+                    continue;
+                const score = candidate.base + head.offset;
+                if (score > bestScore || (score === bestScore && candidate.index < bestIndex)) {
+                    best = which;
+                    bestScore = score;
+                    bestIndex = candidate.index;
+                }
+            }
+            const chosen = lists[best];
+            merged[position] = chosen.list[chosen.at];
+            chosen.at += 1;
+        }
+        return merged;
+    }
+    getCandidates(ctx, registry, requirements) {
         const candidates = [];
         const configuredModels = ctx.config.routing?.candidateModels;
+        const passes = (model) => !requirements || this.matchesRequirements(model, registry, requirements);
         if (configuredModels?.length) {
             for (const model of configuredModels) {
                 const resolved = (0, registry_js_1.resolveModel)(model, ctx.config);
@@ -43,23 +145,19 @@ class AutoRouter {
                     candidates.push({ providerName, model: resolved.model, weight: 0 });
                 }
             }
-            return candidates.filter((candidate) => this.matchesRequirements(candidate.model, ctx.config));
+            return candidates.filter((candidate) => passes(candidate.model));
         }
         const preferences = ctx.config.routing?.modelPreferences?.[ctx.config.routing?.strategy || 'quality'];
         for (const providerName of ctx.providers.keys()) {
-            const preferred = this.preferencesForProvider(providerName, preferences, ctx.config);
+            const preferred = this.preferencesForProvider(providerName, preferences, ctx.config, registry);
             if (preferred.length) {
                 candidates.push(...preferred);
             }
         }
-        return candidates.filter((candidate) => {
-            return this.isAllowed(candidate.model, ctx.config) && this.matchesRequirements(candidate.model, ctx.config);
-        });
+        return candidates.filter((candidate) => this.isAllowed(candidate.model, ctx.config) && passes(candidate.model));
     }
-    score(model, strategy, config, providerIsLocal = false) {
-        const registry = (0, registry_js_1.getModelRegistry)(config);
-        const normalized = model.startsWith('ollama/') ? model.slice(7) : model;
-        const caps = registry[model] || registry[normalized] || this.localFallbackCapabilities(model);
+    score(model, strategy, registry, providerIsLocal = false) {
+        const caps = this.capabilitiesOf(model, registry);
         if (strategy === 'privacy')
             return providerIsLocal || isLocalModel(model) ? 100 : 30;
         if (strategy === 'speed')
@@ -68,6 +166,10 @@ class AutoRouter {
             return this.costScore(model, caps);
         return this.qualityScore(model, caps);
     }
+    capabilitiesOf(model, registry) {
+        const normalized = model.startsWith('ollama/') ? model.slice(7) : model;
+        return registry[model] || registry[normalized] || this.localFallbackCapabilities(model);
+    }
     localFallbackCapabilities(model) {
         return {
             inputModalities: ['text'],
@@ -113,7 +215,7 @@ class AutoRouter {
             return 65;
         return Math.min(85, caps.maxContextTokens / 2000);
     }
-    preferencesForProvider(providerName, preferences, config) {
+    preferencesForProvider(providerName, preferences, config, registry) {
         if (preferences?.length) {
             return preferences
                 .map((preference) => typeof preference === 'string'
@@ -132,7 +234,7 @@ class AutoRouter {
         const registryModels = (0, registry_js_1.listModelsForProvider)(providerName, config);
         if (registryModels.length) {
             return registryModels
-                .filter((model) => this.isProviderRunnable(providerName, model, config))
+                .filter((model) => this.isProviderRunnable(providerName, model, registry))
                 .map((model) => ({ providerName, model, weight: 0 }));
         }
         if (providerName === 'ollama') {
@@ -173,52 +275,44 @@ class AutoRouter {
             return false;
         return !deny.some((entry) => this.matchesModelPattern(model, entry));
     }
-    matchesRequirements(model, config) {
-        const requirements = config.routing?.requiredCapabilities;
-        if (!requirements)
-            return true;
-        const registry = (0, registry_js_1.getModelRegistry)(config);
-        const normalized = model.startsWith('ollama/') ? model.slice(7) : model;
-        const caps = registry[model] || registry[normalized] || this.localFallbackCapabilities(model);
-        if (requirements.streaming !== undefined && caps.streaming !== requirements.streaming)
-            return false;
-        if (requirements.toolCalling !== undefined && caps.toolCalling !== requirements.toolCalling)
-            return false;
-        if (requirements.structuredOutputs !== undefined && caps.structuredOutputs !== requirements.structuredOutputs)
+    matchesRequirements(model, registry, requirements) {
+        const caps = this.capabilitiesOf(model, registry);
+        const { mustBe, mustNotBe } = capabilityMasks(caps);
+        if ((mustBe & requirements.mustBe) !== requirements.mustBe)
             return false;
-        if (requirements.jsonMode !== undefined && caps.jsonMode !== requirements.jsonMode)
+        if ((mustNotBe & requirements.mustNotBe) !== requirements.mustNotBe)
             return false;
-        if (requirements.reasoning !== undefined && Boolean(caps.reasoning) !== requirements.reasoning)
+        const source = requirements.source;
+        if (source.minContextTokens && caps.maxContextTokens < source.minContextTokens)
             return false;
-        if (requirements.minContextTokens && caps.maxContextTokens < requirements.minContextTokens)
+        if (source.maxInputCostPer1k !== undefined && caps.costPer1kInput > source.maxInputCostPer1k)
             return false;
-        if (requirements.maxInputCostPer1k !== undefined && caps.costPer1kInput > requirements.maxInputCostPer1k)
+        if (source.maxOutputCostPer1k !== undefined && caps.costPer1kOutput > source.maxOutputCostPer1k)
             return false;
-        if (requirements.maxOutputCostPer1k !== undefined && caps.costPer1kOutput > requirements.maxOutputCostPer1k)
+        if (source.statuses?.length && caps.status && !source.statuses.includes(caps.status))
             return false;
-        if (requirements.statuses?.length && caps.status && !requirements.statuses.includes(caps.status))
+        if (source.inputModalities?.some((modality) => !caps.inputModalities.includes(modality)))
             return false;
-        if (requirements.inputModalities?.some((modality) => !caps.inputModalities.includes(modality)))
-            return false;
-        if (requirements.outputModalities?.some((modality) => !caps.outputModalities.includes(modality)))
+        if (source.outputModalities?.some((modality) => !caps.outputModalities.includes(modality)))
             return false;
         return true;
     }
     matchesModelPattern(model, pattern) {
         if (pattern === model)
             return true;
-        if (!pattern.includes('*'))
-            return false;
-        const regex = new RegExp(`^${pattern
-            .split('*')
-            .map((part) => {
-            return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        })
-            .join('.*')}$`);
-        return regex.test(model);
+        let regex = this.patterns.get(pattern);
+        if (regex === undefined) {
+            regex = pattern.includes('*')
+                ? new RegExp(`^${pattern
+                    .split('*')
+                    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+                    .join('.*')}$`)
+                : null;
+            this.patterns.set(pattern, regex);
+        }
+        return regex ? regex.test(model) : false;
     }
-    isProviderRunnable(providerName, model, config) {
-        const registry = (0, registry_js_1.getModelRegistry)(config);
+    isProviderRunnable(providerName, model, registry) {
         const caps = registry[model];
         if (!caps?.endpoints)
             return true;
@@ -230,16 +324,55 @@ class AutoRouter {
             return caps.endpoints.includes('generateContent');
         return true;
     }
-    healthScore(providerName, ctx) {
+    healthOffsets(ctx) {
         if (!ctx.config.health?.enabled || !ctx.health?.length)
-            return 0;
-        const snapshot = ctx.health.find((item) => item.providerName === providerName);
-        if (!snapshot)
-            return 0;
-        return snapshot.healthy ? snapshot.score / 10 : -100;
+            return undefined;
+        const offsets = new Map();
+        for (const snapshot of ctx.health) {
+            if (offsets.has(snapshot.providerName))
+                continue;
+            offsets.set(snapshot.providerName, snapshot.healthy ? snapshot.score / 10 : -100);
+        }
+        return offsets;
     }
 }
 exports.AutoRouter = AutoRouter;
+function compileRequirements(requirements) {
+    if (!requirements)
+        return undefined;
+    let mustBe = 0;
+    let mustNotBe = 0;
+    BOOLEAN_CAPABILITIES.forEach((name, bit) => {
+        const wanted = requirements[name];
+        if (wanted === true)
+            mustBe |= 1 << bit;
+        else if (wanted === false)
+            mustNotBe |= 1 << bit;
+    });
+    return { mustBe, mustNotBe, source: requirements };
+}
+function capabilityMasks(caps) {
+    let mustBe = 0;
+    let mustNotBe = 0;
+    BOOLEAN_CAPABILITIES.forEach((name, bit) => {
+        const value = name === 'reasoning' ? Boolean(caps.reasoning) : caps[name];
+        if (value === true)
+            mustBe |= 1 << bit;
+        else if (value === false)
+            mustNotBe |= 1 << bit;
+    });
+    return { mustBe, mustNotBe };
+}
+function normalizedRequirements(requirements) {
+    if (!requirements)
+        return null;
+    return Object.keys(requirements)
+        .sort()
+        .map((key) => [key, requirements[key]]);
+}
+function byScore(a, b) {
+    return b.base - a.base || a.index - b.index;
+}
 function isLocalModel(model) {
     return (model.startsWith('ollama/') ||
         model.startsWith('lmstudio/') ||

package/dist-cjs/server/assistant.d.ts

@@ -1,3 +1,4 @@
+import type { GraphStreamProjection } from '../types/graph.js';
 import type { AssistantRunContext, ServerAssistant } from '../types/server.js';
 /**
  * The part of a compiled graph the adapter uses.
@@ -11,11 +12,15 @@ export interface GraphLike {
         threadId?: string;
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
+        tenantId?: string;
+        control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** Answers an interrupt and continues the thread. */
     resume(threadId: string, value: unknown, options: {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
+        tenantId?: string;
+        control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** The thread's checkpoint, at its latest step or at one given. */
     state(threadId: string, step?: number): Promise<{
@@ -28,18 +33,56 @@ export interface GraphLike {
     continue?(threadId: string, options: {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
+        tenantId?: string;
+        control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** Writes values into a thread's state, which is how a rollback is applied. */
     updateState?(threadId: string, values: Record<string, unknown>, options?: {
         asNode?: string;
     }): Promise<unknown>;
+    /** Runs an input as a stream of typed events. Used when the assistant serves `events`. */
+    events?(input: unknown, options: GraphEventOptionsLike): GraphEventsLike;
+    /** Like `events()`, answering an interrupt. */
+    resumeEvents?(threadId: string, value: unknown, options: GraphEventOptionsLike): GraphEventsLike;
+    /** Like `events()`, continuing a thread from its latest checkpoint. */
+    continueEvents?(threadId: string, options: GraphEventOptionsLike): GraphEventsLike;
 }
+/** The options of a graph's `events()` the adapter passes. */
+type GraphEventOptionsLike = {
+    threadId?: string;
+    tenantId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    control?: DrainSwitch;
+    include?: GraphStreamProjection[];
+};
+/** A graph's event stream, as the adapter reads it: the events, then the run's result. */
+type GraphEventsLike = AsyncIterable<unknown> & {
+    result: Promise<{
+        status: string;
+        state: unknown;
+        interrupt?: unknown;
+        interrupts?: unknown[];
+    }>;
+};
+/** Asks a graph to stop after its current superstep. A graph's `RunControl` has this shape. */
+type DrainSwitch = {
+    readonly draining: boolean;
+    readonly reason?: string;
+};
 /** Options for `graphAssistant()`. */
 export interface GraphAssistantOptions {
     /** What the assistant is, reported by the assistants endpoint. */
     description?: string;
     /** Metadata recorded on every checkpoint the server's runs create. */
     metadata?: Record<string, unknown>;
+    /**
+     * Records these projections of the graph's event stream on each run, such as `messages` and
+     * `tools`, so a client following the run sees model output and tool calls as they happen. The
+     * run's last event still carries its state and any question, as without it. Defaults to none: one
+     * event per superstep.
+     */
+    events?: GraphStreamProjection[];
 }
 /**
  * Serves a compiled graph as an assistant.
@@ -61,3 +104,4 @@ export declare function graphAssistant(graph: GraphLike, options?: GraphAssistan
 export declare function functionAssistant(run: (input: unknown, context: AssistantRunContext) => AsyncIterable<unknown> | Promise<unknown> | unknown, options?: {
     description?: string;
 }): ServerAssistant;
+export {};

package/dist-cjs/server/assistant.js

@@ -3,19 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.graphAssistant = graphAssistant;
 exports.functionAssistant = functionAssistant;
 function graphAssistant(graph, options = {}) {
+    const projections = options.events?.length ? options.events : undefined;
+    const eventOptions = (context, threadId) => ({
+        ...(threadId ? { threadId } : {}),
+        signal: context.signal,
+        metadata: { ...options.metadata, runId: context.runId },
+        ...tenantOf(context),
+        ...(context.control ? { control: context.control } : {}),
+        include: [...(projections ?? []), 'values'],
+    });
     return {
         description: options.description,
         stream(input, context) {
+            if (projections && graph.events) {
+                return withResult(graph.events(input ?? {}, eventOptions(context, context.threadId)));
+            }
             return graph.stream(input ?? {}, {
                 threadId: context.threadId,
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
+                ...(context.control ? { control: context.control } : {}),
             });
         },
         resume(threadId, value, context) {
+            if (projections && graph.resumeEvents) {
+                return withResult(graph.resumeEvents(threadId, value, eventOptions(context)));
+            }
             return graph.resume(threadId, value, {
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
+                ...(context.control ? { control: context.control } : {}),
             });
         },
         async state(threadId) {
@@ -33,9 +52,13 @@ function graphAssistant(graph, options = {}) {
             if (checkpoint.status !== 'running' && checkpoint.status !== 'failed' && checkpoint.status !== 'interrupted') {
                 return undefined;
             }
+            if (projections && graph.continueEvents)
+                return withResult(graph.continueEvents(threadId, eventOptions(context)));
             return graph.continue(threadId, {
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
+                ...(context.control ? { control: context.control } : {}),
             });
         },
         async restore(threadId, step) {
@@ -61,3 +84,19 @@ function functionAssistant(run, options = {}) {
         },
     };
 }
+function tenantOf(context) {
+    const tenantId = context.principal?.tenantId;
+    return tenantId ? { tenantId } : {};
+}
+async function* withResult(events) {
+    for await (const event of events)
+        yield event;
+    const result = await events.result;
+    yield {
+        type: result.status === 'awaiting_input' ? 'interrupt' : 'done',
+        status: result.status,
+        state: result.state,
+        ...(result.interrupt === undefined ? {} : { interrupt: result.interrupt }),
+        ...(result.interrupts === undefined ? {} : { interrupts: result.interrupts }),
+    };
+}

package/dist-cjs/server/errors.d.ts

@@ -32,6 +32,18 @@ export declare class ForbiddenError extends ServerError {
     /** The scope the route required. */
     scope: string);
 }
+/**
+ * Thrown by an assistant to hand its run to another worker while this replica drains: the server puts
+ * the run back on the queue as its next attempt instead of failing it. A function assistant checks
+ * `context.control?.draining` between its own steps, saves where it got with `context.saveProgress()`,
+ * and throws this; the next worker reads `context.progress`. Thrown when the replica is not draining,
+ * it fails the run like any error.
+ */
+export declare class RunHandOffError extends Error {
+    /** Always `RUN_HANDED_OFF`. */
+    readonly code = "RUN_HANDED_OFF";
+    constructor(message?: string);
+}
 /** Raised when a thread is already running something and the busy policy is `reject`. */
 export declare class ThreadBusyError extends ServerError {
     /** The thread. */

package/dist-cjs/server/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AssistantCapabilityError = exports.TenantLimitError = exports.ThreadBusyError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = exports.NotFoundError = exports.ServerError = void 0;
+exports.AssistantCapabilityError = exports.TenantLimitError = exports.ThreadBusyError = exports.RunHandOffError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = exports.NotFoundError = exports.ServerError = void 0;
 class ServerError extends Error {
     code;
     status;
@@ -43,6 +43,14 @@ class ForbiddenError extends ServerError {
     }
 }
 exports.ForbiddenError = ForbiddenError;
+class RunHandOffError extends Error {
+    code = 'RUN_HANDED_OFF';
+    constructor(message = 'Handed to another worker while this one drains') {
+        super(message);
+        this.name = 'RunHandOffError';
+    }
+}
+exports.RunHandOffError = RunHandOffError;
 class ThreadBusyError extends ServerError {
     threadId;
     runId;

package/dist-cjs/server/index.d.ts

@@ -9,7 +9,7 @@
  */
 export { functionAssistant, type GraphAssistantOptions, graphAssistant, type GraphLike, } from './assistant.js';
 export { CronScheduler, type CronSchedulerOptions, type DueCronJob, parseCron } from './cron.js';
-export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, ServerError, type TenantLimit, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
+export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, RunHandOffError, ServerError, type TenantLimit, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
 export { MemoryRunEventLog, type MemoryRunEventLogOptions, type RedisEventLogLikeClient, RedisRunEventLog, type RedisRunEventLogOptions, } from './events.js';
 export { type NodeListenerOptions, type NodeRequestLike, type NodeResponseLike, toNodeListener, } from './node.js';
 export { type DrainResult, RunManager, type RunManagerOptions, type RunQueueOptions, type StartRunOptions, } from './runs.js';

package/dist-cjs/server/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryServerStore = exports.fromStore = exports.createAgentServer = exports.RunManager = exports.toNodeListener = exports.RedisRunEventLog = exports.MemoryRunEventLog = exports.UnauthorizedError = exports.ThreadBusyError = exports.TenantLimitError = exports.ServerError = exports.NotFoundError = exports.ForbiddenError = exports.BadRequestError = exports.AssistantCapabilityError = exports.parseCron = exports.CronScheduler = exports.graphAssistant = exports.functionAssistant = void 0;
+exports.MemoryServerStore = exports.fromStore = exports.createAgentServer = exports.RunManager = exports.toNodeListener = exports.RedisRunEventLog = exports.MemoryRunEventLog = exports.UnauthorizedError = exports.ThreadBusyError = exports.TenantLimitError = exports.ServerError = exports.RunHandOffError = exports.NotFoundError = exports.ForbiddenError = exports.BadRequestError = exports.AssistantCapabilityError = exports.parseCron = exports.CronScheduler = exports.graphAssistant = exports.functionAssistant = void 0;
 var assistant_js_1 = require("./assistant.js");
 Object.defineProperty(exports, "functionAssistant", { enumerable: true, get: function () { return assistant_js_1.functionAssistant; } });
 Object.defineProperty(exports, "graphAssistant", { enumerable: true, get: function () { return assistant_js_1.graphAssistant; } });
@@ -12,6 +12,7 @@ Object.defineProperty(exports, "AssistantCapabilityError", { enumerable: true, g
 Object.defineProperty(exports, "BadRequestError", { enumerable: true, get: function () { return errors_js_1.BadRequestError; } });
 Object.defineProperty(exports, "ForbiddenError", { enumerable: true, get: function () { return errors_js_1.ForbiddenError; } });
 Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "RunHandOffError", { enumerable: true, get: function () { return errors_js_1.RunHandOffError; } });
 Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_js_1.ServerError; } });
 Object.defineProperty(exports, "TenantLimitError", { enumerable: true, get: function () { return errors_js_1.TenantLimitError; } });
 Object.defineProperty(exports, "ThreadBusyError", { enumerable: true, get: function () { return errors_js_1.ThreadBusyError; } });

package/dist-cjs/server/runs.d.ts

@@ -97,6 +97,10 @@ export declare class RunManager {
     private readonly local;
     /** Runs holding one of this replica's execution slots. */
     private readonly slots;
+    /** The drain switch of each run this replica is executing, so `drain()` can reach graph runs. */
+    private readonly controls;
+    /** Runs handed back to the queue during a drain, as each graph run stopped at a boundary. */
+    private readonly drainedRuns;
     private readonly state;
     private readonly events;
     private readonly now;
@@ -155,6 +159,8 @@ export declare class RunManager {
      * it with a `TenantLimitError`.
      */
     start(options: StartRunOptions): Promise<RunRecord>;
+    /** The rest of `start()`, once the thread, if any, is this run's. */
+    private startClaimed;
     /** Cancels a run, including one another replica is executing. */
     cancel(runId: string, principal?: Principal, reason?: string): Promise<RunRecord>;
     /**
@@ -206,8 +212,29 @@ export declare class RunManager {
     private freeSlot;
     private schedule;
     private tick;
-    /** Applies the busy policy, returning the thread once it is free to run something new. */
+    /**
+     * Applies the busy policy, returning the thread once this run holds it. The thread is claimed
+     * atomically, so of several replicas starting runs on one thread at once, exactly one proceeds and
+     * the rest meet the policy; a thread still busy after the policy has run its course is refused.
+     */
     private settleBusyThread;
+    /**
+     * Claims a thread for a run. The claim is a record in the operation store under a unique
+     * idempotency key, moved from run to run by compare-and-set, so two replicas cannot both take a free
+     * thread: creating it races on the key, and taking it over races on the sequence. Resolves
+     * undefined once this run holds the thread, or the id of the unfinished run that does.
+     *
+     * A store without `findByIdempotencyKey` falls back to the thread record's `activeRunId`, which is
+     * what every release before 2.2 used, and which two replicas racing can both see empty.
+     */
+    private claimThread;
+    /**
+     * Whether a thread's holder no longer needs it: its run finished, or it was never recorded and its
+     * claim is old enough that the replica starting it must have died.
+     */
+    private runIsFree;
+    /** Frees a thread this run holds. Losing the compare-and-set means another run took it over, which is fine. */
+    private releaseClaim;
     /** Waits for a run to finish, for the `enqueue` policy. */
     private waitForRun;
     private releaseThread;