@sequenceholdings/managed-functions 0.3.4 → 0.3.5

package/README.md

@@ -138,6 +138,69 @@ A denied write is still denied; the helper supplies no permission
 fallback. A network error may follow a successful write: use application-level
 idempotency and inspect persisted results before retrying.
 
+## Read process run status as the service account
+
+The process-read client requires SDK **0.3.5**, CLI **0.4.6**, and an environment
+advertising `processes_read` support. These release requirements are not proof
+that a particular environment has been upgraded. Deployment preflight checks
+the environment before uploading.
+
+Declare the exact processes and the account that will read them:
+
+```yaml
+service_account: document-runtime
+capabilities:
+  processes:
+    read: [document-review, document-review-part]
+```
+
+The declaration permits at most 64 distinct process IDs, with at most 8192
+bytes across their names. It grants no process permissions. The attached
+account needs process Viewer access, including visibility of every run for
+paged reads. Process Invoker normally implies Viewer. Processes whose runs
+have narrower visibility are refused instead of returning an incomplete
+activity list that could be mistaken for proof that no run exists.
+
+```ts
+import { createFunctionServiceProcessesClient } from '@sequenceholdings/managed-functions'
+
+// Construct inside the handler, using its platform-delivered request and a
+// deployment-configured origin. Never choose the origin from user input.
+const processes = createFunctionServiceProcessesClient({
+  request,
+  baseUrl: 'https://your-environment.example.com',
+})
+const run = await processes.getRun({ process: 'document-review', runId })
+const page = await processes.listRunsPage({
+  process: 'document-review',
+  statuses: ['pending', 'running'],
+  entity: { type: 'document', ids: documentIds },
+  limit: 100,
+})
+```
+
+`getRun` returns only `id`, `processId`, `status`, `entityType`, `entityId`,
+`startedAt` and `completedAt`. Dates are ISO strings; entity fields and
+`completedAt` may be null. Runtime error text, metadata, state, output and steps
+are not exposed. `listRunsPage` returns `{ runs, nextCursor }`; follow every
+non-null cursor with the same filters. Each page permits at most 500 runs and
+500 entity IDs. `entity.id` and `entity.ids` are mutually exclusive.
+`archived: true` selects archived runs instead of the default unarchived runs.
+
+The client sends only an invocation-bound process credential and never follows
+redirects or retries. Atlas rechecks the function version, organization,
+declarations, current service-account attachment and permissions. Completed
+invocation records revoke access; bounded expiry covers delayed ledger writes.
+Create a new client for each invocation and never log or persist its headers.
+Local handler execution without platform delegation cannot use this client.
+
+`FunctionProcessReadError` exposes `status` and `code`. Only
+`404 / run_not_found` proves the expected run is absent after authorization.
+Denied, expired, unavailable or malformed reads must not be treated as an
+empty activity list. Reads do not atomically reserve work: applications must
+still coordinate concurrent starts through a durable claim or idempotency
+mechanism.
+
 ## Opt-in cache
 
 Opt-in caching inside a Managed Function. When the manifest declares a `cache` block, the platform passes a process-reused `context` as the HTTP handler's third argument. Existing two-argument handlers keep working.

package/dist/capabilities.d.ts

