@nodetool-ai/websocket 0.7.0-rc.23 → 0.8.1

package/dist/fake-runtime.js

@@ -0,0 +1,270 @@
+/**
+ * Hermetic execution fakes shared by the test backends.
+ *
+ * Both test servers need workflows and chat to run with no API keys and no
+ * network, while pure-compute nodes still run for real so the assertions mean
+ * something:
+ *   - `e2e-server.ts` runs the shipped templates for the web E2E runner.
+ *   - `screenshot-server.ts` (with `NODETOOL_FAKE_PROVIDERS=1`) serves the
+ *     seeded fixtures to the user-journey suite.
+ *
+ * Faking strategy:
+ *   - LLM/agent providers: every registered provider id is re-registered with
+ *     `FakeProvider` (a ScriptedProvider with no required credentials), so
+ *     `getProvider` / `isProviderConfigured` and the runner's `resolveProvider`
+ *     all return a configured fake regardless of how a node resolves its
+ *     provider.
+ *   - External / media-generating nodes (fal, replicate, search, http, image /
+ *     video / audio generation, …) resolve to an executor returning
+ *     type-correct placeholder outputs derived from the node's output metadata,
+ *     so downstream and output nodes still receive well-formed values.
+ *   - Structural nodes (input/output/control) and pure-compute nodes (text,
+ *     data, math, …) run for real.
+ *
+ * Set `NODETOOL_FAKE_DEBUG=1` for per-node REAL/FAKE resolution logging.
+ */
+import { ScriptedProvider, autoScript, registerProvider, listRegisteredProviderIds, isToolCall } from "@nodetool-ai/runtime";
+import { chunkSchema } from "@nodetool-ai/protocol";
+/** Valid 1x1 transparent PNG — bytes for faked image/media outputs, so
+ *  downstream nodes that decode them don't choke. */
+export const TINY_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4////fwAJ+wP9KobjigAAAABJRU5ErkJggg==";
+/** The text every faked LLM call returns. Assert on this in tests. */
+export const FAKE_LLM_TEXT = "deterministic e2e response";
+/** The value every faked non-media output slot returns. */
+export const FAKE_OUTPUT_TEXT = "deterministic e2e output";
+const FAKE_TRANSCRIPTION_TEXT = FAKE_LLM_TEXT;
+const FAKE_TRANSCRIPTION_WORDS = [
+    { text: "deterministic", timestamp: [0, 1] },
+    { text: "e2e", timestamp: [1, 2] },
+    { text: "response", timestamp: [2, 3] }
+];
+const FAKE_TRANSCRIPTION_SEGMENTS = [{ text: FAKE_TRANSCRIPTION_TEXT, timestamp: [0, 3] }];
+const debugEnabled = () => process.env.NODETOOL_FAKE_DEBUG === "1";
+function debug(message) {
+    if (!debugEnabled())
+        return;
+    // eslint-disable-next-line no-console
+    console.error(message);
+}
+// ── Provider faking ─────────────────────────────────────────────────────────
+/**
+ * Validate a `Chunk` a fake provider is about to yield against the B1
+ * protocol schema (`packages/protocol/src/messages.ts`) and throw a
+ * descriptive error on mismatch. Called unconditionally — this module only
+ * ever runs in tests, so there is no production cost to always-on validation.
+ * See RELIABILITY_ARCHITECTURE.md §8 point 5 ("Fakes derive from contracts").
+ */
+export function assertValidFakeChunk(chunk) {
+    const result = chunkSchema.safeParse(chunk);
+    if (!result.success) {
+        throw new Error(`[fake-runtime] FakeProvider emitted a Chunk that fails processingMessageSchemas.chunk: ${result.error.message}\n` +
+            `Chunk: ${JSON.stringify(chunk)}`);
+    }
+}
+/** A provider that returns deterministic scripted responses; ignores kwargs. */
+export class FakeProvider extends ScriptedProvider {
+    constructor(_kwargs) {
+        const inner = autoScript({
+            plan: {
+                title: "Agent task",
+                steps: [
+                    { id: "s1", instructions: "Complete the objective", depends_on: [] }
+                ]
+            },
+            text: FAKE_LLM_TEXT
+        });
+        super([
+            (messages, tools) => {
+                debug(`[fake-runtime] script tools=[${tools
+                    .map((t) => t.name)
+                    .join(",")}] roles=[${messages.map((m) => m.role).join(",")}]`);
+                return inner(messages, tools);
+            }
+        ]);
+    }
+    /**
+     * Validate every yielded `Chunk` (the only `ProcessingMessage`-shaped
+     * payload a fake provider emits — tool calls and session updates carry no
+     * `type: "chunk"` discriminator) against the B1 schema before it reaches
+     * downstream consumers.
+     */
+    async *generateMessages(args) {
+        for await (const item of super.generateMessages(args)) {
+            if (!isToolCall(item) && item.type === "chunk") {
+                assertValidFakeChunk(item);
+            }
+            yield item;
+        }
+    }
+}
+/**
+ * Replace every registered provider (openai, anthropic, gemini, …) with the
+ * FakeProvider, registered with no required credentials. This makes
+ * `isProviderConfigured` return true and `getProvider` return a fake on every
+ * resolution path — so agent/LLM nodes never demand a real API key.
+ *
+ * Call again after node registration: providers self-register on import, so a
+ * package loaded during registry setup can add a real provider afterwards.
+ */
+export function fakeAllProviders() {
+    for (const id of listRegisteredProviderIds()) {
+        registerProvider(id, FakeProvider, {});
+    }
+}
+/** A `resolveProvider` implementation that always hands back a fake. */
+export const resolveFakeProvider = async () => new FakeProvider();
+// ── Executor faking ─────────────────────────────────────────────────────────
+const MEDIA_TYPES = new Set(["image", "audio", "video", "document"]);
+/** Node namespaces that reach external services (network / API keys) and must
+ *  be faked. Matched as a prefix of the node type. */
+const EXTERNAL_PREFIXES = [
+    "fal.",
+    "replicate.",
+    "elevenlabs.",
+    "huggingface.",
+    "kie.",
+    "openai.",
+    "google.",
+    "search.",
+    "vector.chroma",
+    "lib.http",
+    "lib.pymupdf",
+    "lib.sqlite",
+    "lib.browser",
+    "nodetool.generators.web"
+];
+/** Provider-backed node classes that don't produce media outputs (so the
+ *  media-output heuristic misses them) but still need a real model/provider —
+ *  faked by class name (last segment of the node type). */
+const FAKE_NODE_CLASSES = new Set(["AutomaticSpeechRecognition"]);
+/** Structural nodes must always run for real: inputs dispatch run params,
+ *  outputs emit results, control routes the graph. */
+const STRUCTURAL_PREFIXES = [
+    "nodetool.input.",
+    "nodetool.output.",
+    "nodetool.control."
+];
+const baseType = (slot) => slot?.type?.type ?? "any";
+const isStructural = (nodeType) => STRUCTURAL_PREFIXES.some((p) => nodeType.startsWith(p));
+const isExternal = (nodeType) => EXTERNAL_PREFIXES.some((p) => nodeType.startsWith(p));
+const isFakeByClass = (nodeType) => FAKE_NODE_CLASSES.has(nodeType.split(".").pop() ?? "");
+const outputsMedia = (meta) => (meta?.outputs ?? []).some((o) => MEDIA_TYPES.has(baseType(o)));
+const inputsMedia = (meta) => (meta?.properties ?? []).some((p) => MEDIA_TYPES.has(baseType(p)));
+const needsSecret = (meta) => Array.isArray(meta?.required_settings) && meta.required_settings.length > 0;
+/** Nodes that shell out to external runtimes (ffmpeg/ffprobe, …) cannot run on
+ *  the CI box regardless of their declared IO types — e.g. `timeline.AddClips`
+ *  probes media bytes but is timeline-typed on both sides. */
+const needsRuntime = (meta) => Array.isArray(meta?.required_runtimes) && meta.required_runtimes.length > 0;
+/** Build a type-correct placeholder for a single output slot. */
+export function fakeValueForType(type) {
+    if (MEDIA_TYPES.has(type)) {
+        const mime = type === "image"
+            ? "image/png"
+            : type === "audio"
+                ? "audio/mpeg"
+                : type === "video"
+                    ? "video/mp4"
+                    : "application/octet-stream";
+        return {
+            type,
+            uri: `data:${mime};base64,${TINY_PNG_BASE64}`,
+            data: TINY_PNG_BASE64,
+            mimeType: mime
+        };
+    }
+    switch (type) {
+        case "str":
+        case "text":
+            return FAKE_OUTPUT_TEXT;
+        case "int":
+        case "float":
+            return 0;
+        case "bool":
+            return true;
+        case "list":
+            return [];
+        case "dict":
+            return {};
+        default:
+            return null;
+    }
+}
+/** An executor that emits placeholder outputs for a node's declared slots. */
+export function fakeExecutor(meta, nodeType, staticProperties = {}) {
+    return {
+        async process(inputs) {
+            const outputs = meta?.outputs ?? [];
+            if (outputs.length === 0)
+                return inputs;
+            const result = {};
+            const effectiveNodeType = nodeType ?? meta?.node_type;
+            const transcribeWithTimestamps = effectiveNodeType === "openai.audio.Transcribe" &&
+                { ...staticProperties, ...inputs }.timestamps === true;
+            for (const slot of outputs) {
+                if (effectiveNodeType === "openai.audio.Transcribe") {
+                    if (slot.name === "text") {
+                        result[slot.name] = FAKE_TRANSCRIPTION_TEXT;
+                        continue;
+                    }
+                    if (transcribeWithTimestamps && slot.name === "words") {
+                        result[slot.name] = FAKE_TRANSCRIPTION_WORDS;
+                        continue;
+                    }
+                    if (transcribeWithTimestamps && slot.name === "segments") {
+                        result[slot.name] = FAKE_TRANSCRIPTION_SEGMENTS;
+                        continue;
+                    }
+                }
+                result[slot.name] = fakeValueForType(baseType(slot));
+            }
+            return result;
+        }
+    };
+}
+/** True when a node type should be faked rather than executed for real. */
+export function shouldFakeNode(nodeType, meta) {
+    if (isStructural(nodeType))
+        return false;
+    return (needsSecret(meta) ||
+        needsRuntime(meta) ||
+        outputsMedia(meta) ||
+        inputsMedia(meta) ||
+        isExternal(nodeType) ||
+        isFakeByClass(nodeType));
+}
+/**
+ * Build a `resolveExecutor` that fakes external/provider-backed nodes and runs
+ * everything else for real.
+ *
+ * `getRegistry` is a callback rather than a value because the registry only
+ * exists once `createTestUiServer` calls `configureRegistry`, which happens
+ * after the options object is constructed.
+ *
+ * @param getRegistry     returns the live registry, or null before setup
+ * @param passthrough     when true, unknown node types echo their inputs
+ *                        through instead of throwing (e.g. `test.Input`)
+ */
+export function createFakeExecutorResolver(getRegistry, { passthrough = true } = {}) {
+    const echo = {
+        async process(inputs) {
+            return inputs;
+        }
+    };
+    return (node) => {
+        const registry = getRegistry();
+        if (!registry || !registry.has(node.type)) {
+            if (!passthrough && registry)
+                return registry.resolve(node);
+            return echo;
+        }
+        if (isStructural(node.type))
+            return registry.resolve(node);
+        const meta = registry.getMetadata(node.type);
+        const fake = shouldFakeNode(node.type, meta);
+        debug(`[fake-runtime] ${node.id} ${node.type} -> ${fake ? "FAKE" : "REAL"}`);
+        return fake
+            ? fakeExecutor(meta, node.type, node.properties ?? {})
+            : registry.resolve(node);
+    };
+}
+//# sourceMappingURL=fake-runtime.js.map

