dsh-openwrite 0.2.28 → 0.2.33

package/packages/openwrite-bridge/lib/domain.js

@@ -1,5 +1,5 @@
 import { Service } from '@deepseek-ai/cordis';
-import { StudioClient, workspaceRootHeaders, workspaceRootsEqual, mutationAffectsState } from './client.js';
+import { StudioClient, StudioError, workspaceRootHeaders, workspaceRootsEqual, mutationAffectsState } from './client.js';
 import { workspaceContextFromExec } from './tools.js';
 export const CONFIG_ROUTE = '/studio-panel/config.json';
 export const API_PROXY_ROUTE = '/studio-panel/api';
@@ -8,7 +8,8 @@ export const INVALIDATION_ROUTE = '/studio-panel/invalidation.json';
 const PROXY_TIMEOUT_MS = 60_000;
 /** Cap for the best-effort upstream context_epoch read; never blocks a snapshot longer. */
 const CONTEXT_EPOCH_TIMEOUT_MS = 5_000;
-const WRITABLE_PATHS = new Set([
+/** Every browser write path the proxy forwards. Exported for the regression test. */
+export const WRITABLE_PATHS = new Set([
     'writing-assets',
     'arc-reconcile',
     'assets',
@@ -56,11 +57,44 @@ const WRITABLE_PATHS = new Set([
     'model/embedding/delete',
     'model/profiles',
     'model/profiles/delete',
+    // The two-step delete the panel drives: preview first, then the real delete.
+    'model/profiles/delete-preview',
     'model/routes',
+    // One profile that calls a model of the host's own directory.
+    'model/host-profiles',
     'chapter/delete-batch',
     'research/settings',
+    'research/preferences',
+]);
+export const WRITABLE_PATH_RE = /^(?:tasks\/[A-Za-z0-9_-]+\/(?:cancel|retry|confirm)|revisions\/(?:selection|from-review|rev_[A-Za-z0-9_-]+\/(?:apply|reject|regenerate)))$/;
+/**
+ * Paths whose payload is global, not project-scoped.
+ *
+ * The model profile library lives outside every project — Studio keeps it in
+ * the user's preferences directory (`model-profiles.json`), and every model
+ * route is registered with `requires_project=False`. The host settings dialog
+ * is the one surface that is opened *without* a bound workspace, so these
+ * paths must be reachable without a workspace id: the browser sends no
+ * `X-Dsh-Workspace-Id` and the proxy forwards the call without a project
+ * root, exactly as the contract's project-free routes expect.
+ *
+ * Every other proxied path stays fail-closed on a missing workspace id.
+ */
+export const GLOBAL_PATHS = new Set([
+    'model',
+    'model/test',
+    'model/embedding',
+    'model/embedding/test',
+    'model/embedding/select',
+    'model/embedding/delete',
+    'model/profiles',
+    'model/profiles/delete',
+    'model/profiles/delete-preview',
+    'model/routes',
+    'model/host-models',
+    'model/host-profiles',
+    'research/preferences',
 ]);
-const WRITABLE_PATH_RE = /^(?:tasks\/[A-Za-z0-9_-]+\/(?:cancel|retry|confirm)|revisions\/(?:selection|from-review|rev_[A-Za-z0-9_-]+\/(?:apply|reject|regenerate)))$/;
 /** Mutation/SSE state bucket key for context-less (legacy) mutations. */
 const LEGACY_ROOT_KEY = '';
 function sendJson(res, status, payload) {
@@ -72,13 +106,33 @@ function sendJson(res, status, payload) {
     });
     res.end(body);
 }
+/**
+ * Ceiling for one proxied request body. The runtime route already caps its
+ * uploads at 1 KiB; without a cap here an authenticated browser session can
+ * push an unbounded body into the host process's memory.
+ */
+const MAX_PROXY_BODY_BYTES = 32 * 1024 * 1024;
+/** Ceiling for one proxied download (export / project archive). */
+const MAX_PROXY_DOWNLOAD_BYTES = 64 * 1024 * 1024;
+/** Per-stream ceiling on undelivered SSE bytes before the stream is dropped. */
+const MAX_SSE_PENDING_BYTES = 4 * 1024 * 1024;
+/** Concurrent invalidation streams allowed per workspace root. */
+const MAX_SSE_STREAMS_PER_ROOT = 64;
+/** Reap an SSE connection that has been silent this long (half-open peers). */
+const SSE_IDLE_TIMEOUT_MS = 120_000;
 async function readBody(req) {
     const iterator = req[Symbol.asyncIterator];
     if (iterator === undefined)
         return Buffer.alloc(0);
     const chunks = [];
+    let total = 0;
     for await (const chunk of iterator.call(req)) {
-        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        total += bytes.byteLength;
+        if (total > MAX_PROXY_BODY_BYTES) {
+            throw new StudioError(`Proxied request body exceeds ${MAX_PROXY_BODY_BYTES} bytes`, 413, 'PAYLOAD_TOO_LARGE');
+        }
+        chunks.push(bytes);
     }
     return Buffer.concat(chunks);
 }
@@ -214,6 +268,8 @@ export class NovelDomainService extends Service {
     connect;
     baseUrl;
     resolveWorkspace;
+    /** Undelivered SSE bytes per stream, for backpressure (see notifyMutation). */
+    streamPending = new Map();
     /** Per-root invalidation state, keyed by canonical workspace root ('' = legacy). */
     roots = new Map();
     /** Open SSE connections bound to the root key they subscribed to. */
@@ -247,9 +303,41 @@ export class NovelDomainService extends Service {
         state.lastMutation = { revision: state.revision, resource: resourceForPath(path), path };
         this.roots.set(root, state);
         const event = JSON.stringify({ workspace_root: root, ...state.lastMutation });
+        const payload = `event: invalidate\ndata: ${event}\n\n`;
         for (const [stream, key] of this.streams) {
-            if (key === root)
-                stream.write(`event: invalidate\ndata: ${event}\n\n`);
+            if (key !== root)
+                continue;
+            // Honour backpressure. `write()` returning false means the socket is not
+            // draining; without a `drain` listener the host buffers every event for a
+            // stalled client without bound. Track pending bytes and drop a stream that
+            // falls too far behind — EventSource reconnects and catches up from the
+            // revision in the ready event.
+            const pending = (this.streamPending.get(stream) ?? 0) + Buffer.byteLength(payload);
+            if (pending > MAX_SSE_PENDING_BYTES) {
+                this.streamPending.delete(stream);
+                this.streams.delete(stream);
+                try {
+                    stream.end();
+                }
+                catch { /* already disconnected */ }
+                continue;
+            }
+            const drained = stream.write(payload);
+            if (drained === false) {
+                this.streamPending.set(stream, pending);
+                const onDrain = () => {
+                    stream.on?.('drain', onDrain);
+                    const left = Math.max(0, (this.streamPending.get(stream) ?? 0) - Buffer.byteLength(payload));
+                    if (left === 0)
+                        this.streamPending.delete(stream);
+                    else
+                        this.streamPending.set(stream, left);
+                };
+                stream.on?.('drain', onDrain);
+            }
+            else {
+                this.streamPending.delete(stream);
+            }
         }
     }
     /** Snapshot of one root's invalidation state (zero revision when never mutated). */
@@ -283,6 +371,21 @@ export class NovelDomainService extends Service {
      * closed per the contract: missing id → 400 WORKSPACE_CONTEXT_MISSING, no
      * registry → 503 WORKSPACE_REGISTRY_UNAVAILABLE, unknown id → 400 WORKSPACE_UNKNOWN.
      */
+    /**
+     * The workspace a browser view belongs to, for invalidation only.
+     *
+     * An unknown or absent workspace id resolves to the global bucket rather
+     * than to a rejection: the payload of a global path does not depend on the
+     * workspace, so a stale id must not turn a readable answer into an error.
+     */
+    viewerRoot(id) {
+        if (id === undefined || id === '')
+            return LEGACY_ROOT_KEY;
+        if (this.resolveWorkspace === undefined)
+            return LEGACY_ROOT_KEY;
+        const root = this.resolveWorkspace(id);
+        return root === undefined || root === null ? LEGACY_ROOT_KEY : root;
+    }
     resolveBrowserWorkspace(id) {
         if (id === undefined) {
             return { rejection: { status: 400, code: 'WORKSPACE_CONTEXT_MISSING', message: 'missing workspace id (x-dsh-workspace-id header or ?workspace= param)' } };
@@ -315,6 +418,8 @@ export class NovelDomainService extends Service {
         // route does not close requests already handled by it; end them explicitly
         // so EventSource reconnects to the newly mounted plugin after a reload.
         const responses = new Set();
+        /** Responses the dispose cleanup already answered; handlers must not write again. */
+        const finalized = new Set();
         const lifetime = new AbortController();
         let disposed = false;
         ctx.effect(() => () => {
@@ -322,24 +427,59 @@ export class NovelDomainService extends Service {
             lifetime.abort();
             for (const response of responses) {
                 this.streams.delete(response);
+                this.streamPending.delete(response);
+                finalized.add(response);
+                // A response the handler has not started must not be ended with no
+                // status and no body: Node silently drops the later writeHead/end, so
+                // the browser sees an empty 200 and pollInvalidation throws on .json(),
+                // flipping the panel to "offline" on a mere plugin reload.
                 try {
-                    response.end();
+                    if (response.headersSent !== true) {
+                        response.writeHead(503, { 'content-type': 'application/json', 'cache-control': 'no-cache' });
+                        response.end(JSON.stringify({ error: 'novel-domain is reloading', code: 'NOVEL_DOMAIN_DISPOSED' }));
+                    }
+                    else if (response.writableEnded !== true) {
+                        response.end();
+                    }
                 }
                 catch { /* already disconnected */ }
             }
             responses.clear();
+            // Do NOT clear `finalized`: a handler suspended on its upstream epoch read
+            // resumes after this cleanup and must still see that its response was
+            // already answered, or it writes a second status into a closed socket.
         }, 'novel-domain: close live invalidation responses');
         ctx.effect(() => register({
             kind: 'exact',
             path: CONFIG_ROUTE,
-            handler: (req, res) => {
+            handler: async (req, res) => {
                 if (req.method !== 'GET' && req.method !== 'HEAD') {
                     res.writeHead(405);
                     res.end();
                     return;
                 }
                 res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-cache' });
-                res.end(JSON.stringify({ studioUrl: this.baseUrl }));
+                // In managed mode `this.baseUrl` is only the configured default (often
+                // the never-bound 127.0.0.1:4567); the real backend is the one `connect()`
+                // resolves. Report the live URL when there is one, and say so when the
+                // mode makes a static URL meaningless.
+                const managed = this.connect !== undefined;
+                // Await the resolution so the route answers once, with the real URL.
+                let studioUrl = this.baseUrl;
+                let available = true;
+                if (this.connect !== undefined) {
+                    try {
+                        const connection = await this.connect();
+                        if (connection !== undefined)
+                            studioUrl = connection.baseUrl;
+                    }
+                    catch {
+                        available = false;
+                    }
+                }
+                res.end(JSON.stringify(available
+                    ? { studioUrl, managed }
+                    : { studioUrl, managed, available: false }));
             },
         }), 'novel-domain: config route');
         ctx.effect(() => register({
@@ -370,19 +510,35 @@ export class NovelDomainService extends Service {
                 // how polling clients observe background task transitions that never
                 // touch the bridge-local revision.
                 responses.add(res);
-                const contextEpoch = await this.fetchContextEpoch(resolved.root, resolved.id, lifetime.signal);
-                responses.delete(res);
-                if (disposed)
-                    return;
-                sendJson(res, 200, contextEpoch === null ? snapshot : { ...snapshot, context_epoch: contextEpoch });
+                try {
+                    const contextEpoch = await this.fetchContextEpoch(resolved.root, resolved.id, lifetime.signal);
+                    // Check `disposed` while still registered: deleting `res` first made
+                    // this guard unreachable, and the cleanup then ended an unstarted
+                    // response as an empty 200.
+                    if (disposed || finalized.has(res)) {
+                        // Already answered by the dispose cleanup: its 503 notice stands.
+                        if (!finalized.has(res)) {
+                            sendJson(res, 503, { error: 'novel-domain is reloading', code: 'NOVEL_DOMAIN_DISPOSED' });
+                        }
+                        return;
+                    }
+                    sendJson(res, 200, contextEpoch === null ? snapshot : { ...snapshot, context_epoch: contextEpoch });
+                }
+                finally {
+                    responses.delete(res);
+                }
             },
         }), 'novel-domain: invalidation snapshot');
         ctx.effect(() => register({
             kind: 'exact',
             path: EVENTS_ROUTE,
             handler: async (req, res) => {
-                if (disposed) {
-                    sendJson(res, 503, { error: 'novel-domain is reloading', code: 'NOVEL_DOMAIN_DISPOSED' });
+                if (disposed || finalized.has(res)) {
+                    // A reload ends every live response with a 503 notice; a handler that
+                    // resumes afterwards must not write to it again.
+                    if (!finalized.has(res)) {
+                        sendJson(res, 503, { error: 'novel-domain is reloading', code: 'NOVEL_DOMAIN_DISPOSED' });
+                    }
                     return;
                 }
                 if (req.method !== 'GET') {
@@ -395,6 +551,17 @@ export class NovelDomainService extends Service {
                     NovelDomainService.sendRejection(res, resolved.rejection);
                     return;
                 }
+                // Cap concurrent streams per root, and reap connections whose peer
+                // vanished without FIN/RST (sleep, Wi-Fi handoff) — those never emit
+                // 'close', so both maps and the socket leak until OS keepalive.
+                let live = 0;
+                for (const key of this.streams.values())
+                    if (key === resolved.root)
+                        live += 1;
+                if (live >= MAX_SSE_STREAMS_PER_ROOT) {
+                    sendJson(res, 429, { error: 'Too many live invalidation streams for this workspace', code: 'SSE_LIMIT' });
+                    return;
+                }
                 res.writeHead(200, {
                     'content-type': 'text/event-stream',
                     'cache-control': 'no-cache',
@@ -402,16 +569,23 @@ export class NovelDomainService extends Service {
                 });
                 responses.add(res);
                 this.streams.set(res, resolved.root);
-                const dispose = () => { this.streams.delete(res); responses.delete(res); };
+                const dispose = () => { this.streams.delete(res); this.streamPending.delete(res); responses.delete(res); };
                 res.on?.('close', dispose);
                 res.on?.('error', dispose);
+                res.setTimeout?.(SSE_IDLE_TIMEOUT_MS, () => { dispose(); try {
+                    res.end();
+                }
+                catch { /* already gone */ } });
                 // The ready event carries the upstream context epoch when it is
                 // readable; the stream waits for the fetch to settle (capped at
                 // CONTEXT_EPOCH_TIMEOUT_MS), never longer. A client gone by then
                 // simply never gets the ready event — polling carries epochs anyway.
                 const revision = this.roots.get(resolved.root)?.revision ?? 0;
                 const contextEpoch = await this.fetchContextEpoch(resolved.root, resolved.id, lifetime.signal);
-                if (disposed || !this.streams.has(res))
+                // The dispose cleanup may have ended this response already (with its
+                // 503 notice); writing again would throw or be silently dropped. The
+                // entry guard above already covers `writableEnded`.
+                if (disposed || !this.streams.has(res) || finalized.has(res))
                     return;
                 const ready = { workspace_root: resolved.root, revision };
                 if (contextEpoch !== null)
@@ -433,14 +607,28 @@ export class NovelDomainService extends Service {
             }
             // Every browser request carries only a workspace_id; the trusted host
             // registry resolves it to the canonical root (contract §2.2).
-            const resolved = this.resolveBrowserWorkspace(headerValue(req, 'x-dsh-workspace-id'));
+            const method = req.method ?? 'GET';
+            const pathPart = sub.split('?')[0]?.slice(1) ?? '';
+            const isWrite = method === 'POST' || method === 'PUT';
+            // A global path (the model library) is answered without a workspace:
+            // its payload lives outside every project, and the settings dialog has
+            // no workspace bound to send.
+            const isGlobal = GLOBAL_PATHS.has(pathPart);
+            const resolved = isGlobal
+                ? { root: '', id: '' }
+                : this.resolveBrowserWorkspace(headerValue(req, 'x-dsh-workspace-id'));
             if ('rejection' in resolved) {
                 NovelDomainService.sendRejection(res, resolved.rejection);
                 return;
             }
-            const method = req.method ?? 'GET';
-            const pathPart = sub.split('?')[0]?.slice(1) ?? '';
-            const isWrite = method === 'POST' || method === 'PUT';
+            // A global path is answered without a workspace: its payload lives
+            // outside every project. The view that asked is still a view, though —
+            // its own workspace has to learn that the model library moved. The
+            // upstream call stays workspace-free; only the invalidation follows the
+            // requester, and a request that named no workspace stays global.
+            const mutationRoot = isGlobal
+                ? this.viewerRoot(headerValue(req, 'x-dsh-workspace-id'))
+                : resolved.root;
             if (!isWrite && method !== 'GET' && method !== 'HEAD') {
                 sendJson(res, 405, { error: 'novel-domain proxy allows only GET/HEAD and allowlisted writes' });
                 return;
@@ -453,8 +641,10 @@ export class NovelDomainService extends Service {
             try {
                 const headers = {
                     accept: 'application/json',
-                    ...workspaceRootHeaders(resolved.root, true),
-                    'x-openwrite-workspace-id': resolved.id,
+                    // A global path carries no workspace identity at all: the Core reads
+                    // a blank root header as "legacy mode" and serves the request from
+                    // the root app, whose model library is the user's global one.
+                    ...(isGlobal ? {} : { ...workspaceRootHeaders(resolved.root, true), 'x-openwrite-workspace-id': resolved.id }),
                 };
                 const sessionId = headerValue(req, 'x-dsh-session-id');
                 if (sessionId !== undefined)
@@ -477,12 +667,27 @@ export class NovelDomainService extends Service {
                 if (lifetime.aborted)
                     return;
                 const actualRoot = upstream.headers.get('X-OpenWrite-Project-Path');
-                if (upstream.ok && actualRoot && !workspaceRootsEqual(decodeURIComponent(actualRoot), resolved.root)) {
+                // A global path asked for no project, so the root the upstream reports
+                // is the only one it can have: comparing it against an empty request
+                // root would reject every answer.
+                if (!isGlobal && upstream.ok && actualRoot && !workspaceRootsEqual(decodeURIComponent(actualRoot), resolved.root)) {
                     await upstream.body?.cancel();
                     sendJson(res, 409, { error: 'Connected workspace differs from requested project', code: 'WORKSPACE_CONTEXT_MISMATCH', details: { requested_path: resolved.root, project_path: decodeURIComponent(actualRoot) } });
                     return;
                 }
+                // Bound the buffer: an export or project archive is read fully into
+                // memory, and `content-length` is computed from it afterwards.
+                const declaredLength = Number(upstream.headers.get('content-length') ?? '');
+                if (Number.isFinite(declaredLength) && declaredLength > MAX_PROXY_DOWNLOAD_BYTES) {
+                    await upstream.body?.cancel();
+                    sendJson(res, 502, { error: 'The download is too large to proxy', code: 'DOWNLOAD_TOO_LARGE', details: { limit: MAX_PROXY_DOWNLOAD_BYTES } });
+                    return;
+                }
                 const upstreamBytes = Buffer.from(await upstream.arrayBuffer());
+                if (upstreamBytes.byteLength > MAX_PROXY_DOWNLOAD_BYTES) {
+                    sendJson(res, 502, { error: 'The download is too large to proxy', code: 'DOWNLOAD_TOO_LARGE', details: { limit: MAX_PROXY_DOWNLOAD_BYTES } });
+                    return;
+                }
                 const bytes = compactTaskList(upstreamBytes, pathPart, method);
                 const responseHeaders = {
                     'content-type': upstream.headers.get('content-type') ?? 'application/json',
@@ -500,17 +705,33 @@ export class NovelDomainService extends Service {
                 res.writeHead(upstream.status, responseHeaders);
                 res.end(bytes);
                 if (isWrite && upstream.ok && mutationAffectsState(pathPart, body, upstream.headers)) {
-                    this.notifyMutation(`/api/${pathPart}`, { workspaceRoot: resolved.root, workspaceId: resolved.id });
+                    this.notifyMutation(`/api/${pathPart}`, { workspaceRoot: mutationRoot, workspaceId: resolved.id });
                 }
             }
             catch (error) {
-                if (!lifetime.aborted) {
+                // A browser that disconnects mid-upload makes readBody reject; writing a
+                // response into a dead socket throws again and masks the real cause.
+                if (!lifetime.aborted && !res.headersSent && res.writableEnded !== true) {
                     const failure = error;
                     if (failure.code === 'RUNTIME_PLATFORM_UNSUPPORTED') {
                         sendJson(res, 503, { error: failure.message, code: failure.code });
                     }
-                    else
-                        sendJson(res, 502, { error: '写作环境暂不可用，请打开环境与诊断重试' });
+                    else if (failure.code === 'PAYLOAD_TOO_LARGE') {
+                        sendJson(res, 413, { error: failure.message, code: failure.code });
+                    }
+                    else if (failure.code === 'DOWNLOAD_TOO_LARGE') {
+                        sendJson(res, 502, { error: failure.message, code: failure.code });
+                    }
+                    else {
+                        // Preserve the upstream identity: the panel maps specific codes
+                        // (DOCUMENT_CONFLICT, STALE_REVISION, WORKSPACE_NOT_INITIALIZED, …)
+                        // to localized, actionable messages. Collapsing them into one 502
+                        // turns a recoverable conflict into an opaque failure.
+                        const status = typeof failure.status === 'number' && failure.status >= 400 && failure.status < 600 ? failure.status : 502;
+                        const code = typeof failure.code === 'string' && failure.code !== '' ? failure.code : 'STUDIO_UNAVAILABLE';
+                        const message = status === 502 ? '写作环境暂不可用，请打开环境与诊断重试' : (failure.message ?? 'Studio request failed');
+                        sendJson(res, status, { error: message, code, ...(failure.details === undefined ? {} : { details: failure.details }) });
+                    }
                 }
             }
             finally {

package/packages/openwrite-bridge/lib/host-llm.d.ts

@@ -0,0 +1,188 @@
+/**
+ * A loopback-only, OpenAI-compatible relay onto the host's own model
+ * directory.
+ *
+ * OpenWrite's Core speaks the OpenAI chat-completions protocol (LiteLLM), so
+ * giving it a plain HTTP endpoint is enough to make every model dsh itself can
+ * reach — the host's own adapters and the models other plugins register into
+ * the same directory — usable from a writing task. The relay never sees a
+ * provider key: the host's `llm` service owns the credentials and performs the
+ * call, so the relay only translates a request shape.
+ *
+ * The relay is deliberately NOT mounted on the host's web server. That port is
+ * browser-authenticated and possibly reachable from the LAN; this one is bound
+ * to 127.0.0.1 on an ephemeral port and answers only to a machine token that
+ * is handed to the Core process over its private stdio handshake.
+ */
+/** Structural view of the host's `llm` service (`ctx.get('llm')`). */
+export interface HostLlmService {
+    listProviders(): Array<{
+        id: string;
+        name: string;
+    }>;
+    listConfigurableProviders?(): Array<{
+        provider: string;
+        displayName: string;
+        settingsNs: string;
+    }>;
+    listModels(provider: string): Promise<Array<{
+        provider: string;
+        id: string;
+        name: string;
+        description?: string;
+    }>>;
+    resolveModelInfo?(provider: string, model: string, signal?: AbortSignal): Promise<{
+        context?: {
+            contextWindow?: number;
+        };
+    }>;
+    stream(options: HostGenerateOptions): AsyncIterable<HostStreamChunk>;
+}
+/** Why the host's model call stopped. A failure carries the provider's words. */
+export interface HostFinishReason {
+    kind: 'stop' | 'tool-calls' | 'max-tokens' | 'aborted' | 'error' | string;
+    failure?: {
+        message?: string;
+        code?: string;
+        status?: number;
+    };
+}
+export interface HostGenerateOptions {
+    provider: string;
+    model: string;
+    messages: unknown[];
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+    tools?: unknown[];
+    reasoningEffort?: string;
+    signal?: AbortSignal;
+}
+export type HostStreamChunk = {
+    type: 'block-start';
+    index: number;
+    blockType: string;
+} | {
+    type: 'text-delta';
+    index: number;
+    text: string;
+} | {
+    type: 'reasoning-delta';
+    index: number;
+    text: string;
+} | {
+    type: 'tool-call-delta';
+    index: number;
+    id: string;
+    name?: string;
+    argumentsDelta: string;
+} | {
+    type: 'block-end';
+    index: number;
+    block: {
+        type: string;
+        text?: string;
+        id?: string;
+        name?: string;
+        arguments?: string;
+    };
+} | {
+    type: 'usage';
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+} | {
+    type: 'finish';
+    reason: string | HostFinishReason;
+};
+/** The host's own default-model selection, when the host composes that service. */
+export type HostDefaultSelection = () => {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+} | undefined;
+/** Pseudo model id meaning "whatever dsh itself would use right now". */
+export declare const HOST_CURRENT_MODEL = "host/current";
+/** One directory entry the Core side renders as a selectable model. */
+export interface HostModelEntry {
+    /** `provider/model` route, or {@link HOST_CURRENT_MODEL}. */
+    id: string;
+    provider: string;
+    model: string;
+    label: string;
+    description: string;
+    /** The route's own context budget, when the adapter declares one. */
+    contextTokens: number;
+}
+export interface HostModelCatalog {
+    available: boolean;
+    providers: Array<{
+        id: string;
+        name: string;
+    }>;
+    models: HostModelEntry[];
+    /** Present when the host composes a default-model service. */
+    current: {
+        provider: string;
+        model: string;
+    } | null;
+    error: string;
+}
+export interface HostLlmRelayOptions {
+    llm: HostLlmService;
+    /** Machine token; every request must present it as a bearer credential. */
+    token: string;
+    /** The host's default-model selection, when the host composes that service. */
+    defaultSelection?: HostDefaultSelection;
+    /**
+     * How long one provider's directory may take before the catalog gives up on
+     * it. Overridable so the gate can be exercised without waiting for it.
+     */
+    providerDeadlineMs?: number;
+    /**
+     * How long one model's context lookup may take. It is optional metadata, so
+     * a slow lookup must cost the entry its context window, never the entry.
+     */
+    modelDeadlineMs?: number;
+}
+export declare class HostLlmRelay {
+    private readonly options;
+    private server?;
+    private port;
+    private closed;
+    constructor(options: HostLlmRelayOptions);
+    /** Bind the loopback port. Idempotent. */
+    listen(): Promise<void>;
+    /** The OpenAI-compatible base URL Core should use. */
+    baseUrl(): string;
+    /** The machine token Core must present. */
+    token(): string;
+    close(): Promise<void>;
+    /** The host's model directory, including the models other plugins registered. */
+    catalog(): Promise<HostModelCatalog>;
+    /** One provider's models, or none when that provider did not answer in time. */
+    private providerModels;
+    /** The route's own context budget, or 0 when the adapter declares none. */
+    private contextTokens;
+    /** Split `provider/model`; the first segment is the provider route. */
+    private resolveRoute;
+    private handle;
+    private authorized;
+    private chatCompletions;
+    /**
+     * Retry once without the reasoning effort when the host refuses it.
+     *
+     * A model that declares no reasoning support rejects an explicit effort
+     * (the host reports `UNSUPPORTED_REASONING_EFFORT` as a terminal finish).
+     * Asking for "no reasoning" must never turn into a failed call, so the
+     * second attempt drops the effort and lets the provider decide. The retry
+     * only happens before any content was produced: the refusal arrives as the
+     * first chunk, so nothing has been written to the client yet.
+     */
+    private withEffortFallback;
+    private writeChunk;
+}
+/** A fresh machine token for one relay instance. */
+export declare function newRelayToken(): string;