@loomcycle/client 1.121.0 → 1.122.0

package/dist/client.d.ts

@@ -25,7 +25,7 @@
  */
 import { InteractiveSession } from "./interactive.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, 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 } 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, 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";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -1288,14 +1288,184 @@ export declare class LoomcycleClient {
         tenant?: string;
         signal?: AbortSignal;
     }): Promise<DefNamesResponse>;
-    /** Every OperatorTokenDef name (`GET /v1/_operatortokendef/names`), with its
-     *  subject and token counts — never a token. **Admin token only**: token
+    /** Every OperatorTokenDef name (`GET /v1/_operatortokendef/names`), one row
+     *  per (tenant, name), with its subject, token counts and current def_id —
+     *  never a token. **Admin token only**: token
      *  minting stays operator-only, so a `substrate:tenant` token is refused
      *  with 403. */
     listOperatorTokenDefNames(opts?: {
         tenant?: string;
         signal?: AbortSignal;
     }): Promise<OperatorTokenDefNamesResponse>;
+    /** `path` with the admin tenant focus and any extra query parameters. */
+    private aclPath;
+    /** Every group of the tenant, stored and config-declared, sorted by name
+     *  (`GET /v1/_groups`). */
+    listGroups(opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GroupListResponse>;
+    /** One stored group with its direct members and the groups it is inside of
+     *  (`GET /v1/_groups/{name}`). A config-only group is not stored and raises
+     *  NotFoundError; {@link LoomcycleClient.getGroupEffective} covers it. */
+    getGroup(name: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GroupDetail>;
+    /** Every user the group holds, through nested groups at any depth and
+     *  config-declared members included (`GET /v1/_groups/{name}/effective`). */
+    getGroupEffective(name: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GroupEffective>;
+    /** Create a group, or update its description and `external_id` if the name
+     *  exists (`POST /v1/_groups`). A group with an `external_id` is owned by an
+     *  identity provider: a later write to it raises a 409 LoomcycleError with
+     *  code `group_external`. */
+    createGroup(body: CreateGroupBody, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GroupRow>;
+    /** Delete a group and every membership edge naming it
+     *  (`DELETE /v1/_groups/{name}`). Bindings to it stay and apply to no one.
+     *  NotFoundError when there is no such group. */
+    deleteGroup(name: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        deleted: string;
+    }>;
+    /** Add a user or a group to a group (`POST /v1/_groups/{name}/members`). A
+     *  group member nests: its members are in this group too. The server
+     *  refuses an edge that would close a cycle or nest too deep (400), one
+     *  that exists (409 `group_member_exists`), and a delegated writer adding
+     *  itself (403 `acl_self_elevation`). */
+    addGroupMember(name: string, member: {
+        kind: GroupMemberKind;
+        id: string;
+    }, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GroupMemberChange>;
+    /** Remove one membership edge
+     *  (`DELETE /v1/_groups/{name}/members/{kind}/{id}`). NotFoundError when
+     *  there is no such edge. */
+    removeGroupMember(name: string, kind: GroupMemberKind, id: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<GroupMemberChange>;
+    /** The AclDef family, op-dispatched — the same ops the gRPC `AclDef` RPC
+     *  and the MCP `acldef` tool take. Every op but `names` posts to
+     *  `POST /v1/_acldef`; `names` reads `GET /v1/_acldef/names`, which is
+     *  where that op lives on HTTP. The response varies by op; the typed
+     *  helpers below return each op's shape. */
+    aclDef(input: AclDefInput, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /** Every rule list of the tenant, stored and config-declared, plus the
+     *  built-in baselines (`aclDef` op `list`). Retired lists only with
+     *  `includeRetired`. */
+    listAclDefs(opts?: {
+        includeRetired?: boolean;
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclDefListResponse>;
+    /** One rule list, retired or not (`aclDef` op `get`). A config-declared
+     *  list is returned with `source: "config"`. NotFoundError when absent. */
+    getAclDef(name: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclDefRow>;
+    /** Create or replace a rule list by name (`aclDef` op `put`): bumps its
+     *  version and un-retires it. The rules are validated first; a list the
+     *  engine could not enforce is refused with 400. A delegated writer may
+     *  not rewrite a list bound to itself (403 `acl_self_elevation`). */
+    putAclDef(body: {
+        name: string;
+        rules: AclRule[];
+        description?: string;
+    }, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclDefRow>;
+    /** Retire a rule list (`aclDef` op `retire`). Bindings to it stay and match
+     *  nothing; a later `putAclDef` of the name brings it back. NotFoundError
+     *  when there is no live list of that name. */
+    retireAclDef(name: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        retired: string;
+    }>;
+    /** Check rules without storing them (`aclDef` op `validate`). Rules the
+     *  engine refuses raise InvalidArgumentError (code `acl_invalid`) naming
+     *  the fault. */
+    validateAclRules(rules: AclRule[], opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclValidateResult>;
+    /** The resource types, verbs and transports a rule may name (`aclDef` op
+     *  `catalog`). */
+    getAclCatalog(opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclCatalog>;
+    /** Every live rule-list name a binding in the tenant can reach, stored and
+     *  config-declared, sorted (`GET /v1/_acldef/names`). */
+    listAclDefNames(opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclDefNamesResponse>;
+    /** Every binding of the tenant, stored and config-declared
+     *  (`GET /v1/_aclbinding`). Retired ones only with `includeRetired`. */
+    listAclBindings(opts?: {
+        includeRetired?: boolean;
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclBindingListResponse>;
+    /** Bind a rule list to a subject (`POST /v1/_aclbinding`). The list must
+     *  exist and `expires_at` must be in the future, or InvalidArgumentError
+     *  (code `acl_binding_invalid`). A delegated writer may not bind itself, a
+     *  group it is in, its token or its tenant (403 `acl_self_elevation`). An
+     *  empty `subject_id` / `expires_at` is left out of the request. */
+    createAclBinding(body: CreateAclBindingBody, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AclBinding>;
+    /** Retire a binding by its `binding_id` (`DELETE /v1/_aclbinding/{id}`).
+     *  NotFoundError when there is no live binding of that id. A config
+     *  binding has no id and cannot be retired here. */
+    deleteAclBinding(bindingId: string, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        retired: string;
+    }>;
+    /** May the subject do this? (`POST /v1/_authz/evaluation`, AuthZEN 1.0).
+     *  Omit `subject` to ask about yourself. */
+    authzEvaluation(req: AuthzEvaluationRequest, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AuthzDecision>;
+    /** Up to 256 questions for one subject in one call
+     *  (`POST /v1/_authz/evaluations`); decisions come back in order. */
+    authzEvaluations(req: AuthzEvaluationsRequest, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AuthzEvaluationsResponse>;
+    /** A decision with its working: every rule read for the resource's type
+     *  and why it did or did not match (`POST /v1/_authz/explain`). */
+    authzExplain(req: AuthzEvaluationRequest, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AuthzExplainResponse>;
+    /** What a draft of lists and bindings would decide, beside what is decided
+     *  now (`POST /v1/_authz/simulate`). Nothing is written. */
+    authzSimulate(req: AuthzSimulateRequest, opts?: {
+        tenant?: string;
+        signal?: AbortSignal;
+    }): Promise<AuthzSimulateResponse>;
     /** Every schedule: static yaml `scheduled_runs` and ScheduleDefs, merged by
      *  name (`GET /v1/_schedules/list-all`), sorted by name. A tenant token sees
      *  only its own tenant's ScheduleDefs — static schedules are operator

package/dist/client.js

@@ -1496,6 +1496,8 @@ export class LoomcycleClient {
         };
         if (opts.headers)
             overlay.headers = opts.headers;
+        if (opts.binaryResults)
+            overlay.binary_results = opts.binaryResults;
         const createInput = { op: "create", name: opts.name, overlay };
         if (opts.description)
             createInput.description = opts.description;
@@ -1821,13 +1823,183 @@ export class LoomcycleClient {
     async listDocumentSourceDefNames(opts) {
         return this.listDefNames("documentsourcedef", opts);
     }
-    /** Every OperatorTokenDef name (`GET /v1/_operatortokendef/names`), with its
-     *  subject and token counts — never a token. **Admin token only**: token
+    /** Every OperatorTokenDef name (`GET /v1/_operatortokendef/names`), one row
+     *  per (tenant, name), with its subject, token counts and current def_id —
+     *  never a token. **Admin token only**: token
      *  minting stays operator-only, so a `substrate:tenant` token is refused
      *  with 403. */
     async listOperatorTokenDefNames(opts) {
         return this.listDefNames("operatortokendef", opts);
     }
+    // ---- Access control: groups, rule lists, bindings, decisions (RFC EY / EZ) ----
+    //
+    // Groups, lists and bindings are the tenant operator's: a `substrate:tenant`
+    // token, an admin, or the legacy shared token. Any other principal is
+    // refused with 403 (InsufficientScopeError). Every call acts in the caller's
+    // own tenant; `tenant` is an admin's focus on another one and is ignored for
+    // a tenant operator. Rows the config declares are listed beside the stored
+    // ones with `source: "config"`; they cannot be written here. Every write
+    // takes effect on every replica at once. A rule that refuses a call throws
+    // AclDeniedError (403 `acl_denied`) naming the rules that decided.
+    //
+    // The decision questions (authzEvaluation / authzEvaluations / authzExplain
+    // / authzSimulate) are open to any principal about itself; naming another
+    // subject of the tenant needs a tenant operator (403 `authz_subject`).
+    // Every call here needs a persistent store (503 otherwise) and is refused
+    // from inside a run.
+    /** `path` with the admin tenant focus and any extra query parameters. */
+    aclPath(path, tenant, extra) {
+        const q = new URLSearchParams(extra);
+        if (tenant)
+            q.set("tenant", tenant);
+        const qs = q.toString();
+        return qs ? `${path}?${qs}` : path;
+    }
+    /** Every group of the tenant, stored and config-declared, sorted by name
+     *  (`GET /v1/_groups`). */
+    async listGroups(opts) {
+        return jsonFetch(this.ctx, this.aclPath("/v1/_groups", opts?.tenant), opts);
+    }
+    /** One stored group with its direct members and the groups it is inside of
+     *  (`GET /v1/_groups/{name}`). A config-only group is not stored and raises
+     *  NotFoundError; {@link LoomcycleClient.getGroupEffective} covers it. */
+    async getGroup(name, opts) {
+        return jsonFetch(this.ctx, this.aclPath(`/v1/_groups/${encodeURIComponent(name)}`, opts?.tenant), opts);
+    }
+    /** Every user the group holds, through nested groups at any depth and
+     *  config-declared members included (`GET /v1/_groups/{name}/effective`). */
+    async getGroupEffective(name, opts) {
+        return jsonFetch(this.ctx, this.aclPath(`/v1/_groups/${encodeURIComponent(name)}/effective`, opts?.tenant), opts);
+    }
+    /** Create a group, or update its description and `external_id` if the name
+     *  exists (`POST /v1/_groups`). A group with an `external_id` is owned by an
+     *  identity provider: a later write to it raises a 409 LoomcycleError with
+     *  code `group_external`. */
+    async createGroup(body, opts) {
+        return postJSON(this.ctx, this.aclPath("/v1/_groups", opts?.tenant), body, opts);
+    }
+    /** Delete a group and every membership edge naming it
+     *  (`DELETE /v1/_groups/{name}`). Bindings to it stay and apply to no one.
+     *  NotFoundError when there is no such group. */
+    async deleteGroup(name, opts) {
+        return deleteJSON(this.ctx, this.aclPath(`/v1/_groups/${encodeURIComponent(name)}`, opts?.tenant), opts);
+    }
+    /** Add a user or a group to a group (`POST /v1/_groups/{name}/members`). A
+     *  group member nests: its members are in this group too. The server
+     *  refuses an edge that would close a cycle or nest too deep (400), one
+     *  that exists (409 `group_member_exists`), and a delegated writer adding
+     *  itself (403 `acl_self_elevation`). */
+    async addGroupMember(name, member, opts) {
+        return postJSON(this.ctx, this.aclPath(`/v1/_groups/${encodeURIComponent(name)}/members`, opts?.tenant), { kind: member.kind, id: member.id }, opts);
+    }
+    /** Remove one membership edge
+     *  (`DELETE /v1/_groups/{name}/members/{kind}/{id}`). NotFoundError when
+     *  there is no such edge. */
+    async removeGroupMember(name, kind, id, opts) {
+        const path = `/v1/_groups/${encodeURIComponent(name)}/members/${encodeURIComponent(kind)}/${encodeURIComponent(id)}`;
+        return deleteJSON(this.ctx, this.aclPath(path, opts?.tenant), opts);
+    }
+    /** The AclDef family, op-dispatched — the same ops the gRPC `AclDef` RPC
+     *  and the MCP `acldef` tool take. Every op but `names` posts to
+     *  `POST /v1/_acldef`; `names` reads `GET /v1/_acldef/names`, which is
+     *  where that op lives on HTTP. The response varies by op; the typed
+     *  helpers below return each op's shape. */
+    async aclDef(input, opts) {
+        if (input.op === "names")
+            return this.listAclDefNames(opts);
+        return postJSON(this.ctx, this.aclPath("/v1/_acldef", opts?.tenant), input, opts);
+    }
+    /** Every rule list of the tenant, stored and config-declared, plus the
+     *  built-in baselines (`aclDef` op `list`). Retired lists only with
+     *  `includeRetired`. */
+    async listAclDefs(opts) {
+        const input = { op: "list" };
+        if (opts?.includeRetired)
+            input.include_retired = true;
+        return (await this.aclDef(input, opts));
+    }
+    /** One rule list, retired or not (`aclDef` op `get`). A config-declared
+     *  list is returned with `source: "config"`. NotFoundError when absent. */
+    async getAclDef(name, opts) {
+        return (await this.aclDef({ op: "get", name }, opts));
+    }
+    /** Create or replace a rule list by name (`aclDef` op `put`): bumps its
+     *  version and un-retires it. The rules are validated first; a list the
+     *  engine could not enforce is refused with 400. A delegated writer may
+     *  not rewrite a list bound to itself (403 `acl_self_elevation`). */
+    async putAclDef(body, opts) {
+        const input = { op: "put", name: body.name, rules: body.rules };
+        if (body.description !== undefined)
+            input.description = body.description;
+        return (await this.aclDef(input, opts));
+    }
+    /** Retire a rule list (`aclDef` op `retire`). Bindings to it stay and match
+     *  nothing; a later `putAclDef` of the name brings it back. NotFoundError
+     *  when there is no live list of that name. */
+    async retireAclDef(name, opts) {
+        return (await this.aclDef({ op: "retire", name }, opts));
+    }
+    /** Check rules without storing them (`aclDef` op `validate`). Rules the
+     *  engine refuses raise InvalidArgumentError (code `acl_invalid`) naming
+     *  the fault. */
+    async validateAclRules(rules, opts) {
+        return (await this.aclDef({ op: "validate", rules }, opts));
+    }
+    /** The resource types, verbs and transports a rule may name (`aclDef` op
+     *  `catalog`). */
+    async getAclCatalog(opts) {
+        return (await this.aclDef({ op: "catalog" }, opts));
+    }
+    /** Every live rule-list name a binding in the tenant can reach, stored and
+     *  config-declared, sorted (`GET /v1/_acldef/names`). */
+    async listAclDefNames(opts) {
+        return jsonFetch(this.ctx, this.aclPath("/v1/_acldef/names", opts?.tenant), opts);
+    }
+    /** Every binding of the tenant, stored and config-declared
+     *  (`GET /v1/_aclbinding`). Retired ones only with `includeRetired`. */
+    async listAclBindings(opts) {
+        const extra = opts?.includeRetired ? { include_retired: "1" } : undefined;
+        return jsonFetch(this.ctx, this.aclPath("/v1/_aclbinding", opts?.tenant, extra), opts);
+    }
+    /** Bind a rule list to a subject (`POST /v1/_aclbinding`). The list must
+     *  exist and `expires_at` must be in the future, or InvalidArgumentError
+     *  (code `acl_binding_invalid`). A delegated writer may not bind itself, a
+     *  group it is in, its token or its tenant (403 `acl_self_elevation`). An
+     *  empty `subject_id` / `expires_at` is left out of the request. */
+    async createAclBinding(body, opts) {
+        const out = { acl: body.acl, subject_kind: body.subject_kind };
+        if (body.subject_id)
+            out.subject_id = body.subject_id;
+        if (body.expires_at)
+            out.expires_at = body.expires_at;
+        return postJSON(this.ctx, this.aclPath("/v1/_aclbinding", opts?.tenant), out, opts);
+    }
+    /** Retire a binding by its `binding_id` (`DELETE /v1/_aclbinding/{id}`).
+     *  NotFoundError when there is no live binding of that id. A config
+     *  binding has no id and cannot be retired here. */
+    async deleteAclBinding(bindingId, opts) {
+        return deleteJSON(this.ctx, this.aclPath(`/v1/_aclbinding/${encodeURIComponent(bindingId)}`, opts?.tenant), opts);
+    }
+    /** May the subject do this? (`POST /v1/_authz/evaluation`, AuthZEN 1.0).
+     *  Omit `subject` to ask about yourself. */
+    async authzEvaluation(req, opts) {
+        return postJSON(this.ctx, this.aclPath("/v1/_authz/evaluation", opts?.tenant), req, opts);
+    }
+    /** Up to 256 questions for one subject in one call
+     *  (`POST /v1/_authz/evaluations`); decisions come back in order. */
+    async authzEvaluations(req, opts) {
+        return postJSON(this.ctx, this.aclPath("/v1/_authz/evaluations", opts?.tenant), req, opts);
+    }
+    /** A decision with its working: every rule read for the resource's type
+     *  and why it did or did not match (`POST /v1/_authz/explain`). */
+    async authzExplain(req, opts) {
+        return postJSON(this.ctx, this.aclPath("/v1/_authz/explain", opts?.tenant), req, opts);
+    }
+    /** What a draft of lists and bindings would decide, beside what is decided
+     *  now (`POST /v1/_authz/simulate`). Nothing is written. */
+    async authzSimulate(req, opts) {
+        return postJSON(this.ctx, this.aclPath("/v1/_authz/simulate", opts?.tenant), req, opts);
+    }
     // ---- Schedules admin (GET/POST /v1/_schedules/...) ----
     //
     // What the Web UI's schedules page drives: the merged list, one schedule's

package/dist/errors.d.ts

@@ -17,6 +17,7 @@
  * that behavior. PR 5b switches `runStreaming` + every new method
  * to raise typed errors via `raiseFromResponse`.
  */
+import type { AuthzReason } from "./types.js";
 export declare class LoomcycleError extends Error {
     readonly status?: number;
     readonly bodyText?: string;
@@ -253,6 +254,34 @@ export declare class InsufficientScopeError extends LoomcycleError {
         requiredScope?: string;
     });
 }
+/** An HTTP 403 because an access-control list refused the call: body code
+ *  `acl_denied`. The token's scopes would allow it, but a rule bound to the
+ *  caller (to its subject, a group it is in, its token or its tenant) denies
+ *  it, or, where the deployment enforces lists, no rule allows it.
+ *  `reasons` names the rules that decided — empty when none did — so an
+ *  operator can find the list to change with `authzExplain`. Not retryable:
+ *  the same call is refused until a list or binding changes.
+ *
+ *  Other access-control refusals (`acl_self_elevation`, `authz_subject`,
+ *  `operator_plane`, …) stay a plain LoomcycleError with that `code`. */
+export declare class AclDeniedError extends LoomcycleError {
+    /** The verb asked, e.g. `read`, `author`, `manage`. Null when the body did
+     *  not carry one. */
+    readonly action: string | null;
+    /** The resource asked about, `type:name` (e.g. `def:acl/ops`). Null when
+     *  the body did not carry one. */
+    readonly resource: string | null;
+    /** The rules that decided, denies first; empty when no rule matched. */
+    readonly reasons: AuthzReason[];
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        code?: string;
+        action?: string;
+        resource?: string;
+        reasons?: AuthzReason[];
+    });
+}
 /** Every HTTP 503. The status is shared between a condition that clears on
  *  its own and features this deployment does not have
  *  (`decision_not_configured`, `store_unavailable`, `vector_unsupported`, …),

package/dist/errors.js

@@ -268,6 +268,33 @@ export class InsufficientScopeError extends LoomcycleError {
         this.requiredScope = opts?.requiredScope ?? null;
     }
 }
+/** An HTTP 403 because an access-control list refused the call: body code
+ *  `acl_denied`. The token's scopes would allow it, but a rule bound to the
+ *  caller (to its subject, a group it is in, its token or its tenant) denies
+ *  it, or, where the deployment enforces lists, no rule allows it.
+ *  `reasons` names the rules that decided — empty when none did — so an
+ *  operator can find the list to change with `authzExplain`. Not retryable:
+ *  the same call is refused until a list or binding changes.
+ *
+ *  Other access-control refusals (`acl_self_elevation`, `authz_subject`,
+ *  `operator_plane`, …) stay a plain LoomcycleError with that `code`. */
+export class AclDeniedError extends LoomcycleError {
+    /** The verb asked, e.g. `read`, `author`, `manage`. Null when the body did
+     *  not carry one. */
+    action;
+    /** The resource asked about, `type:name` (e.g. `def:acl/ops`). Null when
+     *  the body did not carry one. */
+    resource;
+    /** The rules that decided, denies first; empty when no rule matched. */
+    reasons;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "AclDeniedError";
+        this.action = opts?.action ?? null;
+        this.resource = opts?.resource ?? null;
+        this.reasons = opts?.reasons ?? [];
+    }
+}
 /** Every HTTP 503. The status is shared between a condition that clears on
  *  its own and features this deployment does not have
  *  (`decision_not_configured`, `store_unavailable`, `vector_unsupported`, …),

package/dist/fetch-helpers.d.ts

@@ -79,6 +79,7 @@ export declare function deleteJSON<T>(ctx: _FetchContext, path: string, opts?: {
  *   401         → AuthError
  *   403 + code "insufficient_scope" (or an older server's
  *         WWW-Authenticate scope hint) → InsufficientScopeError
+ *   403 + code "acl_denied" → AclDeniedError (action, resource, reasons)
  *   403 (other) → LoomcycleError (base)
  *   404 + "snapshot"   → SnapshotNotFoundError ────────┐
  *   404 + "session"    → SessionNotFoundError          │  All extend
@@ -86,6 +87,7 @@ export declare function deleteJSON<T>(ctx: _FetchContext, path: string, opts?: {
  *   404 + (other)      → NotFoundError (base)          │  catch any 404
  *                                                      │  with one
  *                                                      │  instanceof.
+ *   409 + an access-control code (group_external, *_exists) → LoomcycleError
  *   409 + "already_pausing" / "already paused" → AlreadyPausingError
  *   409 + "not_paused" / "not paused"          → NotPausedError
  *   409 + "session"                            → SessionBusyError

package/dist/fetch-helpers.js

@@ -9,7 +9,7 @@
  * Method-level code in client.ts stays focused on URL + body shape;
  * the boring fetch + error-translation machinery lives here.
  */
-import { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, ChannelCursorRegressionError, InsufficientScopeError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
+import { AclDeniedError, AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, ChannelCursorRegressionError, InsufficientScopeError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
 /** authHeaders builds the standard request header set: JSON Accept
  *  + Bearer token when the client was constructed with one. The
  *  caller adds Content-Type when posting a body. */
@@ -159,6 +159,7 @@ export async function deleteJSON(ctx, path, opts) {
  *   401         → AuthError
  *   403 + code "insufficient_scope" (or an older server's
  *         WWW-Authenticate scope hint) → InsufficientScopeError
+ *   403 + code "acl_denied" → AclDeniedError (action, resource, reasons)
  *   403 (other) → LoomcycleError (base)
  *   404 + "snapshot"   → SnapshotNotFoundError ────────┐
  *   404 + "session"    → SessionNotFoundError          │  All extend
@@ -166,6 +167,7 @@ export async function deleteJSON(ctx, path, opts) {
  *   404 + (other)      → NotFoundError (base)          │  catch any 404
  *                                                      │  with one
  *                                                      │  instanceof.
+ *   409 + an access-control code (group_external, *_exists) → LoomcycleError
  *   409 + "already_pausing" / "already paused" → AlreadyPausingError
  *   409 + "not_paused" / "not paused"          → NotPausedError
  *   409 + "session"                            → SessionBusyError
@@ -230,6 +232,15 @@ export async function raiseFromResponse(resp) {
                     requiredScope: stringField(bodyObject(bodyText)?.required_scope) ?? hinted,
                 });
             }
+            if (opts.code === "acl_denied") {
+                const body = bodyObject(bodyText) ?? {};
+                throw new AclDeniedError(msg, {
+                    ...opts,
+                    action: stringField(body.action),
+                    resource: stringField(body.resource),
+                    reasons: aclReasons(body.reasons),
+                });
+            }
             throw new LoomcycleError(msg, opts);
         }
         case 404:
@@ -248,6 +259,11 @@ export async function raiseFromResponse(resp) {
                 throw new AgentNotFoundError(msg, opts);
             throw new NotFoundError(msg, opts);
         case 409:
+            // The access-control conflicts carry a code, and their messages quote
+            // caller-chosen names (a group called "session-ops"), which the
+            // keyword matches below would misread.
+            if (opts.code !== undefined && ACL_CONFLICT_CODES.has(opts.code))
+                throw new LoomcycleError(msg, opts);
             if (bodyLower.includes("already_pausing") || bodyLower.includes("already paused"))
                 throw new AlreadyPausingError(msg, opts);
             if (bodyLower.includes("not_paused") || bodyLower.includes("not paused"))
@@ -339,6 +355,39 @@ export async function raiseFromResponse(resp) {
             throw new LoomcycleError(msg, opts);
     }
 }
+/** The 409 codes of the access-control management routes: a group an
+ *  identity provider owns, and a row or membership that already exists. */
+const ACL_CONFLICT_CODES = new Set([
+    "group_external",
+    "group_exists",
+    "group_member_exists",
+    "acl_exists",
+    "acl_binding_exists",
+]);
+/** aclReasons reads an `acl_denied` body's `reasons`, keeping only entries
+ *  with the fields a reason always has: a proxy's or an older server's
+ *  stray value must not surface as a rule. */
+function aclReasons(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const r of v) {
+        if (r === null || typeof r !== "object")
+            continue;
+        const o = r;
+        const acl = stringField(o.acl);
+        const rule = numberField(o.rule);
+        const effect = o.effect;
+        if (acl === undefined || rule === undefined || (effect !== "allow" && effect !== "deny"))
+            continue;
+        const reason = { acl, rule, effect };
+        const version = numberField(o.version);
+        if (version !== undefined)
+            reason.version = version;
+        out.push(reason);
+    }
+    return out;
+}
 /** retryAfterMs reads a `Retry-After` header given in seconds, as the server
  *  always sends it, and returns milliseconds; undefined when the header is
  *  absent or not a number (an HTTP-date form is not parsed). */