@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/dist/workflows/types.d.ts

@@ -141,6 +141,219 @@ export type ShellActionNodeDefinition = WorkflowNodeCommon & {
     updates?: ShellActionUpdates;
 };
 export type ActionNodeDefinition = FunctionActionNodeDefinition | ShellActionNodeDefinition;
+export type HumanDecisionTextInput = {
+    kind: "text";
+    name: string;
+    prompt: string;
+    minLength: number;
+    maxLength: number;
+};
+export type HumanDecisionChoice = {
+    label: string;
+    input?: HumanDecisionTextInput;
+};
+export type HumanDecisionChoiceMap = Record<string, HumanDecisionChoice>;
+export type DecisionPresentationParagraph = {
+    kind: "paragraph";
+    text: string;
+};
+export type DecisionPresentationSection = {
+    kind: "section";
+    title: string;
+};
+export type DecisionPresentationBullets = {
+    kind: "bullets";
+    items: string[];
+};
+export type DecisionPresentationFields = {
+    kind: "fields";
+    items: Array<{
+        label: string;
+        value: string;
+    }>;
+};
+export type DecisionPresentationPreformatted = {
+    kind: "preformatted";
+    text: string;
+};
+export type DecisionPresentationBlock = DecisionPresentationParagraph | DecisionPresentationSection | DecisionPresentationBullets | DecisionPresentationFields | DecisionPresentationPreformatted;
+export type DecisionPresentation = {
+    schema: "pi-workflows.decision-presentation.v1";
+    summary: string;
+    blocks: DecisionPresentationBlock[];
+};
+export type LegacyHumanDecisionPrompt = {
+    title: string;
+    body: unknown;
+    subject?: never;
+    presentation?: never;
+    revision?: never;
+    /** Optional absolute expiry. An expired request cannot accept an answer. */
+    expiresAt?: string;
+};
+export type PresentedHumanDecisionPrompt<TSubject = unknown> = {
+    title: string;
+    subject: TSubject;
+    presentation: DecisionPresentation;
+    body?: never;
+    /** Positive revision of the decision subject and presentation. Defaults to 1. */
+    revision?: number;
+    /** Optional absolute expiry. An expired request cannot accept an answer. */
+    expiresAt?: string;
+};
+export type HumanDecisionPrompt = LegacyHumanDecisionPrompt | PresentedHumanDecisionPrompt;
+export type HumanDecisionAudience = string | ((context: WorkflowNodeContext) => MaybePromise<string>);
+export type HumanDecisionNodeContract = {
+    audience: HumanDecisionAudience;
+    choices: HumanDecisionChoiceMap;
+    request: (context: WorkflowNodeContext) => MaybePromise<HumanDecisionPrompt>;
+};
+type HumanDecisionRequestCommon = {
+    decisionId: string;
+    requestDigest: string;
+    runId: string;
+    workflowName: string;
+    nodeId: string;
+    attemptId: string;
+    audience: string;
+    title: string;
+    choices: HumanDecisionChoiceMap;
+    createdAt: string;
+    expiresAt?: string;
+};
+export type HumanDecisionRequestV1 = HumanDecisionRequestCommon & {
+    schema: "pi-workflows.human-decision-request.v1";
+    body: unknown;
+};
+export type HumanDecisionRequestV2 = HumanDecisionRequestCommon & {
+    schema: "pi-workflows.human-decision-request.v2";
+    subject: unknown;
+    presentation: DecisionPresentation;
+    revision: number;
+    subjectDigest: string;
+    presentationDigest: string;
+};
+export type HumanDecisionRequest = HumanDecisionRequestV1 | HumanDecisionRequestV2;
+/**
+ * Complete operator-facing request passed to a decision channel. It excludes
+ * the canonical subject and legacy body by design.
+ */
+export type HumanDecisionChannelRequest = HumanDecisionRequestCommon & {
+    schema: "pi-workflows.human-decision-channel-request.v1";
+    sourceSchema: HumanDecisionRequest["schema"];
+    presentation: DecisionPresentation;
+    presentationDigest: string;
+    revision: number;
+};
+export type HumanDecisionResponse = {
+    choice: string;
+    input?: Record<string, string>;
+};
+export type HumanDecisionAnswerSource = {
+    channel: string;
+    actorId: string;
+    eventId: string;
+};
+export type HumanDecisionSubmission = HumanDecisionResponse & {
+    decisionId: string;
+    requestDigest: string;
+    source: HumanDecisionAnswerSource;
+    idempotencyKey: string;
+};
+type AcceptedHumanDecisionCommon = {
+    decisionId: string;
+    requestDigest: string;
+    response: HumanDecisionResponse;
+    source: HumanDecisionAnswerSource;
+    idempotencyKey: string;
+    acceptedAt: string;
+    answerDigest: string;
+};
+export type AcceptedHumanDecisionV1 = AcceptedHumanDecisionCommon & {
+    schema: "pi-workflows.human-decision-accepted.v1";
+};
+export type AcceptedHumanDecisionV2 = AcceptedHumanDecisionCommon & {
+    schema: "pi-workflows.human-decision-accepted.v2";
+    subjectDigest: string;
+    presentationDigest: string;
+    revision: number;
+};
+export type AcceptedHumanDecision = AcceptedHumanDecisionV1 | AcceptedHumanDecisionV2;
+type HumanDecisionReceiptCommon = {
+    decisionId: string;
+    requestDigest: string;
+    nodeId: string;
+    response: HumanDecisionResponse;
+    acceptedAt: string;
+    answerDigest: string;
+};
+export type HumanDecisionReceiptV1 = HumanDecisionReceiptCommon & {
+    schema: "pi-workflows.human-decision-receipt.v1";
+};
+export type HumanDecisionReceiptV2 = HumanDecisionReceiptCommon & {
+    schema: "pi-workflows.human-decision-receipt.v2";
+    subjectDigest: string;
+    presentationDigest: string;
+    revision: number;
+};
+export type HumanDecisionReceipt = HumanDecisionReceiptV1 | HumanDecisionReceiptV2;
+export type HumanDecisionDeliveryRecordV1 = {
+    schema: "pi-workflows.human-decision-delivery.v1";
+    attemptId: string;
+    decisionId: string;
+    requestDigest: string;
+    channel: string;
+    state: "intent" | "confirmed" | "failed" | "unknown";
+    createdAt: string;
+    finishedAt?: string;
+    messageCount?: number;
+    errorCode?: string;
+};
+export type HumanDecisionDeliveryRecordV2 = {
+    schema: "pi-workflows.human-decision-delivery.v2";
+    attemptId: string;
+    decisionId: string;
+    requestDigest: string;
+    presentationDigest: string;
+    channel: string;
+    phase: "intent" | "part" | "complete";
+    state: "intent" | "confirmed" | "failed" | "unknown";
+    createdAt: string;
+    finishedAt?: string;
+    recipientIndex?: number;
+    partIndex?: number;
+    partCount?: number;
+    contentDigest?: string;
+    messageCount?: number;
+    errorCode?: string;
+};
+export type HumanDecisionDeliveryRecord = HumanDecisionDeliveryRecordV1 | HumanDecisionDeliveryRecordV2;
+export type HumanDecisionSettlementRecord = {
+    schema: "pi-workflows.human-decision-settlement.v1";
+    attemptId: string;
+    decisionId: string;
+    requestDigest: string;
+    channel: string;
+    state: "confirmed" | "failed";
+    createdAt: string;
+    finishedAt: string;
+    errorCode?: string;
+};
+export type HumanDecisionCancellationRecord = {
+    schema: "pi-workflows.human-decision-cancellation.v1";
+    decisionId: string;
+    requestDigest: string;
+    cancelledAt: string;
+    reason: "cancelled" | "expired";
+};
+export type HumanDecisionContinuationRecord = {
+    schema: "pi-workflows.human-decision-continuation.v1";
+    decisionId: string;
+    requestDigest: string;
+    parentRunId: string;
+    runId: string;
+    createdAt: string;
+};
 /**
  * A pause point. The run terminates with status `waiting` so a human (or an
  * external trigger) can decide how to continue. The optional `run` callback
@@ -150,6 +363,8 @@ export type CheckpointNodeDefinition = WorkflowNodeCommon & {
     nodeType: "checkpoint";
     summary?: string;
     run?: (context: WorkflowNodeContext) => MaybePromise<unknown>;
+    /** Typed verified-human request. Still executes as a checkpoint node. */
+    humanDecision?: HumanDecisionNodeContract;
 };
 export type WorkflowNodeDefinition = AgentNodeDefinition | ComputeNodeDefinition | NotifyNodeDefinition | ActionNodeDefinition | CheckpointNodeDefinition;
 export type WorkflowPresentationContext = {
@@ -160,11 +375,58 @@ export type WorkflowPresentationContext = {
     /** Aborted if a new run starts, the session closes, or prompt generation times out. */
     signal: AbortSignal;
 };
-export type WorkflowDefinition = {
+/** Runtime parser that also carries its normalized TypeScript result type. */
+export type WorkflowValueParser<T> = (value: unknown) => MaybePromise<T>;
+export type WorkflowExitDefinition<TOutput = unknown> = {
+    /** Successful terminal node whose output leaves through this exit. */
+    from: string;
+    /** Optional runtime output normalizer and validator. */
+    validate?: WorkflowValueParser<TOutput>;
+};
+export type WorkflowExitMap = Record<string, WorkflowExitDefinition>;
+export type WorkflowInputOf<TWorkflow> = TWorkflow extends WorkflowDefinition<infer TInput, any, any> ? TInput : unknown;
+export type WorkflowExitOutputs<TWorkflow> = TWorkflow extends WorkflowDefinition<any, infer TExits, any> ? {
+    [K in keyof TExits]: TExits[K] extends WorkflowExitDefinition<infer TOutput> ? TOutput : unknown;
+} : Record<string, unknown>;
+export type WorkflowIncludedResult<TWorkflow> = {
+    [K in keyof WorkflowExitOutputs<TWorkflow>]: {
+        exit: K;
+        output: WorkflowExitOutputs<TWorkflow>[K];
+    };
+}[keyof WorkflowExitOutputs<TWorkflow>];
+export type WorkflowIncludeDefinition<TWorkflow extends WorkflowDefinition<any, any, any> = WorkflowDefinition<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 direct definition that supplies the contract for a dynamic reference. */
+    contract?: TWorkflow;
+};
+export type WorkflowIncludeMap = Record<string, WorkflowIncludeDefinition>;
+export type WorkflowIncludeExitReference<TIncludes extends WorkflowIncludeMap> = {
+    [K in keyof TIncludes & string]: TIncludes[K] extends WorkflowIncludeDefinition<infer TWorkflow> ? `${K}.${Extract<keyof WorkflowExitOutputs<TWorkflow>, string>}` : never;
+}[keyof TIncludes & string];
+export type WorkflowTypedEdge<TNodes extends Record<string, WorkflowNodeDefinition>, TIncludes extends WorkflowIncludeMap> = {
+    from: (keyof TNodes & string) | WorkflowIncludeExitReference<TIncludes>;
+    to: (keyof TNodes & string) | (keyof TIncludes & string);
+} | {
+    from: keyof TNodes & string;
+    switch: {
+        on: string;
+        cases: Record<string, (keyof TNodes & string) | (keyof TIncludes & string)>;
+    };
+};
+export type WorkflowDefinition<TInput = any, TExits extends WorkflowExitMap = WorkflowExitMap, TIncludes extends WorkflowIncludeMap = WorkflowIncludeMap> = {
     name: string;
+    /** Module URL used to attest directly imported child workflow files. */
+    source?: string;
+    /** Stable public input-and-exit contract identity for compatible overrides. */
+    contractId?: string;
+    /** Optional runtime input normalizer and validator. */
+    input?: WorkflowValueParser<TInput>;
     /** Optional human-readable run title (static or derived from input). */
     title?: string | ((context: {
-        input: unknown;
+        input: TInput;
         workflowName: string;
     }) => MaybePromise<string | undefined>);
     /**
@@ -175,6 +437,8 @@ export type WorkflowDefinition = {
     presentationPrompt?: string | ((context: WorkflowPresentationContext) => MaybePromise<string | undefined>);
     startAt: string;
     nodes: Record<string, WorkflowNodeDefinition>;
+    includes?: TIncludes;
+    exits?: TExits;
     edges: WorkflowEdge[];
     /** Guard against unbounded loops. Defaults to the engine's maxSteps. */
     maxSteps?: number;
@@ -255,6 +519,21 @@ export type WorkflowSource = {
     path: string;
     hash: string;
 };
+export type WorkflowMountedSource = {
+    mountPath: string[];
+    workflowName: string;
+    source: WorkflowSource;
+};
+export type WorkflowMountSnapshot = {
+    mountPath: string[];
+    workflowName: string;
+    entryNode: string;
+    exits: Record<string, string>;
+    maxSteps?: number;
+};
+export type WorkflowCompositionSnapshot = {
+    mounts: WorkflowMountSnapshot[];
+};
 export type WorkflowRunState = {
     schema: "pi-workflows.run-state.v1";
     /**
@@ -276,6 +555,10 @@ export type WorkflowRunState = {
     runTitle?: string;
     /** Stable built-in identity or immutable file source used by this run. */
     workflowSource?: WorkflowSource;
+    /** Sorted immutable sources used by included workflow mounts. */
+    workflowSources?: WorkflowMountedSource[];
+    /** SHA-256 of the fully resolved definition snapshot. */
+    definitionDigest?: string;
     /** Legacy fields accepted only by the bounded built-in migration. */
     workflowPath?: string;
     workflowHash?: string;
@@ -293,6 +576,8 @@ export type WorkflowRunState = {
     currentAttemptId?: string;
     currentNodeStartedAt?: string;
     statusDetail?: string;
+    /** Redacted verified-human receipt carried by a continuation run. */
+    humanDecision?: HumanDecisionReceipt;
     /** True while the run is held at a step boundary by a pause request. */
     paused?: boolean;
     waitingOn?: string;
@@ -306,13 +591,23 @@ export type WorkflowNodeSnapshot = {
     summary?: string;
     expectedOutput?: string;
     actionExecution?: "function" | "shell";
+    mountPath?: string[];
+    localNodeId?: string;
+    includeTransition?: "entry" | "exit";
+    humanDecision?: {
+        audience: string;
+        dynamicAudience?: boolean;
+        choices: HumanDecisionChoiceMap;
+    };
 };
 export type WorkflowDefinitionSnapshot = {
     schema: "pi-workflows.definition-snapshot.v1";
     name: string;
+    contractId?: string;
     startAt: string;
     nodes: Record<string, WorkflowNodeSnapshot>;
     edges: WorkflowEdge[];
+    composition?: WorkflowCompositionSnapshot;
 };
 export type WorkflowTraceEvent = {
     seq: number;
@@ -388,6 +683,8 @@ export type WorkflowRunManifest = {
     workflowName: string;
     runTitle?: string;
     workflowSource?: WorkflowSource;
+    workflowSources?: WorkflowMountedSource[];
+    definitionDigest?: string;
     startedAt: string;
     finishedAt?: string;
     status: WorkflowRunStatus;
@@ -501,3 +798,4 @@ export type WorkflowEngineOptions = {
     /** Observer invoked after every persisted trace event. */
     onEvent?: (event: WorkflowTraceEvent, state: WorkflowRunState) => void;
 };
+export {};

package/docs/CONTROLLERS.md

@@ -25,7 +25,7 @@ The first production use case is pull request automation. A controller can obser
 
 ## Boundaries
 
-The graph engine remains the execution layer for finite work. It does not import the controller runtime. The controller runtime may start workflows through a narrow scheduler interface.
+The graph engine remains the execution layer for finite work. A finite workflow can include another finite workflow in the same run through `includeWorkflow()`. Use a controller child run when work needs an independent retry history, stable request key, parallel lifecycle, or indefinite reconciliation. The graph engine does not import the controller runtime. The controller runtime may start workflows through a narrow scheduler interface.
 
 The Pi extension is a host. It discovers definitions, displays status, and supplies the conversation-backed agent executor while Pi is running. A headless host can use the same controller runtime with another `AgentStepExecutor`.
 

package/docs/DESIGN_PHILOSOPHY.md

@@ -10,7 +10,7 @@ A new primitive belongs in the engine only when it solves a general problem that
 
 ## Composition
 
-Workflows combine `agent`, `compute`, `action`, `notify`, and `checkpoint` nodes through explicit edges. `shell` is the command form of an action. Built-in workflows should use the same public parts available to workflow authors.
+Workflows combine `agent`, `compute`, `action`, `notify`, and `checkpoint` nodes through explicit edges. `shell` is the command form of an action. A finite workflow can include another finite workflow through typed input and named exits. This keeps shared prompts and routing in one source. Built-in workflows should use the same public parts available to workflow authors.
 
 Shared behavior should usually start as a data format or pure helper used by a workflow composition. For example, progress can be structured data carried through a general update channel instead of a special progress node.