@ory/argus 0.9.1 → 0.10.0

package/dist/contract-suite.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Shared contract suite for harness plugin tests.
+ *
+ * Every harness plugin translates the same core decisions (session gates,
+ * `gateToolCall`, audit-only) onto its own native signals (exit codes,
+ * `{ decision: "block" }`, `{ block: true }`, thrown errors, …). The
+ * *decision semantics* are core-owned and tested once in `packages/core`;
+ * what varies per harness is only the translation. This suite re-runs the
+ * canonical scenario tables through a harness's real entry point via a
+ * small adapter, so a plugin cannot ship with a divergent understanding of
+ * observe / enforce / fail-open / audit-only — without each plugin
+ * re-transcribing the tables.
+ *
+ * A harness test file calls:
+ *
+ * ```ts
+ * runHarnessContractSuite({
+ *   harness: "claude-code",
+ *   tool: "Bash",
+ *   sessionCanBlock: true,
+ *   sessionStart: async ({ client, gates }) => {
+ *     const out = await handleHookEvent(sessionInput(), client, gates);
+ *     return { blocked: out.decision === "block", reason: out.reason };
+ *   },
+ *   toolBefore: async ({ client, gates }, tool) => { ... },
+ * });
+ * ```
+ *
+ * and then adds only its genuinely harness-specific tests: export shape,
+ * event-name dispatch, block-signal details, input parsing (MCP names,
+ * `subagent_type`), unique span enrichment, and the install CLI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHarnessContractSuite = runHarnessContractSuite;
+const vitest_1 = require("vitest");
+const config_js_1 = require("./config.js");
+const testing_js_1 = require("./testing.js");
+const DISABLED_DECISION = {
+    proceed: true,
+    mode: "disabled",
+    reason: "ORY_USER_LOGIN not enabled",
+};
+function makeGates(userDecision = DISABLED_DECISION) {
+    return {
+        userLogin: vitest_1.vi.fn(async () => userDecision),
+        agentGate: vitest_1.vi.fn(async () => ({
+            kind: "none",
+            reason: "not configured in contract suite",
+            warnings: [],
+        })),
+        subAgentGate: vitest_1.vi.fn(async () => ({
+            kind: "none",
+            subAgentType: "none",
+            reason: "not configured in contract suite",
+            warnings: [],
+        })),
+    };
+}
+const ENV_KEYS = [
+    "ORY_PROJECT_URL",
+    "ORY_API_KEY",
+    "ORY_SESSION_TOKEN",
+    "ORY_OAUTH2_TOKEN",
+    "ORY_USER_SESSION_TOKEN",
+    "ORY_USER_OAUTH2_TOKEN",
+    "ORY_USER_LOGIN",
+    "ORY_USER_SUBJECT_ID",
+    "ORY_USER_SUBJECT_NAMESPACE",
+    "ORY_AGENT_SUBJECT_ID",
+    "ORY_PERMISSION_MODE",
+    "ORY_PERMISSION_NAMESPACE",
+    "ORY_INTERACTIVE_TOOLS",
+];
+/**
+ * Run the canonical harness contract scenarios through the adapter.
+ * Call once per harness test file, then add harness-specific tests.
+ */
+function runHarnessContractSuite(adapter) {
+    const toolCanBlock = adapter.toolCanBlock ?? true;
+    (0, vitest_1.describe)(`${adapter.harness} — Ory harness contract`, () => {
+        let client;
+        let restoreConfigDir;
+        const savedEnv = {};
+        (0, vitest_1.beforeEach)(() => {
+            for (const key of ENV_KEYS) {
+                savedEnv[key] = process.env[key];
+                delete process.env[key];
+            }
+            restoreConfigDir = (0, testing_js_1.useTempConfigDir)();
+            process.env.ORY_PROJECT_URL = "https://test.projects.oryapis.com";
+            client = (0, testing_js_1.createMockClient)({ harness: adapter.harness });
+        });
+        (0, vitest_1.afterEach)(() => {
+            restoreConfigDir();
+            for (const key of ENV_KEYS) {
+                if (savedEnv[key] === undefined)
+                    delete process.env[key];
+                else
+                    process.env[key] = savedEnv[key];
+            }
+        });
+        const ctx = (gates = makeGates()) => ({ client, gates });
+        // ── Session start never blocks on auth/infra failures ─────────
+        (0, vitest_1.describe)("session start is fail-open", () => {
+            vitest_1.it.each([
+                { name: "valid session token", env: "session", stub: testing_js_1.stubSessionSuccess },
+                { name: "inactive session", env: "session", stub: testing_js_1.stubSessionInactive },
+                { name: "session network error", env: "session", stub: testing_js_1.stubSessionNetworkError },
+                { name: "MFA required", env: "session", stub: testing_js_1.stubSessionMfaRequired },
+                { name: "valid OAuth2 token", env: "oauth2", stub: testing_js_1.stubOAuth2Success },
+                { name: "inactive OAuth2 token", env: "oauth2", stub: testing_js_1.stubOAuth2Inactive },
+                { name: "unconfigured (no project URL)", env: "none", stub: undefined },
+            ])("proceeds with $name", async ({ env, stub, name }) => {
+                if (name.includes("OAuth2") && adapter.legacyOAuth2 === false)
+                    return;
+                if (env === "session")
+                    process.env.ORY_SESSION_TOKEN = "token-under-test";
+                if (env === "oauth2")
+                    process.env.ORY_OAUTH2_TOKEN = "token-under-test";
+                if (env === "none")
+                    delete process.env.ORY_PROJECT_URL;
+                stub?.(client);
+                const outcome = await adapter.sessionStart(ctx());
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+            });
+        });
+        // ── User-login gate translation ────────────────────────────────
+        (0, vitest_1.describe)("user-login gate", () => {
+            const declined = {
+                proceed: false,
+                mode: "declined",
+                reason: "User declined the OAuth2 consent screen",
+            };
+            (0, vitest_1.it)(adapter.sessionCanBlock
+                ? "translates a declined login into the native session block"
+                : "treats a declined login as advisory (no session block channel)", async () => {
+                const gates = makeGates(declined);
+                const outcome = await adapter.sessionStart(ctx(gates));
+                (0, vitest_1.expect)(outcome.blocked).toBe(adapter.sessionCanBlock);
+                if (adapter.sessionCanBlock) {
+                    (0, vitest_1.expect)(outcome.reason).toBeTruthy();
+                }
+            });
+            (0, vitest_1.it)("runs the agent gate even when the user gate declines", async () => {
+                const gates = makeGates(declined);
+                await adapter.sessionStart(ctx(gates));
+                (0, vitest_1.expect)(gates.agentGate).toHaveBeenCalledOnce();
+            });
+            (0, vitest_1.it)("proceeds without legacy verification when the gate handled auth", async () => {
+                process.env.ORY_SESSION_TOKEN = "should-not-be-verified";
+                const verify = (0, testing_js_1.stubSessionSuccess)(client);
+                const gates = makeGates({ proceed: true, mode: "ok", reason: "logged in" });
+                const outcome = await adapter.sessionStart(ctx(gates));
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)(verify).not.toHaveBeenCalled();
+            });
+            (0, vitest_1.it)("falls through to legacy verification when the gate is disabled", async () => {
+                process.env.ORY_SESSION_TOKEN = "legacy-token";
+                const verify = (0, testing_js_1.stubSessionSuccess)(client);
+                const outcome = await adapter.sessionStart(ctx());
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)(verify).toHaveBeenCalled();
+            });
+        });
+        // ── Tool gate translation ──────────────────────────────────────
+        (0, vitest_1.describe)("tool gate", () => {
+            vitest_1.it.each([
+                { check: "allowed", mode: "enforce", blocked: false, invoke: true, block: false },
+                { check: "denied", mode: "enforce", blocked: toolCanBlock, invoke: false, block: true },
+                { check: "denied", mode: "observe", blocked: false, invoke: true, block: true },
+                { check: "network_error", mode: "enforce", blocked: false, invoke: false, block: false },
+                { check: "rate_limited", mode: "enforce", blocked: false, invoke: false, block: false },
+            ])("check=$check × $mode → blocked=$blocked", async ({ check, mode, blocked, invoke, block }) => {
+                const stubs = {
+                    allowed: testing_js_1.stubPermissionAllowed,
+                    denied: testing_js_1.stubPermissionDenied,
+                    network_error: testing_js_1.stubPermissionNetworkError,
+                    rate_limited: testing_js_1.stubPermissionRateLimited,
+                };
+                stubs[check](client);
+                process.env.ORY_PERMISSION_MODE = mode;
+                const outcome = await adapter.toolBefore(ctx(), adapter.tool);
+                (0, vitest_1.expect)(outcome.blocked).toBe(blocked);
+                if (blocked)
+                    (0, vitest_1.expect)(outcome.reason).toBeTruthy();
+                const invokeSpans = (0, testing_js_1.getTraceSpans)(client, "tool.invoke");
+                const blockSpans = (0, testing_js_1.getTraceSpans)(client, "tool.block");
+                if (invoke) {
+                    (0, vitest_1.expect)(invokeSpans.length).toBeGreaterThanOrEqual(1);
+                    (0, vitest_1.expect)(invokeSpans[0].attributes?.toolName).toBe(adapter.tool);
+                }
+                else {
+                    (0, vitest_1.expect)(invokeSpans).toHaveLength(0);
+                }
+                if (block) {
+                    (0, vitest_1.expect)(blockSpans.length).toBeGreaterThanOrEqual(1);
+                    (0, vitest_1.expect)(blockSpans[0].attributes?.blocked).toBe(mode === "enforce" && toolCanBlock);
+                }
+                else {
+                    (0, vitest_1.expect)(blockSpans).toHaveLength(0);
+                }
+                // Observe-mode denies also emit the audit span; enforce must not.
+                const observeSpans = (0, testing_js_1.getTraceSpans)(client, "permission.observe_deny");
+                (0, vitest_1.expect)(observeSpans).toHaveLength(check === "denied" && mode === "observe" ? 1 : 0);
+            });
+            (0, vitest_1.it)("skips the permission check entirely in audit-only mode", async () => {
+                (0, config_js_1.saveConfig)({ auditOnly: true });
+                const checkSpy = vitest_1.vi.spyOn(client, "checkPermission");
+                process.env.ORY_PERMISSION_MODE = "enforce";
+                const outcome = await adapter.toolBefore(ctx(), adapter.tool);
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)(checkSpy).not.toHaveBeenCalled();
+            });
+            (0, vitest_1.it)("addresses the check to ORY_USER_SUBJECT_ID when set", async () => {
+                process.env.ORY_USER_SUBJECT_ID = "user:custom-override";
+                (0, testing_js_1.stubPermissionAllowed)(client);
+                await adapter.toolBefore(ctx(), adapter.tool);
+                const [span] = (0, testing_js_1.getTraceSpans)(client, "tool.invoke");
+                (0, vitest_1.expect)(span.attributes?.subjectId).toBe("user:custom-override");
+            });
+        });
+        // ── Post-tool + passthrough ────────────────────────────────────
+        if (adapter.toolAfter) {
+            (0, vitest_1.it)("records tool.complete after execution", async () => {
+                await adapter.toolAfter(ctx(), adapter.tool);
+                const spans = (0, testing_js_1.getTraceSpans)(client, "tool.complete");
+                (0, vitest_1.expect)(spans.length).toBeGreaterThanOrEqual(1);
+                (0, vitest_1.expect)(spans[0].attributes?.toolName).toBe(adapter.tool);
+            });
+        }
+        if (adapter.unknownEvent) {
+            (0, vitest_1.it)("passes unknown events through with the native empty response", async () => {
+                const raw = await adapter.unknownEvent(ctx());
+                (0, vitest_1.expect)(raw).toEqual(adapter.unknownEventOutput);
+            });
+        }
+    });
+}

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export { resolveUserSubject, subjectLabel, type UserSubjectRef, } from "./subjec
 export { formatDenialMessage, formatDenialSummary, formatAlertMessage, formatAlertSummary, alertAttributes, OryDenialError, type DenialContext, type AlertAttributes, } from "./denial.js";
 export { summarizeToolInput, summarizeToolOutput, type ToolInputSummary, type ToolOutputSummary, } from "./tool-metadata.js";
 export { OtlpExporter, otlpExporterFromEnv, parseKeyValueList, type SpanExporter, type OtlpExporterOptions, type OtlpProtocol, } from "./otel/index.js";
