@osolmaz/pi-workflows 0.16.1 → 0.16.3

package/src/{controllers → resource-managers}/store.ts

@@ -1,10 +1,10 @@
 import type {
   ChildWorkflowRecord,
-  ControllerEvent,
-  ControllerQueueClaim,
-  ControllerResource,
-  ControllerResourceRef,
-  ControllerResourceStatus,
+  ResourceManagerEvent,
+  ResourceManagerQueueClaim,
+  ManagedResource,
+  ManagedResourceRef,
+  ManagedResourceStatus,
   EffectRecord,
   JsonObject,
 } from "./types.js";
@@ -15,7 +15,7 @@ export type QueueRequeueOptions = {
 };
 
 export type QueueItem = {
-  controller: string;
+  resourceManager: string;
   key: string;
   availableAt: string;
   consecutiveErrors: number;
@@ -39,61 +39,65 @@ export type WorkflowRecordUpdate = {
   error?: string | null;
 };
 
-export interface ControllerStore {
+export interface ResourceManagerStore {
   close(): void;
 
   putResource<TSpec, TStatus>(options: {
-    controller: string;
+    resourceManager: string;
     key: string;
     spec: TSpec;
     initialStatus: TStatus;
     now?: string;
-  }): ControllerResource<TSpec, TStatus>;
+  }): ManagedResource<TSpec, TStatus>;
   getResource<TSpec = unknown, TStatus = unknown>(
-    ref: ControllerResourceRef,
-  ): ControllerResource<TSpec, TStatus> | undefined;
-  getResourceByUid(uid: string): ControllerResource | undefined;
+    ref: ManagedResourceRef,
+  ): ManagedResource<TSpec, TStatus> | undefined;
+  getResourceByUid(uid: string): ManagedResource | undefined;
   listResources<TSpec = unknown, TStatus = unknown>(options?: {
-    controller?: string;
-  }): ControllerResource<TSpec, TStatus>[];
+    resourceManager?: string;
+  }): ManagedResource<TSpec, TStatus>[];
   updateStatus<TStatus>(options: {
-    ref: ControllerResourceRef;
+    ref: ManagedResourceRef;
     expectedResourceVersion: number;
-    claim: ControllerQueueClaim;
-    status: ControllerResourceStatus<TStatus>;
+    claim: ResourceManagerQueueClaim;
+    status: ManagedResourceStatus<TStatus>;
     finalizers?: string[];
     now?: string;
-  }): ControllerResource<unknown, TStatus>;
-  requestDeletion(ref: ControllerResourceRef, now?: string): ControllerResource;
+  }): ManagedResource<unknown, TStatus>;
+  requestDeletion(ref: ManagedResourceRef, now?: string): ManagedResource;
   updateFinalizers(options: {
-    ref: ControllerResourceRef;
+    ref: ManagedResourceRef;
     expectedResourceVersion: number;
     finalizers: string[];
     now?: string;
-  }): ControllerResource;
+  }): ManagedResource;
   deleteResource(
-    ref: ControllerResourceRef,
+    ref: ManagedResourceRef,
     expectedResourceVersion: number,
-    claim: ControllerQueueClaim,
+    claim: ResourceManagerQueueClaim,
   ): boolean;
 
