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

package/lib/dsh/api-proxy-face.d.ts

@@ -1,400 +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 type { ProjectListPort } from '../features/project-list.js';
-import type { WorkspaceResolver } from '../features/project-bind.js';
-/** The workspace rows the catalog port needs (subset of WorkspaceView). */
-export interface WorkspaceCatalogEntry {
-    workspaceId: string;
-    title: string;
-    /** Canonical directory; present in Host responses, rendered only to proven administrators. */
-    path?: string | undefined;
-}
-/** The narrow slice of ApiProxy this module speaks. */
-export interface DshApiProxyFace {
-    workspace: {
-        list(request: RpcRequestShape<Record<string, never>>): Promise<RpcResponseShape<{
-            items: WorkspaceCatalogEntry[];
-        }>>;
-    };
-    sessions: {
-        prompt(request: RpcRequestShape<{
-            sessionId: string;
-            mode: 'queue' | 'steer';
-            content: Array<{
-                type: 'text';
-                text: string;
-            } | {
-                type: 'image';
-                mediaType: string;
-                data: string;
-            }>;
-        }>): Promise<RpcResponseShape<{
-            accepted: true;
-        }>>;
-        create(request: RpcRequestShape<{
-            workspaceId?: string;
-            sessionId?: string;
-            agentPreset?: string;
-        }>): Promise<RpcResponseShape<{
-            sessionId: string;
-        }>>;
-        cancel(request: RpcRequestShape<{
-            sessionId: string;
-        }>): Promise<RpcResponseShape<{
-            accepted: true;
-        }>>;
-        updateQueue(request: RpcRequestShape<{
-            sessionId: string;
-            itemId: string;
-            action: {
-                kind: 'remove';
-            };
-        }>): Promise<RpcResponseShape<{
-            accepted: true;
-        }>>;
-        list(request: RpcRequestShape<{
-            cursor?: string;
-        }>): Promise<RpcResponseShape<{
-            items: SessionSummaryShape[];
-        }>>;
-        models(request: RpcRequestShape<{
-            sessionId: string;
-        }>): Promise<RpcResponseShape<SessionModelsShape>>;
-        selectModel(request: RpcRequestShape<{
-            sessionId: string;
-            provider: string;
-            model: string;
-            reasoningEffort?: string;
-        }>): Promise<RpcResponseShape<{
-            selected: ModelSelectionShape;
-        }>>;
-    };
-}
-/** Defensive read of the title projection in a list row's values. */
-export interface SessionProjectionsShape {
-    values?: {
-        title?: unknown;
-    };
-}
-/** The per-session summary `sessions.list` returns (rc.2 rich rows). */
-export interface SessionSummaryShape {
-    sessionId: string;
-    updatedAt: number;
-    running: boolean;
-    blank: boolean;
-    cwd?: string;
-    agentPreset?: string;
-    origin?: 'subagent';
-    projections?: SessionProjectionsShape;
-}
-/** The complete provider/model/reasoning selection (dsh-agent ModelSelection). */
-export interface ModelSelectionShape {
-    provider: string;
-    model: string;
-    reasoningEffort?: string;
-}
-/** One reasoning effort a model's adapter advertises (sessions.d.ts). */
-import type { DshModelPort } from '../features/model-control.js';
-export interface ModelReasoningEffortShape {
-    id: string;
-    name: string;
-    description?: string;
-}
-/** Exact-route reasoning metadata for one catalog model. */
-export interface ModelReasoningShape {
-    efforts: ModelReasoningEffortShape[];
-    defaultEffort?: string;
-}
-/** One model inside a provider group (sessions.d.ts ModelCatalogModel). */
-export interface ModelCatalogModelShape {
-    id: string;
-    name: string;
-    description?: string;
-    reasoning?: ModelReasoningShape;
-}
-/** One provider group and its models (sessions.d.ts ModelProviderGroup). */
-export interface ModelProviderGroupShape {
-    id: string;
-    name: string;
-    models: ModelCatalogModelShape[];
-}
-/** The detached model directory `session.models` returns for one session. */
-export interface SessionModelsShape {
-    current: ModelSelectionShape;
-    routable: boolean;
-    groups: ModelProviderGroupShape[];
-    failures: Array<{
-        id: string;
-        name: string;
-        message: string;
-    }>;
-}
-/** Signature-layer narrow request form (RpcId brand erased at this seam). */
-export interface RpcRequestShape<P> {
-    rpcId: string;
-    payload: P;
-}
-/** Signature-layer narrow response form with the business ok/error result. */
-export interface RpcResponseShape<T> {
-    rpcId: string;
-    result: {
-        ok: true;
-        value: T;
-    } | {
-        ok: false;
-        error: {
-            code: string;
-            message: string;
-        };
-    };
-}
-/** Raised when the Host did not answer within the bounded window. */
-export declare class RpcTimeoutError extends Error {
-    constructor(timeoutMs: number);
-}
-/** Race one apiProxy promise against a bounded window. */
-export declare function withRpcTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
-/** Diagnostic sink shared by both faces. */
-export type ApiProxyLog = (event: string, detail?: unknown) => void;
-export interface ApiProxyFaceOptions {
-    timeoutMs?: number;
-    log?: ApiProxyLog;
-}
-/**
- * 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 declare function createWorkspaceResolver(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): WorkspaceResolver;
-/**
- * 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 declare function createWorkspaceCatalogPort(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): ProjectListPort;
-export type WorkspaceDetailOutcome = {
-    outcome: 'found';
-    workspace: {
-        id: string;
-        title: string;
-        path: string | undefined;
-    };
-} | {
-    outcome: 'stale';
-} | {
-    outcome: 'failed';
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function readWorkspaceDetail(dsh: DshApiProxyFace, reference: string, options?: ApiProxyFaceOptions): Promise<WorkspaceDetailOutcome>;
-export type PromptOutcome = {
-    outcome: 'accepted';
-} | {
-    outcome: 'rejected';
-    reason: string;
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function promptSession(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-    prompt: string;
-    images?: ReadonlyArray<{
-        mediaType: string;
-        base64: string;
-    }>;
-}, options?: ApiProxyFaceOptions & {
-    rpcId?: string;
-}): Promise<PromptOutcome>;
-/**
- * Steer the session's active turn: `session.prompt` with `mode: 'steer'`,
- * carrying the same stable request-id discipline as the queue path.
- */
-export declare function steerSession(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-    prompt: string;
-}, options?: ApiProxyFaceOptions & {
-    rpcId?: string;
-}): Promise<PromptOutcome>;
-export type CreateSessionOutcome = {
-    outcome: 'completed';
-    sessionId: string;
-} | {
-    outcome: 'rejected';
-    reason: string;
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function createSessionViaProxy(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-    workspaceId: string;
-}, options?: ApiProxyFaceOptions): Promise<CreateSessionOutcome>;
-/** The durable Session-id baseline reconciliation reconciles against. */
-export type SessionIdListOutcome = {
-    outcome: 'completed';
-    ids: string[];
-} | {
-    outcome: 'failed';
-} | {
-    outcome: 'unknown';
-};
-/** List durable Session ids (`session.list`, v1 returns everything). */
-export declare function listSessionIds(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): Promise<SessionIdListOutcome>;
-/** A list row narrowed to what the /session resume surface renders. */
-export interface SessionResumeRow {
-    sessionId: string;
-    title: string | undefined;
-    updatedAt: number;
-    running: boolean;
-    blank: boolean;
-    cwd: string | undefined;
-    origin: 'subagent' | undefined;
-}
-export type SessionSummariesOutcome = {
-    outcome: 'completed';
-    sessions: SessionResumeRow[];
-} | {
-    outcome: 'failed';
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function listSessionSummaries(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): Promise<SessionSummariesOutcome>;
-export type CancelOutcome = {
-    outcome: 'accepted';
-} | {
-    outcome: 'rejected';
-    reason: string;
-} | {
-    outcome: 'unknown';
-};
-/** Cancel the session's active turn (`session.cancel`); DSH preserves the pending inbox. */
-export declare function cancelSessionViaProxy(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-}, options?: ApiProxyFaceOptions): Promise<CancelOutcome>;
-export type QueueRemoveOutcome = {
-    outcome: 'accepted';
-} | {
-    outcome: 'rejected';
-    reason: string;
-} | {
-    outcome: 'unknown';
-};
-/** Remove one pending inbox item (`session.updateQueue`, action remove). */
-export declare function removeQueueItemViaProxy(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-    itemId: string;
-}, options?: ApiProxyFaceOptions): Promise<QueueRemoveOutcome>;
-/** The carrier verdict apiProxy.respond resolves with (RpcReceipt). */
-export type RespondReceipt = {
-    accepted: true;
-} | {
-    accepted: false;
-    reason: 'not-pending' | 'bad-response';
-} | {
-    accepted: unknown;
-};
-export type RespondOutcome = {
-    outcome: 'confirmed';
-} | {
-    outcome: 'rejected';
-    reason: string;
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function createClientRespondPort(dsh: {
-    respond(message: unknown): Promise<unknown>;
-}, options?: ApiProxyFaceOptions): {
-    respond(rpcId: string, value: unknown): Promise<RespondOutcome>;
-};
-export type SessionModelsOutcome = {
-    outcome: 'completed';
-    models: SessionModelsShape;
-} | {
-    outcome: 'failed';
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function sessionModels(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-}, options?: ApiProxyFaceOptions): Promise<SessionModelsOutcome>;
-export type SelectModelOutcome = {
-    outcome: 'completed';
-    selected: ModelSelectionShape;
-} | {
-    outcome: 'rejected';
-    reason: string;
-} | {
-    outcome: 'unknown';
-};
-/**
- * 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 declare function selectSessionModel(dsh: DshApiProxyFace, request: {
-    sessionId: string;
-    provider: string;
-    model: string;
-    reasoningEffort?: string;
-}, options?: ApiProxyFaceOptions): Promise<SelectModelOutcome>;
-/**
- * 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 declare function createModelPort(dsh: DshApiProxyFace, options?: ApiProxyFaceOptions): DshModelPort;