qlogicagent 2.13.3 → 2.13.5

package/dist/cli/tool-bootstrap.test.js

@@ -0,0 +1,94 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import { afterEach } from "vitest";
+import { enforceAbsoluteFloors, setBootstrapWorkdir, setGroupSecurityMode, validateExecCommand } from "./tool-bootstrap.js";
+describe("enforceAbsoluteFloors", () => {
+    it("no longer hard-blocks paths outside the workspace (the pipeline gates those)", () => {
+        const ROOT = path.join(os.tmpdir(), "qla-bootstrap-test-root");
+        setBootstrapWorkdir(ROOT);
+        // A path clearly outside ROOT. Under the old model this was a hard block;
+        // cross-workspace decisions now belong to the permission pipeline, so the
+        // tool-layer floor must NOT block it.
+        const outside = path.join(os.tmpdir(), "qla-bootstrap-test-OTHER", "secret.txt");
+        expect(enforceAbsoluteFloors(outside)).toBeNull();
+        // A path inside ROOT is likewise not blocked by the floor.
+        const inside = path.join(ROOT, "src", "index.ts");
+        expect(enforceAbsoluteFloors(inside)).toBeNull();
+    });
+    it("still hard-blocks device/system paths regardless of mode", () => {
+        expect(enforceAbsoluteFloors("/dev/zero")).not.toBeNull();
+        expect(enforceAbsoluteFloors("/dev/null")).not.toBeNull();
+        expect(enforceAbsoluteFloors("/proc/self/mem")).not.toBeNull();
+        expect(enforceAbsoluteFloors("/sys/kernel")).not.toBeNull();
+    });
+    it("returns an error message that names the offending device path", () => {
+        const err = enforceAbsoluteFloors("/dev/zero");
+        expect(err).toContain("/dev/zero");
+    });
+});
+describe("validateExecCommand", () => {
+    const ROOT = path.join(os.tmpdir(), "qla-exec-test-root");
+    it("cross-workspace paths are NOT hard-blocked (pipeline gates them)", () => {
+        // Reading a file clearly outside ROOT — old model blocked this; now the
+        // permission pipeline gates it, so validateExecCommand must return null.
+        expect(validateExecCommand("cat /other/x.txt", ROOT)).toBeNull();
+    });
+    it("output redirection to outside workspace is NOT hard-blocked", () => {
+        // Old model blocked redirections outside workspace; pipeline now owns that.
+        expect(validateExecCommand("echo hi > /other/x.txt", ROOT)).toBeNull();
+    });
+    it("still blocks redirection to device paths (absolute floor)", () => {
+        expect(validateExecCommand("echo x > /dev/sda", ROOT)).toMatch(/device|system|blocked/i);
+    });
+    it("still blocks commands referencing /proc device paths", () => {
+        expect(validateExecCommand("cat /proc/self/mem", ROOT)).toMatch(/device|system|blocked/i);
+    });
+    it("still blocks commands referencing /sys paths", () => {
+        expect(validateExecCommand("ls /sys/kernel", ROOT)).toMatch(/device|system|blocked/i);
+    });
+    it("allows /dev/null (standard null device)", () => {
+        expect(validateExecCommand("ls 2>/dev/null", ROOT)).toBeNull();
+    });
+    it("allows commands with in-workspace paths", () => {
+        expect(validateExecCommand("cat src/a.ts", ROOT)).toBeNull();
+    });
+    it("allows simple commands with no paths", () => {
+        expect(validateExecCommand("echo hello", ROOT)).toBeNull();
+    });
+});
+describe("validateExecCommand — group-sensitive file gate (parity with file tools)", () => {
+    const ROOT = path.join(os.tmpdir(), "qla-exec-group-root");
+    afterEach(() => setGroupSecurityMode(false));
+    it("blocks reading .env via exec in group mode", () => {
+        setBootstrapWorkdir(ROOT);
+        setGroupSecurityMode(true);
+        expect(validateExecCommand("cat .env", ROOT)).toMatch(/group-sensitive/i);
+        expect(validateExecCommand("cat ./config/.env", ROOT)).toMatch(/group-sensitive/i);
+    });
+    it("blocks reading key/credential files via exec in group mode", () => {
+        setBootstrapWorkdir(ROOT);
+        setGroupSecurityMode(true);
+        expect(validateExecCommand("head id_rsa", ROOT)).toMatch(/group-sensitive/i);
+        expect(validateExecCommand("cp secrets/server.key /tmp/", ROOT)).toMatch(/group-sensitive/i);
+        expect(validateExecCommand("grep -r token credentials.json", ROOT)).toMatch(/group-sensitive/i);
+    });
+    it("blocks writing a sensitive file via redirection in group mode", () => {
+        setBootstrapWorkdir(ROOT);
+        setGroupSecurityMode(true);
+        expect(validateExecCommand("echo x > config/app.pem", ROOT)).toMatch(/group-sensitive/i);
+    });
+    it("allows the same commands when NOT in group mode", () => {
+        setBootstrapWorkdir(ROOT);
+        setGroupSecurityMode(false);
+        expect(validateExecCommand("cat .env", ROOT)).toBeNull();
+        expect(validateExecCommand("head id_rsa", ROOT)).toBeNull();
+    });
+    it("allows non-sensitive commands in group mode", () => {
+        setBootstrapWorkdir(ROOT);
+        setGroupSecurityMode(true);
+        expect(validateExecCommand("npm test", ROOT)).toBeNull();
+        expect(validateExecCommand("cat src/index.ts", ROOT)).toBeNull();
+        expect(validateExecCommand("ls -la", ROOT)).toBeNull();
+    });
+});

