@osolmaz/pi-workflows 0.16.2 → 0.16.3

package/src/extension/resource-manager-command.ts

@@ -0,0 +1,45 @@
+import type { JsonValue } from "../state/json.js";
+
+export type ParsedResourceManagerArgs =
+  | { kind: "list" }
+  | { kind: "get"; resourceManager: string; key: string }
+  | { kind: "apply"; resourceManager: string; key: string; spec: JsonValue }
+  | { kind: "reconcile"; resourceManager: string; key: string }
+  | { kind: "delete"; resourceManager: string; key: string };
+
+const RESOURCE_MANAGER_USAGE =
+  "Usage: /resource-manager [list|get <resource-manager> <key>|apply <resource-manager> <key> <json>|reconcile <resource-manager> <key>|delete <resource-manager> <key>]";
+
+export function parseResourceManagerArgs(args: string): ParsedResourceManagerArgs {
+  const trimmed = args.trim();
+  if (trimmed.length === 0 || trimmed === "list") return { kind: "list" };
+
+  const apply = trimmed.match(/^apply\s+(\S+)\s+(\S+)\s+([\s\S]+)$/u);
+  if (apply !== null) {
+    let spec: JsonValue;
+    try {
+      spec = JSON.parse(apply[3] as string) as JsonValue;
+    } catch (error) {
+      throw new Error(
+        `Invalid resource manager spec JSON: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    return {
+      kind: "apply",
+      resourceManager: apply[1] as string,
+      key: apply[2] as string,
+      spec,
+    };
+  }
+
+  const operation = trimmed.match(/^(get|reconcile|delete)\s+(\S+)\s+(\S+)$/u);
+  if (operation !== null) {
+    return {
+      kind: operation[1] as "get" | "reconcile" | "delete",
+      resourceManager: operation[2] as string,
+      key: operation[3] as string,
+    };
+  }
+
+  throw new Error(RESOURCE_MANAGER_USAGE);
+}

package/src/extension/session-delivery.ts

@@ -20,7 +20,7 @@ type QueuedSessionDelivery = {
 const SESSION_ENTRY_CONFIRMATION_MS = 10_000;
 
 /**
- * Delivers at most one host-owned message into a Pi session at a time.
+ * Delivers at most one server-owned message into a Pi session at a time.
  *
  * Pi's public sendMessage API does not return the saved session entry ID. Keep
  * the claimed delivery in memory until that entry becomes observable. Polling
@@ -54,7 +54,7 @@ export class SessionDeliveryCoordinator {
           return;
         }
 
-        // Remember the host claim before the final idle check. If Pi starts a
+        // Remember the server claim before the final idle check. If Pi starts a
         // turn while the claim request is in flight, a later poll can use this
         // exact still-live claim instead of making a conflicting second claim.
         this.claimed = delivery;

package/src/extension/session-view.ts

@@ -10,7 +10,7 @@ import { buildWidgetView } from "./widget.js";
 const WIDGET_KEY = "pi-workflows";
 const WIDGET_SCROLL_STEP = 3;
 
-/** Client-backed projection of the host-owned run into the origin Pi session. */
+/** Client-backed projection of the server-owned run into the origin Pi session. */
 export class SessionWorkflowView {
   private session: WorkflowSessionView | null = null;
   private scroll: number | null = null;

package/src/extension/workflow-message-coordinator.ts

@@ -25,7 +25,7 @@ type PendingTurn = {
   end: { stopReason: WorkflowTurnStopReason; responseSessionEntryId: string | null } | null;
 };
 
-/** Adds every host-owned workflow message to one Pi session through one public API path. */
+/** Adds every server-owned workflow message to one Pi session through one public API path. */
 export class WorkflowMessageCoordinator {
   private readonly queued = new Set<string>();
   private readonly closedTurnMessages = new Set<string>();
@@ -296,7 +296,7 @@ export class WorkflowMessageCoordinator {
       },
     });
     if (response.outcome !== "accepted" && response.outcome !== "adopted") {
-      throw new Error(response.error ?? "Workflow host rejected the Pi branch report");
+      throw new Error(response.error ?? "Workflow server rejected the Pi branch report");
     }
     for (const entry of entries) {
       const message = messageById(view, entry.workflowMessageId);
@@ -364,7 +364,7 @@ async function reportTurn(
     payload: report as unknown as JsonValue,
   });
   if (response.outcome !== "accepted" && response.outcome !== "adopted") {
-    throw new Error(response.error ?? "Workflow host rejected the model-turn report");
+    throw new Error(response.error ?? "Workflow server rejected the model-turn report");
   }
   const receipt = response.receipt;
   if (
@@ -372,12 +372,12 @@ async function reportTurn(
     receipt.schema !== WORKFLOW_TURN_REPORT_RECEIPT_SCHEMA ||
     !["active", "settled", "absent"].includes(String(receipt.ownership))
   ) {
-    throw new Error("Workflow host returned an invalid model-turn receipt");
+    throw new Error("Workflow server returned an invalid model-turn receipt");
   }
   const ownership = receipt.ownership as WorkflowTurnReportReceipt["ownership"];
   if (ownership === "absent") {
     if (receipt.turn !== null) {
-      throw new Error("Workflow host returned an invalid model-turn receipt");
+      throw new Error("Workflow server returned an invalid model-turn receipt");
     }
   } else if (
     !isRecord(receipt.turn) ||
@@ -388,7 +388,7 @@ async function reportTurn(
     receipt.turn.targetSessionId !== report.targetSessionId ||
     receipt.turn.state !== (ownership === "active" ? "started" : "ended")
   ) {
-    throw new Error("Workflow host returned an invalid model-turn receipt");
+    throw new Error("Workflow server returned an invalid model-turn receipt");
   }
   return receipt as unknown as WorkflowTurnReportReceipt;
 }

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

@@ -1,16 +1,16 @@
 import type {
-  ControllerCondition,
-  ControllerConditionInput,
-  ControllerConditionStatus,
-  ControllerResourceStatus,
-  ControllerStatusPatch,
+  ManagedResourceCondition,
+  ManagedResourceConditionInput,
+  ManagedResourceConditionStatus,
+  ManagedResourceStatus,
+  ResourceManagerStatusPatch,
 } from "./types.js";
 
 export function conditionTrue(
   type: string,
   reason: string,
   message?: string,
-): ControllerConditionInput {
+): ManagedResourceConditionInput {
   return condition(type, true, reason, message);
 }
 
@@ -18,7 +18,7 @@ export function conditionFalse(
   type: string,
   reason: string,
   message?: string,
-): ControllerConditionInput {
+): ManagedResourceConditionInput {
   return condition(type, false, reason, message);
 }
 
@@ -26,23 +26,23 @@ export function conditionUnknown(
   type: string,
   reason: string,
   message?: string,
-): ControllerConditionInput {
+): ManagedResourceConditionInput {
   return condition(type, "unknown", reason, message);
 }
 
 export function applyStatusPatch<TStatus>(
-  current: ControllerResourceStatus<TStatus>,
-  patch: ControllerStatusPatch<TStatus> | undefined,
+  current: ManagedResourceStatus<TStatus>,
+  patch: ResourceManagerStatusPatch<TStatus> | undefined,
   generation: number,
   now: string,
-): ControllerResourceStatus<TStatus> {
+): ManagedResourceStatus<TStatus> {
   return {
     observedGeneration: generation,
     conditions: mergeConditions(current.conditions, patch?.conditions ?? [], generation, now),
-    controllerStatus:
-      patch !== undefined && Object.hasOwn(patch, "controllerStatus")
-        ? (patch.controllerStatus as TStatus)
-        : current.controllerStatus,
+    resourceManagerStatus:
+      patch !== undefined && Object.hasOwn(patch, "resourceManagerStatus")
+        ? (patch.resourceManagerStatus as TStatus)
+        : current.resourceManagerStatus,
     ...(patch?.workflowRun === null
       ? {}
       : patch?.workflowRun !== undefined
@@ -54,11 +54,11 @@ export function applyStatusPatch<TStatus>(
 }
 
 export function mergeConditions(
-  current: ControllerCondition[],
-  updates: ControllerConditionInput[],
+  current: ManagedResourceCondition[],
+  updates: ManagedResourceConditionInput[],
   generation: number,
   now: string,
-): ControllerCondition[] {
+): ManagedResourceCondition[] {
   const byType = new Map(current.map((item) => [item.type, item]));
   const seen = new Set<string>();
   for (const update of updates) {
@@ -68,7 +68,7 @@ export function mergeConditions(
     }
     seen.add(update.type);
     const previous = byType.get(update.type);
-    const next: ControllerCondition = {
+    const next: ManagedResourceCondition = {
       ...update,
       observedGeneration: generation,
       lastTransitionTime:
@@ -83,11 +83,11 @@ export function mergeConditions(
 
 function condition(
   type: string,
-  status: ControllerConditionStatus,
+  status: ManagedResourceConditionStatus,
   reason: string,
   message: string | undefined,
-): ControllerConditionInput {
-  const value: ControllerConditionInput = {
+): ManagedResourceConditionInput {
+  const value: ManagedResourceConditionInput = {
     type,
     status,
     reason,
@@ -97,7 +97,7 @@ function condition(
   return value;
 }
 
-function validateCondition(value: ControllerConditionInput): void {
+function validateCondition(value: ManagedResourceConditionInput): void {
   if (value.type.trim().length === 0) {
     throw new Error("Condition type must not be empty");
   }

package/src/resource-managers/definition.ts

@@ -0,0 +1,71 @@
+import type {
+  AnyResourceManagerDefinition,
+  ResourceManagerDefinition,
+  ManagedResource,
+} from "./types.js";
+
+const RESOURCE_MANAGER_DEFINITION_BRAND = Symbol.for("pi-workflows.resource-manager-definition");
+const RESOURCE_MANAGER_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export function defineResourceManager<TSpec, TStatus>(
+  definition: ResourceManagerDefinition<TSpec, TStatus>,
+): ResourceManagerDefinition<TSpec, TStatus> {
+  assertValidResourceManagerDefinition(definition);
+  if (isResourceManagerDefinition(definition)) {
+    return definition;
+  }
+  Object.defineProperty(definition, RESOURCE_MANAGER_DEFINITION_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return definition;
+}
+
+export function isResourceManagerDefinition(value: unknown): value is AnyResourceManagerDefinition {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<PropertyKey, unknown>)[RESOURCE_MANAGER_DEFINITION_BRAND] === true
+  );
+}
+
+export function assertValidResourceManagerDefinition<TSpec, TStatus>(
+  definition: ResourceManagerDefinition<TSpec, TStatus>,
+): void {
+  if (definition === null || typeof definition !== "object") {
+    throw new Error("Invalid resource manager definition: expected an object");
+  }
+  if (!RESOURCE_MANAGER_NAME_PATTERN.test(definition.name)) {
+    throw new Error(
+      `Invalid resource manager definition: name ${JSON.stringify(definition.name)} must match ${RESOURCE_MANAGER_NAME_PATTERN.source}`,
+    );
+  }
+  if (typeof definition.initialStatus !== "function") {
+    throw new Error("Invalid resource manager definition: initialStatus must be a function");
+  }
+  if (typeof definition.reconcile !== "function") {
+    throw new Error("Invalid resource manager definition: reconcile must be a function");
+  }
+  if (
+    definition.timeoutMs !== undefined &&
+    (!Number.isSafeInteger(definition.timeoutMs) || definition.timeoutMs <= 0)
+  ) {
+    throw new Error(
+      "Invalid resource manager definition: timeoutMs must be a positive safe integer",
+    );
+  }
+}
+
+export function asAnyResourceManagerDefinition<TSpec, TStatus>(
+  definition: ResourceManagerDefinition<TSpec, TStatus>,
+): AnyResourceManagerDefinition {
+  return definition as unknown as ResourceManagerDefinition<unknown, unknown>;
+}
+
+export function asTypedResource<TSpec, TStatus>(
+  resource: ManagedResource,
+): ManagedResource<TSpec, TStatus> {
+  return resource as ManagedResource<TSpec, TStatus>;
+}

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

@@ -1,9 +1,9 @@
 import { jsonFingerprint } from "./json.js";
-import type { ControllerStore } from "./store.js";
+import type { ResourceManagerStore } from "./store.js";
 import type {
-  ControllerEffects,
-  ControllerQueueClaim,
-  ControllerResource,
+  ResourceManagerEffects,
+  ResourceManagerQueueClaim,
+  ManagedResource,
   EffectApplication,
   EffectDefinition,
   EffectObservation,
@@ -11,13 +11,13 @@ import type {
   JsonObject,
 } from "./types.js";
 
-export class ControllerEffectService implements ControllerEffects {
+export class ResourceManagerEffectService implements ResourceManagerEffects {
   private used = false;
 
   constructor(
-    private readonly store: ControllerStore,
-    private readonly resource: ControllerResource,
-    private readonly claim: ControllerQueueClaim,
+    private readonly store: ResourceManagerStore,
+    private readonly resource: ManagedResource,
+    private readonly claim: ResourceManagerQueueClaim,
     private readonly signal: AbortSignal,
   ) {}
 
@@ -115,7 +115,7 @@ export class ControllerEffectService implements ControllerEffects {
 
   private recordEvent(type: string, effectKey: string, extra: JsonObject = {}): void {
     this.store.recordEvent({
-      controller: this.resource.metadata.controller,
+      resourceManager: this.resource.metadata.resourceManager,
       key: this.resource.metadata.key,
       claim: this.claim,
       type,

package/src/resource-managers/errors.ts

@@ -0,0 +1,27 @@
+export class ManagedResourceConflictError extends Error {
+  constructor(resourceManager: string, key: string) {
+    super(`Managed resource ${resourceManager}/${key} changed during reconciliation`);
+    this.name = "ManagedResourceConflictError";
+  }
+}
+
+export class ManagedResourceNotFoundError extends Error {
+  constructor(resourceManager: string, key: string) {
+    super(`Managed resource not found: ${resourceManager}/${key}`);
+    this.name = "ManagedResourceNotFoundError";
+  }
+}
+
+export class EffectRequestConflictError extends Error {
+  constructor(key: string) {
+    super(`Effect key ${JSON.stringify(key)} was reused with a different request`);
+    this.name = "EffectRequestConflictError";
+  }
+}
+
+export class WorkflowRequestConflictError extends Error {
+  constructor(key: string) {
+    super(`Workflow request key ${JSON.stringify(key)} was reused with different input`);
+    this.name = "WorkflowRequestConflictError";
+  }
+}

package/src/resource-managers/index.ts

@@ -0,0 +1,88 @@
+export {
+  assertValidResourceManagerDefinition,
+  defineResourceManager,
+  isResourceManagerDefinition,
+} from "./definition.js";
+export {
+  applyStatusPatch,
+  conditionFalse,
+  conditionTrue,
+  conditionUnknown,
+  mergeConditions,
+} from "./conditions.js";
+export {
+  EffectRequestConflictError,
+  ManagedResourceConflictError,
+  ManagedResourceNotFoundError,
+  WorkflowRequestConflictError,
+} from "./errors.js";
+export { ResourceManagerEffectService } from "./effects.js";
+export { canonicalJson, jsonFingerprint } from "./json.js";
+export { ResourceManagerRuntime, type ResourceManagerRuntimeOptions } from "./runtime.js";
+export { createResultHelpers, requeue, requeueAfter, settled } from "./results.js";
+export {
+  SqliteResourceManagerStore,
+  type RunEventRecord,
+  type WorkflowRunClaimOptions,
+  type WorkflowRunPreparationResult,
+  type WorkflowRunQueueRecord,
+  type WorkflowRunReservationOptions,
+} from "./sqlite.js";
+export {
+  type ResourceManagerStore,
+  type EffectReservation,
+  type QueueItem,
+  type QueueRequeueOptions,
+  type WorkflowRecordUpdate,
+  type WorkflowReservation,
+} from "./store.js";
+export {
+  resourceManagerFileStem,
+  resourceManagerSearchDirs,
+  discoverResourceManagers,
+  loadResourceManagerFile,
+  loadDiscoveredResourceManagers,
+  type DiscoveredResourceManager,
+} from "./loader.js";
+export {
+  ResourceManagerWorkflowCoordinator,
+  type ResourceManagerWorkflowControlRequest,
+  type ResourceManagerWorkflowScheduler,
+  type WorkflowSchedulerRequest,
+  type WorkflowSchedulerResult,
+} from "./workflows.js";
+export type {
+  AnyResourceManagerDefinition,
+  ChildWorkflowRecord,
+  ChildWorkflowReference,
+  ChildWorkflowRequest,
+  ChildWorkflowState,
+  ManagedResourceCondition,
+  ManagedResourceConditionInput,
+  ManagedResourceConditionStatus,
+  ResourceManagerDefinition,
+  ResourceManagerEffects,
+  ResourceManagerFollowUpResult,
+  ResourceManagerQueueFollowUpRequest,
+  ResourceManagerRemoveFollowUpRequest,
+  ResourceManagerSettingsChangeRequest,
+  ResourceManagerSettingsChangeResult,
+  ResourceManagerEvent,
+  ResourceManagerQueueClaim,
+  ManagedResource,
+  ManagedResourceRef,
+  ManagedResourceStatus,
+  ResourceManagerStatusPatch,
+  ResourceManagerWorkflows,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  EffectState,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  MaybePromise,
+  ReconcileContext,
+  ReconcileResult,
+} from "./types.js";

package/src/resource-managers/loader.ts

@@ -0,0 +1,111 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { isResourceManagerDefinition } from "./definition.js";
+import type { AnyResourceManagerDefinition } from "./types.js";
+
+const RESOURCE_MANAGER_FILE_SUFFIXES = [
+  ".resource-manager.ts",
+  ".resource-manager.js",
+  ".resource-manager.mts",
+  ".resource-manager.mjs",
+];
+
+export type DiscoveredResourceManager = {
+  name: string;
+  path: string;
+  source: "project" | "global";
+};
+
+export function resourceManagerSearchDirs(options: {
+  cwd: string;
+  homeDir?: string;
+}): { dir: string; source: DiscoveredResourceManager["source"] }[] {
+  const homeDir = options.homeDir ?? os.homedir();
+  return [
+    { dir: path.join(options.cwd, ".pi", "resource-managers"), source: "project" },
+    { dir: path.join(homeDir, ".pi", "agent", "resource-managers"), source: "global" },
+  ];
+}
+
+export function resourceManagerFileStem(filePath: string): string {
+  const base = path.basename(filePath);
+  const suffix = RESOURCE_MANAGER_FILE_SUFFIXES.find((candidate) => base.endsWith(candidate));
+  return suffix === undefined ? base : base.slice(0, -suffix.length);
+}
+
+const RESOURCE_MANAGER_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+const WORKFLOW_ENTRY = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../workflows/index",
+);
+
+export async function loadResourceManagerFile(
+  filePath: string,
+): Promise<AnyResourceManagerDefinition> {
+  const absolutePath = path.resolve(filePath);
+  const jiti = createJiti(pathToFileURL(absolutePath).href, {
+    interopDefault: true,
+    moduleCache: false,
+    alias: {
+      "@osolmaz/pi-workflows/resource-managers": RESOURCE_MANAGER_ENTRY,
+      "@osolmaz/pi-workflows": WORKFLOW_ENTRY,
+    },
+  });
+  const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
+  if (!isResourceManagerDefinition(loaded)) {
+    throw new Error(
+      `ResourceManager module must default-export defineResourceManager(...): ${absolutePath}`,
+    );
+  }
+  return loaded;
+}
+
+export async function discoverResourceManagers(options: {
+  cwd: string;
+  homeDir?: string;
+}): Promise<DiscoveredResourceManager[]> {
+  const discovered: DiscoveredResourceManager[] = [];
+  const seen = new Set<string>();
+  for (const { dir, source } of resourceManagerSearchDirs(options)) {
+    for (const filePath of await listResourceManagerFiles(dir)) {
+      const name = resourceManagerFileStem(filePath);
+      if (seen.has(name)) {
+        continue;
+      }
+      seen.add(name);
+      discovered.push({ name, path: filePath, source });
+    }
+  }
+  return discovered;
+}
+
+export async function loadDiscoveredResourceManagers(options: {
+  cwd: string;
+  homeDir?: string;
+}): Promise<AnyResourceManagerDefinition[]> {
+  return await Promise.all(
+    (await discoverResourceManagers(options)).map(
+      async (entry) => await loadResourceManagerFile(entry.path),
+    ),
+  );
+}
+
+async function listResourceManagerFiles(dir: string): Promise<string[]> {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        RESOURCE_MANAGER_FILE_SUFFIXES.some((suffix) => entry.name.endsWith(suffix)),
+    )
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}

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

@@ -1,4 +1,4 @@
-import type { ControllerStatusPatch, ReconcileContext, ReconcileResult } from "./types.js";
+import type { ResourceManagerStatusPatch, ReconcileContext, ReconcileResult } from "./types.js";
 
 export function createResultHelpers<TStatus>(): Pick<
   ReconcileContext<TStatus>,
@@ -27,20 +27,20 @@ export function createResultHelpers<TStatus>(): Pick<
 }
 
 export function settled<TStatus>(
-  status?: ControllerStatusPatch<TStatus>,
+  status?: ResourceManagerStatusPatch<TStatus>,
 ): ReconcileResult<TStatus> {
   return createResultHelpers<TStatus>().settled(status);
 }
 
 export function requeue<TStatus>(
-  status?: ControllerStatusPatch<TStatus>,
+  status?: ResourceManagerStatusPatch<TStatus>,
 ): ReconcileResult<TStatus> {
   return createResultHelpers<TStatus>().requeue(status);
 }
 
 export function requeueAfter<TStatus>(
   afterMs: number,
-  status?: ControllerStatusPatch<TStatus>,
+  status?: ResourceManagerStatusPatch<TStatus>,
 ): ReconcileResult<TStatus> {
   return createResultHelpers<TStatus>().requeueAfter(afterMs, status);
 }