Poppy client (personal agent)

A reference Personal Agent (the client side of Poppy), as a library and a CLI (poppy-agent). There is no public Poppy agent yet; this one exists to test Company (server) implementations end to end. It is written strictly against the spec, not against any particular server.

What it implementsCopy Anchor Link

Not implemented: extensions (none are advertised; unknown ones are ignored), Personal Agent-side OpenAPI schema validation.

CLICopy Anchor Link

@adonis-agora/agent ships the CLI as the poppy-agent bin:

npx poppy-agent --help          # or: pnpm exec poppy-agent --help, inside a project that depends on it

State lives in ~/.config/poppy-agent/state.json (or --state / $POPPY_AGENT_STATE), mode 0600: the agent's private keys, per-Company User IDs, DPoP keys, Account Tokens, Session Tokens and conversation cursors. --profile <name> acts for another local user (different User IDs).

Identity: client_id must be HTTPSCopy Anchor Link

The spec requires client_id to be an HTTPS URL the Company can fetch. Two ways:

A tunnel (spec-compliant).

cloudflared tunnel --url http://127.0.0.1:7777          # prints https://<random>.trycloudflare.com
# or: tailscale funnel 7777
poppy-agent init --base-url https://<random>.trycloudflare.com --name "My Test Agent"
poppy-agent serve-identity --port 7777

serve-identity serves /agent.json, /jwks.json, /logo.svg and /oauth/callback (Direct Sign-In redirects land there and are relayed to the signin process through the state dir).

--insecure-dev (NOT spec-compliant, local only). With --insecure-dev (or POPPY_AGENT_INSECURE_DEV=1) the agent accepts http:// everywhere the spec demands HTTPS: its own client_id, poppy.json, the issuer, endpoints and redirects. Every run prints a loud banner. The Company must be configured to accept an http://localhost client_id too. Never use it against a real Company.

poppy-agent init --base-url http://localhost:7777 --insecure-dev
poppy-agent serve-identity --insecure-dev        # or let `signin` serve it in-process

CommandsCopy Anchor Link

poppy-agent discover example.com
poppy-agent session example.com [--new] [--scope poppy:read] [--resource <url>]
poppy-agent signin example.com --method direct|device|mediated --scope "poppy:read poppy:write"
poppy-agent status
poppy-agent apis example.com
poppy-agent api example.com GET /orders
poppy-agent api example.com POST /addresses --data '{"line1":"…"}'
poppy-agent mcp tools example.com
poppy-agent mcp call example.com search_products '{"query":"jacket"}'
poppy-agent chat example.com          # /help inside for /data /context /as /handoff /signin /direct /decline /leave /close
poppy-agent open example.com https://example.com/orders [--print]
poppy-agent disconnect example.com
OPENROUTER_API_KEY=… poppy-agent ask example.com "Is the insulated jacket available in M?" [--model …] [--max-steps 8] [--yes]

In chat, what you type is sent with sender: "agent" by default (you act as the agent's brain). /as human marks messages as the User's own words (7.8); in a Direct Conversation they are always human. open warns that browser assertions must only be posted from a browser the agent controls (section 5); use a dedicated or automation browser profile, or --print and load the page there.

Testing against a local Agora app (MeuProntoo / Lastro)Copy Anchor Link

With an app serving Poppy (@adonis-agora/authkit-server's personalAgents.poppy and this package's conversation endpoint):

1. Run the app with Poppy enabled, e.g. http://localhost:3333. Check curl http://localhost:3333/.well-known/poppy.json and the issuer's /.well-known/oauth-authorization-server (it must list the app's domain in poppy_domains).
2. Let the dev server accept an http client_id (its dev-only setting for Client ID Metadata Documents over http/localhost), or use a tunnel for the agent identity and keep the app on HTTPS (e.g. its own tunnel) to stay spec-compliant.
3. Create and serve the agent identity:

   Copy Text

   poppy-agent init --base-url http://localhost:7777 --name "Poppy Dev Agent" --insecure-dev
   poppy-agent serve-identity --insecure-dev &

   If the app requires registration/allowlisting of client_ids, register http://localhost:7777/agent.json.
4. Discover and start a Session:

   Copy Text

   poppy-agent discover localhost:3333 --insecure-dev
   poppy-agent session localhost:3333 --insecure-dev         # signed out, DPoP-bound

5. Sign in with whatever the app offers:

   Copy Text

   poppy-agent signin localhost:3333 --method direct --insecure-dev    # browser, PKCE, iss check
   poppy-agent signin localhost:3333 --method device --insecure-dev
   poppy-agent signin localhost:3333 --method mediated --insecure-dev

6. Use it: apis, api …, mcp tools …, chat localhost:3333 --insecure-dev (try asking for account data to trigger an authorization event, /signin, and continue), open localhost:3333 http://localhost:3333/ --insecure-dev, ask ….
7. Sign out: poppy-agent disconnect localhost:3333 --insecure-dev, then session again shows signed_in: false on the same session_id.

Watch stderr for tracing: retries (DPoP nonce, Retry-After, new Sessions) are logged.

LibraryCopy Anchor Link

@adonis-agora/agent/poppy-client is framework-agnostic: no AdonisJS import anywhere in its module tree (a test enforces it), only Node built-ins, jose and the MCP SDK client. Use it from a CLI, a worker, or any server.

import { AgentIdentity, ConversationClient, PoppyAgent, StateStore, newMessageId } from '@adonis-agora/agent/poppy-client';

const store = await StateStore.open();
const agent = new PoppyAgent({ store, identity: new AgentIdentity(store.data.identity!) });
const company = await agent.company('example.com');
const conv = new ConversationClient(company);
const { conversation_id } = await conv.start({ id: newMessageId(), sender: 'agent', text: 'Hi' });
for await (const item of conv.follow(conversation_id, { untilSettled: true })) console.log(item);

TestsCopy Anchor Link

The package's tests (test/poppy-client/) run unit tests plus end-to-end tests against an in-process fake Poppy Company (test/poppy-client/fixtures/fake_company.ts): poppy.json, RFC 8414 metadata, a token endpoint verifying private_key_jwt, JWT bearer assertions and DPoP (nonce, ath, jti replay, key binding), authorization/device/mediated sign-in, revocation, an OpenAPI API, a conversation endpoint with JSON long-poll and SSE (deltas, dropped streams), a browser session endpoint and an MCP server. Each check a Company MUST perform is recorded as a violation when the client breaks it, so the fake doubles as a conformance check of the client.

To try the CLI by hand against the fake:

cd packages/adonis
node --import=@poppinss/ts-exec test/poppy-client/fixtures/serve_fake.ts 7790 &
poppy-agent init --base-url http://127.0.0.1:7788 --insecure-dev
poppy-agent serve-identity --insecure-dev &
poppy-agent chat 127.0.0.1:7790 --insecure-dev

Mediated credentials for the fake: dana@example.com / hunter2, code 123456.