@osolmaz/pi-workflows 0.13.1 → 0.13.3

package/src/controllers/workflow-engine-scheduler.ts

@@ -1,4 +1,5 @@
-import { WorkflowEngine } from "../workflows/engine.js";
+import { compositionMetadata } from "../workflows/composition.js";
+import { WorkflowEngine, workflowIdentityMismatch } from "../workflows/engine.js";
 import type { WorkflowRunStore } from "../workflows/store.js";
 import type {
   WorkflowDefinition,
@@ -7,6 +8,14 @@ import type {
   WorkflowSource,
 } from "../workflows/types.js";
 import type {
+  ControllerFollowUpResult,
+  ControllerQueueFollowUpRequest,
+  ControllerRemoveFollowUpRequest,
+  ControllerSettingsChangeRequest,
+  ControllerSettingsChangeResult,
+} from "./types.js";
+import type {
+  ControllerWorkflowControlRequest,
   ControllerWorkflowScheduler,
   WorkflowSchedulerRequest,
   WorkflowSchedulerResult,
@@ -96,6 +105,99 @@ export class WorkflowEngineScheduler implements ControllerWorkflowScheduler {
     return { state: "running", runId };
   }
 
+  async changeSettings(
+    request: ControllerWorkflowControlRequest<ControllerSettingsChangeRequest>,
+    signal: AbortSignal,
+  ): Promise<ControllerSettingsChangeResult> {
+    signal.throwIfAborted();
+    const bundle = this.options.store.readRun(request.runId);
+    if (bundle === null) throw new Error(`Workflow run not found: ${request.runId}`);
+    const resolved = await this.options.resolveWorkflow(bundle.state.workflowName);
+    signal.throwIfAborted();
+    if (workflowIdentityMismatch(bundle.state, resolved.workflow, resolved.workflowSource)) {
+      throw new Error(`Workflow source changed since run ${request.runId} started`);
+    }
+    const scopes = this.options.store.listSettingsScopes(request.runId);
+    const scopeId = request.scopeId ?? (scopes.length === 1 ? scopes[0]?.scopeId : undefined);
+    if (scopeId === undefined) {
+      throw new Error("Controller settings changes require scopeId when several scopes exist");
+    }
+    const scope = this.options.store.getSettingsScope(scopeId);
+    if (scope === undefined || scope.activeRunId !== request.runId) {
+      throw new Error(`Workflow settings scope not found: ${scopeId}`);
+    }
+    const definition =
+      scope.mountPath === ""
+        ? resolved.workflow.settings
+        : compositionMetadata(resolved.workflow)?.scopes[scope.mountPath]?.settings;
+    if (definition === undefined) {
+      throw new Error(`Workflow scope ${scopeId} does not declare editable settings`);
+    }
+    const result = await this.options.store.changeSettings(definition, {
+      runId: request.runId,
+      scopeId,
+      requestId: request.actorRequestKey,
+      ...(request.expectedChangeNumber !== undefined
+        ? { expectedChangeNumber: request.expectedChangeNumber }
+        : {}),
+      actor: { type: "controller", id: request.controllerResourceUid },
+      source: "controller-request",
+      patch: request.patch,
+    });
+    return {
+      runId: request.runId,
+      scopeId,
+      changeNumber: result.scope.changeNumber,
+      adopted: result.adopted,
+    };
+  }
+
+  async queueFollowUp(
+    request: ControllerWorkflowControlRequest<ControllerQueueFollowUpRequest>,
+    signal: AbortSignal,
+  ): Promise<ControllerFollowUpResult> {
+    signal.throwIfAborted();
+    const targetSessionId = this.options.store.originSessionId(request.runId);
+    if (targetSessionId === undefined) {
+      throw new Error("Controller follow-up requires a workflow run with an origin Pi session");
+    }
+    const result = this.options.store.queueFollowUp({
+      runId: request.runId,
+      requestId: request.actorRequestKey,
+      targetSessionId,
+      actor: { type: "controller", id: request.controllerResourceUid },
+      source: "controller-request",
+      prompt: request.prompt,
+    });
+    return {
+      runId: request.runId,
+      followUpId: result.followUp.followUpId,
+      order: result.followUp.order,
+      state: result.followUp.state,
+      adopted: result.adopted,
+    };
+  }
+
+  async removeFollowUp(
+    request: ControllerWorkflowControlRequest<ControllerRemoveFollowUpRequest>,
+    signal: AbortSignal,
+  ): Promise<ControllerFollowUpResult> {
+    signal.throwIfAborted();
+    const result = this.options.store.removeFollowUp({
+      runId: request.runId,
+      followUpId: request.followUpId,
+      actor: { type: "controller", id: request.controllerResourceUid },
+      source: "controller-request",
+    });
+    return {
+      runId: request.runId,
+      followUpId: result.followUpId,
+      order: result.order,
+      state: result.state,
+      adopted: false,
+    };
+  }
+
   async waitForIdle(): Promise<void> {
     await Promise.all([...this.active.values()].map((entry) => entry.promise));
   }

package/src/controllers/workflows.ts

@@ -5,8 +5,13 @@ import type {
   ChildWorkflowRecord,
   ChildWorkflowRequest,
   ChildWorkflowState,
+  ControllerFollowUpResult,
   ControllerQueueClaim,
+  ControllerQueueFollowUpRequest,
+  ControllerRemoveFollowUpRequest,
   ControllerResource,
+  ControllerSettingsChangeRequest,
+  ControllerSettingsChangeResult,
   ControllerWorkflows,
 } from "./types.js";
 
@@ -24,12 +29,36 @@ export type WorkflowSchedulerResult = {
   error?: string;
 };
 
+export type ControllerWorkflowControlRequest<TRequest> = TRequest & {
+  controllerResourceUid: string;
+  actorRequestKey: string;
+};
+
 export interface ControllerWorkflowScheduler {
   ensure(
     request: WorkflowSchedulerRequest,
     signal: AbortSignal,
     onComplete: (result: WorkflowSchedulerResult) => void,
   ): Promise<WorkflowSchedulerResult>;
+  changeSettings?(
+    request: ControllerWorkflowControlRequest<ControllerSettingsChangeRequest>,
+    signal: AbortSignal,
+  ): Promise<ControllerSettingsChangeResult>;
+  queueFollowUp?(
+    request: ControllerWorkflowControlRequest<ControllerQueueFollowUpRequest>,
+    signal: AbortSignal,
+  ): Promise<ControllerFollowUpResult>;
+  removeFollowUp?(
+    request: ControllerWorkflowControlRequest<ControllerRemoveFollowUpRequest>,
+    signal: AbortSignal,
+  ): Promise<ControllerFollowUpResult>;
+}
+
+function controllerRequestKey(resource: ControllerResource, requestKey: string): string {
+  if (requestKey.trim().length === 0) {
+    throw new Error("Controller workflow requestKey must not be empty");
+  }
+  return `controller:${resource.metadata.uid}:${requestKey}`;
 }
 
 export class ControllerWorkflowCoordinator {
@@ -45,6 +74,45 @@ export class ControllerWorkflowCoordinator {
   ): ControllerWorkflows {
     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");
+        }
+        return await this.scheduler.changeSettings(
+          {
+            ...request,
+            controllerResourceUid: resource.metadata.uid,
+            actorRequestKey: controllerRequestKey(resource, request.requestKey),
+          },
+          signal,
+        );
+      },
+      queueFollowUp: async (request) => {
+        if (this.scheduler?.queueFollowUp === undefined) {
+          throw new Error("This controller host does not support workflow follow-ups");
+        }
+        return await this.scheduler.queueFollowUp(
+          {
+            ...request,
+            controllerResourceUid: resource.metadata.uid,
+            actorRequestKey: controllerRequestKey(resource, request.requestKey),
+          },
+          signal,
+        );
+      },
+      removeFollowUp: async (request) => {
+        if (this.scheduler?.removeFollowUp === undefined) {
+          throw new Error("This controller host does not support workflow follow-ups");
+        }
+        return await this.scheduler.removeFollowUp(
+          {
+            ...request,
+            controllerResourceUid: resource.metadata.uid,
+            actorRequestKey: controllerRequestKey(resource, request.requestKey),
+          },
+          signal,
+        );
+      },
     };
   }
 