-  enqueue(ref: ControllerResourceRef, availableAt?: string): void;
+  enqueue(ref: ManagedResourceRef, availableAt?: string): void;
   claimNext(options: {
-    controllers: string[];
+    resourceManagers: string[];
     ownerId: string;
     leaseMs: number;
     now?: string;
-    exclude?: ControllerResourceRef[];
-  }): ControllerQueueClaim | undefined;
-  renewClaim(claim: ControllerQueueClaim, leaseMs: number, now?: string): boolean;
-  settleClaim(claim: ControllerQueueClaim, now?: string): boolean;
-  requeueClaim(claim: ControllerQueueClaim, options: QueueRequeueOptions, now?: string): boolean;
+    exclude?: ManagedResourceRef[];
+  }): ResourceManagerQueueClaim | undefined;
+  renewClaim(claim: ResourceManagerQueueClaim, leaseMs: number, now?: string): boolean;
+  settleClaim(claim: ResourceManagerQueueClaim, now?: string): boolean;
+  requeueClaim(
+    claim: ResourceManagerQueueClaim,
+    options: QueueRequeueOptions,
+    now?: string,
+  ): boolean;
   listQueue(): QueueItem[];
 
   reserveEffect(options: {
     key: string;
     resourceUid: string;
-    claim: ControllerQueueClaim;
+    claim: ResourceManagerQueueClaim;
     generation: number;
     kind: string;
     requestFingerprint: string;
@@ -103,7 +107,7 @@ export interface ControllerStore {
   updateEffect(options: {
     resourceUid: string;
     key: string;
-    claim: ControllerQueueClaim;
+    claim: ResourceManagerQueueClaim;
     state: EffectRecord["state"];
     externalRef?: string;
     error?: string;
@@ -113,7 +117,7 @@ export interface ControllerStore {
 
   reserveWorkflow(options: {
     resourceUid: string;
-    claim: ControllerQueueClaim;
+    claim: ResourceManagerQueueClaim;
     requestKey: string;
     workflow: string;
     inputFingerprint: string;
@@ -123,18 +127,22 @@ export interface ControllerStore {
   updateWorkflow(
     requestId: string,
     update: WorkflowRecordUpdate,
-    claim: ControllerQueueClaim,
+    claim: ResourceManagerQueueClaim,
   ): ChildWorkflowRecord;
   completeWorkflow(requestId: string, update: WorkflowRecordUpdate): ChildWorkflowRecord;
   listWorkflows(resourceUid: string): ChildWorkflowRecord[];
 
   recordEvent(options: {
-    controller: string;
+    resourceManager: string;
     key: string;
-    claim?: ControllerQueueClaim;
+    claim?: ResourceManagerQueueClaim;
     type: string;
     payload?: JsonObject;
     now?: string;
-  }): ControllerEvent;
-  listEvents(options?: { controller?: string; key?: string; limit?: number }): ControllerEvent[];
+  }): ResourceManagerEvent;
+  listEvents(options?: {
+    resourceManager?: string;
+    key?: string;
+    limit?: number;
+  }): ResourceManagerEvent[];
 }

package/src/{controllers → resource-managers}/types.ts

@@ -5,11 +5,11 @@ export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
 export type JsonObject = { [key: string]: JsonValue };
 
-export type ControllerConditionStatus = true | false | "unknown";
+export type ManagedResourceConditionStatus = true | false | "unknown";
 
-export type ControllerCondition = {
+export type ManagedResourceCondition = {
   type: string;
-  status: ControllerConditionStatus;
+  status: ManagedResourceConditionStatus;
   reason: string;
   message?: string;
   observedGeneration: number;
@@ -31,17 +31,17 @@ export type ChildWorkflowReference = {
   attempt: number;
 };
 
-export type ControllerResourceStatus<TStatus> = {
+export type ManagedResourceStatus<TStatus> = {
   observedGeneration: number;
-  conditions: ControllerCondition[];
-  controllerStatus: TStatus;
+  conditions: ManagedResourceCondition[];
+  resourceManagerStatus: TStatus;
   workflowRun?: ChildWorkflowReference;
 };
 
-export type ControllerResource<TSpec = unknown, TStatus = unknown> = {
+export type ManagedResource<TSpec = unknown, TStatus = unknown> = {
   metadata: {
     uid: string;
-    controller: string;
+    resourceManager: string;
     key: string;
     resourceVersion: number;
     generation: number;
@@ -49,24 +49,24 @@ export type ControllerResource<TSpec = unknown, TStatus = unknown> = {
     finalizers: string[];
   };
   spec: TSpec;
-  status: ControllerResourceStatus<TStatus>;
+  status: ManagedResourceStatus<TStatus>;
 };
 
-export type ControllerResourceRef = {
-  controller: string;
+export type ManagedResourceRef = {
+  resourceManager: string;
   key: string;
 };
 
-export type ControllerConditionInput = {
+export type ManagedResourceConditionInput = {
   type: string;
-  status: ControllerConditionStatus;
+  status: ManagedResourceConditionStatus;
   reason: string;
   message?: string;
 };
 
-export type ControllerStatusPatch<TStatus> = {
-  controllerStatus?: TStatus;
-  conditions?: ControllerConditionInput[];
+export type ResourceManagerStatusPatch<TStatus> = {
+  resourceManagerStatus?: TStatus;
+  conditions?: ManagedResourceConditionInput[];
   workflowRun?: ChildWorkflowReference | null;
   finalizers?: string[];
 };
@@ -74,12 +74,12 @@ export type ControllerStatusPatch<TStatus> = {
 export type ReconcileResult<TStatus> =
   | {
       kind: "settled";
-      status?: ControllerStatusPatch<TStatus>;
+      status?: ResourceManagerStatusPatch<TStatus>;
     }
   | {
       kind: "requeue";
       afterMs?: number;
-      status?: ControllerStatusPatch<TStatus>;
+      status?: ResourceManagerStatusPatch<TStatus>;
     };
 
 export type EffectState = "pending" | "applied" | "rejected" | "indeterminate";
@@ -115,7 +115,7 @@ export type EffectDefinition<TRequest> = {
   apply: (signal: AbortSignal) => MaybePromise<EffectApplication>;
 };
 
-export interface ControllerEffects {
+export interface ResourceManagerEffects {
   ensure<TRequest>(definition: EffectDefinition<TRequest>): Promise<EffectRecord>;
 }
 
@@ -133,7 +133,7 @@ export type ChildWorkflowRecord = ChildWorkflowReference & {
   error?: string;
 };
 
-export type ControllerSettingsChangeRequest = {
+export type ResourceManagerSettingsChangeRequest = {
   requestKey: string;
   runId: string;
   scopeId?: string;
@@ -141,20 +141,20 @@ export type ControllerSettingsChangeRequest = {
   patch: JsonPatch;
 };
 
-export type ControllerSettingsChangeResult = {
+export type ResourceManagerSettingsChangeResult = {
   runId: string;
   scopeId: string;
   changeNumber: number;
   adopted: boolean;
 };
 
-export type ControllerQueueFollowUpRequest = {
+export type ResourceManagerQueueFollowUpRequest = {
   requestKey: string;
   runId: string;
   prompt: string;
 };
 
-export type ControllerFollowUpResult = {
+export type ResourceManagerFollowUpResult = {
   runId: string;
   followUpId: string;
   order: number;
@@ -162,50 +162,59 @@ export type ControllerFollowUpResult = {
   adopted: boolean;
 };
 
-export type ControllerRemoveFollowUpRequest = {
+export type ResourceManagerRemoveFollowUpRequest = {
   requestKey: string;
   runId: string;
   followUpId: string;
 };
 
-export interface ControllerWorkflows {
+export interface ResourceManagerWorkflows {
   ensure(request: ChildWorkflowRequest): Promise<ChildWorkflowRecord>;
-  changeSettings(request: ControllerSettingsChangeRequest): Promise<ControllerSettingsChangeResult>;
-  queueFollowUp(request: ControllerQueueFollowUpRequest): Promise<ControllerFollowUpResult>;
-  removeFollowUp(request: ControllerRemoveFollowUpRequest): Promise<ControllerFollowUpResult>;
+  changeSettings(
+    request: ResourceManagerSettingsChangeRequest,
+  ): Promise<ResourceManagerSettingsChangeResult>;
+  queueFollowUp(
+    request: ResourceManagerQueueFollowUpRequest,
+  ): Promise<ResourceManagerFollowUpResult>;
+  removeFollowUp(
+    request: ResourceManagerRemoveFollowUpRequest,
+  ): Promise<ResourceManagerFollowUpResult>;
 }
 
 export type ReconcileContext<TStatus> = {
   signal: AbortSignal;
-  effects: ControllerEffects;
-  workflows: ControllerWorkflows;
-  settled(status?: ControllerStatusPatch<TStatus>): ReconcileResult<TStatus>;
-  requeue(status?: ControllerStatusPatch<TStatus>): ReconcileResult<TStatus>;
-  requeueAfter(afterMs: number, status?: ControllerStatusPatch<TStatus>): ReconcileResult<TStatus>;
+  effects: ResourceManagerEffects;
+  workflows: ResourceManagerWorkflows;
+  settled(status?: ResourceManagerStatusPatch<TStatus>): ReconcileResult<TStatus>;
+  requeue(status?: ResourceManagerStatusPatch<TStatus>): ReconcileResult<TStatus>;
+  requeueAfter(
+    afterMs: number,
+    status?: ResourceManagerStatusPatch<TStatus>,
+  ): ReconcileResult<TStatus>;
 };
 
-export type ControllerDefinition<TSpec = unknown, TStatus = unknown> = {
+export type ResourceManagerDefinition<TSpec = unknown, TStatus = unknown> = {
   name: string;
   initialStatus: (spec: TSpec) => TStatus;
   reconcile: (
     context: ReconcileContext<TStatus>,
-    resource: ControllerResource<TSpec, TStatus>,
+    resource: ManagedResource<TSpec, TStatus>,
   ) => MaybePromise<ReconcileResult<TStatus>>;
   timeoutMs?: number;
 };
 
-export type AnyControllerDefinition = {
+export type AnyResourceManagerDefinition = {
   name: string;
   initialStatus(spec: unknown): unknown;
   reconcile(
     context: ReconcileContext<unknown>,
-    resource: ControllerResource,
+    resource: ManagedResource,
   ): MaybePromise<ReconcileResult<unknown>>;
   timeoutMs?: number;
 };
 
-export type ControllerQueueClaim = {
-  controller: string;
+export type ResourceManagerQueueClaim = {
+  resourceManager: string;
   key: string;
   ownerId: string;
   token: string;
@@ -216,10 +225,10 @@ export type ControllerQueueClaim = {
   expiresAt: string;
 };
 
-export type ControllerEvent = {
+export type ResourceManagerEvent = {
   seq: number;
   recordedAt: string;
-  controller: string;
+  resourceManager: string;
   key: string;
   type: string;
   payload: JsonObject;

package/src/{controllers → resource-managers}/workflows.ts

@@ -1,18 +1,18 @@
 import { createRunId } from "../workflows/store.js";
 import { jsonFingerprint } from "./json.js";
-import type { ControllerStore } from "./store.js";
+import type { ResourceManagerStore } from "./store.js";
 import type {
   ChildWorkflowRecord,
   ChildWorkflowRequest,
   ChildWorkflowState,
-  ControllerFollowUpResult,
-  ControllerQueueClaim,
-  ControllerQueueFollowUpRequest,
-  ControllerRemoveFollowUpRequest,
-  ControllerResource,
-  ControllerSettingsChangeRequest,
-  ControllerSettingsChangeResult,
-  ControllerWorkflows,
+  ResourceManagerFollowUpResult,
+  ResourceManagerQueueClaim,
+  ResourceManagerQueueFollowUpRequest,
+  ResourceManagerRemoveFollowUpRequest,
+  ManagedResource,
+  ResourceManagerSettingsChangeRequest,
+  ResourceManagerSettingsChangeResult,
+  ResourceManagerWorkflows,
 } from "./types.js";
 
 export type WorkflowSchedulerRequest = {
@@ -29,86 +29,88 @@ export type WorkflowSchedulerResult = {
   error?: string;
 };
 
-export type ControllerWorkflowControlRequest<TRequest> = TRequest & {
-  controllerResourceUid: string;
+export type ResourceManagerWorkflowControlRequest<TRequest> = TRequest & {
+  managedResourceUid: string;
   actorRequestKey: string;
 };
 
-export interface ControllerWorkflowScheduler {
+export interface ResourceManagerWorkflowScheduler {
   ensure(
     request: WorkflowSchedulerRequest,
     signal: AbortSignal,
     onComplete: (result: WorkflowSchedulerResult) => void,
   ): Promise<WorkflowSchedulerResult>;
   changeSettings?(
-    request: ControllerWorkflowControlRequest<ControllerSettingsChangeRequest>,
+    request: ResourceManagerWorkflowControlRequest<ResourceManagerSettingsChangeRequest>,
     signal: AbortSignal,
-  ): Promise<ControllerSettingsChangeResult>;
+  ): Promise<ResourceManagerSettingsChangeResult>;
   queueFollowUp?(
-    request: ControllerWorkflowControlRequest<ControllerQueueFollowUpRequest>,
+    request: ResourceManagerWorkflowControlRequest<ResourceManagerQueueFollowUpRequest>,
     signal: AbortSignal,
-  ): Promise<ControllerFollowUpResult>;
+  ): Promise<ResourceManagerFollowUpResult>;
   removeFollowUp?(
-    request: ControllerWorkflowControlRequest<ControllerRemoveFollowUpRequest>,
+    request: ResourceManagerWorkflowControlRequest<ResourceManagerRemoveFollowUpRequest>,
     signal: AbortSignal,
-  ): Promise<ControllerFollowUpResult>;
+  ): Promise<ResourceManagerFollowUpResult>;
 }
 
-function controllerRequestKey(resource: ControllerResource, requestKey: string): string {
+function resourceManagerRequestKey(resource: ManagedResource, requestKey: string): string {
   if (requestKey.trim().length === 0) {
-    throw new Error("Controller workflow requestKey must not be empty");
+    throw new Error("ResourceManager workflow requestKey must not be empty");
   }
-  return `controller:${resource.metadata.uid}:${requestKey}`;
+  return `resourceManager:${resource.metadata.uid}:${requestKey}`;
 }
 
-export class ControllerWorkflowCoordinator {
+export class ResourceManagerWorkflowCoordinator {
   constructor(
-    private readonly store: ControllerStore,
-    private readonly scheduler?: ControllerWorkflowScheduler,
+    private readonly store: ResourceManagerStore,
+    private readonly scheduler?: ResourceManagerWorkflowScheduler,
   ) {}
 
   forResource(
-    resource: ControllerResource,
-    claim: ControllerQueueClaim,
+    resource: ManagedResource,
+    claim: ResourceManagerQueueClaim,
     signal: AbortSignal,
-  ): ControllerWorkflows {
+  ): ResourceManagerWorkflows {
     return {
       ensure: async (request) => await this.ensure(resource, claim, request, signal),
       changeSettings: async (request) => {
         if (this.scheduler?.changeSettings === undefined) {
-          throw new Error("This controller host does not support workflow settings changes");
+          throw new Error(
+            "This resource manager runtime does not support workflow settings changes",
+          );
         }
         return await this.scheduler.changeSettings(
           {
             ...request,
-            controllerResourceUid: resource.metadata.uid,
-            actorRequestKey: controllerRequestKey(resource, request.requestKey),
+            managedResourceUid: resource.metadata.uid,
+            actorRequestKey: resourceManagerRequestKey(resource, request.requestKey),
           },
           signal,
         );
       },
       queueFollowUp: async (request) => {
         if (this.scheduler?.queueFollowUp === undefined) {
-          throw new Error("This controller host does not support workflow follow-ups");
+          throw new Error("This resource manager runtime does not support workflow follow-ups");
         }
         return await this.scheduler.queueFollowUp(
           {
             ...request,
-            controllerResourceUid: resource.metadata.uid,
-            actorRequestKey: controllerRequestKey(resource, request.requestKey),
+            managedResourceUid: resource.metadata.uid,
+            actorRequestKey: resourceManagerRequestKey(resource, request.requestKey),
           },
           signal,
         );
       },
       removeFollowUp: async (request) => {
         if (this.scheduler?.removeFollowUp === undefined) {
-          throw new Error("This controller host does not support workflow follow-ups");
+          throw new Error("This resource manager runtime does not support workflow follow-ups");
         }
         return await this.scheduler.removeFollowUp(
           {
             ...request,
-            controllerResourceUid: resource.metadata.uid,
-            actorRequestKey: controllerRequestKey(resource, request.requestKey),
+            managedResourceUid: resource.metadata.uid,
+            actorRequestKey: resourceManagerRequestKey(resource, request.requestKey),
           },
           signal,
         );
@@ -131,8 +133,8 @@ export class ControllerWorkflowCoordinator {
   }
 
   private async ensure(
-    resource: ControllerResource,
-    claim: ControllerQueueClaim,
+    resource: ManagedResource,
+    claim: ResourceManagerQueueClaim,
     request: ChildWorkflowRequest,
     signal: AbortSignal,
   ): Promise<ChildWorkflowRecord> {
@@ -212,7 +214,7 @@ export class ControllerWorkflowCoordinator {
     const resource = this.store.getResourceByUid(resourceUid);
     if (resource !== undefined) {
       this.store.enqueue({
-        controller: resource.metadata.controller,
+        resourceManager: resource.metadata.resourceManager,
         key: resource.metadata.key,
       });
     }
@@ -221,14 +223,14 @@ export class ControllerWorkflowCoordinator {
   private recordEvent(
     record: ChildWorkflowRecord,
     type: string,
-    claim: ControllerQueueClaim,
+    claim: ResourceManagerQueueClaim,
   ): void {
     const resource = this.store.getResourceByUid(record.resourceUid);
     if (resource === undefined) {
       return;
     }
     this.store.recordEvent({
-      controller: resource.metadata.controller,
+      resourceManager: resource.metadata.resourceManager,
       key: resource.metadata.key,
       claim,
       type,

package/src/{host → server}/channel-supervisor.ts

@@ -9,17 +9,17 @@ import {
   type ChannelAdapterMessage,
   type ChannelAdapterResponse,
 } from "../channels/protocol.js";
-import { ChildWorkerSupervisor, type SupervisedWorkerResult } from "./child-worker-supervisor.js";
-import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
-import type { WorkerOutcome } from "./state.js";
+import { ChildRunnerSupervisor, type SupervisedRunnerResult } from "./child-runner-supervisor.js";
+import { ServerProcessRegistry, type ProcessIdentity } from "./processes.js";
+import type { RunnerOutcome } from "./state.js";
 
 export class ChannelAdapterSupervisor {
-  private readonly supervisor: ChildWorkerSupervisor<ChannelAdapterMessage, ChannelAdapterResponse>;
+  private readonly supervisor: ChildRunnerSupervisor<ChannelAdapterMessage, ChannelAdapterResponse>;
 
   constructor(
     readonly launch: ChannelAdapterLaunch,
     private readonly options: {
-      registry: HostProcessRegistry;
+      registry: ServerProcessRegistry;
       onMessage: (message: ChannelAdapterMessage) => Promise<ChannelAdapterResponse>;
       env?: Record<string, string>;
       startupTimeoutMs?: number;
@@ -28,7 +28,7 @@ export class ChannelAdapterSupervisor {
       onDiagnostic?: (message: string) => void;
     },
   ) {
-    this.supervisor = new ChildWorkerSupervisor({
+    this.supervisor = new ChildRunnerSupervisor({
       label: `Telegram channel adapter ${launch.profile}`,
       registry: options.registry,
       onMessage: options.onMessage,
@@ -63,11 +63,11 @@ export class ChannelAdapterSupervisor {
     });
   }
 
-  async wait(): Promise<SupervisedWorkerResult> {
+  async wait(): Promise<SupervisedRunnerResult> {
     return await this.supervisor.wait();
   }
 
-  async stop(outcome: WorkerOutcome = "cancelled"): Promise<void> {
+  async stop(outcome: RunnerOutcome = "cancelled"): Promise<void> {
     await this.supervisor.stop(outcome);
   }
 }