@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/fn-context/rpc/platform.d.ts

@@ -12,7 +12,17 @@ export type PlatformInvokeHandler = (input: {
 export declare function createPlatformRouter(invoke: PlatformInvokeHandler): import("@trpc/server").TRPCBuiltRouter<{
     ctx: RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
     invoke: import("@trpc/server").TRPCMutationProcedure<{

package/dist/fn-context/rpc/records.d.ts

@@ -2,9 +2,8 @@ import { z } from 'zod';
 import { type RpcContext } from './trpc-init.js';
 /**
  * `ctx.api.db` of every function and the Orchestrator (15 §10.16): the same
- * reads and writes as a page script and its actions, over RPC, one call per request. A write carries
- * its call key (its place in the run: `write:1`, `write:2`, …): within an Orchestrator Run the same
- * request sent again returns the first answer instead of writing twice.
+ * reads and writes as a page script and its actions, over RPC, one call per request. A write is done
+ * each time it is sent (38 §2.7): the platform keeps no key to answer a repeat with the first answer.
  */
 declare const readInput: z.ZodObject<{
     table: z.ZodString;
@@ -25,7 +24,6 @@ declare const writeInput: z.ZodObject<{
         upsert: "upsert";
     }>;
     args: z.ZodUnknown;
-    callKey: z.ZodString;
 }, z.core.$strip>;
 export type RecordsReadInput = z.infer<typeof readInput>;
 export type RecordsWriteInput = z.infer<typeof writeInput>;
@@ -51,7 +49,17 @@ export type RecordsHandlers = {
 export declare function createRecordsRouter(handlers: RecordsHandlers): import("@trpc/server").TRPCBuiltRouter<{
     ctx: RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
     read: import("@trpc/server").TRPCMutationProcedure<{
@@ -68,7 +76,6 @@ export declare function createRecordsRouter(handlers: RecordsHandlers): import("
             table: string;
             method: "create" | "delete" | "update" | "upsert";
             args: unknown;
-            callKey: string;
         };
         output: RecordsResult;
         meta: object;

package/dist/fn-context/rpc/records.js

@@ -2,9 +2,8 @@ import { z } from 'zod';
 import { publicProcedure, router } from './trpc-init.js';
 /**
  * `ctx.api.db` of every function and the Orchestrator (15 §10.16): the same
- * reads and writes as a page script and its actions, over RPC, one call per request. A write carries
- * its call key (its place in the run: `write:1`, `write:2`, …): within an Orchestrator Run the same
- * request sent again returns the first answer instead of writing twice.
+ * reads and writes as a page script and its actions, over RPC, one call per request. A write is done
+ * each time it is sent (38 §2.7): the platform keeps no key to answer a repeat with the first answer.
  */
 const readInput = z.object({
     table: z.string().min(1),
@@ -15,7 +14,6 @@ const writeInput = z.object({
     table: z.string().min(1),
     method: z.enum(['create', 'update', 'upsert', 'delete']),
     args: z.unknown(),
-    callKey: z.string().min(1).max(200),
 });
 export function createRecordsRouter(handlers) {
     return router({

package/dist/fn-context/rpc/trpc-client.d.ts

@@ -1,4 +1,41 @@
 import type { ApiHost, CaseOrchestratorApiHost } from '../types.js';
+/**
+ * A request that got no answer from the platform itself (74 §3.2): the platform always answers JSON, so any
+ * other answer is a gateway's. `reached: false` only when the request certainly never got to the platform.
+ */
+export declare class RpcTransportError extends Error {
+    readonly reached: boolean | 'unknown';
+    readonly name = "RpcTransportError";
+    constructor(message: string, reached: boolean | 'unknown');
+}
+/**
+ * `fetch` for the platform's RPC: a failure to connect, or an answer that is not the platform's (not JSON),
+ * becomes an {@link RpcTransportError} saying whether the request reached it. The answer is read whole here:
+ * one that breaks as it is read (a body cut off, bad JSON) is an {@link RpcTransportError} too, so whatever
+ * fails before this is called (the code's arguments that cannot be sent as JSON) stays the code's.
+ */
+export declare function platformFetch(input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]): Promise<Response>;
+/** Sent again: the platform was busy (`TOO_MANY_REQUESTS`), or the request never reached it. */
+export declare function shouldRetryRpc(error: {
+    data?: {
+        code?: string;
+    } | null;
+    cause?: unknown;
+}, attempts: number): boolean;
+/**
+ * A failed call as company code sees it: an `Error` with the platform's message and, when the platform
+ * refused it for a reason of the business (`subject_busy`, `run_ended`, a write's code), that reason as
+ * `error.code` (64 §12).
+ */
+export declare function rpcSafe<T>(promise: Promise<T>): Promise<T>;
+/**
+ * A read's arguments as sent, `after` cut down to the place the platform reads off it (18 §4.6): the
+ * row's `id`, `createdAt` and `updatedAt`, and of each field this read's `orderBy` names, the slot's
+ * `value`. `after: rows.at(-1)` is a row with whatever it `include`d; sent whole, a big include tree
+ * could pass the request's size limit for nothing. Anything that is no row goes as given, for the
+ * platform to refuse with its reason.
+ */
+export declare function placeOnly(args: unknown): unknown;
 export declare function createRpcApiHost(options: {
     baseUrl: string;
     getToken: () => string | Promise<string>;
@@ -7,5 +44,10 @@ export declare function createRpcApiHost(options: {
     getRequestId?: () => string | undefined;
     getTags?: () => string[] | undefined;
     waitUntil?: (promise: Promise<unknown>) => void;
+    /**
+     * Asked before each call is sent, with its procedure's path (`platform.invoke`, `log.emit`, …): throws
+     * to refuse it. The Worker refuses a `ctx` kept from another call (64 §6).
+     */
+    checkCall?: (path: string) => void;
 }): ApiHost & CaseOrchestratorApiHost;
 //# sourceMappingURL=trpc-client.d.ts.map

package/dist/fn-context/rpc/trpc-client.js

@@ -4,6 +4,7 @@ import { integrationSurfaceKeys, } from '../../core/context/types.js';
 import { bindEnvService } from '../../core/context/env.js';
 import { CASE_ORCHESTRATOR_TOOL_NAMES, } from '../../core/case-orchestrator/types.js';
 import { getLogger } from '../../logger.js';
+import { PlatformUnavailableError } from '../../core/functions/errors.js';
 import { REQUEST_ID_HEADER, RUNTIME_VERSION_HEADER, formatRuntimeVersion } from './request-id.js';
 const logger = getLogger(['runtime', 'rpc']);
 /**
@@ -12,6 +13,83 @@ const logger = getLogger(['runtime', 'rpc']);
  */
 const BUSY_RETRIES = 5;
 const busyDelayMs = (attempt) => Math.min(500 * 2 ** attempt, 5_000) + Math.floor(Math.random() * 250);
+/**
+ * A call that certainly never reached the platform (a gateway's error page, a refused connection, a name that
+ * did not resolve) is sent again this many times, after the same growing pause (74 §3.2). One that may have
+ * reached it (504, a connection cut after it was sent) is not, read or write alike.
+ */
+const UNREACHED_RETRIES = 3;
+/**
+ * A request that got no answer from the platform itself (74 §3.2): the platform always answers JSON, so any
+ * other answer is a gateway's. `reached: false` only when the request certainly never got to the platform.
+ */
+export class RpcTransportError extends Error {
+    reached;
+    name = 'RpcTransportError';
+    constructor(message, reached) {
+        super(message);
+        this.reached = reached;
+    }
+}
+/** A gateway's own answer that may come after the platform got the request: its timeouts (504; Cloudflare 520, 524). */
+const MAYBE_REACHED_STATUSES = new Set([504, 520, 524]);
+/** Fetch failures where no connection was ever made. */
+const NOT_CONNECTED = /ECONNREFUSED|ENOTFOUND|EAI_AGAIN|getaddrinfo/;
+function connectFailure(error) {
+    for (let current = error, depth = 0; current && depth < 5; depth += 1) {
+        const { code, message, errors } = current;
+        if (NOT_CONNECTED.test(`${String(code ?? '')} ${String(message ?? '')}`))
+            return true;
+        if (Array.isArray(errors) && errors.some(connectFailure))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * `fetch` for the platform's RPC: a failure to connect, or an answer that is not the platform's (not JSON),
+ * becomes an {@link RpcTransportError} saying whether the request reached it. The answer is read whole here:
+ * one that breaks as it is read (a body cut off, bad JSON) is an {@link RpcTransportError} too, so whatever
+ * fails before this is called (the code's arguments that cannot be sent as JSON) stays the code's.
+ */
+export async function platformFetch(input, init) {
+    let response;
+    try {
+        response = await fetch(input, init);
+    }
+    catch (error) {
+        const reached = connectFailure(error) ? false : 'unknown';
+        throw new RpcTransportError(`the platform could not be reached: ${error instanceof Error ? error.message : String(error)}`, reached);
+    }
+    if (!/json/i.test(response.headers.get('content-type') ?? '')) {
+        const body = (await response.text().catch(() => '')).slice(0, 120).replace(/\s+/g, ' ');
+        throw new RpcTransportError(`HTTP ${response.status} from a gateway, not the platform: ${body}`, MAYBE_REACHED_STATUSES.has(response.status) ? 'unknown' : false);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new RpcTransportError(`the platform's answer was cut off: ${error instanceof Error ? error.message : String(error)}`, 'unknown');
+    }
+    try {
+        JSON.parse(text);
+    }
+    catch {
+        throw new RpcTransportError(`the platform's answer is not valid JSON: ${text.slice(0, 120)}`, 'unknown');
+    }
+    return new Response(text, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+function transportErrorOf(error) {
+    const cause = error?.cause;
+    return cause instanceof RpcTransportError ? cause : null;
+}
+/** Sent again: the platform was busy (`TOO_MANY_REQUESTS`), or the request never reached it. */
+export function shouldRetryRpc(error, attempts) {
+    if (error.data?.code === 'TOO_MANY_REQUESTS')
+        return attempts <= BUSY_RETRIES;
+    return transportErrorOf(error)?.reached === false && attempts <= UNREACHED_RETRIES;
+}
 function rpcLogger(c, getTags, waitUntil) {
     const emit = (level, message, extra) => {
         const pending = c.log.emit.mutate({ level, message, extra, tags: getTags?.() }).catch(() => { });
@@ -28,10 +106,25 @@ function rpcLogger(c, getTags, waitUntil) {
         error: (message, extra) => emit('error', message, extra),
     };
 }
-function rpcSafe(promise) {
+/**
+ * A failed call as company code sees it: an `Error` with the platform's message and, when the platform
+ * refused it for a reason of the business (`subject_busy`, `run_ended`, a write's code), that reason as
+ * `error.code` (64 §12).
+ */
+export function rpcSafe(promise) {
     return promise.catch((err) => {
         if (err instanceof Error && err.constructor?.name === 'TRPCClientError') {
-            throw new Error(`RPC call failed: ${err.message}`);
+            // No answer from the platform, one that broke as it was read (`platformFetch` says so), or its own
+            // failure (5xx): the platform's (74 §3.2), marked so. What failed before the request was sent (the
+            // code's arguments that are no JSON, a ctx kept from another call) stays the code's.
+            const status = err.data?.httpStatus;
+            const platform = transportErrorOf(err) !== null || (typeof status === 'number' && status >= 500);
+            const message = `RPC call failed: ${transportErrorOf(err)?.message ?? err.message}`;
+            const failed = (platform ? new PlatformUnavailableError(message) : new Error(message));
+            const reason = err.data?.reason;
+            if (typeof reason === 'string')
+                failed.code = reason;
+            throw failed;
         }
         throw err;
     });
@@ -93,7 +186,7 @@ function buildPlatformApis(c) {
 function buildCaseOrchestratorTools(c) {
     const tools = CASE_ORCHESTRATOR_TOOL_NAMES.map((tool) => [
         tool,
-        (input, callOptions) => rpcSafe(c.caseOrchestratorTools.invoke.mutate({ tool, input, callKey: callOptions.callKey })),
+        (input) => rpcSafe(c.caseOrchestratorTools.invoke.mutate({ tool, input })),
     ]);
     // The tool registry guarantees the shape; TS cannot follow it through Object.fromEntries.
     return Object.fromEntries(tools);
@@ -106,24 +199,49 @@ function unwrapRecords(result) {
     error.code = result.error.code;
     throw error;
 }
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The keys of a row the platform always reads off `after`: its id and times. */
+const PLACE_KEYS = new Set(['id', 'createdAt', 'updatedAt']);
+/**
+ * A read's arguments as sent, `after` cut down to the place the platform reads off it (18 §4.6): the
+ * row's `id`, `createdAt` and `updatedAt`, and of each field this read's `orderBy` names, the slot's
+ * `value`. `after: rows.at(-1)` is a row with whatever it `include`d; sent whole, a big include tree
+ * could pass the request's size limit for nothing. Anything that is no row goes as given, for the
+ * platform to refuse with its reason.
+ */
+export function placeOnly(args) {
+    if (!isPlainObject(args) || !isPlainObject(args.after))
+        return args;
+    const ordered = new Set();
+    for (const entry of Array.isArray(args.orderBy) ? args.orderBy : [args.orderBy]) {
+        if (isPlainObject(entry))
+            for (const field of Object.keys(entry))
+                ordered.add(field);
+    }
+    const place = Object.entries(args.after).flatMap(([key, value]) => {
+        if (PLACE_KEYS.has(key))
+            return [[key, value]];
+        if (!ordered.has(key))
+            return [];
+        // A slot: only its value places the row (a lookup's included `row` does not).
+        return [[key, isPlainObject(value) ? (Object.hasOwn(value, 'value') ? { value: value.value } : {}) : value]];
+    });
+    return { ...args, after: Object.fromEntries(place) };
+}
 /**
  * `ctx.api.db` of every function and the Orchestrator (15 §10.15 task 4, §10.16): every table, as a
- * page script and its actions see them, one request per call. Writes are numbered in the order this
- * run makes them; for an Orchestrator Run the same request sent again (a retried request) carries the
- * same key and is not made twice.
+ * page script and its actions see them, one request per call; a write is done each time (38 §2.7). A
+ * read's `after` goes as its place only ({@link placeOnly}).
  */
 function buildDbApi(c) {
-    let writes = 0;
     const db = new Proxy({}, {
         get(_, table) {
             if (typeof table !== 'string')
                 return undefined;
-            const read = (method) => async (args) => unwrapRecords(await rpcSafe(c.records.read.mutate({ table, method, args: args ?? {} })));
-            const write = (method) => async (args) => {
-                writes += 1;
-                const callKey = `write:${writes}`;
-                return unwrapRecords(await rpcSafe(c.records.write.mutate({ table, method, args: args ?? {}, callKey })));
-            };
+            const read = (method) => async (args) => unwrapRecords(await rpcSafe(c.records.read.mutate({ table, method, args: placeOnly(args ?? {}) })));
+            const write = (method) => async (args) => unwrapRecords(await rpcSafe(c.records.write.mutate({ table, method, args: args ?? {} })));
             return {
                 $table: table,
                 findUnique: read('findUnique'),
@@ -147,12 +265,14 @@ export function createRpcApiHost(options) {
             client = createTRPCClient({
                 links: [
                     retryLink({
-                        retry: ({ error, attempts }) => error.data?.code === 'TOO_MANY_REQUESTS' && attempts <= BUSY_RETRIES,
+                        retry: ({ error, attempts }) => shouldRetryRpc(error, attempts),
                         retryDelayMs: busyDelayMs,
                     }),
                     httpLink({
                         url: baseUrl,
-                        headers: async () => {
+                        fetch: platformFetch,
+                        headers: async ({ op }) => {
+                            options.checkCall?.(op.path);
                             const headers = {
                                 authorization: `Bearer ${await options.getToken()}`,
                                 [RUNTIME_VERSION_HEADER]: formatRuntimeVersion(options.runtimeVersion, options.runtimeSource),
@@ -169,24 +289,33 @@ export function createRpcApiHost(options) {
         }
         return client;
     }
+    /** The integrations the call brought; without them, the backend lists them. */
+    async function surfacesOf(c, given) {
+        if (given.surfaces)
+            return given.surfaces;
+        const started = Date.now();
+        logger.info('integration.listSurfaces start', { url: options.baseUrl });
+        const metas = await rpcSafe(c.integration.listSurfaces.query());
+        logger.info('integration.listSurfaces ok', { durationMs: Date.now() - started, count: metas.length });
+        return metas;
+    }
     return {
-        async buildApi(_run) {
+        async buildApi(_run, given = {}) {
             const c = getClient(options.baseUrl);
-            const started = Date.now();
-            logger.info('integration.listSurfaces start', { url: options.baseUrl });
-            const metas = await rpcSafe(c.integration.listSurfaces.query());
-            logger.info('integration.listSurfaces ok', { durationMs: Date.now() - started, count: metas.length });
+            const metas = await surfacesOf(c, given);
             return {
                 ...buildPlatformApis(c),
                 integration: buildSurfaces(c, metas),
                 log: rpcLogger(c, options.getTags, options.waitUntil),
+                // Every function's (38 §2.7): each call names its instance.
+                tools: buildCaseOrchestratorTools(c),
                 ...buildDbApi(c),
             };
         },
-        async buildCaseOrchestratorApi(_run) {
+        async buildCaseOrchestratorApi(_run, given = {}) {
             const c = getClient(options.baseUrl);
             // A function's api (25 §7), so a function called from the Orchestrator with its ctx works the same.
-            const metas = await rpcSafe(c.integration.listSurfaces.query());
+            const metas = await surfacesOf(c, given);
             return {
                 ...buildPlatformApis(c),
                 integration: buildSurfaces(c, metas),

package/dist/fn-context/rpc/trpc-init.d.ts

@@ -3,11 +3,29 @@ export type RpcContext = {
     run: RunClaims;
     requestId?: string;
     runtimeVersion?: string;
+    /**
+     * The platform's gate around every procedure (64 §5): the rate, and whether an Orchestrator's task still
+     * runs. Set by the platform's context; every procedure built on {@link publicProcedure} passes through it,
+     * so a new one cannot miss it. Absent (a test calling one router directly), the procedure just runs.
+     */
+    around?: <T>(call: {
+        path: string;
+    }, next: () => Promise<T>) => Promise<T>;
 };
 export declare const router: import("@trpc/server").TRPCRouterBuilder<{
     ctx: RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }>;
 /**

package/dist/fn-context/rpc/trpc-init.js

@@ -1,13 +1,19 @@
 import { initTRPC, TRPCError } from '@trpc/server';
-import { isRpcCodedError } from './errors.js';
-const t = initTRPC.context().create();
+import { isRpcCodedError, rpcErrorReason } from './errors.js';
+const t = initTRPC.context().create({
+    // A refusal's business code (`subject_busy`, `run_ended`, …) goes back beside its message (64 §12).
+    errorFormatter({ shape, error }) {
+        const reason = rpcErrorReason(error.cause);
+        return reason ? { ...shape, data: { ...shape.data, reason } } : shape;
+    },
+});
 export const router = t.router;
 /**
  * Applied to every procedure so domain errors reach the caller with the status they declared,
  * without each dispatcher wrapping its own body in try/catch.
  */
-export const publicProcedure = t.procedure.use(async ({ next }) => {
-    const result = await next();
+export const publicProcedure = t.procedure.use(async ({ ctx, path, next }) => {
+    const result = ctx.around ? await ctx.around({ path }, () => next()) : await next();
     if (!result.ok && isRpcCodedError(result.error.cause)) {
         const cause = result.error.cause;
         throw new TRPCError({ code: cause.rpcCode, message: cause.message, cause });

package/dist/fn-context/rpc/trpc-router-factory.d.ts

@@ -12,13 +12,33 @@ export declare function createAppRouter(modules: {
 }): import("@trpc/server").TRPCBuiltRouter<{
     ctx: import("./trpc-init.js").RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
     integration: import("@trpc/server").TRPCBuiltRouter<{
         ctx: import("./trpc-init.js").RpcContext;
         meta: object;
-        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+            message: string;
+            code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+            data: {
+                code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+                httpStatus: number;
+                path?: string;
+                stack?: string;
+                reason: string;
+            };
+        };
         transformer: false;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         listSurfaces: import("@trpc/server").TRPCQueryProcedure<{
@@ -52,7 +72,17 @@ export declare function createAppRouter(modules: {
     platform: import("@trpc/server").TRPCBuiltRouter<{
         ctx: import("./trpc-init.js").RpcContext;
         meta: object;
-        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+            message: string;
+            code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+            data: {
+                code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+                httpStatus: number;
+                path?: string;
+                stack?: string;
+                reason: string;
+            };
+        };
         transformer: false;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         invoke: import("@trpc/server").TRPCMutationProcedure<{
@@ -68,7 +98,17 @@ export declare function createAppRouter(modules: {
     log: import("@trpc/server").TRPCBuiltRouter<{
         ctx: import("./trpc-init.js").RpcContext;
         meta: object;
-        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+            message: string;
+            code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+            data: {
+                code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+                httpStatus: number;
+                path?: string;
+                stack?: string;
+                reason: string;
+            };
+        };
         transformer: false;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         emit: import("@trpc/server").TRPCMutationProcedure<{
@@ -87,14 +127,23 @@ export declare function createAppRouter(modules: {
     caseOrchestratorTools: import("@trpc/server").TRPCBuiltRouter<{
         ctx: import("./trpc-init.js").RpcContext;
         meta: object;
-        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+            message: string;
+            code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+            data: {
+                code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+                httpStatus: number;
+                path?: string;
+                stack?: string;
+                reason: string;
+            };
+        };
         transformer: false;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         invoke: import("@trpc/server").TRPCMutationProcedure<{
             input: {
                 tool: string;
                 input: unknown;
-                callKey: string;
             };
             output: unknown;
             meta: object;
@@ -103,7 +152,17 @@ export declare function createAppRouter(modules: {
     records: import("@trpc/server").TRPCBuiltRouter<{
         ctx: import("./trpc-init.js").RpcContext;
         meta: object;
-        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+            message: string;
+            code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+            data: {
+                code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+                httpStatus: number;
+                path?: string;
+                stack?: string;
+                reason: string;
+            };
+        };
         transformer: false;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         read: import("@trpc/server").TRPCMutationProcedure<{
@@ -120,7 +179,6 @@ export declare function createAppRouter(modules: {
                 table: string;
                 method: "create" | "delete" | "update" | "upsert";
                 args: unknown;
-                callKey: string;
             };
             output: import("./records.js").RecordsResult;
             meta: object;

package/dist/fn-context/run-scope.js

@@ -2,7 +2,7 @@ import { ORCHESTRATOR_ENTRY } from '../core/case-orchestrator/types.js';
 /** The Case Orchestrator scope of a run, or null when it is not a complete Case Orchestrator run. */
 export function asCaseOrchestratorRun(run) {
     const scoped = run;
-    if (run.entry !== ORCHESTRATOR_ENTRY || !scoped.instanceId || !scoped.agentRunId)
+    if (run.entry !== ORCHESTRATOR_ENTRY || !scoped.instanceId || !scoped.orchestratorTaskId)
         return null;
     return run;
 }

package/dist/fn-context/types.d.ts

@@ -1,5 +1,5 @@
 import type { ORCHESTRATOR_ENTRY, CaseOrchestratorApi, CaseOrchestratorContext } from '../core/case-orchestrator/types.js';
-import type { SystemContext } from '../core/context/types.js';
+import type { IntegrationSurfaceMeta, SystemContext } from '../core/context/types.js';
 /** Alias for {@link SystemContext} (08 ActionContext shape). */
 export type ActionContext = SystemContext;
 /**
@@ -7,8 +7,19 @@ export type ActionContext = SystemContext;
  * function runs). Its ids are plain strings on the wire; the function's `ctx.meta` types them.
  */
 export type ActionDataSlice = Pick<ActionContext, 'config'> & {
-    time: Omit<ActionContext['time'], 'format' | 'day'>;
+    /** `ignore` absent (a platform before 68 §6.2): nothing is ignored. */
+    time: Omit<ActionContext['time'], 'format' | 'day' | 'at' | 'parts' | 'ignore'> & Partial<Pick<ActionContext['time'], 'ignore'>>;
     meta: ActionContext['meta'];
+    /**
+     * What `ctx.api.integration` offers this run (its connections and mailboxes, with their credentials),
+     * listed by the platform as it calls the function: the host builds the api from it instead of asking
+     * the backend first. Not part of `ctx` itself.
+     */
+    surfaces?: IntegrationSurfaceMeta[];
+};
+/** What the call brought for the api ({@link ActionDataSlice.surfaces}): a host lists what is left out. */
+export type ApiGiven = {
+    surfaces?: IntegrationSurfaceMeta[];
 };
 /** Identity / scope for a single function invocation (ApiHost may key caches on this). */
 export type RunScope = {
@@ -31,19 +42,22 @@ export type RunScope = {
 };
 /** Who fulfills `ctx.api` (Fake local vs Rpc remote). */
 export type ApiHost = {
-    buildApi(run: RunScope): Promise<ActionContext['api']>;
+    buildApi(run: RunScope, given?: ApiGiven): Promise<ActionContext['api']>;
 };
 /** `ctx` of `orchestrator` before the host adds `params`. */
 export type CaseOrchestratorActionContext = Omit<CaseOrchestratorContext, 'params'>;
 /** Who fulfills the Case Orchestrator's `ctx.api` (Fake local vs Rpc remote). */
 export type CaseOrchestratorApiHost = {
-    buildCaseOrchestratorApi(run: RunScope): Promise<CaseOrchestratorApi>;
+    buildCaseOrchestratorApi(run: RunScope, given?: ApiGiven): Promise<CaseOrchestratorApi>;
 };
-/** Run scope of an Orchestrator call: the instance it is limited to and its active run (`AgentRun`). */
+/**
+ * Run scope of an Orchestrator call: the instance it is limited to and the `OrchestratorTask` it runs
+ * for (40 §2.3: no `AgentRun`), refused once that task stops running.
+ */
 export type CaseOrchestratorRunScope = RunScope & {
     entry: typeof ORCHESTRATOR_ENTRY;
     instanceId: string;
-    agentRunId: string;
+    orchestratorTaskId: string;
 };
 /** A verified run token's scope; narrow with {@link asCaseOrchestratorRun}. */
 export type RunClaims = RunScope | CaseOrchestratorRunScope;