@ory/argus 1.2.3 → 1.3.0

package/README.md

@@ -90,6 +90,31 @@ Resolve the user and agent identities at session start. Non-blocking by default;
 | `ensureSubAgentIdentity` | Spawn-scoped child Talos identity issued through the authenticated parent |
 | `resolveUserSubject`, `subjectLabel` | Subject resolution and printable labels for activity and denial messages |
 
+For SPIFFE deployments, call
+`createSpiffeFileRequestAuthenticator({ generationPath, generationFile,
+expectedServerSpiffeId })`. `expectedServerSpiffeId` requires that exact URI SAN on
+the peer leaf certificate; normal CA-chain verification remains enabled, while DNS
+SANs and other workload identities in the same bundle do not satisfy the check.
+The helper returns a concrete `RuntimeRequestAuthenticator`. The generation directory
+defaults to `svid.pem`, `svid-key.pem`, and `bundle.pem`; names are configurable.
+It uses TLS 1.3 mutual TLS and never adds a forwarded identity header. Atomically
+switch the generation directory symlink to rotate all three PEM files without mixing
+generations or restarting the process. When `generationFile` is set, its contents are
+also checked before and after each snapshot. Hosted Web-PKI servers must explicitly
+set `verifyHostname: true` instead of `expectedServerSpiffeId`; that mode reads the
+bundle as part of the material snapshot but uses system trust roots and ordinary
+HTTPS hostname verification. Server-SPIFFE mode trusts the workload bundle and
+requires the exact sole URI SAN. Exactly one identity mode is required.
+The legacy three-path form remains available but cannot guarantee a coherent snapshot.
+One request setup is retried if rotation races with certificate/key validation.
+
+Headless deployments normally supply only `ORY_AGENT_API_KEY` (or an injected runtime
+authenticator such as SPIFFE) plus `ORY_PROJECT_URL` and `ORY_AGENT_SECURITY_URL`.
+Before PKCE, Argus resolves the administrator-provisioned subject and opaque root from
+Agent Security, keeps them in process memory, and reuses the root unchanged for child
+lineage. `ORY_AGENT_SUBJECT_ID` and `ORY_AGENT_ROOT_DELEGATION` remain compatibility
+overrides; a complete legacy package skips the context request.
+
 ### Logger
 
 - `DebugLogger`: recursively redacted structured activity plus verbose diagnostics in one NDJSON stream

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

@@ -370,7 +370,7 @@ PKCE flow, permission tuples, and activity events are all visible:
    survives across runs.
 
 For full env-var coverage (including the user/agent split,
-`ORY_USER_SUBJECT_NAMESPACE`, agent DCR knobs), see {{REF_AUTH_SETUP}}.
+`ORY_USER_SUBJECT_NAMESPACE`, and `ORY_AGENT_API_KEY`), see {{REF_AUTH_SETUP}}.
 
 ## What this skill does NOT do
 

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

