# open-pr

Adopt this skill: https://proskills.md/skills/other/cloudflare-agents-agent-think-skills-open-pr

Page: https://proskills.md/skills/other/cloudflare-agents-agent-think-skills-open-pr
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: agent-think/skills/open-pr/SKILL.md
size: 8033
upstream: https://github.com/cloudflare/agents/blob/main/agent-think/skills/open-pr/SKILL.md

````text
---
name: open-pr
description: Take a cloudflare/agents GitHub issue plus any repro findings and one-shot a fix PR — branch, change, test, push, and open the PR linked to the issue.
---

The current user message contains an `<agent-think-run>` envelope with
`repository`, `issue`, `instruction`, `requested-by`, and (when available)
`trigger-comment-id`.
Use those values exactly. Never infer or substitute another target from examples,
workspace contents, GitHub searches, or concurrent issues. If the envelope or a
required field is absent, stop without cloning/editing/pushing/posting and return a
structured skipped result. When `trigger-comment-id` is present, your first
container action is the liveness reaction:

```bash
gh api repos/<repository>/issues/comments/<trigger-comment-id>/reactions \
  -f content=rocket
```

Produce a focused fix PR, authored as **yourself** — the agent-think GitHub App.
Do not impersonate any user.

The instruction is the free-form text the user typed after `@agent-think` (it
may be empty). Treat it as a direct instruction — e.g. constraints
on the fix, a preferred approach, or a pointer to the suspect area — and weight
it highly, but stay within the scope of the issue.

All `gh`, `git`, `npm`, `curl`, and `wrangler` commands must run on the
`container` backend (`bash({ command, backend: "container" })`) — the `shell`
backend has no real binaries or network. `gh` is already authenticated as the
app; use it directly (no token handling). Work under `/workspace`; put long
logs and disposable scratch files in container-local `/temp`.

## 0. Clone the repo

Clone the target repo directly under `/workspace` using its repository name
(`cloudflare/agents` → `/workspace/agents`):

```bash
REPO_DIR="/workspace/$(basename <repo>)"
if [ ! -d "$REPO_DIR/.git" ]; then
  git clone https://github.com/<repo>.git "$REPO_DIR"
fi
cd "$REPO_DIR"
```

## 1. Gather everything known

```bash
gh issue view <issueNumber> --repo <repo> --json title,body,labels,author,comments
```

Read the body and **every comment**. In particular look for a comment from the
prior repro run (`@agent-think repro`): it may contain a minimal reproduction, a live URL,
observed-vs-expected behavior, and a **root-cause hypothesis** pointing at a
file/line. Use it as your starting point — do not re-derive what is already
known.

**Decide if this is fixable in one shot.** If the issue is a feature request
needing design, is too vague, spans many subsystems, or you cannot locate a
confident root cause, stop: return `prOpened: false`, `skipped: true`, and a
`summary` explaining why. Post a brief, polite comment saying the pr-agent is
skipping it and what additional detail would help; begin it with
`Requested by @<requestedBy>` when the run envelope has a requester.

## 2. Locate the root cause

With the repo cloned at `$REPO_DIR`, read the relevant code in
`packages/agents`, `packages/think`, etc. Confirm the hypothesis (or form your
own) by reading the actual implementation. Identify the smallest change that
fixes the reported behavior.

## 3. Branch and set commit identity

Commit as the agent-think app itself:

```bash
git config user.name "agent-think[bot]"
git config user.email "agent-think[bot]@users.noreply.github.com"
BRANCH="fix/issue-<issueNumber>-$(date +%s)"
git checkout -b "$BRANCH"
```

## 4. Make the fix

- Smallest correct change. Fewest files. Match the existing code style.
- Add or update a **test** that fails before the fix and passes after, when the
  area is testable.
- Add a changeset if the repo uses them (`.changeset/`) for a user-facing fix:
  create a markdown file following the existing format in `.changeset/`.
- Update **examples and docs** when the change affects behavior they show:
  if an `examples/*` app or a `docs/`/README section demonstrates the code you
  touched, keep it truthful in the same PR.

## 5. Verify

Install and run the affected package's checks (monorepo uses pnpm + Nx):

```bash
# NOISY commands (installs, builds, test suites) MUST be redirected to a
# container-local /temp file and tailed — streaming megabytes of live output
# through the session can kill it irrecoverably:
mkdir -p /temp
CI=1 pnpm install --frozen-lockfile --reporter=append-only \
  > /temp/install.log 2>&1 || (tail -40 /temp/install.log; false)
tail -20 /temp/install.log
# Prefer scoped/affected runs; fall back to package scripts.
pnpm -w exec oxfmt --check . || pnpm -w exec oxfmt --write .
pnpm -w exec oxlint . || true
# Run the relevant package's typecheck + tests, redirected the same way:
pnpm --filter <package> typecheck > /temp/typecheck.log 2>&1; tail -30 /temp/typecheck.log
pnpm --filter <package> test > /temp/test.log 2>&1; tail -40 /temp/test.log
```

(`/temp` is outside the `/workspace` mount and is not synchronized.)

Record whether tests passed in `testsPassed`. If you cannot make tests pass and
the failure is your change's fault, fix it; if tests are unrelated/flaky, note
that in the PR body. Do not open a PR whose own new test fails.

## 6. Deploy a live demo of the PR

Every PR ships with a **temporary deployment demoing the change** so reviewers
click a link and see the fixed behavior instead of imagining it.

1. Build the fixed package(s) in the repo and pack them:

```bash
pnpm --filter <package> build
(cd packages/<package> && npm pack --pack-destination /workspace)   # -> /workspace/<package>-x.y.z.tgz
```

2. Build a minimal demo app in `/workspace/demo-<issueNumber>` that exercises
   the fixed path. Follow the activated reproduce skill's **"Minimal frontend
   (required)"** recipe — same 7 files — but install the packed tarball so the
   demo runs YOUR fix:

```bash
npm install /workspace/<package>-x.y.z.tgz
```

If the repro run left a `repro/issue-<issueNumber>` branch, start from that
project instead and just swap the dependency to the packed build — the same
UI then demos broken-before / fixed-after.

3. Deploy and verify the fix is actually observable in the page:

```bash
npm run deploy      # vite build && wrangler deploy --temporary
curl -sS -i "<demoUrl>/" | head -5
```

Capture the `https://...workers.dev` URL as `demoUrl`. Ignore the claim URL
the deploy prints — it never goes in a PR.

Use judgment: changes with no runtime surface (docs-only, types-only, CI) skip
the demo — say so in the PR body ("no runtime surface to demo") rather than
deploying something meaningless.

## 7. Commit, push, open the PR

```bash
git status --short
git add -A
git commit -m "fix: <concise description> (#<issueNumber>)"
git push -u origin "$BRANCH"

gh pr create --repo <repo> \
  --base main \
  --head "$BRANCH" \
  --title "fix: <concise description> (#<issueNumber>)" \
  --body-file /temp/pr-body.md
```

Write the PR body outside the checkout at `/temp/pr-body.md`. It must include:

- `Requested by @<requestedBy>` near the top, using the exact sanitized
  `requested-by` mention from the run envelope (omit only when it is `unknown`).
- `Closes #<issueNumber>` so the issue auto-links.
- **What was wrong** (root cause, citing the file/line).
- **What changed** and why this is the minimal fix.
- **Testing**: what you added/ran and the result.
- **Demo**: phrase it exactly like "Demo URL (expires after 60 mins):
  <demoUrl>" plus one line of click instructions and a note that it runs the
  packed build from this branch. If skipped, one line on why.
- A link back to the repro-agent's reproduction (comment and/or the
  `repro/issue-<issueNumber>` branch) if one exists.
- A "🤖 generated by the pr-agent — please review carefully" footer.

Capture the PR URL and branch name.

Do **not** post an acknowledgement or "opened a PR" comment on the issue. The
PR links back to the issue via `Closes #<issueNumber>`. The only case where you
comment is the skip path in the **Gather everything known** step (no PR
exists to show).

## 8. Return the structured result

Return exactly:

