Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.
JavaScript agent-collaborationagent-harnessagent-orchestrationagent-teamagent-workflowai-assistantai-automationai-employeeai-productivityai-teamai-workflowautonomous-agentsclaude-code-guiclaude-coworkdesktop-agentlocal-firstmulti-agentmulti-agent-systemself-evolving-agentstask-automation
Split commander file-tools sandbox into read-write and read-only roots
wyta1836a30ef14
diff --git a/src/main/features/group_chat/bus.ts b/src/main/features/group_chat/bus.tsindex 970514bb..2f833355 100644--- a/src/main/features/group_chat/bus.ts+++ b/src/main/features/group_chat/bus.ts@@ -847,22 +847,24 @@ async function runTurn(state: CidState, w: WorkerState, item: QueueItem): Promis| { type: 'progress'; text: string }| { type: 'event'; event: { stream: string; data?: unknown } };const processItems: ProcessItem[] = [];- // Skill directories are referenced by `$builtin_skills_dir` /- // `$custom_skills_dir` template vars in the system prompt — commander +- // agents are explicitly told to `cat .../<id>/SKILL.md` to read the- // skill body before executing. Path-sandbox blocks anything outside- // workspace + attachment dir by default, so we have to expose the two- // skill roots here as `extraRoots` (mirrors the skill-edit chat pattern- // in features/skills.ts). Builtin first to match the prompt's- // "locate by source" guidance.+ // Skill / agent directories are referenced by `$builtin_skills_dir` /+ // `$custom_skills_dir` / `$custom_agents_dir` template vars in the+ // system prompt — commander + agents are told to `cat .../<id>/SKILL.md`+ // to read the skill body before executing, and to `read_file` an+ // agent.json before emitting an `<agent>` edit container so the rewrite+ // is grounded in current state. Path-sandbox blocks anything outside+ // workspace + attachment by default, so we expose these as+ // `readOnlyExtraRoots`: file-tools (read_file / search_files /+ // grep_files / stat_file) can see them, but write-side tools+ // (edit_file / write_file / bash / markdown_to_pdf / generate_image)+ // cannot mutate paths inside. The structured `<agent>` / `<skill>`+ // containers are the only sanctioned mutation channels — any direct+ // edit_file would skip safeId / validateAgentInputs / bilingual+ // description normalisation / cache invalidation / the "view detail"+ // chip, so the sandbox-level lock keeps the LLM honest even if the+ // prompt strays. Builtin first to match the prompt's "locate by+ // source" guidance.const skillRoots = [BUILTIN_SKILLS_DIR, userSkillsDir(uid)];- // Same shape for agent directories: chat_commander.md tells the- // commander to `search_files` for an agent.json under- // `$custom_agents_dir/` and then `read_file` the matching agent.json- // before emitting an `<agent>` edit container — without these roots- // the read trips E_PATH_OUT_OF_SCOPE and the LLM falls back to- // rewriting from the slim `agents_index` view, which silently drops- // workflow / description / skill_list (the prompt warns about this).const agentRoots = [BUILTIN_AGENTS_DIR, userAgentsDir(uid)];if (cliAgent) {// CLI-backed agent path: spawn the local CLI in the user's workspace@@ -954,7 +956,7 @@ async function runTurn(state: CidState, w: WorkerState, item: QueueItem): PromishasProducedPath,cacheRetention: 'short',abortSignal: w.abortController.signal,- extraRoots: [...skillRoots, ...agentRoots],+ readOnlyExtraRoots: [...skillRoots, ...agentRoots],...(extraTools.length ? { extraTools } : {}),...(skillList !== undefined ? { skillList } : {}),})) {diff --git a/src/main/model/client.ts b/src/main/model/client.tsindex b2e06e74..2dffadee 100644--- a/src/main/model/client.ts+++ b/src/main/model/client.ts@@ -82,9 +82,18 @@ export interface ChatOptions {* dir in addition to the user's active workspace. */cid?: string;/** Extra absolute directory roots whitelisted for file-tools on top of- * workspace + attachment. Skill-edit chats pass the skill dir so the LLM- * can read / search files it's about to overwrite via <<<skill-file>>>. */+ * workspace + attachment. Read AND write are permitted under these roots.+ * Per-skill edit chats pass the skill dir so the LLM can read / search /+ * overwrite files it manages. */extraRoots?: readonly string[];+ /** Read-only extra roots: read tools (read_file / search_files /+ * grep_files / stat_file) can see these, but write-side tools+ * (edit_file / write_file / bash / markdown_to_pdf / html_to_pdf /+ * generate_image) cannot mutate paths inside. Used by group-chat+ * commander to inspect agent / skill specs while the structured+ * `<agent>` / `<skill>` containers remain the only sanctioned mutation+ * channels. */+ readOnlyExtraRoots?: readonly string[];/** Fired with the absolute path of every file produced by the local-exec* tools (`write_file`, `markdown_to_pdf`, `html_to_pdf`) during this run.* `features/chats` uses this to attach a `produced[]` list to thediff --git a/src/main/model/core-agent/client.ts b/src/main/model/core-agent/client.tsindex 7542fc09..6aad78a1 100644--- a/src/main/model/core-agent/client.ts+++ b/src/main/model/core-agent/client.ts@@ -84,6 +84,7 @@ export async function* streamChatWithModel(opts: ChatOptions): AsyncGenerator<StskillList,extraTools,extraRoots,+ readOnlyExtraRoots,agentId,cid,onFileWritten,@@ -178,6 +179,7 @@ export async function* streamChatWithModel(opts: ChatOptions): AsyncGenerator<St...(skillList !== undefined ? { skillList } : {}),...(extraTools && extraTools.length ? { extraTools } : {}),...(extraRoots && extraRoots.length ? { extraRoots } : {}),+ ...(readOnlyExtraRoots && readOnlyExtraRoots.length ? { readOnlyExtraRoots } : {}),...(onFileWritten ? { onFileWritten } : {}),...(hasProducedPath ? { hasProducedPath } : {}),});diff --git a/src/main/model/core-agent/file-tools.ts b/src/main/model/core-agent/file-tools.tsindex 5dee918d..0a428421 100644--- a/src/main/model/core-agent/file-tools.ts+++ b/src/main/model/core-agent/file-tools.ts@@ -73,12 +73,22 @@ export interface FileToolsOpts {* attachment scope (workspace-only). */cid?: string;/** Extra absolute directory roots to allow on top of workspace + attachment.- * Used by skill-edit chats to expose the skill dir for read_file /- * search_files / grep_files / stat_file. */+ * Read AND write are permitted under these roots — used by per-skill edit+ * chats to expose the skill dir for the `<<<skill-file>>>` tooling. */extraRoots?: readonly string[];+ /** Read-only extra roots: file-tools (read_file / search_files / grep_files+ * / stat_file) can see these, but write-side tools (edit_file / write_file+ * / bash / markdown_to_pdf / html_to_pdf / generate_image) cannot mutate+ * paths inside. Used by the group-chat commander to inspect agent.json /+ * built-in agents / skill specs without giving direct-write access — the+ * `<agent>` / `<skill>` containers are the only sanctioned mutation+ * channels for those resources, and a sandbox-level lock keeps the LLM+ * honest even when its prompt strays. */+ readOnlyExtraRoots?: readonly string[];}-/** Assemble the allowed-roots list for the current (uid, cid). */+/** Assemble the allowed-roots list for the current (uid, cid). File-tools+ * read side: workspace + attachment + extraRoots + readOnlyExtraRoots. */function allowedRoots(opts: FileToolsOpts): string[] {const roots: string[] = [];try {@@ -92,6 +102,9 @@ function allowedRoots(opts: FileToolsOpts): string[] {if (opts.extraRoots?.length) {for (const r of opts.extraRoots) if (r) roots.push(r);}+ if (opts.readOnlyExtraRoots?.length) {+ for (const r of opts.readOnlyExtraRoots) if (r) roots.push(r);+ }return roots;}diff --git a/src/main/model/core-agent/runner.ts b/src/main/model/core-agent/runner.tsindex 06bec6e1..5efde80a 100644--- a/src/main/model/core-agent/runner.ts+++ b/src/main/model/core-agent/runner.ts@@ -86,8 +86,17 @@ export interface BuildRunnerParams {extraTools?: AgentTool[];/** Extra absolute directory roots whitelisted for file-tools (read_file /* stat_file / search_files / grep_files) on top of workspace + attachment.- * Used by skill-edit chats to expose the skill dir. */+ * Read AND write are permitted under these roots. Used by per-skill+ * edit chats to expose the skill dir. */extraRoots?: readonly string[];+ /** Read-only extra roots: read tools (read_file / search_files /+ * grep_files / stat_file) can see them, but write-side tools+ * (edit_file / write_file / bash / markdown_to_pdf / html_to_pdf /+ * generate_image) cannot mutate paths inside. Used by group-chat+ * commander to inspect agent / skill specs without giving direct-write+ * access — the structured `<agent>` / `<skill>` containers are the+ * only sanctioned mutation channels for those resources. */+ readOnlyExtraRoots?: readonly string[];/** Fires with the absolute path after each successful `write_file` /* `markdown_to_pdf` / `html_to_pdf` call. See `model/client.ts`* `ChatOptions.onFileWritten` for the caller-facing contract. */@@ -199,11 +208,16 @@ export async function buildRunner(params: BuildRunnerParams): Promise<{// Same last-write-wins rule — placed after localTools so `read_file` wins// over core-agent's builtin `read_file`. Skipped when uid is unknown// (e.g. ad-hoc test runs) since file-tools need it for cache scoping.+ // `readOnlyExtraRoots` is intentionally only threaded HERE — write-side+ // localTools / image-gen-tool stay limited to workspace + attachment ++ // (read-write) extraRoots, so paths the caller marks read-only physically+ // can't be mutated by the LLM.const fileTools = uid? createFileTools({userId: uid,...(params.cid ? { cid: params.cid } : {}),...(params.extraRoots?.length ? { extraRoots: params.extraRoots } : {}),+ ...(params.readOnlyExtraRoots?.length ? { readOnlyExtraRoots: params.readOnlyExtraRoots } : {}),}): [];diff --git a/src/main/prompts/chat_commander.md b/src/main/prompts/chat_commander.mdindex e593e4d9..cdc031c2 100644--- a/src/main/prompts/chat_commander.md+++ b/src/main/prompts/chat_commander.md@@ -224,6 +224,8 @@ Emit one `<agent>...</agent>` container per agent being created or edited this t**Do NOT call `write_file` / `bash` to dump the `<agent>` container as a file** (e.g. `<name>-agent-definition.xml`). The container is a contract between the LLM and the server: the server parses the inline container in your reply and persists it to `agent.json`. An extra `write_file` only leaks an unused XML file into the user's workspace — there is no downstream consumer for it. Pitfall: this has already shipped a stray `GEO-agent-definition.xml` to the workspace once.+**Do NOT use `edit_file` / `write_file` / `bash` to mutate `agent.json` directly.** Read for inspection is allowed; every mutation goes through the `<agent>` container above — direct writes skip id / schema validation, bilingual description normalisation, registry invalidation, and the "view agent" chip. The sandbox now physically blocks these writes; the rule here keeps you from wasting a tool call probing it.+### When to create vs edit- **No `<agent_id>`** → create a brand-new agent from the supplied fields. Triggered when the user says "help me crystallize / create / refine an agent from this conversation"; base it on the **whole conversation history** in **one shot**, distilling "what the user has been doing repeatedly".- **With `<agent_id>X</agent_id>`** → patch the existing custom agent X. Sub-tags you emit replace; sub-tags you omit are preserved. Triggered when the user says "把 X 的工作流改成…" / "给 X 加一个输入字段叫 Y" / "X 的描述太啰嗦,改清楚一点" etc.@@ -336,6 +338,8 @@ Emit one `<skill>...</skill>` container per skill being created or edited this t**Do NOT call `write_file` / `bash` to dump the container or any inner block as a file** — the server parses them inline and persists each block to `<skill_dir>/<path>`. An extra `write_file` only leaks an unused scratch file into the workspace.+**Do NOT use `edit_file` / `write_file` / `bash` to mutate any file under `<skill_dir>/<id>/` directly.** Read for inspection is allowed; every mutation goes through `<<<skill-file>>>` blocks inside the `<skill>` container — direct writes skip frontmatter normalisation, the rename-by-name path, registry invalidation, and the "view skill" chip. The sandbox now physically blocks these writes; the rule here keeps you from wasting a tool call probing it.+### When to create vs edit- **No `<skill_id>`** → create a brand-new skill. Triggered by "make / write me a skill that does X" / "把这个能力封装成 skill". The new skill's id comes from the SKILL.md frontmatter `name` field; you choose it.