@osolmaz/pi-workflows 0.16.0 → 0.16.2

package/src/workflows/tool-input.ts

@@ -12,7 +12,8 @@ const inputSchema = Type.Unknown({
     "Ordinary checkpoint answer for answer; protected human decisions require a human channel; optional structured workflow input for start",
 });
 const runIdSchema = Type.String({
-  description: "Run id; optional for status, cancel, and answer",
+  description:
+    "Run id; required for restart and optional for status, cancel, answer, settings, and follow-ups",
 });
 const stepSchema = Type.String({
   description: "Workflow step id; required when action is update or submit",
@@ -44,6 +45,33 @@ export const WorkflowActionSchemas = {
     },
     noExtraProperties,
   ),
+  restart: Type.Object({ action: Type.Literal("restart"), runId: runIdSchema }, noExtraProperties),
+  "change-settings": Type.Object(
+    {
+      action: Type.Literal("change-settings"),
+      runId: Type.Optional(runIdSchema),
+      scopeId: Type.Optional(Type.String()),
+      expectedChangeNumber: Type.Optional(Type.Integer({ minimum: 0 })),
+      patch: Type.Unknown(),
+    },
+    noExtraProperties,
+  ),
+  "queue-follow-up": Type.Object(
+    {
+      action: Type.Literal("queue-follow-up"),
+      runId: Type.Optional(runIdSchema),
+      prompt: Type.String({ minLength: 1 }),
+    },
+    noExtraProperties,
+  ),
+  "remove-follow-up": Type.Object(
+    {
+      action: Type.Literal("remove-follow-up"),
+      runId: Type.Optional(runIdSchema),
+      followUpId: Type.String(),
+    },
+    noExtraProperties,
+  ),
   status: Type.Object(
     { action: Type.Literal("status"), runId: Type.Optional(runIdSchema) },
     noExtraProperties,
@@ -102,6 +130,13 @@ type ToolInputParser<Output> = (value: unknown) => Output;
 const workflowInputParsers = {
   list: (value) => parseToolInput(WorkflowActionSchemas.list, value, "workflow"),
   start: (value) => parseToolInput(WorkflowActionSchemas.start, value, "workflow"),
+  restart: (value) => parseToolInput(WorkflowActionSchemas.restart, 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"),
   status: (value) => parseToolInput(WorkflowActionSchemas.status, value, "workflow"),
   pause: (value) => parseToolInput(WorkflowActionSchemas.pause, value, "workflow"),
   resume: (value) => parseToolInput(WorkflowActionSchemas.resume, value, "workflow"),

package/src/workflows/types.ts

@@ -53,9 +53,7 @@ export type WorkflowEffectRecovery = "idempotent" | "manual";
 export type WorkflowManagedEffect = {
   /** Stable external effect category, for example `github.comment`. */
   type: string;
-  /** Stable key. Idempotent adapters must pass this key to the external system. */
-  idempotencyKey: string | ((context: WorkflowNodeContext) => MaybePromise<string>);
-  /** Canonical request data used to reject key reuse with another operation. */
+  /** Canonical request data used to reject engine-owned key reuse with another operation. */
   request: unknown | ((context: WorkflowNodeContext) => MaybePromise<unknown>);
   /** `manual` never retries after an uncertain child exit. */
   recovery: WorkflowEffectRecovery;
@@ -97,9 +95,9 @@ export type WorkflowProgressData = {
 
 export type WorkflowNodeCommon = {
   /**
-   * Per-node timeout or a callback that derives it from the run context.
-   * Null disables the wall-clock deadline. Omission falls back to the engine
-   * default (15 minutes).
+   * Per-node active-execution timeout or a callback that derives it from the run context.
+   * Waiting, paused, disconnected, and host-down origin-session time does not count.
+   * Null disables the deadline. Omission falls back to the engine default (15 minutes).
    */
   timeoutMs?: number | null | ((context: WorkflowNodeContext) => MaybePromise<number | null>);
   /** Short human-readable label shown in the viewer while the node runs. */
@@ -436,7 +434,7 @@ export type HumanDecisionSettlementRecord = {
   decisionId: string;
   requestDigest: string;
   channel: string;
-  state: "confirmed" | "failed";
+  state: "confirmed" | "failed" | "unknown";
   createdAt: string;
   finishedAt: string;
   errorCode?: string;
@@ -719,7 +717,7 @@ export type WorkflowRunState = {
   currentNode?: string;
   currentAttemptId?: string;
   currentNodeStartedAt?: string;
-  /** Durable wall-clock deadline for the current attempt. Null disables the deadline. */
+  /** Durable active-execution deadline for the current attempt. Null disables the deadline. */
   currentNodeDeadlineAt?: string | null;
   currentSettingsScopeId?: string;
   currentSettingsChangeNumber?: number;

package/src/workflows/workflow-message-content.ts

@@ -0,0 +1,197 @@
+import type { JsonValue } from "../state/json.js";
+import {
+  WORKFLOW_MESSAGE_CONTENT_SCHEMA,
+  type WorkflowMessageContent,
+  type WorkflowStepReason,
+} from "../state/workflow-messages.js";
+import type { AgentStepContract } from "./types.js";
+
+export const WORKFLOW_STEP_MESSAGE_TYPE = "pi-workflows-step";
+export const WORKFLOW_DECISION_MESSAGE_TYPE = "pi-workflows-interaction";
+export const WORKFLOW_NOTIFICATION_MESSAGE_TYPE = "pi-workflows-notification";
+export const WORKFLOW_TERMINAL_MESSAGE_TYPE = "pi-workflows-presentation";
+export const WORKFLOW_FOLLOW_UP_MESSAGE_TYPE = "pi-workflows-follow-up";
+
+export function stepWorkflowMessageContent(options: {
+  workflowMessageId: string;
+  requestId: string;
+  contract: JsonValue;
+  reason: WorkflowStepReason;
+}): WorkflowMessageContent {
+  const outer = requireRecord(options.contract, "Stored workflow step contract");
+  const agent = requireAgentContract(outer.contract);
+  const details: Record<string, JsonValue> = {
+    schema: "pi-workflows.agent-step-message.v1",
+    kind: "step",
+    contract: agent as unknown as JsonValue,
+    requestId: options.requestId,
+    workflowMessageId: options.workflowMessageId,
+    reason: options.reason,
+  };
+  if (isRecord(outer.presentation)) details.presentation = outer.presentation as JsonValue;
+  return {
+    schema: WORKFLOW_MESSAGE_CONTENT_SCHEMA,
+    customType: WORKFLOW_STEP_MESSAGE_TYPE,
+    content: typeof outer.prompt === "string" ? outer.prompt : "Continue the workflow step.",
+    display: true,
+    details,
+    triggerTurn: true,
+  };
+}
+
+export function decisionWorkflowMessageContent(options: {
+  workflowMessageId: string;
+  requestId: string;
+  runId: string;
+  contract: JsonValue;
+}): WorkflowMessageContent {
+  const contract = requireRecord(options.contract, "Stored workflow decision contract");
+  return {
+    schema: WORKFLOW_MESSAGE_CONTENT_SCHEMA,
+    customType: WORKFLOW_DECISION_MESSAGE_TYPE,
+    content: decisionPrompt(contract),
+    display: true,
+    details: {
+      workflowMessageId: options.workflowMessageId,
+      requestId: options.requestId,
+      runId: options.runId,
+      kind: "decision",
+    },
+    triggerTurn: false,
+  };
+}
+
+export function notificationWorkflowMessageContent(options: {
+  workflowMessageId: string;
+  notificationId: string;
+  runId: string;
+  kind: "progress" | "final";
+  content: string;
+}): WorkflowMessageContent {
+  return {
+    schema: WORKFLOW_MESSAGE_CONTENT_SCHEMA,
+    customType: WORKFLOW_NOTIFICATION_MESSAGE_TYPE,
+    content: options.content,
+    display: true,
+    details: {
+      workflowMessageId: options.workflowMessageId,
+      notificationId: options.notificationId,
+      runId: options.runId,
+      kind: options.kind,
+    },
+    triggerTurn: false,
+  };
+}
+
+export function terminalWorkflowMessageContent(options: {
+  workflowMessageId: string;
+  runId: string;
+  content: string;
+  details: JsonValue;
+}): WorkflowMessageContent {
+  return {
+    schema: WORKFLOW_MESSAGE_CONTENT_SCHEMA,
+    customType: WORKFLOW_TERMINAL_MESSAGE_TYPE,
+    content: options.content,
+    display: false,
+    details: {
+      workflowMessageId: options.workflowMessageId,
+      runId: options.runId,
+      kind: "terminal",
+      terminal: options.details,
+    },
+    triggerTurn: true,
+  };
+}
+
+export function followUpWorkflowMessageContent(options: {
+  workflowMessageId: string;
+  followUpId: string;
+  runId: string;
+  prompt: string;
+}): WorkflowMessageContent {
+  return {
+    schema: WORKFLOW_MESSAGE_CONTENT_SCHEMA,
+    customType: WORKFLOW_FOLLOW_UP_MESSAGE_TYPE,
+    content: options.prompt,
+    display: true,
+    details: {
+      workflowMessageId: options.workflowMessageId,
+      followUpId: options.followUpId,
+      runId: options.runId,
+      kind: "followUp",
+    },
+    triggerTurn: true,
+  };
+}
+
+function requireAgentContract(value: unknown): AgentStepContract {
+  if (
+    !isRecord(value) ||
+    typeof value.runId !== "string" ||
+    typeof value.workflowName !== "string" ||
+    typeof value.nodeId !== "string" ||
+    typeof value.attemptId !== "string" ||
+    (value.completion !== "submit" && value.completion !== "assistant")
+  ) {
+    throw new Error("Stored workflow agent contract is invalid");
+  }
+  return value as unknown as AgentStepContract;
+}
+
+function decisionPrompt(contract: Record<string, unknown>): string {
+  const title = typeof contract.title === "string" ? contract.title : "Workflow decision";
+  const presentation = isRecord(contract.presentation) ? contract.presentation : {};
+  const blocks = Array.isArray(presentation.blocks)
+    ? presentation.blocks.flatMap((block) => decisionBlockText(block))
+    : [];
+  const choices = isRecord(contract.choices)
+    ? Object.entries(contract.choices).map(([key, value]) => {
+        const choice = isRecord(value) ? value : {};
+        const label = typeof choice.label === "string" ? choice.label : key;
+        const input = isRecord(choice.input) ? choice.input : undefined;
+        const prompt = input === undefined ? "" : `; input: ${String(input.prompt ?? "text")}`;
+        return `- ${key}: ${label}${prompt}`;
+      })
+    : [];
+  return [
+    title,
+    typeof presentation.summary === "string" ? presentation.summary : "",
+    ...blocks,
+    choices.length === 0 ? "" : `Choices:\n${choices.join("\n")}`,
+    "A human must answer this protected decision with `/workflow answer`.",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function decisionBlockText(value: unknown): string[] {
+  if (!isRecord(value)) return [];
+  if (value.kind === "paragraph" && typeof value.text === "string") return [value.text];
+  if (value.kind === "section" && typeof value.title === "string") return [value.title];
+  if (value.kind === "preformatted" && typeof value.text === "string") return [value.text];
+  if (value.kind === "bullets" && Array.isArray(value.items)) {
+    return [value.items.map((item) => `- ${String(item)}`).join("\n")];
+  }
+  if (value.kind === "fields" && Array.isArray(value.items)) {
+    return [
+      value.items
+        .flatMap((item) =>
+          isRecord(item) && typeof item.label === "string" && typeof item.value === "string"
+            ? [`${item.label}: ${item.value}`]
+            : [],
+        )
+        .join("\n"),
+    ];
+  }
+  return [];
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`${label} is invalid`);
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/extension/decision-channels.d.ts

@@ -1,134 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { HumanDecisionStore } from "../workflows/human-decision.js";
-import type { ResolvedHumanDecision, HumanDecisionAnswerSource, HumanDecisionCancellationRecord, HumanDecisionChannelRequest, HumanDecisionResponse } from "../workflows/types.js";
-export type HumanDecisionChannelAnswer = {
-    request: HumanDecisionChannelRequest;
-    response: HumanDecisionResponse;
-    source: HumanDecisionAnswerSource;
-    idempotencyKey: string;
-};
-export type HumanDecisionDeliveryResult = {
-    status: "confirmed" | "failed" | "unknown";
-    channel: string;
-    attemptId: string;
-    errorCode?: string;
-};
-export type SettledHumanDecision = ResolvedHumanDecision | HumanDecisionCancellationRecord;
-export interface HumanDecisionChannel {
-    readonly id: string;
-    start(): Promise<void>;
-    deliver(request: HumanDecisionChannelRequest): Promise<HumanDecisionDeliveryResult>;
-    settle(decision: SettledHumanDecision): Promise<void>;
-    stop(): Promise<void>;
-}
-export type DecisionChannelConfig = {
-    schema: "pi-workflows.channels.v1";
-    audiences: Record<string, {
-        channels: string[];
-        accept: "first-valid-answer";
-    }>;
-    telegramProfiles?: Record<string, {
-        credential: string;
-        allowedUserIds: string[];
-        allowedChatIds: string[];
-    }>;
-};
-export type DecisionCredentialConfig = {
-    schema: "pi-workflows.credentials.v1";
-    telegram: Record<string, {
-        tokenFile: string;
-    }>;
-};
-type ResolvedDecisionCredentials = Record<string, string>;
-export type LoadedDecisionChannelConfig = {
-    channels: DecisionChannelConfig;
-    credentials: ResolvedDecisionCredentials;
-    configDir: string;
-};
-export type TelegramFetch = (input: string, init?: RequestInit) => Promise<{
-    ok: boolean;
-    status: number;
-    json(): Promise<unknown>;
-}>;
-export type PiDecisionUi = Pick<ExtensionContext["ui"], "custom" | "input">;
-export declare function decisionConfigDir(env?: NodeJS.ProcessEnv): string;
-export declare function loadDecisionChannelConfig(configDir?: string): Promise<LoadedDecisionChannelConfig | null>;
-export declare function audienceChannels(config: DecisionChannelConfig | null, audience: string): string[];
-export declare class PiDecisionChannel implements HumanDecisionChannel {
-    private readonly options;
-    readonly id = "pi";
-    private promptAbort;
-    private settlementTask;
-    constructor(options: {
-        actorId: string;
-        ui: PiDecisionUi;
-        store: HumanDecisionStore;
-        onAnswer: (answer: HumanDecisionChannelAnswer) => Promise<void>;
-    });
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    deliver(request: HumanDecisionChannelRequest): Promise<HumanDecisionDeliveryResult>;
-    private alreadyDecided;
-    settle(decision: SettledHumanDecision): Promise<void>;
-    private settleOnce;
-}
-export declare class TelegramDecisionChannel implements HumanDecisionChannel {
-    readonly id: string;
-    private readonly profile;
-    private readonly store;
-    private readonly fetchFn;
-    private readonly apiBase;
-    private readonly onAnswer;
-    private readonly projection;
-    private running;
-    private pollAbort;
-    private pollTask;
-    private readonly settlementTasks;
-    constructor(options: {
-        profileName: string;
-        token: string;
-        allowedUserIds: string[];
-        allowedChatIds: string[];
-        store: HumanDecisionStore;
-        configDir?: string;
-        onAnswer: (answer: HumanDecisionChannelAnswer) => Promise<void>;
-        fetchFn?: TelegramFetch;
-        apiBase?: string;
-        ownerId?: string;
-    });
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    deliver(request: HumanDecisionChannelRequest): Promise<HumanDecisionDeliveryResult>;
-    settle(decision: SettledHumanDecision): Promise<void>;
-    private settleOnce;
-    handleUpdate(value: unknown): Promise<void>;
-    private registerCallbacks;
-    private channelPath;
-    private allowed;
-    private isStale;
-    private poll;
-    private deliverPendingRequests;
-    private call;
-}
-export declare function createTelegramChannels(options: {
-    config: DecisionChannelConfig;
-    credentials: ResolvedDecisionCredentials;
-    store: HumanDecisionStore;
-    configDir?: string;
-    onAnswer: (answer: HumanDecisionChannelAnswer) => Promise<void>;
-    fetchFn?: TelegramFetch;
-    apiBase?: string;
-}): Map<string, TelegramDecisionChannel>;
-export declare function verifyTelegramTokenFile(tokenFile: string, fetchFn?: TelegramFetch, apiBase?: string): Promise<void>;
-export declare function writeDecisionChannelProfile(options: {
-    configDir?: string;
-    audience: string;
-    profile: string;
-    credential: string;
-    tokenFile: string;
-    allowedUserIds: string[];
-    allowedChatIds: string[];
-}): Promise<void>;
-export declare function renderDecisionText(request: HumanDecisionChannelRequest): string;
-export declare function renderTelegramParts(request: HumanDecisionChannelRequest, textLimit?: number): string[];
-export {};