package/dist/cli/tool-catalog.d.ts

@@ -0,0 +1,4 @@
+import type { ToolBootstrap, ToolCatalog } from "../runtime/ports/index.js";
+import { type ToolRegistry } from "./tool-registry-adapter.js";
+export declare function createCliToolCatalog(registry?: ToolRegistry): ToolCatalog;
+export declare function createCliToolBootstrap(toolCatalog?: ToolCatalog): ToolBootstrap;

package/dist/cli/tool-catalog.js

@@ -0,0 +1,14 @@
+import { getAllBaseTools, setBootstrapWorkdir } from "./tool-bootstrap.js";
+import { createToolCatalogFromRegistry } from "./tool-registry-adapter.js";
+export function createCliToolCatalog(registry) {
+    return createToolCatalogFromRegistry(registry);
+}
+export function createCliToolBootstrap(toolCatalog) {
+    return {
+        getAllBaseTools: (config) => getAllBaseTools({
+            ...config,
+            toolCatalog: config?.toolCatalog ?? toolCatalog,
+        }),
+        setWorkdir: setBootstrapWorkdir,
+    };
+}

package/dist/cli/tool-invoker-factory.d.ts

@@ -0,0 +1,12 @@
+import type { ToolInvoker } from "../agent/types.js";
+import type { NotificationMethod, NotificationMethodMap } from "../protocol/notifications.js";
+import type { MediaPersistence } from "../runtime/infra/media-persistence.js";
+import type { ToolCatalog } from "../runtime/ports/index.js";
+export interface LocalToolInvokerDeps {
+    mediaPersistence: MediaPersistence;
+    toolCatalog: ToolCatalog;
+    getSessionId(): string;
+    log(message: string): void;
+    sendNotification<M extends NotificationMethod>(method: M, params: NotificationMethodMap[M]): void;
+}
+export declare function createLocalToolInvoker(deps: LocalToolInvokerDeps): ToolInvoker;

