@kelloggt/dsh-program-agents 0.0.0-stage → 0.1.1

package/dist/app/inbox.js

@@ -0,0 +1,253 @@
+import { ProgramError } from '../runtime/protocol.js';
+/** ACK may have committed before its response was lost. Neither retry nor NACK is safe. */
+export class SettlementUnknownError extends ProgramError {
+    messageId;
+    outcome = 'unknown';
+    operation = 'ack';
+    cause;
+    constructor(messageId, cause) {
+        super('SETTLEMENT_UNKNOWN', `ACK outcome is unknown for inbox message ${messageId}; do not repeat its callback or automatically retry settlement`);
+        this.messageId = messageId;
+        this.name = 'SettlementUnknownError';
+        this.cause = cause;
+    }
+}
+const bound = (value, name, min, max) => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max)
+        throw new ProgramError('INVALID_INPUT', `${name} must be an integer from ${min} to ${max}`);
+    return value;
+};
+const cancelled = () => new ProgramError('CANCELLED', 'Inbox processing was cancelled; a running callback must cooperate with context.signal');
+const processingTimeout = () => new ProgramError('TIMEOUT', 'Inbox processing deadline exceeded; a running callback may still have effects after its lease expires');
+const frozen = (value) => {
+    if (value !== null && typeof value === 'object') {
+        for (const child of Object.values(value))
+            frozen(child);
+        Object.freeze(value);
+    }
+    return value;
+};
+const claimArgs = (message, leaseToken) => {
+    const value = typeof message === 'string' ? { id: message, leaseToken } : message;
+    if (!value || typeof value.id !== 'string' || !value.id || value.id.length > 256 || typeof value.leaseToken !== 'string' || !value.leaseToken || value.leaseToken.length > 256)
+        throw new ProgramError('INVALID_INPUT', 'Ack/nack requires the claimed message or its id and leaseToken');
+    return { id: value.id, leaseToken: value.leaseToken };
+};
+const optionsFor = (options, managed) => {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new ProgramError('INVALID_INPUT', 'Invalid inbox receive options');
+    const waitMs = bound(options.waitMs === undefined ? 0 : options.waitMs, 'waitMs', 0, 30_000);
+    const leaseMs = bound(options.leaseMs === undefined ? 60_000 : options.leaseMs, 'leaseMs', managed ? 500 : 1, 300_000);
+    const timeoutMs = options.timeoutMs === undefined ? undefined : bound(options.timeoutMs, 'timeoutMs', 1, 120_000);
+    if (options.signal !== undefined && (!options.signal || typeof options.signal.aborted !== 'boolean' || typeof options.signal.addEventListener !== 'function' || typeof options.signal.removeEventListener !== 'function'))
+        throw new ProgramError('INVALID_INPUT', 'Invalid inbox cancellation signal');
+    return { waitMs, leaseMs, timeoutMs, signal: options.signal };
+};
+/**
+ * Managed processing invokes the callback once per claim, renews while it runs, and ACKs
+ * only a fulfilled, uninterrupted callback. No bridge effect or callback is retried.
+ *
+ * This is NOT exactly-once processing: crashes, lease loss, and uncooperative callbacks
+ * can cause redelivery and overlapping external effects. Use application idempotency.
+ * Cancellation rejects receive promptly but does not NACK a still-running callback.
+ * Its claim is renewed only until the processing deadline; then renewal stops and the
+ * last lease expires naturally. A late callback never ACKs. Each helper retains one
+ * of its 32 slots until the actual callback settles, even after the caller has left.
+ */
+export function createProgramInbox(call) {
+    let active = 0;
+    const claim = async (options = {}) => {
+        const { waitMs, leaseMs, timeoutMs, signal } = optionsFor(options, false);
+        return call('inbox.receive', { ...(options.waitMs === undefined ? {} : { waitMs }), ...(options.leaseMs === undefined ? {} : { leaseMs }) }, { timeoutMs, signal });
+    };
+    const settle = (method, message, leaseToken, options) => call(method, claimArgs(message, leaseToken), options);
+    const managed = async (options, handler) => {
+        const { waitMs, leaseMs, timeoutMs, signal } = optionsFor(options, true);
+        const processingTimeoutMs = bound(options.processingTimeoutMs === undefined ? 120_000 : options.processingTimeoutMs, 'processingTimeoutMs', 1, 3_600_000);
+        if (signal?.aborted)
+            throw cancelled();
+        if (active >= 32)
+            throw new ProgramError('BACKPRESSURE', 'Inbox managed callback limit exceeded');
+        active++;
+        let message;
+        try {
+            // A claim is acquired before any user code runs. The processing deadline starts
+            // after acquisition, independently of long-poll and individual RPC deadlines.
+            message = await call('inbox.receive', { waitMs, leaseMs }, { timeoutMs, signal });
+            if (message !== null) {
+                claimArgs(message);
+                const receipt = message.receipt;
+                if (!receipt || receipt.id !== message.id || receipt.status !== 'claimed' || typeof receipt.leaseUntil !== 'string' || !Number.isFinite(Date.parse(receipt.leaseUntil)) || Date.parse(receipt.leaseUntil) <= Date.now())
+                    throw new ProgramError('INVALID_RESPONSE', 'Inbox receive did not confirm a live claim');
+            }
+        }
+        catch (error) {
+            active--;
+            throw error;
+        }
+        if (message === null) {
+            active--;
+            if (signal?.aborted)
+                throw cancelled();
+            return null;
+        }
+        const processingDeadline = performance.now() + processingTimeoutMs;
+        const context = new AbortController();
+        const renewalController = new AbortController();
+        let failed = false;
+        let failure;
+        let ackStarted = false;
+        let renewalStopped = false;
+        let heartbeatTimer;
+        let deadlineTimer;
+        let renewal;
+        let rejectInterrupted;
+        const interrupted = new Promise((_resolve, reject) => { rejectInterrupted = reject; });
+        void interrupted.catch(() => { });
+        const removeAbort = () => signal?.removeEventListener('abort', onAbort);
+        const stopRenewal = (abortPending = false) => {
+            renewalStopped = true;
+            clearTimeout(heartbeatTimer);
+            heartbeatTimer = undefined;
+            if (abortPending)
+                renewalController.abort();
+        };
+        const interrupt = (error, stop = false) => {
+            if (stop) {
+                stopRenewal(true);
+                clearTimeout(deadlineTimer);
+                deadlineTimer = undefined;
+            }
+            if (!context.signal.aborted)
+                context.abort(error);
+            // Once ACK was attempted, only its response can determine the result. A lost
+            // response is SettlementUnknownError, never a misleading cancellation + NACK.
+            if (ackStarted || failed)
+                return;
+            failed = true;
+            failure = error;
+            removeAbort();
+            rejectInterrupted(error);
+        };
+        const onAbort = () => interrupt(cancelled());
+        const heartbeatMs = Math.floor(leaseMs / 3);
+        const schedule = () => {
+            if (!renewalStopped)
+                heartbeatTimer = setTimeout(() => {
+                    heartbeatTimer = undefined;
+                    renewal = (async () => {
+                        try {
+                            const receipt = await call('inbox.renew', { id: message.id, leaseToken: message.leaseToken, leaseMs }, { signal: renewalController.signal, timeoutMs: Math.min(timeoutMs ?? 120_000, heartbeatMs) });
+                            if (!receipt || receipt.id !== message.id || receipt.status !== 'claimed' || typeof receipt.leaseUntil !== 'string' || !Number.isFinite(Date.parse(receipt.leaseUntil)) || Date.parse(receipt.leaseUntil) <= Date.now())
+                                throw new ProgramError('INVALID_RESPONSE', 'Inbox renewal did not confirm a live claim');
+                        }
+                        catch (error) {
+                            if (!renewalController.signal.aborted)
+                                interrupt(error, true);
+                        }
+                    })();
+                    void renewal.then(schedule);
+                }, heartbeatMs);
+        };
+        const cleanup = () => {
+            clearTimeout(deadlineTimer);
+            deadlineTimer = undefined;
+            stopRenewal(true);
+            removeAbort();
+        };
+        const nack = async () => {
+            // Never reuse the cancelled callback signal for settlement. One bounded,
+            // best-effort NACK is made only AFTER actual user code has stopped running.
+            try {
+                await settle('inbox.nack', message, undefined, { timeoutMs: timeoutMs ?? 120_000 });
+            }
+            catch { /* Expiry/revocation may already have fenced this claim. No retries. */ }
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        deadlineTimer = setTimeout(() => {
+            deadlineTimer = undefined;
+            interrupt(processingTimeout(), true);
+            removeAbort();
+        }, processingTimeoutMs);
+        if (signal?.aborted)
+            onAbort();
+        schedule();
+        const work = (async () => {
+            try {
+                let result;
+                try {
+                    if (failed)
+                        throw failure;
+                    const { leaseToken: _token, ...visible } = message;
+                    result = await handler(frozen(visible), Object.freeze({ signal: context.signal }));
+                }
+                catch (error) {
+                    if (!failed) {
+                        failed = true;
+                        failure = error;
+                    }
+                    if (!context.signal.aborted)
+                        context.abort(failure);
+                }
+                // Drain the one possible renewal before making a settlement decision. A
+                // late renewal failure must not be hidden by a callback's successful return.
+                stopRenewal();
+                if (renewal)
+                    await renewal;
+                if (signal?.aborted && !failed) {
+                    failed = true;
+                    failure = cancelled();
+                }
+                // A synchronous callback may monopolize the event loop past its deadline,
+                // preventing the timer from running. It still must never acquire an ACK.
+                if (!failed && performance.now() >= processingDeadline) {
+                    failed = true;
+                    failure = processingTimeout();
+                }
+                if (failed) {
+                    cleanup();
+                    await nack();
+                    throw failure;
+                }
+                ackStarted = true;
+                clearTimeout(deadlineTimer);
+                deadlineTimer = undefined;
+                try {
+                    const receipt = await settle('inbox.ack', message, undefined, { timeoutMs, signal });
+                    if (!receipt || receipt.id !== message.id || receipt.status !== 'acked')
+                        throw new ProgramError('INVALID_RESPONSE', 'Inbox ACK did not confirm settlement');
+                }
+                catch (error) {
+                    throw new SettlementUnknownError(message.id, error);
+                }
+                return result;
+            }
+            finally {
+                cleanup();
+                active--;
+            }
+        })();
+        return Promise.race([work, interrupted]);
+    };
+    function receive(optionsOrHandler = {}, handler) {
+        if (typeof optionsOrHandler === 'function') {
+            if (handler !== undefined)
+                return Promise.reject(new ProgramError('INVALID_INPUT', 'Receive expects one handler'));
+            return managed({}, optionsOrHandler);
+        }
+        if (handler === undefined)
+            return claim(optionsOrHandler);
+        if (typeof handler !== 'function')
+            return Promise.reject(new ProgramError('INVALID_INPUT', 'Receive handler must be a function'));
+        return managed(optionsOrHandler, handler);
+    }
+    return {
+        receive,
+        claim,
+        renew: async (message, leaseMs, options) => call('inbox.renew', { ...claimArgs(message), leaseMs: bound(leaseMs, 'leaseMs', 1, 300_000) }, options),
+        ack: (message, token, options) => settle('inbox.ack', message, token, options),
+        nack: (message, token, options) => settle('inbox.nack', message, token, options),
+        receipt: (id, options) => call('inbox.receipt', { id }, options),
+    };
+}
+//# sourceMappingURL=inbox.js.map

package/dist/app/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../src/app/inbox.ts"],"names":[],"mappings":"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"}

package/dist/app/index.d.ts

@@ -0,0 +1,70 @@
+import type { JsonValue } from '../types.js';
+import { type LoggerOptions } from '../monitoring/logger.js';
+export * from './models.js';
+export * from './conversations.js';
+export * from './inbox.js';
+export * from './agents.js';
+export * from './tools.js';
+export { installGlobalErrorHandlers } from '../monitoring/fatal.js';
+export { createLogger, StructuredLogger, type LoggerOptions, type LogMetadata } from '../monitoring/logger.js';
+export type { InboxMessage, MessageReceipt, ReceiveOptions } from './mailbox.js';
+export type { JsonValue } from '../types.js';
+export { ProgramError } from '../runtime/protocol.js';
+export { createProgramEndpoints, listenProgramEndpoint, type ProgramEndpoints, type ProgramEndpointBinding, type PublishEndpointOptions, type UnpublishEndpointOptions, type ListeningProgramEndpoint, type EndpointBridgeCall } from './endpoints.js';
+export interface CallOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface ConnectProgramOptions {
+    url?: string;
+    token?: string;
+    runId?: string;
+    generation?: number;
+    timeoutMs?: number;
+    logger?: LoggerOptions;
+}
+export interface AgentInfo {
+    id: string;
+    name?: string;
+    [key: string]: JsonValue | undefined;
+}
+export interface McpToolInfo {
+    server: string;
+    tool: string;
+    name: string;
+    description?: string;
+    inputSchema?: JsonValue;
+}
+export interface SendOptions extends CallOptions {
+    correlationId?: string;
+}
+/** Explicit connection only: ordinary programs require no SDK and gain no implicit permission. */
+export declare function connectProgram(options?: ConnectProgramOptions): {
+    id: string | undefined;
+    generation: number | undefined;
+    call: <T = JsonValue>(method: string, input?: JsonValue, callOptions?: CallOptions) => Promise<T>;
+    logger: import("../monitoring/logger.js").StructuredLogger;
+    endpoints: import("./endpoints.js").ProgramEndpoints;
+    sendSupervisor: (body: JsonValue, sendOptions?: SendOptions) => Promise<JsonValue>;
+    supervisor: {
+        send: (body: JsonValue, sendOptions?: SendOptions) => Promise<JsonValue>;
+    };
+    agents: import("./agents.js").ProgramAgents;
+    mcp: {
+        forServer: (server: string) => import("./tools.js").ProgramToolClient;
+        listTools: (params?: {
+            cursor?: string;
+        }, options?: CallOptions) => Promise<import("./tools.js").ListToolsResult>;
+        callTool: (params: import("./tools.js").CallToolRequestParams, options?: CallOptions) => Promise<import("./tools.js").CallToolResult>;
+        /** @deprecated Use mcp.forServer(server).listTools(). */
+        list: (callOptions?: CallOptions) => Promise<McpToolInfo[]>;
+        call: <T = JsonValue>(server: string, tool: string, args?: JsonValue, callOptions?: CallOptions) => Promise<T>;
+    };
+    models: import("./models.js").ProgramModels;
+    conversations: import("./conversations.js").ProgramConversations;
+    tools: import("./tools.js").ProgramToolClient;
+    inbox: import("./inbox.js").ProgramInbox;
+};
+export type ProgramConnection = ReturnType<typeof connectProgram>;
+/** Convenience for a one-off escalation; uses explicit bridge env and does not retry. */
+export declare function sendSupervisor(body: JsonValue, options?: SendOptions): Promise<JsonValue>;

package/dist/app/index.js

@@ -0,0 +1,147 @@
+import { assertJson, isRecord, ProgramError, validName } from '../runtime/protocol.js';
+import { createLogger } from '../monitoring/logger.js';
+import { createProgramEndpoints } from './endpoints.js';
+import { createProgramInbox } from './inbox.js';
+import { createProgramAgents } from './agents.js';
+import { createProgramTools } from './tools.js';
+import { createProgramModels } from './models.js';
+import { createProgramConversations } from './conversations.js';
+import { createProgramStream } from './stream.js';
+export * from './models.js';
+export * from './conversations.js';
+export * from './inbox.js';
+export * from './agents.js';
+export * from './tools.js';
+export { installGlobalErrorHandlers } from '../monitoring/fatal.js';
+export { createLogger, StructuredLogger } from '../monitoring/logger.js';
+export { ProgramError } from '../runtime/protocol.js';
+export { createProgramEndpoints, listenProgramEndpoint } from './endpoints.js';
+/** Explicit connection only: ordinary programs require no SDK and gain no implicit permission. */
+export function connectProgram(options = {}) {
+    const rawUrl = options.url ?? process.env.DSH_PROGRAM_BRIDGE_URL;
+    const token = options.token ?? process.env.DSH_PROGRAM_BRIDGE_TOKEN;
+    if (!rawUrl || !token)
+        throw new ProgramError('NOT_CONFIGURED', 'Program bridge is not configured; launch under a bridge-enabled supervisor or pass url and token explicitly');
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new ProgramError('INVALID_CONFIG', 'Invalid program bridge URL');
+    }
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.pathname !== '/' || url.search || url.hash || typeof token !== 'string' || token.length > 1024 || !/^[A-Za-z0-9_-]+$/.test(token))
+        throw new ProgramError('INVALID_CONFIG', 'Program bridge requires a direct 127.0.0.1 HTTP endpoint and opaque token');
+    const defaultTimeout = options.timeoutMs ?? 120_000;
+    if (!Number.isSafeInteger(defaultTimeout) || defaultTimeout < 1 || defaultTimeout > 120_000)
+        throw new ProgramError('INVALID_CONFIG', 'Bridge timeout must be between 1 and 120000 ms');
+    const generationText = process.env.DSH_PROGRAM_GEN;
+    const generation = options.generation ?? (generationText === undefined ? undefined : Number(generationText));
+    if (generation !== undefined && (!Number.isSafeInteger(generation) || generation < 1))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid bridge generation');
+    let pending = 0;
+    const logger = createLogger(options.logger);
+    const call = async (method, input = null, callOptions = {}) => {
+        if (!validName(method))
+            throw new ProgramError('INVALID_INPUT', 'Invalid bridge method');
+        assertJson(input);
+        const body = JSON.stringify({ method, input });
+        if (Buffer.byteLength(body) > 64 * 1024)
+            throw new ProgramError('LIMIT', 'Bridge request exceeds 64 KiB');
+        const timeoutMs = callOptions.timeoutMs ?? defaultTimeout;
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)
+            throw new ProgramError('INVALID_INPUT', 'Bridge timeout must be between 1 and 120000 ms');
+        if (callOptions.signal?.aborted)
+            throw new ProgramError('CANCELLED', 'Bridge call was cancelled before sending');
+        if (pending >= 32)
+            throw new ProgramError('BACKPRESSURE', 'Program bridge pending call limit exceeded');
+        pending++;
+        const controller = new AbortController();
+        const abort = () => controller.abort(new ProgramError('CANCELLED', 'Bridge call cancelled; effect outcome may be unknown'));
+        const timer = setTimeout(() => controller.abort(new ProgramError('TIMEOUT', 'Bridge deadline exceeded; effect outcome may be unknown')), timeoutMs);
+        callOptions.signal?.addEventListener('abort', abort, { once: true });
+        if (callOptions.signal?.aborted)
+            abort();
+        try {
+            // Never retry effects or follow redirects with a run credential.
+            const response = await fetch(new URL('/call', url), { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, body, signal: controller.signal, redirect: 'error' });
+            const reader = response.body?.getReader();
+            if (!reader)
+                throw new ProgramError('INVALID_RESPONSE', 'Bridge returned no response body');
+            const chunks = [];
+            let bytes = 0;
+            try {
+                for (;;) {
+                    const item = await reader.read();
+                    if (item.done)
+                        break;
+                    bytes += item.value.length;
+                    if (bytes > 64 * 1024) {
+                        await reader.cancel();
+                        throw new ProgramError('LIMIT', 'Bridge response exceeds 64 KiB');
+                    }
+                    chunks.push(item.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            let payload;
+            try {
+                payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            }
+            catch {
+                throw new ProgramError('INVALID_RESPONSE', 'Bridge returned malformed JSON');
+            }
+            assertJson(payload);
+            if (!isRecord(payload) || typeof payload.ok !== 'boolean')
+                throw new ProgramError('INVALID_RESPONSE', 'Invalid bridge response envelope');
+            if (!payload.ok) {
+                if (!isRecord(payload.error) || typeof payload.error.code !== 'string' || typeof payload.error.message !== 'string')
+                    throw new ProgramError('INVALID_RESPONSE', 'Invalid bridge error envelope');
+                throw new ProgramError(payload.error.code, payload.error.message);
+            }
+            if (!response.ok || !Object.hasOwn(payload, 'result'))
+                throw new ProgramError('INVALID_RESPONSE', 'Invalid bridge success response');
+            return payload.result;
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw controller.signal.reason;
+            throw error;
+        }
+        finally {
+            pending--;
+            clearTimeout(timer);
+            callOptions.signal?.removeEventListener('abort', abort);
+        }
+    };
+    const sendSupervisor = (body, sendOptions = {}) => call('supervisor.send', { body, ...(sendOptions.correlationId === undefined ? {} : { correlationId: sendOptions.correlationId }) }, sendOptions);
+    const tools = createProgramTools(call);
+    return {
+        id: options.runId ?? process.env.DSH_PROGRAM_RUN_ID,
+        generation,
+        call,
+        logger,
+        endpoints: createProgramEndpoints(call),
+        sendSupervisor,
+        supervisor: { send: sendSupervisor },
+        agents: createProgramAgents(call),
+        mcp: {
+            forServer: (server) => createProgramTools(call, server),
+            listTools: tools.listTools,
+            callTool: tools.callTool,
+            /** @deprecated Use mcp.forServer(server).listTools(). */
+            list: (callOptions) => call('mcp.list', null, callOptions),
+            call: (server, tool, args = null, callOptions) => call('mcp.call', { server, tool, args }, callOptions),
+        },
+        models: createProgramModels(call),
+        conversations: createProgramConversations(call, createProgramStream(url, token)),
+        tools,
+        inbox: createProgramInbox(call),
+    };
+}
+/** Convenience for a one-off escalation; uses explicit bridge env and does not retry. */
+export function sendSupervisor(body, options = {}) {
+    return connectProgram().sendSupervisor(body, options);
+}
+//# sourceMappingURL=index.js.map

package/dist/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"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"}

