@ory/amp 0.11.0 → 0.12.0

package/README.md

@@ -1,117 +1,137 @@
 # Ory Agent Plugin: Amp
 
-[Ory](https://ory.com) bundled into [Amp](https://ampcode.com) (Sourcegraph's coding agent): skills that scaffold Ory authentication into your codebase, a local Ory stack you can spin up in one command, and (when pointed at an Ory project) authentication, authorization, and audit for every tool Amp runs.
+Security and developer experience for [Amp](https://ampcode.com) (Sourcegraph's coding agent), powered by [Ory](https://ory.com).
 
-You don't need an Ory account or any prior Ory experience to start.
+**Security.** Amp runs real actions on your machine — editing files, running shell commands, calling APIs. The plugin gives every session a verifiable identity (you sign in once; Amp and any sub-agents it spawns each get their own), checks every tool call against permissions you control, and records each decision as an audit trace you can ship to your observability stack. It starts in watch mode so nothing is blocked on day one, and if Ory is ever unreachable it steps aside rather than locking you out.
 
-## New to Ory?
+**Developer experience.** A single command installs the plugin and walks you through connecting — choose Ory Network, a local Docker stack, or audit-only, and it wires up the project, sign-in client, login, and permissions for you. It also helps you build Ory into your own app: ask in plain language to scaffold login, registration, and recovery pages, run a local Ory, or manage identities and permissions through the bundled MCP server.
 
-[Ory](https://www.ory.com/docs/) is an open-source identity and access platform — login, registration, sessions, social sign-in, multi-factor auth, and fine-grained permissions, so you don't have to build any of that yourself. Two things make it easy to try with no prior experience:
+## What you'll need
 
-- **Ory Elements** are prebuilt, themeable UI components for the auth pages. The scaffolding skills wire them into your app for you.
-- **The local Ory stack** is a complete Ory running on your laptop in Docker — no account, no signup, no API key.
+- [Amp](https://ampcode.com), installed
+- Node.js **22 or newer**
+- [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
+- macOS or Linux (Windows works via WSL2)
 
-## What this plugin does
+## Get started
 
-Two independent things, and you can use either on its own:
+Run one command. It installs the plugin and walks you through connecting:
 
-1. **Build auth into your app.** Have Amp scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This needs nothing but Docker.
-2. **Govern the agent itself.** Authenticate Amp's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See [Agent security](#agent-security).
+```bash
+npx -y -p @ory/amp ory-amp install
+```
 
-## Prerequisites
+You'll be asked how you want to connect — **press Enter for the default**:
 
-- [Amp](https://ampcode.com) installed
-- Node.js **≥ 22**
-- [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
-- macOS or Linux. Windows works via WSL2.
+- **Ory Network** *(default)* — sign in, or create a free account, in your browser. The project, keys, permissions, and login are all set up for you. Nothing to configure by hand.
+- **Local** — run a complete Ory on your laptop with Docker. No account, no signup, no keys. Great for trying it out.
+- **Audit-only** — skip Ory entirely and just log what Amp does.
 
-## Install
+That's it. Confirm everything landed with:
 
 ```bash
-npx -y -p @ory/amp ory-amp install
+npx -y -p @ory/amp ory-amp status
 ```
 
-`install` performs two registrations and materializes the Ory skills:
+`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, whether the plugin is wired into Amp, and recent activity.
 
-1. Registers the Ory **permission delegate** in Amp's settings (`~/.config/amp/settings.json`) under the flat top-level `amp.permissions` key as `{ tool: "*", action: "delegate", to: "ory-amp-permission" }` — this is the blocking gate.
-2. Writes the **in-process plugin** loader at `<project>/.amp/plugins/ory.ts` so Amp's Bun TypeScript runtime discovers it for session auth and audit tracing.
+Re-run install with `--reconfigure` to change your connection later, or `--no-configure` to skip the wizard and configure by hand.
 
-The Ory skill playbooks land under `<project>/.agents/skills/` (Amp's project skills directory).
+## What you get
 
-```bash
-npx -y -p @ory/amp ory-amp status      # confirm delegate + plugin registration
-npx -y -p @ory/amp ory-amp uninstall   # remove the delegate, plugin, and skills
-```
+Once connected, every tool Amp runs is governed by Ory — three things happen automatically:
 
-`status` prints configuration, user and agent identity, per-tool permission coverage, whether the delegate and in-process plugin are registered, and a tail of recent debug logs.
+- **Who's driving.** You sign in once in your browser; Amp gets its own identity too, and registers it automatically on first run. No tokens to copy around, and the "who acted on whose behalf" trail stays queryable later.
+- **What it's allowed to do.** Before a tool runs, Ory checks whether it's permitted. It starts in **watch mode** — nothing is blocked, you just *see* what would be — so it never gets in your way on day one.
+- **A record of everything.** Every decision (allowed, denied, skipped) is logged as a trace you can send to a viewer like Jaeger or Honeycomb, or just a file.
 
-## Quickstart (≈ 3 minutes)
+If Ory is ever slow or unreachable, the plugin gets out of the way and lets Amp keep working — so it can't lock you out.
 
-From any project where you'd like Ory authentication, inside Amp:
+### See what's happening
 
-1. **Start a local Ory instance.** Ask Amp *"start the local Ory stack"* or invoke the `ory-local-up` skill. A banner prints the seeded test user's email and password — note them.
-2. **Scaffold Ory into your project.** Ask Amp *"add Ory auth to this app"* (the `ory-auth-setup` skill). It installs Ory Elements, wires the SDK, and generates the login / registration / recovery / settings pages, all targeting the local stack.
-3. **Sign in.** Start your app, visit the login page, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, zero configuration.
+Everything the plugin does is observable out of the box — no configuration required:
 
-Continue to [Agent security](#agent-security) when you're ready to enforce.
+- **Status at a glance.** `npx -y -p @ory/amp ory-amp status` shows what's configured, who's signed in, how many built-in tools your permissions cover, and the most recent tool-call activity.
+- **Live traces.** Every tool call is recorded as an OpenTelemetry-style span. Watch them stream as the agent works:
 
-## How the integration works
+  ```bash
+  npx -y -p @ory/amp ory-amp watch
+  ```
 
-Amp's Ory integration is a **hybrid** of two mechanisms:
+  Spans are also written to `~/.config/ory-agent-plugins/amp/ory-agent-trace.ndjson` (NDJSON, one span per line) — tail that file, or point `OTEL_EXPORTER_OTLP_ENDPOINT` at a collector to ship them straight to Jaeger, Honeycomb, or Grafana.
+- **Debug log.** For a verbose play-by-play, set `ORY_AGENT_DEBUG=true`; structured logs land in `~/.config/ory-agent-plugins/amp/ory-agent-debug.log`.
 
-- **Blocking gate — a permission delegate helper (`ory-amp-permission`).** Registered in `amp.permissions`, Amp invokes it per tool call with the tool params on stdin and decides by **exit code**: `0` = allow, `1` = ask, `≥2` = reject (stderr is surfaced to the model). This is the only part that can block. Amp enforces a 10-second delegate timeout and treats a delegate that outlives it as a reject, so the delegate applies its own deadline to the Ory permission check (default 5 seconds, configurable via `ORY_AMP_CHECK_TIMEOUT_MS`) and fails open (allows) when the check is slow, hanging, or unreachable.
-- **Advisory in-process plugin (`.amp/plugins/ory.ts`).** Discovered by Amp's Bun runtime, it handles session-start auth (advisory — it cannot hard-block at session start) and post-tool audit tracing.
+### Ready to enforce?
 
-The phases map as:
+When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
 
-- **Session start** (in-process plugin) — run the user and agent auth gates; advisory.
-- **Per-tool decision** (delegate) — check the tool against Ory Permissions; in enforce mode a deny exits `2` (reject), in observe mode it records a `permission.observe_deny` span and allows (exit `0`).
-- **Post-tool** (in-process plugin) — trace-only audit spans.
+```bash
+npx -y -p @ory/amp ory-amp permissions enforce
+```
 
-The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config): the agent always starts, and enforcement is only as strong as your permission grants.
+Now a denied tool is actually blocked and Amp shows why. Go back to watch mode anytime with `permissions observe`. Use `permissions status` to see what's covered and `permissions bootstrap` to (re-)grant the built-in tools.
 
-## Agent security
+<details>
+<summary>How the plugin plugs into Amp</summary>
 
-Once pointed at an Ory project (local or hosted), Amp's session and every tool call can be governed by Ory.
+Amp gets the plugin in two pieces that work together:
 
-- **Authentication.** The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is on (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted thereafter). The Amp process (the **agent**) gets its own OAuth2 identity via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run.
-- **Authorization.** Before any tool runs, the delegate checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relations) against the user's subject and rejects on `deny`.
-- **Audit.** Every decision is recorded as a structured trace span (NDJSON file and/or OTLP export).
+- **A permission gate** registered in Amp's settings (`~/.config/amp/settings.json`) under the `amp.permissions` key. Before every tool call, Amp hands the tool and its params to this gate and reads the answer from its **exit code**: `0` = allow, `1` = ask, `≥2` = reject (the reason on stderr is shown to Amp). This is the piece that can actually block.
+- **An in-process plugin** at `<project>/.amp/plugins/ory.ts`, which Amp's built-in TypeScript runtime loads to sign you in at the start of a session and record what happened after each tool runs. It can't block from there, so it's advisory only — the gate above does the blocking.
 
-### Permission modes: observe → enforce
+Amp gives the gate 10 seconds to answer and treats a slower gate as a reject, so the plugin sets its own shorter deadline (5 seconds, adjustable with `ORY_AMP_CHECK_TIMEOUT_MS`) and lets the tool through if the Ory check is slow, stuck, or unreachable — it never leaves you hanging.
 
-After install the integration runs in **observe mode**: every tool call is checked, but a deny is recorded as a `permission.observe_deny` audit span and the tool runs anyway.
+The Ory skills land under `<project>/.agents/skills/`. `uninstall` removes the gate, the plugin, and the skills.
 
-```bash
-# Grant the current user `use` on every built-in tool (idempotent):
-npx -y -p @ory/amp ory-amp permissions bootstrap
+</details>
 
-# See allowed/denied per tool:
-npx -y -p @ory/amp ory-amp permissions status
+## Also: add login to your own app
 
-# Turn on hard blocking once the observe-mode logs look right:
-npx -y -p @ory/amp ory-amp permissions enforce
-```
+Beyond securing Amp, the plugin helps you build Ory into whatever you're working on. The Ory skills are **model-invoked** — just ask Amp in plain language and the right one takes over (Amp doesn't use slash commands for these). Ask Amp *"add Ory login to this app"* and it scaffolds the login, registration, recovery, and settings pages (using [Ory Elements](https://github.com/ory/elements)) wired to a local Ory — no signup or keys needed. Start that local Ory by asking *"start the local Ory stack"* (it prints a test email + password to sign in with).
+
+More bundled **skills** cover login and social sign-in (Google, GitHub, Apple…), permissions onboarding, and playbooks for wiring Ory into your own agents, E2B sandboxes, or Temporal workers.
 
-Switch back any time with `permissions observe`. To disable Ory entirely (audit logging only), run `ory-amp configure --audit-only`.
+The local Ory runs entirely on your laptop: the Ory APIs at `http://localhost:4000`, a login UI on `:4455` (not `:3000`, to avoid clashing with Next.js dev servers), the Ory Console on `:4100`, and a trace viewer (Jaeger) on `:16686`.
 
-## Pointing at a real Ory project
+## Configure by hand (CI / advanced)
 
-The Quickstart uses the local stack. To point at a hosted [Ory Network](https://console.ory.sh) project:
+The guided setup covers most people. For scripted or CI setups, or to point at an existing Ory Network project, configure directly. Settings are saved to `~/.config/ory-agent-plugins/config.json` and shared across all your Ory agent plugins; environment variables win when both are set.
 
 ```bash
 npx -y -p @ory/amp ory-amp configure \
-  --project-url https://<id>.projects.oryapis.com \
-  --oauth2-client-id <public OAuth2 client id>
+  --project-url https://<slug>.projects.oryapis.com \
+  --oauth2-client-id <sign-in client id> \
+  --user-login
+```
+
+Amp's own identity registers itself automatically on first run — nothing to create. The `--oauth2-client-id` is the one piece browser sign-in needs (the public client registered with the four loopback callback URLs `http://127.0.0.1:47823..47826/callback`); the guided setup makes it for you. Pass `--api-key ory_pat_...` only to override Amp's auto-created identity with a static token. For logging-only with no checks, use `--audit-only`. The matching env vars are `ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, `ORY_USER_LOGIN`, and `ORY_AGENT_API_KEY`.
+
+With nothing configured, the plugin still loads and runs in **pass-through mode**: skills and logging work, but no checks run and nothing is blocked. Perfectly fine if you only want the app-building features.
+
+## Commands
+
 ```
+ory-amp install | uninstall        Install/remove; --reconfigure re-runs setup, --no-configure skips it
+ory-amp status                     Show configuration, identities, permission coverage, and recent activity
+ory-amp watch                      Tail the live trace stream (OTel spans)
+ory-amp permissions <cmd>          status | bootstrap | observe (watch) | enforce (block)
+ory-amp configure <flags>          Point at a project by hand (--project-url, --oauth2-client-id, --user-login, --audit-only)
+ory-amp agent <status|unregister>  Manage Amp's own auto-created identity
+```
+
+All prefixed with `npx -y -p @ory/amp`.
 
-`--oauth2-client-id` is required whenever `--project-url` is set — the user PKCE flow needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`). See the [repo README](../../README.md) and [`AGENTS.md`](../../AGENTS.md) for the full environment-variable reference and permission-mode semantics. Config is shared across every Ory agent plugin at `~/.config/ory-agent-plugins/config.json`.
+## Troubleshooting
 
-Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked.
+- **Local Ory fails to start** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
+- **Browser sign-in loops** — reset with `ory-amp agent unregister` and try again.
+- **`npx` grabbed an old version** — force the latest: `npx -y -p @ory/amp@latest ory-amp …`.
+- **A tool check feels slow** — the plugin gives up on a stalled Ory check and lets the tool through; tune the deadline with `ORY_AMP_CHECK_TIMEOUT_MS`.
+- **Want to see what's happening** — `npx -y -p @ory/amp ory-amp status` for a snapshot, `npx -y -p @ory/amp ory-amp watch` for the live trace stream, or set `ORY_AGENT_DEBUG=true` for a verbose log. Traces and logs live under `~/.config/ory-agent-plugins/amp/` (see [See what's happening](#see-whats-happening)).
 
-## Links
+## Learn more
 
-- [Ory documentation](https://www.ory.com/docs/)
+- [Ory documentation](https://www.ory.com/docs/) · [Ory Console](https://console.ory.sh) · [Ory Elements](https://github.com/ory/elements)
 - [Amp documentation](https://ampcode.com)
 - [Repo README](../../README.md) and [AGENTS.md](../../AGENTS.md) — full env-var and permission-mode reference
 

package/dist/cli/main.js

@@ -52,14 +52,19 @@ function main() {
     const [command, ...args] = process.argv.slice(2);
     switch (command) {
         case "install":
+            (0, argus_1.beginDeferNextSteps)();
             install(args);
-            postInstallPermissions("ory-amp", "amp").then(() => process.exit(0), (err) => {
+            (0, argus_1.runPostInstall)("ory-amp", "amp", args).then(() => process.exit(0), (err) => {
                 console.error(err.message ?? err);
                 process.exit(1);
             });
             break;
         case "uninstall":
             uninstall(args);
+            (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
             break;
         case "configure":
             (0, argus_1.runConfigureCommand)("ory-amp", args);
@@ -91,6 +96,9 @@ function main() {
                 process.exit(1);
             });
             break;
+        case "watch":
+            (0, argus_1.runWatchCommand)("amp", args);
+            break;
         case "help":
         case "--help":
         case "-h":
@@ -117,12 +125,6 @@ function uninstall(args) {
     process.argv = ["node", "setup.js", "--uninstall", ...args];
     require("./setup.js");
 }
-async function postInstallPermissions(binName, harness) {
-    const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
-    (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
-        bootstrappedAutomatically: bootstrapped,
-    });
-}
 function parseProjectDir(args) {
     const idx = args.indexOf("--project-dir");
     if (idx !== -1 && args[idx + 1])
@@ -175,6 +177,7 @@ Commands:
                                    (status, bootstrap, observe, enforce)
   setup [--project-dir <path>]     Write config directly (fallback)
   status [--project-dir <path>]    Show plugin configuration and status
+  watch [trace-file]               Tail the trace stream (OTel spans) live
   local <cmd>                      Manage local Ory dev environment
                                    (up, down, status, seed, logs, env, configure, reset)
 
@@ -184,7 +187,7 @@ After installing, the Ory integration runs in two parts:
 
 Examples:
   npx -y -p @ory/amp ory-amp install
-  npx -y -p @ory/amp ory-amp configure --project-url https://<id>.projects.oryapis.com
+  npx -y -p @ory/amp ory-amp configure --project-url https://<slug>.projects.oryapis.com
   npx -y -p @ory/amp ory-amp permissions bootstrap
   npx -y -p @ory/amp ory-amp status
 `);

package/dist/cli/setup.js

@@ -192,6 +192,18 @@ function main() {
     console.log(`  Delegate: ${DELEGATE_BIN} (tool: "*", action: delegate)`);
     console.log(`Ory in-process plugin written to ${pluginFile}`);
     console.log(`Ory skills installed under ${skillsDir}`);
-    (0, argus_1.printNextSteps)("Amp", "npx ory-amp-setup --uninstall");
+    (0, argus_1.printNextSteps)("Amp", "npx -y -p @ory/amp ory-amp-setup --uninstall", {
+        binName: "ory-amp",
+        harness: "amp",
+    });
 }
 main();
+// When invoked directly as the `-setup` bin with `--uninstall`, also clear
+// stored Ory credentials. When required by the plugin's main CLI, that
+// command owns the purge, so the `require.main` guard prevents a double run.
+if (require.main === module && process.argv.includes("--uninstall")) {
+    (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
+        console.error(err.message ?? err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/amp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Ory plugin for Amp (Sourcegraph's coding agent): a permission delegate that authorizes every tool call plus an in-process plugin for session auth and audit tracing",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -67,7 +67,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.11.0"
+    "@ory/argus": "0.12.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",