package/dist/cli/tool-invoker-factory.js

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { runWithMediaOutputDir } from "./media-runtime-facade.js";
+import { processToolResult } from "./tool-result-processor.js";
+export function createLocalToolInvoker(deps) {
+    return {
+        invoke: async (turnId, name, args, signal) => {
+            if (name.startsWith("$")) {
+                return { result: args };
+            }
+            const localTool = deps.toolCatalog.findTool(name);
+            if (!localTool) {
+                return { result: "", error: `Unknown tool: ${name}` };
+            }
+            if (typeof localTool.execute !== "function") {
+                return { result: "", error: `Tool is not executable: ${name}` };
+            }
+            const executeTool = localTool.execute;
+            const callId = `tc_${randomUUID().slice(0, 8)}`;
+            try {
+                const parsedArgs = JSON.parse(args);
+                const sessionId = deps.getSessionId();
+                let mediaOutputDir;
+                try {
+                    mediaOutputDir = deps.mediaPersistence.getMediaDir();
+                }
+                catch {
+                    mediaOutputDir = undefined;
+                }
+                const result = await runWithMediaOutputDir(mediaOutputDir, () => executeTool(callId, parsedArgs, signal));
+                return await processToolResult({
+                    turnId,
+                    sessionId,
+                    result,
+                    mediaPersistence: deps.mediaPersistence,
+                    log: deps.log,
+                    sendNotification: (method, params) => deps.sendNotification(method, params),
+                });
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                return { result: "", error: errMsg };
+            }
+        },
+    };
+}

package/dist/cli/tool-registration-modules.contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/tool-registration-modules.contract.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { coreToolRegistrationModule } from "./core-tool-coordinator.js";
+import { devToolRegistrationModule } from "./dev-tool-bootstrap.js";
+import { localCoreToolRegistrationModule } from "./tool-bootstrap-core-registration.js";
+import { localWebToolRegistrationModule } from "./tool-bootstrap-web-registration.js";
+import { localWorkflowToolRegistrationModule } from "./tool-bootstrap-workflow-registration.js";
+import { localMediaToolRegistrationModule } from "./tool-bootstrap-media-registration.js";
+import { mcpToolRegistrationModule } from "./mcp-bootstrap.js";
+import { pluginToolRegistrationModule } from "./plugin-bootstrap.js";
+import { skillMetaToolRegistrationModule } from "./skill-meta-tool-bootstrap.js";
+const modules = [
+    { name: "core", module: coreToolRegistrationModule, kind: "core" },
+    { name: "dev", module: devToolRegistrationModule, kind: "dev" },
+    { name: "local-core", module: localCoreToolRegistrationModule, kind: "core" },
+    { name: "web", module: localWebToolRegistrationModule, kind: "web" },
+    { name: "workflow", module: localWorkflowToolRegistrationModule, kind: "workflow" },
+    { name: "media", module: localMediaToolRegistrationModule, kind: "media" },
+    { name: "mcp", module: mcpToolRegistrationModule, kind: "mcp" },
+    { name: "plugin", module: pluginToolRegistrationModule, kind: "plugin" },
+    { name: "skill", module: skillMetaToolRegistrationModule, kind: "skill" },
+];
+describe("tool registration module contract", () => {
+    it("keeps every bootstrap family behind the same module shape", () => {
+        const ids = new Set();
+        for (const entry of modules) {
+            expect(entry.module.id, entry.name).toEqual(expect.any(String));
+            expect(entry.module.id.length, entry.name).toBeGreaterThan(0);
+            expect(ids.has(entry.module.id), entry.name).toBe(false);
+            expect(entry.module.kind, entry.name).toBe(entry.kind);
+            expect(entry.module.register, entry.name).toEqual(expect.any(Function));
+            ids.add(entry.module.id);
+        }
+    });
+    it("keeps local registration modules responsible for their own domain deps", () => {
+        const noop = () => { };
+        const projectRoot = process.cwd();
+        const coreTools = [];
+        localCoreToolRegistrationModule.register({
+            tools: coreTools,
+            backgroundTaskRuntime: null,
+            askUserCallback: null,
+            getCwd: () => projectRoot,
+            activeProjectRoot: () => projectRoot,
+            resolveSandboxConfig: () => undefined,
+            listToolNames: () => [],
+            findRegisteredTool: () => undefined,
+            activateRegisteredTool: () => false,
+            isGroupSecurityMode: () => false,
+            log: { info: noop, warn: noop },
+        });
+        expect(coreTools.map((tool) => tool.name)).toEqual(expect.arrayContaining([
+            "read",
+            "write",
+            "search",
+            "instructions",
+            "tool_search",
+        ]));
+        const webTools = [];
+        localWebToolRegistrationModule.register({ tools: webTools });
+        expect(webTools.map((tool) => tool.name)).toEqual(expect.arrayContaining(["web_fetch", "web_search"]));
+        const workflowTools = [];
+        localWorkflowToolRegistrationModule.register({
+            tools: workflowTools,
+            activeProjectRoot: () => projectRoot,
+        });
+        expect(workflowTools.map((tool) => tool.name)).toContain("workflow");
+        const mediaTools = [];
+        localMediaToolRegistrationModule.register({
+            tools: mediaTools,
+            getCwd: () => projectRoot,
+            activeProjectRoot: () => projectRoot,
+        });
+        expect(mediaTools.map((tool) => tool.name)).toEqual(expect.arrayContaining(["image_generate", "file_upload"]));
+    });
+});

