doover-js 0.11.0 → 0.12.1

package/dist/client/multiplex-client.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MultiplexClient = void 0;
-const multiplex_merge_1 = require("./multiplex-merge");
-const batch_1 = require("../types/batch");
-const errors_1 = require("./errors");
-const snowflake_1 = require("../utils/snowflake");
-const multiplex_gateway_1 = require("./multiplex-gateway");
+const multiplex_merge_js_1 = require("./multiplex-merge.js");
+const batch_js_1 = require("../types/batch.js");
+const errors_js_1 = require("./errors.js");
+const snowflake_js_1 = require("../utils/snowflake.js");
+const multiplex_gateway_js_1 = require("./multiplex-gateway.js");
 /** "<subclient>.<method>" → spec. Drives the generic non-core facades. */
 const NONCORE_METHODS = {
     // alarms
@@ -246,7 +246,7 @@ class MultiplexClient {
             gatewayMembersForAgent: (agentId) => this.membersForAgentWithCapability(agentId, "gateway.subscribe")
                 .map(({ id, client }) => ({ id, gateway: client.gateway })),
         };
-        return new multiplex_gateway_1.MultiplexGateway(host);
+        return new multiplex_gateway_js_1.MultiplexGateway(host);
     }
     // ===== helpers =====
     /** Resolve the optional `{ sources?: string[] }` bag from a method's trailing
@@ -275,7 +275,7 @@ class MultiplexClient {
     /** Throw if no enabled member supports `cap` at all (regardless of agent). */
     assertSomeMemberSupports(cap) {
         if (!this.enabledClients().some(({ client }) => client.supports(cap))) {
-            throw new errors_1.UnsupportedCapabilityError(cap, this.clientId);
+            throw new errors_js_1.UnsupportedCapabilityError(cap, this.clientId);
         }
     }
     isNotFound(err) {
@@ -286,7 +286,7 @@ class MultiplexClient {
             return "messages.listHistorical";
         if (params?.before) {
             try {
-                const { timestamp: ts } = (0, snowflake_1.extractSnowflakeId)(params.before);
+                const { timestamp: ts } = (0, snowflake_js_1.extractSnowflakeId)(params.before);
                 if (typeof ts === "number" && ts < Date.now() - 24 * 60 * 60 * 1000)
                     return "messages.listHistorical";
             }
@@ -295,7 +295,7 @@ class MultiplexClient {
         return "messages.list";
     }
     unsupportedMethod(_method, cap) {
-        return () => Promise.reject(new errors_1.UnsupportedCapabilityError(cap, this.clientId));
+        return () => Promise.reject(new errors_js_1.UnsupportedCapabilityError(cap, this.clientId));
     }
     /**
      * Route a cross-agent batch mutation.
@@ -324,13 +324,13 @@ class MultiplexClient {
                 if (sources && sources.length === 1) {
                     const only = members.find((m) => m.id === sources[0]);
                     if (!only)
-                        throw new errors_1.UnsupportedCapabilityError(cap, sources[0]);
+                        throw new errors_js_1.UnsupportedCapabilityError(cap, sources[0]);
                     members = [only];
                 }
                 if (members.length === 0)
-                    throw new errors_1.UnsupportedCapabilityError(cap, self.clientId);
+                    throw new errors_js_1.UnsupportedCapabilityError(cap, self.clientId);
                 if (members.length > 1) {
-                    throw new errors_1.AmbiguousWriteError(cap, members.map((m) => m.id));
+                    throw new errors_js_1.AmbiguousWriteError(cap, members.map((m) => m.id));
                 }
                 const target = members[0];
                 const group = groups.get(target.id) ?? {
@@ -362,7 +362,7 @@ class MultiplexClient {
                     };
                 });
             }
-            return (0, batch_1.mergeBatchResponses)([
+            return (0, batch_js_1.mergeBatchResponses)([
                 { items: results, count: results.length, succeeded: 0, failed: 0 },
             ]);
         };
@@ -409,13 +409,13 @@ class MultiplexClient {
             if (sources && sources.length === 1) {
                 const only = members.find((m) => m.id === sources[0]);
                 if (!only)
-                    throw new errors_1.UnsupportedCapabilityError(cap, sources[0]);
+                    throw new errors_js_1.UnsupportedCapabilityError(cap, sources[0]);
                 members = [only];
             }
             if (members.length === 0)
-                throw new errors_1.UnsupportedCapabilityError(cap, self.clientId);
+                throw new errors_js_1.UnsupportedCapabilityError(cap, self.clientId);
             if (members.length > 1)
-                throw new errors_1.AmbiguousWriteError(cap, members.map((m) => m.id));
+                throw new errors_js_1.AmbiguousWriteError(cap, members.map((m) => m.id));
             const target = members[0];
             const subclient = method.split(".")[0];
             const fnName = method.split(".")[1];
@@ -432,7 +432,7 @@ class MultiplexClient {
             const agentId = self.extractAgentId(args);
             const members = self.candidates(agentId, cap, sources);
             if (members.length === 0)
-                throw new errors_1.UnsupportedCapabilityError(cap, self.clientId);
+                throw new errors_js_1.UnsupportedCapabilityError(cap, self.clientId);
             const subclient = method.split(".")[0];
             const fnName = method.split(".")[1];
             let lastErr;
@@ -458,7 +458,7 @@ class MultiplexClient {
             const agentId = self.extractAgentId(args);
             const members = self.candidates(agentId, cap, sources);
             if (members.length === 0)
-                throw new errors_1.UnsupportedCapabilityError(cap, self.clientId);
+                throw new errors_js_1.UnsupportedCapabilityError(cap, self.clientId);
             const subclient = method.split(".")[0];
             const fnName = method.split(".")[1];
             let lastErr;
@@ -485,7 +485,7 @@ class MultiplexClient {
                 self.assertSomeMemberSupports("channels.list");
                 const members = self.candidates(agentId, "channels.list", sources);
                 const perMember = await Promise.all(members.map((m) => m.client.channels.listChannels(...args)));
-                return (0, multiplex_merge_1.dedupeBy)([].concat(...perMember), (c) => c.name);
+                return (0, multiplex_merge_js_1.dedupeBy)([].concat(...perMember), (c) => c.name);
             },
             async getChannel(agentIdOrId, ...rest) {
                 const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
@@ -566,7 +566,7 @@ class MultiplexClient {
                 self.assertSomeMemberSupports(implied);
                 const members = self.candidates(agentId, implied, sources);
                 const perMember = await Promise.all(members.map((m) => m.client.messages.listMessages(...args)));
-                return (0, multiplex_merge_1.mergeMessages)(perMember, { order: params?.order ?? "desc", limit: params?.limit });
+                return (0, multiplex_merge_js_1.mergeMessages)(perMember, { order: params?.order ?? "desc", limit: params?.limit });
             },
             async getMessage(agentIdOrId, ...rest) {
                 const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
@@ -620,7 +620,7 @@ class MultiplexClient {
                     members = members.filter((m) => allow.has(m.id));
                 }
                 const responses = await Promise.all(members.map((m) => m.client.agents.listAgents(...args)));
-                const merged = (0, multiplex_merge_1.dedupeBy)([].concat(...responses.map((r) => (r.agents ?? r.results ?? []))), (a) => a.id);
+                const merged = (0, multiplex_merge_js_1.dedupeBy)([].concat(...responses.map((r) => (r.agents ?? r.results ?? []))), (a) => a.id);
                 return { agents: merged, results: merged, count: merged.length };
             },
             async getMultiAgentMessages(channelName, ...rest) {
@@ -632,7 +632,7 @@ class MultiplexClient {
                     members = members.filter((m) => allow.has(m.id));
                 }
                 const responses = await Promise.all(members.map((m) => m.client.agents.getMultiAgentMessages(...args)));
-                const merged = (0, multiplex_merge_1.mergeMessages)(responses.map((r) => r.results), { order: "desc" });
+                const merged = (0, multiplex_merge_js_1.mergeMessages)(responses.map((r) => r.results), { order: "desc" });
                 // Union each member's per-agent resume cursors so a paginating caller
                 // keeps walking. If one agent lives in two members with different
                 // cursors, keep the lexically-highest (newest) — resuming from the
@@ -660,7 +660,7 @@ class MultiplexClient {
                     members = members.filter((m) => allow.has(m.id));
                 }
                 const responses = await Promise.all(members.map((m) => m.client.agents.getMultiAgentAggregates(...args)));
-                const merged = (0, multiplex_merge_1.dedupeBy)([].concat(...responses.map((r) => r.results)), (a) => a.agent_id);
+                const merged = (0, multiplex_merge_js_1.dedupeBy)([].concat(...responses.map((r) => r.results)), (a) => a.agent_id);
                 return { results: merged, count: merged.length };
             },
             getTokenState: self.makeFanoutFirst("agents.getTokenState", "agents.tokenRead"),
@@ -683,7 +683,7 @@ class MultiplexClient {
                 const spec = NONCORE_METHODS[key];
                 if (!spec) {
                     // Unknown method on a non-core subclient — treat as unsupported (read).
-                    return () => Promise.reject(new errors_1.UnsupportedCapabilityError(self.guessNonCoreCap(subclientName), self.clientId));
+                    return () => Promise.reject(new errors_js_1.UnsupportedCapabilityError(self.guessNonCoreCap(subclientName), self.clientId));
                 }
                 if (spec.kind === "write-route") {
                     return self.routedWrite(key, spec.cap);
@@ -694,7 +694,7 @@ class MultiplexClient {
                     const agentId = !spec.agentScoped ? undefined : self.extractAgentId(args);
                     let members = self.candidates(agentId, spec.cap, sources);
                     if (members.length === 0)
-                        throw new errors_1.UnsupportedCapabilityError(spec.cap, self.clientId);
+                        throw new errors_js_1.UnsupportedCapabilityError(spec.cap, self.clientId);
                     let lastErr;
                     for (const m of members) {
                         try {

package/dist/client/multiplex-gateway.d.ts

@@ -1,6 +1,6 @@
-import type { GatewayClientLike } from "./data-client";
-import type { ChannelRef } from "../types/common";
-import type { WebSocketSession } from "../gateway/types";
+import type { GatewayClientLike } from "./data-client.js";
+import type { ChannelRef } from "../types/common.js";
+import type { WebSocketSession } from "../gateway/types.js";
 /** Minimal view of what MultiplexGateway needs from the owning multiplex. */
 export interface MultiplexGatewayHost {
     /** Enabled members with `gateway.subscribe`. */

package/dist/client/multiplex-merge.d.ts

@@ -1,4 +1,4 @@
-import type { MessageStructure } from "../types/common";
+import type { MessageStructure } from "../types/common.js";
 /** Keep the first item for each key; preserve input order otherwise. */
 export declare function dedupeBy<T>(items: T[], keyOf: (item: T) => string): T[];
 /**

package/dist/client/offline-cache.d.ts

@@ -1,5 +1,5 @@
-import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client";
-import type { Capability } from "./capabilities";
+import type { AgentScope, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, DataClient, DataClientStatus, GatewayClientLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, RpcDispatcherLike, TurnApiLike, UsersApiLike } from "./data-client.js";
+import type { Capability } from "./capabilities.js";
 export declare const DEFAULT_OFFLINE_RETENTION_MS: number;
 export type OfflineCacheMode = "read-through" | "network-first" | "cache-first" | "cache-only";
 export interface OfflineReadCacheOptions {

package/dist/client/offline-cache.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfflineDataClient = exports.MemoryOfflineStorageAdapter = exports.DEFAULT_OFFLINE_RETENTION_MS = void 0;
-const errors_1 = require("./errors");
-const request_options_1 = require("./request-options");
+const errors_js_1 = require("./errors.js");
+const request_options_js_1 = require("./request-options.js");
 exports.DEFAULT_OFFLINE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 class MemoryOfflineStorageAdapter {
     constructor() {
@@ -128,7 +128,7 @@ class OfflineDataClient {
         const target = this.client.agents;
         return {
             listAgents: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 return this.readCached(() => target.listAgents(...this.withDelegateOptions(args, request)), {
                     operation: "agents.listAgents",
                     kind: "agents.list",
@@ -137,7 +137,7 @@ class OfflineDataClient {
                 });
             }),
             getMultiAgentMessages: ((channelName, ...rest) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)([channelName, ...rest]);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)([channelName, ...rest]);
                 const params = args[1];
                 return this.readCached(() => target.getMultiAgentMessages(...this.withDelegateOptions(args, request)), {
                     operation: "agents.getMultiAgentMessages",
@@ -149,7 +149,7 @@ class OfflineDataClient {
                 });
             }),
             getMultiAgentAggregates: ((channelName, ...rest) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)([channelName, ...rest]);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)([channelName, ...rest]);
                 const params = args[1];
                 return this.readCached(() => target.getMultiAgentAggregates(...this.withDelegateOptions(args, request)), {
                     operation: "agents.getMultiAgentAggregates",
@@ -166,7 +166,7 @@ class OfflineDataClient {
         const target = this.client.channels;
         return {
             listChannels: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const agentId = extractAgentId(args);
                 return this.readCached(() => target.listChannels(...this.withDelegateOptions(args, request)), {
                     operation: "channels.listChannels",
@@ -177,7 +177,7 @@ class OfflineDataClient {
                 });
             }),
             getChannel: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
                 return this.readCached(() => target.getChannel(...this.withDelegateOptions(args, request)), {
                     operation: "channels.getChannel",
@@ -199,7 +199,7 @@ class OfflineDataClient {
         const target = this.client.aggregates;
         return {
             getAggregate: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
                 return this.readCached(() => target.getAggregate(...this.withDelegateOptions(args, request)), {
                     operation: "aggregates.getAggregate",
@@ -217,7 +217,7 @@ class OfflineDataClient {
             patchAggregate: this.offlineGuard("aggregates.patchAggregate", target.patchAggregate.bind(target)),
             batchPatchAggregates: this.offlineGuard("aggregates.batchPatchAggregates", target.batchPatchAggregates.bind(target)),
             getAggregateAttachment: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
                 const attachmentId = String(args[2] ?? args[1] ?? "");
                 return this.readBlobCached(() => target.getAggregateAttachment(...this.withDelegateOptions(args, request)), {
@@ -235,7 +235,7 @@ class OfflineDataClient {
         const target = this.client.messages;
         return {
             listMessages: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
                 return this.readCached(() => target.listMessages(...this.withDelegateOptions(args, request)), {
                     operation: "messages.listMessages",
@@ -249,7 +249,7 @@ class OfflineDataClient {
                 });
             }),
             getMessage: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
                 const messageId = String(args[2] ?? args[1] ?? "");
                 return this.readCached(() => target.getMessage(...this.withDelegateOptions(args, request)), {
@@ -274,7 +274,7 @@ class OfflineDataClient {
             batchDeleteMessages: this.offlineGuard("messages.batchDeleteMessages", target.batchDeleteMessages.bind(target)),
             getTimeseries: ((...args) => target.getTimeseries(...args)),
             getMessageAttachment: ((...rawArgs) => {
-                const { args, request } = (0, request_options_1.splitRequestOptions)(rawArgs);
+                const { args, request } = (0, request_options_js_1.splitRequestOptions)(rawArgs);
                 const { agentId, channelName } = extractChannelId(args);
                 const messageId = String(args[2] ?? args[1] ?? "");
                 const attachmentId = String(args[3] ?? args[2] ?? "");
@@ -351,7 +351,7 @@ class OfflineDataClient {
     offlineGuard(operation, fn) {
         return ((...args) => {
             if (!this.isOnline())
-                throw new errors_1.DooverOfflineError(operation);
+                throw new errors_js_1.DooverOfflineError(operation);
             return fn(...args);
         });
     }
@@ -416,7 +416,7 @@ class OfflineDataClient {
                 isOfflineFallback: !this.isOnline(),
                 isExpired: false,
             });
-            throw new errors_1.DooverOfflineError(descriptor.operation, `No cached attachment is available for "${descriptor.operation}" while offline.`, key);
+            throw new errors_js_1.DooverOfflineError(descriptor.operation, `No cached attachment is available for "${descriptor.operation}" while offline.`, key);
         }
         if (effective.mode === "cache-first") {
             const cached = await this.storage.getBlob?.(key);
@@ -468,7 +468,7 @@ class OfflineDataClient {
             isOfflineFallback: !this.isOnline(),
             isExpired: false,
         });
-        throw new errors_1.DooverOfflineError(operation, `No cached data is available for "${operation}" while offline.`, key);
+        throw new errors_js_1.DooverOfflineError(operation, `No cached data is available for "${operation}" while offline.`, key);
     }
     async tryReadRecord(key, allowExpired) {
         const record = await this.storage.getJson(key);
@@ -657,7 +657,7 @@ class OfflineDataClient {
         return false;
     }
     withDelegateOptions(args, request) {
-        const delegate = (0, request_options_1.delegateRequestOptions)(request);
+        const delegate = (0, request_options_js_1.delegateRequestOptions)(request);
         return delegate ? [...args, delegate] : args;
     }
     cacheKey(descriptor) {

package/dist/client/provenance.d.ts

@@ -1,4 +1,4 @@
-import type { SourceProvenance } from "../types/provenance";
+import type { SourceProvenance } from "../types/provenance.js";
 /** A stamped value: adds `__source` to plain objects and their array elements.
  *  For object values, also adds `__source` to any known nested-object props
  *  (aggregate, message) and stamps elements of array-valued props. */

package/dist/client/request-options.d.ts

@@ -1,4 +1,4 @@
-import type { OfflineReadCacheOptions } from "./offline-cache";
+import type { OfflineReadCacheOptions } from "./offline-cache.js";
 export declare const REQUEST_OPTIONS_SYMBOL: unique symbol;
 export interface DooverRequestOptions {
     /**

package/dist/client/singleton.d.ts

@@ -1,5 +1,5 @@
-import type { DooverClientConfig } from "../http/rest-client";
-import { DooverClient } from "./doover-client";
+import type { DooverClientConfig } from "../http/rest-client.js";
+import { DooverClient } from "./doover-client.js";
 /**
  * Get the process-wide `DooverClient` instance, creating it on first call.
  *

package/dist/client/singleton.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDooverClient = getDooverClient;
 exports.peekDooverClient = peekDooverClient;
 exports.resetDooverClient = resetDooverClient;
-const doover_client_1 = require("./doover-client");
+const doover_client_js_1 = require("./doover-client.js");
 const GLOBAL_KEY = "__doover_js_client__";
 function globalBag() {
     return globalThis;
@@ -32,7 +32,7 @@ function getDooverClient(config) {
         }
         return existing;
     }
-    const client = new doover_client_1.DooverClient(config);
+    const client = new doover_client_js_1.DooverClient(config);
     bag[GLOBAL_KEY] = client;
     return client;
 }

package/dist/client/status-tracker.d.ts

@@ -1,4 +1,4 @@
-import type { AgentScope, DataClientStatus, GatewayClientLike } from "./data-client";
+import type { AgentScope, DataClientStatus, GatewayClientLike } from "./data-client.js";
 /**
  * Tracks a `DataClient`'s realtime status by subscribing to its gateway's
  * `open` / `ready` / `close` / `wssError` events. Emits a fresh

package/dist/esm/apis/_args.d.ts

@@ -0,0 +1,16 @@
+export interface ChannelIdentifierLike {
+    agentId: string;
+    channelName: string;
+}
+export interface AgentIdentifierLike {
+    agentId: string;
+}
+export declare function resolveChannelArgs<TOptions>(args: unknown[]): {
+    agentId: string;
+    channelName: string;
+    options?: TOptions;
+};
+export declare function resolveAgentArgs<TOptions>(args: unknown[]): {
+    agentId: string;
+    options?: TOptions;
+};

package/dist/esm/apis/_args.js

@@ -0,0 +1,27 @@
+import { isDooverRequestOptions } from "../client/request-options.js";
+export function resolveChannelArgs(args) {
+    if (typeof args[0] === "string") {
+        const options = isDooverRequestOptions(args[2]) ? undefined : args[2];
+        return {
+            agentId: args[0],
+            channelName: args[1],
+            options: options,
+        };
+    }
+    const id = args[0];
+    const options = isDooverRequestOptions(args[1]) ? undefined : args[1];
+    return {
+        agentId: id.agentId,
+        channelName: id.channelName,
+        options: options,
+    };
+}
+export function resolveAgentArgs(args) {
+    if (typeof args[0] === "string") {
+        const options = isDooverRequestOptions(args[1]) ? undefined : args[1];
+        return { agentId: args[0], options: options };
+    }
+    const id = args[0];
+    const options = isDooverRequestOptions(args[1]) ? undefined : args[1];
+    return { agentId: id.agentId, options: options };
+}

package/dist/esm/apis/agents-api.d.ts

@@ -0,0 +1,196 @@
+import type { AgentAggregate, BatchMessagesResponse } from "../types/openapi.js";
+import type { AgentsResponse, GetAgentsOptions } from "../types/viewer.js";
+import type { RestClient } from "../http/rest-client.js";
+import type { DooverRequestOptions } from "../client/request-options.js";
+export interface MultiAgentMessagesParams {
+    agent_id: string[];
+    /**
+     * Per-agent `before` cursors, parallel to `agent_id`. When set, must
+     * be the same length as `agent_id`; each agent then uses its own
+     * cursor as the upper bound instead of the global `before`. This is
+     * how paginating clients should resume from a previous response's
+     * `next_cursors` map — each agent paginates independently with no
+     * inter-agent "watermark retain".
+     */
+    agent_before?: string[];
+    before?: string;
+    after?: string;
+    limit?: number;
+    agent_message_limit?: number;
+    field_name?: string[];
+}
+/**
+ * One token-posture knob across all three layers, so a UI can show
+ * "inherited from organisation" vs "overridden on this device" and offer a reset
+ * without duplicating the precedence rule client-side.
+ */
+export interface TokenPolicyField<T> {
+    /** What is actually enforced: `agent_override` if set, else `org_default`. */
+    effective: T | null;
+    /** This device's override. `null` means it inherits. */
+    agent_override: T | null;
+    /** The organisation-wide default inherited when not overridden. */
+    org_default: T | null;
+}
+export interface AgentTokenState {
+    /**
+     * Unix-ms revocation floor: every long-lived credential issued before this is
+     * rejected. `null` means nothing has ever been revoked for this agent.
+     */
+    tokens_valid_from: number | null;
+    /** Auth kill-switch — while true, every auth attempt is rejected. */
+    auth_locked: boolean;
+    self_rotation: TokenPolicyField<boolean>;
+    max_age_ms: TokenPolicyField<number>;
+    reuse_grace_ms: TokenPolicyField<number>;
+}
+/**
+ * A token-posture override. `null` on any field means "inherit the organisation
+ * default"; there is no way to express "explicitly off, ignoring the default",
+ * because every knob here is off when absent.
+ */
+export interface AgentTokenPolicy {
+    /** Allow the device to trade its own credential for a fresh one. */
+    self_rotation?: boolean | null;
+    /**
+     * Hard maximum credential age. Only valid alongside `self_rotation` — without
+     * it the device cannot rotate before the deadline and will be locked out.
+     */
+    max_age_ms?: number | null;
+    /**
+     * Grace window after a rotation before a stale credential counts as reuse.
+     * Setting this opts the device into *automatic* lockout on reuse detection.
+     */
+    reuse_grace_ms?: number | null;
+}
+export interface ResourcePermission {
+    permission_id: string;
+    permission: string;
+}
+export interface AdhocTokenResponse {
+    /** Shown once. Not retrievable afterwards. */
+    token: string;
+    token_id: string | null;
+}
+export interface DeviceTokenResponse {
+    /** Shown once. Not stored anywhere and not retrievable afterwards. */
+    token: string;
+    /** Unix-ms issuance time, which is what the revocation floor compares against. */
+    issued_at_ms: number | null;
+}
+export interface MultiAgentAggregatesParams {
+    agent_id: string[];
+    /**
+     * Project the response to only the named top-level keys of each aggregate's
+     * `data`. Useful for large aggregates (e.g. `tag_values`) when the caller
+     * only needs a subset of the tag tree.
+     */
+    field_name?: string[];
+}
+export declare class AgentsApi {
+    private readonly rest;
+    private readonly controlApiUrl?;
+    constructor(rest: RestClient, controlApiUrl?: string | undefined);
+    listAgents(options?: GetAgentsOptions): Promise<AgentsResponse>;
+    listAgents(requestOptions?: DooverRequestOptions): Promise<AgentsResponse>;
+    listAgents(options?: GetAgentsOptions, requestOptions?: DooverRequestOptions): Promise<AgentsResponse>;
+    /**
+     * Batch-fetch recent messages for many agents. Auto-chunks `agent_id`
+     * (and the parallel `agent_before` cursors, if given) at MULTI_AGENT_CHUNK_SIZE
+     * so each request's URL stays under CloudFront's 8,192-byte quota. Chunks
+     * are fetched in parallel and merged: `results`/`count` concat-and-sum,
+     * `next_cursors`/`at_limit_agent_ids` union, legacy `next` becomes the
+     * lexically-highest cursor across at-limit agents.
+     */
+    getMultiAgentMessages(channelName: string, params: MultiAgentMessagesParams): Promise<BatchMessagesResponse>;
+    /**
+     * Batch-fetch aggregates for many agents. Auto-chunks `agent_id` so each
+     * request's URL stays under CloudFront's hard 8,192-byte URL quota — each
+     * agent contributes ~30 chars (`agent_id=<snowflake>&`), so the chunk size
+     * below caps the query string at ~7.5KB even before the base URL. Chunks
+     * are fetched in parallel and merged into one `{ results, count }` so
+     * callers never have to think about the limit.
+     */
+    getMultiAgentAggregates(channelName: string, params: MultiAgentAggregatesParams): Promise<{
+        results: AgentAggregate[];
+        count: number;
+    }>;
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId: string): Promise<AgentTokenState>;
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId: string, policy: AgentTokenPolicy): Promise<{
+        effective: AgentTokenPolicy;
+    }>;
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId: string, locked: boolean): Promise<void>;
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId: string): Promise<{
+        tokens_valid_from: number;
+    }>;
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId: string, tokensValidFrom: number | null): Promise<{
+        tokens_valid_from: number | null;
+    }>;
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId: string, options?: {
+        permissions?: ResourcePermission[];
+        timeout?: number;
+    }): Promise<AdhocTokenResponse>;
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId: string): Promise<DeviceTokenResponse>;
+}