@dinoxx/dinox-cli 2.11.0 → 2.13.0

package/README.md

@@ -103,7 +103,7 @@ winget install OpenJS.NodeJS.LTS
 dino update
 ```
 
-它会自动根据你当前的安装方式选择合适的包管理器执行更新。升级完成后会检查本机已安装的 Agent：有 `claude` 但没有 ACP 命令时安装 `@agentclientprotocol/claude-agent-acp`，有 `codex` 时安装 `@agentclientprotocol/codex-acp`，有 `zcode` 时安装 `zcode-acp`。已经装过的适配器会跳过；某个适配器安装失败只给出警告，不影响 CLI 升级本身。
+它会自动根据你当前的安装方式选择合适的包管理器执行更新。升级完成后会检查本机已安装的 Agent：有 `claude` 但没有 ACP 命令时安装 `@agentclientprotocol/claude-agent-acp`，有 `codex` 时安装 `@agentclientprotocol/codex-acp`，有 `zcode` 时安装 `zcode-acp`，有 `pi` 时安装 `pi-acp`，有 `agy` 时安装 `agy-acp`，有 `muse` 时安装 `@bex-co/muse-code-acp`。已经装过的适配器会跳过；某个适配器安装失败只给出警告，不影响 CLI 升级本身。
 
 ---
 
@@ -947,7 +947,7 @@ dino gateway reload
 dino gateway remove Hermes
 ```
 
