@ory/argus 0.6.2 → 0.7.1

package/assets/skills/ory-build-agent/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: ory-build-agent
+description: Build your own AI agent that authenticates the user, authorizes every tool call against Ory Permissions, and emits trace spans — by dropping `@ory/argus` directly into the Claude Agent SDK, OpenAI Agents SDK, Mastra, Vercel AI SDK, PydanticAI / LangGraph, or as an external service called by Salesforce Agentforce. Use when the user wants to wire Ory into a custom agent they own — phrases like "add Ory to my own agent", "build a custom agent with Ory auth", "wrap my Claude Agent SDK tools with Ory permissions", "OpenAI Agents SDK with Ory", "Mastra agent with Ory permissions", "Agentforce action with Ory", "use `@ory/argus` directly". For wiring Ory into an existing agent harness (Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode) use the corresponding `@ory/<harness>` plugin instead.
+---
+
+# Build your own agent with `@ory/argus`
+
+You are helping the user wire Ory Identities, Permissions, and tracing into
+**an agent they are building themselves**. They are not extending Claude Code,
+Codex, or one of the other harness plugins — they own the agent loop and
+choose where to intercept tool calls.
+
+The integration is the same three moves regardless of SDK:
+
+1. **User gate at start.** `ensureUserAuthenticated(client, …)` — the human at
+   the keyboard becomes the subject of every permission check.
+2. **Agent gate at start.** `ensureAgentIdentity(client, …)` — the process
+   making outbound Ory API calls gets its own credential (OAuth2 Dynamic
+   Client Registration by default, persisted across sessions).
+3. **Permission check on every tool call.** Wrap the SDK's tool dispatch with
+   `checkAndDecide(client, …)` and branch on `decision.kind`. Record a
+   `tool.complete` span after the tool returns.
+
+`@ory/argus` ships every helper and handles fail-open semantics (network
+errors, rate limits, unconfigured project → allow). The SDKs differ only in
+**where** that wrapper goes.
+
+> **Precondition:** the user has an Ory project (or will spin up the local
+> stack — see {{REF_LOCAL_DEV}}) and has the env vars from
+> {{REF_AUTH_SETUP}} figured out. Do not fabricate credentials or scaffold a
+> project on their behalf.
+
+## Step 1 — Pick the SDK and confirm the agent shape
+
+Ask the user which SDK they're using and what the agent looks like. Below
+are the SDKs this skill carries explicit recipes for. Others (LangChain,
+LlamaIndex, generic OpenAI tool-calling loops) follow the same pattern —
+wrap each tool dispatch with the gate from Step 4.
+
+| SDK | Language | Where Ory hooks in |
+|---|---|---|
+| Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) | TypeScript / Python | `canUseTool` callback on `query({...})` |
+| OpenAI Agents SDK (`@openai/agents`) | TypeScript | Per-tool `execute` wrapper or `RunHooks.onToolStart` |
+| Salesforce Agentforce (Agent Builder) | declarative + Apex | External Service / side-car — see "Salesforce" below |
+| Mastra (`@mastra/core`) | TypeScript | Higher-order wrapper around each tool's `execute` |
+| Mistral AI (`@mistralai/mistralai` / `mistralai`) | TypeScript / Python | Per-tool wrapper inside the chat-completion loop or the Agents API tool registry |
+| PydanticAI (`pydantic-ai`) | Python | `@agent.tool` decorator stack |
+| Vercel AI SDK (`ai`) | TypeScript | Higher-order wrapper at `streamText({ tools })` |
+| LangGraph (`langgraph`) | Python / TypeScript | `ToolNode` wrapper or `RunnableLambda` per tool |
+
+Also establish:
+
+- **Interactive vs headless.** Desktop / terminal agents can run PKCE login.
+  Headless services (CI, daemons, Salesforce side-cars) must pre-supply
+  `ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN`.
+- **Which tools to gate.** Usually all of them. Some SDKs have built-in
+  "safe" steps (an LLM-only reasoning step, a model-provided memory tool)
+  that don't need a permission check.
+- **Language.** `@ory/argus` is JavaScript-first. Python frameworks call out
+  to a tiny Node side-car or use the official `ory-client` Python SDK
+  directly; the snippet below shows the side-car shape.
+
+## Step 2 — Install `@ory/argus`
+
+```bash
+npm install @ory/argus
+```
+
+That's the only Ory dependency you need. The Ory SDK clients
+(`@ory/client`) and the OAuth2/PKCE plumbing are re-exported and ready to
+use.
+
+## Step 3 — Construct the client and run both gates
+
+Put this at the top of the agent's bootstrap, before the agent loop starts
+processing the first message:
+
+```ts
+import {
+  OryAgentClient,
+  ensureUserAuthenticated,
+  ensureAgentIdentity,
+  resolveConfig,
+} from "@ory/argus";
+
+const client = OryAgentClient.fromEnv("my-agent");
+const { projectUrl } = resolveConfig();
+
+// 1. User gate — interactive PKCE when ORY_USER_LOGIN=1, no-op otherwise.
+const userDecision = await ensureUserAuthenticated(client, {
+  binName: "my-agent",
+  harness: "my-agent",
+  allowBlock: true, // flip to false if your agent can't refuse to start
+});
+if (userDecision.proceed === false) {
+  console.error(`Ory user login: ${userDecision.reason}`);
+  process.exit(2);
+}
+
+// 2. Agent gate — never blocks; resolves machine credentials (DCR by default).
+await ensureAgentIdentity(client, { projectUrl, harness: "my-agent" });
+
+// 3. (optional) write the user→agent delegation tuple for audit.
+if (client.userPrincipal.subject && client.agentPrincipal.subject) {
+  await client
+    .createRelationship({
+      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
+      object: `agent:${client.agentPrincipal.subject}`,
+      relation: "delegate",
+      subjectId: `user:${client.userPrincipal.subject}`,
+    })
+    .catch(() => undefined); // audit-only — swallow failures
+}
+```
+
+Set `allowBlock: false` when the agent runs in-process inside a parent
+application and can't refuse to start. The gate still runs in advisory mode
+— it refreshes tokens, prompts on TTY, emits the `user.auth` span — but
+always returns `proceed: true`.
+
+## Step 4 — The shared gate body
+
+This snippet is reused verbatim from every SDK-specific section in Step 5.
+Put it next to where you construct the client.
+
+```ts
+import {
+  checkAndDecide,
+  resolveUserSubject,
+  subjectLabel,
+} from "@ory/argus";
+
+async function gateTool(toolName: string, sessionId: string) {
+  const subject = resolveUserSubject(client, `session:${sessionId}`);
+  const decision = await checkAndDecide(
+    client,
+    {
+      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
+      object: toolName,
+      relation: "use",
+      ...subject,
+    },
+    { spanAttributes: { toolName } }
+  );
+
+  switch (decision.kind) {
+    case "allow":
+    case "observe":
+    case "fail_open":
+      return { allow: true as const };
+    case "deny":
+      return {
+        allow: false as const,
+        message: `Ory denied ${toolName} for ${subjectLabel(subject)}.`,
+      };
+  }
+}
+```
+
+After the tool finishes (whichever SDK), record a completion span:
+
+```ts
+client.tracer.record("tool.complete", "ok", {
+  attributes: { toolName, durationMs },
+});
+```
+
+`checkAndDecide` already records `permission.check`, `permission.observe_deny`
+(on observe), and `tool.block` (on deny). You only own `tool.complete`.
+
+## Step 5 — SDK-specific wiring
+
+### Claude Agent SDK
+
+The Claude Agent SDK exposes a `canUseTool` callback that fires before every
+tool invocation. Drop the gate there:
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+const stream = query({
+  prompt,
+  options: {
+    canUseTool: async (toolName, input, { signal }) => {
+      const sessionId = currentSessionId(); // your own correlation id
+      const gate = await gateTool(toolName, sessionId);
+      if (!gate.allow) {
+        return { behavior: "deny", message: gate.message };
+      }
+      return { behavior: "allow", updatedInput: input };
+    },
+  },
+});
+
+for await (const msg of stream) { /* standard handling */ }
+```
+
+`canUseTool` only fires for tools the SDK controls. If the agent also
+registers MCP servers, wrap each MCP tool handler the same way — see the
+`@ory/argus` `parseClaudeCodeMcpTool` / `checkMcpPermission` helpers for an
+MCP-flavored version of the gate.
+
+### OpenAI Agents SDK
+
+The OpenAI Agents SDK supports per-run lifecycle hooks via `RunHooks` plus
+per-tool `execute` overrides. Pick whichever you prefer:
+
+```ts
+import { Agent, Runner, tool } from "@openai/agents";
+
+const search = tool({
+  name: "search",
+  description: "...",
+  parameters: SearchParams,
+  execute: async (input, ctx) => {
+    const gate = await gateTool("search", ctx.runId);
+    if (!gate.allow) return { error: gate.message };
+    return realSearch(input);
+  },
+});
+
+const agent = new Agent({ name: "my-agent", tools: [search], model: "gpt-4.1" });
+await new Runner().run(agent, prompt);
+```
+
+For agent-wide enforcement without per-tool wrapping, register a
+`on_tool_start` hook on the runner and throw on deny — the SDK surfaces the
+throw to the model as a tool error.
+
+### Salesforce Agentforce (Agent Builder)
+
+Agentforce is a declarative agent inside the Salesforce platform — you
+**cannot** embed `@ory/argus` in the agent process. Instead:
+
+1. Stand up a small Node.js service that hosts the gated tools and exposes
+   each as an HTTP endpoint. Inside that service, run Steps 3 + 4 exactly as
+   above, then call `gateTool(...)` at the top of every handler.
+2. Register the service in Salesforce as a **Named Credential** plus an
+   **External Service** (OpenAPI 3 spec). Each operation becomes an
+   Agentforce **Action**.
+3. Define an Agentforce **Topic** whose actions call the External Service
+   operations. The gate runs inside your Node service on every call; denies
+   come back as tool errors the agent surfaces to the user.
+
+Pre-supply `ORY_USER_SESSION_TOKEN` (or `ORY_USER_OAUTH2_TOKEN`) to the
+side-car from a session the user established out-of-band — for example, a
+PKCE flow at sign-on into the Experience Cloud site that fronts the agent.
+A headless side-car cannot run PKCE on its own.
+
+### Mastra Agent Framework
+
+Mastra runs tools via `tool.execute({ context, runtimeContext })`. Wrap the
+agent's tool registry at construction:
+
+```ts
+import { Agent } from "@mastra/core";
+
+function gated<T extends { id: string; execute: (a: any) => Promise<any> }>(t: T): T {
+  const original = t.execute.bind(t);
+  return {
+    ...t,
+    execute: async (args: any) => {
+      const sessionId = args.runtimeContext?.sessionId ?? "unknown";
+      const gate = await gateTool(t.id, sessionId);
+      if (!gate.allow) return { error: gate.message };
+      return original(args);
+    },
+  };
+}
+
+const agent = new Agent({
+  name: "my-agent",
+  model,
+  tools: Object.fromEntries(
+    Object.entries(tools).map(([id, t]) => [id, gated(t)])
+  ),
+});
+```
+
+### Mistral AI
+
+Mistral's SDK (`@mistralai/mistralai` for TypeScript, `mistralai` for
+Python) exposes two surfaces. Both gate the same way.
+
+**Chat-completion loop with tools.** You own the loop: call `chat.complete`,
+inspect `tool_calls` on the response, run each tool, send the results back.
+Gate inside the tool dispatcher:
+
+```ts
+import { Mistral } from "@mistralai/mistralai";
+
+const client_ai = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
+
+async function step(messages: any[], sessionId: string) {
+  const res = await client_ai.chat.complete({
+    model: "mistral-large-latest",
+    messages,
+    tools, // [{ type: "function", function: { name, parameters, description } }]
+    toolChoice: "auto",
+  });
+  const choice = res.choices[0];
+  if (!choice.message.toolCalls?.length) return choice.message;
+
+  const toolResults = await Promise.all(
+    choice.message.toolCalls.map(async (call) => {
+      const gate = await gateTool(call.function.name, sessionId);
+      if (!gate.allow) {
+        return { toolCallId: call.id, name: call.function.name, content: gate.message };
+      }
+      const output = await runTool(call.function.name, JSON.parse(call.function.arguments));
+      return { toolCallId: call.id, name: call.function.name, content: JSON.stringify(output) };
+    })
+  );
+  return step(
+    [...messages, choice.message, ...toolResults.map((r) => ({ role: "tool", ...r }))],
+    sessionId
+  );
+}
+```
+
+**Mistral Agents API (la Plateforme).** When you use the managed Agents API
+(`agents.create({ tools })`, `conversations.start`), Mistral runs the tool
+loop server-side and only calls back to your code for tools it can't
+execute itself — i.e. your "function" tools delivered via webhook. Wrap
+each webhook handler with `gateTool(...)` and return either the result or
+the gate's denial message. The server-side connectors (`web_search`,
+`code_interpreter`, MCP connectors) execute inside Mistral and bypass your
+gate — model them explicitly in your Ory namespace if you want to control
+them, e.g. by writing per-connector tuples and skipping the agent
+definition for users without the relation.
+
+The same Python recipe applies via the `mistralai` package — replace the
+`client_ai.chat.complete(...)` call with `client_ai.chat.complete(...)` from
+the Python SDK and use the side-car pattern for `gateTool` (see
+PydanticAI).
+
+### PydanticAI (Python — covers the "Pi"-style framework slot)
+
+Pure-Python agents don't link `@ory/argus` directly. The two supported
+patterns:
+
+- **Side-car HTTP service.** Run a small Node process that exposes
+  `POST /gate` (calls `gateTool`) and `POST /trace` (calls
+  `client.tracer.record(...)`). Your Python agent calls these from inside
+  each `@agent.tool`.
+- **Direct Ory APIs.** Use the official `ory-client` Python SDK to call
+  `PermissionApi.check_permission()` and post audit spans to your own
+  collector. You lose the fail-open / observe-mode helpers; re-implement
+  them in Python.
+
+Side-car pattern:
+
+```python
+from pydantic_ai import Agent, RunContext
+import httpx
+
+agent = Agent("openai:gpt-4.1", deps_type=AgentDeps)
+
+@agent.tool
+async def search(ctx: RunContext[AgentDeps], q: str) -> str:
+    r = await httpx.post("http://localhost:5310/gate",
+                          json={"tool": "search", "session": ctx.deps.session_id})
+    if not r.json()["allow"]:
+        return r.json()["message"]
+    return real_search(q)
+```
+
+The same Python pattern applies verbatim to **LangGraph** (wrap each
+`ToolNode` in a `RunnableLambda` that calls `/gate` first) and to
+**LlamaIndex** agents (override `FunctionTool.acall`).
+
+### Vercel AI SDK
+
+The `ai` package's `tool()` helper produces descriptors consumed by
+`streamText` / `generateText`. Wrap them at construction:
+
+```ts
+import { streamText, tool } from "ai";
+
+function gated(name: string, def: ReturnType<typeof tool>) {
+  return tool({
+    ...def,
+    execute: async (input, ctx) => {
+      const gate = await gateTool(name, ctx.toolCallId);
+      if (!gate.allow) return { error: gate.message };
+      return def.execute(input, ctx);
+    },
+  });
+}
+
+await streamText({
+  model,
+  tools: { search: gated("search", searchTool), write: gated("write", writeTool) },
+  prompt,
+});
+```
+
+### LangGraph (TypeScript)
+
+LangGraph's `ToolNode` runs a registered tool array. Wrap each tool the same
+way Vercel AI SDK does, then pass the wrapped array to `new ToolNode(...)`.
+The `gateTool` body does not change.
+
+## Step 6 — Test against the local Ory stack
+
+Before pointing at production, run the gate against the local stack so the
+PKCE flow, permission tuples, and trace spans are all visible:
+
+1. {{REF_LOCAL_UP}} — brings up Kratos / Keto / Hydra on `localhost:4000`
+   and seeds a demo user. The banner prints the email + password.
+2. Export the env vars the launcher writes (`ORY_PROJECT_URL`,
+   `ORY_USER_LOGIN=1`, `ORY_OAUTH2_CLIENT_ID`, optional
+   `ORY_AGENT_TRACE_FILE` for an NDJSON span log).
+3. Start your agent. Confirm the browser opens for PKCE login.
+4. Invoke a gated tool and `tail -f $ORY_AGENT_TRACE_FILE | jq .` — you
+   should see `user.auth` → `agent.auth` → `permission.check` →
+   `tool.complete` for every call.
+5. Promote to enforce once the `use` tuples are seeded: either
+   `ORY_PERMISSION_MODE=enforce` for one launch, or use one of the harness
+   CLIs to flip it persistently (e.g. `npx -y -p @ory/claude-code ory-claude
+   permissions enforce` — same shared config file).
+6. {{REF_LOCAL_DOWN}} when done. Volumes persist, so the seeded user
+   survives across runs.
+
+For full env-var coverage (including the user/agent split,
+`ORY_USER_SUBJECT_NAMESPACE`, agent DCR knobs), see {{REF_AUTH_SETUP}}.
+
+## What this skill does NOT do
+
+- It does not generate the agent. The user owns the agent loop, tool
+  catalog, and deployment shape. This skill only drops `@ory/argus` into
+  whatever they already have.
+- It does not write the permission tuples. Seed them with
+  `... permissions bootstrap` (run via any of the harness CLIs — same shared
+  config file) or by calling `client.createRelationship` directly.
+- It does not adapt one of the existing harness plugins (`@ory/claude-code`,
+  `@ory/codex`, `@ory/gemini-cli`, `@ory/openclaw`, `@ory/opencode`). Those
+  are for users running those harnesses — not building a custom agent.
+- It does not invent SDK-internal types. The snippets are the canonical
+  shape, but SDK hook signatures drift release-to-release — verify against
+  the user's pinned version before pasting.

package/assets/skills/ory-e2b-sandbox/SKILL.md

@@ -66,7 +66,7 @@ export const template = Template()
   // Sandbox runtime defaults. Per-tenant secrets (project URL, tokens, client
   // IDs) MUST be passed at Sandbox.create() time, never baked into the image.
   .setEnvs({
-    ORY_AUTH_GATE: "1",
+    ORY_USER_LOGIN: "1",
     ORY_PERMISSION_MODE: "observe",
     ORY_PERMISSION_NAMESPACE: "AgentTools",
     ORY_AGENT_DEBUG: "true",
@@ -198,7 +198,7 @@ await sbx.commands.run("{{BIN}} --version");  // sanity check
 ```
 
 Sandboxes are headless, so the user **must** pre-supply
