@ory/argus 0.11.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # Ory Argus: Agent and Developer Experience
 
-The core API behind every Ory Agent Plugin and Extension. Argus wraps [Ory Identities](https://www.ory.com/ory-ecosystem), [Ory Permissions](https://ory.com/permissions), MCP authorization, and distributed tracing into a single client. Each of the harness packages (`@ory/claude-code`, `@ory/codex`, `@ory/gemini-cli`, `@ory/openclaw`, `@ory/opencode`) is a thin adapter that maps one harness's hook contract onto Argus.
+The core API behind every Ory Agent Plugin and Extension. Argus wraps [Ory Identities](https://www.ory.com/ory-ecosystem), [Ory Permissions](https://ory.com/permissions), MCP authorization, and distributed tracing into a single client. Each harness package (`@ory/claude-code`, `@ory/codex`, `@ory/gemini-cli`, and the rest — see the [root README](../../README.md) for the full list) is a thin adapter that maps one harness's hook contract onto Argus.
 
 Argus is also published on its own so you can build new harness plugins or extensions, embed Ory into a custom agent runtime, or instrument any SDK that exposes event lifecycle hooks for session start, tool execution, and tool completion.
 

package/dist/agent-auth.d.ts

@@ -88,6 +88,29 @@ export declare function loadAgentDynamicCredentials(): OryAgentDynamicCredential
 export declare function saveAgentDynamicCredentials(creds: OryAgentDynamicCredentials): void;
 /** Remove persisted DCR credentials (e.g. after revocation or unregister). */
 export declare function clearAgentDynamicCredentials(): void;
+/** Outcome of a best-effort RFC 7592 client revocation. */
+export interface RevokeAgentClientResult {
+    /**
+     * `deleted` — the server-side client was removed (or was already gone);
+     * `skipped` — no management credentials were persisted, so we couldn't
+     * try; `failed` — the DELETE was attempted but the server rejected it.
+     */
+    status: "deleted" | "skipped" | "failed";
+    /** HTTP status when the server responded. */
+    httpStatus?: number;
+    /** Human-readable detail for warnings (present on `skipped` / `failed`). */
+    message?: string;
+}
+/**
+ * Best-effort RFC 7592 `DELETE` of a dynamically-registered OAuth2 client.
+ *
+ * Requires the registration management URI and access token to have been
+ * persisted at registration time; otherwise returns `{ status: "skipped" }`.
+ * Never throws — a missing client (404) counts as `deleted`, and any other
+ * network/HTTP failure is captured in the result so callers can warn and
+ * still clear local state.
+ */
+export declare function revokeAgentDynamicClient(creds: OryAgentDynamicCredentials): Promise<RevokeAgentClientResult>;
 export interface RegisterAgentClientArgs {
     projectUrl: string;
     /** Bearer used as the initial access token (RFC 7591 §3). */

package/dist/agent-auth.js

@@ -36,6 +36,7 @@ exports.clearSubAgentDynamicCredentials = clearSubAgentDynamicCredentials;
 exports.loadAgentDynamicCredentials = loadAgentDynamicCredentials;
 exports.saveAgentDynamicCredentials = saveAgentDynamicCredentials;
 exports.clearAgentDynamicCredentials = clearAgentDynamicCredentials;
+exports.revokeAgentDynamicClient = revokeAgentDynamicClient;
 exports.registerAgentClient = registerAgentClient;
 exports.resolveAgentCredentials = resolveAgentCredentials;
 exports.fetchClientCredentialsToken = fetchClientCredentialsToken;
@@ -116,6 +117,40 @@ function clearAgentDynamicCredentials() {
         return next;
     });
 }
+/**
+ * Best-effort RFC 7592 `DELETE` of a dynamically-registered OAuth2 client.
+ *
+ * Requires the registration management URI and access token to have been
+ * persisted at registration time; otherwise returns `{ status: "skipped" }`.
+ * Never throws — a missing client (404) counts as `deleted`, and any other
+ * network/HTTP failure is captured in the result so callers can warn and
+ * still clear local state.
+ */
+async function revokeAgentDynamicClient(creds) {
+    if (!creds.registrationClientUri || !creds.registrationAccessToken) {
+        return {
+            status: "skipped",
+            message: "no registration_access_token persisted",
+        };
+    }
+    const oidc = new client_1.OidcApi(new client_1.Configuration({
+        basePath: creds.projectUrl,
+        accessToken: creds.registrationAccessToken,
+    }));
+    try {
+        await oidc.deleteOidcDynamicClient({ id: creds.clientId });
+        return { status: "deleted" };
+    }
+    catch (err) {
+        const httpStatus = err
+            ?.response?.status;
+        // Already gone server-side — treat as success.
+        if (httpStatus === 404)
+            return { status: "deleted", httpStatus };
+        const message = err instanceof Error ? err.message : String(err);
+        return { status: "failed", httpStatus, message };
+    }
+}
 /**
  * Register a new OAuth2 client via RFC 7591. Authorization is carried
  * either by the user's interactive token (the natural bootstrap) or by
@@ -144,7 +179,13 @@ async function registerAgentClient(args) {
                 scope: "openid offline_access",
                 token_endpoint_auth_method: "client_secret_post",
             },
-        });
+        }, 
+        // The generated SDK declares no security scheme for the public DCR create
+        // operation (`/oauth2/register`), so it never attaches the bearer from the
+        // Configuration's `accessToken`. Ory projects that gate DCR behind an
+        // initial access token then reject the unauthenticated request and the
+        // agent never gets credentials. Send the bearer explicitly.
+        args.auth ? { headers: { Authorization: `Bearer ${args.auth}` } } : undefined);
     }
     catch (err) {
         const status = err?.response?.status;

package/dist/auth.js

@@ -103,6 +103,10 @@ async function pkceLogin(options) {
     server.close();
     if (result.kind !== "ok")
         return result;
+    // Mirror the browser success page on the terminal so it's unambiguous the
+    // flow finished and the browser tab can be closed — the user's attention is
+    // often still on the browser at this point.
+    process.stderr.write("Signed in. You can close the browser tab — continuing here…\n\n");
     try {
         const tokens = await exchangeCodeForTokens({
             projectUrl: options.projectUrl,
@@ -203,18 +207,18 @@ function waitForCallback(server, opts) {
             }
             const error = url.searchParams.get("error");
             if (error) {
-                respond(res, 400, "Authentication declined. You may close this window.");
+                respondHtml(res, 400, resultPage("cancelled"));
                 settle({ kind: "declined", reason: "user_denied" });
                 return;
             }
             const state = url.searchParams.get("state");
             const code = url.searchParams.get("code");
             if (!code || state !== opts.expectedState) {
-                respond(res, 400, "State mismatch.");
+                respondHtml(res, 400, resultPage("mismatch"));
                 settle({ kind: "declined", reason: "state_mismatch" });
                 return;
             }
-            respond(res, 200, "Sign-in complete. You may close this window and return to your terminal.");
+            respondHtml(res, 200, resultPage("success"));
             settle({ kind: "ok", code });
         };
         server.on("request", onRequest);
@@ -230,6 +234,75 @@ function respond(res, status, body) {
     res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
     res.end(body + "\n");
 }
+function respondHtml(res, status, html) {
+    res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
+    res.end(html);
+}
+/**
+ * The page the browser lands on after the OAuth2 redirect. The whole point is
+ * to make the next action unambiguous: on success it tells the user, in plain
+ * words, that they can close the tab and return to the terminal (the #1
+ * source of "is it done? do I close this?" confusion). Self-contained HTML —
+ * inline styles only, Ory-branded (Indigo #4F46E5), no external requests — so
+ * it renders identically offline and on the loopback origin.
+ */
+function resultPage(kind) {
+    const view = {
+        success: {
+            accent: "#4F46E5", // Ory Indigo
+            icon: "✓", // ✓
+            title: "Signed in to Ory",
+            body: "You can <strong>close this tab</strong> and return to your terminal — setup continues automatically.",
+        },
+        cancelled: {
+            accent: "#F43F5E", // Ory Rose
+            icon: "&#10005;", // ✕
+            title: "Sign-in cancelled",
+            body: "No changes were made. <strong>Close this tab</strong> and return to your terminal to try again.",
+        },
+        mismatch: {
+            accent: "#F43F5E",
+            icon: "!",
+            title: "Sign-in could not be verified",
+            body: "The login response failed a security check. <strong>Close this tab</strong> and re-run the login from your terminal.",
+        },
+    }[kind];
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${view.title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; align-items: center; justify-content: center;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: #0F172A; color: #E2E8F0;
+  }
+  .card { max-width: 26rem; padding: 2.5rem 2rem; text-align: center; }
+  .badge {
+    width: 4rem; height: 4rem; border-radius: 9999px; margin: 0 auto 1.25rem;
+    display: flex; align-items: center; justify-content: center;
+    font-size: 2rem; line-height: 1; font-weight: 700;
+    background: ${view.accent}22; color: ${view.accent};
+  }
+  h1 { font-size: 1.35rem; margin: 0 0 .5rem; color: #F8FAFC; }
+  p { margin: 0; line-height: 1.55; color: #94A3B8; }
+  strong { color: #E2E8F0; font-weight: 600; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="badge">${view.icon}</div>
+    <h1>${view.title}</h1>
+    <p>${view.body}</p>
+  </div>
+</body>
+</html>
+`;
+}
 // ─── Browser launch ───────────────────────────────────────────────────
 async function launchBrowser(url, override) {
     if (override) {

package/dist/cli-invocation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Helper for rendering copy-pasteable `npx` invocations in CLI banners,
+ * help text, and prompts.
+ *
+ * Every harness plugin ships a CLI bin named `ory-<short>` (e.g.
+ * `ory-claude`, `ory-gemini`). Those bins only resolve on `PATH` when the
+ * package is already installed. In the common install flow the user runs
+ * `npx @ory/<harness> install` — a one-shot npx invocation that leaves
+ * nothing on `PATH` — so a follow-up banner that says `npx ory-claude
+ * permissions bootstrap` fails: npm can't find a package literally named
+ * `ory-claude` and errors out.
+ *
+ * The always-resolvable form is `npx -y -p @ory/<harness> ory-<short>
+ * <args>`, which is exactly what the READMEs document. {@link oryNpx}
+ * renders that prefix for a given bin name so every banner is
+ * copy-paste-safe from a clean shell.
+ */
+/**
+ * Render a copy-pasteable `npx` invocation prefix for a harness bin.
+ *
+ * Returns `npx -y -p <package> <binName>` when the bin's package is
+ * known, so the command resolves from a clean shell. Each package ships
+ * sibling `-setup` and `-hook` bins alongside its main `ory-<short>` bin;
+ * those normalize to the same package. Falls back to the bare `npx
+ * <binName>` for unknown bins (preserving prior behavior) — that only
+ * resolves when the bin is already on `PATH`, so keep
+ * {@link BIN_TO_PACKAGE} in sync with the shipped bins.
+ *
+ * @example
+ *   oryNpx("ory-claude")                       // "npx -y -p @ory/claude-code ory-claude"
+ *   oryNpx("ory-claude-setup")                 // "npx -y -p @ory/claude-code ory-claude-setup"
+ *   `${oryNpx("ory-claude")} permissions status`
+ */
+export declare function oryNpx(binName: string): string;

package/dist/cli-invocation.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Helper for rendering copy-pasteable `npx` invocations in CLI banners,
+ * help text, and prompts.
+ *
+ * Every harness plugin ships a CLI bin named `ory-<short>` (e.g.
+ * `ory-claude`, `ory-gemini`). Those bins only resolve on `PATH` when the
+ * package is already installed. In the common install flow the user runs
+ * `npx @ory/<harness> install` — a one-shot npx invocation that leaves
+ * nothing on `PATH` — so a follow-up banner that says `npx ory-claude
+ * permissions bootstrap` fails: npm can't find a package literally named
+ * `ory-claude` and errors out.
+ *
+ * The always-resolvable form is `npx -y -p @ory/<harness> ory-<short>
+ * <args>`, which is exactly what the READMEs document. {@link oryNpx}
+ * renders that prefix for a given bin name so every banner is
+ * copy-paste-safe from a clean shell.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oryNpx = oryNpx;
+/**
+ * Maps each harness CLI bin name to its npm package. Keyed by the bin
+ * name callers pass into the shared CLI helpers (always `ory-<short>`).
+ * When adding a new harness plugin, add its bin here so its banners emit
+ * a resolvable command.
+ */
+const BIN_TO_PACKAGE = {
+    "ory-claude": "@ory/claude-code",
+    "ory-codex": "@ory/codex",
+    "ory-gemini": "@ory/gemini-cli",
+    "ory-openclaw": "@ory/openclaw",
+    "ory-opencode": "@ory/opencode",
+    "ory-continue": "@ory/continue",
+    "ory-goose": "@ory/goose",
+    "ory-cline": "@ory/cline",
+    "ory-amp": "@ory/amp",
+    "ory-pi": "@ory/pi",
+    "ory-antigravity": "@ory/antigravity",
+};
+/**
+ * Render a copy-pasteable `npx` invocation prefix for a harness bin.
+ *
+ * Returns `npx -y -p <package> <binName>` when the bin's package is
+ * known, so the command resolves from a clean shell. Each package ships
+ * sibling `-setup` and `-hook` bins alongside its main `ory-<short>` bin;
+ * those normalize to the same package. Falls back to the bare `npx
+ * <binName>` for unknown bins (preserving prior behavior) — that only
+ * resolves when the bin is already on `PATH`, so keep
+ * {@link BIN_TO_PACKAGE} in sync with the shipped bins.
+ *
+ * @example
+ *   oryNpx("ory-claude")                       // "npx -y -p @ory/claude-code ory-claude"
+ *   oryNpx("ory-claude-setup")                 // "npx -y -p @ory/claude-code ory-claude-setup"
+ *   `${oryNpx("ory-claude")} permissions status`
+ */
+function oryNpx(binName) {
+    const base = binName.replace(/-(setup|hook)$/, "");
+    const pkg = BIN_TO_PACKAGE[base];
+    return pkg ? `npx -y -p ${pkg} ${binName}` : `npx ${binName}`;
+}

package/dist/cli.d.ts

@@ -22,22 +22,32 @@ export declare function printOryConfig(): void;
  */
 export declare function printEnvironment(): void;
 /**
- * Print the last 5 debug log entries if ORY_AGENT_LOG_FILE is set and exists.
+ * Print the last 5 debug log entries. When `harness` is given the path is
+ * resolved the same way the plugin does at runtime — the default per-harness
+ * data-dir location when `ORY_AGENT_LOG_FILE` is unset — so `status` finds the
+ * log without the reader hand-setting env vars. The debug log only exists when
+ * a session ran with `ORY_AGENT_DEBUG=true`; when it doesn't, this prints a
+ * one-line pointer on how to turn it on rather than staying silent.
  */
-export declare function printLogTail(): void;
+export declare function printLogTail(harness?: string): void;
 /**
  * Print the "Configure your Ory credentials" help text.
  */
 export declare function printEnvHelp(binName: string): void;
 /**
- * Print the last 5 trace entries if ORY_AGENT_TRACE_FILE is set and exists.
+ * Print the last 5 trace spans. When `harness` is given the path is resolved
+ * the same way the plugin does at runtime — the default per-harness data-dir
+ * location when `ORY_AGENT_TRACE_FILE` is unset — so `status` shows recent
+ * activity out of the box (traces are written on every recorded span). When no
+ * spans have been recorded yet, prints a one-line pointer at the trace file so
+ * the reader knows where to look (and how to watch it live).
  */
-export declare function printTraceTail(): void;
+export declare function printTraceTail(harness?: string): void;
 /**
  * Run the live trace watcher. Tails the NDJSON trace file and prints
  * formatted spans to stdout as they arrive. Blocks until interrupted.
  */
-export declare function runWatchCommand(args: string[]): void;
+export declare function runWatchCommand(harness: string, args: string[]): void;
 /**
  * Returns true if `/dev/tty` can be opened for reading. Use this before
  * attempting to prompt the user — the harness has already taken stdin so