@kernel.chat/kbot 2.27.0 → 3.0.0

package/dist/telemetry.js

@@ -0,0 +1,219 @@
+// K:BOT Telemetry — Structured JSON event logging, local-only
+//
+// Writes telemetry events to ~/.kbot/telemetry/ as NDJSON files (one per day).
+// No external reporting — all data stays on the user's machine.
+// Events are buffered in memory and flushed every 5 seconds or 50 events,
+// whichever comes first.
+//
+// NDJSON format: one JSON object per line, newline-separated.
+// File naming: YYYY-MM-DD.ndjson
+//
+// Event types:
+//   session_start / session_end   — session lifecycle
+//   tool_call_start / tool_call_end / tool_call_error — tool execution
+//   checkpoint_save / checkpoint_resume — checkpoint system
+//   agent_route — agent routing decisions
+//   api_call / api_error — LLM API interactions
+//   cost_update — cumulative cost tracking
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, appendFile, readFile, readdir, unlink, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+// ── Constants ──
+const TELEMETRY_DIR = join(homedir(), '.kbot', 'telemetry');
+const FLUSH_INTERVAL_MS = 5_000; // Flush every 5 seconds
+const FLUSH_THRESHOLD = 50; // Or when buffer reaches 50 events
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// ── TelemetryEmitter ──
+export class TelemetryEmitter {
+    dir;
+    sessionId;
+    buffer = [];
+    flushTimer = null;
+    initialized = false;
+    flushing = false;
+    constructor(sessionId, dir) {
+        this.sessionId = sessionId;
+        this.dir = dir || TELEMETRY_DIR;
+        // Start periodic flush
+        this.flushTimer = setInterval(() => {
+            this.flush().catch(() => {
+                // Flush errors are non-critical — events may be lost but agent keeps running
+            });
+        }, FLUSH_INTERVAL_MS);
+        // Prevent the timer from keeping the process alive
+        if (this.flushTimer && typeof this.flushTimer.unref === 'function') {
+            this.flushTimer.unref();
+        }
+    }
+    /** Ensure the telemetry directory exists */
+    async ensureDir() {
+        if (this.initialized)
+            return;
+        if (!existsSync(this.dir)) {
+            await mkdir(this.dir, { recursive: true });
+        }
+        this.initialized = true;
+    }
+    /**
+     * Emit a telemetry event. Buffers it in memory.
+     * When the buffer reaches FLUSH_THRESHOLD, triggers an immediate flush.
+     */
+    emit(event, data, duration_ms) {
+        const telemetryEvent = {
+            timestamp: Date.now(),
+            sessionId: this.sessionId,
+            event,
+            data,
+        };
+        if (duration_ms !== undefined) {
+            telemetryEvent.duration_ms = duration_ms;
+        }
+        this.buffer.push(telemetryEvent);
+        // Flush immediately if buffer is full
+        if (this.buffer.length >= FLUSH_THRESHOLD) {
+            this.flush().catch(() => {
+                // Non-critical
+            });
+        }
+    }
+    /**
+     * Flush buffered events to the daily NDJSON file.
+     * Each event is one JSON line, appended atomically.
+     */
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        if (this.flushing)
+            return; // Prevent concurrent flushes
+        this.flushing = true;
+        try {
+            await this.ensureDir();
+            // Drain buffer atomically
+            const events = this.buffer.splice(0);
+            // Group events by date (in case buffer spans midnight)
+            const byDate = new Map();
+            for (const event of events) {
+                const dateKey = new Date(event.timestamp).toISOString().slice(0, 10); // YYYY-MM-DD
+                const existing = byDate.get(dateKey) || [];
+                existing.push(event);
+                byDate.set(dateKey, existing);
+            }
+            // Append to each day's file
+            for (const [dateKey, dayEvents] of byDate) {
+                const filePath = join(this.dir, `${dateKey}.ndjson`);
+                const lines = dayEvents.map(e => JSON.stringify(e)).join('\n') + '\n';
+                await appendFile(filePath, lines, 'utf-8');
+            }
+        }
+        catch {
+            // Telemetry writes failing should never crash the agent
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /**
+     * Read all telemetry events for a specific session.
+     * Scans all NDJSON files and filters by sessionId.
+     */
+    async getSessionEvents(sessionId) {
+        await this.ensureDir();
+        let files;
+        try {
+            files = await readdir(this.dir);
+        }
+        catch {
+            return [];
+        }
+        const ndjsonFiles = files
+            .filter(f => f.endsWith('.ndjson'))
+            .sort(); // chronological order
+        const events = [];
+        for (const file of ndjsonFiles) {
+            try {
+                const content = await readFile(join(this.dir, file), 'utf-8');
+                const lines = content.split('\n').filter(line => line.trim());
+                for (const line of lines) {
+                    try {
+                        const event = JSON.parse(line);
+                        if (event.sessionId === sessionId) {
+                            events.push(event);
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        return events;
+    }
+    /**
+     * Remove telemetry files older than maxAge.
+     * Returns the number of files removed.
+     */
+    async cleanup(maxAge) {
+        await this.ensureDir();
+        const maxAgeMs = maxAge ?? DEFAULT_MAX_AGE_MS;
+        const cutoff = Date.now() - maxAgeMs;
+        let removed = 0;
+        let files;
+        try {
+            files = await readdir(this.dir);
+        }
+        catch {
+            return 0;
+        }
+        for (const file of files) {
+            if (!file.endsWith('.ndjson'))
+                continue;
+            const filePath = join(this.dir, file);
+            try {
+                const fileStat = await stat(filePath);
+                if (fileStat.mtimeMs < cutoff) {
+                    await unlink(filePath);
+                    removed++;
+                }
+            }
+            catch {
+                // File may have been removed — ignore
+            }
+        }
+        return removed;
+    }
+    /**
+     * Flush remaining events and stop the periodic flush timer.
+     * Call this when the session ends or the process is exiting.
+     */
+    async destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Final flush
+        await this.flush();
+    }
+}
+// ── Convenience: module-level singleton ──
+let _instance = null;
+export function getTelemetryEmitter(sessionId) {
+    if (!_instance) {
+        if (!sessionId)
+            throw new Error('TelemetryEmitter requires a sessionId on first call');
+        _instance = new TelemetryEmitter(sessionId);
+    }
+    return _instance;
+}
+export function destroyTelemetryEmitter() {
+    if (_instance) {
+        const p = _instance.destroy();
+        _instance = null;
+        return p;
+    }
+    return Promise.resolve();
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/terminal-caps.d.ts

@@ -0,0 +1,20 @@
+export interface TerminalCapabilities {
+    truecolor: boolean;
+    color256: boolean;
+    basicColor: boolean;
+    sixel: boolean;
+    kittyGraphics: boolean;
+    iterm2Images: boolean;
+    unicode: boolean;
+    braille: boolean;
+    syncOutput: boolean;
+    program: string;
+    columns: number;
+    rows: number;
+}
+export declare function detectTerminalCapabilities(): TerminalCapabilities;
+export declare function withSyncOutput(fn: () => void): void;
+export declare function rgb(r: number, g: number, b: number): string;
+export declare function bgRgb(r: number, g: number, b: number): string;
+export declare function gradient(text: string, startColor: [number, number, number], endColor: [number, number, number]): string;
+//# sourceMappingURL=terminal-caps.d.ts.map

package/dist/terminal-caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-caps.d.ts","sourceRoot":"","sources":["../src/terminal-caps.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,oBAAoB;IAEnC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IAGpB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IAGtB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IAGjB,UAAU,EAAE,OAAO,CAAC;IAGpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,0BAA0B,IAAI,oBAAoB,CAyCjE;AAKD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAYnD;AAKD,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CASvH"}

package/dist/terminal-caps.js

@@ -0,0 +1,80 @@
+// K:BOT Terminal Capability Detection — zero dependencies
+//
+// Detects what the current terminal supports and provides feature flags.
+// Enables progressive enhancement: Braille sparklines, inline images
+// (Sixel/Kitty/iTerm2), synchronized output, and truecolor gradients.
+//
+// Everything degrades gracefully — if detection fails, callers fall back
+// to existing basic output.
+export function detectTerminalCapabilities() {
+    const env = process.env;
+    const program = env.TERM_PROGRAM ?? env.TERMINAL_EMULATOR ?? '';
+    const colorterm = env.COLORTERM ?? '';
+    const term = env.TERM ?? '';
+    // Color detection
+    const truecolor = colorterm === 'truecolor' || colorterm === '24bit'
+        || ['iterm2', 'wezterm', 'kitty', 'alacritty', 'rio'].some(t => program.toLowerCase().includes(t));
+    const color256 = truecolor || term.includes('256color');
+    const basicColor = color256 || process.stdout.isTTY === true;
+    // Graphics detection
+    const kittyGraphics = program.toLowerCase() === 'kitty' || env.KITTY_WINDOW_ID !== undefined;
+    const iterm2Images = program === 'iTerm.app' || program === 'WezTerm' || env.ITERM_SESSION_ID !== undefined;
+    const sixel = ['mlterm', 'xterm', 'foot', 'contour'].some(t => program.toLowerCase().includes(t))
+        || term === 'xterm-sixel';
+    // Unicode/Braille
+    const locale = env.LANG ?? env.LC_ALL ?? '';
+    const unicode = locale.includes('UTF-8') || locale.includes('utf-8') || locale.includes('UTF8');
+    const braille = unicode; // Braille requires Unicode
+    // Synchronized output (most modern terminals support it)
+    const syncOutput = kittyGraphics || iterm2Images
+        || ['wezterm', 'contour', 'foot', 'rio'].some(t => program.toLowerCase().includes(t));
+    return {
+        truecolor,
+        color256,
+        basicColor,
+        sixel,
+        kittyGraphics,
+        iterm2Images,
+        unicode,
+        braille,
+        syncOutput,
+        program: program || term || 'unknown',
+        columns: process.stdout.columns ?? 80,
+        rows: process.stdout.rows ?? 24,
+    };
+}
+// ── Synchronized output wrapper ──
+// Prevents flicker by buffering screen updates between begin/end markers.
+export function withSyncOutput(fn) {
+    const caps = detectTerminalCapabilities();
+    if (caps.syncOutput) {
+        process.stdout.write('\x1b[?2026h'); // Begin synchronized update
+    }
+    try {
+        fn();
+    }
+    finally {
+        if (caps.syncOutput) {
+            process.stdout.write('\x1b[?2026l'); // End synchronized update
+        }
+    }
+}
+// ── Truecolor helpers ──
+// Generate ANSI escape sequences for 24-bit color terminals.
+export function rgb(r, g, b) {
+    return `\x1b[38;2;${r};${g};${b}m`;
+}
+export function bgRgb(r, g, b) {
+    return `\x1b[48;2;${r};${g};${b}m`;
+}
+export function gradient(text, startColor, endColor) {
+    const chars = [...text];
+    return chars.map((char, i) => {
+        const t = chars.length > 1 ? i / (chars.length - 1) : 0;
+        const r = Math.round(startColor[0] + (endColor[0] - startColor[0]) * t);
+        const g = Math.round(startColor[1] + (endColor[1] - startColor[1]) * t);
+        const b = Math.round(startColor[2] + (endColor[2] - startColor[2]) * t);
+        return `${rgb(r, g, b)}${char}`;
+    }).join('') + '\x1b[0m';
+}
+//# sourceMappingURL=terminal-caps.js.map

package/dist/terminal-caps.js.map

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

package/dist/tool-pipeline.d.ts

@@ -0,0 +1,86 @@
+export interface ToolContext {
+    toolName: string;
+    toolArgs: Record<string, any>;
+    toolCallId: string;
+    result?: string;
+    error?: string;
+    durationMs?: number;
+    metadata: Record<string, any>;
+    aborted: boolean;
+    abortReason?: string;
+}
+export type NextFunction = () => Promise<void>;
+export type ToolMiddleware = (ctx: ToolContext, next: NextFunction) => Promise<void>;
+export declare class ToolPipeline {
+    private middleware;
+    /** Append middleware to the end of the pipeline */
+    use(mw: ToolMiddleware): this;
+    /** Insert middleware at a specific position */
+    useAt(index: number, mw: ToolMiddleware): this;
+    /** Remove middleware by reference */
+    remove(mw: ToolMiddleware): this;
+    /** Execute the pipeline for a tool context */
+    execute(ctx: ToolContext): Promise<ToolContext>;
+    /** Number of middleware in the pipeline */
+    get length(): number;
+}
+/**
+ * Permission check middleware.
+ * Blocks tool execution if the user denies the operation.
+ */
+export declare function permissionMiddleware(checkPermission: (name: string, args: any) => Promise<boolean>): ToolMiddleware;
+/**
+ * Pre/post hook middleware.
+ * Runs user-defined hooks before and after tool execution.
+ */
+export declare function hookMiddleware(runPreHook: (name: string, args: any) => {
+    blocked: boolean;
+    blockReason?: string;
+}, runPostHook: (name: string, args: any, result: string) => void): ToolMiddleware;
+/**
+ * Timeout middleware.
+ * Aborts tool execution if it exceeds the configured timeout.
+ */
+export declare function timeoutMiddleware(defaultTimeout?: number): ToolMiddleware;
+/**
+ * Metrics recording middleware.
+ * Records execution duration and error state.
+ */
+export declare function metricsMiddleware(recordMetrics: (name: string, duration: number, error?: string) => void): ToolMiddleware;
+/**
+ * Result truncation middleware.
+ * Truncates tool output that exceeds maxSize characters.
+ */
+export declare function truncationMiddleware(maxSize?: number): ToolMiddleware;
+/**
+ * Telemetry middleware.
+ * Emits tool_call_start and tool_call_end events.
+ */
+export declare function telemetryMiddleware(emit: (event: string, data: any) => void): ToolMiddleware;
+/**
+ * Execution middleware — the actual tool call.
+ * This should be the last middleware in the pipeline.
+ */
+export declare function executionMiddleware(executeTool: (name: string, args: any) => Promise<{
+    result: string;
+    error?: string;
+}>): ToolMiddleware;
+/**
+ * Create the default pipeline with the standard middleware stack.
+ * Order: telemetry? → permission → hooks → metrics → timeout → truncation → execution
+ */
+export declare function createDefaultPipeline(deps: {
+    checkPermission: (name: string, args: any) => Promise<boolean>;
+    runPreHook: (name: string, args: any) => {
+        blocked: boolean;
+        blockReason?: string;
+    };
+    runPostHook: (name: string, args: any, result: string) => void;
+    executeTool: (name: string, args: any) => Promise<{
+        result: string;
+        error?: string;
+    }>;
+    recordMetrics: (name: string, duration: number, error?: string) => void;
+    emit?: (event: string, data: any) => void;
+}): ToolPipeline;
+//# sourceMappingURL=tool-pipeline.d.ts.map

package/dist/tool-pipeline.d.ts.map

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

package/dist/tool-pipeline.js

@@ -0,0 +1,200 @@
+// K:BOT Tool Execution Middleware Pipeline
+// Composable Express/Koa-style middleware stack for tool execution.
+// Each middleware calls next() to continue the chain.
+//
+// Order matters: first added = outermost (runs first on the way in, last on the way out).
+// The execution middleware should always be last.
+//
+// Usage:
+//   const pipeline = new ToolPipeline()
+//   pipeline.use(permissionMiddleware(checkPermission))
+//   pipeline.use(metricsMiddleware(recordMetrics))
+//   pipeline.use(executionMiddleware(executeTool))
+//   await pipeline.execute(ctx)
+export class ToolPipeline {
+    middleware = [];
+    /** Append middleware to the end of the pipeline */
+    use(mw) {
+        this.middleware.push(mw);
+        return this;
+    }
+    /** Insert middleware at a specific position */
+    useAt(index, mw) {
+        this.middleware.splice(index, 0, mw);
+        return this;
+    }
+    /** Remove middleware by reference */
+    remove(mw) {
+        const idx = this.middleware.indexOf(mw);
+        if (idx !== -1)
+            this.middleware.splice(idx, 1);
+        return this;
+    }
+    /** Execute the pipeline for a tool context */
+    async execute(ctx) {
+        let index = 0;
+        const next = async () => {
+            if (ctx.aborted)
+                return;
+            if (index >= this.middleware.length)
+                return;
+            const mw = this.middleware[index++];
+            await mw(ctx, next);
+        };
+        await next();
+        return ctx;
+    }
+    /** Number of middleware in the pipeline */
+    get length() {
+        return this.middleware.length;
+    }
+}
+// ── Built-in middleware factories ──
+/**
+ * Permission check middleware.
+ * Blocks tool execution if the user denies the operation.
+ */
+export function permissionMiddleware(checkPermission) {
+    return async (ctx, next) => {
+        const allowed = await checkPermission(ctx.toolName, ctx.toolArgs);
+        if (!allowed) {
+            ctx.aborted = true;
+            ctx.abortReason = 'Permission denied by user';
+            ctx.error = 'Tool call was denied by user';
+            return;
+        }
+        await next();
+    };
+}
+/**
+ * Pre/post hook middleware.
+ * Runs user-defined hooks before and after tool execution.
+ */
+export function hookMiddleware(runPreHook, runPostHook) {
+    return async (ctx, next) => {
+        const preResult = runPreHook(ctx.toolName, ctx.toolArgs);
+        if (preResult.blocked) {
+            ctx.aborted = true;
+            ctx.abortReason = preResult.blockReason ?? 'Blocked by pre-tool hook';
+            ctx.error = `Blocked by hook: ${ctx.abortReason}`;
+            return;
+        }
+        await next();
+        if (ctx.result && !ctx.error) {
+            runPostHook(ctx.toolName, ctx.toolArgs, ctx.result);
+        }
+    };
+}
+/**
+ * Timeout middleware.
+ * Aborts tool execution if it exceeds the configured timeout.
+ */
+export function timeoutMiddleware(defaultTimeout = 300_000) {
+    return async (ctx, next) => {
+        const timeout = ctx.metadata.timeout ?? defaultTimeout;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        ctx.metadata.abortController = controller;
+        try {
+            await Promise.race([
+                next(),
+                new Promise((_, reject) => {
+                    controller.signal.addEventListener('abort', () => {
+                        reject(new Error(`Tool ${ctx.toolName} timed out after ${timeout}ms`));
+                    });
+                }),
+            ]);
+        }
+        catch (err) {
+            if (err.message?.includes('timed out')) {
+                ctx.error = err.message;
+                ctx.aborted = true;
+                ctx.abortReason = 'Execution timed out';
+            }
+            else {
+                throw err;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+/**
+ * Metrics recording middleware.
+ * Records execution duration and error state.
+ */
+export function metricsMiddleware(recordMetrics) {
+    return async (ctx, next) => {
+        const start = Date.now();
+        await next();
+        ctx.durationMs = Date.now() - start;
+        recordMetrics(ctx.toolName, ctx.durationMs, ctx.error);
+    };
+}
+/**
+ * Result truncation middleware.
+ * Truncates tool output that exceeds maxSize characters.
+ */
+export function truncationMiddleware(maxSize = 50_000) {
+    return async (ctx, next) => {
+        await next();
+        if (ctx.result && ctx.result.length > maxSize) {
+            const remaining = ctx.result.length - maxSize;
+            ctx.result = ctx.result.slice(0, maxSize) +
+                `\n\n[... truncated ${remaining} characters. Use more specific queries to get focused results.]`;
+        }
+    };
+}
+/**
+ * Telemetry middleware.
+ * Emits tool_call_start and tool_call_end events.
+ */
+export function telemetryMiddleware(emit) {
+    return async (ctx, next) => {
+        emit('tool_call_start', { tool: ctx.toolName, args: ctx.toolArgs });
+        await next();
+        emit('tool_call_end', {
+            tool: ctx.toolName,
+            duration_ms: ctx.durationMs,
+            success: !ctx.error,
+            error: ctx.error,
+        });
+    };
+}
+/**
+ * Execution middleware — the actual tool call.
+ * This should be the last middleware in the pipeline.
+ */
+export function executionMiddleware(executeTool) {
+    return async (ctx, next) => {
+        try {
+            const result = await executeTool(ctx.toolName, ctx.toolArgs);
+            ctx.result = result.result;
+            if (result.error)
+                ctx.error = result.error;
+        }
+        catch (err) {
+            ctx.error = err.message ?? String(err);
+        }
+        await next(); // allow post-execution middleware
+    };
+}
+/**
+ * Create the default pipeline with the standard middleware stack.
+ * Order: telemetry? → permission → hooks → metrics → timeout → truncation → execution
+ */
+export function createDefaultPipeline(deps) {
+    const pipeline = new ToolPipeline();
+    if (deps.emit) {
+        pipeline.use(telemetryMiddleware(deps.emit));
+    }
+    pipeline.use(permissionMiddleware(deps.checkPermission));
+    pipeline.use(hookMiddleware(deps.runPreHook, deps.runPostHook));
+    pipeline.use(metricsMiddleware(deps.recordMetrics));
+    pipeline.use(timeoutMiddleware());
+    pipeline.use(truncationMiddleware());
+    pipeline.use(executionMiddleware(deps.executeTool));
+    return pipeline;
+}
+//# sourceMappingURL=tool-pipeline.js.map

package/dist/tool-pipeline.js.map

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