@personaai/runtime 0.15.0 → 0.16.0

package/README.md

@@ -5,7 +5,13 @@ shared engine every framework adapter (`@personaai/adapters/express`, `@personaa
 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.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
+**v0.16.0.** New opt-in outbound messaging: `POST /messages` (plain SMS/WhatsApp send) and
+`POST /messages/agent` (the Agent composes the reply), both behind `capabilities.messages` — off by
+default because a send targets any E.164 number the caller names and spends this Project's Twilio
+balance. Also includes `/memory` and `/memory/file`'s `scope: "workspace"` for an Agent's own
+`/workspace/` files, full Workflows engine support
+(`POST /workflows/:id/stream`, `GET /workflows`, `POST /workflows/runs/:runId/cancel`,
+`GET /workflows/runs/:runId/resume`), 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.
@@ -81,10 +87,10 @@ user; `resolveUser` returning `null` or throwing responds `401`.
 | --- | --- | --- |
 | `POST` | `/chat` | `client.chat.stream(agentId, {messages, threadId, resume, contextOverride})`, streamed out as SSE. `agentId`/`messages` required in the body. Response carries an `x-persona-run-id` header — see [Reconnect and resume](#reconnect-and-resume). |
 | `GET` | `/chat/:runId/resume` | Reattaches to the run started by the matching `POST /chat`. See [Reconnect and resume](#reconnect-and-resume). |
-| `GET` | `/threads` | `client.threads.list({page, limit})` |
+| `GET` | `/threads` | `client.threads.list({page, limit})` — each item's `agentId` is populated as `{_id, name, avatar, slug, sandboxEnabled}` |
 | `POST` | `/threads` | `client.threads.create({agentId})` |
 | `POST` | `/threads/bulk-delete` | `client.threads.bulkDelete(ids)` |
-| `GET` | `/threads/:id` | `client.threads.get(id)` |
+| `GET` | `/threads/:id` | `client.threads.get(id)` — `agentId` populated the same way as `list()`; check `sandboxEnabled` here to decide whether to show a Terminal-style UI for this Thread's Agent |
 | `PATCH` | `/threads/:id` | `client.threads.update(id, {title?, isArchived?})` |
 | `DELETE` | `/threads/:id` | `client.threads.delete(id)` → `204` |
 | `GET` | `/threads/:id/messages` | `client.threads.getMessages(id)` — full history + graph state, the same data `chat.stream()` resumes from; load a past conversation on page reopen. |
@@ -96,8 +102,8 @@ user; `resolveUser` returning `null` or throwing responds `401`.
 | `POST` | `/files/bulk-delete` | `client.files.bulkDelete(ids)` |
 | `GET` | `/files/:id` | `client.files.download(id)` — raw bytes, streamed through as `kind: 'binary'` |
 | `DELETE` | `/files/:id` | `client.files.delete(id)` → `204` |
-| `GET` | `/memory` | `client.memory.list()` |
-| `GET` | `/memory/file` | `client.memory.getFile({path, scope?, agentId?})` — `path` query param required |
+| `GET` | `/memory` | `client.memory.list()` → `{userFiles, agentMemories, agentWorkspaces}` |
+| `GET` | `/memory/file` | `client.memory.getFile({path, scope?, agentId?})` — `path` query param required. `scope` is `"user"` (default), `"agent"`, or `"workspace"` (an Agent's own `/workspace/` files); `"agent"`/`"workspace"` require `agentId`. |
 | `PUT` | `/memory/file` | `client.memory.writeFile({path, content, scope?, agentId?})` — creates or overwrites |
 | `DELETE` | `/memory/file` | `client.memory.deleteFile({path, scope?, agentId?})` → `204` |
 | `GET` | `/mcps/:id/oauth/owner/authorize` | `client.mcps.oauth.getOwnerAuthorizeUrl(id)` → `{url}` to redirect the Project owner to |
@@ -171,6 +177,8 @@ how to enable them safely.
 | `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)` |
+| `POST` | `/messages` | `messages` | `client.messages.send({to, body?, channel?, mediaUrl?, contentSid?, contentVariables?})` → `{channel, to, from, messageSids, status, parts}`. `to` is any E.164 number; the channel is inferred from a `whatsapp:` prefix unless given. A body is required unless `contentSid` supplies an approved WhatsApp template. |
+| `POST` | `/messages/agent` | `messages` | `client.messages.sendFromAgent({agentId, to, prompt, channel?, displayName?})` — runs the Agent on the conversation shared by all channels for that number, then delivers its reply. `422` for guarded (`interruptOn`) Agents, same as voice. |
 
 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`
@@ -187,9 +195,15 @@ oversight:
   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, workflow canvas builder/publishing, and full Agent/MCP-server CRUD. **Every one of these defaults to `false`.** Upgrading
+  co-pilot, workflow canvas builder/publishing, full Agent/MCP-server CRUD, and outbound
+  SMS/WhatsApp. **Every one of these defaults to `false`.** Upgrading
   this package never silently exposes new surface to whoever `resolveUser` accepts.
 
