@ory/argus 0.14.0 → 1.0.0

package/assets/skills/ory-temporal-worker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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 structured activity events. 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
@@ -9,7 +9,7 @@ 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
+full lifecycle emits structured activity events. **Workflows stay deterministic** — only
 Activities call out to Ory.
 
 This skill carries the workflow. You generate the files in the user's repo; the
@@ -70,7 +70,7 @@ import {
 } 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
+// every activity event so worker-originated audit lives in its own namespace
 // alongside the CLI plugins.
 const ory = OryAgentClient.fromEnv("temporal");
 
@@ -84,7 +84,7 @@ function bootstrap(): Promise<void> {
         binName: "temporal-worker",
         harness: "temporal",
         // The user gate runs every invocation and never blocks: it refreshes
-        // tokens and emits the audit span, but the worker proceeds even if the
+        // tokens and emits the audit event, but the worker proceeds even if the
         // user is unauthenticated. Enforcement happens at the per-Activity
         // permission check (permissionMode).
       });
@@ -102,13 +102,13 @@ async function gate(toolName: string, userSubject: string): Promise<void> {
   const decision = await checkAndDecide(
     ory,
     {
-      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
+      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTool",
       object: toolName,
       relation: "use",
       ...subject,
     },
     {
-      spanAttributes: {
+      activityAttributes: {
         toolName,
         workflowId: Context.current().info.workflowExecution.workflowId,
         activityId: Context.current().info.activityId,
@@ -147,9 +147,9 @@ Key choices:
   identity, but always proceeds. 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
+- **`harness: "temporal"`.** Distinguishes worker-originated events in the
+  unified activity log.
+- **Activity 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
@@ -215,7 +215,7 @@ 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
+export ORY_AGENT_LOG_FILE=$PWD/ory-agent-debug.log
 npm run start                 # boots the worker, polls task queue
 ```
 
@@ -226,49 +226,47 @@ cd temporal-worker
 npm run workflow
 ```
 
-Tail the trace file to confirm the gates fired:
+Tail the activity log to confirm the gates fired:
 
 ```bash
-tail -f ory-trace.ndjson | jq .
+tail -f ory-agent-debug.log | jq .
 ```
 
 You should see:
 
-- exactly one `user.auth` span (the worker's first Activity triggered
+- exactly one `user.auth` activity event (the worker's first Activity triggered
   `bootstrap()`),
-- exactly one `agent.auth` span,
-- one `tool.invoke` (allow) or `tool.block` (deny) span **per Activity
+- exactly one `agent.auth` activity event,
+- one `tool.invoke` (allow) or `tool.block` (deny) event **per Activity
   execution**.
 
-The Workflow itself produces no Ory spans — only its Activities do.
+The Workflow itself produces no Ory activity — 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:
+recorded as a `permission.observe_deny` activity event. Once the user has confirmed
+the deny set is what they expect, an admin promotes the posture to `enforce` in
+the Ory Console (Agent Security). It is a permission on the project, read on
+every session, so the worker picks it up on its next run with no redeploy.
 
-```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}}.
+On a hosted Ory project, grant `use` on each Activity name (`send_email`, …) in
+the Ory Console (Agent Security) before promoting the posture there — otherwise
+enforcement blocks every Activity. 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.
+To exercise the deny path locally, kick the Workflow with an Activity name the
+local stack never granted, and watch it 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`.
+- Pin a static agent identity with `ORY_AGENT_CLIENT_ID +
+  ORY_AGENT_CLIENT_SECRET` (client_credentials) so the worker doesn't
+  re-register on every cold start.
+- Set retention and access controls for the worker's unified activity log.
+  Ory Agent Security owns service telemetry; the worker does not export traces.
 - Use Temporal Cloud or a self-hosted Temporal cluster instead of
   `temporal server start-dev`; the worker code does not change.
 

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

@@ -1,32 +1,57 @@
 ---
 name: ory-permissions-onboarding
-description: Onboard a fresh install onto Ory Permissions for AI agent tool calls. Use when the user has just installed the Ory plugin and wants to enforce per-tool authorization without first getting blocked by missing tuples. Walks through observe-mode observation, idempotent tuple bootstrap, and promotion to enforce mode.
+description: Onboard a fresh install onto Ory Permissions for AI agent tool calls. Use when the user has just installed the Ory plugin and wants per-tool authorization enforced without first getting blocked by missing permissions. Covers connecting the plugin, reading coverage in observe mode, and what has to happen in the Ory Console (grants, blocks, enforce posture).
 ---
 
 # Onboard onto Ory Permissions for Agent Tool Calls
 
 You are helping a user move a freshly-installed Ory agent plugin from
-"permissions are running but never block" (the default after install)
-to "permissions are enforcing" (the production posture), without the
-common first-run failure mode of getting every tool call blocked
-because no tuples exist yet.
+"disconnected" to "permissions are enforcing", without the common
+first-run failure mode of getting every tool call blocked because the
+project has no grants yet.
+
+**The plugin only reads permissions. It never writes them.** Everything
+that provisions the project — the permission model, per-tool grants,
+explicit blocks, and the observe/enforce posture — is done in the **Ory
+Console** (Agent Security) by someone with access to the project. That
+split is deliberate: it means installing and connecting a plugin needs
+nothing but project connection details and a public OAuth2 client id, with no
+workspace privilege and no project API key.
+
+Two things govern behavior:
+
+- **Whether Agent Security is connected** — it runs when a project URL,
+  canonical Agent Security origin, and public OAuth2 client id resolve. Existing
+  configurations fall back to the project URL when the canonical origin is
+  unset. Not connected means no login and no permission checks, with
+  tool calls recorded locally. Skills, commands, the local dev stack, and
+  the MCP server work either way — they don't need a project at all.
+- **`permissionMode`** — `observe` or `enforce`, **read from the Ory
+  project** on every session, and only meaningful once connected.
+  `observe` (the default) runs every check, records denials, and lets the
+  tool proceed. `enforce` blocks on deny. There is no local override — an
+  admin sets it in the Console.
+
+The journey: **install → connect → observe → grant in the Console →
+enforce in the Console.**
+
+## Step 1: Connect the plugin to the project
+
+A fresh install has the developer-experience half working and Agent
+Security not connected. Copy the connection details shown in the Ory Console
+under **Agent Security**:
 
-The plugin ships with two orthogonal switches:
-
-- **`auditOnly`** — a kill switch. When set, Ory is *off entirely* (no
-  auth, no permission checks). This is for users who want only audit
-  logging of tool invocations. Not what onboarding is about.
-- **`permissionMode`** — the dial this skill is about. `observe` (the
-  default) runs every permission check, logs denials, but allows the
-  tool to proceed. `enforce` blocks on deny. Mode is read from
-  `ORY_PERMISSION_MODE` first, then the shared config file, then
-  defaults to `observe`.
-
-The journey: **install → observe → bootstrap → enforce.**
+```sh
+{{NPX}} configure --project-url <URL> --agent-security-url <URL>
+```
 
-## Step 1: Confirm the plugin is installed and configured
+- **project URL** — the project's SDK URL (`https://<slug>.projects.oryapis.com`).
+- **Agent Security URL** — the canonical broker origin (`https://agents.console.ory.com` in production).
+- **OAuth2 client id** — the project's public login client, provisioned
+  in the Console. The per-session user login needs it to complete its
+  PKCE browser flow.
 
-Verify the plugin is wired up and pointing at the right Ory project:
+Then confirm what the plugin resolved:
 
 ```sh
 {{NPX}} status
@@ -35,133 +60,135 @@ Verify the plugin is wired up and pointing at the right Ory project:
 What you want to see:
 
 - **Project URL**: a real Ory URL or your local dev gateway (not "NOT SET").
-- **API Key**: set (Ory Network) or unset (local Keto OSS — that's fine).
-- **Mode**: not "audit-only" — that would mean Ory is disabled.
-
-If any of those are wrong, fix them before continuing:
+- **OAuth2 Client**: the project's public login client (not "NOT SET").
+- **Agent Security**: connected. If it says "not connected", it names the
+  unresolved connection value.
 
-```sh
-{{NPX}} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]
-```
-
-`--oauth2-client-id` is the public OAuth2 client registered in your Ory project (needed for the per-session user login to complete its PKCE browser flow; see the *Register the user OAuth2 client* section of the plugin README).
+If the user doesn't have those values, they need them from whoever
+administers the project. Don't try to create the client from here — the
+plugin has no privilege to, by design.
 
 ## Step 2: Look at the current permission posture
 
 ```sh
-{{NPX}} permissions status
+{{NPX}} permissions
 ```
 
 This prints:
 
-- The current **permission mode** (`observe` or `enforce`) and where it
-  was resolved from (env / config / default).
-- The **subject** (the user identity tuples are checked against).
+- The live **permission mode** (`observe` or `enforce`) and whether it
+  came from the project, a cached value, or the default.
+- The **subject** — the user identity permissions are checked against.
 - For each tool in this harness's built-in catalog, **allowed / denied /
-  errored** based on a real `checkPermission` call against your Ory
-  project right now.
+  blocked / errored**, from a real check against the project right now.
+- A one-line coverage summary for decomposed shell command words.
 
-On a fresh install you will almost always see every tool reported as
-**denied** — because no tuples exist yet for the current user. That's
-expected, and in observe mode it is *not blocking anyone*. The tool
-calls are running through; you are simply seeing what *would* be
-blocked once enforce mode is turned on.
+On a freshly-connected project you will usually see every tool reported
+as **denied** — no grants exist for this user yet. In observe mode that
+blocks nobody: tool calls run through, and you are seeing what *would*
+be blocked under enforce.
 
-If the status command prints `Mode: enforce` but tuples are missing,
-stop here: tool calls *are* being blocked right now. Either bootstrap
-(next step) or run `{{NPX}} permissions observe` first to flip back to
-non-blocking.
+If status prints `Mode: enforce` while tools are denied, tool calls
+**are** being blocked right now. The fix is in the Console (grant the
+tools, or move the project back to observe) — not from the CLI.
 
-## Step 3: Bootstrap tuples for the harness's built-in tools
+## Step 3: Run a real session in observe mode
 
-Grant the current user `use` on every tool the harness ships with:
+Observe mode is the discovery phase. Use the harness normally, then look
+at what was recorded:
 
 ```sh
-{{NPX}} permissions bootstrap
+{{NPX}} status          # summary + recent activity
+{{NPX}} watch           # live event, decision, and error view
 ```
 
-This is **idempotent** — Keto returns 409 on a tuple that already
-exists, and the command treats that as success. Safe to re-run any time
-(e.g. after the harness adds a new tool to its catalog).
-
-The command writes `<namespace>:<tool>#use@<userSubject>` for each tool
-in the harness's known catalog. MCP server tools are *not* covered —
-they are discovered dynamically per session, so they need tuples added
-out-of-band as they come into scope.
-
-### When bootstrap can't write tuples
+Launch the harness with `ORY_AGENT_DEBUG=true` to include verbose diagnostics in
+the watched log and stderr. Denials appear as `permission.observe_deny` activity events (and
+`permission.block_observed` for an explicit block), with the tool name
+and the subject. That list is exactly what has to be granted before
+enforce is safe.
 
-Two common failure modes:
+## Step 4: Grant the tools in the Ory Console
 
-1. **No user identity cached.** Bootstrap needs to know which subject
-   to grant tuples to. If the user login has never completed (no PKCE login,
-   no `ORY_USER_SUBJECT_ID`), the command refuses. Run the harness once
-   (the user login runs every session) 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
-   via `keto relation-tuples create`, the Ory Console's *Add
-   relationship* dialog, or `curl` against Keto's write API. Hand the
-   list to whoever holds write credentials.
-
-### Add tuples for non-default tools
-
-If the harness has tools beyond the built-in catalog (MCP servers,
-custom commands), grant them by writing tuples directly. Use the same
-shape:
+In the Ory Console → **Agent Security**, grant the subject `use` on the
+tools it needs. The grant shape the runtime checks is:
 
 ```
-namespace: AgentTools           (or whatever ORY_PERMISSION_NAMESPACE is set to)
-object:    <tool name>
+namespace: AgentTool           (or whatever ORY_PERMISSION_NAMESPACE is set to)
+object:    <tool name>          (e.g. Read, Bash, WebFetch)
 relation:  use
-subject:   <user subject id>
+subject:   User:<id>            (a SubjectSet — namespace `User`, object the user id)
 ```
 
-Re-run `{{NPX}} permissions status` afterwards to confirm coverage.
+Notes worth passing on to the user:
 
-## Step 4: Promote to enforce mode
+- The subject is a **SubjectSet** (`User:<id>`), which is what the
+  Console's *Add relationship* dialog emits and exactly what the runtime
+  check uses. A bare subject id will not match.
+- Granting a **group** and putting users in it scales better than
+  per-user grants; the check follows subject-set expansion.
+- **Shell command words** are authorized separately in the `ShellTool`
+  namespace (`ShellTool:curl#use`, …) because a denied surface is
+  otherwise reachable through `bash -c "curl …"`.
+- **MCP server tools** are discovered dynamically per session, so they
+  are not in the built-in catalog and need granting as they come into
+  scope.
 
-Once `permissions status` shows the tools you actually use are
-`allowed`, flip the dial:
+Re-run `{{NPX}} permissions` afterwards to confirm coverage.
 
-```sh
-{{NPX}} permissions enforce
-```
+## Step 5: Promote to enforce in the Console
+
+Once the tools the user actually needs report `allowed`, an admin flips
+the posture in the Console (Agent Security). The mode is a permission on
+the project, so it can be set **project-wide** — covering principals
+that don't exist yet — or **per principal** as an exception.
 
-This persists `permissionMode = "enforce"` in the shared config file.
-Subsequent sessions will block any tool call that returns deny. Mode
-can always be flipped back:
+Every session reads the live mode, so the change takes effect without
+reinstalling or reconfiguring anything. Confirm it landed:
 
 ```sh
-{{NPX}} permissions observe
+{{NPX}} permissions
 ```
 
-`ORY_PERMISSION_MODE`, when set, overrides the config — useful for CI
-runs that want enforce regardless of what's persisted, or for one-off
-debugging sessions where you want observe without rewriting config.
-
-## Step 5: Verify a real session
+## Step 6: Verify a real session under enforce
 
 Start a normal agent session and confirm:
 
 - **Allowed tools** invoke without complaint.
-- **Denied tools** (if any) are blocked with a clear "Ory: permission
-  denied" message.
-- The trace file shows `permission.check` spans for each tool call and
-  `tool.block` spans for any denial.
+- **Denied tools** are blocked with a clear "Ory: permission denied"
+  message naming the tool (or the shell command word).
+- The activity log shows `permission.check` events per tool call and
+  `tool.block` events for denials.
+
+If a tool is unexpectedly blocked, run `{{NPX}} permissions` to
+see whether it is `denied` (no grant) or `blocked` (an explicit
+deny-override), then fix it in the Console and re-test.
+
+## Explicit blocks (deny-override)
+
+Granting is additive. To express the opposite — a subject is **blocked**
+from a tool, beating any grant, including one inherited through a group —
+an admin writes a `blockedSubjects` relation in the Console. Ory evaluates it
+natively (the `use` permit is "granted AND not blocked"), so it holds
+no matter how the grant was reached.
 
-If a tool is unexpectedly blocked, run `{{NPX}} permissions status` to
-confirm whether the tuple exists, then add or fix tuples and re-test.
+A block behaves like any other deny: under **observe** it is recorded (a
+`permission.block_observed` activity event) but the tool still runs; under
+**enforce** it blocks. `permissions` marks blocked tools so they
+are distinguishable from a plain missing grant at a glance.
 
-## Reference: what each command does
+## Reference
 
 | Command | Effect |
 |---|---|
-| `{{NPX}} permissions status` | Print mode + per-tool allow/deny breakdown for the current user. Read-only. |
-| `{{NPX}} permissions bootstrap` | Write `use` tuples for the harness's built-in tools. Idempotent. |
-| `{{NPX}} permissions bootstrap --dry-run` | Print what would be written without making any changes. |
-| `{{NPX}} permissions observe` | Persist `permissionMode = "observe"` (denies log, allow through). |
-| `{{NPX}} permissions enforce` | Persist `permissionMode = "enforce"` (denies block). |
+| `{{NPX}} configure --project-url <URL> --agent-security-url <URL>` | Connect the plugin to the canonical Agent Security broker. |
+| `{{NPX}} configure --disconnect` | Turn sign-in and permission checks back off. Skills, commands, the local stack, and activity logging are unaffected. |
+| `{{NPX}} permissions` | Print the live mode + per-tool allowed/denied/blocked breakdown. Read-only. |
+| `{{NPX}} status` | Configuration, identities, permission coverage, recent activity. |
+
+Done in the **Ory Console** (Agent Security), not from the CLI: applying
+the permission model, granting `use` on tools, writing explicit blocks,
+and setting the observe/enforce posture.
 
 For deeper background on the authentication side of the flow (which
 identity is the subject, how the user gate resolves it), see