Discovery

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

client.list()

List available definitions from local files and the registry. Note: list() always queries the registry first and only falls back to bundled definitions after the request fails — in a genuinely offline environment expect a few seconds of retry/backoff before the local list returns.

Requires authentication

Parameters

filteroptional{ type?: DefinitionType; domain?: string }

Optional filter.

Return Fields

typerequiredDefinitionType

Definition type.

namerequiredstring

Definition name.

versionrequiredstring

Latest version.

displayNamerequiredstring

Human-readable display name.

descriptionrequiredstring

Short description.

domainrequiredDomain

Domain classification.

agentTypeoptionalAgentType

Agent type (for agents).

statusrequired'draft' | 'published' | 'deprecated' | 'archived'

Publication status.

tagsoptionalstring[]

Discovery tags.

list(filter?: { type?: DefinitionType; domain?: string }): Promise<DefinitionSummary[]>

typescript

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

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

const agents = await client.list({ type: 'agent' });
for (const a of agents) {
  console.log(`${a.name}@${a.version} — ${a.description}`);
}

Response Type

// DefinitionSummary[]
{
  type: DefinitionType;
  name: string;
  version: string;
  displayName: string;
  description: string;
  domain: Domain;
  agentType?: AgentType;
  status: 'draft' | 'published' | 'deprecated' | 'archived';
  tags?: string[];
}

client.describe()

Inspect a definition's metadata and interface. When a name is registered as more than one type, pass `type` to disambiguate.

Requires authentication

Parameters

namerequiredstring

Definition name, optionally with a version suffix (e.g. 'code-validator@1.2.0').

versionoptionalstring

Explicit version (overrides any suffix in name).

typeoptionalDefinitionType

Definition type to disambiguate when the same name exists across types.

Return Fields

typerequiredDefinitionType

Resolved definition type.

namerequiredstring

Resolved name.

versionrequiredstring

Resolved version.

hashrequiredstring

Content-addressed hash of the definition.

interfacerequiredRecord<string, unknown>

The definition's declared interface (inputs, outputs, tags).

riskProfileoptionalRecord<string, unknown> | null

Safety-scanner risk profile, or null when none is recorded.

describe(name: string, version?: string, type?: DefinitionType): Promise<{ type; name; version; hash; interface; riskProfile }>

typescript

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

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

// Pass `type` to disambiguate when a name spans multiple types
const meta = await client.describe('socrates-explorer', undefined, 'agent');
console.log(meta.type, meta.version, meta.hash);

Response Type

// { type; name; version; hash; interface; riskProfile }
{
  type: DefinitionType;
  name: string;
  version: string;
  hash: string;
  interface: Record<string, unknown>;
  riskProfile?: Record<string, unknown> | null;
}

client.clearCache()

Clear the definition resolution cache. Call after registry updates in long-lived processes so the next resolve fetches fresh content.

clearCache(): void

typescript

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

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

// After publishing a new version elsewhere
client.clearCache();

Response Type

void