@ory/goose 0.11.1 → 0.12.0

package/README.md

@@ -1,112 +1,145 @@
 # Ory Agent Plugin: Goose
 
-[Ory](https://ory.com) bundled into [Goose](https://github.com/block/goose) (Block's open-source 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 Goose runs.
+Security and developer experience for [Goose](https://github.com/block/goose) (Block's open-source coding agent), powered by [Ory](https://ory.com).
 
-You don't need an Ory account or any prior Ory experience to start.
+**Security.** Goose 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; Goose 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.
 
-This integration is verified against the `goose` binary (v1.39.0). The plugin-directory layout, the `hooks.json` schema, and the discovery paths all match the binary's shell-hook plugin contract (see [block/goose#9304](https://github.com/block/goose/pull/9304)).
+**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.
 
-## New to Ory?
+Verified against the `goose` binary (v1.39.0): the plugin layout, the `hooks.json` schema, and the discovery paths all match Goose's shell-hook plugin contract (see [block/goose#9304](https://github.com/block/goose/pull/9304)).
 
-[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.
+- [Goose](https://github.com/block/goose), 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 Goose 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 Goose'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/goose ory-goose install
+```
 
-## Prerequisites
+The installer drops a self-contained plugin at `<project>/.agents/plugins/ory/`, where Goose finds it on its own at startup — no `goose configure` step and nothing else in your Goose config gets touched. Then it asks how you want to connect — **press Enter for the default**:
 
-- [Goose](https://github.com/block/goose) 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 Goose does.
 
-## Install
+That's it. Confirm everything landed with:
 
 ```bash
-npx -y -p @ory/goose ory-goose install
+npx -y -p @ory/goose ory-goose status
 ```
 
-This is the simplest install of any harness in this repo: it drops a self-contained plugin tree at `<project>/.agents/plugins/ory/` (or `~/.agents/plugins/ory/` with `--global`) — a `plugin.json` manifest plus `hooks/hooks.json` and the Ory skills. **No config mutation, no MCP registration, no `goose configure` step.** Goose auto-discovers the plugin directory at startup.
+`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, whether the plugin is registered (project and global), and recent activity.
 
-```bash
-npx -y -p @ory/goose ory-goose install --global   # install for all projects
-npx -y -p @ory/goose ory-goose status              # confirm what landed
-npx -y -p @ory/goose ory-goose uninstall           # remove the ory plugin dir
-```
+Re-run install with `--reconfigure` to change your connection later, `--no-configure` to skip the wizard, or `--global` to install for every project (at `~/.agents/plugins/ory/`).
 
-`status` prints configuration, user and agent identity, per-tool permission coverage, plugin registration (project + global), and a tail of recent debug logs.
+## What you get
 
-## Quickstart (≈ 3 minutes)
+Once connected, every tool Goose runs is governed by Ory — three things happen automatically:
 
-From any project where you'd like Ory authentication, inside Goose:
+- **Who's driving.** You sign in once in your browser (a standard, secure browser login); Goose gets its own separate identity and registers it automatically on first run. No tokens to copy around, and the "who did what" 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 Jaeger, Honeycomb, Grafana, or just a file.
 
-1. **Start a local Ory instance.** Ask Goose *"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 Goose *"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.
+Under the hood, Goose runs the plugin as a small program for each thing it does, handing it the event and reading back a decision. The `hooks.json` file maps that: **SessionStart** signs you in, **PreToolUse** (the one point that can block) runs the permission check, and the rest — **PostToolUse, BeforeReadFile, AfterFileEdit, BeforeShellExecution, Stop, SessionEnd** — just record activity. If Ory is ever unreachable, the plugin gets out of the way and lets Goose keep working, so it can't lock you out.
 
-Continue to [Agent security](#agent-security) when you're ready to enforce.
+### See what's happening
 
-## How the integration works
+Everything the plugin does is observable out of the box — no configuration required:
 
-Goose discovers external **shell-hook plugins** by directory and invokes the hook binary as a subprocess for each lifecycle event (Claude-Code-style: event payload as JSON on stdin, decision on stdout). A hook blocks a tool call by returning `{"action":"block","message":"…"}` (the `RawHookAction` shape); the plugin also exits with code 2 as a defensive secondary block signal.
+- **Status at a glance.** `npx -y -p @ory/goose ory-goose 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:
 
-The `hooks.json` maps these phases to the Ory hook:
+  ```bash
+  npx -y -p @ory/goose ory-goose watch
+  ```
 
-- **SessionStart** — run the user and agent auth gates.
-- **PreToolUse** — the only blocking event; check the tool against Ory Permissions, deny blocks in enforce mode.
-- **PostToolUse / BeforeReadFile / AfterFileEdit / BeforeShellExecution / Stop / SessionEnd** — trace-only audit spans.
+  Spans are also written to `~/.config/ory-agent-plugins/goose/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/goose/ory-agent-debug.log`.
 
-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.
+### Ready to enforce?
 
-## Agent security
+When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
 
-Once pointed at an Ory project (local or hosted), Goose's session and every tool call can be governed by Ory.
+```bash
+npx -y -p @ory/goose ory-goose permissions enforce
+```
 
-- **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 Goose 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 plugin checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relations) against the user's subject and blocks on `deny`.
-- **Audit.** Every decision is recorded as a structured trace span (NDJSON file and/or OTLP export).
+Now a denied tool is actually blocked and Goose 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.
 
-### Permission modes: observe → enforce
+## Also: add login to your own app
 
-After install the plugin 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.
+Beyond securing Goose, the plugin helps you build Ory into whatever you're working on — backed by a local Ory, so it needs nothing but Docker. Ask Goose in plain language, e.g. *"add Ory auth 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.
 
-```bash
-# Grant the current user `use` on every built-in tool (idempotent):
-npx -y -p @ory/goose ory-goose permissions bootstrap
+These are **skills** — vetted playbooks Goose runs when you ask for them in chat. Start a local Ory with the `ory-local-up` skill (it prints a test email + password to sign in with) and tear it down with `ory-local-down`. More skills cover `ory-auth-setup`, `ory-login-flow`, `ory-social-login` (Google, GitHub, Apple…), `ory-permissions-onboarding`, and more.
 
-# See allowed/denied per tool:
-npx -y -p @ory/goose ory-goose permissions status
+## Configure by hand (CI / advanced)
 
-# Turn on hard blocking once the observe-mode logs look right:
-npx -y -p @ory/goose ory-goose permissions enforce
+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/goose ory-goose configure \
+  --project-url https://<slug>.projects.oryapis.com \
+  --oauth2-client-id <sign-in client id> \
+  --user-login
 ```
 
-Switch back any time with `permissions observe`. To disable Ory entirely (audit logging only), run `ory-goose configure --audit-only`.
+Goose'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 guided setup makes it for you). Persist the login toggle with `--user-login` / `--no-user-login`, or set it per-session with `ORY_USER_LOGIN=true`. 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`.
 
-## Pointing at a real Ory project
+<details>
+<summary>Create the sign-in client by hand</summary>
 
-The Quickstart uses the local stack. To point at a hosted [Ory Network](https://console.ory.sh) project:
+The guided setup normally does this. To do it yourself, create a **public** OAuth2 client (no secret) listing all four loopback URLs — the plugin tries each in turn so sign-in survives a busy port:
 
 ```bash
-npx -y -p @ory/goose ory-goose configure \
-  --project-url https://<id>.projects.oryapis.com \
-  --oauth2-client-id <public OAuth2 client id>
+ory create oauth2-client --project <project-id> \
+  --name "ory-agent-plugin" \
+  --grant-type authorization_code,refresh_token \
+  --response-type code \
+  --scope openid,offline_access \
+  --token-endpoint-auth-method none \
+  --redirect-uri http://127.0.0.1:47823/callback \
+  --redirect-uri http://127.0.0.1:47824/callback \
+  --redirect-uri http://127.0.0.1:47825/callback \
+  --redirect-uri http://127.0.0.1:47826/callback
 ```
 
-`--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`.
+Pass the resulting id to `configure --oauth2-client-id`. Running headless with a session token already? Set `ORY_USER_SESSION_TOKEN` and skip the browser step entirely.
+
+</details>
+
+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-goose install | uninstall        Install/remove; --reconfigure re-runs setup, --no-configure skips it, --global installs everywhere
+ory-goose status                     Show configuration, identities, permission coverage, registration, recent activity
+ory-goose watch                      Tail the live trace stream (OTel spans)
+ory-goose permissions <cmd>          status | bootstrap | observe (watch) | enforce (block)
+ory-goose configure <flags>          Point at a project by hand (--project-url, --oauth2-client-id, --user-login, --audit-only)
+ory-goose agent <status|unregister>  Manage Goose's own auto-created identity
+```
+
+All prefixed with `npx -y -p @ory/goose`.
+
+## Troubleshooting
 
-Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked.
+- **The 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-goose agent unregister` and try again.
+- **`npx` grabbed an old version** — force the latest: `npx -y -p @ory/goose@latest ory-goose …`.
+- **Goose isn't picking up the plugin** — confirm the tree at `<project>/.agents/plugins/ory/` exists (or re-run the installer), and restart Goose.
+- **Want to see what's happening** — `npx -y -p @ory/goose ory-goose status` for a snapshot, `npx -y -p @ory/goose ory-goose 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/goose/` (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)
 - [Goose repository](https://github.com/block/goose)
 - [Repo README](../../README.md) and [AGENTS.md](../../AGENTS.md) — full env-var and permission-mode reference
 

package/dist/cli/main.js

@@ -58,14 +58,19 @@ function main() {
     const [command, ...args] = process.argv.slice(2);
     switch (command) {
         case "install":
+            (0, argus_1.beginDeferNextSteps)();
             install(args);
-            postInstallPermissions("ory-goose", "goose").then(() => process.exit(0), (err) => {
+            (0, argus_1.runPostInstall)("ory-goose", "goose", 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-goose", args);
@@ -97,6 +102,9 @@ function main() {
                 process.exit(1);
             });
             break;
+        case "watch":
+            (0, argus_1.runWatchCommand)("goose", args);
+            break;
         case "help":
         case "--help":
         case "-h":
@@ -118,12 +126,6 @@ function uninstall(_args) {
     const setupArgs = (0, argus_1.parseSetupArgs)({ supportsGlobal: true });
     (0, setup_js_1.runSetup)({ ...setupArgs, uninstall: true });
 }
-async function postInstallPermissions(binName, harness) {
-    const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
-    (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
-        bootstrappedAutomatically: bootstrapped,
-    });
-}
 function pluginRoots() {
     return {
         project: path.join(process.cwd(), ".agents", "plugins", PLUGIN_NAME),
@@ -152,7 +154,7 @@ function help() {
 ory-goose — Ory plugin for Goose
 
 Usage:
-  npx ory-goose <command> [options]
+  npx -y -p @ory/goose ory-goose <command> [options]
 
 Commands:
   install [--global]     Install the Ory plugin (project-local, or --global)
@@ -162,6 +164,7 @@ Commands:
   permissions <cmd>      Manage permission mode and tool permissions (status, bootstrap, observe, enforce)
   setup [--project-dir]  Write the plugin tree directly (advanced)
   status                 Show plugin status and configuration
+  watch [trace-file]     Tail the trace stream (OTel spans) live
   local <cmd>            Manage local Ory dev environment (up, down, status, seed, ...)
 
 After installing, Goose auto-discovers the plugin and hooks into these
@@ -171,10 +174,10 @@ lifecycle events:
   PostToolUse            Audit log tool executions
 
 Examples:
-  npx ory-goose install            # Install into ./.agents/plugins/ory
-  npx ory-goose install --global   # Install into ~/.agents/plugins/ory
-  npx ory-goose status             # Check configuration
-  npx ory-goose uninstall          # Remove the plugin
+  npx -y -p @ory/goose ory-goose install            # Install into ./.agents/plugins/ory
+  npx -y -p @ory/goose ory-goose install --global   # Install into ~/.agents/plugins/ory
+  npx -y -p @ory/goose ory-goose status             # Check configuration
+  npx -y -p @ory/goose ory-goose uninstall          # Remove the plugin
 `);
 }
 main();

package/dist/cli/setup.js

@@ -158,7 +158,10 @@ function runSetup(args) {
     writePluginTree(pluginRoot, version);
     console.log(`Ory plugin installed to ${pluginRoot}`);
     console.log(`  plugin.json + hooks/hooks.json + skills/ written.`);
-    (0, argus_1.printNextSteps)("Goose", "npx ory-goose-setup --uninstall");
+    (0, argus_1.printNextSteps)("Goose", "npx -y -p @ory/goose ory-goose-setup --uninstall", {
+        binName: "ory-goose",
+        harness: "goose",
+    });
 }
 function main() {
     if (process.argv.includes("--help") || process.argv.includes("-h")) {
@@ -170,4 +173,12 @@ function main() {
 }
 if (require.main === module) {
     main();
+    // Direct `-setup --uninstall` path: also clear stored Ory credentials.
+    // (The `ory-goose uninstall` command handles this itself.)
+    if (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/goose",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Ory plugin for Goose (Block's open-source agent CLI): scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -66,7 +66,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.11.1"
+    "@ory/argus": "0.12.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",