@dsh-enhanced/coding-subscription-provider 0.1.0

package/lib/process.d.ts

@@ -0,0 +1,114 @@
+import type { CliInvocation } from './providers.js';
+export interface SpawnedProcess {
+    readonly pid?: number;
+    readonly stdout?: NodeJS.ReadableStream | null;
+    readonly stderr?: NodeJS.ReadableStream | null;
+    readonly exitCode?: number | null;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once(event: 'error' | 'close' | 'spawn', listener: (...args: any[]) => void): this;
+    removeListener?(event: 'error' | 'close' | 'spawn', listener: (...args: any[]) => void): this;
+    unref?(): void;
+}
+/** Whether the prompt argv was handed to the OS; the only safe basis for reasoning about replay. */
+export type PromptSubmissionState = 'not-submitted' | 'submitted' | 'unknown';
+/** Coarse lifecycle phase a failure was observed in, transport-scoped (auth lives in the adapter). */
+export type CliLifecyclePhase = 'spawn' | 'initialize' | 'prompt' | 'stream' | 'terminal' | 'child-close';
+/** Progress of the bounded child teardown attempt; `timed-out` means close was not proven. */
+export type TeardownState = 'not-started' | 'in-progress' | 'completed' | 'timed-out';
+/** Latency metrics with named clock origins so they stay comparable across providers. */
+export interface CliLifecycleMetrics {
+    /** Spawn to the first accepted (recognized) protocol event. */
+    readonly spawnToFirstEventMs?: number;
+    /** First recognized event to the first assistant text chunk. */
+    readonly eventToFirstTextMs?: number;
+    /** Spawn to the successful terminal event. */
+    readonly spawnToTerminalMs?: number;
+    /** Stop request to child-close teardown completion. */
+    readonly teardownDurationMs?: number;
+}
+/**
+ * Credential-free lifecycle facts for one CLI invocation. Diagnostic side-channel only:
+ * it never carries prompt text, stderr, tokens or argv, and never changes settlement.
+ */
+export interface ProviderFailureContext {
+    readonly phase: CliLifecyclePhase;
+    readonly promptSubmissionState: PromptSubmissionState;
+    readonly assistantTextObserved: boolean;
+    readonly teardownState: TeardownState;
+    readonly terminalReason?: string;
+    readonly exitCode?: number | null;
+    readonly signal?: NodeJS.Signals | null;
+    /** Explicit-clock-origin latency metrics; only measurable ones are present. */
+    readonly metrics?: CliLifecycleMetrics;
+}
+export type SpawnProcess = (command: string, args: readonly string[], options: {
+    cwd: string;
+    shell: false;
+    detached: boolean;
+    stdio: readonly ['ignore', 'pipe', 'pipe'];
+    env: NodeJS.ProcessEnv;
+}) => SpawnedProcess;
+export interface RunCliTextOptions {
+    readonly spawn?: SpawnProcess;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly killGraceMs?: number;
+    readonly maxLineBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxStderrBytes?: number;
+    /** Names only. Values are copied from process.env; callers cannot pass secret values. */
+    readonly extraEnvNames?: readonly string[];
+    readonly onDiagnostic?: (diagnostic: string) => void;
+    /** Receives credential-free lifecycle facts exactly once at settlement (success or failure); never affects the stream. */
+    readonly onSettled?: (context: ProviderFailureContext) => void;
+}
+export type CliProtocolFailureReason = 'MALFORMED_JSON' | 'NO_JSON_EVENTS' | 'UNRECOGNIZED_EVENTS' | 'NO_ASSISTANT_TEXT' | 'MISSING_SUCCESS_TERMINAL' | 'INVALID_TERMINAL' | 'REPORTED_FAILURE';
+/** A stable, credential-free protocol failure that the adapter can map. */
+export declare class CliProtocolError extends Error {
+    readonly provider: CliInvocation['provider'];
+    readonly reason: CliProtocolFailureReason;
+    readonly code = "CLI_PROTOCOL_ERROR";
+    constructor(provider: CliInvocation['provider'], reason: CliProtocolFailureReason);
+}
+export type CliSubscriptionAuthFailureReason = 'MISSING_AUTH_EVENT' | 'UNEXPECTED_AUTH_SOURCE';
+/** Cursor reported, or failed to report, the subscription login required by this route. */
+export declare class CliSubscriptionAuthError extends Error {
+    readonly provider: 'cursor';
+    readonly reason: CliSubscriptionAuthFailureReason;
+    readonly code = "CLI_SUBSCRIPTION_AUTH_ERROR";
+    constructor(provider: 'cursor', reason: CliSubscriptionAuthFailureReason);
+}
+/** The child really closed, but not with an unambiguous zero-code, no-signal exit. */
+export declare class CliProcessExitError extends Error {
+    readonly provider: CliInvocation['provider'];
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly code = "CLI_PROCESS_EXIT_ERROR";
+    constructor(provider: CliInvocation['provider'], exitCode: number | null, signal: NodeJS.Signals | null);
+}
+/** SIGKILL was requested, but ChildProcess never proved process/stdio closure. */
+export declare class CliTeardownTimeoutError extends Error {
+    readonly provider: CliInvocation['provider'];
+    readonly timeoutMs: number;
+    readonly code = "CLI_TEARDOWN_TIMEOUT";
+    constructor(provider: CliInvocation['provider'], timeoutMs: number);
+}
+/** Build an inherited environment that favours the local CLI's subscription login over API-key billing. */
+export declare function buildSubscriptionEnv(extraEnvNames?: readonly string[]): NodeJS.ProcessEnv;
+/**
+ * Starts one local, already-authenticated coding CLI and yields only assistant text.
+ * It never reads credential files or accepts credential values in config. An explicitly
+ * allowlisted environment name may still be forwarded unchanged to the official CLI.
+ * No shell is invoked.
+ */
+export declare function runCliText(invocation: CliInvocation, options?: RunCliTextOptions): AsyncIterable<string>;
+export interface ParsedEvent {
+    readonly text?: string;
+    /** True when text is a full aggregate that must not repeat prior deltas. */
+    readonly terminal: boolean;
+    readonly outcome?: 'success' | 'failure' | 'invalid';
+    readonly auth?: 'subscription' | 'other';
+}
+export declare function parseAssistantEvent(provider: CliInvocation['provider'], line: string): ParsedEvent | undefined;
+export declare function parseAssistantText(provider: CliInvocation['provider'], line: string): string | undefined;
+//# sourceMappingURL=process.d.ts.map

package/lib/process.d.ts.map

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