Skip to content

armgit / Orkas

Public Imported from GitHub
0

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.

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.ts
index 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): Promis
hasProducedPath,
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.ts
index 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 the
diff --git a/src/main/model/core-agent/client.ts b/src/main/model/core-agent/client.ts
index 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<St
skillList,
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.ts
index 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.ts
index 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.md
index 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.