@biaoo/tiangong-wiki 0.2.2 → 0.2.3

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/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/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,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biaoo/tiangong-wiki",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Local-first wiki index and query engine for Markdown knowledge pages (Tiangong Wiki).",
   "type": "module",
   "publishConfig": {

package/references/troubleshooting.md

@@ -73,8 +73,11 @@ The agent uses [Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) to p
 | `WIKI_AGENT_API_KEY` | If enabled | API key for the LLM provider |
 | `WIKI_AGENT_MODEL` | No | Model name (e.g. `gpt-5.4`, `Qwen/Qwen3.5-397B-A17B-GPTQ-Int4`) |
 | `WIKI_AGENT_BATCH_SIZE` | No | Max concurrent vault items per batch (default: `5`) |
+| `WIKI_AGENT_SANDBOX_MODE` | No | Codex sandbox mode: `danger-full-access` (default) or `workspace-write` |
 | `WIKI_PARSER_SKILLS` | No | Comma-separated parser skill list (e.g. `pdf,docx,pptx,xlsx`) |
 
+`tiangong-wiki setup` now prompts for `WIKI_AGENT_SANDBOX_MODE` when automatic vault processing is enabled. The default is `danger-full-access`, and the setup wizard highlights that this mode grants full runtime access.
+
 ---
 
 ## Common Issues
@@ -102,6 +105,10 @@ Always run `tiangong-wiki lint --path <page-id> --format json` after mutations.
 
 Parser skills must be installed under `<workspace-root>/.agents/skills/`. Run `tiangong-wiki skill` to inspect installed skills. Use `tiangong-wiki skill update --all` to update.
 
+### Codex workflow sandbox fails to initialize
+
+If the agent workflow fails with `bwrap`, `unshare`, `uid_map`, or similar sandbox startup errors, switch `WIKI_AGENT_SANDBOX_MODE` to `danger-full-access`. Use `workspace-write` only when you explicitly want that sandbox mode and know the host supports it.
+
 ---
 
 ## LLM Provider Setup