@pdpp/cli 0.1.0-beta.7 → 0.1.0

package/README.md

@@ -4,8 +4,8 @@ Command-line tools for PDPP providers.
 
 ## Status
 
-This package is the public npm home for the `pdpp` command. The beta CLI
-supports three command namespaces:
+This package is the public npm home for the `pdpp` command. The CLI
+supports four command namespaces:
 
 - **`pdpp connect <provider-url>`** — delegated access: discovers provider
   metadata, self-registers a public client when the AS advertises dynamic
@@ -13,6 +13,47 @@ supports three command namespaces:
   stores scoped client credentials in the project-local `.pdpp/` cache without
   asking for an owner bearer token.
 
+- **`pdpp owner-agent <onboard|status|control|connectors|setup|revoke>`** — trusted owner-agent
+  onboarding for a local agent that acts as the operator (for example Daisy).
+  This is owner-level local automation, deliberately separate from the default
+  grant-scoped `pdpp connect` path; ordinary agents should not use it.
+  `onboard <entrypoint-url>` discovers the `pdpp_owner_agent_onboarding`
+  advisory block (falling back to the RFC 8628 device-authorization shape in
+  authorization-server metadata), runs browser-mediated owner approval, and
+  writes the issued credential to a local file with `0600` permissions. The
+  bearer is never printed; only the verification URL, code, and non-secret
+  status are shown. Pass `--credential-file` to target Daisy's first supported
+  path `~/applications/daisy/.pi/agent/pdpp-owner-agent.json`; otherwise the
+  credential defaults to `~/.pdpp/owner-agents/<host>.json` and stores the
+  bearer as top-level `access_token` for local agents. `status` introspects the
+  stored credential. `control` lists the non-secret owner-agent control
+  capabilities (`GET /v1/owner/control`) and configured connection instances
+  (`GET /v1/owner/connections`) — each connection's `connection_id`, connector,
+  and label/label-needed state — so a trusted agent can discover what it can do
+  and what is configured without printing the bearer. `connectors list`,
+  `connectors search <query>`, and `connectors explain <connector-id>` read the
+  non-secret connector-template catalog (`GET /v1/owner/connector-templates`) so
+  a human or agent can discover Amazon/Gmail/Slack-like setup options before
+  starting anything. These discovery commands are read-only and do not mint
+  enrollment codes. `setup <connector-id>` is the start command: it requests the
+  same non-secret connection setup plan and next-step contract the console
+  add-source flow and owner-agent REST surface, by calling the shared server
+  planner (`POST /v1/owner/connections/intents`). It sends the stored bearer only
+  as an `Authorization` header, formats the plan's support state (`supported`,
+  `proof-gated`, `unsupported`, `deployment-blocked`), modality, and primary
+  owner next step, and surfaces owner-openable setup material (enrollment codes,
+  enroll endpoints, runbook paths) when present. Pass `--display-name <name>` to
+  label the resulting connection. No connection is created by this call; it
+  materializes only when the owner-mediated step completes. The setup plan never
+  includes provider secrets, owner cookies, browser cookies, or grant-scoped MCP
+  bearer material, and the bearer is never printed. `revoke` deletes its
+  dynamically registered client via the owner-session-gated RFC 7592 dashboard
+  path; run `pdpp ref login <authorization-server>` first or provide
+  `PDPP_OWNER_SESSION_COOKIE`. Owner-agent bearers are REST/control-plane
+  credentials; `/mcp` rejects them. Routine chat-hosted and task-scoped agents
+  should use the grant-scoped `pdpp connect` / MCP path instead, not an owner
+  bearer.
+
 - **`pdpp collector <advertise|enroll|run>`** — operator surface for the
   local collector runner. Pairs a host the operator controls (Claude Code or
   Codex CLI data) with a remote PDPP reference deployment via device-scoped
@@ -20,9 +61,9 @@ supports three command namespaces:
   cannot run on its own. The runner ships separately as
   `@pdpp/local-collector` and owns the `pdpp-local-collector` binary; `pdpp
   collector ...` is a slim `@pdpp/cli` shim that resolves that package lazily.
