runwork 0.25.3 → 0.26.0

package/bundled-types/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Framework client entry: browser-side helpers an app's frontend imports as
+ * `@runworkai/framework/client`, so app code never carries this plumbing
+ * itself.
+ *
+ * Analytics: what people do in the app, reported to the workspace.
+ *
+ * Envelope follows the Segment Spec (the de-facto standard Google Analytics,
+ * Mixpanel, PostHog and friends all map to), so nothing here needs to change
+ * if the workspace later forwards events to a real analytics tool.
+ *
+ * The app does not interpret events. `/api/analytics` stamps the app's
+ * identity and forwards to the workspace, which decides what each one means.
+ * Today a `page` counts as one USE of the app, the multiplier behind a
+ * standalone app's value in the workspace's reports. `track` events are kept
+ * for a later analytics surface.
+ *
+ * A page load is reported here because the document is served before the
+ * app's Worker runs, leaving no server-side trace otherwise. Once per
+ * document, not per route change: the workspace counts an opened tool, and a
+ * person navigating inside it is still one use.
+ *
+ * Fire-and-forget. Nothing here may ever affect the person using the app.
+ */
+/** Record a custom event. Use a flat Title Case name ("Report Exported") and put variables in properties. */
+export declare function track(event: string, properties?: Record<string, unknown>): void;
+/** Record a named screen or view inside the app. */
+export declare function screen(name: string, properties?: Record<string, unknown>): void;
+/**
+ * Tell the workspace who this browser belongs to, in the APP's own terms.
+ * A claim, recorded as data; the workspace never grants anything on it.
+ */
+export declare function identify(userId: string, traits?: Record<string, unknown>): void;
+/** Attach this person to a company, account or team the app knows about. */
+export declare function group(groupId: string, traits?: Record<string, unknown>): void;
+/** Link a past anonymous identity to a known one. */
+export declare function alias(userId: string, previousId?: string): void;
+/** Record that this app was opened. Called once automatically on load. */
+export declare function page(): void;

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

