@ory/argus 0.7.0 → 0.7.2

package/assets/commands/temporal-up.md

@@ -0,0 +1,43 @@
+# Start Local Temporal Dev Server
+
+Start a local [Temporal](https://temporal.io) development server alongside the
+local Ory stack so the worker scaffolded by `ory-temporal-worker` can connect.
+This runs Temporal's bundled dev server (Temporal Server + Postgres + Web UI in
+one process) — not a production cluster.
+
+Prerequisite: the [Temporal CLI](https://docs.temporal.io/cli) is installed and
+`temporal` is on `PATH`. On macOS: `brew install temporal`. On Linux/Windows:
+download from <https://temporal.download>.
+
+Run:
+
+```bash
+temporal server start-dev
+```
+
+This will:
+
+1. Start the Temporal Server on `localhost:7233` (the gRPC endpoint workers and
+   clients connect to)
+2. Expose the Web UI on <http://localhost:8233>
+3. Persist state under `~/.config/temporalio/` so workflows survive a restart
+
+The process runs in the foreground. Stop it with `Ctrl+C`; data is preserved.
+For a clean reset, delete `~/.config/temporalio/` and start again.
+
+For the matching Ory side of the stack (Identities, Permissions, OAuth2, login
+UI, Jaeger), use {{REF_LOCAL_UP}}. The two stacks are independent — Temporal
+runs on `:7233/:8233`, Ory runs on `:4000` and friends — so they can run side
+by side without port conflicts.
+
+Once both are up, point the worker at them:
+
+```bash
+export ORY_PROJECT_URL=http://localhost:4000
+export ORY_AUTH_GATE=1
+cd temporal-worker
+npm run start
+```
+
+See the `ory-temporal-worker` skill for the full worker scaffold and the
+permission-gate wiring.

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-temporal-worker/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: ory-temporal-worker
+description: Scaffold a [Temporal](https://temporal.io) TypeScript worker where every Activity execution is gated by Ory — the user is authenticated, the worker's agent identity is resolved via DCR, each Activity invocation runs an Ory Permission check, and the full lifecycle emits trace spans. Use when the user asks to "add Ory to my Temporal worker", "wire Ory permissions into Temporal activities", "create a Temporal worker with Ory auth", "build a Temporal TypeScript project with the Ory agent client", or any close variant. The skill scaffolds the project in the user's repo following <https://docs.temporal.io/develop/typescript/set-up-your-local-typescript> — it does not run the worker.
+---
+
+# Ory-authed Temporal TypeScript worker
+
+You are helping the user scaffold a [Temporal](https://temporal.io) TypeScript
+worker where every Activity execution is gated by Ory: the user is
+authenticated, the worker's agent identity is resolved via OAuth2 Dynamic Client
+Registration, each Activity invocation runs an Ory Permission check, and the
+full lifecycle emits trace spans. **Workflows stay deterministic** — only
+Activities call out to Ory.
+
+This skill carries the workflow. You generate the files in the user's repo; the
+user runs the Temporal CLI and the worker.
+
+> **Precondition:** Node.js 20+ is installed, and the user has installed (or
+> will install) the [Temporal CLI](https://docs.temporal.io/cli). On macOS:
+> `brew install temporal`. On Linux/Windows: download from
+> <https://temporal.download> and put `temporal` on `PATH`. If the binary is
+> missing, point the user at the docs and stop — do not fabricate it.
+
+## Step 1 — Confirm the target
+
+Before writing files, confirm with the user:
+
+1. **Where the worker should live.** Default to `temporal-worker/` at the repo
+   root unless the user says otherwise.
+2. **Task queue name.** Default `agent-tools`. The worker and the workflow
+   starter must agree on this string.
+3. **Ory project URL.** For local development point at the local Ory stack
+   ({{REF_LOCAL_UP}}) on `http://localhost:4000`. For Ory Network, the user
+   plumbs their project URL through the worker's env. Either way the worker
+   needs network reachability to the Ory APIs at runtime.
+
+## Step 2 — Scaffold the Temporal project
+
+Run the official Temporal scaffold and select the `hello-world` sample when
+prompted. Then add the Ory agent client:
+
+```bash
+npx @temporalio/create@latest temporal-worker
+cd temporal-worker
+npm install @ory/argus
+```
+
+The scaffold lays down `src/{activities.ts, workflows.ts, worker.ts, client.ts}`
+and pre-configures the Worker to connect to the Temporal dev server at
+`localhost:7233`. The Web UI lives at <http://localhost:8233> once the dev
+server is running.
+
+## Step 3 — Wrap Activities with the Ory gate
+
+Activities are where side effects happen, so they are the right place to put
+the permission check. **Never call Ory from inside a Workflow** — Workflows are
+deterministic and replayed; a live Ory call would break replay safety.
+
+Replace the scaffold's `src/activities.ts` with:
+
+```ts
+import { Context } from "@temporalio/activity";
+import {
+  OryAgentClient,
+  ensureUserAuthenticated,
+  ensureAgentIdentity,
+  checkAndDecide,
+  resolveUserSubject,
+  subjectLabel,
+} from "@ory/argus";
+
+// One client per worker process. `harness` is a label that shows up on
+// every trace span so worker-originated audit lives in its own namespace
+// alongside the CLI plugins.
+const ory = OryAgentClient.fromEnv("temporal");
+
+// Run the user + agent gates exactly once per process. Activities call
+// `bootstrap()` lazily and await the same promise on subsequent calls.
+let bootstrapped: Promise<void> | undefined;
+function bootstrap(): Promise<void> {
+  if (!bootstrapped) {
+    bootstrapped = (async () => {
+      await ensureUserAuthenticated(ory, {
+        binName: "temporal-worker",
+        harness: "temporal",
+        // Temporal's Activity entry point has no channel to carry a
+        // session-start block, so the user gate runs in advisory mode:
+        // it still refreshes tokens and emits the audit span, but the
+        // worker proceeds even if the user is unauthenticated. Hard
+        // enforcement happens at the per-Activity permission check.
+        allowBlock: false,
+      });
+      await ensureAgentIdentity(ory, {
+        projectUrl: process.env.ORY_PROJECT_URL,
+      });
+    })();
+  }
+  return bootstrapped;
+}
+
+async function gate(toolName: string, userSubject: string): Promise<void> {
+  await bootstrap();
+  const subject = resolveUserSubject(ory, userSubject);
+  const decision = await checkAndDecide(
+    ory,
+    {
+      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
+      object: toolName,
+      relation: "use",
+      ...subject,
+    },
+    {
+      spanAttributes: {
+        toolName,
+        workflowId: Context.current().info.workflowExecution.workflowId,
+        activityId: Context.current().info.activityId,
+      },
+    }
+  );
+
+  switch (decision.kind) {
+    case "allow":
+    case "observe":
+    case "fail_open":
+      return;
+    case "deny":
+      throw new Error(
+        `Ory denied use of ${toolName} for ${subjectLabel(subject)}`
+      );
+  }
+}
+
+export async function sendEmail(input: {
+  user: string;
+  to: string;
+  subject: string;
+}): Promise<string> {
+  await gate("send_email", input.user);
+  // …real side effect here…
+  return `sent to ${input.to}`;
+}
+```
+
+Key choices:
+
+- **Activities call Ory, Workflows don't.** Anything that needs a live decision
+  goes in an Activity. Workflows only orchestrate.
+- **`allowBlock: false`.** The Activity boundary can't carry a session-start
+  block, so the user gate runs in advisory mode. Enforcement is at the
+  permission check, which throws on deny — Temporal will mark the Activity as
+  failed and surface the error via the Workflow result or retry policy.
+- **`harness: "temporal"`.** Distinguishes worker-originated spans in the trace
+  file from CLI plugin spans.
+- **Span attributes carry the Workflow + Activity IDs.** This is how operators
+  correlate Ory denials back to Temporal executions in the Web UI.
+
+## Step 4 — Pass the user subject through the Workflow
+
+Workflows must be deterministic, so they cannot read `process.env` or call out
+to Ory. The user subject travels as Workflow input. Update `src/workflows.ts`:
+
+```ts
+import { proxyActivities } from "@temporalio/workflow";
+import type * as activities from "./activities";
+
+const { sendEmail } = proxyActivities<typeof activities>({
+  startToCloseTimeout: "1 minute",
+});
+
+export async function notifyUser(input: {
+  user: string;
+  to: string;
+}): Promise<string> {
+  return sendEmail({
+    user: input.user,
+    to: input.to,
+    subject: "hello",
+  });
+}
+```
+
+And `src/client.ts`:
+
+```ts
+import { Connection, Client } from "@temporalio/client";
+import { nanoid } from "nanoid";
+import { notifyUser } from "./workflows";
+
+const client = new Client({ connection: await Connection.connect() });
+const handle = await client.workflow.start(notifyUser, {
+  taskQueue: "agent-tools",
+  workflowId: `notify-${nanoid()}`,
+  args: [{ user: "user@example.com", to: "alice@example.com" }],
+});
+console.log("workflow started:", handle.workflowId);
+console.log("result:", await handle.result());
+```
+
+`src/worker.ts` stays as the scaffold writes it — `Worker.create` already
+registers Workflows and Activities together and listens on the task queue.
+
+## Step 5 — Run it
+
+Three terminals. See {{REF_LOCAL_UP}} for the Ory side; the Temporal side uses
+the Temporal CLI's bundled dev server (Postgres + Temporal Server + Web UI in
+one process):
+
+```bash
+# Terminal 1 — local Ory stack (Kratos, Keto, Hydra, gateway)
+{{REF_LOCAL_UP}}
+
+# Terminal 2 — local Temporal dev server (Web UI at http://localhost:8233)
+temporal server start-dev
+
+# Terminal 3 — the worker, pointed at both
+cd temporal-worker
+export ORY_PROJECT_URL=http://localhost:4000
+export ORY_AUTH_GATE=1
+export ORY_AGENT_DEBUG=true
+export ORY_AGENT_TRACE_FILE=$PWD/ory-trace.ndjson
+npm run start                 # boots the worker, polls task queue
+```
+
+In a fourth terminal, kick the workflow once:
+
+```bash
+cd temporal-worker
+npm run workflow
+```
+
+Tail the trace file to confirm the gates fired:
+
+```bash
+tail -f ory-trace.ndjson | jq .
+```
+
+You should see:
+
+- exactly one `user.auth` span (the worker's first Activity triggered
+  `bootstrap()`),
+- exactly one `agent.auth` span,
+- one `tool.invoke` (allow) or `tool.block` (deny) span **per Activity
+  execution**.
+
+The Workflow itself produces no Ory spans — only its Activities do.
+
+## Step 6 — Promotion from observe to enforce
+
+The worker starts in `observe` mode by default: denies pass through but each is
+recorded as a `permission.observe_deny` audit span. Once the user has confirmed
+the deny set is what they expect, promote to enforcement:
+
+```bash
+export ORY_PERMISSION_MODE=enforce
+```
+
+On a fresh Ory project, run the permissions bootstrap once before flipping the
+switch so the `use` tuples for each Activity name (`send_email`, …) exist —
+see {{REF_PERMISSIONS_ONBOARDING}}.
+
+To exercise the deny path locally, write a tuple that explicitly removes `use`
+for the test user against one Activity object, kick the Workflow, and watch the
+Activity fail with the `Ory denied use of …` error in the Temporal Web UI.
+
+## Step 7 — Beyond the dev server
+
+This skill stops at the local dev server. For production:
+
+- Pin a static agent identity with `ORY_AGENT_API_KEY` (single key) or
+  `ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET` (client_credentials) so the
+  worker doesn't re-register on every cold start.
+- Persist the worker's `ory-trace.ndjson` somewhere durable, or replace the
+  file tracer with an OpenTelemetry exporter wired up around `ory.tracer`.
+- Use Temporal Cloud or a self-hosted Temporal cluster instead of
+  `temporal server start-dev`; the worker code does not change.
+
+## What this skill does NOT do
+
+- It does not modify the user's Ory project — use {{REF_AUTH_SETUP}} for that.
+- It does not call Ory from inside a Workflow. Workflows are deterministic and
+  must never make non-deterministic calls; all gating lives in Activities.
+- It does not deploy the worker. The user runs `temporal server start-dev` and
+  `npm run start` locally; production deployment is out of scope.
+- It does not pin Temporal or `@ory/argus` versions. For reproducibility, pin
+  both in the generated `package.json` before committing.

package/dist/skills.d.ts

@@ -3,8 +3,11 @@
  *
  * 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
+ * e2b-sandbox, temporal-worker) and the local-stack commands (local-up,
+ * local-down, temporal-up) 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
  * and commands. Plugins then write the rendered docs into whatever location

package/dist/skills.js

@@ -4,8 +4,11 @@
  *
  * 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
+ * e2b-sandbox, temporal-worker) and the local-stack commands (local-up,
+ * local-down, temporal-up) 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
  * and commands. Plugins then write the rendered docs into whatever location
@@ -86,6 +89,16 @@ 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",
+    },
+    {
+        id: "temporal-worker",
+        name: "ory-temporal-worker",
+        file: "skills/ory-temporal-worker/SKILL.md",
+    },
 ];
 const COMMAND_SOURCES = [
     {
@@ -102,6 +115,13 @@ const COMMAND_SOURCES = [
         description: "Stop the local Ory dev stack, preserving data volumes.",
         file: "commands/local-down.md",
     },
+    {
+        id: "temporal-up",
+        name: "ory-temporal-up",
+        slug: "temporal-up",
+        description: "Start the local Temporal TypeScript dev server (Temporal Server + Web UI) for the Ory-authed worker scaffold.",
+        file: "commands/temporal-up.md",
+    },
 ];
 /** Names of the skills materialized by the plugins (for uninstall cleanup). */
 exports.ORY_SKILL_NAMES = SKILL_SOURCES.map((s) => s.name);
@@ -128,21 +148,25 @@ function buildProfile(harness, opts) {
     const skillRef = (name) => harness === "claude-code" ? code(`/project:${name}`) : code(name);
     let localUp;
     let localDown;
+    let temporalUp;
     switch (harness) {
         case "claude-code":
             localUp = code("/ory-agent-plugin:local-up");
             localDown = code("/ory-agent-plugin:local-down");
+            temporalUp = code("/ory-agent-plugin:temporal-up");
             break;
         case "gemini-cli":
         case "opencode":
             localUp = code("/ory:local-up");
             localDown = code("/ory:local-down");
+            temporalUp = code("/ory:temporal-up");
             break;
         case "codex":
         case "openclaw":
         default:
             localUp = code("ory-local-up");
             localDown = code("ory-local-down");
+            temporalUp = code("ory-temporal-up");
             break;
     }
     return {
@@ -156,8 +180,11 @@ function buildProfile(harness, opts) {
             "{{REF_LOGIN_FLOW}}": skillRef("ory-login-flow"),
             "{{REF_SOCIAL_LOGIN}}": skillRef("ory-social-login"),
             "{{REF_LOCAL_DEV}}": skillRef("ory-local-dev"),
+            "{{REF_PERMISSIONS_ONBOARDING}}": skillRef("ory-permissions-onboarding"),
+            "{{REF_TEMPORAL_WORKER}}": skillRef("ory-temporal-worker"),
             "{{REF_LOCAL_UP}}": localUp,
             "{{REF_LOCAL_DOWN}}": localDown,
+            "{{REF_TEMPORAL_UP}}": temporalUp,
         },
     };
 }

package/package.json

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