-  Public onboarding should use `npx -y @pdpp/local-collector@beta ...` or
-  `npm i -g @pdpp/local-collector@beta` until the package is promoted from beta
-  to latest, unless the operator intentionally wants the `@pdpp/cli` shim.
+  Public onboarding should use `npx -y @pdpp/local-collector ...` or
+  `npm i -g @pdpp/local-collector`, unless the operator intentionally wants
+  the `@pdpp/cli` shim.
 
 - **`pdpp ref ...`** — reference operator diagnostics over `_ref` routes on a
   running reference deployment. Current subcommands: `pdpp ref run timeline
@@ -34,12 +75,9 @@ supports three command namespaces:
 
 ```bash
 # @pdpp/cli package, npx-launched pdpp binary
-npx -y @pdpp/cli@beta --help
+npx -y @pdpp/cli --help
 ```
 
-Use the `beta` dist-tag until PDPP intentionally enables stable `latest`
-publication.
-
 When working from this monorepo without installing or linking the binary, use
 the workspace executable:
 
@@ -54,11 +92,11 @@ local workspace launcher.
 The local collector runtime is a separate public package:
 
 ```bash
-# @pdpp/local-collector@beta package, npx-launched pdpp-local-collector binary
-npx -y @pdpp/local-collector@beta advertise
+# @pdpp/local-collector package, npx-launched pdpp-local-collector binary
+npx -y @pdpp/local-collector advertise
 
-# @pdpp/local-collector@beta package, installs the pdpp-local-collector binary
-npm i -g @pdpp/local-collector@beta
+# @pdpp/local-collector package, installs the pdpp-local-collector binary
+npm i -g @pdpp/local-collector
 pdpp-local-collector advertise
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdpp/cli",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0",
   "description": "Command-line tools for PDPP providers.",
   "type": "module",
   "bin": {
@@ -44,6 +44,6 @@
     "access": "public",
     "provenance": false,
     "registry": "https://registry.npmjs.org/",
-    "tag": "beta"
+    "tag": "latest"
   }
 }

package/src/collector/commands.js

@@ -12,12 +12,11 @@ cannot run on its own. Runner-owned flags are documented by
 Distribution:
   The collector runtime ships in @pdpp/local-collector, a separate npm
   package owned by the PDPP monorepo. @pdpp/cli stays slim and resolves
-  the runner lazily. Until the package is promoted from beta to latest,
-  install or run the beta dist-tag explicitly:
-    # @pdpp/local-collector@beta package, installs pdpp-local-collector
-    npm i -g @pdpp/local-collector@beta
-    # @pdpp/local-collector@beta package, npx-launched pdpp-local-collector
-    npx -y @pdpp/local-collector@beta advertise
+  the runner lazily. Install or run it from npm:
+    # @pdpp/local-collector package, installs pdpp-local-collector
+    npm i -g @pdpp/local-collector
+    # @pdpp/local-collector package, npx-launched pdpp-local-collector
+    npx -y @pdpp/local-collector advertise
   See openspec/changes/publish-pdpp-local-collector/design.md.
 
 Usage:

package/src/collector/runner.js

@@ -10,7 +10,7 @@ import { CollectorUsageError } from './errors.js';
  * Resolve the published `@pdpp/local-collector` package, if installed.
  *
  * The shim prefers an installed `@pdpp/local-collector` so an operator who
- * `npm i -g @pdpp/cli@beta && npm i -g @pdpp/local-collector@beta` can run
+ * `npm i -g @pdpp/cli && npm i -g @pdpp/local-collector` can run
  * `pdpp collector ...` without a monorepo checkout. Resolution is lazy —
  * the CLI does NOT declare a runtime dependency on `@pdpp/local-collector`
  * (per `publish-pdpp-local-collector` task 4.4); a missing package is
