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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Kellogg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# DSH Program Agents
+
+You know how subagents can send messages to each other, launch new subagents, call LLMs, use tools, etc? A lot of agents write non-trivial amounts of code just to operate normally. _What if an "agent" was just code?_ 
+
+_**Program agents**_ — no agent loop, just regular software that a supervising agent can edit & manage.
+
+This repo includes
+* A typescript SDK for [DSH (DeepSeek Harness)](https://github.com/deepseek-ai/deepseek-harness) that wraps tool calling, LLM calling, inter-agent messaging, etc.
+* A process manager that keeps the program agent running, or not, whatever you need
+* Logging/monitoring so that errors get funneled to the supervising agent
+* Named models for configurable software so you can upgrade models easily
+* A skill to teach your agent how to write program agents
+
+## Installation
+
+You'll need [Node.js](https://nodejs.org/) **22.18 or newer** and Git. This plugin currently targets **DSH 0.2.1-rc.2**; use that version for the setup below.
+
+### 1. Install DSH
+
+Install the [DSH CLI](https://github.com/deepseek-ai/deepseek-harness) and pnpm:
+
+```sh
+npm install -g @deepseek-ai/dsh@0.2.1-rc.2 pnpm@10
+dsh web
+```
+
+DSH opens its web UI at `http://127.0.0.1:3080` and creates your web profile. Stop it with **Ctrl+C** while you install the plugins below.
+
+### 2. Install Program Agents
+
+The first npm release is being prepared. Once published, install it with:
+
+```sh
+dsh plugin --profile web add @kelloggt/dsh-program-agents
+mkdir -p ~/.dsh/skills
+cp -R ~/.dsh/profiles/web/node_modules/@kelloggt/dsh-program-agents/skills/program-agents ~/.dsh/skills/
+```
+
+This enables the plugin automatically. Until that release is available, build it from a checkout:
+
+```sh
+git clone https://github.com/tkellogg/dsh-program-agents.git
+cd dsh-program-agents
+pnpm install --frozen-lockfile
+pnpm build
+
+# Install the skill so DSH's agents know how to use program agents.
+mkdir -p ~/.dsh/skills
+cp -R skills/program-agents ~/.dsh/skills/
+```
+
+Add the following to `~/.dsh/profiles/web/cordis.patch.yml`, keeping any existing entries. Replace `/absolute/path/to/dsh-program-agents` with the checkout's full path (run `pwd` to find it):
+
+```yaml
+- insert:
+    - id: program-agents
+      name: /absolute/path/to/dsh-program-agents/dist/host/index.js
+```
+
+Keep the checkout in that location: DSH loads the built plugin from it.
+
+Maintainers: see [Publishing to npm](docs/publishing.md) for the release steps.
+
+### 3. Connect Codex or Claude
+
+To use your ChatGPT or Claude subscription, install [dsh-plugin-subscriptions](https://github.com/V1ki/dsh-plugin-subscriptions):
+
+```sh
+dsh plugin --profile web add dsh-plugin-subscriptions
+dsh web
+```
+
+In DSH, open **Settings → Subscriptions** and click **Connect** for the provider you want:
+
+- **ChatGPT (Codex):** sign in with your ChatGPT account in the browser.
+- **Claude:** imports your existing Claude Code login when available. Otherwise, follow the browser authorization flow; the Claude Code CLI is optional.
+
+These providers use your subscription login, so no API key is needed. Open the session's model picker (`/model`) and select a model under **ChatGPT (Codex)** or **Claude (Subscription)**.
+
+If you use another model provider, skip the subscriptions plugin and run `dsh web` after step 2. In a new chat, ask DSH to use the **program-agents** skill to build and start a program. The **Program agents** panel above the composer shows its status and Start/Stop/Restart controls.
+
+## Why not just regular software?
+* _Error handling_ — software that discovers problems and dynamically adapts
+* _Slowly changing software_ — e.g. in data engineering you'll run into new data bugs or learn new things about the data in production. Program agents merely evolve to handle new situations
+* _World-integrated agents_ — a collection of loops that poll web services like Github or Salesforce for events and messages and forward them onto a real agent
+* _Heavily AI-integrated software_ — Regular software with agents and chatbots wired deeply throughout
+
+## Default workflow
+
+1. Build an app using a foreground **watch/reload** command.
+2. Register its name, description, argv command, URLs and optional log path with `program_register`.
+3. Start using `program_start` or the composer's **Start** button. The UI dispatches through the exact live parent's public tool pipeline; it does not create an unrelated shell/Agent.
+4. Edit source; let the watcher reload rather than repeatedly restarting manually. Check application readiness using its actual health/API URL and logs.
+
+## Development commands
+
+Run `pnpm install --frozen-lockfile` after cloning, then use these scripts from the repository root:
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm build` | Build the host, browser client, SDK, and examples. |
+| `pnpm typecheck` | Check the source TypeScript. |
+| `pnpm typecheck:references` | Check the copyable application references. |
+| `pnpm test` | Run the test suite. |
+| `pnpm check` | Build, check references, and run tests. |
+| `pnpm example` | Run the standalone supervisor example. |
+| `pnpm release:pack` | Run all checks and create the release archive. |
+| `pnpm release:inspect` | List the files in the current version's archive. |
+| `pnpm release:publish:dry-run` | Preview publishing the archive. |
+| `pnpm release:login` | Sign in to npm. |
+| `pnpm release:publish` | Publish the existing archive publicly to npm. |
+
+See [Publishing to npm](docs/publishing.md) for the release workflow.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Installing this bundle enables the host plugin. DSH discovers the web client
+# through the dsh.client declaration in package.json.
+- insert:
+    - id: program-agents
+      name: '@kelloggt/dsh-program-agents'

package/dist/app/agents.d.ts

@@ -0,0 +1,50 @@
+import type { JsonValue } from '../types.js';
+import { type AgentTarget, type ResponseSchema, type RequestRecord } from '../requests.js';
+import { ProgramError } from '../runtime/protocol.js';
+import type { AgentInfo, CallOptions, SendOptions } from './index.js';
+export type { AgentTarget, ResponseSchema, JSONSchema, RequestStatus, ResponseReceipt } from '../requests.js';
+export interface AgentRequestView {
+    requestId: string;
+    status: RequestRecord['status'];
+    agentId?: string;
+    createdAt: string;
+    deadline: string;
+    response?: JsonValue;
+    error?: string;
+}
+export interface AskOptions extends CallOptions {
+    requestId?: string;
+    responseSchema?: ResponseSchema;
+    instructions?: string;
+}
+/** Runtime schema plus identity parser for statically typed ask results. A TS
+ * interface alone disappears at runtime and cannot validate an Agent reply. */
+export interface AgentResponseType<T extends JsonValue> {
+    readonly schema: ResponseSchema;
+    parse(value: JsonValue): T;
+}
+export declare function responseType<T extends JsonValue>(schema: ResponseSchema): AgentResponseType<T>;
+export declare const responseTypes: {
+    string: () => AgentResponseType<string>;
+};
+export declare class AgentRequestError extends ProgramError {
+    readonly requestId: string;
+    readonly status: RequestRecord['status'];
+    constructor(code: string, message: string, requestId: string, status: RequestRecord['status']);
+}
+export type AgentBridgeCall = <T = JsonValue>(method: string, input?: JsonValue, options?: CallOptions) => Promise<T>;
+export interface ProgramAgents {
+    list(options?: CallOptions): Promise<AgentInfo[]>;
+    get(id: string, options?: CallOptions): Promise<AgentInfo | null>;
+    send(target: AgentTarget, body: JsonValue, options?: SendOptions): Promise<JsonValue>;
+    ask(target: AgentTarget, body: JsonValue, options?: AskOptions & {
+        responseSchema?: undefined;
+    }): Promise<string>;
+    ask<T extends JsonValue = JsonValue>(target: AgentTarget, body: JsonValue, options: AskOptions & {
+        responseSchema: ResponseSchema;
+    }): Promise<T>;
+    ask<T extends JsonValue>(target: AgentTarget, body: JsonValue, responseType: AgentResponseType<T>, options?: AskOptions): Promise<T>;
+    request(requestId: string, options?: CallOptions): Promise<AgentRequestView | null>;
+    cancel(requestId: string, options?: CallOptions): Promise<AgentRequestView>;
+}
+export declare function createProgramAgents(call: AgentBridgeCall): ProgramAgents;

package/dist/app/agents.js

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+import { createResponseValidator } from '../requests.js';
+import { ProgramError } from '../runtime/protocol.js';
+export function responseType(schema) { const validate = createResponseValidator(schema); return { schema, parse(value) { validate(value); return value; } }; }
+export const responseTypes = { string: () => responseType({ type: 'string' }) };
+export class AgentRequestError extends ProgramError {
+    requestId;
+    status;
+    constructor(code, message, requestId, status) {
+        super(code, message);
+        this.requestId = requestId;
+        this.status = status;
+    }
+}
+export function createProgramAgents(call) {
+    const request = (requestId, options) => call('agents.request', { requestId }, options);
+    const cancel = (requestId, options) => call('agents.cancel', { requestId }, options);
+    const ask = async (target, body, options = {}) => {
+        const timeout = options.timeoutMs ?? 120000;
+        if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3600000)
+            throw new ProgramError('INVALID_INPUT', 'Agent ask timeout must be 1..3600000ms');
+        options.signal?.throwIfAborted();
+        const key = options.requestId ?? randomUUID();
+        // Compile before sending anything: invalid schemas cannot spend model tokens.
+        const validate = createResponseValidator(options.responseSchema);
+        let view;
+        const controller = new AbortController(), timer = setTimeout(() => controller.abort(new ProgramError('TIMEOUT', 'Agent response deadline exceeded')), timeout);
+        const abort = () => controller.abort(options.signal?.reason ?? new ProgramError('CANCELLED', 'Agent ask cancelled'));
+        options.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            view = await call('agents.ask', { target: target, body, requestId: key, timeoutMs: timeout, ...options.responseSchema === undefined ? {} : { responseSchema: options.responseSchema }, ...options.instructions === undefined ? {} : { prompt: options.instructions } }, { signal: controller.signal, timeoutMs: Math.min(timeout, 120000) });
+            while (view.status === 'pending')
+                view = await call('agents.wait', { requestId: view.requestId, waitMs: Math.min(25000, Math.max(0, Date.parse(view.deadline) - Date.now())) }, { signal: controller.signal, timeoutMs: 30000 });
+            if (view.status === 'answered') {
+                validate(view.response);
+                return view.response;
+            }
+            throw new AgentRequestError(view.status === 'dispatch-unknown' ? 'DISPATCH_UNKNOWN' : view.status === 'expired' ? 'TIMEOUT' : view.status === 'cancelled' ? 'CANCELLED' : 'AGENT_REQUEST_FAILED', view.error ?? 'Agent request ' + view.status, view.requestId, view.status);
+        }
+        catch (error) {
+            // Cancellation only settles this response contract, never pretends the Agent's
+            // reasoning/external effects were undone. No message/delegation retries.
+            if (controller.signal.aborted) {
+                await cancel(view?.requestId ?? key, { timeoutMs: 5000 }).catch(() => { });
+                throw new AgentRequestError(options.signal?.aborted ? 'CANCELLED' : 'TIMEOUT', 'Agent ask interrupted; inspect the durable request before repeating work', view?.requestId ?? key, view?.status ?? 'pending');
+            }
+            if (error instanceof AgentRequestError)
+                throw error;
+            if (view?.status === 'answered' && error instanceof ProgramError && error.code === 'INVALID_RESPONSE')
+                throw error;
+            if (error instanceof ProgramError && !['TIMEOUT', 'CANCELLED', 'INVALID_RESPONSE', 'CALL_FAILED'].includes(error.code))
+                throw error;
+            throw new AgentRequestError('DISPATCH_UNKNOWN', 'Request transport failed; inspect using the request key before repeating work', view?.requestId ?? key, view?.status ?? 'dispatch-unknown');
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    };
+    return {
+        list: options => call('agents.list', null, options), get: (id, options) => call('agents.get', { id }, options),
+        send: (target, body, options = {}) => call('agents.send', { ...typeof target === 'string' ? { id: target } : { target: target }, body, ...options.correlationId === undefined ? {} : { correlationId: options.correlationId } }, options),
+        ask: ((target, body, typeOrOptions = {}, options = {}) => {
+            if ('schema' in typeOrOptions && 'parse' in typeOrOptions)
+                return ask(target, body, { ...options, responseSchema: typeOrOptions.schema }).then(value => typeOrOptions.parse(value));
+            return ask(target, body, typeOrOptions);
+        }), request, cancel,
+    };
+}
+//# sourceMappingURL=agents.js.map

package/dist/app/agents.js.map

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

package/dist/app/conversations.d.ts

@@ -0,0 +1,8 @@
+import type { JsonValue } from '../types.js';
+import type { CallOptions } from './index.js';
+import type { ProgramConversations } from '../conversations.js';
+export type * from '../conversations.js';
+export type ConversationBridgeCall = <T = JsonValue>(method: string, input?: JsonValue, options?: CallOptions) => Promise<T>;
+export type ConversationBridgeStream = (method: string, input?: JsonValue, options?: CallOptions) => AsyncIterable<JsonValue>;
+/** App-side handles contain no credentials, Agent objects, model calls, or tool loop. */
+export declare function createProgramConversations(call: ConversationBridgeCall, stream: ConversationBridgeStream): ProgramConversations;

package/dist/app/conversations.js

@@ -0,0 +1,26 @@
+import { randomUUID } from 'node:crypto';
+import { ProgramError } from '../runtime/protocol.js';
+/** App-side handles contain no credentials, Agent objects, model calls, or tool loop. */
+export function createProgramConversations(call, stream) {
+    const sendInput = (id, message, options = {}) => ({
+        id, message: message, requestId: options.requestId ?? randomUUID(), ...(options.mode === undefined ? {} : { mode: options.mode }),
+    });
+    const handle = (info) => Object.freeze({
+        ...info,
+        history: (options, callOptions) => call('conversations.history', { id: info.id, ...options }, callOptions),
+        events: (options = {}) => stream('conversations.events', { id: info.id, ...(options.maxMessages === undefined ? {} : { maxMessages: options.maxMessages }) }, { signal: options.signal }),
+        send: (message, options = {}) => call('conversations.send', sendInput(info.id, message, options), { signal: options.signal }),
+        ask: (message, options = {}) => {
+            if ('mode' in options && options.mode !== 'queue')
+                throw new ProgramError('INVALID_INPUT', 'Conversation ask requires a queued, distinct turn; use send for steering');
+            return stream('conversations.ask', sendInput(info.id, message, { requestId: options.requestId, signal: options.signal }), { signal: options.signal });
+        },
+        interrupt: options => call('conversations.interrupt', { id: info.id }, options),
+    });
+    return {
+        open: async (options, callOptions) => handle(await call('conversations.open', options, callOptions)),
+        get: async (id, options) => { const info = await call('conversations.get', { id }, options); return info ? handle(info) : null; },
+        list: options => call('conversations.list', {}, options),
+    };
+}
+//# sourceMappingURL=conversations.js.map

package/dist/app/conversations.js.map

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

package/dist/app/endpoints.d.ts

@@ -0,0 +1,36 @@
+import type { Server } from 'node:net';
+import type { ProgramEndpointBinding } from '../endpoints.js';
+import type { JsonValue } from '../types.js';
+import type { CallOptions } from './index.js';
+export type { ProgramEndpointBinding } from '../endpoints.js';
+export interface PublishEndpointOptions {
+    port: number;
+}
+export interface UnpublishEndpointOptions {
+    port?: number;
+}
+export interface ListeningProgramEndpoint {
+    port: number;
+    /** Authoritative bind host, not a browser-facing hostname. */
+    host: string;
+    /** Local verification URL; wildcard binds use their loopback equivalent. */
+    localUrl: string;
+    /** Close this listener and await its conditional unpublication. Idempotent. */
+    close(): Promise<void>;
+}
+export interface ProgramEndpoints {
+    list(options?: CallOptions): Promise<ProgramEndpointBinding[]>;
+    publish(id: string, address: PublishEndpointOptions, options?: CallOptions): Promise<ProgramEndpointBinding>;
+    unpublish(id: string, address?: UnpublishEndpointOptions, options?: CallOptions): Promise<ProgramEndpointBinding>;
+    /** Bind using current host configuration, then advertise the actual OS port. */
+    listen(id: string, server: Server, options?: CallOptions): Promise<ListeningProgramEndpoint>;
+}
+export type EndpointBridgeCall = <T = JsonValue>(method: string, input?: JsonValue, options?: CallOptions) => Promise<T>;
+/** Typed endpoint bridge helpers. Calls are never retried and use existing call cancellation. */
+export declare function createProgramEndpoints(call: EndpointBridgeCall): ProgramEndpoints;
+/**
+ * Bind a fresh Node net/http/https server using authoritative bridge configuration.
+ * Existing published ports and the app's environment do not choose the bind address.
+ * Frameworks managing their own listeners can instead use list/publish/unpublish.
+ */
+export declare function listenProgramEndpoint(endpoints: Pick<ProgramEndpoints, 'list' | 'publish' | 'unpublish'>, id: string, server: Server, options?: CallOptions): Promise<ListeningProgramEndpoint>;

package/dist/app/endpoints.js

@@ -0,0 +1,162 @@
+import { endpointName } from '../endpoints.js';
+import { ProgramError } from '../runtime/protocol.js';
+const managedServers = new WeakSet();
+const cancelled = () => new ProgramError('CANCELLED', 'Endpoint listen was cancelled');
+const unavailable = () => new ProgramError('UNAVAILABLE', 'Endpoint server closed during setup');
+const unbracket = (host) => host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+/** Typed endpoint bridge helpers. Calls are never retried and use existing call cancellation. */
+export function createProgramEndpoints(call) {
+    const endpoints = {
+        list: (options) => call('endpoints.list', null, options),
+        publish: (id, { port }, options) => call('endpoints.publish', { id, port }, options),
+        unpublish: (id, { port } = {}, options) => call('endpoints.unpublish', { id, ...(port === undefined ? {} : { port }) }, options),
+        listen: (id, server, options) => listenProgramEndpoint(endpoints, id, server, options),
+    };
+    return endpoints;
+}
+/**
+ * Bind a fresh Node net/http/https server using authoritative bridge configuration.
+ * Existing published ports and the app's environment do not choose the bind address.
+ * Frameworks managing their own listeners can instead use list/publish/unpublish.
+ */
+export async function listenProgramEndpoint(endpoints, id, server, options = {}) {
+    if (!endpointName(id))
+        throw new ProgramError('INVALID_INPUT', 'Invalid endpoint id');
+    if (server.listening || managedServers.has(server))
+        throw new ProgramError('BUSY', 'Endpoint helper requires an unbound, unmanaged server');
+    managedServers.add(server);
+    let attemptedBind = false;
+    let closed = false;
+    let setupComplete = false;
+    let setupFailed = false;
+    let setupError;
+    let port;
+    let publication;
+    let unpublication;
+    let closing;
+    let rejectSetup;
+    let resolveListening;
+    const interrupted = new Promise((_resolve, reject) => { rejectSetup = reject; });
+    // An error can arrive between awaited setup stages, before the next race attaches.
+    void interrupted.catch(() => { });
+    const listening = new Promise((resolve) => { resolveListening = resolve; });
+    const onListening = () => resolveListening();
+    const failSetup = (error) => {
+        if (!setupFailed) {
+            setupFailed = true;
+            setupError = error;
+        }
+        rejectSetup(error);
+    };
+    const onError = (error) => failSetup(error);
+    const onAbort = () => failSetup(cancelled());
+    const unpublish = () => {
+        if (!publication || port === undefined)
+            return Promise.resolve();
+        // A close during publication must unpublish AFTER that call settles, not before it.
+        return unpublication ??= (async () => {
+            await publication.catch(() => { });
+            await endpoints.unpublish(id, { port });
+        })();
+    };
+    const onClose = () => {
+        closed = true;
+        if (!setupComplete)
+            failSetup(unavailable());
+        else
+            managedServers.delete(server);
+        // Event callbacks cannot report a rejection; handle.close() still awaits/reports it.
+        if (publication)
+            void unpublish().catch(() => { });
+    };
+    const removeSetupListeners = () => {
+        server.removeListener('listening', onListening);
+        server.removeListener('error', onError);
+        options.signal?.removeEventListener('abort', onAbort);
+    };
+    const closeServer = () => new Promise((resolve, reject) => {
+        // Calling close also cancels an in-progress DNS/bind attempt. Do not merely test
+        // server.listening: it is false while listen is still acquiring its socket.
+        try {
+            server.close((error) => {
+                if (error && error.code !== 'ERR_SERVER_NOT_RUNNING')
+                    reject(error);
+                else
+                    resolve();
+            });
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+    try {
+        const bindings = await endpoints.list(options);
+        const binding = Array.isArray(bindings) ? bindings.find((item) => item?.id === id) : undefined;
+        if (!binding)
+            throw new ProgramError('NOT_FOUND', `Endpoint ${id} is not configured`);
+        if (typeof binding.bindHost !== 'string' || !binding.bindHost || !Number.isSafeInteger(binding.requestedPort) || binding.requestedPort < 0 || binding.requestedPort > 65535 || !['http', 'https'].includes(binding.protocol))
+            throw new ProgramError('INVALID_RESPONSE', 'Invalid endpoint binding configuration');
+        if (options.signal?.aborted)
+            throw cancelled();
+        // Do not take ownership of a server that somebody bound while list was pending.
+        if (server.listening)
+            throw new ProgramError('BUSY', 'Endpoint server was bound during configuration lookup');
+        server.once('listening', onListening);
+        server.on('error', onError);
+        server.once('close', onClose);
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        attemptedBind = true;
+        server.listen({ port: binding.requestedPort, host: unbracket(binding.bindHost) });
+        await Promise.race([listening, interrupted]);
+        if (setupFailed)
+            throw setupError;
+        if (options.signal?.aborted)
+            throw cancelled();
+        if (closed || !server.listening)
+            throw unavailable();
+        const address = server.address();
+        if (!address || typeof address === 'string' || !Number.isSafeInteger(address.port) || address.port < 1 || address.port > 65535)
+            throw new ProgramError('UNAVAILABLE', 'Endpoint server did not bind a TCP port');
+        port = address.port;
+        publication = endpoints.publish(id, { port }, options);
+        await Promise.race([publication, interrupted]);
+        if (setupFailed)
+            throw setupError;
+        if (options.signal?.aborted)
+            throw cancelled();
+        if (closed || !server.listening)
+            throw unavailable();
+        setupComplete = true;
+        removeSetupListeners();
+        let localHost = unbracket(binding.bindHost);
+        if (localHost === '0.0.0.0')
+            localHost = '127.0.0.1';
+        else if (localHost === '::')
+            localHost = '::1';
+        if (localHost.includes(':'))
+            localHost = `[${localHost}]`;
+        return {
+            port,
+            host: binding.bindHost,
+            localUrl: `${binding.protocol}://${localHost}:${port}/`,
+            close: () => closing ??= (async () => {
+                if (!closed)
+                    await closeServer();
+                await unpublish();
+            })(),
+        };
+    }
+    catch (error) {
+        setupComplete = true;
+        removeSetupListeners();
+        // Publish failures/cancellation have potentially unknown effects, so compensate
+        // once with the exact port. A failed bind never publishes or unpublishes.
+        if (attemptedBind && !closed)
+            await closeServer().catch(() => { });
+        await unpublish().catch(() => { });
+        server.removeListener('close', onClose);
+        managedServers.delete(server);
+        throw error;
+    }
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/app/endpoints.js.map

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

package/dist/app/inbox.d.ts

@@ -0,0 +1,61 @@
+import type { JsonValue } from '../types.js';
+import { ProgramError } from '../runtime/protocol.js';
+import type { CallOptions } from './index.js';
+import type { InboxMessage, MessageReceipt, ReceiveOptions } from './mailbox.js';
+export type InboxBridgeCall = <T = JsonValue>(method: string, input?: JsonValue, options?: CallOptions) => Promise<T>;
+export interface InboxReceiveOptions extends ReceiveOptions, CallOptions {
+}
+export interface ManagedReceiveOptions extends InboxReceiveOptions {
+    /** Callback deadline, independently of individual bridge calls. Default 120s; maximum 1h. */
+    processingTimeoutMs?: number;
+}
+export type ReadonlyInboxJson = string | number | boolean | null | readonly ReadonlyInboxJson[] | {
+    readonly [key: string]: ReadonlyInboxJson;
+};
+/** The callback cannot access the claim token or any settlement operation. */
+export type HandlerMessage = Readonly<Omit<InboxMessage, 'leaseToken' | 'body' | 'receipt'>> & {
+    readonly body: ReadonlyInboxJson;
+    readonly receipt: Readonly<MessageReceipt>;
+};
+export interface InboxHandlerContext {
+    readonly signal: AbortSignal;
+}
+export type InboxHandler<R> = (message: HandlerMessage, context: InboxHandlerContext) => R | PromiseLike<R>;
+type Claim = Pick<InboxMessage, 'id' | 'leaseToken'>;
+export interface ProgramInbox {
+    receive<R>(handler: InboxHandler<R>): Promise<R | null>;
+    receive<R>(options: ManagedReceiveOptions | undefined, handler: InboxHandler<R>): Promise<R | null>;
+    /** @deprecated Prefer receive(options, handler), which owns renewal and settlement. */
+    receive(options?: InboxReceiveOptions): Promise<InboxMessage | null>;
+    /** Low-level manual claim: the caller must renew and settle its own live lease. */
+    claim(options?: InboxReceiveOptions): Promise<InboxMessage | null>;
+    /** Low-level renewal, fenced by the exact live claim token and run. */
+    renew(message: Claim, leaseMs: number, options?: CallOptions): Promise<MessageReceipt>;
+    /** Low-level, single-attempt ACK. A rejected call may already have committed. */
+    ack(message: Claim | string, leaseToken?: string, options?: CallOptions): Promise<MessageReceipt>;
+    /** Low-level, single-attempt NACK. Requires the exact, unexpired claim. */
+    nack(message: Claim | string, leaseToken?: string, options?: CallOptions): Promise<MessageReceipt>;
+    /** Low-level durable status lookup; acceptance is not successful processing. */
+    receipt(id: string, options?: CallOptions): Promise<MessageReceipt | null>;
+}
+/** ACK may have committed before its response was lost. Neither retry nor NACK is safe. */
+export declare class SettlementUnknownError extends ProgramError {
+    readonly messageId: string;
+    readonly outcome: "unknown";
+    readonly operation: "ack";
+    readonly cause: unknown;
+    constructor(messageId: string, cause: unknown);
+}
+/**
+ * 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 declare function createProgramInbox(call: InboxBridgeCall): ProgramInbox;
+export {};