@osolmaz/pi-workflows 0.13.2 → 0.13.3

package/examples/workflows/live-settings.workflow.ts

@@ -0,0 +1,93 @@
+import {
+  agent,
+  allowSettingsPath,
+  compute,
+  defineWorkflow,
+  settingsRoute,
+  workflowSettings,
+} from "@osolmaz/pi-workflows";
+
+type Settings = {
+  instructions: string[];
+  route: "normal" | "careful";
+  variables: Record<string, unknown>;
+};
+
+function parseSettings(value: unknown): Settings {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("settings must be an object");
+  }
+  const settings = value as Partial<Settings>;
+  if (
+    !Array.isArray(settings.instructions) ||
+    !settings.instructions.every((item) => typeof item === "string") ||
+    (settings.route !== "normal" && settings.route !== "careful") ||
+    settings.variables === null ||
+    typeof settings.variables !== "object" ||
+    Array.isArray(settings.variables)
+  ) {
+    throw new Error("settings are invalid");
+  }
+  return {
+    instructions: [...settings.instructions],
+    route: settings.route,
+    variables: { ...settings.variables },
+  };
+}
+
+export default defineWorkflow({
+  name: "live-settings",
+  settings: workflowSettings<Settings>({
+    initial: { instructions: [], route: "normal", variables: {} },
+    parse: parseSettings,
+    description: "Instructions, variables, and the future route for this example.",
+    paths: [
+      allowSettingsPath("/instructions", {
+        read: ["session", "human"],
+        add: ["session", "human"],
+        remove: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+      allowSettingsPath("/route", {
+        read: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+      allowSettingsPath("/variables", {
+        read: ["session", "human"],
+        add: ["session", "human"],
+        remove: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+    ],
+  }),
+  startAt: "prepare",
+  nodes: {
+    prepare: agent({
+      prompt: ({ settings }) =>
+        [
+          "Prepare the requested work.",
+          `Current instructions and variables: ${JSON.stringify(settings)}`,
+          "The user can change future settings or queue several post-completion prompts while this step runs.",
+        ].join("\n"),
+      expectedOutput: `{ "prepared": "summary" }`,
+    }),
+    choose: settingsRoute({
+      run: ({ settings }) => ({ route: (settings as Settings).route }),
+    }),
+    normal: compute({
+      run: ({ settings }) => ({ mode: "normal", settings }),
+    }),
+    careful: compute({
+      run: ({ settings }) => ({ mode: "careful", settings }),
+    }),
+  },
+  edges: [
+    { from: "prepare", to: "choose" },
+    {
+      from: "choose",
+      switch: { on: "$.route", cases: { normal: "normal", careful: "careful" } },
+    },
+  ],
+  presentationPrompt:
+    "Explain which route and settings were used. Any queued follow-up prompts run only after this response settles.",
+});

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.13.2"
+version = "0.13.3"
 min_herdr_version = "0.7.0"
 description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/src/builtins/autoimplement.workflow.ts

@@ -13,6 +13,7 @@ import {
   includedResult,
 } from "../workflows/definition.js";
 import { digest } from "../workflows/human-decision.js";
+import { allowSettingsPath, workflowSettings } from "../workflows/settings.js";
 import type { WorkflowActionContext, WorkflowNodeContext } from "../workflows/types.js";
 import autodocWorkflow, { type AutodocInput } from "./autodoc.workflow.js";
 import {
@@ -40,6 +41,11 @@ import workspacePreparationWorkflow, {
   type WorkspacePreparationInput,
 } from "./workspace-preparation.workflow.js";
 
+export type AutoimplementSettings = {
+  merge: boolean;
+  addedInstructions: string[];
+};
+
 export type AutoimplementInput = {
   task: string;
   plan?: unknown;
@@ -577,6 +583,27 @@ function parseInput(value: unknown): AutoimplementInput {
   };
 }
 
+function parseAutoimplementSettings(value: unknown): AutoimplementSettings {
+  const settings = requireRecord(value, "autoimplement settings");
+  if (typeof settings.merge !== "boolean") {
+    throw new Error("autoimplement settings merge must be a boolean");
+  }
+  if (
+    !Array.isArray(settings.addedInstructions) ||
+    settings.addedInstructions.some((item) => typeof item !== "string")
+  ) {
+    throw new Error("autoimplement settings addedInstructions must be an array of strings");
+  }
+  return {
+    merge: settings.merge,
+    addedInstructions: [...settings.addedInstructions] as string[],
+  };
+}
+
+function autoimplementSettings(context: WorkflowNodeContext): AutoimplementSettings {
+  return parseAutoimplementSettings(context.settings);
+}
+
 function parseExistingPlan(value: unknown): ExistingPlanDiscovery {
   const result = requireRecord(value, "existing plan discovery");
   if (result.route !== "found" && result.route !== "blocked") {
@@ -790,7 +817,7 @@ function createBlockerClaim(context: WorkflowNodeContext): BlockerClaim {
     unrelatedFailures: Array.isArray(result.unrelatedFailures) ? result.unrelatedFailures : [],
     recoveryAttempts: Array.isArray(result.repairAttempts) ? result.repairAttempts : [],
     alternativesChecked: [],
-    authorityFact: `scope=${(context.input as AutoimplementInput).scope ?? "unspecified"}; merge=${(context.input as AutoimplementInput).merge === true}`,
+    authorityFact: `scope=${(context.input as AutoimplementInput).scope ?? "unspecified"}; merge=${autoimplementSettings(context).merge}`,
   };
 }
 
@@ -919,8 +946,8 @@ function parseDeliveryResult(
   if (result.status !== "completed" && result.status !== "blocked") {
     throw new Error("delivery status must be completed or blocked");
   }
-  const request = context.input as AutoimplementInput;
-  if (request.merge !== true && result.merged === true) {
+  const settings = autoimplementSettings(context);
+  if (settings.merge !== true && result.merged === true) {
     throw new Error("delivery cannot merge without explicit merge: true");
   }
   if (result.status === "blocked") return result;
@@ -960,7 +987,7 @@ function parseDeliveryResult(
     }
     actual.set(repository.repository, repository);
   }
-  const mergeExpected = request.merge === true;
+  const mergeExpected = settings.merge === true;
   for (const expected of published) {
     const repository = actual.get(path.resolve(expected.repository));
     if (repository === undefined || repository.pr !== expected.pr) {
@@ -1298,6 +1325,28 @@ export const autoimplementWorkflow = defineWorkflow({
   contractId: "pi-workflows.autoimplement.v1",
   name: "autoimplement",
   input: parseInput,
+  settings: workflowSettings<AutoimplementSettings, AutoimplementInput>({
+    initial: (input) => ({ merge: input.merge === true, addedInstructions: [] }),
+    parse: parseAutoimplementSettings,
+    description: "Future merge behavior and instructions added during this run.",
+    paths: [
+      allowSettingsPath("/merge", {
+        read: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+      allowSettingsPath("/addedInstructions", {
+        read: ["session", "human"],
+        add: ["session", "human"],
+        remove: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+    ],
+    validateChange: ({ before, after, actor }) => {
+      if (actor.type === "session" && before.merge === false && after.merge === true) {
+        throw new Error("A model workflow step cannot grant merge authority");
+      }
+    },
+  }),
   title: ({ input }) => `autoimplement: ${input.task.slice(0, 60)}`,
   presentationPrompt:
     "Summarize what was implemented, the review rounds by severity, the CI result, the PR or merge result, and any remaining limitation. Include exact validation commands.",
@@ -1616,7 +1665,7 @@ export const autoimplementWorkflow = defineWorkflow({
           `Current result and claimed blocker: ${JSON.stringify(latestBlockerClaim(context))}`,
           `Authorized scope: ${request.scope ?? request.repository ?? "the current repository and task"}`,
           `Constraints and authority: ${JSON.stringify(request.constraints ?? [])}`,
-          `Merge authorized: ${request.merge === true}`,
+          `Merge currently allowed: ${autoimplementSettings(context).merge === true}`,
           `Previous blocker challenges: ${JSON.stringify(blockerChallenges(context))}`,
           `Recent workflow attempts: ${JSON.stringify(recentWorkflowAttempts(context))}`,
         ].join("\n");
@@ -1925,10 +1974,9 @@ export const autoimplementWorkflow = defineWorkflow({
       timeoutMs: 30 * 60_000,
       statusDetail: "finalizing PRs",
       prompt: (context) => {
-        const request = context.input as AutoimplementInput;
         return [
-          request.merge === false
-            ? "Leave every verified PR ready without merging because input disabled merge."
+          autoimplementSettings(context).merge === false
+            ? "Leave every verified PR ready without merging because current workflow settings disable merge."
             : "Handle verified PRs one at a time and merge each unless repository policy or explicit user instructions prohibit it.",
           "Before each mutation, inspect the current PR head, merge state, and existing final report. Do not merge an already merged expected head or post a duplicate report.",
           "Use each repository's required merge method.",

package/src/builtins/catalog.ts

@@ -11,7 +11,7 @@ export const builtinWorkflowCatalog = new BuiltinWorkflowCatalog([
   { id: "plain-summary", revision: "3", definition: plainSummaryWorkflow },
   { id: "autoplan", revision: "5", definition: autoplanWorkflow },
   { id: "autodoc", revision: "2", definition: autodocWorkflow },
-  { id: "autoimplement", revision: "10", definition: autoimplementWorkflow },
+  { id: "autoimplement", revision: "11", definition: autoimplementWorkflow },
   { id: "plan-approval", revision: "4", definition: planApprovalWorkflow },
   { id: "sanity-check", revision: "6", definition: sanityCheckWorkflow },
   {

package/src/controllers/index.ts

@@ -49,6 +49,7 @@ export {
 } from "./workflow-engine-scheduler.js";
 export {
   ControllerWorkflowCoordinator,
+  type ControllerWorkflowControlRequest,
   type ControllerWorkflowScheduler,
   type WorkflowSchedulerRequest,
   type WorkflowSchedulerResult,
@@ -64,6 +65,11 @@ export type {
   ControllerConditionStatus,
   ControllerDefinition,
   ControllerEffects,
+  ControllerFollowUpResult,
+  ControllerQueueFollowUpRequest,
+  ControllerRemoveFollowUpRequest,
+  ControllerSettingsChangeRequest,
+  ControllerSettingsChangeResult,
   ControllerEvent,
   ControllerQueueClaim,
   ControllerResource,

package/src/controllers/sqlite.ts

@@ -155,9 +155,8 @@ type RunRow = {
   workflowName: string;
   workflowRef: string;
   runStatus: string;
-  workflowSourceHash: Buffer;
-  workflowSourcesHash: Buffer | null;
   definitionDigest: Buffer;
+  definitionHash: Buffer;
   inputHash: Buffer;
   launchOptionsHash: Buffer;
   status: WorkflowRunLaunchStatus;
@@ -176,6 +175,12 @@ type RunRow = {
   ownerId: string | null;
   claimExpiresAt: number | null;
 };
+type RunSourceIdentityRow = {
+  mountPath: string;
+  sourceType: "builtin" | "file";
+  sourceRef: string;
+  sourceRevision: string;
+};
 
 type EffectRow = {
   effectId: string;
@@ -1049,9 +1054,6 @@ export class SqliteControllerStore implements ControllerStore {
       const resourceId = resourceIdFor("run", options.runId);
       const definitionHash = this.state.putJson(options.definitionSnapshot, now);
       const queuedSource = queuedWorkflowSource(options.workflowSource);
-      const sourceHash = this.state.putJson(queuedSource.root, now);
-      const mountedSourcesHash =
-        queuedSource.mounted.length === 0 ? null : this.state.putJson(queuedSource.mounted, now);
       const inputHash = this.state.putJson(options.input ?? null, now);
       const launchHash = this.state.putJson(options.launchOptions ?? {}, now);
       this.state.connection
@@ -1071,15 +1073,13 @@ export class SqliteControllerStore implements ControllerStore {
       this.state.connection
         .prepare("INSERT INTO leases(resource_id, generation) VALUES (?, 0)")
         .run(resourceId);
-      const source = sourceParts(options.workflowSourceRef, options.definitionDigest);
       this.state.connection
         .prepare(
           `INSERT INTO runs(
              run_id, resource_id, project_id, parent_run_id, definition_digest,
-             workflow_ref, workflow_source_hash, launch_options_hash,
-             source_type, source_ref, source_revision, status, paused,
-             input_hash, workflow_sources_hash, created_at, updated_at
-           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'queued', 0, ?, ?, ?, ?)`,
+             workflow_ref, launch_options_hash, status, paused,
+             input_hash, created_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, 'queued', 0, ?, ?, ?)`,
         )
         .run(
           options.runId,
@@ -1088,16 +1088,12 @@ export class SqliteControllerStore implements ControllerStore {
           options.parentRunId ?? null,
           definitionDigest,
           options.workflowSourceRef,
-          sourceHash,
           launchHash,
-          source.type,
-          source.ref,
-          source.revision,
           inputHash,
-          mountedSourcesHash,
           now,
           now,
         );
+      insertQueuedRunSources(this.state, options.runId, queuedSource);
       this.state.connection
         .prepare(
           `INSERT INTO run_bindings(run_id, origin_session_id, execution_mode, created_at)
@@ -2238,11 +2234,7 @@ export class SqliteControllerStore implements ControllerStore {
       runId: row.runId,
       workflowName: row.workflowName,
       workflowSourceRef: row.workflowRef,
-      workflowSource: {
-        root: this.state.readJson(row.workflowSourceHash),
-        mounted:
-          row.workflowSourcesHash === null ? [] : this.state.readJson(row.workflowSourcesHash),
-      },
+      workflowSource: readQueuedRunSources(this.state, row),
       initialized: row.runStatus !== "queued",
       definitionDigest: `sha256:${row.definitionDigest.toString("hex")}`,
       input: this.state.readJson(row.inputHash),
@@ -2469,8 +2461,6 @@ export class SqliteControllerStore implements ControllerStore {
         .prepare(
           `UPDATE runs
            SET status = ?, paused = 0, status_detail = NULL, error_hash = ?,
-               current_node = NULL, current_attempt_id = NULL,
-               current_node_started_at = NULL, waiting_on = NULL,
                updated_at = ?, finished_at = ?
            WHERE run_id = ?`,
         )
@@ -2776,9 +2766,8 @@ function workflowSelect(clause: string): string {
 function workflowRunSelect(clause: string): string {
   return `SELECT r.run_id AS runId, r.resource_id AS resourceId,
     d.workflow_name AS workflowName, r.workflow_ref AS workflowRef, r.status AS runStatus,
-    r.workflow_source_hash AS workflowSourceHash,
-    r.workflow_sources_hash AS workflowSourcesHash,
-    r.definition_digest AS definitionDigest, r.input_hash AS inputHash,
+    r.definition_digest AS definitionDigest, d.definition_hash AS definitionHash,
+    r.input_hash AS inputHash,
     r.launch_options_hash AS launchOptionsHash,
     q.status, q.available_at AS availableAt, q.affinity_runner_id AS affinityRunnerId,
     q.consecutive_errors AS consecutiveErrors, q.error_code AS errorCode,
@@ -2886,6 +2875,9 @@ function isLeaseRow(value: unknown): value is LeaseRow {
 function isRunRow(value: unknown): value is RunRow {
   return isRecord(value);
 }
+function isRunSourceIdentityRow(value: unknown): value is RunSourceIdentityRow {
+  return isRecord(value);
+}
 function isEffectRow(value: unknown): value is EffectRow {
   return isRecord(value);
 }
@@ -2958,24 +2950,126 @@ function digestBuffer(value: string): Buffer {
   if (!/^[a-f0-9]{64}$/i.test(hex)) throw new Error("Expected a SHA-256 digest");
   return Buffer.from(hex, "hex");
 }
-function queuedWorkflowSource(value: unknown): { root: unknown; mounted: unknown[] } {
-  if (isRecord(value) && (value.kind === "builtin" || value.kind === "file")) {
+type QueuedSource = {
+  root:
+    | { kind: "builtin"; id: string; revision: string }
+    | { kind: "file"; path: string; hash: string };
+  mounted: Array<{
+    mountPath: string[];
+    workflowName: string;
+    source:
+      | { kind: "builtin"; id: string; revision: string }
+      | { kind: "file"; path: string; hash: string };
+  }>;
+};
+
+function queuedWorkflowSource(value: unknown): QueuedSource {
+  if (isWorkflowSource(value)) {
     return { root: value, mounted: [] };
   }
-  if (isRecord(value) && isRecord(value.root) && Array.isArray(value.mounted)) {
+  if (
+    isRecord(value) &&
+    isWorkflowSource(value.root) &&
+    Array.isArray(value.mounted) &&
+    value.mounted.every(isMountedWorkflowSource)
+  ) {
     return { root: value.root, mounted: value.mounted };
   }
   throw new Error("Stored workflow source identity is invalid");
 }
 
-function sourceParts(
-  ref: string,
-  revision: string,
-): { type: "builtin" | "file"; ref: string; revision: string } {
-  return ref.startsWith("builtin:")
-    ? { type: "builtin", ref: ref.slice(8), revision }
-    : { type: "file", ref, revision };
+function isWorkflowSource(value: unknown): value is QueuedSource["root"] {
+  return (
+    isRecord(value) &&
+    ((value.kind === "builtin" &&
+      typeof value.id === "string" &&
+      typeof value.revision === "string") ||
+      (value.kind === "file" && typeof value.path === "string" && typeof value.hash === "string"))
+  );
+}
+
+function isMountedWorkflowSource(value: unknown): value is QueuedSource["mounted"][number] {
+  return (
+    isRecord(value) &&
+    Array.isArray(value.mountPath) &&
+    value.mountPath.every((part) => typeof part === "string") &&
+    typeof value.workflowName === "string" &&
+    isWorkflowSource(value.source)
+  );
+}
+
+function insertQueuedRunSources(state: StateDatabase, runId: string, value: QueuedSource): void {
+  const insert = state.connection.prepare(
+    `INSERT INTO run_sources(run_id, mount_path, source_type, source_ref, source_revision)
+     VALUES (?, ?, ?, ?, ?)`,
+  );
+  const root = queuedSourceParts(value.root);
+  insert.run(runId, "", root.type, root.ref, root.revision);
+  for (const mounted of value.mounted) {
+    const source = queuedSourceParts(mounted.source);
+    insert.run(runId, mounted.mountPath.join("/"), source.type, source.ref, source.revision);
+  }
+}
+
+function queuedSourceParts(source: QueuedSource["root"]): {
+  type: "builtin" | "file";
+  ref: string;
+  revision: string;
+} {
+  return source.kind === "builtin"
+    ? { type: "builtin", ref: source.id, revision: source.revision }
+    : { type: "file", ref: source.path, revision: source.hash };
+}
+
+function readQueuedRunSources(state: StateDatabase, run: RunRow): QueuedSource {
+  const rows = state.connection
+    .prepare(
+      `SELECT mount_path AS mountPath, source_type AS sourceType,
+              source_ref AS sourceRef, source_revision AS sourceRevision
+       FROM run_sources WHERE run_id = ? ORDER BY mount_path`,
+    )
+    .all(run.runId)
+    .filter(isRunSourceIdentityRow);
+  const rootRow = rows.find((row) => row.mountPath === "");
+  if (rootRow === undefined) throw new Error(`Workflow run source is missing: ${run.runId}`);
+  const snapshot = state.readJson(run.definitionHash);
+  const mounts =
+    isRecord(snapshot) &&
+    isRecord(snapshot.composition) &&
+    Array.isArray(snapshot.composition.mounts)
+      ? snapshot.composition.mounts
+      : [];
+  const names = new Map(
+    mounts.flatMap((mount) => {
+      if (
+        !isRecord(mount) ||
+        !Array.isArray(mount.mountPath) ||
+        !mount.mountPath.every((part) => typeof part === "string") ||
+        typeof mount.workflowName !== "string"
+      ) {
+        return [];
+      }
+      return [[mount.mountPath.join("/"), mount.workflowName] as const];
+    }),
+  );
+  return {
+    root: rowToSource(rootRow),
+    mounted: rows
+      .filter((row) => row.mountPath !== "")
+      .map((row) => ({
+        mountPath: row.mountPath.split("/"),
+        workflowName: names.get(row.mountPath) ?? row.mountPath,
+        source: rowToSource(row),
+      })),
+  };
 }
+
+function rowToSource(row: RunSourceIdentityRow): QueuedSource["root"] {
+  return row.sourceType === "builtin"
+    ? { kind: "builtin", id: row.sourceRef, revision: row.sourceRevision }
+    : { kind: "file", path: row.sourceRef, hash: row.sourceRevision };
+}
+
 function effectStatus(value: EffectRecord["state"]): string {
   return value === "indeterminate" ? "ambiguous" : value;
 }

package/src/controllers/types.ts

@@ -1,3 +1,5 @@
+import type { JsonPatch } from "../workflows/json-patch.js";
+
 export type MaybePromise<T> = T | Promise<T>;
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
@@ -131,8 +133,46 @@ export type ChildWorkflowRecord = ChildWorkflowReference & {
   error?: string;
 };
 
+export type ControllerSettingsChangeRequest = {
+  requestKey: string;
+  runId: string;
+  scopeId?: string;
+  expectedChangeNumber?: number;
+  patch: JsonPatch;
+};
+
+export type ControllerSettingsChangeResult = {
+  runId: string;
+  scopeId: string;
+  changeNumber: number;
+  adopted: boolean;
+};
+
+export type ControllerQueueFollowUpRequest = {
+  requestKey: string;
+  runId: string;
+  prompt: string;
+};
+
+export type ControllerFollowUpResult = {
+  runId: string;
+  followUpId: string;
+  order: number;
+  state: string;
+  adopted: boolean;
+};
+
+export type ControllerRemoveFollowUpRequest = {
+  requestKey: string;
+  runId: string;
+  followUpId: string;
+};
+
 export interface ControllerWorkflows {
   ensure(request: ChildWorkflowRequest): Promise<ChildWorkflowRecord>;
+  changeSettings(request: ControllerSettingsChangeRequest): Promise<ControllerSettingsChangeResult>;
+  queueFollowUp(request: ControllerQueueFollowUpRequest): Promise<ControllerFollowUpResult>;
+  removeFollowUp(request: ControllerRemoveFollowUpRequest): Promise<ControllerFollowUpResult>;
 }
 
 export type ReconcileContext<TStatus> = {