@allin-ai/agent-client 0.1.0

package/dist/control.js

@@ -0,0 +1,217 @@
+import { lstat, mkdir, unlink } from "node:fs/promises";
+import { createConnection, createServer, } from "node:net";
+import path from "node:path";
+import { resolveAgentControlEndpoint } from "./paths.js";
+const controlFs = { mkdir, lstat, unlink };
+function absent(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function controlError(error) {
+    return error instanceof Error ? error.message : "Control request failed";
+}
+function parseRequest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("Control request must be an object");
+    }
+    const input = value;
+    if (typeof input.id !== "string" || !input.id)
+        throw new TypeError("Control request id is required");
+    if (input.method === "health")
+        return { id: input.id, method: "health" };
+    if (input.method === "status")
+        return { id: input.id, method: "status" };
+    if (input.method === "sync")
+        return { id: input.id, method: "sync" };
+    if (input.method === "approve" &&
+        typeof input.executionId === "string" &&
+        input.executionId) {
+        return { id: input.id, method: "approve", executionId: input.executionId };
+    }
+    throw new TypeError("Unsupported control request");
+}
+function defaultEndpointActive(endpoint) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ path: endpoint });
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve(false);
+        }, 250);
+        socket.once("connect", () => {
+            clearTimeout(timeout);
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => {
+            clearTimeout(timeout);
+            resolve(false);
+        });
+    });
+}
+async function prepareUnixSocket(endpoint, fs, endpointActive) {
+    await fs.mkdir(path.dirname(endpoint), { recursive: true });
+    try {
+        const entry = await fs.lstat(endpoint);
+        if (!entry.isSocket()) {
+            throw new Error(`Refusing to remove non-socket control path: ${endpoint}`);
+        }
+    }
+    catch (error) {
+        if (absent(error))
+            return;
+        throw error;
+    }
+    if (await endpointActive(endpoint)) {
+        throw new Error(`Agent control socket is already active: ${endpoint}`);
+    }
+    await fs.unlink(endpoint);
+}
+function listen(server, endpoint) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        // Endpoint is always a Unix-domain socket or a Windows named pipe.
+        server.listen(endpoint);
+    });
+}
+function close(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+}
+/**
+ * Start the local control server. Its API deliberately has no host/port field,
+ * preventing an unauthenticated TCP listener from being configured here.
+ */
+export async function startAgentControlServer(options) {
+    const platform = options.platform ?? process.platform;
+    const endpoint = options.socketPath ??
+        (options.paths
+            ? resolveAgentControlEndpoint(options.paths, platform)
+            : undefined);
+    if (!endpoint)
+        throw new TypeError("socketPath or paths is required for agent control");
+    if (platform !== "win32") {
+        await prepareUnixSocket(endpoint, options.fileSystem ?? controlFs, options.endpointActive ?? defaultEndpointActive);
+    }
+    const server = (options.serverFactory ?? createServer)(async (socket) => {
+        let pending = "";
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+            pending += chunk;
+            if (pending.length > 64 * 1024) {
+                socket.destroy(new Error("Control request is too large"));
+                return;
+            }
+            let newline = pending.indexOf("\n");
+            while (newline >= 0) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                void handleLine(options.control, socket, line);
+                newline = pending.indexOf("\n");
+            }
+        });
+    });
+    await listen(server, endpoint);
+    return { endpoint, close: () => close(server) };
+}
+async function handleLine(control, socket, line) {
+    let response;
+    let request;
+    try {
+        request = parseRequest(JSON.parse(line));
+        if (request.method === "health") {
+            response = { id: request.id, ok: true, result: await control.health() };
+        }
+        else if (request.method === "status") {
+            response = { id: request.id, ok: true, result: await control.status() };
+        }
+        else if (request.method === "sync") {
+            if (!control.sync)
+                throw new Error("Local Agent Client does not support sync");
+            await control.sync();
+            response = { id: request.id, ok: true };
+        }
+        else {
+            await control.approve(request.executionId);
+            response = { id: request.id, ok: true };
+        }
+    }
+    catch (error) {
+        response = {
+            id: request?.id ?? "unknown",
+            ok: false,
+            error: controlError(error),
+        };
+    }
+    socket.write(`${JSON.stringify(response)}\n`);
+}
+function sendControlRequest(endpoint, request, options) {
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    return new Promise((resolve, reject) => {
+        const socket = (options.connect ??
+            ((pathToSocket) => createConnection({ path: pathToSocket })))(endpoint);
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            reject(new Error("Timed out waiting for local agent control response"));
+        }, options.timeoutMs ?? 5_000);
+        let pending = "";
+        socket.setEncoding("utf8");
+        socket.once("connect", () => {
+            socket.write(`${JSON.stringify({ id, ...request })}\n`);
+        });
+        socket.on("data", (chunk) => {
+            pending += chunk;
+            const newline = pending.indexOf("\n");
+            if (newline < 0)
+                return;
+            clearTimeout(timeout);
+            socket.end();
+            try {
+                const response = JSON.parse(pending.slice(0, newline));
+                if (response.id !== id)
+                    throw new Error("Mismatched local control response");
+                if (!response.ok)
+                    throw new Error(response.error ?? "Local control request failed");
+                resolve(response.result);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        socket.once("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+/** Client seam used by the future CLI/Desktop without opening a network port. */
+export function createAgentControlClient(endpoint, options = {}) {
+    return {
+        async health() {
+            return (await sendControlRequest(endpoint, { method: "health" }, options));
+        },
+        async status() {
+            return (await sendControlRequest(endpoint, { method: "status" }, options));
+        },
+        async approve(executionId) {
+            if (!executionId.trim())
+                throw new TypeError("executionId must be a nonempty string");
+            await sendControlRequest(endpoint, { method: "approve", executionId }, options);
+        },
+        async sync() {
+            await sendControlRequest(endpoint, { method: "sync" }, options);
+        },
+    };
+}
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

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

package/dist/credentials.d.ts

@@ -0,0 +1,44 @@
+import { type AgentPaths } from "./paths.js";
+export type CredentialStore = {
+    load(clientId: string): Promise<string | null>;
+    save(clientId: string, token: string): Promise<void>;
+    clear(clientId: string): Promise<void>;
+};
+export type SecurityCommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/** Process port: tests can verify the exact security invocation without spawning a process. */
+export type SecurityExecutor = (file: string, args: string[]) => Promise<SecurityCommandResult>;
+export type CredentialFileSystem = {
+    mkdir(dir: string, options: {
+        recursive: true;
+    }): Promise<string | undefined>;
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    writeFile(file: string, data: string, options: {
+        encoding: "utf8";
+        mode: number;
+        flag: "wx";
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(file: string): Promise<void>;
+    chmod(file: string, mode: number): Promise<void>;
+    stat(file: string): Promise<{
+        mode: number;
+    }>;
+};
+export type CredentialStoreOptions = {
+    homeDir?: string;
+    paths?: Pick<AgentPaths, "credentialsRoot">;
+    platform?: NodeJS.Platform;
+    executor?: SecurityExecutor;
+    fs?: CredentialFileSystem;
+    serviceName?: string;
+};
+/**
+ * Keychain is preferred on macOS. A mode-0600, atomic local file is used only
+ * when Keychain itself is unavailable (or on a platform without Keychain).
+ */
+export declare function createCredentialStore(options?: CredentialStoreOptions): CredentialStore;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAWA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,+FAA+F;AAC/F,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAEpC,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,GACtD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,EAAE,CAAC,EAAE,oBAAoB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AA8OF;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,sBAA2B,GACnC,eAAe,CASjB"}

package/dist/credentials.js

@@ -0,0 +1,229 @@
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { resolveAgentPaths } from "./paths.js";
+const credentialFs = {
+    mkdir,
+    readFile,
+    writeFile,
+    rename,
+    unlink,
+    chmod,
+    stat,
+};
+const KEYCHAIN_SERVICE = "allinai-agent";
+function credentialFileName(clientId) {
+    if (!clientId.trim())
+        throw new TypeError("clientId must be a nonempty string");
+    return `${encodeURIComponent(clientId)}.token`;
+}
+function credentialFilePath(root, clientId) {
+    return path.join(root, credentialFileName(clientId));
+}
+function missingFile(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function keychainUnavailable(error, platform) {
+    if (platform !== "darwin")
+        return true;
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT") {
+        return true;
+    }
+    const message = typeof error === "object" && error !== null && "stderr" in error
+        ? `${String(error.stdout ?? "")} ${String(error.stderr ?? "")}`.toLowerCase()
+        : messageOf(error).toLowerCase();
+    return (message.includes("keychain is not available") ||
+        message.includes("no keychain"));
+}
+function keychainItemMissing(result) {
+    const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    return text.includes("could not be found") || text.includes("item not found");
+}
+function defaultSecurityExecutor() {
+    return async (file, args) => {
+        const { execFile } = await import("node:child_process");
+        return await new Promise((resolve, reject) => {
+            execFile(file, args, { shell: false }, (error, stdout, stderr) => {
+                if (error && typeof error.code !== "number") {
+                    reject(error);
+                    return;
+                }
+                resolve({
+                    code: typeof error?.code === "number"
+                        ? error.code
+                        : 0,
+                    stdout,
+                    stderr,
+                });
+            });
+        });
+    };
+}
+async function deleteIfPresent(fs, file) {
+    try {
+        await fs.unlink(file);
+    }
+    catch (error) {
+        if (!missingFile(error))
+            throw error;
+    }
+}
+class FileCredentialStore {
+    root;
+    fs;
+    constructor(root, fs) {
+        this.root = root;
+        this.fs = fs;
+    }
+    async load(clientId) {
+        const file = credentialFilePath(this.root, clientId);
+        try {
+            const info = await this.fs.stat(file);
+            if ((info.mode & 0o077) !== 0) {
+                throw new Error(`Credential fallback file ${file} must have mode 0600`);
+            }
+            const token = (await this.fs.readFile(file, "utf8")).trim();
+            return token || null;
+        }
+        catch (error) {
+            if (missingFile(error))
+                return null;
+            throw error;
+        }
+    }
+    async save(clientId, token) {
+        if (!token.trim())
+            throw new TypeError("token must be a nonempty string");
+        await this.fs.mkdir(this.root, { recursive: true });
+        const file = credentialFilePath(this.root, clientId);
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            await this.fs.writeFile(temporary, token, {
+                encoding: "utf8",
+                mode: 0o600,
+                flag: "wx",
+            });
+            await this.fs.chmod(temporary, 0o600);
+            await this.fs.rename(temporary, file);
+            await this.fs.chmod(file, 0o600);
+        }
+        catch (error) {
+            await deleteIfPresent(this.fs, temporary);
+            throw error;
+        }
+    }
+    async clear(clientId) {
+        await deleteIfPresent(this.fs, credentialFilePath(this.root, clientId));
+    }
+}
+class KeychainCredentialStore {
+    platform;
+    executor;
+    serviceName;
+    fallback;
+    constructor(platform, executor, paths, fs, serviceName) {
+        this.platform = platform;
+        this.executor = executor;
+        this.serviceName = serviceName;
+        this.fallback = new FileCredentialStore(paths.credentialsRoot, fs);
+    }
+    async load(clientId) {
+        if (this.platform !== "darwin")
+            return this.fallback.load(clientId);
+        try {
+            const result = await this.executor("security", [
+                "find-generic-password",
+                "-a",
+                clientId,
+                "-s",
+                this.serviceName,
+                "-w",
+            ]);
+            if (result.code === 0)
+                return result.stdout.trim() || null;
+            // A functioning Keychain is authoritative. Do not silently prefer an
+            // old fallback file merely because this account has no Keychain item.
+            if (keychainItemMissing(result))
+                return null;
+            if (keychainUnavailable(result, this.platform))
+                return this.fallback.load(clientId);
+            throw new Error(`Keychain load failed: ${result.stderr || result.stdout || result.code}`);
+        }
+        catch (error) {
+            if (keychainUnavailable(error, this.platform))
+                return this.fallback.load(clientId);
+            throw error;
+        }
+    }
+    async save(clientId, token) {
+        if (!token.trim())
+            throw new TypeError("token must be a nonempty string");
+        if (this.platform !== "darwin")
+            return this.fallback.save(clientId, token);
+        try {
+            const result = await this.executor("security", [
+                "add-generic-password",
+                "-U",
+                "-a",
+                clientId,
+                "-s",
+                this.serviceName,
+                "-w",
+                token,
+            ]);
+            if (result.code === 0)
+                return;
+            if (keychainUnavailable(result, this.platform))
+                return this.fallback.save(clientId, token);
+            throw new Error(`Keychain save failed: ${result.stderr || result.stdout || result.code}`);
+        }
+        catch (error) {
+            if (keychainUnavailable(error, this.platform))
+                return this.fallback.save(clientId, token);
+            throw error;
+        }
+    }
+    async clear(clientId) {
+        if (this.platform !== "darwin")
+            return this.fallback.clear(clientId);
+        try {
+            const result = await this.executor("security", [
+                "delete-generic-password",
+                "-a",
+                clientId,
+                "-s",
+                this.serviceName,
+            ]);
+            if (result.code === 0 || keychainItemMissing(result)) {
+                await this.fallback.clear(clientId);
+                return;
+            }
+            if (keychainUnavailable(result, this.platform))
+                return this.fallback.clear(clientId);
+            throw new Error(`Keychain clear failed: ${result.stderr || result.stdout || result.code}`);
+        }
+        catch (error) {
+            if (keychainUnavailable(error, this.platform))
+                return this.fallback.clear(clientId);
+            throw error;
+        }
+    }
+}
+/**
+ * Keychain is preferred on macOS. A mode-0600, atomic local file is used only
+ * when Keychain itself is unavailable (or on a platform without Keychain).
+ */
+export function createCredentialStore(options = {}) {
+    const paths = options.paths ?? resolveAgentPaths(options.homeDir);
+    return new KeychainCredentialStore(options.platform ?? process.platform, options.executor ?? defaultSecurityExecutor(), paths, options.fs ?? credentialFs, options.serviceName ?? KEYCHAIN_SERVICE);
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

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

package/dist/hub.d.ts

@@ -0,0 +1,83 @@
+import http from "node:http";
+import { AGENT_CLIENT_PROTOCOL_VERSION, type HubRuntimeEvent } from "./wire.js";
+import type { ClientCommand, ClientEvent, PluginSyncAcknowledgement } from "./client/types.js";
+export declare const HUB_HEARTBEAT_STALE_MS: number;
+/** Compatibility-only HTTP registration record; it is not an executor. */
+export type MemoryHubRuntime = {
+    runtimeId: string;
+    displayName: string;
+    protocolVersion: number;
+    registeredAt: number;
+    lastSeen: number;
+};
+export type MemoryHubClient = {
+    clientId: string;
+    protocolVersion: typeof AGENT_CLIENT_PROTOCOL_VERSION;
+    connectedAt: number;
+    lastSeen: number;
+    online: boolean;
+    pendingOutboxCount: number;
+};
+export type MemoryHubOptions = {
+    /** Shared Hub token; generated when omitted (read it from hub.token). */
+    token?: string;
+    /** Nodes silent longer than this are reported stale (default 90s). */
+    staleMs?: number;
+    /** Push hook for embedded-Hub audit events. */
+    onRuntimeEvents?: (runtimeId: string, events: HubRuntimeEvent[]) => void;
+    /** Push hook for compatibility registration events. */
+    onRegister?: (runtime: MemoryHubRuntime) => void;
+    /** Receives the strict v2 acknowledgement for a local plugin desired-state revision. */
+    onPluginSyncAcknowledgement?: (clientId: string, acknowledgement: PluginSyncAcknowledgement) => void;
+    /** Replace the process-wide client logger before the Hub starts. */
+    logger?: import("./logger.js").BridgeLogger;
+    /**
+     * Custom token check for HTTP + WS auth (for example a DB-backed per-user
+     * credential lookup). It may be asynchronous and is awaited at every gate.
+     */
+    authorizeToken?: (candidate: string, req: http.IncomingMessage) => boolean | Promise<boolean>;
+    /** Max WS message bytes (default 1 MiB); guards the public exposure surface. */
+    maxPayloadBytes?: number;
+};
+/** A durable offer is retained until the Client reports the required state. */
+type ClientOffer = {
+    offerId: string;
+    targetClientId: string;
+    command: ClientCommand;
+};
+export type MemoryHubSnapshot = {
+    runtimes: MemoryHubRuntime[];
+    watermark: Record<string, Record<string, number>>;
+    clients?: Omit<MemoryHubClient, "online" | "pendingOutboxCount">[];
+    offers?: ClientOffer[];
+    executionWatermarks?: Record<string, number>;
+};
+export type MemoryHub = ReturnType<typeof createMemoryHub>;
+export declare function createMemoryHub(options?: MemoryHubOptions): {
+    token: string;
+    handle: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<boolean>;
+    attach: (server: http.Server, opts?: {
+        fallback?: (req: http.IncomingMessage, res: http.ServerResponse) => void;
+        onUnknownUpgrade?: (req: http.IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => void;
+        authorizeToken?: (candidate: string, req: http.IncomingMessage) => boolean | Promise<boolean>;
+    }) => void;
+    start: (host?: string, port?: number) => Promise<{
+        port: number;
+        close: () => Promise<void>;
+    }>;
+    offer: (targetClientId: string, command: ClientCommand) => void;
+    receiveEvents: (clientId: string, events: ClientEvent[]) => Record<string, number>;
+    listRuntimes: () => Array<MemoryHubRuntime & {
+        online: boolean;
+        stale: boolean;
+    }>;
+    listClients: () => MemoryHubClient[];
+    events: (runtimeId: string) => HubRuntimeEvent[];
+    clientEvents: (executionId: string) => ClientEvent[];
+    watermark: () => MemoryHubSnapshot["watermark"];
+    snapshot: () => MemoryHubSnapshot;
+    restore: (state: MemoryHubSnapshot) => void;
+    stop: () => void;
+};
+export {};
+//# sourceMappingURL=hub.d.ts.map

package/dist/hub.d.ts.map

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