@@ -0,0 +1,315 @@
+---
+name: ory-deploy-agent
+description: Build and deploy a headless TypeScript agent through Ory Agent Security using the Claude Agent SDK, `@ory/claude-agent-sdk`, the `ory-agent` deployment CLI, and either a generated Talos credential or customer-operated SPIFFE on Generic Docker or Kubernetes. Use for an end-to-end managed agent deployment or Agent Security deployment validation.
+---
+
+# Build and deploy an Agent Security managed agent
+
+Use this playbook for the canonical validated application stack:
+
+- TypeScript on Node.js 22
+- `@anthropic-ai/claude-agent-sdk` with Ory's `createOryHooks`
+- Generic Docker with Docker Compose, or Kubernetes
+- Agent Security's `talos_api_key`, or customer-operated `spiffe_x509_svid`
+
+Do not substitute another SDK in this workflow. Choose one runtime and credential
+path deliberately; do not combine Talos and SPIFFE credentials.
+Use `ory-build-agent` when the user asks for a different integration.
+Use {{REF_DEPLOY_OPENAI_E2B}} when the user asks to deploy a Python OpenAI
+Agents SDK application on E2B; that skill owns the Talos and sandbox lifecycle.
+
+## Safety
+
+Work autonomously, but ask before overwriting an existing application. Never
+print, inspect, commit, or place in a prompt:
+
+- `ORY_USER_OAUTH2_TOKEN`
+- `ANTHROPIC_API_KEY`
+- any value from `.ory/credentials.env`
+- SPIFFE private keys or SVID file contents
+
+The user OAuth2 token administers deployments as the signed-in identity. The
+generated `ORY_AGENT_API_KEY` or customer-issued SVID is a separate runtime
+credential. Never exchange their roles. Do not revoke a deployment or workload
+registration unless the user explicitly asks.
+
+## Prerequisites
+
+Require Node.js 22 or newer, npm, Docker with `docker compose`, and Go 1.24 or
+newer unless `ory-agent` is installed. Require only this application environment
+value:
+
+```text
+ANTHROPIC_API_KEY
+```
+
+Agent Security must have a connected project URL, but it need not come from an
+environment variable: the CLI reads the shared plugin config and its persisted
+user login. Headless CI sets `ORY_PROJECT_URL` as connection configuration and
+`ORY_USER_OAUTH2_TOKEN` to a user OAuth2 access token.
+`ORY_AGENT_SECURITY_URL` is optional and defaults to
+`https://agents.console.ory.com`.
+
+Check the authenticated context without exposing a token:
+
+```bash
+ory-agent auth status
+```
+
+The server response is authoritative for the connected project and owner.
+
+## Build the agent
+
+Inspect the repository first and preserve its package manager and conventions.
+For a new TypeScript application, install:
+
+```bash
+npm install @ory/argus @ory/claude-agent-sdk @anthropic-ai/claude-agent-sdk zod
+npm install --save-dev typescript @types/node
+```
+
+Build a headless service with `GET /healthz` and `POST /run`. Wire the SDK at
+its supported hook boundary, and consume the query stream:
+
+```ts
+import {
+  createSdkMcpServer,
+  query,
+  tool,
+  type Options,
+} from "@anthropic-ai/claude-agent-sdk";
+import { OryAgentClient } from "@ory/argus";
+import { createOryHooks } from "@ory/claude-agent-sdk";
+import { z } from "zod";
+
+const deploymentProbe = tool(
+  "deployment_probe",
+  "Return a fixed deployment health marker",
+  { marker: z.literal("ready").default("ready") },
+  async ({ marker }) => ({
+    content: [{ type: "text", text: marker }],
+  }),
+);
+
+const deploymentServer = createSdkMcpServer({
+  name: "deployment",
+  version: "1.0.0",
+  tools: [deploymentProbe],
+});
+
+const ory = OryAgentClient.fromEnv("claude-agent-sdk");
+
+function options(): Options {
+  return {
+    tools: [],
+    mcpServers: { deployment: deploymentServer },
+    allowedTools: ["mcp__deployment__deployment_probe"],
+    // The packages use compatible hook shapes without sharing SDK types.
+    hooks: createOryHooks({ client: ory }) as unknown as Options["hooks"],
+  };
+}
+
+async function runClaude(prompt: string) {
+  const messages = query({
+    prompt,
+    options: options(),
+  });
+  for await (const message of messages) {
+    // Convert the SDK result into the service's response shape.
+  }
+}
+
+// POST /run passes the request prompt to runClaude.
+// POST /probe passes a fixed prompt that requires deployment_probe.
+await runClaude("Call deployment_probe exactly once and return its result.");
+```
+
+All tool execution must pass through these hooks. Add a local
+`deployment_probe` tool using the Claude Agent SDK's supported tool/MCP surface.
+Expose `POST /probe`, but do not invoke the tool implementation directly: run a
+fixed Claude SDK `query` that instructs Claude to call `deployment_probe`, with
+the same `createOryHooks()` wiring as `/run`. This intentionally makes a model
+request so the validation exercises the real `SessionStart`, `PreToolUse`, and
+`PostToolUse` lifecycle instead of claiming that a direct MCP call is secured by
+hooks that never ran.
+
+Add focused tests for health, the fixed probe query, hook wiring on both SDK
+query paths, and the absence of embedded credentials. Run formatting, type
+checking, tests, and the production build before deployment.
+
+## Containerize
+
+Create a production Dockerfile and either `compose.yaml` or Kubernetes workload
+manifests. The service must receive `ANTHROPIC_API_KEY` by secret reference, bind
+to `0.0.0.0`, expose the application port, and define a health check. Ignore
+credentials, deployment state, dependencies, build output, and local environment
+files in Git and the Docker context.
+
+For Talos, load `.ory/credentials.env` with Compose `env_file` or the equivalent
+Kubernetes Secret. For SPIFFE, use the file-backed environment contract in
+`examples/spiffe`: mount the parent of the atomically switched `current`
+generation read-only, and point `ORY_AGENT_SPIFFE_GENERATION_PATH` at `current`.
+TypeScript `OryAgentClient.fromEnv()` and Python `OryAgentClient.from_env()` use
+the same variables and reload the certificate, private key, and trust bundle for
+every broker request.
+
+Run `docker compose config` without printing its environment section.
+
+## Initialize and plan
+
+Install a published, pinned coordinated CLI release, never `latest`. Obtain the
+version from the release or package selected by the user; do not invent or
+hardcode a future version in generated guidance:
+
+```bash
+go install github.com/ory/ory-agent-plugins/cmd/ory-agent@<release-version>
+ory-agent init
+ory-agent validate
+ory-agent deployment plan
+```
+
+The generated manifest uses this identity-free shape:
+
+```yaml
+api_version: agent-security.ory.sh/v1
+kind: AgentDeployment
+name: my-sdk-agent
+agent_type: claude-agent-sdk
+runtime_id: generic-docker
+package_recipe: docker-compose
+package_recipe_version: v1
+credential_method: talos_api_key
+credential_ttl_seconds: 2592000
+credential_rate_limit:
+  quota: 600
+  window_seconds: 60
+```
+
+For customer-operated SPIFFE connecting to hosted Agent Security, replace the
+credential-specific fields with:
+
+```yaml
+credential_method: spiffe_x509_svid
+spiffe_id: spiffe://customer.example/agent/my-sdk-agent
+spiffe_trust_relationship_id: <active-trust-relationship-uuid>
+```
+
+Hosted mode omits both `agent_security_mtls_url` and `spiffe_server_id`. The
+server supplies its Web-PKI mTLS endpoint, and the runtime uses system trust
+roots with HTTPS hostname verification. A customer-operated portable Agent
+Security deployment requires its explicit `agent_security_mtls_url` and may add
+an exact `spiffe_server_id`; use the values supplied for that environment.
+Do not attempt a hosted SPIFFE deployment until Agent Security advertises the
+capability; hosted rollout remains gated on DNS and certificate convergence.
+The deployment package supplies non-secret runtime identity configuration; the
+customer's workload identity system supplies the SVID, private key, and bundle.
+Do not put PEM material in the manifest or deployment package.
+
+Do not add project or owner fields unless the user deliberately requests an
+override. The CLI resolves both through remote `auth status`; an explicit
+project is sent to the owner-scoped server route for validation, while an
+explicit owner must equal the authenticated identity.
+
+## Create and deploy
+
+Create and decrypt the one-time package:
+
+```bash
+ory-agent deployment ensure --credential-file .ory/credentials.env
+```
+
+The CLI creates an ephemeral age identity, verifies the package digest, and
+atomically writes `.ory/credentials.env` and `.ory/deployment.json` with mode
+`0600`. Verify only that the files exist, are non-empty, ignored by Git, and
+excluded from the Docker build context.
+
+If an existing deployment is reused but the credential file is absent, stop.
+For Talos, the one-time secret cannot be reissued. Explain that replacement
+requires an explicit revoke, but do not revoke without approval. SPIFFE key
+material is never issued by this command; a missing SVID is an operator-side
+workload identity problem and must not trigger Talos fallback.
+
+Start and validate:
+
+```bash
+docker compose up --build --detach
+```
+
+Verify `/healthz` and invoke `/probe` first. The guarded probe makes the first
+authenticated runtime request that activates a ready deployment. Then run:
+
+```bash
+ory-agent deployment wait --for active --timeout 10m
+ory-agent deployment status
+```
+
+Finally invoke `/run` with a prompt that calls `deployment_probe`. Diagnose
+failures with secret-redacted logs.
+
+## Customer-operated SPIFFE
+
+SPIFFE is an integration contract, not an Ory-managed SPIRE installation. The
+customer exclusively owns and operates:
+
+- SPIRE or another conforming SPIFFE implementation
+- workload and node attestation, selectors, and registration entries
+- SVID and trust-bundle issuance, filesystem delivery, rotation, and revocation
+- helper/CSI/sidecar availability and the permissions on mounted key material
+
+Ory records the expected workload identity and authenticates broker requests.
+Neither `ory-agent deployment ensure` nor the Ory packages install SPIRE, choose
+selectors, create registrations, issue SVIDs, rotate files, or revoke workload
+entries.
+
+Use the generated file-backed contract exactly:
+
+```text
+ORY_AGENT_CREDENTIAL_METHOD=spiffe_x509_svid
+ORY_AGENT_SPIFFE_ID=spiffe://customer.example/agent/my-sdk-agent
+ORY_AGENT_SPIFFE_GENERATION_PATH=/run/ory-spiffe/current
+ORY_SPIFFE_GENERATION_FILE=generation
+```
+
+`ORY_SPIFFE_GENERATION_FILE` is optional. When used, the customer-side writer
+must update one generation directory completely, update its marker, and
+atomically switch `current`. The application mount must include the parent
+directory rather than bind-mounting the old symlink target. Direct-path mode is
+also supported with all three of `ORY_AGENT_SPIFFE_SVID_PATH`,
+`ORY_AGENT_SPIFFE_KEY_PATH`, and `ORY_AGENT_SPIFFE_TRUST_BUNDLE_PATH`, but an
+atomic generation directory is preferred for rotation.
+Hosted mode must leave `ORY_AGENT_SPIFFE_SERVER_ID` unset so the runtime uses
+system roots and hostname verification. For customer-operated portable Agent
+Security, set `ORY_AGENT_SECURITY_URL` to its explicit mTLS URL and optionally
+set `ORY_AGENT_SPIFFE_SERVER_ID` to the exact server workload ID.
+
+Use `examples/spiffe/docker/compose.yaml` as the Generic Docker contract. It
+expects the customer's material writer on the host and mounts its output
+read-only. Use `examples/spiffe/kubernetes/deployment.yaml` as the Kubernetes
+contract. It expects a customer-provisioned `customer-spiffe-material` PVC; adapt
+that volume to the customer's CSI/helper pattern without adding SPIRE lifecycle
+resources to the application deployment.
+
+Before production, run the local contract tests and then validate these states
+in the customer's non-production identity domain:
+
+1. Package configuration: both TypeScript and Python resolve an injected SPIFFE
+   credential and do not use `ORY_AGENT_API_KEY`.
+2. Authentication: a valid SVID reaches Agent Security over TLS 1.3 mTLS;
+   hosted mode verifies the Web-PKI hostname, while portable mode matches the
+   exact server SPIFFE URI SAN when one is configured.
+3. Authorization: an allowed `deployment_probe` runs; the same tool is blocked
+   after an explicit deny in enforce mode.
+4. Rotation: atomically switch `current`; the next request uses the new SVID
+   without restarting the application.
+5. Revocation: revoke the customer-owned registration/SVID and confirm the next
+   request fails authentication without falling back to Talos. Separately,
+   `ory-agent deployment revoke` revokes the Ory deployment record only; it does
+   not delete a SPIRE registration.
+
+## Report
+
+Report changed files, format/typecheck/test/build results, Docker health,
+non-secret deployment ID and status, fixed-query and user-query probe results,
+activation status, and blockers. Never report credentials, environment values,
+authorization headers, or credential-file contents. Leave resources running for
+inspection unless the user asks for cleanup.

