runwork 0.4.1 → 0.5.0

package/bundled-types/core-agent.d.ts

@@ -24,6 +24,7 @@
 import { z } from 'zod';
 import type { Env } from './core-utils';
 import type { IntegrationClient } from './core-integrations';
+import type { ExecutionLimits } from './task-delegation/types';
 /**
  * Agent state persisted across conversations
  */
@@ -84,6 +85,10 @@ export interface AgentDefinition {
     memoryStrategy?: MemoryStrategy;
     /** Custom tools for this agent */
     customTools?: AgentToolDefinition[];
+    /** Default task instruction for task agents. Can be overridden per execution. */
+    prompt?: string;
+    /** Cost/time limits for task agent sandbox execution. Optional overrides. */
+    executionLimits?: ExecutionLimits;
 }
 /**
  * Custom tool definition for agents
@@ -134,6 +139,9 @@ export interface RegisterAgentRequest {
     integrations: string[];
     entities: string[];
     tools?: AgentToolMeta[];
+    systemPrompt?: string;
+    prompt?: string;
+    executionLimits?: ExecutionLimits;
 }
 /**
  * Tool metadata for API responses (JSON-serializable, no Zod)

package/bundled-types/core-base-agent.d.ts

@@ -65,6 +65,10 @@ export declare class BaseAgent extends AIChatAgent<Env> {
      * Uses entity classes directly with EntityContext
      */
     private buildEntityTools;
+    /**
+     * Build tools for running complex tasks via a sandboxed AI sub-agent
+     */
+    private buildCodeExecutionTools;
     /**
      * Get integration client (lazy-loaded)
      */

