@caracalai/sdk 0.1.6-rc.3 → 0.2.0-rc.2

package/dist/advanced.d.ts

@@ -1,8 +1,13 @@
-export * from './envelope.js';
-export * from './context.js';
-export * from './coordinator.js';
-export * from './primitives.js';
-export * from './http.js';
+export { HeaderAuthorization, HeaderTraceparent, HeaderTracestate, HeaderBaggage, BaggageAgentSession, BaggageDelegationEdge, BaggageParentEdge, BaggageSession, BaggageHop, MaxHop, formatTraceparent, parseTraceparent, encodeBaggage, parseBaggage, fromHeaders, decodeEnvelope, encodeEnvelope, toHeaders, } from './envelope.js';
+export type { Envelope, HeaderGetter, HeaderSetter } from './envelope.js';
+export { current, captureContext, bind, withOverrides, toEnvelope, fromEnvelope, fromVerifiedEnvelope, describeAuthority, } from './context.js';
+export type { CaracalContext, AuthoritySummary, VerifiedClaims } from './context.js';
+export { CoordinatorError, Lifecycle, startCoordinatorSession, terminateSession, acquireSessionLease, heartbeatSession, createDelegation, revokeDelegation, getInboundDelegation, listInboundDelegations, } from './coordinator.js';
+export type { CoordinatorCallEvent, CoordinatorClient, SessionStatus, DelegationConstraints, StartSessionRequest, StartSessionResponse, DelegationRequest, DelegationResponse, HeartbeatResponse, InboundDelegation, } from './coordinator.js';
+export { Authority, session, delegate, acceptDelegation, startSession, attachSession } from './primitives.js';
+export type { AuthorityMode, SessionInput, DelegateInput, Delegation, StartSessionInput, SessionHandle, AttachSessionInput, } from './primitives.js';
+export { caracalContextMiddleware, caracalFastifyHook } from './http.js';
+export type { IncomingLike, FastifyRequestLike, ServerResponseLike, FastifyReplyLike, ConnectMiddleware } from './http.js';
 export { Caracal } from './client.js';
-export type { CaracalConfig, SpawnOptions, DelegateOptions, LifecycleHook, RootOptions, TokenSource, ClientSecretOptions, } from './client.js';
+export type { CaracalConfig, SessionOptions, DelegateOptions, LifecycleHook, CallOptions, TokenSource, ClientCredentials, CredentialsResolver, ClientSecretOptions, } from './client.js';
 //# sourceMappingURL=advanced.d.ts.map

package/dist/advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAUA,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,YAAY,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EACf,aAAa,EACb,WAAW,EACX,WAAW,EACX,mBAAmB,GACpB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACzE,OAAO,EACL,OAAO,EACP,cAAc,EACd,IAAI,EACJ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AACpF,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC7G,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACxE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC1H,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAA"}

package/dist/advanced.js

@@ -7,10 +7,10 @@
  * "@caracalai/sdk" entrypoint; reach for these when building a transport
  * adapter or framework integration.
  */
-export * from './envelope.js';
-export * from './context.js';
-export * from './coordinator.js';
-export * from './primitives.js';
-export * from './http.js';
+export { HeaderAuthorization, HeaderTraceparent, HeaderTracestate, HeaderBaggage, BaggageAgentSession, BaggageDelegationEdge, BaggageParentEdge, BaggageSession, BaggageHop, MaxHop, formatTraceparent, parseTraceparent, encodeBaggage, parseBaggage, fromHeaders, decodeEnvelope, encodeEnvelope, toHeaders, } from './envelope.js';
+export { current, captureContext, bind, withOverrides, toEnvelope, fromEnvelope, fromVerifiedEnvelope, describeAuthority, } from './context.js';
+export { CoordinatorError, Lifecycle, startCoordinatorSession, terminateSession, acquireSessionLease, heartbeatSession, createDelegation, revokeDelegation, getInboundDelegation, listInboundDelegations, } from './coordinator.js';
+export { Authority, session, delegate, acceptDelegation, startSession, attachSession } from './primitives.js';
+export { caracalContextMiddleware, caracalFastifyHook } from './http.js';
 export { Caracal } from './client.js';
 //# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,OAAO,EACP,cAAc,EACd,IAAI,EACJ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,kBAAkB,CAAA;AAazB,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAU7G,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAExE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA"}

