@personaai/runtime 0.9.5 → 0.11.0

package/dist/index.d.cts

@@ -69,11 +69,15 @@ type RuntimeResponse = RuntimeBufferedResponse | RuntimeStreamResponse | Runtime
 interface RunContext {
     userId: string;
     /** Which endpoint started this run. */
-    kind: 'chat' | 'architect';
-    /** Absent for `kind: 'architect'` — the Architect co-pilot has no target agentId, it builds/edits Agents itself. */
+    kind: 'chat' | 'architect' | 'workflow';
+    /** Absent for `kind: 'architect'` or `kind: 'workflow'` without an agent step. */
     agentId?: string;
+    /** Set when `kind: 'workflow'`. */
+    workflowId?: string;
     threadId?: string;
-    messages: ChatMessageInput[];
+    messages?: ChatMessageInput[];
+    /** Input parameters provided to the workflow run. */
+    input?: unknown;
 }
 interface RunResult {
     /** Assembled assistant text (concatenated TEXT_MESSAGE_CHUNK deltas), same as `ChatResult.text`. */
@@ -87,8 +91,9 @@ interface RunResult {
 interface ErrorContext {
     userId: string | null;
     /** Which stage of request handling the error came from. */
-    phase: 'auth' | 'chat' | 'architect';
+    phase: 'auth' | 'chat' | 'architect' | 'workflow';
     agentId?: string;
+    workflowId?: string;
     threadId?: string;
 }
 interface ToolCallContext {
@@ -99,6 +104,14 @@ interface ToolCallContext {
     toolName: string;
     toolCallId: string;
 }
+interface WorkflowNodeContext {
+    userId: string;
+    workflowId: string;
+    nodeId: string;
+    nodeType: string;
+    nodeLabel: string;
+    input?: unknown;
+}
 interface FileUploadContext {
     userId: string;
     fileName: string;
@@ -136,6 +149,10 @@ interface RuntimeHooks {
     beforeToolCall?(ctx: ToolCallContext): void | Promise<void>;
     /** Fires when the matching TOOL_CALL_RESULT event arrives. `result` is the raw (string or JSON-parsed) tool output. */
     afterToolCall?(ctx: ToolCallContext, result: unknown): void | Promise<void>;
+    /** Fires when a workflow node begins execution (CUSTOM event `workflow_node_started`). */
+    beforeWorkflowNode?(ctx: WorkflowNodeContext): void | Promise<void>;
+    /** Fires when a workflow node finishes execution (CUSTOM event `workflow_node_completed`). `output` is the step output. */
+    afterWorkflowNode?(ctx: WorkflowNodeContext, output: unknown): void | Promise<void>;
     /** Fires after a file finishes uploading via `POST /files`. */
     onFileUpload?(ctx: FileUploadContext): void | Promise<void>;
     /**
@@ -194,6 +211,8 @@ interface RuntimeCapabilities {
     auditLogs?: boolean;
     /** The Architect co-pilot — builds/edits Agents on the caller's behalf via tool calls. @default false */
     architect?: boolean;
+    /** Full Workflow CRUD, draft authoring, versions, and Mermaid export beyond the always-on execution routes. @default false */
+    workflowsWrite?: boolean;
 }
 /**
  * Serves a list of code-defined REST tools (built with `defineRestTool`
@@ -307,6 +326,6 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.9.4";
+declare const RUNTIME_VERSION = "0.10.0";
 
-export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type VoiceSessionCreateContext, createRuntime };
+export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };

package/dist/index.d.ts

@@ -69,11 +69,15 @@ type RuntimeResponse = RuntimeBufferedResponse | RuntimeStreamResponse | Runtime
 interface RunContext {
     userId: string;
     /** Which endpoint started this run. */
-    kind: 'chat' | 'architect';
-    /** Absent for `kind: 'architect'` — the Architect co-pilot has no target agentId, it builds/edits Agents itself. */
+    kind: 'chat' | 'architect' | 'workflow';
+    /** Absent for `kind: 'architect'` or `kind: 'workflow'` without an agent step. */
     agentId?: string;
+    /** Set when `kind: 'workflow'`. */
+    workflowId?: string;
     threadId?: string;
-    messages: ChatMessageInput[];
+    messages?: ChatMessageInput[];
+    /** Input parameters provided to the workflow run. */
+    input?: unknown;
 }
 interface RunResult {
     /** Assembled assistant text (concatenated TEXT_MESSAGE_CHUNK deltas), same as `ChatResult.text`. */
@@ -87,8 +91,9 @@ interface RunResult {
 interface ErrorContext {
     userId: string | null;
     /** Which stage of request handling the error came from. */
-    phase: 'auth' | 'chat' | 'architect';
+    phase: 'auth' | 'chat' | 'architect' | 'workflow';
     agentId?: string;
+    workflowId?: string;
     threadId?: string;
 }
 interface ToolCallContext {
@@ -99,6 +104,14 @@ interface ToolCallContext {
     toolName: string;
     toolCallId: string;
 }
+interface WorkflowNodeContext {
+    userId: string;
+    workflowId: string;
+    nodeId: string;
+    nodeType: string;
+    nodeLabel: string;
+    input?: unknown;
+}
 interface FileUploadContext {
     userId: string;
     fileName: string;
@@ -136,6 +149,10 @@ interface RuntimeHooks {
     beforeToolCall?(ctx: ToolCallContext): void | Promise<void>;
     /** Fires when the matching TOOL_CALL_RESULT event arrives. `result` is the raw (string or JSON-parsed) tool output. */
     afterToolCall?(ctx: ToolCallContext, result: unknown): void | Promise<void>;
+    /** Fires when a workflow node begins execution (CUSTOM event `workflow_node_started`). */
+    beforeWorkflowNode?(ctx: WorkflowNodeContext): void | Promise<void>;
+    /** Fires when a workflow node finishes execution (CUSTOM event `workflow_node_completed`). `output` is the step output. */
+    afterWorkflowNode?(ctx: WorkflowNodeContext, output: unknown): void | Promise<void>;
     /** Fires after a file finishes uploading via `POST /files`. */
     onFileUpload?(ctx: FileUploadContext): void | Promise<void>;
     /**
@@ -194,6 +211,8 @@ interface RuntimeCapabilities {
     auditLogs?: boolean;
     /** The Architect co-pilot — builds/edits Agents on the caller's behalf via tool calls. @default false */
     architect?: boolean;
+    /** Full Workflow CRUD, draft authoring, versions, and Mermaid export beyond the always-on execution routes. @default false */
+    workflowsWrite?: boolean;
 }
 /**
  * Serves a list of code-defined REST tools (built with `defineRestTool`
@@ -307,6 +326,6 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.9.4";
+declare const RUNTIME_VERSION = "0.10.0";
 
-export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type VoiceSessionCreateContext, createRuntime };
+export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };

package/dist/index.js

@@ -131,7 +131,7 @@ function evictStaleRuns(runs, now, graceMs = DEFAULT_RUN_GRACE_MS, maxTracked =
 }
 
 // src/version.ts
-var RUNTIME_VERSION = "0.9.4";
+var RUNTIME_VERSION = "0.10.0";
 
 // src/routes/health.ts
 var alwaysOnCapabilities = {
@@ -140,7 +140,8 @@ var alwaysOnCapabilities = {
   agents: true,
   files: true,
   memory: true,
-  mcpOAuth: true
+  mcpOAuth: true,
+  workflows: true
 };
 var healthRoute = async (_request, ctx) => {
   try {
@@ -294,7 +295,8 @@ function newAccumulator() {
     interrupted: false,
     erroredInBand: false,
     threadCreateFired: false,
-    toolNames: /* @__PURE__ */ new Map()
+    toolNames: /* @__PURE__ */ new Map(),
+    nodeMeta: /* @__PURE__ */ new Map()
   };
 }
 async function processEvent(event, acc, runCtx, hooks) {
@@ -314,7 +316,45 @@ async function processEvent(event, acc, runCtx, hooks) {
       break;
     }
     case EventType.CUSTOM: {
-      if (e.name === "hitl_request" || e.name === "clarification_request") acc.interrupted = true;
+      if (e.name === "hitl_request" || e.name === "clarification_request") {
+        acc.interrupted = true;
+      } else if (e.name === "workflow_node_started") {
+        const val = e.value ?? {};
+        const nodeId = String(val.nodeId ?? "");
+        const nodeType = String(val.nodeType ?? "");
+        const nodeLabel = String(val.nodeLabel ?? "");
+        if (nodeId) acc.nodeMeta.set(nodeId, { nodeType, nodeLabel });
+        if (runCtx.workflowId) {
+          await hooks?.beforeWorkflowNode?.({
+            userId: runCtx.userId,
+            workflowId: runCtx.workflowId,
+            nodeId,
+            nodeType,
+            nodeLabel,
+            input: val.input
+          });
+        }
+      } else if (e.name === "workflow_node_completed") {
+        const val = e.value ?? {};
+        const nodeId = String(val.nodeId ?? "");
+        const meta = acc.nodeMeta.get(nodeId);
+        const nodeType = String(val.nodeType ?? meta?.nodeType ?? "");
+        const nodeLabel = String(val.nodeLabel ?? meta?.nodeLabel ?? "");
+        if (runCtx.workflowId) {
+          await hooks?.afterWorkflowNode?.(
+            {
+              userId: runCtx.userId,
+              workflowId: runCtx.workflowId,
+              nodeId,
+              nodeType,
+              nodeLabel
+            },
+            val.output ?? val
+          );
+        }
+      } else if (e.name === "workflow_node_failed") {
+        acc.erroredInBand = true;
+      }
       break;
     }
     case EventType.RUN_ERROR: {
@@ -421,6 +461,7 @@ var RunDriver = class {
           userId: this.runCtx.userId,
           phase: this.runCtx.kind,
           agentId: this.runCtx.agentId,
+          workflowId: this.runCtx.workflowId,
           threadId: this.runCtx.threadId
         },
         err
@@ -651,6 +692,7 @@ function parseArchitectBody(body) {
   }
   return {
     messages: b.messages,
+    threadId: typeof b.threadId === "string" ? b.threadId : void 0,
     resume: b.resume ?? void 0
   };
 }
@@ -659,6 +701,7 @@ var architectRoute = async (request, ctx) => {
   logger.debug("architectRoute start", { userId: request.userId });
   const body = parseArchitectBody(request.body);
   logger.trace("architectRoute body", {
+    threadId: body.threadId,
     messageCount: body.messages?.length ?? 0,
     hasResume: !!body.resume
   });
@@ -666,18 +709,20 @@ var architectRoute = async (request, ctx) => {
   const runCtx = {
     userId,
     kind: "architect",
+    threadId: body.threadId,
     messages: body.messages
   };
-  logger.debug("beforeRun hook (architect)", { userId });
+  logger.debug("beforeRun hook (architect)", { userId, threadId: body.threadId });
   await ctx.hooks?.beforeRun?.(runCtx);
   logger.trace("beforeRun completed (architect)");
-  logger.debug("starting architect stream");
+  logger.debug("starting architect stream", { threadId: body.threadId });
   const stream = ctx.client.architect.stream({
     messages: body.messages,
+    threadId: body.threadId,
     resume: body.resume
   });
   const runId = crypto.randomUUID();
-  logger.info("architect run created", { runId, userId });
+  logger.info("architect run created", { runId, userId, threadId: body.threadId });
   const driver = new RunDriver(runId, runCtx, stream, ctx.hooks, ctx.mode);
   ctx.runs.set(runId, driver);
   logger.debug("architect driver registered", { runId, trackedRuns: ctx.runs.size });
@@ -1319,6 +1364,158 @@ var listAuditLogs = async (request, ctx) => {
   return json(200, items);
 };
 
+// src/routes/workflows.ts
+var listWorkflows = async (request, ctx) => {
+  const items = await ctx.client.workflows.list({
+    page: toInt(request.query.page),
+    limit: toInt(request.query.limit),
+    search: request.query.search,
+    scope: request.query.scope,
+    visibility: request.query.visibility,
+    isEnabled: request.query.isEnabled !== void 0 ? request.query.isEnabled === "true" : void 0
+  });
+  return json(200, items);
+};
+var createWorkflow = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const input = {
+    name: requireStringField(body, "name"),
+    description: typeof body.description === "string" ? body.description : void 0,
+    visibility: body.visibility,
+    isEnabled: typeof body.isEnabled === "boolean" ? body.isEnabled : void 0,
+    draft: body.draft ?? void 0
+  };
+  const idempotencyKey = request.headers["idempotency-key"];
+  const workflow = await ctx.client.workflows.create(input, idempotencyKey);
+  return json(201, workflow);
+};
+var getWorkflow = async (_request, ctx) => {
+  const workflow = await ctx.client.workflows.get(requireParam(ctx.params, "id"));
+  return json(200, workflow);
+};
+var updateWorkflow = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const input = {
+    name: typeof body.name === "string" ? body.name : void 0,
+    description: typeof body.description === "string" ? body.description : void 0,
+    visibility: body.visibility,
+    isEnabled: typeof body.isEnabled === "boolean" ? body.isEnabled : void 0,
+    draft: body.draft ?? void 0
+  };
+  const updated = await ctx.client.workflows.update(
+    requireParam(ctx.params, "id"),
+    input
+  );
+  return json(200, updated);
+};
+var deleteWorkflow = async (_request, ctx) => {
+  await ctx.client.workflows.delete(requireParam(ctx.params, "id"));
+  return noContent();
+};
+var saveWorkflowDraft = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const draft = body;
+  const updated = await ctx.client.workflows.saveDraft(
+    requireParam(ctx.params, "id"),
+    draft
+  );
+  return json(200, updated);
+};
+var publishWorkflow = async (_request, ctx) => {
+  const version = await ctx.client.workflows.publish(requireParam(ctx.params, "id"));
+  return json(201, version);
+};
+var listWorkflowVersions = async (request, ctx) => {
+  const items = await ctx.client.workflows.listVersions(
+    requireParam(ctx.params, "id"),
+    {
+      page: toInt(request.query.page),
+      limit: toInt(request.query.limit)
+    }
+  );
+  return json(200, items);
+};
+var getWorkflowVersion = async (_request, ctx) => {
+  const versionNum = toInt(ctx.params.version);
+  const version = await ctx.client.workflows.getVersion(
+    requireParam(ctx.params, "id"),
+    versionNum ?? 1
+  );
+  return json(200, version);
+};
+var getWorkflowMermaid = async (_request, ctx) => {
+  const result = await ctx.client.workflows.getMermaid(requireParam(ctx.params, "id"));
+  return json(200, result);
+};
+var listWorkflowRuns = async (request, ctx) => {
+  const items = await ctx.client.workflows.listRuns(requireParam(ctx.params, "id"), {
+    page: toInt(request.query.page),
+    limit: toInt(request.query.limit),
+    status: request.query.status,
+    isDryRun: request.query.isDryRun !== void 0 ? request.query.isDryRun === "true" : void 0
+  });
+  return json(200, items);
+};
+var getWorkflowRun = async (_request, ctx) => {
+  const run = await ctx.client.workflows.getRun(requireParam(ctx.params, "runId"));
+  return json(200, run);
+};
+var cancelWorkflowRun = async (_request, ctx) => {
+  const result = await ctx.client.workflows.cancel(requireParam(ctx.params, "runId"));
+  return json(200, result);
+};
+
+// src/routes/workflowStream.ts
+function parseWorkflowStreamBody(body) {
+  if (body === void 0 || body === null) return {};
+  if (typeof body !== "object") {
+    throw new RuntimeHttpError(400, "INVALID_REQUEST", "Request body must be a JSON object.");
+  }
+  const b = body;
+  return {
+    input: b.input,
+    dryRun: typeof b.dryRun === "boolean" ? b.dryRun : void 0,
+    version: typeof b.version === "number" ? b.version : void 0
+  };
+}
+var workflowStreamRoute = async (request, ctx) => {
+  const workflowId = requireParam(ctx.params, "id");
+  const body = parseWorkflowStreamBody(request.body);
+  const userId = request.userId;
+  const runCtx = {
+    userId,
+    kind: "workflow",
+    workflowId,
+    input: body.input
+  };
+  await ctx.hooks?.beforeRun?.(runCtx);
+  const stream = ctx.client.workflows.stream(workflowId, {
+    input: body.input,
+    dryRun: body.dryRun,
+    version: body.version
+  });
+  const runId = crypto.randomUUID();
+  const driver = new RunDriver(runId, runCtx, stream, ctx.hooks, ctx.mode);
+  ctx.runs.set(runId, driver);
+  try {
+    await driver.waitForFirstFrame();
+  } catch (err) {
+    ctx.runs.delete(runId);
+    throw err;
+  }
+  return {
+    kind: "stream",
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      connection: "keep-alive",
+      "x-persona-run-id": runId
+    },
+    body: withHeartbeats(driver.subscribe(-1), ctx.heartbeatIntervalMs)
+  };
+};
+
 // src/runtime.ts
 function resolveCapabilities(capabilities) {
   return {
@@ -1329,7 +1526,8 @@ function resolveCapabilities(capabilities) {
     knowledge: capabilities?.knowledge ?? false,
     stores: capabilities?.stores ?? false,
     auditLogs: capabilities?.auditLogs ?? false,
-    architect: capabilities?.architect ?? false
+    architect: capabilities?.architect ?? false,
+    workflowsWrite: capabilities?.workflowsWrite ?? false
   };
 }
 function buildRoutes(capabilities) {
@@ -1405,6 +1603,19 @@ function buildRoutes(capabilities) {
       method: "POST",
       pattern: ["mcps", ":id", "call-tool"],
       handler: callMcpTool
+    },
+    // Workflows — read-only discovery & execution always on; authoring ops behind workflowsWrite.
+    { method: "GET", pattern: ["workflows"], handler: listWorkflows },
+    { method: "POST", pattern: ["workflows", ":id", "stream"], handler: workflowStreamRoute },
+    {
+      method: "GET",
+      pattern: ["workflows", "runs", ":runId", "resume"],
+      handler: createResumeRoute("workflow")
+    },
+    {
+      method: "POST",
+      pattern: ["workflows", "runs", ":runId", "cancel"],
+      handler: cancelWorkflowRun
     }
   ];
   if (capabilities.agentsWrite) {
@@ -1505,6 +1716,21 @@ function buildRoutes(capabilities) {
       }
     );
   }
+  if (capabilities.workflowsWrite) {
+    routes.push(
+      { method: "POST", pattern: ["workflows"], handler: createWorkflow },
+      { method: "GET", pattern: ["workflows", ":id"], handler: getWorkflow },
+      { method: "PATCH", pattern: ["workflows", ":id"], handler: updateWorkflow },
+      { method: "DELETE", pattern: ["workflows", ":id"], handler: deleteWorkflow },
+      { method: "PUT", pattern: ["workflows", ":id", "draft"], handler: saveWorkflowDraft },
+      { method: "POST", pattern: ["workflows", ":id", "publish"], handler: publishWorkflow },
+      { method: "GET", pattern: ["workflows", ":id", "versions"], handler: listWorkflowVersions },
+      { method: "GET", pattern: ["workflows", ":id", "versions", ":version"], handler: getWorkflowVersion },
+      { method: "GET", pattern: ["workflows", ":id", "mermaid"], handler: getWorkflowMermaid },
+      { method: "GET", pattern: ["workflows", ":id", "runs"], handler: listWorkflowRuns },
+      { method: "GET", pattern: ["workflows", "runs", ":runId"], handler: getWorkflowRun }
+    );
+  }
   return routes;
 }
 function resolveMode(options) {