@biaoo/tiangong-wiki 0.2.2 → 0.3.0

package/README.md

@@ -99,7 +99,112 @@ tiangong-wiki dashboard                               # open dashboard in browse
 # or: tiangong-wiki daemon run                        # run the daemon in the foreground for debugging
 ```
 
-> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
+> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference. For a centralized Linux + `systemd` + Nginx deployment, see [references/centralized-service-deployment.md](./references/centralized-service-deployment.md). That deployment guide now also includes Git repository / GitHub remote setup for daemon-side commit and optional auto-push.
+
+## MCP Server
+
+Tiangong Wiki ships a separate MCP adapter that talks to the daemon over HTTP. It uses the MCP Streamable HTTP transport, not stdio.
+
+Start it after the daemon is already listening:
+
+```bash
+tiangong-wiki daemon run
+```
+
+In another shell:
+
+```bash
+export WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787
+export WIKI_MCP_HOST=127.0.0.1
+export WIKI_MCP_PORT=9400
+export WIKI_MCP_PATH=/mcp
+
+tiangong-wiki-mcp-server
+```
+
+The server prints a JSON line like:
+
+```json
+{"status":"listening","host":"127.0.0.1","port":9400,"healthUrl":"http://127.0.0.1:9400/health","mcpUrl":"http://127.0.0.1:9400/mcp"}
+```
+
+If you are running from a source checkout instead of a global install:
+
+```bash
+npm install
+npm run build
+
+WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787 \
+WIKI_MCP_PORT=9400 \
+node mcp-server/dist/index.js
+
+# or during development
+npm run dev:mcp-server
+```
+
+Required MCP-side environment variables:
+
+- `WIKI_DAEMON_BASE_URL`: base URL of the wiki daemon, for example `http://127.0.0.1:8787`
+- `WIKI_MCP_HOST`: bind host for the MCP HTTP server, default `127.0.0.1`
+- `WIKI_MCP_PORT`: bind port for the MCP HTTP server, default random free port
+- `WIKI_MCP_PATH`: MCP route path, default `/mcp`
+
+Bearer token note:
+
+- Bearer tokens are not configured in `.wiki.env`, daemon env, or MCP env
+- In the current V1 deployment model, Bearer tokens live in the reverse proxy config
+- See [references/examples/centralized-service/nginx-centralized-wiki.conf](./references/examples/centralized-service/nginx-centralized-wiki.conf) for the current `map $http_authorization ...` example
+- In production, keep token values in a private Nginx include file such as `/etc/nginx/snippets/wiki-auth-tokens.conf`, then `include` it from the main site config instead of hardcoding secrets in the repo
+
+## Using the MCP From Clients
+
+Any MCP client that supports Streamable HTTP can connect to the MCP endpoint:
+
+- Local debug endpoint: `http://127.0.0.1:9400/mcp`
+- Health check: `http://127.0.0.1:9400/health`
+- Production recommendation: expose `/mcp` behind a reverse proxy and keep daemon/MCP bound to loopback
+
+Read tools can be called directly. Write tools such as `wiki_page_create`, `wiki_page_update`, and `wiki_sync` require these headers:
+
+- `x-wiki-actor-id`
+- `x-wiki-actor-type`
+- `x-request-id`
+
+In production, the recommended model is: the client sends `Authorization: Bearer ...` to the reverse proxy, the proxy validates the token there, and the proxy injects the actor headers before forwarding to the MCP server. For local debugging without a proxy, your client must send those headers itself when calling write tools.
+
+Minimal Node.js MCP client example:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:9400/mcp"), {
+  requestInit: {
+    headers: {
+      "x-wiki-actor-id": "agent:demo",
+      "x-wiki-actor-type": "agent",
+      "x-request-id": "req-demo-1",
+    },
+  },
+});
+
+const client = new Client({ name: "demo-client", version: "1.0.0" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+const search = await client.callTool({
+  name: "wiki_search",
+  arguments: { query: "bayes", limit: 5 },
+});
+```
+
+Current MCP tools include:
+
+- Query: `wiki_find`, `wiki_fts`, `wiki_search`, `wiki_graph`
+- Page: `wiki_page_info`, `wiki_page_read`, `wiki_page_create`, `wiki_page_update`
+- Type: `wiki_type_list`, `wiki_type_show`, `wiki_type_recommend`
+- Vault: `wiki_vault_list`, `wiki_vault_queue`
+- Maintenance: `wiki_sync`, `wiki_lint`
 
 ## CLI
 

package/README.zh-CN.md

@@ -99,7 +99,112 @@ tiangong-wiki dashboard                               # 在浏览器中打开仪
 # 或者：tiangong-wiki daemon run                      # 前台运行 daemon，适合调试
 ```
 
-> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
+> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。如需部署中心化服务（Linux + `systemd` + Nginx），见 [references/centralized-service-deployment.md](./references/centralized-service-deployment.md)。该部署文档现在也包含了 Git 仓库初始化、GitHub remote 配置和 daemon 自动 push 的 Git 配置说明。
+
+## MCP Server
+
+Tiangong Wiki 提供了独立的 MCP 适配层，通过 HTTP 调用 daemon。它使用的是 MCP 的 Streamable HTTP 传输，不是 stdio。
+
+启动 MCP 前，先确保 daemon 已经在监听：
+
+```bash
+tiangong-wiki daemon run
+```
+
+另开一个终端：
+
+```bash
+export WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787
+export WIKI_MCP_HOST=127.0.0.1
+export WIKI_MCP_PORT=9400
+export WIKI_MCP_PATH=/mcp
+
+tiangong-wiki-mcp-server
+```
+
+启动后会输出一行 JSON，例如：
+
+```json
+{"status":"listening","host":"127.0.0.1","port":9400,"healthUrl":"http://127.0.0.1:9400/health","mcpUrl":"http://127.0.0.1:9400/mcp"}
+```
+
+如果你不是通过全局安装使用，而是在源码仓库里运行：
+
+```bash
+npm install
+npm run build
+
+WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787 \
+WIKI_MCP_PORT=9400 \
+node mcp-server/dist/index.js
+
+# 或者开发态运行
+npm run dev:mcp-server
+```
+
+MCP 侧需要的环境变量：
+
+- `WIKI_DAEMON_BASE_URL`：wiki daemon 的 base URL，例如 `http://127.0.0.1:8787`
+- `WIKI_MCP_HOST`：MCP HTTP 服务绑定地址，默认 `127.0.0.1`
+- `WIKI_MCP_PORT`：MCP HTTP 服务绑定端口，默认随机空闲端口
+- `WIKI_MCP_PATH`：MCP 路由路径，默认 `/mcp`
+
+Bearer token 说明：
+
+- Bearer token 不配置在 `.wiki.env`、daemon env 或 MCP env 里
+- 当前 V1 部署模型里，Bearer token 配在反向代理层
+- 具体示例见 [references/examples/centralized-service/nginx-centralized-wiki.conf](./references/examples/centralized-service/nginx-centralized-wiki.conf) 中的 `map $http_authorization ...`
+- 生产环境建议把 token 放在私有的 Nginx include 文件中，例如 `/etc/nginx/snippets/wiki-auth-tokens.conf`，再由主站点配置 `include` 进来，不要把真实密钥硬编码在仓库示例里
+
+## 客户端如何使用这个 MCP
+
+任何支持 Streamable HTTP 的 MCP client 都可以连接到这个服务：
+
+- 本地调试地址：`http://127.0.0.1:9400/mcp`
+- 健康检查：`http://127.0.0.1:9400/health`
+- 生产环境建议：对外只暴露反向代理后的 `/mcp`，daemon 和 MCP 自身只监听 loopback
+
+读工具可以直接调用。写工具，如 `wiki_page_create`、`wiki_page_update`、`wiki_sync`，额外要求这些 header：
+
+- `x-wiki-actor-id`
+- `x-wiki-actor-type`
+- `x-request-id`
+
+生产环境推荐模式是：客户端只向反向代理发送 `Authorization: Bearer ...`，由反向代理在代理层完成 token 校验，并在转发到 MCP server 前注入 actor headers。若你在本地直接连 MCP 做调试，则需要由客户端自己带上这些 header 才能调用写工具。
+
+最小 Node.js MCP client 示例：
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:9400/mcp"), {
+  requestInit: {
+    headers: {
+      "x-wiki-actor-id": "agent:demo",
+      "x-wiki-actor-type": "agent",
+      "x-request-id": "req-demo-1",
+    },
+  },
+});
+
+const client = new Client({ name: "demo-client", version: "1.0.0" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+const search = await client.callTool({
+  name: "wiki_search",
+  arguments: { query: "bayes", limit: 5 },
+});
+```
+
+当前 MCP tools 包括：
+
+- 查询：`wiki_find`、`wiki_fts`、`wiki_search`、`wiki_graph`
+- 页面：`wiki_page_info`、`wiki_page_read`、`wiki_page_create`、`wiki_page_update`
+- 类型：`wiki_type_list`、`wiki_type_show`、`wiki_type_recommend`
+- Vault：`wiki_vault_list`、`wiki_vault_queue`
+- 维护：`wiki_sync`、`wiki_lint`
 
 ## CLI
 

package/dist/commands/create.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { buildCliWriteActor } from "../daemon/write-actor.js";
 import { createPage } from "../operations/write.js";
 import { writeJson } from "../utils/output.js";
 export function registerCreateCommand(program) {
@@ -20,7 +21,9 @@ export function registerCreateCommand(program) {
                 endpoint,
                 method: "POST",
                 path: "/create",
+                timeoutMs: 310_000,
                 body: {
+                    actor: buildCliWriteActor(process.env),
                     type: options.type,
                     title: options.title,
                     nodeId: options.nodeId ?? undefined,

package/dist/commands/sync.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { buildCliWriteActor } from "../daemon/write-actor.js";
 import { runSyncCommand } from "../operations/write.js";
 import { writeJson } from "../utils/output.js";
 export function registerSyncCommand(program) {
@@ -24,7 +25,9 @@ export function registerSyncCommand(program) {
                 endpoint,
                 method: "POST",
                 path: "/sync",
+                timeoutMs: 310_000,
                 body: {
+                    actor: buildCliWriteActor(process.env),
                     path: options.path ?? undefined,
                     force: options.force === true,
                     skipEmbedding: options.skipEmbedding === true,

package/dist/commands/template.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { buildCliWriteActor } from "../daemon/write-actor.js";
 import { renderTemplateLintResult, runTemplateLint } from "../operations/template-lint.js";
 import { createTemplate, listTemplates, showTemplate } from "../operations/type-template.js";
 import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
@@ -90,7 +91,9 @@ export function registerTemplateCommand(program) {
                 endpoint,
                 method: "POST",
                 path: "/template/create",
+                timeoutMs: 310_000,
                 body: {
+                    actor: buildCliWriteActor(process.env),
                     type: options.type,
                     title: options.title,
                 },

package/dist/core/codex-workflow.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { Codex } from "@openai/codex-sdk";
 import { readWorkflowResult } from "./workflow-result.js";
+import { resolveAgentSettings } from "./paths.js";
 import { readTextFileSync, writeTextFileSync } from "../utils/fs.js";
 import { AppError } from "../utils/errors.js";
 export const CODEX_WORKFLOW_VERSION = "2026-04-07";
@@ -85,16 +86,10 @@ async function runThread(thread, input) {
                 continue;
             }
             if (event.type === "turn.failed") {
-                throw new AppError("Codex workflow turn failed", "runtime", {
-                    cause: event.error.message,
-                    threadId: activeThreadId,
-                });
+                throw classifyWorkflowRuntimeError("Codex workflow turn failed", event.error.message, activeThreadId);
             }
             if (event.type === "error") {
-                throw new AppError("Codex workflow stream failed", "runtime", {
-                    cause: event.message,
-                    threadId: activeThreadId,
-                });
+                throw classifyWorkflowRuntimeError("Codex workflow stream failed", event.message, activeThreadId);
             }
         }
     }
@@ -103,10 +98,7 @@ async function runThread(thread, input) {
             throw error;
         }
         const message = error instanceof Error ? error.message : String(error);
-        throw new AppError("Codex workflow turn failed", "runtime", {
-            cause: message,
-            threadId: activeThreadId,
-        });
+        throw classifyWorkflowRuntimeError("Codex workflow turn failed", message, activeThreadId);
     }
     if (!activeThreadId && thread.id) {
         activeThreadId = thread.id;
@@ -118,6 +110,10 @@ async function runThread(thread, input) {
     return activeThreadId;
 }
 export class CodexSdkWorkflowRunner {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
     // The SDK can only continue a thread by sending a new input, so queue retries
     // must not automatically resume real workflow threads inline.
     async startWorkflow(input) {
@@ -127,7 +123,7 @@ export class CodexSdkWorkflowRunner {
             modelReasoningEffort: "low",
             workingDirectory: input.workspaceRoot,
             skipGitRepoCheck: true,
-            sandboxMode: "workspace-write",
+            sandboxMode: this.options.sandboxMode ?? "danger-full-access",
             networkAccessEnabled: true,
             approvalPolicy: "never",
             webSearchMode: "disabled",
@@ -143,7 +139,7 @@ export class CodexSdkWorkflowRunner {
             modelReasoningEffort: "low",
             workingDirectory: input.workspaceRoot,
             skipGitRepoCheck: true,
-            sandboxMode: "workspace-write",
+            sandboxMode: this.options.sandboxMode ?? "danger-full-access",
             networkAccessEnabled: true,
             approvalPolicy: "never",
             webSearchMode: "disabled",
@@ -229,5 +225,31 @@ export function createDefaultWorkflowRunner(env = process.env) {
         const delayMs = Number.parseInt(env.WIKI_TEST_FAKE_WORKFLOW_DELAY_MS ?? "0", 10) || 0;
         return createSkipOnlyTestWorkflowRunner({ delayMs, mode: "delay-skip" });
     }
-    return new CodexSdkWorkflowRunner();
+    return new CodexSdkWorkflowRunner({
+        sandboxMode: resolveAgentSettings(env).sandboxMode,
+    });
+}
+function isSandboxStartupFailure(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("bwrap") ||
+        normalized.includes("bubblewrap") ||
+        normalized.includes("uid map") ||
+        normalized.includes("uid_map") ||
+        normalized.includes("gid map") ||
+        normalized.includes("gid_map") ||
+        normalized.includes("unshare") ||
+        normalized.includes("operation not permitted"));
+}
+function classifyWorkflowRuntimeError(baseMessage, cause, threadId) {
+    if (isSandboxStartupFailure(cause)) {
+        return new AppError("Codex workflow sandbox failed to initialize", "runtime", {
+            cause,
+            threadId,
+            phase: "sandbox",
+        });
+    }
+    return new AppError(baseMessage, "runtime", {
+        cause,
+        threadId,
+    });
 }

package/dist/core/db.js

@@ -149,6 +149,25 @@ function ensureBaseTables(db, embeddingDimensions) {
       key TEXT PRIMARY KEY,
       value TEXT
     );
+
+    CREATE TABLE IF NOT EXISTS daemon_write_jobs (
+      job_id TEXT PRIMARY KEY,
+      task_type TEXT NOT NULL,
+      status TEXT NOT NULL,
+      enqueued_at TEXT NOT NULL,
+      started_at TEXT,
+      finished_at TEXT,
+      duration_ms INTEGER,
+      timeout_ms INTEGER NOT NULL,
+      queue_depth_at_enqueue INTEGER NOT NULL DEFAULT 0,
+      result_summary TEXT,
+      error_message TEXT,
+      error_details TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_daemon_write_jobs_status ON daemon_write_jobs(status);
+    CREATE INDEX IF NOT EXISTS idx_daemon_write_jobs_enqueued_at ON daemon_write_jobs(enqueued_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_daemon_write_jobs_finished_at ON daemon_write_jobs(finished_at DESC);
   `);
     ensureTableColumns(db, "vault_processing_queue", {
         claimed_at: "TEXT",

package/dist/core/onboarding.js

@@ -6,7 +6,7 @@ import { DEFAULT_WIKI_ENV_FILE, getCliEnvironmentInfo, parseEnvFile, serializeEn
 import { resolveTemplateFilePath, loadConfig } from "./config.js";
 import { EmbeddingClient } from "./embedding.js";
 import { writeGlobalConfig } from "./global-config.js";
-import { parseVaultHashMode, resolveAgentSettings } from "./paths.js";
+import { parseVaultHashMode, parseWikiAgentSandboxMode, resolveAgentSettings } from "./paths.js";
 import { loadSynologyConfigFromEnv, normalizeSynologyRemotePath, withSynologyClient } from "./synology.js";
 import { ensureWikiSkillInstall, formatParserSkills, inspectSkillInstall, installParserSkill, OPTIONAL_PARSER_SKILLS, parseParserSkillSelection, parseParserSkills, resolveWorkspaceRootFromWikiPath, resolveWorkspaceSkillPath, resolveWorkspaceSkillPaths, } from "./workspace-skills.js";
 import { scaffoldWorkspaceAssets } from "./workspace-bootstrap.js";
@@ -36,11 +36,16 @@ const MANAGED_ENV_KEYS = new Set([
     "WIKI_AGENT_API_KEY",
     "WIKI_AGENT_MODEL",
     "WIKI_AGENT_BATCH_SIZE",
+    "WIKI_AGENT_SANDBOX_MODE",
     "WIKI_PARSER_SKILLS",
 ]);
 function writeSection(output, title) {
     output.write(`\n${title}\n`);
 }
+function writeWarning(output, message) {
+    const isTty = "isTTY" in output && output.isTTY;
+    output.write(isTty ? `\x1b[31m${message}\x1b[0m\n` : `${message}\n`);
+}
 function resolvePackageRoot(packageRoot) {
     return packageRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 }
@@ -73,6 +78,14 @@ function safeVaultHashMode(rawValue, defaultValue) {
         return defaultValue;
     }
 }
+function safeAgentSandboxMode(rawValue) {
+    try {
+        return parseWikiAgentSandboxMode(rawValue);
+    }
+    catch {
+        return "danger-full-access";
+    }
+}
 function safeBooleanFlag(rawValue, defaultValue) {
     if (rawValue === undefined || rawValue.trim().length === 0) {
         return defaultValue;
@@ -381,6 +394,7 @@ function getPathDefaults(env, cwd) {
         agentApiKey: env.WIKI_AGENT_API_KEY ?? null,
         agentModel: env.WIKI_AGENT_MODEL ?? null,
         agentBatchSize: env.WIKI_AGENT_BATCH_SIZE ?? "5",
+        agentSandboxMode: safeAgentSandboxMode(env.WIKI_AGENT_SANDBOX_MODE),
         parserSkills: parseParserSkills(env.WIKI_PARSER_SKILLS, { strict: false }),
     };
 }
@@ -447,14 +461,32 @@ async function collectAgentSettings(driver, ctx, defaults) {
             agentApiKey: null,
             agentModel: null,
             agentBatchSize: null,
+            agentSandboxMode: null,
         };
     }
+    writeWarning(ctx.output, "Warning: danger-full-access grants full access to the runtime workspace.");
     return {
         agentEnabled: true,
         agentBaseUrl: await promptText(driver, "WIKI_AGENT_BASE_URL", defaults.agentBaseUrl ?? "https://api.openai.com/v1", { validator: (value) => validateUrl(value, "WIKI_AGENT_BASE_URL") }),
         agentApiKey: await promptPassword(driver, "WIKI_AGENT_API_KEY", defaults.agentApiKey ?? "", { required: true }),
         agentModel: await promptText(driver, "WIKI_AGENT_MODEL", defaults.agentModel ?? "", { required: true }),
         agentBatchSize: await promptText(driver, "WIKI_AGENT_BATCH_SIZE", defaults.agentBatchSize ?? "5", { validator: (value) => validateNonNegativeInteger(value, "WIKI_AGENT_BATCH_SIZE") }),
+        agentSandboxMode: await driver.select({
+            message: "WIKI_AGENT_SANDBOX_MODE",
+            defaultValue: defaults.agentSandboxMode ?? "danger-full-access",
+            choices: [
+                {
+                    value: "danger-full-access",
+                    label: "danger-full-access",
+                    description: "Full access to the runtime workspace. Default.",
+                },
+                {
+                    value: "workspace-write",
+                    label: "workspace-write",
+                    description: "Use Codex workspace-write sandbox when the host supports it.",
+                },
+            ],
+        }),
     };
 }
 async function collectSynologySettings(driver, ctx, defaults) {
@@ -532,6 +564,7 @@ function buildSetupSummary(values) {
         lines.push(`  WIKI_AGENT_BASE_URL: ${values.agentBaseUrl}`);
         lines.push(`  WIKI_AGENT_MODEL: ${values.agentModel}`);
         lines.push(`  WIKI_AGENT_BATCH_SIZE: ${values.agentBatchSize}`);
+        lines.push(`  WIKI_AGENT_SANDBOX_MODE: ${values.agentSandboxMode}`);
     }
     if (values.vaultSource === "synology") {
         lines.push(`  SYNOLOGY_BASE_URL: ${values.synologyBaseUrl}`);
@@ -569,6 +602,7 @@ function writeSetupEnvFile(values) {
         ["WIKI_AGENT_API_KEY", values.agentEnabled ? values.agentApiKey : null],
         ["WIKI_AGENT_MODEL", values.agentEnabled ? values.agentModel : null],
         ["WIKI_AGENT_BATCH_SIZE", values.agentEnabled ? values.agentBatchSize : null],
+        ["WIKI_AGENT_SANDBOX_MODE", values.agentEnabled ? values.agentSandboxMode : null],
         ["WIKI_PARSER_SKILLS", formatParserSkills(values.parserSkills)],
     ];
     const body = [

package/dist/core/page-source.js

@@ -0,0 +1,25 @@
+import { parsePage } from "./frontmatter.js";
+import { normalizePageId, resolvePagePath } from "./paths.js";
+import { pathExistsSync, readTextFileSync, sha256Text } from "../utils/fs.js";
+export function buildPageRevision(rawMarkdown) {
+    if (rawMarkdown === null) {
+        return null;
+    }
+    return sha256Text(rawMarkdown);
+}
+export function readCanonicalPageSource(filePath, wikiPath, config) {
+    const pageId = normalizePageId(filePath, wikiPath);
+    const rawMarkdown = pathExistsSync(filePath) ? readTextFileSync(filePath) : null;
+    const parsed = rawMarkdown === null ? null : parsePage(filePath, wikiPath, config);
+    return {
+        pageId,
+        pagePath: filePath,
+        rawMarkdown,
+        frontmatter: parsed?.ok ? parsed.parsed.rawData : {},
+        revision: buildPageRevision(rawMarkdown),
+    };
+}
+export function readCanonicalPageSourceById(pageId, wikiPath, config) {
+    const canonicalPageId = normalizePageId(pageId, wikiPath);
+    return readCanonicalPageSource(resolvePagePath(canonicalPageId, wikiPath), wikiPath, config);
+}

package/dist/core/paths.js

@@ -89,12 +89,20 @@ export function parseWikiAgentBackend(raw) {
     }
     throw new AppError(`WIKI_AGENT_BACKEND must be "codex-workflow", got ${raw}`, "config");
 }
+export function parseWikiAgentSandboxMode(raw) {
+    const value = (raw ?? "danger-full-access").trim().toLowerCase();
+    if (value === "danger-full-access" || value === "workspace-write") {
+        return value;
+    }
+    throw new AppError(`WIKI_AGENT_SANDBOX_MODE must be "danger-full-access" or "workspace-write", got ${raw}`, "config");
+}
 export function resolveAgentSettings(env = process.env, options = {}) {
     const enabled = parseBooleanFlag("WIKI_AGENT_ENABLED", env.WIKI_AGENT_ENABLED, false);
     const baseUrl = normalizeOptionalUrl(env.WIKI_AGENT_BASE_URL);
     const apiKey = env.WIKI_AGENT_API_KEY?.trim() || null;
     const model = env.WIKI_AGENT_MODEL?.trim() || null;
     const batchSize = parseNonNegativeInteger(env.WIKI_AGENT_BATCH_SIZE, 5, "WIKI_AGENT_BATCH_SIZE");
+    const sandboxMode = parseWikiAgentSandboxMode(env.WIKI_AGENT_SANDBOX_MODE);
     const workflowTimeoutSeconds = parsePositiveInteger(env.WIKI_WORKFLOW_TIMEOUT, 600, "WIKI_WORKFLOW_TIMEOUT");
     const missing = [];
     if (enabled) {
@@ -114,6 +122,7 @@ export function resolveAgentSettings(env = process.env, options = {}) {
         apiKey,
         model,
         batchSize,
+        sandboxMode,
         workflowTimeoutSeconds,
         configured: enabled && missing.length === 0,
         missing,
@@ -146,6 +155,7 @@ export function resolveRuntimePaths(env = process.env) {
         daemonPidPath: path.join(wikiRoot, ".wiki-daemon.pid"),
         daemonLogPath: path.join(wikiRoot, ".wiki-daemon.log"),
         daemonStatePath: path.join(wikiRoot, ".wiki-daemon.state.json"),
+        auditLogPath: path.join(wikiRoot, "..", ".wiki-runtime", "audit.ndjson"),
     };
 }
 export function normalizePageId(inputPath, wikiPath) {

package/dist/core/workflow-result.js

@@ -148,6 +148,11 @@ export function readWorkflowResult(resultPath) {
         fail(`Workflow result not found: ${resultPath}`);
     }
     const rawText = readTextFileSync(resultPath);
+    if (!rawText.trim()) {
+        fail("Workflow result is empty", {
+            resultPath,
+        });
+    }
     let parsed;
     try {
         parsed = JSON.parse(rawText);

package/dist/daemon/audit-log.js

@@ -0,0 +1,18 @@
+import { appendFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { ensureDirSync } from "../utils/fs.js";
+import { toOffsetIso } from "../utils/time.js";
+export function appendAuditEvent(paths, actor, input) {
+    ensureDirSync(path.dirname(paths.auditLogPath));
+    const event = {
+        eventId: randomUUID(),
+        timestamp: toOffsetIso(),
+        requestId: actor.requestId,
+        actorId: actor.actorId,
+        actorType: actor.actorType,
+        ...input,
+    };
+    appendFileSync(paths.auditLogPath, `${JSON.stringify(event)}\n`, "utf8");
+    return event;
+}

package/dist/daemon/client.js

@@ -124,7 +124,7 @@ export async function requestDaemonJson(options) {
         method: options.method,
         headers: options.body === undefined ? undefined : { "content-type": "application/json" },
         body: options.body === undefined ? undefined : JSON.stringify(options.body),
-    }, 5_000);
+    }, options.timeoutMs ?? (options.method === "POST" ? 310_000 : 5_000));
 }
 function warnReadFallback(availability) {
     const location = availability.state