@scitrera/aether-client 0.1.58

package/dist/index.d.cts

@@ -0,0 +1,4063 @@
+import { Long } from '@grpc/proto-loader';
+
+/**
+ * SubmitAuditEventResponse acknowledges a SubmitAuditEventRequest. success=false
+ * indicates the event was rejected before persistence (event type forbidden,
+ * rate-limited, ACL denial, audit disabled, etc.).
+ */
+interface SubmitAuditEventResponse__Output {
+    /**
+     * Echoes the request's correlation ID
+     */
+    'clientRequestId': (string);
+    /**
+     * True iff the event was enqueued for persistence
+     */
+    'success': (boolean);
+    /**
+     * ERR_AUDIT_TYPE_FORBIDDEN / ERR_PERMISSION_DENIED / ERR_AUDIT_RATE_LIMITED / ERR_AUDIT_DISABLED
+     */
+    'errorCode': (string);
+    /**
+     * Human-readable rejection reason
+     */
+    'errorMessage': (string);
+}
+
+/**
+ * Type definitions for the Aether TypeScript SDK.
+ *
+ * This module provides comprehensive type definitions for principal types,
+ * message types, KV scopes, topic construction, and callback handlers.
+ * These types mirror the protobuf definitions in api/proto/aether.proto
+ * and match the patterns established by the Go and Python SDKs.
+ *
+ * @module types
+ */
+/**
+ * Principal types supported by the Aether gateway.
+ *
+ * Each principal type has different routing rules and permissions:
+ * - Agent: Persistent entity with workspace/impl/spec identity
+ * - UniqueTask: Named task with persistent identity
+ * - NonUniqueTask: Ephemeral task with server-assigned ID
+ * - User: Browser/session-based identity with userId/windowId
+ * - WorkflowEngine: Event processor (singleton per gateway)
+ * - MetricsBridge: Telemetry collector (singleton per gateway)
+ * - Orchestrator: Compute provisioner for lazy-loading agents/tasks
+ */
+declare enum PrincipalType {
+    Agent = "agent",
+    UniqueTask = "unique_task",
+    NonUniqueTask = "non_unique_task",
+    User = "user",
+    WorkflowEngine = "workflow_engine",
+    MetricsBridge = "metrics_bridge",
+    Orchestrator = "orchestrator",
+    Service = "service"
+}
+/**
+ * Message types for the Aether messaging protocol.
+ *
+ * - Chat: Conversational messages between principals
+ * - Control: Control/command messages for state changes
+ * - ToolCall: Tool invocation messages
+ * - Event: Broadcast events processed by WorkflowEngine
+ * - Metric: Telemetry data collected by MetricsBridge
+ */
+declare enum MessageType {
+    Unspecified = 0,
+    Chat = 1,
+    Control = 2,
+    ToolCall = 3,
+    Event = 4,
+    Metric = 5,
+    Opaque = 6
+}
+/**
+ * Scopes for KV store operations.
+ *
+ * - Global: Accessible to all entities across all workspaces
+ * - Workspace: Accessible within a specific workspace
+ * - User: Accessible to a specific user across all workspaces
+ * - UserWorkspace: Accessible to a specific user within a specific workspace
+ * - GlobalExclusive: Global scope with exclusive (single-owner) write semantics
+ * - WorkspaceExclusive: Workspace scope with exclusive (single-owner) write semantics
+ * - UserShared: User scope shared across all agent implementations
+ * - UserWorkspaceShared: User-workspace scope shared across all agent implementations
+ */
+declare enum KVScope {
+    Unspecified = 0,
+    Global = 1,
+    Workspace = 2,
+    User = 3,
+    UserWorkspace = 4,
+    GlobalExclusive = 5,
+    WorkspaceExclusive = 6,
+    UserShared = 7,
+    UserWorkspaceShared = 8
+}
+/**
+ * Modes for task assignment.
+ *
+ * - SelfAssign: Caller self-assigns the task (default)
+ * - Targeted: Task is assigned to a specific agent (may trigger orchestration)
+ * - Pool: Any matching worker can claim the task
+ */
+declare enum TaskAssignmentMode {
+    SelfAssign = 0,
+    Targeted = 1,
+    Pool = 2
+}
+/**
+ * Signal types from the gateway.
+ */
+declare enum SignalType {
+    ForceDisconnect = 0,
+    GracefulDisconnect = 1
+}
+/**
+ * An incoming message received from the Aether gateway.
+ */
+interface IncomingMessage {
+    /** The topic from which the message originated (identifies the sender). */
+    readonly sourceTopic: string;
+    /** The raw message payload. */
+    readonly payload: Uint8Array;
+    /** The type of the message (Chat, Control, ToolCall, Event, Metric). */
+    readonly messageType?: number;
+    /** Local timestamp when the message was received. */
+    readonly receivedAt: Date;
+}
+/**
+ * An outgoing message to send through the Aether gateway.
+ */
+interface OutgoingMessage {
+    /** The destination topic string. */
+    targetTopic: string;
+    /** The message payload (bytes). */
+    payload: Uint8Array;
+    /** The type of message. Defaults to Chat. */
+    messageType?: MessageType;
+}
+/**
+ * A configuration snapshot received upon connection.
+ * Contains KV store data for the client's workspace.
+ */
+interface ConfigSnapshot {
+    /** Workspace-scoped key-value pairs (opaque bytes; decode with msgpack/TextDecoder as needed). */
+    readonly kv: Record<string, Uint8Array>;
+    /** Global-scoped key-value pairs (opaque bytes; decode with msgpack/TextDecoder as needed). */
+    readonly globalKv: Record<string, Uint8Array>;
+    /** Workspace-exclusive-scoped key-value pairs (opaque bytes). */
+    readonly workspaceExclusiveKv: Record<string, Uint8Array>;
+    /** Global-exclusive-scoped key-value pairs (opaque bytes). */
+    readonly globalExclusiveKv: Record<string, Uint8Array>;
+}
+/**
+ * A signal from the gateway (e.g., force disconnect).
+ */
+interface Signal {
+    /** The signal type. */
+    readonly type: SignalType;
+    /** Additional context for the signal. */
+    readonly reason: string;
+}
+/**
+ * An error response from the gateway.
+ */
+interface ErrorResponse {
+    /** Error code string. */
+    readonly code: string;
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Whether the client should retry this request. */
+    readonly retryable: boolean;
+    /** Suggested retry delay in milliseconds (0 = use default backoff). */
+    readonly retryAfterMs: number;
+}
+/**
+ * Connection acknowledgment received after successful connection.
+ */
+interface ConnectionAck {
+    /** Server-assigned session identifier. Store for session resumption. */
+    readonly sessionId: string;
+    /** Whether this was a resumed session. */
+    readonly resumed: boolean;
+    /** For non-unique tasks: the server-assigned task instance ID. Empty otherwise. */
+    readonly assignedId: string;
+}
+/**
+ * A task assignment received by orchestrators.
+ */
+interface TaskAssignment {
+    readonly taskId: string;
+    readonly taskType: string;
+    readonly assignedTo: string;
+    readonly metadata: Record<string, string>;
+    readonly assignedAt: number;
+    readonly profile: string;
+    readonly launchParams: Record<string, string>;
+    readonly targetImplementation: string;
+    readonly workspace: string;
+    readonly specifier: string;
+}
+/**
+ * Response from a KV store operation.
+ */
+interface KVResponse {
+    readonly success: boolean;
+    /** Retrieved value (for GET operations). */
+    readonly value: Uint8Array;
+    /** List of keys (for LIST operations). */
+    readonly keys: string[];
+    /** Key-value pairs (for LIST with values). */
+    readonly kvMap: Record<string, string>;
+    /** Correlation ID echoed from the request. */
+    readonly requestId: string;
+    /** Result of INCREMENT/DECREMENT operations. */
+    readonly counterValue?: number;
+    /** Whether the guarded increment/decrement was applied (INCREMENT_IF/DECREMENT_IF). */
+    readonly applied?: boolean;
+}
+/**
+ * Parameters for a KV GET operation.
+ */
+interface KVGetOptions {
+    key: string;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV PUT operation.
+ */
+interface KVPutOptions {
+    key: string;
+    value: Uint8Array;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** TTL in seconds (0 = no expiration). */
+    ttl?: number;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV LIST operation.
+ */
+interface KVListOptions {
+    keyPrefix?: string;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV DELETE operation.
+ */
+interface KVDeleteOptions {
+    key: string;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV INCREMENT operation.
+ */
+interface KVIncrementOptions {
+    key: string;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV DECREMENT operation.
+ */
+interface KVDecrementOptions {
+    key: string;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV INCREMENT_IF operation (increment only if counter is below ceiling).
+ */
+interface KVIncrementIfOptions {
+    key: string;
+    /** Amount to increment. Default: 1. */
+    delta?: bigint | number;
+    /** Ceiling guard: increment only if the current value is strictly below this. */
+    ceiling: bigint | number;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Parameters for a KV DECREMENT_IF operation (decrement only if counter is above floor).
+ */
+interface KVDecrementIfOptions {
+    key: string;
+    /** Amount to decrement. Default: 1. */
+    delta?: bigint | number;
+    /** Floor guard: decrement only if the current value is strictly above this. */
+    floor: bigint | number;
+    scope?: KVScope;
+    userId?: string;
+    workspace?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * A progress update received from an agent or task.
+ * Delivered via the pg.{workspace} RabbitMQ stream with server-side filtering.
+ */
+interface ProgressUpdate {
+    /** The identity of the reporting agent/task (topic format). */
+    readonly source: string;
+    /** Task or correlation ID this progress relates to. */
+    readonly taskId: string;
+    /** Current state (e.g., "running", "finishing", "idle"). */
+    readonly state: string;
+    /** Completion fraction 0.0-1.0, or -1 for indeterminate. */
+    readonly completion: number;
+    /** Human-readable summary of current activity. */
+    readonly summary: string;
+    /** Structured step information for multi-step operations. */
+    readonly step?: ProgressStep;
+    /** Server timestamp when progress was received (Unix milliseconds). */
+    readonly timestampMs: number;
+    /** Workspace the progress originated from. */
+    readonly workspace: string;
+    /** Correlation ID from the originating request. */
+    readonly requestId: string;
+    /** Arbitrary metadata from the reporter. */
+    readonly metadata: Record<string, string>;
+    /** Target recipient identity topic (empty = broadcast). */
+    readonly recipient: string;
+}
+/**
+ * A discrete step within a multi-step progress operation.
+ */
+interface ProgressStep {
+    /** Step name/title. */
+    readonly name: string;
+    /** Detailed description of what this step is doing. */
+    readonly detail: string;
+    /** Step sequence number (1-based). */
+    readonly sequence: number;
+    /** Total number of steps (0 = unknown). */
+    readonly totalSteps: number;
+    /** Step type hint for UI rendering (e.g., "llm_call", "tool_use"). */
+    readonly stepType: string;
+}
+/**
+ * Options for reporting progress from an agent or task.
+ */
+interface ReportProgressOptions {
+    /** Task or correlation ID this progress relates to. Required. */
+    taskId: string;
+    /** Current state (e.g., "running", "finishing", "idle"). */
+    state?: string;
+    /** Completion fraction 0.0-1.0, or -1 for indeterminate. Default: -1. */
+    completion?: number;
+    /** Human-readable summary of current activity. */
+    summary?: string;
+    /** Step name for multi-step progress. */
+    stepName?: string;
+    /** Step detail description. */
+    stepDetail?: string;
+    /** Step sequence number (1-based). */
+    stepSequence?: number;
+    /** Total number of steps (0 = unknown). */
+    stepTotal?: number;
+    /** Step type hint for UI rendering. */
+    stepType?: string;
+    /** Target identity topic to receive updates (empty = broadcast). */
+    recipient?: string;
+    /** Correlation ID for the originating request. */
+    requestId?: string;
+    /** Arbitrary key-value metadata. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Response from a checkpoint operation.
+ */
+interface CheckpointResponse {
+    readonly success: boolean;
+    readonly data: Uint8Array;
+    readonly keys: string[];
+    readonly error: string;
+    readonly savedAt: number;
+    readonly requestId: string;
+}
+/**
+ * Represents a task's information from the server.
+ */
+interface TaskInfo {
+    taskId: string;
+    taskType: string;
+    status: string;
+    workspace: string;
+    targetTopic: string;
+    assignedTo: string;
+    createdAt: number;
+    startedAt: number;
+    completedAt: number;
+    attempt: number;
+    maxAttempts: number;
+    error: string;
+    metadata: Record<string, string>;
+}
+/**
+ * Response to a task query (list or get).
+ */
+interface TaskQueryResponse {
+    success: boolean;
+    error: string;
+    task?: TaskInfo;
+    tasks: TaskInfo[];
+    totalCount: number;
+    /** Correlation ID echoed from the request. */
+    requestId?: string;
+}
+/**
+ * Response to a task operation (cancel or retry).
+ */
+interface TaskOperationResponse {
+    success: boolean;
+    message: string;
+    error: string;
+    task?: TaskInfo;
+    /** Correlation ID echoed from the request. */
+    requestId?: string;
+}
+/**
+ * Response to a CreateTaskRequest that carried a non-empty request_id.
+ * Gives the creator the server-assigned task_id for later COMPLETE/FAIL/CANCEL.
+ */
+interface CreateTaskResponse {
+    /** Whether the task was created successfully. */
+    success: boolean;
+    /** Server-assigned task ID on success. */
+    taskId: string;
+    /** Initial task status, e.g., "pending", "assigned", "pending_pool". */
+    status: string;
+    /** Error code on failure, e.g., "ERR_PERMISSION_DENIED". */
+    errorCode: string;
+    /** Human-readable error description. */
+    errorMessage: string;
+    /** Echoed from the originating CreateTaskRequest for correlation. */
+    requestId: string;
+    /** For TARGETED tasks successfully delivered: the receiving identity string. */
+    assignedTo: string;
+}
+/**
+ * Generic workspace operation response.
+ */
+interface WorkspaceResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly message: string;
+    readonly totalCount: number;
+    readonly requestId?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Generic agent operation response.
+ */
+interface AgentResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly message: string;
+    readonly totalCount: number;
+    readonly requestId?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Generic ACL operation response.
+ */
+interface ACLResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly message: string;
+    readonly requestId?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Stable principal reference attached to an authority grant.
+ */
+interface AuthorityGrantPrincipalRef {
+    readonly principalType: string;
+    readonly principalId: string;
+}
+/**
+ * Resource-specific scope entry attached to an authority grant.
+ */
+interface AuthorityGrantResourceScope {
+    readonly resourceType: string;
+    readonly patterns: string[];
+}
+/**
+ * Authority grant details returned by runtime or admin grant APIs.
+ */
+interface AuthorityGrantInfo {
+    readonly grantId: string;
+    readonly rootGrantId: string;
+    readonly subject?: AuthorityGrantPrincipalRef;
+    readonly delegate?: AuthorityGrantPrincipalRef;
+    readonly issuedBy?: AuthorityGrantPrincipalRef;
+    readonly rootSubject?: AuthorityGrantPrincipalRef;
+    readonly parentGrantId: string;
+    readonly mayDelegate: boolean;
+    readonly remainingHops: number;
+    readonly workspaceScope: string[];
+    readonly resourceScope: AuthorityGrantResourceScope[];
+    readonly operationScope: string[];
+    readonly maxAccessLevel: number;
+    readonly accessLevelName: string;
+    readonly audienceType: string;
+    readonly audienceId: string;
+    readonly validWhileAudienceActive: boolean;
+    readonly expiresAt: number;
+    readonly renewableUntil: number;
+    readonly renewedAt: number;
+    readonly revoked: boolean;
+    readonly revokedAt: number;
+    readonly reason: string;
+    readonly metadata: Record<string, string>;
+    readonly createdAt: number;
+}
+/**
+ * Runtime authority-grant operation response.
+ */
+interface AuthorityGrantResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly message: string;
+    readonly grant?: AuthorityGrantInfo;
+    readonly requestId: string;
+    /**
+     * For LIST_MY_GRANTS / LIST_GRANTS_ON_ME / BATCH_EXCHANGE results.
+     */
+    readonly grants?: AuthorityGrantInfo[];
+    /**
+     * Total matching rows ignoring pagination (LIST_*) or count of returned
+     * grants (BATCH_EXCHANGE).
+     */
+    readonly total?: number;
+    /**
+     * Server's hint to clients on how often to revalidate cached grants
+     * (seconds). Zero means "no hint" — clients fall back to their own policy.
+     */
+    readonly cacheHintTtlSeconds?: number;
+}
+/**
+ * Server-pushed AuthorityGrantRevocation event. Sent on the downstream
+ * stream when a grant the connected client holds is revoked, directly or
+ * via cascade from a parent revocation.
+ */
+interface AuthorityGrantRevocation {
+    readonly grantId: string;
+    readonly rootGrantId: string;
+    readonly reason: string;
+    readonly revokedAt: number;
+    readonly cascade: boolean;
+}
+/**
+ * Workflow operation response.
+ */
+interface WorkflowResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly message: string;
+    readonly data?: Uint8Array;
+    readonly totalCount: number;
+    readonly requestId?: string;
+}
+/**
+ * Options for querying tasks.
+ */
+interface TaskQueryOptions {
+    workspace?: string;
+    status?: string;
+    taskType?: string;
+    limit?: number;
+    offset?: number;
+    timeout?: number;
+}
+/**
+ * Information about an API token.
+ */
+interface TokenInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly principalType: string;
+    readonly workspacePatterns: string[];
+    readonly scopes: string[];
+    readonly createdBy: string;
+    readonly expiresAt: number;
+    readonly lastUsedAt: number;
+    readonly revoked: boolean;
+    readonly revokedAt: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/**
+ * Response to a token operation.
+ */
+interface TokenResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly message: string;
+    readonly token?: TokenInfo;
+    readonly tokens: TokenInfo[];
+    readonly totalCount: number;
+    readonly plaintextToken: string;
+    readonly createdToken?: TokenInfo;
+    readonly requestId: string;
+}
+/** Handler for incoming messages. */
+type MessageHandler = (message: IncomingMessage) => void | Promise<void>;
+/** Handler for configuration snapshots. */
+type ConfigHandler = (config: ConfigSnapshot) => void | Promise<void>;
+/** Handler for signals from the gateway. */
+type SignalHandler = (signal: Signal) => void | Promise<void>;
+/** Handler for error responses from the gateway. */
+type ErrorHandler = (error: ErrorResponse) => void | Promise<void>;
+/** Handler for KV operation responses. */
+type KVResponseHandler = (response: KVResponse) => void | Promise<void>;
+/** Handler for task assignments (used by orchestrators). */
+type TaskAssignmentHandler = (assignment: TaskAssignment) => void | Promise<void>;
+/** Handler for checkpoint responses. */
+type CheckpointResponseHandler = (response: CheckpointResponse) => void | Promise<void>;
+/** Handler for create task responses. */
+type CreateTaskResponseHandler = (response: CreateTaskResponse) => void | Promise<void>;
+/** Handler for task query responses. */
+type TaskQueryResponseHandler = (response: TaskQueryResponse) => void;
+/** Handler for task operation responses. */
+type TaskOperationResponseHandler = (response: TaskOperationResponse) => void;
+/** Handler for workspace operation responses. */
+type WorkspaceResponseHandler = (response: WorkspaceResponse) => void | Promise<void>;
+/** Handler for agent operation responses. */
+type AgentResponseHandler = (response: AgentResponse) => void | Promise<void>;
+/** Handler for ACL operation responses. */
+type ACLResponseHandler = (response: ACLResponse) => void | Promise<void>;
+/** Handler for runtime authority-grant responses. */
+type AuthorityGrantResponseHandler = (response: AuthorityGrantResponse) => void | Promise<void>;
+/** Handler for server-pushed authority-grant revocation events. */
+type AuthorityGrantRevocationHandler = (event: AuthorityGrantRevocation) => void | Promise<void>;
+/** Handler for workflow operation responses. */
+type WorkflowResponseHandler = (response: WorkflowResponse) => void | Promise<void>;
+/** Handler for token operation responses. */
+type TokenResponseHandler = (response: TokenResponse) => void;
+/** Response type for submitAuditEvent requests. */
+type AuditSubmitResponse = SubmitAuditEventResponse__Output;
+/** Handler for audit-submit responses. */
+type AuditSubmitResponseHandler = (response: AuditSubmitResponse) => void;
+/** Handler for progress updates from agents/tasks. */
+type ProgressHandler = (update: ProgressUpdate) => void | Promise<void>;
+/** Handler for successful connection. */
+type ConnectHandler = (ack: ConnectionAck) => void | Promise<void>;
+/** Handler for disconnection events. */
+type DisconnectHandler = (reason: string) => void | Promise<void>;
+/** Handler for reconnection attempts. */
+type ReconnectingHandler = (attempt: number) => void | Promise<void>;
+/**
+ * TLS configuration for secure connections.
+ */
+interface TLSOptions {
+    /** PEM-encoded root CA certificates for server verification. */
+    rootCerts?: Buffer;
+    /** PEM-encoded client private key (for mTLS). */
+    privateKey?: Buffer;
+    /** PEM-encoded client certificate chain (for mTLS). */
+    certChain?: Buffer;
+    /** Override server hostname for certificate validation. */
+    serverNameOverride?: string;
+}
+/**
+ * Connection behavior configuration.
+ */
+interface ConnectionOptions {
+    /** Maximum number of connection attempts (0 = infinite for reconnection). Default: 5. */
+    maxRetries?: number;
+    /** Initial backoff delay in milliseconds. Default: 1000. */
+    initialBackoff?: number;
+    /** Maximum backoff delay in milliseconds. Default: 30000. */
+    maxBackoff?: number;
+    /** Multiplier for exponential backoff. Default: 2.0. */
+    backoffMultiplier?: number;
+    /** Whether to automatically reconnect on connection loss. Default: true. */
+    autoReconnect?: boolean;
+    /** Timeout for establishing a connection in milliseconds. Default: 30000. */
+    connectTimeout?: number;
+    /**
+     * When true, if the gateway returns a DuplicateIdentityError (ALREADY_EXISTS)
+     * during connection, the client will wait briefly and retry. Useful when a
+     * previous instance may still be releasing its distributed lock.
+     * Default: false.
+     */
+    retryOnDuplicate?: boolean;
+    /**
+     * How long to wait (ms) before retrying after a DuplicateIdentityError.
+     * Only used when retryOnDuplicate is true. Default: 5000.
+     */
+    retryOnDuplicateDelay?: number;
+    /**
+     * Maximum number of duplicate-identity retries before giving up.
+     * Only used when retryOnDuplicate is true. Default: 5.
+     */
+    retryOnDuplicateMaxAttempts?: number;
+}
+/**
+ * Authentication credentials passed to the gateway.
+ */
+interface Credentials {
+    [key: string]: string;
+}
+/**
+ * Creates a credentials object with an API key.
+ *
+ * @param key - The long-lived API key for authentication
+ * @returns Credentials map with the API key header
+ */
+declare function withAPIKey(key: string): Credentials;
+/**
+ * Creates a credentials object with a bearer token.
+ *
+ * @param token - The OAuth/JWT bearer token
+ * @returns Credentials map with the authorization header
+ */
+declare function withToken(token: string): Credentials;
+/**
+ * Creates a credentials object with a task token.
+ *
+ * @param token - The short-lived task authentication token
+ * @returns Credentials map with the token header
+ */
+declare function withTaskToken(token: string): Credentials;
+/**
+ * Creates a credentials object with a tenant ID.
+ *
+ * @param tenantId - The tenant identifier
+ * @returns Credentials map with the tenant ID header
+ */
+declare function withTenant(tenantId: string): Credentials;
+
+/**
+ * KV (key-value) store operations for the Aether TypeScript SDK.
+ *
+ * This module provides the KVClient class for interacting with the
+ * hierarchical KV store through the Aether gateway connection.
+ *
+ * KV operations support four scopes:
+ * - Global: Accessible to all entities across all workspaces
+ * - Workspace: Accessible within a specific workspace
+ * - User: Accessible to a specific user across all workspaces
+ * - UserWorkspace: Accessible to a specific user within a specific workspace
+ *
+ * @module kv
+ */
+
+/**
+ * KVClient provides KV store operations over an Aether connection.
+ *
+ * Access this through `client.kv()` rather than constructing directly.
+ *
+ * Supports both async (fire-and-forget with callback) and sync (Promise-based)
+ * operation modes.
+ *
+ * @example
+ * ```typescript
+ * const kv = client.kv();
+ *
+ * // Async put (fire-and-forget)
+ * kv.put({ key: "my-key", value: encode("my-value"), scope: KVScope.Global });
+ *
+ * // Sync get (returns a Promise)
+ * const response = await kv.getSync({ key: "my-key", scope: KVScope.Global });
+ * if (response.success) {
+ *   console.log("Value:", response.value);
+ * }
+ * ```
+ */
+declare class KVClient {
+    private _client;
+    /** @internal */
+    constructor(client: AetherClient);
+    /**
+     * Retrieves a value from the KV store (async).
+     *
+     * The response is delivered via the onKVResponse handler callback.
+     * For synchronous operation, use {@link getSync}.
+     *
+     * @param opts - Get operation options
+     */
+    get(opts: KVGetOptions): void;
+    /**
+     * Stores a value in the KV store (async).
+     *
+     * The response is delivered via the onKVResponse handler callback.
+     * For synchronous operation, use {@link putSync}.
+     *
+     * @param opts - Put operation options
+     */
+    put(opts: KVPutOptions): void;
+    /**
+     * Removes a key from the KV store (async).
+     *
+     * The response is delivered via the onKVResponse handler callback.
+     * For synchronous operation, use {@link deleteSync}.
+     *
+     * @param opts - Delete operation options
+     */
+    delete(opts: KVDeleteOptions): void;
+    /**
+     * Lists keys from the KV store (async).
+     *
+     * The response is delivered via the onKVResponse handler callback.
+     * For synchronous operation, use {@link listSync}.
+     *
+     * @param opts - List operation options
+     */
+    list(opts?: KVListOptions): void;
+    /**
+     * Retrieves a value from the KV store and waits for the response.
+     *
+     * @param opts - Get operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    getSync(opts: KVGetOptions): Promise<KVResponse>;
+    /**
+     * Stores a value in the KV store and waits for the response.
+     *
+     * @param opts - Put operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    putSync(opts: KVPutOptions): Promise<KVResponse>;
+    /**
+     * Removes a key from the KV store and waits for the response.
+     *
+     * @param opts - Delete operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    deleteSync(opts: KVDeleteOptions): Promise<KVResponse>;
+    /**
+     * Lists keys from the KV store and waits for the response.
+     *
+     * @param opts - List operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    listSync(opts?: KVListOptions): Promise<KVResponse>;
+    /**
+     * Increments a counter in the KV store (async).
+     *
+     * The response is delivered via the onKVResponse handler callback.
+     * For synchronous operation, use {@link incrementSync}.
+     *
+     * @param opts - Increment operation options
+     */
+    increment(opts: KVIncrementOptions): void;
+    /**
+     * Decrements a counter in the KV store (async).
+     *
+     * The response is delivered via the onKVResponse handler callback.
+     * For synchronous operation, use {@link decrementSync}.
+     *
+     * @param opts - Decrement operation options
+     */
+    decrement(opts: KVDecrementOptions): void;
+    /**
+     * Increments a counter in the KV store and waits for the response.
+     *
+     * @param opts - Increment operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response with counterValue set
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    incrementSync(opts: KVIncrementOptions): Promise<KVResponse>;
+    /**
+     * Decrements a counter in the KV store and waits for the response.
+     *
+     * @param opts - Decrement operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response with counterValue set
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    decrementSync(opts: KVDecrementOptions): Promise<KVResponse>;
+    /**
+     * Increments a counter only if it is strictly below `ceiling` (async).
+     *
+     * The response (with `applied` and `counterValue`) is delivered via the onKVResponse callback.
+     * For synchronous operation, use {@link incrementIfSync}.
+     *
+     * @param opts - IncrementIf operation options
+     */
+    incrementIf(opts: KVIncrementIfOptions): void;
+    /**
+     * Decrements a counter only if it is strictly above `floor` (async).
+     *
+     * The response (with `applied` and `counterValue`) is delivered via the onKVResponse callback.
+     * For synchronous operation, use {@link decrementIfSync}.
+     *
+     * @param opts - DecrementIf operation options
+     */
+    decrementIf(opts: KVDecrementIfOptions): void;
+    /**
+     * Increments a counter only if it is strictly below `ceiling`, and waits for the response.
+     *
+     * @param opts - IncrementIf operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response with `counterValue` and `applied` set
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    incrementIfSync(opts: KVIncrementIfOptions): Promise<KVResponse>;
+    /**
+     * Decrements a counter only if it is strictly above `floor`, and waits for the response.
+     *
+     * @param opts - DecrementIf operation options (includes optional timeout)
+     * @returns Promise resolving to the KV response with `counterValue` and `applied` set
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    decrementIfSync(opts: KVDecrementIfOptions): Promise<KVResponse>;
+    /**
+     * Retrieves a value from the global scope (async).
+     *
+     * @param key - The key to retrieve
+     */
+    getGlobal(key: string): void;
+    /**
+     * Stores a value in the global scope (async).
+     *
+     * @param key - The key to store
+     * @param value - The value to store
+     */
+    putGlobal(key: string, value: Uint8Array): void;
+    /**
+     * Removes a key from the global scope (async).
+     *
+     * @param key - The key to delete
+     */
+    deleteGlobal(key: string): void;
+    /**
+     * Lists keys from the global scope (async).
+     *
+     * @param keyPrefix - Prefix to filter keys (empty for all)
+     */
+    listGlobal(keyPrefix?: string): void;
+    /**
+     * Waits for a correlated KV response with timeout.
+     * @internal
+     */
+    private _waitForResponse;
+}
+
+/**
+ * Checkpoint operations for the Aether TypeScript SDK.
+ *
+ * Checkpoints allow agents/tasks to persist arbitrary state that survives
+ * restarts. This is separate from message offset tracking (handled
+ * automatically by RabbitMQ Streams).
+ *
+ * @module checkpoint
+ */
+
+/**
+ * Options for a checkpoint save operation.
+ */
+interface CheckpointSaveOptions {
+    /** The checkpoint data to save. */
+    data: Uint8Array;
+    /** Checkpoint key. Allows multiple named checkpoints per identity. Default: "default". */
+    key?: string;
+    /** TTL in seconds (-1 = server default, 0 = no expiration). */
+    ttl?: number;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Options for a checkpoint load operation.
+ */
+interface CheckpointLoadOptions {
+    /** Checkpoint key to load. Default: "default". */
+    key?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Options for a checkpoint delete operation.
+ */
+interface CheckpointDeleteOptions {
+    /** Checkpoint key to delete. Default: "default". */
+    key?: string;
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * Options for a checkpoint list operation.
+ */
+interface CheckpointListOptions {
+    /** Timeout in milliseconds for sync operations. */
+    timeout?: number;
+}
+/**
+ * CheckpointClient provides checkpoint operations over an Aether connection.
+ *
+ * Access this through `client.checkpoint()` rather than constructing directly.
+ *
+ * Supports both async (fire-and-forget with callback) and sync (Promise-based)
+ * operation modes.
+ *
+ * @example
+ * ```typescript
+ * const cp = client.checkpoint();
+ *
+ * // Save state
+ * const encoder = new TextEncoder();
+ * await cp.saveSync({ data: encoder.encode(JSON.stringify(myState)) });
+ *
+ * // Load state
+ * const response = await cp.loadSync({});
+ * if (response.success && response.data.length > 0) {
+ *   const state = JSON.parse(new TextDecoder().decode(response.data));
+ * }
+ *
+ * // List checkpoints
+ * const listResponse = await cp.listSync({});
+ * console.log("Checkpoint keys:", listResponse.keys);
+ * ```
+ */
+declare class CheckpointClient {
+    private _client;
+    /** @internal */
+    constructor(client: AetherClient);
+    /**
+     * Saves checkpoint data (async).
+     * The response is delivered via the onCheckpointResponse handler.
+     */
+    save(opts: CheckpointSaveOptions): void;
+    /**
+     * Loads checkpoint data (async).
+     * The response is delivered via the onCheckpointResponse handler.
+     */
+    load(opts?: CheckpointLoadOptions): void;
+    /**
+     * Deletes a checkpoint (async).
+     * The response is delivered via the onCheckpointResponse handler.
+     */
+    delete(opts?: CheckpointDeleteOptions): void;
+    /**
+     * Lists checkpoint keys (async).
+     * The response is delivered via the onCheckpointResponse handler.
+     */
+    list(): void;
+    /**
+     * Saves checkpoint data and waits for the response.
+     *
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    saveSync(opts: CheckpointSaveOptions): Promise<CheckpointResponse>;
+    /**
+     * Loads checkpoint data and waits for the response.
+     *
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    loadSync(opts?: CheckpointLoadOptions): Promise<CheckpointResponse>;
+    /**
+     * Deletes a checkpoint and waits for the response.
+     *
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    deleteSync(opts?: CheckpointDeleteOptions): Promise<CheckpointResponse>;
+    /**
+     * Lists checkpoint keys and waits for the response.
+     *
+     * @throws {@link TimeoutError} if the operation times out
+     */
+    listSync(opts?: CheckpointListOptions): Promise<CheckpointResponse>;
+    private _waitForResponse;
+}
+
+/**
+ * Tunnel (tunnelDial) support for the Aether TypeScript SDK.
+ *
+ * Provides `tunnelDial()` on AetherClient for opening a bidirectional byte-stream
+ * tunnel through the Aether gRPC connection to a remote service.
+ *
+ * Uses the Web Streams API (ReadableStream / WritableStream) so callers work
+ * in both Node ≥18 and browser environments.
+ *
+ * @module tunnel
+ */
+
+/** Wire protocol for the tunnel. */
+type TunnelProtocol = "tcp" | "udp" | "ws" | "websocket";
+/** Options for tunnelDial(). */
+interface TunnelDialOptions {
+    /** Hint passed to the remote sidecar (e.g. "host:port"). */
+    remoteHint?: string;
+    /** Idle timeout in ms (server-side enforcement). */
+    idleTimeoutMs?: number;
+    /** Byte quota (server-side enforcement). */
+    maxBytes?: number;
+    /** Arbitrary metadata forwarded in TunnelOpen (e.g. WS sub-protocols). */
+    metadata?: Record<string, string>;
+    /** Reserved for v2 reconnect/resume; ignored in v1. */
+    sessionToken?: string;
+    /** Initial outbound credit window (default: 16). */
+    initialCredits?: number;
+    /**
+     * Pin the tunnel to a named terminator backend. The backend's allow-list
+     * still applies — explicit naming selects which backend's ACL is consulted,
+     * not whether the tunnel is allowed.
+     */
+    backend?: string;
+}
+/** Reason string from a remote TunnelClose frame. */
+type TunnelCloseReason = "NORMAL" | "PEER_RESET" | "IDLE_TIMEOUT" | "QUOTA" | "ERROR" | string;
+/** Error thrown when the remote side sends a TunnelClose frame. */
+declare class TunnelClosedError extends Error {
+    readonly reason: TunnelCloseReason;
+    readonly detail: string;
+    constructor(reason: TunnelCloseReason, detail: string);
+}
+/**
+ * Duplex tunnel object returned by tunnelDial().
+ *
+ * - `readable`: incoming bytes from the remote end.
+ * - `writable`: outgoing bytes to the remote end.
+ * - `close()`: send a NORMAL TunnelClose and clean up.
+ */
+interface TunnelStream {
+    /** Readable stream of inbound Uint8Array chunks from the remote end. */
+    readonly readable: ReadableStream<Uint8Array>;
+    /** Writable stream; write Uint8Array chunks to send to the remote end. */
+    readonly writable: WritableStream<Uint8Array>;
+    /** Sends TunnelClose{NORMAL} and tears down both streams. */
+    close(): void;
+    /** Resolves when the tunnel is fully closed (either side). */
+    readonly closed: Promise<void>;
+}
+/** @internal */
+interface TunnelInflight {
+    /** Push inbound data (from downstream TunnelData) into the readable side. */
+    pushData(data: Uint8Array, fin: boolean): void;
+    /** Replenish outbound credits (from downstream TunnelAck). */
+    addCredits(n: number): void;
+    /** Signal that the remote closed the tunnel. */
+    closeWithError(err: TunnelClosedError): void;
+}
+/**
+ * Opens a byte-stream tunnel through the Aether connection.
+ *
+ * @param client   - Connected AetherClient instance.
+ * @param target   - Target topic (e.g. "sv::proxy::default").
+ * @param protocol - Wire protocol: "tcp", "udp", "ws", or "websocket".
+ * @param options  - Optional dial parameters.
+ * @returns A TunnelStream with readable/writable Web Streams and a close() method.
+ * @throws {@link ConnectionError} if not connected.
+ */
+declare function tunnelDial(client: AetherClient, target: string, protocol: TunnelProtocol, options?: TunnelDialOptions): TunnelStream;
+
+/**
+ * Authority grant cache for the Aether TypeScript client.
+ *
+ * Mirrors the Python `AuthorityGrantCache` (see
+ * `sdk/python-client/scitrera_aether_client/authority_cache.py`):
+ *
+ * - Caches grants per `(sourceSessionId, audienceType, audienceId)`.
+ * - Soft-renews at `expiresAt - softRenewSkewMs` (configurable).
+ * - Honors server `cacheHintTtlSeconds` from `AuthorityGrantResponse` as
+ *   an upper bound on the cached lifetime.
+ * - Listens for `AuthorityGrantRevocation` push events and invalidates
+ *   matching entries by `grantId` OR `rootGrantId` (cascade).
+ * - `deriveForTask(...)` uses the idempotent `DERIVE_FOR_TARGET` op so
+ *   repeated calls return the same grant rather than minting new ones.
+ *
+ * Concurrency: per-key in-flight Promise dedupe collapses concurrent
+ * `getOrExchange` / `deriveForTask` calls so only one network round-trip
+ * happens per cache key at a time.
+ *
+ * @module authority-cache
+ */
+
+/**
+ * Configuration for {@link AuthorityGrantCache}.
+ */
+interface AuthorityGrantCacheOptions {
+    /**
+     * Soft-renew skew, in milliseconds. Re-exchange a grant this long
+     * before its server-side `expiresAt`. Default: 30000 (30 s) to match
+     * the connection-lock heartbeat cadence.
+     */
+    softRenewSkewMs?: number;
+    /**
+     * Default per-op timeout (ms) passed through to the underlying client
+     * when the cache issues exchange / derive / revoke calls. Default:
+     * 10000.
+     */
+    opTimeoutMs?: number;
+    /**
+     * Wall-clock provider, returning unix-ms. Pluggable for tests.
+     * Default: `Date.now`.
+     */
+    clock?: () => number;
+    /**
+     * When true the cache treats `AuthorityGrantInfo.expiresAt` as
+     * unix-MILLISECONDS rather than unix-seconds. The proto comment on
+     * `AuthorityGrantInfo` says "Unix seconds" but the runtime
+     * `ACLAuthorityGrantInfo` uses milliseconds in practice — pick the
+     * unit your gateway emits. Default: `false` (seconds).
+     */
+    expiresAtInMillis?: boolean;
+}
+/** Subset of {@link AetherClient} the cache depends on. */
+interface AuthorityCacheClient {
+    exchangeAuthorityGrant(opts: Record<string, unknown>): Promise<AuthorityGrantResponse>;
+    deriveAuthorityGrantForTarget(opts: Record<string, unknown>): Promise<AuthorityGrantResponse>;
+    revokeAuthorityGrant(grantId: string, timeout?: number): Promise<AuthorityGrantResponse>;
+    _removeAuthorityCache?(cache: AuthorityGrantCache): void;
+}
+/**
+ * Per-actor cache of runtime authority grants. See module docstring for
+ * the behavioural contract.
+ */
+declare class AuthorityGrantCache {
+    private readonly _client;
+    private readonly _softRenewSkewMs;
+    private readonly _opTimeoutMs;
+    private readonly _clock;
+    private readonly _expiresAtInMillis;
+    private readonly _entries;
+    /** grantId -> set of cache keys, for fast revocation lookup. */
+    private readonly _grantIdIndex;
+    /** rootGrantId -> set of cache keys, for cascade invalidation. */
+    private readonly _rootGrantIdIndex;
+    /** In-flight per-key fetch promises, for single-flight de-dupe. */
+    private readonly _inflight;
+    private _closed;
+    constructor(client: AuthorityCacheClient, opts?: AuthorityGrantCacheOptions);
+    /**
+     * Return a cached grant for the (sourceSessionId, audienceType,
+     * audienceId) triplet, or exchange a fresh one. Callers MUST keep the
+     * rest of the request shape stable for a given key.
+     *
+     * Returns `null` when the gateway response is missing, has
+     * `success === false`, or carries no grant — callers should fall back
+     * to direct invocation or surface the error.
+     */
+    getOrExchange(opts: {
+        sourceSessionId: string;
+        audienceType?: string;
+        audienceId?: string;
+        workspaceScope?: string[];
+        resourceScope?: {
+            resourceType: string;
+            patterns: string[];
+        }[];
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        validWhileAudienceActive?: boolean;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        metadata?: Record<string, string>;
+        timeout?: number;
+    }): Promise<AuthorityGrantInfo | null>;
+    /**
+     * Idempotent derive for a target task: returns an existing visible
+     * grant matching (parentGrantId, taskId, audience) when one is in
+     * place, otherwise mints a new one via `DERIVE_FOR_TARGET`. Safe to
+     * call repeatedly without leaking grants.
+     */
+    deriveForTask(opts: {
+        parentGrantId: string;
+        taskId: string;
+        audienceType?: string;
+        audienceId?: string;
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        timeout?: number;
+    }): Promise<AuthorityGrantInfo | null>;
+    /** General form of {@link deriveForTask} for arbitrary target principals. */
+    deriveForTarget(opts: {
+        parentGrantId: string;
+        targetType: string;
+        targetId: string;
+        audienceType?: string;
+        audienceId?: string;
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        timeout?: number;
+    }): Promise<AuthorityGrantInfo | null>;
+    /**
+     * Drop every cache entry whose grant ID OR root grant ID matches.
+     * Returns the number of entries dropped. Safe to call from any
+     * context.
+     */
+    invalidate(grantIdOrRoot: string): number;
+    /**
+     * Best-effort revoke every cached grant on the gateway, then clear.
+     * Per-grant errors are caught and logged via `console.warn`.
+     */
+    revokeAll(): Promise<void>;
+    /**
+     * Invalidate cache entries matching a server-pushed revocation event.
+     * Returns the number of entries dropped. Wired into the client
+     * dispatch loop by {@link AetherClient.makeAuthorityCache}; tests may
+     * also call this directly.
+     */
+    handleRevocationEvent(evt: AuthorityGrantRevocation): number;
+    /** Cache stats for observability tests. */
+    stats(): {
+        size: number;
+        grantIdsIndexed: number;
+        rootGrantIdsIndexed: number;
+    };
+    /**
+     * Report whether `grantId` is currently cached and fresh (not revoked,
+     * not past its soft-renew deadline). Cache-only — never round-trips to
+     * the gateway. Stale/revoked entries observed here are evicted as a
+     * side-effect.
+     */
+    isValid(grantId: string): boolean;
+    /**
+     * Return a snapshot of every cached grant that is currently fresh,
+     * de-duplicated by `grantId`. Stale/revoked entries observed during
+     * the snapshot are evicted as a side-effect.
+     */
+    listActive(): AuthorityGrantInfo[];
+    /**
+     * Drop `grantId` from the cache without calling the gateway. Alias of
+     * {@link invalidate} with a name that telegraphs the local-only
+     * semantics; the matching server-side revoke is
+     * {@link AetherClient.revokeAuthorityGrant}. Returns the number of
+     * entries dropped.
+     */
+    revokeLocal(grantId: string): number;
+    /**
+     * Force-drop a cached grant and re-exchange it.
+     *
+     * Returns `null` when the cache does not know `grantId`, the matching
+     * entry was originally derived (those cannot be refreshed via
+     * exchange — re-derive explicitly), or the underlying exchange fails.
+     */
+    refresh(grantId: string, opts?: {
+        workspaceScope?: string[];
+        resourceScope?: {
+            resourceType: string;
+            patterns: string[];
+        }[];
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        validWhileAudienceActive?: boolean;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        metadata?: Record<string, string>;
+        timeout?: number;
+    }): Promise<AuthorityGrantInfo | null>;
+    /**
+     * Deregister this cache from its parent client so it stops receiving
+     * AuthorityGrantRevocation events. Idempotent.
+     */
+    close(): void;
+    private _getUnexpired;
+    private _store;
+    private _drop;
+    private _index;
+    private _unindex;
+    private _withInflight;
+}
+
+/**
+ * Proxy HTTP support for the Aether TypeScript SDK.
+ *
+ * Provides `proxyHttp()` on AetherClient for tunneling HTTP requests through
+ * the Aether gRPC stream, and `AetherFetchTransport` as a drop-in replacement
+ * for the Web Fetch API transport layer.
+ *
+ * Bodies larger than CHUNK_THRESHOLD (256 KB) are split into
+ * ProxyHttpBodyChunk frames and reassembled on the response side.
+ *
+ * @module proxy
+ */
+
+/** Transport-layer error kinds from the gateway. */
+declare enum ProxyErrorKind {
+    Unknown = 0,
+    DialFailed = 1,
+    Timeout = 2,
+    UpstreamReset = 3,
+    AclDenied = 4,
+    SidecarUnavailable = 5,
+    PayloadTooLarge = 6,
+    DecodeFailed = 7
+}
+/** Transport-layer error from the gateway (not an HTTP error). */
+interface ProxyError {
+    readonly kind: ProxyErrorKind;
+    readonly message: string;
+}
+/** Structured response from a proxied HTTP request. */
+interface ProxyHttpResponse {
+    readonly requestId: string;
+    readonly statusCode: number;
+    readonly headers: Record<string, string>;
+    readonly body: Uint8Array;
+    readonly bodyChunked: boolean;
+    readonly error?: ProxyError;
+}
+/** Options for proxyHttp(). */
+interface ProxyHttpOptions {
+    /** Request headers to send. */
+    headers?: Record<string, string>;
+    /** Request body (raw bytes). */
+    body?: Uint8Array;
+    /** Timeout in milliseconds (default: 30 000). */
+    timeoutMs?: number;
+    /** Whether to follow HTTP redirects (default: true). */
+    followRedirects?: boolean;
+    /**
+     * Pin the request to a named terminator backend. The backend's allow-list
+     * still applies — explicit naming selects which backend's ACL is consulted,
+     * not whether the request is allowed.
+     */
+    backend?: string;
+    /**
+     * Opt into unbounded response streaming (SSE / log tails / model token
+     * streams). When true, ``timeoutMs`` becomes the time-to-first-byte
+     * deadline only; subsequent body bytes are governed by
+     * ``streamIdleTimeoutMs``. The response body is delivered as a real
+     * ``ReadableStream<Uint8Array>`` so consumers can iterate chunks as they
+     * arrive without buffering the whole response.
+     */
+    streamResponse?: boolean;
+    /**
+     * Idle deadline (ms) between body bytes when ``streamResponse=true``.
+     * Default 30 000 (30s) when unset. Exceeding closes the stream with
+     * ``ProxyError{TIMEOUT}``.
+     */
+    streamIdleTimeoutMs?: number;
+    /**
+     * Maximum total response body bytes when ``streamResponse=true``. 0 (the
+     * default) means "use the per-backend cap". Exceeding closes the stream
+     * with ``ProxyError{PAYLOAD_TOO_LARGE}``.
+     */
+    maxResponseBodyBytes?: number;
+}
+/** Error thrown when the proxy transport layer fails. */
+declare class ProxyHttpError extends Error {
+    readonly proxyError: ProxyError;
+    constructor(err: ProxyError);
+}
+/**
+ * Sends an HTTP request through the Aether gRPC stream to a service principal
+ * and returns a fetch-compatible `Response` object.
+ *
+ * @param client - Connected AetherClient instance
+ * @param target - Target topic, e.g. `"sv::memorylayer::default"` or wildcard `"sv::memorylayer"`
+ * @param method - HTTP method, e.g. `"GET"`, `"POST"`
+ * @param path   - Path including query string, e.g. `"/v1/memories/abc"`
+ * @param opts   - Optional headers, body, timeout, followRedirects
+ * @returns A `Response`-compatible object (standard Web API Response)
+ * @throws {@link ProxyHttpError} on transport-layer failure
+ * @throws {@link TimeoutError} if the request times out
+ * @throws {@link ConnectionError} if not connected
+ */
+declare function proxyHttp(client: AetherClient, target: string, method: string, path: string, opts?: ProxyHttpOptions): Promise<Response>;
+/**
+ * A drop-in transport for the Web Fetch API that routes requests through
+ * an Aether gRPC connection to a service principal.
+ *
+ * @example
+ * ```typescript
+ * const transport = new AetherFetchTransport(agentClient, "sv::memorylayer::default");
+ * const response = await transport.fetch("/v1/memories/abc");
+ * ```
+ */
+declare class AetherFetchTransport {
+    private readonly _client;
+    private readonly _target;
+    private readonly _defaultTimeoutMs;
+    private readonly _defaultBackend;
+    /**
+     * @param client  - Connected AetherClient
+     * @param target  - Default target topic (e.g. `"sv::memorylayer::default"`)
+     * @param timeoutMs - Default request timeout in ms (default: 30 000)
+     * @param backend - Optional default terminator backend name applied to
+     *   every request. The backend's allow-list still applies — explicit
+     *   naming selects which backend's ACL is consulted.
+     */
+    constructor(client: AetherClient, target: string, timeoutMs?: number, backend?: string);
+    /**
+     * Fetch-compatible method. Accepts a URL string or Request object plus
+     * optional RequestInit overrides.
+     *
+     * The URL hostname/protocol is ignored — requests are routed to the
+     * configured target topic. Only the pathname + search are used as the path.
+     *
+     * @returns Web API `Response`
+     */
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Base client implementation for the Aether TypeScript SDK.
+ *
+ * This module provides the AetherClient class that handles gRPC connection
+ * management, TLS configuration, message queue infrastructure, and automatic
+ * reconnection with exponential backoff. Specific client types (AgentClient,
+ * UserClient, etc.) extend this base client.
+ *
+ * Key architectural principle: The connection itself IS the distributed lock
+ * AND the heartbeat. When the gRPC stream closes, the identity lock is
+ * immediately released. No separate heartbeat API exists.
+ *
+ * @module client
+ */
+
+/**
+ * Configuration options for the base Aether client.
+ */
+interface AetherClientOptions {
+    /** Gateway address in host:port format. Required. */
+    address: string;
+    /** Optional TLS configuration for secure connections. */
+    tls?: TLSOptions;
+    /** Connection behavior configuration. */
+    connection?: ConnectionOptions;
+    /** Authentication credentials. */
+    credentials?: Credentials;
+    /** Whether to automatically reconnect on connection loss. Default: true. */
+    reconnect?: boolean;
+    /** Initial delay in ms between reconnect attempts. Default: 1000. */
+    reconnectDelay?: number;
+    /** Maximum delay in ms between reconnect attempts. Default: 30000. */
+    maxReconnectDelay?: number;
+    /**
+     * When true, if the gateway returns a DuplicateIdentityError (ALREADY_EXISTS)
+     * during connection, the client will wait and retry automatically.
+     * Shorthand for connection.retryOnDuplicate. Default: false.
+     */
+    retryOnDuplicate?: boolean;
+    /**
+     * How long to wait (ms) before retrying after a DuplicateIdentityError.
+     * Shorthand for connection.retryOnDuplicateDelay. Default: 5000.
+     */
+    retryOnDuplicateDelay?: number;
+}
+/** @internal */
+interface KVOperationParams {
+    op: "GET" | "PUT" | "LIST" | "DELETE" | "INCREMENT" | "DECREMENT" | "INCREMENT_IF" | "DECREMENT_IF";
+    scope: KVScope;
+    key?: string;
+    value?: Uint8Array;
+    userId?: string;
+    workspace?: string;
+    ttl?: number;
+    requestId?: string;
+    /** Guard value for INCREMENT_IF (ceiling) and DECREMENT_IF (floor) operations. */
+    guardValue?: bigint;
+    /** Step size for INCREMENT_IF / DECREMENT_IF. When omitted the server defaults to 1. */
+    deltaValue?: bigint;
+}
+/** @internal */
+interface CheckpointOperationParams {
+    op: "SAVE" | "LOAD" | "DELETE" | "LIST";
+    key?: string;
+    data?: Uint8Array;
+    ttl?: number;
+    requestId?: string;
+}
+/**
+ * Base client for connecting to the Aether distributed control plane.
+ *
+ * AetherClient manages the gRPC bidirectional streaming connection,
+ * handles automatic reconnection with exponential backoff, and provides
+ * the message send/receive infrastructure.
+ *
+ * This class is not typically used directly. Instead, use one of the
+ * specialized client types:
+ * - {@link AgentClient} for agent connections
+ * - {@link UserClient} for user/browser connections
+ *
+ * @example
+ * ```typescript
+ * import { AetherClient } from "@scitrera/aether-client";
+ *
+ * const client = new AetherClient({ address: "localhost:50051" });
+ *
+ * client.onMessage((msg) => {
+ *   console.log(`Received from ${msg.sourceTopic}:`, msg.payload);
+ * });
+ *
+ * await client.connect();
+ * ```
+ */
+declare class AetherClient {
+    protected readonly _address: string;
+    protected readonly _tls: TLSOptions | undefined;
+    protected readonly _connectionOpts: Required<ConnectionOptions>;
+    protected readonly _credentials: Credentials;
+    protected _connected: boolean;
+    protected _connecting: boolean;
+    protected _sessionId: string;
+    protected _resumeSessionId: string;
+    private _requestCounter;
+    private _onMessage;
+    private _onConfig;
+    private _onSignal;
+    private _onError;
+    private _onKVResponse;
+    private _onTaskAssignment;
+    private _onCheckpointResponse;
+    private _onProgress;
+    private _onConnect;
+    private _onDisconnect;
+    private _onReconnecting;
+    private _onTaskQueryResponse;
+    private _onTaskOperationResponse;
+    private _onCreateTaskResponse;
+    private _onWorkspaceResponse;
+    private _onAgentResponse;
+    private _onACLResponse;
+    private _onAuthorityGrantResponse;
+    private _onAuthorityGrantRevocation;
+    private _onAuditSubmitResponse;
+    private _authorityGrantCaches;
+    private _onWorkflowResponse;
+    private _onTokenResponse;
+    private _onChatMessage;
+    private _onControlMessage;
+    private _onToolCallMessage;
+    private _onEventMessage;
+    private _onMetricMessage;
+    private _pendingKVRequests;
+    private _pendingCheckpointRequests;
+    private _pendingTaskQueryRequests;
+    private _pendingTaskOpRequests;
+    private _pendingCreateTaskRequests;
+    private _pendingWorkspaceRequests;
+    private _pendingAgentRequests;
+    private _pendingACLRequests;
+    private _pendingAuthorityGrantRequests;
+    private _pendingWorkflowRequests;
+    private _pendingAuditSubmitRequests;
+    private _pendingTokenRequests;
+    _pendingProxyHttpRequests: Map<string, (response: ProxyHttpResponse) => void>;
+    _pendingProxyHttpChunks: Map<string, Uint8Array<ArrayBufferLike>[]>;
+    _pendingProxyHttpStreams: Map<string, {
+        controller: ReadableStreamDefaultController<Uint8Array>;
+        headerResolved: boolean;
+    }>;
+    _pendingTunnels: Map<string, TunnelInflight>;
+    private _kvClient;
+    private _checkpointClient;
+    private readonly _retryOnDuplicate;
+    private readonly _retryOnDuplicateDelay;
+    private readonly _retryOnDuplicateMaxAttempts;
+    private _grpcClient;
+    private _stream;
+    private _disconnectRequested;
+    private _reconnecting;
+    private _packageDefinition;
+    /**
+     * Creates a new AetherClient.
+     *
+     * The client is created but not connected. Call {@link connect} to establish
+     * the connection to the gateway.
+     *
+     * @param options - Client configuration options
+     * @throws {@link InvalidArgumentError} if the address is not provided
+     */
+    constructor(options: AetherClientOptions);
+    /**
+     * Establishes a connection to the Aether gateway.
+     *
+     * Opens a gRPC bidirectional stream and sends the InitConnection message.
+     * If auto-reconnect is enabled, the client will automatically attempt to
+     * reconnect on connection loss.
+     *
+     * If `retryOnDuplicate` is enabled and the gateway responds with a
+     * DuplicateIdentityError (ALREADY_EXISTS), the client will wait briefly
+     * and retry up to `retryOnDuplicateMaxAttempts` times. This handles the
+     * race condition where a previous instance's lock has not yet expired.
+     *
+     * @throws {@link ConnectionError} if the connection cannot be established
+     * @throws {@link DuplicateIdentityError} if identity is already connected
+     *   and retryOnDuplicate is disabled or exhausted
+     */
+    connect(): Promise<void>;
+    /**
+     * Attempts connection, retrying on DuplicateIdentityError.
+     * @internal
+     */
+    private _connectWithDuplicateRetry;
+    /**
+     * Gracefully disconnects from the Aether gateway.
+     *
+     * Closes the gRPC stream and releases the identity lock on the server.
+     * Automatic reconnection is suppressed for this disconnection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Returns whether the client is currently connected to the gateway.
+     */
+    get connected(): boolean;
+    /**
+     * Returns the current session ID assigned by the gateway.
+     * Empty string if not connected.
+     */
+    get sessionId(): string;
+    /**
+     * Sends a message through the Aether gateway.
+     *
+     * @param message - The outgoing message to send
+     * @throws {@link ConnectionError} if not connected
+     */
+    send(message: OutgoingMessage): Promise<void>;
+    /**
+     * Sends a KV operation through the gateway.
+     * @internal Used by KVClient.
+     */
+    sendKVOperation(params: KVOperationParams): void;
+    /**
+     * Sends a checkpoint operation through the gateway.
+     * @internal Used by CheckpointClient.
+     */
+    sendCheckpointOperation(params: CheckpointOperationParams): void;
+    /**
+     * Registers a handler for incoming messages.
+     *
+     * @param handler - Function called when a message is received
+     *
+     * @example
+     * ```typescript
+     * client.onMessage((msg) => {
+     *   console.log(`From ${msg.sourceTopic}: ${new TextDecoder().decode(msg.payload)}`);
+     * });
+     * ```
+     */
+    onMessage(handler: MessageHandler): void;
+    /**
+     * Registers a handler for configuration snapshots.
+     *
+     * Called once when the connection is established, providing the initial
+     * KV store state for the workspace.
+     *
+     * @param handler - Function called when a config snapshot is received
+     */
+    onConfig(handler: ConfigHandler): void;
+    /**
+     * Registers a handler for signals from the gateway.
+     *
+     * @param handler - Function called when a signal is received
+     */
+    onSignal(handler: SignalHandler): void;
+    /**
+     * Registers a handler for error responses from the gateway.
+     *
+     * @param handler - Function called when an error response is received
+     */
+    onError(handler: ErrorHandler): void;
+    /**
+     * Registers a handler for KV operation responses.
+     *
+     * @param handler - Function called when a KV response is received
+     */
+    onKVResponse(handler: KVResponseHandler): void;
+    /**
+     * Registers a handler for task assignments.
+     *
+     * Used by orchestrators to receive task assignments that require
+     * starting new agent or task instances.
+     *
+     * @param handler - Function called when a task assignment is received
+     */
+    onTaskAssignment(handler: TaskAssignmentHandler): void;
+    /**
+     * Registers a handler for checkpoint operation responses.
+     *
+     * @param handler - Function called when a checkpoint response is received
+     */
+    onCheckpointResponse(handler: CheckpointResponseHandler): void;
+    /**
+     * Registers a handler for progress updates from agents/tasks.
+     *
+     * Progress updates are delivered via the pg.{workspace} stream with
+     * server-side recipient filtering.
+     *
+     * @param handler - Function called when a progress update is received
+     */
+    onProgress(handler: ProgressHandler): void;
+    /**
+     * Registers a handler for successful connections.
+     *
+     * Called both for initial connection and reconnections.
+     *
+     * @param handler - Function called with the connection acknowledgment
+     */
+    onConnect(handler: ConnectHandler): void;
+    /**
+     * Registers a handler for disconnection events.
+     *
+     * Called before any automatic reconnection attempt.
+     *
+     * @param handler - Function called with the disconnection reason
+     */
+    onDisconnect(handler: DisconnectHandler): void;
+    /**
+     * Registers a handler for reconnection attempts.
+     *
+     * @param handler - Function called with the attempt number
+     */
+    onReconnecting(handler: ReconnectingHandler): void;
+    /**
+     * Registers a handler for task query responses.
+     *
+     * @param handler - Function called when a task query response is received
+     */
+    onTaskQueryResponse(handler: TaskQueryResponseHandler): void;
+    /**
+     * Registers a handler for task operation responses.
+     *
+     * @param handler - Function called when a task operation response is received
+     */
+    onTaskOperationResponse(handler: TaskOperationResponseHandler): void;
+    /**
+     * Registers a handler for create-task responses (fire-and-forget path,
+     * i.e. when no request_id is supplied or a response arrives without a
+     * matching pending entry).
+     *
+     * @param handler - Function called when a create-task response is received
+     */
+    onCreateTaskResponse(handler: CreateTaskResponseHandler): void;
+    /**
+     * Registers a handler for Chat messages.
+     *
+     * @param handler - Function called when a Chat message is received
+     */
+    onChatMessage(handler: MessageHandler): void;
+    /**
+     * Registers a handler for Control messages.
+     *
+     * @param handler - Function called when a Control message is received
+     */
+    onControlMessage(handler: MessageHandler): void;
+    /**
+     * Registers a handler for ToolCall messages.
+     *
+     * @param handler - Function called when a ToolCall message is received
+     */
+    onToolCallMessage(handler: MessageHandler): void;
+    /**
+     * Registers a handler for Event messages.
+     *
+     * @param handler - Function called when an Event message is received
+     */
+    onEventMessage(handler: MessageHandler): void;
+    /**
+     * Registers a handler for Metric messages.
+     *
+     * @param handler - Function called when a Metric message is received
+     */
+    onMetricMessage(handler: MessageHandler): void;
+    /**
+     * Returns the KV operations client.
+     *
+     * @returns The KVClient instance for performing KV store operations
+     *
+     * @example
+     * ```typescript
+     * const kv = client.kv();
+     * const response = await kv.getSync({ key: "my-key", scope: KVScope.Global });
+     * ```
+     */
+    kv(): KVClient;
+    /**
+     * Returns the checkpoint operations client.
+     *
+     * @returns The CheckpointClient instance for checkpoint save/load/delete/list
+     *
+     * @example
+     * ```typescript
+     * const cp = client.checkpoint();
+     * const response = await cp.loadSync({ key: "my-state" });
+     * ```
+     */
+    checkpoint(): CheckpointClient;
+    /**
+     * Generates a unique request ID for correlating responses.
+     * @internal
+     */
+    nextRequestId(): string;
+    /**
+     * Registers a pending KV request for response correlation.
+     * @internal
+     */
+    registerPendingKVRequest(requestId: string, callback: (response: KVResponse) => void): void;
+    /**
+     * Registers a pending checkpoint request for response correlation.
+     * @internal
+     */
+    registerPendingCheckpointRequest(requestId: string, callback: (response: CheckpointResponse) => void): void;
+    /**
+     * Removes a pending request (used on timeout cleanup).
+     * @internal
+     */
+    removePendingRequest(requestId: string): void;
+    /**
+     * Builds the InitConnection message for the connection handshake.
+     * Subclasses override this to provide their specific identity.
+     * @internal
+     */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Establishes the gRPC connection and starts the message loop.
+     * @internal
+     */
+    private _establishConnection;
+    /**
+     * Closes the gRPC connection.
+     * @internal
+     */
+    private _closeConnection;
+    /**
+     * Sends an upstream message on the gRPC stream.
+     * @internal
+     */
+    protected _sendUpstream(message: Record<string, unknown>): void;
+    /**
+     * Routes a downstream message to the appropriate handler.
+     * @internal
+     */
+    private _handleDownstreamMessage;
+    /**
+     * Handles gRPC stream errors.
+     * @internal
+     */
+    private _handleStreamError;
+    /**
+     * Handles gRPC stream end.
+     * @internal
+     */
+    private _handleStreamEnd;
+    /**
+     * Attempts automatic reconnection with exponential backoff.
+     * @internal
+     */
+    private _attemptReconnection;
+    /**
+     * Reports progress for a task through the Aether gateway.
+     *
+     * Progress updates are routed through RabbitMQ Streams via the pg.{workspace}
+     * topic with server-side recipient filtering.
+     *
+     * @param opts - Progress report options
+     * @throws {@link ConnectionError} if not connected
+     */
+    reportProgress(opts: ReportProgressOptions): void;
+    /**
+     * Encodes a Metric object to protobuf bytes using the loaded proto descriptor.
+     *
+     * Uses the `aether.v1.Metric` type from the package definition stored at
+     * connection time. Throws if the descriptor is not yet available — sending
+     * JSON-encoded bytes here would silently fail on the gateway with
+     * ERR_METRIC_INVALID, so we eagerly surface the misuse.
+     *
+     * @param metric - The metric object to encode
+     * @returns Encoded bytes
+     * @internal
+     */
+    protected _encodeMetric(metric: Record<string, unknown>): Uint8Array;
+    /**
+     * Low-level message send helper used by subclasses.
+     * @internal
+     */
+    protected _sendMessage(targetTopic: string, payload: Uint8Array, messageType: MessageType): void;
+    /**
+     * Parses a raw task info object from the server into a TaskInfo.
+     * @internal
+     */
+    private _parseTaskInfo;
+    /**
+     * Parses a raw authority grant object from the server into an AuthorityGrantInfo.
+     * @internal
+     */
+    private _parseAuthorityGrantInfo;
+    /**
+     * Lists tasks with optional filters.
+     */
+    queryTasks(opts?: TaskQueryOptions): Promise<TaskQueryResponse>;
+    /**
+     * Gets a specific task by ID.
+     */
+    getTask(taskId: string, timeout?: number): Promise<TaskQueryResponse>;
+    /**
+     * Cancels a running or queued task.
+     */
+    cancelTask(taskId: string, reason?: string, timeout?: number): Promise<TaskOperationResponse>;
+    /**
+     * Retries a failed task.
+     */
+    retryTask(taskId: string, timeout?: number): Promise<TaskOperationResponse>;
+    /**
+     * Completes a task (for POOL workers).
+     */
+    completeTask(taskId: string, timeout?: number): Promise<TaskOperationResponse>;
+    /**
+     * Marks a task as failed (for POOL workers).
+     */
+    failTask(taskId: string, reason?: string, timeout?: number): Promise<TaskOperationResponse>;
+    /**
+     * Sends a CreateTaskRequest and waits for the server's CreateTaskResponse.
+     *
+     * A unique request_id is injected automatically so the response can be
+     * correlated.  Unlike the fire-and-forget `createTask` override in subclasses,
+     * this method blocks until the gateway echoes back the assigned task_id.
+     *
+     * @param op - CreateTaskRequest fields (task_type, workspace, assignment_mode, etc.)
+     * @param timeout - Timeout in ms (default 10 000)
+     * @returns Promise resolving to the CreateTaskResponse
+     */
+    createTaskBlocking(op: Record<string, unknown>, timeout?: number): Promise<CreateTaskResponse>;
+    /**
+     * Sends a workspace operation upstream.
+     *
+     * @param op - The workspace operation payload
+     * @param timeout - Timeout in ms
+     * @returns Promise resolving to the workspace response
+     */
+    sendWorkspaceOperation(op: Record<string, unknown>, timeout?: number): Promise<WorkspaceResponse>;
+    /**
+     * Sends an agent operation upstream.
+     *
+     * @param op - The agent operation payload
+     * @param timeout - Timeout in ms
+     * @returns Promise resolving to the agent response
+     */
+    sendAgentOperation(op: Record<string, unknown>, timeout?: number): Promise<AgentResponse>;
+    /**
+     * Sends an ACL operation upstream.
+     *
+     * @param op - The ACL operation payload
+     * @param timeout - Timeout in ms
+     * @returns Promise resolving to the ACL response
+     */
+    sendACLOperation(op: Record<string, unknown>, timeout?: number): Promise<ACLResponse>;
+    /**
+     * Sends a runtime authority-grant operation upstream.
+     *
+     * @param op - The authority grant operation payload
+     * @param timeout - Timeout in ms
+     * @returns Promise resolving to the authority-grant response
+     */
+    sendAuthorityGrantOperation(op: Record<string, unknown>, timeout?: number): Promise<AuthorityGrantResponse>;
+    /**
+     * Submits a foreign audit event to the gateway's audit pipeline.
+     *
+     * @param opts - Audit event fields
+     * @param timeout - Timeout in ms (default 10 000)
+     * @returns Promise resolving to the audit-submit response
+     */
+    submitAuditEvent(opts: {
+        eventType: string;
+        operation?: string;
+        resourceType?: string;
+        resourceId?: string;
+        workspace?: string;
+        success?: boolean;
+        errorMessage?: string;
+        metadata?: Record<string, string>;
+    }, timeout?: number): Promise<AuditSubmitResponse>;
+    /**
+     * Sends a workflow operation upstream.
+     *
+     * @param op - The workflow operation payload
+     * @param timeout - Timeout in ms
+     * @returns Promise resolving to the workflow response
+     */
+    sendWorkflowOperation(op: Record<string, unknown>, timeout?: number): Promise<WorkflowResponse>;
+    /**
+     * Registers a handler for workspace operation responses.
+     *
+     * @param handler - Function called when a workspace response is received
+     */
+    onWorkspaceResponse(handler: WorkspaceResponseHandler): void;
+    /**
+     * Registers a handler for agent operation responses.
+     *
+     * @param handler - Function called when an agent response is received
+     */
+    onAgentResponse(handler: AgentResponseHandler): void;
+    /**
+     * Registers a handler for ACL operation responses.
+     *
+     * @param handler - Function called when an ACL response is received
+     */
+    onACLResponse(handler: ACLResponseHandler): void;
+    /**
+     * Registers a handler for runtime authority-grant responses.
+     *
+     * @param handler - Function called when an authority-grant response is received
+     */
+    onAuthorityGrantResponse(handler: AuthorityGrantResponseHandler): void;
+    /**
+     * Registers a handler for unsolicited audit-submit responses (i.e. responses
+     * not correlated to a pending {@link submitAuditEvent} call).
+     *
+     * @param handler - Function called when an audit-submit response is received
+     */
+    onAuditSubmitResponse(handler: AuditSubmitResponseHandler): void;
+    /**
+     * Registers a handler for server-pushed AuthorityGrantRevocation events.
+     * Caches registered via {@link makeAuthorityCache} are invoked first; the
+     * user handler runs after every cache has been notified.
+     */
+    onAuthorityGrantRevocation(handler: AuthorityGrantRevocationHandler): void;
+    /**
+     * Bootstrap a runtime authority grant for the current actor.
+     *
+     * If `sourceSessionId` is empty, only a user may self-exchange. When it
+     * is set, the caller must hold the `_perm:exchange_authority_grants`
+     * permission and the referenced session must belong to an active user.
+     */
+    exchangeAuthorityGrant(opts?: {
+        sourceSessionId?: string;
+        workspaceScope?: string[];
+        resourceScope?: {
+            resourceType: string;
+            patterns: string[];
+        }[];
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        audienceType?: string;
+        audienceId?: string;
+        validWhileAudienceActive?: boolean;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        metadata?: Record<string, string>;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /**
+     * Derive a child runtime authority grant for a downstream delegate.
+     */
+    deriveAuthorityGrant(opts: {
+        parentGrantId: string;
+        delegateType: string;
+        delegateId: string;
+        workspaceScope?: string[];
+        resourceScope?: {
+            resourceType: string;
+            patterns: string[];
+        }[];
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        audienceType?: string;
+        audienceId?: string;
+        validWhileAudienceActive?: boolean;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        metadata?: Record<string, string>;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /** Get a runtime authority grant by ID. */
+    getAuthorityGrant(grantId: string, timeout?: number): Promise<AuthorityGrantResponse>;
+    /**
+     * Renew a runtime authority grant lease. `expiresAt` (proto units) takes
+     * precedence; `extendSeconds` extends the current expiry by N seconds
+     * server-side and is ignored when `expiresAt` is non-zero.
+     */
+    renewAuthorityGrant(opts: {
+        grantId: string;
+        expiresAt?: number;
+        extendSeconds?: number;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /** Revoke a runtime authority grant by ID. */
+    revokeAuthorityGrant(grantId: string, timeout?: number): Promise<AuthorityGrantResponse>;
+    /** List grants where the actor is delegate or subject. */
+    listMyAuthorityGrants(opts?: {
+        audienceType?: string;
+        audienceId?: string;
+        includeRevoked?: boolean;
+        limit?: number;
+        offset?: number;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /** List grants where the actor is the subject (i.e., grants OTHERS hold on me). */
+    listAuthorityGrantsOnMe(opts?: {
+        audienceType?: string;
+        audienceId?: string;
+        includeRevoked?: boolean;
+        limit?: number;
+        offset?: number;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /** Exchange multiple authority grants in a single round-trip. */
+    batchExchangeAuthorityGrants(opts: {
+        requests: Record<string, unknown>[];
+        stopOnFirstError?: boolean;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /**
+     * Idempotent derive: returns existing visible grant matching
+     * (parentGrantId, target, audience) or mints a new one.
+     *
+     * Safe to call repeatedly without leaking grants.
+     */
+    deriveAuthorityGrantForTarget(opts: {
+        parentGrantId: string;
+        targetType: string;
+        targetId: string;
+        audienceType?: string;
+        audienceId?: string;
+        operationScope?: string[];
+        maxAccessLevel?: number;
+        expiresAt?: number;
+        renewableUntil?: number;
+        mayDelegate?: boolean;
+        remainingHops?: number;
+        reason?: string;
+        timeout?: number;
+    }): Promise<AuthorityGrantResponse>;
+    /**
+     * Construct a new {@link AuthorityGrantCache} wired into this client.
+     * AuthorityGrantRevocation push events on the downstream stream are
+     * dispatched to the cache automatically. Call {@link AuthorityGrantCache.close}
+     * to deregister it.
+     */
+    makeAuthorityCache(opts?: AuthorityGrantCacheOptions): AuthorityGrantCache;
+    /** @internal */
+    _removeAuthorityCache(cache: AuthorityGrantCache): void;
+    /**
+     * Registers a handler for workflow operation responses.
+     *
+     * @param handler - Function called when a workflow response is received
+     */
+    onWorkflowResponse(handler: WorkflowResponseHandler): void;
+    /**
+     * Sends a token management operation to the gateway.
+     *
+     * @param op - The token operation payload
+     * @param timeout - Timeout in ms
+     * @returns Promise resolving to the token response
+     */
+    sendTokenOperation(op: Record<string, unknown>, timeout?: number): Promise<TokenResponse>;
+    /**
+     * Registers a handler for token operation responses.
+     *
+     * @param handler - Function called when a token response is received
+     */
+    onTokenResponse(handler: TokenResponseHandler): void;
+}
+
+/**
+ * Admin client for the Aether TypeScript SDK.
+ *
+ * AdminClient wraps a connected AetherClient and provides named helper methods
+ * for all administrative operations exposed through the gRPC streaming protocol:
+ * token management, ACL rules, workspace CRUD, agent registry, and gateway
+ * health / connection queries.
+ *
+ * The underlying AetherClient must already be connected before calling any
+ * AdminClient method. All methods return Promises that resolve when the
+ * gateway sends the correlated response, or reject on timeout.
+ *
+ * @module admin
+ */
+
+/** Timeout option shared by all admin methods. */
+interface AdminTimeoutOptions {
+    /** Operation timeout in milliseconds. Default: 10000. */
+    timeout?: number;
+}
+/** Options for creating an API token. */
+interface CreateTokenOptions extends AdminTimeoutOptions {
+    /** Human-readable name for the token. Required. */
+    name: string;
+    /** Principal type this token authenticates (e.g., "agent", "user"). */
+    principalType?: string;
+    /** Glob patterns for workspaces this token may access. */
+    workspacePatterns?: string[];
+    /** Permission scopes granted by this token. */
+    scopes?: string[];
+    /** Expiry duration in seconds from now (0 = no expiry). */
+    expiresInSeconds?: number;
+}
+/** Options for revoking an API token. */
+interface RevokeTokenOptions extends AdminTimeoutOptions {
+    /** Token ID to revoke. Required. */
+    tokenId: string;
+}
+/** Options for listing API tokens. */
+interface ListTokensOptions extends AdminTimeoutOptions {
+    /** Filter by principal type. */
+    principalType?: string;
+    /** If true, include revoked tokens in results. */
+    includeRevoked?: boolean;
+    /** Maximum number of results to return. */
+    limit?: number;
+}
+/** Options for creating an ACL rule (granting access). */
+interface CreateACLRuleOptions extends AdminTimeoutOptions {
+    /** Principal type being granted access (e.g., "agent", "user"). Required. */
+    principalType: string;
+    /** Principal ID being granted access. Required. */
+    principalId: string;
+    /** Resource type the access applies to (e.g., "workspace"). Required. */
+    resourceType: string;
+    /** Resource ID the access applies to. Required. */
+    resourceId: string;
+    /** Permission level (e.g., "read", "write", "admin"). Required. */
+    permission: string;
+    /** Optional expiry as Unix timestamp (seconds). 0 = no expiry. */
+    expiresAt?: number;
+    /** Arbitrary metadata to attach to the rule. */
+    metadata?: Record<string, string>;
+}
+/** Options for deleting an ACL rule. */
+interface DeleteACLRuleOptions extends AdminTimeoutOptions {
+    /** Rule ID to delete. Required. */
+    ruleId: string;
+}
+/** Options for listing ACL rules. */
+interface ListACLRulesOptions extends AdminTimeoutOptions {
+    /** Filter by principal type. */
+    principalType?: string;
+    /** Filter by principal ID. */
+    principalId?: string;
+    /** Filter by resource type. */
+    resourceType?: string;
+    /** Filter by resource ID. */
+    resourceId?: string;
+}
+/** Options for reading a fallback policy by category. */
+interface GetFallbackPolicyOptions extends AdminTimeoutOptions {
+    /**
+     * Rule category, formatted as "{principal_type}_{resource_type}" (e.g.,
+     * "user_workspace", "agent_kv_scope", "service_kv_scope").
+     */
+    ruleCategory: string;
+}
+/** Options for upserting a fallback policy. */
+interface SetFallbackPolicyOptions extends AdminTimeoutOptions {
+    /** Rule category to upsert. */
+    ruleCategory: string;
+    /**
+     * Default access level when no explicit acl_rules row matches. Use the
+     * numeric tiers from internal/acl/types.go: 0=NONE, 10=READ, 20=READWRITE,
+     * 30=MANAGE, 40=ADMIN, 50=SUPERADMIN.
+     */
+    fallbackAccessLevel: number;
+}
+/** Options for listing workspaces. */
+interface ListWorkspacesOptions extends AdminTimeoutOptions {
+    /** Maximum number of results to return. */
+    limit?: number;
+    /** Offset for pagination. */
+    offset?: number;
+}
+/** Data for creating a workspace. */
+interface CreateWorkspaceOptions extends AdminTimeoutOptions {
+    /** Workspace ID (the string identifier). Required. */
+    workspaceId: string;
+    /** Human-readable display name. */
+    displayName?: string;
+    /** Arbitrary metadata. */
+    metadata?: Record<string, string>;
+}
+/** Data for updating a workspace. */
+interface UpdateWorkspaceOptions extends AdminTimeoutOptions {
+    /** Workspace ID to update. Required. */
+    workspaceId: string;
+    /** New display name. */
+    displayName?: string;
+    /** Updated metadata. */
+    metadata?: Record<string, string>;
+}
+/** Options for deleting a workspace. */
+interface DeleteWorkspaceOptions extends AdminTimeoutOptions {
+    /** Workspace ID to delete. Required. */
+    workspaceId: string;
+}
+/** Options for listing registered agent types. */
+interface ListAgentsOptions extends AdminTimeoutOptions {
+    /** Filter by workspace. */
+    workspace?: string;
+    /** Maximum number of results to return. */
+    limit?: number;
+}
+/** Options for getting a specific agent registration. */
+interface GetAgentOptions extends AdminTimeoutOptions {
+    /** The agent implementation name. Required. */
+    implementation: string;
+}
+/** Response from admin queries. Loosely typed to accommodate the AdminResponse oneof. */
+interface AdminQueryResponse {
+    readonly success: boolean;
+    readonly error: string;
+    readonly health?: Record<string, unknown>;
+    readonly info?: Record<string, unknown>;
+    readonly stats?: Record<string, unknown>;
+    readonly connection?: Record<string, unknown>;
+    readonly connections?: Record<string, unknown>[];
+    readonly totalCount: number;
+}
+/** Handler type for admin query responses. */
+type AdminQueryResponseHandler = (response: AdminQueryResponse) => void | Promise<void>;
+/** Options for listing connections. */
+interface ListConnectionsOptions extends AdminTimeoutOptions {
+    /** Filter by workspace. */
+    workspace?: string;
+    /** Filter by principal type. */
+    principalType?: string;
+}
+/** Options for disconnecting a session. */
+interface DisconnectSessionOptions extends AdminTimeoutOptions {
+    /** Session ID to disconnect. Required. */
+    sessionId: string;
+    /** Optional reason message sent to the disconnected client. */
+    reason?: string;
+}
+/**
+ * Administrative client for managing an Aether gateway.
+ *
+ * AdminClient wraps any connected {@link AetherClient} (typically an
+ * AgentClient or UserClient) and exposes named helper methods for the full
+ * set of administrative operations that are available through the gRPC
+ * streaming protocol.
+ *
+ * @example
+ * ```typescript
+ * import { AgentClient, AdminClient } from "@scitrera/aether-client";
+ *
+ * const agent = new AgentClient({
+ *   address: "localhost:50051",
+ *   workspace: "default",
+ *   implementation: "admin-agent",
+ *   specifier: "ops-1",
+ *   credentials: { "x-api-key": "my-admin-key" },
+ * });
+ * await agent.connect();
+ *
+ * const admin = new AdminClient(agent);
+ *
+ * // List workspaces
+ * const wsr = await admin.listWorkspaces();
+ * console.log(wsr);
+ *
+ * // Create a token
+ * const tr = await admin.createToken({ name: "ci-token", principalType: "agent" });
+ * console.log(tr.plaintextToken);
+ * ```
+ */
+declare class AdminClient {
+    private readonly _client;
+    /**
+     * Creates an AdminClient backed by the given AetherClient.
+     *
+     * The AetherClient must be connected before calling any method.
+     *
+     * @param client - A connected AetherClient instance
+     */
+    constructor(client: AetherClient);
+    /**
+     * Creates a new API token.
+     *
+     * @param opts - Token creation parameters
+     * @returns Promise resolving to the token response (includes plaintextToken)
+     */
+    createToken(opts: CreateTokenOptions): Promise<TokenResponse>;
+    /**
+     * Revokes an API token by ID.
+     *
+     * @param opts - Revoke options containing the token ID
+     * @returns Promise resolving to the token response
+     */
+    revokeToken(opts: RevokeTokenOptions): Promise<TokenResponse>;
+    /**
+     * Lists API tokens with optional filters.
+     *
+     * @param opts - List options
+     * @returns Promise resolving to the token response (tokens array)
+     */
+    listTokens(opts?: ListTokensOptions): Promise<TokenResponse>;
+    /**
+     * Creates an ACL rule granting access.
+     *
+     * @param opts - ACL rule creation parameters
+     * @returns Promise resolving to the ACL response
+     */
+    createACLRule(opts: CreateACLRuleOptions): Promise<ACLResponse>;
+    /**
+     * Deletes an ACL rule by ID.
+     *
+     * @param opts - Delete options containing the rule ID
+     * @returns Promise resolving to the ACL response
+     */
+    deleteACLRule(opts: DeleteACLRuleOptions): Promise<ACLResponse>;
+    /**
+     * Lists ACL rules with optional filters.
+     *
+     * @param opts - List options
+     * @returns Promise resolving to the ACL response (rules array in response)
+     */
+    listACLRules(opts?: ListACLRulesOptions): Promise<ACLResponse>;
+    /**
+     * Reads the fallback policy for a rule category.
+     *
+     * Fallback policies decide the default ACL outcome when no explicit
+     * `acl_rules` row matches the (principal_type, resource_type) pair.
+     * The `ruleCategory` is the catonical
+     * `{principal_type}_{resource_type}` slug — e.g., "agent_kv_scope".
+     */
+    getFallbackPolicy(opts: GetFallbackPolicyOptions): Promise<ACLResponse>;
+    /**
+     * Upserts a fallback policy for a rule category.
+     *
+     * Use ``fallbackAccessLevel: 0`` to flip a category to default-deny.
+     */
+    setFallbackPolicy(opts: SetFallbackPolicyOptions): Promise<ACLResponse>;
+    /**
+     * Lists workspaces.
+     *
+     * @param opts - List options
+     * @returns Promise resolving to the workspace response
+     */
+    listWorkspaces(opts?: ListWorkspacesOptions): Promise<WorkspaceResponse>;
+    /**
+     * Creates a new workspace.
+     *
+     * @param opts - Workspace creation parameters
+     * @returns Promise resolving to the workspace response
+     */
+    createWorkspace(opts: CreateWorkspaceOptions): Promise<WorkspaceResponse>;
+    /**
+     * Updates an existing workspace.
+     *
+     * @param opts - Workspace update parameters
+     * @returns Promise resolving to the workspace response
+     */
+    updateWorkspace(opts: UpdateWorkspaceOptions): Promise<WorkspaceResponse>;
+    /**
+     * Deletes a workspace by ID.
+     *
+     * @param opts - Delete options containing the workspace ID
+     * @returns Promise resolving to the workspace response
+     */
+    deleteWorkspace(opts: DeleteWorkspaceOptions): Promise<WorkspaceResponse>;
+    /**
+     * Lists registered agent types.
+     *
+     * @param opts - List options
+     * @returns Promise resolving to the agent response
+     */
+    listAgents(opts?: ListAgentsOptions): Promise<AgentResponse>;
+    /**
+     * Gets the registration details for a specific agent implementation.
+     *
+     * @param opts - Options including the implementation name
+     * @returns Promise resolving to the agent response
+     */
+    getAgent(opts: GetAgentOptions): Promise<AgentResponse>;
+    /**
+     * Queries gateway health, including component status for Redis, RabbitMQ,
+     * and PostgreSQL.
+     *
+     * Note: This sends a GET_HEALTH admin query through the gRPC stream.
+     * The gateway must have admin-over-stream enabled.
+     *
+     * @param timeout - Timeout in milliseconds (default: 10000)
+     * @returns Promise resolving to the admin query response
+     */
+    getHealth(timeout?: number): Promise<AdminQueryResponse>;
+    /**
+     * Lists active connections on the gateway.
+     *
+     * @param opts - Optional filter and timeout options
+     * @returns Promise resolving to the admin query response (connections array)
+     */
+    getConnections(opts?: ListConnectionsOptions): Promise<AdminQueryResponse>;
+    /**
+     * Forcibly disconnects a session by session ID.
+     *
+     * @param opts - Options containing the session ID and optional reason
+     * @returns Promise resolving to the workspace response
+     */
+    disconnectSession(opts: DisconnectSessionOptions): Promise<WorkspaceResponse>;
+}
+
+/**
+ * MetricEntry is one additive delta within a Metric message.
+ */
+interface MetricEntry {
+    /**
+     * e.g. "tokens_in", "time_seconds", "pages_rendered"
+     */
+    'name'?: (string);
+    /**
+     * sub-classifier, e.g. "modelA", "" (free-form, may be empty)
+     */
+    'kind'?: (string);
+    /**
+     * additive delta; negative requires capability/metric_credit
+     */
+    'qty'?: (number | string);
+}
+
+/**
+ * Metric is the canonical payload for SendMessage when message_type == METRIC.
+ * All entries are interpreted as additive deltas; negative qty requires the
+ * `capability/metric_credit` ACL permission on the sender.
+ */
+interface Metric {
+    /**
+     * Optional correlation ID (request/trace) tying these entries to upstream work.
+     */
+    'traceId'?: (string);
+    /**
+     * One or more counter deltas. At least one entry is required.
+     */
+    'entries'?: (MetricEntry)[];
+    /**
+     * Free-form tags / hints. Documented well-known keys:
+     * lifecycle      = "startup" | "shutdown"
+     * source.version, source.region, source.host, ...
+     */
+    'metadata'?: ({
+        [key: string]: string;
+    });
+    /**
+     * Optional client-side timestamp (ms since epoch). The server always also
+     * stamps MessageEnvelope.timestamp_ms; this is for client-side ordering hints.
+     */
+    'clientTimestampMs'?: (number | string | Long);
+}
+
+/**
+ * Fluent builder for constructing Metric payloads.
+ *
+ * Metric is the canonical payload for SendMessage when message_type == METRIC.
+ * All entries are interpreted as additive deltas; negative qty values require
+ * the `capability/metric_credit` ACL permission on the sender.
+ *
+ * @module metrics-builder
+ *
+ * @example
+ * ```typescript
+ * import { newMetric } from "@scitrera/aether-client";
+ *
+ * const metric = newMetric()
+ *   .trace("req-abc-123")
+ *   .add("tokens_in", "modelA", 512)
+ *   .add("tokens_out", "modelA", 128)
+ *   .tag("source.version", "1.0.0")
+ *   .clientTimestampMs(Date.now())
+ *   .build();
+ *
+ * agent.sendMetric(metric);
+ * ```
+ */
+
+/**
+ * Fluent builder for constructing a {@link Metric}.
+ */
+declare class MetricBuilder {
+    private m;
+    constructor();
+    /**
+     * Sets the optional correlation/trace ID tying these entries to upstream work.
+     */
+    trace(id: string): this;
+    /**
+     * Adds a metric entry (additive delta).
+     *
+     * @param name - Counter name, e.g. "tokens_in", "time_seconds"
+     * @param kind - Sub-classifier, e.g. "modelA" (may be empty)
+     * @param qty  - Additive delta; negative requires `capability/metric_credit`
+     */
+    add(name: string, kind: string, qty: number): this;
+    /**
+     * Adds a free-form metadata tag.
+     *
+     * Well-known keys: lifecycle ("startup" | "shutdown"),
+     * source.version, source.region, source.host, ...
+     */
+    tag(key: string, value: string): this;
+    /**
+     * Sets the optional client-side timestamp (ms since epoch).
+     *
+     * The server always stamps its own authoritative timestamp on the
+     * MessageEnvelope; this field is an advisory ordering hint only.
+     *
+     * Accepts `number` or `string` to support int64 values that exceed
+     * `Number.MAX_SAFE_INTEGER` (the generated proto type allows both,
+     * driven by `--longs=String` in compile_protos.sh).
+     */
+    clientTimestampMs(ts: number | string): this;
+    /**
+     * Returns the constructed Metric object.
+     */
+    build(): Metric;
+}
+/**
+ * Creates a new {@link MetricBuilder}.
+ *
+ * @example
+ * ```typescript
+ * const metric = newMetric()
+ *   .add("tokens_in", "gpt4", 512)
+ *   .build();
+ * ```
+ */
+declare function newMetric(): MetricBuilder;
+
+/**
+ * Agent client implementation for the Aether TypeScript SDK.
+ *
+ * This module provides the AgentClient class for connecting to the Aether
+ * gateway as an agent. Agents are persistent entities with
+ * workspace/implementation/specifier identity that can send and receive
+ * messages, manage state, and participate in task orchestration.
+ *
+ * @module agents
+ */
+
+/**
+ * Configuration options for the AgentClient.
+ */
+interface AgentClientOptions extends AetherClientOptions {
+    /** The workspace to connect to. Required. */
+    workspace: string;
+    /** The agent implementation type. Required. */
+    implementation: string;
+    /** The unique specifier for this agent instance. Required. */
+    specifier: string;
+}
+/**
+ * Options for creating a task.
+ */
+interface CreateTaskOptions {
+    /** The type of task to create. Required. */
+    taskType: string;
+    /** The workspace for the task. If empty, uses the agent's workspace. */
+    workspace?: string;
+    /** For TARGETED mode: the agent to assign to. */
+    targetAgentId?: string;
+    /** For POOL mode: the agent implementation type to match. */
+    targetImplementation?: string;
+    /** Optional parameter overrides for orchestration. */
+    launchParamOverrides?: Record<string, string>;
+    /** Optional task metadata. */
+    metadata?: Record<string, string>;
+    /** Assignment mode. Default: SelfAssign. */
+    assignmentMode?: TaskAssignmentMode;
+}
+/**
+ * Client for connecting to the Aether gateway as an agent.
+ *
+ * Agents are persistent entities identified by workspace, implementation,
+ * and specifier. Each agent identity can only have one active connection
+ * at a time (Connection = Lock paradigm).
+ *
+ * AgentClient extends AetherClient and adds agent-specific functionality:
+ * - Identity management (workspace, implementation, specifier)
+ * - Messaging helpers (sendToAgent, sendToUser, sendToTask, broadcast)
+ * - Event and metric publishing
+ * - Workspace switching
+ * - Task creation
+ *
+ * @example
+ * ```typescript
+ * import { AgentClient } from "@scitrera/aether-client";
+ *
+ * const agent = new AgentClient({
+ *   address: "localhost:50051",
+ *   workspace: "prod",
+ *   implementation: "data-processor",
+ *   specifier: "instance-1",
+ * });
+ *
+ * agent.onMessage((msg) => {
+ *   console.log(`Received from ${msg.sourceTopic}:`, msg.payload);
+ * });
+ *
+ * await agent.connect();
+ * ```
+ */
+declare class AgentClient extends AetherClient {
+    private _workspace;
+    private readonly _implementation;
+    private readonly _specifier;
+    /**
+     * Creates a new AgentClient.
+     *
+     * @param options - Agent client configuration
+     * @throws {@link InvalidArgumentError} if required fields are missing
+     */
+    constructor(options: AgentClientOptions);
+    /** Returns the agent's current workspace. */
+    get workspace(): string;
+    /** Returns the agent's implementation type. */
+    get implementation(): string;
+    /** Returns the agent's specifier (instance identifier). */
+    get specifier(): string;
+    /**
+     * Returns this agent's topic address.
+     *
+     * Format: ag.{workspace}.{implementation}.{specifier}
+     */
+    get topic(): string;
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Switches the agent's workspace.
+     *
+     * Sends a SwitchWorkspace message to the gateway, which will update
+     * the agent's topic subscription and optionally send a new ConfigSnapshot.
+     *
+     * @param newWorkspace - The new workspace to switch to
+     * @throws {@link InvalidArgumentError} if the workspace is empty
+     */
+    switchWorkspace(newWorkspace: string): void;
+    /**
+     * Sends a message to a specific agent.
+     *
+     * @param workspace - Target agent's workspace
+     * @param implementation - Target agent's implementation type
+     * @param specifier - Target agent's specifier
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific task.
+     *
+     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     *
+     * @param workspace - Target task's workspace
+     * @param implementation - Target task's implementation type
+     * @param specifier - Target task's specifier (empty for broadcast)
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific user session.
+     *
+     * @param userId - Target user's ID
+     * @param windowId - Target user's window/session ID
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToUser(userId: string, windowId: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a user's workspace scope.
+     *
+     * This reaches the user regardless of which window/tab they are using.
+     *
+     * @param userId - Target user's ID
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToUserWorkspace(userId: string, workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to all agents in a workspace.
+     *
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    broadcastToAgents(workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to all users in a workspace.
+     *
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    broadcastToUsers(workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Publishes an event to the workflow engine.
+     *
+     * @param payload - Event payload (bytes)
+     */
+    sendEvent(payload: Uint8Array): void;
+    /**
+     * Publishes a metric to the metrics bridge.
+     *
+     * @param metric - Structured metric to publish. Use {@link newMetric} to construct one.
+     */
+    sendMetric(metric: Metric): void;
+    /**
+     * Creates a new task with the specified parameters.
+     *
+     * @param opts - Task creation options
+     * @throws {@link InvalidArgumentError} if task type is missing
+     */
+    createTask(opts: CreateTaskOptions): void;
+    /**
+     * Registers a handler specifically for task-related messages.
+     *
+     * Filters incoming messages to only those from task topics (tu.* or ta.*).
+     *
+     * @param handler - Function called when a task message is received
+     */
+    onTaskMessage(handler: MessageHandler): void;
+    /**
+     * Registers a handler specifically for control messages.
+     *
+     * Note: Since the base protocol delivers all messages through a single
+     * stream, this filters based on source topic prefixes. For more granular
+     * filtering, use onMessage directly and inspect the payload.
+     *
+     * @param handler - Function called when a control message is received
+     */
+    onControlMessage(handler: MessageHandler): void;
+}
+
+/**
+ * Task client implementation for the Aether TypeScript SDK.
+ *
+ * This module provides the TaskClient class for connecting to the Aether
+ * gateway as a task. Tasks can be unique (named, with a specifier) or
+ * non-unique (server-assigned ID, load-balanced via broadcast topic).
+ *
+ * @module tasks
+ */
+
+/**
+ * Configuration options for the TaskClient.
+ */
+interface TaskClientOptions extends AetherClientOptions {
+    /** The workspace to connect to. Required. */
+    workspace: string;
+    /** The task implementation type. Required. */
+    implementation: string;
+    /** Unique specifier for this task. Empty for non-unique tasks. */
+    uniqueSpecifier?: string;
+}
+/**
+ * Client for connecting to the Aether gateway as a task.
+ *
+ * Tasks come in two flavors:
+ * - **Unique tasks** (with specifier): Persistent identity like agents,
+ *   only one connection at a time. Topic: tu.{workspace}.{impl}.{spec}
+ * - **Non-unique tasks** (empty specifier): Server-assigned ID, multiple
+ *   instances allowed. Subscribe to both ta.{workspace}.{impl}.{id} and
+ *   the shared tb.{workspace}.{impl} broadcast for work claiming.
+ *
+ * @example
+ * ```typescript
+ * // Unique task
+ * const task = new TaskClient({
+ *   address: "localhost:50051",
+ *   workspace: "prod",
+ *   implementation: "report-gen",
+ *   uniqueSpecifier: "daily-report",
+ * });
+ *
+ * // Non-unique task (worker pool)
+ * const worker = new TaskClient({
+ *   address: "localhost:50051",
+ *   workspace: "prod",
+ *   implementation: "data-processor",
+ * });
+ * ```
+ */
+declare class TaskClient extends AetherClient {
+    private _workspace;
+    private readonly _implementation;
+    private readonly _uniqueSpecifier;
+    constructor(options: TaskClientOptions);
+    get workspace(): string;
+    get implementation(): string;
+    get uniqueSpecifier(): string;
+    /** Whether this is a unique (named) task. */
+    get isUnique(): boolean;
+    /**
+     * Returns this task's topic address.
+     * For unique tasks: tu.{workspace}.{impl}.{spec}
+     * For non-unique tasks: returns the broadcast topic tb.{workspace}.{impl}
+     * (the actual instance topic is assigned by the server).
+     */
+    get topic(): string;
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Switches the task's workspace.
+     *
+     * @param newWorkspace - The new workspace to switch to
+     * @throws {@link InvalidArgumentError} if the workspace is empty
+     */
+    switchWorkspace(newWorkspace: string): void;
+    /**
+     * Sends a message to a specific agent.
+     */
+    sendToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific task.
+     * For unique tasks (with specifier), uses tu.* topic.
+     * For non-unique tasks (empty specifier), uses tb.* broadcast topic.
+     */
+    sendToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific user session.
+     */
+    sendToUser(userId: string, windowId: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Publishes an event to the workflow engine.
+     */
+    sendEvent(payload: Uint8Array): void;
+    /**
+     * Publishes a metric to the metrics bridge.
+     *
+     * @param metric - Structured metric to publish. Use {@link newMetric} to construct one.
+     */
+    sendMetric(metric: Metric): void;
+    /**
+     * Creates a new task with the specified parameters.
+     *
+     * @param opts - Task creation options
+     * @throws {@link InvalidArgumentError} if task type is missing
+     */
+    createTask(opts: CreateTaskOptions): void;
+}
+
+/**
+ * User client implementation for the Aether TypeScript SDK.
+ *
+ * This module provides the UserClient class for connecting to the Aether
+ * gateway as a user. Users are identified by userId and windowId, allowing
+ * multiple browser tabs or sessions per user.
+ *
+ * Per the Aether specification, users can only send direct messages.
+ * They cannot publish events or metrics like agents and tasks can.
+ *
+ * @module users
+ */
+
+/**
+ * Configuration options for the UserClient.
+ */
+interface UserClientOptions extends AetherClientOptions {
+    /** The user's unique identifier. Required. */
+    userId: string;
+    /** The window/session identifier. Required. */
+    windowId: string;
+    /** Optional initial workspace association. */
+    workspace?: string;
+}
+/**
+ * Client for connecting to the Aether gateway as a user.
+ *
+ * Users are identified by userId and windowId, allowing multiple browser
+ * tabs or sessions per user. Each user session (userId + windowId combination)
+ * is unique and can only have one active connection at a time.
+ *
+ * UserClient extends AetherClient and adds user-specific functionality:
+ * - Identity management (userId, windowId)
+ * - Messaging helpers (sendToAgent, sendToUser, sendToTask)
+ * - Optional workspace association
+ *
+ * Note: Per the Aether specification, users can only send direct messages.
+ * They cannot publish events or metrics.
+ *
+ * @example
+ * ```typescript
+ * import { UserClient } from "@scitrera/aether-client";
+ *
+ * const user = new UserClient({
+ *   address: "localhost:50051",
+ *   userId: "alice",
+ *   windowId: "tab-1",
+ * });
+ *
+ * user.onIncomingMessage((msg) => {
+ *   console.log(`Received from ${msg.sourceTopic}:`, msg.payload);
+ * });
+ *
+ * await user.connect();
+ *
+ * // Send a message to an agent
+ * const encoder = new TextEncoder();
+ * user.sendToAgent("prod", "data-processor", "instance-1",
+ *   encoder.encode(JSON.stringify({ action: "process" }))
+ * );
+ * ```
+ */
+declare class UserClient extends AetherClient {
+    private readonly _userId;
+    private readonly _windowId;
+    private _workspace;
+    /**
+     * Creates a new UserClient.
+     *
+     * @param options - User client configuration
+     * @throws {@link InvalidArgumentError} if required fields are missing
+     */
+    constructor(options: UserClientOptions);
+    /** Returns the user's unique identifier. */
+    get userId(): string;
+    /** Returns the user's window/session identifier. */
+    get windowId(): string;
+    /** Returns the user's current workspace (if set). */
+    get workspace(): string;
+    /**
+     * Returns this user's topic address.
+     *
+     * Format: us.{userId}.{windowId}
+     */
+    get topic(): string;
+    /**
+     * Returns this user's workspace-scoped topic address.
+     *
+     * Format: uw.{userId}.{workspace}
+     *
+     * Returns empty string if no workspace is set.
+     */
+    get workspaceTopic(): string;
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Sets the user's current workspace for workspace-scoped operations.
+     *
+     * This is a local operation that does not notify the gateway.
+     *
+     * @param workspace - The workspace to associate with
+     */
+    setWorkspace(workspace: string): void;
+    /**
+     * Switches the user's workspace on the gateway.
+     *
+     * Sends a SwitchWorkspace message to the gateway, which will update
+     * topic subscriptions (including progress) and send a new ConfigSnapshot.
+     *
+     * @param newWorkspace - The new workspace to switch to
+     * @throws {@link InvalidArgumentError} if the workspace is empty
+     */
+    switchWorkspace(newWorkspace: string): void;
+    /**
+     * Sends a message to a specific agent.
+     *
+     * @param workspace - Target agent's workspace
+     * @param implementation - Target agent's implementation type
+     * @param specifier - Target agent's specifier
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific task.
+     *
+     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     *
+     * @param workspace - Target task's workspace
+     * @param implementation - Target task's implementation type
+     * @param specifier - Target task's specifier (empty for broadcast)
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific user session.
+     *
+     * @param userId - Target user's ID
+     * @param windowId - Target user's window/session ID
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToUser(userId: string, windowId: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a user's workspace scope.
+     *
+     * @param userId - Target user's ID
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToUserWorkspace(userId: string, workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Creates a new task with the specified parameters.
+     *
+     * Users can create tasks targeting agents or task pools.
+     *
+     * @param opts - Task creation options
+     * @throws {@link InvalidArgumentError} if task type is missing
+     */
+    createTask(opts: CreateTaskOptions): void;
+    /**
+     * Registers a handler for all incoming messages.
+     *
+     * This is an alias for onMessage, provided for API clarity in the
+     * user context.
+     *
+     * @param handler - Function called when a message is received
+     */
+    onIncomingMessage(handler: MessageHandler): void;
+}
+
+/**
+ * Orchestrator client implementation for the Aether TypeScript SDK.
+ *
+ * Orchestrators manage agent/task lifecycle: receiving startup requests
+ * when targeted agents are offline, launching compute resources, and
+ * managing agent pools and scaling.
+ *
+ * @module orchestrator
+ */
+
+/**
+ * Configuration options for the OrchestratorClient.
+ */
+interface OrchestratorClientOptions extends AetherClientOptions {
+    /** The orchestrator implementation type (e.g., "kubernetes-orchestrator"). Required. */
+    implementation: string;
+    /** Profiles this orchestrator supports (e.g., ["kubernetes", "docker"]). Required, at least one. */
+    supportedProfiles: string[];
+    /** Unique specifier for this instance. Auto-generated if not provided. */
+    specifier?: string;
+}
+/**
+ * Client for connecting to the Aether gateway as an orchestrator.
+ *
+ * Orchestrators receive task assignments via the onTaskAssignment handler
+ * and are responsible for launching the appropriate compute resources.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new OrchestratorClient({
+ *   address: "localhost:50051",
+ *   implementation: "k8s-orchestrator",
+ *   supportedProfiles: ["kubernetes"],
+ * });
+ *
+ * orchestrator.onTaskAssignment((assignment) => {
+ *   console.log(`Starting ${assignment.targetImplementation} for task ${assignment.taskId}`);
+ *   // Launch container based on assignment.launchParams
+ * });
+ *
+ * await orchestrator.connect();
+ * ```
+ */
+declare class OrchestratorClient extends AetherClient {
+    private readonly _implementation;
+    private readonly _specifier;
+    private readonly _supportedProfiles;
+    constructor(options: OrchestratorClientOptions);
+    get implementation(): string;
+    get specifier(): string;
+    get supportedProfiles(): string[];
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Sends a status/control message to an agent.
+     */
+    sendStatusToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a status/control message to a task.
+     * For unique tasks (with specifier), uses tu.* topic.
+     * For non-unique tasks (empty specifier), uses tb.* broadcast topic.
+     */
+    sendStatusToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+}
+/**
+ * Configuration options for BaseOrchestrator subclasses.
+ */
+interface BaseOrchestratorOptions extends OrchestratorClientOptions {
+    /**
+     * Whether to log task assignment details to the console.
+     * Default: false.
+     */
+    logAssignments?: boolean;
+}
+/**
+ * Abstract base class for building orchestrators.
+ *
+ * BaseOrchestrator wraps {@link OrchestratorClient} and provides a structured
+ * framework for managing agent/task lifecycle. Subclasses implement the
+ * abstract {@link launchTask} method to handle task assignments with their
+ * specific compute backend (Docker, Kubernetes, subprocess, etc.).
+ *
+ * The class manages the full orchestrator lifecycle:
+ * - Connecting to the Aether gateway as an Orchestrator principal
+ * - Receiving {@link TaskAssignment} messages and dispatching to launchTask
+ * - Error handling and logging hooks
+ *
+ * @example
+ * ```typescript
+ * import { BaseOrchestrator, TaskAssignment } from "@scitrera/aether-client";
+ *
+ * class MyOrchestrator extends BaseOrchestrator {
+ *   async launchTask(assignment: TaskAssignment): Promise<void> {
+ *     console.log(`Launching task ${assignment.taskId} (profile: ${assignment.profile})`);
+ *     // Start a subprocess, container, etc. using assignment.launchParams
+ *   }
+ * }
+ *
+ * const orch = new MyOrchestrator({
+ *   address: "localhost:50051",
+ *   implementation: "my-orchestrator",
+ *   supportedProfiles: ["my-profile"],
+ * });
+ *
+ * orch.onConnect((ack) => {
+ *   console.log(`Connected with session ${ack.sessionId}`);
+ * });
+ *
+ * await orch.connect();
+ * ```
+ */
+declare abstract class BaseOrchestrator {
+    /** The underlying OrchestratorClient for direct gateway access. */
+    readonly client: OrchestratorClient;
+    private readonly _logAssignments;
+    /**
+     * Creates a new BaseOrchestrator.
+     *
+     * @param options - Orchestrator configuration options
+     */
+    constructor(options: BaseOrchestratorOptions);
+    /**
+     * Called when the gateway assigns a task to this orchestrator.
+     *
+     * Subclasses must implement this method to launch the appropriate compute
+     * resource (container, process, VM, etc.) based on the assignment details.
+     *
+     * The assignment includes:
+     * - `taskId`: Unique task identifier
+     * - `profile`: The profile that matched (from supportedProfiles)
+     * - `targetImplementation`: The agent/task implementation to launch
+     * - `workspace`: The workspace this task belongs to
+     * - `specifier`: Optional unique specifier for the agent/task
+     * - `launchParams`: Key-value launch parameters (image, command, env vars, etc.)
+     * - `metadata`: Arbitrary task metadata
+     *
+     * @param assignment - The task assignment received from the gateway
+     */
+    abstract launchTask(assignment: TaskAssignment): void | Promise<void>;
+    /**
+     * Connects to the Aether gateway.
+     *
+     * Must be called before the orchestrator can receive task assignments.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the Aether gateway.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Returns whether the orchestrator is currently connected.
+     */
+    get connected(): boolean;
+    /**
+     * Returns the current session ID assigned by the gateway.
+     * Empty string if not connected.
+     */
+    get sessionId(): string;
+    /**
+     * Returns the orchestrator's implementation type.
+     */
+    get implementation(): string;
+    /**
+     * Returns the orchestrator's specifier.
+     */
+    get specifier(): string;
+    /**
+     * Returns the list of profiles this orchestrator supports.
+     */
+    get supportedProfiles(): string[];
+    /**
+     * Registers a handler for successful connection events.
+     *
+     * @param handler - Called with the ConnectionAck when connected
+     */
+    onConnect(handler: (ack: ConnectionAck) => void | Promise<void>): void;
+    /**
+     * Registers a handler for disconnection events.
+     *
+     * @param handler - Called with the reason string when disconnected
+     */
+    onDisconnect(handler: (reason: string) => void | Promise<void>): void;
+    /**
+     * Registers a handler for reconnection attempts.
+     *
+     * @param handler - Called with the attempt number on each reconnect try
+     */
+    onReconnecting(handler: (attempt: number) => void | Promise<void>): void;
+    /**
+     * Sends a status/control message to an agent.
+     *
+     * @param workspace - Target agent's workspace
+     * @param implementation - Target agent's implementation type
+     * @param specifier - Target agent's specifier
+     * @param payload - Message payload
+     * @param messageType - Message type. Default: Control
+     */
+    sendStatusToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a status/control message to a task.
+     *
+     * @param workspace - Target task's workspace
+     * @param implementation - Target task's implementation type
+     * @param specifier - Target task's specifier (empty for broadcast)
+     * @param payload - Message payload
+     * @param messageType - Message type. Default: Control
+     */
+    sendStatusToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Internal handler that logs and dispatches to launchTask.
+     * @internal
+     */
+    private _handleAssignment;
+}
+
+/**
+ * Workflow engine client implementation for the Aether TypeScript SDK.
+ *
+ * The workflow engine is the sole subscriber to event.* topics and processes
+ * broadcast events to trigger downstream actions by sending commands to
+ * agents/tasks. It is a singleton per gateway deployment.
+ *
+ * @module workflow
+ */
+
+/**
+ * Configuration options for the WorkflowEngineClient.
+ *
+ * No additional identity fields are needed — the workflow engine is
+ * identified by its principal type alone (singleton per gateway).
+ */
+type WorkflowEngineClientOptions = AetherClientOptions;
+/**
+ * Client for connecting to the Aether gateway as a workflow engine.
+ *
+ * The workflow engine receives all events (event.*) and can send commands
+ * to any principal type. It is the central event processor for the system.
+ *
+ * @example
+ * ```typescript
+ * const engine = new WorkflowEngineClient({
+ *   address: "localhost:50051",
+ * });
+ *
+ * engine.onMessage((msg) => {
+ *   // Process incoming events
+ *   const event = JSON.parse(new TextDecoder().decode(msg.payload));
+ *   console.log(`Event from ${msg.sourceTopic}:`, event);
+ * });
+ *
+ * await engine.connect();
+ * ```
+ */
+declare class WorkflowEngineClient extends AetherClient {
+    constructor(options: WorkflowEngineClientOptions);
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Sends a command to a specific agent.
+     */
+    sendCommandToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a command to a specific task.
+     * For unique tasks (with specifier), uses tu.* topic.
+     * For non-unique tasks (empty specifier), uses tb.* broadcast topic.
+     */
+    sendCommandToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a broadcast to all agents in a workspace.
+     */
+    broadcastToAgents(workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a broadcast to all users in a workspace.
+     */
+    broadcastToUsers(workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific user session.
+     */
+    sendToUser(userId: string, windowId: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Publishes a metric to the metrics bridge.
+     *
+     * @param metric - Structured metric to publish. Use {@link newMetric} to construct one.
+     */
+    sendMetric(metric: Metric): void;
+}
+
+/**
+ * Metrics bridge client implementation for the Aether TypeScript SDK.
+ *
+ * The metrics bridge is a receive-only client that subscribes to metric.*
+ * topics to collect telemetry data from agents and tasks. It is a singleton
+ * per gateway deployment.
+ *
+ * @module metrics
+ */
+
+/**
+ * Configuration options for the MetricsBridgeClient.
+ *
+ * No additional identity fields are needed — the metrics bridge is
+ * identified by its principal type alone (singleton per gateway).
+ */
+type MetricsBridgeClientOptions = AetherClientOptions;
+/**
+ * Client for connecting to the Aether gateway as a metrics bridge.
+ *
+ * The metrics bridge is receive-only: it subscribes to metric.* topics
+ * to collect telemetry data published by agents and tasks. It does not
+ * send messages to other principals.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new MetricsBridgeClient({
+ *   address: "localhost:50051",
+ * });
+ *
+ * bridge.onMessage((msg) => {
+ *   // Process incoming metrics
+ *   const metric = JSON.parse(new TextDecoder().decode(msg.payload));
+ *   console.log(`Metric from ${msg.sourceTopic}:`, metric);
+ * });
+ *
+ * await bridge.connect();
+ * ```
+ */
+declare class MetricsBridgeClient extends AetherClient {
+    constructor(options: MetricsBridgeClientOptions);
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Sends an acknowledgment to a source topic.
+     *
+     * @param targetTopic - The topic to send the acknowledgment to
+     * @param payload - The acknowledgment payload
+     */
+    sendAcknowledgment(targetTopic: string, payload: Uint8Array): void;
+}
+
+/**
+ * Bridge client implementation for the Aether TypeScript SDK.
+ *
+ * This module provides the BridgeClient class for connecting to the Aether
+ * gateway as a cross-workspace message bridge. Bridges relay messages across
+ * workspace boundaries and can send to any principal type in any workspace.
+ *
+ * Unlike workspace-scoped principals (agents, tasks, users), bridges have no
+ * workspace field in their identity — allowing them to send to targets in any
+ * workspace. Each bridge identity can only have one active connection at a time
+ * (Connection = Lock paradigm).
+ *
+ * @module bridge
+ */
+
+/**
+ * Configuration options for the BridgeClient.
+ */
+interface BridgeClientOptions extends AetherClientOptions {
+    /** The bridge implementation type (e.g., "aether-msgbridge", "webhook-bridge"). Required. */
+    implementation: string;
+    /** The unique specifier for this bridge instance (e.g., "default", "discord-1"). Required. */
+    specifier: string;
+}
+/**
+ * Client for connecting to the Aether gateway as a cross-workspace message bridge.
+ *
+ * Bridges are identified by implementation and specifier with no workspace field,
+ * allowing them to operate across workspace boundaries. Each bridge identity can
+ * only have one active connection at a time (Connection = Lock paradigm).
+ *
+ * BridgeClient extends AetherClient and adds bridge-specific functionality:
+ * - Identity management (implementation, specifier)
+ * - Messaging helpers to any workspace (sendToAgent, sendToUser, sendToTask, broadcast)
+ *
+ * Topic format: br.{implementation}.{specifier}
+ *
+ * @example
+ * ```typescript
+ * import { BridgeClient } from "@scitrera/aether-client";
+ *
+ * const bridge = new BridgeClient({
+ *   address: "localhost:50051",
+ *   implementation: "aether-msgbridge",
+ *   specifier: "discord-1",
+ * });
+ *
+ * bridge.onMessage((msg) => {
+ *   console.log(`Received from ${msg.sourceTopic}:`, msg.payload);
+ * });
+ *
+ * await bridge.connect();
+ *
+ * // Send to any workspace — bridges are cross-workspace
+ * const encoder = new TextEncoder();
+ * bridge.sendToAgent("prod", "my-agent", "instance-1", encoder.encode("Hello!"));
+ * bridge.sendToUser("alice", "tab-1", encoder.encode("Notification from Discord"));
+ * ```
+ */
+declare class BridgeClient extends AetherClient {
+    private readonly _implementation;
+    private readonly _specifier;
+    /**
+     * Creates a new BridgeClient.
+     *
+     * @param options - Bridge client configuration
+     * @throws {@link InvalidArgumentError} if required fields are missing
+     */
+    constructor(options: BridgeClientOptions);
+    /** Returns the bridge's implementation type. */
+    get implementation(): string;
+    /** Returns the bridge's specifier (instance identifier). */
+    get specifier(): string;
+    /**
+     * Returns this bridge's topic address.
+     *
+     * Format: br.{implementation}.{specifier}
+     */
+    get topic(): string;
+    /** @internal */
+    protected _buildInitMessage(): Record<string, unknown>;
+    /**
+     * Sends a message to a specific agent in any workspace.
+     *
+     * @param workspace - Target agent's workspace
+     * @param implementation - Target agent's implementation type
+     * @param specifier - Target agent's specifier
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToAgent(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific task in any workspace.
+     *
+     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     *
+     * @param workspace - Target task's workspace
+     * @param implementation - Target task's implementation type
+     * @param specifier - Target task's specifier (empty for broadcast)
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToTask(workspace: string, implementation: string, specifier: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a specific user session.
+     *
+     * @param userId - Target user's ID
+     * @param windowId - Target user's window/session ID
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToUser(userId: string, windowId: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to a user's workspace scope.
+     *
+     * This reaches the user regardless of which window/tab they are using.
+     *
+     * @param userId - Target user's ID
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    sendToUserWorkspace(userId: string, workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to all agents in a workspace.
+     *
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    broadcastToAgents(workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+    /**
+     * Sends a message to all users in a workspace.
+     *
+     * @param workspace - Target workspace
+     * @param payload - Message payload (bytes)
+     * @param messageType - Message type. Default: Chat
+     */
+    broadcastToUsers(workspace: string, payload: Uint8Array, messageType?: MessageType): void;
+}
+
+/**
+ * Error hierarchy for the Aether TypeScript SDK.
+ *
+ * This module provides a structured set of error classes that map to common
+ * error scenarios in Aether client operations, mirroring the error hierarchies
+ * in the Go SDK (errors.go) and Python SDK (exceptions.py).
+ *
+ * All errors extend the base AetherError class, making it easy to catch all
+ * SDK-related errors with a single catch clause.
+ *
+ * @module errors
+ */
+/**
+ * Base error class for all Aether SDK errors.
+ *
+ * All Aether-specific errors extend this class.
+ */
+declare class AetherError extends Error {
+    /** Optional error code (e.g., gRPC status code name). */
+    readonly code: string;
+    /** Optional additional error details. */
+    readonly details: string;
+    /** The underlying cause, if any. */
+    readonly cause?: Error;
+    constructor(message: string, code?: string, details?: string, cause?: Error);
+}
+/**
+ * Indicates a connection to the Aether gateway failed.
+ *
+ * This includes initial connection failures, network errors, and
+ * disconnection events that cannot be automatically recovered.
+ */
+declare class ConnectionError extends AetherError {
+    constructor(message?: string, code?: string, details?: string, cause?: Error);
+}
+/**
+ * Indicates the connection was unexpectedly closed.
+ *
+ * This can happen due to network issues, server restarts, or
+ * force disconnect signals from the server.
+ */
+declare class ConnectionClosedError extends AetherError {
+    /** Reason for the disconnection. */
+    readonly reason: string;
+    constructor(reason?: string, code?: string, cause?: Error);
+}
+/**
+ * Indicates automatic reconnection failed after exhausting all retries.
+ */
+declare class ReconnectionError extends AetherError {
+    /** Number of reconnection attempts made. */
+    readonly attempts: number;
+    constructor(attempts: number, cause?: Error);
+}
+/**
+ * Indicates authentication failed.
+ *
+ * Maps to gRPC UNAUTHENTICATED status code. Authentication errors
+ * are non-recoverable and will not trigger automatic reconnection.
+ */
+declare class AuthenticationError extends AetherError {
+    constructor(message?: string, details?: string, cause?: Error);
+}
+/**
+ * Indicates the client lacks permission to perform an operation.
+ *
+ * Maps to gRPC PERMISSION_DENIED status code. Permission errors
+ * are non-recoverable and will not trigger automatic reconnection.
+ */
+declare class PermissionDeniedError extends AetherError {
+    constructor(message?: string, details?: string, cause?: Error);
+}
+/**
+ * Indicates an identity is already in use.
+ *
+ * In Aether, each agent or unique task identity can only have one active
+ * connection at a time (Connection = Lock paradigm). This error indicates
+ * another client is already connected with the same identity.
+ *
+ * Maps to gRPC ALREADY_EXISTS status code.
+ */
+declare class DuplicateIdentityError extends AetherError {
+    /** The conflicting identity string. */
+    readonly identity: string;
+    constructor(identity?: string, details?: string, cause?: Error);
+}
+/**
+ * Indicates an operation timed out.
+ *
+ * This can occur during connection attempts, message sends, or
+ * synchronous KV/checkpoint operations.
+ *
+ * Maps to gRPC DEADLINE_EXCEEDED status code.
+ */
+declare class TimeoutError extends AetherError {
+    /** The operation that timed out. */
+    readonly operation: string;
+    /** The timeout duration that was exceeded, in seconds. */
+    readonly timeoutSeconds: number;
+    constructor(operation?: string, timeoutSeconds?: number, cause?: Error);
+}
+/**
+ * Indicates an invalid argument was provided to an operation.
+ *
+ * Maps to gRPC INVALID_ARGUMENT status code.
+ */
+declare class InvalidArgumentError extends AetherError {
+    /** The name of the invalid argument. */
+    readonly argument: string;
+    constructor(message?: string, argument?: string, cause?: Error);
+}
+/**
+ * Indicates a requested resource was not found.
+ *
+ * Maps to gRPC NOT_FOUND status code.
+ */
+declare class NotFoundError extends AetherError {
+    /** The resource that was not found. */
+    readonly resource: string;
+    constructor(resource?: string, cause?: Error);
+}
+/**
+ * Indicates an operation is not implemented by the server.
+ *
+ * Maps to gRPC UNIMPLEMENTED status code.
+ */
+declare class UnimplementedError extends AetherError {
+    /** The unimplemented operation name. */
+    readonly operation: string;
+    constructor(operation?: string, cause?: Error);
+}
+/**
+ * Indicates an error with message handling.
+ *
+ * This includes serialization errors, invalid message formats,
+ * or protocol violations.
+ */
+declare class MessageError extends AetherError {
+    constructor(message?: string, cause?: Error);
+}
+/**
+ * Indicates a KV store operation failed.
+ */
+declare class KVOperationError extends AetherError {
+    /** The KV operation that failed. */
+    readonly operation: string;
+    /** The key involved in the failed operation. */
+    readonly key: string;
+    constructor(operation?: string, key?: string, cause?: Error);
+}
+/**
+ * Indicates a checkpoint operation failed.
+ */
+declare class CheckpointError extends AetherError {
+    /** The checkpoint operation that failed. */
+    readonly operation: string;
+    /** The checkpoint key involved. */
+    readonly key: string;
+    constructor(operation?: string, key?: string, cause?: Error);
+}
+/**
+ * Checks if an error is recoverable (should trigger reconnection).
+ *
+ * Non-recoverable errors include authentication failures, permission denials,
+ * and other terminal error conditions.
+ *
+ * @param error - The error to check
+ * @returns true if the error is recoverable, false otherwise
+ */
+declare function isRecoverable(error: Error): boolean;
+/**
+ * Checks if an error is a connection-related error.
+ *
+ * @param error - The error to check
+ * @returns true if the error is connection-related
+ */
+declare function isConnectionError(error: Error): boolean;
+/**
+ * Checks if an error is a timeout-related error.
+ *
+ * @param error - The error to check
+ * @returns true if the error is timeout-related
+ */
+declare function isTimeoutError(error: Error): boolean;
+
+/** Prefix for agent topics. */
+declare const TOPIC_PREFIX_AGENT = "ag";
+/** Prefix for unique task topics. */
+declare const TOPIC_PREFIX_UNIQUE_TASK = "tu";
+/** Prefix for non-unique task topics. */
+declare const TOPIC_PREFIX_TASK = "ta";
+/** Prefix for task broadcast topics. */
+declare const TOPIC_PREFIX_TASK_BROADCAST = "tb";
+/** Prefix for user session topics. */
+declare const TOPIC_PREFIX_USER = "us";
+/** Prefix for user workspace topics. */
+declare const TOPIC_PREFIX_USER_WORKSPACE = "uw";
+/** Prefix for global agent broadcast topics. */
+declare const TOPIC_PREFIX_GLOBAL_AGENTS = "ga";
+/** Prefix for global user broadcast topics. */
+declare const TOPIC_PREFIX_GLOBAL_USERS = "gu";
+/** Prefix for event topics (workflow engine). */
+declare const TOPIC_PREFIX_EVENT = "event";
+/** Prefix for metric topics (metrics bridge). */
+declare const TOPIC_PREFIX_METRIC = "metric";
+/** Prefix for progress stream topics. */
+declare const TOPIC_PREFIX_PROGRESS = "pg";
+/** Prefix for bridge topics. */
+declare const TOPIC_PREFIX_BRIDGE = "br";
+/**
+ * Creates a topic string for a specific agent.
+ *
+ * @param workspace - The agent's workspace
+ * @param implementation - The agent's implementation type
+ * @param specifier - The agent's unique specifier
+ * @returns Topic string in format: ag::{workspace}::{implementation}::{specifier}
+ *
+ * @example
+ * ```typescript
+ * const topic = agentTopic("prod", "data-processor", "instance-1");
+ * // Returns: "ag::prod::data-processor::instance-1"
+ * ```
+ */
+declare function agentTopic(workspace: string, implementation: string, specifier: string): string;
+/**
+ * Creates a broadcast topic for all agents in a workspace.
+ *
+ * @param workspace - The workspace to broadcast to
+ * @returns Topic string in format: ga::{workspace}
+ */
+declare function globalAgentsTopic(workspace: string): string;
+/**
+ * Creates a topic string for a unique (named) task.
+ *
+ * @param workspace - The task's workspace
+ * @param implementation - The task's implementation type
+ * @param specifier - The task's unique specifier
+ * @returns Topic string in format: tu::{workspace}::{implementation}::{specifier}
+ */
+declare function uniqueTaskTopic(workspace: string, implementation: string, specifier: string): string;
+/**
+ * Creates a topic string for a non-unique task instance.
+ *
+ * @param workspace - The task's workspace
+ * @param implementation - The task's implementation type
+ * @param id - The server-assigned task instance ID
+ * @returns Topic string in format: ta::{workspace}::{implementation}::{id}
+ */
+declare function taskTopic(workspace: string, implementation: string, id: string): string;
+/**
+ * Creates a broadcast topic for task load balancing.
+ *
+ * Non-unique tasks subscribe to this topic to receive work items that can
+ * be claimed by any available worker of that implementation type.
+ *
+ * @param workspace - The task's workspace
+ * @param implementation - The task's implementation type
+ * @returns Topic string in format: tb::{workspace}::{implementation}
+ */
+declare function taskBroadcastTopic(workspace: string, implementation: string): string;
+/**
+ * Creates a topic string for a user session.
+ *
+ * @param userId - The user's unique identifier
+ * @param windowId - The window/session identifier
+ * @returns Topic string in format: us::{userId}::{windowId}
+ */
+declare function userTopic(userId: string, windowId: string): string;
+/**
+ * Creates a topic string for user workspace messages.
+ *
+ * Messages sent to this topic reach a specific user regardless of which
+ * window/tab they are using.
+ *
+ * @param userId - The user's unique identifier
+ * @param workspace - The workspace
+ * @returns Topic string in format: uw::{userId}::{workspace}
+ */
+declare function userWorkspaceTopic(userId: string, workspace: string): string;
+/**
+ * Creates a broadcast topic for all users in a workspace.
+ *
+ * @param workspace - The workspace to broadcast to
+ * @returns Topic string in format: gu::{workspace}
+ */
+declare function globalUsersTopic(workspace: string): string;
+/**
+ * Creates a topic string for broadcast events.
+ *
+ * @param eventType - The event type identifier
+ * @returns Topic string in format: event::{eventType}
+ */
+declare function eventTopic(eventType: string): string;
+/**
+ * Returns the wildcard pattern for all events.
+ *
+ * This is the topic that Workflow Engines subscribe to.
+ *
+ * @returns "event::*"
+ */
+declare function eventWildcardTopic(): string;
+/**
+ * Creates a topic string for telemetry/metrics.
+ *
+ * @param metricType - The metric type identifier
+ * @returns Topic string in format: metric::{metricType}
+ */
+declare function metricTopic(metricType: string): string;
+/**
+ * Returns the wildcard pattern for all metrics.
+ *
+ * This is the topic that Metrics Bridges subscribe to.
+ *
+ * @returns "metric::*"
+ */
+declare function metricWildcardTopic(): string;
+/**
+ * Creates a topic string for workspace progress updates.
+ *
+ * Progress updates from agents and tasks in a workspace are published to this
+ * topic. Users and agents subscribe to it with server-side recipient filtering.
+ *
+ * @param workspace - The workspace
+ * @returns Topic string in format: pg::{workspace}
+ */
+declare function progressTopic(workspace: string): string;
+/**
+ * Creates a topic string for a specific bridge instance.
+ *
+ * Bridges are cross-workspace principals identified only by implementation
+ * and specifier (no workspace component).
+ *
+ * @param implementation - The bridge implementation type (e.g., "aether-msgbridge")
+ * @param specifier - The bridge's unique specifier (e.g., "discord-1")
+ * @returns Topic string in format: br::{implementation}::{specifier}
+ *
+ * @example
+ * ```typescript
+ * const topic = bridgeTopic("aether-msgbridge", "discord-1");
+ * // Returns: "br::aether-msgbridge::discord-1"
+ * ```
+ */
+declare function bridgeTopic(implementation: string, specifier: string): string;
+
+export { type ACLResponse, type ACLResponseHandler, AdminClient, type AdminQueryResponse, type AdminQueryResponseHandler, type AdminTimeoutOptions, AetherClient, type AetherClientOptions, AetherError, AetherFetchTransport, AgentClient, type AgentClientOptions, type AgentResponse, type AgentResponseHandler, type AuditSubmitResponse, type AuditSubmitResponseHandler, AuthenticationError, type AuthorityCacheClient, AuthorityGrantCache, type AuthorityGrantCacheOptions, type AuthorityGrantInfo, type AuthorityGrantPrincipalRef, type AuthorityGrantResourceScope, type AuthorityGrantResponse, type AuthorityGrantResponseHandler, type AuthorityGrantRevocation, type AuthorityGrantRevocationHandler, BaseOrchestrator, type BaseOrchestratorOptions, BridgeClient, type BridgeClientOptions, CheckpointClient, type CheckpointDeleteOptions, CheckpointError, type CheckpointListOptions, type CheckpointLoadOptions, type CheckpointResponse, type CheckpointResponseHandler, type CheckpointSaveOptions, type ConfigHandler, type ConfigSnapshot, type ConnectHandler, type ConnectionAck, ConnectionClosedError, ConnectionError, type ConnectionOptions, type CreateACLRuleOptions, type CreateTaskOptions, type CreateTokenOptions, type CreateWorkspaceOptions, type Credentials, type DeleteACLRuleOptions, type DeleteWorkspaceOptions, type DisconnectHandler, type DisconnectSessionOptions, DuplicateIdentityError, type ErrorHandler, type ErrorResponse, type GetAgentOptions, type IncomingMessage, InvalidArgumentError, KVClient, type KVDecrementIfOptions, type KVDecrementOptions, type KVDeleteOptions, type KVGetOptions, type KVIncrementIfOptions, type KVIncrementOptions, type KVListOptions, KVOperationError, type KVPutOptions, type KVResponse, type KVResponseHandler, KVScope, type ListACLRulesOptions, type ListAgentsOptions, type ListConnectionsOptions, type ListTokensOptions, type ListWorkspacesOptions, MessageError, type MessageHandler, MessageType, type Metric, MetricBuilder, type MetricEntry, MetricsBridgeClient, type MetricsBridgeClientOptions, NotFoundError, OrchestratorClient, type OrchestratorClientOptions, type OutgoingMessage, PermissionDeniedError, PrincipalType, type ProgressHandler, type ProgressStep, type ProgressUpdate, type ProxyError, ProxyErrorKind, ProxyHttpError, type ProxyHttpOptions, type ProxyHttpResponse, type ReconnectingHandler, ReconnectionError, type ReportProgressOptions, type RevokeTokenOptions, type Signal, type SignalHandler, SignalType, type TLSOptions, TOPIC_PREFIX_AGENT, TOPIC_PREFIX_BRIDGE, TOPIC_PREFIX_EVENT, TOPIC_PREFIX_GLOBAL_AGENTS, TOPIC_PREFIX_GLOBAL_USERS, TOPIC_PREFIX_METRIC, TOPIC_PREFIX_PROGRESS, TOPIC_PREFIX_TASK, TOPIC_PREFIX_TASK_BROADCAST, TOPIC_PREFIX_UNIQUE_TASK, TOPIC_PREFIX_USER, TOPIC_PREFIX_USER_WORKSPACE, type TaskAssignment, type TaskAssignmentHandler, TaskAssignmentMode, TaskClient, type TaskClientOptions, type TaskInfo, type TaskOperationResponse, type TaskOperationResponseHandler, type TaskQueryOptions, type TaskQueryResponse, type TaskQueryResponseHandler, TimeoutError, type TokenInfo, type TokenResponse, type TokenResponseHandler, TunnelClosedError, type TunnelDialOptions, type TunnelProtocol, type TunnelStream, UnimplementedError, type UpdateWorkspaceOptions, UserClient, type UserClientOptions, WorkflowEngineClient, type WorkflowEngineClientOptions, type WorkflowResponse, type WorkflowResponseHandler, type WorkspaceResponse, type WorkspaceResponseHandler, agentTopic, bridgeTopic, eventTopic, eventWildcardTopic, globalAgentsTopic, globalUsersTopic, isConnectionError, isRecoverable, isTimeoutError, metricTopic, metricWildcardTopic, newMetric, progressTopic, proxyHttp, taskBroadcastTopic, taskTopic, tunnelDial, uniqueTaskTopic, userTopic, userWorkspaceTopic, withAPIKey, withTaskToken, withTenant, withToken };