@loomcycle/client 1.125.0 → 1.126.0

package/dist/client.d.ts

@@ -24,11 +24,18 @@
  * full mapping table.
  */
 import { InteractiveSession } from "./interactive.js";
+import { LoomcycleOAuth } from "./oauth.js";
 import { ClientToolHost, type ConnectClientToolsOptions } from "./client-tools.js";
-import type { ChangeFeedFrame, StreamChangesOptions, CredentialListResponse, CredentialMeta, CryptoKeyEncoding, CryptoKeyExport, CryptoKeyExternal, CryptoKeyType, CryptoRequest, CryptoResultByOp, DecideRequest, DecideResponse, DecisionModelsResponse, CredentialScope, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResult, Agent, AgentEvent, AgentList, CancelAgentResult, ClientOptions, ContinueOptions, RunOverrideOptions, EffectiveConfigResponse, RunFileInput, RunInboxDownload, AgentOverridableResponse, RetuneRunResponse, RunConfigResponse, RunPromptResponse, CreateSnapshotOptions, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureHookDefOptions, EnsureHookDefResult, HookDefInput, HookDefOverlay, HookDefRowResponse, CreateDefOptions, ForkDefOptions, HookDefForkOverlay, ScheduleDefInput, ScheduleDefOverlay, ScheduleDefRowResponse, WebhookDefInput, WebhookDefOverlay, WebhookDefRowResponse, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, InterruptListResponse, InterruptStatus, ListUserAgentsOptions, WalkRunsPage, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ListTeamChannelsOptions, PeekTeamChannelOptions, ReleaseTeamChannelOptions, TeamChannelPeekResult, TeamChannelReleaseResult, TeamChannelsResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, ReleaseChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, ListUserTokensResponse, RunnableAgentsResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEmbedStatsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryBackfillResponse, MemoryPurgeResponse, MemoryReembedResponse, MemoryScopeIDsResponse, MemoryScopesResponse, MemorySearchInput, MemorySearchResponse, PauseResult, RetentionOverride, PersistentVolumesResponse, EphemeralVolumesResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, CompactRunResult, RunTreeDeletion, ReplaySessionResult, CancelTurnResult, ReviewRunResult, RunBatchOptions, RunBatchResult, RunOptions, ConfiguredRun, ConfiguredRunPatch, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, CreatedTeam, CreateTeamOptions, DefNamesResponse, ForkTeamOptions, ModelAliasesResponse, OperatorTokenDefNamesResponse, ProviderModelsResponse, RoutingResponse, ScheduleListResponse, SchedulePauseResult, ScheduleRunNowResult, ScheduleStateView, ListTeamsResponse, PromotedTeam, RetiredTeam, TeamBreakpoints, TeamDefDetail, TeamRunDetached, TeamRunTarget, TeamVerification, TeamDraft, TeamDraftVerification, TeamVersionList, TeamDiagram, TeamRunResult, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, EvaluationSubmitInput, EvaluationGetInput, EvaluationListForRunInput, EvaluationListForDefInput, EvaluationAggregateInput, EvaluationInput, EvaluationSubmitResult, EvaluationRecord, EvaluationListForRunResult, EvaluationListForDefResult, EvaluationAggregate, TranscriptResponse, WhoamiResponse, UsageDimension, UsageReportResponse, TokenLimit, TokenLimitsResponse, ConfigResponse, SetTokenLimitRequest, AclBinding, AclBindingListResponse, AclCatalog, AclDefInput, AclDefListResponse, AclDefNamesResponse, AclDefRow, AclRule, AclValidateResult, AuthzDecision, AuthzEvaluationRequest, AuthzEvaluationsRequest, AuthzEvaluationsResponse, AuthzExplainResponse, AuthzSimulateRequest, AuthzSimulateResponse, CreateAclBindingBody, CreateGroupBody, GroupDetail, GroupEffective, GroupListResponse, GroupMemberChange, GroupMemberKind, GroupRow } from "./types.js";
+import type { ChangeFeedFrame, StreamChangesOptions, CredentialListResponse, CredentialMeta, CryptoKeyEncoding, CryptoKeyExport, CryptoKeyExternal, CryptoKeyType, CryptoRequest, CryptoResultByOp, DecideRequest, DecideResponse, DecisionModelsResponse, CredentialScope, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResult, Agent, AgentEvent, AgentList, CancelAgentResult, ClientOptions, ContinueOptions, RunOverrideOptions, EffectiveConfigResponse, RunFileInput, RunInboxDownload, AgentOverridableResponse, RetuneRunResponse, RunConfigResponse, RunPromptResponse, CreateSnapshotOptions, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureHookDefOptions, EnsureHookDefResult, HookDefInput, HookDefOverlay, HookDefRowResponse, CreateDefOptions, ForkDefOptions, HookDefForkOverlay, ScheduleDefInput, ScheduleDefOverlay, ScheduleDefRowResponse, WebhookDefInput, WebhookDefOverlay, WebhookDefRowResponse, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, InterruptListResponse, InterruptStatus, ListUserAgentsOptions, WalkRunsPage, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ListTeamChannelsOptions, PeekTeamChannelOptions, ReleaseTeamChannelOptions, TeamChannelPeekResult, TeamChannelReleaseResult, TeamChannelsResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, ReleaseChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, ListUserTokensResponse, UserIdentitiesResponse, AuthGateListResponse, CreateInviteBody, CreatedInvite, AuthInviteListResponse, CreatedPasswordReset, GateIdentitiesResponse, GateTenantStatus, RunnableAgentsResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEmbedStatsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryBackfillResponse, MemoryPurgeResponse, MemoryReembedResponse, MemoryScopeIDsResponse, MemoryScopesResponse, MemorySearchInput, MemorySearchResponse, PauseResult, RetentionOverride, PersistentVolumesResponse, EphemeralVolumesResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, CompactRunResult, RunTreeDeletion, ReplaySessionResult, CancelTurnResult, ReviewRunResult, RunBatchOptions, RunBatchResult, RunOptions, ConfiguredRun, ConfiguredRunPatch, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, CreatedTeam, CreateTeamOptions, DefNamesResponse, ForkTeamOptions, ModelAliasesResponse, OperatorTokenDefNamesResponse, ProviderModelsResponse, RoutingResponse, ScheduleListResponse, SchedulePauseResult, ScheduleRunNowResult, ScheduleStateView, ListTeamsResponse, PromotedTeam, RetiredTeam, TeamBreakpoints, TeamDefDetail, TeamRunDetached, TeamRunTarget, TeamVerification, TeamDraft, TeamDraftVerification, TeamVersionList, TeamDiagram, TeamRunResult, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, EvaluationSubmitInput, EvaluationGetInput, EvaluationListForRunInput, EvaluationListForDefInput, EvaluationAggregateInput, EvaluationInput, EvaluationSubmitResult, EvaluationRecord, EvaluationListForRunResult, EvaluationListForDefResult, EvaluationAggregate, TranscriptResponse, WhoamiResponse, UsageDimension, UsageBucket, UsageReportResponse, TokenLimit, TokenLimitsResponse, ConfigResponse, SetTokenLimitRequest, AclBinding, AclBindingListResponse, AclCatalog, AclDefInput, AclDefListResponse, AclDefNamesResponse, AclDefRow, AclRule, AclValidateResult, AuthzDecision, AuthzEvaluationRequest, AuthzEvaluationsRequest, AuthzEvaluationsResponse, AuthzExplainResponse, AuthzSimulateRequest, AuthzSimulateResponse, CreateAclBindingBody, CreateGroupBody, GroupDetail, GroupEffective, GroupListResponse, GroupMemberChange, GroupMemberKind, GroupRow, AppClientConfig, AppClientEntry, ClientDefInput, ClientDefListResponse, ClientDefNamesResponse, ClientDefRecord, ClientDefRetireResult, ClientDefVerifyResult, DeviceLoginOptions, DeviceLoginResult } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
+    private readonly tokenProvider?;
+    private oauthHelper?;
+    private readonly rawFetch?;
     constructor(opts?: ClientOptions);
