runwork 0.2.0

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

@@ -0,0 +1,89 @@
+/**
+ * Base Agent - Durable Object for AI Agents
+ * DO NOT MODIFY THIS FILE - You may break the agent functionality
+ *
+ * This is the Durable Object class for AI agents built on Cloudflare's Agents SDK.
+ * It extends AIChatAgent which provides:
+ * - WebSocket connection handling
+ * - Message persistence (SQLite)
+ * - Streaming response resumption
+ * - State management
+ *
+ * LLM calls go through runwork's AI proxy, which:
+ * - Handles API keys securely (no keys in vibe-app)
+ * - Provides analytics, caching, and rate limiting via AI Gateway
+ * - Supports multiple providers (OpenAI, Anthropic, etc.)
+ *
+ * Agent definitions are loaded from the APP_AGENTS registry based on
+ * the agent name stored in the DO's storage.
+ */
+import { AIChatAgent } from 'agents/ai-chat-agent';
+import { type StreamTextOnFinishCallback, type ToolSet } from 'ai';
+import { type Env } from './core-utils';
+import { type AgentDefinition, type AgentRuntimeStatus } from './core-agent';
+/**
+ * BaseAgent - The Durable Object for all agents
+ *
+ * This class extends AIChatAgent directly, which means:
+ * - The class itself IS the Durable Object (not wrapped in another DO)
+ * - AIChatAgent handles WebSocket connections, message persistence, and streaming
+ * - We implement onChatMessage() to process incoming messages using the AI SDK
+ *
+ * Agent instances are identified by DO ID format: "{agentName}:{sessionId}"
+ */
+export declare class BaseAgent extends AIChatAgent<Env> {
+    private definition;
+    private integrationClient;
+    private agentName;
+    /**
+     * Called when the agent starts (on first request or after hibernation)
+     * Load the agent definition from storage
+     */
+    onStart(): Promise<void>;
+    /**
+     * Set the agent name and load its definition
+     * Called when initializing a new agent instance
+     */
+    setAgentName(name: string): Promise<void>;
+    /**
+     * Handle incoming chat messages using AI SDK
+     * This is the main entry point called by AIChatAgent when a message arrives
+     */
+    onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>): Promise<Response>;
+    /**
+     * Build tools from agent definition using AI SDK tool() helper
+     */
+    private buildTools;
+    /**
+     * Build tools for accessing integrations using AI SDK tool() helper
+     * Uses shared definitions from core-agent.ts, wraps with executors
+     * @param integrations - List of integration IDs to build tools for
+     */
+    private buildIntegrationTools;
+    /**
+     * Build tools for accessing entities using AI SDK tool() helper
+     * Uses entity classes directly with EntityContext
+     */
+    private buildEntityTools;
+    /**
+     * Get integration client (lazy-loaded)
+     */
+    private getIntegrationClient;
+    /**
+     * Get tool execution context
+     */
+    private getToolContext;
+    /**
+     * Get the agent's name
+     */
+    getAgentName(): string | null;
+    /**
+     * Get the agent's definition
+     */
+    getDefinition(): AgentDefinition | null;
+    /**
+     * Get runtime status - actual availability of tools and integrations
+     * This checks real connectivity, not just declared capabilities
+     */
+    getStatus(): Promise<AgentRuntimeStatus>;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Core Channels
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides:
+ * - postToChannel(): Post rich markdown messages to workspace channels
+ *
+ * Channels are auto-created if they don't exist, with automatic app event filtering.
+ * When running outside a workspace (standalone mode), calls are silently skipped.
+ */
+export interface PostToChannelParams {
+    /** Channel name (e.g., "#inventory-alerts" or "inventory-alerts"). Auto-normalized: # stripped, lowercased, trimmed. */
+    channel: string;
+    /** Markdown message content */
+    content: string;
+    /** Optional structured metadata attached to the message */
+    metadata?: Record<string, unknown>;
+}
+interface ChannelEnv {
+    WORKSPACE_API_URL?: string;
+    WORKSPACE_API_KEY?: string;
+    WORKSPACE_ID?: string;
+    APP_ID?: string;
+    APP_NAME?: string;
+    DEPLOYMENT_MODE?: 'preview' | 'production';
+    WorkspaceObject?: DurableObjectNamespace;
+}
+/**
+ * Any context that supports waitUntil - compatible with both
+ * ExecutionContext (Hono route handlers) and DurableObjectState (DOs).
+ */
+type WaitUntilContext = Pick<ExecutionContext, 'waitUntil'>;
+/**
+ * Post a rich markdown message to a workspace channel.
+ * Fire-and-forget: uses ctx.waitUntil so it doesn't block the response.
+ * Silently skips if workspace env vars are not configured (standalone mode).
+ *
+ * Channels are auto-created on first use. The channel will automatically
+ * include this app's system events via filter projection.
+ */
+export declare function postToChannel(ctx: WaitUntilContext, env: ChannelEnv, params: PostToChannelParams): void;
+export {};

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

