@loomcycle/client 1.121.0 → 1.123.0

package/README.md

@@ -501,12 +501,58 @@ One method per substrate family returns every declared name with its version rol
 | `listWebhookDefNames(opts?)` | `GET /v1/_webhookdef/names` |
 | `listMemoryBackendDefNames(opts?)` | `GET /v1/_memorybackenddef/names` |
 | `listDocumentSourceDefNames(opts?)` | `GET /v1/_documentsourcedef/names` |
-| `listOperatorTokenDefNames(opts?)` | `GET /v1/_operatortokendef/names` — **admin token only**; `{name, tenant_id, subject, token_count, has_current, last_updated}`, never a token. |
+| `listOperatorTokenDefNames(opts?)` | `GET /v1/_operatortokendef/names` — **admin token only**; one row per (tenant, name): `{name, tenant_id, subject, token_count, has_current, current_def_id?, last_updated}`, never a token. Rotate or retire by `current_def_id`; a per-user (`u-`) name is refused as a target. |
 
 All but the last return `DefNamesResponse`; `live_version_count` / `active_retired` are reported by the AgentDef, SkillDef, HookDef and MCPServerDef families. Teams have `listTeams()`.
 
 Team options ride on existing methods: `createTeam(name, overlay, { promote, description })` sends the create's own fields (omitted, a create is promoted — the server default; `promote: false` authors it without putting it in force), `forkTeam(name, overlay, { promote, parentDefId, description })` sends the fork's (omitted, the fork is authored but not active — the server default for a fork), and `runTeam({ ..., interruptOnCap: true })` asks a human whether to continue, reroute or abort when a state hits its iteration cap, instead of ending with `iteration_cap`.
 