+export { resolveNamespace, sessionStart, gate, complete, registerSubagent, wrapTool, type SessionStartResult, type SessionStartOptions, type RegisterSubagentOptions, type GateResult, type GateOptions, type WrapToolOptions, } from "./adapters.js";

package/dist/index.js

@@ -2,7 +2,7 @@
 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.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = 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.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.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;
 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");
@@ -164,3 +164,10 @@ var index_js_3 = require("./otel/index.js");
 Object.defineProperty(exports, "OtlpExporter", { enumerable: true, get: function () { return index_js_3.OtlpExporter; } });
 Object.defineProperty(exports, "otlpExporterFromEnv", { enumerable: true, get: function () { return index_js_3.otlpExporterFromEnv; } });
 Object.defineProperty(exports, "parseKeyValueList", { enumerable: true, get: function () { return index_js_3.parseKeyValueList; } });
+var adapters_js_1 = require("./adapters.js");
+Object.defineProperty(exports, "resolveNamespace", { enumerable: true, get: function () { return adapters_js_1.resolveNamespace; } });
+Object.defineProperty(exports, "sessionStart", { enumerable: true, get: function () { return adapters_js_1.sessionStart; } });
+Object.defineProperty(exports, "gate", { enumerable: true, get: function () { return adapters_js_1.gate; } });
+Object.defineProperty(exports, "complete", { enumerable: true, get: function () { return adapters_js_1.complete; } });
+Object.defineProperty(exports, "registerSubagent", { enumerable: true, get: function () { return adapters_js_1.registerSubagent; } });
+Object.defineProperty(exports, "wrapTool", { enumerable: true, get: function () { return adapters_js_1.wrapTool; } });