package/bundled-types/core-types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * This file defines default types provided by the platform.
+ * DO NOT EDIT THIS FILE. You can define your own types in `shared/types.ts` file.
+ */
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Response from a Nango action or sync trigger
+ */
+export interface NangoActionResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    /** True if error is due to missing integration connection (user hasn't connected yet) */
+    isConnectionError?: boolean;
+    /** True if error is due to insufficient permissions/scopes (401/403 from external API) */
+    isPermissionError?: boolean;
+    /** HTTP status code from the external API (if available) */
+    statusCode?: number;
+}
+/**
+ * Nango proxy request options - used for direct API calls through Nango
+ */
+export interface NangoProxyOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    endpoint: string;
+    providerConfigKey: string;
+    data?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    retries?: number;
+}
+/**
+ * Metadata for a stored file
+ */
+export interface FileMetadata {
+    id: string;
+    key: string;
+    name: string;
+    size: number;
+    contentType: string;
+    uploadedAt: number;
+    uploadedBy?: string;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Options for uploading a file
+ */
+export interface UploadOptions {
+    key?: string;
+    name?: string;
+    contentType?: string;
+    uploadedBy?: string;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Options for downloading a file
+ */
+export interface DownloadOptions {
+    range?: {
+        offset?: number;
+        length?: number;
+    };
+}
+/**
+ * Options for listing files
+ */
+export interface ListFilesOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+    delimiter?: string;
+}
+/**
+ * Result of listing files
+ */
+export interface ListFilesResult {
+    files: FileMetadata[];
+    cursor?: string;
+    truncated: boolean;
+}
+/**
+ * Request for generating a presigned URL
+ */
+export interface PresignedUrlRequest {
+    appId: string;
+    key: string;
+    action: 'read' | 'write';
+    contentType?: string;
+    expiresIn?: number;
+}
+/**
+ * Response containing a presigned URL
+ */
+export interface PresignedUrlResponse {
+    url: string;
+    expiresAt: number;
+}

package/bundled-types/core-workspace.d.ts

@@ -7,6 +7,7 @@
  * their capabilities (entities, components, endpoints, etc.).
  */
 import type { Env } from './core-utils';
+import type { ExecutionLimits } from './task-delegation/types';
 /**
  * WorkspaceUser - Represents a member of the workspace
  * Read-only data provided by the platform
@@ -153,6 +154,9 @@ export interface RegisterAgentRequest extends Record<string, unknown> {
     integrations: string[];
     entities: string[];
     deploymentMode?: 'preview' | 'production';
+    systemPrompt?: string;
+    prompt?: string;
+    executionLimits?: ExecutionLimits;
 }
 /**
  * WorkspaceContext - Helper for cross-app data queries
@@ -255,6 +259,9 @@ export declare class WorkspaceContext {
         type: 'conversational' | 'task';
         integrations: string[];
         entities: string[];
+        systemPrompt?: string;
+        prompt?: string;
+        executionLimits?: ExecutionLimits;
     }): Promise<void>;
     /**
      * Register all scheduled jobs, removing any stale entries not in the list.
@@ -309,6 +316,9 @@ export declare class WorkspaceContext {
         type: 'conversational' | 'task';
         integrations?: string[];
         entities?: string[];
+        systemPrompt?: string;
+        prompt?: string;
+        executionLimits?: ExecutionLimits;
     }>): Promise<void>;
     /**
      * Register all components, removing any stale entries not in the list.

package/bundled-types/index.d.ts

@@ -17,3 +17,5 @@ export * from './channels';
 export * from './workspace';
 export * from './events';
 export * from './components';
+export { runAgentTask, getAgentTaskStatus } from './task-delegation';
+export type { AgentTaskExecution, RunAgentTaskOptions } from './task-delegation';

package/bundled-types/shared/core-types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * This file defines default types provided by the platform.
+ * DO NOT EDIT THIS FILE. You can define your own types in `shared/types.ts` file.
+ */
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Response from a Nango action or sync trigger
+ */
+export interface NangoActionResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    /** True if error is due to missing integration connection (user hasn't connected yet) */
+    isConnectionError?: boolean;
+    /** True if error is due to insufficient permissions/scopes (401/403 from external API) */
+    isPermissionError?: boolean;
+    /** HTTP status code from the external API (if available) */
+    statusCode?: number;
+}
+/**
+ * Nango proxy request options - used for direct API calls through Nango
+ */
+export interface NangoProxyOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    endpoint: string;
+    providerConfigKey: string;
+    data?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    retries?: number;
+}
+/**
+ * Metadata for a stored file
+ */
+export interface FileMetadata {
+    id: string;
+    key: string;
+    name: string;
+    size: number;
+    contentType: string;
+    uploadedAt: number;
+    uploadedBy?: string;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Options for uploading a file
+ */
+export interface UploadOptions {
+    key?: string;
+    name?: string;
+    contentType?: string;
+    uploadedBy?: string;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Options for downloading a file
+ */
+export interface DownloadOptions {
+    range?: {
+        offset?: number;
+        length?: number;
+    };
+}
+/**
+ * Options for listing files
+ */
+export interface ListFilesOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+    delimiter?: string;
+}
+/**
+ * Result of listing files
+ */
+export interface ListFilesResult {
+    files: FileMetadata[];
+    cursor?: string;
+    truncated: boolean;
+}
+/**
+ * Request for generating a presigned URL
+ */
+export interface PresignedUrlRequest {
+    appId: string;
+    key: string;
+    action: 'read' | 'write';
+    contentType?: string;
+    expiresIn?: number;
+}
+/**
+ * Response containing a presigned URL
+ */
+export interface PresignedUrlResponse {
+    url: string;
+    expiresAt: number;
+}

package/bundled-types/shared/shared/core-types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * This file defines default types provided by the platform.
+ * DO NOT EDIT THIS FILE. You can define your own types in `shared/types.ts` file.
+ */
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Response from a Nango action or sync trigger
+ */
+export interface NangoActionResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    /** True if error is due to missing integration connection (user hasn't connected yet) */
+    isConnectionError?: boolean;
+    /** True if error is due to insufficient permissions/scopes (401/403 from external API) */
+    isPermissionError?: boolean;
+    /** HTTP status code from the external API (if available) */
+    statusCode?: number;
+}
+/**
+ * Nango proxy request options - used for direct API calls through Nango
+ */
+export interface NangoProxyOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    endpoint: string;
+    providerConfigKey: string;
+    data?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    retries?: number;
+}
+/**
+ * Metadata for a stored file
+ */
+export interface FileMetadata {
+    id: string;
+    key: string;
+    name: string;
+    size: number;
+    contentType: string;
+    uploadedAt: number;
+    uploadedBy?: string;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Options for uploading a file
+ */
+export interface UploadOptions {
+    key?: string;
+    name?: string;
+    contentType?: string;
+    uploadedBy?: string;
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Options for downloading a file
+ */
+export interface DownloadOptions {
+    range?: {
+        offset?: number;
+        length?: number;
+    };
+}
+/**
+ * Options for listing files
+ */
+export interface ListFilesOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+    delimiter?: string;
+}
+/**
+ * Result of listing files
+ */
+export interface ListFilesResult {
+    files: FileMetadata[];
+    cursor?: string;
+    truncated: boolean;
+}
+/**
+ * Request for generating a presigned URL
+ */
+export interface PresignedUrlRequest {
+    appId: string;
+    key: string;
+    action: 'read' | 'write';
+    contentType?: string;
+    expiresIn?: number;
+}
+/**
+ * Response containing a presigned URL
+ */
+export interface PresignedUrlResponse {
+    url: string;
+    expiresAt: number;
+}

package/bundled-types/task-delegation/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * delegateTask -- orchestrates the full task-delegation flow.
+ *
+ * 1. Validates required env vars (WORKSPACE_API_URL, WORKSPACE_API_KEY)
+ * 2. Resolves execution limits (per-call options tighten but cannot loosen agent-level limits)
+ * 3. Creates a SandboxBridge and prepares the session
+ * 4. Executes the agent task with keepalive and timeout
+ * 5. Reads output files and returns the result
+ */
+import type { DelegateTaskOptions, DelegateTaskResult, DelegateTaskStream, ExecutionLimits } from './types';
+export { SandboxBridge } from './sandbox-bridge';
+export { StreamParser } from './stream-parser';
+export { filterEnvVars, generateSessionId, parseDurationToMs, buildSessionClaudeMd, buildWorkspaceClaudeMd, buildMcpSettingsJson, buildPrepareSessionRequest, buildCleanupCommands, } from './session-manager';
+export { delegateTaskToolSchema, RESERVED_ENV_VARS } from './types';
+export type { DelegateTaskOptions, DelegateTaskResult, DelegateTaskStream, DelegateTaskStreamEvent, DelegateTaskStreamTextEvent, DelegateTaskStreamToolUseEvent, DelegateTaskStreamToolResultEvent, DelegateTaskStreamErrorEvent, DelegateTaskStreamStatusEvent, DelegateTaskUsage, DelegateTaskInputFile, DelegateTaskOutputFile, ExecutionLimits, ExecutionStreamLog, DelegateWorkspaceContext, PrepareSessionRequest, PrepareSessionResponse, ExecuteAgentRequest, ExecuteAgentResponse, ReadOutputsRequest, ReadOutputsResponse, } from './types';
+/**
+ * Contextual information provided by the calling agent/framework
+ * to configure the delegated task execution environment.
+ */
+export interface DelegateTaskContext {
+    env: {
+        WORKSPACE_API_URL?: string;
+        WORKSPACE_API_KEY?: string;
+        WORKSPACE_ID?: string;
+        APP_ID?: string;
+        APP_NAME?: string;
+        RUNWORK_AI_PROXY_URL?: string;
+        RUNWORK_PROXY_TOKEN?: string;
+        [key: string]: string | undefined;
+    };
+    /** Name of the agent initiating the task; used for logging and session paths */
+    agentName?: string;
+    /** Agent-level execution limits; per-call options can tighten but not loosen these */
+    executionLimits?: ExecutionLimits;
+}
+/**
+ * Delegate a task to a subordinate agent process running in a sandboxed
+ * environment. The process has access to tools, can read/write files, and
+ * returns structured output when complete.
+ *
+ * Non-streaming overload: awaits the full result.
+ */
+export declare function delegateTask(options: DelegateTaskOptions, context: DelegateTaskContext): Promise<DelegateTaskResult>;
+/**
+ * Streaming overload: returns a DelegateTaskStream that yields events as the
+ * task progresses. The final result is available via `stream.result`.
+ */
+export declare function delegateTask(options: DelegateTaskOptions & {
+    stream: true;
+}, context: DelegateTaskContext): DelegateTaskStream;

package/bundled-types/task-delegation/sandbox-bridge.d.ts

@@ -0,0 +1,88 @@
+/**
+ * SandboxBridge - HTTP client for the WorkspaceAgent /agent-sandbox/* routes.
+ * Runs inside vibe-app Workers/DOs (framework code) and uses the standard
+ * Cloudflare Workers fetch API — no external dependencies.
+ */
+import type { PrepareSessionRequest, PrepareSessionResponse, ExecuteAgentRequest, ExecuteAgentResponse, ReadOutputsRequest, ReadOutputsResponse, DelegateWorkspaceContext } from './types';
+export declare class SandboxBridge {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly workspaceId;
+    constructor(workspaceApiUrl: string, workspaceApiKey: string, workspaceId: string);
+    private request;
+    /**
+     * Prepare (or resume) a sandbox session.
+     * Must be called before executing code in a new session.
+     */
+    prepareSession(req: PrepareSessionRequest): Promise<PrepareSessionResponse>;
+    /**
+     * Execute a Agent task inside the sandbox session.
+     * Returns the full output once the run completes.
+     */
+    executeAgent(req: ExecuteAgentRequest): Promise<ExecuteAgentResponse>;
+    /**
+     * Execute a Agent task with SSE streaming output.
+     * Returns the raw Response so the caller can parse the event stream.
+     * The body contains `stream: true` and `Accept: text/event-stream` is set.
+     */
+    executeAgentStream(req: ExecuteAgentRequest): Promise<Response>;
+    /**
+     * Read file contents back from the sandbox after execution.
+     */
+    readOutputs(req: ReadOutputsRequest): Promise<ReadOutputsResponse>;
+    /**
+     * Query the current status of a sandbox session.
+     * Returns whether the session process is still running and its exit code if finished.
+     */
+    getSessionStatus(sessionId: string): Promise<{
+        running: boolean;
+        exitCode?: number;
+    }>;
+    /**
+     * Fetch workspace context (apps, MCP servers, skills) from the WorkspaceAgent.
+     * Used to populate CLAUDE.md and MCP settings with real workspace data.
+     */
+    getWorkspaceContext(): Promise<DelegateWorkspaceContext>;
+    /**
+     * Save the full event log for a completed execution to R2 for replay.
+     */
+    saveExecutionStream(req: {
+        sessionId: string;
+        content: string;
+    }): Promise<void>;
+    /**
+     * Retrieve a previously saved execution stream from R2.
+     * Returns null if the stream has not been persisted yet.
+     */
+    getExecutionStream(sessionId: string): Promise<{
+        executionId: string;
+        events: Array<{
+            type: string;
+            [key: string]: unknown;
+        }>;
+        result: {
+            response: string;
+            usage: {
+                inputTokens: number;
+                outputTokens: number;
+                cost: number;
+            };
+            exitCode: number;
+        };
+        timestamp: string;
+    } | null>;
+    /**
+     * Read new content from the stream.log file for a running or completed execution.
+     * Uses offset-based reads so callers only get new content each poll.
+     * Returns the new content and the updated offset for the next poll.
+     */
+    readStreamLog(sessionPath: string, offset?: number): Promise<{
+        content: string;
+        offset: number;
+    }>;
+    /**
+     * Send a keepalive ping to reset the sandbox idle timer.
+     * Fire-and-forget: errors are silently swallowed to avoid disrupting the caller.
+     */
+    sendKeepalive(): void;
+}

package/bundled-types/task-delegation/session-manager.d.ts

@@ -0,0 +1,86 @@
+import type { DelegateTaskOptions } from './types';
+export declare function generateSessionId(): string;
+export declare function buildWorkspaceClaudeMd(context: {
+    workspaceName: string;
+    workspaceId: string;
+    apps: Array<{
+        name: string;
+        id: string;
+        description: string;
+    }>;
+    mcpServers: string[];
+    externalMcpServers: string[];
+}): string;
+export declare function buildSessionClaudeMd(context: {
+    appName: string;
+    appId: string;
+    agentName: string;
+    sessionId: string;
+    maxBudget: number;
+    timeout: string;
+}): string;
+export declare function buildMcpSettingsJson(context: {
+    workspaceId: string;
+    workspaceMcpUrl?: string;
+    apps: Array<{
+        name: string;
+        id: string;
+        mcpUrl?: string;
+    }>;
+    externalMcpServers?: Array<{
+        name: string;
+        url?: string;
+        command?: string;
+        args?: string[];
+    }>;
+}): string;
+export declare function filterEnvVars(env: Record<string, string> | undefined): Record<string, string>;
+export declare function buildPrepareSessionRequest(options: DelegateTaskOptions, context: {
+    appId: string;
+    appName: string;
+    agentName: string;
+    maxBudget: number;
+    timeout: string;
+    workspaceName: string;
+    workspaceId: string;
+    workspaceMcpUrl?: string;
+    apps: Array<{
+        name: string;
+        id: string;
+        description: string;
+        mcpUrl?: string;
+    }>;
+    mcpServers: string[];
+    externalMcpServers: Array<{
+        name: string;
+        url?: string;
+        command?: string;
+        args?: string[];
+    }>;
+    skillFiles: Array<{
+        name: string;
+        content: string;
+    }>;
+}): {
+    appId: string;
+    agentName: string;
+    sessionId: string;
+    inputFiles: {
+        name: string;
+        content: string;
+        encoding: "utf-8" | "base64";
+    }[];
+    claudeMdContent: string;
+    workspaceClaudeMdContent: string;
+    settingsJsonContent: string;
+    skillFiles: {
+        name: string;
+        content: string;
+    }[];
+};
+/**
+ * Returns shell commands to clean up sessions older than maxAgeDays.
+ * Called lazily by prepare-session route before creating new sessions.
+ */
+export declare function buildCleanupCommands(basePath: string, appId: string, agentName: string, maxAgeDays?: number): string[];
+export declare function parseDurationToMs(duration: string): number;

package/bundled-types/task-delegation/stream-parser.d.ts

@@ -0,0 +1,25 @@
+import type { DelegateTaskStreamEvent, DelegateTaskUsage } from './types';
+/**
+ * Parses Agent sandbox `--output-format stream-json` output into typed events.
+ *
+ * Agent sandbox emits one JSON object per line. This parser converts each line
+ * into zero or more DelegateTaskStreamEvent objects and accumulates token
+ * usage/cost across the full run.
+ *
+ * Designed for use both in real-time streaming (parse each line as it arrives)
+ * and post-hoc parsing (parse all stdout lines after execution completes).
+ */
+export declare class StreamParser {
+    private accumulatedUsage;
+    private lastResponse;
+    /**
+     * Parse a single line of Agent sandbox stream-json output into zero or more
+     * DelegateTaskStreamEvents. Returns an empty array for empty lines, invalid
+     * JSON, or unknown message types.
+     */
+    parseLine(line: string): DelegateTaskStreamEvent[];
+    /** Return a copy of the usage accumulated across all parsed messages. */
+    getAccumulatedUsage(): DelegateTaskUsage;
+    /** Return the last assistant response text seen in the stream. */
+    getLastResponse(): string;
+}

package/bundled-types/task-delegation/task-delegation/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Task delegation -- thin HTTP wrappers for the platform's task agent API.
+ *
+ * runAgentTask() triggers execution via /trigger-task-agent.
+ * getAgentTaskStatus() polls execution status via /agent-execution/:id.
+ */
+import type { RunAgentTaskOptions, AgentTaskExecution } from './types';
+import type { Env } from '../core-utils';
+export { agentTaskToolSchema, RESERVED_ENV_VARS } from './types';
+export type { AgentTaskResult, AgentTaskUsage, AgentTaskInputFile, AgentTaskOutputFile, ExecutionLimits, AgentTaskExecution, RunAgentTaskOptions, } from './types';
+/**
+ * Trigger a task agent execution via the platform's /trigger-task-agent endpoint.
+ *
+ * This is a thin HTTP wrapper -- it asks the platform to start (or resume) an
+ * agent execution and returns the execution metadata. Use
+ * {@link getAgentTaskStatus} to poll for completion when running in async mode.
+ *
+ * @param agentName - Agent name. Use "appId:agentName" to target an agent in
+ *   another app; otherwise the current app's APP_ID is used.
+ * @param env - Worker environment bindings (needs WORKSPACE_API_URL, WORKSPACE_API_KEY, APP_ID)
+ * @param options - Optional prompt, input files, timeout, session resume, and await flag
+ */
+export declare function runAgentTask(agentName: string, env: Env, options?: RunAgentTaskOptions): Promise<AgentTaskExecution>;
+/**
+ * Query the status of a task agent execution by its execution ID.
+ *
+ * @param executionId - The execution identifier returned by {@link runAgentTask}
+ * @param env - Worker environment bindings (needs WORKSPACE_API_URL, WORKSPACE_API_KEY)
+ */
+export declare function getAgentTaskStatus(executionId: string, env: Env): Promise<AgentTaskExecution>;