@phigon/observer 8.1.0 → 8.2.0

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

@@ -0,0 +1,73 @@
+/** One exact process lifetime: a PID alone is never an identity. */
+export type ExactProcess = Readonly<{
+    processId: number;
+    startedAt: Date;
+}>;
+export type TreeStopMode = "stop" | "kill";
+export type TreeStopOutcome = Readonly<{
+    outcome: "stale" | "exited" | "access_denied" | "graceful_unsupported" | "console_shared" | "self_target";
+}> | Readonly<{
+    outcome: "failed";
+    code: string;
+}> | Readonly<{
+    outcome: "dispatched";
+    rootRunning: boolean;
+    /** Verified descendants that were signalled. */
+    descendants: number;
+    /** Signalled descendants still running at the end of the wait. */
+    descendantsRunning: number;
+    /** Running descendants the OS would not let the observer stop. */
+    descendantsDenied: number;
+}>;
+/** Stops one exact process and the descendants it started. */
+export interface ProcessTreeControl {
+    stop(target: ExactProcess, mode: TreeStopMode): Promise<TreeStopOutcome>;
+}
+export type TreeStopReceipt = Readonly<{
+    state: "succeeded" | "failed" | "rejected";
+    code: string;
+    detail: string;
+    targetStillRunning: boolean;
+}>;
+/** Plain-language receipts; detail stays within the 256-character journal bound. */
+export declare function describeTreeOutcome(outcome: TreeStopOutcome, graceful: boolean): TreeStopReceipt;
+export declare function defaultProcessTreeControl(platform?: NodeJS.Platform): ProcessTreeControl;
+export type ProcessRow = Readonly<{
+    processId: number;
+    parentId: number;
+    startedAt: number;
+    zombie: boolean;
+}>;
+type Signal = "SIGTERM" | "SIGKILL" | 0;
+/**
+ * Linux and macOS: one process-table snapshot verifies the root's start time
+ * immediately before signalling, and finds descendants whose start is not
+ * earlier than their parent's (a stale parent PID cannot adopt them). The
+ * observer and everything it started are never members.
+ */
+export declare class UnixProcessTreeControl implements ProcessTreeControl {
+    #private;
+    constructor(options?: Readonly<{
+        list?: () => Promise<ReadonlyMap<number, ProcessRow>>;
+        signal?: (processId: number, signal: Signal) => void;
+        sleep?: (milliseconds: number) => Promise<void>;
+        observerProcessId?: number;
+        clock?: () => number;
+    }>);
+    stop(target: ExactProcess, mode: TreeStopMode): Promise<TreeStopOutcome>;
+}
+export declare function descendantsOf(table: ReadonlyMap<number, ProcessRow>, root: ProcessRow, observerProcessId: number): ProcessRow[];
+export declare function readUnixProcessTable(): Promise<ReadonlyMap<number, ProcessRow>>;
+export declare function parseUnixProcessTable(stdout: string): ReadonlyMap<number, ProcessRow>;
+/**
+ * Windows: the native helper holds a handle to every member while it works,
+ * so no member's PID can be recycled before the report is written.
+ */
+export declare class WindowsProcessTreeControl implements ProcessTreeControl {
+    #private;
+    constructor(run?: (args: readonly string[]) => Promise<string>);
+    stop(target: ExactProcess, mode: TreeStopMode): Promise<TreeStopOutcome>;
+}
+export declare function parseTreeReport(stdout: string): TreeStopOutcome;
+export {};
+//# sourceMappingURL=process-tree.d.ts.map

package/dist/src/process-tree.d.ts.map

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

package/dist/src/process-tree.js

