workflow-studio/compute

Overview

This document covers the internal architecture of the @workflow-studio/compute package, which defines the core types and interfaces for remote workflow execution.

Package Structure

packages/compute/
├── src/
│   ├── index.ts           # Core types and adapter
│   └── types.ts           # Additional type definitions (if any)
└── package.json

Core Types

Compute Scopes

Authentication scopes for API operations:

export type ComputeScope =
  | 'trigger:write'   // Trigger new workflow runs
  | 'runs:read'       // Read run status and results
  | 'runs:write'      // Cancel or resume runs
  | 'deploy:read'     // Read deployment information
  | 'deploy:write'    // Create and activate deployments
  | 'admin'           // Full access
  | 'world:proxy';    // Internal world operations

Execution Mode

export type ExecutionMode = 'local' | 'remote';

Trigger Request/Response

export interface ComputeTriggerRequest {
  workflowName: string;
  input?: unknown;
  runId?: string;
  deploymentId?: string;
  specVersion?: number;
}

export interface ComputeTriggerResponse {
  runId: string;
  status: string;
  deploymentId: string;
}

Resume Request/Response

export interface ComputeResumeRequest {
  runId: string;
  reason?: string;
  payload?: unknown;
}

export interface ComputeResumeResponse {
  accepted: boolean;
}

Webhook Response

export interface ComputeWebhookResponse {
  accepted: boolean;
  eventId?: string;
}

Compute Interface

The Compute interface defines the contract between the app host and the execution backend:

export interface Compute {
  // Deployment
  getDeploymentId(): Promise<string>;
  
  // Queue operations
  publish(
    queueName: ValidQueueName,
    message: QueuePayload,
    opts?: QueueOptions
  ): Promise<{ messageId: MessageId }>;
  
  createConsumer(
    queueNamePrefix: QueuePrefix,
    handler: (
      message: unknown,
      meta: {
        attempt: number;
        queueName: ValidQueueName;
        messageId: MessageId;
      }
    ) => Promise<void | { timeoutSeconds: number }>
  ): (req: Request) => Promise<Response>;
  
  // Optional lifecycle hooks
  trigger?(req: ComputeTriggerRequest): Promise<ComputeTriggerResponse>;
  resume?(req: ComputeResumeRequest): Promise<ComputeResumeResponse>;
  webhookIngress?(provider: string, req: Request): Promise<ComputeWebhookResponse>;
  waitUntil?(promise: Promise<unknown>): void;
  getBaseUrl?(port?: number): Promise<string> | string;
  start?(): Promise<void>;
  close?(): Promise<void>;
}

World Compute Adapter

The createWorldComputeAdapter function bridges the Compute interface to a World instance:

export function createWorldComputeAdapter(world: World): Compute {
  return {
    getDeploymentId: () => world.getDeploymentId(),
    
    publish: (queueName, message, opts) => 
      world.queue(queueName, message, opts),
    
    createConsumer: (prefix, handler) => 
      world.createQueueHandler(prefix, handler),
    
    start: world.start?.bind(world),
    close: world.close?.bind(world),
  };
}

This adapter is used by the compute worker when running in "local" mode (where the worker's world is the actual execution environment).

Type Dependencies

The Compute interface depends on types from @workflow/world:

import type {
  MessageId,
  QueueOptions,
  QueuePayload,
  QueuePrefix,
  ValidQueueName,
  World,
} from '@workflow/world';

These types ensure compatibility between the compute layer and the underlying world implementation.

On this page