package/dist/cli/tool-registry-adapter.d.ts

@@ -0,0 +1,5 @@
+import { type ToolRegistry } from "../skills/tools.js";
+import type { ToolCatalog } from "../runtime/ports/index.js";
+export type { ToolRegistry };
+export declare function createToolCatalogFromRegistry(registry?: ToolRegistry): ToolCatalog;
+export declare function createLegacyToolCatalog(): ToolCatalog;

package/dist/cli/tool-registry-adapter.js

@@ -0,0 +1,27 @@
+import { activateTool, addTool, addTools, clearActivatedTools, findTool, getDefaultToolRegistry, getToolManifest, getToolNames, removeTool, setToolPool, } from "../skills/tools.js";
+export function createToolCatalogFromRegistry(registry = getDefaultToolRegistry()) {
+    return {
+        findTool: (name) => registry.findTool(name),
+        getToolManifest: (includeDeferred) => registry.getToolManifest(includeDeferred),
+        getToolNames: () => registry.getToolNames(),
+        setTools: (tools) => registry.setTools(tools),
+        addTool: (tool) => registry.addTool(tool),
+        addTools: (tools) => registry.addTools(tools),
+        removeTool: (name) => registry.removeTool(name),
+        activateTool: (name) => registry.activateTool(name),
+        clearActivatedTools: () => registry.clearActivatedTools(),
+    };
+}
+export function createLegacyToolCatalog() {
+    return {
+        findTool: (name) => findTool(name),
+        getToolManifest: (includeDeferred) => getToolManifest(includeDeferred),
+        getToolNames: () => getToolNames(),
+        setTools: (tools) => setToolPool(tools),
+        addTool: (tool) => addTool(tool),
+        addTools: (tools) => addTools(tools),
+        removeTool: (name) => removeTool(name),
+        activateTool: (name) => activateTool(name),
+        clearActivatedTools: () => clearActivatedTools(),
+    };
+}

package/dist/cli/tool-result-processor.d.ts

@@ -0,0 +1,14 @@
+import type { ToolInvoker } from "../agent/types.js";
+import { type MediaPersistence } from "../runtime/infra/media-persistence.js";
+import type { PortableToolResult } from "../skills/portable-tool.js";
+type ToolInvokeResult = Awaited<ReturnType<ToolInvoker["invoke"]>>;
+export interface ToolResultProcessorDeps {
+    turnId: string;
+    sessionId?: string;
+    result: PortableToolResult;
+    mediaPersistence: MediaPersistence;
+    log(message: string): void;
+    sendNotification(method: string, params: unknown): void;
+}
+export declare function processToolResult(deps: ToolResultProcessorDeps): Promise<ToolInvokeResult>;
+export {};