+`messages` is the one opt-in flag that isn't configuration: it's a per-request action, like
+`voice/sessions`. It's still off by default because a send reaches any number the caller names
+and spends this Project's Twilio balance — whoever `resolveUser` accepts would be able to text
+arbitrary people, which is a materially larger blast radius than an end-user-scoped chat run.
+
 ```ts
 createRuntime({
   // ...
@@ -203,6 +217,7 @@ createRuntime({
     auditLogs: false,        // default
     architect: false,        // default
     workflowsWrite: false,   // default — authoring and version snapshots
+    messages: false,         // default — sends spend the Project's Twilio balance
   },
 });
 ```
@@ -415,7 +430,7 @@ modes (`mode: 'development' | 'production'`, default `'production'` unless
 
 ## Not yet implemented
 
-This is v0.5.1. Every SDK resource now has a route (see [Routes](#routes)); what's left is either a
+This is v0.16.0. Every SDK resource now has a route (see [Routes](#routes)); what's left is either a
 genuine unclosed gap or an intentional package boundary, not an oversight:
 
 - **Multi-instance reconnect/resume** — see

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.10.0";
+var RUNTIME_VERSION = "0.16.0";
 
 // src/routes/health.ts
 var alwaysOnCapabilities = {
@@ -878,6 +878,92 @@ var createVoiceSession = async (request, ctx) => {
   return json(201, ticket);
 };
 
+// src/routes/messages.ts
+var MESSAGE_CHANNELS = /* @__PURE__ */ new Set(["sms", "whatsapp"]);
+function optionalChannel(body) {
+  const value = body.channel;
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !MESSAGE_CHANNELS.has(value)) {
+    throw new RuntimeHttpError(400, "INVALID_REQUEST", '"channel" must be "sms" or "whatsapp".');
+  }
+  return value;
+}
+function optionalStringField(body, field) {
+  const value = body[field];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new RuntimeHttpError(400, "INVALID_REQUEST", `"${field}" must be a non-empty string.`);
+  }
+  return value;
+}
+function optionalMediaUrl(body) {
+  const value = body.mediaUrl;
+  if (value === void 0) return void 0;
+  if (typeof value === "string" && value.length > 0) return value;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+    return value;
+  }
+  throw new RuntimeHttpError(
+    400,
+    "INVALID_REQUEST",
+    '"mediaUrl" must be a string or an array of strings.'
+  );
+}
+function optionalContentVariables(body) {
+  const value = body.contentVariables;
+  if (value === void 0) return void 0;
+  if (typeof value === "string") return value;
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  throw new RuntimeHttpError(
+    400,
+    "INVALID_REQUEST",
+    '"contentVariables" must be an object or a JSON string.'
+  );
+}
+var sendMessage = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const to = requireStringField(body, "to");
+  const channel = optionalChannel(body);
+  const text = optionalStringField(body, "body");
+  const mediaUrl = optionalMediaUrl(body);
+  const contentSid = optionalStringField(body, "contentSid");
+  const contentVariables = optionalContentVariables(body);
+  if (text === void 0 && contentSid === void 0) {
+    throw new RuntimeHttpError(
+      400,
+      "INVALID_REQUEST",
+      '"body" is required unless "contentSid" is provided.'
+    );
+  }
+  const delivery = await ctx.client.messages.send({
+    to,
+    ...channel ? { channel } : {},
+    ...text ? { body: text } : {},
+    ...mediaUrl ? { mediaUrl } : {},
+    ...contentSid ? { contentSid } : {},
+    ...contentVariables ? { contentVariables } : {}
+  });
+  return json(200, delivery);
+};
+var sendAgentMessage = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const agentId = requireStringField(body, "agentId");
+  const to = requireStringField(body, "to");
+  const prompt = requireStringField(body, "prompt");
+  const channel = optionalChannel(body);
+  const displayName = optionalStringField(body, "displayName");
+  const delivery = await ctx.client.messages.sendFromAgent({
+    agentId,
+    to,
+    prompt,
+    ...channel ? { channel } : {},
+    ...displayName ? { displayName } : {}
+  });
+  return json(200, delivery);
+};
+
 // src/routes/agents.ts
 var listAgents = async (request, ctx) => {
   const items = await ctx.client.agents.list({
@@ -1607,7 +1693,8 @@ function resolveCapabilities(capabilities) {
     rcpSources: capabilities?.rcpSources ?? false,
     auditLogs: capabilities?.auditLogs ?? false,
     architect: capabilities?.architect ?? false,
-    workflowsWrite: capabilities?.workflowsWrite ?? false
+    workflowsWrite: capabilities?.workflowsWrite ?? false,
+    messages: capabilities?.messages ?? false
   };
 }
 function buildRoutes(capabilities) {
@@ -1698,6 +1785,12 @@ function buildRoutes(capabilities) {
       handler: cancelWorkflowRun
     }
   ];
+  if (capabilities.messages) {
+    routes.push(
+      { method: "POST", pattern: ["messages"], handler: sendMessage },
+      { method: "POST", pattern: ["messages", "agent"], handler: sendAgentMessage }
+    );
+  }
   if (capabilities.agentsWrite) {
     routes.push(
       { method: "POST", pattern: ["agents"], handler: createAgent },