+### Access control (RFC EY / EZ)
+
+Groups, access-control rule lists, the bindings that attach a list to a subject, and the AuthZEN-shaped decision questions. Groups, lists and bindings are the tenant operator's (`substrate:tenant`, an admin, or the legacy shared token; any other principal gets an `InsufficientScopeError`); the decision questions are open to any principal about itself. Every call acts in your own tenant; `opts.tenant` focuses another for an admin and is ignored for a tenant token. Rows the config declares (`acls:` / `groups:` / `acl_bindings:`) are listed beside the stored ones with `source: "config"`, without versions or timestamps, and cannot be written here. Every call needs a persistent store and is refused from inside a run.
+
+| Method | Route | Returns |
+|---|---|---|
+| `listGroups(opts?)` | `GET /v1/_groups` | `GroupListResponse` — stored and config groups, by name |
+| `getGroup(name, opts?)` | `GET /v1/_groups/{name}` | `GroupDetail` — a stored group, its direct members, `contained_in`; a config-only group is a `NotFoundError` |
+| `getGroupEffective(name, opts?)` | `GET /v1/_groups/{name}/effective` | `GroupEffective` — every user through nested groups, config members included |
+| `createGroup({name, description?, external_id?}, opts?)` | `POST /v1/_groups` | `GroupRow` — an upsert by name |
+| `deleteGroup(name, opts?)` | `DELETE /v1/_groups/{name}` | `{deleted}` |
+| `addGroupMember(name, {kind, id}, opts?)` | `POST /v1/_groups/{name}/members` | `GroupMemberChange`; `kind` is `user` or `group` (nesting) |
+| `removeGroupMember(name, kind, id, opts?)` | `DELETE /v1/_groups/{name}/members/{kind}/{id}` | `GroupMemberChange` with `removed: true` |
+| `aclDef(input, opts?)` | `POST /v1/_acldef` | the op's body; `op: "names"` reads `GET /v1/_acldef/names` |
+| `listAclDefs({includeRetired?}?)` | `aclDef` op `list` | `AclDefListResponse` — `acls` plus the read-only `builtin` baselines |
+| `getAclDef(name, opts?)` | op `get` | `AclDefRow` |
+| `putAclDef({name, rules, description?}, opts?)` | op `put` | `AclDefRow` — creates or replaces, bumping `version` |
+| `retireAclDef(name, opts?)` | op `retire` | `{retired}` |
+| `validateAclRules(rules, opts?)` | op `validate` | `AclValidateResult`; bad rules are an `InvalidArgumentError` with code `acl_invalid` |
+| `getAclCatalog(opts?)` | op `catalog` | `AclCatalog` — types, verbs, scopes, transports |
+| `listAclDefNames(opts?)` | `GET /v1/_acldef/names` | `{names}` |
+| `listAclBindings({includeRetired?}?)` | `GET /v1/_aclbinding` | `AclBindingListResponse` |
+| `createAclBinding({acl, subject_kind, subject_id?, expires_at?}, opts?)` | `POST /v1/_aclbinding` | `AclBinding`; a missing list or a past expiry is an `InvalidArgumentError` with code `acl_binding_invalid` |
+| `deleteAclBinding(bindingId, opts?)` | `DELETE /v1/_aclbinding/{id}` | `{retired}` |
+| `authzEvaluation(req, opts?)` | `POST /v1/_authz/evaluation` | `AuthzDecision` — `decision` is true only when a rule allowed |
+| `authzEvaluations(req, opts?)` | `POST /v1/_authz/evaluations` | `{evaluations}` — up to 256, in order |
+| `authzExplain(req, opts?)` | `POST /v1/_authz/explain` | `AuthzExplainResponse` — every rule read and why |
+| `authzSimulate(req, opts?)` | `POST /v1/_authz/simulate` | `AuthzSimulateResponse` — `now` and `with_draft` per request; nothing is written |
+
+`whoami()` also reports `acl_mode` (`compat` / `shadow` / `enforce`), the caller's `groups` and `acl_version`, each absent when the server does not send it. A delegated writer changing its own authority is refused with code `acl_self_elevation`; a write to a group an identity provider owns (`external_id` set) with a 409 `group_external`. A rule that refuses any call — here or on any other route — throws `AclDeniedError` (see [Errors](#errors)).
+
+```ts
+const { names } = await client.listAclDefNames();
+await client.putAclDef({
+  name: "support-tier-1",
+  rules: [{ effect: "deny", actions: ["invoke"], resources: ["tool:Bash"] }],
+});
+await client.createAclBinding({ acl: "support-tier-1", subject_kind: "group", subject_id: "support" });
+const why = await client.authzExplain({
+  subject: { type: "user", id: "alice" },
+  action: { name: "invoke" },
+  resource: { type: "tool", id: "Bash" },
+});
+console.log(why.decision.outcome, why.traces);
+```
+
 ### Decision models
 
 Ask a **decision model** typed questions about a piece of text and get each answer with its probabilities. A decision model does not write: it reads the `state` you give it and answers a choice, a yes/no or a score, so there is no reply to parse and a call costs a few output tokens. Use it to route, gate, rank or grade text you already have. No run is involved; the tokens are charged to the caller and count against its token budget.