package/dist/cli/tool-result-processor.js

@@ -0,0 +1,83 @@
+import { toFileMediaUrl } from "../runtime/infra/media-persistence.js";
+export async function processToolResult(deps) {
+    const inlineImageUrls = [];
+    let resultText = deps.result.content
+        .map(content => {
+        if (content.type === "image" && content.data) {
+            const mime = content.mimeType || "image/png";
+            inlineImageUrls.push(`data:${mime};base64,${content.data}`);
+            return "[Image]";
+        }
+        return content.text ?? "";
+    })
+        .join("\n");
+    const imageUrls = inlineImageUrls.length > 0
+        ? [...inlineImageUrls, ...(deps.result.imageUrls ?? [])]
+        : deps.result.imageUrls;
+    const errorClassification = deps.result.details?.error;
+    const error = errorClassification ? resultText : undefined;
+    const detailsType = deps.result.details?.type;
+    const nextDetails = deps.result.details ? { ...deps.result.details } : undefined;
+    let mediaBaseType = detailsType?.split("_")[0];
+    if (detailsType === "three_d_generate")
+        mediaBaseType = "3d";
+    if (mediaBaseType && ["image", "tts", "video", "music", "3d"].includes(mediaBaseType)) {
+        let mediaUrls = deps.result.details?.mediaUrls ?? [];
+        if (mediaUrls.length > 0) {
+            try {
+                const downloads = await deps.mediaPersistence.downloadAll(mediaUrls, { type: mediaBaseType, sessionId: deps.sessionId || undefined }, { warn: (message) => deps.log(message) });
+                if (downloads.length > 0) {
+                    const persistedUrlByRemote = new Map(downloads.map(download => [download.remoteUrl, toFileMediaUrl(download.localPath)]));
+                    for (const download of downloads) {
+                        resultText = resultText.replaceAll(download.remoteUrl, download.localPath);
+                    }
+                    mediaUrls = mediaUrls.map(url => persistedUrlByRemote.get(url) ?? url);
+                    deps.sendNotification("turn.media_persisted", {
+                        turnId: deps.turnId,
+                        files: downloads.map(download => ({
+                            remoteUrl: download.remoteUrl,
+                            localPath: download.localPath,
+                            bytes: download.bytes,
+                            mimeType: download.mimeType,
+                        })),
+                    });
+                }
+            }
+            catch {
+                // Media persistence is best-effort; tool execution remains authoritative.
+            }
+        }
+        if (nextDetails)
+            nextDetails.mediaUrls = mediaUrls;
+    }
+    if (detailsType === "task" && !errorClassification && deps.result.details?.taskList) {
+        try {
+            const taskDetails = deps.result.details;
+            if (taskDetails?.taskList) {
+                deps.sendNotification("turn.todos_updated", {
+                    turnId: deps.turnId,
+                    items: taskDetails.taskList,
+                    summary: {
+                        total: taskDetails.total ?? taskDetails.taskList.length,
+                        completed: taskDetails.completed ?? 0,
+                        inProgress: taskDetails.inProgress ?? 0,
+                        notStarted: taskDetails.notStarted ?? 0,
+                    },
+                });
+            }
+        }
+        catch {
+            // Best-effort notification; never mask the tool result.
+        }
+    }
+    const toolReferences = Array.isArray(deps.result.details?.matches)
+        ? deps.result.details.matches
+        : undefined;
+    return {
+        result: resultText,
+        error,
+        toolReferences,
+        imageUrls,
+        details: nextDetails,
+    };
+}

package/dist/cli/tool-result-processor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/tool-result-processor.test.js

