@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/src/client/index.ts

@@ -0,0 +1,24 @@
+export {
+  WorkflowClient,
+  WorkflowClientVersionError,
+  type WorkflowClientOptions,
+} from "./client.js";
+export {
+  CLIENT_PROTOCOL_SCHEMA,
+  CLIENT_PROTOCOL_VERSION,
+  clientSocketPath,
+  type ClientEvent,
+  type ClientHello,
+  type ClientOperation,
+  type ClientOutcome,
+  type ClientRequest,
+  type ClientResponse,
+} from "./protocol.js";
+export type {
+  OriginActivityReport,
+  WorkflowDisplay,
+  WorkflowDisplayStatus,
+  WorkflowRunSummary,
+  WorkflowRunView,
+  WorkflowSessionView,
+} from "./view.js";

package/src/client/materialize.ts

@@ -0,0 +1,228 @@
+import type { JsonValue } from "../state/json.js";
+import type { WorkflowClient } from "./client.js";
+import type { WorkflowSessionView } from "./view.js";
+
+type ViewerPageKind =
+  | "steps"
+  | "trace"
+  | "session_entries"
+  | "session_events"
+  | "settings"
+  | "follow_ups"
+  | "updates";
+
+type ViewerPage = {
+  start: number;
+  total: number;
+  items: JsonValue[];
+};
+
+/** Assemble one complete run revision and hydrate every referenced value. */
+export async function materializeRunView(
+  client: WorkflowClient,
+  value: JsonValue,
+): Promise<JsonValue> {
+  if (
+    !isRecord(value) ||
+    value.schema !== "pi-workflows.run-view.v1" ||
+    typeof value.runId !== "string" ||
+    !Number.isSafeInteger(value.revision)
+  ) {
+    return value;
+  }
+  const view = structuredClone(value);
+  const runId = value.runId;
+  const revision = value.revision as number;
+  const state = isRecord(view.state) ? view.state : {};
+  view.state = state;
+  const initialSteps = Array.isArray(state.steps) ? state.steps : [];
+  const steps = await completePage(client, runId, revision, "steps", {
+    start: safeInteger(view.stepStart, 0),
+    total: safeInteger(view.stepTotal, initialSteps.length),
+    items: initialSteps,
+  });
+  state.steps = steps;
+  view.stepStart = 0;
+  view.stepTotal = steps.length;
+
+  const tracePage = pageValue(view.tracePage);
+  const trace = await completePage(client, runId, revision, "trace", tracePage);
+  view.tracePage = { ...(isRecord(view.tracePage) ? view.tracePage : {}), start: 0, items: trace };
+
+  const session = isRecord(view.session) ? view.session : {};
+  view.session = session;
+  const entryPage = pageValue(session.entryPage);
+  const entries = await completePage(client, runId, revision, "session_entries", entryPage);
+  session.entryPage = {
+    ...(isRecord(session.entryPage) ? session.entryPage : {}),
+    start: 0,
+    items: entries,
+  };
+  const eventPage = pageValue(session.eventPage);
+  const events = await completePage(client, runId, revision, "session_events", eventPage);
+  session.eventPage = {
+    ...(isRecord(session.eventPage) ? session.eventPage : {}),
+    start: 0,
+    items: events,
+  };
+
+  const initialSettings = Array.isArray(view.settingsScopes) ? view.settingsScopes : [];
+  const settings = await completePage(client, runId, revision, "settings", {
+    start: safeInteger(view.settingsStart, 0),
+    total: safeInteger(view.settingsTotal, initialSettings.length),
+    items: initialSettings,
+  });
+  view.settingsScopes = settings;
+  view.settingsStart = 0;
+  view.settingsTotal = settings.length;
+
+  const followUpQueue = isRecord(view.followUpQueue) ? view.followUpQueue : {};
+  const initialFollowUps = Array.isArray(followUpQueue.items) ? followUpQueue.items : [];
+  const followUps = await completePage(client, runId, revision, "follow_ups", {
+    start: safeInteger(view.followUpStart, 0),
+    total: safeInteger(view.followUpTotal, initialFollowUps.length),
+    items: initialFollowUps,
+  });
+  followUpQueue.items = followUps;
+  view.followUpQueue = followUpQueue;
+  view.followUpStart = 0;
+  view.followUpTotal = followUps.length;
+
+  const initialUpdates = Array.isArray(view.updates) ? view.updates : [];
+  const updates = await completePage(client, runId, revision, "updates", {
+    start: safeInteger(view.updateStart, 0),
+    total: safeInteger(view.updateTotal, initialUpdates.length),
+    items: initialUpdates,
+  });
+  view.updates = updates;
+  state.updates = updates;
+  view.updateStart = 0;
+  view.updateTotal = updates.length;
+
+  const hydrated = await client.hydrateContent(runId, view);
+  if (!isRecord(hydrated)) return hydrated;
+  const workflow = isRecord(hydrated.workflow) ? hydrated.workflow : null;
+  if (workflow !== null && isDefinitionSnapshot(workflow.content)) {
+    hydrated.workflow = workflow.content;
+  }
+  materializeGraphHistory(hydrated);
+  return hydrated;
+}
+
+/** Assemble and hydrate the one session view consumed by the Pi extension. */
+export async function materializeSessionView(
+  client: WorkflowClient,
+  session: WorkflowSessionView,
+): Promise<WorkflowSessionView> {
+  const run =
+    session.run === null
+      ? null
+      : ((await materializeRunView(client, session.run as unknown as JsonValue)) as unknown as
+          | WorkflowSessionView["run"]
+          | null);
+  const pendingInteractions = await Promise.all(
+    session.pendingInteractions.map(async (interaction) => {
+      const runId = isRecord(interaction) ? interaction.runId : undefined;
+      return typeof runId === "string"
+        ? await client.hydrateContent(runId, interaction)
+        : interaction;
+    }),
+  );
+  return { ...session, run, pendingInteractions };
+}
+
+async function completePage(
+  client: WorkflowClient,
+  runId: string,
+  revision: number,
+  kind: ViewerPageKind,
+  initial: ViewerPage,
+): Promise<JsonValue[]> {
+  if (
+    initial.start < 0 ||
+    initial.total < 0 ||
+    initial.start + initial.items.length > initial.total
+  ) {
+    throw new Error(`Workflow ${kind} page is invalid`);
+  }
+  const items = Array<JsonValue | undefined>(initial.total).fill(undefined);
+  for (const [offset, item] of initial.items.entries()) items[initial.start + offset] = item;
+  for (;;) {
+    const cursor = items.findIndex((item) => item === undefined);
+    if (cursor < 0) return items as JsonValue[];
+    const response = await client.request({
+      operation: "view.page",
+      runId,
+      expectedRevision: revision,
+      payload: { kind, cursor },
+    });
+    if (response.outcome !== "accepted" || !isRecord(response.receipt)) {
+      throw new Error(response.error ?? `Workflow ${kind} page is unavailable`);
+    }
+    const page = response.receipt;
+    if (
+      page.schema !== "pi-workflows.run-page.v1" ||
+      page.runId !== runId ||
+      page.revision !== revision ||
+      page.kind !== kind ||
+      page.cursor !== cursor ||
+      !Number.isSafeInteger(page.start) ||
+      page.total !== initial.total ||
+      !Array.isArray(page.items)
+    ) {
+      throw new Error(`Workflow ${kind} page changed while loading`);
+    }
+    const start = page.start as number;
+    if (start < 0 || start + page.items.length > initial.total) {
+      throw new Error(`Workflow ${kind} page is outside its history`);
+    }
+    let added = 0;
+    for (const [offset, item] of page.items.entries()) {
+      const index = start + offset;
+      if (items[index] === undefined) added += 1;
+      items[index] = item;
+    }
+    if (added === 0) throw new Error(`Workflow ${kind} page made no progress`);
+  }
+}
+
+function materializeGraphHistory(view: Record<string, JsonValue>): void {
+  const history = isRecord(view.graphHistory) ? view.graphHistory : undefined;
+  if (
+    history === undefined ||
+    !Array.isArray(history.steps) ||
+    !Array.isArray(history.transitions) ||
+    !history.transitions.every((transition) => typeof transition === "string")
+  ) {
+    throw new Error("Workflow graph history is invalid");
+  }
+  view.graphSteps = history.steps;
+  view.graphStepStart = 0;
+  view.graphStepTotal = history.steps.length;
+  view.takenTransitions = history.transitions;
+  view.takenTransitionStart = 0;
+  view.takenTransitionTotal = history.transitions.length;
+}
+
+function pageValue(value: JsonValue | undefined): ViewerPage {
+  const record = isRecord(value) ? value : {};
+  const items = Array.isArray(record.items) ? record.items : [];
+  const start = safeInteger(record.start, 0);
+  return {
+    start,
+    total: safeInteger(record.total, start + items.length),
+    items,
+  };
+}
+
+function safeInteger(value: JsonValue | undefined, fallback: number): number {
+  return Number.isSafeInteger(value) && (value as number) >= 0 ? (value as number) : fallback;
+}
+
+function isDefinitionSnapshot(value: JsonValue | undefined): value is Record<string, JsonValue> {
+  return isRecord(value) && value.schema === "pi-workflows.definition-snapshot.v1";
+}
+
+function isRecord(value: unknown): value is Record<string, JsonValue> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/client/protocol.ts