-`ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN` — otherwise the auth gate's
+`ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN` — otherwise user login's
 PKCE browser flow has no target and hangs. See {{REF_AUTH_SETUP}} for the full
 env-var matrix.
 

package/assets/skills/permissions-onboarding/SKILL.md

@@ -92,9 +92,9 @@ out-of-band as they come into scope.
 Two common failure modes:
 
 1. **No user identity cached.** Bootstrap needs to know which subject
-   to grant tuples to. If the auth gate has never run (no PKCE login,
+   to grant tuples to. If user login has never run (no PKCE login,
    no `ORY_USER_SUBJECT_ID`), the command refuses. Run the harness once
-   with `ORY_AUTH_GATE=1` to cache a user token, or set
+   with `ORY_USER_LOGIN=1` to cache a user token, or set
    `ORY_USER_SUBJECT_ID=<id>` to target a known subject.
 2. **Credentials lack write scope on the permission namespace.** The
    command prints the full tuple list so you can apply them manually

package/dist/agent-auth.js

@@ -290,7 +290,7 @@ async function resolveAgentCredentials(options = {}) {
     }
     return {
         kind: "none",
-        reason: "No agent credentials configured. Run with a user session (ORY_AUTH_GATE=1) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
+        reason: "No agent credentials configured. Run with a user session (ORY_USER_LOGIN=1) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
         warnings,
     };
 }