package/dist/app/mailbox.d.ts

@@ -0,0 +1,63 @@
+import type { JsonValue } from '../types.js';
+/** Namespace persists across run/watch generations. claimant must come from the host, never a request body. */
+export interface MessageScope {
+    ownerId: string;
+    program: string;
+    claimant?: string;
+}
+export interface MessageReceipt {
+    id: string;
+    status: 'accepted' | 'claimed' | 'acked';
+    acceptedAt: string;
+    claimedAt?: string;
+    ackedAt?: string;
+    leaseUntil?: string;
+    attempts: number;
+}
+export interface InboxMessage {
+    id: string;
+    from: string;
+    body: JsonValue;
+    createdAt: string;
+    correlationId?: string;
+    leaseToken: string;
+    receipt: MessageReceipt;
+}
+export interface ReceiveOptions {
+    waitMs?: number;
+    leaseMs?: number;
+}
+export interface MessageStoreOptions {
+    maxPendingPerProgram?: number;
+    maxMessages?: number;
+    clock?: () => number;
+}
+/** Durable at-least-once queue. Acceptance is not app processing; only explicit ack records that. */
+export declare class MessageStore {
+    private readonly db;
+    private readonly maxPending;
+    private readonly maxMessages;
+    private readonly clock;
+    private closed;
+    constructor(path: string, options?: MessageStoreOptions);
+    send(scope: MessageScope, message: {
+        from: string;
+        body: JsonValue;
+        correlationId?: string;
+    }): MessageReceipt;
+    receive(scope: MessageScope, options?: ReceiveOptions, signal?: AbortSignal): Promise<InboxMessage | null>;
+    /** Extend only an unexpired claim belonging to this exact run and token. Never resurrect a lease. */
+    renew(scope: MessageScope, id: string, leaseToken: string, leaseMs: number): MessageReceipt;
+    /** Low-level settlement. The exact live token is consumed; never retry an unknown ACK outcome. */
+    ack(scope: MessageScope, id: string, leaseToken: string): MessageReceipt;
+    nack(scope: MessageScope, id: string, leaseToken: string): MessageReceipt;
+    receipt(scope: MessageScope, id: string): MessageReceipt | null;
+    /** Release only this revoked run's claims; namespace and unacked messages survive. */
+    releaseClaims(scope: MessageScope): void;
+    close(): void;
+    private row;
+    private claim;
+    private checkScope;
+    private bound;
+    private transaction;
+}