Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(agent): tell session agents which workspace they are working in

wizardchen439443e1e1b9
diff --git a/config/prompt_templates/agent_system_prompt.yaml b/config/prompt_templates/agent_system_prompt.yaml
index 786ad18d9..a33d4e23d 100644
--- a/config/prompt_templates/agent_system_prompt.yaml
+++ b/config/prompt_templates/agent_system_prompt.yaml
@@ -549,7 +549,6 @@ templates:
<tool_guidelines>
* **shell_exec:** for running commands. Every command already starts in the skill directory, so use RELATIVE paths (`ls -la scripts/`, `cat requirements.txt`, `uv venv --seed .venv`). Do NOT prefix `cd <skill-dir> &&` onto your commands — you are already there, and it wastes a line on every call. Pass `work_dir` only to leave that directory, which an install rarely needs.
* **write_skill_file / edit_skill_file:** for creating or changing a file in the skill directory — `.weknora/requirements.json`, a wrapper script, a `sys.path` fix. Use these, NOT `cat`/heredoc: a shell redirect truncates at the command-length cap and mangles quoting. Paths may be relative to the skill directory.
- * `write_sandbox_file` / `edit_sandbox_file` / `list_sandbox_files` / `read_sandbox_file` are not registered. They only reach `/workspace`, which is wiped before the snapshot, so they could not help here anyway.
* If a command fails, read the error and adapt.
</tool_guidelines>
diff --git a/internal/agent/prompts.go b/internal/agent/prompts.go
index 80d158d35..0e13b2629 100644
--- a/internal/agent/prompts.go
+++ b/internal/agent/prompts.go
@@ -253,6 +253,18 @@ func formatSkillsMetadata(skillsMetadata []*skills.SkillMetadata, shellExecEnabl
builder.WriteString(fmt.Sprintf(" %s\n\n", skill.Description))
}
+ builder.WriteString("#### Workspace\n\n")
+ builder.WriteString("Everything you run happens in this session's sandbox, ")
+ builder.WriteString("whose working directory is `/workspace`:\n")
+ builder.WriteString("- `/workspace/input`: the user's uploaded files, listed in ")
+ builder.WriteString("`<sandbox_attachments>`. Read-only — pass their absolute paths as arguments\n")
+ builder.WriteString("- `/workspace/output`: what you generate for the user. ")
+ builder.WriteString("Files here are collected for download\n")
+ builder.WriteString("- `/workspace/.skill-packages/<skill>`: where on-demand Python extras go, ")
+ builder.WriteString("since the skill tree is frozen after install\n")
+ builder.WriteString("- The skills themselves live under `/opt/weknora/tenant/skills` and are ")
+ builder.WriteString("reached through `read_skill` / `execute_skill_script`, never by `ls` or `cat`\n\n")
+
builder.WriteString("#### Tool Reference\n\n")
builder.WriteString("- `read_skill(skill_name)`: Load SKILL.md **and** list the skill's files. This is how you discover scripts — do not `list_sandbox_files` or `ls` `/opt/weknora/tenant/skills/...`\n")
builder.WriteString("- `read_skill(skill_name, file_path)`: Read one file inside the skill (`file_path` is relative, e.g. `scripts/generate_ppt.py`)\n")
@@ -261,6 +273,9 @@ func formatSkillsMetadata(skillsMetadata []*skills.SkillMetadata, shellExecEnabl
builder.WriteString(" - `input`: Pass data directly via stdin (use this when you have data in memory, e.g. JSON string)\n")
builder.WriteString(" - `args`: Command-line arguments; pass absolute `/workspace/input/...` paths from `<sandbox_attachments>` for user-uploaded files\n")
builder.WriteString(" - Treat `/workspace/input` as read-only and write generated files only to `$WEKNORA_SKILL_OUTPUT_DIR`\n")
+ builder.WriteString(" - Scripts run with `/workspace` as their working directory, so a relative ")
+ builder.WriteString("path inside a script resolves there, not inside the skill; ")
+ builder.WriteString("`$WEKNORA_SKILL_DIR` is how a script reaches its own files\n")
builder.WriteString(sandboxArtifactReferenceGuidance())
builder.WriteString(" - Each skill keeps its dependencies to itself (virtualenv or node_modules); ")
builder.WriteString("this tool already runs scripts the right way. A bare `python3 -c` / `node -e` ")
@@ -271,7 +286,10 @@ func formatSkillsMetadata(skillsMetadata []*skills.SkillMetadata, shellExecEnabl
builder.WriteString("then execute_skill_script; or ask the user to reinstall the skill so extras are baked in\n")
if shellExecEnabled {
builder.WriteString("- `shell_exec(command, work_dir, timeout_sec, max_output_bytes, max_stderr_bytes, env)`: Freely execute shell commands and explore the current session's isolated Cube sandbox\n")
- builder.WriteString(" - User-uploaded files are restored under `/workspace/input` and listed in `<sandbox_attachments>`\n")
+ builder.WriteString(" - Every command already starts in `/workspace`, so use relative paths ")
+ builder.WriteString("(`ls -la output/`) and do not prefix `cd /workspace &&`. A `cd` inside one ")
+ builder.WriteString("command does not carry over to the next; pass `work_dir` when a command ")
+ builder.WriteString("must run elsewhere\n")
builder.WriteString(" - Use `find` and `ls` to discover files; use `cat`, `head`, `tail`, and `sed` to inspect text; use `grep` and `awk` to search and process content; use `file` for an unknown type\n")
builder.WriteString(" - Do not `ls` / `find` / `cat` / `file` a skill under `/opt/weknora/tenant/skills` to discover scripts. `read_skill(skill_name)` already lists them; that tree also contains `.venv` / `node_modules`\n")
builder.WriteString(" - Use shell pipelines, redirects, scripts, package managers, compilers, and other installed commands whenever they are the most direct way to complete the task\n")
diff --git a/internal/agent/prompts_shell_test.go b/internal/agent/prompts_shell_test.go
index 8a1fb6823..ed6854cdb 100644
--- a/internal/agent/prompts_shell_test.go
+++ b/internal/agent/prompts_shell_test.go
@@ -31,6 +31,13 @@ func TestFormatSkillsMetadataIncludesShellGuidanceOnlyWhenEnabled(t *testing.T)
assert.Contains(t, enabled, "install_deps.py")
assert.Contains(t, enabled, "never nest ASCII")
+ assert.Contains(t, enabled, "Every command already starts in `/workspace`")
+ assert.Contains(t, enabled, "do not prefix `cd /workspace &&`")
+
disabled := formatSkillsMetadata(metadata, false)
assert.NotContains(t, disabled, "shell_exec")
+ // The workspace layout describes where skill scripts read and write, so it
+ // stays even when the agent has no shell of its own.
+ assert.Contains(t, disabled, "whose working directory is `/workspace`")
+ assert.Contains(t, disabled, "/workspace/output")
}
diff --git a/internal/agent/tools/shell_exec.go b/internal/agent/tools/shell_exec.go
index e3562b5dc..0b37cdb9c 100644
--- a/internal/agent/tools/shell_exec.go
+++ b/internal/agent/tools/shell_exec.go
@@ -128,6 +128,17 @@ var shellExecTool = BaseTool{
name: ToolShellExec,
description: `Run a shell command inside the current session's isolated remote sandbox.
+## Working Directory
+- Every command already starts in ` + "`/workspace`" + `, this session's own
+ workspace. Use RELATIVE paths (` + "`ls -la output/`" + `,
+ ` + "`python3 report.py`" + `) and do NOT prefix ` + "`cd /workspace && `" + `
+ onto them — you are already there, and the prefix wastes a line on every call.
+- ` + "`input/`" + ` holds the user's uploaded files and is read-only;
+ ` + "`output/`" + ` is collected for download, so generated files belong there.
+- Each call starts in that directory again: a ` + "`cd`" + ` inside one command
+ does not carry over to the next one. Pass ` + "`work_dir`" + ` when a command
+ must run elsewhere.
+
## Usage
- Use freely to explore and operate inside the sandbox: inspect files, search
content, transform data, run programs, manage dependencies, install system packages and verify outputs.
@@ -136,9 +147,9 @@ var shellExecTool = BaseTool{
` + "`grep`" + ` / ` + "`awk`" + ` to search; ` + "`file`" + ` for an unknown type.
Do not ` + "`apt-get install`" + ` inspection utilities (` + "`tree`" + `, editors)
after a 127 — those packages vanish with the session.
-- User-uploaded files listed in ` + "`<sandbox_attachments>`" + ` are restored under
- ` + "`/workspace/input`" + `. Treat them as read-only inputs; write generated files
- under ` + "`/workspace/output`" + `.
+- User-uploaded files are listed in the current ` + "`<sandbox_attachments>`" + `
+ block, with the absolute ` + "`/workspace/input/...`" + ` path to pass to a
+ command that takes an input file.
- Install extra Python packages into the session overlay
(` + "`python3 -m pip install --target /workspace/.skill-packages/<skill> ...`" + `),
never into ` + "`/opt/weknora/tenant/skills`" + `. The skill venv is frozen after
@@ -183,8 +194,9 @@ var shellExecTool = BaseTool{
Supports pipes, redirects, ` + "`&&`" + ` / ` + "`||`" + ` chaining. Keep this short;
large scripts go through ` + "`write_sandbox_file`" + `; small edits go through
` + "`edit_sandbox_file`" + `.
-- ` + "`work_dir`" + ` (optional): working directory, defaults to ` + "`/workspace`" + `.
- Created on demand if it doesn't exist.
+- ` + "`work_dir`" + ` (optional): an absolute path under ` + "`/workspace`" + `,
+ defaulting to ` + "`/workspace`" + ` itself — omit it unless the command has to
+ run in another directory. Created on demand if it doesn't exist.
- ` + "`timeout_sec`" + ` (optional): per-call timeout in seconds. Defaults to 120,
capped at 600. Large installs (LibreOffice, TensorFlow) may need the cap.
- ` + "`max_output_bytes`" + ` (optional): maximum bytes returned from stdout.
@@ -230,7 +242,7 @@ type ShellExecInput struct {
// Command is the shell command to execute. Runs under `/bin/bash -l -c`.
Command string `json:"command" jsonschema:"Shell command to execute (single line, supports pipes and && chaining). Runs under /bin/bash -l -c."`
// WorkDir is the working directory for the command; defaults to /workspace.
- WorkDir string `json:"work_dir,omitempty" jsonschema:"Working directory for the command. Defaults to /workspace. Created on demand if missing."`
+ WorkDir string `json:"work_dir,omitempty" jsonschema:"Absolute work dir. Commands already start in /workspace; omit unless the command must run elsewhere."` //nolint:lll // one-line struct tag
// TimeoutSec caps execution time. Zero uses the default (120s); the
// value is hard-capped at 600s regardless of what the LLM requests.
TimeoutSec int `json:"timeout_sec,omitempty" jsonschema:"Per-call timeout in seconds. Defaults to 120, hard-capped at 600."`
@@ -381,9 +393,6 @@ func installShellExecDescription(defaultWorkDir string) string {
command-length cap and mangles quoting.
- Install Python extras into the skill's ` + "`.venv`" + `, Node extras into
` + "`node_modules`" + `. Prefer ` + "`uv pip install`" + ` / ` + "`python3 -m venv`" + `.
-- ` + "`write_sandbox_file`" + ` / ` + "`read_sandbox_file`" + ` are not
- available; they only reach ` + "`/workspace`" + `, which is wiped before the
- snapshot.
## Parameters
- ` + "`command`" + ` (required): the shell one-liner under ` + "`/bin/bash -l -c`" + `.
diff --git a/internal/agent/tools/skill_execute.go b/internal/agent/tools/skill_execute.go
index 0caf01b40..42ec44e66 100644
--- a/internal/agent/tools/skill_execute.go
+++ b/internal/agent/tools/skill_execute.go
@@ -20,6 +20,14 @@ var executeSkillScriptTool = BaseTool{
name: ToolExecuteSkillScript,
description: `Execute a script with a skill's own interpreter and dependencies.
+## Working Directory
+- The script runs with ` + "`/workspace`" + ` as its working directory, whichever
+ skill it belongs to. A relative path the script itself opens resolves there,
+ not inside the skill; ` + "`$WEKNORA_SKILL_DIR`" + ` is how a script reaches the
+ files installed beside it.
+- Generated files belong in ` + "`$WEKNORA_SKILL_OUTPUT_DIR`" + `, which is
+ collected for download. ` + "`/workspace/input`" + ` is read-only.
+
## Usage
- ` + "`script_path`" + ` is either:
- a path **inside the skill** (` + "`scripts/analyze.py`" + `), or