package/assets/skills/ory-deploy-openai-e2b/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: ory-deploy-openai-e2b
+description: Build and deploy a Python OpenAI Agents SDK application in E2B with `ory-openai-agents`, the `ory-agent` CLI, and an Agent Security Talos deployment credential. Use when the user asks to build, secure, or deploy an OpenAI agent on E2B, including a prompted web-page generator.
+---
+
+# Build and deploy an OpenAI agent on E2B
+
+Use this playbook to turn the user's intent into a complete, secured deployment:
+
+- Python with the OpenAI Agents SDK
+- `ory-openai-agents` at every function-tool boundary
+- an immutable, credential-free E2B template
+- Agent Security runtime `e2b` and recipe `e2b-sandbox` `v1`
+- a generated `talos_api_key` managed through the `ory-agent` CLI
+
+The user should be able to ask for an agent in product terms. Inspect the repository,
+preserve its package manager and conventions, scaffold the application and controller,
+run validation, and deploy it through the commands below. Ask before overwriting an
+existing application or revoking a deployment. Ask for missing credentials; never
+fabricate them.
+
+Use `ory-build-agent` for another SDK and `ory-deploy-agent` for the canonical Claude
+Agent SDK Docker/Kubernetes deployment. Use `ory-e2b-sandbox` only when installing an
+Ory coding-harness plugin into an E2B image; do not combine that recipe with this Agent
+SDK application deployment.
+
+## Security boundaries
+
+Keep these components separate:
+
+1. The trusted controller holds `E2B_API_KEY`, `OPENAI_API_KEY`, and the decrypted
+   `.ory/credentials.env` values.
+2. The E2B template contains only source and pinned dependencies. It contains no
+   credentials and no Agent start command.
+3. The sandbox receives `OPENAI_API_KEY` and `ORY_*` only in the Agent command's
+   `envs`. A credential-free preview process must not inherit them.
+4. Agent Security owns the Agent identity, root delegation, Talos credential, policy,
+   activation, and activity records. It does not provision E2B resources.
+
+Never print, inspect, commit, upload, or place in a prompt:
+
+- `OPENAI_API_KEY` or `E2B_API_KEY`
+- `ORY_AGENT_API_KEY`
+- any value from `.ory/credentials.env`
+- a user OAuth2 token
+
+Never inject `ORY_USER_OAUTH2_TOKEN` into E2B. The deployment package is a complete
+headless runtime identity and skips browser login. Always kill the sandbox after use;
+never pause, snapshot, or fork it after credentials have entered it.
+
+## Prerequisites
+
+Require:
+
+- a pinned published `ory-agent` release
+- Python 3.10 or newer and the repository's Python package workflow
+- an authenticated Ory Agent Plugin session for deployment administration
+- `E2B_API_KEY` and `OPENAI_API_KEY` in the trusted controller environment
+- project-level Talos rate limiting enabled before relying on deployment quotas
+
+Check Ory authentication without exposing its token:
+
+```bash
+ory-agent auth status
+```
+
+Stop if the catalog-selected coordinated `ory-openai-agents` and `ory-argus` release
+does not exist in the approved Python registry. Pin the tested OpenAI SDK and coordinated
+Ory release, including transitives, in the repository's lock file. Do not use `latest`.
+
+## Scaffold the application
+
+For a web-page generator, create this shape unless the repository already establishes
+another layout:
+
+```text
+app/agent.py
+app/preview.py
+controller/launch.py
+tests/test_agent.py
+requirements.in
+requirements.lock
+template.py
+```
+
+The sandbox must not contain the E2B SDK; only the external controller creates E2B
+resources. Expose narrow function tools instead of shell access. For a static page
+generator, use a fixed output directory, fixed filenames, prompt and output size limits,
+and HTML/CSS only.
+
+Use one shared Ory client for the input guardrail and completion hooks. OpenAI tool-input
+guardrails belong on each `FunctionTool`, not on `Agent`:
+
+```python
+import sys
+from pathlib import Path
+from uuid import uuid4
+
+from agents import Agent, Runner, function_tool
+from ory_argus import OryAgentClient, with_hook_context
+from ory_openai_agents import ory_run_hooks, ory_tool_input_guardrail
+
+OUTPUT_DIR = Path("/workspace/output")
+MAX_FILE_BYTES = 256_000
+ory = OryAgentClient.from_env("openai-agents")
+ory_guardrail = ory_tool_input_guardrail(client=ory)
+
+
+def write_bounded(name: str, content: str) -> None:
+    encoded = content.encode("utf-8")
+    if len(encoded) > MAX_FILE_BYTES:
+        raise ValueError(f"{name} exceeds {MAX_FILE_BYTES} bytes")
+    (OUTPUT_DIR / name).write_bytes(encoded)
+
+
+@function_tool(tool_input_guardrails=[ory_guardrail])
+def write_web_page(index_html: str, styles_css: str) -> str:
+    """Write one static web page to the fixed preview directory."""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    write_bounded("index.html", index_html)
+    write_bounded("styles.css", styles_css)
+    return "Wrote index.html and styles.css"
+
+
+agent = Agent(
+    name="Web Page Builder",
+    instructions=(
+        "Create an accessible responsive static page. Call write_web_page exactly once. "
+        "Do not generate JavaScript, forms, remote resources, network requests, analytics, "
+        "automatic navigation, or secrets."
+    ),
+    tools=[write_web_page],
+)
+
+
+def run(prompt: str, *, session_id: str | None = None) -> str:
+    with with_hook_context(ory, session_id=session_id or uuid4().hex):
+        status = "error"
+        try:
+            result = Runner.run_sync(agent, prompt, hooks=ory_run_hooks(client=ory))
+            status = "ok"
+        finally:
+            ory.logger.activity(
+                "session.end",
+                status,
+                attributes={"harness": "openai-agents"},
+            )
+            if not ory.flush_events(timeout=3):
+                print("Agent Security activity flush did not complete", file=sys.stderr)
+    return str(result.final_output)
+```
+
+Every side-effecting local function tool needs the Ory guardrail. Hosted tools and model
+built-ins do not pass through a function-tool guardrail; do not claim they are protected.
+Installing the adapter alone protects nothing. Keep the entire Runner invocation, terminal
+session activity, and event flush inside one `with_hook_context`; use a controller-owned stable
+job or conversation ID when available, otherwise generate a new opaque ID for each run.
+
+Add a fixed probe mode that runs the same OpenAI `Runner` and instructs the model to call
+`write_web_page` exactly once with known harmless content. Do not invoke the Python tool
+function directly: the probe must exercise session start, Talos authentication,
+authorization, tool execution, completion activity, and event flush.
+
+Serve generated files from a separate process with a restrictive CSP: no scripts,
+connections, forms, framing, base URI, remote resources, or MIME sniffing. Do not pass the
+Agent command environment to the preview process.
+
+Test prompt bounds, output bounds, fixed paths, allowed execution, enforce-mode denial,
+shared-client guardrail/hooks wiring, and secret-free source and fixtures. Run formatting,
+lint, unit tests, and a real-SDK compatibility test before building the template.
+
+## Build an immutable E2B template
+
+Generate a Python E2B template that installs the locked dependencies and copies only the
+application:
+
+```python
+from e2b import Template
+
+template = (
+    Template()
+    .from_ubuntu_image("22.04")
+    .apt_install(["python3", "python3-pip"])
+    .set_workdir("/workspace")
+    .copy("requirements.lock", "/workspace/requirements.lock")
+    .run_cmd("python3 -m pip install --no-cache-dir -r requirements.lock")
+    .copy("app", "/workspace/app")
+    .make_dir("/workspace/output", mode=0o700)
+)
+```
+
+Do not configure the Agent as a template start command: sandbox-creation credentials do
+not exist during the template build. Build in a trusted release environment, scan source
+and logs for secret markers, and record the returned immutable build ID. Production must
+use `<template-name>:<build-id>`, never a moving tag or bare build ID.
+
+## Initialize the Agent Security deployment
+
+Generate the supported manifest and workflow through the CLI rather than hand-writing
+the API request:
+
+```bash
+ory-agent init \
+  --name web-page-generator \
+  --agent-type openai-agents \
+  --runtime-id e2b \
+  --package-recipe e2b-sandbox \
+  --package-recipe-version v1 \
+  --credential-method talos_api_key
+ory-agent validate
+ory-agent deployment plan
+```
+
+The resulting `.ory/agent.yaml` must contain this selection and no project, owner, or
+credential values:
+
+```yaml
+agent_type: openai-agents
+runtime_id: e2b
+package_recipe: e2b-sandbox
+package_recipe_version: v1
+credential_method: talos_api_key
+```
+
+Review the plan. Then create the one-time package:
+
+```bash
+ory-agent deployment ensure --credential-file .ory/credentials.env
+```
+
+The CLI verifies the package and atomically writes `.ory/credentials.env` and the
+non-secret `.ory/deployment.json` with mode `0600`. Verify only existence, mode,
+non-empty size, Git ignore coverage, and exclusion from build contexts. Never read the
+credential file into chat or terminal output. If a deployment is reused but the one-time
+credential file is missing, stop and explain that replacement requires explicit
+revocation. Do not revoke without approval.
+
+## Launch through the trusted controller
+
+Load `.ory/credentials.env` into a validated in-memory map without logging it. Require
+exactly the deployment variables emitted by Agent Security, including
+`ORY_AGENT_API_KEY`, `ORY_AGENT_SUBJECT_ID`, and `ORY_AGENT_ROOT_DELEGATION`. Add
+`OPENAI_API_KEY` only to the Agent command environment.
+
+The controller must:
+
+1. Authenticate and rate-limit its caller.
+2. Create a sandbox from the exact `<template-name>:<build-id>` with a bounded lifetime.
+3. Disable public traffic unless preview is required.
+4. Deny outbound traffic by default and allow only the exact OpenAI, Agent Security, Ory
+   project, and required application hosts.
+5. Write the bounded prompt to a file rather than a shell argument.
+6. Run the Agent with `sandbox.commands.run(..., envs=agent_env, timeout=...)`.
+7. Start preview separately without `envs=agent_env`.
+8. Kill the sandbox in every failure, cancellation, expiry, and completion path.
+
+Do not put deployment values in `Sandbox.create(..., envs=...)`; command-scoped injection
+keeps them away from unrelated processes. E2B environment values remain visible inside
+the sandbox OS, so run only the intended customer application there.
+
+When exposing a preview, set `allow_public_traffic` to false, keep the E2B traffic access
+token in the controller, and proxy through a dedicated authenticated preview origin.
+Render generated content in a sandboxed iframe without same-origin, forms, popups, or
+top-navigation privileges. Never return the traffic token to untrusted page content.
+
+## Activate and validate
+
+Agent Security changes a deployment from `ready` to `active` on its first authenticated
+runtime request. Therefore use this order:
+
+1. Launch a canary sandbox from the immutable build.
+2. Run the fixed guarded probe inside it with command-scoped credentials.
+3. Verify the expected output files exist without dumping process environment.
+4. Run `ory-agent deployment wait --for active --timeout 10m`.
+5. Run `ory-agent deployment status`.
+6. Run the user's page-generation prompt and validate the static output.
+
+Start in Agent Security `observe`, review the recorded decision and activity, grant the
+expected tool, deliberately promote policy to `enforce`, and prove an explicit deny keeps
+the tool from writing output. Adapter infrastructure errors fail open, so E2B isolation,
+narrow tools, egress restrictions, timeouts, and output validation remain required.
+
+## Report
+
+Report changed files, dependency locks, checks, immutable E2B build ID, non-secret
+deployment ID and status, probe result, output validation, and blockers. Do not report
+credentials, environment values, authorization headers, traffic tokens, prompts that may
+contain sensitive data, or generated secret material. Leave a preview running only when
+the user explicitly asks to inspect it and its controller owns a bounded cleanup lease.

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