package/dist/cli.js

@@ -146,7 +146,7 @@ function printEnvironment() {
     console.log("");
     console.log("Environment:");
     const vars = [
-        ["ORY_AUTH_GATE", process.env.ORY_AUTH_GATE, false],
+        ["ORY_USER_LOGIN", process.env.ORY_USER_LOGIN, false],
         [
             "ORY_AGENT_API_KEY",
             process.env.ORY_AGENT_API_KEY ? "(set)" : undefined,

package/dist/dev.js

@@ -403,9 +403,9 @@ function buildLocalOryEnv(gatewayUrl, seed) {
     return {
         ORY_PROJECT_URL: gatewayUrl,
         ORY_PERMISSION_NAMESPACE: seed.permissions.namespace,
-        // User gate — always on in local dev so the launcher demonstrates
+        // User login — always on in local dev so the launcher demonstrates
         // the interactive PKCE login UX end-to-end every session.
-        ORY_AUTH_GATE: "1",
+        ORY_USER_LOGIN: "1",
         // Agent identity — the harness self-registers via DCR on first run
         // using the user's bearer as the initial access token. No static
         // client_credentials are seeded; explicitly clear them so a leaking

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { Tracer, ActiveSpan, deriveTraceId, formatSpan, watchTraceFile, type Tra
 export { loadConfig, saveConfig, resolveConfig, mutateConfig, getConfigPath, getDataDir, getHarnessDataDir, type OryPluginConfig, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, type PermissionMode, } from "./config.js";
 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 AuthGateDecision, type AuthGateMode, type AuthGateOptions, } from "./auth-gate.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 { 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";

package/dist/index.js

@@ -42,9 +42,9 @@ Object.defineProperty(exports, "clearPkceFlightLock", { enumerable: true, get: f
 Object.defineProperty(exports, "waitForPeerTokens", { enumerable: true, get: function () { return auth_store_js_1.waitForPeerTokens; } });
 Object.defineProperty(exports, "waitForPeerTokensSync", { enumerable: true, get: function () { return auth_store_js_1.waitForPeerTokensSync; } });
 Object.defineProperty(exports, "TOKEN_EXPIRY_SKEW_SEC", { enumerable: true, get: function () { return auth_store_js_1.TOKEN_EXPIRY_SKEW_SEC; } });
-var auth_gate_js_1 = require("./auth-gate.js");
-Object.defineProperty(exports, "ensureUserAuthenticated", { enumerable: true, get: function () { return auth_gate_js_1.ensureUserAuthenticated; } });
-Object.defineProperty(exports, "ensureAuthenticated", { enumerable: true, get: function () { return auth_gate_js_1.ensureAuthenticated; } });
+var user_login_js_1 = require("./user-login.js");
+Object.defineProperty(exports, "ensureUserAuthenticated", { enumerable: true, get: function () { return user_login_js_1.ensureUserAuthenticated; } });
+Object.defineProperty(exports, "ensureAuthenticated", { enumerable: true, get: function () { return user_login_js_1.ensureAuthenticated; } });
 var agent_auth_js_1 = require("./agent-auth.js");
 Object.defineProperty(exports, "resolveAgentCredentials", { enumerable: true, get: function () { return agent_auth_js_1.resolveAgentCredentials; } });
 Object.defineProperty(exports, "ensureAgentIdentity", { enumerable: true, get: function () { return agent_auth_js_1.ensureAgentIdentity; } });

package/dist/local/manager.js

@@ -647,7 +647,7 @@ function printSeedResult(result) {
     console.log("To use with any Ory agent plugin, set these environment variables:");
     console.log("");
     console.log(`  export ORY_PROJECT_URL=${configs_js_1.GATEWAY_URL}`);
-    console.log(`  export ORY_AUTH_GATE=1`);
+    console.log(`  export ORY_USER_LOGIN=1`);
     console.log(`  export ORY_OAUTH2_CLIENT_ID=${result.user.client.clientId}`);
     console.log(`  export ORY_USER_SUBJECT_NAMESPACE=User`);
     console.log(`  export ORY_USER_SUBJECT_ID=${result.user.identity.id}`);

package/dist/permissions-cli.js

@@ -40,7 +40,7 @@ function resolveNamespace() {
  * Apply persisted user OAuth2 tokens (if any) to the client's user
  * principal so downstream subject resolution and tuple writes see a
  * concrete identity. Mirrors what `ensureUserAuthenticated` does on a
- * cache hit — but works whether or not `ORY_AUTH_GATE` is enabled.
+ * cache hit — but works whether or not `ORY_USER_LOGIN` is enabled.
  */
 function attachCachedUserPrincipal(client) {
     const tokens = (0, auth_store_js_1.loadTokens)();
@@ -151,7 +151,7 @@ async function runPermissionsStatus(binName, harness) {
     const subjectId = (0, subject_js_1.subjectLabel)(subject);
     if (subjectId === "agent:unknown") {
         console.log("No user identity resolved.");
-        console.log("Run the harness once (so the auth gate caches a token) or set");
+        console.log("Run the harness once (so user login caches a token) or set");
         console.log("ORY_USER_SUBJECT_ID to probe against a known subject.");
         return 0;
     }
@@ -235,7 +235,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
         console.error("No user identity resolved — refusing to write permissions for an unknown subject.");
         console.error("");
         console.error("Either:");
-        console.error("  - run the harness once with ORY_AUTH_GATE=1 so a user token is cached, or");
+        console.error("  - run the harness once with ORY_USER_LOGIN=1 so a user token is cached, or");
         console.error("  - set ORY_USER_SUBJECT_ID=<id> to target a known subject.");
         return 1;
     }

package/dist/setup.js

@@ -374,7 +374,7 @@ Environment variables:
   ORY_PROJECT_URL       Your Ory project URL (required at runtime)
   ORY_AGENT_API_KEY     Agent API key / OAuth2 bearer (preferred name;
                         ORY_API_KEY is honored as a deprecated alias)
-  ORY_AUTH_GATE         Set to "1" to enable the interactive user login gate
+  ORY_USER_LOGIN        Set to "1" to enable the interactive user login
   ORY_PERMISSION_MODE   "observe" (default) or "enforce" — what to do on deny
   ORY_AGENT_DEBUG       Set to "true" for debug logging
   ORY_AGENT_LOG_FILE    Path to write debug logs
@@ -391,8 +391,8 @@ function printNextSteps(harnessName, uninstallCmd) {
     console.log("     export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
     console.log("     export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
-    console.log("  2. Turn on the interactive user login gate (opt-in):");
-    console.log("     export ORY_AUTH_GATE=1");
+    console.log("  2. Turn on the interactive user login (opt-in):");
+    console.log("     export ORY_USER_LOGIN=1");
     console.log(`     Without this, ${harnessName} runs without a human Ory identity attached`);
     console.log("     to the session and permission checks fall back to a session:<id> subject.");
     console.log("");

package/dist/skills.d.ts

@@ -3,7 +3,7 @@
  *
  * The skill playbooks (auth-setup, login-flow, social-login, local-dev,
  * permissions-onboarding, contribute-integration, build-integration,
- * e2b-sandbox) and the local-stack commands (local-up, local-down) live once,
+ * e2b-sandbox, build-agent) and the local-stack commands (local-up, local-down) live once,
  * as token-bearing templates under `packages/core/assets/`. Every harness plugin renders them
  * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
  * harness's CLI binary, package name, and the way it references sibling skills

package/dist/skills.js

@@ -4,7 +4,7 @@
  *
  * The skill playbooks (auth-setup, login-flow, social-login, local-dev,
  * permissions-onboarding, contribute-integration, build-integration,
- * e2b-sandbox) and the local-stack commands (local-up, local-down) live once,
+ * e2b-sandbox, build-agent) and the local-stack commands (local-up, local-down) live once,
  * as token-bearing templates under `packages/core/assets/`. Every harness plugin renders them
  * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
  * harness's CLI binary, package name, and the way it references sibling skills
@@ -86,6 +86,11 @@ const SKILL_SOURCES = [
         name: "ory-e2b-sandbox",
         file: "skills/ory-e2b-sandbox/SKILL.md",
     },
+    {
+        id: "build-agent",
+        name: "ory-build-agent",
+        file: "skills/ory-build-agent/SKILL.md",
+    },
 ];
 const COMMAND_SOURCES = [
     {

package/dist/status-cli.d.ts

@@ -1,5 +1,5 @@
 /**
- * Render the "User identity" block. Shows the `ORY_AUTH_GATE` state and,
+ * Render the "User identity" block. Shows the `ORY_USER_LOGIN` state and,
  * when a PKCE token is cached, the resolved subject and expiry.
  */
 export declare function printUserIdentitySection(): void;

package/dist/status-cli.js

@@ -24,10 +24,10 @@ const cli_js_1 = require("./cli.js");
 function resolveNamespace() {
     return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
 }
-const AUTH_GATE_ENABLED = new Set(["1", "true", "yes", "on"]);
-function isAuthGateOn() {
-    const v = process.env.ORY_AUTH_GATE?.toLowerCase();
-    return !!v && AUTH_GATE_ENABLED.has(v);
+const USER_LOGIN_ENABLED = new Set(["1", "true", "yes", "on"]);
+function isUserLoginEnabled() {
+    const v = process.env.ORY_USER_LOGIN?.toLowerCase();
+    return !!v && USER_LOGIN_ENABLED.has(v);
 }
 /**
  * Format a relative duration like "4h 32m" or "12s" for a future deadline.
@@ -49,22 +49,22 @@ function formatExpiresIn(expiresAtSec, nowMs = Date.now()) {
     return `${remaining}s`;
 }
 /**
- * Render the "User identity" block. Shows the `ORY_AUTH_GATE` state and,
+ * Render the "User identity" block. Shows the `ORY_USER_LOGIN` state and,
  * when a PKCE token is cached, the resolved subject and expiry.
  */
 function printUserIdentitySection() {
-    const gateOn = isAuthGateOn();
+    const loginOn = isUserLoginEnabled();
     const tokens = (0, auth_store_js_1.loadTokens)();
     console.log("");
     console.log("User identity (interactive PKCE login):");
-    console.log(`  Gate:        ${gateOn ? "on (ORY_AUTH_GATE)" : "off (set ORY_AUTH_GATE=1 to enable)"}`);
+    console.log(`  Login:       ${loginOn ? "on (ORY_USER_LOGIN)" : "off (set ORY_USER_LOGIN=1 to enable)"}`);
     if (!tokens) {
         console.log("  Token cache: empty");
-        if (gateOn) {
+        if (loginOn) {
             console.log("  Subject:     (will resolve at next session start)");
         }
         else {
-            console.log("  Subject:     (gate disabled — no PKCE login will run)");
+            console.log("  Subject:     (login disabled — no PKCE flow will run)");
         }
         return;
     }
@@ -209,7 +209,7 @@ async function printPermissionsSection(binName, harness) {
     }
     const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
     if (!hasUser) {
-        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_AUTH_GATE=1 once,`);
+        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=1 once,`);
         console.log(`               or set ORY_USER_SUBJECT_ID to probe a known subject)`);
         return;
     }

package/dist/subject.d.ts

@@ -27,8 +27,8 @@ export type UserSubjectRef = {
     };
 };
 /**
- * Resolve the user subject for permission checks. Prefers the auth-gate's
- * `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
+ * Resolve the user subject for permission checks. Prefers the user
+ * login's `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
  * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
  *

package/dist/subject.js

@@ -21,8 +21,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveUserSubject = resolveUserSubject;
 exports.subjectLabel = subjectLabel;
 /**
- * Resolve the user subject for permission checks. Prefers the auth-gate's
- * `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
+ * Resolve the user subject for permission checks. Prefers the user
+ * login's `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
  * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
  *

package/dist/{auth-gate.d.ts → user-login.d.ts}

@@ -1,5 +1,5 @@
 /**
- * User authentication gate. Orchestrates the "first interaction must
+ * User login. Orchestrates the "first interaction must
  * authenticate the human user" requirement across all plugins:
  *
  *   1. Resolve config (env + ~/.config/ory-agent-plugins/config.json).
@@ -17,20 +17,20 @@
  * Every terminal path emits exactly one `user.auth` trace span so that
  * the audit trail is complete regardless of outcome.
  *
- * The whole gate is a no-op (mode `disabled`) unless the
- * `ORY_AUTH_GATE` env var is set to `1`/`true` — phased rollout.
+ * The whole flow is a no-op (mode `disabled`) unless the
+ * `ORY_USER_LOGIN` env var is set to `1`/`true`.
  *
- * This gate authenticates the *user* (the human at the keyboard). The
+ * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved
  * non-interactively via env-configured machine credentials and is not
- * handled here — see `ensureAgentIdentity` (forthcoming).
+ * handled here — see `ensureAgentIdentity`.
  */
 import { OryAgentClient } from "./client.js";
 import { type OryOAuth2Tokens } from "./config.js";
 import { promptForProjectUrl } from "./cli.js";
 import { pkceLogin } from "./auth.js";
-export type AuthGateMode = "disabled" | "audit_only" | "env_token" | "ok" | "refreshed" | "skipped" | "declined" | "error";
-export interface AuthGateOptions {
+export type UserLoginMode = "disabled" | "audit_only" | "env_token" | "ok" | "refreshed" | "skipped" | "declined" | "error";
+export interface UserLoginOptions {
     /** Bin name used in user-facing prompts (e.g. "ory-claude"). */
     binName: string;
     /** Logical harness name (used by the tracer). */
@@ -47,11 +47,11 @@ export interface AuthGateOptions {
     /** Override the prompt-for-URL step (for tests). */
     promptForProjectUrlFn?: typeof promptForProjectUrl;
 }
-export interface AuthGateDecision {
+export interface UserLoginDecision {
     /** Whether the caller should let the session proceed. */
     proceed: boolean;
     /** Stable mode identifier for telemetry and tests. */
-    mode: AuthGateMode;
+    mode: UserLoginMode;
     /** Human-readable reason; safe to surface to the operator. */
     reason: string;
     /** Subject (sub claim) when authenticated. */
@@ -61,7 +61,7 @@ export interface AuthGateDecision {
  * The entry point that every plugin's session-start handler should call
  * to authenticate the human user. Always returns a decision; never throws.
  */
-export declare function ensureUserAuthenticated(client: OryAgentClient, options: AuthGateOptions): Promise<AuthGateDecision>;
+export declare function ensureUserAuthenticated(client: OryAgentClient, options: UserLoginOptions): Promise<UserLoginDecision>;
 /** Re-export so callers don't need to import auth.ts directly. */
 export type { OryOAuth2Tokens };
 /**

package/dist/{auth-gate.js → user-login.js}

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * User authentication gate. Orchestrates the "first interaction must
+ * User login. Orchestrates the "first interaction must
  * authenticate the human user" requirement across all plugins:
  *
  *   1. Resolve config (env + ~/.config/ory-agent-plugins/config.json).
@@ -18,13 +18,13 @@
  * Every terminal path emits exactly one `user.auth` trace span so that
  * the audit trail is complete regardless of outcome.
  *
- * The whole gate is a no-op (mode `disabled`) unless the
- * `ORY_AUTH_GATE` env var is set to `1`/`true` — phased rollout.
+ * The whole flow is a no-op (mode `disabled`) unless the
+ * `ORY_USER_LOGIN` env var is set to `1`/`true`.
  *
- * This gate authenticates the *user* (the human at the keyboard). The
+ * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved
  * non-interactively via env-configured machine credentials and is not
- * handled here — see `ensureAgentIdentity` (forthcoming).
+ * handled here — see `ensureAgentIdentity`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureAuthenticated = void 0;
@@ -34,8 +34,8 @@ const cli_js_1 = require("./cli.js");
 const auth_store_js_1 = require("./auth-store.js");
 const auth_js_1 = require("./auth.js");
 const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
-function isGateEnabled() {
-    const v = process.env.ORY_AUTH_GATE?.toLowerCase();
+function isUserLoginEnabled() {
+    const v = process.env.ORY_USER_LOGIN?.toLowerCase();
     return !!v && ENABLED_VALUES.has(v);
 }
 function clientId() {
@@ -63,17 +63,17 @@ function recordAuthSpan(client, decision) {
  * to authenticate the human user. Always returns a decision; never throws.
  */
 async function ensureUserAuthenticated(client, options) {
-    if (!isGateEnabled()) {
+    if (!isUserLoginEnabled()) {
         const decision = {
             proceed: true,
             mode: "disabled",
-            reason: "ORY_AUTH_GATE is not enabled",
+            reason: "ORY_USER_LOGIN is not enabled",
         };
         recordAuthSpan(client, decision);
         return decision;
     }
     try {
-        const decision = await runGate(client, options);
+        const decision = await runUserLogin(client, options);
         attachUserPrincipal(client, decision);
         recordAuthSpan(client, decision);
         return decision;
@@ -123,7 +123,7 @@ function attachUserPrincipal(client, decision) {
         });
     }
 }
-async function runGate(client, options) {
+async function runUserLogin(client, options) {
     const ttyCheck = options.isTtyAvailableFn ?? cli_js_1.isTtyAvailable;
     const tty = ttyCheck();
     let resolved = (0, config_js_1.resolveConfig)();
@@ -131,7 +131,7 @@ async function runGate(client, options) {
         return {
             proceed: true,
             mode: "audit_only",
-            reason: "Configured for audit-only mode; auth gate is a no-op",
+            reason: "Configured for audit-only mode; user login is a no-op",
         };
     }
     // 1. Project URL.
@@ -220,8 +220,8 @@ async function runGate(client, options) {
     // `-t`, `docker exec` without `-it`, IDE-integrated terminals) can still
     // complete sign-in by pasting the URL into any browser that can reach
     // 127.0.0.1. Truly unattended runs (CI=true) are short-circuited by
-    // `pkceLogin` itself via `detectHeadless`, and operators can bypass the
-    // gate entirely with `ORY_USER_SESSION_TOKEN` or `ORY_AUTH_GATE=0`.
+    // `pkceLogin` itself via `detectHeadless`, and operators can bypass
+    // login entirely with `ORY_USER_SESSION_TOKEN` or `ORY_USER_LOGIN=0`.
     // PKCE-flight lock so concurrent processes share a single browser flow.
     const lock = (0, auth_store_js_1.tryAcquirePkceFlightLock)();
     if (!lock) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "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",