@@ -0,0 +1,256 @@
+import { execFile } from "node:child_process";
+import { guardianRunnerPath } from "./guardian-native.js";
+/** Plain-language receipts; detail stays within the 256-character journal bound. */
+export function describeTreeOutcome(outcome, graceful) {
+    const receipt = (state, code, detail, targetStillRunning) => ({ state, code, detail, targetStillRunning });
+    switch (outcome.outcome) {
+        case "stale":
+            return receipt("rejected", "stale_target", "The process ID now belongs to a different process. Nothing was signalled.", false);
+        case "exited":
+            return receipt("rejected", "target_already_stopped", "The agent process had already exited. Nothing was signalled.", false);
+        case "self_target":
+            return receipt("rejected", "self_target_rejected", "Observer refuses to terminate its own process.", true);
+        case "access_denied":
+            return receipt("failed", "access_denied", "The operating system denied permission to stop this process. It may run as another user or as administrator. It is still running.", true);
+        case "graceful_unsupported":
+            return receipt("rejected", "graceful_stop_unsupported", "This agent has no window to close and no terminal to press Ctrl+C in, so a graceful stop is not possible. Nothing was sent. Use force stop instead.", true);
+        case "console_shared":
+            return receipt("rejected", "terminal_shared", "Other programs share this agent's terminal, and Ctrl+C would reach them too. Nothing was sent. Use force stop instead.", true);
+        case "failed":
+            return receipt("failed", "os_dispatch_failed", `The operating system could not complete the request (${outcome.code}). The agent may still be running.`, true);
+        case "dispatched": {
+            if (outcome.rootRunning) {
+                return receipt("failed", "process_still_running", graceful
+                    ? "The stop request was sent, but the agent is still running after 5 seconds. It was not escalated; use force stop if needed."
+                    : "Force stop was sent, but the agent still reports running.", true);
+            }
+            const remaining = outcome.descendantsRunning + outcome.descendantsDenied;
+            if (remaining > 0) {
+                return receipt("succeeded", "process_stopped_children_running", `The agent process exited, but ${remaining} of its child processes ${remaining === 1 ? "is" : "are"} still running.`, false);
+            }
+            return receipt("succeeded", "process_stopped", outcome.descendants > 0
+                ? `The agent process and its ${outcome.descendants} child ${outcome.descendants === 1 ? "process" : "processes"} exited.`
+                : "The agent process exited.", false);
+        }
+    }
+}
+export function defaultProcessTreeControl(platform = process.platform) {
+    return platform === "win32" ? new WindowsProcessTreeControl() : new UnixProcessTreeControl();
+}
+const maxDescendants = 1024;
+// Graceful stop gives the agent time to save state; force stop is immediate.
+const exitWait = { stop: 5_000, kill: 3_000 };
+/**
+ * Linux and macOS: one process-table snapshot verifies the root's start time
+ * immediately before signalling, and finds descendants whose start is not
+ * earlier than their parent's (a stale parent PID cannot adopt them). The
+ * observer and everything it started are never members.
+ */
+export class UnixProcessTreeControl {
+    #list;
+    #signal;
+    #sleep;
+    #observerProcessId;
+    #clock;
+    constructor(options = {}) {
+        this.#list = options.list ?? readUnixProcessTable;
+        this.#signal = options.signal ?? ((processId, signal) => { process.kill(processId, signal); });
+        this.#sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+        this.#observerProcessId = options.observerProcessId ?? process.pid;
+        this.#clock = options.clock ?? Date.now;
+    }
+    async stop(target, mode) {
+        if (target.processId === this.#observerProcessId)
+            return { outcome: "self_target" };
+        let table;
+        try {
+            table = await this.#list();
+        }
+        catch {
+            return { outcome: "failed", code: "process_table_unavailable" };
+        }
+        const root = table.get(target.processId);
+        if (root === undefined || root.zombie)
+            return { outcome: "exited" };
+        if (!sameStart(root.startedAt, target.startedAt.getTime()))
+            return { outcome: "stale" };
+        const descendants = descendantsOf(table, root, this.#observerProcessId);
+        const signal = mode === "stop" ? "SIGTERM" : "SIGKILL";
+        try {
+            this.#signal(root.processId, signal);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ESRCH")
+                return { outcome: "exited" };
+            if (code === "EPERM")
+                return { outcome: "access_denied" };
+            return { outcome: "failed", code: String(code ?? "unknown").slice(0, 32) };
+        }
+        const denied = new Set();
+        for (const descendant of descendants) {
+            try {
+                this.#signal(descendant.processId, signal);
+            }
+            catch (error) {
+                if (error.code === "EPERM")
+                    denied.add(descendant.processId);
+            }
+        }
+        const members = [root, ...descendants];
+        const deadline = this.#clock() + exitWait[mode];
+        while (this.#clock() < deadline && members.some((member) => this.#alive(member.processId))) {
+            await this.#sleep(100);
+        }
+        // A final snapshot tells an exited process from a zombie or a reused PID.
+        let after;
+        try {
+            after = await this.#list();
+        }
+        catch {
+            after = undefined;
+        }
+        const running = (member) => {
+            if (after === undefined)
+                return this.#alive(member.processId);
+            const current = after.get(member.processId);
+            return current !== undefined && !current.zombie && sameStart(current.startedAt, member.startedAt);
+        };
+        const stillRunning = descendants.filter(running);
+        return {
+            outcome: "dispatched",
+            rootRunning: running(root),
+            descendants: descendants.length,
+            // Counted separately so a receipt can say why a child survived.
+            descendantsRunning: stillRunning.filter((member) => !denied.has(member.processId)).length,
+            descendantsDenied: stillRunning.filter((member) => denied.has(member.processId)).length,
+        };
+    }
+    #alive(processId) {
+        try {
+            this.#signal(processId, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === "EPERM";
+        }
+    }
+}
+export function descendantsOf(table, root, observerProcessId) {
+    const children = new Map();
+    for (const row of table.values()) {
+        if (row.processId === row.parentId)
+            continue;
+        const siblings = children.get(row.parentId) ?? [];
+        siblings.push(row);
+        children.set(row.parentId, siblings);
+    }
+    const found = [];
+    const seen = new Set([root.processId]);
+    const queue = [root];
+    for (let index = 0; index < queue.length && found.length < maxDescendants; index++) {
+        const parent = queue[index];
+        for (const child of children.get(parent.processId) ?? []) {
+            if (seen.has(child.processId) || child.processId <= 1 || child.processId === observerProcessId)
+                continue;
+            seen.add(child.processId);
+            // ps start times have one-second resolution.
+            if (child.zombie || child.startedAt < parent.startedAt - 999)
+                continue;
+            found.push(child);
+            queue.push(child);
+            if (found.length >= maxDescendants)
+                break;
+        }
+    }
+    return found;
+}
+function sameStart(observed, expected) {
+    return Math.abs(observed - expected) < 1_000;
+}
+export async function readUnixProcessTable() {
+    const stdout = await new Promise((resolve, reject) => execFile("ps", ["-A", "-o", "pid=,ppid=,stat=,lstart="], { timeout: 3_000, maxBuffer: 8 << 20, encoding: "utf8", env: { ...process.env, LANG: "C", LC_ALL: "C" } }, (error, output) => error ? reject(error) : resolve(output)));
+    return parseUnixProcessTable(stdout);
+}
+export function parseUnixProcessTable(stdout) {
+    const table = new Map();
+    for (const line of stdout.split(/\r?\n/u)) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+\s+\S+\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s*$/u.exec(line);
+        if (match === null)
+            continue;
+        const processId = Number(match[1]);
+        const startedAt = Date.parse(match[4]);
+        if (!Number.isSafeInteger(processId) || processId < 1 || !Number.isFinite(startedAt))
+            continue;
+        table.set(processId, { processId, parentId: Number(match[2]), startedAt, zombie: match[3].startsWith("Z") });
+    }
+    return table;
+}
+/**
+ * Windows: the native helper holds a handle to every member while it works,
+ * so no member's PID can be recycled before the report is written.
+ */
+export class WindowsProcessTreeControl {
+    #run;
+    constructor(run) {
+        this.#run = run ?? runGuardianHelper;
+    }
+    async stop(target, mode) {
+        let stdout;
+        try {
+            stdout = await this.#run([
+                "--kill-pid", String(target.processId),
+                "--started-at", target.startedAt.toISOString(),
+                "--tree", ...(mode === "stop" ? ["--graceful"] : []),
+            ]);
+        }
+        catch (error) {
+            const code = error.killed === true
+                ? "helper_timeout"
+                : `helper_${String(error.code ?? "failed")}`;
+            return { outcome: "failed", code: code.slice(0, 32) };
+        }
+        return parseTreeReport(stdout);
+    }
+}
+function runGuardianHelper(args) {
+    return new Promise((resolve, reject) => execFile(guardianRunnerPath(), args, {
+        windowsHide: true, timeout: 20_000, maxBuffer: 16 << 10, encoding: "utf8",
+    }, (error, stdout) => error ? reject(error) : resolve(stdout)));
+}
+export function parseTreeReport(stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout.trim());
+    }
+    catch {
+        return { outcome: "failed", code: "helper_report_invalid" };
+    }
+    if (value === null || typeof value !== "object")
+        return { outcome: "failed", code: "helper_report_invalid" };
+    const report = value;
+    const count = (key) => {
+        const item = report[key];
+        return typeof item === "number" && Number.isSafeInteger(item) && item >= 0 ? item : 0;
+    };
+    switch (report["outcome"]) {
+        case "stale":
+        case "exited":
+        case "access_denied":
+        case "graceful_unsupported":
+        case "console_shared":
+        case "self_target":
+            return { outcome: report["outcome"] };
+        case "dispatched":
+            return {
+                outcome: "dispatched",
+                rootRunning: report["root_running"] === true,
+                descendants: count("descendants"),
+                descendantsRunning: count("descendants_running"),
+                descendantsDenied: count("descendants_denied"),
+            };
+        default:
+            return { outcome: "failed", code: `helper_${String(report["outcome"] ?? "invalid")}`.slice(0, 32) };
+    }
+}
+//# sourceMappingURL=process-tree.js.map