@@ -5,6 +5,11 @@ description: Scaffold an E2B (e2b.dev) sandbox template that boots with {{PKG}}
 
 # E2B sandbox with Ory agent security
 
+> **Agent SDK deployment:** If the user owns an OpenAI Agents SDK application and
+> wants Agent Security to issue its headless runtime identity, do not use this
+> coding-harness image recipe. Use {{REF_DEPLOY_OPENAI_E2B}} for the complete
+> `ory-agent`, Talos, immutable-template, and trusted-controller workflow.
+
 You are helping the user scaffold an [E2B](https://e2b.dev) sandbox template
 that preinstalls and registers the {{PKG}} plugin. The resulting template
 publishes a named image; every `Sandbox.create("<tag>")` call from their SDK
@@ -114,9 +119,9 @@ E2B_API_KEY=e2b_***
 ORY_PROJECT_URL=https://<slug>.projects.oryapis.com
 ORY_OAUTH2_CLIENT_ID=
 ORY_USER_OAUTH2_TOKEN=
-# Optional: pin a static agent identity instead of DCR.
-# ORY_AGENT_CLIENT_ID=
-# ORY_AGENT_CLIENT_SECRET=
+# Optional: supply a process-local Talos runtime credential. Otherwise session
+# start loads or enrolls one through the platform's credential-store support.
+# ORY_AGENT_API_KEY=
 ```
 
 ### `integrations/e2b/package.json`
@@ -152,8 +157,7 @@ Generate a README that captures:
   `npm run build:prod`.
 - A `Sandbox.create("agent-ory", { envs: { ... } })` example showing which env
   vars to inject at runtime (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`,
-  `ORY_USER_OAUTH2_TOKEN`, optional
-  `ORY_AGENT_CLIENT_ID` + `ORY_AGENT_CLIENT_SECRET`).
+  `ORY_USER_OAUTH2_TOKEN`, optional `ORY_AGENT_API_KEY`).
 - A pointer to {{REF_AUTH_SETUP}} for full env-var coverage and to
   {{REF_LOCAL_DEV}} for testing the same plugin locally before publishing the
   template.
@@ -196,7 +200,7 @@ const sbx = await Sandbox.create("agent-ory", {
 await sbx.commands.run("{{BIN}} --version");  // sanity check
 ```
 
-Sandboxes are headless, so the user **must** pre-supply
+Sandboxes using this interactive coding-harness recipe are headless, so the user **must** pre-supply
 `ORY_USER_OAUTH2_TOKEN` — otherwise user login's
 PKCE browser flow has no target and hangs. See {{REF_AUTH_SETUP}} for the full
 env-var matrix.