runwork 0.24.0 → 0.25.0

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

@@ -81,6 +81,16 @@ export interface AgentDefinition {
     integrations?: string[];
     /** Entity names the agent can read/write */
     entities?: string[];
+    /**
+     * Endpoints on OTHER apps in this workspace that the agent may call, as
+     * `'<app>:<METHOD>:<path>'` — e.g. `'labcrm:GET:/v1/portal/catalog'`.
+     * `<app>` is the target app's slug; `<path>` is the path exactly as registered,
+     * `:param` placeholders included.
+     *
+     * Declared explicitly, like `entities` and `integrations`: an agent can only
+     * call what the app author listed, never an arbitrary endpoint.
+     */
+    appEndpoints?: string[];
     /** Memory strategy */
     memoryStrategy?: MemoryStrategy;
     /** Custom tools for this agent */
@@ -90,6 +100,27 @@ export interface AgentDefinition {
     /** Cost/time limits for task agent sandbox execution. Optional overrides. */
     executionLimits?: ExecutionLimits;
 }
+/** A parsed `'<app>:<METHOD>:<path>'` agent endpoint reference. */
+export interface AppEndpointRef {
+    app: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+}
+/**
+ * Parse `'labcrm:GET:/v1/portal/invite/:token'`.
+ *
+ * Split on the first two colons only: the path itself contains colons for its
+ * `:param` segments, so a naive split would mangle every parameterized endpoint.
+ * Returns null for anything malformed rather than throwing, so one bad entry in an
+ * agent definition costs that one tool instead of the whole agent.
+ */
+export declare function parseAppEndpointRef(ref: string): AppEndpointRef | null;
+/**
+ * Stable, model-friendly tool name for an endpoint reference, e.g.
+ * `call_labcrm_get_v1_portal_invite`. Param segments are dropped so the name
+ * stays readable; the full path is in the tool description.
+ */
+export declare function appEndpointToolName(ref: AppEndpointRef): string;
 /**
  * Custom tool definition for agents
  */

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

@@ -64,6 +64,13 @@ export declare class BaseAgent extends AIChatAgent<Env> {
      * Build tools for accessing entities using AI SDK tool() helper
      * Uses entity classes directly with EntityContext
      */
+    /**
+     * One tool per endpoint the agent is allowed to call on another app.
+     *
+     * Routed through `callAppEndpoint`, so it works in preview and production
+     * alike: a production app cannot HTTP-fetch a sibling's public URL.
+     */
+    private buildAppEndpointTools;
     private buildEntityTools;
     /**
      * Build tools for running complex tasks via a sandboxed AI sub-agent

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

@@ -15,11 +15,16 @@ type ZodSchema = z.ZodType<any, any, any>;
 export type EndpointAuthType = 'apiKey' | 'public';
 /**
  * Caller principal type resolved by the platform and passed via the
- * `X-Public-Endpoint-Auth-Type` header. `user` and `workspace_key` are
+ * `X-Public-Endpoint-Auth-Type` header. `user`, `workspace_key` and `app` are
  * authenticated principals the platform has already authorized; `api_key`
  * additionally carries a validated key id; `none` is unauthenticated.
+ *
+ * `app` means a sibling app in the same workspace called this endpoint through
+ * the platform (see `callAppEndpoint`). The platform records which app made the
+ * call, but does not forward that id here: it is self-asserted by the caller and
+ * must not be used for authorization until app identity is verifiable.
  */
-export type EndpointPrincipalType = 'none' | 'api_key' | 'workspace_key' | 'user';
+export type EndpointPrincipalType = 'none' | 'api_key' | 'workspace_key' | 'user' | 'app';
 /**
  * HTTP methods supported by endpoints
  */
@@ -62,7 +67,7 @@ export interface EndpointContext<TQuery = Record<string, unknown>, TBody = unkno
 export interface EndpointAuthInfo {
     /** Authentication requirement declared by the endpoint */
     type: EndpointAuthType;
-    /** Resolved caller principal type (api_key, workspace_key, user, none) */
+    /** Resolved caller principal type (api_key, workspace_key, user, app, none) */
     principalType?: EndpointPrincipalType;
     /** API key ID (if authenticated with an API key) */
     apiKeyId?: string;

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

@@ -162,6 +162,34 @@ export interface RegisterAgentRequest extends Record<string, unknown> {
  * WorkspaceContext - Helper for cross-app data queries
  * Provides methods to query entities from other apps in the same workspace
  */
+/**
+ * Options for calling a public endpoint on another app in the workspace.
+ */
+export interface CallAppEndpointOptions {
+    /**
+     * Target app, normally its slug as shown in the dashboard (e.g. 'labcrm').
+     * An app id or worker name also resolves. If the slug is wrong, the error
+     * response lists the slugs available in this workspace.
+     */
+    app: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Endpoint path exactly as registered, path params included: '/v1/orders/:id'. */
+    path: string;
+    /** Values for the `:param` segments in `path`. */
+    pathParams?: Record<string, string>;
+    queryParams?: Record<string, string>;
+    /** JSON body. Ignored for GET and HEAD. */
+    body?: unknown;
+}
+/**
+ * Result of a cross-app endpoint call. `ok` and `status` are the target
+ * endpoint's own response status, not the transport's.
+ */
+export interface CallAppEndpointResult<T = unknown> {
+    ok: boolean;
+    status: number;
+    data: T;
+}
 export declare class WorkspaceContext {
     private env;
     private workspaceId;
@@ -198,6 +226,45 @@ export declare class WorkspaceContext {
      * Delete an entity in another app in the workspace
      */
     deleteEntity(entityName: string, id: string): Promise<void>;
+    /**
+     * Transport for cross-app endpoint calls.
+     *
+     * Deliberately NOT `workspaceFetch`, for two reasons:
+     *
+     * 1. `workspaceFetch` retries over HTTP whenever the Durable Object returns a
+     *    non-2xx. That is right for entity CRUD, where a non-2xx means the DO
+     *    itself failed. Here a non-2xx is the TARGET ENDPOINT'S OWN ANSWER, so
+     *    retrying would re-send the request — duplicating POSTs — and in production
+     *    the retry goes to the platform's own domain, which a Workers for Platforms
+     *    worker cannot fetch: it hangs until timeout, the very failure this function
+     *    exists to avoid. A status is a result, never a transport error.
+     *
+     * 2. Production therefore uses the DO binding ONLY, mirroring `workspaceApiFetch`
+     *    in core-utils.ts, which is the proven path for every other platform call
+     *    made from a deployed app. Preview and sandbox keep the HTTP path, where the
+     *    app is reached over a tunnel rather than the dispatch namespace.
+     */
+    private endpointCallFetch;
+    /**
+     * Call a public endpoint on another app in this workspace.
+     *
+     * Production apps run in a Workers for Platforms dispatch namespace and cannot
+     * HTTP-fetch the platform's app domain, so a direct `fetch()` to a sibling app's
+     * public URL hangs until it times out. This routes through the workspace instead,
+     * which reaches the target app via the dispatcher.
+     *
+     * The call arrives at the target as an `app` principal, which satisfies endpoints
+     * declared `auth: 'apiKey'`. No API key is needed or sent.
+     *
+     * @example
+     * const invite = await callAppEndpoint(env, {
+     *   app: 'labcrm',
+     *   method: 'GET',
+     *   path: '/v1/portal/invite/:token',
+     *   pathParams: { token },
+     * });
+     */
+    callAppEndpoint<T = unknown>(options: CallAppEndpointOptions): Promise<CallAppEndpointResult<T>>;
     /**
      * Register an entity with the workspace so other apps can query it
      */
@@ -430,6 +497,22 @@ export declare function listWorkspaceEntity<T = unknown>(env: Env, entityName: s
  * @example
  * const contact = await getWorkspaceEntity<Contact>(env, 'Contact', 'contact-123');
  */
+/**
+ * Call a public endpoint on ANOTHER app in this workspace.
+ *
+ * Use this instead of `fetch()` against a sibling app's public URL: production apps
+ * cannot HTTP-fetch the platform's app domain and such a fetch hangs until timeout.
+ *
+ * @example
+ * const result = await callAppEndpoint(env, {
+ *   app: 'labcrm',
+ *   method: 'POST',
+ *   path: '/v1/portal/orders',
+ *   body: { items },
+ * });
+ * if (!result.ok) throw new Error(`CRM rejected the order: ${result.status}`);
+ */
+export declare function callAppEndpoint<T = unknown>(env: Env, options: CallAppEndpointOptions): Promise<CallAppEndpointResult<T>>;
 export declare function getWorkspaceEntity<T = unknown>(env: Env, entityName: string, id: string): Promise<T | null>;
 /**
  * Create an entity in ANOTHER app in the workspace (cross-app ONLY)

package/bundled-types/workspace.d.ts

@@ -1,2 +1,2 @@
-export { WorkspaceContext, getWorkspaceContext, listWorkspaceEntity, getWorkspaceEntity, createWorkspaceEntity, updateWorkspaceEntity, deleteWorkspaceEntity, initializeWorkspace, } from './core-workspace';
-export type { WorkspaceUser, ListUsersOptions, ListUsersResponse, NotifyUserParams, NotifyUserResult, ListEntityRequest, ListEntityResponse, GetEntityRequest, CreateEntityRequest, UpdateEntityRequest, DeleteEntityRequest, RegisterEntityRequest, RegisterAppRequest, RegisterComponentRequest, RegisterScheduleRequest, RegisterWorkflowRequest, RegisterEndpointRequest, RegisterIntegrationRequest, RegisterAgentRequest as WorkspaceRegisterAgentRequest, } from './core-workspace';
+export { WorkspaceContext, getWorkspaceContext, listWorkspaceEntity, getWorkspaceEntity, createWorkspaceEntity, updateWorkspaceEntity, deleteWorkspaceEntity, callAppEndpoint, initializeWorkspace, } from './core-workspace';
+export type { WorkspaceUser, ListUsersOptions, ListUsersResponse, NotifyUserParams, NotifyUserResult, ListEntityRequest, ListEntityResponse, GetEntityRequest, CreateEntityRequest, UpdateEntityRequest, DeleteEntityRequest, RegisterEntityRequest, RegisterAppRequest, RegisterComponentRequest, RegisterScheduleRequest, RegisterWorkflowRequest, RegisterEndpointRequest, RegisterIntegrationRequest, CallAppEndpointOptions, CallAppEndpointResult, RegisterAgentRequest as WorkspaceRegisterAgentRequest, } from './core-workspace';