@osolmaz/pi-workflows 0.2.0 → 0.3.0

package/src/builtins/monitor.workflow.ts

@@ -0,0 +1,278 @@
+import { agent, compute, defineWorkflow, shell } from "../workflows/index.js";
+import type { WorkflowNodeContext } from "../workflows/types.js";
+
+const MIN_INTERVAL_MINUTES = 1;
+const MAX_INTERVAL_MINUTES = 24 * 60;
+const DEFAULT_MAX_CHECKS = 1_000;
+const MAX_CHECKS = 1_000;
+const MAX_OBSERVATION_CHARS = 8_000;
+const MAX_REPORT_CHARS = 4_000;
+const MAX_REASON_CHARS = 2_000;
+const SLEEP_TIMEOUT_MARGIN_MS = 60_000;
+const NODE_TIMEOUT_MARGIN_MS = 2 * 60_000;
+
+type MonitorInput = {
+  task: string;
+  everyMinutes: number;
+  reportWhen?: string;
+  stopWhen?: string;
+  maxChecks?: number;
+};
+
+type MonitorConfig = {
+  task: string;
+  everyMinutes: number;
+  reportWhen: string;
+  stopWhen: string;
+  maxChecks: number;
+};
+
+type MonitorRoute = "continue_quiet" | "continue_report" | "stop_quiet" | "stop_report";
+
+type MonitorCheck = {
+  route: MonitorRoute;
+  observation: string;
+  report?: string;
+  reason: string;
+};
+
+const MONITOR_ROUTES = new Set<MonitorRoute>([
+  "continue_quiet",
+  "continue_report",
+  "stop_quiet",
+  "stop_report",
+]);
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireBoundedString(value: unknown, label: string, maxChars: number): string {
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${label} must not be empty`);
+  }
+  if (trimmed.length > maxChars) {
+    throw new Error(`${label} must be at most ${maxChars} characters`);
+  }
+  return trimmed;
+}
+
+function prepareInput(input: unknown): MonitorConfig {
+  const value = requireRecord(input, "monitor input") as Partial<MonitorInput>;
+  const task = requireBoundedString(value.task, "task", 8_000);
+  if (
+    typeof value.everyMinutes !== "number" ||
+    !Number.isInteger(value.everyMinutes) ||
+    value.everyMinutes < MIN_INTERVAL_MINUTES ||
+    value.everyMinutes > MAX_INTERVAL_MINUTES
+  ) {
+    throw new Error(
+      `everyMinutes must be an integer from ${MIN_INTERVAL_MINUTES} through ${MAX_INTERVAL_MINUTES}`,
+    );
+  }
+  const maxChecks = value.maxChecks ?? DEFAULT_MAX_CHECKS;
+  if (!Number.isInteger(maxChecks) || maxChecks <= 0 || maxChecks > MAX_CHECKS) {
+    throw new Error(`maxChecks must be an integer from 1 through ${MAX_CHECKS}`);
+  }
+  return {
+    task,
+    everyMinutes: value.everyMinutes,
+    reportWhen:
+      value.reportWhen === undefined
+        ? "The observed state changes materially or needs the user's attention."
+        : requireBoundedString(value.reportWhen, "reportWhen", 4_000),
+    stopWhen:
+      value.stopWhen === undefined
+        ? "The user cancels the monitor or it reaches its maximum check count."
+        : requireBoundedString(value.stopWhen, "stopWhen", 4_000),
+    maxChecks,
+  };
+}
+
+function configFrom(outputs: Record<string, unknown>): MonitorConfig {
+  return outputs.prepare as MonitorConfig;
+}
+
+function completedChecks(context: WorkflowNodeContext): number {
+  return context.state.steps.filter((step) => step.nodeId === "check" && step.outcome === "ok")
+    .length;
+}
+
+function validateCheck(output: unknown): MonitorCheck {
+  const value = requireRecord(output, "monitor check output");
+  if (typeof value.route !== "string" || !MONITOR_ROUTES.has(value.route as MonitorRoute)) {
+    throw new Error(`route must be one of ${[...MONITOR_ROUTES].join(", ")}`);
+  }
+  const route = value.route as MonitorRoute;
+  const observation = requireBoundedString(value.observation, "observation", MAX_OBSERVATION_CHARS);
+  const reason = requireBoundedString(value.reason, "reason", MAX_REASON_CHARS);
+  const reports = route === "continue_report" || route === "stop_report";
+  const report =
+    value.report === undefined
+      ? undefined
+      : requireBoundedString(value.report, "report", MAX_REPORT_CHARS);
+  if (reports && report === undefined) {
+    throw new Error(`route ${route} requires a report`);
+  }
+  return {
+    route,
+    observation,
+    ...(report !== undefined ? { report } : {}),
+    reason,
+  };
+}
+
+function validateReportAck(output: unknown): { reported: true } {
+  const value = requireRecord(output, "report acknowledgement");
+  if (value.reported !== true) {
+    throw new Error("report acknowledgement must set reported to true");
+  }
+  return { reported: true };
+}
+
+function reportPrompt(outputs: Record<string, unknown>): string {
+  const check = outputs.check as MonitorCheck;
+  return [
+    "Write one concise normal assistant message to the user with this monitoring update:",
+    check.report ?? check.observation,
+    "Do not add unrelated detail.",
+    "After writing the update, submit the acknowledgement required by the workflow step contract.",
+  ].join("\n\n");
+}
+
+export default defineWorkflow({
+  name: "monitor",
+  title: ({ input }) => {
+    try {
+      const task = prepareInput(input).task;
+      return `monitor: ${task.slice(0, 80)}`;
+    } catch {
+      return "monitor";
+    }
+  },
+  presentationPrompt: ({ finalOutput }) => {
+    const result = requireRecord(finalOutput, "monitor result");
+    if (result.reported === true) {
+      return undefined;
+    }
+    return `Tell the user concisely why this monitor stopped: ${String(result.reason ?? "monitor ended")}`;
+  },
+  startAt: "prepare",
+  maxSteps: 5_010,
+  nodes: {
+    prepare: compute({
+      run: ({ input }) => prepareInput(input),
+    }),
+    guard: compute({
+      run: (context) => {
+        const config = configFrom(context.outputs);
+        const checks = completedChecks(context);
+        return checks >= config.maxChecks
+          ? { route: "stop", checks, reason: `Reached the ${config.maxChecks}-check limit.` }
+          : { route: "check", checks };
+      },
+    }),
+    continue_guard: compute({
+      run: (context) => {
+        const config = configFrom(context.outputs);
+        const checks = completedChecks(context);
+        return checks >= config.maxChecks
+          ? { route: "stop", checks, reason: `Reached the ${config.maxChecks}-check limit.` }
+          : { route: "sleep", checks };
+      },
+    }),
+    check: agent({
+      statusDetail: "checking monitored target",
+      prompt: (context) => {
+        const config = configFrom(context.outputs);
+        const previous = context.outputs.check as MonitorCheck | undefined;
+        const checkNumber = completedChecks(context) + 1;
+        return [
+          `Perform monitoring check ${checkNumber} of at most ${config.maxChecks}.`,
+          `Task: ${config.task}`,
+          `Report when: ${config.reportWhen}`,
+          `Stop when: ${config.stopWhen}`,
+          previous === undefined
+            ? "There is no previous observation. Report the initial state only when the report condition calls for it."
+            : `Previous accepted observation: ${previous.observation}`,
+          "Use available tools to inspect the current state. Observe only unless the task explicitly authorizes a mutation.",
+          "Choose continue_quiet, continue_report, stop_quiet, or stop_report. A report route requires concise report text.",
+        ].join("\n\n");
+      },
+      expectedOutput:
+        '{ "route": "continue_quiet" | "continue_report" | "stop_quiet" | "stop_report", "observation": "current factual state", "report": "required for report routes", "reason": "short reason" }',
+      validate: (output) => validateCheck(output),
+    }),
+    report_continue: agent({
+      statusDetail: "reporting monitor update",
+      prompt: ({ outputs }) => reportPrompt(outputs),
+      expectedOutput: '{ "reported": true }',
+      validate: (output) => validateReportAck(output),
+    }),
+    report_stop: agent({
+      statusDetail: "reporting final monitor update",
+      prompt: ({ outputs }) => reportPrompt(outputs),
+      expectedOutput: '{ "reported": true }',
+      validate: (output) => validateReportAck(output),
+    }),
+    sleep: shell({
+      statusDetail: "waiting for next monitor check",
+      timeoutMs: MAX_INTERVAL_MINUTES * 60_000 + NODE_TIMEOUT_MARGIN_MS,
+      exec: ({ outputs }) => {
+        const config = configFrom(outputs);
+        const sleepMs = config.everyMinutes * 60_000;
+        return {
+          command: process.execPath,
+          args: ["-e", "setTimeout(() => {}, Number(process.argv[1]))", String(sleepMs)],
+          timeoutMs: sleepMs + SLEEP_TIMEOUT_MARGIN_MS,
+          maxOutputChars: 1_024,
+        };
+      },
+      parse: (_result, { outputs }) => ({ waitedMinutes: configFrom(outputs).everyMinutes }),
+    }),
+    finish: compute({
+      run: ({ outputs }) => {
+        const check = outputs.check as MonitorCheck | undefined;
+        const guard = outputs.guard as { reason?: string } | undefined;
+        const continueGuard = outputs.continue_guard as { reason?: string } | undefined;
+        return {
+          reason: continueGuard?.reason ?? guard?.reason ?? check?.reason ?? "Monitor finished.",
+          observation: check?.observation ?? null,
+          reported:
+            outputs.report_stop !== undefined ||
+            (check !== undefined && check.route === "stop_report"),
+        };
+      },
+    }),
+  },
+  edges: [
+    { from: "prepare", to: "guard" },
+    { from: "guard", switch: { on: "$.route", cases: { check: "check", stop: "finish" } } },
+    {
+      from: "check",
+      switch: {
+        on: "$.route",
+        cases: {
+          continue_quiet: "continue_guard",
+          continue_report: "report_continue",
+          stop_quiet: "finish",
+          stop_report: "report_stop",
+        },
+      },
+    },
+    { from: "report_continue", to: "continue_guard" },
+    { from: "report_stop", to: "finish" },
+    {
+      from: "continue_guard",
+      switch: { on: "$.route", cases: { sleep: "sleep", stop: "finish" } },
+    },
+    { from: "sleep", to: "guard" },
+  ],
+});

package/src/controllers/conditions.ts

@@ -0,0 +1,110 @@
+import type {
+  ControllerCondition,
+  ControllerConditionInput,
+  ControllerConditionStatus,
+  ControllerResourceStatus,
+  ControllerStatusPatch,
+} from "./types.js";
+
+export function conditionTrue(
+  type: string,
+  reason: string,
+  message?: string,
+): ControllerConditionInput {
+  return condition(type, true, reason, message);
+}
+
+export function conditionFalse(
+  type: string,
+  reason: string,
+  message?: string,
+): ControllerConditionInput {
+  return condition(type, false, reason, message);
+}
+
+export function conditionUnknown(
+  type: string,
+  reason: string,
+  message?: string,
+): ControllerConditionInput {
+  return condition(type, "unknown", reason, message);
+}
+
+export function applyStatusPatch<TStatus>(
+  current: ControllerResourceStatus<TStatus>,
+  patch: ControllerStatusPatch<TStatus> | undefined,
+  generation: number,
+  now: string,
+): ControllerResourceStatus<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,
+    ...(patch?.workflowRun === null
+      ? {}
+      : patch?.workflowRun !== undefined
+        ? { workflowRun: patch.workflowRun }
+        : current.workflowRun !== undefined
+          ? { workflowRun: current.workflowRun }
+          : {}),
+  };
+}
+
+export function mergeConditions(
+  current: ControllerCondition[],
+  updates: ControllerConditionInput[],
+  generation: number,
+  now: string,
+): ControllerCondition[] {
+  const byType = new Map(current.map((item) => [item.type, item]));
+  const seen = new Set<string>();
+  for (const update of updates) {
+    validateCondition(update);
+    if (seen.has(update.type)) {
+      throw new Error(`Condition ${JSON.stringify(update.type)} was updated more than once`);
+    }
+    seen.add(update.type);
+    const previous = byType.get(update.type);
+    const next: ControllerCondition = {
+      ...update,
+      observedGeneration: generation,
+      lastTransitionTime:
+        previous !== undefined && previous.status === update.status
+          ? previous.lastTransitionTime
+          : now,
+    };
+    byType.set(update.type, next);
+  }
+  return [...byType.values()];
+}
+
+function condition(
+  type: string,
+  status: ControllerConditionStatus,
+  reason: string,
+  message: string | undefined,
+): ControllerConditionInput {
+  const value: ControllerConditionInput = {
+    type,
+    status,
+    reason,
+    ...(message !== undefined ? { message } : {}),
+  };
+  validateCondition(value);
+  return value;
+}
+
+function validateCondition(value: ControllerConditionInput): void {
+  if (value.type.trim().length === 0) {
+    throw new Error("Condition type must not be empty");
+  }
+  if (value.reason.trim().length === 0) {
+    throw new Error("Condition reason must not be empty");
+  }
+  if (value.status !== true && value.status !== false && value.status !== "unknown") {
+    throw new Error(`Invalid condition status for ${JSON.stringify(value.type)}`);
+  }
+}

package/src/controllers/definition.ts

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

package/src/controllers/effects.ts

@@ -0,0 +1,123 @@
+import { jsonFingerprint } from "./json.js";
+import type { ControllerStore } from "./store.js";
+import type {
+  ControllerEffects,
+  ControllerResource,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  JsonObject,
+} from "./types.js";
+
+export class ControllerEffectService implements ControllerEffects {
+  private used = false;
+
+  constructor(
+    private readonly store: ControllerStore,
+    private readonly resource: ControllerResource,
+    private readonly signal: AbortSignal,
+  ) {}
+
+  async ensure<TRequest>(definition: EffectDefinition<TRequest>): Promise<EffectRecord> {
+    if (this.used) {
+      throw new Error("A reconciliation pass may ensure only one external effect");
+    }
+    this.used = true;
+    const requestFingerprint = jsonFingerprint(definition.request);
+    const reservation = this.store.reserveEffect({
+      key: definition.key,
+      resourceUid: this.resource.metadata.uid,
+      generation: this.resource.metadata.generation,
+      kind: definition.kind,
+      requestFingerprint,
+    });
+    if (reservation.record.state === "applied" || reservation.record.state === "rejected") {
+      return reservation.record;
+    }
+
+    if (!reservation.created) {
+      const observed = await this.observe(definition);
+      const recovered = this.applyObservation(definition.key, observed);
+      if (recovered !== undefined) {
+        return recovered;
+      }
+    }
+
+    return await this.apply(definition);
+  }
+
+  private async observe<TRequest>(
+    definition: EffectDefinition<TRequest>,
+  ): Promise<EffectObservation> {
+    try {
+      return await definition.observe(this.signal);
+    } catch (error) {
+      this.recordEvent("effect_observe_failed", definition.key, {
+        error: boundedError(error),
+      });
+      throw error;
+    }
+  }
+
+  private applyObservation(key: string, observation: EffectObservation): EffectRecord | undefined {
+    if (observation.state === "not_applied") {
+      return undefined;
+    }
+    const record = this.store.updateEffect({
+      resourceUid: this.resource.metadata.uid,
+      key,
+      state: observation.state === "applied" ? "applied" : "indeterminate",
+      ...("externalRef" in observation && observation.externalRef !== undefined
+        ? { externalRef: observation.externalRef }
+        : {}),
+    });
+    this.recordEvent(
+      observation.state === "applied" ? "effect_recovered" : "effect_indeterminate",
+      key,
+    );
+    return record;
+  }
+
+  private async apply<TRequest>(definition: EffectDefinition<TRequest>): Promise<EffectRecord> {
+    let result: EffectApplication;
+    try {
+      result = await definition.apply(this.signal);
+    } catch (error) {
+      const message = boundedError(error);
+      const record = this.store.updateEffect({
+        resourceUid: this.resource.metadata.uid,
+        key: definition.key,
+        state: "indeterminate",
+        error: message,
+      });
+      this.recordEvent("effect_indeterminate", definition.key, { error: message });
+      return record;
+    }
+    const record = this.store.updateEffect({
+      resourceUid: this.resource.metadata.uid,
+      key: definition.key,
+      state: result.state,
+      ...(result.state === "applied" && result.externalRef !== undefined
+        ? { externalRef: result.externalRef }
+        : {}),
+      ...(result.state !== "applied" && result.error !== undefined ? { error: result.error } : {}),
+    });
+    this.recordEvent(`effect_${result.state}`, definition.key);
+    return record;
+  }
+
+  private recordEvent(type: string, effectKey: string, extra: JsonObject = {}): void {
+    this.store.recordEvent({
+      controller: this.resource.metadata.controller,
+      key: this.resource.metadata.key,
+      type,
+      payload: { effectKey, ...extra },
+    });
+  }
+}
+
+function boundedError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.length <= 8_192 ? message : `${message.slice(0, 8_192)}…`;
+}

package/src/controllers/errors.ts

@@ -0,0 +1,27 @@
+export class ResourceConflictError extends Error {
+  constructor(controller: string, key: string) {
+    super(`Controller resource ${controller}/${key} changed during reconciliation`);
+    this.name = "ResourceConflictError";
+  }
+}
+
+export class ResourceNotFoundError extends Error {
+  constructor(controller: string, key: string) {
+    super(`Controller resource not found: ${controller}/${key}`);
+    this.name = "ResourceNotFoundError";
+  }
+}
+
+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/controllers/index.ts

@@ -0,0 +1,90 @@
+export {
+  assertValidControllerDefinition,
+  defineController,
+  isControllerDefinition,
+} from "./definition.js";
+export {
+  applyStatusPatch,
+  conditionFalse,
+  conditionTrue,
+  conditionUnknown,
+  mergeConditions,
+} from "./conditions.js";
+export {
+  EffectRequestConflictError,
+  ResourceConflictError,
+  ResourceNotFoundError,
+  WorkflowRequestConflictError,
+} from "./errors.js";
+export { ControllerEffectService } from "./effects.js";
+export { canonicalJson, jsonFingerprint } from "./json.js";
+export { ControllerManager, type ControllerManagerOptions } from "./manager.js";
+export { createResultHelpers, requeue, requeueAfter, settled } from "./results.js";
+export {
+  SqliteControllerStore,
+  type RunEventRecord,
+  type WorkflowRunQueueRecord,
+} from "./sqlite.js";
+export {
+  CONTROLLER_STORE_SCHEMA,
+  controllerProjectScope,
+  controllerStoreBaseDir,
+  controllerStorePath,
+  projectControllerStoreBaseDir,
+  projectControllerStorePath,
+  type ControllerStore,
+  type EffectReservation,
+  type QueueItem,
+  type QueueRequeueOptions,
+  type WorkflowRecordUpdate,
+  type WorkflowReservation,
+} from "./store.js";
+export {
+  controllerFileStem,
+  controllerSearchDirs,
+  discoverControllers,
+  loadControllerFile,
+  loadDiscoveredControllers,
+  type DiscoveredController,
+} from "./loader.js";
+export {
+  WorkflowEngineScheduler,
+  type ResolvedChildWorkflow,
+  type WorkflowEngineSchedulerOptions,
+} from "./workflow-engine-scheduler.js";
+export {
+  ControllerWorkflowCoordinator,
+  type ControllerWorkflowScheduler,
+  type WorkflowSchedulerRequest,
+  type WorkflowSchedulerResult,
+} from "./workflows.js";
+export type {
+  AnyControllerDefinition,
+  ChildWorkflowRecord,
+  ChildWorkflowReference,
+  ChildWorkflowRequest,
+  ChildWorkflowState,
+  ControllerCondition,
+  ControllerConditionInput,
+  ControllerConditionStatus,
+  ControllerDefinition,
+  ControllerEffects,
+  ControllerEvent,
+  ControllerQueueClaim,
+  ControllerResource,
+  ControllerResourceRef,
+  ControllerResourceStatus,
+  ControllerStatusPatch,
+  ControllerWorkflows,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  EffectState,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  MaybePromise,
+  ReconcileContext,
+  ReconcileResult,
+} from "./types.js";