package/dist/src/process-tree.js.map

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

package/dist/src/server-authority.d.ts

@@ -0,0 +1,26 @@
+import * as tls from "node:tls";
+/**
+ * A company's own Phigon server (run by the Phigon app) signs its HTTPS
+ * certificate with an authority of its own. The pairing command carries
+ * that authority's SHA-256 fingerprint; pairing pins it here, and every
+ * later HTTPS and gRPC connection trusts it.
+ */
+export declare const SERVER_AUTHORITY_FILE = "server-ca.pem";
+export declare function serverAuthorityPath(dataDirectory: string): string;
+/** Reads `--server-ca-sha256`: 64 hex characters, with or without colons. */
+export declare function parseAuthorityFingerprint(value: string): string;
+/** Adds an authority to the ones this process trusts for HTTPS and gRPC. */
+export declare function trustAuthority(pem: string): void;
+/** Trusts the authority saved when this computer paired, and returns its file. */
+export declare function trustSavedAuthority(dataDirectory: string): string | undefined;
+export declare function forgetServerAuthority(dataDirectory: string): Promise<void>;
+type Connect = (options: tls.ConnectionOptions, listener: () => void) => tls.TLSSocket;
+/**
+ * Finds the certificate in the server's chain whose SHA-256 matches the
+ * pinned fingerprint, saves it and trusts it. Nothing is sent to the server
+ * on this connection; the requests that follow are verified normally,
+ * including the server's name, against the pinned authority.
+ */
+export declare function pinServerAuthority(url: URL, fingerprint: string, dataDirectory: string, connect?: Connect): Promise<string>;
+export {};
+//# sourceMappingURL=server-authority.d.ts.map

