@osolmaz/pi-workflows 0.13.1 → 0.13.3

package/src/state/schema.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 export const STATE_APPLICATION_ID = 0x50495746;
 export const STATE_SCHEMA_NAME = "pi-workflows-state";
 export const STATE_SCHEMA_VERSION = 1;
-export const STATE_APP_VERSION = "0.12.1";
+export const STATE_APP_VERSION = "0.13.3";
 
 export const STATE_SCHEMA_SQL = String.raw`
 CREATE TABLE schema_meta (
@@ -34,7 +34,8 @@ CREATE TABLE blobs (
 CREATE TABLE resources (
   resource_id TEXT PRIMARY KEY,
   resource_type TEXT NOT NULL CHECK (resource_type IN (
-    'run', 'session', 'decision', 'controller', 'effect', 'channel', 'notification', 'turn_intent'
+    'run', 'session', 'decision', 'controller', 'effect', 'channel', 'notification', 'turn_intent',
+    'settings', 'follow_up_queue', 'follow_up'
   )),
   aggregate_key TEXT NOT NULL,
   revision INTEGER NOT NULL DEFAULT 0 CHECK (revision >= 0),
@@ -94,11 +95,7 @@ CREATE TABLE runs (
   parent_run_id TEXT REFERENCES runs(run_id),
   definition_digest BLOB NOT NULL REFERENCES workflow_definitions(definition_digest),
   workflow_ref TEXT NOT NULL,
-  workflow_source_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
   launch_options_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
-  source_type TEXT NOT NULL CHECK (source_type IN ('builtin', 'file')),
-  source_ref TEXT NOT NULL,
-  source_revision TEXT NOT NULL,
   title TEXT,
   status TEXT NOT NULL CHECK (status IN (
     'queued', 'running', 'waiting', 'completed', 'failed', 'timed_out', 'cancelled'
@@ -106,7 +103,7 @@ CREATE TABLE runs (
   paused INTEGER NOT NULL DEFAULT 0 CHECK (paused IN (0, 1)),
   status_detail TEXT,
   input_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
-  output_hash BLOB REFERENCES blobs(blob_hash),
+  final_output_hash BLOB REFERENCES blobs(blob_hash),
   error_hash BLOB REFERENCES blobs(blob_hash),
   created_at INTEGER NOT NULL,
   updated_at INTEGER NOT NULL,
@@ -118,6 +115,15 @@ CREATE INDEX runs_project_idx ON runs(project_id, created_at DESC);
 CREATE INDEX runs_status_idx ON runs(status, updated_at DESC);
 CREATE INDEX runs_parent_idx ON runs(parent_run_id);
 
+CREATE TABLE run_sources (
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  mount_path TEXT NOT NULL,
+  source_type TEXT NOT NULL CHECK (source_type IN ('builtin', 'file')),
+  source_ref TEXT NOT NULL,
+  source_revision TEXT NOT NULL,
+  PRIMARY KEY (run_id, mount_path)
+) STRICT;
+
 CREATE TABLE run_bindings (
   run_id TEXT PRIMARY KEY REFERENCES runs(run_id) ON DELETE CASCADE,
   origin_session_id TEXT NOT NULL,
@@ -127,6 +133,92 @@ CREATE TABLE run_bindings (
 
 CREATE INDEX run_bindings_session_idx ON run_bindings(origin_session_id, created_at DESC);
 
+CREATE TABLE workflow_settings (
+  scope_id TEXT PRIMARY KEY,
+  resource_id TEXT NOT NULL UNIQUE REFERENCES resources(resource_id) ON DELETE CASCADE,
+  origin_run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  active_run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  mount_path TEXT NOT NULL,
+  invocation INTEGER NOT NULL CHECK (invocation > 0),
+  initial_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  current_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE (origin_run_id, mount_path, invocation)
+) STRICT;
+
+CREATE INDEX workflow_settings_active_run_idx ON workflow_settings(active_run_id, mount_path, invocation);
+
+CREATE TABLE workflow_setting_changes (
+  change_id TEXT PRIMARY KEY,
+  scope_id TEXT NOT NULL REFERENCES workflow_settings(scope_id) ON DELETE CASCADE,
+  request_id TEXT NOT NULL,
+  change_number INTEGER NOT NULL CHECK (change_number > 0),
+  actor_type TEXT NOT NULL CHECK (actor_type IN (
+    'session', 'host', 'controller', 'channel', 'human', 'policy', 'control', 'system'
+  )),
+  actor_id TEXT,
+  source_type TEXT NOT NULL,
+  patch_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  before_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  after_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  accepted_at INTEGER NOT NULL,
+  UNIQUE (scope_id, request_id),
+  UNIQUE (scope_id, change_number)
+) STRICT;
+
+CREATE TABLE workflow_follow_up_queues (
+  run_id TEXT PRIMARY KEY REFERENCES runs(run_id) ON DELETE CASCADE,
+  resource_id TEXT NOT NULL UNIQUE REFERENCES resources(resource_id) ON DELETE CASCADE,
+  origin_session_id TEXT,
+  presentation_state TEXT NOT NULL DEFAULT 'none' CHECK (presentation_state IN (
+    'none', 'not-needed', 'pending', 'settled', 'unavailable'
+  )),
+  presentation_entry_id TEXT,
+  presentation_assistant_entry_id TEXT,
+  presentation_reason_hash BLOB REFERENCES blobs(blob_hash),
+  presentation_updated_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  CHECK (
+    (presentation_state IN ('none', 'not-needed', 'pending') AND presentation_assistant_entry_id IS NULL AND presentation_reason_hash IS NULL)
+    OR
+    (presentation_state = 'unavailable' AND presentation_assistant_entry_id IS NULL AND presentation_reason_hash IS NOT NULL)
+    OR
+    (presentation_state = 'settled' AND presentation_entry_id IS NOT NULL AND presentation_assistant_entry_id IS NOT NULL AND presentation_reason_hash IS NULL)
+  )
+) STRICT;
+
+CREATE TABLE workflow_follow_ups (
+  follow_up_id TEXT PRIMARY KEY,
+  resource_id TEXT NOT NULL UNIQUE REFERENCES resources(resource_id) ON DELETE CASCADE,
+  queue_resource_id TEXT NOT NULL REFERENCES resources(resource_id),
+  run_id TEXT NOT NULL REFERENCES workflow_follow_up_queues(run_id) ON DELETE CASCADE,
+  request_id TEXT NOT NULL,
+  order_number INTEGER NOT NULL CHECK (order_number > 0),
+  target_session_id TEXT NOT NULL,
+  actor_type TEXT NOT NULL CHECK (actor_type IN (
+    'session', 'host', 'controller', 'channel', 'human', 'policy', 'control', 'system'
+  )),
+  actor_id TEXT,
+  source_type TEXT NOT NULL,
+  prompt_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
+  status TEXT NOT NULL CHECK (status IN (
+    'queued', 'pending_presentation', 'ready', 'sent', 'removed', 'cancelled'
+  )),
+  session_entry_id TEXT,
+  reason_hash BLOB REFERENCES blobs(blob_hash),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  sent_at INTEGER,
+  UNIQUE (run_id, request_id),
+  UNIQUE (run_id, order_number),
+  CHECK ((status = 'sent') = (session_entry_id IS NOT NULL AND sent_at IS NOT NULL)),
+  CHECK ((status IN ('removed', 'cancelled')) = (reason_hash IS NOT NULL))
+) STRICT;
+
+CREATE INDEX workflow_follow_ups_delivery_idx ON workflow_follow_ups(target_session_id, status, order_number);
+
 CREATE TABLE run_queue (
   run_id TEXT PRIMARY KEY REFERENCES runs(run_id) ON DELETE CASCADE,
   status TEXT NOT NULL CHECK (status IN (
@@ -155,14 +247,16 @@ CREATE TABLE node_attempts (
   attempt_number INTEGER NOT NULL CHECK (attempt_number > 0),
   node_type TEXT NOT NULL,
   status TEXT NOT NULL CHECK (status IN (
-    'pending', 'running', 'waiting', 'completed', 'failed', 'timed_out', 'cancelled'
+    'pending', 'running', 'waiting', 'interrupted',
+    'completed', 'failed', 'timed_out', 'cancelled'
   )),
-  input_hash BLOB REFERENCES blobs(blob_hash),
-  contract_hash BLOB REFERENCES blobs(blob_hash),
-  presentation_hash BLOB REFERENCES blobs(blob_hash),
+  prompt_hash BLOB REFERENCES blobs(blob_hash),
   output_hash BLOB REFERENCES blobs(blob_hash),
-  result_hash BLOB REFERENCES blobs(blob_hash),
+  receipt_hash BLOB REFERENCES blobs(blob_hash),
   error_hash BLOB REFERENCES blobs(blob_hash),
+  settings_scope_id TEXT REFERENCES workflow_settings(scope_id),
+  settings_change_number INTEGER CHECK (settings_change_number IS NULL OR settings_change_number >= 0),
+  settings_hash BLOB REFERENCES blobs(blob_hash),
   started_at INTEGER,
   deadline_at INTEGER,
   finished_at INTEGER,
@@ -175,10 +269,22 @@ CREATE UNIQUE INDEX node_attempts_active_idx ON node_attempts(run_id)
 WHERE status IN ('pending', 'running', 'waiting');
 CREATE INDEX node_attempts_run_idx ON node_attempts(run_id, created_at);
 
+CREATE TABLE run_steps (
+  run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+  step_index INTEGER NOT NULL CHECK (step_index >= 0),
+  attempt_id TEXT NOT NULL REFERENCES node_attempts(attempt_id),
+  output_override_hash BLOB REFERENCES blobs(blob_hash),
+  PRIMARY KEY (run_id, step_index),
+  UNIQUE (run_id, attempt_id)
+) STRICT;
+
+CREATE INDEX run_steps_attempt_idx ON run_steps(attempt_id);
+
 CREATE TABLE workflow_updates (
   update_id TEXT PRIMARY KEY,
   attempt_id TEXT NOT NULL REFERENCES node_attempts(attempt_id) ON DELETE CASCADE,
   update_seq INTEGER NOT NULL CHECK (update_seq > 0),
+  run_revision INTEGER NOT NULL CHECK (run_revision > 0),
   update_type TEXT NOT NULL,
   update_key TEXT NOT NULL,
   data_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
@@ -216,6 +322,18 @@ CREATE TABLE session_entries (
   UNIQUE (segment_id, entry_id)
 ) STRICT;
 
+CREATE TABLE attempt_entries (
+  attempt_id TEXT NOT NULL REFERENCES node_attempts(attempt_id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('prompt', 'response', 'first', 'last')),
+  segment_id TEXT NOT NULL,
+  entry_id TEXT NOT NULL,
+  PRIMARY KEY (attempt_id, role),
+  FOREIGN KEY (segment_id, entry_id)
+    REFERENCES session_entries(segment_id, entry_id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX attempt_entries_entry_idx ON attempt_entries(segment_id, entry_id);
+
 CREATE TABLE session_events (
   segment_id TEXT NOT NULL REFERENCES session_segments(segment_id) ON DELETE CASCADE,
   event_seq INTEGER NOT NULL CHECK (event_seq > 0),
@@ -287,7 +405,6 @@ CREATE TABLE continuations (
   decision_id TEXT PRIMARY KEY REFERENCES human_decisions(decision_id) ON DELETE CASCADE,
   parent_run_id TEXT NOT NULL UNIQUE REFERENCES runs(run_id),
   continuation_run_id TEXT NOT NULL UNIQUE REFERENCES runs(run_id),
-  response_hash BLOB NOT NULL REFERENCES blobs(blob_hash),
   created_at INTEGER NOT NULL
 ) STRICT;
 

package/src/viewer/cli.ts

@@ -6,6 +6,7 @@ import { SqliteControllerStore } from "../controllers/sqlite.js";
 import { syncHerdrPlugin } from "../herdr/setup.js";
 import { sanitizeText } from "../render/ansi.js";
 import { StateDatabase } from "../state/database.js";
+import { pruneState } from "../state/prune.js";
 import { WorkflowRunStore, workflowStateDatabasePath } from "../workflows/store.js";
 import {
   formatDuration,
@@ -25,6 +26,8 @@ Usage:
   pi-workflows controller <controller> <key>
   pi-workflows state status|verify
   pi-workflows state backup <destination>
+  pi-workflows state prune --before <timestamp> --dry-run
+  pi-workflows state prune --before <timestamp> --backup <absolute-path> --apply
   pi-workflows host [--project <dir>] [-- <extra pi args>]
   pi-workflows herdr sync [--json]
   pi-workflows herdr setup [--json]
@@ -38,8 +41,10 @@ export type CliArgs = {
   controllerName?: string;
   resourceKey?: string;
   herdrAction?: string;
-  stateAction?: "status" | "verify" | "backup";
+  stateAction?: "status" | "verify" | "backup" | "prune";
   backupDestination?: string;
+  pruneBefore?: string;
+  pruneApply?: boolean;
   once: boolean;
   json: boolean;
   project?: string | undefined;
@@ -52,12 +57,20 @@ export function parseCliArgs(argv: string[]): CliArgs {
   let once = false;
   let json = false;
   let project: string | undefined;
+  let pruneBefore: string | undefined;
+  let backupDestination: string | undefined;
+  let pruneApply = false;
+  let pruneDryRun = false;
   const positionals: string[] = [];
   const piArgs: string[] = [];
 
   while (args.length > 0) {
     const arg = args.shift() as string;
     if (arg === "--project") project = requiredValue(args, "--project");
+    else if (arg === "--before") pruneBefore = requiredValue(args, "--before");
+    else if (arg === "--backup") backupDestination = requiredValue(args, "--backup");
+    else if (arg === "--apply") pruneApply = true;
+    else if (arg === "--dry-run") pruneDryRun = true;
     else if (arg === "--once") once = true;
     else if (arg === "--json") json = true;
     else if (arg === "--help" || arg === "-h") return { command: "help", once, json };
@@ -80,8 +93,30 @@ export function parseCliArgs(argv: string[]): CliArgs {
   }
   if (command === "state") {
     const action = positionals[0];
-    if (action !== "status" && action !== "verify" && action !== "backup") {
-      throw new Error("state requires status, verify, or backup");
+    if (action !== "status" && action !== "verify" && action !== "backup" && action !== "prune") {
+      throw new Error("state requires status, verify, backup, or prune");
+    }
+    if (action === "prune") {
+      if (positionals.length !== 1) throw new Error("state prune accepts no positional arguments");
+      if (pruneBefore === undefined) throw new Error("state prune requires --before <timestamp>");
+      if (pruneApply === pruneDryRun) {
+        throw new Error("state prune requires exactly one of --dry-run or --apply");
+      }
+      if (pruneApply && backupDestination === undefined) {
+        throw new Error("state prune --apply requires --backup <absolute-path>");
+      }
+      if (pruneDryRun && backupDestination !== undefined) {
+        throw new Error("state prune --dry-run does not accept --backup");
+      }
+      return {
+        command,
+        stateAction: action,
+        pruneBefore,
+        pruneApply,
+        ...(backupDestination === undefined ? {} : { backupDestination }),
+        once,
+        json,
+      };
     }
     if (action === "backup") {
       if (positionals.length !== 2) throw new Error("state backup requires <destination>");
@@ -251,6 +286,15 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
 }
 
 async function runStateCommand(databasePath: string, args: CliArgs): Promise<void> {
+  if (args.stateAction === "prune") {
+    const report = await pruneState(databasePath, {
+      before: args.pruneBefore as string,
+      apply: args.pruneApply === true,
+      ...(args.backupDestination === undefined ? {} : { backupPath: args.backupDestination }),
+    });
+    process.stdout.write(`${JSON.stringify(report)}\n`);
+    return;
+  }
   if (args.stateAction === "backup") {
     const state = new StateDatabase({ filePath: databasePath });
     try {
@@ -274,10 +318,13 @@ async function runStateCommand(databasePath: string, args: CliArgs): Promise<voi
            (SELECT count(*) FROM runs) AS runs,
            (SELECT count(*) FROM controller_resources) AS controllers,
            (SELECT count(*) FROM human_decisions) AS decisions,
+           (SELECT count(*) FROM workflow_settings) AS settingsScopes,
+           (SELECT count(*) FROM workflow_follow_ups WHERE status IN ('queued', 'pending_presentation', 'ready')) AS pendingFollowUps,
            (SELECT count(*) FROM effects WHERE status IN ('pending', 'applying', 'ambiguous')) AS unsettledEffects,
-           (SELECT count(*) FROM leases WHERE owner_id IS NOT NULL) AS activeLeases`,
+           (SELECT count(*) FROM leases
+            WHERE owner_id IS NOT NULL AND expires_at > ?) AS activeLeases`,
       )
-      .get();
+      .get(Date.now());
     process.stdout.write(
       `Database: ${databasePath}\nSize: ${fs.statSync(databasePath).size} bytes\n${JSON.stringify(counts)}\n`,
     );

package/src/viewer/render.ts

@@ -102,8 +102,10 @@ function stepLine(
     step.error !== undefined
       ? ansi.red(previewValue(step.error, 60))
       : ansi.dim(previewValue(step.output, 60));
+  const settings =
+    step.settingsChangeNumber === undefined ? "" : `, settings ${step.settingsChangeNumber}`;
   return fitWidth(
-    ` ${marker}${glyph} ${step.nodeId} ${ansi.dim(`(${step.nodeType}, ${formatDuration(durationMs)})`)} ${preview}`,
+    ` ${marker}${glyph} ${step.nodeId} ${ansi.dim(`(${step.nodeType}, ${formatDuration(durationMs)}${settings})`)} ${preview}`,
     width,
   );
 }
@@ -181,6 +183,16 @@ function inspectorLines(step: WorkflowStepRecord, width: number): string[] {
   for (const raw of (rendered ?? "null").split("\n")) {
     lines.push(fitWidth(`  ${sanitizeText(raw)}`, width));
   }
+  if (step.settingsScopeId !== undefined) {
+    lines.push(
+      fitWidth(
+        ansi.dim(
+          `  settings ${step.settingsChangeNumber ?? 0} · ${sanitizeText(step.settingsScopeId)} · ${step.settingsHash?.slice(0, 12) ?? "unknown hash"}`,
+        ),
+        width,
+      ),
+    );
+  }
   if (step.action) {
     const receipt = [
       step.action.actionType,
@@ -273,6 +285,36 @@ export function renderRunDetailLines(
     }
   }
 
+  if ((bundle.settingsScopes?.length ?? 0) > 0) {
+    lines.push("");
+    lines.push(ansi.bold("workflow settings"));
+    for (const scope of bundle.settingsScopes ?? []) {
+      lines.push(
+        fitWidth(
+          `  ${sanitizeText(scope.mountPath || "root")} #${scope.invocation} · change ${scope.changeNumber} · ${scope.settingsHash.slice(0, 12)}`,
+          size.width,
+        ),
+      );
+    }
+  }
+
+  if ((bundle.followUpQueue?.followUps.length ?? 0) > 0) {
+    lines.push("");
+    lines.push(
+      ansi.bold(
+        `follow-ups · presentation ${bundle.followUpQueue?.presentationState ?? "unknown"}`,
+      ),
+    );
+    for (const followUp of bundle.followUpQueue?.followUps ?? []) {
+      lines.push(
+        fitWidth(
+          `  ${followUp.order}. ${followUp.state} · ${followUp.followUpId} · ${sanitizeText(followUp.source)}`,
+          size.width,
+        ),
+      );
+    }
+  }
+
   if (steps.length > 0) {
     lines.push("");
     lines.push(ansi.bold("steps"));

package/src/viewer/session-reducer.ts

@@ -20,7 +20,6 @@ export type TemporalTool = {
   messageId: string;
   toolName: string;
   status: "running" | "finished" | "failed";
-  updates: number;
   args?: unknown;
   result?: unknown;
 };
@@ -155,22 +154,6 @@ function foldSessionEvents(
                 ? "thinking"
                 : "toolCall",
           );
-        } else if (
-          contentIndex !== undefined &&
-          (assistantType === "text_delta" ||
-            assistantType === "thinking_delta" ||
-            assistantType === "toolcall_delta")
-        ) {
-          const block = ensureBlock(
-            message,
-            contentIndex,
-            assistantType === "text_delta"
-              ? "text"
-              : assistantType === "thinking_delta"
-                ? "thinking"
-                : "toolCall",
-          );
-          block.text += payloadString(event.payload, "delta") ?? "";
         } else if (
           contentIndex !== undefined &&
           (assistantType === "text_end" || assistantType === "thinking_end")
@@ -181,10 +164,10 @@ function foldSessionEvents(
             assistantType === "text_end" ? "text" : "thinking",
           );
           const content = payloadString(event.payload, "content") ?? "";
-          if (block.text !== content) {
+          if (block.text.length > 0 && block.text !== content) {
             diagnostics.push(`${assistantType} mismatch for ${event.messageId}:${contentIndex}`);
-            block.text = content;
           }
+          block.text = content;
         } else if (contentIndex !== undefined && assistantType === "toolcall_end") {
           const block = ensureBlock(message, contentIndex, "toolCall");
           block.value = event.payload.toolCall;
@@ -229,22 +212,12 @@ function foldSessionEvents(
           messageId: event.messageId,
           toolName: payloadString(event.payload, "toolName") ?? "tool",
           status: "running",
-          updates: 0,
           ...(event.payload.args === undefined ? {} : { args: event.payload.args }),
         };
         tools.set(event.toolCallId, tool);
         toolOrder.push(event.toolCallId);
         break;
       }
-      case "tool_execution_updated": {
-        const tool = event.toolCallId ? tools.get(event.toolCallId) : undefined;
-        if (tool) {
-          tool.updates += 1;
-        } else {
-          diagnostics.push(`tool_execution_updated ${event.seq} precedes start`);
-        }
-        break;
-      }
       case "tool_execution_finished": {
         const tool = event.toolCallId ? tools.get(event.toolCallId) : undefined;
         if (!tool) {

package/src/workflows/composition.ts

@@ -31,6 +31,7 @@ export type WorkflowScopeMetadata = {
   path: string;
   workflowName: string;
   maxSteps?: number;
+  settings?: WorkflowDefinition["settings"];
   authoredNodes: Record<string, string>;
   childMounts: Record<string, string>;
 };
@@ -41,6 +42,7 @@ export type WorkflowEntryMetadata = {
   parentPath: string;
   workflowName: string;
   input: WorkflowIncludeDefinition["input"];
+  settings?: WorkflowIncludeDefinition["settings"];
   normalizeInput?: WorkflowDefinition["input"];
 };
 
@@ -125,6 +127,7 @@ export function compileWorkflowDefinition<TWorkflow extends WorkflowDefinition<a
       path: scopePath,
       workflowName: current.name,
       ...(current.maxSteps !== undefined ? { maxSteps: current.maxSteps } : {}),
+      ...(current.settings !== undefined ? { settings: current.settings } : {}),
       authoredNodes,
       childMounts,
     };
@@ -155,6 +158,11 @@ export function compileWorkflowDefinition<TWorkflow extends WorkflowDefinition<a
           `Workflow include ${qualify(scopePath, name)} is unresolved: ${include.workflow}`,
         );
       }
