@ory/argus 0.11.1 → 0.12.0

package/dist/config.d.ts

@@ -73,7 +73,21 @@ export interface OryAgentCredentialsBlock {
  */
 export type PermissionMode = "observe" | "enforce";
 export interface OryPluginConfig {
+    /**
+     * Ory project API URL — the SDK base path all API calls target. The Ory
+     * Console "Get Started" panel calls this `ORY_SDK_URL`; the env var of that
+     * name is accepted as an alias for `ORY_PROJECT_URL` (see {@link resolveConfig}).
+     */
     projectUrl?: string;
+    /**
+     * Ory project UUID — the other half of the Console "Get Started" pair
+     * (`ORY_PROJECT_ID`). Persisted by the interactive installer because the
+     * admin `ory` CLI operations key off it (`--project <id>`). It is an
+     * identifier for admin APIs, **not** an SDK URL source: the SDK base URL is
+     * always the slug-based {@link projectUrl}, and a project id (a UUID) must
+     * never be substituted for a slug when building it.
+     */
+    projectId?: string;
     apiKey?: string;
     /**
      * Public OAuth2 client id used by the user PKCE browser flow when
@@ -93,6 +107,23 @@ export interface OryPluginConfig {
      * tuple set is correct. See {@link PermissionMode}.
      */
     permissionMode?: PermissionMode;
+    /**
+     * Whether the interactive user PKCE login runs at session start. When
+     * true, every session runs `ensureUserAuthenticated`; when unset the
+     * flow is a no-op. Set via `configure --user-login` / `--no-user-login`.
+     * The `ORY_USER_LOGIN` env var overrides this when set. Requires an
+     * OAuth2 client id ({@link oauth2ClientId}) to actually complete a login.
+     */
+    userLogin?: boolean;
+    /**
+     * Permission-check subject namespace for the human user. When set, the
+     * user is addressed as a SubjectSet `<namespace>:<subject>` in permission
+     * checks instead of a direct SubjectID — this must match how the tuples
+     * were written in Keto. The local stack seeds tuples as `User:<id>`, so the
+     * local-stack install path persists `"User"` here to make enforce mode work
+     * out of the box. The `ORY_USER_SUBJECT_NAMESPACE` env var overrides this.
+     */
+    userSubjectNamespace?: string;
     /** Credentials for the human user (interactive PKCE login). */
     user?: OryUserCredentials;
     /** Credentials for the AI agent process (machine identity). */
@@ -128,6 +159,14 @@ export declare function getConfigPath(): string;
  * does not exist or is invalid.
  */
 export declare function loadConfig(): OryPluginConfig;
+/**
+ * Read `ORY_USER_LOGIN` from the environment. Returns `true`/`false` when
+ * the var is set (any recognized truthy value enables it; anything else
+ * disables it), or `undefined` when the var is absent/empty so callers
+ * fall back to the config file. Centralized here so the user gate, status
+ * CLI, and configure command resolve it identically.
+ */
+export declare function parseUserLoginEnv(): boolean | undefined;
 /**
  * Save config to the config file. Merges with existing values — only
  * provided fields are overwritten. Concurrent processes serialize via a
@@ -147,18 +186,40 @@ export declare function saveConfig(update: Partial<{
  * atomic via write-temp + rename.
  */
 export declare function mutateConfig(mutator: (current: OryPluginConfig) => OryPluginConfig): void;
+/**
+ * True when `value` looks like an Ory project **id** (a UUID) rather than a
+ * project **slug**. Project slugs are human-readable tokens (e.g.
+ * `nervous-galileo-1a2b3c`) and are never UUIDs, so this cleanly distinguishes
+ * the two. Used to guard the SDK-URL derivation: the URL subdomain must be the
+ * slug — a project id must never be substituted for it (see
+ * {@link projectUrlFromSlug}). The id addresses project-scoped **admin** APIs
+ * (the `ory` CLI's `--project` flag), which is a different concern from the SDK
+ * base URL.
+ */
+export declare function looksLikeProjectId(value: string): boolean;
 /**
  * Resolve config by checking environment variables first, then the config file.
  * Returns the merged result with the source of each value.
+ *
+ * `projectUrl` accepts `ORY_SDK_URL` as an alias for `ORY_PROJECT_URL` (the two
+ * names the Console "Get Started" uses). The SDK URL is **always** slug-based;
+ * `projectId` (`ORY_PROJECT_ID`) is a distinct identifier for admin APIs and is
+ * never turned into an SDK URL — a project id is not a slug.
  */
 export declare function resolveConfig(): {
     projectUrl?: string;
+    projectId?: string;
     apiKey?: string;
     oauth2ClientId?: string;
     auditOnly: boolean;
     permissionMode: PermissionMode;
     permissionModeSource: "env" | "config" | "default";
+    userLogin: boolean;
+    userLoginSource: "env" | "config" | "default";
+    userSubjectNamespace?: string;
+    userSubjectNamespaceSource: "env" | "config" | "none";
     projectUrlSource: "env" | "config" | "none";
+    projectIdSource: "env" | "config" | "none";
     apiKeySource: "env" | "config" | "none";
     oauth2ClientIdSource: "env" | "config" | "none";
 };

package/dist/config.js

@@ -37,13 +37,16 @@ exports.getDataDir = getDataDir;
 exports.getHarnessDataDir = getHarnessDataDir;
 exports.getConfigPath = getConfigPath;
 exports.loadConfig = loadConfig;
+exports.parseUserLoginEnv = parseUserLoginEnv;
 exports.saveConfig = saveConfig;
 exports.mutateConfig = mutateConfig;
+exports.looksLikeProjectId = looksLikeProjectId;
 exports.resolveConfig = resolveConfig;
 exports.configPromptMessage = configPromptMessage;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const cli_invocation_js_1 = require("./cli-invocation.js");
 /**
  * Single OS-agnostic data directory for *all* Ory agent plugin state:
  * the shared config file, persisted DCR credentials, and any harness
@@ -114,10 +117,17 @@ function loadConfig() {
         const parsed = JSON.parse(raw);
         return {
             projectUrl: typeof parsed.projectUrl === "string" ? parsed.projectUrl : undefined,
+            projectId: typeof parsed.projectId === "string" && parsed.projectId.trim()
+                ? parsed.projectId.trim()
+                : undefined,
             apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : undefined,
             oauth2ClientId: typeof parsed.oauth2ClientId === "string" ? parsed.oauth2ClientId : undefined,
             auditOnly: parsed.auditOnly === true ? true : undefined,
             permissionMode: parsePermissionMode(parsed.permissionMode),
+            userLogin: typeof parsed.userLogin === "boolean" ? parsed.userLogin : undefined,
+            userSubjectNamespace: typeof parsed.userSubjectNamespace === "string" && parsed.userSubjectNamespace.trim()
+                ? parsed.userSubjectNamespace.trim()
+                : undefined,
             user: parseUserCredentials(parsed),
             agent: parseAgentCredentials(parsed),
         };
@@ -129,6 +139,21 @@ function loadConfig() {
 function parsePermissionMode(value) {
     return value === "observe" || value === "enforce" ? value : undefined;
 }
+/** Env values that turn the interactive user login on. */
+const USER_LOGIN_ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+/**
+ * Read `ORY_USER_LOGIN` from the environment. Returns `true`/`false` when
+ * the var is set (any recognized truthy value enables it; anything else
+ * disables it), or `undefined` when the var is absent/empty so callers
+ * fall back to the config file. Centralized here so the user gate, status
+ * CLI, and configure command resolve it identically.
+ */
+function parseUserLoginEnv() {
+    const raw = process.env.ORY_USER_LOGIN;
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    return USER_LOGIN_ENABLED_VALUES.has(raw.trim().toLowerCase());
+}
 function parseAgentCredentials(parsed) {
     const raw = parsed.agent;
     if (!raw || typeof raw !== "object")
@@ -350,33 +375,84 @@ function writeConfigAtomic(config) {
     fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
     fs.renameSync(tmp, target);
 }
+/** Matches an Ory project UUID (the value `ORY_PROJECT_ID` carries). */
+const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * True when `value` looks like an Ory project **id** (a UUID) rather than a
+ * project **slug**. Project slugs are human-readable tokens (e.g.
+ * `nervous-galileo-1a2b3c`) and are never UUIDs, so this cleanly distinguishes
+ * the two. Used to guard the SDK-URL derivation: the URL subdomain must be the
+ * slug — a project id must never be substituted for it (see
+ * {@link projectUrlFromSlug}). The id addresses project-scoped **admin** APIs
+ * (the `ory` CLI's `--project` flag), which is a different concern from the SDK
+ * base URL.
+ */
+function looksLikeProjectId(value) {
+    return PROJECT_ID_RE.test(value.trim());
+}
 /**
  * Resolve config by checking environment variables first, then the config file.
  * Returns the merged result with the source of each value.
+ *
+ * `projectUrl` accepts `ORY_SDK_URL` as an alias for `ORY_PROJECT_URL` (the two
+ * names the Console "Get Started" uses). The SDK URL is **always** slug-based;
+ * `projectId` (`ORY_PROJECT_ID`) is a distinct identifier for admin APIs and is
+ * never turned into an SDK URL — a project id is not a slug.
  */
 function resolveConfig() {
     const file = loadConfig();
-    const envProjectUrl = process.env.ORY_PROJECT_URL;
+    // ORY_PROJECT_URL is the documented name; ORY_SDK_URL is the name the Ory
+    // Console "Get Started" panel and the Ory SDKs use — accepted as an alias.
+    const envProjectUrl = process.env.ORY_PROJECT_URL?.trim() || process.env.ORY_SDK_URL?.trim() || undefined;
+    const envProjectId = process.env.ORY_PROJECT_ID?.trim() || undefined;
     // ORY_AGENT_API_KEY is the documented name; ORY_API_KEY is the deprecated
     // alias kept for back-compat (agent-auth emits a warning when only the
     // legacy form is set).
     const envApiKey = process.env.ORY_AGENT_API_KEY ?? process.env.ORY_API_KEY;
     const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
     const envMode = parsePermissionMode(process.env.ORY_PERMISSION_MODE);
+    const envUserLogin = parseUserLoginEnv();
+    const envUserSubjectNamespace = process.env.ORY_USER_SUBJECT_NAMESPACE?.trim() || undefined;
     const permissionMode = envMode ?? file.permissionMode ?? "observe";
     const permissionModeSource = envMode
         ? "env"
         : file.permissionMode
             ? "config"
             : "default";
+    const userLogin = envUserLogin ?? file.userLogin ?? false;
+    const userLoginSource = envUserLogin !== undefined
+        ? "env"
+        : file.userLogin !== undefined
+            ? "config"
+            : "default";
+    const projectId = envProjectId ?? file.projectId;
+    // The SDK URL is only ever an explicit, slug-based URL (from ORY_PROJECT_URL,
+    // ORY_SDK_URL, or the config file). The project id is NOT a URL source — it
+    // addresses admin APIs, and its value is a UUID, not a slug.
+    const projectUrl = envProjectUrl ?? file.projectUrl;
+    const projectUrlSource = envProjectUrl
+        ? "env"
+        : file.projectUrl
+            ? "config"
+            : "none";
     return {
-        projectUrl: envProjectUrl ?? file.projectUrl,
+        projectUrl,
+        projectId,
         apiKey: envApiKey ?? file.apiKey,
         oauth2ClientId: envClientId ?? file.oauth2ClientId,
         auditOnly: file.auditOnly === true,
         permissionMode,
         permissionModeSource,
-        projectUrlSource: envProjectUrl ? "env" : file.projectUrl ? "config" : "none",
+        userLogin,
+        userLoginSource,
+        userSubjectNamespace: envUserSubjectNamespace ?? file.userSubjectNamespace,
+        userSubjectNamespaceSource: envUserSubjectNamespace
+            ? "env"
+            : file.userSubjectNamespace
+                ? "config"
+                : "none",
+        projectUrlSource,
+        projectIdSource: envProjectId ? "env" : file.projectId ? "config" : "none",
         apiKeySource: envApiKey ? "env" : file.apiKey ? "config" : "none",
         oauth2ClientIdSource: envClientId ? "env" : file.oauth2ClientId ? "config" : "none",
     };
@@ -388,10 +464,10 @@ function configPromptMessage(binName) {
     return ("The Ory agent plugin is installed but not yet configured.\n" +
         "\n" +
         "  Option 1 — Connect to Ory (enables authentication and permission checks):\n" +
-        `    npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]\n` +
+        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]\n` +
         "\n" +
         "  Option 2 — Continue without authentication (audit logging only):\n" +
-        `    npx ${binName} configure --audit-only\n` +
+        `    ${(0, cli_invocation_js_1.oryNpx)(binName)} configure --audit-only\n` +
         "\n" +
         `Configuration is saved to ${configFile()} and shared across all agent plugins.`);
 }

package/dist/dev.d.ts

@@ -40,6 +40,14 @@ export interface DevLauncherConfig {
     install(ctx: InstallContext): void;
     /** Extra tip lines to print before launch */
     extraTips?: string[];
+    /**
+     * Base args always passed to the harness binary at launch, prepended to any
+     * args forwarded from the dev-launcher CLI. Use for dev-only flags a plugin
+     * needs to exercise its hooks — e.g. Codex requires
+     * `--dangerously-bypass-hook-trust` so freshly installed (untrusted) plugin
+     * hooks run without the interactive trust prompt.
+     */
+    launchArgs?: string[];
 }
 /**
  * Parse the dev-launcher CLI args, splitting out launcher-only flags from the

package/dist/dev.js

@@ -259,6 +259,16 @@ async function runDevLauncher(config) {
     if ((0, auth_store_js_1.clearPkceFlightLock)()) {
         console.log("[ory-dev] Cleared stale PKCE flight lock from a previous run.");
     }
+    // Local dev demonstrates the full interactive PKCE browser login on every
+    // launch. `buildLocalOryEnv` already clears env-supplied tokens, but a
+    // still-valid *persisted* token from a prior run would short-circuit
+    // `ensureUserAuthenticated` (mode "ok", "Re-using persisted access token")
+    // so no browser prompt appears. Drop persisted user tokens too, so each
+    // local launch reliably fires the login. Runs only in local-Ory mode — when
+    // pointed at a real project (`ORY_DEV_LOCAL=0`), persisted tokens are kept.
+    if (localEnabled) {
+        (0, auth_store_js_1.clearTokens)();
+    }
     assertNpmAvailable();
     console.log(`[ory-dev] Ensuring local npm registry is running...`);
     await (0, manager_js_1.ensureRegistryRunning)();
@@ -325,7 +335,8 @@ async function runDevLauncher(config) {
             ? buildOtelEnv(otelEndpoint, config.harnessName)
             : {}),
     };
-    const result = (0, node_child_process_1.spawnSync)(config.command, forwardedArgs, {
+    const launchArgs = [...(config.launchArgs ?? []), ...forwardedArgs];
+    const result = (0, node_child_process_1.spawnSync)(config.command, launchArgs, {
         cwd: sandbox,
         stdio: "inherit",
         env,

package/dist/index.d.ts

@@ -5,12 +5,15 @@ export { loadConfig, saveConfig, resolveConfig, mutateConfig, getConfigPath, get
 export { pkceLogin, refreshAccessToken, detectHeadless, generateCodeVerifier, sha256Base64Url, buildAuthorizeUrl, LOOPBACK_PORTS, DEFAULT_LOGIN_TIMEOUT_MS, type PkceLoginOptions, type PkceLoginOutcome, type PkceDeclineReason, } from "./auth.js";
 export { loadTokens, saveTokens, clearTokens, isExpired, refreshAndSave, tryAcquirePkceFlightLock, clearPkceFlightLock, waitForPeerTokens, waitForPeerTokensSync, TOKEN_EXPIRY_SKEW_SEC, type PkceFlightLock, } from "./auth-store.js";
 export { ensureUserAuthenticated, ensureAuthenticated, type UserLoginDecision, type UserLoginMode, type UserLoginOptions, } from "./user-login.js";
-export { resolveAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, saveAgentDynamicCredentials, clearAgentDynamicCredentials, loadSubAgentDynamicCredentials, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, AGENT_TOKEN_EXPIRY_SKEW_SEC, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.js";
+export { resolveAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, fetchClientCredentialsToken, registerAgentClient, loadAgentDynamicCredentials, saveAgentDynamicCredentials, clearAgentDynamicCredentials, loadSubAgentDynamicCredentials, saveSubAgentDynamicCredentials, clearSubAgentDynamicCredentials, revokeAgentDynamicClient, AGENT_TOKEN_EXPIRY_SKEW_SEC, type AgentCredentials, type AgentCredentialKind, type ResolveAgentCredentialsOptions, type EnsureAgentIdentityOptions, type RegisterAgentClientArgs, type RevokeAgentClientResult, type SubAgentIdentity, type EnsureSubAgentIdentityOptions, } from "./agent-auth.js";
+export { clearCredentialsForUninstall, type ClearCredentialsOptions, type ClearCredentialsResult, } from "./uninstall.js";
 export { type SessionInfo, type OAuth2TokenInfo, type PermissionCheck, type PermissionResult, type BatchPermissionResult, type OryError, type OryErrorCode, } from "./types.js";
 export { runConfigureCommand, runAgentCommand, printOryConfig, printEnvironment, printLogTail, printEnvHelp, printTraceTail, runWatchCommand, isTtyAvailable, promptOnTty, promptForProjectUrl, interactiveConfigPrompt, } from "./cli.js";
+export { oryNpx } from "./cli-invocation.js";
 export { runPermissionsCommand, isUserIdentityCached, maybeAutoBootstrap, printPermissionsOnboardingHelp, } from "./permissions-cli.js";
+export { runInteractiveSetup, runPostInstall, projectUrlFromSlug, LOOPBACK_REDIRECT_URIS, type OryCliRunner, type OryExecResult, type InteractiveSetupDeps, type InteractiveSetupOutcome, type InteractiveSetupResult, } from "./interactive-setup.js";
 export { runStatusCommand, printUserIdentitySection, printAgentIdentitySection, printPermissionsSection, type StatusCommandOptions, } from "./status-cli.js";
-export { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, resolveHookCommand, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, resolveMcpServerCommand, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
+export { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, resolveHookCommand, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, nextStepsSink, beginDeferNextSteps, emitDeferredNextSteps, resolveMcpServerCommand, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
 export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./dev.js";
 export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";
 export { runLocalCommand, ensureDevJaeger, stopDevJaeger, DEV_JAEGER_CONTAINER, type EnsureDevJaegerResult, type StopDevJaegerResult, } from "./local/index.js";

package/dist/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printOryConfig = exports.runAgentCommand = exports.runConfigureCommand = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.clearSubAgentDynamicCredentials = exports.saveSubAgentDynamicCredentials = exports.loadSubAgentDynamicCredentials = exports.clearAgentDynamicCredentials = exports.saveAgentDynamicCredentials = exports.loadAgentDynamicCredentials = exports.registerAgentClient = exports.fetchClientCredentialsToken = exports.ensureSubAgentIdentity = exports.ensureAgentIdentity = exports.resolveAgentCredentials = exports.ensureAuthenticated = exports.ensureUserAuthenticated = exports.TOKEN_EXPIRY_SKEW_SEC = exports.waitForPeerTokensSync = exports.waitForPeerTokens = exports.clearPkceFlightLock = exports.tryAcquirePkceFlightLock = exports.refreshAndSave = exports.isExpired = exports.clearTokens = exports.saveTokens = exports.loadTokens = exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = exports.buildAuthorizeUrl = exports.sha256Base64Url = exports.generateCodeVerifier = exports.detectHeadless = exports.refreshAccessToken = exports.pkceLogin = exports.getHarnessDataDir = exports.getDataDir = exports.getConfigPath = exports.mutateConfig = exports.resolveConfig = exports.saveConfig = exports.loadConfig = exports.watchTraceFile = exports.formatSpan = exports.deriveTraceId = exports.ActiveSpan = exports.Tracer = exports.redactLogData = exports.DebugLogger = exports.OryAgentClient = void 0;
-exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = void 0;
-exports.wrapTool = exports.registerSubagent = exports.complete = exports.gate = exports.sessionStart = exports.resolveNamespace = exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.runWithUserSubject = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.TOOL_EXECUTION_PHASES = exports.USER_FACING_PHASES = exports.HARNESS_LIFECYCLE_MAP = exports.isToolExecutionPhase = exports.isUserFacingPhase = exports.classifyLifecycle = exports.isInteractiveTool = exports.getInteractiveToolCatalog = exports.INTERACTIVE_TOOL_CATALOG = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.gateToolCall = exports.applyPermissionMode = exports.checkAndDecide = exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = void 0;
+exports.runConfigureCommand = exports.clearCredentialsForUninstall = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.revokeAgentDynamicClient = exports.clearSubAgentDynamicCredentials = exports.saveSubAgentDynamicCredentials = exports.loadSubAgentDynamicCredentials = exports.clearAgentDynamicCredentials = exports.saveAgentDynamicCredentials = exports.loadAgentDynamicCredentials = exports.registerAgentClient = exports.fetchClientCredentialsToken = exports.ensureSubAgentIdentity = exports.ensureAgentIdentity = exports.resolveAgentCredentials = exports.ensureAuthenticated = exports.ensureUserAuthenticated = exports.TOKEN_EXPIRY_SKEW_SEC = exports.waitForPeerTokensSync = exports.waitForPeerTokens = exports.clearPkceFlightLock = exports.tryAcquirePkceFlightLock = exports.refreshAndSave = exports.isExpired = exports.clearTokens = exports.saveTokens = exports.loadTokens = exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = exports.buildAuthorizeUrl = exports.sha256Base64Url = exports.generateCodeVerifier = exports.detectHeadless = exports.refreshAccessToken = exports.pkceLogin = exports.getHarnessDataDir = exports.getDataDir = exports.getConfigPath = exports.mutateConfig = exports.resolveConfig = exports.saveConfig = exports.loadConfig = exports.watchTraceFile = exports.formatSpan = exports.deriveTraceId = exports.ActiveSpan = exports.Tracer = exports.redactLogData = exports.DebugLogger = exports.OryAgentClient = void 0;
+exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.emitDeferredNextSteps = exports.beginDeferNextSteps = exports.nextStepsSink = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.LOOPBACK_REDIRECT_URIS = exports.projectUrlFromSlug = exports.runPostInstall = exports.runInteractiveSetup = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.oryNpx = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = exports.printOryConfig = exports.runAgentCommand = void 0;
+exports.sessionStart = exports.resolveNamespace = exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.runWithUserSubject = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.TOOL_EXECUTION_PHASES = exports.USER_FACING_PHASES = exports.HARNESS_LIFECYCLE_MAP = exports.isToolExecutionPhase = exports.isUserFacingPhase = exports.classifyLifecycle = exports.isInteractiveTool = exports.getInteractiveToolCatalog = exports.INTERACTIVE_TOOL_CATALOG = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.gateToolCall = exports.applyPermissionMode = exports.checkAndDecide = exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = void 0;
+exports.wrapTool = exports.registerSubagent = exports.complete = exports.gate = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return client_js_1.OryAgentClient; } });
 var logger_js_1 = require("./logger.js");
@@ -57,7 +58,10 @@ Object.defineProperty(exports, "clearAgentDynamicCredentials", { enumerable: tru
 Object.defineProperty(exports, "loadSubAgentDynamicCredentials", { enumerable: true, get: function () { return agent_auth_js_1.loadSubAgentDynamicCredentials; } });
 Object.defineProperty(exports, "saveSubAgentDynamicCredentials", { enumerable: true, get: function () { return agent_auth_js_1.saveSubAgentDynamicCredentials; } });
 Object.defineProperty(exports, "clearSubAgentDynamicCredentials", { enumerable: true, get: function () { return agent_auth_js_1.clearSubAgentDynamicCredentials; } });
+Object.defineProperty(exports, "revokeAgentDynamicClient", { enumerable: true, get: function () { return agent_auth_js_1.revokeAgentDynamicClient; } });
 Object.defineProperty(exports, "AGENT_TOKEN_EXPIRY_SKEW_SEC", { enumerable: true, get: function () { return agent_auth_js_1.AGENT_TOKEN_EXPIRY_SKEW_SEC; } });
+var uninstall_js_1 = require("./uninstall.js");
+Object.defineProperty(exports, "clearCredentialsForUninstall", { enumerable: true, get: function () { return uninstall_js_1.clearCredentialsForUninstall; } });
 var cli_js_1 = require("./cli.js");
 Object.defineProperty(exports, "runConfigureCommand", { enumerable: true, get: function () { return cli_js_1.runConfigureCommand; } });
 Object.defineProperty(exports, "runAgentCommand", { enumerable: true, get: function () { return cli_js_1.runAgentCommand; } });
@@ -71,11 +75,18 @@ Object.defineProperty(exports, "isTtyAvailable", { enumerable: true, get: functi
 Object.defineProperty(exports, "promptOnTty", { enumerable: true, get: function () { return cli_js_1.promptOnTty; } });
 Object.defineProperty(exports, "promptForProjectUrl", { enumerable: true, get: function () { return cli_js_1.promptForProjectUrl; } });
 Object.defineProperty(exports, "interactiveConfigPrompt", { enumerable: true, get: function () { return cli_js_1.interactiveConfigPrompt; } });
+var cli_invocation_js_1 = require("./cli-invocation.js");
+Object.defineProperty(exports, "oryNpx", { enumerable: true, get: function () { return cli_invocation_js_1.oryNpx; } });
 var permissions_cli_js_1 = require("./permissions-cli.js");
 Object.defineProperty(exports, "runPermissionsCommand", { enumerable: true, get: function () { return permissions_cli_js_1.runPermissionsCommand; } });
 Object.defineProperty(exports, "isUserIdentityCached", { enumerable: true, get: function () { return permissions_cli_js_1.isUserIdentityCached; } });
 Object.defineProperty(exports, "maybeAutoBootstrap", { enumerable: true, get: function () { return permissions_cli_js_1.maybeAutoBootstrap; } });
 Object.defineProperty(exports, "printPermissionsOnboardingHelp", { enumerable: true, get: function () { return permissions_cli_js_1.printPermissionsOnboardingHelp; } });
+var interactive_setup_js_1 = require("./interactive-setup.js");
+Object.defineProperty(exports, "runInteractiveSetup", { enumerable: true, get: function () { return interactive_setup_js_1.runInteractiveSetup; } });
+Object.defineProperty(exports, "runPostInstall", { enumerable: true, get: function () { return interactive_setup_js_1.runPostInstall; } });
+Object.defineProperty(exports, "projectUrlFromSlug", { enumerable: true, get: function () { return interactive_setup_js_1.projectUrlFromSlug; } });
+Object.defineProperty(exports, "LOOPBACK_REDIRECT_URIS", { enumerable: true, get: function () { return interactive_setup_js_1.LOOPBACK_REDIRECT_URIS; } });
 var status_cli_js_1 = require("./status-cli.js");
 Object.defineProperty(exports, "runStatusCommand", { enumerable: true, get: function () { return status_cli_js_1.runStatusCommand; } });
 Object.defineProperty(exports, "printUserIdentitySection", { enumerable: true, get: function () { return status_cli_js_1.printUserIdentitySection; } });
@@ -95,6 +106,9 @@ Object.defineProperty(exports, "mergeFlatHooks", { enumerable: true, get: functi
 Object.defineProperty(exports, "removeFlatHooks", { enumerable: true, get: function () { return setup_js_1.removeFlatHooks; } });
 Object.defineProperty(exports, "printSetupHelp", { enumerable: true, get: function () { return setup_js_1.printSetupHelp; } });
 Object.defineProperty(exports, "printNextSteps", { enumerable: true, get: function () { return setup_js_1.printNextSteps; } });
+Object.defineProperty(exports, "nextStepsSink", { enumerable: true, get: function () { return setup_js_1.nextStepsSink; } });
+Object.defineProperty(exports, "beginDeferNextSteps", { enumerable: true, get: function () { return setup_js_1.beginDeferNextSteps; } });
+Object.defineProperty(exports, "emitDeferredNextSteps", { enumerable: true, get: function () { return setup_js_1.emitDeferredNextSteps; } });
 Object.defineProperty(exports, "resolveMcpServerCommand", { enumerable: true, get: function () { return setup_js_1.resolveMcpServerCommand; } });
 Object.defineProperty(exports, "mcpServerEntry", { enumerable: true, get: function () { return setup_js_1.mcpServerEntry; } });
 Object.defineProperty(exports, "mergeMcpServer", { enumerable: true, get: function () { return setup_js_1.mergeMcpServer; } });

package/dist/interactive-setup.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Interactive install wizard. Runs after a harness plugin has been
+ * registered, stepping the user through connecting the plugin to Ory:
+ *
+ *   1. Choose a connection: **Ory Network** (browser login / account
+ *      creation) or **local / audit-only** (no project, audit logging only).
+ *   2. Ory Network branch: shell out to the official `ory` CLI to log in,
+ *      pick a workspace, pick a project (→ `projectUrl`), and create the
+ *      public OAuth2 client the PKCE user login needs (→ `oauth2ClientId`).
+ *   3. Persist the resolved values to the shared config file and enable the
+ *      interactive user login.
+ *   4. Best-effort "full setup": run the PKCE user login now (we hold the
+ *      project URL + client id), resolve the agent DCR identity, and let the
+ *      caller bootstrap permissions from the freshly-cached user identity.
+ *
+ * The whole wizard is **fail-open and skippable**: on a missing TTY, a
+ * `--no-configure` flag, an already-configured plugin (without
+ * `--reconfigure`), a missing `ory` CLI, or any `ory` failure it prints the
+ * manual `configure` instructions and returns without throwing. Install must
+ * never crash because setup was declined or the network was unreachable.
+ *
+ * The Ory Network integration deliberately reuses the official `ory` CLI
+ * rather than re-implementing the Console API: the CLI already owns Network
+ * browser login + account creation, workspace/project listing, and OAuth2
+ * client creation, and the client it creates is exactly the one the plugin
+ * READMEs document for manual setup.
+ */
+import { OryAgentClient } from "./client.js";
+import { ensureUserAuthenticated } from "./user-login.js";
+import { ensureAgentIdentity } from "./agent-auth.js";
+import { ensureLocalOryStack, seedLocalEnvironment } from "./local/index.js";
+/** Loopback redirect URIs the PKCE user login expects on the OAuth2 client. */
+export declare const LOOPBACK_REDIRECT_URIS: readonly string[];
+/** Result of running a captured `ory` command. */
+export interface OryExecResult {
+    /** Exit code; `null` when the process could not be spawned (CLI missing). */
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Thin, injectable wrapper around the `ory` binary. Tests stub this to drive
+ * the wizard without a real CLI; the default implementation shells out.
+ */
+export interface OryCliRunner {
+    /** Run `ory <args>` capturing stdout/stderr. `opts.input` is written to
+     *  the child's stdin (used to feed JSON to `ory create relationships -f -`). */
+    exec(args: string[], opts?: {
+        input?: string;
+    }): OryExecResult;
+    /** Run `ory <args>` inheriting the terminal (for the browser login). */
+    execInteractive(args: string[]): number;
+}
+/**
+ * Build a runner bound to a specific `ory` binary (a bare command resolved on
+ * `PATH`, or an absolute path to a plugin-installed binary). {@link defaultRunner}
+ * uses the bare `"ory"`; {@link installOryCli} returns one bound to the binary
+ * it just installed.
+ */
+export declare function createOryRunner(oryBin: string): OryCliRunner;
+/**
+ * npm spec for the Ory CLI installed on demand when the `ory` binary isn't on
+ * `PATH`. `@ory/cli` ships the platform `ory` binary and exposes it as its
+ * `bin`, so an isolated `npm install` gives us a working CLI without touching
+ * the user's global environment. Pinned to a major to stay reproducible while
+ * still picking up patch/minor fixes.
+ */
+export declare const ORY_CLI_NPM_SPEC = "@ory/cli@^1";
+export interface InteractiveSetupDeps {
+    runner?: OryCliRunner;
+    isTtyAvailableFn?: () => boolean;
+    promptFn?: (prompt: string) => Promise<string | null>;
+    clientFactory?: (harness: string) => OryAgentClient;
+    userLoginFn?: typeof ensureUserAuthenticated;
+    agentGateFn?: typeof ensureAgentIdentity;
+    /** Injectable local-stack bring-up (defaults to {@link ensureLocalOryStack}). */
+    localStackFn?: typeof ensureLocalOryStack;
+    /** Injectable local-stack seeder (defaults to {@link seedLocalEnvironment}). */
+    seedFn?: typeof seedLocalEnvironment;
+    /**
+     * Injectable Ory-CLI installer used when the `ory` binary isn't on `PATH`.
+     * Returns a runner bound to the installed binary, or null if the install
+     * failed. Defaults to a real `npm install` of {@link ORY_CLI_NPM_SPEC}.
+     */
+    installOryCliFn?: () => Promise<OryCliRunner | null>;
+}
+export type InteractiveSetupOutcome = "skipped_flag" | "skipped_no_tty" | "skipped_configured" | "audit_only" | "local_configured" | "network_configured" | "network_fallback";
+export interface InteractiveSetupResult {
+    outcome: InteractiveSetupOutcome;
+    projectUrl?: string;
+    oauth2ClientId?: string;
+    /** Whether a user identity was authenticated during the wizard. */
+    userAuthenticated?: boolean;
+    /**
+     * When true, the caller should NOT run the DCR-token-based
+     * {@link maybeAutoBootstrap}. The wizard bootstraps permissions itself via
+     * the admin-authenticated `ory` CLI on the Ory Network path — the runtime
+     * agent/user tokens can't write relation tuples on a hosted project, so
+     * running maybeAutoBootstrap there would only produce 403s.
+     */
+    skipAutoBootstrap?: boolean;
+}
+/**
+ * The shared post-install entry point every harness's `install` command
+ * calls. Runs the interactive setup wizard, then (using whatever identity the
+ * wizard cached) bootstraps permissions and prints the onboarding banner.
+ *
+ * This is the single seam that centralizes what each harness previously
+ * open-coded as a local `postInstallPermissions` helper.
+ */
+export declare function runPostInstall(binName: string, harness: string, args?: string[], deps?: InteractiveSetupDeps): Promise<void>;
+/**
+ * Run the interactive setup wizard. Always resolves; never throws.
+ */
+export declare function runInteractiveSetup(binName: string, harness: string, args?: string[], deps?: InteractiveSetupDeps): Promise<InteractiveSetupResult>;
+/**
+ * Derive the canonical Ory Network project SDK/API URL from a project **slug**.
+ * The subdomain is always the slug — never the project id. A project id (a
+ * UUID) reaching here means a slug and an id were confused upstream, which
+ * would build a URL that points nowhere, so we refuse it loudly rather than
+ * silently misconfigure the plugin.
+ */
+export declare function projectUrlFromSlug(slug: string): string;