package/dist/lifecycle.js

@@ -44,6 +44,7 @@ exports.isToolExecutionPhase = isToolExecutionPhase;
  * `passthrough` via {@link classifyLifecycle}.
  */
 exports.HARNESS_LIFECYCLE_MAP = {
+    // ── Coding-agent harnesses ──
     "claude-code": {
         SessionStart: "session.start",
         SessionEnd: "session.stop",
@@ -88,6 +89,134 @@ exports.HARNESS_LIFECYCLE_MAP = {
         "tool.execute.before": "tool.before",
         "tool.execute.after": "tool.after",
     },
+    // Continue's `Stop` brackets a turn (not the session) and `ConfigChange`
+    // carries no lifecycle meaning — both fall through to passthrough and are
+    // traced as audit spans by the handler.
+    continue: {
+        SessionStart: "session.start",
+        SessionEnd: "session.stop",
+        PreToolUse: "tool.before",
+        PostToolUse: "tool.after",
+        PostToolUseFailure: "tool.failure",
+        PermissionRequest: "permission.ask",
+        UserPromptSubmit: "user.prompt",
+        SubagentStart: "subagent.start",
+        SubagentStop: "subagent.stop",
+        PreCompact: "compaction",
+    },
+    // Goose's file/shell notification hooks surface activity to the user and
+    // are trace-only — user-facing, never gated.
+    goose: {
+        SessionStart: "session.start",
+        SessionEnd: "session.stop",
+        Stop: "session.stop",
+        PreToolUse: "tool.before",
+        PostToolUse: "tool.after",
+        PostToolUseFailure: "tool.failure",
+        UserPromptSubmit: "user.prompt",
+        BeforeReadFile: "user.interaction",
+        AfterFileEdit: "user.interaction",
+        BeforeShellExecution: "user.interaction",
+        AfterShellExecution: "user.interaction",
+    },
+    cline: {
+        agent_start: "session.start",
+        agent_resume: "session.start",
+        agent_abort: "session.stop",
+        agent_end: "session.stop",
+        agent_error: "session.stop",
+        session_shutdown: "session.stop",
+        tool_call: "tool.before",
+        tool_result: "tool.after",
+        prompt_submit: "user.prompt",
+        pre_compact: "compaction",
+    },
+    // Amp is hybrid: session.start / tool.result are in-process plugin events;
+    // tool.call is gated by the subprocess permission delegate. agent.start /
+    // agent.end bracket a turn and fall through to passthrough.
+    amp: {
+        "session.start": "session.start",
+        "tool.call": "tool.before",
+        "tool.result": "tool.after",
+    },
+    // Pi runs session start in the extension factory body (awaited before
+    // startup); `session_start` is the harness's equivalent event name.
+    pi: {
+        session_start: "session.start",
+        tool_call: "tool.before",
+        tool_result: "tool.after",
+    },
+    // Google Antigravity (`agy` CLI / IDE). Subprocess hooks with
+    // Claude-Code-style snake_case payloads. PreInvocation/PostInvocation
+    // bracket each agent turn (not user prompts), so they fall through to
+    // passthrough and are traced as audit spans by the handler.
+    antigravity: {
+        SessionStart: "session.start",
+        SessionEnd: "session.stop",
+        Stop: "session.stop",
+        PreToolUse: "tool.before",
+        PostToolUse: "tool.after",
+        Notification: "user.interaction",
+    },
+    // ── Agent SDK integrations ── (parity with `ory_argus.lifecycle`; each
+    // entry names the canonical extension point the integration hooks)
+    langchain: {
+        "wrap_tool_call.before": "tool.before",
+        "wrap_tool_call.after": "tool.after",
+        on_tool_start: "tool.before",
+        on_tool_end: "tool.after",
+        on_tool_error: "tool.failure",
+    },
+    "openai-agents": {
+        tool_input_guardrail: "tool.before",
+        tool_output_guardrail: "tool.after",
+        on_tool_start: "tool.before",
+        on_tool_end: "tool.after",
+        on_handoff: "subagent.start",
+    },
+    crewai: {
+        ToolUsageStartedEvent: "tool.before",
+        ToolUsageFinishedEvent: "tool.after",
+        ToolUsageErrorEvent: "tool.failure",
+    },
+    llamaindex: {
+        AgentToolCallEvent: "tool.before",
+        function_call: "tool.before",
+        function_call_result: "tool.after",
+    },
+    "pydantic-ai": {
+        "call_tool.before": "tool.before",
+        "call_tool.after": "tool.after",
+    },
+    "agent-framework": {
+        "function_middleware.before": "tool.before",
+        "function_middleware.after": "tool.after",
+    },
+    "vercel-ai": {
+        "execute.before": "tool.before",
+        "execute.after": "tool.after",
+    },
+    "claude-agent-sdk": {
+        PreToolUse: "tool.before",
+        PostToolUse: "tool.after",
+    },
+    "google-adk": {
+        before_tool_callback: "tool.before",
+        after_tool_callback: "tool.after",
+        transfer_to_agent: "subagent.start",
+    },
+    mastra: {
+        beforeToolCall: "tool.before",
+        afterToolCall: "tool.after",
+    },
+    strands: {
+        BeforeToolCallEvent: "tool.before",
+        AfterToolCallEvent: "tool.after",
+    },
+    "cloudflare-agents": {
+        "execute.before": "tool.before",
+        "execute.after": "tool.after",
+    },
 };
 /**
  * Resolve a harness event name to its canonical {@link LifecyclePhase}.

package/dist/local/configs.d.ts

@@ -73,8 +73,8 @@ export declare const GATEWAY_PORT = 4000;
 export declare const GATEWAY_URL = "http://localhost:4000";
 export declare const CONSOLE_PORT = 4100;
 export declare const CONSOLE_URL = "http://localhost:4100";
-export declare const LOGIN_UI_PORT = 3000;
-export declare const LOGIN_UI_URL = "http://localhost:3000";
+export declare const LOGIN_UI_PORT = 4455;
+export declare const LOGIN_UI_URL = "http://localhost:4455";
 export declare const KRATOS_PUBLIC_PORT = 4433;
 export declare const KRATOS_ADMIN_PORT = 4434;
 export declare const KETO_READ_PORT = 4466;

package/dist/local/configs.js

@@ -189,6 +189,14 @@ function nginxGatewayService() {
  * `COOKIE_SECRET` and `CSRF_COOKIE_SECRET` are required by the image —
  * the container exits at startup if they're missing. Both must be at
  * least 32 chars. Fixed dev-only values so launches are deterministic.
+ *
+ * `DANGEROUSLY_DISABLE_SECURE_CSRF_COOKIES=true` is required for local
+ * dev (HTTP, not HTTPS). Without it the csrf-csrf library sets `Secure`
+ * cookies, which the browser silently drops over plain HTTP. This causes
+ * every self-service flow (login, registration, settings) to fail with a
+ * 403 CSRF error, and the registration handler's redirectOnSoftError
+ * enters an infinite redirect loop — pegging CPU and making the UI
+ * unusable. Only safe for loopback-local dev.
  */
 function loginUiService() {
     return `  login-ui:
@@ -207,6 +215,7 @@ function loginUiService() {
       COOKIE_SECRET: "ory-agent-plugins-local-cookie-secret-32+"
       CSRF_COOKIE_NAME: "ory_agent_plugins_local_csrf"
       CSRF_COOKIE_SECRET: "ory-agent-plugins-local-csrf-secret-32+!"
+      DANGEROUSLY_DISABLE_SECURE_CSRF_COOKIES: "true"
     depends_on:
       - kratos
       - hydra
@@ -616,7 +625,7 @@ exports.GATEWAY_PORT = 4000;
 exports.GATEWAY_URL = `http://localhost:${exports.GATEWAY_PORT}`;
 exports.CONSOLE_PORT = 4100;
 exports.CONSOLE_URL = `http://localhost:${exports.CONSOLE_PORT}`;
-exports.LOGIN_UI_PORT = 3000;
+exports.LOGIN_UI_PORT = 4455;
 exports.LOGIN_UI_URL = `http://localhost:${exports.LOGIN_UI_PORT}`;
 exports.KRATOS_PUBLIC_PORT = 4433;
 exports.KRATOS_ADMIN_PORT = 4434;

package/dist/local/manager.d.ts

@@ -24,10 +24,12 @@ export interface EnsureLocalOryStackResult {
  * Bring up the local Ory stack and wait for the gateway to be healthy.
  *
  * Idempotent and fail-graceful: returns a typed result instead of exiting.
- * If the gateway is already healthy the function short-circuits without
- * touching Docker. When `quiet` is set, progress is logged to stderr only
- * (suitable for the dev launcher); otherwise it prints to stdout in the
- * format `localUp` historically used.
+ * If the gateway is already healthy AND the running stack's config matches
+ * what the current code generates (verified by a config fingerprint), the
+ * function short-circuits without touching Docker; otherwise it regenerates
+ * the config and runs `docker compose up -d --wait` to reconcile. When
+ * `quiet` is set, progress is logged to stderr only (suitable for the dev
+ * launcher); otherwise it prints to stdout in the format `localUp` historically used.
  */
 export declare function ensureLocalOryStack(opts?: {
     quiet?: boolean;

package/dist/local/manager.js

@@ -57,6 +57,7 @@ exports.localEnv = localEnv;
 exports.localConfigure = localConfigure;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
 const configs_js_1 = require("./configs.js");
 const health_js_1 = require("./health.js");
@@ -196,28 +197,86 @@ function dumpCapturedOutput(label, result) {
     process.stderr.write(`── end ${label} output ──\n\n`);
 }
 // ─── Write config files ────────────────────────────────────────────
+/**
+ * Render the full set of local-stack config files as `{ relPath, content }`
+ * pairs. Pure function of the code, `projectRoot`, and `consoleCfg` — no I/O.
+ * `writeConfigs` writes these and `configFingerprint` hashes them, so the
+ * on-disk stack and its change-detection signal never drift.
+ */
+function renderConfigs(projectRoot, consoleCfg) {
+    return [
+        {
+            relPath: "docker-compose.yml",
+            content: (0, configs_js_1.dockerComposeYaml)(projectRoot, consoleCfg),
+        },
+        { relPath: "kratos/kratos.yml", content: (0, configs_js_1.kratosConfigYaml)() },
+        {
+            relPath: "kratos/identity-schema.json",
+            content: (0, configs_js_1.kratosIdentitySchema)(),
+        },
+        { relPath: "keto/keto.yml", content: (0, configs_js_1.ketoConfigYaml)() },
+        { relPath: "hydra/hydra.yml", content: (0, configs_js_1.hydraConfigYaml)() },
+        // nginx config is always emitted — the gateway is no longer optional.
+        { relPath: "nginx/nginx.conf", content: (0, configs_js_1.nginxConf)() },
+    ];
+}
+/**
+ * Stable content hash of the rendered config set. Used to decide whether an
+ * already-running stack still matches the config the current code would
+ * generate; a change (e.g. the login-UI port, a service env var) invalidates
+ * the fast-path short-circuit so the stack is reconciled instead of reused.
+ */
+function configFingerprint(projectRoot, consoleCfg) {
+    const hash = crypto.createHash("sha256");
+    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg)) {
+        hash.update(relPath);
+        hash.update("\0");
+        hash.update(content);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+const CONFIG_FINGERPRINT_FILE = ".config-fingerprint";
+/** Read the fingerprint recorded after the last successful bring-up. */
+function readConfigFingerprint(localDir) {
+    try {
+        return fs
+            .readFileSync(path.join(localDir, CONFIG_FINGERPRINT_FILE), "utf8")
+            .trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Record the fingerprint of the config the running stack was brought up with. */
+function writeConfigFingerprint(localDir, fingerprint) {
+    try {
+        fs.writeFileSync(path.join(localDir, CONFIG_FINGERPRINT_FILE), fingerprint + "\n");
+    }
+    catch {
+        // Best-effort: a missing fingerprint only costs a reconcile next launch.
+    }
+}
 function writeConfigs(localDir, projectRoot, consoleCfg) {
     ensureDir(localDir);
     ensureDir(path.join(localDir, "kratos"));
     ensureDir(path.join(localDir, "keto"));
     ensureDir(path.join(localDir, "hydra"));
     ensureDir(path.join(localDir, "nginx"));
-    fs.writeFileSync(path.join(localDir, "docker-compose.yml"), (0, configs_js_1.dockerComposeYaml)(projectRoot, consoleCfg));
-    fs.writeFileSync(path.join(localDir, "kratos", "kratos.yml"), (0, configs_js_1.kratosConfigYaml)());
-    fs.writeFileSync(path.join(localDir, "kratos", "identity-schema.json"), (0, configs_js_1.kratosIdentitySchema)());
-    fs.writeFileSync(path.join(localDir, "keto", "keto.yml"), (0, configs_js_1.ketoConfigYaml)());
-    fs.writeFileSync(path.join(localDir, "hydra", "hydra.yml"), (0, configs_js_1.hydraConfigYaml)());
-    // nginx config is always emitted — the gateway is no longer optional.
-    fs.writeFileSync(path.join(localDir, "nginx", "nginx.conf"), (0, configs_js_1.nginxConf)());
+    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg)) {
+        fs.writeFileSync(path.join(localDir, relPath), content);
+    }
 }
 /**
  * Bring up the local Ory stack and wait for the gateway to be healthy.
  *
  * Idempotent and fail-graceful: returns a typed result instead of exiting.
- * If the gateway is already healthy the function short-circuits without
- * touching Docker. When `quiet` is set, progress is logged to stderr only
- * (suitable for the dev launcher); otherwise it prints to stdout in the
- * format `localUp` historically used.
+ * If the gateway is already healthy AND the running stack's config matches
+ * what the current code generates (verified by a config fingerprint), the
+ * function short-circuits without touching Docker; otherwise it regenerates
+ * the config and runs `docker compose up -d --wait` to reconcile. When
+ * `quiet` is set, progress is logged to stderr only (suitable for the dev
+ * launcher); otherwise it prints to stdout in the format `localUp` historically used.
  */
 async function ensureLocalOryStack(opts = {}) {
     const localDir = opts.localDir ?? getLocalDir();
@@ -232,13 +291,25 @@ async function ensureLocalOryStack(opts = {}) {
     }
     const gatewayCfg = (0, configs_js_1.getGatewayConfig)();
     const healthUrl = `${configs_js_1.GATEWAY_URL}${gatewayCfg.healthPath}`;
-    // Short-circuit if the gateway is already serving — keeps repeated dev
-    // launches fast and avoids re-pulling/restarting healthy containers.
-    // Skip the short-circuit when ORY_CONSOLE_LITE_PATH is explicitly set so
-    // a path change on a subsequent run actually triggers a rebuild (compose
-    // diffs the regenerated YAML and recreates the console when needed).
+    // Short-circuit if the gateway is already serving AND the running stack was
+    // brought up with the same config the current code would generate — keeps
+    // repeated dev launches fast without re-pulling/restarting healthy
+    // containers. Gateway health alone is not enough: a config change to any
+    // service (e.g. the login-UI port, a service env var) leaves the gateway
+    // healthy while the rest of the stack runs stale config, so we also require
+    // the config fingerprint to match. On a mismatch we fall through and let
+    // `docker compose up -d --wait` diff the regenerated YAML and recreate only
+    // the changed containers.
+    //
+    // Skip the short-circuit entirely when ORY_CONSOLE_LITE_PATH is explicitly
+    // set so a rebuild is forced even when the path is unchanged (the console
+    // source tree behind the path may have changed, which the fingerprint of the
+    // generated config can't see).
     const explicitConsoleLiteOverride = (process.env.ORY_CONSOLE_LITE_PATH ?? "").trim() !== "";
+    const fingerprint = configFingerprint(projectRoot, consoleCfg);
+    const configUnchanged = readConfigFingerprint(localDir) === fingerprint;
     if (!explicitConsoleLiteOverride &&
+        configUnchanged &&
         (await isGatewayHealthy(1_500, healthUrl))) {
         return { status: "already-running", gatewayUrl: configs_js_1.GATEWAY_URL, localDir };
     }
@@ -320,6 +391,10 @@ async function ensureLocalOryStack(opts = {}) {
             detail: "Gateway did not become healthy within 2 minutes.",
         };
     }
+    // Record the fingerprint of the config the stack was actually brought up
+    // with (consoleCfg may have fallen back to disabled above), so the next
+    // launch can short-circuit only while the config is unchanged.
+    writeConfigFingerprint(localDir, configFingerprint(projectRoot, consoleCfg));
     return { status: "started", gatewayUrl: configs_js_1.GATEWAY_URL, localDir };
 }
 async function localUp(opts = {}) {