@tinycloud/sdk-services 3.1.0-beta.7 → 3.1.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-qwMmB7qB.cjs';
-export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-qwMmB7qB.cjs';
+import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-CVwwxqXF.cjs';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-CVwwxqXF.cjs';
 import { z } from 'zod';
-import { B as BaseService } from './BaseService-C8zRy0ww.cjs';
-export { a as BaseServiceOptions, R as RequestSignal, S as ServiceConstructor, b as ServiceRegistration } from './BaseService-C8zRy0ww.cjs';
+import { B as BaseService } from './BaseService-DWbPbov7.cjs';
+export { a as BaseServiceOptions, R as RequestSignal, S as ServiceConstructor, b as ServiceRegistration } from './BaseService-DWbPbov7.cjs';
 import { IKVService } from './kv/index.cjs';
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVChange, KVChangesAuthority, KVChangesOptions, KVChangesResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.cjs';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.cjs';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.cjs';
@@ -1521,9 +1521,51 @@ interface SubscribeOptions {
 }
 interface HooksServiceConfig extends Record<string, unknown> {
     host?: string;
+    /** Shared-stream retry tuning; see {@link HookStreamRetryConfig}. */
+    streamRetry?: HookStreamRetryConfig;
+}
+/**
+ * Retry policy for the shared `/hooks/events` stream. When the stream fails
+ * (network error, 5xx, or an expired/rotated ticket rejected with 401/403)
+ * it is re-opened with exponential backoff: `HOOK_STREAM_RETRY_BASE_DELAY_MS`
+ * (~250 ms) doubling to `HOOK_STREAM_RETRY_MAX_DELAY_MS` (~30 s) with jitter.
+ * The retry streak resets after an event is received or a stream remains open
+ * for at least 5 seconds. Retries stop when no subscribers remain, when the
+ * service is aborted, or when minting the hook ticket is refused (the iterator
+ * throws that typed error instead).
+ */
+interface HookStreamRetryConfig {
+    /**
+     * Delay before retry attempt `attempt` (1-based). Defaults to the jittered
+     * exponential backoff described above. Must return milliseconds.
+     */
+    delay?: (attempt: number) => number;
+    /**
+     * How a retry delay is awaited — the injectable clock. `delayMs` is the
+     * resolved delay for `attempt`; `signal` aborts the wait early when the
+     * subscription set changes or the service stops. Rejecting or throwing is
+     * treated like a completed wait. After a custom wait returns — whether it
+     * fulfilled, rejected or threw — the service still yields one event-loop
+     * turn so a persistently failing stream can never starve the process.
+     * Defaults to an abortable, unref'd `setTimeout`.
+     */
+    wait?: (delayMs: number, attempt: number, signal: AbortSignal) => Promise<void>;
 }
 
 interface IHooksService {
+    /**
+     * Stream hook events until `options.signal` aborts, the SDK signs out or
+     * the session ends, or the consumer stops iterating. Transient stream
+     * failures — network errors, 5xx, and an expired or rotated ticket rejected
+     * by `/hooks/events` (401/403) — are retried internally with backoff and
+     * never reach the iterator.
+     *
+     * The iterator throws when minting the hook ticket is refused. The thrown
+     * plain `ServiceError` carries `meta.status` with the refusing HTTP status,
+     * so `for await` consumers can branch on it. Stream diagnostics contain only
+     * SDK allow-listed identifiers; foreign error messages and causes are not
+     * copied.
+     */
     subscribe(subscriptions: HookSubscription[], options?: SubscribeOptions): AsyncIterable<HookEvent>;
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
@@ -1534,10 +1576,13 @@ declare class HooksService extends BaseService implements IHooksService {
     static readonly serviceName = "hooks";
     protected _config: HooksServiceConfig;
     private readonly _subscribers;
-    private _sharedStreamTask?;
-    private _sharedStreamAbort?;
-    private _refreshChain;
-    private _activeSignature;
+    /** True while the one supervisor loop runs. Set only by wake(), cleared only at loop exit. */
+    private _supervising;
+    /** The supervisor's current step, interruptible by wake(). */
+    private _phase?;
+    /** Bumped on every session change; part of the plan key. */
+    private _sessionGeneration;
+    private _lastContextSignal?;
     constructor(config?: HooksServiceConfig);
     get config(): HooksServiceConfig;
     private get host();
@@ -1545,14 +1590,60 @@ declare class HooksService extends BaseService implements IHooksService {
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
     unregister(id: string, options?: HookWebhookUnregisterOptions): Promise<Result<void>>;
-    private scheduleSharedStreamRefresh;
-    private refreshSharedStream;
-    private collectSharedStreamState;
-    private runSharedStream;
-    private abortSharedStream;
+    /**
+     * Called after anything that may change what the supervisor should do:
+     * subscribe, unsubscribe, session change, sign-out. Interrupts the running
+     * step if the plan moved away from it, and starts the supervisor if none
+     * runs. Touches only SDK-owned state, so it never throws into callers such
+     * as `ServiceContext.setSession`.
+     */
+    private wake;
+    /**
+     * The only owner of the shared stream. Each iteration is one attempt
+     * (mint → open → drain), then a classification and, unless the attempt was
+     * superseded or released its subscribers, a backoff. Every await is a
+     * `phase` that wake() can interrupt; an interrupted phase yields
+     * `undefined`, so a superseded mint can never act. Outside `attempt` and
+     * `pause`, which each own one catch, the loop touches only SDK state.
+     */
+    private supervise;
+    /**
+     * Run one step under an interrupt that wake() fires when the plan key moves
+     * on. An interrupted step's result is discarded. The interrupt is also
+     * fired when the step returns, which releases whatever it left open: the
+     * request signal and its listeners, an unread response body, a timer.
+     */
+    private phase;
+    /**
+     * One mint → open → drain. The single catch site for everything the
+     * attempt touches that the SDK does not own: context accessors, invoke,
+     * fetch, response bodies, the SSE parser. Never rejects.
+     */
+    private attempt;
+    /**
+     * Back off before the next attempt. `config.streamRetry` overrides the
+     * delay and the clock; whatever they do, the pause ends by the delay or the
+     * interrupt, then yields one timer turn so an instant clock cannot starve
+     * due timers or the process.
+     */
+    private pause;
+    /** The stream the current subscribers need, or undefined when none remain. */
+    private plan;
+    private dispatch;
+    /**
+     * Detach every subscriber. With `error`, their iterators throw it after
+     * draining buffered events; without, they complete.
+     */
+    private release;
+    private report;
+    /**
+     * Unreachable by construction. If the loop ever rejects anyway, fail its
+     * subscribers visibly instead of stranding them or crashing the process.
+     */
+    private collapse;
+    onSessionChange(session: ServiceSession | null): void;
+    onSignOut(): void;
     private createHookHeaders;
-    private mintHookTicket;
-    private openHookStream;
     private createInvokeHeaders;
 }
 
@@ -2287,4 +2378,4 @@ declare class SecretsService implements ISecretsService {
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-export { type AuthorizationVerdict, BaseService, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, authorizationVerdictOf, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, isStorageFullError, networkError, notFoundError, parseAuthError, parseCapabilityResource, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, validatedCapabilityOf, wrapError };
+export { type AuthorizationVerdict, BaseService, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookStreamRetryConfig, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, authorizationVerdictOf, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, isStorageFullError, networkError, notFoundError, parseAuthError, parseCapabilityResource, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, validatedCapabilityOf, wrapError };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-qwMmB7qB.js';
-export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-qwMmB7qB.js';
+import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-CVwwxqXF.js';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-CVwwxqXF.js';
 import { z } from 'zod';
-import { B as BaseService } from './BaseService-DU-lE-Qx.js';
-export { a as BaseServiceOptions, R as RequestSignal, S as ServiceConstructor, b as ServiceRegistration } from './BaseService-DU-lE-Qx.js';
+import { B as BaseService } from './BaseService-B_UKhVht.js';
+export { a as BaseServiceOptions, R as RequestSignal, S as ServiceConstructor, b as ServiceRegistration } from './BaseService-B_UKhVht.js';
 import { IKVService } from './kv/index.js';
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVChange, KVChangesAuthority, KVChangesOptions, KVChangesResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.js';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.js';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.js';
@@ -1521,9 +1521,51 @@ interface SubscribeOptions {
 }
 interface HooksServiceConfig extends Record<string, unknown> {
     host?: string;
+    /** Shared-stream retry tuning; see {@link HookStreamRetryConfig}. */
+    streamRetry?: HookStreamRetryConfig;
+}
+/**
+ * Retry policy for the shared `/hooks/events` stream. When the stream fails
+ * (network error, 5xx, or an expired/rotated ticket rejected with 401/403)
+ * it is re-opened with exponential backoff: `HOOK_STREAM_RETRY_BASE_DELAY_MS`
+ * (~250 ms) doubling to `HOOK_STREAM_RETRY_MAX_DELAY_MS` (~30 s) with jitter.
+ * The retry streak resets after an event is received or a stream remains open
+ * for at least 5 seconds. Retries stop when no subscribers remain, when the
+ * service is aborted, or when minting the hook ticket is refused (the iterator
+ * throws that typed error instead).
+ */
+interface HookStreamRetryConfig {
+    /**
+     * Delay before retry attempt `attempt` (1-based). Defaults to the jittered
+     * exponential backoff described above. Must return milliseconds.
+     */
+    delay?: (attempt: number) => number;
+    /**
+     * How a retry delay is awaited — the injectable clock. `delayMs` is the
+     * resolved delay for `attempt`; `signal` aborts the wait early when the
+     * subscription set changes or the service stops. Rejecting or throwing is
+     * treated like a completed wait. After a custom wait returns — whether it
+     * fulfilled, rejected or threw — the service still yields one event-loop
+     * turn so a persistently failing stream can never starve the process.
+     * Defaults to an abortable, unref'd `setTimeout`.
+     */
+    wait?: (delayMs: number, attempt: number, signal: AbortSignal) => Promise<void>;
 }
 
 interface IHooksService {
+    /**
+     * Stream hook events until `options.signal` aborts, the SDK signs out or
+     * the session ends, or the consumer stops iterating. Transient stream
+     * failures — network errors, 5xx, and an expired or rotated ticket rejected
+     * by `/hooks/events` (401/403) — are retried internally with backoff and
+     * never reach the iterator.
+     *
+     * The iterator throws when minting the hook ticket is refused. The thrown
+     * plain `ServiceError` carries `meta.status` with the refusing HTTP status,
+     * so `for await` consumers can branch on it. Stream diagnostics contain only
+     * SDK allow-listed identifiers; foreign error messages and causes are not
+     * copied.
+     */
     subscribe(subscriptions: HookSubscription[], options?: SubscribeOptions): AsyncIterable<HookEvent>;
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
@@ -1534,10 +1576,13 @@ declare class HooksService extends BaseService implements IHooksService {
     static readonly serviceName = "hooks";
     protected _config: HooksServiceConfig;
     private readonly _subscribers;
-    private _sharedStreamTask?;
-    private _sharedStreamAbort?;
-    private _refreshChain;
-    private _activeSignature;
+    /** True while the one supervisor loop runs. Set only by wake(), cleared only at loop exit. */
+    private _supervising;
+    /** The supervisor's current step, interruptible by wake(). */
+    private _phase?;
+    /** Bumped on every session change; part of the plan key. */
+    private _sessionGeneration;
+    private _lastContextSignal?;
     constructor(config?: HooksServiceConfig);
     get config(): HooksServiceConfig;
     private get host();
@@ -1545,14 +1590,60 @@ declare class HooksService extends BaseService implements IHooksService {
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
     unregister(id: string, options?: HookWebhookUnregisterOptions): Promise<Result<void>>;
-    private scheduleSharedStreamRefresh;
-    private refreshSharedStream;
-    private collectSharedStreamState;
-    private runSharedStream;
-    private abortSharedStream;
+    /**
+     * Called after anything that may change what the supervisor should do:
+     * subscribe, unsubscribe, session change, sign-out. Interrupts the running
+     * step if the plan moved away from it, and starts the supervisor if none
+     * runs. Touches only SDK-owned state, so it never throws into callers such
+     * as `ServiceContext.setSession`.
+     */
+    private wake;
+    /**
+     * The only owner of the shared stream. Each iteration is one attempt
+     * (mint → open → drain), then a classification and, unless the attempt was
+     * superseded or released its subscribers, a backoff. Every await is a
+     * `phase` that wake() can interrupt; an interrupted phase yields
+     * `undefined`, so a superseded mint can never act. Outside `attempt` and
+     * `pause`, which each own one catch, the loop touches only SDK state.
+     */
+    private supervise;
+    /**
+     * Run one step under an interrupt that wake() fires when the plan key moves
+     * on. An interrupted step's result is discarded. The interrupt is also
+     * fired when the step returns, which releases whatever it left open: the
+     * request signal and its listeners, an unread response body, a timer.
+     */
+    private phase;
+    /**
+     * One mint → open → drain. The single catch site for everything the
+     * attempt touches that the SDK does not own: context accessors, invoke,
+     * fetch, response bodies, the SSE parser. Never rejects.
+     */
+    private attempt;
+    /**
+     * Back off before the next attempt. `config.streamRetry` overrides the
+     * delay and the clock; whatever they do, the pause ends by the delay or the
+     * interrupt, then yields one timer turn so an instant clock cannot starve
+     * due timers or the process.
+     */
+    private pause;
+    /** The stream the current subscribers need, or undefined when none remain. */
+    private plan;
+    private dispatch;
+    /**
+     * Detach every subscriber. With `error`, their iterators throw it after
+     * draining buffered events; without, they complete.
+     */
+    private release;
+    private report;
+    /**
+     * Unreachable by construction. If the loop ever rejects anyway, fail its
+     * subscribers visibly instead of stranding them or crashing the process.
+     */
+    private collapse;
+    onSessionChange(session: ServiceSession | null): void;
+    onSignOut(): void;
     private createHookHeaders;
-    private mintHookTicket;
-    private openHookStream;
     private createInvokeHeaders;
 }
 
@@ -2287,4 +2378,4 @@ declare class SecretsService implements ISecretsService {
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-export { type AuthorizationVerdict, BaseService, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, authorizationVerdictOf, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, isStorageFullError, networkError, notFoundError, parseAuthError, parseCapabilityResource, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, validatedCapabilityOf, wrapError };
+export { type AuthorizationVerdict, BaseService, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookStreamRetryConfig, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, authorizationVerdictOf, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, isStorageFullError, networkError, notFoundError, parseAuthError, parseCapabilityResource, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, validatedCapabilityOf, wrapError };