package/dist/client.d.ts

@@ -1,64 +1,249 @@
-import { type CaracalContext } from './context.js';
+import { type CaracalContext, type VerifiedClaims } from './context.js';
 import { type HeaderGetter } from './envelope.js';
-import { type CoordinatorClient } from './coordinator.js';
-import { type Grant, type ServiceAgent } from './primitives.js';
-import { type DelegationConstraints } from './coordinator.js';
+import { type Authority, type Delegation, type SessionHandle } from './primitives.js';
+import { type CoordinatorCallEvent, type CoordinatorClient, type DelegationConstraints } from './coordinator.js';
 import type { JsonObject } from './json.js';
+import { type ApprovalState, type OAuthEvent } from '@caracalai/oauth';
 export interface ResourceBinding {
     resourceId: string;
     upstreamPrefix: string;
 }
 export type TokenSource = () => string | Promise<string>;
-export interface CaracalConfig {
-    coordinator: CoordinatorClient;
+/** The credential triple a client-secret client acts as. */
+export interface ClientCredentials {
     zoneId: string;
     applicationId: string;
+    clientSecret: string;
+}
+/**
+ * Resolves the current client credentials at each control-plane operation, so
+ * a secret rotated by a secrets manager or a credential provisioned after the
+ * process started is simply presented on the next exchange - the client is
+ * never rebuilt. Returning null or undefined means no usable credential exists
+ * yet; the operation fails closed with CredentialsUnavailableError.
+ */
+export type CredentialsResolver = () => ClientCredentials | null | undefined | Promise<ClientCredentials | null | undefined>;
+/** A control-plane operation ran while the credentials resolver had no usable credential; the operation fails closed. */
+export declare class CredentialsUnavailableError extends Error {
+    constructor();
+}
+/** A minted resource mandate and the lifetime the STS granted it. */
+export interface MintedMandate {
+    token: string;
+    expiresInSeconds: number;
+}
+/** A federated Subject and the mandate proving it. */
+export interface FederatedSubject {
+    /** Anchors Coordinator attribution when passed as subjectAuthorityRecordId; it does not alone propagate the user sub to later mints. */
+    subjectAuthorityRecordId: string;
+    /** The Subject mandate used for user-facing flows; it carries no resource authority. */
+    token: string;
+    expiresInSeconds: number;
+}
+/**
+ * Client-secret credential surface behind a configured Caracal client:
+ * resolves the acting identity, invalidates the cached lifecycle token after
+ * a server-side rejection, and mints scoped resource mandates for gateway
+ * calls. Integrators never construct one: `fromClientSecret` (and profile or
+ * environment detection) wires it into the client; the interface exists so
+ * the credential surface can be observed and faked in tests.
+ */
+export interface ClientSecretExchanger {
+    invalidate(): void;
+    /** The zone and application the credentials currently resolve to; fails closed when unresolved. */
+    identity(): Promise<{
+        zoneId: string;
+        applicationId: string;
+        credentialGeneration?: string;
+    }>;
+    mintMandate(resourceId: string, scopes: string[], opts?: {
+        sessionId?: string;
+        delegationId?: string;
+        ttlSeconds?: number;
+        approvalId?: string;
+        signal?: AbortSignal;
+        cache?: boolean;
+    }): Promise<MintedMandate>;
+    /** Exchanges an end user's external identity token for a Subject mandate; never cached. */
+    federateSubject(idToken: string, opts?: {
+        ttlSeconds?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<MintedMandate>;
+    waitForApproval(approvalId: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<ApprovalState>;
+    /** Attaches the observability sink token-exchange events report to. */
+    onEvent(cb: (event: OAuthEvent) => void): void;
+}
+export interface CaracalConfig {
+    coordinator: CoordinatorClient;
+    /** Static identity; omitted for a credentials-resolver client, which resolves it through the exchanger per operation. */
+    zoneId?: string;
+    applicationId?: string;
     subjectToken?: string;
     tokenSource?: TokenSource;
+    exchanger?: ClientSecretExchanger;
     gatewayUrl?: string;
     resources?: ResourceBinding[];
+    /** Default TTL for sessions run with session(); a session started with startSession lives by its heartbeat lease instead. */
     defaultTtlSeconds?: number;
+    /** Receives SDK operational warnings (lease loss, cleanup failures, boundary misconfiguration); defaults to console.warn. */
+    logger?: (message: string, err?: unknown) => void;
 }
-export interface SpawnOptions {
-    grant?: Grant;
+export interface SessionOptions {
+    authority?: Authority;
     ttlSeconds?: number;
-    subjectSessionId?: string;
-    parentId?: string;
+    /** Authority record attached to the Session for Coordinator attribution; it does not alone propagate the user sub to later mints. */
+    subjectAuthorityRecordId?: string;
+    /** Federated Subject mandate proving control of subjectAuthorityRecordId. */
+    subjectAuthorityRecordToken?: string;
+    /** Session to parent under; defaults to the session bound on the calling context. */
+    parentSessionId?: string;
+    /** What this session is for, in operator terms; recorded as metadata.task and shown wherever the session is inspected. */
+    task?: string;
     metadata?: JsonObject;
+    /** Role labels the zone's grant policy matches (`input.principal.labels`); descriptive for policy and audit, never grants. */
     labels?: string[];
+    /** W3C trace id (32 lowercase hex characters) to correlate the session under; generated when absent. */
     traceId?: string;
+    /**
+     * Optional stable operation identifier from a queue, webhook, workflow, or scheduler.
+     * Reusing it with the same inputs replays the Coordinator's session-creation result;
+     * changed inputs fail with a conflict. It does not suppress this callback or make
+     * downstream side effects exactly once. Ordinary code should omit it.
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
 }
-export interface ServiceOptions {
-    grant?: Grant;
+export interface StartSessionOptions {
+    authority?: Authority;
     ttlSeconds?: number;
-    subjectSessionId?: string;
-    parentId?: string;
+    /** Authority record attached to the Session for Coordinator attribution; it does not alone propagate the user sub to later mints. */
+    subjectAuthorityRecordId?: string;
+    /** Federated Subject mandate proving control of subjectAuthorityRecordId. */
+    subjectAuthorityRecordToken?: string;
+    /** Session to parent under; defaults to the session bound on the calling context. */
+    parentSessionId?: string;
+    /** What this session is for, in operator terms; recorded as metadata.task and shown wherever the session is inspected. */
+    task?: string;
     metadata?: JsonObject;
+    /** Role labels the zone's grant policy matches (`input.principal.labels`); descriptive for policy and audit, never grants. */
     labels?: string[];
+    /** W3C trace id (32 lowercase hex characters) to correlate the session under; generated when absent. */
     traceId?: string;
+    /** Optional stable operation identifier; see SessionOptions.idempotencyKey for its creation-only guarantee. */
+    idempotencyKey?: string;
+    /**
+     * Auto-heartbeat cadence. Leave unset to derive it from the server lease;
+     * a positive value fixes the interval; zero or a negative value disables
+     * the background timer, leaving the lease to manual heartbeat calls.
+     */
     heartbeatIntervalMs?: number;
+    /** Called once if the coordinator reports the session permanently gone. */
+    onLeaseLost?: (err: unknown) => void;
+    /** Called when the coordinator reports a different service-session state. */
+    onStateChange?: (status: string) => void;
+    signal?: AbortSignal;
 }
 export interface DelegateOptions {
-    to: string;
-    toApplicationId: string;
+    toSessionId: string;
+    /** Receiving application; defaults to the caller's own application for same-app delegation. */
+    toApplicationId?: string;
     resourceId?: string;
     scopes: string[];
     constraints?: DelegationConstraints;
-    ttlSeconds?: number;
+    ttlSeconds: number;
+    signal?: AbortSignal;
 }
 export type LifecycleHook = (ctx: CaracalContext) => void | Promise<void>;
-export interface RootOptions {
-    allowRoot?: boolean;
+/**
+ * One delegation presentation by this client. Emitted whenever
+ * acceptDelegation binds a delegation - and with `ok: false` when an
+ * up-front validation rejects it - so a forensic consumer can correlate
+ * which workload presented which delegation on which session.
+ */
+export interface DelegationAcceptEvent {
+    type: 'delegation.accept';
+    delegationId: string;
+    sessionId?: string;
+    validated: boolean;
+    ok: boolean;
+    durationMs: number;
+}
+/** Control-plane operation reported to onEvent subscribers: a token exchange, an approval wait, a coordinator call, or a delegation acceptance. */
+export type CaracalEvent = OAuthEvent | CoordinatorCallEvent | DelegationAcceptEvent;
+export type EventHook = (event: CaracalEvent) => void;
+/** Identity selection for calls made outside a bound session context. */
+export interface CallOptions {
+    /** Run the call as the application's own identity instead of a bound session; explicit opt-in. */
+    asApplication?: boolean;
+}
+/**
+ * Transport behavior options. `scopes` switches gateway-routed requests from
+ * the raw subject token to a scoped resource mandate minted for the routed
+ * resource and the bound session identity; requires a client-secret
+ * configuration. `approvalId` retries an approval-gated mint so the request
+ * proceeds once an authenticated approver has satisfied the hold. `timeoutMs`
+ * bounds every request the transport sends when the caller supplies no signal
+ * of its own (combined when both are present). `propagation` controls where
+ * the context envelope (traceparent, baggage) is written: 'always' (the
+ * default) propagates to every host so downstream Caracal-aware services can
+ * rebind context; 'gateway-only' keeps the caracal.* correlation ids off
+ * third-party hosts.
+ */
+export interface TransportOptions extends CallOptions {
+    scopes?: string[];
+    approvalId?: string;
+    timeoutMs?: number;
+    propagation?: 'always' | 'gateway-only';
+}
+/** Optional mint inputs: a TTL override, the approval id for retrying an approval-gated mint, an explicit context, and an abort signal. */
+export interface MandateOptions {
+    ttlSeconds?: number;
+    approvalId?: string;
+    ctx?: CaracalContext;
+    signal?: AbortSignal;
+}
+/**
+ * Application transport behavior. `scopes` is the authority every request
+ * presents; `labels` mark the sessions each mint cycle starts and are the
+ * role labels the zone's grant policy matches - unset, they default to the
+ * application id, the same default role `ensureGrants` authors, so a grant
+ * and its transport align without either naming a role; `mandateTtlSeconds`
+ * bounds each minted mandate (the backing sessions outlive it by a small
+ * buffer).
+ */
+export interface ApplicationTransportOptions {
+    scopes: string[];
+    labels?: string[];
+    mandateTtlSeconds?: number;
+    approvalId?: string;
+    timeoutMs?: number;
+}
+export interface BindOptions extends CallOptions {
+    verify?: (token: string) => void | VerifiedClaims | Promise<void | VerifiedClaims>;
 }
 export interface ClientSecretOptions {
     coordinatorUrl: string;
     stsUrl: string;
-    zoneId: string;
-    applicationId: string;
-    clientSecret: string;
-    resources: Array<string | ResourceBinding>;
+    /** Static credential triple; pass `credentials` instead when the credential is rotated or provisioned at runtime. */
+    zoneId?: string;
+    applicationId?: string;
+    clientSecret?: string;
+    /** Dynamic credential source, resolved per operation; exactly one of this or the static triple is required. */
+    credentials?: CredentialsResolver;
+    /**
+     * Resources this client mints lifecycle tokens for and routes through the
+     * Gateway. Optional for a client that only runs application transports,
+     * which mint per resource; session and lifecycle paths require at least one.
+     */
+    resources?: Array<string | ResourceBinding>;
     gatewayUrl?: string;
     scope?: string;
+    /** Seeds CaracalConfig.defaultTtlSeconds for sessions run with session(). */
+    defaultTtlSeconds?: number;
     fetchImpl?: typeof fetch;
 }
 export interface CaracalOptions {
@@ -66,14 +251,21 @@ export interface CaracalOptions {
     configPath?: string;
     clientSecret?: Partial<ClientSecretOptions>;
 }
-export interface GatewayRequest {
+export interface GatewayTarget {
     url: string;
     headers: Record<string, string>;
 }
 export declare class Caracal {
     readonly config: CaracalConfig;
-    private agentStartHooks;
-    private agentEndHooks;
+    private sessionStartHooks;
+    private sessionEndHooks;
+    private eventHooks;
+    private appAuthorities;
+    private appInflight;
+    private appGeneration;
+    private appProvisionTail;
+    private closed;
+    private unverifiedBoundaryWarned;
     /**
      * Creates a Caracal client. With no arguments, credentials are
      * auto-detected from `CARACAL_CONFIG`, the default generated profile, or
@@ -84,41 +276,261 @@ export declare class Caracal {
     static fromEnv(env?: NodeJS.ProcessEnv): Caracal;
     static fromClientSecret(opts: ClientSecretOptions): Caracal;
     static fromConfig(path?: string, env?: NodeJS.ProcessEnv): Caracal;
+    /**
+     * Releases client-held state: cached application mandates and their
+     * in-flight mint cycles are dropped, the credential exchanger's cached
+     * lifecycle token is invalidated, and the sessions backing released
+     * application transports are terminated best-effort - any that termination
+     * misses retire on their own TTL. The client stays usable; the next call
+     * simply mints fresh state.
+     */
     close(): Promise<void>;
-    spawn<T>(fn: () => Promise<T>, opts?: SpawnOptions): Promise<T>;
-    spawnService(opts?: ServiceOptions): Promise<ServiceAgent>;
-    delegate<T>(opts: DelegateOptions, fn: () => Promise<T>): Promise<T>;
+    private warnLog;
+    private ensureOpen;
+    /**
+     * The zone and application this client acts as: the static configuration
+     * when present, otherwise resolved through the credentials source, which
+     * fails closed while no usable credential exists. Useful for logging and
+     * metric labels.
+     */
+    identity(): Promise<{
+        zoneId: string;
+        applicationId: string;
+    }>;
+    /**
+     * Run fn inside a governed session: a bounded identity Caracal establishes
+     * around whatever fn executes - an AI agent step, a job, a tool call, any
+     * code. The session binds delegated authority, records audit attribution,
+     * and is retired when fn returns. Pass `authority: Authority.narrow([...])`
+     * to bound the session to a subset of the caller's scopes.
+     *
+     * @example
+     * ```ts
+     * const summary = await caracal.session(async (ctx) => {
+     *   log.info({ sessionId: ctx.sessionId }, 'triage run started')
+     *   const res = await caracal.fetch('resource://pipernet', '/tickets')
+     *   return res.json()
+     * }, { labels: ['ticket-triage'] })
+     * ```
+     *
+     * @example Narrowed child session
+     * ```ts
+     * await caracal.session(work, {
+     *   authority: Authority.narrow(['tickets:read'], { resourceId: 'resource://pipernet' }),
+     * })
+     * ```
+     */
+    session<T>(fn: (ctx: CaracalContext) => Promise<T>, opts?: SessionOptions): Promise<T>;
+    /**
+     * Start a governed session that outlives a block: the returned handle keeps
+     * the session's lease renewed and the holder retires it with close.
+     */
+    startSession(opts?: StartSessionOptions): Promise<SessionHandle>;
+    /**
+     * Delegate a slice of the current session's authority to an existing peer
+     * session and return the created delegation. The receiver defaults to the
+     * caller's own application; name toApplicationId only for cross-application
+     * delegation. The receiving session accepts it with acceptDelegation.
+     */
+    delegate(opts: DelegateOptions): Promise<Delegation>;
+    /**
+     * Run fn under a delegation received from a peer: the current session
+     * context is rebound so token exchanges inside fn present the delegation.
+     * Acceptance is local; the STS re-validates the delegation on every mint,
+     * so a wrong or revoked id fails at first use. Pass `{ validate: true }`
+     * to check the delegation up front instead: the coordinator's inbound
+     * listing for this session must hold it live, so a mistyped or already
+     * revoked id fails here with a targeted error.
+     */
+    acceptDelegation<T>(delegationId: string, fn: () => Promise<T>, opts?: {
+        validate?: boolean;
+    }): Promise<T>;
+    /**
+     * Re-attach to a service session that already exists - typically after a
+     * process restart, using a session id the previous holder persisted (for
+     * example from SessionHandle.sessionId). The session is validated with an
+     * immediate lease renewal, and the returned handle renews and retires it
+     * exactly like one from startSession.
+     */
+    attachSession(sessionId: string, opts?: {
+        heartbeatIntervalMs?: number;
+        onLeaseLost?: (err: unknown) => void;
+    }): Promise<SessionHandle>;
     bind<T>(ctx: CaracalContext, fn: () => Promise<T>): Promise<T>;
-    onAgentStart(cb: LifecycleHook): void;
-    onAgentEnd(cb: LifecycleHook): void;
+    onSessionStart(cb: LifecycleHook): void;
+    onSessionEnd(cb: LifecycleHook): void;
+    /**
+     * Subscribes to control-plane operation events: token exchanges (with cache
+     * outcome), approval waits, and coordinator calls, each carrying outcome and
+     * duration. Bridge them to any metrics or tracing system; a hook that throws
+     * is ignored and never disturbs the operation that emitted the event.
+     * Returns a disposer that unsubscribes the hook.
+     */
+    onEvent(cb: EventHook): () => void;
+    private emitEvent;
     private fire;
     current(): CaracalContext | undefined;
-    headers(opts?: RootOptions): Record<string, string>;
-    headersAsync(opts?: RootOptions): Promise<Record<string, string>>;
-    bindFromHeaders<T>(headers: Record<string, string | string[] | undefined> | HeaderGetter, fn: () => Promise<T>, opts?: RootOptions): Promise<T>;
     /**
-     * Returns a fetch-shaped function that injects the Caracal envelope (traceparent
-     * + baggage) onto outbound requests and, for gateway-routed calls, replaces the
-     * `Authorization` header with the current subject token. Pass to any provider
-     * SDK that accepts a custom fetch.
+     * Envelope headers plus the bearer credential for the current context.
+     * The context token is returned as bound; long-lived holders needing a
+     * refreshed own-credential token use headersAsync. Calling as the
+     * application's own identity requires `{ asApplication: true }`.
+     */
+    headers(opts?: CallOptions): Record<string, string>;
+    /**
+     * Async variant of headers. For contexts this process established from its
+     * own credentials, the bearer is resolved fresh through the token source so
+     * long-lived holders never present an expired token; inbound contexts stay
+     * pinned to the caller's token.
+     */
+    headersAsync(opts?: CallOptions): Promise<Record<string, string>>;
+    bindFromHeaders<T>(headers: Headers | Record<string, string | string[] | undefined> | HeaderGetter, fn: () => Promise<T>, opts?: BindOptions): Promise<T>;
+    /**
+     * Returns a fetch-shaped function that injects the Caracal context envelope
+     * (traceparent, tracestate, baggage) onto outbound requests, merging with any
+     * headers the caller or an OpenTelemetry SDK already set. The bearer is
+     * attached only to gateway-routed calls, where the Gateway terminates it at
+     * the trust boundary: a scoped mandate when `scopes` is set, otherwise the
+     * context's subject token. No default timeout is applied unless `timeoutMs`
+     * is set; a caller-supplied `init.signal` still applies (combined when both
+     * are present). Pass to any provider SDK that accepts a custom fetch.
+     *
+     * @example Hand the transport to a provider SDK
+     * ```ts
+     * const openai = new OpenAI({
+     *   baseURL: 'https://api.pipernet.example/v1',
+     *   apiKey: 'unused-gateway-injects-credentials',
+     *   fetch: caracal.transport({ scopes: ['chat:complete'] }),
+     * })
+     * ```
+     */
+    transport(opts?: TransportOptions): typeof fetch;
+    /**
+     * Resolves the bearer for a gateway-bound request: a scoped mandate when
+     * scopes are set and the routed resource is known, a fresh token from the
+     * token source for contexts this process established from its own
+     * credentials, the pinned context token for inbound-bound contexts, or the
+     * application token when running as the application itself.
+     */
+    private gatewayToken;
+    /**
+     * Mints a resource mandate for the current session: a short-lived token
+     * audienced to `resourceId` and narrowed to `scopes`, carrying the session
+     * and delegation of the bound context. The STS evaluates policy against
+     * that session's authority, so a narrowed child can mint only what its
+     * delegation allows. Results are cached per resource, scope set, and
+     * session identity, and refreshed before expiry.
+     *
+     * When a scope is approval-gated this throws ApprovalRequiredError; retry
+     * with `approvalId` set to the returned approval id once an authenticated
+     * approver has satisfied it. Requires a client-secret configuration.
      */
-    transport(opts?: RootOptions): typeof fetch;
-    gatewayRequest(resourceId: string, path?: string): GatewayRequest;
+    mintMandate(resourceId: string, scopes: string[], opts?: MandateOptions): Promise<MintedMandate>;
+    /**
+     * Exchange an end user's identity token from a zone-trusted external issuer
+     * for the Subject's Caracal Authority record. The returned subjectAuthorityRecordId
+     * anchors governed work to that user (`session(fn, { subjectAuthorityRecordId })`),
+     * and the returned token is the user's own mandate for user-facing flows
+     * such as approval decisions. Never cached: each federation is an explicit
+     * identity event, recorded in the audit stream. Requires a client-secret
+     * configuration and a subject issuer registered on the zone.
+     */
+    federateSubject(idToken: string, opts?: {
+        ttlSeconds?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<FederatedSubject>;
+    /**
+     * Long-polls an approval until an approver decides it, it
+     * expires, or the timeout elapses. Returns the final lifecycle state:
+     * 'approved' means retrying the mint with `approvalId` set will succeed;
+     * 'rejected', 'expired', and 'consumed' are terminal; 'pending' means the
+     * timeout elapsed with no decision and waiting again is safe. Pass `signal`
+     * to abort the wait early.
+     */
+    waitForApproval(approvalId: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<ApprovalState>;
+    /**
+     * Runs an approval-gated operation end to end. fn is invoked once; when it
+     * throws ApprovalRequiredError the client long-polls the approval and, on
+     * approval, invokes fn again with the approval id so the retried mint
+     * consumes the decision. Any other outcome (rejected, expired, consumed, or
+     * the wait timing out) rethrows the original ApprovalRequiredError, whose
+     * approvalId lets the caller resume the wait later.
+     *
+     * @example
+     * ```ts
+     * const mandate = await caracal.withApproval((approvalId) =>
+     *   caracal.mintMandate('resource://pipernet', ['funds:transfer'], { approvalId }),
+     * )
+     * ```
+     */
+    withApproval<T>(fn: (approvalId?: string) => Promise<T>, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    gatewayRequest(resourceId: string, path?: string): GatewayTarget;
     /**
      * One-call happy path: sends `init` to `path` on the given resource through the
-     * Gateway with Caracal context and authority injected. Equivalent to building a
-     * `gatewayRequest` and calling it with `transport`. The resource header always
-     * wins over any caller-supplied `X-Caracal-Resource`.
+     * Gateway with Caracal context and authority injected. Accepts the transport
+     * options inline: pass `scopes` to authorize with a scoped resource mandate,
+     * `approvalId` to retry an approval-gated call once its hold is satisfied, and
+     * `asApplication` to call as the application's own identity. The resource header
+     * always wins over any caller-supplied `X-Caracal-Resource`. No default timeout
+     * is applied; pass `timeoutMs` or `signal` (e.g. AbortSignal.timeout) to bound a call.
+     */
+    fetch(resourceId: string, path?: string, init?: RequestInit & TransportOptions): Promise<Response>;
+    /**
+     * A fetch pinned to one resource, running as the application's own
+     * identity rather than a bound session context: each mint cycle bootstraps
+     * a lifecycle token, starts a source/target session pair, narrows the
+     * target to `scopes` on the resource over a delegation, and mints a fresh
+     * single-use mandate for every request. Authority cycles are cached per
+     * resolved identity, resource, scope set, effective labels, and mandate
+     * TTL, then re-provisioned on a fresh session pair before expiry; sessions from
+     * a failed cycle are terminated best-effort. Requests already addressed to
+     * the Gateway pass through unchanged; other absolute URLs are rewritten
+     * onto it. When a scope is approval-gated the request rejects with
+     * ApprovalRequiredError. Requires a client-secret configuration.
+     *
+     * Provisioning costs four control-plane calls (bootstrap mint, two session
+     * spawns, one delegation) roughly once per TTL. Every Gateway request then
+     * performs one uncached final mint so its replay-protected JTI is unique.
+     *
+     * @example Application-identity LLM transport
+     * ```ts
+     * const llm = new OpenAI({
+     *   baseURL: 'https://api.pipernet.example/v1',
+     *   apiKey: 'unused-gateway-injects-credentials',
+     *   fetch: caracal.applicationTransport('resource://pipernet', { scopes: ['chat:complete'] }),
+     * })
+     * ```
      */
-    fetch(resourceId: string, path?: string, init?: RequestInit, opts?: RootOptions): Promise<Response>;
+    applicationTransport(resourceId: string, opts: ApplicationTransportOptions): typeof fetch;
+    private appAuthority;
+    private withAppProvisioning;
+    private appAuthorityCycle;
+    private retireAppAuthorities;
     private routeThroughGateway;
+    /** Reports whether the request is already addressed to the Gateway origin, where the subject token terminates. */
+    private targetsGateway;
     /**
-     * Binds Caracal context after a verifier boundary. This does not verify JWT
-     * signatures, audience, scopes, token use, or revocation.
+     * Binds Caracal context at the inbound request boundary. Pass `verify` to
+     * enforce the bearer token before binding; without it this middleware only
+     * propagates context and must sit behind a verifier boundary. Boundary
+     * failures (missing token, verify rejection) answer 401 directly; errors
+     * thrown by downstream handlers still flow to the framework error path.
      */
-    contextMiddleware(opts?: RootOptions): (req: {
+    contextMiddleware(opts?: BindOptions): (req: {
         headers: Record<string, string | string[] | undefined>;
-    }, _res: unknown, next: (err?: unknown) => void) => void;
+    }, res: {
+        statusCode: number;
+        setHeader(name: string, value: string): void;
+        end(body?: string): void;
+    }, next: (err?: unknown) => void) => void;
+    private invalidate;
     private rootTokenSync;
     private rootToken;
 }