> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# React SDK

> React hooks and provider for Polpo 0.15.35

## Install

```bash theme={null}
npm install @polpo-ai/sdk@0.15.35 @polpo-ai/react@0.15.35
```

## Provider

```tsx theme={null}
import { PolpoProvider } from "@polpo-ai/react";

export function App() {
  return (
    <PolpoProvider baseUrl="/api/polpo" autoConnect={false}>
      <Dashboard />
    </PolpoProvider>
  );
}
```

Provider props are `baseUrl`, `apiKey`, `fetch`, `apiPrefix`, `user`, `autoConnect`, and `eventFilter`.

<Warning>Do not ship a Cloud project key in a React bundle. Proxy requests through your backend. Direct Cloud SSE also requires an authorization header, which native browser `EventSource` cannot set; keep `autoConnect={false}` unless your application proxy provides authenticated SSE.</Warning>

## Chat

```tsx theme={null}
const {
  messages, sendMessage, sendToolResult,
  sessionId, setSessionId, newSession,
  status, error, isStreaming, pendingToolCall, abort,
} = useChat({
  agent: "backend-dev",
  loop: "implementation-flow",
  onFinish: (text) => console.log(text),
  onSessionCreated: (id) => console.log(id),
  onAskUser: (payload) => showQuestions(payload),
  onToolCall: (call) => console.log(call),
});

await sendMessage("Review the handler");
await sendMessage([
  { type: "text", text: "Analyze this file" },
  { type: "file", file_id: "/workspace/report.pdf" },
]);
await setSessionId(null);
```

`useChat` also accepts `onChunk`, `onError`, `onUpdate`, `onMissionPreview`, `onVaultPreview`, `onOpenFile`, `onNavigateTo`, and `onOpenTab`. `onFinish` receives the final text string. `setSessionId` accepts `string | null` and returns a promise.

## Resource hooks

```tsx theme={null}
const { tasks, createTask, deleteTask, retryTask, refetch } = useTasks();
const { task } = useTask("task_123");
const { missions, createMission, deleteMission } = useMissions();
const { agents, addAgent, updateAgent, removeAgent } = useAgents();
const { processes } = useProcesses();
const { memory, save } = useMemory();
const { memory: agentMemory, save: saveAgentMemory } = useAgentMemory("backend-dev");
```

All create calls must follow the Agent API schemas. For example, tasks require `title`, `description`, and `assignTo`; missions require a JSON-encoded `data` string.

### Mission detail

```tsx theme={null}
const {
  mission, report, executeMission, resumeMission, abortMission,
  createTask, updateTask, deleteTask, reorderTasks,
  addCheckpoint, updateCheckpoint, removeCheckpoint,
  addQualityGate, updateQualityGate, removeQualityGate,
  addTeamMember, updateTeamMember, removeTeamMember,
  updateNotifications,
} = useMission("mission_123");
```

Mission task mutation methods identify tasks by title.

### Sessions

```tsx theme={null}
const {
  sessions, activeSessionId, setActiveSessionId,
  getMessages, renameSession, deleteSession, refetch,
} = useSessions();
```

### Files

```tsx theme={null}
const {
  roots, entries, listFiles, previewFile, readFile,
  uploadFile, createDirectory, renameFile, deleteFile, searchFiles,
} = useFiles("/src");

await uploadFile("/workspace", file, file.name);
```

### Skills

```tsx theme={null}
const {
  skills, createSkill, installSkills, deleteSkill,
  assignSkill, unassignSkill,
} = useSkills();

await createSkill({
  name: "code-review",
  description: "Reviews changes",
  content: "Check correctness and tests.",
});
await installSkills("github:acme/polpo-skills", { skillNames: ["testing"] });
```

### Schedules

```tsx theme={null}
const { schedules, createSchedule, updateSchedule, deleteSchedule } = useSchedules();
await createSchedule({ missionId: "mission_123", expression: "0 2 * * *", recurring: true });
await updateSchedule("mission_123", { enabled: false });
await deleteSchedule("mission_123");
```

### Playbooks

```tsx theme={null}
const { playbooks, loading, createPlaybook, deletePlaybook } = usePlaybooks();
await createPlaybook({
  name: "repo-scan",
  description: "Scan a repository",
  mission: { tasks: [{ title: "Scan", description: "Map the code", assignTo: "analyst" }] },
});
```

### Legacy vault

```tsx theme={null}
const { entries, saveEntry, patchEntry, removeEntry } = useVaultEntries("emailer");
await saveEntry({
  agent: "emailer",
  service: "smtp",
  type: "smtp",
  credentials: { host: "smtp.example.com", user: "bot", pass: "secret" },
});
await patchEntry("emailer", "smtp", { credentials: { pass: "rotated" } });
await removeEntry("emailer", "smtp");
```

Use project Connections for new shared API keys, OAuth accounts, and external integrations. Vault hooks remain for compatibility with agent-scoped secrets.

### Mission delays

```tsx theme={null}
const {
  activeDelays, fetchedDelays, loading, refetch,
  addDelay, updateDelay, removeDelay,
} = useActiveDelays();

await addDelay("mission_123", {
  name: "Wait for data",
  afterTasks: ["Collect data"],
  blocksTasks: ["Analyze data"],
  duration: "PT1H",
});
```

## Direct client and connection status

```tsx theme={null}
const { client, connectionStatus } = usePolpo();
```

`usePolpo` does not expose the internal store. Hooks perform initial fetches; hooks backed by the shared store can also react to SSE when a compatible event connection is configured. Use their `refetch` methods to reconcile after connection gaps.