-`detect` 会在 `PATH` 上查找 ACP agent，并用真实握手确认能否启动。覆盖范围与 [Paseo 的 ACP catalog](https://github.com/getpaseo/paseo/blob/main/packages/app/src/data/acp-provider-catalog.ts) 对齐，只认本机已经装好的命令，不会为了探测去 `npx -y` 下载。每个 agent 一握手完就打印，不用等最慢的那个。某个启动方式一直不应答时，不再换参数重试。`--add` 把已确认的 agent 写入当前账号的 gateway 配置，并由 daemon 托管。`gateway list` 只显示环境变量名，不显示值。`dino gateway mcp` 由这些 agent 拉起，对外提供只读的 Dinox 知识工具。
+`detect` 会在 `PATH` 上查找 ACP agent，并用真实握手确认能否启动。覆盖范围与 [Paseo 的 ACP catalog](https://github.com/getpaseo/paseo/blob/main/packages/app/src/data/acp-provider-catalog.ts) 对齐，另外包含 Pi（`pi-acp`）、Antigravity（`agy-acp`）、Muse Code（`muse-code-acp`）和 OMP（`omp acp`）。只认本机已经装好的命令，不会为了探测去 `npx -y` 下载。每个 agent 一握手完就打印，不用等最慢的那个。某个启动方式一直不应答时，不再换参数重试。`--add` 把已确认的 agent 写入当前账号的 gateway 配置，并由 daemon 托管。`gateway list` 只显示环境变量名，不显示值。`dino gateway mcp` 由这些 agent 拉起，对外提供笔记、待办、标签、卡片盒等读写工具，以及把本机文件放进回复的 `send_file`。账号、同步、守护进程和 gateway 自身的命令不在这套工具里。
 
 ### 6.16 `info`：查看版本与技能仓库地址
 

package/dist/commands/gateway/index.js

@@ -5,7 +5,6 @@ import { autoInstallDaemonService, describeDaemonServiceAutoInstall } from '../.
 import { loadConfig } from '../../config/store.js';
 import { addGateway, adoptDetectedAgent, getGatewaysFilePath, loadGateways, removeGateway, } from '../../gateway/config.js';
 import { detectAcpAgents, inferAgentId } from '../../gateway/detect.js';
-import { serveDinoxMcpOverStdio } from '../../gateway/mcpServer.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printHumanReadableWarning, printSuccess, } from '../../utils/output.js';
 import { registerCommandGroup } from '../descriptor/register.js';
@@ -307,7 +306,7 @@ export const gatewayCommandGroup = {
         },
         {
             name: 'mcp',
-            description: 'Serve Dinox tools over stdio MCP: read-only knowledge tools and send_file (started by gateway agents)',
+            description: 'Serve Dinox tools over stdio MCP: full read/write knowledge tools and send_file (started by gateway agents)',
             schema: {
                 path: 'gateway.mcp',
                 risk: 'read',
@@ -316,7 +315,10 @@ export const gatewayCommandGroup = {
                 output: { type: 'structured', summary: 'MCP JSON-RPC over stdio until stdin closes', fields: [] },
                 examples: ['dino gateway mcp'],
             },
-            action: serveDinoxMcpOverStdio,
+            action: async () => {
+                const { serveDinoxMcpOverStdio } = await import('../../gateway/mcpServer.js');
+                await serveDinoxMcpOverStdio();
+            },
         },
         {
             name: 'reload',

package/dist/gateway/adapters/index.js

@@ -1,4 +1,4 @@
-import { GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from '../mcpEnv.js';
+import { DINOX_MCP_SERVER_NAME, GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from '../mcpEnv.js';
 import { AcpGatewayAdapter } from './acp.js';
 import { EchoGatewayAdapter } from './echo.js';
 /**
@@ -15,7 +15,7 @@ export function dinoxMcpServerConfig(options) {
         entry[0] !== GATEWAY_KNOWLEDGE_TOOLS_ENV &&
         typeof entry[1] === 'string');
     return {
-        name: 'dinox',
+        name: DINOX_MCP_SERVER_NAME,
         command: process.execPath,
         args: [...process.execArgv, entrypoint, 'gateway', 'mcp'],
         env: [

package/dist/gateway/detect.js

@@ -29,7 +29,12 @@ export const KNOWN_ACP_AGENTS = [
     { id: 'copilot', name: 'GitHub Copilot', candidates: [['copilot', '--acp']] },
     { id: 'cursor', name: 'Cursor Agent', candidates: [['cursor-agent', 'acp']] },
     { id: 'opencode', name: 'OpenCode', candidates: [['opencode', 'acp']] },
-    { id: 'pi', name: 'pi', candidates: [['pi-acp']] },
+    {
+        id: 'pi',
+        name: 'pi',
+        candidates: [['pi-acp']],
+        adapter: { baseBinary: 'pi', packageName: 'pi-acp' },
+    },
     { id: 'goose', name: 'Goose', candidates: [['goose', 'acp']] },
     { id: 'qwen', name: 'Qwen Code', candidates: [['qwen', '--acp'], ['qwen', '--acp', '--experimental-skills'], ['qwen', '--experimental-acp']] },
     { id: 'kimi', name: 'Kimi Code CLI', candidates: [['kimi', 'acp'], ['kimi', '--acp']] },
@@ -43,7 +48,21 @@ export const KNOWN_ACP_AGENTS = [
         adapter: { baseBinary: 'zcode', packageName: 'zcode-acp' },
     },
     // Launch lines follow Paseo's ACP catalog (packages/app/src/data/acp-provider-catalog.ts).
+    // Pi, Antigravity, Muse, and OMP are native in Paseo; here they run through ACP adapters.
     // Local binaries only: detect must not run `npx -y`, which would download a package just to probe it.
+    {
+        id: 'antigravity',
+        name: 'Antigravity',
+        candidates: [['agy-acp']],
+        adapter: { baseBinary: 'agy', packageName: 'agy-acp' },
+    },
+    {
+        id: 'muse',
+        name: 'Muse Code',
+        candidates: [['muse-code-acp'], ['muse-acp']],
+        adapter: { baseBinary: 'muse', packageName: '@bex-co/muse-code-acp' },
+    },
+    { id: 'omp', name: 'OMP', candidates: [['omp', 'acp'], ['omp-acp']] },
     { id: 'amp', name: 'Amp', candidates: [['amp-acp']] },
     {
         id: 'auggie',

package/dist/gateway/mcpCommandTools.d.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { CommandSchema } from '../commands/schema/types.js';
+/**
+ * One MCP tool per command group, generated from the command schemas. Each runs
+ * the real CLI as a child process without a shell, preserving the CLI's own
+ * validation, dry-run and confirmation guards. Approval belongs to the agent's
+ * permission flow, guided by the tool annotations.
+ */
+/** Command groups exposed as MCP tools. */
+export declare const MCP_COMMAND_GROUPS: readonly ["note", "tag", "box", "todo", "view", "prop", "template", "prompt", "graph", "storage", "meta.stats"];
+/** Commands deliberately excluded from the MCP surface. */
+export declare const MCP_COMMAND_EXCLUSIONS: readonly ["auth.*", "config.*", "daemon.*", "gateway.*", "doctor", "skills.*", "update", "sync", "info", "schema", "meta.schema"];
+/** Runs a CLI invocation and captures its output. */
+export type CommandRunner = (argv: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/** Runs the current CLI entry point without a shell. */
+export declare const runCliCommand: CommandRunner;
+/** Validates tool inputs and builds CLI arguments in schema order. */
+export declare function commandArgv(schema: CommandSchema, input: Record<string, unknown>): string[];
+/** Builds grouped MCP tool definitions from the command schemas. */
+export declare function commandToolDefinitions(): {
+    name: string;
+    commands: CommandSchema[];
+    config: {
+        description: string;
+        annotations: {
+            openWorldHint: boolean;
+            destructiveHint?: boolean | undefined;
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            action: z.ZodEnum<{
+                [x: string]: string;
+            }>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        };
+    };
+}[];
+/** Registers command tools using the real CLI or an injected runner. */
+export declare function registerCommandTools(server: McpServer, runner?: CommandRunner): void;

package/dist/gateway/mcpCommandTools.js

@@ -0,0 +1,179 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { listCommandSchemas } from '../commands/schema/spec.js';
+/**
+ * One MCP tool per command group, generated from the command schemas. Each runs
+ * the real CLI as a child process without a shell, preserving the CLI's own
+ * validation, dry-run and confirmation guards. Approval belongs to the agent's
+ * permission flow, guided by the tool annotations.
+ */
+/** Command groups exposed as MCP tools. */
+export const MCP_COMMAND_GROUPS = [
+    'note', 'tag', 'box', 'todo', 'view', 'prop', 'template', 'prompt', 'graph', 'storage', 'meta.stats',
+];
+/** Commands deliberately excluded from the MCP surface. */
+export const MCP_COMMAND_EXCLUSIONS = [
+    'auth.*', 'config.*', 'daemon.*', 'gateway.*', 'doctor', 'skills.*', 'update', 'sync', 'info', 'schema', 'meta.schema',
+];
+const execute = promisify(execFile);
+/** Runs the current CLI entry point without a shell. */
+export const runCliCommand = (argv) => {
+    const entryPoint = process.argv[1];
+    if (entryPoint === undefined)
+        throw new Error('Cannot run CLI command: process.argv[1] is undefined');
+    return execute(process.execPath, [...process.execArgv, entryPoint, ...argv], {
+        env: process.env,
+        timeout: 120_000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+};
+function key(name) {
+    return name
+        .replace(/^[<[.]+|[>\].]+$/g, '')
+        .replace(/[-_]+([a-zA-Z0-9])/g, (_match, letter) => letter.toUpperCase());
+}
+function flag(name) {
+    return name.match(/--[\w-]+/)[0];
+}
+function optionKey(name) {
+    return key(flag(name).replace(/^--(?:no-)?/, ''));
+}
+function text(value) {
+    return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
+}
+function parse(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function actionName(schema) {
+    return schema.path.split('.').slice(1).join('.');
+}
+function optionType(option) {
+    return option.type ?? (/[<[]/.test(option.name) ? 'string' : 'boolean');
+}
+function describeAction(schema) {
+    const args = (schema.arguments ?? []).map((arg) => `${key(arg.name)}:string${arg.required ? '!' : '?'}`);
+    const options = (schema.options ?? []).map((option) => {
+        const required = option.required ? '!' : '?';
+        const choices = option.enum ? `(${option.enum.join('|')})` : '';
+        return `${optionKey(option.name)}:${optionType(option)}${required}${choices}`;
+    });
+    const inputs = [...args, ...options].join(' ') || '(no input)';
+    return `${actionName(schema)} [${schema.risk}]: ${schema.summary}\n${inputs}`;
+}
+function toolAnnotations(commands) {
+    const readOnly = commands.every((schema) => schema.risk === 'read');
+    return {
+        readOnlyHint: readOnly,
+        ...(!readOnly ? { destructiveHint: commands.some((schema) => schema.risk === 'high-risk-write') } : {}),
+    };
+}
+/** Validates tool inputs and builds CLI arguments in schema order. */
+export function commandArgv(schema, input) {
+    const args = schema.arguments ?? [];
+    const options = schema.options ?? [];
+    const allowed = new Set([...args.map((arg) => key(arg.name)), ...options.map((option) => optionKey(option.name))]);
+    for (const name of Object.keys(input)) {
+        if (!allowed.has(name))
+            throw new Error(`Unknown input key: ${name}`);
+    }
+    const positionals = [];
+    let omitted = false;
+    for (const arg of args) {
+        const value = input[key(arg.name)];
+        if (value === undefined) {
+            if (arg.required)
+                throw new Error(`Missing required argument: ${key(arg.name)}`);
+            omitted = true;
+        }
+        else {
+            if (typeof value !== 'string' || omitted)
+                throw new Error(`Invalid positional argument: ${key(arg.name)}`);
+            positionals.push(value);
+        }
+    }
+    const flags = [];
+    for (const option of options) {
+        const name = optionKey(option.name);
+        const value = input[name];
+        if (value === undefined) {
+            if (option.required)
+                throw new Error(`Missing required option: ${name}`);
+            continue;
+        }
+        const type = optionType(option);
+        const valid = type === 'string[]'
+            ? Array.isArray(value) && value.every((item) => typeof item === 'string')
+            : typeof value === type && (type !== 'number' || Number.isFinite(value));
+        if (!valid || (option.enum && !option.enum.includes(String(value))))
+            throw new Error(`Invalid value for ${name} (${type})`);
+        const long = flag(option.name);
+        if (type === 'boolean') {
+            if (long.startsWith('--no-')) {
+                if (value === false)
+                    flags.push(long);
+            }
+            else if (value === true) {
+                flags.push(long);
+            }
+        }
+        else if (Array.isArray(value)) {
+            // --fields is CSV; the other array descriptors use repeatable collectors.
+            if (long === '--fields') {
+                flags.push(`${long}=${value.join(',')}`);
+            }
+            else {
+                for (const item of value)
+                    flags.push(`${long}=${String(item)}`);
+            }
+        }
+        else {
+            flags.push(`${long}=${String(value)}`);
+        }
+    }
+    return [...schema.path.split('.'), ...flags, '--format', 'json', '--', ...positionals];
+}
+/** Builds grouped MCP tool definitions from the command schemas. */
+export function commandToolDefinitions() {
+    return MCP_COMMAND_GROUPS.map((group) => {
+        const commands = listCommandSchemas().filter((schema) => group === 'meta.stats' ? schema.path === group : schema.path.startsWith(`${group}.`));
+        const actions = commands.map(actionName);
+        const description = 'Dinox CLI commands. search_notes/read_note/search_todos/related_notes are the fast daemon-backed path for plain search/read. ' +
+            'High-risk writes need dryRun: true first, then the CLI confirmation options listed below (e.g. confirm/expectedCount); ' +
+            'CLI guards enforce them. Input keys are camelCase.\n' +
+            commands.map(describeAction).join('\n');
+        return {
+            name: group === 'meta.stats' ? 'dinox_stats' : `dinox_${group}`,
+            commands,
+            config: {
+                description,
+                annotations: { ...toolAnnotations(commands), openWorldHint: group === 'storage' },
+                inputSchema: { action: z.enum(actions), input: z.record(z.string(), z.unknown()).optional() },
+            },
+        };
+    });
+}
+/** Registers command tools using the real CLI or an injected runner. */
+export function registerCommandTools(server, runner = runCliCommand) {
+    for (const tool of commandToolDefinitions()) {
+        server.registerTool(tool.name, tool.config, async ({ action, input }) => {
+            try {
+                const schema = tool.commands.find((command) => actionName(command) === action);
+                if (!schema)
+                    throw new Error(`Unknown action: ${action}`);
+                const result = await runner(commandArgv(schema, input ?? {}));
+                return text(parse(result.stdout));
+            }
+            catch (error) {
+                const failure = error;
+                const message = failure.stdout?.trim() || failure.stderr?.trim() || failure.message || String(error);
+                return { ...text(parse(message)), isError: true };
+            }
+        });
+    }
+}

package/dist/gateway/mcpEnv.d.ts

@@ -3,3 +3,5 @@
 export declare const GATEWAY_SESSION_TOKEN_ENV = "DINOX_GATEWAY_SESSION_TOKEN";
 /** `0` offers only `send_file`: the owner turned the knowledge tools off. */
 export declare const GATEWAY_KNOWLEDGE_TOOLS_ENV = "DINOX_GATEWAY_KNOWLEDGE_TOOLS";
+/** Must not collide with MCP servers the user already registered with the agent. */
+export declare const DINOX_MCP_SERVER_NAME = "dinox-gateway";

package/dist/gateway/mcpEnv.js

@@ -3,3 +3,5 @@
 export const GATEWAY_SESSION_TOKEN_ENV = 'DINOX_GATEWAY_SESSION_TOKEN';
 /** `0` offers only `send_file`: the owner turned the knowledge tools off. */
 export const GATEWAY_KNOWLEDGE_TOOLS_ENV = 'DINOX_GATEWAY_KNOWLEDGE_TOOLS';
+/** Must not collide with MCP servers the user already registered with the agent. */
+export const DINOX_MCP_SERVER_NAME = 'dinox-gateway';

package/dist/gateway/mcpServer.d.ts

@@ -1,3 +1,4 @@
+import { type CommandRunner } from './mcpCommandTools.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export type DaemonCall = (method: string, params?: unknown, options?: {
     timeoutMs?: number;
@@ -5,6 +6,7 @@ export type DaemonCall = (method: string, params?: unknown, options?: {
 export type DinoxMcpOptions = {
     /** Offer the knowledge tools (notes, todos, conversations); default true. */
     knowledgeTools?: boolean;
+    commandRunner?: CommandRunner;
     /** The session `send_file` belongs to; absent, `send_file` is not offered. */
     sessionToken?: string;
     /** Resolves relative `send_file` paths; default the process directory. */

package/dist/gateway/mcpServer.js

@@ -1,17 +1,18 @@
 import path from 'node:path';
+import { registerCommandTools } from './mcpCommandTools.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { sendDaemonRequest } from '../daemon/client.js';
-import { GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from './mcpEnv.js';
+import { DINOX_MCP_SERVER_NAME, GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from './mcpEnv.js';
 import { READ_CONVERSATION_MAX_LIMIT } from './conversationContext.js';
 import { getPackageVersion } from '../utils/version.js';
 /**
  * Dinox tools for gateway agents, served over stdio MCP. The agent launches
- * this as a child process (`dino gateway mcp`); every call goes through the
- * daemon, which owns the database. The knowledge tools are read-only by
- * design: writes from a third-party agent would bypass the app's approval
- * flow. `send_file` only adds a file to the reply the agent is writing.
+ * this as a child process (`dino gateway mcp`). Curated reads use the daemon;
+ * command-group tools run the CLI and allow writes. Approval belongs to the
+ * agent's permission flow. Destructive actions are flagged by annotations and
+ * retain the CLI's dry-run/confirmation guards. `send_file` adds reply files.
  */
 const MAX_NOTE_CHARS = 20_000;
 const MAX_RESULTS = 50;
@@ -24,15 +25,18 @@ function failure(error) {
     return { ...text(`Dinox is unavailable: ${error instanceof Error ? error.message : String(error)}`), isError: true };
 }
 export function createDinoxMcpServer(call = (method, params, options) => sendDaemonRequest(method, params, options), options = {}) {
-    const server = new McpServer({ name: 'dinox', version: getPackageVersion() });
+    const server = new McpServer({ name: DINOX_MCP_SERVER_NAME, version: getPackageVersion() });
     if (options.sessionToken)
         registerSendFile(server, call, options.sessionToken, options.cwd ?? process.cwd());
-    if (options.knowledgeTools !== false)
+    if (options.knowledgeTools !== false) {
         registerKnowledgeTools(server, call);
+        registerCommandTools(server, options.commandRunner);
+    }
     return server;
 }
 function registerSendFile(server, call, sessionToken, cwd) {
     server.registerTool('send_file', {
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
         description: 'Show the user a file from this computer (an image you generated, a document, a chart, ...). The user talks to ' +
             'you from the Dinox app and cannot open files on this computer, so a path alone is useless to them: call this ' +
             'for every file they should see, then answer as usual. Images appear in the reply; other files as attachments. ' +
@@ -53,15 +57,18 @@ function registerSendFile(server, call, sessionToken, cwd) {
 }
 function registerKnowledgeTools(server, call) {
     server.registerTool('search_notes', {
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Search the user's Dinox notes by keyword. Returns id, title, summary, tags and folders; use read_note for full content.",
         inputSchema: {
             query: z.string().describe('Keywords; empty string lists recent notes'),
+            offset: z.number().int().min(0).optional().describe('Results to skip; use nextOffset from the previous page'),
+            boxes: z.array(z.string()).optional().describe('Card box (folder) names or ids; notes in any of them match'),
             tags: z.string().optional().describe('Tag filter expression, e.g. "work AND !draft"'),
             createdFrom: z.string().optional().describe('ISO date lower bound'),
             createdTo: z.string().optional().describe('ISO date upper bound'),
             limit: z.number().int().min(1).max(MAX_RESULTS).optional(),
         },
-    }, async ({ query, tags, createdFrom, createdTo, limit }) => {
+    }, async ({ query, tags, createdFrom, createdTo, limit, offset = 0, boxes }) => {
         try {
             const result = (await call('note.search', {
                 keyword: query,
@@ -69,26 +76,34 @@ function registerKnowledgeTools(server, call) {
                 tagsExpression: tags || undefined,
                 createdAtFrom: createdFrom,
                 createdAtTo: createdTo,
-                boxValues: [],
+                boxValues: boxes ?? [],
                 matchEmptyZettelBoxes: false,
                 limit: limit ?? 10,
-                offset: 0,
+                offset,
             }));
-            return text({ totalCount: result.totalCount, notes: result.rows });
+            const nextOffset = offset + result.rows.length;
+            const hasMore = nextOffset < result.totalCount;
+            return text({ totalCount: result.totalCount, notes: result.rows, hasMore, ...(hasMore ? { nextOffset } : {}), stale: result.stale === true });
         }
         catch (error) {
             return failure(error);
         }
     });
     server.registerTool('read_note', {
-        description: 'Read one Dinox note as Markdown, with title, tags, folders and properties.',
-        inputSchema: { id: z.string().describe('Note id from search_notes') },
-    }, async ({ id }) => {
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        description: 'Read one Dinox note as Markdown, with title, tags, folders and properties. Use nextOffset to page through truncated content.',
+        inputSchema: {
+            id: z.string().describe('Note id from search_notes'),
+            offset: z.number().int().min(0).optional().describe('Character offset into the Markdown content; use nextOffset from a truncated result'),
+        },
+    }, async ({ id, offset = 0 }) => {
         try {
-            const { note } = (await call('note.detail', { id }));
+            const result = (await call('note.detail', { id }));
+            const { note } = result;
             if (!note)
                 return { ...text(`Note not found: ${id}`), isError: true };
             const markdown = String(note.content_md ?? note.content_text ?? '');
+            const truncated = offset + MAX_NOTE_CHARS < markdown.length;
             return text({
                 id: note.id,
                 title: note.title,
@@ -97,8 +112,11 @@ function registerKnowledgeTools(server, call) {
                 properties: note.properties,
                 createdAt: note.created_at,
                 updatedAt: note.updated_at,
-                truncated: markdown.length > MAX_NOTE_CHARS,
-                content: markdown.slice(0, MAX_NOTE_CHARS),
+                totalChars: markdown.length,
+                truncated,
+                ...(truncated ? { nextOffset: offset + MAX_NOTE_CHARS } : {}),
+                content: markdown.slice(offset, offset + MAX_NOTE_CHARS),
+                stale: result.stale === true,
             });
         }
         catch (error) {
@@ -106,6 +124,7 @@ function registerKnowledgeTools(server, call) {
         }
     });
     server.registerTool('search_todos', {
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: "Search the user's Dinox todo items.",
         inputSchema: {
             query: z.string().describe('Keywords; empty string lists all'),
@@ -129,6 +148,7 @@ function registerKnowledgeTools(server, call) {
         }
     });
     server.registerTool('related_notes', {
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: 'Notes linked to a note (backlinks and outlinks, up to the given depth).',
         inputSchema: {
             id: z.string().describe('Note id'),
@@ -143,6 +163,7 @@ function registerKnowledgeTools(server, call) {
         }
     });
     server.registerTool('read_conversation', {
+        annotations: { readOnlyHint: true, openWorldHint: false },
         description: 'Read messages of a Dinox conversation, oldest first: who said what (the user, or which agent answered). ' +
             'Use it when the conversation context you were given says earlier messages are not shown. Returns the newest ' +
             'messages before `before`; pass the first returned id as `before` to page further back.',

package/dist/gateway/runExecutor.d.ts

@@ -30,8 +30,13 @@ export type RunExecutorDeps = {
 export declare function agentInstructionsPreamble(instructions: string): string | undefined;
 /** How the user sees this conversation, so the agent hands over files instead of printing their paths. */
 export declare const SESSION_DELIVERY_NOTE: string;
-/** What a new session starts with: how replies reach the user, then the user's instructions. */
-export declare function sessionPreamble(instructions: string): string;
+/** The knowledge tools available to the agent in Dinox. */
+export declare const DINOX_KNOWLEDGE_NOTE: string;
+/** What a new session starts with: available tools, then the user's instructions. */
+export declare function sessionPreamble(instructions: string, options: {
+    delivery: boolean;
+    knowledge: boolean;
+}): string | undefined;
 /**
  * Runs accepted turns on one gateway. A thread has at most one active run;
  * turns sent meanwhile wait in a per-thread FIFO and, when it ends, run

package/dist/gateway/runExecutor.js

@@ -49,9 +49,15 @@ export const SESSION_DELIVERY_NOTE = [
     'To show them a file you made or found (an image, a document, a chart, ...), call the Dinox send_file tool with its path.',
     '</dinox_delivery>',
 ].join('\n');
-/** What a new session starts with: how replies reach the user, then the user's instructions. */
-export function sessionPreamble(instructions) {
-    return [SESSION_DELIVERY_NOTE, agentInstructionsPreamble(instructions)].filter(Boolean).join('\n\n');
+/** The knowledge tools available to the agent in Dinox. */
+export const DINOX_KNOWLEDGE_NOTE = [
+    '<dinox_knowledge>',
+    "The Dinox tools can search and read the user's Dinox notes, todos and conversations (search_notes, read_note, search_todos, related_notes, read_conversation). The dinox_* tools can also create, update and organize Dinox data. Confirm with the user before writes they did not request, and dry-run high-risk actions first. Use them when the request may involve what the user has written down in Dinox.",
+    '</dinox_knowledge>',
+].join('\n');
+/** What a new session starts with: available tools, then the user's instructions. */
+export function sessionPreamble(instructions, options) {
+    return [options.delivery && SESSION_DELIVERY_NOTE, options.knowledge && DINOX_KNOWLEDGE_NOTE, agentInstructionsPreamble(instructions)].filter(Boolean).join('\n\n') || undefined;
 }
 function withErrorText(message, error) {
     return { ...message, metadata: { ...(message.metadata ?? {}), error } };
@@ -323,7 +329,7 @@ export class GatewayRunExecutor {
             const result = await adapter.runTurn({
                 sessionId: continued?.sessionId ?? null,
                 cwd,
-                sessionPreamble: this.deps.uploadFile ? sessionPreamble(instructions) : agentInstructionsPreamble(instructions),
+                sessionPreamble: sessionPreamble(instructions, { delivery: !!this.deps.uploadFile, knowledge: gateway.dinoxTools !== false }),
                 prompt: withConversationContext(prompt, context, { canReadConversation: gateway.dinoxTools !== false }),
                 resources,
                 signal: active.controller.signal,

package/dist/gateway/types.d.ts

@@ -36,7 +36,7 @@ export type GatewayDefinition = {
     /** Extra environment for the agent process (secrets stay on this machine). */
     env?: Record<string, string>;
     enabled: boolean;
-    /** Offer the read-only Dinox knowledge tools (MCP) to the agent; default true. */
+    /** Offer the Dinox knowledge tools (MCP) to the agent; default true. */
     dinoxTools?: boolean;
     /** Default `ask`. */
     approval?: GatewayApprovalMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoxx/dinox-cli",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {