Metadata-Version: 2.5
Name: papaya-agent-client
Version: 0.10.2
Summary: Configurable local runner for Papaya agent-client jobs
Author: Papaya
Keywords: agents,automation,claude-code-plugin,local-runner,mcp,papaya
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: fastmcp==3.2.4
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=14.0
Description-Content-Type: text/markdown

# Papaya Agent Client

`papaya-agent` connects a coding harness on your machine to Papaya, so the model
works as one of your Papaya agents: it gets that agent's tools, persona, rules
and memories, and Papaya can see what it is doing. Two ways to use it, sharing
one connection. **Interactive**: you open Claude Code (or Cursor, or Codex)
yourself, and the bundled plugin gives the session the Papaya tools and keeps it
in step through hooks. **Unattended**: `papaya-agent listen` pulls the agent's
event stream, reserves the subject an event is about, and runs a harness for it.

The published Python package is `papaya-agent-client`, the npm package is
`papaya-agent`, and the command you run is always `papaya-agent`.

## Install

```bash
npx papaya-agent connect
```

That is the whole setup. The npm package is a small shim: it finds `uv` on your
`PATH`, or downloads one pinned, checksum verified copy into its own directory,
and runs `papaya-agent-client==<the shim's own version>` through it. After a
successful `connect` it runs `uv tool install` so `papaya-agent` is on your
`PATH` for good, plus `uv tool update-shell` once per installed copy. To manage
the Python package yourself instead, `uv tool install papaya-agent-client` and
then `papaya-agent connect`. Either way `papaya-agent` has to stay on your
`PATH`, because the Claude Code plugin runs it both for its hooks and for the
`papaya` MCP server itself; `papaya-agent hooks doctor` tells you if it is.

Two environment variables steer the shim, and neither is needed normally.
`PAPAYA_UV` is a path to a `uv` binary of your choosing, which wins over `uv` on
`PATH` and over the downloaded copy. `PAPAYA_AGENT_SOURCE` replaces the package
spec the shim installs from: a local path, a git URL, or anything else `uv`
accepts. Without it, a version PyPI cannot resolve is retried once from the
matching git tag. The shim needs Node 18 or later and has no dependencies.

## Connect

`papaya-agent connect` signs you in, pins this machine to one Papaya agent, and
sets your harness up. `--harness` chooses between `claude` (the default),
`cursor` and `codex`.

Sign-in is a loopback redirect with PKCE. `connect` binds
`http://127.0.0.1:<ephemeral port>/callback`, asks Papaya where its sign-in page
is, opens your browser there, and waits up to five minutes. The link is printed
as well as opened, so a browser on another machine works too. What you see:

```text
Waiting for you to approve in the browser…
https://app.trypapaya.ai/cli/authorize?state=...&code_challenge=...
Signed in as Sarah Wolf (sarah@example.com)
Workspace: Papaya HQ (papaya)
Agent: Engineering Agent @eng (engineer)
Connected as Engineering Agent (@eng) in Papaya HQ.
Durable context: available. Read it with the `get_my_agent_context` tool.
Declared to Papaya as runtime claude-code (renews its own leases, rule interception advisory: this session enforces the agent's rules itself).
Token saved to /Users/you/.papaya-agent/connect-token (0600). It is never written into harness config.
```

The browser authenticates **you**, and nothing else. The workspace and the agent
are chosen afterwards, in the terminal, from the same lists `--workspace` and
`--agent` filter; a single candidate is auto-picked with a line saying which,
and more than one gets a numbered prompt. If you deny the request, or five
minutes pass with no answer, `connect` prints one line and exits 1; a callback
carrying somebody else's `state` is answered and ignored, and the flow keeps
waiting. The run ends with the harness instructions, the Claude Code plugin
installed, the `papaya-agent listen` line for that harness (see
[Listening for events](#listening-for-events)), and one line naming the agent
and the workspace and telling you the `papaya` tools are ready in any
repository.

Your token is stored only in `~/.papaya-agent/connect-token` and
`~/.papaya-agent/config.json`, both `0600`. `connect` never writes it into
`.mcp.json`, `settings.json`, `~/.cursor/mcp.json` or any other shared file, and
there is no environment variable for you to set anywhere.

### Sign-in fallbacks

`--device` waits for you to approve a short code in the Papaya app, which is
what to use over SSH or on a headless machine. It prints
`Open <link> and approve code ABCD-EFGH`, then the plain link and the code on
lines of their own so they are easy to copy, then `Waiting for approval in
Papaya...`, and still tries to open the browser unless you pass `--no-browser`.
In this mode you pick the workspace and the agent in the app, so `--workspace`
and `--agent` do not apply and `connect` says so. Polling honours the interval
the server asks for, doubles the wait (up to 60 seconds) when the server says to
slow down, and gives up when the code expires. An expired code, a denied request
or a code already used prints one line and exits 1; three network failures in a
row exit 2. `--password` signs in with email and password instead.

Two fallbacks happen on their own, each with a one-line notice: a Papaya server
with no browser sign-in route, or a machine that cannot bind a loopback port,
falls back to the device code, and a server with neither falls back to the
password.

### Every `connect` flag

| Flag | Meaning |
| --- | --- |
| `--harness {claude,cursor,codex}` | Which harness to configure. Default `claude`. |
| `--workspace <id\|slug\|name>` | Pick the workspace without the prompt. |
| `--agent <id\|handle\|slug\|name>` | Pick the agent without the prompt. |
| `--name <text>` | Name this connection. Default `<harness> on <hostname>`, e.g. `Claude Code on laptop`. |
| `--device` | Sign in with a device code instead of the browser. |
| `--password` | Sign in with email and password instead of the browser. |
| `--no-browser` | Print the sign-in link instead of opening it. Still the loopback flow. |
| `--no-install` | Do not install the Claude Code plugin, which `connect` otherwise does for you. |
| `--install` | Run the harness's own registration command. Cursor and Codex need this; Claude Code installs the plugin without it. Claude Code and Codex then get the `papaya-agent listen` line to run next. |
| `--print` | Print only the `mcpServers` JSON on stdout (status lines go to stderr) and install nothing. |
| `--via-proxy` | Point the harness at the legacy local proxy. See [MCP modes](#mcp-modes). |
| `--read-only` | With `--via-proxy`, expose no write tools. Without `--via-proxy` it is an error. |

## What Claude Code gets

`connect` installs the plugin that ships inside the Python package. To find it
and install it by hand:

```bash
python -c "from papaya_agent_client.connect import plugin_root; print(plugin_root())"
claude plugin marketplace add <plugin_root>
claude plugin install papaya@papaya-agent-client
```

### The tools

The plugin's `.mcp.json` registers one server, `papaya`, running
`${PAPAYA_AGENT_BIN:-papaya-agent} mcp passthrough` over stdio, and `connect`
writes the same entry for every harness: `{"type": "stdio", "command":
"papaya-agent", "args": ["mcp", "passthrough"]}`, without the `type` for Cursor
and Codex. That command proxies the hosted Papaya MCP server at
`https://api.trypapaya.ai/api/v1/mcp/` and reads your token out of
`~/.papaya-agent/connect-token` itself, so no URL and no token appear in any
harness config file.

The pass-through connects once before it serves, which does two jobs. A token
the hosted server rejects fails there, on your terminal, with `Papaya rejected
this machine's token. Run papaya-agent connect` on stderr and exit 1. And the
remote server's startup instructions, which carry your agent's per-connection
context, are copied onto the proxy so the model still sees them. Tools,
resources and prompts are forwarded as they are, so a tool Papaya adds server
side appears without a client release.

### The hooks

An interactive session has no wrapper process around it, so the guarantees
`papaya-agent listen` gives an unattended run (reserve, work, release) come from
Claude Code's own hooks instead. `hooks/hooks.json` wires seven events to six
bash scripts.

| Event | Script | What it does |
| --- | --- | --- |
| `SessionStart` | `papaya-session-start.sh` | Mints this session's reservation session id, appends `PAPAYA_AGENT_TOKEN`, `PAPAYA_WORKSPACE_ID`, `PAPAYA_SESSION_ID` (and `PAPAYA_API_URL` on a non-production server) to `$CLAUDE_ENV_FILE`, injects the agent's durable context, and tells Papaya what this runtime can do. |
| `PreCompact` | `papaya-precompact.sh` | Refreshes and re-injects the context so it survives compaction. |
| `UserPromptSubmit` | `papaya-prompt.sh` | Injects a header plus the new context when the context changed since this session last saw it. Silent otherwise, which is almost every prompt. |
| `PreToolUse` | `papaya-guard.sh` | Enforces the checkable part of the agent's rules before a Papaya tool runs. Exit 2 blocks the call and tells the model why. |
| `PostToolUse` | `papaya-post-tool.sh` | Renews the session's reservations mid-turn, at most once every 180 seconds. |
| `Stop` | `papaya-stop.sh Stop` | Renews every subject reservation this session holds, at the lease length the server granted. |
| `SessionEnd` | `papaya-stop.sh SessionEnd` | Releases them. |

`PreToolUse` is registered against the matcher `mcp__papaya__.*`, so it never
speaks for the harness's own file or shell tools. `SessionStart` and
`PreCompact` get a 15 second timeout, the rest get 10.

**Why `Stop` renews and only `SessionEnd` releases.** `Stop` fires whenever the
model finishes responding, including a pause to ask you a question mid-task, and
releasing there would hand the subject to somebody else while the work is half
done. So `Stop` is the interactive equivalent of the listener's renew tick, and
`SessionEnd`, which fires once when the session is over, is the release. For a
long turn `Stop` is not enough, which is what `PostToolUse` is for; it is gated
on `~/.papaya-agent/renew-<claude session id>.stamp` (`0600`), and while that
file is younger than 180 seconds the hook exits without starting Python.
`SessionEnd` deletes the stamp.

**When a lease goes away.** A 409 means another session holds the subject now,
so the hook releases nothing: it is no longer ours to release. A reply of
`renewed: false` means the lease was lost too (a person released it, or it
expired) and this call has just re-acquired it, so the hook releases it again
and a session never re-takes what somebody handed back. `Stop` and `PostToolUse`
print one line of `{"decision": "block", "reason": "..."}` on stdout naming each
subject, because Claude Code shows the model nothing from a hook that exits 0
and the session would otherwise carry on working a subject it lost. `SessionEnd`
never blocks, and a payload with `stop_hook_active` set is only logged, because
blocking a turn that a block already resumed would loop. All three touch only
reservations whose `holder.session_id` is this session's, so a listener sharing
the connection keeps its own; they find each other through Claude Code's
`session_id`, recorded at `SessionStart` in the per-connection context cache.

**Rule enforcement is deliberately narrow.** Only a rule carrying an `enforce`
object is mechanical: `{"deny_tool": "<glob>"}` blocks the tool outright, and
`{"require_substring": {"tool": "<glob>", "substring": "<str>"}}` blocks it
unless the serialised tool input contains that substring. The glob is matched
with the `mcp__papaya__` prefix stripped, so rules read `post_message`, and
rules with no `enforce` object are for the model to follow. Every hook is
fail-soft and enforcement fails **open**: no cache, no rules, an unreadable
payload or any exception allows the call and logs to `~/.papaya-agent/hook.log`.

### The skill, PAPAYA.md, and checking it worked

`skills/papaya-connect/SKILL.md` tells the model when to run `connect`, how to
verify with `whoami`, how to read the full context with `get_my_agent_context`
(resource `papaya://me/context`), and the memory rules: `save_agent_memory` for
things about the agent itself, `propose_memory` for the workspace or the people
in it. `PAPAYA.md` is the same guidance as plain instructions, for harnesses
that load a file instead of running hooks. `papaya-agent hooks doctor` prints
every hook the plugin registers and whether its script is present and
executable, where `papaya-agent` resolves on your `PATH`, which connection and
agent are current, and the last 20 lines of `~/.papaya-agent/hook.log`.

### Cursor and Codex

Both get the same `papaya` server, and neither runs hooks, so both load
`PAPAYA.md` for the persona and memory rules instead.
`connect --harness cursor --install` merges the `papaya` entry into
`~/.cursor/mcp.json`; `connect --harness codex --install` runs
`codex mcp add papaya -- papaya-agent mcp passthrough`, which is where
`codex exec` later finds the server, and ends by printing
`papaya-agent listen --harness codex`. Without hooks nothing renews or releases
a subject for those sessions: they rely on `papaya-agent listen` when a
listener drives them, and otherwise on lease expiry or an explicit
`release_subject`.

The whole Codex setup, which is what the app's Connect dialog shows:

```bash
uv tool install papaya-agent-client
papaya-agent connect --harness codex --install
papaya-agent listen --harness codex
```

### What a connection tells Papaya about itself

Every connection reports what is on the other end of it, which is how the app
can tell an interactive session from a listener, and how Papaya knows whether to
enforce the agent's rules itself. The plugin at `SessionStart` and
`connect --harness claude` both declare `runtime_kind: claude-code` with
`heartbeat: true` and `interception: "advisory"`, because the `PreToolUse` hook
already enforces the rules locally. `--harness cursor` and `--harness codex`
declare `cursor` and `codex` with `heartbeat: false` and
`interception: "enforcing"`, so Papaya enforces server side. A listener declares
its `--runtime-kind` (default `custom`) with `heartbeat: true` and
`interception: "none"`, plus `delivery`, `resume` and
`max_concurrent_subjects`. `SessionStart` reports at most once per connection
per 24 hours and `connect` once per run; both are fail-soft.

### Durable context from the CLI

```bash
papaya-agent context            # the composed block, at most 6000 characters
papaya-agent context --json     # {"content_hash", "changed", "block", ...}
papaya-agent context --refresh  # bypass the cache
```

`context` reads the connection the latest `connect` recorded, asks Papaya for
the agent's persona, rules and memories with that connection's token (never
asking for sensitive memories), and caches the result per connection at
`~/.papaya-agent/context-cache/<connection_id>.json` (`0600`, directory `0700`)
for 60 seconds, keyed by the hash Papaya returns. An unchanged hash reuses the
cached rendering, a changed hash overwrites it, and if Papaya cannot be reached
the last cached block is served. `--hook
{SessionStart,PreCompact,UserPromptSubmit}` is how the plugin's own scripts call
it: it prints the hook JSON on stdout and never fails a session.

## Listening for events

`papaya-agent listen` runs the connected-agent event loop for the connection
`connect` made. Every turn has the same shape, whatever harness you point it at:
pull events, apply the playbook, reserve the subject, run your command, renew
the lease while it runs, release on exit, advance the cursor. HTTP polling is
the contract; the WebSocket only carries a doorbell saying "go pull", so the
listener reacts at once but never depends on the socket. At startup it reports
its capabilities to Papaya, fail-soft.

| Flag | Default | Meaning |
| --- | --- | --- |
| `--harness {claude-code,codex}` | `claude-code` | Which bundled runner drives events: `papaya-claude-runner.sh` or `papaya-codex-runner.sh`. Exits 1 before connecting if that harness's CLI (`claude` or `codex`) is not on `PATH`. |
| `--run '<command>'` | the harness's bundled runner | Your own harness command instead. `{prompt}` is replaced with the generated instruction; without it the prompt goes to stdin. No CLI is looked for. |
| `--poll-interval N` | `20` (or `PAPAYA_POLL_INTERVAL`) | Seconds between event pulls. |
| `--max-concurrent N` | `1` | Subjects worked on at once. |
| `--runtime-kind KIND` | the harness's name, or `custom` with a bare `--run` | Label reported to Papaya. An explicit `--harness` labels a `--run` command too. |
| `--resume` | off | Advertise that this runtime can resume a previous session. |
| `--match REGEX` | none | Only act on events matching. Repeatable, and every pattern must match. |
| `--exclude REGEX` | none | Never act on events matching. Repeatable. |
| `--explain-match FILE` | none | Print the canonical string and the verdict for a saved envelope, then exit. |

Claude Code and Codex are two bundled runners behind one flag, and the lines
`connect --install` printed are the ones to run:

```bash
papaya-agent listen                   # Claude Code, the default
papaya-agent listen --harness codex   # Codex
```

Both runner scripts ship inside the wheel, so neither line needs a path, from
an installed copy or a source checkout. `--harness` is also the runtime label
the listener reports, so a listener and an interactive session for the same
tool show up under one name in Papaya. If the harness's CLI is not on `PATH`
the listener says so (`Codex is not installed: ... is not on PATH.`) and exits
1 before it connects. `--run` still takes any command of your own, `{prompt}`
included, and is never checked against a binary:

```bash
papaya-agent listen --run './my-runner.sh {prompt}'                  # reported as custom
papaya-agent listen --harness codex --run './my-codex.sh {prompt}'   # reported as codex
```

The bundled Claude runner reads one environment variable of its own,
`PAPAYA_CLAUDE_PERMISSION_MODE`, which is the `--permission-mode` it passes to
`claude`. It defaults to `bypassPermissions`; set it to `acceptEdits`, `plan` or
`default` for a stricter mode. The bundled Codex runner runs `codex exec`, with
`--cd` set to the working directory, and leaves the `papaya` server to Codex's
own config, which `connect --harness codex --install` registered.

### The playbook

Each event kind maps to `act`, `acknowledge` or `ignore`. The mapping comes from
the agent's resolved playbook, edited in the Papaya app and merged by the server
over the defaults, which are `act` for `mention.you`, `work_item.assigned`,
`work_item.comment`, `dm.received` and `approval.waiting`, `acknowledge` for
`work_item.status_changed`, and `ignore` for `subject.reserved` and
`subject.released`. **No model call is made to decide.**

`acknowledge` advances the cursor and does nothing else; `ignore` does the same
and does not log it as interesting. An unknown kind is ignored, and an `act` on
an event the server did not mark reservable, or that carries no subject, is
downgraded to `acknowledge`, because the listener never reserves a subject the
server did not offer a lease on.

### Which events are this machine's

One Papaya agent can have a listener on every machine you own, and only one of
them has the backend checked out. `--match` and `--exclude` are how a listener
says what it can actually do. Both are Python regexes (`re.search`,
case-insensitive), both repeat, and both are tested against one canonical string
per event: `"<kind> <subject> " + json.dumps(payload, sort_keys=True)`.

```bash
# The bug machine: only work items whose kind is "bug".
papaya-agent listen --match 'work_item.*"kind": "bug"'

# The backend machine: anything except the frontend.
papaya-agent listen --exclude 'frontend'
```

Every `--match` must hit and no `--exclude` may, so patterns narrow rather than
widen, and an event that hits both is refused: saying "never this" is the
stronger statement. An event that does not pass is treated exactly like an
`ignore`, so the cursor advances, nothing is reserved, and one line is logged
(`[listen] event=4512 not mine (--match/--exclude): ...`). The filter is local
to the machine: the server never sees it, so it never routes around it, and only
events the playbook already resolved to `act` reach it.

To test a pattern without running anything, save an envelope (any run leaves one
at `$PAPAYA_EVENT_FILE`) and ask
`papaya-agent listen --explain-match ./envelope.json --match '"kind": "bug"'`.
It prints the canonical string and then `Verdict: run` or `Verdict: not mine
(--match/--exclude)`, and exits `0` when the event would be worked here, `1`
when it would not, and `2` when the file is not a readable envelope. A malformed
pattern is rejected before anything connects.

### Subject reservations

A subject (`work_item:<uuid>`, `thread:<uuid>`, `dm:<uuid>`, `proposal:<uuid>`)
is the unit of work, and only one session works a subject at a time. Before
running, the listener reserves it; if another session already holds it, the
holder is logged, the event is skipped, and the cursor moves on, with no retry
storm and no jitter. While the harness runs, the lease is renewed every third of
the granted lease length, and network failures are retried on the next tick,
because the server-side expiry is the safety net and a flaky network should not
kill good work. On any exit (clean, crash or SIGTERM) it is released.

A renewal that comes back 409 means the lease was lost: the harness is killed
and the subject is **not** released, because this session no longer owns it. A
renewal that comes back `renewed: false` means the lease was lost too and this
call has just taken the subject again, so the harness is killed and the subject
**is** released, because the accidental re-acquire made this session the holder.
That second case is how a person releasing a subject stops the holder: reserving
is acquire-or-extend, so the next renew would otherwise quietly take the subject
back and carry on working on something a person had deliberately taken away.

**Losing a race is not the end of it.** A subject this listener wanted but lost
is remembered with the event that asked for it, up to 200 subjects, oldest
forgotten first. When a `subject.released` arrives for one of them, the listener
bids again and runs the *original* event, not the release notice
(`[listen] event=4530 re-bid on work_item:5d0c... after expired`). `expired`,
`revoked` and `declined` invite a re-bid. `holder` and `human` drop the entry
instead: the work is done, or somebody decided on purpose that no agent should
be doing it. A re-bid is a run like any other, so it waits for a free slot and
is skipped again if a faster peer got there first.

**A harness can say "not mine" itself.** Some things are only knowable once the
run has started: wrong repository, wrong branch, a machine without the tool the
ticket needs. A harness command that exits with status **75** says exactly that,
so the subject is released as `declined`, the one release reason that invites
peers to re-bid, and the event is not run again here. Every other exit status,
including a crash, releases the subject as usual. The generated prompt tells the
model about the convention, so a harness that just runs a model gets this free.

### The cursor

The client-held cursor lives at
`~/.papaya-agent/events-cursor-<connection-id>.json` (`0600`). It only ever
passes an event the listener has finished with, so a listener that dies mid-run
re-reads that event on restart; delivery is at-least-once and the server is
idempotent. After each handled batch the listener also acks the cursor server
side, so a fresh machine resumes. A missing or corrupt cursor file reads as `0`
rather than refusing to start, and when every worker slot is busy the remaining
events are left in the stream for the next pull.

### What the harness receives

The command runs with `{prompt}` replaced by a short generated instruction: the
playbook guidance, the event kind and subject, the triggering text, how to hand
the work back, the closing steps, and a pointer to the envelope. It is capped at
2,000 characters, and truncation trims the free text rather than these three
closing lines:

```text
If this event is not yours to act on (wrong repository, wrong machine, out of scope), exit with status 75 and do nothing else.
Before you finish: propose durable learnings (propose_memory for the workspace or people, save_agent_memory for yourself) and leave a short closing comment on the subject.
The full envelope is at $PAPAYA_EVENT_FILE.
```

Writing memories back stays the model's job and stays proposal-only: no hook and
no part of the listener writes a memory. Everything else arrives in the
environment:

| Variable | Contents |
| --- | --- |
| `PAPAYA_EVENT_FILE` | Path to the full JSON event envelope (`0600`, deleted on exit). |
| `PAPAYA_EVENT_KIND` | The event kind, e.g. `work_item.assigned`. |
| `PAPAYA_SUBJECT` | The reserved subject. |
| `PAPAYA_WORK_ITEM_ID` | The work item UUID, when the subject is a work item. |
| `PAPAYA_SESSION_ID` | This listener process's session id (`<hostname>-l-<8 hex>`). |
| `PAPAYA_AGENT_TOKEN` | The `pagc_` token for this connection. |
| `PAPAYA_WORKSPACE_ID` | The workspace UUID. |
| `PAPAYA_API_URL` | The Papaya API base URL. |
| `PAPAYA_CONTEXT_FILE` | Path to the rendered durable-context bundle (`0600`, deleted on exit). |
| `PAPAYA_WORKING_DIRECTORY` | The resolved working directory, which the Codex example passes to `--cd`. |

When the subject is a work item, `papaya-claude-runner.sh` reuses that UUID as
the Claude session id, so a follow-up event resumes the same conversation.
`papaya-codex-runner.sh` uses only `codex exec` and `--cd` from Codex's public
documentation, so it works with a stock Codex; to invoke Codex differently,
point `--run` at your own copy.

### Legacy: dispatched jobs

There is an older model in which Papaya dispatches a job to this machine and the
client runs a configured local command for it. It is still supported, and
`listen` uses it when this machine has no connection from `papaya-agent
connect`, meaning a machine set up with `papaya-agent login` instead. The client
opens one WebSocket per configured agent, drains queued jobs on startup and
reconnect, runs the agent's configured command, and posts the result back.

The command is an argument array and is never run through a shell: an argument
containing `{prompt}` receives the job prompt, otherwise the prompt goes to
stdin, and `{job_id}`, `{runner_session_key}`, `{runner_session_id}`,
`{work_item_id}` and `{runner_session_file}` are substituted the same way. Job
working-directory hints must resolve inside the agent's allowed directories.
Each claimed job leaves its prompt and directory resolution metadata in
`~/.papaya-agent/job-logs/<job-id>/`, and `PAPAYA_AGENT_LOG_FULL_PROMPT=true`
also prints the whole prompt to the console.

Follow-up work from the same work item can carry a prior session id, which
reaches the command as `PAPAYA_RUNNER_SESSION_KEY`, `PAPAYA_RUNNER_SESSION_ID`
and `PAPAYA_RUNNER_SESSION_FILE`, alongside `PAPAYA_JOB_ID`,
`PAPAYA_EXTERNAL_JOB_ID` and `PAPAYA_WORK_ITEM_ID`. A wrapper should resume the
external session when `PAPAYA_RUNNER_SESSION_ID` is set and write the current
session id to `PAPAYA_RUNNER_SESSION_FILE` when it finishes, so the next
dispatch resumes it. `scripts/papaya-claude-runner.sh` does that: configure it
as the agent's command with the Papaya `agent_ref` as its one argument
(`["/path/to/scripts/papaya-claude-runner.sh", "scout"]`), and with no prompt
argument it reads the prompt from stdin, which is what this path does.

## Managing agents and sessions

| Command | What it does |
| --- | --- |
| `papaya-agent login` | Sign in with email and password, then configure local agent connections for the legacy job model. It **replaces** the whole configured set, and does not open WebSockets or start listening. |
| `papaya-agent agents add` | The same configuration flow, merging into what is already there. Re-running it for an agent that already has a connection rotates that connection's token. |
| `papaya-agent agents edit` | Edit one configured agent's command, working directory, allowed directories and timeout. Choose exactly one. |
| `papaya-agent agents remove` | Remove configured agents. |
| `papaya-agent logout` | Clear the saved user session and every configured agent. It does not delete `~/.papaya-agent/connect-token`; run `connect` again to replace that. |
| `papaya-agent workspaces` | List workspace IDs, slugs and names for the saved user session. |
| `papaya-agent context` | Print the connected agent's durable context. See [above](#durable-context-from-the-cli). |

For each agent, `login` and `agents add` ask for a display name, the command to
run when Papaya dispatches a job (default `claude -p {prompt}
--enable-auto-mode`), a working directory, the allowed working directories, and
a timeout in seconds (default 600). Your password is never stored. The saved
config lives at `~/.papaya-agent/config.json` (`0600`) and holds the user
refresh token plus one scoped `pagc_...` token per configured agent; rotating a
connection invalidates that connection's old token and no other machine's.

`workspaces` prints a column-aligned table of IDs, slugs and names by default,
one JSON object per line with `--json`, and IDs only with `-q`. Without a saved
user session it prints `Run papaya-agent login first.` and exits 1.

## MCP modes

`papaya-agent mcp passthrough` is the default: the full hosted tool set, proxied
over stdio, with the token read from `~/.papaya-agent/connect-token`. It is what
the plugin runs and what `connect` writes into every harness config, and
`--agent <ref>` serves a configured agent's stored token instead, so one machine
can serve a second agent without re-running `connect`. The only reasons to
choose `papaya-agent connect --via-proxy` instead are `acting_as` on every write
result, so the harness can see which Papaya agent it just spoke as, and
`--read-only`, which exposes no write tools at all.

### The legacy local proxy

`papaya-agent mcp` is a hand-built proxy that predates the pass-through, kept
for those two things alone, and its tool set is a hand-maintained subset rather
than whatever the hosted server publishes. `connect --via-proxy` emits it as
`papaya-agent mcp --agent <ref> [--read-only]`, and with `--install` registers it
through `claude mcp add` or `codex mcp add` (or, for Cursor, by merging into
`~/.cursor/mcp.json`). Run directly, exactly one of these is required:

- `--agent <ref>`: one assistant acts as one Papaya agent. Tool calls need no
  `agent_ref`, which makes it the least ambiguous mode. Add `--read-only` for a
  session that must read Papaya but not write to it.
- `--multi-agent`: one assistant coordinates across several Papaya agents. Tool
  calls require `agent_ref`.
- `--user`: expose connected-service tools using your saved Papaya user session
  rather than an agent identity. Add `--workspace <id>` if the account has more
  than one workspace.

The tools it exposes are `papaya_whoami`, `papaya_list_channels`,
`papaya_read_channel_messages` and, unless `--read-only`, `papaya_post_message`;
`--multi-agent` adds `papaya_list_agents`. Connected-service tools (for example
`github__...`, `linear__...`, `google__...`, `trello__...`) are loaded in
`--agent` and `--user` mode only, never in `--multi-agent` mode, and only for
providers the workspace has connected. Under `--read-only` those are filtered by
name, which is a heuristic: a tool whose name reads as a write is dropped.

```bash
papaya-agent mcp list-agents                        # agent_ref, name, workspace id
papaya-agent mcp print-config --agent scout         # one pinned server
papaya-agent mcp print-config --multi-pinned        # one server per configured agent
papaya-agent mcp print-config --multi-agent         # one shared server
papaya-agent mcp print-config --user --workspace <workspace-id>
papaya-agent mcp persona-prompt --agent scout       # instructions pinning a shared server to one identity
papaya-agent mcp doctor --agent scout               # diagnostics, no raw tokens
```

`print-config` also takes `--read-only`, and `persona-prompt` requires
`--agent`. The agent that `papaya-agent connect` pinned is always in
`list-agents`, even on a machine with no `agents` block in
`~/.papaya-agent/config.json`: its identity comes from the `connect` record and
its token from `~/.papaya-agent/connect-token`. That derived entry is rebuilt on
every load and never written back into `config.json`, which is what makes
`papaya-agent connect --via-proxy` work with nothing else set up.

## Troubleshooting

**No `papaya` tools after connecting.** Run `papaya-agent connect` again and
restart the harness. There is no environment variable to set and nothing to put
in a shell profile; the two things worth checking are that `papaya-agent` is on
your `PATH` and that the plugin is installed, and `papaya-agent hooks doctor`
answers both.

**A Papaya tool returns 401, or the server says the token was rejected.** The
connection's token is stale: run `papaya-agent connect` again and restart the
session. The pass-through says the same on its stderr and exits 1 rather than
serving a broken session.

**`papaya-agent: command not found`, or the harness cannot find it.** The
harness starts the CLI by name, so it has to be on the `PATH` the harness
inherited. Install it with `uv tool install papaya-agent-client` and open a new
terminal, or set `PAPAYA_AGENT_BIN` to an absolute path; `hooks doctor` prints
which of those is in effect.

**A machine with no browser (SSH, a container, a server).** Use `papaya-agent
connect --device` and approve the short code in the Papaya app, or `papaya-agent
connect --no-browser` and open the printed link from another machine.

**A Papaya server without the browser sign-in route.** `connect` falls back on
its own, printing `This Papaya server has no browser sign-in yet; using the
device code instead.` and continuing with the device flow; a server with no
device flow either falls back again to email and password.

**`listen` says the harness is not installed.** `--harness` resolves a bundled
runner that starts `claude` or `codex` by name, so that CLI has to be on the
`PATH` of the terminal running `listen`. Install it and run `listen` again, or
pass `--run '<command with {prompt}>'` to drive something else.

**The listener says an event is "not mine".** That is `--match` or `--exclude`
refusing it. Check the pattern with `papaya-agent listen --explain-match
<envelope.json>`, which prints the string your pattern is tested against.

## Developing this client

### Repository layout

| Path | What is in it |
| --- | --- |
| `papaya_agent_client/__main__.py` | The argparse tree, the authority for every command and flag, plus `login`, `logout`, `workspaces` and the legacy job loop. |
| `papaya_agent_client/connect.py` | `connect`: sign-in flow selection, workspace and agent choice, harness config, plugin install. |
| `papaya_agent_client/browser_signin.py` | The loopback listener and the PKCE sign-in. |
| `papaya_agent_client/auth.py` | Password sign-in and session refresh. |
| `papaya_agent_client/api_client.py` | Every Papaya HTTP call, and the typed errors callers branch on. |
| `papaya_agent_client/config.py` | `~/.papaya-agent/config.json`, endpoint selection, agent configs. |
| `papaya_agent_client/context.py` | Durable context: fetch, hash cache, compose, and the `SessionStart`, `PreCompact` and `UserPromptSubmit` hooks. |
| `papaya_agent_client/hooks.py` | The `Stop`, `PostToolUse` and `SessionEnd` hooks, the renew stamp, the hook log, and `hooks doctor`. |
| `papaya_agent_client/guard.py` | The `PreToolUse` hook: rule evaluation, fail-open. |
| `papaya_agent_client/listener.py` | The event loop: pull, playbook, scope filter, reserve, renew, release, re-bid, cursor. |
| `papaya_agent_client/playbook.py` | The `act` / `acknowledge` / `ignore` decision and the default table. |
| `papaya_agent_client/command_runner.py` | Running a harness command: token substitution, streaming, timeout, cancellation. |
| `papaya_agent_client/passthrough.py` | `mcp passthrough`: the proxy of the hosted MCP server. |
| `papaya_agent_client/mcp_server.py` | The legacy hand-built proxy and the `print-config` / `doctor` / `persona-prompt` helpers. |
| `papaya_agent_client/mcp_identity.py` | Stable `agent_ref` slugs and the derived connect identity. |
| `papaya_agent_client/ws_client.py` | The WebSocket carrying the doorbell and the legacy job notification. |
| `papaya_agent_client/plugin/` | The plugin, shipped as package data: `.mcp.json`, `hooks/`, `skills/`, `PAPAYA.md`, and the Claude, Cursor and Codex manifests. |
| `scripts/` | The bundled runners `papaya-claude-runner.sh` and `papaya-codex-runner.sh`, one per `listen --harness`. Both are force-included in the wheel. |
| `npm/` | The `papaya-agent` shim: `bin/`, `lib/` (uv bootstrap, checksum, targets, source spec), `test/`. |
| `tests/` | `test_connect.py` (connect, the plugin, the hooks, the doc rules), `test_listener.py`, `test_passthrough.py`, `test_client_runtime.py` (the legacy job path), `test_version_pins.py`. |

### Local setup

```bash
uv sync
uv run papaya-agent --help
```

Every command in this README works from a source checkout with `uv run` in front
of it. To point the client at a Papaya running on your machine, set
`LOCAL_PAPAYA`, for example `LOCAL_PAPAYA=true uv run papaya-agent connect`. Any
value other than `true` (case-insensitive) means production, which is
`https://api.trypapaya.ai` over HTTP and `wss://api.trypapaya.ai` for the
socket; `LOCAL_PAPAYA` switches both to `http://localhost:5173` and
`ws://localhost:5173`. Endpoints are re-derived from the environment on every
load and rewritten into `config.json` on every save, so switching is just the
variable.

### Running the tests

```bash
uv run pytest -q                          # the Python suite
node --test test/*.test.js                # the npm shim, run from npm/
claude plugin validate papaya_agent_client/plugin   # the plugin manifests
```

CI runs the first two on every pull request, against Python 3.11 and 3.13 and
Node 18 and 22. Some tests keep this repository honest rather than testing
behaviour, and they are the ones most likely to fail on a documentation change.
In `tests/test_connect.py`: `test_plugin_and_docs_avoid_em_dashes` forbids an em
dash anywhere in the plugin or in this README;
`test_docs_never_tell_anyone_to_export_a_token` forbids any plugin file or part
of this README telling somebody to put a token in a shell profile; and
`test_version_is_pinned_across_pyproject_banner_and_manifests` requires
`pyproject.toml`, the CLI banner and the three plugin manifests to carry one
version. `tests/test_version_pins.py` requires `npm/package.json` to match
`pyproject.toml`, forbids a version literal in the shim's source, checks `uv` is
pinned once and its download checksum verified, and checks the release workflow
gates on the version and publishes with no stored token.

### Working on the plugin

`claude --plugin-dir papaya_agent_client/plugin` loads the plugin for one
session without installing it. The hooks shell out to `papaya-agent` by name, so
in a source checkout point `PAPAYA_AGENT_BIN` at a wrapper that runs `uv run
papaya-agent`, or install the package with `uv tool install .`. `papaya-agent
hooks doctor` shows which scripts are registered and whether each is present and
executable, and `~/.papaya-agent/hook.log` is where a fail-soft hook records
what went wrong.

### Bumping the version

The version appears in seven places and tests enforce that they agree:
`pyproject.toml` (`project.version`), `npm/package.json` (`version`), `_BANNER`
in `papaya_agent_client/__main__.py`, `plugin.json` in each of
`papaya_agent_client/plugin/.claude-plugin/`, `.cursor-plugin/` and
`.codex-plugin/`, and the version literal asserted in `tests/test_connect.py`.
The git tag is the eighth, and the release workflow checks it against the first
two.

### Releasing

The Python package and the npm shim are one release with one version number.
`.github/workflows/release.yml` runs on a `v*` tag and refuses to publish
anything unless the tag, `pyproject.toml` and `npm/package.json` all name the
same version, and unless both test suites pass.

```bash
# 1. bump every version listed above
uv run pytest -q
node --test npm/test/*.test.js

# 2. tag and push
git tag v0.10.2
git push origin v0.10.2
```

There are no registry tokens and no repository secrets. Both registries use
trusted publishing: GitHub mints a short-lived OIDC token for the workflow run,
the registry checks that the run came from this repository, this workflow file
and the named GitHub environment, and every upload carries a provenance
attestation the registry publishes beside it. The publish jobs do nothing but
publish, hold only the `id-token: write` permission they need, and consume
artifacts built by a job with no publishing rights.

Setting a trusted publisher up is a one-time task for a registry owner. On
[PyPI](https://pypi.org/manage/account/publishing/), under *Add a new pending
publisher*: project `papaya-agent-client`, owner `Papaya-HQ`, repository
`papaya-agent-client`, workflow `release.yml`, environment `pypi`. A pending
publisher lets the first release create the project; afterwards it lives under
the project's own Publishing settings. On npm, from the package page under
*Settings*, *Trusted Publisher*: GitHub Actions, organization `Papaya-HQ`,
repository `papaya-agent-client`, workflow `release.yml`, environment `npm`. npm
only lets an existing package name a trusted publisher, so the very first
`papaya-agent` release is one `npm publish --access public` from a maintainer's
own machine in `npm/`, with interactive two-factor auth and no token stored
anywhere; every tag after that publishes from Actions.

Both jobs run inside GitHub environments named `pypi` and `npm`. Creating them
under Settings, Environments is optional (a job creates a missing one on first
use), but a required reviewer on either one turns a tag push into a release that
a person has to approve.

The npm shim is plain CommonJS with no build step and no runtime dependencies.
`npm/lib/uv-version.json` is the single pinned `uv` version it downloads when a
machine has none; bumping it is a one-line change, and the download is checksum
verified against Astral's `.sha256` sidecar every time.

## History

Two planning documents from before this client shipped are kept under
`docs/history/`, and describe intentions rather than the current client: the
[MCP plan](docs/history/papaya-agent-client-mcp-detailed-implementation-plan.md)
and the
[`workspaces` plan](docs/history/papaya-agent-client-workspaces-command-plan.md).