- `prOpened` (boolean)
- `skipped` (boolean)
- `summary` (string — one or two sent
````

## File: README.md
upstream: https://github.com/cloudflare/agents/blob/main/README.md

````text
# Cloudflare Agents

[![npm version](https://img.shields.io/npm/v/agents)](https://www.npmjs.com/package/agents)
[![npm downloads](https://img.shields.io/npm/dw/agents)](https://www.npmjs.com/package/agents)

![npm install agents](assets/npm-install-agents.svg)

Agents are persistent, stateful execution environments for agentic workloads, powered by Cloudflare [Durable Objects](https://developers.cloudflare.com/durable-objects/). Each agent has its own state, storage, and lifecycle — with built-in support for real-time communication, scheduling, AI model calls, MCP, workflows, and more.

Agents hibernate when idle and wake on demand. You can run millions of them — one per user, per session, per game room — each costs nothing when inactive.

```sh
npm create cloudflare@latest -- --template cloudflare/agents-starter
```

Or add to an existing project:

```sh
npm install agents
```

**[Read the docs](https://developers.cloudflare.com/agents/)** — getting started, API reference, guides, and more.

## Quick Example

A counter agent with persistent state, callable methods, and real-time sync to a React frontend:

```typescript
// server.ts
import { Agent, routeAgentRequest, callable } from "agents";

export type CounterState = { count: number };

export class CounterAgent extends Agent<Env, CounterState> {
  initialState = { count: 0 };

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }

  @callable()
  decrement() {
    this.setState({ count: this.state.count - 1 });
    return this.state.count;
  }
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};
```

```tsx
// client.tsx
import { useAgent } from "agents/react";
import { useState } from "react";
import type { CounterAgent, CounterState } from "./server";

function Counter() {
  const [count, setCount] = useState(0);

  const agent = useAgent<CounterAgent, CounterState>({
    agent: "CounterAgent",
    onStateUpdate: (state) => setCount(state.count)
  });

  return (
    <div>
      <span>{count}</span>
      <button onClick={() => agent.stub.increment()}>+</button>
      <button onClick={() => agent.stub.decrement()}>-</button>
    </div>
  );
}
```

State changes sync to all connected clients automatically. Call methods like they're local functions.

The agent is a Durable Object, so it needs a binding and a SQLite migration in `wrangler.jsonc`:

```jsonc
{
  "name": "counter",
  "main": "server.ts",
  "compatibility_date": "2026-06-11",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }]
}
```

## Features

| Feature                 | Description                                                                     |
| ----------------------- | ------------------------------------------------------------------------------- |
| **Persistent State**    | Syncs to all connected clients, survives restarts                               |
| **Callable Methods**    | Type-safe RPC via the `@callable()` decorator                                   |
| **Sub-agents**          | Parent/child DO composition via facets, nested routing, and typed parent lookup |
| **Agent Tools**         | Run chat-capable sub-agents as tools with streaming child timelines             |
| **Scheduling**          | One-time, recurring, and cron-based tasks                                       |
| **WebSockets**          | Real-time bidirectional communication with lifecycle hooks                      |
| **AI Chat**             | Message persistence, resumable streaming, server/client tool execution          |
| **MCP**                 | Act as MCP servers or connect as MCP clients (HTTP, SSE, RPC, elicitation)      |
| **WebMCP**              | Expose page-local tools or bridge remote MCP tools to browser agents            |
| **Workflows**           | Durable multi-step tasks with human-in-the-loop approval                        |
| **Email**               | Send, receive, and reply via Cloudflare Email Service                           |
| **Voice**               | Continuous STT, streaming TTS, VAD, interruption, SFU utilities                 |
| **Browser Agents**      | Run agents in the browser tab with `agents/browser`                             |
| **Code Mode**           | LLMs generate executable TypeScript instead of individual tool calls            |
| **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem          |
| **x402 Payments**       | Pay-per-call APIs and tools via the x402 protocol                               |
| **Observability**       | Built-in tracing, metrics, and structured logs                                  |
| **SQL**                 | Direct SQLite queries via Durable Objects                                       |
| **React Hooks**         | `useAgent`, `useAgentChat`, `useVoiceAgent` for frontend integration            |
| **Vanilla JS Client**   | `AgentClient` and `VoiceClient` for non-React environments                      |

## Packages

| Package                                                 | Description                                                                                   |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [`agents`](packages/agents)                             | Core SDK — Agents, routing, Voice, Channels, scheduling, MCP, workflows, x402, browser agents |
| [`@cloudflare/ai-chat`](packages/ai-chat)               | Higher-level AI chat — persistent messages, resumable streaming, tool execution               |
| [`@cloudflare/think`](packages/think)                   | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools  |
| [`@cloudflare/codemode`](packages/codemode)             | LLMs write executable code that calls your tools, instead of one tool call at a time          |
| [`@cloudflare/shell`](packages/shell)                   | Deprecated: use [`@cloudflare/computer`](https://github.com/cloudflare/computer) workspaces   |
| [`@cloudflare/voice`](packages/voice)                   | Deprecated compatibility wrapper for the `agents/voice` exports                               |
| [`@cloudflare/worker-bundler`](packages/worker-bundler) | Build and bundle Workers at runtime, for use with the Worker Loader binding                   |
| [`hono-agents`](packages/hono-agents)                   | Hono middleware for adding agents to Hono apps                                                |

> AI-chat modules used to live in `agents/ai-chat-agent`, `agents/chat`, `agents/ai-react`, and `agents/ai-types`. Those entry points still re-export, but they're deprecated — import from `@cloudflare/ai-chat` directly. New chat-from-scratch projects should look at `@cloudflare/think`.

## Examples

The [`examples/`](examples) directory has 30+ self-contained demos. A non-exhaustive tour:

- **Showcase** — [`playground/`](examples/playground) is the kitchen-sink app: state, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in one UI
- **Chat & assistants** — [`agents-as-tools/`](examples/agents-as-tools), [`computer-skills/`](examples/computer-skills), [`r2-skills/`](examples/r2-skills), [`workspace-chat/`](examples/workspace-chat), [`resumable-stream-chat/`](examples/resumable-stream-chat), [`structured-input/`](examples/structured-input), [`dynamic-tools/`](examples/dynamic-tools), [`multi-ai-chat/`](examples/multi-ai-chat), [`context-overflow-recovery/`](examples/context-overflow-recovery)
- **MCP** — [`mcp/`](examples/mcp), [`mcp-client/`](examples/mcp-client)
````