@@ -230,8 +230,8 @@ export declare const integrationApiSchema: z.ZodObject<{
     endpoint: z.ZodString;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    method: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
     endpoint: string;
+    method: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
     data?: Record<string, unknown> | undefined;
 }, {
     endpoint: string;

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

@@ -66,8 +66,6 @@ export type Doc<T> = {
  * - Security validation on all field names
  */
 export declare class EntityDO extends DurableObject<Env> {
-    ctx: DurableObjectState;
-    env: Env;
     private _tableReady;
     private _migrationDone;
     constructor(ctx: DurableObjectState, env: Env);

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

@@ -41,12 +41,5 @@ export declare function toChannelName(appName: string): string;
  * these entries in the observability timeline.
  */
 export declare function flog(level: 'info' | 'warn' | 'error', system: string, message: string, data?: Record<string, unknown>): void;
-/**
- * Emit an event to the workspace unified event stream.
- * Fire-and-forget: uses ctx.waitUntil so it doesn't block the response.
- * Silently skips if workspace env vars are not configured (standalone mode).
- *
- * Automatically routes events to a channel derived from APP_NAME when available.
- */
 export declare function emitEvent(ctx: WaitUntilContext, env: EventEnv, event: EmitEventParams): void;
 export {};

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

@@ -207,10 +207,6 @@ export declare class FileStorageClient {
  */
 export declare function createFileStorageClient(env: Env): FileStorageClient;
 import type { Hono } from 'hono';
-/**
- * Mount file storage routes on the Hono app
- * Provides REST API for R2 bucket operations
- */
 export declare function fileStorageRoutes(app: Hono<{
     Bindings: Env;
 }>): void;

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

@@ -69,7 +69,109 @@ export declare const isStr: (s: unknown) => s is string;
  * that would cause structured clone to fail in ctx.storage.put().
  */
 export declare function safeClone<T>(value: T, fallback?: T): T;
-export declare function platformFetch(env: Env, url: string | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Platform fetch - routes requests through WorkspaceObject DO for production workers.
+ *
+ * Workers for Platforms (WfP) workers cannot reliably make HTTP requests back to their
+ * parent platform worker (they get 522 timeouts). This utility routes platform API calls
+ * through the WorkspaceObject Durable Object binding, which works across worker boundaries.
+ *
+ * Supported paths:
+ * - /api/proxy/integrations/* - Integration proxy (Nango)
+ * - /api/proxy/openai/* - AI Gateway proxy
+ * - /api/storage/presign - Storage presigned URLs
+ *
+ * For preview containers (DEPLOYMENT_MODE !== 'production'), uses standard fetch.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * const response = await fetch('https://runwork.ai/api/proxy/integrations/proxy/contacts', options);
+ *
+ * // Use:
+ * const response = await platformFetch(env, 'https://runwork.ai/api/proxy/integrations/proxy/contacts', options);
+ * ```
+ */
+/**
+ * What the app was doing when it made a call.
+ *
+ * Internal plumbing, deliberately not exported from the package: app authors
+ * never set this, the framework establishes it at each entry point (schedule
+ * tick, workflow run, route handler, agent turn) and `platformFetch` below
+ * reads it. It lives beside `platformFetch` because that is its only consumer.
+ *
+ * WHY IT EXISTS: usage rows record `appId` and `userId` and nothing about what
+ * was executing, so a HubSpot call made by a nightly schedule cannot be told
+ * apart from one a person made from their own agent. `runId` is the field that
+ * cannot be reconstructed later: it links one run's AI calls and integration
+ * calls together, which is what per-run cost is built from.
+ *
+ * Design: docs/plans/2026-08-28-baselines-capture-redesign.md section 4.1.
+ */
+export interface RunContext {
+    /**
+     * WHAT was executing. Only constructs the framework itself runs, never
+     * "where the caller was" (a browser, MCP, the CLI): that is a different
+     * question and `audit_logs.actor_type` owns it.
+     */
+    kind: 'schedule' | 'workflow' | 'endpoint' | 'route' | 'agent';
+    /**
+     * Human-readable name, following the convention the audit rows already use:
+     * a schedule/workflow/agent slug, or `METHOD /path` for endpoints and routes.
+     *
+     * OMITTED rather than defaulted when genuinely unknown. A placeholder string
+     * like 'unknown' becomes a value every query has to filter out, and it is
+     * indistinguishable from an app that named something 'unknown'.
+     */
+    name?: string;
+    /**
+     * App-local registry key, so a usage row joins back to a registration. The
+     * app id is a column of its own, so this is the part after it: a slug for
+     * schedules, workflows and agents, `METHOD /path` for endpoints.
+     */
+    resourceKey?: string;
+    /** One id shared by everything emitted inside this execution. */
+    runId: string;
+    /** The enclosing run, for workflow steps, nested calls and sub-agents. */
+    parentRunId?: string;
+    trigger?: 'cron' | 'manual' | 'webhook' | 'chat' | 'api';
+    /**
+     * The person who started this run. Named to match the governance program's
+     * `DelegationChain.triggererUserId` (`worker/types/permissions.ts`), which is
+     * the same fact: one name for it across both programs.
+     *
+     * ATTRIBUTION, NEVER AUTHORITY. This travels on a header from the app, behind
+     * the shared WORKSPACE_API_KEY, so an app can put any user id here. The
+     * platform may RECORD it; nothing may ever AUTHORIZE on it. Whose authority a
+     * run borrows is resolved platform-side by PermissionService, not stated by
+     * the caller.
+     */
+    triggererUserId?: string;
+    attempt?: number;
+}
+/** Header carrying the context to the platform side, which writes the audit row. */
+export declare const RUN_CONTEXT_HEADER = "x-runwork-run-context";
+/**
+ * Run `fn` with `ctx` as the ambient execution context.
+ *
+ * Nesting is automatic: entering a context inside another records the outer
+ * `runId` as `parentRunId` unless the caller set one. That is what makes a
+ * sub-agent's calls point at the run that started it. Re-entering the SAME
+ * run id is not nesting (a workflow resumes into its own run across wake-ups)
+ * and must not make a run its own parent.
+ */
+export declare function withRunContext<T>(ctx: RunContext, fn: () => T): T;
+/** The current execution context, or undefined outside any entry point. */
+export declare function getRunContext(): RunContext | undefined;
+/**
+ * Merge the context header into request headers.
+ *
+ * One serialised header rather than several, so adding a field never needs a
+ * matching change in the platform's parsing. Never overwrites a header the
+ * caller set: a caller that knows its own context beats the ambient one.
+ */
+export declare function withRunContextHeader(init?: HeadersInit): HeadersInit | undefined;
+export declare function platformFetch(env: Env, url: string | URL, rawInit?: RequestInit): Promise<Response>;
 /**
  * Workspace API fetch - routes workspace service requests through WorkspaceObject DO
  * for production WfP workers, avoiding 522 recursive invocation errors.
@@ -82,4 +184,4 @@ export declare function platformFetch(env: Env, url: string | URL, init?: Reques
  * @param path - Workspace API sub-path (e.g., '/ingest-event')
  * @param init - Standard fetch options
  */
-export declare function workspaceApiFetch(env: Pick<Env, 'WORKSPACE_API_URL' | 'WORKSPACE_API_KEY' | 'WORKSPACE_ID' | 'DEPLOYMENT_MODE' | 'WorkspaceObject'>, path: string, init?: RequestInit): Promise<Response>;
+export declare function workspaceApiFetch(env: Pick<Env, 'WORKSPACE_API_URL' | 'WORKSPACE_API_KEY' | 'WORKSPACE_ID' | 'DEPLOYMENT_MODE' | 'WorkspaceObject'>, path: string, rawInit?: RequestInit): Promise<Response>;

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

@@ -9,7 +9,7 @@
  * - Types are defined in core-workflow-types.ts
  * - Native DO-based implementation is in core-workflow-instance.ts and core-workflow-coordinator.ts
  */
-import type { Env } from './core-utils';
+import { type Env } from './core-utils';
 export type { WorkflowResult, WorkflowStatus, WorkflowInstanceInfo, WorkflowDefinition, WorkflowContext, WorkflowStepUtilities, StepOptions, WaitEventOptions, WorkflowLogger, WorkflowState, WorkflowStatusResponse, } from './core-workflow-types';
 import type { WorkflowInstanceInfo } from './core-workflow-types';
 /**