@eigenpal/sdk 0.6.13 → 0.6.15

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @eigenpal/sdk
 
+## 0.6.15
+
+### Minor Changes
+
+- ca87265: Unify workflow and agent run starts behind the canonical `/api/v1/run/{target}` endpoint, root `eigenpal run` / `eigenpal rerun` commands, and root SDK `client.run()` / `client.rerun()` methods.
+
+  The old nested CLI commands and SDK resource methods for starting workflow or agent runs have been removed.
+
 ## 0.6.10
 
 ### Patch Changes

package/README.md

@@ -29,7 +29,7 @@ const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });
 const result = await client.workflows.executions.runAndWait('extract-invoice', {
   contract_document: file,
 });
-console.log(result.status, result.result);
+console.log(result.status, result.output);
 ```
 
 ## Authentication
@@ -55,23 +55,23 @@ const client = new EigenpalClient({
 
 `baseUrl` likewise wins over the `EIGENPAL_BASE_URL` env fallback. Defaults to `https://app.eigenpal.com` (the hosted cloud).
 
-## Triggering workflows
+## Starting runs
 
-`workflows.run(workflowId, input?, options?)` enqueues a workflow execution.
+`client.run(target, input?, options?)` starts a workflow or agent run. Targets can be strings such as `workflows.extract-invoice` / `agents.invoice-agent` or structured objects like `{ type: 'workflow', slug: 'extract-invoice' }`.
 
 ```ts
-// Async: returns immediately with { executionId }.
-const { executionId } = await client.workflows.run('extract-invoice', {
+// Async: returns immediately with { runId }.
+const { runId } = await client.run('workflows.extract-invoice', {
   contract_document: file,
 });
 
 // Sync: server holds the connection up to 60 seconds.
-const result = await client.workflows.run(
-  'extract-invoice',
+const result = await client.run(
+  { type: 'workflow', slug: 'extract-invoice', version: 'latest' },
   { contract_document: file },
   { waitForCompletion: 60 }
 );
-console.log(result.status, result.result);
+console.log(result.status, result.output);
 
 // Long-running: client-side polling, default 5min cap.
 const final = await client.workflows.executions.runAndWait('extract-invoice', {
@@ -79,7 +79,7 @@ const final = await client.workflows.executions.runAndWait('extract-invoice', {
 });
 ```
 
-The second argument is the workflow input map keyed by input name (as declared in the workflow). Pass `undefined` for inputs-less workflows. `options` carries `version`, `waitForCompletion`, and `overrides`.
+The second argument is the input map keyed by input name. Pass `undefined` for inputs-less runs. `options` carries `waitForCompletion` and workflow `overrides`; put the workflow version or agent source ref in the target.
 
 ## File inputs
 
@@ -87,12 +87,12 @@ When a workflow input is a file, pass a `File`, `Blob`, or explicit `{ content,
 
 ```ts
 // Browser: File from <input type="file">
-await client.workflows.run('extract-invoice', { contract_document: file });
+await client.run('workflows.extract-invoice', { contract_document: file });
 
 // Node: Buffer from fs
 import { readFile } from 'node:fs/promises';
 const buffer = await readFile('contract.pdf');
