@uluops/core

The foundational execution engine for UluOps. Orchestrates AI-powered code analysis through a 4-layer execution hierarchy (Agent > Command > Workflow > Pipeline), manages LLM tool loops via the Vercel AI SDK, and integrates with the UluOps Registry and Validation services. Unlike the data-access SDKs, core actually runs agents against your code — it needs an AI provider key (Anthropic, OpenAI, or Google) and, for registry resolution and tracking, a UluOps API key.

v0.24.3ESM only

Installation

npm install @uluops/core

Quick Start

TypeScript

import { UluOpsClient } from '@uluops/core';

const client = new UluOpsClient({
  apiKey: 'ulr_your-api-key',
});

Constructor Parameters

apiKeyoptionalstring

UluOps platform API key (ulr_*) for registry and submission services. Authenticates against UluOps only — NOT AI providers. Optional when using localDefinitions with trackingEnabled: false. Falls back to ULUOPS_API_KEY or ULU_API_KEY.

aioptionalAIConfig

AI provider configuration. Separates provider credentials from UluOps platform auth. If omitted, defaults to Anthropic using the ANTHROPIC_API_KEY env var.

localDefinitionsoptionalstring

Local definitions directory for development. When set, the engine looks here first before the remote registry. Supports *.agent.yaml, *.command.yaml, *.workflow.yaml, and *.pipeline.yaml. Use the exported STARTER_DEFINITIONS_DIR for the bundled starter agents (offline mode).

trackingEnabledoptionalboolean

Submit execution results to the tracking service.

Default: true

registryUrloptionalstring

Base URL for uluops-registry-api.

Default: https://api.uluops.ai/api/v1/registry

submissionUrloptionalstring

Base URL for the uluops submission API.

Default: https://api.uluops.ai/api/v1

dashboardUrloptionalstring

Base URL for dashboard links in results.

Default: https://app.uluops.ai

defaultProjectoptionalstring

Default project name for the submission service.

timeoutoptionalnumber

Request/execution timeout in milliseconds.

Default: 300000

contextBudgetoptionalnumber

Context window budget in tokens for agent execution. When usage exceeds 80%, the agent is forced to produce output instead of calling more tools. Also enables Anthropic context management (auto-clearing old tool uses at 50%). When unset, the engine uses the resolved model's real context window.

Default: 200000

defaultThinkingBudgetoptionalnumber

Default extended-thinking budget in tokens, used when a model supports extended thinking and no per-call budget is given.

Default: 10000

maxRetriesoptionalnumber

Maximum retries for transient LLM errors (429, 5xx). The AI SDK retries with exponential backoff and respects Retry-After headers.

Default: 2

maxConcurrencyoptionalnumber

Maximum concurrent in-flight LLM generation calls across the whole engine. A shared semaphore throttles fan-out (workflow phases, parallel steps, inline pipeline agents) regardless of how many fan out at once. Falls back to ULUOPS_MAX_CONCURRENCY.

Default: 8

allowedToolsoptionalstring[]

Operator-controlled tool allowlist — the real trust boundary for tool access. Definitions can request tools (e.g. tools: ['bash']), but a tool is only granted if it also appears here. When undefined, all tools EXCEPT 'bash' are allowed (safe default). Set to ['bash', ...] to permit shell access.

Default: undefined (bash blocked, all other tools allowed)

debugoptionalboolean

Enable detailed execution logging (model resolution, prompt sizes, per-step tool calls, usage). Falls back to ULUOPS_DEBUG.

Default: false

Subpath Exports

@uluops/coreUluOpsClient, the four executors (AgentExecutor, CommandExecutor, WorkflowExecutor, PipelineExecutor), service clients (RegistryClient, SubmissionClient), AI integration (AIProvider, ModelCatalog, ToolAdapter, TokenBudgetTracker), and the STARTER_DEFINITIONS_DIR + DEFAULT_* constants.
@uluops/core/typesAll execution, agent, command, workflow, pipeline, registry, submission, and config types (AgentResult, CommandResult, ExecutionInput, UluOpsConfig, …) for type-only imports.
@uluops/core/errorsTyped error classes thrown by the engine — ConfigurationError, IntegrityError, MaxStepsExhaustedError, PreflightError, ExecutionError, WorkflowError, PipelineError, SubmissionError — for instanceof narrowing.

Namespaces

Executionclient

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

Convenienceclient

Thin wrappers over the built-in commands and workflows. Each takes a target path and forwards to runCommand()/runWorkflow() with the corresponding definition name.

5 methods

Discoveryclient

Inspect what's available without executing it. list() enumerates definitions from local files and the registry; describe() returns a single definition's metadata and interface; clearCache() drops the resolution cache in long-lived processes.

3 methods

Submission & Historyclient

Query past runs and manually submit results. The run* methods auto-submit when tracking is enabled; these methods are for explicit history queries, dry-run previews, and out-of-band submission. All delegate to the SubmissionClient.

4 methods