@@ -0,0 +1,21 @@
+/**
+ * Core Component Routes
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides:
+ * 1. Component manifest API at /api/components/manifest.json
+ * 2. Auto-mounting of backend Hono handlers from worker/components/
+ *
+ * Frontend component pages live in src/pages/components/ and are served
+ * by the SPA via React Router (no Worker routing needed).
+ */
+import type { Hono } from 'hono';
+import type { Env } from './core-utils';
+/**
+ * Mount component routes on the Hono app.
+ * - Serves manifest at /api/components/manifest.json
+ * - Auto-mounts backend handlers at /api/components/{path}/*
+ */
+export declare function componentRoutes(app: Hono<{
+    Bindings: Env;
+}>): void;

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

@@ -0,0 +1,198 @@
+/**
+ * Core Public Endpoints Framework
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides the infrastructure for exposing public API endpoints
+ * that external systems can consume with API key authentication or public access.
+ */
+import { type Env } from './core-utils';
+import { z } from 'zod';
+import type { Hono } from 'hono';
+type ZodSchema = z.ZodType<any, any, any>;
+/**
+ * Authentication type for public endpoints
+ */
+export type EndpointAuthType = 'apiKey' | 'public';
+/**
+ * HTTP methods supported by endpoints
+ */
+export type EndpointMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Schema definition for endpoint validation
+ */
+export interface EndpointSchema<TQuery = unknown, TBody = unknown, TResponse = unknown> {
+    /** Query parameters schema */
+    query?: ZodSchema;
+    /** Request body schema (for POST/PUT/PATCH) */
+    body?: ZodSchema;
+    /** Response schema for documentation */
+    response?: ZodSchema;
+}
+/**
+ * Context provided to endpoint handlers
+ */
+export interface EndpointContext<TQuery = Record<string, unknown>, TBody = unknown> {
+    /** Environment bindings */
+    env: Env;
+    /** Original request object */
+    request: Request;
+    /** Validated query parameters */
+    query: TQuery;
+    /** Validated request body (null for GET/DELETE) */
+    body: TBody | null;
+    /** Path parameters extracted from URL */
+    params: Record<string, string>;
+    /** Authentication information */
+    auth: EndpointAuthInfo;
+    /** Request headers */
+    headers: Headers;
+    /** Logger for endpoint operations */
+    logger: EndpointLogger;
+}
+/**
+ * Authentication information passed to handlers
+ */
+export interface EndpointAuthInfo {
+    /** Authentication type used */
+    type: EndpointAuthType;
+    /** API key ID (if authenticated with API key) */
+    apiKeyId?: string;
+    /** Scopes granted to the API key */
+    scopes?: string[];
+    /** Whether request is authenticated */
+    authenticated: boolean;
+}
+/**
+ * Logger for endpoint operations
+ */
+export interface EndpointLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Metadata for endpoint documentation
+ */
+export interface EndpointMeta {
+    /** Human-readable description */
+    description?: string;
+    /** Tags for grouping in documentation */
+    tags?: string[];
+    /** Deprecated flag */
+    deprecated?: boolean;
+    /** Deprecation message */
+    deprecationMessage?: string;
+}
+/**
+ * Public endpoint definition
+ */
+export interface EndpointDefinition<TQuery = Record<string, unknown>, TBody = unknown, TResponse = unknown> {
+    /** URL path (e.g., '/v1/todos', '/users/:id') */
+    path: string;
+    /** HTTP method */
+    method: EndpointMethod;
+    /** Authentication requirement */
+    auth: EndpointAuthType;
+    /** Validation schemas */
+    schema?: EndpointSchema<TQuery, TBody, TResponse>;
+    /** Request handler */
+    handler: EndpointHandler<TQuery, TBody, TResponse>;
+    /** Endpoint metadata for documentation */
+    meta?: EndpointMeta;
+}
+/**
+ * Endpoint handler function type
+ */
+export type EndpointHandler<TQuery = Record<string, unknown>, TBody = unknown, TResponse = unknown> = (ctx: EndpointContext<TQuery, TBody>) => Promise<TResponse>;
+/** Type guard to distinguish EndpointDefinition from function-based route registrars */
+export declare function isEndpointDefinition(entry: unknown): entry is EndpointDefinition;
+/**
+ * Internal: Parsed endpoint info from request headers
+ */
+export interface ParsedEndpointRequest {
+    endpointId: string;
+    appId: string;
+    authType: EndpointAuthType;
+    apiKeyId?: string;
+    scopes?: string[];
+}
+/**
+ * Create a JSON response
+ */
+export declare function jsonResponse<T>(data: T, status?: number): Response;
+/**
+ * Create an error response
+ */
+export declare function errorResponse(message: string, status?: number, code?: string): Response;
+/**
+ * Convert Zod schema to JSON Schema for documentation
+ * This is a simplified conversion that handles common cases
+ */
+export declare function zodToJsonSchema(schema: ZodSchema | undefined): Record<string, unknown> | undefined;
+/**
+ * Endpoint router that matches requests to handlers
+ */
+export declare class EndpointRouter {
+    private endpoints;
+    /**
+     * Register endpoints
+     */
+    register(endpoints: EndpointDefinition<unknown, unknown, unknown>[]): void;
+    /**
+     * Find endpoint matching the request
+     */
+    findEndpoint(method: string, path: string): {
+        endpoint: EndpointDefinition<unknown, unknown, unknown>;
+        params: Record<string, string>;
+    } | null;
+    /**
+     * Get all registered endpoints for documentation
+     */
+    getAllEndpoints(): EndpointDefinition<unknown, unknown, unknown>[];
+}
+/**
+ * Mount an EndpointDefinition as a native Hono route.
+ *
+ * Registers the endpoint at its natural path using the correct HTTP method,
+ * with Zod validation for query/body schemas and full EndpointContext support.
+ * This allows EndpointDefinition entries in APP_ROUTES to work as first-class
+ * Hono routes with middleware, streaming, and WebSocket support intact.
+ */
+export declare function mountEndpointAsHonoRoute(app: Hono<{
+    Bindings: Env;
+}>, endpoint: EndpointDefinition): void;
+/**
+ * Handle an incoming public endpoint request.
+ * Called by the platform when routing requests to the app.
+ */
+export declare function handleEndpointRequest<TQuery = unknown, TBody = unknown, TResponse = unknown>(request: Request, env: Env, endpoints: EndpointDefinition<TQuery, TBody, TResponse>[]): Promise<Response>;
+/**
+ * Custom error for endpoint handlers
+ * Use this to return specific HTTP status codes
+ */
+export declare class EndpointError extends Error {
+    status: number;
+    code?: string | undefined;
+    constructor(message: string, status?: number, code?: string | undefined);
+    static badRequest(message: string): EndpointError;
+    static unauthorized(message?: string): EndpointError;
+    static forbidden(message?: string): EndpointError;
+    static notFound(message?: string): EndpointError;
+    static conflict(message: string): EndpointError;
+}
+/**
+ * Convert endpoint definition to registration data for workspace
+ */
+export declare function endpointToRegistration<TQuery = unknown, TBody = unknown, TResponse = unknown>(endpoint: EndpointDefinition<TQuery, TBody, TResponse>): {
+    path: string;
+    method: EndpointMethod;
+    auth: EndpointAuthType;
+    description?: string;
+    tags?: string[];
+    schema?: {
+        query?: Record<string, unknown>;
+        body?: Record<string, unknown>;
+        response?: Record<string, unknown>;
+    };
+};
+export {};

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

