engineering-behavior-observatory 0.2.1

package/dist/src/process-protocol.d.ts

@@ -0,0 +1,245 @@
+import { type SpawnOptions } from "node:child_process";
+export type ProtocolIdentity = string | number | null;
+export type ProtocolObservationKind = "frame" | "request" | "response" | "notification" | "completion" | "capability" | "error" | "process";
+export type ProtocolObservation = {
+    schemaVersion: "ebo.protocol-observation/v1";
+    sequence: number;
+    observedAt: string;
+    kind: ProtocolObservationKind;
+    source: string;
+    stream?: "stdout" | "stderr";
+    method?: string;
+    id?: ProtocolIdentity;
+    sourceIdentity?: string;
+    raw?: string;
+    parseError?: string;
+    payload?: unknown;
+    evidence?: unknown;
+    status?: string;
+    capability?: string;
+};
+export type ProtocolObservationInput = {
+    source: string;
+    method: string;
+    id?: ProtocolIdentity;
+    sourceIdentity?: string;
+    payload?: unknown;
+    observedAt?: string;
+};
+export type ProtocolCompletionEvidence = {
+    source: string;
+    status: string;
+    evidence: unknown;
+    method?: string;
+    sourceIdentity?: string;
+    observedAt?: string;
+};
+export type ProtocolCapability = {
+    source: string;
+    name: string;
+    status: "available" | "unsupported" | "missing" | "not-checked";
+    details?: unknown;
+    observedAt?: string;
+};
+export type JsonlEvidenceWriterOptions = {
+    maxLineBytes?: number;
+    fsync?: boolean;
+    exclusive?: boolean;
+};
+declare const INTERNAL_RECORDER_TOKEN: unique symbol;
+/**
+ * Appends JSON records one line at a time and optionally fsyncs each append.
+ * A queued writer keeps records ordered even when protocol callbacks overlap.
+ */
+export declare class JsonlEvidenceWriter {
+    readonly path: string;
+    private readonly maxLineBytes;
+    private readonly shouldFsync;
+    private readonly exclusive;
+    private handle;
+    private queue;
+    private closed;
+    private poisoned;
+    private claimed;
+    private preparedExclusive;
+    private hasWrites;
+    private claimLockFd;
+    private claimLockPath;
+    private claimCanonicalPath;
+    private _count;
+    constructor(path: string, options?: JsonlEvidenceWriterOptions);
+    get count(): number;
+    get maxRecordBytes(): number;
+    append(record: unknown, token?: typeof INTERNAL_RECORDER_TOKEN): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    ensureOpen(): Promise<void>;
+    claim(token?: typeof INTERNAL_RECORDER_TOKEN): number;
+    releaseClaim(token?: typeof INTERNAL_RECORDER_TOKEN): void;
+    private releaseClaimNow;
+    private openHandle;
+    private prepareForClaim;
+}
+export declare function openJsonlEvidenceWriter(path: string, options?: JsonlEvidenceWriterOptions): Promise<JsonlEvidenceWriter>;
+export type BoundedDiagnostic = {
+    bytes: Buffer;
+    text: string;
+    sizeBytes: number;
+    truncated: boolean;
+    maxBytes: number;
+};
+/** Keeps a bounded diagnostic prefix while continuing to drain the stream. */
+export declare class BoundedDiagnosticCapture {
+    readonly maxBytes: number;
+    private readonly chunks;
+    private _sizeBytes;
+    private _truncated;
+    private keptBytes;
+    constructor(maxBytes?: number);
+    write(chunk: Uint8Array): void;
+    get sizeBytes(): number;
+    get truncated(): boolean;
+    result(): BoundedDiagnostic;
+}
+export type ProtocolProcessOptions = {
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    source: string;
+    evidencePath?: string;
+    writer?: JsonlEvidenceWriter;
+    stderrPath?: string;
+    maxStderrBytes?: number;
+    maxLineBytes?: number;
+    shutdownGraceMs?: number;
+    killGraceMs?: number;
+    maxInMemoryObservations?: number;
+    signal?: AbortSignal;
+    now?: () => string;
+    spawnOptions?: Omit<SpawnOptions, "stdio" | "env" | "cwd" | "signal" | "timeout" | "killSignal">;
+    onStderr?: (chunk: Uint8Array, final: boolean, recorder: ProtocolEvidenceRecorder) => void | Promise<void>;
+    onFrame?: (payload: unknown, recorder: ProtocolEvidenceRecorder) => void | Promise<void>;
+};
+export type ProcessTermination = "natural" | "shutdown" | "interrupted" | "malformed" | "recorder-error";
+export type ProtocolProcessResult = {
+    status: "completed" | "failed" | "malformed" | "interrupted" | "shutdown";
+    partial: boolean;
+    protocolOnly: true;
+    launch: {
+        command: string;
+        args: string[];
+        cwd: string;
+        pid: number | null;
+        startedAt: string;
+        endedAt: string;
+        exitCode: number | null;
+        signal: NodeJS.Signals | null;
+    };
+    termination: ProcessTermination;
+    stdoutFrames: number;
+    stderr: BoundedDiagnostic;
+    error?: string;
+    recorderError?: string;
+    protocolError?: {
+        line: number;
+        message: string;
+        raw?: string;
+    };
+    evidencePath?: string;
+    stderrPath?: string;
+    droppedObservations: number;
+    observations: ProtocolObservation[];
+};
+export declare class ProtocolEvidenceRecorder {
+    private readonly writer;
+    private readonly source;
+    private readonly now;
+    private sequence;
+    private readonly records;
+    private readonly maxInMemoryObservations;
+    private queue;
+    private fenced;
+    private _dropped;
+    constructor(writer: JsonlEvidenceWriter, source: string, now?: () => string, maxInMemoryObservations?: number);
+    get observations(): readonly ProtocolObservation[];
+    get droppedObservations(): number;
+    /** Prevents late observer callbacks from appending after process finalization. */
+    fence(): void;
+    recordFrame(payload: unknown, observedAt?: string, raw?: string, parseError?: string): Promise<ProtocolObservation>;
+    recordRequest(input: ProtocolObservationInput): Promise<ProtocolObservation>;
+    recordResponse(input: ProtocolObservationInput): Promise<ProtocolObservation>;
+    recordNotification(input: ProtocolObservationInput): Promise<ProtocolObservation>;
+    recordCompletion(input: ProtocolCompletionEvidence): Promise<ProtocolObservation>;
+    recordCapability(input: ProtocolCapability): Promise<ProtocolObservation>;
+    recordError(message: string, evidence?: unknown, token?: typeof INTERNAL_RECORDER_TOKEN): Promise<ProtocolObservation>;
+    recordProcess(status: string, evidence?: unknown, token?: typeof INTERNAL_RECORDER_TOKEN): Promise<ProtocolObservation>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private record;
+}
+export declare class ProtocolProcess {
+    private readonly options;
+    private readonly child;
+    private readonly recorder;
+    private readonly stderrCapture;
+    private readonly stdoutLineLimit;
+    private readonly shutdownGraceMs;
+    private readonly killGraceMs;
+    private readonly maxInMemoryObservations;
+    private readonly writer;
+    private readonly now;
+    private readonly command;
+    private readonly detached;
+    private readonly ownsWriter;
+    private readonly evidencePath?;
+    private readonly stderrPath?;
+    private stderrPersisted;
+    private readonly startedAt;
+    private readonly cwd;
+    private readonly args;
+    private readonly onFrame;
+    private nextLineNumber;
+    private frameCount;
+    private lineQueue;
+    private pendingLineParts;
+    private pendingLineBytes;
+    private protocolFailureQueued;
+    private readonly waitPromise;
+    private termination;
+    private protocolError;
+    private recorderError;
+    private childError;
+    private signalQueue;
+    private abortListener;
+    private closeObserved;
+    private finishStarted;
+    private resolveResult;
+    constructor(options: ProtocolProcessOptions);
+    get pid(): number | undefined;
+    get stdin(): NodeJS.WritableStream;
+    get evidence(): ProtocolEvidenceRecorder;
+    wait(): Promise<ProtocolProcessResult>;
+    shutdown(): Promise<ProtocolProcessResult>;
+    interrupt(graceMs?: number, killGraceMs?: number): Promise<ProtocolProcessResult>;
+    private attachStreams;
+    private consumeStdout;
+    private appendPendingLine;
+    private queuePendingLine;
+    private flushPendingLine;
+    private processLine;
+    private failProtocol;
+    private failRecorder;
+    private setTermination;
+    private sendSignal;
+    private sendSignalNow;
+    private waitForClose;
+    private beginFinish;
+    private forceFinish;
+    private finish;
+}
+export declare function spawnProtocolProcess(options: ProtocolProcessOptions): ProtocolProcess;
+export declare function runProtocolProcess(options: ProtocolProcessOptions): Promise<ProtocolProcessResult>;
+/** Validate a retained protocol envelope against its physical JSONL line. */
+export declare function assertProtocolObservation(value: unknown, lineNumber: number): asserts value is ProtocolObservation;
+export {};