package/dist/fake-runtime.js.map

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

package/dist/file-api.d.ts

@@ -1,12 +1,9 @@
-export interface FileApiOptions {
-    /** Root directory for the file browser sandbox. Defaults to user home. */
-    rootDir?: string;
-}
 /**
- * Handle file browser binary download requests.
- * Route: /api/files/download
+ * Handle file browser binary requests.
+ * Routes:
+ *   /api/files/local — stream a local file by absolute path (Range-capable)
  *
  * JSON ops (list, info) have moved to the tRPC `files` router.
  */
-export declare function handleFileRequest(request: Request, options?: FileApiOptions): Promise<Response>;
+export declare function handleFileRequest(request: Request): Promise<Response>;
 //# sourceMappingURL=file-api.d.ts.map

package/dist/file-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-api.d.ts","sourceRoot":"","sources":["../src/file-api.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqDD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAmBnB"}
+{"version":3,"file":"file-api.d.ts","sourceRoot":"","sources":["../src/file-api.ts"],"names":[],"mappings":"AAyJA;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqB3E"}

package/dist/file-api.js

@@ -1,75 +1,158 @@
 /**
- * File browser API — T-WS-9 (binary download only).
+ * File browser API — binary download + local-file streaming.
  *
  * JSON operations (list, info) have been migrated to the tRPC `files` router.
- * This module retains only the binary download endpoint.
+ * This module retains the binary download endpoint plus a local-file streaming
+ * endpoint used to preview files referenced by `file://` URIs (local/desktop
+ * mode drops). The renderer can't load a raw `file://` URL under `webSecurity`,
+ * so it points media elements at `/api/files/local?path=…` and the backend
+ * streams the bytes off disk with HTTP Range support (needed for audio/video
+ * seeking) — no reading in Electron, no data URIs.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import * as os from "node:os";
+import { corsHeaders, nodeStreamToWebStream, parseRangeHeader } from "./storage-api.js";
+import { localPathDenialMessage, resolveLocalPath } from "./lib/local-file-access.js";
 function errorResponse(status, detail) {
     return new Response(JSON.stringify({ detail }), {
         status,
         headers: { "content-type": "application/json" }
     });
 }
-/**
- * Resolve a user-provided path within the sandbox root.
- * Returns the resolved absolute path, or null if the path escapes the sandbox.
- */
-function resolveSandboxed(rootDir, userPath) {
-    const resolved = path.resolve(rootDir, userPath.startsWith("/") ? "." + userPath : userPath);
-    const normalizedRoot = path.resolve(rootDir);
-    if (!resolved.startsWith(normalizedRoot + path.sep) &&
-        resolved !== normalizedRoot) {
-        return null;
-    }
-    return resolved;
+// ── Local-file streaming (/api/files/local) ─────────────────────────
+const LOCAL_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".m4a": "audio/mp4",
+    ".flac": "audio/flac",
+    ".aac": "audio/aac",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".avi": "video/x-msvideo",
+    ".mkv": "video/x-matroska",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".json": "application/json"
+};
+function localMimeType(filePath) {
+    return (LOCAL_MIME_TYPES[path.extname(filePath).toLowerCase()] ??
+        "application/octet-stream");
 }
