backend.ts

import type { AgentSettings, Submission } from './protocol';

export type BackendOwnership = 'managed' | 'adopted';
export type BackendCapabilities = Record<string, boolean>;
export interface RuntimeMetadata {
    rPid?: number;
    rVersion?: string;
    runtimeSessionId?: string;
    rPath?: string;
    libraryPaths?: string[];
}
export type InspectionMethod =
    | 'workspace'
    | 'workspace_children'
    | 'workspace_view'
    | 'listview_navigate'
    | 'listview_view'
    | 'hover'
    | 'completion'
    | 'dataview_init'
    | 'dataview_page'
    | 'dataview_dispose';
export interface InspectionRequest {
    method: InspectionMethod;
    params: Record<string, unknown>;
    timeout?: number;
}
export interface InputReply {
    value: string;
}
export interface ClientReply {
    result?: unknown;
    error?: string;
}
export interface ResizePlotRequest {
    device: string;
    plot: number;
    width: number;
    height: number;
}

/** Decoded application events; no provider sockets, wire packets or RPC identifiers. */
export type BackendEvent = (
    | { type: 'ready'; metadata: RuntimeMetadata; capabilities: BackendCapabilities }
    | { type: 'metadata'; metadata: RuntimeMetadata }
    | { type: 'started' }
    | { type: 'finished'; state: 'success' | 'error' | 'interrupted' }
    | { type: 'stream'; text: string; channel: string; external?: boolean }
    | { type: 'condition' | 'input' | 'display'; data: Record<string, unknown> }
    | { type: 'workspaceChanged' }
    | { type: 'notification' | 'viewer'; method: string; params: Record<string, unknown> }
    | { type: 'clientRequest'; id: string; method: string; params: unknown }
    | { type: 'clientRequestExpired'; id: string }
    | { type: 'external'; code: string; success: boolean }
    | { type: 'warning' | 'error' | 'truncated'; message: string }
    | { type: 'provider'; data: Record<string, unknown> }
    | { type: 'unavailable'; message: string }
    | { type: 'exit'; code?: number | null; signal?: string | null }
) & { executionId?: string };

export interface SessionBackend {
    readonly ownership: BackendOwnership;
    readonly capabilities: BackendCapabilities;
    onEvent(listener: (event: BackendEvent) => void): () => void;
    start(): Promise<void>;
    /** Acknowledges transport only. Started/finished events establish evaluation outcome. */
    dispatch(submission: Submission): Promise<void>;
    inspect(request: InspectionRequest): Promise<unknown>;
    replyInput(reply: InputReply): Promise<void>;
    replyClientRequest(id: string, reply: ClientReply): Promise<void>;
    interrupt(): Promise<void>;
    /** Explicit user Stop, including for an adopted runtime. Resolves after confirmed exit. */
    stop(options?: { force?: boolean }): Promise<void>;
    resizePlot?(request: ResizePlotRequest): Promise<void>;
    /** Bounded, idempotent cleanup. Must not kill an adopted runtime. */
    dispose(): Promise<void>;
}

export type BackendFactory = (settings: AgentSettings) => SessionBackend;

export function inspectionMethod(value: unknown): InspectionMethod {
    if (
        ![
            'workspace',
            'workspace_children',
            'workspace_view',
            'listview_navigate',
            'listview_view',
            'hover',
            'completion',
            'dataview_init',
            'dataview_page',
            'dataview_dispose',
        ].includes(String(value))
    ) {
        throw new Error('Unsupported inspection method');
    }
    return value as InspectionMethod;
}