@personaai/react 0.17.0 → 0.18.0

package/README.md

@@ -2,7 +2,7 @@
 
 React SDK for [Persona](https://persona.hasanraiyan.me) — hooks and a context provider for building chat UIs against any Persona backend.
 
-> **v0.9.0.** Requires React 18+. Client-side only — never holds a credential.
+> **v0.17.0.** Requires React 18+. Client-side only — never holds a credential.
 
 ## Install
 
@@ -48,19 +48,61 @@ function Chat() {
 
 | Hook                 | Purpose                                                                                         |
 | -------------------- | ----------------------------------------------------------------------------------------------- |
-| `useChat`            | Streaming chat — messages, send, stop, reload, interrupts, workspace files, ephemeral new chat  |
+| `useChat`            | Streaming chat — messages, send, stop, reload, interrupts, live workspace/todo state, sandbox commands, ephemeral new chat |
 | `useArchitectChat`   | Streaming chat with the Agent Architect co-pilot — same mechanics as `useChat`, no `agentId`     |
 | `useWorkflowStream`  | Live streaming workflow execution — real-time node state tracking, cancellation, and resume    |
 | `useWorkflows`       | Workflow discovery & creation — list, paginate, filter, and create workflows                    |
 | `useWorkflow`        | Single workflow authoring — drafts, publishing, versions, and Mermaid diagrams                 |
 | `useWorkflowRuns`    | Workflow run history — list historical runs, get run details, and cancel in-flight runs        |
 | `useVoice`           | Real-time voice calls (Gemini Live) — start/stop/mute, live transcript, tool calls             |
+| `useMessages`        | Outbound SMS/WhatsApp — plain send or Agent-composed reply (`capabilities.messages`)            |
 | `useThreads`         | Thread CRUD — list, create, delete, rename, reset, archive                                     |
 | `useFiles`           | Upload management — list, upload, delete                                                        |
-| `useMemory`          | Persistent memory — read, write, delete                                                         |
-| `useAgents`          | Agent discovery — list available agents                                                         |
+| `useMemory`          | Persistent memory CRUD — `scope: "user" \| "agent" \| "workspace"` (an Agent's own `/workspace/` files) |
+| `useWorkspaceFiles`  | Thin wrapper over `useMemory` (`scope: "workspace"`) scoped to one Agent — list/get/write/delete |
+| `useAgents`          | Agent discovery — list available agents (`visibility: "public"` or self-owned only)             |
+| `useSkills`          | Skill CRUD — list, create, update, delete, usage                                                |
+| `useKnowledgeBases`  | Knowledge base CRUD + document upload/search                                                    |
+| `useRcpSources`      | RCP source CRUD + test connection                                                               |
+| `useMcpAdmin`        | Self-serve MCP connector CRUD (`scope: "mine"` only)                                            |
+| `useMcp`             | MCP discovery + tool listing                                                                    |
+| `useMcpConnections`  | End-user MCP OAuth connect/disconnect flow                                                      |
 | `useConnection`      | Health check — backend connectivity status                                                      |
 
+## Memory & an Agent's `/workspace/` files
+
+```tsx
+const { memory, getFile, writeFile, deleteFile } = useMemory();
+
+// memory.userFiles (shared across every Agent), memory.agentMemories, and
+// memory.agentWorkspaces are each PersonaMemoryAgentGroup[] — grouped one entry per Agent.
+await writeFile({ path: "/preferences.md", content: "Prefers concise answers.", scope: "user" });
+
+// An Agent's own /workspace/ files — the SAME persistent store its `write_file`/`read_file` tool
+// calls use (NOT a Thread's live/checkpointed state, a different, much narrower thing). Shared
+// across every Thread this Subject has with that Agent, not private to one conversation.
+const report = await getFile({ path: "/outputs/report.md", scope: "workspace", agentId });
+```
+
+`useWorkspaceFiles(agentId)` is a thinner wrapper over the same `scope: "workspace"` calls, scoped
+to one Agent up front — handy for a dedicated file-explorer UI that isn't inside an active chat:
+
+```tsx
+const { files, isLoading, writeFile, deleteFile } = useWorkspaceFiles(agentId);
+```
+
+`useChat()`'s own `files`/`todos` are a different, read-only, per-Thread live snapshot (from
+`STATE_SNAPSHOT` events during a run) — use `useWorkspaceFiles`/`useMemory` for CRUD independent of
+an active chat session.
+
+## Sandbox terminal
+
+If an Agent has `sandboxEnabled: true` (check the active Thread's populated `agentId` — see
+`@personaai/sdk`'s README), its `execute` tool calls are real shell commands in an isolated VM, not
+simulated. `useChat()`'s `sandboxCommands: PersonaSandboxCommand[]` is a pure derived view over the
+same tool-call stream already backing `messages` — `{ toolCallId, command, output, exitCode,
+status }` — enough to build a read-only terminal-style replay with no separate fetch or polling.
+
 ## Voice
 
 Real-time voice calls with an Agent, powered by Gemini Live. Requires your backend to be running
@@ -130,6 +172,60 @@ as a text response). Injected messages get a `voice-`-prefixed id. You still cal
 / `voice.stop()` yourself — `useChat` only owns the transcript-to-feed sync, not the call
 lifecycle.
 
+## SMS and WhatsApp
+
+`useMessages()` sends outbound text messages through your own backend's `POST /messages` /
+`POST /messages/agent` routes (requires `@personaai/runtime@^0.16.0` or an adapter built on it).
+Both routes are opt-in there — mount a runtime with `capabilities: { messages: true }`, or they
+404. That's deliberate: `to` is any E.164 number and every send spends the Project's Twilio
+balance, so it isn't end-user-scoped the way `chat`/`voice` are. Anything your `resolveUser`
+accepts on that mount can text arbitrary numbers through it, so enable it only where that's
+acceptable.
+
+```tsx
+import { useMessages } from "@personaai/react";
+
+function FollowUp({ agentId }: { agentId: string }) {
+  const { send, sendFromAgent, isSending, error, lastDelivery } = useMessages();
+
+  return (
+    <div>
+      {/* Plain send — no Agent involved. */}
+      <button
+        onClick={() => send({ to: "+919876543210", body: "Your order shipped!" })}
+        disabled={isSending}
+      >
+        Text customer
+      </button>
+
+      {/* The Agent runs on the shared conversation and its reply is delivered. */}
+      <button
+        onClick={() =>
+          sendFromAgent({
+            agentId,
+            to: "+919876543210",
+            prompt: "Remind them their appointment is tomorrow at 10.",
+          })
+        }
+        disabled={isSending}
+      >
+        Have the agent follow up
+      </button>
+
+      {lastDelivery && <p>Sent in {lastDelivery.parts} part(s)</p>}
+      {error && <p role="alert">{error.message}</p>}
+    </div>
+  );
+}
+```
+
+The channel is inferred from a `whatsapp:` prefix on `to` (or pass `channel: "whatsapp"`). A body
+is required unless you pass an approved WhatsApp template (`contentSid` + `contentVariables`) —
+business-initiated WhatsApp messages outside the 24-hour session window need one. Conversations
+are keyed by phone number, so SMS, WhatsApp, and voice with the same Agent share one thread;
+`sendFromAgent()` continues it rather than starting fresh. Agents with guarded (`interruptOn`)
+tools are rejected with a 422, same as voice — there's no confirmation flow on a text channel.
+
 ## Ephemeral new chat (0.8.0+)
 
 Create a new chat instantly without minting an empty thread. The real `threadId` is created lazily on the first `sendMessage`.