+      if (include.settings !== undefined && child.settings === undefined) {
+        throw new Error(
+          `Workflow include ${qualify(scopePath, name)} maps settings but child ${child.name} declares none`,
+        );
+      }
       const mountPath = qualify(scopePath, name);
       const childExits = child.exits ?? {};
       if (Object.keys(childExits).length === 0) {
@@ -167,6 +175,7 @@ export function compileWorkflowDefinition<TWorkflow extends WorkflowDefinition<a
         parentPath: scopePath,
         workflowName: child.name,
         input: include.input,
+        ...(include.settings !== undefined ? { settings: include.settings } : {}),
         normalizeInput: child.input,
       };
       nodes[entryNode] = {
@@ -176,10 +185,14 @@ export function compileWorkflowDefinition<TWorkflow extends WorkflowDefinition<a
           const parentContext = projectWorkflowContext(context, scopePath, scopes, entries, exits);
           const mapped = include.input ? await include.input(parentContext) : parentContext.input;
           const normalized = child.input ? await child.input(mapped) : mapped;
+          const initialSettings = include.settings
+            ? await include.settings(parentContext)
+            : undefined;
           return {
             schema: "pi-workflows.include-entry.v1",
             invocation: countCompletedEntries(context.state, entryNode) + 1,
             input: normalized === undefined ? null : normalized,
+            ...(initialSettings !== undefined ? { settings: initialSettings } : {}),
           };
         },
       };