-async function handleDownload(url, rootDir) {
+async function handleLocalFileStream(request, url) {
     const userPath = url.searchParams.get("path");
     if (!userPath)
         return errorResponse(400, "path parameter is required");
-    const resolved = resolveSandboxed(rootDir, userPath);
-    if (!resolved)
-        return errorResponse(403, "Path traversal not allowed");
+    // Allowlist, not denylist: the path must resolve inside a configured root
+    // (home by default), both lexically and after symlinks. Same policy the
+    // tRPC file browser applies — see lib/local-file-access.ts.
+    const allowed = await resolveLocalPath(userPath);
+    if (!allowed.ok) {
+        const status = allowed.reason === "invalid" ? 400 : 403;
+        return errorResponse(status, localPathDenialMessage(allowed.reason));
+    }
+    const resolved = allowed.path;
+    let stat;
     try {
-        const stat = await fs.stat(resolved);
-        if (stat.isDirectory()) {
-            return errorResponse(400, "Cannot download a directory");
-        }
-        const content = await fs.readFile(resolved);
-        return new Response(content, {
+        stat = await fs.stat(resolved);
+    }
+    catch {
+        return errorResponse(404, "File not found");
+    }
+    if (stat.isDirectory()) {
+        return errorResponse(400, "Cannot stream a directory");
+    }
+    const cors = corsHeaders(request);
+    const contentType = localMimeType(resolved);
+    const fileSize = stat.size;
+    const lastModified = stat.mtime.toUTCString();
+    if (request.method === "HEAD") {
+        return new Response(null, {
             status: 200,
             headers: {
-                "content-type": "application/octet-stream",
-                "content-length": String(content.byteLength)
+                ...cors,
+                "Content-Type": contentType,
+                "Content-Length": String(fileSize),
+                "Last-Modified": lastModified,
+                "Accept-Ranges": "bytes"
             }
         });
     }
-    catch {
-        return errorResponse(404, "File not found");
+    const rangeHeader = request.headers.get("Range");
+    const range = rangeHeader
+        ? parseRangeHeader(rangeHeader, fileSize)
+        : null;
+    // "unsatisfiable" → 416; an unparseable/unsupported header (null with a header
+    // present) is ignored and the full file served with 200, per RFC 7233.
+    if (range === "unsatisfiable") {
+        return new Response(JSON.stringify({ detail: "Range Not Satisfiable" }), {
+            status: 416,
+            headers: {
+                ...cors,
+                "content-type": "application/json",
+                "Content-Range": `bytes */${fileSize}`
+            }
+        });
     }
+    if (range) {
+        const { start, end } = range;
+        const body = nodeStreamToWebStream(resolved, { start, end });
+        return new Response(body, {
+            status: 206,
+            headers: {
+                ...cors,
+                "Content-Type": contentType,
+                "Content-Length": String(end - start + 1),
+                "Content-Range": `bytes ${start}-${end}/${fileSize}`,
+                "Last-Modified": lastModified,
+                "Accept-Ranges": "bytes"
+            }
+        });
+    }
+    const body = nodeStreamToWebStream(resolved);
+    return new Response(body, {
+        status: 200,
+        headers: {
+            ...cors,
+            "Content-Type": contentType,
+            "Content-Length": String(fileSize),
+            "Last-Modified": lastModified,
+            "Accept-Ranges": "bytes"
+        }
+    });
 }
 /**
- * Handle file browser binary download requests.
- * Route: /api/files/download
+ * Handle file browser binary requests.
+ * Routes:
+ *   /api/files/local — stream a local file by absolute path (Range-capable)
  *
  * JSON ops (list, info) have moved to the tRPC `files` router.
  */
-export async function handleFileRequest(request, options = {}) {
+export async function handleFileRequest(request) {
     // File browser exposes the local filesystem — disabled in production
     if (process.env["NODETOOL_ENV"] === "production") {
         return errorResponse(403, "File browser is disabled in production");
     }
-    if (request.method !== "GET") {
-        return errorResponse(405, "Method not allowed");
-    }
-    const rootDir = options.rootDir ?? os.homedir();
     const url = new URL(request.url);
-    const pathname = url.pathname.replace(/\/+$/, "");
-    if (pathname === "/api/files/download") {
-        return handleDownload(url, rootDir);
+    // A loop, not `/\/+$/`: the regex backtracks quadratically on a long slash
+    // run followed by another character.
+    let end = url.pathname.length;
+    while (end > 0 && url.pathname[end - 1] === "/")
+        end -= 1;
+    const pathname = url.pathname.slice(0, end);
+    if (pathname === "/api/files/local") {
+        if (request.method !== "GET" && request.method !== "HEAD") {
+            return errorResponse(405, "Method not allowed");
+        }
+        return handleLocalFileStream(request, url);
     }
     return errorResponse(404, "Not found");
 }

package/dist/file-api.js.map

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

package/dist/frontend-renderer-registry.d.ts

@@ -0,0 +1,75 @@
+export interface FrontendRendererToolCall {
+    tool_call_id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export type FrontendRendererToolResult = {
+    renderer_id: string;
+    tool_call_id: string;
+    ok: true;
+    result?: unknown;
+} | {
+    renderer_id: string;
+    tool_call_id: string;
+    ok: false;
+    error: string;
+};
+interface ExecuteFrontendRendererToolOptions {
+    userId: string;
+    rendererId?: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    timeoutMs?: number;
+}
+interface ExecuteFrontendRendererToolResult {
+    handled: boolean;
+    result?: unknown;
+}
+/** The small surface the registry needs from a live /ws runner. */
+export interface FrontendRendererRunner {
+    isRendererConnected(): boolean;
+    isRendererReady(): boolean;
+    getRendererToolManifest(): Record<string, Record<string, unknown>>;
+    executeRendererTool(rendererId: string, call: FrontendRendererToolCall, timeoutMs?: number): Promise<FrontendRendererToolResult>;
+}
+export interface FrontendRendererInfo {
+    renderer_id: string;
+    user_id: string;
+    ready: boolean;
+    connected: boolean;
+    active: boolean;
+    last_active_at: number;
+    tools: Record<string, Record<string, unknown>>;
+}
+interface RendererRecord {
+    info: FrontendRendererInfo;
+    runner: FrontendRendererRunner;
+    activitySequence: number;
+}
+export interface FrontendRendererService {
+    list(userId: string): FrontendRendererInfo[];
+    execute(options: ExecuteFrontendRendererToolOptions): Promise<ExecuteFrontendRendererToolResult>;
+}
+/**
+ * User-scoped registry of browser renderers attached to the normal /ws socket.
+ *
+ * A renderer is not listed until its browser has sent a client tool manifest.
+ * Entries are removed as soon as their runner disconnects. The registry owns
+ * selection and authorization so MCP callers cannot accidentally address a
+ * renderer belonging to another user.
+ */
+export declare class FrontendRendererRegistry implements FrontendRendererService {
+    private readonly renderers;
+    private activitySequence;
+    register(userId: string, runner: FrontendRendererRunner): string;
+    markReady(rendererId: string): void;
+    touch(rendererId: string): void;
+    unregister(rendererId: string): void;
+    list(userId: string): FrontendRendererInfo[];
+    /** Resolve an explicit renderer or the most recently active renderer. */
+    resolve(userId: string, rendererId?: string): RendererRecord | null;
+    execute(options: ExecuteFrontendRendererToolOptions): Promise<ExecuteFrontendRendererToolResult>;
+    get size(): number;
+}
+export {};
+//# sourceMappingURL=frontend-renderer-registry.d.ts.map

package/dist/frontend-renderer-registry.d.ts.map

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