@@ -0,0 +1,69 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, it } from "vitest";
+import { MediaPersistence } from "../runtime/infra/media-persistence.js";
+import { processToolResult } from "./tool-result-processor.js";
+describe("processToolResult media persistence", () => {
+    it("copies local media into the session media directory and returns persisted media details", async () => {
+        const projectDir = mkdtempSync(join(tmpdir(), "qlogicagent-media-project-"));
+        const sourceDir = mkdtempSync(join(tmpdir(), "qlogicagent-media-source-"));
+        const sourcePath = join(sourceDir, "voice.wav");
+        writeFileSync(sourcePath, Buffer.from([1, 2, 3, 4]));
+        const notifications = [];
+        const result = await processToolResult({
+            turnId: "turn-1",
+            sessionId: "session-1",
+            mediaPersistence: new MediaPersistence({ projectDir }),
+            result: {
+                content: [{ type: "text", text: `audio: ${pathToFileURL(sourcePath).href}` }],
+                details: {
+                    type: "tts",
+                    provider: "zhipu",
+                    model: "glm-tts",
+                    mediaUrls: [pathToFileURL(sourcePath).href],
+                },
+            },
+            log() { },
+            sendNotification(method, params) {
+                notifications.push({ method, params: params });
+            },
+        });
+        expect(notifications.map(notification => notification.method)).toEqual(["turn.media_persisted"]);
+        const persisted = notifications[0].params.files;
+        expect(persisted).toHaveLength(1);
+        expect(persisted[0].localPath).toContain(join(projectDir, "assets", "audio"));
+        expect(readFileSync(persisted[0].localPath)).toEqual(Buffer.from([1, 2, 3, 4]));
+        expect(result.result).toContain(persisted[0].localPath);
+        expect((result.details?.mediaUrls)[0]).toBe(pathToFileURL(persisted[0].localPath).href);
+    });
+    it("persists data URL media into the session media directory", async () => {
+        const projectDir = mkdtempSync(join(tmpdir(), "qlogicagent-data-media-project-"));
+        const dataUrl = `data:audio/wav;base64,${Buffer.from([5, 6, 7]).toString("base64")}`;
+        const notifications = [];
+        const result = await processToolResult({
+            turnId: "turn-2",
+            sessionId: "session-2",
+            mediaPersistence: new MediaPersistence({ projectDir }),
+            result: {
+                content: [{ type: "text", text: "audio generated" }],
+                details: {
+                    type: "tts",
+                    provider: "gemini",
+                    model: "gemini-tts",
+                    mediaUrls: [dataUrl],
+                },
+            },
+            log() { },
+            sendNotification(method, params) {
+                notifications.push({ method, params: params });
+            },
+        });
+        const persisted = notifications[0].params.files;
+        expect(persisted[0].localPath).toContain(join(projectDir, "assets", "audio"));
+        expect(readFileSync(persisted[0].localPath)).toEqual(Buffer.from([5, 6, 7]));
+        expect(notifications.map(notification => notification.method)).toEqual(["turn.media_persisted"]);
+        expect((result.details?.mediaUrls)[0]).toBe(pathToFileURL(persisted[0].localPath).href);
+    });
+});

package/dist/cli/transport.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transport — abstract I/O layer for JSON-RPC message exchange.
+ *
+ * Decouples the agent protocol handler from the physical transport
+ * (stdin/stdout, WebSocket, Unix Domain Socket, etc.).
+ *
+ * Each transport reads incoming JSON-RPC messages and emits them
+ * to a registered handler; outgoing messages are sent via send().
+ */
+import type { Transport } from "../transport/io-transport.js";
+export type { Transport } from "../transport/io-transport.js";
+/**
+ * Line-delimited JSON over stdin/stdout.
+ * Each line on stdin is a JSON message; each send() writes one JSON line to stdout.
+ * All diagnostic logging goes to stderr.
+ */
+export declare class StdioTransport implements Transport {
+    private messageHandler;
+    private closeHandler;
+    private verbose;
+    constructor(opts?: {
+        verbose?: boolean;
+    });
+    onMessage(handler: (msg: unknown) => void): void;
+    onClose(handler: () => void): void;
+    send(msg: unknown): void;
+    start(): void;
+    close(): void;
+    private log;
+}