@@ -108,12 +108,12 @@ export function resolveTsxBinary(startDir = dirname(fileURLToPath(import.meta.ur
  */
 const RUNNER_MISSING_MESSAGE =
   'pdpp collector requires @pdpp/local-collector. Install once with ' +
-  '"npm i -g @pdpp/local-collector@beta" or run "npx -y @pdpp/local-collector@beta ...". ' +
+  '"npm i -g @pdpp/local-collector" or run "npx -y @pdpp/local-collector ...". ' +
   'See openspec/changes/publish-pdpp-local-collector/design.md.';
 
 const TSX_MISSING_MESSAGE =
   'Could not locate tsx alongside the collector runner. Install ' +
-  '@pdpp/local-collector with "npm i -g @pdpp/local-collector@beta" or run ' +
+  '@pdpp/local-collector with "npm i -g @pdpp/local-collector" or run ' +
   '"pnpm install" at the monorepo root.';
 
 /**

package/src/index.js

@@ -10,6 +10,10 @@ import { runRefGrant } from './ref/commands/grant.js';
 import { runRefTrace } from './ref/commands/trace.js';
 import { runRefLogin } from './ref/commands/login.js';
 import { runRefConnectors } from './ref/commands/connectors.js';
+import { runRefEventSubscriptions } from './ref/commands/event-subscriptions.js';
+import { runRefCall } from './ref/commands/call.js';
+import { readHelp, runRead } from './read/commands.js';
+import { runOwnerAgent } from './owner-agent/command.js';
 import { PdppCliError, PdppUsageError } from './ref/errors.js';
 
 const HELP = `PDPP CLI
@@ -20,9 +24,17 @@ Usage:
   ${PDPP_CLI_BIN_NAME} connect <provider-url>
   ${PDPP_CLI_BIN_NAME} token <provider-url>
 
+${readHelp(PDPP_CLI_BIN_NAME)}
+
 Agent access:
   ${createPdppCliCommand()}
 
+Trusted owner agent (owner-level local automation, not the default agent path):
+  ${PDPP_CLI_BIN_NAME} owner-agent onboard <entrypoint-url> [--credential-file <path>] [--client-id <id>] [--client-name <name>]
+  ${PDPP_CLI_BIN_NAME} owner-agent status [--credential-file <path>] [--entrypoint <url>]
+  ${PDPP_CLI_BIN_NAME} owner-agent control [--credential-file <path>] [--entrypoint <url>]
+  ${PDPP_CLI_BIN_NAME} owner-agent revoke [--credential-file <path>] [--entrypoint <url>] [--cache-root <dir>] [--owner-session <cookie>]
+
 Local collector (pair a host you control with a reference deployment):
   ${PDPP_CLI_BIN_NAME} collector advertise
   ${PDPP_CLI_BIN_NAME} collector enroll --base-url <url> --code <code>
@@ -30,21 +42,30 @@ Local collector (pair a host you control with a reference deployment):
 
 Reference diagnostics (reference server only):
   ${PDPP_CLI_BIN_NAME} ref login <reference-url>
+  ${PDPP_CLI_BIN_NAME} ref call <method> <path> --as-url <url> [--data <json> | --data-stdin]
   ${PDPP_CLI_BIN_NAME} ref run timeline <run-id> --as-url <url>
   ${PDPP_CLI_BIN_NAME} ref grant timeline <grant-id> --as-url <url>
   ${PDPP_CLI_BIN_NAME} ref trace show <trace-id> --as-url <url>
   ${PDPP_CLI_BIN_NAME} ref connectors list --as-url <url>
   ${PDPP_CLI_BIN_NAME} ref connectors show <connector-id> --as-url <url>
+  ${PDPP_CLI_BIN_NAME} ref event-subscriptions list --as-url <url> [--client-id <id>] [--grant-id <id>] [--status <status>]
+  ${PDPP_CLI_BIN_NAME} ref event-subscriptions show <subscription-id> --as-url <url>
+  ${PDPP_CLI_BIN_NAME} ref event-subscriptions disable <subscription-id> --as-url <url> [--reason <text>] [--yes]
 
 Notes:
   Do not ask users for owner bearer tokens for routine delegated access.
-  "pdpp collector" is a thin @pdpp/cli shim. Install @pdpp/local-collector@beta
-  once, or use "npx -y @pdpp/local-collector@beta ..." directly, for filesystem
-  collectors like Claude Code and Codex until the package is promoted to latest.
+  "pdpp collector" is a thin @pdpp/cli shim. Install @pdpp/local-collector
+  once, or use "npx -y @pdpp/local-collector ..." directly, for filesystem
+  collectors like Claude Code and Codex.
   "pdpp ref" commands require a running PDPP reference server and an owner session.
   "pdpp ref login" caches an owner session in project-local .pdpp/ with mode 0600;
   later "pdpp ref" commands use the cache when --owner-session and
   PDPP_OWNER_SESSION_COOKIE are absent.
+  "pdpp ref call" is the escape hatch for owner POST/GET routes without a typed
+  command. It infers auth from the path: /_ref/* uses the owner session cookie,
+  /v1/owner/* uses the owner bearer (PDPP_OWNER_TOKEN or --owner-token-stdin).
+  Bodies are sent as JSON (CSRF-exempt server-side), so no _csrf parsing is
+  needed. Secrets are never printed.
 `;
 
 export async function runCli(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
@@ -106,31 +127,61 @@ export async function runCli(argv, io = { stdout: process.stdout, stderr: proces
     return await runCollector(rest, io);
   }
 
+  if (command === 'read') {
+    try {
+      return await runRead(rest, io);
+    } catch (error) {
+      if (error instanceof PdppUsageError) {
+        io.stderr.write(`${error.message}\n`);
+        return error.exitCode;
+      }
+      if (error instanceof PdppCliError) {
+        io.stderr.write(`${error.message}\n`);
+        return error.exitCode;
+      }
+      throw error;
+    }
+  }
+
+  if (command === 'owner-agent') {
+    return await runOwnerAgent(rest, io);
+  }
+
   if (command === 'ref') {
     const [refCommand, ...refRest] = rest;
 
     if (!refCommand || refCommand === '--help' || refCommand === '-h') {
       io.stdout.write(`Reference diagnostics (reference server only):\n`);
       io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref login <reference-url> [--password-stdin] [--cache-root <dir>]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref call <method> <path> --as-url <url> [--data <json> | --data-stdin] [--auth cookie|bearer] [--owner-session <cookie>] [--owner-token-stdin] [--status-only] [--format json|table]\n`);
       io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref run timeline <run-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
       io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref grant timeline <grant-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
       io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref trace show <trace-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
       io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref connectors list --as-url <url> [--owner-session <cookie>] [--format json|table] [--verbose]\n`);
       io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref connectors show <connector-id> --as-url <url> [--owner-session <cookie>] [--format json|table] [--verbose]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref event-subscriptions list --as-url <url> [--client-id <id>] [--grant-id <id>] [--status <status>] [--owner-session <cookie>] [--format json|table]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref event-subscriptions show <subscription-id> --as-url <url> [--owner-session <cookie>] [--format json|table]\n`);
+      io.stdout.write(`  ${PDPP_CLI_BIN_NAME} ref event-subscriptions disable <subscription-id> --as-url <url> [--reason <text>] [--yes] [--owner-session <cookie>]\n`);
       io.stdout.write(`\nNotes:\n`);
       io.stdout.write(`  "ref login" prompts the reference server's owner-login route and caches the\n`);
       io.stdout.write(`  resulting session in .pdpp/owner-sessions/ (mode 0600). The cookie value is\n`);
       io.stdout.write(`  never printed. The password must come from --password-stdin or\n`);
       io.stdout.write(`  PDPP_OWNER_PASSWORD; it is not accepted on the command line.\n`);
+      io.stdout.write(`  "ref call" infers auth from the path: /_ref/* uses the owner session cookie,\n`);
+      io.stdout.write(`  /v1/owner/* uses the owner bearer (PDPP_OWNER_TOKEN or --owner-token-stdin).\n`);
+      io.stdout.write(`  It refuses a mismatched --auth, sends bodies as JSON (so no _csrf is needed),\n`);
+      io.stdout.write(`  and never prints the cookie or bearer.\n`);
       return 0;
     }
 
     const refDispatch = {
       login: runRefLogin,
+      call: runRefCall,
       run: runRefRun,
       grant: runRefGrant,
       trace: runRefTrace,
       connectors: runRefConnectors,
+      'event-subscriptions': runRefEventSubscriptions,
     };
     const handler = refDispatch[refCommand];
     if (!handler) {

package/src/owner-agent/command.js

@@ -0,0 +1,368 @@
+// `pdpp owner-agent` command surface.
+//
+// Subcommands:
+//   onboard <entrypoint-url> [--credential-file <path>] [--client-id <id>]
+//       Discover the trusted owner-agent onboarding profile, run browser-
+//       mediated owner approval, and write the issued owner-agent credential to
+//       a local file with 0600 permissions. The bearer is never printed.
+//   status [--credential-file <path>] [--entrypoint <url>]
+//       Introspect the stored credential and print only non-secret status.
+//   control [--credential-file <path>] [--entrypoint <url>]
+//       Discover non-secret owner-agent control capabilities (the
+//       GET /v1/owner/control capability document) and list configured
+//       connection instances (GET /v1/owner/connections) with their
+//       connection_id, connector identity, and label/label-needed state. The
+//       bearer is sent as an Authorization header and never printed.
+//   revoke [--credential-file <path>] [--entrypoint <url>]
+//       Revoke the stored credential via owner-session-gated RFC 7592 client
+//       delete. Uses the cached `pdpp ref login` owner session when present.
+//
+// This command is owner-level local automation, distinct from the grant-scoped
+// `pdpp connect` path. It must never present owner bearers as the default path
+// for ordinary agents or external MCP clients.
+
+import { parseArgs } from '../ref/args.js';
+import { ownerSessionHeaders } from '../ref/fetch.js';
+
+import { resolveCredentialFile, writeOwnerAgentCredential, buildCredentialRecord } from './credential-store.js';
+import { discoverOwnerAgentControl, formatOwnerAgentControl } from './control.js';
+import {
+  findConnectorTemplates,
+  formatConnectionSetupPlan,
+  formatConnectorTemplateExplain,
+  formatConnectorTemplates,
+  requestConnectionSetupPlan,
+  requestConnectorTemplates,
+} from './setup.js';
+import { discoverOwnerAgentProfile, normalizeEntrypointUrl } from './discovery.js';
+import { initiateDeviceAuthorization, pollForOwnerAgentToken } from './device-flow.js';
+import { OwnerAgentError } from './errors.js';
+import { introspectOwnerAgentCredential, readCredentialRecord, revokeOwnerAgentCredential } from './lifecycle.js';
+
+const USAGE = `Trusted owner-agent onboarding (owner-level local automation):
+  pdpp owner-agent onboard <entrypoint-url> [--credential-file <path>] [--client-id <id>] [--client-name <name>]
+  pdpp owner-agent status  [--credential-file <path>] [--entrypoint <url>]
+  pdpp owner-agent control [--credential-file <path>] [--entrypoint <url>]
+  pdpp owner-agent connectors list|search <query>|explain <connector-id> [--credential-file <path>] [--entrypoint <url>]
+  pdpp owner-agent setup   <connector-id> [--display-name <name>] [--credential-file <path>] [--entrypoint <url>]
+  pdpp owner-agent revoke  [--credential-file <path>] [--entrypoint <url>] [--cache-root <dir>] [--owner-session <cookie>]
+
+Notes:
+  This is a deliberate local-admin mode, not the default agent path. Ordinary
+  agents should use grant-scoped access (pdpp connect). The issued bearer is
+  written to a local file with 0600 permissions and is never printed.
+  "control" lists non-secret control capabilities and configured connections
+  (connection_id, connector, label/label-needed); it never prints the bearer.
+  "connectors" lists/searches/explains available source setup options from the
+  non-secret connector-template catalog. It is read-only and does not mint
+  enrollment codes or provider credentials.
+  "setup" requests the same non-secret connection setup plan and next-step
+  contract the console and owner-agent REST surface, from the shared server
+  planner (POST /v1/owner/connections/intents); it never prints the bearer and
+  never returns provider secrets.
+  Revocation uses the owner-session-gated dashboard/RFC 7592 path; run
+  "pdpp ref login <authorization-server>" first if no owner session is cached.
+  Daisy's first supported target: ~/applications/daisy/.pi/agent/pdpp-owner-agent.json`;
+
+export async function runOwnerAgent(argv, io = {}, deps = {}) {
+  const out = io.stdout ?? process.stdout;
+  const err = io.stderr ?? process.stderr;
+  const [subcommand, ...rest] = argv;
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+    out.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  try {
+    if (subcommand === 'onboard') {
+      return await runOnboard(rest, { out }, deps);
+    }
+    if (subcommand === 'status') {
+      return await runStatus(rest, { out }, deps);
+    }
+    if (subcommand === 'control') {
+      return await runControl(rest, { out }, deps);
+    }
+    if (subcommand === 'connectors') {
+      return await runConnectors(rest, { out }, deps);
+    }
+    if (subcommand === 'setup') {
+      return await runSetup(rest, { out }, deps);
+    }
+    if (subcommand === 'revoke') {
+      return await runRevoke(rest, { out }, deps);
+    }
+    err.write(`Unknown owner-agent command: ${subcommand}\n\n${USAGE}\n`);
+    return 64;
+  } catch (error) {
+    if (error instanceof OwnerAgentError) {
+      err.write(`${error.message}\n`);
+      return error.exitCode;
+    }
+    throw error;
+  }
+}
+
+async function runConnectors(argv, { out }, deps) {
+  const { record, positionals } = await loadRecord(argv, deps);
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const action = positionals[0] ?? 'list';
+  const templates = await requestConnectorTemplates({ fetchFn, record });
+
+  if (action === 'list') {
+    out.write(formatConnectorTemplates(templates));
+    return 0;
+  }
+  if (action === 'search') {
+    const query = positionals.slice(1).join(' ').trim();
+    if (!query) {
+      throw new OwnerAgentError(
+        'invalid_request',
+        'Usage: pdpp owner-agent connectors search <query> [--credential-file <path>] [--entrypoint <url>]',
+        64
+      );
+    }
+    out.write(formatConnectorTemplates(templates, { query }));
+    return 0;
+  }
+  if (action === 'explain') {
+    const connectorId = positionals[1];
+    if (typeof connectorId !== 'string' || !connectorId.trim()) {
+      throw new OwnerAgentError(
+        'invalid_request',
+        'Usage: pdpp owner-agent connectors explain <connector-id> [--credential-file <path>] [--entrypoint <url>]',
+        64
+      );
+    }
+    const matches = findConnectorTemplates(templates, connectorId);
+    const exact = matches.find((template) => {
+      const key = template?.connector_key ?? template?.connector_id;
+      return typeof key === 'string' && key.toLowerCase() === connectorId.trim().toLowerCase();
+    });
+    out.write(formatConnectorTemplateExplain(exact ?? matches[0] ?? null));
+    return 0;
+  }
+
+  throw new OwnerAgentError(
+    'invalid_request',
+    `Unknown owner-agent connectors command: ${action}\n\n${USAGE}`,
+    64
+  );
+}
+
+async function runOnboard(argv, { out }, deps) {
+  const { flags, positionals } = parseArgs(argv);
+  const entrypoint = normalizeEntrypointUrl(positionals[0]);
+  if (!entrypoint) {
+    throw new OwnerAgentError(
+      'invalid_entrypoint',
+      'Usage: pdpp owner-agent onboard <entrypoint-url> [--credential-file <path>]',
+      64
+    );
+  }
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const now = deps.now ?? (() => Date.now());
+
+  const profile = await discoverOwnerAgentProfile(entrypoint, { fetch: fetchFn });
+
+  const explicitClientId = typeof flags['client-id'] === 'string' ? flags['client-id'] : undefined;
+  const registeredClient = explicitClientId
+    ? { client_id: explicitClientId, client_name: null }
+    : await registerOwnerAgentClient({
+        fetchFn,
+        endpoint: profile.registrationEndpoint,
+        clientName:
+          typeof flags['client-name'] === 'string' && flags['client-name'].trim()
+            ? flags['client-name'].trim()
+            : 'PDPP trusted owner agent',
+      });
+  const clientId = registeredClient.client_id;
+  const registrationClientUri = buildRegistrationClientUri(profile, clientId);
+  const device = await initiateDeviceAuthorization({
+    fetchFn,
+    endpoint: profile.deviceAuthorizationEndpoint,
+    clientId,
+  });
+
+  // Print only non-secret approval instructions.
+  out.write('Trusted owner-agent onboarding (owner-level local automation).\n');
+  out.write(`Open this URL in a browser to approve owner-agent access:\n${device.verificationUri}\n`);
+  if (device.userCode) {
+    out.write(`Verification code: ${device.userCode}\n`);
+  }
+  out.write('Waiting for owner approval...\n');
+
+  const credential = await pollForOwnerAgentToken({
+    fetchFn,
+    endpoint: profile.tokenEndpoint,
+    clientId,
+    deviceCode: device.deviceCode,
+    intervalMs: device.intervalMs,
+    timeoutMs: device.expiresInMs,
+    sleep: deps.sleep,
+    now,
+    onPending: deps.onPending,
+  });
+
+  const record = buildCredentialRecord({
+    resource: profile.resource,
+    authorizationServer: profile.authorizationServer,
+    credential,
+    clientId,
+    introspectionEndpoint: profile.introspectionEndpoint,
+    registrationEndpoint: profile.registrationEndpoint,
+    registrationClientUri,
+    schemaEndpoint: profile.schemaEndpoint,
+    schemaCompactEndpoint: profile.schemaCompactEndpoint,
+    streamsEndpoint: profile.streamsEndpoint,
+    createdAt: new Date(now()).toISOString(),
+  });
+
+  const targetPath = resolveCredentialFile({
+    credentialFile: typeof flags['credential-file'] === 'string' ? flags['credential-file'] : undefined,
+    resource: profile.resource,
+    home: deps.home,
+  });
+  await writeOwnerAgentCredential(targetPath, record);
+
+  // Non-secret status only. Never print credential.access_token.
+  out.write(`Owner-agent credential stored at ${targetPath} (mode 0600)\n`);
+  out.write(`  token kind: ${record.pdpp_token_kind}\n`);
+  if (record.client_id) {
+    out.write(`  client id: ${record.client_id}\n`);
+  }
+  out.write(`  resource: ${record.resource}\n`);
+  if (record.expires_at) {
+    out.write(`  expires: ${record.expires_at}\n`);
+  }
+  if (record.registration_client_uri) {
+    out.write('  revocation: owner-session-gated RFC 7592 client delete handle stored\n');
+  }
+  out.write('Note: /mcp rejects owner bearers; this credential is for owner-level REST/control-plane use.\n');
+  return 0;
+}
+
+async function runStatus(argv, { out }, deps) {
+  const { record } = await loadRecord(argv, deps);
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const introspection = await introspectOwnerAgentCredential({ fetchFn, record });
+  out.write(`active: ${introspection.active}\n`);
+  if (introspection.token_kind) out.write(`token kind: ${introspection.token_kind}\n`);
+  if (introspection.sub) out.write(`subject: ${introspection.sub}\n`);
+  if (introspection.client_id) out.write(`client id: ${introspection.client_id}\n`);
+  if (introspection.exp) out.write(`expires (epoch): ${introspection.exp}\n`);
+  return introspection.active ? 0 : 1;
+}
+
+async function runControl(argv, { out }, deps) {
+  const { record } = await loadRecord(argv, deps);
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const { control, connections } = await discoverOwnerAgentControl({ fetchFn, record });
+  out.write(formatOwnerAgentControl({ control, connections }));
+  return 0;
+}
+
+async function runSetup(argv, { out }, deps) {
+  const { record, flags, positionals } = await loadRecord(argv, deps);
+  const connectorId = positionals[0];
+  if (typeof connectorId !== 'string' || !connectorId.trim()) {
+    throw new OwnerAgentError(
+      'invalid_request',
+      'Usage: pdpp owner-agent setup <connector-id> [--display-name <name>] [--credential-file <path>] [--entrypoint <url>]',
+      64
+    );
+  }
+  const displayName = typeof flags['display-name'] === 'string' ? flags['display-name'] : null;
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const plan = await requestConnectionSetupPlan({ fetchFn, record, connectorId, displayName });
+  out.write(formatConnectionSetupPlan(plan));
+  return 0;
+}
+
+async function runRevoke(argv, { out }, deps) {
+  const { record, targetPath, flags } = await loadRecord(argv, deps);
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const ownerSession = ownerSessionHeaders({
+    ownerSession: flags['owner-session'] || '',
+    referenceUrl: record.authorization_server,
+    cacheRoot: flags['cache-root'],
+  }).Cookie;
+  const result = await revokeOwnerAgentCredential({ fetchFn, record, ownerSessionCookie: ownerSession });
+  out.write(
+    result.already_absent
+      ? `Owner-agent credential already absent at the authorization server (${targetPath}).\n`
+      : `Owner-agent credential revoked (${targetPath}).\n`
+  );
+  return 0;
+}
+
+async function loadRecord(argv, deps) {
+  const { flags, positionals } = parseArgs(argv);
+  const credentialFile = typeof flags['credential-file'] === 'string' ? flags['credential-file'] : undefined;
+  const entrypoint = typeof flags.entrypoint === 'string' ? normalizeEntrypointUrl(flags.entrypoint) : null;
+  const targetPath = resolveCredentialFile({
+    credentialFile,
+    resource: entrypoint ?? 'https://owner-agent.invalid',
+    home: deps.home,
+  });
+  const record = await readCredentialRecord(targetPath);
+  return { record, targetPath, flags, positionals };
+}
+
+export { USAGE as OWNER_AGENT_USAGE };
+
+async function registerOwnerAgentClient({ fetchFn, endpoint, clientName }) {
+  if (!endpoint) {
+    throw new OwnerAgentError(
+      'registration_unavailable',
+      'Owner-agent onboarding requires a registration_endpoint, or pass --client-id for an existing public client.'
+    );
+  }
+  let response;
+  try {
+    response = await fetchFn(endpoint, {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        client_name: clientName,
+        token_endpoint_auth_method: 'none',
+      }),
+    });
+  } catch (error) {
+    throw new OwnerAgentError('registration_failed', `Dynamic client registration failed: ${error.message}.`);
+  }
+  let json = null;
+  try {
+    json = await response.json();
+  } catch {
+    json = null;
+  }
+  if (!response.ok) {
+    const code = json?.error?.code ?? json?.error ?? `http_${response.status}`;
+    throw new OwnerAgentError('registration_failed', `Dynamic client registration failed (${code}).`);
+  }
+  if (!json?.client_id) {
+    throw new OwnerAgentError('registration_invalid', 'Dynamic client registration response did not include client_id.');
+  }
+  return json;
+}
+
+function buildRegistrationClientUri(profile, clientId) {
+  if (!(profile && clientId)) {
+    return null;
+  }
+  if (profile.revocationPathTemplate) {
+    return profile.revocationPathTemplate.replace('{client_id}', encodeURIComponent(clientId));
+  }
+  if (profile.registrationEndpoint) {
+    const base = profile.registrationEndpoint.endsWith('/')
+      ? profile.registrationEndpoint
+      : `${profile.registrationEndpoint}/`;
+    return `${base}${encodeURIComponent(clientId)}`;
+  }
+  return null;
+}