@ory/argus 0.13.0 → 0.13.2

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "repo": "ory-agent-plugins",
-  "commit": "2702eaeaad8d59305e3605a1543b47c6222b4967",
-  "commitShort": "2702eae",
+  "commit": "4961e2084b50f7c37a1c44c93735998394afe12d",
+  "commitShort": "4961e20",
   "branch": "main",
-  "commitDate": "2026-07-14T10:53:59-07:00",
+  "commitDate": "2026-07-14T13:13:40-07:00",
   "dirty": false,
-  "builtAt": "2026-07-14T17:57:49.846Z"
+  "builtAt": "2026-07-14T20:17:46.098Z"
 }

package/dist/interactive-setup.js

@@ -83,6 +83,7 @@ const tool_catalog_js_1 = require("./tool-catalog.js");
 const index_js_1 = require("./local/index.js");
 const subject_js_1 = require("./subject.js");
 const permissions_cli_js_1 = require("./permissions-cli.js");
+const version_cli_js_1 = require("./version-cli.js");
 const ui = __importStar(require("./ui.js"));
 /** Loopback redirect URIs the PKCE user login expects on the OAuth2 client. */
 exports.LOOPBACK_REDIRECT_URIS = auth_js_1.LOOPBACK_PORTS.map((port) => `http://127.0.0.1:${port}/callback`);
