@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/src/workflows/tool-input.ts

@@ -0,0 +1,202 @@
+import { Type, type Static, type TObject, type TProperties, type TSchema } from "typebox";
+import { Parse, ParseError } from "typebox/value";
+
+const noExtraProperties = { additionalProperties: false } as const;
+
+const offsetSchema = Type.Integer({ minimum: 0, description: "Workflow list offset" });
+const workflowSchema = Type.String({
+  description: "Discovered workflow name or workflow file path; required when action is start",
+});
+const inputSchema = Type.Unknown({
+  description: "Checkpoint answer for answer; optional structured workflow input for start",
+});
+const runIdSchema = Type.String({
+  description: "Run id; optional for status and answer",
+});
+const stepSchema = Type.String({
+  description: "Workflow step id; required when action is update or submit",
+});
+const attemptSchema = Type.String({
+  description: "Workflow attempt id; required when action is update or submit",
+});
+const updateSchema = Type.Object(
+  {
+    type: Type.String(),
+    key: Type.String(),
+    data: Type.Record(Type.String(), Type.Unknown()),
+  },
+  noExtraProperties,
+);
+const outputSchema = Type.Unknown({
+  description: "Step output matching the expected shape; required when action is submit",
+});
+
+export const WorkflowActionSchemas = {
+  list: Type.Object(
+    { action: Type.Literal("list"), offset: Type.Optional(offsetSchema) },
+    noExtraProperties,
+  ),
+  start: Type.Object(
+    {
+      action: Type.Literal("start"),
+      workflow: workflowSchema,
+      input: Type.Optional(inputSchema),
+    },
+    noExtraProperties,
+  ),
+  status: Type.Object(
+    { action: Type.Literal("status"), runId: Type.Optional(runIdSchema) },
+    noExtraProperties,
+  ),
+  pause: Type.Object({ action: Type.Literal("pause") }, noExtraProperties),
+  resume: Type.Object({ action: Type.Literal("resume") }, noExtraProperties),
+  cancel: Type.Object({ action: Type.Literal("cancel") }, noExtraProperties),
+  answer: Type.Object(
+    {
+      action: Type.Literal("answer"),
+      input: inputSchema,
+      runId: Type.Optional(runIdSchema),
+    },
+    noExtraProperties,
+  ),
+  update: Type.Object(
+    {
+      action: Type.Literal("update"),
+      step: stepSchema,
+      attempt: attemptSchema,
+      update: updateSchema,
+    },
+    noExtraProperties,
+  ),
+  submit: Type.Object(
+    {
+      action: Type.Literal("submit"),
+      step: stepSchema,
+      attempt: attemptSchema,
+      output: outputSchema,
+    },
+    noExtraProperties,
+  ),
+} as const;
+
+const WorkflowSubmissionActionSchemas = {
+  update: WorkflowActionSchemas.update,
+  submit: WorkflowActionSchemas.submit,
+} as const;
+
+type SchemaValue<Schemas extends Record<string, TSchema>> = Schemas[keyof Schemas];
+
+export type WorkflowToolInput = Static<SchemaValue<typeof WorkflowActionSchemas>>;
+export type WorkflowSubmissionInput = Static<SchemaValue<typeof WorkflowSubmissionActionSchemas>>;
+
+export const WorkflowToolParameters = providerObjectSchema(Object.values(WorkflowActionSchemas));
+export const WorkflowSubmissionToolParameters = providerObjectSchema(
+  Object.values(WorkflowSubmissionActionSchemas),
+);
+
+type ToolInputParser<Output> = (value: unknown) => Output;
+
+const workflowInputParsers = {
+  list: (value) => parseToolInput(WorkflowActionSchemas.list, value, "workflow"),
+  start: (value) => parseToolInput(WorkflowActionSchemas.start, value, "workflow"),
+  status: (value) => parseToolInput(WorkflowActionSchemas.status, value, "workflow"),
+  pause: (value) => parseToolInput(WorkflowActionSchemas.pause, value, "workflow"),
+  resume: (value) => parseToolInput(WorkflowActionSchemas.resume, value, "workflow"),
+  cancel: (value) => parseToolInput(WorkflowActionSchemas.cancel, value, "workflow"),
+  answer: (value) => parseToolInput(WorkflowActionSchemas.answer, value, "workflow"),
+  update: (value) => parseToolInput(WorkflowActionSchemas.update, value, "workflow"),
+  submit: (value) => parseToolInput(WorkflowActionSchemas.submit, value, "workflow"),
+} satisfies Record<keyof typeof WorkflowActionSchemas, ToolInputParser<WorkflowToolInput>>;
+
+const workflowSubmissionInputParsers = {
+  update: (value) =>
+    parseToolInput(WorkflowSubmissionActionSchemas.update, value, "workflow submission"),
+  submit: (value) =>
+    parseToolInput(WorkflowSubmissionActionSchemas.submit, value, "workflow submission"),
+} satisfies Record<
+  keyof typeof WorkflowSubmissionActionSchemas,
+  ToolInputParser<WorkflowSubmissionInput>
+>;
+
+export function parseWorkflowToolInput(value: unknown): WorkflowToolInput {
+  return parseSelectedAction<WorkflowToolInput>(workflowInputParsers, value, "workflow");
+}
+
+export function parseWorkflowSubmissionInput(value: unknown): WorkflowSubmissionInput {
+  return parseSelectedAction<WorkflowSubmissionInput>(
+    workflowSubmissionInputParsers,
+    value,
+    "workflow submission",
+  );
+}
+
+function providerObjectSchema(variants: readonly TObject[]): TObject {
+  const actions: string[] = [];
+  const properties: TProperties = {};
+
+  for (const variant of variants) {
+    const action = variant.properties.action;
+    if (!isRecord(action) || typeof action.const !== "string") {
+      throw new Error("Workflow action schema must have a string action literal.");
+    }
+    actions.push(action.const);
+
+    for (const [name, schema] of Object.entries(variant.properties)) {
+      if (name === "action") continue;
+      const optionalSchema = Type.Optional(schema);
+      const current = properties[name];
+      if (current !== undefined && JSON.stringify(current) !== JSON.stringify(optionalSchema)) {
+        throw new Error(`Workflow property ${JSON.stringify(name)} has incompatible schemas.`);
+      }
+      properties[name] = optionalSchema;
+    }
+  }
+
+  return Type.Object(
+    {
+      action: Type.String({ enum: actions }),
+      ...properties,
+    },
+    noExtraProperties,
+  );
+}
+
+function parseSelectedAction<Output>(
+  parsers: Readonly<Record<string, ToolInputParser<Output>>>,
+  value: unknown,
+  label: string,
+): Output {
+  if (!isRecord(value) || typeof value.action !== "string") throw unknownAction(label);
+  const parser = parsers[value.action];
+  if (parser === undefined) throw unknownAction(label);
+  return parser(value);
+}
+
+function unknownAction(label: string): Error {
+  return new Error(`Invalid ${label} tool input: action is missing or unknown.`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseToolInput<const Schema extends TSchema>(
+  schema: Schema,
+  value: unknown,
+  label: string,
+): Static<Schema> {
+  try {
+    return Parse(schema, value);
+  } catch (error) {
+    if (!(error instanceof ParseError)) throw error;
+    const details = error.cause.errors
+      .slice(0, 3)
+      .map(({ instancePath, message }) => {
+        const field = instancePath.replace(/^\//u, "").replaceAll("/", ".");
+        const clearMessage = message === "must be integer" ? "must be an integer" : message;
+        return `${field ? `${field} ` : ""}${clearMessage}`;
+      })
+      .join("; ");
+    throw new Error(`Invalid ${label} tool input: ${details}`, { cause: error });
+  }
+}

package/src/workflows/types.ts

@@ -177,6 +177,262 @@ export type ShellActionNodeDefinition = WorkflowNodeCommon & {
 
 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
@@ -186,6 +442,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 =
@@ -204,12 +462,88 @@ export type WorkflowPresentationContext = {
   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; workflowName: string }) => MaybePromise<string | undefined>);
+    | ((context: { input: TInput; workflowName: string }) => MaybePromise<string | undefined>);
   /**
    * Optional instructions for a normal assistant response after the run ends.
    * The Pi extension resolves this only after the final state is persisted;
@@ -220,6 +554,8 @@ export type WorkflowDefinition = {
     | ((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;
@@ -308,6 +644,24 @@ export type WorkflowSource =
   | { kind: "builtin"; id: string; revision: string }
   | { kind: "file"; 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";
   /**
@@ -329,6 +683,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;
@@ -346,6 +704,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;
@@ -360,14 +720,24 @@ 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 = {
@@ -460,6 +830,8 @@ export type WorkflowRunManifest = {
   workflowName: string;
   runTitle?: string;
   workflowSource?: WorkflowSource;
+  workflowSources?: WorkflowMountedSource[];
+  definitionDigest?: string;
   startedAt: string;
   finishedAt?: string;
   status: WorkflowRunStatus;