@addozhang/dsh-discord 0.4.0 → 0.5.0-alpha.2

package/lib/dsh/api-proxy-face.js

@@ -1,515 +0,0 @@
-/**
- * The typed face over the Host's in-process `ctx.apiProxy` service
- * (ApiProxyService, the transport-agnostic gateway's direct implementation).
- * Its domain methods speak the narrow RPC signature: `RpcRequest<P>` in,
- * `RpcResponse<T>` out, business errors on `result.ok === false` — they never
- * throw for business outcomes. Two guarantees are added here:
- *
- * 1. Boundedness — a Host that never answers must not wedge an interaction
- *    handler (or a Discord ephemeral) forever; every call races a timeout and
- *    resolves to an unobservable outcome instead.
- * 2. Observability — every terminal outcome is reported through the injected
- *    log sink, so a silent-void call can never again be misread as a hang.
- */
-import { parseWorkspaceReference } from '../policy/disclosure.js';
-/** Raised when the Host did not answer within the bounded window. */
-export class RpcTimeoutError extends Error {
-    constructor(timeoutMs) {
-        super(`dsh apiProxy call did not answer within ${String(timeoutMs)}ms`);
-        this.name = 'RpcTimeoutError';
-    }
-}
-/** Race one apiProxy promise against a bounded window. */
-export function withRpcTimeout(promise, timeoutMs) {
-    let timer;
-    const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => { reject(new RpcTimeoutError(timeoutMs)); }, timeoutMs);
-    });
-    return Promise.race([promise, timeout]).finally(() => {
-        if (timer !== undefined)
-            clearTimeout(timer);
-    });
-}
-/** Default bounded window for unary catalog reads (local, no model work). */
-const CATALOG_TIMEOUT_MS = 5_000;
-/** Default bounded window for prompt admission (the Host may enqueue). */
-const PROMPT_TIMEOUT_MS = 30_000;
-/** Mint a request envelope the way every client shape does. */
-function mintRequest(payload, rpcId) {
-    return { rpcId: rpcId ?? crypto.randomUUID(), payload };
-}
-/**
- * The bind flow's catalog verifier: resolves an opaque `ws:` reference
- * against the live workspace list. A well-formed reference the catalog no
- * longer knows — and any malformed one — resolve `stale` (fail-closed, no
- * write can follow); a Host error is `failed`; a timeout is `unknown`.
- */
-export function createWorkspaceResolver(dsh, options = {}) {
-    const port = createWorkspaceCatalogPort(dsh, options);
-    return {
-        async resolve(reference) {
-            const catalog = await port.listWorkspaces();
-            if (catalog.outcome !== 'completed') {
-                return catalog.outcome === 'unknown' ? { outcome: 'unknown' } : { outcome: 'failed' };
-            }
-            const id = parseWorkspaceReference(reference);
-            const found = id === undefined
-                ? undefined
-                : catalog.workspaces.find(workspace => workspace.id === id);
-            return found === undefined
-                ? { outcome: 'stale' }
-                : { outcome: 'found', workspace: { id: found.id, title: found.title } };
-        },
-    };
-}
-/**
- * The `/project list` catalog port satisfied by the in-process apiProxy.
- * Outcomes follow the port contract: a definitive Host error is `failed`
- * (sanitized before Discord), while a timeout or unreadable body is
- * `unknown` — delivery was not observed, so no retry is implied.
- */
-export function createWorkspaceCatalogPort(dsh, options = {}) {
-    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
-    const log = options.log;
-    return {
-        async listWorkspaces() {
-            let response;
-            try {
-                response = await withRpcTimeout(dsh.workspace.list(mintRequest({})), timeoutMs);
-            }
-            catch (cause) {
-                if (cause instanceof RpcTimeoutError) {
-                    log?.('discord_workspace_list_timeout', { timeoutMs });
-                    return { outcome: 'unknown' };
-                }
-                log?.('discord_workspace_list_threw', { cause: String(cause) });
-                return { outcome: 'failed' };
-            }
-            // A malformed envelope is a definitive, sanitized failure: the Host
-            // answered, so a retry is safe and semantics stay observable-free.
-            const result = response?.result;
-            if (result === undefined) {
-                log?.('discord_workspace_list_malformed');
-                return { outcome: 'failed' };
-            }
-            if (result.ok) {
-                const items = Array.isArray(result.value.items)
-                    ? result.value.items
-                    : [];
-                return {
-                    outcome: 'completed',
-                    workspaces: items.map(workspace => ({
-                        id: workspace.workspaceId,
-                        title: workspace.title,
-                        // The registered path rides every workspace.* row (Host
-                        // WorkspaceView); /session resume scopes candidates by it and
-                        // /project autocomplete abbreviates it — dropping it here once
-                        // silently emptied the resume list everywhere (16.46).
-                        ...(typeof workspace.path === 'string' ? { path: workspace.path } : {}),
-                    })),
-                    // The registry's archived set rides the workspace.list value
-                    // (sessions.list rows carry NO archived marker): /session resume
-                    // subtracts it — resuming an archived session dead-ends in a
-                    // thread whose turns never run (16.49).
-                    archivedSessionIds: Array.isArray(result.value.archivedSessionIds)
-                        ? result.value.archivedSessionIds.filter((id) => typeof id === 'string')
-                        : [],
-                };
-            }
-            log?.('discord_workspace_list_rejected', {
-                code: result.error.code,
-                message: result.error.message,
-            });
-            return { outcome: 'failed' };
-        },
-    };
-}
-/**
- * Read one Workspace's full view (title plus canonical path). The path is
- * for the administrator-only ephemeral info response — the disclosure
- * policy owns whether it ever renders; this face only carries it in memory.
- */
-export async function readWorkspaceDetail(dsh, reference, options = {}) {
-    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.workspace.list(mintRequest({})), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_workspace_detail_timeout', { timeoutMs });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_workspace_detail_threw', { cause: String(cause) });
-        return { outcome: 'failed' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        log?.('discord_workspace_detail_malformed');
-        return { outcome: 'failed' };
-    }
-    if (!result.ok) {
-        log?.('discord_workspace_detail_rejected', { code: result.error.code });
-        return { outcome: 'failed' };
-    }
-    const id = parseWorkspaceReference(reference) ?? (reference === '' ? undefined : reference);
-    const found = Array.isArray(result.value.items)
-        ? result.value.items.find(workspace => workspace.workspaceId === id)
-        : undefined;
-    if (found === undefined)
-        return { outcome: 'stale' };
-    return {
-        outcome: 'found',
-        workspace: {
-            id: found.workspaceId,
-            title: found.title,
-            path: typeof found.path === 'string' ? found.path : undefined,
-        },
-    };
-}
-/**
- * Submit one prompt turn through the in-process apiProxy. A definitive Host
- * error is a rejection carrying the sanitized code; a timeout is `unknown` —
- * the turn may or may not have been admitted, so callers must not resubmit.
- * `options.rpcId` pins the adapter-owned stable request id, which the Host
- * records on the durable `user/message` (`source.rpcId`) for reconciliation.
- * Images (16.50) encode as ordered `image` parts after the text part — the
- * rc.2 `session.prompt` content is parts-shaped at this seam.
- */
-export async function promptSession(dsh, request, options = {}) {
-    return submitPromptTurn(dsh, { ...request, mode: 'queue' }, options);
-}
-/**
- * Steer the session's active turn: `session.prompt` with `mode: 'steer'`,
- * carrying the same stable request-id discipline as the queue path.
- */
-export async function steerSession(dsh, request, options = {}) {
-    return submitPromptTurn(dsh, { ...request, mode: 'steer' }, options);
-}
-async function submitPromptTurn(dsh, request, options) {
-    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.prompt(mintRequest({
-            sessionId: request.sessionId,
-            mode: request.mode,
-            content: [
-                { type: 'text', text: request.prompt },
-                ...(request.images ?? []).map(image => ({ type: 'image', mediaType: image.mediaType, data: image.base64 })),
-            ],
-        }, options.rpcId)), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_prompt_submit_timeout', { timeoutMs, sessionId: request.sessionId });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_prompt_submit_threw', { cause: String(cause), sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        // An unreadable body leaves admission unobservable: the turn MAY have
-        // been admitted, so the at-most-once discipline forbids resubmission.
-        log?.('discord_prompt_submit_malformed', { sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    if (result.ok) {
-        // The wire schema pins accepted to literal true; the Host's own zod
-        // parse enforces it before this seam ever sees the body.
-        return { outcome: 'accepted' };
-    }
-    log?.('discord_prompt_submit_rejected', {
-        code: result.error.code,
-        sessionId: request.sessionId,
-    });
-    return { outcome: 'rejected', reason: result.error.code };
-}
-/**
- * Create one DSH Session against a preallocated id (design.md §10): DSH
- * adopts the same session id idempotently, so an uncertain response never
- * forks a second Session. Same outcome discipline as the prompt path.
- */
-export async function createSessionViaProxy(dsh, request, options = {}) {
-    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.create(mintRequest({
-            workspaceId: request.workspaceId,
-            sessionId: request.sessionId,
-        })), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_session_create_timeout', { timeoutMs, sessionId: request.sessionId });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_session_create_threw', { cause: String(cause), sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        log?.('discord_session_create_malformed', { sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    if (result.ok) {
-        return { outcome: 'completed', sessionId: result.value.sessionId };
-    }
-    log?.('discord_session_create_rejected', { code: result.error.code, sessionId: request.sessionId });
-    return { outcome: 'rejected', reason: result.error.code };
-}
-/** List durable Session ids (`session.list`, v1 returns everything). */
-export async function listSessionIds(dsh, options = {}) {
-    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.list(mintRequest({})), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_session_list_timeout', { timeoutMs });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_session_list_threw', { cause: String(cause) });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        log?.('discord_session_list_malformed');
-        return { outcome: 'failed' };
-    }
-    if (result.ok) {
-        return { outcome: 'completed', ids: Array.isArray(result.value.items) ? result.value.items.map(item => item.sessionId) : [] };
-    }
-    log?.('discord_session_list_rejected', { code: result.error.code });
-    return { outcome: 'failed' };
-}
-/**
- * The rich `sessions.list` for the /session resume surface: titles ride each
- * row's projection values (absence = the session has no title yet), blank
- * sessions are flagged, and rows arrive updatedAt-descending. Defensive
- * narrowing: the wire is untrusted, extra/missing fields never throw.
- */
-export async function listSessionSummaries(dsh, options = {}) {
-    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.list(mintRequest({})), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_session_summaries_timeout', { timeoutMs });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_session_summaries_threw', { cause: String(cause) });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined || !result.ok || !Array.isArray(result.value.items)) {
-        log?.('discord_session_summaries_malformed');
-        return { outcome: 'failed' };
-    }
-    const sessions = [];
-    // The wire is untrusted: narrow every row defensively before use.
-    const items = Array.isArray(result.value.items) ? result.value.items : [];
-    for (const item of items) {
-        if (typeof item !== 'object' || item === null)
-            continue;
-        const row = item;
-        if (typeof row.sessionId !== 'string' || row.sessionId === '')
-            continue;
-        const values = row.projections?.values;
-        const title = typeof values?.title === 'string' && values.title !== '' ? values.title : undefined;
-        sessions.push({
-            sessionId: row.sessionId,
-            title,
-            updatedAt: typeof row.updatedAt === 'number' ? row.updatedAt : 0,
-            running: row.running ?? false,
-            blank: row.blank === true,
-            cwd: typeof row.cwd === 'string' ? row.cwd : undefined,
-            origin: row.origin === 'subagent' ? 'subagent' : undefined,
-        });
-    }
-    return { outcome: 'completed', sessions };
-}
-/** Cancel the session's active turn (`session.cancel`); DSH preserves the pending inbox. */
-export async function cancelSessionViaProxy(dsh, request, options = {}) {
-    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.cancel(mintRequest({ sessionId: request.sessionId })), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_session_cancel_timeout', { timeoutMs, sessionId: request.sessionId });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_session_cancel_threw', { cause: String(cause), sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        log?.('discord_session_cancel_malformed', { sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    if (result.ok)
-        return { outcome: 'accepted' };
-    log?.('discord_session_cancel_rejected', { code: result.error.code, sessionId: request.sessionId });
-    return { outcome: 'rejected', reason: result.error.code };
-}
-/** Remove one pending inbox item (`session.updateQueue`, action remove). */
-export async function removeQueueItemViaProxy(dsh, request, options = {}) {
-    const timeoutMs = options.timeoutMs ?? CATALOG_TIMEOUT_MS;
-    const log = options.log;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.updateQueue(mintRequest({
-            sessionId: request.sessionId,
-            itemId: request.itemId,
-            action: { kind: 'remove' },
-        })), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            log?.('discord_queue_remove_timeout', { timeoutMs, sessionId: request.sessionId });
-            return { outcome: 'unknown' };
-        }
-        log?.('discord_queue_remove_threw', { cause: String(cause), sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        log?.('discord_queue_remove_malformed', { sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    if (result.ok)
-        return { outcome: 'accepted' };
-    log?.('discord_queue_remove_rejected', { code: result.error.code, sessionId: request.sessionId });
-    return { outcome: 'rejected', reason: result.error.code };
-}
-/**
- * The respond face for answerable server-requests (approvals, questions).
- * Builds the full ClientResponse envelope — {type: 'client-response',
- * rpcId, result: {ok: true, value}} is the wire contract; posting the bare
- * payload is silently ignored by the Host (rpcId never resolves) — and
- * maps the RpcReceipt onto the port outcome. Like every call in this module
- * it is bounded (a Host that never resolves the receipt must not wedge an
- * interaction handler or an expiry sweep forever) and never throws: a Host
- * rejection or timeout resolves to `unknown` — the response may or may not
- * have landed, and the callers park the ask `unresolved` on exactly that.
- */
-export function createClientRespondPort(dsh, options = {}) {
-    const log = options.log;
-    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
-    return {
-        async respond(rpcId, value) {
-            let receipt;
-            try {
-                const response = await withRpcTimeout(dsh.respond({
-                    type: 'client-response',
-                    rpcId,
-                    result: { ok: true, value },
-                }), timeoutMs);
-                receipt = response;
-            }
-            catch (cause) {
-                const reason = cause instanceof RpcTimeoutError ? 'discord_client_respond_timeout' : 'discord_client_respond_threw';
-                log?.(reason, { rpcId, ...(cause instanceof RpcTimeoutError ? { timeoutMs } : { cause: String(cause) }) });
-                return { outcome: 'unknown' };
-            }
-            const table = receipt;
-            log?.('discord_client_respond_receipt', { rpcId, receipt: table ?? null });
-            if (table?.accepted === true)
-                return { outcome: 'confirmed' };
-            if (table?.accepted === false) {
-                return { outcome: 'rejected', reason: typeof table.reason === 'string' ? table.reason : 'respond-refused' };
-            }
-            return { outcome: 'unknown' };
-        },
-    };
-}
-/** Bounded window for the per-session model directory read. */
-const MODELS_TIMEOUT_MS = 10_000;
-/**
- * The session's detached model directory: the live selection, whether the
- * current route still serves, and the per-provider catalog groups the
- * /model cascade browses.
- */
-export async function sessionModels(dsh, request, options = {}) {
-    const timeoutMs = options.timeoutMs ?? MODELS_TIMEOUT_MS;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.models(mintRequest({ sessionId: request.sessionId })), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            options.log?.('discord_models_timeout', { sessionId: request.sessionId });
-            return { outcome: 'unknown' };
-        }
-        options.log?.('discord_models_threw', { cause: String(cause), sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined || !result.ok) {
-        options.log?.('discord_models_malformed', {
-            sessionId: request.sessionId,
-            code: result?.ok === false ? result.error.code : 'malformed',
-        });
-        return { outcome: 'failed' };
-    }
-    return { outcome: 'completed', models: result.value };
-}
-/**
- * Select the complete model selection for one session (session.selectModel):
- * the session switches immediately and the Host records the choice as the
- * default for sessions that have not logged their own — the response only
- * proves the session switch, so callers must not claim the persistence
- * outcome (design.md §7).
- */
-export async function selectSessionModel(dsh, request, options = {}) {
-    const timeoutMs = options.timeoutMs ?? PROMPT_TIMEOUT_MS;
-    let response;
-    try {
-        response = await withRpcTimeout(dsh.sessions.selectModel(mintRequest({
-            sessionId: request.sessionId,
-            provider: request.provider,
-            model: request.model,
-            ...(request.reasoningEffort === undefined ? {} : { reasoningEffort: request.reasoningEffort }),
-        })), timeoutMs);
-    }
-    catch (cause) {
-        if (cause instanceof RpcTimeoutError) {
-            options.log?.('discord_model_select_timeout', { sessionId: request.sessionId });
-            return { outcome: 'unknown' };
-        }
-        options.log?.('discord_model_select_threw', { cause: String(cause), sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    const result = response?.result;
-    if (result === undefined) {
-        options.log?.('discord_model_select_malformed', { sessionId: request.sessionId });
-        return { outcome: 'unknown' };
-    }
-    if (result.ok) {
-        return { outcome: 'completed', selected: result.value.selected };
-    }
-    options.log?.('discord_model_select_rejected', { code: result.error.code, sessionId: request.sessionId });
-    return { outcome: 'rejected', reason: result.error.code };
-}
-/**
- * The /model surface over the real session RPCs: the per-session live
- * directory (`session.models`) and the guarded selection mutation
- * (`session.selectModel`) — the shapes model-control reasons about.
- */
-export function createModelPort(dsh, options = {}) {
-    return {
-        models: sessionId => sessionModels(dsh, { sessionId }, options),
-        selectModel: request => selectSessionModel(dsh, request, options),
-    };
-}