@osolmaz/pi-workflows 0.13.2 → 0.13.3

package/src/workflows/tool-input.ts

@@ -30,6 +30,32 @@ const updateSchema = Type.Object(
 const outputSchema = Type.Unknown({
   description: "Step output matching the expected shape; required when action is submit",
 });
+const scopeIdSchema = Type.String({
+  description: "Settings scope id; defaults to the active node scope",
+});
+const expectedChangeNumberSchema = Type.Integer({
+  minimum: 0,
+  description: "Optional settings change number for an atomic compare-and-change",
+});
+const patchOperationSchema = Type.Object(
+  {
+    op: Type.String({ enum: ["add", "remove", "replace", "move", "copy", "test"] }),
+    path: Type.String(),
+    from: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+  },
+  noExtraProperties,
+);
+const patchSchema = Type.Array(patchOperationSchema, {
+  maxItems: 256,
+  description: "RFC 6902 JSON Patch operations",
+});
+const followUpPromptSchema = Type.String({
+  minLength: 1,
+  maxLength: 65536,
+  description: "Normal user prompt to send after successful workflow completion",
+});
+const followUpIdSchema = Type.String({ description: "Queued follow-up id" });
 
 export const WorkflowActionSchemas = {
   list: Type.Object(
@@ -62,6 +88,32 @@ export const WorkflowActionSchemas = {
     },
     noExtraProperties,
   ),
+  "change-settings": Type.Object(
+    {
+      action: Type.Literal("change-settings"),
+      runId: Type.Optional(runIdSchema),
+      scopeId: Type.Optional(scopeIdSchema),
+      expectedChangeNumber: Type.Optional(expectedChangeNumberSchema),
+      patch: patchSchema,
+    },
+    noExtraProperties,
+  ),
+  "queue-follow-up": Type.Object(
+    {
+      action: Type.Literal("queue-follow-up"),
+      runId: Type.Optional(runIdSchema),
+      prompt: followUpPromptSchema,
+    },
+    noExtraProperties,
+  ),
+  "remove-follow-up": Type.Object(
+    {
+      action: Type.Literal("remove-follow-up"),
+      runId: Type.Optional(runIdSchema),
+      followUpId: followUpIdSchema,
+    },
+    noExtraProperties,
+  ),
   update: Type.Object(
     {
       action: Type.Literal("update"),
@@ -107,6 +159,12 @@ const workflowInputParsers = {
   resume: (value) => parseToolInput(WorkflowActionSchemas.resume, value, "workflow"),
   cancel: (value) => parseToolInput(WorkflowActionSchemas.cancel, value, "workflow"),
   answer: (value) => parseToolInput(WorkflowActionSchemas.answer, value, "workflow"),
+  "change-settings": (value) =>
+    parseToolInput(WorkflowActionSchemas["change-settings"], value, "workflow"),
+  "queue-follow-up": (value) =>
+    parseToolInput(WorkflowActionSchemas["queue-follow-up"], value, "workflow"),
+  "remove-follow-up": (value) =>
+    parseToolInput(WorkflowActionSchemas["remove-follow-up"], value, "workflow"),
   update: (value) => parseToolInput(WorkflowActionSchemas.update, value, "workflow"),
   submit: (value) => parseToolInput(WorkflowActionSchemas.submit, value, "workflow"),
 } satisfies Record<keyof typeof WorkflowActionSchemas, ToolInputParser<WorkflowToolInput>>;

package/src/workflows/types.ts

@@ -5,11 +5,17 @@ export type MaybePromise<T> = T | Promise<T>;
  * validators). `outputs` maps node ids to their accepted outputs; `results`
  * maps node ids to the full result record of their latest attempt.
  */
-export type WorkflowNodeContext<TInput = unknown> = {
+export type WorkflowNodeContext<TInput = unknown, TSettings = unknown> = {
   input: TInput;
   outputs: Record<string, unknown>;
   results: Record<string, WorkflowNodeResult>;
   state: WorkflowRunState;
+  /** Fixed settings value captured when this node attempt started, when declared. */
+  settings?: TSettings;
+  /** Stable root or included-workflow settings scope for this attempt. */
+  settingsScopeId?: string;
+  /** Accepted settings change number captured by this attempt. */
+  settingsChangeNumber?: number;
   /**
    * Aborted when the node times out or the run is cancelled. Long-running
    * callbacks should observe it (pass it to fetch/spawn or check
@@ -130,6 +136,8 @@ export type AgentNodeDefinition = SubmittedAgentNodeDefinition | AssistantAgentN
 export type ComputeNodeDefinition = WorkflowNodeCommon & {
   nodeType: "compute";
   run: (context: WorkflowNodeContext) => MaybePromise<unknown>;
+  /** Marks a pure route selector that may rerun before route settlement. */
+  settingsRoute?: true;
 };
 
 /** A durable user-facing message addressed by the runtime to the run's origin session. */
@@ -471,10 +479,13 @@ export type WorkflowExitDefinition<TOutput = unknown> = {
 export type WorkflowExitMap = Record<string, WorkflowExitDefinition>;
 
 export type WorkflowInputOf<TWorkflow> =
-  TWorkflow extends WorkflowDefinition<infer TInput, any, any> ? TInput : unknown;
+  TWorkflow extends WorkflowDefinition<infer TInput, any, any, any> ? TInput : unknown;
+
+export type WorkflowSettingsOf<TWorkflow> =
+  TWorkflow extends WorkflowDefinition<any, any, any, infer TSettings> ? TSettings : unknown;
 
 export type WorkflowExitOutputs<TWorkflow> =
-  TWorkflow extends WorkflowDefinition<any, infer TExits, any>
+  TWorkflow extends WorkflowDefinition<any, infer TExits, any, any>
     ? {
         [K in keyof TExits]: TExits[K] extends WorkflowExitDefinition<infer TOutput>
           ? TOutput
@@ -490,12 +501,14 @@ export type WorkflowIncludedResult<TWorkflow> = {
 }[keyof WorkflowExitOutputs<TWorkflow>];
 
 export type WorkflowIncludeDefinition<
-  TWorkflow extends WorkflowDefinition<any, any, any> = WorkflowDefinition<any, any, any>,
+  TWorkflow extends WorkflowDefinition<any, any, any, any> = WorkflowDefinition<any, any, any, any>,
 > = {
   /** Imported child definition or dynamic discovered name/path. */
   workflow: TWorkflow | string;
   /** Pure parent-to-child input mapping, evaluated on every mount entry. */
   input?: (context: WorkflowNodeContext) => MaybePromise<WorkflowInputOf<TWorkflow>>;
+  /** Optional explicit initial settings mapping for this child invocation. */
+  settings?: (context: WorkflowNodeContext) => MaybePromise<WorkflowSettingsOf<TWorkflow>>;
   /** Optional direct definition that supplies the contract for a dynamic reference. */
   contract?: TWorkflow;
 };
@@ -528,8 +541,11 @@ export type WorkflowDefinition<
   TInput = any,
   TExits extends WorkflowExitMap = WorkflowExitMap,
   TIncludes extends WorkflowIncludeMap = WorkflowIncludeMap,
+  TSettings = any,
 > = {
   name: string;
+  /** Optional workflow-owned JSON settings that can change during a run. */
+  settings?: import("./settings.js").WorkflowSettingsDefinition<TSettings, TInput>;
   /** Module URL used to attest directly imported child workflow files. */
   source?: string;
   /** Stable public input-and-exit contract identity for compatible overrides. */
@@ -605,6 +621,12 @@ export type WorkflowStepRecord = {
   assistantMessage?: AssistantMessageReceipt;
   /** For agent steps recorded inside a Pi conversation. */
   conversation?: ConversationRange;
+  /** Fixed settings scope used by this attempt. */
+  settingsScopeId?: string;
+  /** Fixed accepted-through settings number used by this attempt. */
+  settingsChangeNumber?: number;
+  /** SHA-256 hash of the fixed settings JSON used by this attempt. */
+  settingsHash?: string;
 };
 
 export type WorkflowRunStatus =
@@ -674,6 +696,9 @@ export type WorkflowRunState = {
   currentNode?: string;
   currentAttemptId?: string;
   currentNodeStartedAt?: string;
+  currentSettingsScopeId?: string;
+  currentSettingsChangeNumber?: number;
+  currentSettingsHash?: string;
   statusDetail?: string;
   /** Redacted verified-human receipt carried by a continuation run. */
   humanDecision?: HumanDecisionReceipt;
@@ -690,6 +715,7 @@ export type WorkflowNodeSnapshot = {
   statusDetail?: string;
   summary?: string;
   expectedOutput?: AgentExpectedOutput;
+  settingsRoute?: true;
   actionExecution?: "function" | "shell";
   mountPath?: string[];
   localNodeId?: string;
@@ -711,6 +737,19 @@ export type WorkflowDefinitionSnapshot = {
   nodes: Record<string, WorkflowNodeSnapshot>;
   edges: WorkflowEdge[];
   composition?: WorkflowCompositionSnapshot;
+  settings?: WorkflowSettingsSnapshot;
+  settingsScopes?: Array<{
+    mountPath: string[];
+    settings: WorkflowSettingsSnapshot;
+  }>;
+};
+
+export type WorkflowSettingsSnapshot = {
+  description?: string;
+  paths: Array<{
+    path: string;
+    permissions: Partial<Record<"read" | "add" | "remove" | "replace", string[]>>;
+  }>;
 };
 
 export type WorkflowTraceEvent = {