Registry↗Dashboard↗

Execution

Run definitions across the four-layer hierarchy. Each method resolves a definition by name (or name@version ref), executes it, and — when tracking is enabled — submits the result. Use the typed run* methods when you know the definition type; use run() to auto-route.

6 methods

client.runAgent()

Direct agent execution with call-time options. Use for interactive/ad-hoc validation, experimentation, and development. For reproducible CI runs, use runCommand() instead. Throws ConfigurationError if the resolved definition is not an agent, IntegrityError if integrity pins are supplied and do not match, and MaxStepsExhaustedError if the tool loop exhausts its step ceiling with empty output.

Requires authentication

Parameters

namerequiredstring

Agent name or name@version ref (e.g. 'code-validator' or 'code-validator@1.2.0').

targetOrInputrequiredstring | ExecutionInput

Absolute path to the project directory, or a full ExecutionInput object ({ target, prompt?, options? }).

optionsoptionalExecutionOptions

Runtime overrides.

Return Fields

typerequired'agent'

Discriminator — always 'agent'.

scorerequirednumber | null

Score (0-100), or null for generators/executors that produce artifacts not scores. Null iff maxScore is null.

maxScorerequirednumber | null

Maximum possible score, or null iff score is null.

decisionrequiredstring

Final decision token (e.g. PASS / DEPLOY / EXAMINED).

decisionCategoryoptionalDecisionCategory

Normalized decision category from the agent's vocabulary. Prefer this over re-classifying.

categoriesoptionalArray<{ name; score; maxScore; findings }>

Scored categories with findings.

recommendationsrequiredRecommendation[]

All recommendations produced by the agent.

completenessoptionalCompleteness

Whether the run finished its work (complete / partial / failed), independent of score.

degradationMarkersoptionalDegradationMarker[]

Typed markers for any degradation during the run (e.g. near-exhaustion).

metricsrequiredExecutionMetrics

Token usage, duration, and cost metrics.

rawOutputoptionalstring

Raw LLM output text — the agent's full report before parsing.

dashboardUrloptionalstring

Dashboard URL, populated after tracking submission.

trackingFailedoptionalboolean

True when tracking submission failed — dashboardUrl will be undefined. The run itself still resolved successfully.

trackingErroroptionalTrackingError

Typed reason the tracking submission failed (set alongside trackingFailed): stable machine `code` (e.g. 'PROJECT_LIMIT'), `statusCode`, `message`, `requestId`, and structured `details` (e.g. upgradeUrl). Match on `code`, not `message`.

runAgent(name: string, targetOrInput: string | ExecutionInput, options?: ExecutionOptions): Promise<AgentResult>
typescript
import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: process.env.ULUOPS_API_KEY,
});

// Simple form — agent name + target path
const result = await client.runAgent('code-validator', './src', {
  model: 'sonnet',
  thresholds: { pass: 80 },
});

console.log(`${result.decision} · ${result.score}`);

// With a full input object and an integrity pin
await client.runAgent('security-analyst', { target: './src' }, {
  model: 'opus',
  expectedHash: 'sha256:…',
});
Response Type
// AgentResult
{
  type: 'agent';
  score: number | null;
  maxScore: number | null;
  decision: string;
  decisionCategory?: DecisionCategory;
  categories?: Array<{ name; score; maxScore; findings }>;
  recommendations: Recommendation[];
  completeness?: Completeness;
  degradationMarkers?: DegradationMarker[];
  metrics: ExecutionMetrics;
  rawOutput?: string;
  dashboardUrl?: string;
  trackingFailed?: boolean;
  trackingError?: TrackingError;
}

client.runCommand()

Execute a saved command configuration. Uses model, thresholds, and aggregation from the command definition — ideal for CI/CD and team-standardized validation. Pass overrides.model to override the definition's default model at runtime. Throws ConfigurationError if the definition is not a command, PreflightError if a preflight check fails, and ExecutionError if an underlying agent execution fails.

Requires authentication

Parameters

namerequiredstring

Command name or name@version ref.

inputrequiredExecutionInput

Execution input.

overridesoptional{ model?: string }

Runtime overrides.

Return Fields

typerequired'command'

Discriminator.

decisionrequiredstring

Aggregated final decision.

scoreoptionalnumber | null

Aggregated score (0-100), or null for scoreless (executor) commands. Validators only.

categoriesoptionalCategoryResult[]

Per-category breakdown (validators only).

recommendationsrequiredRecommendation[]

All recommendations across the command's agents.

artifactsoptionalArtifactResult[]

Generated artifacts (executors only).

metricsrequiredCommandMetrics

Command-specific execution metrics.

dashboardUrloptionalstring

Dashboard URL, populated after tracking submission.

runCommand(name: string, input: ExecutionInput, overrides?: { model?: string }): Promise<CommandResult>
typescript
import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: process.env.ULUOPS_API_KEY,
});

const result = await client.runCommand('validate', { target: './src' });
console.log(`${result.decision} · ${result.score}`);
Response Type
// CommandResult
{
  type: 'command';
  decision: string;
  score?: number | null;
  categories?: CategoryResult[];
  recommendations: Recommendation[];
  artifacts?: ArtifactResult[];
  metrics: CommandMetrics;
  dashboardUrl?: string;
}

client.runWorkflow()

Execute a workflow with multi-phase orchestration. Phases run as a DAG with quality gates between them. A gate failure surfaces as a WorkflowError carrying partial phase results (error.context.partialResult). Throws ConfigurationError if the definition is not a workflow.