@@ -0,0 +1,327 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+
+export const CLIENT_PROTOCOL_VERSION = 1;
+export const CLIENT_PROTOCOL_SCHEMA = "pi-workflows.client.v1" as const;
+export const MAX_PROTOCOL_MESSAGE_BYTES = 1024 * 1024;
+
+export const CLIENT_OPERATIONS = [
+  "run.start",
+  "run.pause",
+  "run.resume",
+  "run.cancel",
+  "run.status",
+  "run.list",
+  "checkpoint.answer",
+  "decision.answer",
+  "interaction.submit",
+  "interaction.update",
+  "notification.claim",
+  "notification.deliver",
+  "turn.claim",
+  "turn.resolve",
+  "controller.list",
+  "controller.get",
+  "controller.apply",
+  "controller.reconcile",
+  "controller.delete",
+  "host.status",
+  "host.stop",
+  "view.runs.watch",
+  "view.runs.page",
+  "view.run.get",
+  "view.run.watch",
+  "view.run.unwatch",
+  "view.page",
+  "view.content",
+  "view.session.watch",
+  "activity.report",
+  "state.status",
+  "state.verify",
+  "state.backup",
+  "state.prune",
+] as const;
+
+export const CLIENT_OUTCOMES = [
+  "accepted",
+  "adopted",
+  "rejected",
+  "conflict",
+  "notFound",
+  "claimLost",
+  "unavailable",
+] as const;
+
+export const CLIENT_EVENTS = [
+  "runs",
+  "run_snapshot",
+  "run_patch",
+  "run_page",
+  "session_snapshot",
+  "unavailable",
+] as const;
+
+export type ClientOperation = (typeof CLIENT_OPERATIONS)[number];
+export type ClientOutcome = (typeof CLIENT_OUTCOMES)[number];
+export type ClientEventName = (typeof CLIENT_EVENTS)[number];
+
+export type ClientHello = {
+  schema: typeof CLIENT_PROTOCOL_SCHEMA;
+  type: "hello";
+  connectionId: string;
+  packageVersion: string;
+};
+
+export type ClientRequest = {
+  schema: typeof CLIENT_PROTOCOL_SCHEMA;
+  type: "request";
+  requestId: string;
+  clientId: string;
+  operation: ClientOperation;
+  idempotencyKey: string;
+  runId?: string;
+  expectedRevision?: number;
+  payload: JsonValue;
+};
+
+export type ClientResponse = {
+  schema: typeof CLIENT_PROTOCOL_SCHEMA;
+  type: "response";
+  requestId: string;
+  outcome: ClientOutcome;
+  revision?: number;
+  receipt?: JsonValue;
+  error?: string;
+};
+
+export type ClientEvent = {
+  schema: typeof CLIENT_PROTOCOL_SCHEMA;
+  type: "event";
+  subscriptionId: string;
+  event: ClientEventName;
+  revision?: number;
+  runId?: string;
+  payload: JsonValue;
+};
+
+export type ClientMessage = ClientHello | ClientRequest | ClientResponse | ClientEvent;
+
+export class ClientProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ClientProtocolError";
+  }
+}
+
+export function encodeProtocolMessage(message: ClientMessage): Buffer {
+  const encoded = Buffer.from(canonicalJson(message), "utf8");
+  if (encoded.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new ClientProtocolError("Client protocol message exceeds 1 MiB");
+  }
+  return encoded;
+}
+
+export function encodeProtocolLine(message: ClientMessage): Buffer {
+  const encoded = Buffer.concat([encodeProtocolMessage(message), Buffer.from("\n")]);
+  if (encoded.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new ClientProtocolError("Client protocol message exceeds 1 MiB");
+  }
+  return encoded;
+}
+
+export function parseClientMessage(line: string | Buffer): ClientMessage {
+  const value = parseProtocolValue(line);
+  if (value.schema !== CLIENT_PROTOCOL_SCHEMA) {
+    throw new ClientProtocolError("Invalid client protocol schema");
+  }
+  switch (value.type) {
+    case "hello":
+      return parseHello(value);
+    case "request":
+      return parseRequestValue(value);
+    case "response":
+      return parseResponseValue(value);
+    case "event":
+      return parseEventValue(value);
+    default:
+      throw new ClientProtocolError("Invalid client protocol message type");
+  }
+}
+
+export function parseClientRequest(line: string | Buffer): ClientRequest {
+  const message = parseClientMessage(line);
+  if (message.type !== "request") throw new ClientProtocolError("Expected client request");
+  return message;
+}
+
+export function parseClientResponse(line: string | Buffer): ClientResponse {
+  const message = parseClientMessage(line);
+  if (message.type !== "response") throw new ClientProtocolError("Expected client response");
+  return message;
+}
+
+export function clientRequestFingerprint(request: ClientRequest): Buffer {
+  return createHash("sha256")
+    .update(canonicalJson({ ...request, requestId: undefined }))
+    .digest();
+}
+
+export function clientSocketPath(databasePath: string): string {
+  const stateDirectory = path.dirname(path.resolve(databasePath));
+  if (process.platform === "win32") {
+    const suffix = createHash("sha256").update(stateDirectory).digest("hex").slice(0, 24);
+    return `\\\\.\\pipe\\pi-workflows-${suffix}`;
+  }
+  return path.join(stateDirectory, "host", "host.sock");
+}
+
+export class NdjsonFrameDecoder {
+  private buffered = Buffer.alloc(0);
+
+  push(chunk: Buffer): Buffer[] {
+    this.buffered = Buffer.concat([this.buffered, chunk]);
+    if (this.buffered.byteLength > MAX_PROTOCOL_MESSAGE_BYTES && !this.buffered.includes(0x0a)) {
+      throw new ClientProtocolError("Client protocol message exceeds 1 MiB");
+    }
+    const frames: Buffer[] = [];
+    for (;;) {
+      const newline = this.buffered.indexOf(0x0a);
+      if (newline < 0) break;
+      const frame = this.buffered.subarray(0, newline);
+      this.buffered = this.buffered.subarray(newline + 1);
+      if (frame.byteLength === 0) continue;
+      if (frame.byteLength + 1 > MAX_PROTOCOL_MESSAGE_BYTES) {
+        throw new ClientProtocolError("Client protocol message exceeds 1 MiB");
+      }
+      frames.push(frame);
+    }
+    return frames;
+  }
+}
+
+function parseHello(value: Record<string, unknown>): ClientHello {
+  requireExactKeys(value, ["schema", "type", "connectionId", "packageVersion"]);
+  requireOpaqueId(value.connectionId, "connectionId");
+  requireText(value.packageVersion, "packageVersion");
+  return value as ClientHello;
+}
+
+function parseRequestValue(value: Record<string, unknown>): ClientRequest {
+  requireExactKeys(value, [
+    "schema",
+    "type",
+    "requestId",
+    "clientId",
+    "operation",
+    "idempotencyKey",
+    "runId",
+    "expectedRevision",
+    "payload",
+  ]);
+  requireOpaqueId(value.requestId, "requestId");
+  requireOpaqueId(value.clientId, "clientId");
+  requireOpaqueId(value.idempotencyKey, "idempotencyKey");
+  if (!CLIENT_OPERATIONS.includes(value.operation as ClientOperation)) {
+    throw new ClientProtocolError("Invalid client request operation");
+  }
+  if (value.runId !== undefined) requireOpaqueId(value.runId, "runId");
+  requireOptionalRevision(value.expectedRevision, "request expectedRevision");
+  if (!Object.hasOwn(value, "payload")) {
+    throw new ClientProtocolError("Client request payload is required");
+  }
+  canonicalJson(value.payload);
+  return value as ClientRequest;
+}
+
+function parseResponseValue(value: Record<string, unknown>): ClientResponse {
+  requireExactKeys(value, [
+    "schema",
+    "type",
+    "requestId",
+    "outcome",
+    "revision",
+    "receipt",
+    "error",
+  ]);
+  requireOpaqueId(value.requestId, "requestId");
+  if (!CLIENT_OUTCOMES.includes(value.outcome as ClientOutcome)) {
+    throw new ClientProtocolError("Invalid client response outcome");
+  }
+  requireOptionalRevision(value.revision, "response revision");
+  if (value.error !== undefined) requireText(value.error, "response error");
+  if (value.receipt !== undefined) canonicalJson(value.receipt);
+  return value as ClientResponse;
+}
+
+function parseEventValue(value: Record<string, unknown>): ClientEvent {
+  requireExactKeys(value, [
+    "schema",
+    "type",
+    "subscriptionId",
+    "event",
+    "revision",
+    "runId",
+    "payload",
+  ]);
+  requireOpaqueId(value.subscriptionId, "subscriptionId");
+  if (!CLIENT_EVENTS.includes(value.event as ClientEventName)) {
+    throw new ClientProtocolError("Invalid client event name");
+  }
+  requireOptionalRevision(value.revision, "event revision");
+  if (value.runId !== undefined) requireOpaqueId(value.runId, "runId");
+  if (!Object.hasOwn(value, "payload")) {
+    throw new ClientProtocolError("Client event payload is required");
+  }
+  canonicalJson(value.payload);
+  return value as ClientEvent;
+}
+
+function parseProtocolValue(line: string | Buffer): Record<string, unknown> {
+  const buffer = Buffer.isBuffer(line) ? line : Buffer.from(line, "utf8");
+  if (buffer.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new ClientProtocolError("Client protocol message exceeds 1 MiB");
+  }
+  let value: unknown;
+  try {
+    value = parseJson(buffer.toString("utf8"));
+  } catch {
+    throw new ClientProtocolError("Client protocol message is not valid canonical JSON");
+  }
+  if (!isRecord(value)) throw new ClientProtocolError("Client protocol message must be an object");
+  if (canonicalJson(value) !== buffer.toString("utf8")) {
+    throw new ClientProtocolError("Client protocol message must use canonical JSON");
+  }
+  return value;
+}
+
+function requireExactKeys(value: Record<string, unknown>, allowed: readonly string[]): void {
+  const allowedKeys = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      throw new ClientProtocolError(`Unknown client protocol field: ${key}`);
+    }
+  }
+}
+
+function requireOpaqueId(value: unknown, field: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0 || Buffer.byteLength(value) > 256) {
+    throw new ClientProtocolError(`${field} must be nonempty text of at most 256 bytes`);
+  }
+}
+
+function requireText(value: unknown, field: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ClientProtocolError(`${field} must be nonempty text`);
+  }
+}
+
+function requireOptionalRevision(value: unknown, field: string): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || (value as number) < 0)) {
+    throw new ClientProtocolError(`${field} must be a non-negative integer`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/client/resolver.ts

@@ -0,0 +1,26 @@
+import type { JsonValue } from "../state/json.js";
+
+export type ResolvedWorkflowLaunch = {
+  schema: "pi-workflows.resolved-launch.v1";
+  workflowName: string;
+  workflowSourceRef: string;
+  workflowSource: JsonValue;
+  definitionDigest: string;
+  definitionSnapshot: JsonValue;
+};
+
+export type ResolvedControllerInitialization = {
+  schema: "pi-workflows.resolved-controller-initialization.v1";
+  controllerName: string;
+  controllerPath: string;
+  sourceHash: string;
+  initialStatus: JsonValue;
+};
+
+export type ResolvedSettingsChange = {
+  schema: "pi-workflows.resolved-settings-change.v1";
+  definitionDigest: string;
+  patch: JsonValue;
+  settings: JsonValue;
+  paths: JsonValue;
+};