@@ -805,11 +851,13 @@ When the error body is JSON with a string `code` (`token_limit_exceeded`, `per_u
 | 400 | `InvalidArgumentError` |
 | 401 | `AuthError` |
 | 403 + code `insufficient_scope` | `InsufficientScopeError` (not retryable; `e.requiredScope` names the scope the token lacks — from the body's `required_scope`, or from `WWW-Authenticate` on an older server that sent plain text) |
-| 403 (other) | `LoomcycleError` (base; e.g. `restricted_token`, `operator_key_restricted` on `e.code`) |
+| 403 + code `acl_denied` | `AclDeniedError` (an access-control rule refused the call; `e.action`, `e.resource` and `e.reasons` — the rules that decided, denies first, empty when none matched; not retryable) |
+| 403 (other) | `LoomcycleError` (base; e.g. `restricted_token`, `operator_key_restricted`, `acl_self_elevation`, `authz_subject` on `e.code`) |
 | 404 + "snapshot" | `SnapshotNotFoundError` ⎫ |
 | 404 + "session" | `SessionNotFoundError` ⎬ all extend `NotFoundError` |
 | 404 + "agent" | `AgentNotFoundError` ⎬ |
 | 404 (other) | `NotFoundError` (base) ⎭ catch any 404 with one `instanceof` |
+| 409 + code `group_external` / `group_exists` / `group_member_exists` / `acl_exists` / `acl_binding_exists` | `LoomcycleError` (base; matched by code before the keywords below, which a group named e.g. `session-ops` would trip) |
 | 409 + "already_pausing" / "already paused" | `AlreadyPausingError` |
 | 409 + "not_paused" / "not paused" | `NotPausedError` |
 | 409 + "session" | `SessionBusyError` |

package/dist/cjs/client.js

@@ -1265,6 +1265,16 @@ class LoomcycleClient {
         // the server rejects a malformed one rather than silently ignoring it.
         if (input.when !== undefined)
             body.when = input.when;
+        // The document filters: sent only when set, so a filter-free search's
+        // response stays byte-identical (no `filter` echo).
+        if (input.underPaths !== undefined)
+            body.under_paths = input.underPaths;
+        if (input.excludeUnderPaths !== undefined)
+            body.exclude_under_paths = input.excludeUnderPaths;
+        if (input.documentIds !== undefined)
+            body.document_ids = input.documentIds;
+        if (input.excludeDocumentIds !== undefined)
+            body.exclude_document_ids = input.excludeDocumentIds;
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_memory/search", body, {
             signal: opts?.signal,
         });
@@ -1499,6 +1509,8 @@ 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;
@@ -1824,13 +1836,183 @@ 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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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 (0, fetch_helpers_js_1.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/cjs/errors.js

@@ -19,7 +19,7 @@
  * to raise typed errors via `raiseFromResponse`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.SnapshotVersionError = exports.PromptTooLargeError = exports.RequestTooLargeError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.InsufficientScopeError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.TokenLimitExceededError = exports.RateLimitedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
+exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.SnapshotVersionError = exports.PromptTooLargeError = exports.RequestTooLargeError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.AclDeniedError = exports.InsufficientScopeError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.TokenLimitExceededError = exports.RateLimitedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
 class LoomcycleError extends Error {
     status;
     bodyText;
@@ -283,6 +283,34 @@ class InsufficientScopeError extends LoomcycleError {
     }
 }
 exports.InsufficientScopeError = InsufficientScopeError;
+/** 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`. */
+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 ?? [];
+    }
+}
+exports.AclDeniedError = AclDeniedError;
 /** 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/cjs/fetch-helpers.js

@@ -169,6 +169,7 @@ 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
@@ -176,6 +177,7 @@ 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
@@ -240,6 +242,15 @@ async function raiseFromResponse(resp) {
                     requiredScope: stringField(bodyObject(bodyText)?.required_scope) ?? hinted,
                 });
             }
+            if (opts.code === "acl_denied") {
+                const body = bodyObject(bodyText) ?? {};
+                throw new errors_js_1.AclDeniedError(msg, {
+                    ...opts,
+                    action: stringField(body.action),
+                    resource: stringField(body.resource),
+                    reasons: aclReasons(body.reasons),
+                });
+            }
             throw new errors_js_1.LoomcycleError(msg, opts);
         }
         case 404:
@@ -258,6 +269,11 @@ async function raiseFromResponse(resp) {
                 throw new errors_js_1.AgentNotFoundError(msg, opts);
             throw new errors_js_1.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 errors_js_1.LoomcycleError(msg, opts);
             if (bodyLower.includes("already_pausing") || bodyLower.includes("already paused"))
                 throw new errors_js_1.AlreadyPausingError(msg, opts);
             if (bodyLower.includes("not_paused") || bodyLower.includes("not paused"))
@@ -349,6 +365,39 @@ async function raiseFromResponse(resp) {
             throw new errors_js_1.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). */