package/dist/cli/transport.js

@@ -0,0 +1,68 @@
+/**
+ * Transport — abstract I/O layer for JSON-RPC message exchange.
+ *
+ * Decouples the agent protocol handler from the physical transport
+ * (stdin/stdout, WebSocket, Unix Domain Socket, etc.).
+ *
+ * Each transport reads incoming JSON-RPC messages and emits them
+ * to a registered handler; outgoing messages are sent via send().
+ */
+import { createInterface } from "node:readline";
+// ── StdioTransport ──────────────────────────────────────────
+/**
+ * Line-delimited JSON over stdin/stdout.
+ * Each line on stdin is a JSON message; each send() writes one JSON line to stdout.
+ * All diagnostic logging goes to stderr.
+ */
+export class StdioTransport {
+    messageHandler = null;
+    closeHandler = null;
+    verbose;
+    constructor(opts) {
+        this.verbose = opts?.verbose ?? false;
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
+    send(msg) {
+        process.stdout.write(`${JSON.stringify(msg)}\n`);
+    }
+    start() {
+        // Diagnostic: log raw stdin data events to detect if data arrives at all
+        process.stdin.on("data", (chunk) => {
+            process.stderr.write(`[transport] raw stdin data (${chunk.length} bytes): ${chunk.toString().slice(0, 300)}\n`);
+        });
+        const rl = createInterface({
+            input: process.stdin,
+            crlfDelay: Number.POSITIVE_INFINITY,
+        });
+        rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            process.stderr.write(`[transport] line: ${trimmed.slice(0, 300)}\n`);
+            try {
+                const parsed = JSON.parse(trimmed);
+                this.messageHandler?.(parsed);
+            }
+            catch {
+                process.stderr.write(`[transport] invalid JSON on stdin: ${trimmed.slice(0, 200)}\n`);
+            }
+        });
+        rl.on("close", () => {
+            this.closeHandler?.();
+        });
+    }
+    close() {
+        // stdin-based transport doesn't actively close the stream;
+        // the process exit handles cleanup.
+    }
+    log(message) {
+        if (this.verbose) {
+            process.stderr.write(`[transport] ${message}\n`);
+        }
+    }
+}

package/dist/cli/tunable-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tunable override store — the SINGLE write/read path for settings.tunables.
+ *
+ * Shared by the config.updateTunable RPC (UI settings page) and the `config`
+ * tool (conversational tuning), so both go through identical validation,
+ * persistence, and runtime sync. Values are hot: ModelRegistry.getTunable()
+ * re-reads settings.json on every call, so a persisted override takes effect
+ * on the next read with no restart.
+ */
+import { type TunableDefaults } from "../runtime/config/tunable-defaults.js";
+/** Read the current override map from settings.json (missing file → empty). */
+export declare function readTunableOverrides(settingsPath: string): Record<string, unknown>;
+/**
+ * Validate a tunable update against the declared defaults.
+ * Returns an error message, or null when the update is acceptable.
+ * Coercible values ("3" → 3, "true" → true) are NOT accepted here —
+ * callers wanting leniency must coerce before validating.
+ */
+export declare function validateTunableUpdate(key: string, value: unknown): string | null;
+/** Coerce a string value toward the tunable's declared type ("3"→3, "true"→true). */
+export declare function coerceTunableValue(key: string, value: unknown): unknown;
+/** Persist one override into settings.json and sync live runtime state. */
+export declare function writeTunableOverride(settingsPath: string, key: string, value: unknown): Promise<void>;
+/** Remove one override (value falls back to the declared default). */
+export declare function clearTunableOverride(settingsPath: string, key: string): Promise<void>;
+export type { TunableDefaults };