orchestration

Classes

GraphBuilder

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:60

Constructors

Constructor

new GraphBuilder(): GraphBuilder;

Returns

GraphBuilder

Methods

addConditionalEdge()

addConditionalEdge(
   from, 
   router, 
   targets
): this;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:101

Adds a conditional edge with a routing function. The router inspects state and returns the target node ID. All possible targets must be declared for compile-time validation.

Parameters

from

string

router

(state) => string

targets

readonly string[]

Returns

this

addEdge()

addEdge(
   from, 
   to, 
   options?
): this;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:86

Adds a fixed edge between two nodes.

Parameters

from

string

to

string

options?

maxTraversals?

number

Returns

this

addNode()

addNode(
   id, 
   handler, 
   opts?
): this;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:77

Adds a node to the graph. Supports optional precondition hooks (Issue #997) and verify hook (Issue #994).

Parameters

id

string

handler

NodeHandler

opts?

NodeOptions

Returns

this

addState()

addState<T>(name, schema): this;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:68

Registers a state field with its default value and reducer.

Type Parameters

T

T

Parameters

name

string

schema

StateFieldSchema<T>

Returns

this

compile()

compile(): CompileResult;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:118

Compiles the graph, validating all structural invariants. Returns a CompileResult — either a validated CompiledGraph or a compile error.

Returns

CompileResult

InMemoryCheckpointStore

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:37

In-memory checkpoint store with bounded storage. Checkpoints are evicted on a per-execution basis (oldest first) when limits are exceeded.

Implements

ICheckpointStore

Constructors

Constructor

new InMemoryCheckpointStore(): InMemoryCheckpointStore;

Returns

InMemoryCheckpointStore

Methods

clear()

clear(): void;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:101

Clears all checkpoints.

Returns

void

Implementation of

ICheckpointStore.clear

delete()

delete(id): boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:75

Deletes a checkpoint by ID. Returns true if found and deleted.

Parameters

id

string

Returns

boolean

Implementation of

ICheckpointStore.delete

deleteExecution()

deleteExecution(executionId): number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:88

Deletes all checkpoints for a given execution ID.

Parameters

executionId

string

Returns

number

Implementation of

ICheckpointStore.deleteExecution

latest()

latest(executionId): Checkpoint | undefined;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:58

Loads the latest checkpoint for a given execution ID.

Parameters

executionId

string

Returns

Checkpoint | undefined

Implementation of

ICheckpointStore.latest

list()

list(executionId): readonly CheckpointSummary[];

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:67

Lists all checkpoint summaries for a given execution ID.

Parameters

executionId

string

Returns

readonly CheckpointSummary[]

Implementation of

ICheckpointStore.list

load()

load(id): Checkpoint | undefined;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:54

Loads a checkpoint by ID. Returns undefined if not found.

Parameters

id

string

Returns

Checkpoint | undefined

Implementation of

ICheckpointStore.load

save()

save(checkpoint): void;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:41

Saves a checkpoint. Overwrites if ID already exists.

Parameters

checkpoint

Checkpoint

Returns

void

Implementation of

ICheckpointStore.save

size()

size(): number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:97

Returns total number of checkpoints across all executions.

Returns

number

Implementation of

ICheckpointStore.size

OrchestratorError

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:125

Orchestrator error with context.

Extends

Error

Constructors

Constructor

new OrchestratorError(
   message, 
   code, 
   options?
): OrchestratorError;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:131

Parameters

message

string

code

OrchestratorErrorCode

options?

cause?

Error

step?

string

Returns

OrchestratorError

Overrides

Error.constructor

Properties

cause

readonly cause: Error | undefined;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:129

Overrides

Error.cause

code

readonly code: OrchestratorErrorCode;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:127

message

message: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Error.message

name

readonly name: "OrchestratorError";

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:126

Overrides

Error.name

stack?

optional stack?: string;

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.stack

step

readonly step: string | undefined;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:128

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@25.9.8/node_modules/@types/node/globals.d.ts:55

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

OrchestratorFactory

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:302

Factory for creating IOrchestrator instances.

Provides a unified entry point for all orchestration strategies:

workflow: Static template-based execution
tech_lead: LLM-based task decomposition and orchestration (OrchestratorAdapter)
puppeteer: Policy-based step execution (PuppeteerAdapter)

Example

const factory = await createOrchestratorFactory();
const orchestrator = factory.create('workflow');

const result = await orchestrator.execute(
  { type: 'workflow', templatePath: './templates/code-review.yaml' },
  { url: 'https://github.com/...' }
);

Implements

IOrchestratorFactory

Constructors

Constructor

new OrchestratorFactory(config, workflowEngine?): OrchestratorFactory;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:307

Parameters

Methods

create()

create(type, _config?): IOrchestrator;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:313

Create an orchestrator instance.

Parameters

type

OrchestratorType

Orchestrator type

_config?

Record<string, unknown>

Returns

IOrchestrator

New orchestrator instance

Implementation of

IOrchestratorFactory.create

listTypes()

listTypes(): OrchestratorType[];

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:363

List available orchestrator types.

Returns

OrchestratorType[]

Implementation of

IOrchestratorFactory.listTypes

OutcomeStore

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:69

Bounded, append-only, in-memory store for task outcomes. Evicts oldest entries when capacity is exceeded.

Extended by

PersistentOutcomeStore

Constructors

Constructor

new OutcomeStore(config?): OutcomeStore;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:74

Parameters

config?

OutcomeStoreConfig

Returns

OutcomeStore

Accessors

size

Get Signature

get size(): number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:189

Number of stored outcomes.

Returns

number

Methods

append()

append(outcome): void;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:85

Append a new outcome. Auto-classifies failures missing failureCategory (#1441) and resolves the outcome’s vendor / family via the ModelRegistry (#2548) so family-level retrieval can warm-start siblings after a model retirement.

Parameters

outcome

baselineId?

string = ...

Baseline this outcome forked from (#2697 / Epic F follow-up to #2665). Set on outcomes recorded inside a fork-then-merge graph branch so query({ baselineId: 'B' }) returns every branch outcome forked from baseline B — letting later analysis compare branches as a cohort. Free-form string (caller-assigned); typically the parent node’s executionId or taskId.

categorySource?

"defaulted" | "detected" = ...

Whether category was detected or defaulted (#6549). Absent on legacy rows.

cli

cliSource?

"executed" | "category-default" = ...

How the CLI attribution was obtained. Absent on legacy, unmeasured records.

costUsd?

number = ...

USD cost of the call (#6624), from the ledger’s cost wrappers: the gateway arm’s declaration when a gateway served it, else the registry rate for servedModel. Present ONLY when a price was found. Absent means the cost is unknown — never read an absent cost as $0.

durationMs

number = ...

errorMessage?

string = ...

failureCategory?

family?

string = ...

Family resolved from model via ModelRegistry at write time (#2548).

id

string = ...

model

string = ...

priceBasis?

"unknown" | "list" = ...

What costUsd rests on (#6624): 'list' when a rate was found, 'unknown' when one was looked up and none exists. Absent when no lookup was made, because the adapter reported no token usage.

qualitySignals?

string[] = ...

requestId?

string = ...

Request id correlating this outcome to its originating invocation (#3146).

retryCount?

number = ...

Number of retry attempts before this outcome (#1785).

routedBy?

"composite-router" = ...

Set only when CompositeRouter selected the CLI for this task (#6521).

routingStage?

string = ...

Routing stage that selected this CLI (#1785).

servedModel?

string = ...

The model id the adapter reported serving the call (#6624). model stays what the writer has always put there: some writers store a role or aggregate marker in it (pipeline, worker-<role>, consensus) and readers group on that marker. Absent when the writer had no served model: the call failed, or the adapter reported none.

source

"delegate" | "consensus" | "manual" = OutcomeSourceSchema

success

boolean = ...

timestamp

string = ...

traceId?

string = ...

Distributed trace id correlating this outcome across the pipeline (#3146). Optional + backward-compatible: older JSONL records without it hydrate fine.

triageAction?

string = ...

Triage action taken on the failure (#1506).

vendor?

string = ...

Vendor resolved from model via ModelRegistry at write time (#2548).

voterRole?

string = ...

Voter role for source: 'consensus' outcomes (#2662) — architect, security, etc. Absent on non-consensus outcomes. Lets the stratified outcome report break results down by voter role.

wasRetried?

boolean = ...

Whether this outcome came from a triage-initiated retry (#1506).

Returns

void

clear()

clear(): void;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:194

Remove all stored outcomes.

Returns

void

purgeSkippedWorkers()

purgeSkippedWorkers(): number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:243

Purge false failures with zero execution time (#1528). Removes non-success entries with durationMs=0 — these are either:

Skipped workers (circuit breaker, role auto-disable)
Test-generated entries (E2E eval artifacts)
Pre-execution short-circuits (validation, initialization) Real model execution always takes >0ms. Returns count of purged entries.

Returns

number

query()

query(filter?): readonly {
  baselineId?: string;
  category:   | "planning"
     | "architecture"
     | "code_generation"
     | "code_review"
     | "research"
     | "security_review"
     | "documentation"
     | "testing"
     | "devops"
     | "exploration";
  categorySource?: "defaulted" | "detected";
  cli:   | "unknown"
     | "claude"
     | "gemini"
     | "codex"
     | "opencode"
     | "api:anthropic"
     | "api:google"
     | "api:openai"
     | "api:custom-openai";
  cliSource?: "executed" | "category-default";
  costUsd?: number;
  durationMs: number;
  errorMessage?: string;
  failureCategory?:   | "unknown"
     | "timeout"
     | "parse"
     | "connection"
     | "execution"
     | "rate_limit"
     | "validation"
     | "crash"
     | "authentication"
     | "adapter_unavailable"
     | "generic";
  family?: string;
  id: string;
  model: string;
  priceBasis?: "unknown" | "list";
  qualitySignals?: string[];
  requestId?: string;
  retryCount?: number;
  routedBy?: "composite-router";
  routingStage?: string;
  servedModel?: string;
  source: "delegate" | "consensus" | "manual";
  success: boolean;
  timestamp: string;
  traceId?: string;
  triageAction?: string;
  vendor?: string;
  voterRole?: string;
  wasRetried?: boolean;
}[];

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:105

Query outcomes with optional filters.

Parameters

filter?

baselineId?

string = ...

Restrict to outcomes recorded against a specific baseline (#2697).

category?

cli?

excludeQualitySignals?

string[] = ...

Exclude outcomes with any of these quality signals (#1680).

failureCategory?

limit?

number = ...

since?

string = ...

source?

"delegate" | "consensus" | "manual" = ...

success?

boolean = ...

Returns

readonly { baselineId?: string; category: | "planning" | "architecture" | "code_generation" | "code_review" | "research" | "security_review" | "documentation" | "testing" | "devops" | "exploration"; categorySource?: "defaulted" | "detected"; cli: | "unknown" | "claude" | "gemini" | "codex" | "opencode" | "api:anthropic" | "api:google" | "api:openai" | "api:custom-openai"; cliSource?: "executed" | "category-default"; costUsd?: number; durationMs: number; errorMessage?: string; failureCategory?: | "unknown" | "timeout" | "parse" | "connection" | "execution" | "rate_limit" | "validation" | "crash" | "authentication" | "adapter_unavailable" | "generic"; family?: string; id: string; model: string; priceBasis?: "unknown" | "list"; qualitySignals?: string[]; requestId?: string; retryCount?: number; routedBy?: "composite-router"; routingStage?: string; servedModel?: string; source: "delegate" | "consensus" | "manual"; success: boolean; timestamp: string; traceId?: string; triageAction?: string; vendor?: string; voterRole?: string; wasRetried?: boolean; }[]

queryByModelWithFamilyFallback()

queryByModelWithFamilyFallback(modelId, options?): {
  family?: string;
  outcomes: readonly {
     baselineId?: string;
     category:   | "planning"
        | "architecture"
        | "code_generation"
        | "code_review"
        | "research"
        | "security_review"
        | "documentation"
        | "testing"
        | "devops"
        | "exploration";
     categorySource?: "defaulted" | "detected";
     cli:   | "unknown"
        | "claude"
        | "gemini"
        | "codex"
        | "opencode"
        | "api:anthropic"
        | "api:google"
        | "api:openai"
        | "api:custom-openai";
     cliSource?: "executed" | "category-default";
     costUsd?: number;
     durationMs: number;
     errorMessage?: string;
     failureCategory?:   | "unknown"
        | "timeout"
        | "parse"
        | "connection"
        | "execution"
        | "rate_limit"
        | "validation"
        | "crash"
        | "authentication"
        | "adapter_unavailable"
        | "generic";
     family?: string;
     id: string;
     model: string;
     priceBasis?: "unknown" | "list";
     qualitySignals?: string[];
     requestId?: string;
     retryCount?: number;
     routedBy?: "composite-router";
     routingStage?: string;
     servedModel?: string;
     source: "delegate" | "consensus" | "manual";
     success: boolean;
     timestamp: string;
     traceId?: string;
     triageAction?: string;
     vendor?: string;
     voterRole?: string;
     wasRetried?: boolean;
  }[];
  scope: "literal" | "family" | "empty";
  vendor?: string;
};

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:130

Query outcomes for a specific model with a family-level warm-start fallback (#2548). When the literal modelId has fewer than threshold samples in the store, broaden the result to the model’s {vendor, family} siblings — siblings within a family share enough behavior profile that their outcomes are useful priors for cold starts after a retirement.

Returns the outcomes and a scope flag so callers know whether they’re consuming literal-id data or family-broadened data.

Parameters

modelId

string

options?

extraFilter?

Omit<{ baselineId?: string; category?: | "planning" | "architecture" | "code_generation" | "code_review" | "research" | "security_review" | "documentation" | "testing" | "devops" | "exploration"; cli?: | "unknown" | "claude" | "gemini" | "codex" | "opencode" | "api:anthropic" | "api:google" | "api:openai" | "api:custom-openai"; excludeQualitySignals?: string[]; failureCategory?: | "unknown" | "timeout" | "parse" | "connection" | "execution" | "rate_limit" | "validation" | "crash" | "authentication" | "adapter_unavailable" | "generic"; limit?: number; since?: string; source?: "delegate" | "consensus" | "manual"; success?: boolean; }, "limit">

threshold?

number

Returns

{
  family?: string;
  outcomes: readonly {
     baselineId?: string;
     category:   | "planning"
        | "architecture"
        | "code_generation"
        | "code_review"
        | "research"
        | "security_review"
        | "documentation"
        | "testing"
        | "devops"
        | "exploration";
     categorySource?: "defaulted" | "detected";
     cli:   | "unknown"
        | "claude"
        | "gemini"
        | "codex"
        | "opencode"
        | "api:anthropic"
        | "api:google"
        | "api:openai"
        | "api:custom-openai";
     cliSource?: "executed" | "category-default";
     costUsd?: number;
     durationMs: number;
     errorMessage?: string;
     failureCategory?:   | "unknown"
        | "timeout"
        | "parse"
        | "connection"
        | "execution"
        | "rate_limit"
        | "validation"
        | "crash"
        | "authentication"
        | "adapter_unavailable"
        | "generic";
     family?: string;
     id: string;
     model: string;
     priceBasis?: "unknown" | "list";
     qualitySignals?: string[];
     requestId?: string;
     retryCount?: number;
     routedBy?: "composite-router";
     routingStage?: string;
     servedModel?: string;
     source: "delegate" | "consensus" | "manual";
     success: boolean;
     timestamp: string;
     traceId?: string;
     triageAction?: string;
     vendor?: string;
     voterRole?: string;
     wasRetried?: boolean;
  }[];
  scope: "literal" | "family" | "empty";
  vendor?: string;
}

family?

readonly optional family?: string;

outcomes

readonly outcomes: readonly {
  baselineId?: string;
  category:   | "planning"
     | "architecture"
     | "code_generation"
     | "code_review"
     | "research"
     | "security_review"
     | "documentation"
     | "testing"
     | "devops"
     | "exploration";
  categorySource?: "defaulted" | "detected";
  cli:   | "unknown"
     | "claude"
     | "gemini"
     | "codex"
     | "opencode"
     | "api:anthropic"
     | "api:google"
     | "api:openai"
     | "api:custom-openai";
  cliSource?: "executed" | "category-default";
  costUsd?: number;
  durationMs: number;
  errorMessage?: string;
  failureCategory?:   | "unknown"
     | "timeout"
     | "parse"
     | "connection"
     | "execution"
     | "rate_limit"
     | "validation"
     | "crash"
     | "authentication"
     | "adapter_unavailable"
     | "generic";
  family?: string;
  id: string;
  model: string;
  priceBasis?: "unknown" | "list";
  qualitySignals?: string[];
  requestId?: string;
  retryCount?: number;
  routedBy?: "composite-router";
  routingStage?: string;
  servedModel?: string;
  source: "delegate" | "consensus" | "manual";
  success: boolean;
  timestamp: string;
  traceId?: string;
  triageAction?: string;
  vendor?: string;
  voterRole?: string;
  wasRetried?: boolean;
}[];

scope

readonly scope: "literal" | "family" | "empty";

vendor?

readonly optional vendor?: string;

reclassifyAll()

reclassifyAll(): number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:205

Backfill: reclassify all entries missing failureCategory (#1444). Also reclassifies ‘unknown’ entries with no error message as ‘execution’ (#1511) since ‘unknown’ with no diagnostic info is less useful than the default ‘execution’ category. Returns count of reclassified entries.

Returns

number

summarize()

summarize(filter?): PerformanceSummary;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:161

Aggregate outcomes into a performance summary.

Parameters

filter?

baselineId?

string = ...

Restrict to outcomes recorded against a specific baseline (#2697).

category?

cli?

excludeQualitySignals?

string[] = ...

Exclude outcomes with any of these quality signals (#1680).

failureCategory?

limit?

number = ...

since?

string = ...

source?

"delegate" | "consensus" | "manual" = ...

success?

boolean = ...

Returns

PerformanceSummary

PersistentOutcomeStore

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store-persistence.ts:54

OutcomeStore that persists entries to a JSONL file on disk.

Construction: hydrates from existing JSONL file (Zod-validates each line)
Append: calls super.append() then appendFileSync one JSON line
Corruption: bad lines are skipped with a warning log

Extends

OutcomeStore

Constructors

Constructor

new PersistentOutcomeStore(config?, logger?): PersistentOutcomeStore;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store-persistence.ts:58

Parameters

config?

PersistentOutcomeStoreConfig

logger?

ILogger

Returns

PersistentOutcomeStore

Overrides

OutcomeStore.constructor

Accessors

size

Get Signature

get size(): number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:189

Number of stored outcomes.

Returns

number

Inherited from

OutcomeStore.size

Methods

append()

append(outcome): void;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store-persistence.ts:71

Override append to persist each entry to disk.

Parameters

outcome

baselineId?

string = ...

categorySource?

"defaulted" | "detected" = ...

Whether category was detected or defaulted (#6549). Absent on legacy rows.

cli

cliSource?

"executed" | "category-default" = ...

How the CLI attribution was obtained. Absent on legacy, unmeasured records.

costUsd?

number = ...

durationMs

number = ...

errorMessage?

string = ...

failureCategory?

family?

string = ...

Family resolved from model via ModelRegistry at write time (#2548).

id

string = ...

model

string = ...

priceBasis?

"unknown" | "list" = ...

What costUsd rests on (#6624): 'list' when a rate was found, 'unknown' when one was looked up and none exists. Absent when no lookup was made, because the adapter reported no token usage.

qualitySignals?

string[] = ...

requestId?

string = ...

Request id correlating this outcome to its originating invocation (#3146).

retryCount?

number = ...

Number of retry attempts before this outcome (#1785).

routedBy?

"composite-router" = ...

Set only when CompositeRouter selected the CLI for this task (#6521).

routingStage?

string = ...

Routing stage that selected this CLI (#1785).

servedModel?

string = ...

source

"delegate" | "consensus" | "manual" = OutcomeSourceSchema

success

boolean = ...

timestamp

string = ...

traceId?

string = ...

Distributed trace id correlating this outcome across the pipeline (#3146). Optional + backward-compatible: older JSONL records without it hydrate fine.

triageAction?

string = ...

Triage action taken on the failure (#1506).

vendor?

string = ...

Vendor resolved from model via ModelRegistry at write time (#2548).

voterRole?

string = ...

Voter role for source: 'consensus' outcomes (#2662) — architect, security, etc. Absent on non-consensus outcomes. Lets the stratified outcome report break results down by voter role.

wasRetried?

boolean = ...

Whether this outcome came from a triage-initiated retry (#1506).

Returns

void

Overrides

OutcomeStore.append

clear()

clear(): void;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:194

Remove all stored outcomes.

Returns

void

Inherited from

OutcomeStore.clear

purgeSkippedWorkers()

purgeSkippedWorkers(): number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:243

Purge false failures with zero execution time (#1528). Removes non-success entries with durationMs=0 — these are either:

Skipped workers (circuit breaker, role auto-disable)
Test-generated entries (E2E eval artifacts)
Pre-execution short-circuits (validation, initialization) Real model execution always takes >0ms. Returns count of purged entries.

Returns

number

Inherited from

OutcomeStore.purgeSkippedWorkers

query()

query(filter?): readonly {
  baselineId?: string;
  category:   | "planning"
     | "architecture"
     | "code_generation"
     | "code_review"
     | "research"
     | "security_review"
     | "documentation"
     | "testing"
     | "devops"
     | "exploration";
  categorySource?: "defaulted" | "detected";
  cli:   | "unknown"
     | "claude"
     | "gemini"
     | "codex"
     | "opencode"
     | "api:anthropic"
     | "api:google"
     | "api:openai"
     | "api:custom-openai";
  cliSource?: "executed" | "category-default";
  costUsd?: number;
  durationMs: number;
  errorMessage?: string;
  failureCategory?:   | "unknown"
     | "timeout"
     | "parse"
     | "connection"
     | "execution"
     | "rate_limit"
     | "validation"
     | "crash"
     | "authentication"
     | "adapter_unavailable"
     | "generic";
  family?: string;
  id: string;
  model: string;
  priceBasis?: "unknown" | "list";
  qualitySignals?: string[];
  requestId?: string;
  retryCount?: number;
  routedBy?: "composite-router";
  routingStage?: string;
  servedModel?: string;
  source: "delegate" | "consensus" | "manual";
  success: boolean;
  timestamp: string;
  traceId?: string;
  triageAction?: string;
  vendor?: string;
  voterRole?: string;
  wasRetried?: boolean;
}[];

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:105

Query outcomes with optional filters.

Parameters

filter?

baselineId?

string = ...

Restrict to outcomes recorded against a specific baseline (#2697).

category?

cli?

excludeQualitySignals?

string[] = ...

Exclude outcomes with any of these quality signals (#1680).

failureCategory?

limit?

number = ...

since?

string = ...

source?

"delegate" | "consensus" | "manual" = ...

success?

boolean = ...

Returns

Inherited from

OutcomeStore.query

queryByModelWithFamilyFallback()

queryByModelWithFamilyFallback(modelId, options?): {
  family?: string;
  outcomes: readonly {
     baselineId?: string;
     category:   | "planning"
        | "architecture"
        | "code_generation"
        | "code_review"
        | "research"
        | "security_review"
        | "documentation"
        | "testing"
        | "devops"
        | "exploration";
     categorySource?: "defaulted" | "detected";
     cli:   | "unknown"
        | "claude"
        | "gemini"
        | "codex"
        | "opencode"
        | "api:anthropic"
        | "api:google"
        | "api:openai"
        | "api:custom-openai";
     cliSource?: "executed" | "category-default";
     costUsd?: number;
     durationMs: number;
     errorMessage?: string;
     failureCategory?:   | "unknown"
        | "timeout"
        | "parse"
        | "connection"
        | "execution"
        | "rate_limit"
        | "validation"
        | "crash"
        | "authentication"
        | "adapter_unavailable"
        | "generic";
     family?: string;
     id: string;
     model: string;
     priceBasis?: "unknown" | "list";
     qualitySignals?: string[];
     requestId?: string;
     retryCount?: number;
     routedBy?: "composite-router";
     routingStage?: string;
     servedModel?: string;
     source: "delegate" | "consensus" | "manual";
     success: boolean;
     timestamp: string;
     traceId?: string;
     triageAction?: string;
     vendor?: string;
     voterRole?: string;
     wasRetried?: boolean;
  }[];
  scope: "literal" | "family" | "empty";
  vendor?: string;
};

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:130

Returns the outcomes and a scope flag so callers know whether they’re consuming literal-id data or family-broadened data.

Parameters

modelId

string

options?

extraFilter?

threshold?

number

Returns

{
  family?: string;
  outcomes: readonly {
     baselineId?: string;
     category:   | "planning"
        | "architecture"
        | "code_generation"
        | "code_review"
        | "research"
        | "security_review"
        | "documentation"
        | "testing"
        | "devops"
        | "exploration";
     categorySource?: "defaulted" | "detected";
     cli:   | "unknown"
        | "claude"
        | "gemini"
        | "codex"
        | "opencode"
        | "api:anthropic"
        | "api:google"
        | "api:openai"
        | "api:custom-openai";
     cliSource?: "executed" | "category-default";
     costUsd?: number;
     durationMs: number;
     errorMessage?: string;
     failureCategory?:   | "unknown"
        | "timeout"
        | "parse"
        | "connection"
        | "execution"
        | "rate_limit"
        | "validation"
        | "crash"
        | "authentication"
        | "adapter_unavailable"
        | "generic";
     family?: string;
     id: string;
     model: string;
     priceBasis?: "unknown" | "list";
     qualitySignals?: string[];
     requestId?: string;
     retryCount?: number;
     routedBy?: "composite-router";
     routingStage?: string;
     servedModel?: string;
     source: "delegate" | "consensus" | "manual";
     success: boolean;
     timestamp: string;
     traceId?: string;
     triageAction?: string;
     vendor?: string;
     voterRole?: string;
     wasRetried?: boolean;
  }[];
  scope: "literal" | "family" | "empty";
  vendor?: string;
}

family?

readonly optional family?: string;

outcomes

readonly outcomes: readonly {
  baselineId?: string;
  category:   | "planning"
     | "architecture"
     | "code_generation"
     | "code_review"
     | "research"
     | "security_review"
     | "documentation"
     | "testing"
     | "devops"
     | "exploration";
  categorySource?: "defaulted" | "detected";
  cli:   | "unknown"
     | "claude"
     | "gemini"
     | "codex"
     | "opencode"
     | "api:anthropic"
     | "api:google"
     | "api:openai"
     | "api:custom-openai";
  cliSource?: "executed" | "category-default";
  costUsd?: number;
  durationMs: number;
  errorMessage?: string;
  failureCategory?:   | "unknown"
     | "timeout"
     | "parse"
     | "connection"
     | "execution"
     | "rate_limit"
     | "validation"
     | "crash"
     | "authentication"
     | "adapter_unavailable"
     | "generic";
  family?: string;
  id: string;
  model: string;
  priceBasis?: "unknown" | "list";
  qualitySignals?: string[];
  requestId?: string;
  retryCount?: number;
  routedBy?: "composite-router";
  routingStage?: string;
  servedModel?: string;
  source: "delegate" | "consensus" | "manual";
  success: boolean;
  timestamp: string;
  traceId?: string;
  triageAction?: string;
  vendor?: string;
  voterRole?: string;
  wasRetried?: boolean;
}[];

scope

readonly scope: "literal" | "family" | "empty";

vendor?

readonly optional vendor?: string;

Inherited from

OutcomeStore.queryByModelWithFamilyFallback

reclassifyAll()

reclassifyAll(): number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:205

Returns

number

Inherited from

OutcomeStore.reclassifyAll

summarize()

summarize(filter?): PerformanceSummary;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:161

Aggregate outcomes into a performance summary.

Parameters

filter?

baselineId?

string = ...

Restrict to outcomes recorded against a specific baseline (#2697).

category?

cli?

excludeQualitySignals?

string[] = ...

Exclude outcomes with any of these quality signals (#1680).

failureCategory?

limit?

number = ...

since?

string = ...

source?

"delegate" | "consensus" | "manual" = ...

success?

boolean = ...

Returns

PerformanceSummary

Inherited from

OutcomeStore.summarize

WorkflowOrchestratorAdapter

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:66

Adapter that wraps IWorkflowEngine with IOrchestrator interface.

This adapter bridges the workflow-specific interface to the canonical orchestrator interface, enabling workflow-based orchestration through the unified IOrchestrator contract.

Implements

IOrchestrator

Constructors

Constructor

new WorkflowOrchestratorAdapter(engine, logger?): WorkflowOrchestratorAdapter;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:75

Parameters

engine

IWorkflowEngine

logger?

ILogger

Returns

WorkflowOrchestratorAdapter

Properties

id

readonly id: string;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:67

Unique orchestrator instance ID

Implementation of

IOrchestrator.id

type

readonly type: OrchestratorType = 'workflow';

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:68

Orchestrator type

Implementation of

IOrchestrator.type

Methods

cancel()

cancel(executionId, reason?): Promise<Result<void, OrchestratorError>>;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:184

Cancel a running execution.

Parameters

executionId

string

Execution ID to cancel

reason?

string

Optional cancellation reason

Returns

Promise<Result<void, OrchestratorError>>

Result with void or OrchestratorError

Implementation of

IOrchestrator.cancel

execute()

execute(
   definition, 
   inputs, 
   _options?
): Promise<Result<OrchestratorResult, OrchestratorError>>;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:81

Execute an orchestration.

Parameters

definition

OrchestratorDefinition

What to orchestrate (task, workflow, or policy)

inputs

Record<string, unknown>

Input values for the orchestration

_options?

OrchestratorExecuteOptions

Returns

Promise<Result<OrchestratorResult, OrchestratorError>>

Result with OrchestratorResult or OrchestratorError

Implementation of

IOrchestrator.execute

getHistory()

getHistory(limit?): OrchestratorResult[];

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:217

Get execution history. Optional - for orchestrators that track history.

Parameters

limit?

number

Maximum number of executions to return

Returns

OrchestratorResult[]

Array of past execution results

Implementation of

IOrchestrator.getHistory

getStatus()

getStatus(executionId): ExecutionStatus;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:180

Get status of an execution.

Parameters

executionId

string

Execution ID to check

Returns

ExecutionStatus

Current execution status

Implementation of

IOrchestrator.getStatus

Interfaces

AdaptiveThresholdResult

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:24

Result of computing adaptive thresholds for a CLI+category pair.

Properties

baseline

readonly baseline: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:26

Adjusted baseline success rate (default: 0.7).

coldStart

readonly coldStart: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:30

Minimum samples before adjustment (always 10).

confidence

readonly confidence: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:34

Confidence in the result (0-1), based on sample size.

maxBonus

readonly maxBonus: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:28

Adjusted max bonus cap (default: 10).

sampleCount

readonly sampleCount: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:36

Number of outcomes used for computation.

trend

readonly trend: Trend;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:32

Detected performance trend.

Checkpoint

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:63

A snapshot of graph execution state at a given step boundary. Contains all information needed to resume execution.

Properties

completedResults

readonly completedResults: readonly NodeResult[];

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:77

Results of all completed nodes so far.

createdAt

readonly createdAt: string;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:79

ISO timestamp when checkpoint was created.

executionId

readonly executionId: string;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:67

Execution ID this checkpoint belongs to.

id

readonly id: string;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:65

Unique checkpoint ID.

interrupt?

readonly optional interrupt?: CheckpointInterrupt;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:87

If present, the checkpoint was created because a node returned an Interrupt. The resume API uses this to know which node to re-run and which interrupt id to match resume values against. (#1895)

metadata?

readonly optional metadata?: Record<string, unknown>;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:81

Optional metadata for debugging.

pendingNodeIds

readonly pendingNodeIds: readonly string[];

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:75

IDs of nodes ready to run next.

schemaVersion

readonly schemaVersion: number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:69

Schema version for deserialization.

state

readonly state: Readonly<GraphState>;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:73

Full graph state at this point.

stepNumber

readonly stepNumber: number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:71

Step number when this checkpoint was taken.

CheckpointSummary

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:93

Summary of a checkpoint (for listing without full state).

Properties

completedNodeCount

readonly completedNodeCount: number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:98

createdAt

readonly createdAt: string;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:97

executionId

readonly executionId: string;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:95

id

readonly id: string;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:94

pendingNodeCount

readonly pendingNodeCount: number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:99

stepNumber

readonly stepNumber: number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:96

CompiledGraph

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:269

Compiled graph definition — validated and ready for execution. Immutable after compilation.

Properties

edges

readonly edges: readonly GraphEdge[];

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:271

entryEdges

readonly entryEdges: readonly GraphEdge[];

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:273

nodes

readonly nodes: ReadonlyMap<string, GraphNode>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:270

stateSchema

readonly stateSchema: Readonly<StateSchema>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:272

CompileOptions

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:43

Options for compiling a spec to a graph.

Properties

handlerFactory?

readonly optional handlerFactory?: NodeHandlerFactory;

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:45

Factory for creating node handlers. Defaults to dry-run placeholders.

ConsensusGateNodeOptions

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:83

Options for createConsensusGateNode.

Properties

proposalFrom

readonly proposalFrom: (state) => ConsensusProposalInput;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:89

Derive the proposal/context from graph state (no secrets/ambient state).

Parameters

state

Readonly<GraphState>

Returns

ConsensusProposalInput

verdictKey

readonly verdictKey: string;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:87

Graph-state key the typed verdict is written under.

voter

readonly voter: ConsensusVoter;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:85

The voter to run at this gate.

ConsensusProposalInput

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:27

What a consensus voter is asked to evaluate.

Properties

context?

readonly optional context?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:31

Optional supporting context (e.g. research) the voter may weigh.

proposal

readonly proposal: string;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:29

The proposal text under review (e.g. a plan).

ConsensusVerdict

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:35

The typed verdict a consensus round produces.

Properties

detail?

readonly optional detail?: Record<string, unknown>;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:54

Optional structured detail (approval %, the raw vote, …) for consumers.

feedback

readonly feedback: string;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:52

Reviewer feedback (empty on a clean approval).

outcome

readonly outcome: "rejected" | "approved" | "no_quorum";

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:50

Whether the proposal cleared the consensus bar.

no_quorum (#4135) is DISTINCT from rejected: the panel could not reach a valid quorum (an errored/absent voice under the opt-in absolute_quorum policy, or an error-policy short-circuit) — a recoverable “re-run the missing voice” state, NOT the panel rejecting the proposal. A voter that maps a consensus_vote result into a verdict should surface the vote’s decision here so no_quorum propagates. It is not success — pair the gate with a conditional edge that routes no_quorum to a bounded re-vote/escalate rather than the reject/revise path. The voter-throw fail-closed path stays rejected (an exception is an error, not a valid quorum void). Inert until a caller opts into absolute_quorum.

CriterionFailure

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:19

A specific failure for one unmet criterion.

Properties

criterion

readonly criterion: string;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:21

The unmet acceptance criterion

explanation

readonly explanation: string;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:25

Human-readable explanation

type

readonly type: FailureType;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:23

What type of failure occurred

DecomposeError

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:77

Error detail when decomposition fails.

Properties

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:78

subtaskId?

readonly optional subtaskId?: string;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:79

FailureAnalysis

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:43

Complete failure analysis result.

Properties

failures

readonly failures: readonly CriterionFailure[];

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:49

Individual criterion failures

passed

readonly passed: boolean;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:45

Overall pass/fail

satisfaction

readonly satisfaction: number;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:47

Satisfaction score from validation (0-1)

suggestions

readonly suggestions: readonly ImprovementSuggestion[];

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:51

Suggested improvements

FailureAnalysisError

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:57

Error from failure analysis.

Properties

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:58

GraphExecuteOptions

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:338

Options for graph execution.

Properties

checkpointStore?

readonly optional checkpointStore?: ICheckpointStore;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:357

Optional checkpoint store for durable execution (Issue #837).

executionId?

readonly optional executionId?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:359

Execution ID for checkpoint grouping. Required with checkpointStore.

maxSteps?

readonly optional maxSteps?: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:345

Maximum node executions. A parallel super-step starts only when its full batch fits within the remaining budget.

onEvent?

readonly optional onEvent?: (event) => void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:361

Event listener for streaming observation (Issue #838).

Parameters

event

GraphEvent

Returns

void

onNodeComplete?

readonly optional onNodeComplete?: (result) => void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:346

Parameters

result

NodeResult

Returns

void

priorResults?

readonly optional priorResults?: ReadonlyMap<string, NodeResult>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:355

Prior NodeResults to replay instead of re-executing (#3534, selective-retry). A node with a success entry here is skipped — its result (including stateUpdates) is reused so downstream nodes still see the correct state — while nodes absent here, or present with a non-success status, are re-executed. Lets retryFailed re-run only the failed/skipped nodes while replaying the prior successes.

resumeValues?

readonly optional resumeValues?: Readonly<Record<string, unknown>>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:367

Values supplied for HITL resume. Keyed by Interrupt id; passed to each NodeHandler via its NodeContext on this run only. Empty when not resuming. (#1895)

signal?

readonly optional signal?: AbortSignal;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:339

timeout?

readonly optional timeout?: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:340

GraphExecutionResult

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:317

Result of a full graph execution.

Properties

finalState

readonly finalState: Readonly<GraphState>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:318

halted?

readonly optional halted?: {
  checkpointId: string;
  interruptId: string;
  nodeId: string;
  value: unknown;
};

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:327

Set when execution paused on an Interrupt return. The checkpoint referenced here can be passed to resumeFromCheckpoint(...) along with a matching {[interruptId]: resumeValue} map. (#1895)

checkpointId

readonly checkpointId: string;

interruptId

readonly interruptId: string;

nodeId

readonly nodeId: string;

value

readonly value: unknown;

nodeResults

readonly nodeResults: readonly NodeResult[];

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:319

stepsExecuted

readonly stepsExecuted: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:321

totalDurationMs

readonly totalDurationMs: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:320

GraphNode

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:200

A node in the workflow graph.

Properties

gotoTargets?

readonly optional gotoTargets?: readonly string[];

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:220

Nodes this node may jump to with Command.goto (#5727), mirroring LangGraph’s ends. A dynamic jump is an EDGE the static edge set cannot see, so without declaring it a target reachable only via goto fails checkReachability and the graph will not compile at all.

Declaring is not the same as scheduling: the handler still decides at run time whether to jump, and to which of these. The declaration exists so the builder can validate the topology and so a reader (or a visualizer) can see the dynamic edge.

handler

readonly handler: NodeHandler;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:202

id

readonly id: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:201

preconditions?

readonly optional preconditions?: readonly PreconditionConfig[];

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:206

Precondition hooks run before node execution (Issue #997).

retries?

readonly optional retries?: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:204

timeout?

readonly optional timeout?: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:203

verify?

readonly optional verify?: NodeHook;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:208

Post-step verification hook run after node execution (Issue #994).

HookError

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:35

Error type for hook failures — identifies which hook failed and why.

Properties

hookName

readonly hookName: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:36

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:38

nodeId

readonly nodeId: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:37

ICheckpointStore

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:110

Abstract checkpoint store interface. Implementations provide persistence (in-memory, JSON file, SQLite, etc.).

Methods

clear()

clear(): void;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:133

Clears all checkpoints.

Returns

void

delete()

delete(id): boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:124

Deletes a checkpoint by ID. Returns true if found and deleted.

Parameters

id

string

Returns

boolean

deleteExecution()

deleteExecution(executionId): number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:127

Deletes all checkpoints for a given execution ID.

Parameters

executionId

string

Returns

number

latest()

latest(executionId): Checkpoint | undefined;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:118

Loads the latest checkpoint for a given execution ID.

Parameters

executionId

string

Returns

Checkpoint | undefined

list()

list(executionId): readonly CheckpointSummary[];

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:121

Lists all checkpoint summaries for a given execution ID.

Parameters

executionId

string

Returns

readonly CheckpointSummary[]

load()

load(id): Checkpoint | undefined;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:115

Loads a checkpoint by ID. Returns undefined if not found.

Parameters

id

string

Returns

Checkpoint | undefined

save()

save(checkpoint): void;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:112

Saves a checkpoint. Overwrites if ID already exists.

Parameters

checkpoint

Checkpoint

Returns

void

size()

size(): number;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:130

Returns total number of checkpoints across all executions.

Returns

number

ImprovementSuggestion

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:31

A suggested improvement to address failures.

Properties

action

readonly action: string;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:33

What action to take

priority

readonly priority: 1 | 2 | 3;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:37

Priority: 1 (highest) to 3 (lowest)

targetCriterion

readonly targetCriterion: string;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:35

Which criterion this addresses

IOrchestrator

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:176

Unified orchestrator interface.

This interface provides a canonical path for all orchestration in the system, regardless of the underlying strategy.

Example

const orchestrator: IOrchestrator = factory.create('orchestrator');

const result = await orchestrator.execute(
  { type: 'task', task: myTask },
  { timeout: 30000 }
);

if (result.ok) {
  console.log('Output:', result.value.output);
}

Properties

id

readonly id: string;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:178

Unique orchestrator instance ID

type

readonly type: OrchestratorType;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:181

Orchestrator type

Methods

cancel()

cancel(executionId, reason?): Promise<Result<void, OrchestratorError>>;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:212

Cancel a running execution.

Parameters

executionId

string

Execution ID to cancel

reason?

string

Optional cancellation reason

Returns

Promise<Result<void, OrchestratorError>>

Result with void or OrchestratorError

execute()

execute(
   definition, 
   inputs, 
   options?
): Promise<Result<OrchestratorResult, OrchestratorError>>;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:191

Execute an orchestration.

Parameters

definition

OrchestratorDefinition

What to orchestrate (task, workflow, or policy)

inputs

Record<string, unknown>

Input values for the orchestration

options?

OrchestratorExecuteOptions

Execution options (timeout, budget, callbacks)

Returns

Promise<Result<OrchestratorResult, OrchestratorError>>

Result with OrchestratorResult or OrchestratorError

getHistory()?

optional getHistory(limit?): OrchestratorResult[];

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:245

Get execution history. Optional - for orchestrators that track history.

Parameters

limit?

number

Maximum number of executions to return

Returns

OrchestratorResult[]

Array of past execution results

getStatus()

getStatus(executionId): ExecutionStatus;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:203

Get status of an execution.

Parameters

executionId

string

Execution ID to check

Returns

ExecutionStatus

Current execution status

listAgents()?

optional listAgents(): {
  id: string;
  role: AgentRole;
}[];

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:236

List registered agents. Optional - not all orchestrators manage agent pools.

Returns

{ id: string; role: AgentRole; }[]

Array of registered agent IDs and roles

registerAgent()?

optional registerAgent(agent): void;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:220

Parameters

agent

IAgent

Agent to register

Returns

void

unregisterAgent()?

optional unregisterAgent(agentId): void;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:228

Unregister an agent. Optional - not all orchestrators manage agent pools.

Parameters

agentId

string

Agent ID to unregister

Returns

void

IOrchestratorFactory

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:251

Factory for creating orchestrators.

Methods

create()

create(type, config?): IOrchestrator;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:259

Create an orchestrator instance.

Parameters

type

OrchestratorType

Orchestrator type

config?

Record<string, unknown>

Optional configuration

Returns

IOrchestrator

New orchestrator instance

listTypes()

listTypes(): OrchestratorType[];

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:264

List available orchestrator types.

Returns

OrchestratorType[]

IWorkflowRouter

Defined in: packages/nexus-agents/src/orchestration/workflow-router.ts:86

Public interface for the workflow router.

Methods

getMetrics()

getMetrics(pattern?): readonly PatternMetrics[];

Defined in: packages/nexus-agents/src/orchestration/workflow-router.ts:95

Aggregates this instance’s recorded outcomes, optionally filtered by pattern.

Parameters

pattern?

WorkflowPattern

Returns

readonly PatternMetrics[]

recordOutcome()

recordOutcome(outcome): void;

Defined in: packages/nexus-agents/src/orchestration/workflow-router.ts:93

Records an execution outcome into this router instance’s buffer. Observability only — route() never reads it back (#2824).

Parameters

outcome

PatternOutcome

Returns

void

route()

route(signals, options?): WorkflowRoutingDecision;

Defined in: packages/nexus-agents/src/orchestration/workflow-router.ts:88

Routes a task to the optimal workflow pattern.

Parameters

signals

TaskSignals

options?

WorkflowRouterOptions

Returns

WorkflowRoutingDecision

NodeHookContext

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:26

Context passed to node hooks (preconditions and verification). Provides read-only access to current execution state.

Properties

nodeId

readonly nodeId: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:27

state

readonly state: Readonly<GraphState>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:28

stepNumber

readonly stepNumber: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:29

NodeResult

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:279

Result of a single node execution.

Properties

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:282

error?

readonly optional error?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:284

errorCategory?

readonly optional errorCategory?: "validation" | "internal" | "transient" | "permission" | "business";

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:289

Coarse failure category for a failed result (#3534, selective-retry). Classifies the failure so retry logic can gate on it; only set on failure.

gotoTarget?

readonly optional gotoTarget?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:311

Set when the node returned a Command with goto. The executor uses this to redirect the next runnable set instead of resolving outgoing edges. Validated against the compiled graph; unknown targets are logged + ignored. (#2425)

interrupt?

readonly optional interrupt?: Interrupt;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:304

Set when the node returned an Interrupt envelope (#1895).

isRetryable?

readonly optional isRetryable?: boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:295

Whether re-running this failed node is safe (derived from errorCategory; only transient is retry-safe by default, #3534). Selective-retry uses this to re-run transient failures and leave permanent ones alone.

nodeId

readonly nodeId: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:280

policyBlocked?

readonly optional policyBlocked?: boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:302

Set when the node failed because a policy gate denied the stage boundary (#3177). A policy block is terminal and non-retryable: it halts the pipeline even under continueOnFailure (unlike an ordinary failed node, which continue-mode tolerates).

stateUpdates

readonly stateUpdates: Partial<GraphState>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:281

status

readonly status: "success" | "failed" | "skipped" | "interrupted";

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:283

OrchestratorExecuteOptions

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:28

Orchestrator execution options.

Properties

maxSteps?

optional maxSteps?: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:34

Maximum number of steps/iterations

metadata?

optional metadata?: Record<string, unknown>;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:40

Additional metadata passed to orchestrator

onProgress?

optional onProgress?: (status) => void;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:38

Callback for progress updates

Parameters

status

ExecutionStatus

Returns

void

signal?

optional signal?: AbortSignal;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:30

Abort signal for cancellation

timeout?

optional timeout?: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:32

Maximum execution time in ms

tokenBudget?

optional tokenBudget?: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:36

Token budget for LLM calls

OrchestratorFactoryConfig

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:259

Configuration for OrchestratorFactory. (Enhanced per ADR-0014 - Orchestrator Interface Unification)

Properties

logger?

optional logger?: ILogger;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:261

Logger instance

modelAdapter?

optional modelAdapter?: IModelAdapter;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:263

Model adapter for agent-based orchestrators

orchestratorAgent?

optional orchestratorAgent?: OrchestratorAgentLike;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:274

Alias for techLead (preferred, Issue #759)

puppeteerOrchestrator?

optional puppeteerOrchestrator?: {
  execute: Promise<Result<unknown, unknown>>;
};

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:280

Pre-created PuppeteerOrchestrator instance. Input stays unknown because Puppeteer accepts arbitrary policy-shaped tasks, not the core Task type that the regular agent path requires.

execute()

execute(task): Promise<Result<unknown, unknown>>;

Parameters

task

unknown

Returns

Promise<Result<unknown, unknown>>

techLead?

optional techLead?: OrchestratorAgentLike;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:272

Pre-created orchestrator agent instance for orchestrator adapter. Narrowed from (task: unknown) to OrchestratorAgentLike so a real Orchestrator instance can be passed without an as unknown as cast (#2944). Task-input contract matches OrchestratorAdapter.setOrchestrator.

workflowConfig?

optional workflowConfig?: WorkflowEngineFactoryConfig;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:265

Workflow engine config

OrchestratorResult

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:88

Result of orchestration execution.

Properties

agentsUsed

agentsUsed: string[];

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:110

Agents involved

executedCli?

readonly optional executedCli?: "claude" | "gemini" | "codex" | "opencode";

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:117

CLI used by the last model-backed step, when known.

A run may use several CLIs after failover across steps. This field names only the last executed step’s CLI; it is not an aggregate.

executedCliSource?

readonly optional executedCliSource?: "unknown" | "executed";

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:119

Whether the executed CLI identity was measured or remains unknown.

executionId

executionId: string;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:90

Unique execution ID

orchestratorType

orchestratorType: OrchestratorType;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:92

Orchestrator type that executed

output

output: unknown;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:96

Final aggregated output

steps

steps: OrchestratorStep[];

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:94

Steps executed

tokensMeasured?

optional tokensMeasured?: boolean;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:108

Whether totalTokensUsed is a measurement (#4829).

false means no step reported usage, so the total is a placeholder 0 and NOT a count — for anything cap-shaped, reading it as a count under-counts in the dangerous direction.

totalDurationMs

totalDurationMs: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:98

Total execution time in ms

totalTokensUsed

totalTokensUsed: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:100

Total tokens consumed. Meaningful only when OrchestratorResult.tokensMeasured is not false.

OrchestratorStep

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:55

Step in an orchestration execution.

Properties

action

action: string;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:63

Step action/description

agentId

agentId: string;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:59

Agent that executed the step

durationMs

durationMs: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:67

Duration in ms

error

error: string | undefined;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:82

Error if failed

id

id: string;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:57

Step identifier

output

output: unknown;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:65

Step output

role

role: AgentRole;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:61

Agent role

status

status: "success" | "failed" | "skipped";

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:80

Status

tokensMeasured?

optional tokensMeasured?: boolean;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:78

Whether tokensUsed is a measurement (#4829).

false means no usage was reported for this step, so tokensUsed is a placeholder 0 and NOT a count. Absent means the producer predates the distinction — unknown, not measured. Mirrors ResultMetadata.tokensMeasured (#4734).

tokensUsed

tokensUsed: number;

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:69

Tokens used in this step. Meaningful only when OrchestratorStep.tokensMeasured is not false.

OutcomeStoreConfig

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:28

Extended by

PersistentOutcomeStoreConfig

Properties

maxEntries?

readonly optional maxEntries?: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:29

registry?

readonly optional registry?: ModelRegistry;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:36

Registry used to resolve vendor/family from outcome.model at write time (#2548). Defaults to the process singleton. Pass an explicit registry for tests that want deterministic resolution without touching global state.

PatternMetrics

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:138

Aggregated performance metrics for a pattern-task combination.

Properties

avgDurationMs

readonly avgDurationMs: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:144

pattern

readonly pattern: WorkflowPattern;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:139

successCount

readonly successCount: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:142

successRate

readonly successRate: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:143

taskType

readonly taskType: string;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:140

totalExecutions

readonly totalExecutions: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:141

PatternOutcome

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:122

Recorded outcome for pattern performance tracking.

Properties

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:130

Duration in milliseconds

pattern

readonly pattern: WorkflowPattern;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:124

Pattern that was used

success

readonly success: boolean;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:128

Whether execution succeeded

taskType

readonly taskType: string;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:126

Task type from analyzer

timestamp

readonly timestamp: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:132

Timestamp of recording

PerformanceSummary

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:498

Aggregated performance summary from recorded outcomes.

Properties

avgDurationMs

readonly avgDurationMs: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:501

byCategory

readonly byCategory: ReadonlyMap<string, GroupStats>;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:503

byCli

readonly byCli: ReadonlyMap<string, GroupStats>;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:502

successRate

readonly successRate: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:500

totalTasks

readonly totalTasks: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:499

PersistentOutcomeStoreConfig

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store-persistence.ts:36

Extends

OutcomeStoreConfig

Properties

dataDir?

readonly optional dataDir?: string;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store-persistence.ts:40

Override the data directory (useful for testing).

filePath?

readonly optional filePath?: string;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store-persistence.ts:38

Override the file path (useful for testing).

maxEntries?

readonly optional maxEntries?: number;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:29

Inherited from

OutcomeStoreConfig.maxEntries

registry?

readonly optional registry?: ModelRegistry;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:36

Inherited from

OutcomeStoreConfig.registry

PipelineError

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:22

Error detail when the spec pipeline fails.

Properties

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:23

stage

readonly stage: PipelineStage;

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:24

PreconditionConfig

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:51

Configuration for a precondition hook. Preconditions run before node execution. If a required precondition fails, the node is skipped.

Properties

hook

readonly hook: NodeHook;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:53

name

readonly name: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:52

required?

readonly optional required?: boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:55

If true (default), failure prevents node execution.

PreconditionOutcome

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:35

Outcome of a single precondition hook.

Properties

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:38

error?

readonly optional error?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:39

name

readonly name: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:36

passed

readonly passed: boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:37

PreconditionResult

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:29

Result of running all preconditions for a node.

Properties

passed

readonly passed: boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:30

results

readonly results: readonly PreconditionOutcome[];

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:31

RunGraphWithConsensusOptions

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:120

Options for runGraphWithConsensus.

Properties

initialState?

readonly optional initialState?: GraphState;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:133

Initial graph state.

produce

readonly produce: NodeHandler;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:125

Work node that produces the proposal — it must write the proposal text to proposalKey (default 'proposal') in its returned state patch.

proposalKey?

readonly optional proposalKey?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:129

State key the produce node writes the proposal to. Default 'proposal'.

verdictKey?

readonly optional verdictKey?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:131

State key the verdict is written to. Default 'consensusVerdict'.

voter

readonly voter: ConsensusVoter;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:127

The voter run at the gate.

ScenarioError

Defined in: packages/nexus-agents/src/orchestration/scenario-validator-types.ts:54

Error detail when scenario validation fails.

Properties

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/scenario-validator-types.ts:55

SpecExecutionError

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:22

Error detail when spec execution fails.

Properties

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:23

stage

readonly stage: ExecutionStage;

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:24

SpecExecutionResult

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:53

Result of executing a spec end-to-end.

Properties

dag

readonly dag: {
  edges: {
     from: string;
     to: string;
  }[];
  nodes: {
     capabilities: string[];
     complexity: "simple" | "complex" | "expert" | "moderate";
     dependsOn: string[];
     description: string;
     id: string;
     sourceRequirement?: string;
     type: "config" | "code" | "refactor" | "test" | "docs";
  }[];
  roots: string[];
  specTitle: string;
  totalComplexity: "simple" | "complex" | "expert" | "moderate";
};

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:57

The decomposed task DAG

edges

edges: {
  from: string;
  to: string;
}[];

Dependency edges (from must complete before to)

nodes

nodes: {
  capabilities: string[];
  complexity: "simple" | "complex" | "expert" | "moderate";
  dependsOn: string[];
  description: string;
  id: string;
  sourceRequirement?: string;
  type: "config" | "code" | "refactor" | "test" | "docs";
}[];

All subtask nodes

roots

roots: string[];

Subtask IDs that can execute in parallel (no dependencies)

specTitle

specTitle: string;

Source spec title for traceability

totalComplexity

totalComplexity: "simple" | "complex" | "expert" | "moderate" = ComplexityLevelSchema;

Total estimated complexity across all subtasks

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:63

Total execution duration in milliseconds

executed

readonly executed: boolean;

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:55

Whether configured node handlers ran instead of dry-run placeholders

outputs

readonly outputs: readonly string[];

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:59

Raw execution outputs from graph nodes

validation

readonly validation: {
  allMet: boolean;
  criteria: {
     criterion: string;
     matchedResults: string[];
     met: boolean;
     partialResults: string[];
  }[];
  metCount: number;
  satisfaction: number;
  totalCriteria: number;
};

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:61

Scenario validation against acceptance criteria

allMet

allMet: boolean;

Whether all criteria are met

criteria

criteria: {
  criterion: string;
  matchedResults: string[];
  met: boolean;
  partialResults: string[];
}[];

Per-criterion results

metCount

metCount: number;

Number of criteria met

satisfaction

satisfaction: number;

Satisfaction score from 0 (none met) to 1 (all met)

totalCriteria

totalCriteria: number;

Total acceptance criteria count

SpecParseError

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:78

Error detail when spec parsing fails.

Properties

message

readonly message: string;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:79

section?

readonly optional section?: string;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:80

StateFieldSchema

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:74

Schema entry for a single state field — name, default, and merge strategy.

Type Parameters

T

T = unknown

Properties

defaultValue

readonly defaultValue: T;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:75

reducer

readonly reducer: StateReducer<T>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:76

TaskSignals

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:52

Input signals for workflow routing decisions. Combines explicit caller hints with SharedTaskAnalyzer output.

Properties

dependencyStructure?

readonly optional dependencyStructure?: DependencyStructure;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:60

Dependency structure classification (optional hint)

description

readonly description: string;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:54

Natural language task description

forcePattern?

readonly optional forcePattern?: WorkflowPattern;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:78

Force a specific pattern (escape hatch per DevEx feedback)

hasDependencies?

readonly optional hasDependencies?: boolean;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:58

Whether subtasks depend on each other (optional hint)

isNovel?

readonly optional isNovel?: boolean;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:64

Whether this task type has been seen before

qualityRequirement?

readonly optional qualityRequirement?: QualityRequirement;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:76

Quality requirement level.

Deprecated

Never read — no routing rule consults this field, so setting it does not change the decision (pinned by workflow-router.test.ts). A caller passing it through meta-orchestrator.ts select() has it silently dropped. Removal is tracked in #5097.

requiresConsensus?

readonly optional requiresConsensus?: boolean;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:62

Whether multi-perspective consensus is needed

subtaskCount?

readonly optional subtaskCount?: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:56

Estimated number of subtasks (optional hint)

timeConstraint?

readonly optional timeConstraint?: TimeConstraint;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:66

Time urgency

VerificationResult

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:43

Result of running verification on a node.

Properties

durationMs

readonly durationMs: number;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:45

error?

readonly optional error?: string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:46

passed

readonly passed: boolean;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:44

WorkflowAdapterConfig

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:54

Configuration for WorkflowOrchestratorAdapter.

Extends

WorkflowEngineFactoryConfig

Properties

builtInTemplates?

optional builtInTemplates?: Map<string, WorkflowDefinition>;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-factory.ts:66

Pre-loaded built-in templates (if not provided, loads at creation time)

Inherited from

WorkflowEngineFactoryConfig.builtInTemplates

contextManagerConfig?

optional contextManagerConfig?: Omit<ContextManagerConfig, "budget">;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-helpers.ts:36

Inherited from

WorkflowEngineFactoryConfig.contextManagerConfig

defaultBudget?

optional defaultBudget?: ContextBudget;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-helpers.ts:37

Inherited from

WorkflowEngineFactoryConfig.defaultBudget

defaultTimeoutMs?

optional defaultTimeoutMs?: number;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-helpers.ts:33

Inherited from

WorkflowEngineFactoryConfig.defaultTimeoutMs

expertFactory?

optional expertFactory?: WorkflowExpertFactory;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-factory.ts:70

Optional expert factory for dependency injection (useful for testing)

Inherited from

WorkflowEngineFactoryConfig.expertFactory

logger?

optional logger?: ILogger;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:56

Custom logger

Overrides

WorkflowEngineFactoryConfig.logger

maxConcurrency?

optional maxConcurrency?: number;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-helpers.ts:34

Inherited from

WorkflowEngineFactoryConfig.maxConcurrency

modelAdapter?

optional modelAdapter?: IModelAdapter;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-factory.ts:68

Optional pre-configured model adapter for expert agents

Inherited from

WorkflowEngineFactoryConfig.modelAdapter

templatePaths?

optional templatePaths?: string[];

Defined in: packages/nexus-agents/src/workflows/workflow-engine-helpers.ts:35

Inherited from

WorkflowEngineFactoryConfig.templatePaths

useMockExecutor?

optional useMockExecutor?: boolean;

Defined in: packages/nexus-agents/src/workflows/workflow-engine-factory.ts:72

Use mock executor instead of real StepExecutor (default: false when expertFactory provided)

Inherited from

WorkflowEngineFactoryConfig.useMockExecutor

WorkflowRouterOptions

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:114

Options for the workflow router.

Properties

dryRun?

readonly optional dryRun?: boolean;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:116

Dry run mode — return decision without executing (per DevEx feedback)

WorkflowRoutingDecision

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:84

Routing decision with explanation.

Properties

alternatives

readonly alternatives: readonly WorkflowPattern[];

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:100

Alternative patterns that were considered

analysis

readonly analysis: TaskAnalysisResult;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:102

Analysis result from SharedTaskAnalyzer

capabilityGaps?

readonly optional capabilityGaps?: CapabilityGapReport;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:108

Capability gap report — what’s available vs what’s needed (Issue #906)

confidence

readonly confidence: number;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:96

The rule’s PRIOR for this pattern (0-1) — NOT a measurement of this task (#5957, same call as #5119). Every rule returns an authored literal, so two tasks claimed by the same rule report the same number however much the analyzer’s own signals differ. Read it as “how much this repo trusts this rule”, never as “how well this task fits”.

matchedRules

readonly matchedRules: readonly string[];

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:98

Which rules matched during selection

needsClarification?

readonly optional needsClarification?: boolean;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:104

Whether the task should be clarified before execution (Issue #904)

pattern

readonly pattern: WorkflowPattern;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:86

Selected workflow pattern

reasoning

readonly reasoning: string;

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:88

Human-readable explanation of why this pattern was selected

suggestedQuestions?

readonly optional suggestedQuestions?: readonly string[];

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:106

Suggested clarification questions when needsClarification is true

Type Aliases

CompileResult

type CompileResult = Result<CompiledGraph, GraphCompileError>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:540

Result type for graph compilation.

ComplexityLevel

type ComplexityLevel = z.infer<typeof ComplexityLevelSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:23

ConsensusVoter

type ConsensusVoter = (input) => Promise<ConsensusVerdict>;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:58

Injected voter: run a consensus round and return a verdict.

Parameters

input

ConsensusProposalInput

Returns

Promise<ConsensusVerdict>

CriterionResult

type CriterionResult = z.infer<typeof CriterionResultSchema>;

Defined in: packages/nexus-agents/src/orchestration/scenario-validator-types.ts:32

DagEdge

type DagEdge = z.infer<typeof DagEdgeSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:55

DependencyStructure

type DependencyStructure = "linear" | "dag" | "independent" | "unknown";

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:23

Dependency structure classification for a task.

ExecutionStage

type ExecutionStage = "parse" | "decompose" | "compile" | "execute" | "validate";

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:17

Which stage of execution failed.

FailureType

type FailureType = "missing_implementation" | "partial_match" | "no_output";

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer-types.ts:14

Type of failure detected for an unmet criterion.

FileReference

type FileReference = z.infer<typeof FileReferenceSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:33

GraphCompileError

type GraphCompileError = 
  | {
  nodeId: string;
  type: "duplicate_node";
}
  | {
  nodeId: string;
  referencedBy: string;
  type: "missing_node";
}
  | {
  path: readonly string[];
  type: "cycle_detected";
}
  | {
  message: string;
  type: "no_entry";
}
  | {
  nodeId: string;
  type: "unreachable_node";
}
  | {
  field: string;
  type: "missing_reducer";
};

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:508

Error type for graph compilation failures.

GraphEdge

type GraphEdge = 
  | {
  from: string;
  maxTraversals?: number;
  to: string;
  type: "fixed";
}
  | {
  from: string;
  maxTraversals?: number;
  router: (state) => string;
  targets: readonly string[];
  type: "conditional";
};

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:246

Edge types in the graph.

GraphEvent

type GraphEvent = 
  | {
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "node_started";
}
  | {
  durationMs: number;
  nodeId: string;
  resultKeys: readonly string[];
  stepNumber: number;
  timestamp: number;
  type: "node_completed";
}
  | {
  error: string;
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "node_error";
}
  | {
  detail?: string;
  nodeId: string;
  reason: "interrupted" | "skipped";
  stepNumber: number;
  timestamp: number;
  type: "node_not_completed";
}
  | {
  stepNumber: number;
  timestamp: number;
  type: "state_updated";
  updatedKeys: readonly string[];
}
  | {
  nodesExecuted: number;
  stepNumber: number;
  timestamp: number;
  type: "step_completed";
}
  | {
  durationMs: number;
  halted?: boolean;
  timestamp: number;
  totalNodes: number;
  totalSteps: number;
  type: "execution_complete";
}
  | {
  hookName: string;
  hookPhase: "precondition" | "verify";
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "hook_started";
}
  | {
  durationMs: number;
  hookName: string;
  hookPhase: "precondition" | "verify";
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "hook_completed";
}
  | {
  error: string;
  hookName: string;
  hookPhase: "precondition" | "verify";
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "hook_failed";
}
  | ContextUnavailableEvent;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:375

Discriminated union of graph lifecycle events for streaming observation.

Union Members

Type Literal

{
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "node_started";
}

Type Literal

{
  durationMs: number;
  nodeId: string;
  resultKeys: readonly string[];
  stepNumber: number;
  timestamp: number;
  type: "node_completed";
}

Type Literal

{
  error: string;
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "node_error";
}

Type Literal

{
  detail?: string;
  nodeId: string;
  reason: "interrupted" | "skipped";
  stepNumber: number;
  timestamp: number;
  type: "node_not_completed";
}

detail?

readonly optional detail?: string;

nodeId

readonly nodeId: string;

reason

readonly reason: "interrupted" | "skipped";

stepNumber

readonly stepNumber: number;

timestamp

readonly timestamp: number;

type

readonly type: "node_not_completed";

A node that did not run to completion: it paused for human input (interrupted) or its precondition refused it (skipped).

NodeResult.status is four-way, and the emitter’s else branch used to fold both of these into node_completed — so a node that produced nothing was published to the hash-chained audit trail as “completed in 0ms”, and a skipped result’s error string was dropped entirely because the completion event has no slot for it.

Type Literal

{
  stepNumber: number;
  timestamp: number;
  type: "state_updated";
  updatedKeys: readonly string[];
}

Type Literal

{
  nodesExecuted: number;
  stepNumber: number;
  timestamp: number;
  type: "step_completed";
}

Type Literal

{
  durationMs: number;
  halted?: boolean;
  timestamp: number;
  totalNodes: number;
  totalSteps: number;
  type: "execution_complete";
}

durationMs

readonly durationMs: number;

halted?

readonly optional halted?: boolean;

True when the run stopped awaiting human input rather than finishing.

runSuperStepLoop returns undefined on the interrupt path, which is the same “loop ended normally” signal as running out of runnable nodes, so this event was emitted unconditionally BEFORE the halt check. A paused run published a completion indistinguishable from a finished one, and halted — the truthful marker — lives on the returned Result, which an onEvent consumer such as the audit bridge never sees.

timestamp

readonly timestamp: number;

totalNodes

readonly totalNodes: number;

totalSteps

readonly totalSteps: number;

type

readonly type: "execution_complete";

Type Literal

{
  hookName: string;
  hookPhase: "precondition" | "verify";
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "hook_started";
}

Type Literal

{
  durationMs: number;
  hookName: string;
  hookPhase: "precondition" | "verify";
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "hook_completed";
}

Type Literal

{
  error: string;
  hookName: string;
  hookPhase: "precondition" | "verify";
  nodeId: string;
  stepNumber: number;
  timestamp: number;
  type: "hook_failed";
}

ContextUnavailableEvent

GraphState

type GraphState = Record<string, unknown>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:87

Flattened state values at runtime (one value per field).

IssueReference

type IssueReference = z.infer<typeof IssueReferenceSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:22

KnownSection

type KnownSection = typeof KNOWN_SECTIONS[number];

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:97

NodeHandler

type NodeHandler = (state, ctx?) => Promise<NodeReturn>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:195

Handler function for a graph node. Receives current state and an optional per-run context, returns either:

Partial<GraphState> (legacy, common case) — merged via reducers
Command — update portion is merged via reducers
Interrupt — pauses the graph; emits checkpoint with interrupt metadata

The ctx parameter is optional — pre-#1895 handlers that take only state remain valid (additive widening).

Parameters

state

Readonly<GraphState>

ctx?

NodeContext

Returns

Promise<NodeReturn>

NodeHandlerFactory

type NodeHandlerFactory = (node) => NodeHandler;

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:38

Factory that creates graph node handlers from subtask nodes. Allows plugging in different execution strategies (dry-run, expert delegation, etc.).

(Source: Issue #857 — Pluggable node execution for AI Software Factory)

Parameters

node

SubtaskNode

Returns

NodeHandler

NodeHook

type NodeHook = (ctx) => Promise<Result<void, HookError>>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:44

Hook function signature. Returns ok(void) on success, err(HookError) on failure.

Parameters

ctx

NodeHookContext

Returns

Promise<Result<void, HookError>>

OrchestratorDefinition

type OrchestratorDefinition = 
  | {
  task: Task;
  type: "task";
}
  | {
  templatePath: string;
  type: "workflow";
}
  | {
  initialState: Record<string, unknown>;
  policyId: string;
  type: "policy";
};

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:47

Orchestrator definition - the input that defines what to orchestrate. This is a discriminated union to support different orchestration styles.

OrchestratorErrorCode

type OrchestratorErrorCode = 
  | "TIMEOUT"
  | "CANCELLED"
  | "STEP_FAILED"
  | "AGENT_ERROR"
  | "BUDGET_EXCEEDED"
  | "INVALID_DEFINITION"
  | "NO_AGENTS_AVAILABLE"
  | "POLICY_VIOLATION";

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:146

Error codes for orchestrator failures.

OrchestratorType

type OrchestratorType = "orchestrator" | "puppeteer" | "workflow" | "custom";

Defined in: packages/nexus-agents/src/core/types/orchestrator.ts:23

Orchestration strategy type.

OutcomeFailureCategory

type OutcomeFailureCategory = z.infer<typeof OutcomeFailureCategorySchema>;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:199

Category of failure for failed outcomes (Issue #1025).

OutcomeTaskRecord

type OutcomeTaskRecord = z.infer<typeof OutcomeTaskSchema>;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:187

A single recorded task execution outcome.

ParsedSpec

type ParsedSpec = z.infer<typeof ParsedSpecSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:73

PipelineStage

type PipelineStage = "parse" | "decompose" | "compile";

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline-types.ts:17

Which stage of the pipeline failed.

QualityRequirement

type QualityRequirement = "best-effort" | "high" | "critical";

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:46

Quality requirement level.

Deprecated

Never read. No routing rule consults TaskSignals.qualityRequirement; the value is accepted and silently dropped (a caller passing it through meta-orchestrator.ts select() has it spread into TaskSignals and ignored). Do not confuse it with the analyzer-extracted analysis.constraints.quality string, which IS read for clarification prompts. Removal from the public surface is tracked in #5097.

ScenarioResult

type ScenarioResult = z.infer<typeof ScenarioResultSchema>;

Defined in: packages/nexus-agents/src/orchestration/scenario-validator-types.ts:49

SpecExecutionOptions

type SpecExecutionOptions = CompileOptions & {
  onProgress?: () => void;
  signal?: AbortSignal;
};

Defined in: packages/nexus-agents/src/orchestration/spec-executor-types.ts:31

Options for spec execution. (Source: Issue #857 — Pluggable node execution)

Type Declaration

onProgress?

readonly optional onProgress?: () => void;

Called on every graph event the compiled spec’s execution emits (node started, step completed, …) — the async-job liveness heartbeat for execute_spec (#6162), whose body emits nothing on the pipeline bus.

Returns

void

signal?

readonly optional signal?: AbortSignal;

Cancels the run at the next step boundary (#6305). Handed to the graph executor, which checks it before each super-step, and checked again once the graph returns — so a cancel is always reported as a Spec execution cancelled error at stage execute, never as a partial result that goes on to validation. A node already running is not interrupted. execute_spec threads cancel_job’s signal here. Absent: the run is not cancellable.

StateReducer

type StateReducer<T> = 
  | {
  type: "overwrite";
}
  | {
  type: "append";
}
  | {
  merge: (existing, incoming) => T;
  type: "custom";
};

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:66

State reducer controls how values merge when multiple nodes write to the same state field. Inspired by LangGraph’s Annotated reducers.

Type Parameters

T

T = unknown

StateSchema

type StateSchema = Record<string, StateFieldSchema>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:82

State schema defines all fields and their reducers.

SubtaskNode

type SubtaskNode = z.infer<typeof SubtaskNodeSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:44

SubtaskType

type SubtaskType = z.infer<typeof SubtaskTypeSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:17

TaskDag

type TaskDag = z.infer<typeof TaskDagSchema>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:72

TimeConstraint

type TimeConstraint = "urgent" | "normal" | "relaxed";

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:34

Time constraint urgency level.

'relaxed' is accepted as a caller hint but no inference path produces it: enrichSignals in workflow-router.ts emits only 'urgent' or 'normal', and the sole consumer (ruleNovelTask) tests only for 'urgent', so 'relaxed' and 'normal' route identically. Pinned by workflow-router.test.ts (#5097).

Trend

type Trend = "improving" | "declining" | "stable";

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:21

Direction of performance change over time.

WorkflowPattern

type WorkflowPattern = "sequential" | "wave" | "graph" | "consensus" | "aflow" | "puppeteer";

Defined in: packages/nexus-agents/src/orchestration/workflow-router-types.ts:18

Orchestration patterns available in nexus-agents. Each maps to a concrete execution module.

Variables

CHECKPOINT_SCHEMA_VERSION

const CHECKPOINT_SCHEMA_VERSION: 1 = 1;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-types.ts:57

Schema version for forward compatibility.

ComplexityLevelSchema

const ComplexityLevelSchema: ZodEnum<{
  complex: "complex";
  expert: "expert";
  moderate: "moderate";
  simple: "simple";
}>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:22

Complexity level for a subtask.

CriterionResultSchema

const CriterionResultSchema: ZodObject<{
  criterion: ZodString;
  matchedResults: ZodArray<ZodString>;
  met: ZodBoolean;
  partialResults: ZodArray<ZodString>;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/scenario-validator-types.ts:16

Result of checking a single acceptance criterion.

DagEdgeSchema

const DagEdgeSchema: ZodObject<{
  from: ZodString;
  to: ZodString;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:49

A directed edge in the dependency DAG.

END

const END: "__END__";

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:241

Special sentinel for the graph exit point.

FileReferenceSchema

const FileReferenceSchema: ZodObject<{
  line: ZodOptional<ZodNumber>;
  path: ZodString;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:27

A reference to a file path extracted from spec text.

IssueReferenceSchema

const IssueReferenceSchema: ZodObject<{
  number: ZodNumber;
  raw: ZodString;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:16

A reference to a GitHub issue or PR extracted from spec text.

KNOWN_SECTIONS

const KNOWN_SECTIONS: readonly ["overview", "requirements", "acceptance criteria", "constraints", "goal", "description", "design", "dependencies"];

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:86

Known section headings that the parser recognizes.

OutcomeFailureCategorySchema

const OutcomeFailureCategorySchema: ZodEnum<{
  adapter_unavailable: "adapter_unavailable";
  authentication: "authentication";
  connection: "connection";
  crash: "crash";
  execution: "execution";
  generic: "generic";
  parse: "parse";
  rate_limit: "rate_limit";
  timeout: "timeout";
  unknown: "unknown";
  validation: "validation";
}>;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:32

Failure category for failed task outcomes (Issue #1025).

OutcomeTaskSchema

const OutcomeTaskSchema: ZodObject<{
  baselineId: ZodOptional<ZodString>;
  category: ZodEnum<{
     architecture: "architecture";
     code_generation: "code_generation";
     code_review: "code_review";
     devops: "devops";
     documentation: "documentation";
     exploration: "exploration";
     planning: "planning";
     research: "research";
     security_review: "security_review";
     testing: "testing";
  }>;
  categorySource: ZodOptional<ZodEnum<{
     defaulted: "defaulted";
     detected: "detected";
  }>>;
  cli: ZodUnion<readonly [ZodEnum<{
     claude: "claude";
     codex: "codex";
     gemini: "gemini";
     opencode: "opencode";
   }>, ZodEnum<{
     api:anthropic: "api:anthropic";
     api:custom-openai: "api:custom-openai";
     api:google: "api:google";
     api:openai: "api:openai";
  }>, ZodLiteral<"unknown">]>;
  cliSource: ZodOptional<ZodEnum<{
     category-default: "category-default";
     executed: "executed";
  }>>;
  costUsd: ZodOptional<ZodNumber>;
  durationMs: ZodNumber;
  errorMessage: ZodOptional<ZodString>;
  failureCategory: ZodOptional<ZodEnum<{
     adapter_unavailable: "adapter_unavailable";
     authentication: "authentication";
     connection: "connection";
     crash: "crash";
     execution: "execution";
     generic: "generic";
     parse: "parse";
     rate_limit: "rate_limit";
     timeout: "timeout";
     unknown: "unknown";
     validation: "validation";
  }>>;
  family: ZodOptional<ZodString>;
  id: ZodString;
  model: ZodString;
  priceBasis: ZodOptional<ZodEnum<{
     list: "list";
     unknown: "unknown";
  }>>;
  qualitySignals: ZodOptional<ZodArray<ZodString>>;
  requestId: ZodOptional<ZodString>;
  retryCount: ZodOptional<ZodNumber>;
  routedBy: ZodOptional<ZodEnum<{
     composite-router: "composite-router";
  }>>;
  routingStage: ZodOptional<ZodString>;
  servedModel: ZodOptional<ZodString>;
  source: ZodEnum<{
     consensus: "consensus";
     delegate: "delegate";
     manual: "manual";
  }>;
  success: ZodBoolean;
  timestamp: ZodString;
  traceId: ZodOptional<ZodString>;
  triageAction: ZodOptional<ZodString>;
  vendor: ZodOptional<ZodString>;
  voterRole: ZodOptional<ZodString>;
  wasRetried: ZodOptional<ZodBoolean>;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:92

Schema for a single recorded task outcome.

ParsedSpecSchema

const ParsedSpecSchema: ZodObject<{
  acceptanceCriteria: ZodArray<ZodString>;
  constraints: ZodArray<ZodString>;
  fileReferences: ZodArray<ZodObject<{
     line: ZodOptional<ZodNumber>;
     path: ZodString;
  }, $strip>>;
  issueReferences: ZodArray<ZodObject<{
     number: ZodNumber;
     raw: ZodString;
  }, $strip>>;
  missingSections: ZodArray<ZodString>;
  overview: ZodString;
  rawMarkdown: ZodString;
  requirements: ZodArray<ZodString>;
  techStack: ZodOptional<ZodObject<{
     framework: ZodOptional<ZodString>;
     language: ZodOptional<ZodString>;
     packageManager: ZodOptional<ZodString>;
  }, $strip>>;
  title: ZodString;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser-types.ts:51

Parsed specification from a markdown document.

ScenarioResultSchema

const ScenarioResultSchema: ZodObject<{
  allMet: ZodBoolean;
  criteria: ZodArray<ZodObject<{
     criterion: ZodString;
     matchedResults: ZodArray<ZodString>;
     met: ZodBoolean;
     partialResults: ZodArray<ZodString>;
  }, $strip>>;
  metCount: ZodNumber;
  satisfaction: ZodNumber;
  totalCriteria: ZodNumber;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/scenario-validator-types.ts:37

Overall scenario validation result.

START

const START: "__START__";

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:238

Special sentinel for the graph entry point.

SubtaskNodeSchema

const SubtaskNodeSchema: ZodObject<{
  capabilities: ZodArray<ZodString>;
  complexity: ZodEnum<{
     complex: "complex";
     expert: "expert";
     moderate: "moderate";
     simple: "simple";
  }>;
  dependsOn: ZodArray<ZodString>;
  description: ZodString;
  id: ZodString;
  sourceRequirement: ZodOptional<ZodString>;
  type: ZodEnum<{
     code: "code";
     config: "config";
     docs: "docs";
     refactor: "refactor";
     test: "test";
  }>;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:28

A single decomposed subtask node in the DAG.

SubtaskTypeSchema

const SubtaskTypeSchema: ZodEnum<{
  code: "code";
  config: "config";
  docs: "docs";
  refactor: "refactor";
  test: "test";
}>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:16

The type of work a subtask represents.

TaskDagSchema

const TaskDagSchema: ZodObject<{
  edges: ZodArray<ZodObject<{
     from: ZodString;
     to: ZodString;
  }, $strip>>;
  nodes: ZodArray<ZodObject<{
     capabilities: ZodArray<ZodString>;
     complexity: ZodEnum<{
        complex: "complex";
        expert: "expert";
        moderate: "moderate";
        simple: "simple";
     }>;
     dependsOn: ZodArray<ZodString>;
     description: ZodString;
     id: ZodString;
     sourceRequirement: ZodOptional<ZodString>;
     type: ZodEnum<{
        code: "code";
        config: "config";
        docs: "docs";
        refactor: "refactor";
        test: "test";
     }>;
  }, $strip>>;
  roots: ZodArray<ZodString>;
  specTitle: ZodString;
  totalComplexity: ZodEnum<{
     complex: "complex";
     expert: "expert";
     moderate: "moderate";
     simple: "simple";
  }>;
}, $strip>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer-types.ts:60

The complete dependency DAG produced by decomposition.

Functions

analyzeFailures()

function analyzeFailures(executionResult): Result<FailureAnalysis, never>;

Defined in: packages/nexus-agents/src/orchestration/failure-analyzer.ts:25

Analyzes execution results for failure patterns.

Parameters

executionResult

SpecExecutionResult

Returns

Result<FailureAnalysis, never>

append()

function append<T>(defaultValue?): StateFieldSchema<T[]>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:356

Creates an append reducer for array fields.

Type Parameters

T

T

Parameters

defaultValue?

T[] = []

Returns

StateFieldSchema<T[]>

categorizeOutcomeError()

function categorizeOutcomeError(error): 
  | "unknown"
  | "timeout"
  | "parse"
  | "connection"
  | "execution"
  | "rate_limit"
  | "validation"
  | "crash"
  | "authentication"
  | "adapter_unavailable"
  | "generic";

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:442

Classifies an error into an OutcomeFailureCategory for recording.

Parameters

error

unknown

Returns

categorizeOutcomeErrorMessage()

function categorizeOutcomeErrorMessage(msg): 
  | "unknown"
  | "timeout"
  | "parse"
  | "connection"
  | "execution"
  | "rate_limit"
  | "validation"
  | "crash"
  | "authentication"
  | "adapter_unavailable"
  | "generic";

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:455

Classifies an error message string into an OutcomeFailureCategory.

Parameters

msg

string

Returns

compileSpecToGraph()

function compileSpecToGraph(markdown, options?): Result<CompiledGraph & {
  executed: boolean;
}, PipelineError>;

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline.ts:44

Compiles a markdown specification into an executable graph.

Pipeline: markdown → parseSpec → decomposeSpec → GraphBuilder → CompiledGraph

Parameters

markdown

string

Raw markdown specification text

options?

CompileOptions

Optional compile options (handler factory, etc.)

Returns

Result<CompiledGraph & { executed: boolean; }, PipelineError>

computeAdaptiveThresholds()

function computeAdaptiveThresholds(
   store, 
   cli, 
   category
): AdaptiveThresholdResult;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:65

Computes adaptive thresholds for a routing arm + category pair from outcome data. cli is the arm the rows were recorded under: a CLI slot or, since #6554, an api:* arm — this reads that arm’s rows only, never its slot’s.

Below cold start threshold: returns defaults with zero confidence. Above threshold: adjusts baseline toward observed rate, scales max bonus by confidence, and detects trend.

Parameters

store

OutcomeStore

cli

RoutingArmId

Returns

AdaptiveThresholdResult

createCheckpoint()

function createCheckpoint(opts): Checkpoint;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:137

Creates a checkpoint from the current execution state.

Parameters

opts

completedResults

readonly NodeResult[]

executionId

string

interrupt?

CheckpointInterrupt

Set when persisting an interrupt-flavored checkpoint (#1895).

metadata?

Record<string, unknown>

pendingNodeIds

readonly string[]

state

Readonly<GraphState>

stepNumber

number

Returns

Checkpoint

createCheckpointStore()

function createCheckpointStore(): ICheckpointStore;

Defined in: packages/nexus-agents/src/orchestration/graph/checkpoint-store.ts:164

Creates a new InMemoryCheckpointStore.

Returns

ICheckpointStore

createConsensusGateNode()

function createConsensusGateNode(options): NodeHandler;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:97

Build a NodeHandler that runs a consensus gate and writes the typed verdict to verdictKey in graph state. Pair it with addConditionalEdge on state[verdictKey].outcome to route approve → continue, reject → halt/revise.

Parameters

options

ConsensusGateNodeOptions

Returns

NodeHandler

createDryRunHandler()

function createDryRunHandler(node): (state) => Promise<Partial<GraphState>>;

Defined in: packages/nexus-agents/src/orchestration/spec-pipeline.ts:24

Creates the default dry-run node handler for a subtask. Returns a placeholder string describing the subtask.

Parameters

node

capabilities

string[] = ...

Required capabilities for the executing agent

complexity

"simple" | "complex" | "expert" | "moderate" = ComplexityLevelSchema

Estimated complexity

dependsOn

string[] = ...

IDs of subtasks this depends on

description

string = ...

Human-readable description of what this subtask does

id

string = ...

Unique identifier for this subtask

sourceRequirement?

string = ...

Source requirement text that generated this subtask

type

"config" | "code" | "refactor" | "test" | "docs" = SubtaskTypeSchema

The type of work

Returns

(state) => Promise<Partial<GraphState>>

createOrchestratorFactory()

function createOrchestratorFactory(config?): Promise<IOrchestratorFactory>;

Defined in: packages/nexus-agents/src/orchestration/orchestrator-factory.ts:388

Creates an OrchestratorFactory with async initialization.

This is the recommended way to create an OrchestratorFactory as it properly initializes all async dependencies like the WorkflowEngine.

Parameters

config?

OrchestratorFactoryConfig

Factory configuration

Returns

Promise<IOrchestratorFactory>

Promise resolving to initialized OrchestratorFactory

Example

const factory = await createOrchestratorFactory();
const types = factory.listTypes(); // ['workflow']

const orchestrator = factory.create('workflow');
const result = await orchestrator.execute(...);

createStateComparisonVerifier()

function createStateComparisonVerifier(fields): (preState) => NodeHook;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:141

Creates a state-comparison verification hook. Checks that specified state fields changed after node execution.

Parameters

fields

readonly string[]

Returns

(preState) => NodeHook

createStateGuard()

function createStateGuard(
   name, 
   predicate, 
   errorMessage
): PreconditionConfig;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:169

Creates a precondition that checks state field values. Useful for enforcing invariants before node execution.

Parameters

name

string

predicate

(state) => boolean

errorMessage

string

Returns

PreconditionConfig

createWorkflowRouter()

function createWorkflowRouter(options?): IWorkflowRouter;

Defined in: packages/nexus-agents/src/orchestration/workflow-router.ts:64

Creates a workflow pattern router.

Analyzes task characteristics and selects the optimal orchestration pattern using a rule-based classification system.

Scope of recordOutcome / getMetrics (#2824): the recorded PatternOutcomes live in a buffer owned by this router instance. route() is a deterministic, rule-based classifier — it does NOT consume recorded outcomes, so there is no per-instance learning to “lose”, and nothing to aggregate across processes. The pair is an observability surface only. If cross-process pattern metrics are ever needed, add a dedicated consumer that writes to a shared OutcomeStore rather than widening this router’s responsibility.

Parameters

options?

analyzer?

ISharedTaskAnalyzer

logger?

ILogger

Returns

IWorkflowRouter

customReducer()

function customReducer<T>(defaultValue, merge): StateFieldSchema<T>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:361

Creates a custom reducer with a merge function.

Type Parameters

T

T

Parameters

defaultValue

T

merge

(existing, incoming) => T

Returns

StateFieldSchema<T>

decomposeSpec()

function decomposeSpec(spec): Result<{
  edges: {
     from: string;
     to: string;
  }[];
  nodes: {
     capabilities: string[];
     complexity: "simple" | "complex" | "expert" | "moderate";
     dependsOn: string[];
     description: string;
     id: string;
     sourceRequirement?: string;
     type: "config" | "code" | "refactor" | "test" | "docs";
  }[];
  roots: string[];
  specTitle: string;
  totalComplexity: "simple" | "complex" | "expert" | "moderate";
}, DecomposeError>;

Defined in: packages/nexus-agents/src/orchestration/spec-decomposer.ts:43

Decomposes a parsed spec into a dependency DAG of typed subtasks.

Parameters

spec

acceptanceCriteria

string[] = ...

Acceptance criteria (checklist items)

constraints

string[] = ...

Constraints or limitations

fileReferences

{ line?: number; path: string; }[] = ...

File path references found in the spec

issueReferences

{ number: number; raw: string; }[] = ...

Issue/PR references found in the spec

missingSections

string[] = ...

Sections that were missing from the spec

overview

string = ...

Overview/description text

rawMarkdown

string = ...

Raw markdown source

requirements

string[] = ...

List of requirements

techStack?

{ framework?: string; language?: string; packageManager?: string; } = ...

Inferred technology stack

techStack.framework?

string = ...

Framework or library

techStack.language?

string = ...

Programming language

techStack.packageManager?

string = ...

Package manager

title

string = ...

Spec title (from first H1 or H2 heading)

Returns

Result<{ edges: { from: string; to: string; }[]; nodes: { capabilities: string[]; complexity: "simple" | "complex" | "expert" | "moderate"; dependsOn: string[]; description: string; id: string; sourceRequirement?: string; type: "config" | "code" | "refactor" | "test" | "docs"; }[]; roots: string[]; specTitle: string; totalComplexity: "simple" | "complex" | "expert" | "moderate"; }, DecomposeError>

detectTrend()

function detectTrend(outcomes, windowSize?): Trend;

Defined in: packages/nexus-agents/src/orchestration/outcomes/adaptive-thresholds.ts:110

Detects performance trend by comparing recent vs historical success rates.

Splits outcomes into two windows of windowSize (default 25). If fewer than 2 * windowSize outcomes, uses half-split.

Parameters

outcomes

windowSize?

number = DEFAULT_WINDOW_SIZE

Returns

Trend

emitExecutionComplete()

function emitExecutionComplete(
   totalSteps, 
   totalNodes, 
   durationMs, 
   options?, 
   halted?
): void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-events.ts:147

Emits execution_complete event when graph execution finishes.

Parameters

totalSteps

number

totalNodes

number

durationMs

number

options?

GraphExecuteOptions

halted?

boolean

Returns

void

emitNodeResults()

function emitNodeResults(
   ctx, 
   results, 
   options?
): void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-events.ts:41

Emits node_completed or node_error events for each result.

Parameters

ctx

StepContext

results

readonly NodeResult[]

options?

GraphExecuteOptions

Returns

void

emitNodeStarted()

function emitNodeStarted(ctx, options?): void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-events.ts:31

Emits node_started events for all nodes about to execute.

Parameters

ctx

StepContext

options?

GraphExecuteOptions

Returns

void

emitStateUpdated()

function emitStateUpdated(
   ctx, 
   results, 
   options?
): void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-events.ts:88

Emits state_updated event with deduplicated keys from successful results.

Parameters

ctx

StepContext

results

readonly NodeResult[]

options?

GraphExecuteOptions

Returns

void

emitStepCompleted()

function emitStepCompleted(
   ctx, 
   nodesExecuted, 
   options?
): void;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-events.ts:110

Emits step_completed event after a super-step finishes.

Parameters

ctx

StepContext

nodesExecuted

number

options?

GraphExecuteOptions

Returns

void

executeGraph()

function executeGraph(
   graph, 
   initialInputs, 
   options?
): Promise<Result<GraphExecutionResult, Error>>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-executor.ts:156

Executes a compiled graph workflow.

Uses a super-step model: each step finds all runnable nodes, executes them in parallel, merges state, then resolves edges to find the next set of runnable nodes.

Parameters

graph

CompiledGraph

initialInputs

Readonly<GraphState>

options?

GraphExecuteOptions

Returns

Promise<Result<GraphExecutionResult, Error>>

executeSpec()

function executeSpec(markdown, options?): Promise<Result<SpecExecutionResult, SpecExecutionError>>;

Defined in: packages/nexus-agents/src/orchestration/spec-executor.ts:28

Executes a markdown specification end-to-end.

Parameters

markdown

string

options?

SpecExecutionOptions

Returns

Promise<Result<SpecExecutionResult, SpecExecutionError>>

extractNonErrorMessage()

function extractNonErrorMessage(error): string | undefined;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-types.ts:421

Extracts a classifiable message string from a non-Error value. Returns undefined if the value is truly unclassifiable (#1466).

Parameters

error

unknown

Returns

string | undefined

formatCompileError()

function formatCompileError(error): string;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-types.ts:517

Format a compile error as a human-readable string.

Parameters

error

GraphCompileError

Returns

string

getOutcomeStore()

function getOutcomeStore(): OutcomeStore;

Defined in: packages/nexus-agents/src/orchestration/outcomes/outcome-store.ts:278

Get the shared OutcomeStore singleton. Returns PersistentOutcomeStore when NEXUS_PERSIST_LEARNING=true and the factory has been registered (import outcome-store-persistence first).

Returns

OutcomeStore

overwrite()

function overwrite<T>(defaultValue): StateFieldSchema<T>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-builder.ts:351

Creates an overwrite reducer (last write wins).

Type Parameters

T

T

Parameters

defaultValue

T

Returns

StateFieldSchema<T>

parseSpec()

function parseSpec(markdown): Result<{
  acceptanceCriteria: string[];
  constraints: string[];
  fileReferences: {
     line?: number;
     path: string;
  }[];
  issueReferences: {
     number: number;
     raw: string;
  }[];
  missingSections: string[];
  overview: string;
  rawMarkdown: string;
  requirements: string[];
  techStack?: {
     framework?: string;
     language?: string;
     packageManager?: string;
  };
  title: string;
}, SpecParseError>;

Defined in: packages/nexus-agents/src/orchestration/spec-parser.ts:36

Parses a markdown specification into a typed ParsedSpec structure.

Extracts title, overview, requirements, acceptance criteria, constraints, and references from a well-structured markdown document.

Parameters

markdown

string

Returns

Result<{ acceptanceCriteria: string[]; constraints: string[]; fileReferences: { line?: number; path: string; }[]; issueReferences: { number: number; raw: string; }[]; missingSections: string[]; overview: string; rawMarkdown: string; requirements: string[]; techStack?: { framework?: string; language?: string; packageManager?: string; }; title: string; }, SpecParseError>

runConsensusGate()

function runConsensusGate(voter, input): Promise<ConsensusVerdict>;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:66

Run the consensus gate (the single shared implementation). On any voter error/timeout this fails CLOSED to a rejected verdict — a gate must never let unreviewed work through on an error. The voter receives only the proposal/context (no secrets, no ambient state).

Parameters

voter

ConsensusVoter

input

ConsensusProposalInput

Returns

Promise<ConsensusVerdict>

runGraphWithConsensus()

function runGraphWithConsensus(options): Promise<Result<{
  execution: GraphExecutionResult;
  verdict: ConsensusVerdict | undefined;
}, Error>>;

Defined in: packages/nexus-agents/src/orchestration/graph/consensus-node.ts:144

Convenience composition (#3267): run a single work node, then a consensus gate over its output — START → produce → consensus → END — and return the execution result plus the typed verdict. The proposalKey/verdictKey state channels are declared automatically. For richer control flow (branch on the verdict, loop on reject, multiple gates) use createConsensusGateNode with GraphBuilder + addConditionalEdge directly.

Parameters

options

RunGraphWithConsensusOptions

Returns

Promise<Result<{ execution: GraphExecutionResult; verdict: ConsensusVerdict | undefined; }, Error>>

runPreconditions()

function runPreconditions(
   node, 
   state, 
   stepNumber, 
   options?
): Promise<PreconditionResult>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:58

Runs all precondition hooks for a node. If any required precondition fails, returns passed=false. Optional precondition failures are logged but don’t block execution.

Parameters

node

GraphNode

state

Readonly<GraphState>

stepNumber

number

options?

GraphExecuteOptions

Returns

Promise<PreconditionResult>

runVerification()

function runVerification(
   node, 
   state, 
   stepNumber, 
   options?
): Promise<VerificationResult>;

Defined in: packages/nexus-agents/src/orchestration/graph/graph-hooks.ts:102

Runs the post-step verification hook for a node. Returns the verification result.

Parameters

node

GraphNode

state

Readonly<GraphState>

stepNumber

number

options?

GraphExecuteOptions

Returns

Promise<VerificationResult>

validateScenario()

function validateScenario(spec, results): Result<{
  allMet: boolean;
  criteria: {
     criterion: string;
     matchedResults: string[];
     met: boolean;
     partialResults: string[];
  }[];
  metCount: number;
  satisfaction: number;
  totalCriteria: number;
}, ScenarioError>;

Defined in: packages/nexus-agents/src/orchestration/scenario-validator.ts:69

Validates execution results against a spec’s acceptance criteria.

Parameters

spec

acceptanceCriteria

string[] = ...

Acceptance criteria (checklist items)

constraints

string[] = ...

Constraints or limitations

fileReferences

{ line?: number; path: string; }[] = ...

File path references found in the spec

issueReferences

{ number: number; raw: string; }[] = ...

Issue/PR references found in the spec

missingSections

string[] = ...

Sections that were missing from the spec

overview

string = ...

Overview/description text

rawMarkdown

string = ...

Raw markdown source

requirements

string[] = ...

List of requirements

techStack?

{ framework?: string; language?: string; packageManager?: string; } = ...

Inferred technology stack

techStack.framework?

string = ...

Framework or library

techStack.language?

string = ...

Programming language

techStack.packageManager?

string = ...

Package manager

title

string = ...

Spec title (from first H1 or H2 heading)

results

readonly string[]

Returns

Result<{ allMet: boolean; criteria: { criterion: string; matchedResults: string[]; met: boolean; partialResults: string[]; }[]; metCount: number; satisfaction: number; totalCriteria: number; }, ScenarioError>