@eigenpal/sdk 0.6.17 → 0.7.1

package/src/index.ts

@@ -8,26 +8,21 @@
  * const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY! });
  *
  * // Async — enqueue and poll later.
- * const { runId } = await client.run('workflows.extract-invoice', {
- *   input: { ... },
- * });
+ * const { id } = await client.run('workflows.extract-invoice', { ... });
  *
  * // Sync (server holds the connection up to 60s).
- * const result = await client.run('workflows.extract-invoice', {
- *   input: { ... },
- *   waitForCompletion: 60,
- * });
+ * const result = await client.run('workflows.extract-invoice', { ... }, { waitForCompletion: 60 });
  *
  * // Client-side poll (up to 5min by default).
- * const final = await client.workflows.executions.runAndWait('wf_abc', { input: { ... } });
+ * const final = await client.workflows.executions.runAndWait('wf_abc', { ... });
  * ```
  */
 export {
   EigenpalClient,
   type EigenpalOptions,
   type RerunOptions,
+  type RunCallOptions,
   type RunInput,
-  type RunOptions,
   type RunStartResponse,
   type RunTarget,
 } from './client';
@@ -46,7 +41,7 @@ export {
 export { toFile } from './lib/files';
 export type { FileDescriptor, FileInput, NodeReadableStream } from './lib/files';
 export type { ListAgentsOptions } from './resources/agents';
-export type { ListRunsOptions } from './resources/runs';
+export type { ListRunsOptions, RunExpand, RunExpandSection } from './resources/runs';
 export type { SourceRawOptions, SourceReleasesOptions } from './resources/source';
 export type {
   ListVersionsOptions,
@@ -81,8 +76,8 @@ export type {
   ListVersionsResponse,
   ListWorkflowsResponse,
   RawSourceResponse,
-  RunSummary,
-  RunTargetInputBody,
+  RunListItem,
+  RunStartBody,
   RunsCancelResponse,
   RunsExpectedCreateResponse,
   RunsExpectedFileDeleteResponse,

package/src/lib/files.ts

@@ -168,7 +168,7 @@ export interface MultipartParts {
   fileCount: number;
 }
 
-/** Drain `input` into a FormData, appending each detected file as a field. */
+/** Drain `input` into a FormData, appending each detected file as `files.<name>`. */
 async function appendFiles(
   fd: FormData,
   input: Record<string, unknown> | undefined
@@ -178,7 +178,7 @@ async function appendFiles(
   for (const [key, value] of Object.entries(input ?? {})) {
     if (isFileInput(value)) {
       const { blob, filename } = await resolveFileBlob(value);
-      fd.append(key, blob, filename);
+      fd.append(`files.${key}`, blob, filename);
       fileCount += 1;
     } else {
       scalars[key] = value;
@@ -188,39 +188,52 @@ async function appendFiles(
 }
 
 /**
- * JSON-body counterpart of {@link buildRunMultipart}: per-step overrides ride
- * in the reserved `_overrides` body key.
+ * JSON-body counterpart of {@link buildRunMultipart}: canonical envelope
+ * `{ target, input, overrides?, metadata? }`.
  */
 export function buildRunJsonBody(
+  target: string,
   input: Record<string, unknown> | undefined,
-  overrides?: { steps?: Record<string, Record<string, unknown>> }
+  overrides?: { steps?: Record<string, Record<string, unknown>> },
+  metadata?: Record<string, unknown>
 ): Record<string, unknown> {
-  return overrides ? { ...(input ?? {}), _overrides: overrides } : (input ?? {});
+  const body: Record<string, unknown> = {
+    target,
+    input: input ?? {},
+  };
+  if (overrides) body.overrides = overrides;
+  if (metadata) body.metadata = metadata;
+  return body;
 }
 
 /**
  * Build multipart for the canonical `client.run(...)` endpoint
- * (`POST /api/v1/run/{target}`):
+ * (`POST /api/v1/runs`):
  *
- *   - Each top-level file in `input` becomes a form field (key = input name).
- *   - Non-file inputs go in the `_json` text field (the input object itself).
- *   - Per-step overrides go in the reserved `_overrides` text field.
+ *   - `target` is a required text field.
+ *   - Scalar inputs go in the `input` JSON text field.
+ *   - Each top-level file in `input` becomes `files.<fieldName>`.
+ *   - Per-step overrides and caller metadata use `overrides` / `metadata` JSON parts.
  *
  * Async because stream inputs are drained to bytes here. Only top-level file
  * values are extracted — files nested inside arrays / objects keep their
  * position in the JSON sidecar (the server has no nested-upload path).
  */
 export async function buildRunMultipart(args: {
+  target: string;
   input?: Record<string, unknown>;
   overrides?: { steps?: Record<string, Record<string, unknown>> };
+  metadata?: Record<string, unknown>;
 }): Promise<MultipartParts> {
   const fd = new FormData();
+  fd.append('target', args.target);
   const { scalars, fileCount } = await appendFiles(fd, args.input);
-  if (Object.keys(scalars).length > 0) {
-    fd.append('_json', JSON.stringify(scalars));
-  }
+  fd.append('input', JSON.stringify(scalars));
   if (args.overrides) {
-    fd.append('_overrides', JSON.stringify(args.overrides));
+    fd.append('overrides', JSON.stringify(args.overrides));
+  }
+  if (args.metadata) {
+    fd.append('metadata', JSON.stringify(args.metadata));
   }
   return { formData: fd, fileCount };
 }

package/src/resources/executions.ts

@@ -23,19 +23,12 @@ export interface RunAndWaitOptions {
 }
 
 export type WorkflowRunAndWaitResponse = {
-  runId: string;
+  id: string;
   status?: ExecutionStatus;
   output?: unknown;
   error?: string;
 };
 
-const TERMINAL_STATUSES = new Set<ExecutionStatus>([
-  'completed',
-  'failed',
-  'cancelled',
-  'rejected',
-]);
-
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_RUN_AND_WAIT_TIMEOUT_MS = 5 * 60 * 1000;
 
@@ -55,7 +48,7 @@ export class WorkflowExecutionsResource {
   /**
    * Trigger a workflow and poll for completion client-side.
    *
-   * Unlike `client.run({ waitForCompletion: 60 })`, this helper polls
+   * Unlike `client.run(target, input, { waitForCompletion: 60 })`, this helper polls
    * indefinitely (up to `timeoutMs`, default 5 min) so it works for runs
    * that exceed the server-side 60s sync window. Returns the final
    * response with `status`/`output`/`error` populated.
@@ -70,15 +63,19 @@ export class WorkflowExecutionsResource {
     const deadline = Date.now() + timeoutMs;
 
     const target = `workflows.${workflowId}`;
-    const runUrl = `/api/v1/run/${encodeURIComponent(target)}`;
+    const runUrl = '/api/v1/runs';
     const runQuery =
       options.version && options.version !== 'latest' ? { version: options.version } : undefined;
-    let runResult: { runId: string };
+    let runResult: { id: string };
     if (hasFileInput(input)) {
       // Build the multipart body once, up front — `dispatch` may retry the
       // POST, and a drained stream cannot be replayed.
-      const { formData } = await buildRunMultipart({ input, overrides: options.overrides });
-      runResult = await this.dispatch<{ runId: string }>(
+      const { formData } = await buildRunMultipart({
+        target,
+        input,
+        overrides: options.overrides,
+      });
+      runResult = await this.dispatch<{ id: string }>(
         () =>
           this.client.post({
             url: runUrl,
@@ -87,22 +84,22 @@ export class WorkflowExecutionsResource {
             bodySerializer: null,
             headers: { 'Content-Type': null },
             signal: options.signal,
-          }) as Promise<OperationResult<{ runId: string }>>
+          }) as Promise<OperationResult<{ id: string }>>
       );
     } else {
-      const body = buildRunJsonBody(input, options.overrides);
-      runResult = await this.dispatch<{ runId: string }>(
+      const body = buildRunJsonBody(target, input, options.overrides);
+      runResult = await this.dispatch<{ id: string }>(
         () =>
           this.client.post({
             url: runUrl,
             query: runQuery,
             body,
             signal: options.signal,
-          }) as Promise<OperationResult<{ runId: string }>>
+          }) as Promise<OperationResult<{ id: string }>>
       );
     }
 
-    const runId = runResult.runId;
+    const runId = runResult.id;
 
     while (true) {
       if (options.signal?.aborted) {
@@ -114,27 +111,28 @@ export class WorkflowExecutionsResource {
         );
       }
 
-      const response = await this.dispatch<RunsGetResponse>(
+      const run = (await this.dispatch<RunsGetResponse>(
         () =>
           runsGet({
             client: this.client,
             path: { id: runId },
-            query: { include: 'detail' },
+            query: { expand: 'execution' },
             signal: options.signal,
           }) as Promise<OperationResult<RunsGetResponse>>
-      );
-      const status = response.run as {
-        status?: ExecutionStatus | null;
+      )) as {
+        finished?: boolean;
         output?: unknown;
         error?: string | null;
+        execution?: { status?: ExecutionStatus | null } | null;
       };
 
-      if (status.status && TERMINAL_STATUSES.has(status.status)) {
+      const status = run.execution?.status;
+      if (run.finished) {
         return {
-          runId,
-          status: status.status,
-          ...(status.output != null ? { output: status.output } : {}),
-          ...(status.error != null ? { error: status.error } : {}),
+          id: runId,
+          status: status ?? 'completed',
+          ...(run.output != null ? { output: run.output } : {}),
+          ...(run.error != null ? { error: run.error } : {}),
         };
       }
 

package/src/resources/runs.ts

@@ -2,10 +2,11 @@ import type { OperationResult } from '../client';
 import { EigenpalError } from '../errors';
 import type { Client } from '../generated/client';
 import {
-  runsArtifactGet,
+  runsArtifactsList,
   runsCancel,
   runsComparisonGet,
   runsConnect,
+  runsDefinitionGet,
   runsExpectedCreate,
   runsExpectedFileDelete,
   runsExpectedFileGet,
@@ -24,7 +25,8 @@ import {
   runsTraceGet,
 } from '../generated/sdk.gen';
 import type {
-  RunRerunRequest,
+  RunArtifactsResponse,
+  RunDefinitionResponse,
   RunsCancelResponse,
   RunsComparisonGetResponse,
   RunsConnectResponse,
@@ -54,6 +56,21 @@ type Dispatch = <T>(call: () => Promise<OperationResult<T>>) => Promise<T>;
 export type ListRunsOptions = NonNullable<RunsListData['query']> & { signal?: AbortSignal };
 type SignalOptions = { signal?: AbortSignal };
 
+/**
+ * Expandable sections for `runs.get`. Each token adds one nested object with
+ * the same name. Terminal runs expose top-level `output`, `files`, and `error`.
+ */
+export type RunExpandSection = 'input' | 'usage' | 'execution' | 'debug';
+
+/** Typed section list, or a raw comma-separated string for forward compat. */
+export type RunExpand = readonly RunExpandSection[] | (string & {});
+
+function formatExpand(expand: RunExpand | undefined): string | undefined {
+  if (expand === undefined) return undefined;
+  const joined = typeof expand === 'string' ? expand : expand.join(',');
+  return joined.length > 0 ? joined : undefined;
+}
+
 export class RunsResource {
   public readonly feedback: RunsFeedbackResource;
   public readonly expected: RunsExpectedResource;
@@ -69,7 +86,7 @@ export class RunsResource {
     this.feedback = new RunsFeedbackResource(client, dispatch);
     this.expected = new RunsExpectedResource(client, dispatch);
     this.files = new RunsFilesResource(client, dispatch);
-    this.artifacts = new RunsArtifactsResource(client);
+    this.artifacts = new RunsArtifactsResource(client, dispatch);
     this.comparison = new RunsComparisonResource(client, dispatch);
     this.trace = new RunsTraceResource(client, dispatch);
   }
@@ -79,16 +96,24 @@ export class RunsResource {
     return this.dispatch(() => runsList({ client: this.client, query, signal }));
   }
 
-  async get(runId: string, options: { include?: string; signal?: AbortSignal } = {}) {
-    const response = await this.dispatch<RunsGetResponse>(() =>
+  /**
+   * Fetch the canonical grouped run object. Terminal runs include top-level
+   * `output`, `files`, and `error`. Pass `expand` (for example
+   * `['usage', 'execution']`) to add optional nested detail objects.
+   */
+  async get(
+    runId: string,
+    options: { expand?: RunExpand; signal?: AbortSignal } = {}
+  ): Promise<RunsGetResponse> {
+    const expand = formatExpand(options.expand);
+    return this.dispatch<RunsGetResponse>(() =>
       runsGet({
         client: this.client,
         path: { id: runId },
-        query: options.include ? { include: options.include } : {},
+        query: expand ? { expand } : {},
         signal: options.signal,
       })
     );
-    return response.run;
   }
 
   async cancel(runId: string, options: SignalOptions = {}): Promise<RunsCancelResponse> {
@@ -99,11 +124,11 @@ export class RunsResource {
 
   async rerun(
     runId: string,
-    body: RunRerunRequest = {},
+    query: { version?: string; wait_for_completion?: number } = {},
     options: SignalOptions = {}
   ): Promise<RunsRerunResponse> {
     return this.dispatch(() =>
-      runsRerun({ client: this.client, path: { id: runId }, body, signal: options.signal })
+      runsRerun({ client: this.client, path: { id: runId }, query, signal: options.signal })
     );
   }
 
@@ -120,10 +145,10 @@ export class RunsResource {
     const mode = options.baseline ? 'baseline' : 'expected';
     const [reference, target] = await Promise.all([
       this.get(referenceRunId, {
-        include: mode === 'baseline' ? 'detail,files,output' : 'detail,expected',
+        expand: ['execution'],
         signal: options.signal,
       }),
-      this.get(runId, { include: 'detail,files,output', signal: options.signal }),
+      this.get(runId, { expand: ['execution'], signal: options.signal }),
     ]);
 
     if (isWorkflowRun(reference) && isWorkflowRun(target)) {
@@ -156,6 +181,12 @@ export class RunsResource {
       runsConnect({ client: this.client, path: { id: runId }, signal: options.signal })
     );
   }
+
+  async definition(runId: string, options: SignalOptions = {}): Promise<RunDefinitionResponse> {
+    return this.dispatch(() =>
+      runsDefinitionGet({ client: this.client, path: { id: runId }, signal: options.signal })
+    );
+  }
 }
 
 type RunRecord = Record<string, unknown>;
@@ -174,19 +205,57 @@ export type RunComparisonReport = {
   warnings?: string[];
 };
 
-function isWorkflowRun(run: unknown): run is RunRecord & { stepExecutions: unknown[] } {
-  return isRecord(run) && Array.isArray(run.stepExecutions);
+function isWorkflowRun(run: unknown): run is RunRecord {
+  return isRecord(run) && run.type === 'workflow';
 }
 
 function isRecord(value: unknown): value is RunRecord {
   return value != null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function runExecution(run: RunRecord): RunRecord {
+  return isRecord(run.execution) ? run.execution : {};
+}
+
+function runResult(run: RunRecord): RunRecord {
+  return isRecord(run.result) ? run.result : {};
+}
+
+export function runOutput(run: unknown): unknown {
+  if (!isRecord(run)) return undefined;
+  if (run.output !== undefined) return run.output;
+  return runResult(run).output;
+}
+
+export function runUsage(run: unknown): unknown {
+  return isRecord(run) ? run.usage : undefined;
+}
+
+export function runExecutionDetails(run: unknown): unknown {
+  return isRecord(run) ? run.execution : undefined;
+}
+
+function workflowSteps(run: RunRecord): unknown[] {
+  const steps = runExecution(run).steps;
+  return Array.isArray(steps) ? steps : [];
+}
+
+function agentOutputFiles(run: RunRecord): unknown[] {
+  const rawFiles = runExecution(run).files;
+  const files: RunRecord = isRecord(rawFiles) ? rawFiles : {};
+  return Array.isArray(files.output) ? files.output : [];
+}
+
+function agentExpected(run: RunRecord): RunRecord {
+  const expected = runExecution(run).expected;
+  return isRecord(expected) ? expected : {};
+}
+
 function compareWorkflowRuns(
   referenceRunId: string,
-  reference: RunRecord & { stepExecutions: unknown[] },
+  reference: RunRecord,
   runId: string,
-  target: RunRecord & { stepExecutions: unknown[] },
+  target: RunRecord,
   stepFilter?: string
 ): RunComparisonReport {
   const wanted = stepFilter
@@ -194,11 +263,11 @@ function compareWorkflowRuns(
     .map((step) => step.trim())
     .filter(Boolean);
   const targetSteps = new Map(
-    target.stepExecutions
+    workflowSteps(target)
       .filter(isRecord)
       .map((step) => [String(step.stepName ?? step.name ?? step.id ?? ''), step])
   );
-  const steps = reference.stepExecutions
+  const steps = workflowSteps(reference)
     .filter(isRecord)
     .filter(
       (step) => !wanted?.length || wanted.includes(String(step.stepName ?? step.name ?? step.id))
@@ -237,10 +306,13 @@ function compareArtifactRuns(
 ): RunComparisonReport {
   const referenceRun = isRecord(reference) ? reference : {};
   const targetRun = isRecord(target) ? target : {};
-  const expectedValue = mode === 'baseline' ? referenceRun.output : referenceRun.expected;
+  const expectedValue =
+    mode === 'baseline' ? runOutput(referenceRun) : agentExpected(referenceRun).output;
   const expectedFiles =
-    mode === 'baseline' ? names(referenceRun.resultFiles) : names(referenceRun.expectedFiles);
-  const outputFiles = names(targetRun.resultFiles);
+    mode === 'baseline'
+      ? names(agentOutputFiles(referenceRun))
+      : names(agentExpected(referenceRun).files);
+  const outputFiles = names(agentOutputFiles(targetRun));
   const missing = expectedFiles.filter(
     (name) =>
       !outputFiles.some(
@@ -262,7 +334,7 @@ function compareArtifactRuns(
           (out) => comparableName(out, normalizeDates) === comparableName(name, normalizeDates)
         ) ?? name,
     }));
-  const jsonDifferences = diffJson(expectedValue, targetRun.output);
+  const jsonDifferences = diffJson(expectedValue, runOutput(targetRun));
   return {
     status:
       jsonDifferences.length === 0 && missing.length === 0 && extra.length === 0 ? 'pass' : 'fail',
@@ -479,14 +551,23 @@ export class RunsFilesResource {
 }
 
 export class RunsArtifactsResource {
-  constructor(private readonly client: Client) {}
+  constructor(
+    private readonly client: Client,
+    private readonly dispatch: Dispatch
+  ) {}
+
+  async list(runId: string, options: SignalOptions = {}): Promise<RunArtifactsResponse> {
+    const { signal } = options;
+    return this.dispatch(() =>
+      runsArtifactsList({ client: this.client, path: { id: runId }, signal })
+    );
+  }
 
   async download(runId: string, path: string, options: SignalOptions = {}): Promise<Blob> {
     return downloadBlob(
       () =>
-        runsArtifactGet({
-          client: this.client,
-          path: { id: runId, path },
+        this.client.get({
+          url: `/api/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeArtifactPath(path)}`,
           parseAs: 'blob',
           signal: options.signal,
         }) as Promise<OperationResult<Blob>>
@@ -546,3 +627,7 @@ async function downloadBlob(call: () => Promise<OperationResult<Blob>>): Promise
     status: result.response?.status ?? 0,
   });
 }
+
+function encodeArtifactPath(path: string): string {
+  return path.split('/').map(encodeURIComponent).join('/');
+}

package/src/telemetry.ts

@@ -19,7 +19,7 @@
 export const SDK_LANGUAGE = 'typescript';
 // Rewritten at publish time by scripts/render-sdk-versions.sh.
 // Keep this string literal exactly stable — sed matches on it.
-export const SDK_VERSION = '0.6.17';
+export const SDK_VERSION = '0.7.1';
 
 function detectRuntime(): string {
   const g = globalThis as unknown as {