package/dist/src/server-authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-authority.d.ts","sourceRoot":"","sources":["../../src/server-authority.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAIrD,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAQhD;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7E;AAED,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhF;AAED,KAAK,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,iBAAiB,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,GAAG,CAAC,SAAS,CAAC;AAEvF;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,GAAG,EACR,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,OAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/src/server-authority.js

@@ -0,0 +1,102 @@
+import { createHash, X509Certificate } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { rm, writeFile } from "node:fs/promises";
+import { isIP } from "node:net";
+import { join } from "node:path";
+import * as tls from "node:tls";
+/**
+ * A company's own Phigon server (run by the Phigon app) signs its HTTPS
+ * certificate with an authority of its own. The pairing command carries
+ * that authority's SHA-256 fingerprint; pairing pins it here, and every
+ * later HTTPS and gRPC connection trusts it.
+ */
+export const SERVER_AUTHORITY_FILE = "server-ca.pem";
+const FINGERPRINT = /^[0-9a-f]{64}$/u;
+export function serverAuthorityPath(dataDirectory) {
+    return join(dataDirectory, SERVER_AUTHORITY_FILE);
+}
+/** Reads `--server-ca-sha256`: 64 hex characters, with or without colons. */
+export function parseAuthorityFingerprint(value) {
+    const normalized = value.trim().toLowerCase().replace(/:/gu, "");
+    if (!FINGERPRINT.test(normalized)) {
+        throw new Error("--server-ca-sha256 must be the 64-character fingerprint from the Connect machine dialog.");
+    }
+    return normalized;
+}
+/** Adds an authority to the ones this process trusts for HTTPS and gRPC. */
+export function trustAuthority(pem) {
+    if (typeof tls.setDefaultCACertificates !== "function" || typeof tls.getCACertificates !== "function") {
+        throw new Error("Connecting to a company's own Phigon server needs Node.js 24.5 or newer. Update Node.js and try again.");
+    }
+    const current = tls.getCACertificates("default");
+    if (!current.some((certificate) => sameCertificate(certificate, pem))) {
+        tls.setDefaultCACertificates([...current, pem]);
+    }
+}
+/** Trusts the authority saved when this computer paired, and returns its file. */
+export function trustSavedAuthority(dataDirectory) {
+    const file = serverAuthorityPath(dataDirectory);
+    if (!existsSync(file))
+        return undefined;
+    trustAuthority(readFileSync(file, "utf8"));
+    return file;
+}
+export async function forgetServerAuthority(dataDirectory) {
+    await rm(serverAuthorityPath(dataDirectory), { force: true });
+}
+/**
+ * Finds the certificate in the server's chain whose SHA-256 matches the
+ * pinned fingerprint, saves it and trusts it. Nothing is sent to the server
+ * on this connection; the requests that follow are verified normally,
+ * including the server's name, against the pinned authority.
+ */
+export async function pinServerAuthority(url, fingerprint, dataDirectory, connect = tls.connect) {
+    if (url.protocol !== "https:") {
+        throw new Error("--server-ca-sha256 needs an https:// control plane URL.");
+    }
+    const chain = await peerChain(url, connect);
+    const match = chain.find((raw) => createHash("sha256").update(raw).digest("hex") === fingerprint);
+    if (match === undefined) {
+        throw new Error("The server's certificate does not match the fingerprint in the pairing command. Check that this computer is on the right network and that you copied the whole command.");
+    }
+    const pem = new X509Certificate(match).toString();
+    trustAuthority(pem);
+    const file = serverAuthorityPath(dataDirectory);
+    await writeFile(file, pem, { mode: 0o600 });
+    return file;
+}
+function peerChain(url, connect) {
+    const host = url.hostname.replace(/^\[|\]$/gu, "");
+    const port = Number(url.port || 443);
+    return new Promise((resolve, reject) => {
+        const socket = connect({
+            host,
+            port,
+            ...(isIP(host) ? {} : { servername: host }),
+            // Only to read the chain; the fingerprint decides what is trusted.
+            rejectUnauthorized: false,
+            timeout: 15_000,
+        }, () => {
+            const chain = [];
+            const seen = new Set();
+            let certificate = socket.getPeerCertificate(true);
+            while (certificate?.raw && !seen.has(certificate.fingerprint256)) {
+                seen.add(certificate.fingerprint256);
+                chain.push(certificate.raw);
+                certificate = certificate.issuerCertificate;
+            }
+            socket.end();
+            resolve(chain);
+        });
+        socket.once("error", (error) => reject(new Error(`Could not reach ${url.host}: ${error.message}`)));
+        socket.once("timeout", () => {
+            socket.destroy();
+            reject(new Error(`Connecting to ${url.host} timed out. Check that this computer can reach it on the network.`));
+        });
+    });
+}
+function sameCertificate(a, b) {
+    const strip = (pem) => pem.replace(/\s+/gu, "");
+    return strip(a) === strip(b);
+}
+//# sourceMappingURL=server-authority.js.map

