Executions API

cancel(executionId: string): Promise<ExecutionBase & { userId: string; createdAt: string; startedAt?: string; completedAt?: string; readonly replayed?: true; readonly source?: ExecutionSource; readonly attachments?: ExecutionAttachmentSummary; } & { status: "cancelled"; output?: never; error: ExecutionCancelledError; latencyMs: number; cancellation: ExecutionCancellation; }>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const cancelled = await eyeball.executions.cancel(
  "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
);
if (cancelled.cancellation.dispatchMayHaveBegun) {
  console.warn("Cancellation is best effort; upstream work may complete.");
} else {
  console.log("Provider dispatch was fenced.");
}

get(executionId: string): Promise<ExecutionRecord>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const execution = await eyeball.executions.get(
  "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
);
if (execution.replayed === true) console.log("Accepted replay observed");
if (execution.source?.kind === "voice_session") {
  console.log(execution.source.sessionId);
}
for (const fileId of execution.attachments?.fileIds ?? []) {
  console.log(fileId);
}

list(options?: ListExecutionsOptions): Promise<ExecutionPage>

wait(executionId: string, options?: WaitForExecutionOptions): Promise<TerminalExecutionRecord>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const execution = { executionId: "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8" };

const terminal = await eyeball.executions.wait(execution.executionId, {
  pollMs: 500,
  timeoutMs: 60_000,
});

export interface ListExecutionsOptions {
  status?: ExecutionStatus;
  /** Canonical dotted or restricted wire name. */
  tool?: string;
  /** Uses the client-level userId when omitted. */
  userId?: string;
  cursor?: string;
  limit?: number;
}

export interface WaitForExecutionOptions {
  /** Milliseconds between polls. Defaults to 500. */
  pollMs?: number;
  /** Total milliseconds before a timeout error. Defaults to 60,000. */
  timeoutMs?: number;
}

export interface ExecutionPage {
  executions: readonly ExecutionRecord[];
  nextCursor?: string;
}

export type AsyncExecuteResponse = ExecutionBase & { status: "pending" };

export type ExecutionId = `exe_${string}`;

export interface ExecutionAttachmentSummary {
  readonly count: number;
  readonly fileIds: readonly FileId[];
}

export interface ExecutionCancellation {
  readonly dispatchMayHaveBegun: boolean;
}

export type CancelledExecutionRecord = Extract<
  ExecutionRecord,
  { status: "cancelled" }
>;

export type ExecutionMode = "sync" | "async";

export type ExecutionRecord = ExecutionBase & {
  userId: string;
  createdAt: string;
  startedAt?: string;
  completedAt?: string;
  /**
   * Present as literal `true` after at least one accepted idempotent replay has
   * been observed for this execution.
   *
   * A replay reuses this record's execution ID. Absence does not show whether
   * the original request carried an idempotency key. No raw idempotency key,
   * prefix, hash, scope, or other derivative is included.
   */
  readonly replayed?: true;
  /** Verified bounded origin metadata, when the execution has one. */
  readonly source?: ExecutionSource;
  /** Distinct staged-file IDs referenced by the validated execution input. */
  readonly attachments?: ExecutionAttachmentSummary;
} & (
    | {
        status: "pending" | "running";
        output?: never;
        error?: never;
        latencyMs?: never;
      }
    | {
        status: "succeeded";
        output: JsonValue;
        error?: never;
        latencyMs: number;
      }
    | {
        status: "failed";
        output?: never;
        error: NormalizedToolError;
        latencyMs: number;
      }
    | {
        status: "cancelled";
        output?: never;
        error: ExecutionCancelledError;
        latencyMs: number;
        cancellation: ExecutionCancellation;
      }
  );

export type ExecutionResult = SyncExecuteResponse | AsyncExecuteResponse;

export type ExecutionSource = {
  readonly kind: "voice_session";
  readonly sessionId: string;
};

export type ExecutionStatus =
  | "pending"
  | "running"
  | "succeeded"
  | "failed"
  | "cancelled";

export type TerminalExecutionRecord =
  | SucceededExecutionRecord
  | FailedExecutionRecord
  | CancelledExecutionRecord;