@@ -155,6 +156,17 @@ async function installOryCli() {
  * open-coded as a local `postInstallPermissions` helper.
  */
 async function runPostInstall(binName, harness, args = [], deps = {}) {
+    // Surface the running CLI version up front. `npx -p @ory/<harness>` (no
+    // version pin) will happily reuse a previously-cached install rather than
+    // re-resolve to latest, so a user can silently be running an old CLI whose
+    // install flow predates newer behavior (e.g. the interactive setup wizard)
+    // while believing they're on the current release. Printing the version makes
+    // that mismatch visible at a glance; the README's troubleshooting note
+    // explains how to clear a stale npx cache.
+    const cliVersion = (0, version_cli_js_1.resolveCoreVersion)();
+    if (cliVersion !== "unknown") {
+        ui.info(`${binName} v${cliVersion}`);
+    }
     const result = await runInteractiveSetup(binName, harness, args, deps);
     // The Ory Network wizard path bootstraps permissions itself (via the
     // admin-authenticated `ory` CLI). Only fall back to the DCR-token bootstrap
@@ -638,15 +650,20 @@ async function completeFullSetup(binName, harness, ctx) {
  * The tuples reference the permission namespace (default `AgentTools`), which
  * must be defined in the project's permission model or the write fails with
  * `NotFound`. So we inspect the model first (see {@link inspectPermissionModel})
- * and act on what's actually there:
+ * and act on what's actually there. We provision in every case *except* when
+ * the namespace already exists:
  *
+ *   - **Namespace already defined** → grant directly, touch nothing.
  *   - **No model yet** (a freshly created Ory Network project) → offer to
  *     provision a minimal `<namespace>` model (`ory update opl`), then grant.
- *   - **Namespace already defined** → grant directly.
- *   - **Model exists but defines only *other* namespaces** → we can't
- *     auto-provision, because `ory update opl` overwrites the whole OPL and
- *     would clobber the existing model. Print the exact snippet to add and skip
- *     the grant (it would only `NotFound`).
+ *   - **Model exists (OPL source fetchable) but lacks `<namespace>`** → offer
+ *     to *merge* the namespace into the existing OPL and re-upload it, leaving
+ *     the other namespaces untouched, then grant. Ory Network serves the OPL
+ *     source at a `location` URL in the permission config, which makes this
+ *     non-destructive merge possible.
+ *   - **Model provably exists but its source couldn't be read** → we can't
+ *     merge and `ory update opl` overwrites the whole OPL, so we refuse to
+ *     clobber it: print the exact snippet to add and skip the grant.
  *
  * Best-effort throughout: any failure prints a short, actionable note rather
  * than a wall of errors. Observe mode (the install default) keeps tools working
@@ -658,10 +675,36 @@ async function bootstrapPermissionsViaOry(runner, projectId, harness, subject, p
     if (tools.length === 0)
         return;
     // Ensure the namespace the tuples reference exists, or the write NotFounds.
-    const modelState = inspectPermissionModel(runner, projectId, namespace);
-    if (modelState === "empty") {
-        // No model yet — safe to provision a minimal one (prompted).
-        ui.heading(`This project has no permission model, so '${namespace}' isn't defined yet —`);
+    // We only skip provisioning when the namespace is already defined; every
+    // other state provisions. When we can fetch the existing OPL source we merge
+    // our namespace into it (non-destructive); otherwise we create a fresh
+    // minimal model. The one case we refuse is a model that provably exists but
+    // whose source we couldn't read — overwriting it would clobber it.
+    const model = await inspectPermissionModel(runner, projectId, namespace);
+    if (model.kind === "merge") {
+        // A model exists and we have its OPL source — append our namespace without
+        // disturbing the others (prompted).
+        ui.heading(`This project has a permission model, but it doesn't define '${namespace}'.`);
+        ui.hint("It can be added to the existing model without changing the other namespaces.");
+        ui.blank();
+        const answer = await prompt(ui.promptLine(`Add '${namespace}' to this project's permission model now?`, {
+            hint: "[Y/n]",
+        }));
+        if (isNo(answer)) {
+            printPermissionModelHelp(namespace);
+            return;
+        }
+        if (!provisionPermissionModel(runner, projectId, namespace, model.opl)) {
+            ui.warning(`Could not add '${namespace}' to the permission model automatically.`);
+            printPermissionModelHelp(namespace);
+            return;
+        }
+        ui.success(`Added '${namespace}' to the permission model.`);
+    }
+    else if (model.kind === "empty" || model.kind === "unknown") {
+        // No model (or one we couldn't read at all) — provision a minimal one
+        // (prompted). Reading the config failing is treated as "nothing there".
+        ui.heading(`This project has no '${namespace}' permission model yet —`);
         ui.hint("without it, permission checks can't be granted or enforced.");
         ui.blank();
         const answer = await prompt(ui.promptLine(`Create a minimal '${namespace}' permission model on this project now?`, { hint: "[Y/n]" }));
@@ -676,16 +719,15 @@ async function bootstrapPermissionsViaOry(runner, projectId, harness, subject, p
         }
         ui.success(`Created the '${namespace}' permission model.`);
     }
-    else if (modelState === "missing") {
-        // A model exists but defines other namespaces — provisioning would
-        // overwrite it, so guide the user instead of clobbering their model.
-        ui.heading(`This project has a permission model, but it doesn't define '${namespace}'.`);
-        ui.hint("Adding it automatically would overwrite the existing model, so we won't.");
+    else if (model.kind === "blocked") {
+        // A model provably exists but we couldn't fetch its source, so we can't
+        // merge and `ory update opl` would overwrite it. Guide instead of clobber.
+        ui.heading(`This project has a permission model, but it doesn't define '${namespace}'`);
+        ui.hint("and its source couldn't be read, so adding it automatically might overwrite it.");
         printPermissionModelHelp(namespace);
         return;
     }
-    // "present" (namespace already defined) or "unknown" (couldn't read the
-    // model) fall through and attempt the grant best-effort.
+    // "present" (namespace already defined) falls through and grants directly.
     const subjectPatch = "subjectSet" in subject
         ? {
             subject_set: {
@@ -715,26 +757,13 @@ async function bootstrapPermissionsViaOry(runner, projectId, harness, subject, p
     printPermissionModelHelp(namespace);
 }
 /**
- * Inspect the project's permission model to decide how to make `<namespace>`
- * grantable:
- *
- *   - `present` — the namespace is already defined; grant directly.
- *   - `empty`   — the project has no model at all. A freshly created Ory
- *                 Network project reports this as an empty list, a `null`, or
- *                 an absent `namespaces` key — all of which mean "nothing
- *                 defined yet", so provisioning a minimal model is safe.
- *   - `missing` — a model exists and defines *other* namespaces but not this
- *                 one. `ory update opl` overwrites the whole OPL, so we must
- *                 not auto-provision (it would clobber the existing model).
- *   - `unknown` — the config couldn't be read/parsed; make no assumptions and
- *                 attempt the grant best-effort.
- *
- * The earlier version only recognized the exact `namespaces: []` shape as
- * "empty", so a fresh project reporting `null`/absent namespaces (or one that
- * already had unrelated namespaces) silently skipped provisioning and the grant
- * then failed with `NotFound`.
+ * Inspect the project's permission model. Ory Network reports the config in one
+ * of two shapes: `{ namespaces: [] }` (or `null`) for a project with no model,
+ * and `{ namespaces: { location: "https://….txt" } }` for an OPL-configured
+ * one — where the `.txt` is the full OPL *source*. We fetch that source so a
+ * missing namespace can be merged in rather than clobbering the whole model.
  */
-function inspectPermissionModel(runner, projectId, namespace) {
+async function inspectPermissionModel(runner, projectId, namespace) {
     const r = runner.exec([
         "get",
         "permission-config",
@@ -744,47 +773,75 @@ function inspectPermissionModel(runner, projectId, namespace) {
         "json",
     ]);
     if (r.status !== 0)
-        return "unknown";
+        return { kind: "unknown" };
     const cfg = safeJsonParse(r.stdout);
     if (!cfg || typeof cfg !== "object")
-        return "unknown";
+        return { kind: "unknown" };
     const ns = cfg.namespaces;
-    // A fresh project reports no model as null / an absent key / an empty list.
+    // A fresh project reports no model as null / an absent key.
     if (ns == null)
-        return "empty";
-    if (!Array.isArray(ns))
-        return "unknown";
-    if (ns.length === 0)
-        return "empty";
-    const names = ns
-        .map((n) => n && typeof n === "object"
-        ? n.name
-        : undefined)
-        .filter((n) => typeof n === "string");
-    return names.includes(namespace) ? "present" : "missing";
+        return { kind: "empty" };
+    // OPL-configured form: { namespaces: { location: "https://….txt" } }.
+    // The .txt holds the full OPL source, so we can merge into it.
+    if (!Array.isArray(ns) && typeof ns === "object") {
+        const location = ns.location;
+        if (typeof location !== "string" || !location)
+            return { kind: "empty" };
+        const opl = await fetchOplSource(location);
+        // A model exists but its source is unreadable — can't merge, mustn't clobber.
+        if (opl == null)
+            return { kind: "blocked" };
+        return oplDefinesClass(opl, namespace)
+            ? { kind: "present" }
+            : { kind: "merge", opl };
+    }
+    // Inline compiled form: { namespaces: [{ name, id }, …] } (legacy / self-hosted).
+    // We only have names, not source, so a missing namespace can't be merged.
+    if (Array.isArray(ns)) {
+        if (ns.length === 0)
+            return { kind: "empty" };
+        const names = ns
+            .map((n) => n && typeof n === "object"
+            ? n.name
+            : undefined)
+            .filter((n) => typeof n === "string");
+        return names.includes(namespace) ? { kind: "present" } : { kind: "blocked" };
+    }
+    return { kind: "unknown" };
+}
+/** Fetch the OPL source served at a permission-config `location` URL. */
+async function fetchOplSource(url) {
+    try {
+        const res = await fetch(url);
+        if (!res.ok)
+            return null;
+        return await res.text();
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether an OPL source defines `class <name>`. */
+function oplDefinesClass(opl, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`\\bclass\\s+${escaped}\\b`).test(opl);
 }
 /**
- * Provision a minimal permission model that defines `<namespace>` with a
- * `use` relation, via `ory update opl`. The namespace becomes an OPL class, so
- * it must be a valid identifier; if not, we bail (caller guides instead).
- * Writes the OPL to a temp file because `ory update opl` reads `--file` only
- * (no stdin). Returns true on success.
+ * Provision a permission model that defines `<namespace>` with a `use`
+ * relation, via `ory update opl`. The namespace becomes an OPL class, so it
+ * must be a valid identifier; if not, we bail (caller guides instead).
+ *
+ * When `existingOpl` is given, the namespace is appended to that source
+ * (preserving the model's other namespaces); otherwise a fresh minimal model
+ * is generated. Writes the OPL to a temp file because `ory update opl` reads
+ * `--file` only (no stdin). Returns true on success.
  */
-function provisionPermissionModel(runner, projectId, namespace) {
+function provisionPermissionModel(runner, projectId, namespace, existingOpl) {
     if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(namespace))
         return false;
-    const opl = [
-        'import { Namespace } from "@ory/permission-namespace-types"',
-        "",
-        "class User implements Namespace {}",
-        "",
-        `class ${namespace} implements Namespace {`,
-        "  related: {",
-        "    use: User[]",
-        "  }",
-        "}",
-        "",
-    ].join("\n");
+    const opl = existingOpl !== undefined
+        ? mergeNamespaceIntoOpl(existingOpl, namespace)
+        : freshOpl(namespace);
     let dir;
     try {
         dir = fs.mkdtempSync(path.join(os.tmpdir(), "ory-opl-"));
@@ -820,6 +877,39 @@ function provisionPermissionModel(runner, projectId, namespace) {
         }
     }
 }
+/** A minimal standalone OPL defining `User` and `<namespace>` with `use`. */
+function freshOpl(namespace) {
+    return [
+        'import { Namespace } from "@ory/permission-namespace-types"',
+        "",
+        "class User implements Namespace {}",
+        "",
+        `class ${namespace} implements Namespace {`,
+        "  related: {",
+        "    use: User[]",
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * Append a `<namespace>` class (with a `use: User[]` relation) to an existing
+ * OPL source, leaving every other namespace untouched. Adds a `User` class too
+ * when the source doesn't already define one, since `use` is typed `User[]`.
+ */
+function mergeNamespaceIntoOpl(existingOpl, namespace) {
+    let opl = existingOpl.replace(/\s*$/, "\n");
+    if (!oplDefinesClass(opl, "User")) {
+        opl += "\nclass User implements Namespace {}\n";
+    }
+    opl +=
+        `\nclass ${namespace} implements Namespace {\n` +
+            "  related: {\n" +
+            "    use: User[]\n" +
+            "  }\n" +
+            "}\n";
+    return opl;
+}
 function printPermissionModelHelp(namespace) {
     // When the namespace is a valid OPL class name, show the exact snippet to
     // paste into the model — that's the concrete "how" behind "define it". The

package/dist/version-cli.d.ts

@@ -26,6 +26,13 @@ export interface BuildInfo {
  * `unknown`.
  */
 export declare function resolveBuildInfo(): BuildInfo;
+/**
+ * Resolve the `@ory/argus` core version from this module's own package.json.
+ * Exported so the install flow can surface the running CLI version — every
+ * `@ory/*` package releases in lockstep, so the core version is the release
+ * version of whatever plugin CLI is executing.
+ */
+export declare function resolveCoreVersion(): string;
 export interface VersionInfo {
     plugin: {
         name: string;

package/dist/version-cli.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveBuildInfo = resolveBuildInfo;
+exports.resolveCoreVersion = resolveCoreVersion;
 exports.collectVersionInfo = collectVersionInfo;
 exports.runVersionCommand = runVersionCommand;
 /**
@@ -158,7 +159,12 @@ function readPackageMeta(packageRoot) {
         return { name: "unknown", version: "0.0.0" };
     }
 }
-/** Resolve the `@ory/argus` core version from this module's own package.json. */
+/**
+ * Resolve the `@ory/argus` core version from this module's own package.json.
+ * Exported so the install flow can surface the running CLI version — every
+ * `@ory/*` package releases in lockstep, so the core version is the release
+ * version of whatever plugin CLI is executing.
+ */
 function resolveCoreVersion() {
     let dir = __dirname;
     for (let i = 0; i < 5; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",