@@ -13,6 +13,13 @@ export declare const MANAGED_FUNCTION_CAPABILITIES: {
         };
     };
     readonly features: {
+        readonly processes_read: {
+            readonly field: "capabilities.processes.read";
+            readonly supported: true;
+            readonly limit: "1 to 64 distinct process ids; getRun and listRunsPage only";
+            readonly min_cli: "0.4.6";
+            readonly min_sdk: "0.3.5";
+        };
         readonly postgres_egress: {
             readonly field: "egress";
             readonly supported: true;
@@ -50,6 +57,13 @@ export interface CapabilityTooling {
 export interface ManagedFunctionCapabilities {
     tooling: CapabilityTooling;
     features: {
+        processes_read?: {
+            field: string;
+            supported: boolean;
+            limit: string;
+            min_cli: string;
+            min_sdk: string;
+        };
         postgres_egress?: {
             field: string;
             supported: boolean;
@@ -93,6 +107,7 @@ export interface PreflightManifest {
     capabilities?: {
         data?: Readonly<Record<string, unknown>>;
         storage?: unknown;
+        processes?: unknown;
     };
 }
 export interface PreflightIssue {

package/dist/capabilities.js

@@ -15,6 +15,13 @@ exports.MANAGED_FUNCTION_CAPABILITIES = {
         sdk: { package: exports.MANAGED_FUNCTION_SDK_PACKAGE, min: '0.3.0' },
     },
     features: {
+        processes_read: {
+            field: 'capabilities.processes.read',
+            supported: true,
+            limit: '1 to 64 distinct process ids; getRun and listRunsPage only',
+            min_cli: '0.4.6',
+            min_sdk: '0.3.5',
+        },
         postgres_egress: {
             field: 'egress',
             supported: true,
@@ -58,7 +65,8 @@ function versionIsOlder(installed, required) {
     return false;
 }
 function sdkVersionLowerBound(spec) {
-    return (0, sdk_range_1.concreteOrStaleSdkSpec)(spec, exports.MANAGED_FUNCTION_CAPABILITIES.features.invoke_timeout.min_sdk);
+    const minimum = Object.values(exports.MANAGED_FUNCTION_CAPABILITIES.features).reduce((current, feature) => versionIsOlder(current, feature.min_sdk) ? feature.min_sdk : current, exports.MANAGED_FUNCTION_CAPABILITIES.tooling.sdk.min);
+    return (0, sdk_range_1.concreteOrStaleSdkSpec)(spec, minimum);
 }
 function sdkVersionFromPackageJson(raw) {
     let parsed;

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+export { FUNCTION_PROCESS_TOKEN_HEADER, FUNCTION_PROCESS_READ_PATH, functionProcessReadScopesSchema, readFunctionProcessScopes, functionProcessReadRequestSchema, functionProcessRunSummarySchema } from './processes-contract';
 export { shouldReportAtlasHttp } from './http-tracing';
 import { z } from 'zod';
 export { MANAGED_FUNCTION_LIMITS, MF_LIMITS_CAPS, MF_LIMITS_DEFAULTS, managedFunctionWorkloadLimitsSchema } from './limits';

package/dist/config.js

@@ -1,7 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cacheManifestSchema = exports.CACHE_MAX_TTL_SECONDS = exports.preflightManagedFunction = exports.parseDeployedPolicy = exports.versionIsOlder = exports.sdkVersionLowerBound = exports.sdkVersionFromPackageJson = exports.isPostgresEgress = exports.formatValidationDetail = exports.MANAGED_FUNCTION_SDK_PACKAGE = exports.MANAGED_FUNCTION_CLI_PACKAGE = exports.MANAGED_FUNCTION_CAPABILITIES = exports.managedFunctionWorkloadLimitsSchema = exports.MF_LIMITS_DEFAULTS = exports.MF_LIMITS_CAPS = exports.MANAGED_FUNCTION_LIMITS = exports.shouldReportAtlasHttp = void 0;
+exports.cacheManifestSchema = exports.CACHE_MAX_TTL_SECONDS = exports.preflightManagedFunction = exports.parseDeployedPolicy = exports.versionIsOlder = exports.sdkVersionLowerBound = exports.sdkVersionFromPackageJson = exports.isPostgresEgress = exports.formatValidationDetail = exports.MANAGED_FUNCTION_SDK_PACKAGE = exports.MANAGED_FUNCTION_CLI_PACKAGE = exports.MANAGED_FUNCTION_CAPABILITIES = exports.managedFunctionWorkloadLimitsSchema = exports.MF_LIMITS_DEFAULTS = exports.MF_LIMITS_CAPS = exports.MANAGED_FUNCTION_LIMITS = exports.shouldReportAtlasHttp = exports.functionProcessRunSummarySchema = exports.functionProcessReadRequestSchema = exports.readFunctionProcessScopes = exports.functionProcessReadScopesSchema = exports.FUNCTION_PROCESS_READ_PATH = exports.FUNCTION_PROCESS_TOKEN_HEADER = void 0;
 exports.readCacheConfiguration = readCacheConfiguration;
+var processes_contract_1 = require("./processes-contract");
+Object.defineProperty(exports, "FUNCTION_PROCESS_TOKEN_HEADER", { enumerable: true, get: function () { return processes_contract_1.FUNCTION_PROCESS_TOKEN_HEADER; } });
+Object.defineProperty(exports, "FUNCTION_PROCESS_READ_PATH", { enumerable: true, get: function () { return processes_contract_1.FUNCTION_PROCESS_READ_PATH; } });
+Object.defineProperty(exports, "functionProcessReadScopesSchema", { enumerable: true, get: function () { return processes_contract_1.functionProcessReadScopesSchema; } });
+Object.defineProperty(exports, "readFunctionProcessScopes", { enumerable: true, get: function () { return processes_contract_1.readFunctionProcessScopes; } });
+Object.defineProperty(exports, "functionProcessReadRequestSchema", { enumerable: true, get: function () { return processes_contract_1.functionProcessReadRequestSchema; } });
+Object.defineProperty(exports, "functionProcessRunSummarySchema", { enumerable: true, get: function () { return processes_contract_1.functionProcessRunSummarySchema; } });
 var http_tracing_1 = require("./http-tracing");
 Object.defineProperty(exports, "shouldReportAtlasHttp", { enumerable: true, get: function () { return http_tracing_1.shouldReportAtlasHttp; } });
 const zod_1 = require("zod");

package/dist/deployed-policy.js

@@ -41,9 +41,23 @@ function normalizeCapabilities(value) {
             postgres_egress: normalizePostgres(features.postgres_egress),
             http_headers: normalizeHeaders(features.http_headers),
             invoke_timeout: normalizeTimeout(features.invoke_timeout),
+            processes_read: normalizeProcesses(features.processes_read),
         },
     };
 }
+function normalizeProcesses(value) {
+    if (!value || typeof value.supported !== 'boolean' || typeof value.limit !== 'string')
+        return undefined;
+    if (typeof value.min_cli !== 'string' || typeof value.min_sdk !== 'string')
+        return undefined;
+    return {
+        field: typeof value.field === 'string' ? value.field : 'capabilities.processes.read',
+        supported: value.supported,
+        limit: value.limit,
+        min_cli: value.min_cli,
+        min_sdk: value.min_sdk,
+    };
+}
 function normalizePostgres(value) {
     if (!value || typeof value.supported !== 'boolean' || typeof value.limit !== 'string')
         return undefined;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { createFunctionServiceProcessesClient, FunctionProcessReadError } from './processes';
+export type { FunctionServiceProcessesClient, FunctionServiceProcessesOptions, FunctionProcessRunQuery, FunctionProcessRunSummary, FunctionProcessRunStatus, FunctionProcessRunsPage, FunctionProcessRunsPageQuery, FunctionProcessReadRequest } from './processes';
 export { installFunctionTracing, runWithFunctionTracing } from './tracing';
 export { createFunctionStorageClient } from './storage';
 import { type CacheManager } from "./cache";

package/dist/index.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readCacheConfiguration = exports.cacheManifestSchema = exports.createCacheManager = exports.CacheError = exports.createFunctionStorageClient = exports.runWithFunctionTracing = exports.installFunctionTracing = void 0;
+exports.readCacheConfiguration = exports.cacheManifestSchema = exports.createCacheManager = exports.CacheError = exports.createFunctionStorageClient = exports.runWithFunctionTracing = exports.installFunctionTracing = exports.FunctionProcessReadError = exports.createFunctionServiceProcessesClient = void 0;
 exports.createManagedFunctionContext = createManagedFunctionContext;
+var processes_1 = require("./processes");
+Object.defineProperty(exports, "createFunctionServiceProcessesClient", { enumerable: true, get: function () { return processes_1.createFunctionServiceProcessesClient; } });
+Object.defineProperty(exports, "FunctionProcessReadError", { enumerable: true, get: function () { return processes_1.FunctionProcessReadError; } });
 var tracing_1 = require("./tracing");
 Object.defineProperty(exports, "installFunctionTracing", { enumerable: true, get: function () { return tracing_1.installFunctionTracing; } });
 Object.defineProperty(exports, "runWithFunctionTracing", { enumerable: true, get: function () { return tracing_1.runWithFunctionTracing; } });

package/dist/preflight-issue.d.ts

@@ -0,0 +1,11 @@
+import type { CapabilityTooling, PreflightIssue } from './capabilities';
+export declare function createPreflightIssue({ field, problem, limit, tooling, requiredCli, requiredSdk, cliVersion, sdkVersion, }: {
+    field: string;
+    problem: string;
+    limit: string;
+    tooling: CapabilityTooling;
+    requiredCli: string;
+    requiredSdk: string;
+    cliVersion: string;
+    sdkVersion: string | null;
+}): PreflightIssue;

package/dist/preflight-issue.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPreflightIssue = createPreflightIssue;
+function createPreflightIssue({ field, problem, limit, tooling, requiredCli, requiredSdk, cliVersion, sdkVersion, }) {
+    const installedSdk = sdkVersion ?? 'not declared';
+    return {
+        field,
+        limit,
+        requiredCli,
+        requiredSdk,
+        message: `${field}: ${problem} Supported limit: ${limit}. ` +
+            `Requires ${tooling.cli.package} >= ${requiredCli} (installed ${cliVersion}) ` +
+            `and ${tooling.sdk.package} >= ${requiredSdk} (installed ${installedSdk}).`,
+    };
+}

package/dist/preflight-processes.d.ts

@@ -0,0 +1,10 @@
+import { type CapabilityTooling, type ManagedFunctionCapabilities, type PreflightIssue, type PreflightManifest } from './capabilities';
+export declare function checkProcesses({ manifest, capabilities, tooling, cliVersion, sdkVersion, checkDeployment, issues, }: {
+    manifest: PreflightManifest;
+    capabilities: ManagedFunctionCapabilities | null;
+    tooling: CapabilityTooling;
+    cliVersion: string;
+    sdkVersion: string | null;
+    checkDeployment: boolean;
+    issues: PreflightIssue[];
+}): void;

package/dist/preflight-processes.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkProcesses = checkProcesses;
+const capabilities_1 = require("./capabilities");
+const preflight_issue_1 = require("./preflight-issue");
+const processes_contract_1 = require("./processes-contract");
+const sdk_range_1 = require("./sdk-range");
+function checkProcesses({ manifest, capabilities, tooling, cliVersion, sdkVersion, checkDeployment, issues, }) {
+    const processes = manifest.capabilities?.processes;
+    if (processes === undefined)
+        return;
+    const deployedFeature = capabilities?.features.processes_read;
+    const feature = deployedFeature ?? capabilities_1.MANAGED_FUNCTION_CAPABILITIES.features.processes_read;
+    const details = {
+        limit: feature.limit,
+        tooling,
+        requiredCli: feature.min_cli,
+        requiredSdk: feature.min_sdk,
+        cliVersion,
+        sdkVersion,
+    };
+    const parsed = processes_contract_1.functionProcessReadScopesSchema.safeParse(processes);
+    if (!parsed.success) {
+        issues.push((0, preflight_issue_1.createPreflightIssue)({
+            ...details,
+            field: 'capabilities.processes',
+            problem: (0, capabilities_1.formatValidationDetail)(parsed.error.issues),
+        }));
+        return;
+    }
+    if (checkDeployment && deployedFeature?.supported !== true) {
+        issues.push((0, preflight_issue_1.createPreflightIssue)({
+            ...details,
+            field: feature.field,
+            problem: 'process reads are not supported by this deployment',
+        }));
+        return;
+    }
+    if ((0, capabilities_1.versionIsOlder)(cliVersion, feature.min_cli) || (sdkVersion && (0, sdk_range_1.sdkConstraintIsOlder)(sdkVersion, feature.min_sdk))) {
+        issues.push((0, preflight_issue_1.createPreflightIssue)({
+            ...details,
+            field: feature.field,
+            problem: 'the installed tooling does not support managed function process reads',
+        }));
+    }
+}

package/dist/preflight.d.ts

@@ -1,9 +1,10 @@
 import type { ManagedFunctionLimitCatalog } from './limits';
 import { type ManagedFunctionCapabilities, type PreflightIssue, type PreflightManifest } from './capabilities';
-export declare function preflightManagedFunction({ manifest, limits, capabilities, cliVersion, sdkVersion, }: {
+export declare function preflightManagedFunction({ manifest, limits, capabilities, cliVersion, sdkVersion, checkDeployment, }: {
     manifest: PreflightManifest;
     limits: ManagedFunctionLimitCatalog | null;
     capabilities: ManagedFunctionCapabilities | null;
     cliVersion: string;
     sdkVersion: string | null;
+    checkDeployment?: boolean;
 }): PreflightIssue[];

package/dist/preflight.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preflightManagedFunction = preflightManagedFunction;
 const capabilities_1 = require("./capabilities");
 const sdk_range_1 = require("./sdk-range");
+const preflight_issue_1 = require("./preflight-issue");
+const preflight_processes_1 = require("./preflight-processes");
+const processes_contract_1 = require("./processes-contract");
 const WORKLOAD_FIELDS = [
     'memory_mb',
     'timeout_seconds',
@@ -12,27 +15,16 @@ const WORKLOAD_FIELDS = [
     'max_response_bytes',
     'concurrency',
 ];
-function preflightManagedFunction({ manifest, limits, capabilities, cliVersion, sdkVersion, }) {
+function preflightManagedFunction({ manifest, limits, capabilities, cliVersion, sdkVersion, checkDeployment = true, }) {
     const tooling = capabilities?.tooling ?? capabilities_1.MANAGED_FUNCTION_CAPABILITIES.tooling;
     const issues = [];
     checkWorkload({ manifest, limits, tooling, cliVersion, sdkVersion, issues });
     checkPostgres({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues });
+    (0, preflight_processes_1.checkProcesses)({ manifest, capabilities, tooling, cliVersion, sdkVersion, checkDeployment, issues });
     checkHeaders({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues });
     checkSdkTimeout({ manifest, limits, capabilities, tooling, cliVersion, sdkVersion, issues });
     return issues;
 }
-function issue({ field, problem, limit, tooling, requiredCli, requiredSdk, cliVersion, sdkVersion, }) {
-    const installedSdk = sdkVersion ?? 'not declared';
-    return {
-        field,
-        limit,
-        requiredCli,
-        requiredSdk,
-        message: `${field}: ${problem} Supported limit: ${limit}. ` +
-            `Requires ${tooling.cli.package} >= ${requiredCli} (installed ${cliVersion}) ` +
-            `and ${tooling.sdk.package} >= ${requiredSdk} (installed ${installedSdk}).`,
-    };
-}
 function numericCap(entry) {
     if (!entry || typeof entry !== 'object')
         return null;
@@ -60,7 +52,7 @@ function checkWorkload({ manifest, limits, tooling, cliVersion, sdkVersion, issu
         if (Number.isInteger(value) && value >= cap.min && value <= cap.max)
             continue;
         const unit = cap.unit ? ` ${cap.unit}` : '';
-        issues.push(issue({
+        issues.push((0, preflight_issue_1.createPreflightIssue)({
             field: `limits.${name}`,
             problem: `${value} is outside the range this deployment enforces`,
             limit: `${cap.min} to ${cap.max}${unit}`,
@@ -77,7 +69,7 @@ function checkWorkload({ manifest, limits, tooling, cliVersion, sdkVersion, issu
         return;
     if (typeof cpu === 'number' && Number.isInteger(cpu) && cpu >= cpuCap.min && cpu <= cpuCap.max)
         return;
-    issues.push(issue({
+    issues.push((0, preflight_issue_1.createPreflightIssue)({
         field: 'limits.cpu',
         problem: `${String(cpu)} is outside the range this deployment enforces`,
         limit: `${cpuCap.min} to ${cpuCap.max}, or auto`,
@@ -98,7 +90,7 @@ function checkPostgres({ manifest, capabilities, tooling, cliVersion, sdkVersion
             return;
         const field = `egress[${index}]`;
         if (!feature.supported) {
-            issues.push(issue({
+            issues.push((0, preflight_issue_1.createPreflightIssue)({
                 field,
                 problem: 'PostgreSQL egress is not supported by this deployment',
                 limit: 'hostnames, http(s) URLs, and public IPv4 CIDRs',
@@ -111,7 +103,7 @@ function checkPostgres({ manifest, capabilities, tooling, cliVersion, sdkVersion
             return;
         }
         if ((0, capabilities_1.versionIsOlder)(cliVersion, feature.min_cli)) {
-            issues.push(issue({
+            issues.push((0, preflight_issue_1.createPreflightIssue)({
                 field,
                 problem: 'this CLI rejects PostgreSQL egress that this deployment supports',
                 limit: feature.limit,
@@ -129,7 +121,8 @@ function needsWideHeaders(manifest) {
     const storage = manifest.capabilities?.storage;
     const hasData = !!data && Object.keys(data).length > 0;
     const hasStorage = !!storage && typeof storage === 'object' && Object.keys(storage).length > 0;
-    return hasData || hasStorage;
+    const hasProcesses = processes_contract_1.functionProcessReadScopesSchema.safeParse(manifest.capabilities?.processes).success;
+    return hasData || hasStorage || hasProcesses;
 }
 function checkHeaders({ manifest, capabilities, tooling, cliVersion, sdkVersion, issues, }) {
     const feature = capabilities?.features.http_headers;
@@ -138,9 +131,9 @@ function checkHeaders({ manifest, capabilities, tooling, cliVersion, sdkVersion,
     const supported = capabilities_1.MANAGED_FUNCTION_CAPABILITIES.features.http_headers.max_bytes;
     if (feature.max_bytes >= supported)
         return;
-    issues.push(issue({
+    issues.push((0, preflight_issue_1.createPreflightIssue)({
         field: feature.field,
-        problem: `invocation headers for capabilities.data or capabilities.storage exceed ${feature.max_bytes} bytes and will fail with HTTP 431`,
+        problem: `invocation headers for capabilities.data, capabilities.storage, or capabilities.processes exceed ${feature.max_bytes} bytes and will fail with HTTP 431`,
         limit: feature.limit,
         tooling,
         requiredCli: feature.min_cli,
@@ -159,7 +152,7 @@ function checkSdkTimeout({ manifest, limits, capabilities, tooling, cliVersion,
     if (timeout <= feature.legacy_sdk_max_seconds)
         return;
     const platformMax = numericCap(limits?.workload?.timeout_seconds)?.max ?? feature.max_seconds;
-    issues.push(issue({
+    issues.push((0, preflight_issue_1.createPreflightIssue)({
         field: feature.field,
         problem: `${timeout} seconds exceeds the installed SDK's ${feature.legacy_sdk_max_seconds} second client cap, behind the platform limit of ${platformMax} seconds`,
         limit: feature.limit,

package/dist/processes-contract.d.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+export declare const FUNCTION_PROCESS_TOKEN_HEADER = "x-sequence-process-service-token";
+export declare const FUNCTION_PROCESS_READ_PATH = "/api/managed-functions/processes/read";
+export declare const functionProcessReadScopesSchema: z.ZodObject<{
+    read: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare function readFunctionProcessScopes(manifest: unknown): string[];
+export declare const functionProcessRunStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+    timed_out: "timed_out";
+}>;
+export type FunctionProcessRunStatus = z.infer<typeof functionProcessRunStatusSchema>;
+export declare const functionProcessRunSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    processId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+        timed_out: "timed_out";
+    }>;
+    entityType: z.ZodNullable<z.ZodString>;
+    entityId: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodISODateTime;
+    completedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type FunctionProcessRunSummary = z.infer<typeof functionProcessRunSummarySchema>;
+export declare const functionProcessRunQuerySchema: z.ZodObject<{
+    process: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strict>;
+export declare const functionProcessRunsPageQuerySchema: z.ZodObject<{
+    process: z.ZodString;
+    statuses: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+        timed_out: "timed_out";
+    }>>>;
+    entity: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+        ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type FunctionProcessRunQuery = z.infer<typeof functionProcessRunQuerySchema>;
+export type FunctionProcessRunsPageQuery = z.infer<typeof functionProcessRunsPageQuerySchema>;
+export declare const functionProcessRunsPageSchema: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        processId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            running: "running";
+            completed: "completed";
+            failed: "failed";
+            cancelled: "cancelled";
+            timed_out: "timed_out";
+        }>;
+        entityType: z.ZodNullable<z.ZodString>;
+        entityId: z.ZodNullable<z.ZodString>;
+        startedAt: z.ZodISODateTime;
+        completedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type FunctionProcessRunsPage = z.infer<typeof functionProcessRunsPageSchema>;
+export declare const functionProcessReadRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    process: z.ZodString;
+    runId: z.ZodString;
+    operation: z.ZodLiteral<"getRun">;
+}, z.core.$strict>, z.ZodObject<{
+    process: z.ZodString;
+    statuses: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+        timed_out: "timed_out";
+    }>>>;
+    entity: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+        ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+    operation: z.ZodLiteral<"listRunsPage">;
+}, z.core.$strict>], "operation">;
+export type FunctionProcessReadRequest = z.infer<typeof functionProcessReadRequestSchema>;
+export declare class FunctionProcessReadError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly name = "FunctionProcessReadError";
+    constructor(status: number, code: string, message: string);
+}

package/dist/processes-contract.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionProcessReadError = exports.functionProcessReadRequestSchema = exports.functionProcessRunsPageSchema = exports.functionProcessRunsPageQuerySchema = exports.functionProcessRunQuerySchema = exports.functionProcessRunSummarySchema = exports.functionProcessRunStatusSchema = exports.functionProcessReadScopesSchema = exports.FUNCTION_PROCESS_READ_PATH = exports.FUNCTION_PROCESS_TOKEN_HEADER = void 0;
+exports.readFunctionProcessScopes = readFunctionProcessScopes;
+const zod_1 = require("zod");
+exports.FUNCTION_PROCESS_TOKEN_HEADER = 'x-sequence-process-service-token';
+exports.FUNCTION_PROCESS_READ_PATH = '/api/managed-functions/processes/read';
+const processId = zod_1.z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(/^[A-Za-z0-9._-]+$/);
+const entityId = zod_1.z.string().min(1).max(255);
+exports.functionProcessReadScopesSchema = zod_1.z.strictObject({
+    read: zod_1.z
+        .array(processId)
+        .min(1)
+        .max(64)
+        .refine((ids) => new Set(ids).size === ids.length, 'Process ids must be distinct')
+        .refine((ids) => ids.reduce((bytes, id) => bytes + id.length, 0) <= 8192, 'Process ids must fit within 8192 bytes'),
+});
+function readFunctionProcessScopes(manifest) {
+    if (typeof manifest !== 'object' || manifest === null)
+        return [];
+    const capabilities = Reflect.get(manifest, 'capabilities');
+    if (typeof capabilities !== 'object' || capabilities === null)
+        return [];
+    const processes = Reflect.get(capabilities, 'processes');
+    if (processes === undefined)
+        return [];
+    return exports.functionProcessReadScopesSchema.parse(processes).read;
+}
+exports.functionProcessRunStatusSchema = zod_1.z.enum([
+    'pending',
+    'running',
+    'completed',
+    'failed',
+    'cancelled',
+    'timed_out',
+]);
+exports.functionProcessRunSummarySchema = zod_1.z.object({
+    id: zod_1.z.string().min(1).max(255),
+    processId,
+    status: exports.functionProcessRunStatusSchema,
+    entityType: zod_1.z.string().max(255).nullable(),
+    entityId: zod_1.z.string().max(255).nullable(),
+    startedAt: zod_1.z.iso.datetime({ offset: true }),
+    completedAt: zod_1.z.iso.datetime({ offset: true }).nullable(),
+});
+exports.functionProcessRunQuerySchema = zod_1.z.strictObject({
+    process: processId,
+    runId: zod_1.z.string().min(1).max(255),
+});
+exports.functionProcessRunsPageQuerySchema = zod_1.z.strictObject({
+    process: processId,
+    statuses: zod_1.z.array(exports.functionProcessRunStatusSchema).min(1).max(6).optional(),
+    entity: zod_1.z
+        .strictObject({
+        type: entityId,
+        id: entityId.optional(),
+        ids: zod_1.z.array(entityId).min(1).max(500).optional(),
+    })
+        .refine((value) => value.id === undefined || value.ids === undefined, 'Name one entity id or a set, not both')
+        .optional(),
+    limit: zod_1.z.number().int().min(1).max(500).optional(),
+    cursor: zod_1.z.string().min(1).max(8192).optional(),
+    archived: zod_1.z.boolean().optional(),
+});
+exports.functionProcessRunsPageSchema = zod_1.z.object({
+    runs: zod_1.z.array(exports.functionProcessRunSummarySchema).max(500),
+    nextCursor: zod_1.z.string().nullable(),
+});
+exports.functionProcessReadRequestSchema = zod_1.z.discriminatedUnion('operation', [
+    exports.functionProcessRunQuerySchema.extend({ operation: zod_1.z.literal('getRun') }),
+    exports.functionProcessRunsPageQuerySchema.extend({
+        operation: zod_1.z.literal('listRunsPage'),
+    }),
+]);
+class FunctionProcessReadError extends Error {
+    status;
+    code;
+    name = 'FunctionProcessReadError';
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.FunctionProcessReadError = FunctionProcessReadError;

package/dist/processes.d.ts

@@ -0,0 +1,14 @@
+import { type FunctionProcessRunQuery, type FunctionProcessRunSummary, type FunctionProcessRunsPage, type FunctionProcessRunsPageQuery } from './processes-contract';
+export * from './processes-contract';
+export interface FunctionServiceProcessesOptions {
+    request: {
+        headers: Pick<Headers, 'get'> | Readonly<Record<string, string | readonly string[] | undefined>>;
+    };
+    baseUrl: string;
+    fetchImpl?: typeof globalThis.fetch;
+}
+export interface FunctionServiceProcessesClient {
+    getRun(query: FunctionProcessRunQuery): Promise<FunctionProcessRunSummary>;
+    listRunsPage(query: FunctionProcessRunsPageQuery): Promise<FunctionProcessRunsPage>;
+}
+export declare function createFunctionServiceProcessesClient({ request, baseUrl, fetchImpl, }: FunctionServiceProcessesOptions): FunctionServiceProcessesClient;