package/dist/cjs/index.js

@@ -95,6 +95,15 @@
  *       (opts?): Promise<DefNamesResponse>
  *     listOperatorTokenDefNames(opts?): Promise<OperatorTokenDefNamesResponse>   // admin token only
  *
+ *     // Access control (RFC EY / EZ; tenant operator; opts.tenant = admin focus)
+ *     listGroups / getGroup(name) / getGroupEffective(name) / createGroup(body) /
+ *     deleteGroup(name) / addGroupMember(name, {kind, id}) / removeGroupMember(name, kind, id)
+ *     aclDef(input): Promise<unknown>                             // op-dispatched; names → GET /v1/_acldef/names
+ *     listAclDefs / getAclDef(name) / putAclDef(body) / retireAclDef(name) /
+ *     validateAclRules(rules) / getAclCatalog() / listAclDefNames()
+ *     listAclBindings / createAclBinding(body) / deleteAclBinding(bindingId)
+ *     authzEvaluation(req) / authzEvaluations(req) / authzExplain(req) / authzSimulate(req)   // any principal, about itself
+ *
  *     // Schedules admin
  *     listAllSchedules(opts?): Promise<ScheduleListResponse>      // static yaml + ScheduleDefs, merged
  *     getScheduleState(defId): Promise<ScheduleStateView>
@@ -159,7 +168,9 @@
  *     SnapshotTooLargeError, RequestTooLargeError + PromptTooLargeError
  *     (both subclasses of SnapshotTooLargeError), TokenLimitExceededError
  *     (NOT a BackpressureError: a hard budget, not retryable),
- *     SnapshotVersionError, SubstrateToolRefusedError (v0.8.22).
+ *     SnapshotVersionError, SubstrateToolRefusedError (v0.8.22),
+ *     AclDeniedError (a 403 an access-control rule decided; action,
+ *     resource, reasons).
  *     Every one carries `retryable` (true only for a refusal that clears
  *     on its own).
  *
@@ -171,7 +182,7 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnavailableError = exports.TokenLimitExceededError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.RequestTooLargeError = exports.RateLimitedError = exports.PromptTooLargeError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.InsufficientScopeError = exports.NotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.verifyLoomcycleDelivery = exports.verifyLoomcycleSignature = exports.InteractiveSession = exports.LoomcycleClient = void 0;
+exports.UnavailableError = exports.TokenLimitExceededError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.RequestTooLargeError = exports.RateLimitedError = exports.PromptTooLargeError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.InsufficientScopeError = exports.NotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.AclDeniedError = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.verifyLoomcycleDelivery = exports.verifyLoomcycleSignature = exports.InteractiveSession = exports.LoomcycleClient = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "LoomcycleClient", { enumerable: true, get: function () { return client_js_1.LoomcycleClient; } });
 var interactive_js_1 = require("./interactive.js");
@@ -184,6 +195,7 @@ Object.defineProperty(exports, "ClientToolHost", { enumerable: true, get: functi
 Object.defineProperty(exports, "clientToolsURL", { enumerable: true, get: function () { return client_tools_js_1.clientToolsURL; } });
 Object.defineProperty(exports, "CLIENT_TOOL_SUBPROTOCOL", { enumerable: true, get: function () { return client_tools_js_1.CLIENT_TOOL_SUBPROTOCOL; } });
 var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AclDeniedError", { enumerable: true, get: function () { return errors_js_1.AclDeniedError; } });
 Object.defineProperty(exports, "AgentIDInUseError", { enumerable: true, get: function () { return errors_js_1.AgentIDInUseError; } });
 Object.defineProperty(exports, "AgentNotFoundError", { enumerable: true, get: function () { return errors_js_1.AgentNotFoundError; } });
 Object.defineProperty(exports, "AlreadyPausingError", { enumerable: true, get: function () { return errors_js_1.AlreadyPausingError; } });