@@ -478,6 +491,7 @@ function wrapNode(
         ...common,
         nodeType: "compute",
         run: (context) => (node as ComputeNodeDefinition).run(project(context)),
+        ...(node.settingsRoute === true ? { settingsRoute: true as const } : {}),
       };
     case "notify":
       return {
@@ -637,6 +651,11 @@ export function projectWorkflowContext(
     outputs,
     results,
     state,
+    ...(context.settings !== undefined ? { settings: context.settings } : {}),
+    ...(context.settingsScopeId !== undefined ? { settingsScopeId: context.settingsScopeId } : {}),
+    ...(context.settingsChangeNumber !== undefined
+      ? { settingsChangeNumber: context.settingsChangeNumber }
+      : {}),
     signal: context.signal,
   };
 }

package/src/workflows/definition.ts

@@ -7,6 +7,7 @@ import {
   assertValidShellActionNode,
   assertValidWorkflowDefinitionShape,
 } from "./schema.js";
+import type { WorkflowSettingsDefinition } from "./settings.js";
 import type {
   AgentNodeDefinition,
   AssistantAgentNodeDefinition,
@@ -26,6 +27,7 @@ import type {
   WorkflowInputOf,
   WorkflowNodeContext,
   WorkflowNodeDefinition,
+  WorkflowSettingsOf,
   WorkflowTypedEdge,
   WorkflowValueParser,
 } from "./types.js";
@@ -37,11 +39,13 @@ type WorkflowDefinitionInput<
   TNodes extends Record<string, WorkflowNodeDefinition>,
   TIncludes extends WorkflowIncludeMap,
   TExits extends WorkflowExitMap,
+  TSettings,
 > = Omit<
-  WorkflowDefinition<TInput, TExits, TIncludes>,
-  "input" | "nodes" | "includes" | "exits" | "edges"
+  WorkflowDefinition<TInput, TExits, TIncludes, TSettings>,
+  "input" | "settings" | "nodes" | "includes" | "exits" | "edges"
 > & {
   input?: WorkflowValueParser<TInput>;
+  settings?: WorkflowSettingsDefinition<TSettings, TInput>;
   nodes: TNodes;
   includes?: TIncludes;
   exits?: TExits;
@@ -56,15 +60,16 @@ export function defineWorkflow<
   >,
   const TIncludes extends WorkflowIncludeMap = Record<never, never>,
   const TExits extends WorkflowExitMap = Record<never, never>,
+  TSettings = unknown,
 >(
-  definition: WorkflowDefinitionInput<TInput, TNodes, TIncludes, TExits>,
-): WorkflowDefinition<TInput, TExits, TIncludes> & {
+  definition: WorkflowDefinitionInput<TInput, TNodes, TIncludes, TExits, TSettings>,
+): WorkflowDefinition<TInput, TExits, TIncludes, TSettings> & {
   nodes: TNodes;
   includes?: TIncludes;
   exits?: TExits;
 } {
   assertValidWorkflowDefinitionShape(definition as WorkflowDefinition);
-  const typed = definition as WorkflowDefinition<TInput, TExits, TIncludes> & {
+  const typed = definition as WorkflowDefinition<TInput, TExits, TIncludes, TSettings> & {
     nodes: TNodes;
     includes?: TIncludes;
     exits?: TExits;
@@ -87,6 +92,9 @@ export function includeWorkflow<TWorkflow extends WorkflowDefinition<any, any, a
     input?: (
       context: WorkflowNodeContext,
     ) => Promise<WorkflowInputOf<TWorkflow>> | WorkflowInputOf<TWorkflow>;
+    settings?: (
+      context: WorkflowNodeContext,
+    ) => Promise<WorkflowSettingsOf<TWorkflow>> | WorkflowSettingsOf<TWorkflow>;
   },
 ): WorkflowIncludeDefinition<TWorkflow>;
 export function includeWorkflow<TWorkflow extends WorkflowDefinition<any, any, any>>(
@@ -98,6 +106,9 @@ export function includeWorkflow<TWorkflow extends WorkflowDefinition<any, any, a
     input?: (
       context: WorkflowNodeContext,
     ) => Promise<WorkflowInputOf<TWorkflow>> | WorkflowInputOf<TWorkflow>;
+    settings?: (
+      context: WorkflowNodeContext,
+    ) => Promise<WorkflowSettingsOf<TWorkflow>> | WorkflowSettingsOf<TWorkflow>;
   } = {},
 ): WorkflowIncludeDefinition<TWorkflow> {
   const definition = isWorkflowDefinition(workflowOrDefinition)
@@ -109,6 +120,9 @@ export function includeWorkflow<TWorkflow extends WorkflowDefinition<any, any, a
   if (definition.input !== undefined && typeof definition.input !== "function") {
     throw new Error("Included workflow input must be a function");
   }
+  if (definition.settings !== undefined && typeof definition.settings !== "function") {
+    throw new Error("Included workflow settings must be a function");
+  }
   if (definition.contract !== undefined && !isWorkflowDefinition(definition.contract)) {
     throw new Error("Included workflow contract must be defined with defineWorkflow");
   }