package/src/extension/controller-host.ts

@@ -4,6 +4,7 @@ import {
   loadDiscoveredControllers,
   type AnyControllerDefinition,
   type ControllerResource,
+  type ControllerWorkflowScheduler,
   type WorkflowSchedulerRequest,
   type WorkflowSchedulerResult,
 } from "../controllers/index.js";
@@ -80,6 +81,10 @@ export class PiControllerHost {
   static async create(options: {
     cwd: string;
     startChild: PiChildWorkflowStarter;
+    workflowControls?: Pick<
+      ControllerWorkflowScheduler,
+      "changeSettings" | "queueFollowUp" | "removeFollowUp"
+    >;
   }): Promise<PiControllerHost | undefined> {
     const definitions = await loadDiscoveredControllers({ cwd: options.cwd });
     if (definitions.length === 0) {
@@ -89,7 +94,7 @@ export class PiControllerHost {
     const manager = new ControllerManager({
       store,
       controllers: definitions,
-      workflowScheduler: { ensure: options.startChild },
+      workflowScheduler: { ensure: options.startChild, ...options.workflowControls },
     });
     return new PiControllerHost(definitions, store, manager);
   }

package/src/extension/decision-channels.ts

@@ -28,6 +28,7 @@ const TELEGRAM_TEXT_LIMIT = 4_096;
 const PI_PRESENTATION_WINDOW_LINES = 18;
 const DEFAULT_API_BASE = "https://api.telegram.org";
 const LEASE_TTL_MS = 60_000;
+const LEASE_RENEW_WINDOW_MS = 20_000;
 const LEASE_RETRY_MS = 5_000;
 const POLL_BACKOFF_MS = 1_000;
 const MAX_SETTLEMENT_ATTEMPTS = 3;
@@ -428,6 +429,21 @@ class TelegramProjection {
   }
 
   acquire(now = Date.now()): boolean {
+    const observed = this.lease();
+    const observedToken = tokenHash(this.token);
+    const ownedByThis =
+      observed.ownerId === this.owner &&
+      observed.tokenHash !== null &&
+      observed.tokenHash.equals(observedToken) &&
+      observed.expiresAt !== null &&
+      observed.expiresAt > now;
+    if (ownedByThis) {
+      this.generation = observed.generation;
+      return true;
+    }
+    if (observed.ownerId !== null && observed.expiresAt !== null && observed.expiresAt > now) {
+      return false;
+    }
     return this.state.transaction(() => {
       const lease = this.lease();
       if (
@@ -438,7 +454,11 @@ class TelegramProjection {
       ) {
         return false;
       }
-      const generation = lease.ownerId === this.owner ? lease.generation : lease.generation + 1;
+      const sameToken =
+        lease.ownerId === this.owner &&
+        lease.tokenHash !== null &&
+        lease.tokenHash.equals(observedToken);
+      const generation = sameToken ? lease.generation : lease.generation + 1;
       const result = this.state.connection
         .prepare(
           `UPDATE leases
@@ -449,7 +469,7 @@ class TelegramProjection {
         .run(
           generation,
           this.owner,
-          tokenHash(this.token),
+          observedToken,
           now,
           now,
           now + LEASE_TTL_MS,
@@ -465,6 +485,18 @@ class TelegramProjection {
   }
 
   renew(now = Date.now()): boolean {
+    const lease = this.lease();
+    if (
+      lease.ownerId !== this.owner ||
+      lease.generation !== this.generation ||
+      lease.tokenHash === null ||
+      !lease.tokenHash.equals(tokenHash(this.token)) ||
+      lease.expiresAt === null ||
+      lease.expiresAt <= now
+    ) {
+      return false;
+    }
+    if (lease.expiresAt - now > LEASE_RENEW_WINDOW_MS) return true;
     return (
       this.state.connection
         .prepare(
@@ -1222,11 +1254,11 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
 
   private async poll(signal: AbortSignal): Promise<void> {
     while (this.running && !signal.aborted) {
-      if (!this.projection.acquire()) {
-        await wait(LEASE_RETRY_MS, signal);
-        continue;
-      }
       try {
+        if (!this.projection.acquire()) {
+          await wait(leaseRetryDelay(), signal);
+          continue;
+        }
         await this.deliverPendingRequests();
         const result = await this.call(
           "getUpdates",
@@ -1246,7 +1278,11 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
         if (!this.projection.renew()) this.projection.release();
       } catch {
         if (signal.aborted) return;
-        await wait(POLL_BACKOFF_MS, signal);
+        try {
+          await wait(POLL_BACKOFF_MS, signal);
+        } catch {
+          if (signal.aborted) return;
+        }
       }
     }
   }
@@ -1773,6 +1809,10 @@ async function writePrivateJson(filePath: string, value: unknown): Promise<void>
   await fsp.chmod(filePath, 0o600);
 }
 
+function leaseRetryDelay(): number {
+  return LEASE_RETRY_MS + Math.floor(Math.random() * 1_000);
+}
+
 async function wait(milliseconds: number, signal: AbortSignal): Promise<void> {
   await new Promise<void>((resolve) => {
     const timer = setTimeout(resolve, milliseconds);

package/src/extension/follow-up-coordinator.ts

@@ -0,0 +1,151 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { LeaseClaim } from "../state/mutation.js";
+import type { WorkflowFollowUpRecord } from "../workflows/settings.js";
+import { WorkflowRunStore } from "../workflows/store.js";
+
+const FOLLOW_UP_ID_PREFIX = "pi-workflows-follow-up:";
+
+export type FollowUpDelivery = {
+  followUp: WorkflowFollowUpRecord;
+  claim: LeaseClaim;
+};
+
+export class FollowUpCoordinator {
+  private pending: FollowUpDelivery | undefined;
+  private synchronizing = false;
+
+  constructor(
+    private readonly store: WorkflowRunStore,
+    private readonly ownerId: string,
+    private readonly sendUserMessage: (text: string, options?: { deliverAs?: "followUp" }) => void,
+  ) {}
+
+  async synchronize(ctx: ExtensionContext, workflowActive: boolean): Promise<void> {
+    if (this.synchronizing) return;
+    this.synchronizing = true;
+    try {
+      const sessionId = ctx.sessionManager.getSessionId();
+      if (this.pending !== undefined) {
+        const entryId = findFollowUpEntryId(
+          ctx.sessionManager.getBranch(),
+          this.pending.followUp.followUpId,
+        );
+        if (entryId === undefined) return;
+        this.store.markFollowUpSent(this.pending.followUp.followUpId, this.pending.claim, entryId);
+        this.releaseClaim(this.pending.claim);
+        this.pending = undefined;
+      }
+      if (!ctx.isIdle() || workflowActive) return;
+      const claimed = this.store.claimNextFollowUp(sessionId, this.ownerId);
+      if (claimed === undefined) return;
+      const entryId = findFollowUpEntryId(
+        ctx.sessionManager.getBranch(),
+        claimed.followUp.followUpId,
+      );
+      if (entryId !== undefined) {
+        this.store.markFollowUpSent(claimed.followUp.followUpId, claimed.claim, entryId);
+        this.releaseClaim(claimed.claim);
+        return;
+      }
+      this.pending = claimed;
+      try {
+        this.sendUserMessage(followUpMessageText(claimed.followUp));
+      } catch (error) {
+        this.pending = undefined;
+        this.releaseClaim(claimed.claim);
+        throw error;
+      }
+    } finally {
+      this.synchronizing = false;
+    }
+  }
+
+  clear(): void {
+    this.pending = undefined;
+  }
+
+  private releaseClaim(claim: LeaseClaim): void {
+    try {
+      this.store.releaseFollowUpClaim(claim);
+    } catch {
+      // The lease can expire or move after delivery evidence is saved.
+    }
+  }
+}
+
+export function followUpMessageText(
+  followUp: Pick<WorkflowFollowUpRecord, "followUpId" | "prompt">,
+): string {
+  return `${followUp.prompt}\n\n<!-- ${FOLLOW_UP_ID_PREFIX}${followUp.followUpId} -->`;
+}
+
+export function findFollowUpEntryId(
+  entries: readonly unknown[],
+  followUpId: string,
+): string | undefined {
+  const idText = `${FOLLOW_UP_ID_PREFIX}${followUpId}`;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (!isRecord(entry) || entry.type !== "message" || typeof entry.id !== "string") continue;
+    const message = entry.message;
+    if (!isRecord(message) || message.role !== "user") continue;
+    if (messageText(message.content).includes(idText)) return entry.id;
+  }
+  return undefined;
+}
+
+export function findSettledPresentationEntries(
+  entries: readonly unknown[],
+  runId: string,
+): { presentationEntryId: string; assistantEntryId: string } | undefined {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (!isPresentationEntry(entry, runId)) continue;
+    for (let childIndex = index + 1; childIndex < entries.length; childIndex += 1) {
+      const child = entries[childIndex];
+      if (!isRecord(child) || child.type !== "message" || typeof child.id !== "string") continue;
+      const message = child.message;
+      if (!isRecord(message)) continue;
+      if (message.role === "user") break;
+      if (
+        message.role === "assistant" &&
+        (message.stopReason === "stop" || message.stopReason === "length")
+      ) {
+        return { presentationEntryId: entry.id, assistantEntryId: child.id };
+      }
+    }
+  }
+  return undefined;
+}
+
+function isPresentationEntry(value: unknown, runId: string): value is { id: string } {
+  if (!isRecord(value) || typeof value.id !== "string") return false;
+  if (value.type === "custom_message") {
+    return (
+      value.customType === "pi-workflows-presentation" &&
+      isRecord(value.details) &&
+      value.details.runId === runId
+    );
+  }
+  if (value.type !== "message" || !isRecord(value.message)) return false;
+  return (
+    value.message.role === "custom" &&
+    value.message.customType === "pi-workflows-presentation" &&
+    isRecord(value.message.details) &&
+    value.message.details.runId === runId
+  );
+}
+
+function messageText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value
+    .flatMap((item) =>
+      isRecord(item) && item.type === "text" && typeof item.text === "string" ? [item.text] : [],
+    )
+    .join("\n");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}