@@ -0,0 +1,276 @@
+/**
+ * Core Entity System
+ * DO NOT MODIFY THIS FILE - You may break the entity functionality
+ *
+ * This module provides:
+ * - EntityContext: Unified context for all entity operations
+ * - EntityClass: Interface that all entity types implement
+ * - EntityBase: Base class with instance methods for state management
+ * - Entity: Local storage-backed entity class (replaces IndexedEntity)
+ */
+import type { IntegrationClient } from './core-integrations';
+export interface EntityDOStub {
+    getDoc<T>(key: string): Promise<{
+        v: number;
+        data: T;
+    } | null>;
+    casPut<T>(key: string, expectedV: number, data: T): Promise<{
+        ok: boolean;
+        v: number;
+    }>;
+    del(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    bulkCreate(items: Array<{
+        key: string;
+        data: unknown;
+    }>): Promise<Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>>;
+    bulkUpdate(updates: Array<{
+        key: string;
+        data: Record<string, unknown>;
+    }>): Promise<Array<{
+        key: string;
+        ok: boolean;
+        v: number;
+        data: unknown;
+    }>>;
+    bulkDelete(keys: string[]): Promise<number>;
+    queryEntities(options?: {
+        limit?: number;
+        offset?: number;
+        cursor?: string | null;
+        filters?: Record<string, unknown>;
+        search?: {
+            query: string;
+            fields: string[];
+        };
+        sort?: {
+            field: string;
+            order: 'asc' | 'desc';
+        };
+    }): Promise<{
+        items: Array<{
+            key: string;
+            v: number;
+            data: unknown;
+        }>;
+        total: number;
+        hasMore: boolean;
+        next: string | null;
+    }>;
+    countEntities(filters?: Record<string, unknown>): Promise<number>;
+    exportAll(): Promise<Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>>;
+    importAll(items: Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>): Promise<{
+        imported: number;
+    }>;
+}
+import type { Env } from './core-utils';
+/**
+ * EntityContext - Unified context for all entity operations
+ * Both Entity and IntegrationEntity use this same context type
+ */
+export interface EntityContext {
+    env: Env;
+    client?: IntegrationClient;
+}
+/**
+ * Options for list operations
+ */
+export interface ListOptions {
+    limit?: number;
+    offset?: number;
+    cursor?: string | null;
+    filters?: Record<string, unknown>;
+    search?: {
+        query: string;
+        fields: string[];
+    };
+    sort?: {
+        field: string;
+        order: 'asc' | 'desc';
+    };
+}
+/**
+ * Paginated result from list operations
+ */
+export interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    next: string | null;
+    hasMore: boolean;
+}
+/**
+ * EntityClass - Unified interface for ALL entity types
+ *
+ * Both Entity (local storage) and IntegrationEntity (external API) implement this.
+ * All static CRUD methods take ctx as the first parameter for consistency.
+ */
+export interface EntityClass<T extends {
+    id: string;
+}> {
+    readonly entityName: string;
+    readonly schema?: Record<string, unknown>;
+    list(ctx: EntityContext, options?: ListOptions): Promise<PaginatedResult<T>>;
+    get(ctx: EntityContext, id: string): Promise<T | null>;
+    create(ctx: EntityContext, data: Partial<T>): Promise<T>;
+    update(ctx: EntityContext, id: string, data: Partial<T>): Promise<T>;
+    delete(ctx: EntityContext, id: string): Promise<void>;
+}
+/**
+ * Type-safe entity registry
+ * Maps entity names to their class implementations
+ */
+export declare const entityRegistry: Map<string, EntityClass<{
+    id: string;
+}>>;
+/**
+ * Register an entity class with the registry
+ */
+export declare function registerEntity<T extends {
+    id: string;
+}>(entityClass: EntityClass<T>): void;
+/**
+ * Register multiple entity classes at once
+ */
+export declare function registerEntities(classes: readonly EntityClass<{
+    id: string;
+}>[]): void;
+export type Doc<T> = {
+    v: number;
+    data: T;
+};
+export interface EntityStatics<S, T extends EntityBase<S>> {
+    new (env: Env, id: string): T;
+    readonly entityName: string;
+    readonly initialState: S;
+}
+/**
+ * EntityBase - Internal base class with instance methods for state management
+ *
+ * Provides CAS-based (Compare-And-Swap) state mutations for optimistic concurrency.
+ * Extended by Entity class which adds static CRUD methods.
+ */
+export declare abstract class EntityBase<State> {
+    protected _state: State;
+    protected _version: number;
+    protected readonly stub: EntityDOStub;
+    protected readonly _id: string;
+    protected readonly entityName: string;
+    protected readonly env: Env;
+    constructor(env: Env, id: string);
+    get id(): string;
+    get state(): State;
+    protected key(): string;
+    save(next: State): Promise<void>;
+    protected ensureState(): Promise<State>;
+    mutate(updater: (current: State) => State): Promise<State>;
+    getState(): Promise<State>;
+    patch(p: Partial<State>): Promise<void>;
+    exists(): Promise<boolean>;
+    delete(): Promise<boolean>;
+}
+type EntityState<T> = T extends new (env: Env, id: string) => Entity<infer S> ? S : never;
+type EntityCtor = new (env: Env, id: string) => Entity<{
+    id: string;
+}>;
+type EntityCtorStatic<TCtor> = TCtor & {
+    entityName: string;
+    keyOf(state: EntityState<TCtor>): string;
+    seedData?: ReadonlyArray<EntityState<TCtor>>;
+};
+/**
+ * Entity - Local storage-backed entity class
+ *
+ * Implements the unified EntityClass interface for local DO-backed storage.
+ * All methods take EntityContext as the first parameter.
+ *
+ * @example
+ * ```typescript
+ * export class TodoEntity extends Entity<Todo> {
+ *   static readonly entityName = 'Todo';
+ *   static readonly initialState: Todo = { id: '', title: '', completed: false };
+ * }
+ *
+ * // Usage:
+ * const ctx = { env };
+ * const todos = await TodoEntity.list(ctx, { limit: 50 });
+ * const todo = await TodoEntity.get(ctx, 'todo-123');
+ * await TodoEntity.create(ctx, { title: 'New task' });
+ * ```
+ */
+export declare abstract class Entity<S extends {
+    id: string;
+}> extends EntityBase<S> {
+    static readonly entityName: string;
+    static readonly schema?: Record<string, unknown>;
+    static keyOf<U extends {
+        id: string;
+    }>(state: U): string;
+    /**
+     * List entities with server-side filtering, search, sort, and pagination.
+     * All query operations run in SQL via EntityDO.queryEntities().
+     */
+    static list<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, options?: ListOptions): Promise<PaginatedResult<EntityState<TCtor>>>;
+    /**
+     * Get a single entity by ID
+     */
+    static get<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, id: string): Promise<EntityState<TCtor> | null>;
+    /**
+     * Count entities with optional filters
+     */
+    static count<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, filters?: Record<string, unknown>): Promise<number>;
+    /**
+     * Create a new entity
+     */
+    static create<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, data: Partial<EntityState<TCtor>>): Promise<EntityState<TCtor>>;
+    /**
+     * Update an existing entity (throws if missing)
+     */
+    static update<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, id: string, data: Partial<EntityState<TCtor>>): Promise<EntityState<TCtor>>;
+    /**
+     * Delete an entity
+     */
+    static delete<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, id: string): Promise<void>;
+    /**
+     * Ensure seed data exists (for initial data population)
+     */
+    static ensureSeed<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext): Promise<void>;
+    /**
+     * Create multiple entities in a single RPC call to the DO.
+     * Generates UUIDs for items without an id. Returns all created items.
+     */
+    static createMany<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, dataArray: Partial<EntityState<TCtor>>[]): Promise<EntityState<TCtor>[]>;
+    /**
+     * Update multiple entities in a single RPC call to the DO.
+     * Each update must include an id. Throws if any items are not found.
+     */
+    static updateMany<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, updates: (Partial<EntityState<TCtor>> & {
+        id: string;
+    })[]): Promise<EntityState<TCtor>[]>;
+    /**
+     * Delete multiple entities in a single RPC call to the DO.
+     * Returns the count of items that actually existed and were deleted.
+     */
+    static deleteMany<TCtor extends EntityCtor>(this: EntityCtorStatic<TCtor>, ctx: EntityContext, ids: string[]): Promise<number>;
+    protected ensureState(): Promise<S>;
+}
+import type { Hono } from 'hono';
+/**
+ * Mount entity routes on the Hono app
+ * Provides internal API for entity CRUD from workspace (cross-app operations)
+ */
+export declare function entityRoutes(app: Hono<{
+    Bindings: Env;
+}>): void;
+export {};