@ory/argus 0.14.0 → 1.0.1

package/dist/client.d.ts

@@ -1,23 +1,22 @@
 import { DebugLogger } from "./logger.js";
-import { Tracer } from "./tracer.js";
-import type { SpanExporter } from "./otel/exporter.js";
+import { type EventReporterOptions } from "./event-reporter.js";
+import type { SessionContext } from "./context.js";
+import { type RuntimeCredential, type RuntimeRequestAuthenticator } from "./runtime-credential.js";
 import type { SessionInfo, OAuth2TokenInfo, PermissionCheck, PermissionResult, BatchPermissionResult, OryError } from "./types.js";
 export interface OryAgentConfig {
     /** Ory project URL, e.g. https://your-project.projects.oryapis.com */
     projectUrl: string;
-    /** Ory API key for admin operations */
-    apiKey?: string;
+    /** Agent Security broker URL. Defaults to projectUrl for shipped configs. */
+    agentSecurityUrl?: string;
     /** Which harness this client is running in */
     harness: string;
-    /** Optional log file path for debug output */
+    /** Optional unified activity/debug NDJSON file path. */
     logFile?: string;
-    /** Optional NDJSON trace file path for structured span output */
-    traceFile?: string;
     /**
-     * Permission-check subject namespace for the human user. When set, the
-     * user is addressed as a SubjectSet `<namespace>:<subject>` (matching how
-     * the tuples were written in Keto) rather than a direct SubjectID. Read by
-     * {@link resolveUserSubject}; `ORY_USER_SUBJECT_NAMESPACE` overrides it.
+     * Overrides the namespace the human user is addressed under. Users are always
+     * addressed as a SubjectSet `<namespace>:<subject>` (matching how the tuples
+     * were written in Keto); this only overrides the namespace (default `User`).
+     * Read by {@link resolveUserSubject}; `ORY_USER_SUBJECT_NAMESPACE` overrides it.
      */
     userSubjectNamespace?: string;
     /**
@@ -25,15 +24,81 @@ export interface OryAgentConfig {
      * Set to 0 to disable caching. Default: 60_000 (1 minute).
      */
     sessionCacheTtlMs?: number;
-    /** Optional span exporter (OTLP, vendor SDK, …) attached to the tracer. */
-    exporter?: SpanExporter;
+    /** Noninteractive request authentication, e.g. a SPIFFE mTLS transport. */
+    runtimeRequestAuthenticator?: RuntimeRequestAuthenticator;
+    /** Optional stable runtime subject supplied by the custom integration. */
+    runtimeSubject?: string;
+    /** Disabled by default so direct/test clients never perform background network calls. */
+    eventReporter?: true | Omit<EventReporterOptions, "projectUrl" | "agentSecurityUrl" | "token" | "onUnauthorized" | "logger">;
+}
+/**
+ * Inputs for {@link OryAgentClient.recordDelegation}. The plugin supplies only
+ * the *semantic* ends of the edge; the agent-security broker owns the Keto
+ * tuple shape (namespace, `delegate` relation, and the
+ * `<identity>|<harness>|<host>` join-key encoding), so no tuple/join-key logic
+ * lives in the plugin.
+ */
+export interface RecordDelegationInput {
+    /**
+     * Which edge to record. `agent` records `user → agent`; `subagent` records
+     * `agent → subagent`. Maps to the broker's `PRINCIPAL_KIND_AGENT` /
+     * `PRINCIPAL_KIND_SUBAGENT`.
+     */
+    kind: "agent" | "subagent";
+    /**
+     * Kratos identity the delegation is anchored to (→ `User:<identityId>`).
+     * Required for the `agent` edge; optional for `subagent` (the broker resolves
+     * the anchor from `delegatedBy`).
+     */
+    identityId?: string;
+    /** Host the runtime executes on — part of the `agent` edge join key. */
+    host?: string;
+    /**
+     * Sub-agent runtime type name (e.g. `"explore"`); required for the `subagent`
+     * edge. Sent as `principal.type_name`.
+     */
+    subAgentType?: string;
+    /**
+     * The parent agent's delegation node (`agent:<join>` or the bare join key),
+     * as returned in {@link RecordDelegationResult.nodeId} from the `agent` edge.
+     * Required for the `subagent` edge; echoed verbatim so the plugin never
+     * reconstructs the server's join-key encoding.
+     */
+    delegatedBy?: string;
+    /**
+     * The harness session this edge was recorded in — sent as
+     * `principal.session_id`, which is the field the broker's proto defines. The
+     * dynamic OAuth2 credential is keyed by this session, and the broker also
+     * needs the session to build the corresponding delegation node.
+     *
+     * Defaults to the client's ambient session ({@link OryAgentClient.sessionId},
+     * set by the harness's ambient session context); pass explicitly to override. Absent
+     * for a caller with no session concept, which the broker reads as "keep this
+     * runtime on one stable node" rather than inventing a session for it.
+     */
+    sessionId?: string;
+    /**
+     * Identifier for one *spawn* of a sub-agent, where the harness exposes one
+     * (Cursor's `subagent_id`, Claude Code's `agent_id`, OpenClaw's `childRunId`).
+     * Sent as `principal.per_spawn_id`; it is what distinguishes two concurrent
+     * same-type sub-agents. Absent on harnesses that expose no such id, in which
+     * case concurrent spawns of a type share a node.
+     */
+    perSpawnId?: string;
+}
+/** The delegation node the broker wrote, plus the resolved chain (root-first). */
+export interface RecordDelegationResult {
+    /** The node id written: `agent:<join>` or `subagent:<join>|<type>`. */
+    nodeId: string;
+    /** Root-first chain, e.g. `["User:<id>", "agent:<join>"]`. */
+    delegationChain: string[];
 }
 /**
  * A principal known to the client. Either the human user (interactive
  * PKCE login) or the agent (machine credentials).
  */
 export interface PrincipalIdentity {
-    /** Subject (sub claim or `session:<id>`) — used in audit spans. */
+    /** Subject (sub claim or `session:<id>`) used in audit activity. */
     subject?: string;
     /** Bearer token. Agent's token authenticates outgoing API calls. */
     token?: string;
@@ -42,10 +107,12 @@ export declare class OryAgentClient {
     private frontend;
     private oauth2;
     private permission;
-    private relationship;
     private config;
     readonly logger: DebugLogger;
-    readonly tracer: Tracer;
+    private readonly eventReporter?;
+    private _runtimeCredential?;
+    private readonly _runtimeCredentialsBySession;
+    private readonly _runtimeCredentialsByPrincipalKey;
     private sessionCache;
     private sessionCacheTtlMs;
     /**
@@ -53,35 +120,57 @@ export declare class OryAgentClient {
      * Populated by `ensureUserAuthenticated` on session start.
      */
     private _userPrincipal;
+    private readonly _userPrincipalsBySession;
     /**
      * The AI agent process — the principal that authenticates outgoing
      * Ory API calls. Populated by `ensureAgentIdentity`.
      */
     private _agentPrincipal;
-    /**
-     * Admin credential — an Ory Network **project API key** (`ory_pat_…`) —
-     * used to authenticate the Keto Permission and Relationship APIs.
-     *
-     * This is deliberately distinct from the agent principal's token. Ory
-     * Network's permission APIs authenticate with a project API key and
-     * **reject project-issued OAuth2 access tokens** (a DCR client-credentials
-     * token is answered with `401 "Access token is not active"`). So when the
-     * agent identity resolves to a DCR OAuth2 client — the default path — its
-     * token cannot authenticate permission checks. Holding the admin key here
-     * lets {@link buildApis} route Keto through it while the agent OAuth2 token
-     * still authenticates the OAuth2 / Frontend APIs and carries attribution.
-     *
-     * When unset, Keto calls fall back to the agent token (legacy
-     * single-credential behavior, unchanged for static-key deployments).
-     */
-    private _adminApiKey?;
+    private readonly _agentPrincipalsBySession;
+    private readonly _eventPrincipalsByKey;
     constructor(config: OryAgentConfig);
     /** Build a fresh set of Ory API instances using the current agent token. */
     private buildApis;
+    /** Canonical broker origin, with the shipped project URL fallback applied. */
+    get agentSecurityUrl(): string;
+    private buildBrokerPermissionTransport;
+    private postPermissionChecks;
+    private permissionPrincipal;
+    private subAgentTypeForClient;
     /** Snapshot of the current user principal. */
     get userPrincipal(): PrincipalIdentity;
+    /** Snapshot of the user principal bound to one session. */
+    userPrincipalForSession(sessionId?: string): PrincipalIdentity;
     /** Snapshot of the current agent principal. */
     get agentPrincipal(): PrincipalIdentity;
+    /** Active noninteractive broker credential. It is process memory only. */
+    get runtimeCredential(): RuntimeCredential | undefined;
+    get hasRuntimeCredential(): boolean;
+    setRuntimeCredential(credential: RuntimeCredential | undefined): void;
+    /** Retain an actor-scoped credential for deferred event delivery without activating it globally. */
+    rememberRuntimeCredential(credential: RuntimeCredential): void;
+    /** Run one hook with session/credential state isolated from concurrent hooks. */
+    withRuntimeContext<T>(context: SessionContext, work: () => T): T;
+    /** Snapshot of the agent principal bound to one session. */
+    agentPrincipalForSession(sessionId?: string): PrincipalIdentity;
+    private eventPrincipal;
+    /**
+     * The harness this client runs in (`"claude-code"`, `"codex"`, …). Exposed
+     * because persisted agent / sub-agent credentials and delegation anchors are
+     * keyed first by harness and then by session.
+     */
+    get harness(): string;
+    /**
+     * The harness session currently in scope, or `undefined` outside one.
+     *
+     * Read from standalone ambient session context, which every harness sets from its
+     * own session identifier at the top of a lifecycle invocation — so identity
+     * and delegation code can select the session's credential and node without
+     * each plugin threading the id through its own call chain.
+     */
+    get sessionId(): string | undefined;
+    /** Best-effort bounded flush for short-lived hook subprocesses and tests. */
+    flushEvents(timeoutMs?: number): Promise<void>;
     /**
      * Configured user-subject namespace (from config, resolved at construction).
      * `resolveUserSubject` uses this as the SubjectSet namespace when the
@@ -91,31 +180,23 @@ export declare class OryAgentClient {
     get userSubjectNamespace(): string | undefined;
     /**
      * Set or update the human user principal. The user is the subject of
-     * permission checks but does not authenticate outgoing API calls.
-     * Pass `{}` (or fields set to undefined) to clear.
-     */
-    setUserPrincipal(principal: PrincipalIdentity): void;
-    /** Whether an admin API key is set for the Keto APIs (never exposes it). */
-    get hasAdminApiKey(): boolean;
-    /**
-     * Set or update the admin API key (an Ory Network project API key) used to
-     * authenticate the Keto Permission / Relationship APIs. Rebuilds those API
-     * instances when the key changes; a no-op update leaves them alone so test
-     * stubs survive. See {@link _adminApiKey} for why Keto needs a credential
-     * distinct from the agent's OAuth2 token.
+     * permission checks. Its token does not authenticate agent-attributed calls
+     * (OAuth2 / Frontend / Relationship), but it *is* the fallback credential for
+     * Keto permission reads when no agent token is present (see `buildApis`) — so
+     * a change to the user token rebuilds the API instances, otherwise the
+     * rehydrated user token would never reach the Permission API in a fresh
+     * subprocess. Pass `{}` (or fields set to undefined) to clear.
      */
-    setAdminApiKey(apiKey: string | undefined): void;
+    setUserPrincipal(principal: PrincipalIdentity, sessionId?: string | undefined): void;
     /**
      * Set or update the AI agent principal. The agent's token (when present)
-     * authenticates outgoing calls to the OAuth2 / Frontend APIs and carries
-     * audit attribution ("agent X acting on behalf of user Y"). Note the Keto
-     * Permission / Relationship APIs authenticate with {@link _adminApiKey}
-     * instead when one is set — Ory Network rejects OAuth2 tokens there.
-     * Rebuilds the underlying Ory API instances when the token actually changes
-     * so subsequent calls pick it up; otherwise leaves the API instances alone
-     * (so test stubs survive a no-op update).
+     * authenticates *every* outgoing Ory call — OAuth2 / Frontend and Keto
+     * (Permission / Relationship) alike — and carries audit attribution ("agent X
+     * acting on behalf of user Y"). Rebuilds the underlying Ory API instances when
+     * the token actually changes so subsequent calls pick it up; otherwise leaves
+     * the API instances alone (so test stubs survive a no-op update).
      */
-    setAgentPrincipal(principal: PrincipalIdentity): void;
+    setAgentPrincipal(principal: PrincipalIdentity, sessionId?: string | undefined): void;
     /**
      * Verify an existing session token. Returns cached result if available.
      */
@@ -128,93 +209,55 @@ export declare class OryAgentClient {
     /**
      * Check if a subject has permission to perform an action.
      *
-     * `options.spanAttributes` are merged into the `permission.check` trace
-     * span so callers can attach harness-side context (toolName, mcpServer,
+     * `options.activityAttributes` are merged into the `permission.check` activity
+     * event so callers can attach harness-side context (toolName, mcpServer,
      * etc.) that the wire-level `PermissionCheck` shape doesn't carry.
+     *
+     * `options.informational` marks a check whose `false` result is *not* a
+     * denial — e.g. the permission-mode probe, where "enforce not granted" simply
+     * selects `observe`. Such an event ends `ok` (the read succeeded) rather than
+     * `denied`, so a reader watching activity doesn't mistake a routine mode read
+     * for a blocked tool. The boolean is still recorded as the `allowed`
+     * attribute either way.
      */
     checkPermission(check: PermissionCheck, options?: {
-        spanAttributes?: Record<string, unknown>;
+        activityAttributes?: Record<string, unknown>;
+        informational?: boolean;
     }): Promise<PermissionResult>;
     /**
      * Check multiple permissions in a single request.
      *
-     * `options.spanAttributes` are merged into the `permission.batch_check`
-     * span — same purpose as `checkPermission`'s spanAttributes.
+     * `options.activityAttributes` are merged into the `permission.batch_check`
+     * activity event, for the same purpose as `checkPermission`'s attributes.
      */
     batchCheckPermissions(checks: PermissionCheck[], options?: {
-        spanAttributes?: Record<string, unknown>;
+        activityAttributes?: Record<string, unknown>;
     }): Promise<BatchPermissionResult>;
     /**
-     * Create a relation tuple in Keto. Idempotent: a 409 (tuple already
-     * exists) is swallowed and reported as success. All other errors are
-     * classified and re-thrown — callers wrap in fail-open semantics if
-     * the tuple is non-critical (e.g. audit-only delegation tracking).
-     *
-     * `options.spanAttributes` are merged into the `relationship.create`
-     * trace span so callers can attach context like `delegation: "user→agent"`.
-     */
-    createRelationship(check: PermissionCheck, options?: {
-        spanAttributes?: Record<string, unknown>;
-    }): Promise<{
-        created: boolean;
-        alreadyExisted: boolean;
-    }>;
-    /**
-     * True if the *exact* relation tuple already exists in Keto. Queries the
-     * relation-tuple listing API filtered by the tuple's own coordinates
-     * (namespace/object/relation + subject), so — unlike `checkPermission` —
-     * it does not follow subject-set expansion: it answers "is this literal
-     * tuple stored?", not "does this permission resolve?". Throws a classified
-     * {@link OryError} if the query itself fails.
-     */
-    relationshipExists(check: PermissionCheck): Promise<boolean>;
-    /**
-     * Idempotent relationship write. Keto's create API is **not** idempotent —
-     * `PUT /admin/relation-tuples` inserts a fresh row on every call (each with
-     * a new primary key) and never returns 409, so calling `createRelationship`
-     * on repeated bootstraps / session starts accumulates duplicate tuples.
-     * This reads the exact tuple first (via {@link relationshipExists}) and only
-     * writes when it is absent — which also self-heals if the tuple was deleted
-     * out of band.
+     * Record a delegation edge through the Ory Agent Security broker
+     * (`POST <agentSecurityUrl>/agent-security/v1/delegations:record`), authenticated
+     * with the process runtime credential. The broker constructs and writes the Keto tuple — the plugin
+     * sends only the semantic inputs, so the join-key/tuple encoding stays
+     * server-side and cannot drift here. Returns the node id + chain the broker
+     * assigned. Throws a classified {@link OryError} on any non-2xx; callers wrap
+     * in fail-open semantics (delegation is audit-only).
      *
-     * If the existence probe itself fails, the tuple is left untouched (we do
-     * not write blind, to avoid re-introducing duplicates when the read path is
-     * misbehaving) and the classified error is returned as `probeError`. Callers
-     * that must guarantee the grant exists (e.g. install-time bootstrap) can
-     * fall back to {@link createRelationship} when `probeError` is set.
-     */
-    ensureRelationship(check: PermissionCheck, options?: {
-        spanAttributes?: Record<string, unknown>;
-    }): Promise<{
-        created: boolean;
-        alreadyExisted: boolean;
-        probeError?: OryError;
-    }>;
-    /**
-     * Delete a relation tuple in Keto. Missing tuples (404) are treated as
-     * success so callers can call this idempotently when unwinding state.
-     */
-    deleteRelationship(check: PermissionCheck, options?: {
-        spanAttributes?: Record<string, unknown>;
-    }): Promise<{
-        deleted: boolean;
-        notFound: boolean;
-    }>;
-    /**
-     * Span attributes describing which principals were attached to the
-     * client when the span was started. Useful for correlating audit logs
-     * across the user/agent split.
+     * The broker exists only on hosted Ory; against the local dev stack the call
+     * returns 404 and callers treat it as a best-effort no-op.
      */
-    private principalSpanAttributes;
+    recordDelegation(input: RecordDelegationInput, options?: {
+        fetchImpl?: typeof fetch;
+        activityAttributes?: Record<string, unknown>;
+        agentToken?: string;
+        runtimeCredential?: RuntimeCredential;
+        signal?: AbortSignal;
+    }): Promise<RecordDelegationResult>;
     /**
-     * When a Keto call is auth-rejected while it was authenticated by something
-     * other than an Ory Network project API key (`ory_pat_…`) — e.g. a DCR
-     * OAuth2 access token — the credential *type* is wrong, not merely expired.
-     * Ory Network's Permission / Relationship APIs only accept a project API
-     * key. Emit an actionable hint so the failure isn't misread as a stale
-     * session (the generic `session_inactive` classification of the raw 401).
+     * Activity attributes describing which principals are attached to the
+     * client. Useful for correlating audit logs
+     * across the user/agent split.
      */
-    private warnIfKetoCredentialMismatch;
+    private principalActivityAttributes;
     /**
      * Classify an error from any Ory API call into a structured OryError.
      */
@@ -227,26 +270,20 @@ export declare class OryAgentClient {
      * Create a client from environment variables, falling back to the
      * shared config file at ~/.config/ory-agent-plugins/config.json.
      *
-     * Resolution order for projectUrl and apiKey:
-     *   1. Environment variables (ORY_PROJECT_URL, ORY_API_KEY)
+     * Resolution order for projectUrl:
+     *   1. Environment variables (ORY_PROJECT_URL / ORY_SDK_URL)
      *   2. Config file (~/.config/ory-agent-plugins/config.json)
      *   3. Placeholder (fail-open pass-through mode)
      */
-    static fromEnv(harness: string): OryAgentClient;
+    static fromEnv(harness: string, runtime?: Pick<OryAgentConfig, "runtimeRequestAuthenticator" | "runtimeSubject">): OryAgentClient;
 }
-/** Default debug-log path under the shared per-harness data dir. */
+/** Default unified activity/debug log path under the shared per-harness data dir. */
 export declare const DEFAULT_DEBUG_LOG_FILENAME = "ory-agent-debug.log";
-/** Default trace (NDJSON) path under the shared per-harness data dir. */
-export declare const DEFAULT_TRACE_FILENAME = "ory-agent-trace.ndjson";
 /**
- * Debug log path. Only written when `ORY_AGENT_DEBUG=true` (the logger gates
- * on that); defaulting the path just means an enabled debug session lands in a
- * file automatically — important for subprocess-hook harnesses whose stderr
- * the harness may swallow.
+ * Unified activity/debug log path. Activity is always appended; verbose
+ * debug/info/warn/error entries are appended only when `ORY_AGENT_DEBUG=true`.
  */
 export declare function resolveDebugLogPath(harness: string): string | undefined;
-/** Trace (NDJSON) path. Written on every recorded span when set. */
-export declare function resolveTraceFilePath(harness: string): string | undefined;
 /**
  * Pull the Ory backend request ID from a response headers bag (axios returns
  * lowercase header names). Returns undefined when not present.