-await client.workflows.run('extract-invoice', {
+await client.run('workflows.extract-invoice', {
   contract_document: {
     content: buffer,
     filename: 'contract.pdf',
@@ -112,11 +112,11 @@ const runs = await client.runs.list({
   status: 'failed,cancelled',
 });
 
-const run = await client.runs.get(executionId, { include: 'detail' });
-await client.runs.cancel(executionId);
+const run = await client.runs.get(runId, { include: 'detail' });
+await client.runs.cancel(runId);
 
-const status = await client.runs.get(executionId);
-//   { executionId, status, result?, error?, createdAt, completedAt? }
+const status = await client.runs.get(runId);
+//   { run: { id, status, output?, error?, createdAt, completedAt? } }
 
 const list = await client.runs.list({
   type: 'workflow',
@@ -126,7 +126,7 @@ const list = await client.runs.list({
   limit: 50,
 });
 
-await client.runs.cancel(executionId);
+await client.runs.cancel(runId);
 ```
 
 `/api/v1/runs` is the shared run API for workflow, agent, and eval runs. Use `type=workflow|agent`
@@ -146,12 +146,12 @@ await client.workflows.versions('extract-invoice');
 await client.agents.list({ search: 'invoice' });
 await client.agents.get('invoice-agent');
 
-const { executionId } = await client.agents.run('invoice-agent', {
+const { runId: agentRunId } = await client.run('agents.invoice-agent', {
   invoice: file,
 });
 
-await client.runs.get(executionId);
-await client.runs.cancel(executionId);
+await client.runs.get(agentRunId);
+await client.runs.cancel(agentRunId);
 ```
 
 Agent run listing uses the same shared runs API with `type: 'agent'` and the agent id or slug as
@@ -181,7 +181,7 @@ try {
   const result = await client.workflows.executions.runAndWait('extract-invoice', {
     language: 'en',
   });
-  console.log(result.status, result.result);
+  console.log(result.status, result.output);
 } catch (err) {
   if (err instanceof EigenpalValidationError) {
     for (const issue of err.issues) console.error(`${issue.field}: ${issue.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/sdk",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Official TypeScript SDK for the EigenPal API",
   "type": "module",
   "main": "./src/index.ts",

package/src/client.ts

@@ -1,6 +1,8 @@
 import { EigenpalError, EigenpalTimeoutError, errorFromResponse } from './errors';
 import { createClient, createConfig, type Client, type Config } from './generated/client';
+import { runStartWithTarget } from './generated/sdk.gen';
 import type { ApiErrorEnvelope } from './generated/types.gen';
+import { buildRunJsonBody, buildRunMultipart, hasFileInput } from './lib/files';
 import { AgentsResource } from './resources/agents';
 import { AutomationsResource } from './resources/automations';
 import { RunsResource } from './resources/runs';
@@ -51,6 +53,40 @@ export interface OperationResult<T> {
   request?: Request;
 }
 
+export type RunTarget =
+  | string
+  | {
+      type: 'workflow' | 'agent';
+      id?: string;
+      slug?: string;
+      version?: string;
+    };
+
+export type RunInput = Record<string, unknown>;
+
+export interface RunOptions {
+  input?: RunInput;
+  waitForCompletion?: number;
+  overrides?: { steps?: Record<string, Record<string, unknown>> };
+  signal?: AbortSignal;
+}
+
+export type RunCallOptions = Omit<RunOptions, 'input'>;
+
+export interface RerunOptions {
+  version?: 'latest' | 'original' | string;
+  waitForCompletion?: number;
+  signal?: AbortSignal;
+}
+
+export type RunStartResponse = Record<string, unknown> & {
+  runId: string;
+  type: 'workflow' | 'agent';
+  status?: string;
+  output?: unknown;
+  error?: string | null;
+};
+
 /**
  * The EigenPal SDK client.
  *
@@ -61,10 +97,13 @@ export interface OperationResult<T> {
  * const client = new EigenpalClient();
  *
  * // Async — enqueue and poll later.
- * const { executionId } = await client.workflows.run('wf_abc', { language: 'en' });
+ * const { runId } = await client.run('workflows.extract-invoice', {
+ *   input: { language: 'en' },
+ * });
  *
  * // Sync (server holds the connection up to 60s).
- * const result = await client.workflows.run('wf_abc', { language: 'en' }, {
+ * const result = await client.run('workflows.extract-invoice', {
+ *   input: { language: 'en' },
  *   waitForCompletion: 60,
  * });
  *
@@ -73,9 +112,9 @@ export interface OperationResult<T> {
  * ```
  */
 export class EigenpalClient {
-  /** Workflow operations: `list`, `get`, `versions`, `run`. */
+  /** Workflow definition operations: `list`, `get`, `versions`. Start runs with `client.run(...)`. */
   public readonly workflows: WorkflowsResource;
-  /** Agent operations: `list`, `get`, `create`, `run`, `executions`. */
+  /** Agent operations: `list`, `get`, `create`, `executions`. Start runs with `client.run(...)`. */
   public readonly agents: AgentsResource;
   /** Source repository operations: repository metadata, raw files, releases, lockfiles, and secret decrypt. */
   public readonly source: SourceResource;
@@ -135,6 +174,83 @@ export class EigenpalClient {
     return this.client;
   }
 
+  async run(
+    target: RunTarget,
+    input?: RunInput,
+    options?: RunCallOptions
+  ): Promise<RunStartResponse>;
+  async run(target: RunTarget, options?: RunOptions): Promise<RunStartResponse>;
+  async run(request: { target: RunTarget } & RunOptions): Promise<RunStartResponse>;
+  async run(
+    targetOrRequest: RunTarget | ({ target: RunTarget } & RunOptions),
+    inputOrOptions: RunInput | RunOptions = {},
+    options: RunCallOptions = {}
+  ): Promise<RunStartResponse> {
+    const targetPassedDirectly =
+      typeof targetOrRequest === 'string' ||
+      (targetOrRequest &&
+        typeof targetOrRequest === 'object' &&
+        'type' in targetOrRequest &&
+        !('target' in targetOrRequest));
+    const request = targetPassedDirectly
+      ? { target: targetOrRequest, ...normalizeRunArgs(inputOrOptions, options) }
+      : (targetOrRequest as { target: RunTarget } & RunOptions);
+    const { pathTarget, version } = pathTargetFromRunTarget(request.target);
+    const query = runQuery({
+      waitForCompletion: request.waitForCompletion,
+      version,
+    });
+
+    if (hasFileInput(request.input)) {
+      const { formData } = await buildRunMultipart({
+        input: request.input,
+        overrides: request.overrides,
+      });
+      return this._request<RunStartResponse>(
+        () =>
+          this.client.post({
+            url: `/api/v1/run/${encodeURIComponent(pathTarget)}`,
+            query,
+            body: formData,
+            bodySerializer: null,
+            headers: { 'Content-Type': null },
+            signal: request.signal,
+          }) as Promise<OperationResult<RunStartResponse>>
+      );
+    }
+
+    const body = buildRunJsonBody(request.input, request.overrides);
+    return this._request<RunStartResponse>(
+      () =>
+        runStartWithTarget({
+          client: this.client,
+          path: { target: pathTarget },
+          query,
+          body,
+          signal: request.signal,
+        }) as Promise<OperationResult<RunStartResponse>>
+    );
+  }
+
+  async rerun(runId: string, options: RerunOptions = {}): Promise<Record<string, unknown>> {
+    return this._request<Record<string, unknown>>(
+      () =>
+        this.client.post({
+          url: '/api/v1/runs/{id}/rerun',
+          path: { id: runId },
+          query:
+            options.waitForCompletion !== undefined
+              ? { wait_for_completion: options.waitForCompletion }
+              : undefined,
+          body:
+            options.version && options.version !== 'latest'
+              ? { sourceRef: options.version }
+              : undefined,
+          signal: options.signal,
+        }) as Promise<OperationResult<Record<string, unknown>>>
+    );
+  }
+
   /**
    * Run an operation with automatic retries on 5xx / 429 / network errors,
    * and centralized error mapping into typed `EigenpalError` subclasses.
@@ -208,6 +324,39 @@ export class EigenpalClient {
   }
 }
 
+function pathTargetFromRunTarget(target: RunTarget): { pathTarget: string; version?: string } {
+  if (typeof target === 'string') {
+    const [pathTarget, version, extra] = target.split('@');
+    if (!pathTarget || version === '' || extra !== undefined) {
+      throw new EigenpalError('Run target strings must be <target> or <target>@<version>.', {
+        status: 0,
+      });
+    }
+    return { pathTarget, version: version && version !== 'latest' ? version : undefined };
+  }
+  const idOrSlug = target.slug ?? target.id;
+  if (!idOrSlug) {
+    throw new EigenpalError('Run target objects require `slug` or `id`.', { status: 0 });
+  }
+  const root = target.type === 'agent' ? 'agents' : 'workflows';
+  const name = idOrSlug.includes('.') ? idOrSlug : `${root}.${idOrSlug.split('/').join('.')}`;
+  return {
+    pathTarget: name,
+    version: target.version && target.version !== 'latest' ? target.version : undefined,
+  };
+}
+
+function runQuery(options: {
+  waitForCompletion?: number;
+  version?: string;
+}): { wait_for_completion?: number; version?: string } | undefined {
+  const query: { wait_for_completion?: number; version?: string } = {};
+  if (options.waitForCompletion !== undefined)
+    query.wait_for_completion = options.waitForCompletion;
+  if (options.version) query.version = options.version;
+  return Object.keys(query).length > 0 ? query : undefined;
+}
+
 function assertJsonResponse(response: Response): void {
   // 204 No Content has no body — accept silently.
   if (response.status === 204) return;
@@ -224,6 +373,26 @@ function assertJsonResponse(response: Response): void {
   );
 }
 
+function normalizeRunArgs(
+  inputOrOptions: RunInput | RunOptions,
+  options: RunCallOptions
+): RunOptions {
+  if (Object.keys(options).length > 0) {
+    return { ...options, input: inputOrOptions as RunInput };
+  }
+  if (looksLikeRunOptions(inputOrOptions)) {
+    return inputOrOptions;
+  }
+  return { input: inputOrOptions as RunInput };
+}
+
+function looksLikeRunOptions(value: unknown): value is RunOptions {
+  if (!value || typeof value !== 'object') return false;
+  return (
+    'input' in value || 'waitForCompletion' in value || 'overrides' in value || 'signal' in value
+  );
+}
+
 function isRetriableStatus(status: number): boolean {
   return status >= 500 || status === 429;
 }

package/src/generated/index.ts

@@ -7,7 +7,6 @@ export {
   agentsFilesUploadBatch,
   agentsGet,
   agentsList,
-  agentsRun,
   agentsTriggersEmailCreateAlias,
   agentsTriggersEmailDeleteAlias,
   agentsTriggersEmailGet,
@@ -17,6 +16,7 @@ export {
   agentsUpdate,
   agentsVersionsList,
   automationsSync,
+  runStartWithTarget,
   runsArtifactGet,
   runsCancel,
   runsComparisonGet,
@@ -46,7 +46,6 @@ export {
   sourceSecretsEncrypt,
   workflowsGet,
   workflowsList,
-  workflowsRun,
   workflowsVersionsList,
   type Options,
 } from './sdk.gen';
@@ -77,11 +76,6 @@ export type {
   AgentsListErrors,
   AgentsListResponse,
   AgentsListResponses,
-  AgentsRunData,
-  AgentsRunError,
-  AgentsRunErrors,
-  AgentsRunResponse,
-  AgentsRunResponses,
   AgentsTriggersEmailCreateAliasData,
   AgentsTriggersEmailCreateAliasError,
   AgentsTriggersEmailCreateAliasErrors,
@@ -142,17 +136,20 @@ export type {
   PatchAgentBody,
   PatchAgentResponse,
   RawSourceResponse,
-  RunAgentBody,
-  RunAgentResponse,
   RunEnvelope,
   RunFeedbackRequest,
   RunFilesResponse,
   RunRerunRequest,
   RunRerunResponse,
   RunResumeResponse,
+  RunStartResponse,
+  RunStartWithTargetData,
+  RunStartWithTargetError,
+  RunStartWithTargetErrors,
+  RunStartWithTargetResponse,
+  RunStartWithTargetResponses,
   RunSummary,
-  RunWorkflowBody,
-  RunWorkflowResponse,
+  RunTargetInputBody,
   RunsArtifactGetData,
   RunsArtifactGetError,
   RunsArtifactGetErrors,
@@ -308,11 +305,6 @@ export type {
   WorkflowsListErrors,
   WorkflowsListResponse,
   WorkflowsListResponses,
-  WorkflowsRunData,
-  WorkflowsRunError,
-  WorkflowsRunErrors,
-  WorkflowsRunResponse,
-  WorkflowsRunResponses,
   WorkflowsVersionsListData,
   WorkflowsVersionsListError,
   WorkflowsVersionsListErrors,

package/src/generated/sdk.gen.ts

@@ -24,9 +24,6 @@ import type {
   AgentsListData,
   AgentsListErrors,
   AgentsListResponses,
-  AgentsRunData,
-  AgentsRunErrors,
-  AgentsRunResponses,
   AgentsTriggersEmailCreateAliasData,
   AgentsTriggersEmailCreateAliasErrors,
   AgentsTriggersEmailCreateAliasResponses,
@@ -114,6 +111,9 @@ import type {
   RunsResumeData,
   RunsResumeErrors,
   RunsResumeResponses,
+  RunStartWithTargetData,
+  RunStartWithTargetErrors,
+  RunStartWithTargetResponses,
   RunsTraceGetData,
   RunsTraceGetErrors,
   RunsTraceGetResponses,
@@ -141,9 +141,6 @@ import type {
   WorkflowsListData,
   WorkflowsListErrors,
   WorkflowsListResponses,
-  WorkflowsRunData,
-  WorkflowsRunErrors,
-  WorkflowsRunResponses,
   WorkflowsVersionsListData,
   WorkflowsVersionsListErrors,
   WorkflowsVersionsListResponses,
@@ -253,24 +250,6 @@ export const agentsUpdate = <ThrowOnError extends boolean = false>(
     },
   });
 
-/**
- * Run an agent
- *
- * Enqueues an agent run. Returns 202 with `{ runId }` by default. Pass `wait_for_completion=<seconds>` to hold the connection until the run reaches a terminal state. File inputs are uploaded as multipart/form-data.
- */
-export const agentsRun = <ThrowOnError extends boolean = false>(
-  options: Options<AgentsRunData, ThrowOnError>
-) =>
-  (options.client ?? client).post<AgentsRunResponses, AgentsRunErrors, ThrowOnError>({
-    security: [{ scheme: 'bearer', type: 'http' }],
-    url: '/api/v1/agents/{agentId}/run',
-    ...options,
-    headers: {
-      'Content-Type': 'application/json',
-      ...options.headers,
-    },
-  });
-
 /**
  * Delete an agent email alias
  *
@@ -455,6 +434,28 @@ export const automationsSync = <ThrowOnError extends boolean = false>(
     ...options,
   });
 
+/**
+ * Start a workflow or agent run
+ *
+ * Starts a run for a workflow or agent target. The target lives in the URL path; the optional `version` query parameter selects a release/ref and defaults to `latest`. The request body is the input object; a reserved `_overrides` key (workflow targets only) carries per-step output overrides for replay. Run provenance may be declared with the `X-Eigenpal-Trigger` header (`api` or `cli`).
+ */
+export const runStartWithTarget = <ThrowOnError extends boolean = false>(
+  options: Options<RunStartWithTargetData, ThrowOnError>
+) =>
+  (options.client ?? client).post<
+    RunStartWithTargetResponses,
+    RunStartWithTargetErrors,
+    ThrowOnError
+  >({
+    security: [{ scheme: 'bearer', type: 'http' }],
+    url: '/api/v1/run/{target}',
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+  });
+
 /**
  * Download run artifact
  *
@@ -886,24 +887,6 @@ export const workflowsGet = <ThrowOnError extends boolean = false>(
     ...options,
   });
 
-/**
- * Execute a workflow (async or sync)
- *
- * Enqueues a workflow execution. Returns 201 with `{ executionId }` by default. Pass `wait_for_completion=<seconds>` (max 60) to hold the connection until the run reaches a terminal state; the body then also includes `status`, `result`, and `error`. File inputs are uploaded as `multipart/form-data` (each file as a top-level form field; `_json` field carries scalar inputs).
- */
-export const workflowsRun = <ThrowOnError extends boolean = false>(
-  options: Options<WorkflowsRunData, ThrowOnError>
-) =>
-  (options.client ?? client).post<WorkflowsRunResponses, WorkflowsRunErrors, ThrowOnError>({
-    security: [{ scheme: 'bearer', type: 'http' }],
-    url: '/api/v1/workflows/{id}/run',
-    ...options,
-    headers: {
-      'Content-Type': 'application/json',
-      ...options.headers,
-    },
-  });
-
 /**
  * List tagged versions for a workflow
  *