Requires authentication

Parameters

namerequiredstring

Workflow name or name@version ref.

inputrequiredExecutionInput

Execution input ({ target, prompt?, options? }); target is the absolute project path.

Return Fields

typerequired'workflow'

Discriminator.

decisionrequiredstring

Aggregate workflow decision.

phasesrequiredPhaseResult[]

Phase-by-phase results.

recommendationsrequiredRecommendation[]

Flattened recommendations across phases.

metricsrequiredWorkflowMetrics

Phases executed/passed/warned/blocked plus token and cost totals.

runWorkflow(name: string, input: ExecutionInput): Promise<WorkflowResult>
typescript
import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: process.env.ULUOPS_API_KEY,
});

const result = await client.runWorkflow('ship', { target: './src' });
console.log(`${result.decision} · ${result.metrics.phasesPassed} phases passed`);
Response Type
// WorkflowResult
{
  type: 'workflow';
  decision: string;
  phases: PhaseResult[];
  recommendations: Recommendation[];
  metrics: WorkflowMetrics;
}

client.runPipeline()

Execute a pipeline with multi-stage orchestration, synchronously to completion. For long-running pipelines you want to monitor or cancel, use startPipeline() instead. Throws ConfigurationError if the definition is not a pipeline, and PipelineError if a stage fails (error.context holds stage name/index).

Requires authentication

Parameters

namerequiredstring

Pipeline name or name@version ref.

inputrequiredExecutionInput

Execution input ({ target, prompt?, options? }); target is the absolute project path.

Return Fields

typerequired'pipeline'

Discriminator.

statusrequired'pending' | 'running' | 'complete' | 'failed' | 'cancelled'

Execution status.

stagesrequiredStageResult[]

Stage-by-stage results.

triggeroptionalTriggerInfo

Trigger information.

artifactsoptionalPipelineArtifact[]

Generated artifacts.

metricsrequiredPipelineMetrics

Stages executed plus token and cost totals.

runPipeline(name: string, input: ExecutionInput): Promise<PipelineResult>
typescript
import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: process.env.ULUOPS_API_KEY,
});

const result = await client.runPipeline('security-audit', { target: './src' });
console.log(`${result.status} · ${result.stages.length} stages`);
Response Type
// PipelineResult
{
  type: 'pipeline';
  status: 'pending' | 'running' | 'complete' | 'failed' | 'cancelled';
  stages: StageResult[];
  trigger?: TriggerInfo;
  artifacts?: PipelineArtifact[];
  metrics: PipelineMetrics;
}

client.run()

Universal execution — auto-routes based on definition type. Resolves the name and delegates to the appropriate executor. Use when the definition type is not known at the call site; prefer the typed run* methods when it is, for a precise return type. Throws ConfigurationError if the resolved definition has an unknown type.

Requires authentication

Parameters

namerequiredstring

Definition name or name@version ref (any of the four types).

inputrequiredExecutionInput

Execution input ({ target, prompt?, options? }); target is the absolute project path.

Return Fields

typerequiredExecutionType

Discriminator — 'agent' | 'command' | 'workflow' | 'pipeline'. Narrow on this to refine the result shape.

decisionrequiredstring

Final decision.

scoreoptionalnumber | null

Aggregated score (0-100) when the execution type produces one; null for scoreless runs.

recommendationsrequiredRecommendation[]

All recommendations.

metricsrequiredExecutionMetrics

Token usage, duration, and cost metrics.

run(name: string, input: ExecutionInput): Promise<ExecutionResult | AgentResult>
typescript
import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: process.env.ULUOPS_API_KEY,
});

const result = await client.run('code-validator', { target: './src' });

if (result.type === 'agent') {
  console.log(`Agent score: ${result.score}`);
} else {
  console.log(`${result.type}: ${result.decision}`);
}
Response Type
// ExecutionResult | AgentResult
{
  type: ExecutionType;
  decision: string;
  score?: number | null;
  recommendations: Recommendation[];
  metrics: ExecutionMetrics;
}

client.startPipeline()

Start an async pipeline execution and get a PipelineHandle for monitoring and control. Calling handle.wait() resolves with the final PipelineResult and tracks it (when tracking is enabled), mirroring runPipeline(). Throws ConfigurationError if the definition is not a pipeline.

Requires authentication

Parameters

namerequiredstring

Pipeline name or name@version ref.

inputrequiredExecutionInput

Execution input ({ target, prompt?, options? }); target is the absolute project path.

Return Fields

executionIdrequiredstring

Read-only id for this execution.

statusrequired() => Promise<PipelineResult>

Poll the current pipeline state.

waitrequired(pollIntervalMs?: number) => Promise<PipelineResult>

Resolve with the final result; tracks the run on completion.

cancelrequired() => Promise<void>

Request cancellation of the running pipeline.

startPipeline(name: string, input: ExecutionInput): Promise<PipelineHandle>
typescript
import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: process.env.ULUOPS_API_KEY,
});

const handle = await client.startPipeline('security-audit', { target: './src' });
console.log(`Started ${handle.executionId}`);

const result = await handle.wait();
console.log(`${result.status} · ${result.stages.length} stages`);
Response Type
// PipelineHandle
{
  executionId: string;
  status: () => Promise<PipelineResult>;
  wait: (pollIntervalMs?: number) => Promise<PipelineResult>;
  cancel: () => Promise<void>;
}