+    /** The app sign-in helper (RFC FL) for this server: same base URL and
+     *  fetch, never this client's bearer. See {@link LoomcycleOAuth}. */
+    get oauth(): LoomcycleOAuth;
     /**
      * Run an agent and stream events. Returns AsyncIterable<AgentEvent>;
      * the iterator completes when the server closes the SSE stream.
@@ -501,7 +508,8 @@ export declare class LoomcycleClient {
         signal?: AbortSignal;
     }): Promise<WalkRunsPage>;
     /** Aggregated token-usage + cost report (RFC AV). Group by any of
-     *  tenant/user/provider/model/source/purpose over an optional time window;
+     *  tenant/user/provider/model/source/purpose/tier/user_tier/agent/class over
+     *  an optional time window, split into periods with `bucket`;
      *  group by `source` for the operator-vs-tenant split, by `purpose` to see
      *  what OCR and speech-to-text cost (a row's `audio_seconds` is the audio its
      *  speech-to-text calls transcribed). Tenant-scoped server-side: a
@@ -515,6 +523,16 @@ export declare class LoomcycleClient {
         to?: string;
         /** Super-admin tenant focus (?tenant=); ignored for a tenant principal. */
         tenant?: string;
+        /** Split the window into UTC periods; each row then carries `period`.
+         *  `hour` reaches only `detail_since` onward. */
+        bucket?: UsageBucket;
+        /** Keep the `top` largest values of the first `groupBy` dimension (by
+         *  `topBy`, default cost); the rest fold into rows marked `other`. */
+        top?: number;
+        topBy?: "cost" | "tokens" | "calls";
+        /** Keep rows whose dimension is one of the values. `tenant` is not a
+         *  filter: it is the `tenant` focus above. */
+        filters?: Partial<Record<Exclude<UsageDimension, "tenant">, string[]>>;
         signal?: AbortSignal;
     }): Promise<UsageReportResponse>;
     /** Instance configuration: build identity, the feature matrix, and the live
@@ -635,12 +653,16 @@ export declare class LoomcycleClient {
      *  "isolated" confines the member to its own user scope. 409 on a duplicate
      *  (tenant, subject). */
     createUser(body: CreateUserBody, opts?: {
+        tenant?: string;
         signal?: AbortSignal;
     }): Promise<UserRecord>;
     /** Patch mutable fields on a user in the caller's own tenant. An omitted key
      *  leaves the column unchanged. Disabling a user (status:"disabled") also
-     *  revokes its delegated tokens server-side. Cross-tenant target → 404. */
+     *  revokes its delegated tokens server-side. A pending user is activated by
+     *  {@link approveUser}, not here (409 `use_approve`). Cross-tenant target →
+     *  404. */
     updateUser(subject: string, body: UpdateUserBody, opts?: {
+        tenant?: string;
         signal?: AbortSignal;
     }): Promise<UserRecord>;
     /** Delete the user identity row in the caller's own tenant (204). Its
@@ -648,8 +670,126 @@ export declare class LoomcycleClient {
      *  Owned data (runs / sessions / memory) is left intact — this is not
      *  erasure ({@link erasureExecute}). Cross-tenant target → 404. */
     deleteUser(subject: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Approve a user awaiting approval: `pending` → `active`
+     *  (`POST /v1/_users/{subject}/approve`). A sign-in gate configured with
+     *  `new_user.status: pending` provisions people who can sign in but are
+     *  refused everything until this call. Returns the updated record. 409
+     *  `not_pending` for a user that is not pending; 404 for an unknown or
+     *  cross-tenant subject. An `auth:manage` credential may approve only a user
+     *  at its floor (403 `target_beyond_floor`). */
+    approveUser(subject: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<UserRecord>;
+    /** The identity-provider accounts a user signs in with
+     *  (`GET /v1/_users/{subject}/identities`): one row per linked gate, never a
+     *  secret. A user reads its own; a tenant operator or an admin reads any in
+     *  the tenant. Password-gate logins, with whether a password and an
+     *  authenticator are set, are {@link listGateIdentities}. */
+    listUserIdentities(subject: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<UserIdentitiesResponse>;
+    /** Unlink one identity-provider account from a user
+     *  (`DELETE /v1/_users/{subject}/identities/{gate}`, 204). Sessions made
+     *  through it end on their next request. For a tenant operator or an admin;
+     *  a user unlinking its own account must do it from a recently
+     *  signed-in Web UI session, so a bearer is refused (403
+     *  `link_needs_own_session`). A password gate's login is removed with
+     *  {@link removeGateCredentials} instead (409 `password_gate`). 404
+     *  `identity_not_found` when no account of that gate is linked. */
+    unlinkUserIdentity(subject: string, gate: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Sign in through the server's device gate (RFC 8628): shows the person a
+     *  code through `onPrompt`, polls until they approve it in a signed-in Web
+     *  UI session (`/ui/device`), and returns the token issued to them. The
+     *  token is the approver's own member token, at most the device gate's
+     *  `token_ttl` and never past the approving session or the credential it
+     *  was made from. Sends no bearer: a client constructed without one can
+     *  call it. Throws {@link DeviceLoginError} when the login is denied,
+     *  expires, or the server refuses it; 404 `device_login_disabled` when no
+     *  device gate is configured. */
+    deviceLogin(opts: DeviceLoginOptions): Promise<DeviceLoginResult>;
+    /** Every configured sign-in gate (`GET /v1/_authgate`): kind, label,
+     *  whether a browser can sign in through it, its identity map and an
+     *  external gate's key fingerprint and removal timing — never key
+     *  material. **Admin token only.** `probe: true` also fetches each
+     *  external gate's discovery document (bounded) and compares it with the
+     *  registration. */
+    listAuthGates(opts?: {
+        probe?: boolean;
+        signal?: AbortSignal;
+    }): Promise<AuthGateListResponse>;
+    /** Invite a person to sign in through a password gate
+     *  (`POST /v1/_authgate/{gate}/invites`). Without `subject` the invite
+     *  makes a new user, at the gate's new-user floor unless the gate is
+     *  trusted; with one it gives that existing user a login (409
+     *  `credential_exists` if it has one — issue a reset instead). Returns the
+     *  one-time link, shown once. */
+    createInvite(gate: string, body: CreateInviteBody, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<CreatedInvite>;
+    /** A password gate's invites in the tenant, live and past
+     *  (`GET /v1/_authgate/{gate}/invites`), never their codes. An admin naming
+     *  no tenant lists every tenant's. */
+    listInvites(gate: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AuthInviteListResponse>;
+    /** Revoke a live invite (`DELETE /v1/_authgate/{gate}/invites/{id}`, 204).
+     *  409 `invite_not_live` when it was already redeemed, revoked or expired;
+     *  another tenant's invite is a 404. */
+    revokeInvite(gate: string, inviteId: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Issue a one-time link that sets a new password for a user with a login
+     *  at the gate (`POST /v1/_authgate/{gate}/resets`). A user with an
+     *  authenticator still needs a code from it. Completing the reset ends the
+     *  user's sessions from the old password and retires its delegated tokens.
+     *  404 `login_not_found` when the user has no login at the gate. */
+    createPasswordReset(gate: string, subject: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<CreatedPasswordReset>;
+    /** Remove a user's password, authenticator and recovery codes at a gate
+     *  (`DELETE /v1/_authgate/{gate}/credentials/{subject}`, 204). The login
+     *  stays reserved, so a later {@link createPasswordReset} restores access. */
+    removeGateCredentials(gate: string, subject: string, opts?: {
+        tenant?: string;
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Change the login a user signs in with at a gate
+     *  (`PATCH /v1/_authgate/{gate}/logins/{subject}`). The subject does not
+     *  change, so nothing the user owns moves. Returns the normalised login;
+     *  409 `login_taken` when another user has it. */
+    renameGateLogin(gate: string, subject: string, login: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        subject: string;
+        login: string;
+    }>;
+    /** A user's logins at every gate, and whether it has a password and a
+     *  confirmed authenticator (`GET /v1/_authgate/{gate}/identities`) — never
+     *  a secret. `gate` must name a password gate. */
+    listGateIdentities(gate: string, subject: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GateIdentitiesResponse>;
+    /** Whether the tenant has, or ever had, a user and whether an owner invite
+     *  is live (`GET /v1/_authgate/{gate}/tenant-status`) — what deciding on an
+     *  owner invite needs, and nothing about who the users are. */
+    getGateTenantStatus(gate: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GateTenantStatus>;
     /** Mint a bearer token for one of the caller's own ACTIVE users. The granted
      *  scopes are DERIVED server-side from the member's access_mode (never sent),
      *  and the plaintext `token` is returned exactly ONCE — store it now, it is
@@ -1265,6 +1405,59 @@ export declare class LoomcycleClient {
     volumeDef(input: SubstrateToolInput, opts?: {
         signal?: AbortSignal;
     }): Promise<SubstrateToolResponse>;
+    /** The ClientDef op dispatch, as sent: `{op, name?, def_id?, client?,
+     *  description?, tenant?, content_sha256?}`. The typed methods below are
+     *  the usual way in. */
+    clientDef(input: ClientDefInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /** Register an app (`op: "create"`). Its redirect URIs and origins are
+     *  checked as strictly as a config client's. `tenant` is for an admin: the
+     *  tenant whose people it signs in, "" (the default) for every tenant. */
+    createClientDef(name: string, client: AppClientConfig, opts?: {
+        description?: string;
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<ClientDefRecord>;
+    /** Change an app (`op: "update"`): a new version, whole. Codes issued
+     *  under the old version that were not exchanged yet stop working. */
+    updateClientDef(name: string, client: AppClientConfig, opts?: {
+        description?: string;
+        signal?: AbortSignal;
+    }): Promise<ClientDefRecord>;
+    /** One app by name (a config client too) or one version by `def_id`
+     *  (`op: "get"`). */
+    getClientDef(ref: {
+        name?: string;
+        def_id?: string;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AppClientEntry>;
+    /** The apps the caller may see, config ones included (`op: "list"`). An
+     *  admin may focus one tenant with `tenant` ("" = the every-tenant ones). */
+    listClientDefs(opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<ClientDefListResponse>;
+    /** Take an app out of service (`op: "retire"`): its unused codes are
+     *  voided, its sign-ins revoked and their access tokens retired. The name
+     *  is not reusable. */
+    retireClientDef(name: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<ClientDefRetireResult>;
+    /** Whether an app is deployed and, with `contentSha256`, whether it matches
+     *  (`op: "verify"`). An absent app answers `deployed: false`. */
+    verifyClientDef(name: string, opts?: {
+        contentSha256?: string;
+        signal?: AbortSignal;
+    }): Promise<ClientDefVerifyResult>;
+    /** The apps the caller may see, by name (`GET /v1/_clientdef/names`). An
+     *  admin may focus one tenant with `tenant`; unlike the other families'
+     *  name lists, `""` is a focus too (the every-tenant apps). */
+    listClientDefNames(opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<ClientDefNamesResponse>;
     private listDefNames;
     /** Every AgentDef name (`GET /v1/_agentdef/names`). */
     listAgentDefNames(opts?: {

package/dist/client.js

@@ -23,9 +23,11 @@
  * via fetch-helpers.ts:raiseFromResponse — see README.md for the
  * full mapping table.
  */
-import { authHeaders, deleteRequest, deleteJSON, jsonFetch, patchJSON, postJSON, putJSON, raiseFromResponse, } from "./fetch-helpers.js";
+import { authHeaders, authorizedFetch, deleteRequest, deleteJSON, jsonFetch, patchJSON, postJSON, putJSON, raiseFromResponse, } from "./fetch-helpers.js";
 import { parseSSE } from "./stream.js";
 import { InteractiveSession } from "./interactive.js";
+import { LoomcycleOAuth } from "./oauth.js";
+import { deviceLogin } from "./device-login.js";
 import { ClientToolHost, clientToolsURL, } from "./client-tools.js";
 /** samplingToWire maps the camelCase SamplingOptions to the snake_case wire
  *  object, omitting unset fields so they inherit the agent's value. */
@@ -217,13 +219,30 @@ function applyOverridesToWire(body, opts) {
 }
 export class LoomcycleClient {
     ctx;
+    tokenProvider;
+    oauthHelper;
+    rawFetch;
     constructor(opts = {}) {
+        if (opts.authToken && opts.tokenProvider) {
+            throw new TypeError("LoomcycleClient: pass authToken or tokenProvider, not both");
+        }
+        const fetchImpl = opts.fetch ?? fetch;
+        this.rawFetch = opts.fetch;
+        this.tokenProvider = opts.tokenProvider;
         this.ctx = {
             baseUrl: (opts.baseUrl ?? "http://127.0.0.1:8787").replace(/\/$/, ""),
             authToken: opts.authToken,
-            fetchImpl: opts.fetch ?? fetch,
+            // With a provider, ctx.authToken stays unset and the wrapper sets the
+            // header on every request, so no method needs to know.
+            fetchImpl: opts.tokenProvider ? authorizedFetch(fetchImpl, opts.tokenProvider) : fetchImpl,
         };
     }
+    /** The app sign-in helper (RFC FL) for this server: same base URL and
+     *  fetch, never this client's bearer. See {@link LoomcycleOAuth}. */
+    get oauth() {
+        this.oauthHelper ??= new LoomcycleOAuth({ baseUrl: this.ctx.baseUrl, fetch: this.rawFetch });
+        return this.oauthHelper;
+    }
     // ---- Run lifecycle ----
     /**
      * Run an agent and stream events. Returns AsyncIterable<AgentEvent>;
@@ -841,7 +860,8 @@ export class LoomcycleClient {
         return { agents: resp.agents ?? [], next_cursor: resp.next_cursor ?? "" };
     }
     /** Aggregated token-usage + cost report (RFC AV). Group by any of
-     *  tenant/user/provider/model/source/purpose over an optional time window;
+     *  tenant/user/provider/model/source/purpose/tier/user_tier/agent/class over
+     *  an optional time window, split into periods with `bucket`;
      *  group by `source` for the operator-vs-tenant split, by `purpose` to see
      *  what OCR and speech-to-text cost (a row's `audio_seconds` is the audio its
      *  speech-to-text calls transcribed). Tenant-scoped server-side: a
@@ -857,6 +877,16 @@ export class LoomcycleClient {
             params.set("to", opts.to);
         if (opts?.tenant)
             params.set("tenant", opts.tenant);
+        if (opts?.bucket)
+            params.set("bucket", opts.bucket);
+        if (opts?.top)
+            params.set("top", String(opts.top));
+        if (opts?.topBy)
+            params.set("top_by", opts.topBy);
+        for (const [dim, values] of Object.entries(opts?.filters ?? {})) {
+            if (values && values.length > 0)
+                params.set(dim, values.join(","));
+        }
         const q = params.toString() ? `?${params.toString()}` : "";
         return jsonFetch(this.ctx, `/v1/_usage${q}`, opts);
     }
@@ -981,28 +1011,151 @@ export class LoomcycleClient {
     //
     // A tenant operator (substrate:tenant) manages the first-class users in its
     // OWN tenant and mints/lists/revokes bearer tokens for them. The tenant is
-    // always server-derived from the authenticated principal — never sent — so
-    // there is no tenant field on any of these calls. Requires a persistent store
+    // server-derived from the authenticated principal. `opts.tenant` (sent as
+    // ?tenant=) names another only for an admin token, and for an `auth:manage`
+    // credential, which must name one (400 `tenant_required` otherwise); a
+    // tenant operator always acts in its own tenant. Requires a persistent store
     // (503 otherwise).
     /** Register a first-class user in the caller's own tenant. `access_mode`
      *  defaults to "tenant" (collaborates on tenant-shared primitives);
      *  "isolated" confines the member to its own user scope. 409 on a duplicate
      *  (tenant, subject). */
     async createUser(body, opts) {
-        return postJSON(this.ctx, "/v1/_users", body, opts);
+        return postJSON(this.ctx, this.aclPath("/v1/_users", opts?.tenant), body, {
+            signal: opts?.signal,
+        });
     }
     /** Patch mutable fields on a user in the caller's own tenant. An omitted key
      *  leaves the column unchanged. Disabling a user (status:"disabled") also
-     *  revokes its delegated tokens server-side. Cross-tenant target → 404. */
+     *  revokes its delegated tokens server-side. A pending user is activated by
+     *  {@link approveUser}, not here (409 `use_approve`). Cross-tenant target →
+     *  404. */
     async updateUser(subject, body, opts) {
-        return patchJSON(this.ctx, `/v1/_users/${encodeURIComponent(subject)}`, body, opts);
+        return patchJSON(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}`, opts?.tenant), body, { signal: opts?.signal });
     }
     /** Delete the user identity row in the caller's own tenant (204). Its
      *  delegated tokens are retired first so the bearer cannot outlive the row.
      *  Owned data (runs / sessions / memory) is left intact — this is not
      *  erasure ({@link erasureExecute}). Cross-tenant target → 404. */
     async deleteUser(subject, opts) {
-        return deleteRequest(this.ctx, `/v1/_users/${encodeURIComponent(subject)}`, opts);
+        return deleteRequest(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Approve a user awaiting approval: `pending` → `active`
+     *  (`POST /v1/_users/{subject}/approve`). A sign-in gate configured with
+     *  `new_user.status: pending` provisions people who can sign in but are
+     *  refused everything until this call. Returns the updated record. 409
+     *  `not_pending` for a user that is not pending; 404 for an unknown or
+     *  cross-tenant subject. An `auth:manage` credential may approve only a user
+     *  at its floor (403 `target_beyond_floor`). */
+    async approveUser(subject, opts) {
+        return postJSON(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}/approve`, opts?.tenant), undefined, { signal: opts?.signal });
+    }
+    /** The identity-provider accounts a user signs in with
+     *  (`GET /v1/_users/{subject}/identities`): one row per linked gate, never a
+     *  secret. A user reads its own; a tenant operator or an admin reads any in
+     *  the tenant. Password-gate logins, with whether a password and an
+     *  authenticator are set, are {@link listGateIdentities}. */
+    async listUserIdentities(subject, opts) {
+        return jsonFetch(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}/identities`, opts?.tenant), opts);
+    }
+    /** Unlink one identity-provider account from a user
+     *  (`DELETE /v1/_users/{subject}/identities/{gate}`, 204). Sessions made
+     *  through it end on their next request. For a tenant operator or an admin;
+     *  a user unlinking its own account must do it from a recently
+     *  signed-in Web UI session, so a bearer is refused (403
+     *  `link_needs_own_session`). A password gate's login is removed with
+     *  {@link removeGateCredentials} instead (409 `password_gate`). 404
+     *  `identity_not_found` when no account of that gate is linked. */
+    async unlinkUserIdentity(subject, gate, opts) {
+        return deleteRequest(this.ctx, this.aclPath(`/v1/_users/${encodeURIComponent(subject)}/identities/${encodeURIComponent(gate)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Sign in through the server's device gate (RFC 8628): shows the person a
+     *  code through `onPrompt`, polls until they approve it in a signed-in Web
+     *  UI session (`/ui/device`), and returns the token issued to them. The
+     *  token is the approver's own member token, at most the device gate's
+     *  `token_ttl` and never past the approving session or the credential it
+     *  was made from. Sends no bearer: a client constructed without one can
+     *  call it. Throws {@link DeviceLoginError} when the login is denied,
+     *  expires, or the server refuses it; 404 `device_login_disabled` when no
+     *  device gate is configured. */
+    async deviceLogin(opts) {
+        return deviceLogin(this.ctx, opts);
+    }
+    // ---- RFC FA: sign-in gates + the password gate's management API ----
+    //
+    // Invitations, reset links, credential removal, login renames and a user's
+    // logins at a password gate, addressed by the gate's configured name. None
+    // takes a password: the person sets their own through the link. A tenant
+    // operator manages its own tenant, an admin any (`opts.tenant`, defaulting
+    // to its own), and an `auth:manage` credential any tenant it names — it
+    // must name one (400 `tenant_required`) and is held to the gate's new-user
+    // floor. A gate that is not a password gate is a 404 `gate_not_found`.
+    // Requires a persistent store (503 otherwise).
+    /** Every configured sign-in gate (`GET /v1/_authgate`): kind, label,
+     *  whether a browser can sign in through it, its identity map and an
+     *  external gate's key fingerprint and removal timing — never key
+     *  material. **Admin token only.** `probe: true` also fetches each
+     *  external gate's discovery document (bounded) and compares it with the
+     *  registration. */
+    async listAuthGates(opts) {
+        const q = opts?.probe ? "?probe=1" : "";
+        return jsonFetch(this.ctx, `/v1/_authgate${q}`, opts);
+    }
+    /** Invite a person to sign in through a password gate
+     *  (`POST /v1/_authgate/{gate}/invites`). Without `subject` the invite
+     *  makes a new user, at the gate's new-user floor unless the gate is
+     *  trusted; with one it gives that existing user a login (409
+     *  `credential_exists` if it has one — issue a reset instead). Returns the
+     *  one-time link, shown once. */
+    async createInvite(gate, body, opts) {
+        return postJSON(this.ctx, `/v1/_authgate/${encodeURIComponent(gate)}/invites`, withTenant(body, opts?.tenant), { signal: opts?.signal });
+    }
+    /** A password gate's invites in the tenant, live and past
+     *  (`GET /v1/_authgate/{gate}/invites`), never their codes. An admin naming
+     *  no tenant lists every tenant's. */
+    async listInvites(gate, opts) {
+        return jsonFetch(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/invites`, opts?.tenant), opts);
+    }
+    /** Revoke a live invite (`DELETE /v1/_authgate/{gate}/invites/{id}`, 204).
+     *  409 `invite_not_live` when it was already redeemed, revoked or expired;
+     *  another tenant's invite is a 404. */
+    async revokeInvite(gate, inviteId, opts) {
+        return deleteRequest(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/invites/${encodeURIComponent(inviteId)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Issue a one-time link that sets a new password for a user with a login
+     *  at the gate (`POST /v1/_authgate/{gate}/resets`). A user with an
+     *  authenticator still needs a code from it. Completing the reset ends the
+     *  user's sessions from the old password and retires its delegated tokens.
+     *  404 `login_not_found` when the user has no login at the gate. */
+    async createPasswordReset(gate, subject, opts) {
+        return postJSON(this.ctx, `/v1/_authgate/${encodeURIComponent(gate)}/resets`, withTenant({ subject }, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Remove a user's password, authenticator and recovery codes at a gate
+     *  (`DELETE /v1/_authgate/{gate}/credentials/{subject}`, 204). The login
+     *  stays reserved, so a later {@link createPasswordReset} restores access. */
+    async removeGateCredentials(gate, subject, opts) {
+        return deleteRequest(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/credentials/${encodeURIComponent(subject)}`, opts?.tenant), { signal: opts?.signal });
+    }
+    /** Change the login a user signs in with at a gate
+     *  (`PATCH /v1/_authgate/{gate}/logins/{subject}`). The subject does not
+     *  change, so nothing the user owns moves. Returns the normalised login;
+     *  409 `login_taken` when another user has it. */
+    async renameGateLogin(gate, subject, login, opts) {
+        return patchJSON(this.ctx, `/v1/_authgate/${encodeURIComponent(gate)}/logins/${encodeURIComponent(subject)}`, withTenant({ login }, opts?.tenant), { signal: opts?.signal });
+    }
+    /** A user's logins at every gate, and whether it has a password and a
+     *  confirmed authenticator (`GET /v1/_authgate/{gate}/identities`) — never
+     *  a secret. `gate` must name a password gate. */
+    async listGateIdentities(gate, subject, opts) {
+        return jsonFetch(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/identities`, opts?.tenant, {
+            subject,
+        }), opts);
+    }
+    /** Whether the tenant has, or ever had, a user and whether an owner invite
+     *  is live (`GET /v1/_authgate/{gate}/tenant-status`) — what deciding on an
+     *  owner invite needs, and nothing about who the users are. */
+    async getGateTenantStatus(gate, opts) {
+        return jsonFetch(this.ctx, this.aclPath(`/v1/_authgate/${encodeURIComponent(gate)}/tenant-status`, opts?.tenant), opts);
     }
     /** Mint a bearer token for one of the caller's own ACTIVE users. The granted
      *  scopes are DERIVED server-side from the member's access_mode (never sent),
@@ -1196,7 +1349,11 @@ export class LoomcycleClient {
      *  `.close()` to stop. Uses the global WebSocket (browsers, Node 22+); pass
      *  `WebSocketImpl` (e.g. the `ws` package) on older Node. */
     connectClientTools(opts) {
-        const host = new ClientToolHost(clientToolsURL(this.ctx.baseUrl), this.ctx.authToken, opts);
+        // A provider is asked on every (re)connect, so a host outliving one
+        // access token reconnects with the next.
+        const provider = this.tokenProvider;
+        const auth = provider ? () => provider.getToken() : this.ctx.authToken;
+        const host = new ClientToolHost(clientToolsURL(this.ctx.baseUrl), auth, opts);
         host.start();
         return host;
     }
@@ -1833,6 +1990,73 @@ export class LoomcycleClient {
     async volumeDef(input, opts) {
         return postJSON(this.ctx, "/v1/_volumedef", input, opts);
     }
+    // ---- App clients (RFC FL ClientDef) ----
+    //
+    // The apps that sign people in through this server's gates, registered at
+    // runtime beside the config's `auth.clients`. A tenant operator
+    // (substrate:tenant) registers its own tenant's; an admin any tenant's, or
+    // one for every tenant. Config clients are read only here, and another
+    // tenant's client answers as not found. A refusal raises
+    // SubstrateToolRefusedError. Each method posts to `POST /v1/_clientdef`.
+    /** The ClientDef op dispatch, as sent: `{op, name?, def_id?, client?,
+     *  description?, tenant?, content_sha256?}`. The typed methods below are
+     *  the usual way in. */
+    async clientDef(input, opts) {
+        return postJSON(this.ctx, "/v1/_clientdef", input, opts);
+    }
+    /** Register an app (`op: "create"`). Its redirect URIs and origins are
+     *  checked as strictly as a config client's. `tenant` is for an admin: the
+     *  tenant whose people it signs in, "" (the default) for every tenant. */
+    async createClientDef(name, client, opts) {
+        const input = { op: "create", name, client };
+        if (opts?.description !== undefined)
+            input.description = opts.description;
+        if (opts?.tenant !== undefined)
+            input.tenant = opts.tenant;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** Change an app (`op: "update"`): a new version, whole. Codes issued
+     *  under the old version that were not exchanged yet stop working. */
+    async updateClientDef(name, client, opts) {
+        const input = { op: "update", name, client };
+        if (opts?.description !== undefined)
+            input.description = opts.description;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** One app by name (a config client too) or one version by `def_id`
+     *  (`op: "get"`). */
+    async getClientDef(ref, opts) {
+        return (await this.clientDef({ op: "get", ...ref }, opts));
+    }
+    /** The apps the caller may see, config ones included (`op: "list"`). An
+     *  admin may focus one tenant with `tenant` ("" = the every-tenant ones). */
+    async listClientDefs(opts) {
+        const input = { op: "list" };
+        if (opts?.tenant !== undefined)
+            input.tenant = opts.tenant;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** Take an app out of service (`op: "retire"`): its unused codes are
+     *  voided, its sign-ins revoked and their access tokens retired. The name
+     *  is not reusable. */
+    async retireClientDef(name, opts) {
+        return (await this.clientDef({ op: "retire", name }, opts));
+    }
+    /** Whether an app is deployed and, with `contentSha256`, whether it matches
+     *  (`op: "verify"`). An absent app answers `deployed: false`. */
+    async verifyClientDef(name, opts) {
+        const input = { op: "verify", name };
+        if (opts?.contentSha256)
+            input.content_sha256 = opts.contentSha256;
+        return (await this.clientDef(input, signalOpts(opts)));
+    }
+    /** The apps the caller may see, by name (`GET /v1/_clientdef/names`). An
+     *  admin may focus one tenant with `tenant`; unlike the other families'
+     *  name lists, `""` is a focus too (the every-tenant apps). */
+    async listClientDefNames(opts) {
+        const q = opts?.tenant !== undefined ? `?tenant=${encodeURIComponent(opts.tenant)}` : "";
+        return jsonFetch(this.ctx, `/v1/_clientdef/names${q}`, opts);
+    }
     // ---- Def name enumeration (GET /v1/_<family>def/names) ----
     //
     // Every name declared in one substrate family, each with its version
@@ -3347,6 +3571,12 @@ function defWriteInput(op, name, overlay, opts) {
         input.promote = opts.promote;
     return input;
 }
+/** A password-gate management body with the tenant the caller named. The
+ *  POST/PATCH routes read the tenant from the body where the others read
+ *  ?tenant=; like aclPath, an empty tenant is left out. */
+function withTenant(body, tenant) {
+    return tenant ? { ...body, tenant } : body;
+}
 function signalOpts(opts) {
     return opts?.signal ? { signal: opts.signal } : undefined;
 }

package/dist/device-login.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @internal — reached through LoomcycleClient.deviceLogin().
+ *
+ * The client side of loomcycle's device login (RFC 8628, a `kind: device`
+ * sign-in gate): ask the server for a code pair, show the person the short
+ * code, poll until they approve it in a signed-in Web UI session, and return
+ * the token issued to them. Both requests are unauthenticated — the device
+ * code is the credential — so no bearer the client holds is sent with them.
+ */
+import type { _FetchContext } from "./fetch-helpers.js";
+import type { DeviceLoginOptions, DeviceLoginResult } from "./types.js";
+export declare function deviceLogin(ctx: _FetchContext, opts: DeviceLoginOptions): Promise<DeviceLoginResult>;