package/dist/src/server-authority.js.map

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

package/dist/src/stream-client.d.ts

@@ -15,6 +15,8 @@ export type ObserverStreamMetrics = Readonly<{
     lastAcknowledgedSequence: bigint;
     queue: QueueMetrics;
 }>;
+/** What the stream needs from the action executor. */
+export type ActionExecutor = Pick<AgentActionExecutor, "execute" | "manifest">;
 export type StreamClientOptions = Readonly<{
     config: ObserverConfig;
     credentialStore?: CredentialStore;
@@ -25,7 +27,7 @@ export type StreamClientOptions = Readonly<{
     onPolicy?: (policy: CollectionPolicy) => void;
     onCursorReset?: (acknowledgedSequence: bigint, allocationSequence: bigint) => void;
     onAcknowledgement?: (sequence: bigint) => void | Promise<void>;
-    actionExecutor?: AgentActionExecutor;
+    actionExecutor?: ActionExecutor;
     onHistorySync?: (command: HistorySyncCommand) => Promise<HistorySyncResult>;
     handshakeTimeoutMs?: number;
     responseTimeoutMs?: number;

package/dist/src/stream-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-client.d.ts","sourceRoot":"","sources":["../../src/stream-client.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAOhF,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,0CAA0C,CAAC;AAWlD,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,oCAAoC,CAAC;AAK5C,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,KAAK,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAOtE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE,YAAY,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,KAAK,CAAC,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CACd,oBAAoB,EAAE,MAAM,EAC5B,kBAAkB,EAAE,MAAM,KACvB,IAAI,CAAC;IACV,iBAAiB,CAAC,EAAE,CAClB,QAAQ,EAAE,MAAM,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,qBAAa,oBAAoB;;gBA8BnB,OAAO,EAAE,mBAAmB;IA2BxC,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAWzD,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;IAK1C,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBrD,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB7C,OAAO,IAAI,qBAAqB;CAujBjC;AA0FD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,gBAAgB,GACvB,aAAa,CA2If"}
+{"version":3,"file":"stream-client.d.ts","sourceRoot":"","sources":["../../src/stream-client.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAOhF,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,0CAA0C,CAAC;AAWlD,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,oCAAoC,CAAC;AAK5C,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,KAAK,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAOtE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE,YAAY,CAAC;CACrB,CAAC,CAAC;AAEH,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC;AAE/E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,KAAK,CAAC,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CACd,oBAAoB,EAAE,MAAM,EAC5B,kBAAkB,EAAE,MAAM,KACvB,IAAI,CAAC;IACV,iBAAiB,CAAC,EAAE,CAClB,QAAQ,EAAE,MAAM,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,qBAAa,oBAAoB;;gBA+BnB,OAAO,EAAE,mBAAmB;IA2BxC,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAWzD,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;IAK1C,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBrD,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B7C,OAAO,IAAI,qBAAqB;CAulBjC;AA0FD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,gBAAgB,GACvB,aAAa,CA2If"}