@personaai/runtime 0.9.5 → 0.11.0

package/README.md

@@ -1,14 +1,11 @@
 # @personaai/runtime
 
 Framework-agnostic runtime engine for [Persona](https://persona.hasanraiyan.me). This is the
-shared engine every framework adapter (`@personaai/express`, `@personaai/nextjs`, ...) is meant
+shared engine every framework adapter (`@personaai/adapters/express`, `@personaai/adapters/nextjs/server`, ...) is meant
 to be a thin translation layer over — see
 [the SDK Ecosystem plan](https://github.com/hasanraiyan/agent-marketplace/blob/feat/ai/product-research/11-sdk-new/package-ecosystem.md).
 
-**v0.5.1.** The first framework adapter has shipped: [`@personaai/express` v0.1.0](https://persona.hasanraiyan.me/guides/express/quickstart)
-(Wave 3 of the
-[SDK Ecosystem plan](https://github.com/hasanraiyan/agent-marketplace/blob/feat/ai/product-research/11-sdk-new/package-ecosystem.md))
-is published and mounts this runtime as an Express Router. For non-Express hosts, see
+**v0.10.0.** Added full Workflows engine support (`POST /workflows/:id/stream`, `GET /workflows`, `POST /workflows/runs/:runId/cancel`, `GET /workflows/runs/:runId/resume`), `workflowsWrite` gated authoring capability, and `beforeWorkflowNode`/`afterWorkflowNode` lifecycle hooks. Unified adapter [`@personaai/adapters`](https://persona.hasanraiyan.me/guides/express/quickstart) provides `express`/`nextjs`/`nestjs` bindings. For non-covered hosts, see
 [Quickstart](#quickstart) for how to run it directly against raw Node `http`, and
 [Not yet implemented](#not-yet-implemented) for what's missing before it's a complete Level 2
 runtime.
@@ -46,7 +43,7 @@ world — see `RunContext`/the design notes below for why this boundary is absol
 
 ## Quickstart (raw Node `http`)
 
-Using Express? Skip this section and use the published [`@personaai/express` adapter](https://persona.hasanraiyan.me/guides/express/quickstart).
+Using Express, Next.js, or NestJS? Skip this section and use the published [`@personaai/adapters` adapters](https://persona.hasanraiyan.me/guides/express/quickstart) — `import { toExpressRouter } from '@personaai/adapters/express'`, `import { createPersonaHandler } from '@personaai/adapters/nextjs/server'`, or `import { PersonaModule } from '@personaai/adapters/nestjs'`.
 For every other host there's no `@personaai/node` adapter package yet, so this release ships a
 small, tested bridge at [`examples/node-handler.ts`](./examples/node-handler.ts) in this repo
 for running the runtime directly against Node's `http` module, just enough to demo/smoke-test
@@ -108,6 +105,10 @@ user; `resolveUser` returning `null` or throwing responds `401`.
 | `GET` | `/mcps/:id/oauth/user/status` | `client.mcps.oauth.getUserConnectionStatus(id)` |
 | `DELETE` | `/mcps/:id/oauth/user/connection` | `client.mcps.oauth.disconnectUserConnection(id)` → `204` |
 | `DELETE` | `/mcps/:id/oauth/owner/connection` | `client.mcps.oauth.disconnectOwnerConnection(id)` → `204` |
+| `GET` | `/workflows` | `client.workflows.list({page, limit, search, scope, visibility, isEnabled})` — read-only discovery of available workflows. |
+| `POST` | `/workflows/:id/stream` | `client.workflows.stream(id, {input, dryRun, version})` — multi-step workflow execution with node-level AG-UI event streaming. Response carries `x-persona-run-id`. |
+| `GET` | `/workflows/runs/:runId/resume` | Reattaches to in-flight or recent workflow execution with frame replay (`?since=<seq>`). |
+| `POST` | `/workflows/runs/:runId/cancel` | `client.workflows.cancel(runId)` → aborts active execution. |
 | `GET` | `/health` | `client.whoami()` → `{status, version, capabilities}`. Does **not** require `resolveUser` — it's a liveness/capability probe, not a user-scoped call. |
 
 `scope` for memory routes is `'user'` (default) or `'agent'` (`agentId` then required).
@@ -159,12 +160,21 @@ how to enable them safely.
 | `GET` | `/stores/:id/files` | `stores` | `client.stores.listFiles(id)` |
 | `GET`/`PUT`/`DELETE` | `/stores/:id/file` | `stores` | `client.stores.getFile/writeFile/deleteFile(id, {path, content?})` |
 | `GET` | `/audit-logs` | `auditLogs` | `client.auditLogs.list({page, limit, eventType})` |
-| `POST` | `/architect` | `architect` | `client.architect.stream({messages, resume})`, streamed out as SSE, same `x-persona-run-id`/reconnect mechanics as `/chat`. No `agentId` — the Architect builds/edits the caller's own Agents. |
+| `POST` | `/architect` | `architect` | `client.architect.stream({messages, threadId, resume})`, streamed out as SSE, same `x-persona-run-id`/reconnect mechanics as `/chat`. No `agentId` — the Architect builds/edits the caller's own Agents. `threadId` resumes a named Architect conversation (has no effect without an asserted external user). |
 | `GET` | `/architect/:runId/resume` | `architect` | Reattaches to the matching `POST /architect` run. |
+| `POST` | `/workflows` | `workflowsWrite` | `client.workflows.create(input)` |
+| `GET`/`PATCH`/`DELETE` | `/workflows/:id` | `workflowsWrite` | `client.workflows.get/update/delete(id)` |
+| `PUT` | `/workflows/:id/draft` | `workflowsWrite` | `client.workflows.saveDraft(id, draft)` |
+| `POST` | `/workflows/:id/publish` | `workflowsWrite` | `client.workflows.publish(id)` |
+| `GET` | `/workflows/:id/versions` | `workflowsWrite` | `client.workflows.listVersions(id)` |
+| `GET` | `/workflows/:id/versions/:version` | `workflowsWrite` | `client.workflows.getVersion(id, version)` |
+| `GET` | `/workflows/:id/mermaid` | `workflowsWrite` | `client.workflows.getMermaid(id)` → `{mermaid}` |
+| `GET` | `/workflows/:id/runs` | `workflowsWrite` | `client.workflows.listRuns(id, params)` |
+| `GET` | `/workflows/runs/:runId` | `workflowsWrite` | `client.workflows.getRun(runId)` |
 
 A disabled capability's routes are simply absent from the route table — a request to one 404s
 (or, where an always-on route shares the same path with a different method, e.g. `POST /agents`
-while only `GET /agents` is always-on, `405`) rather than 403, so a disabled capability leaks no
+while only `GET /agents` is always-on, or `POST /workflows` while `GET /workflows` is always-on, `405`) rather than 403, so a disabled capability leaks no
 information about what it would have done.
 
 ## Capabilities — admin surface
@@ -173,25 +183,26 @@ The routes above are split into two trust tiers, and this is a deliberate design
 oversight:
 
 - **Always on**: things an end user does in their own chat session — send messages, manage their
-  own conversations/files/memory, connect their own MCP account. Scoped entirely to whichever
+  own conversations/files/memory, connect their own MCP account, run workflows. Scoped entirely to whichever
   user `resolveUser` returns.
 - **Opt-in via `capabilities`**: Project-level configuration — LLM provider credentials, skill
   authoring, knowledge base and vector store management, security audit logs, an agent-building
-  co-pilot, and full Agent/MCP-server CRUD. **Every one of these defaults to `false`.** Upgrading
+  co-pilot, workflow canvas builder/publishing, and full Agent/MCP-server CRUD. **Every one of these defaults to `false`.** Upgrading
   this package never silently exposes new surface to whoever `resolveUser` accepts.
 
 ```ts
 createRuntime({
   // ...
   capabilities: {
-    agentsWrite: false, // default
-    mcps: false,        // default
-    providers: false,   // default — holds API keys, think hard before enabling
-    skills: false,       // default
-    knowledge: false,    // default
-    stores: false,        // default
-    auditLogs: false,     // default
-    architect: false,     // default
+    agentsWrite: false,    // default
+    mcps: false,           // default
+    providers: false,      // default — holds API keys, think hard before enabling
+    skills: false,          // default
+    knowledge: false,       // default
+    stores: false,           // default
+    auditLogs: false,        // default
+    architect: false,        // default
+    workflowsWrite: false,   // default — authoring and version snapshots
   },
 });
 ```
@@ -415,9 +426,8 @@ genuine unclosed gap or an intentional package boundary, not an oversight:
   design**, not a gap: see [Capabilities](#capabilities--admin-surface). A capability is on or off
   per mount; anything finer belongs in `resolveUser` or a hook, not the runtime.
 - Framework adapters beyond the shipped ones (`@personaai/node`, `@personaai/fastify`,
-  `@personaai/hono`) — **by design**, not a gap: this package is the foundation they're meant to
-  wrap, not a replacement for them. `@personaai/nextjs` (Wave 2), `@personaai/express` and
-  `@personaai/nestjs` (Wave 3) have shipped.
+   `@personaai/hono`) — **by design**, not a gap: this package is the foundation they're meant to
+   wrap, not a replacement for them. `@personaai/adapters` (unified `express`/`nextjs`/`nestjs` via subpaths, Wave 3) has shipped — legacy names `@personaai/nextjs`/`@personaai/express`/`@personaai/nestjs` are deprecated shims.
 
 ## Roadmap
 

package/dist/index.cjs

@@ -159,7 +159,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 = {
@@ -168,7 +168,8 @@ var alwaysOnCapabilities = {
   agents: true,
   files: true,
   memory: true,
-  mcpOAuth: true
+  mcpOAuth: true,
+  workflows: true
 };
 var healthRoute = async (_request, ctx) => {
   try {
@@ -322,7 +323,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) {
@@ -342,7 +344,45 @@ async function processEvent(event, acc, runCtx, hooks) {
       break;
     }
     case import_sdk3.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 import_sdk3.EventType.RUN_ERROR: {
@@ -449,6 +489,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
@@ -679,6 +720,7 @@ function parseArchitectBody(body) {
   }
   return {
     messages: b.messages,
+    threadId: typeof b.threadId === "string" ? b.threadId : void 0,
     resume: b.resume ?? void 0
   };
 }
@@ -687,6 +729,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
   });
@@ -694,18 +737,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 });
@@ -1347,6 +1392,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 {
@@ -1357,7 +1554,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) {
@@ -1433,6 +1631,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) {
@@ -1533,6 +1744,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) {