Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
refactor(skills): introduce write_skill_file and edit_skill_file tools for skill directory management
wizardchendd647fefad99
diff --git a/config/builtin_agents.yaml b/config/builtin_agents.yamlindex 9a9ea5a18..6716fba71 100644--- a/config/builtin_agents.yaml+++ b/config/builtin_agents.yaml@@ -261,8 +261,15 @@ builtin_agents:max_iterations: 30kb_selection_mode: "none"retrieve_kb_only_when_mentioned: false+ # The install path unions these three in regardless of what is written+ # here: an install that cannot write its own skill directory cannot+ # record what it did. They are listed for accuracy, not as the source of+ # truth. write_skill_file / edit_skill_file reach only the one skill+ # being installed and are never offered to a tenant-editable agent.allowed_tools:- "shell_exec"+ - "write_skill_file"+ - "edit_skill_file"web_search_enabled: falseweb_search_max_results: 0reflection_enabled: falsediff --git a/config/prompt_templates/agent_system_prompt.yaml b/config/prompt_templates/agent_system_prompt.yamlindex b9c8ed5dc..786ad18d9 100644--- a/config/prompt_templates/agent_system_prompt.yaml+++ b/config/prompt_templates/agent_system_prompt.yaml@@ -516,9 +516,19 @@ templates:1. Read the SKILL.md text in the user message and work out what has to be installed. Dependencies are often described in prose rather than a requirements file — read carefully.2. Inspect the skill directory with `ls -la` before installing, so you know which of requirements.txt / pyproject.toml / package.json actually exist.3. Install dependencies INTO THE SKILL DIRECTORY (see <isolation>), including on-demand extras (see <on_demand_dependencies>).- 4. Reply with a short summary: what you installed, where it went.+ 4. PROVE the imports resolve by running them (see <prove_it_runs>). Do not skip this: nothing else can check it.+ 5. Reply with a short summary: what you installed, where it went, and anything you had to change in the skill's own files.</workflow>+ <prove_it_runs>+ You are the only party that can tell whether this skill's imports actually resolve. The server's check parses files without executing them, so it never finds out — it will not catch an import you left broken.+ - For each script the skill offers, run the import the way the skill would: `<skill-dir>/.venv/bin/python -c 'import x'`, or the script's own `--help` if it has one.+ - A failure is usually one of two things. A missing distribution: install it. Or a module the skill SHIPS that Python cannot find — then the script needs its directory on `sys.path`.+ - Prefer installing over editing. Editing a shipped source file is a last resort with a real cost: `read_skill` serves the uploaded archive while scripts run from this image, so a later session would read one version of that file and run another. If you must edit one with `edit_skill_file`, keep the change as small as possible and name the file in your summary so the user can fix the archive.+ - Import names and distribution names differ often: PIL → pillow, yaml → pyyaml, docx → python-docx, pptx → python-pptx, cv2 → opencv-python-headless, bs4 → beautifulsoup4, sklearn → scikit-learn, fitz → pymupdf.+ - Do not report success until every entry point imports cleanly.+ </prove_it_runs>+<on_demand_dependencies>Many skills defer optional packages (python-docx, python-pptx, …) to a first-use script such as `scripts/install_deps.py --word`. That pattern does not work after this install: the skill tree is snapshotted read-only and `uv venv` often has no pip, so a later chat cannot `pip install` into the venv.- Install every extra NOW. Read SKILL.md, requirements extras, pyproject optional-dependencies, and any `install_deps.py` / whitelist of locked packages.@@ -537,8 +547,9 @@ templates:</isolation><tool_guidelines>- * **shell_exec:** your only tool. `write_sandbox_file` / `edit_sandbox_file` / `list_sandbox_files` / `read_sandbox_file` are not registered. You may set `work_dir` to the skill directory (it is allowed for this session) and then use relative paths, or leave `work_dir` unset and use absolute paths. Both work.- * Write `.weknora/requirements.json` with a short `mkdir -p .weknora && cat > .weknora/requirements.json <<'EOF'` redirect. Do not call `write_sandbox_file` — it only accepts `/workspace`, which is wiped before the snapshot.+ * **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/tools/definitions.go b/internal/agent/tools/definitions.goindex 71803ecfe..d1c2436b4 100644--- a/internal/agent/tools/definitions.go+++ b/internal/agent/tools/definitions.go@@ -32,6 +32,16 @@ const (ToolReadSandboxFile = "read_sandbox_file"ToolWriteSandboxFile = "write_sandbox_file"ToolEditSandboxFile = "edit_sandbox_file"+ // ToolWriteSkillFile / ToolEditSkillFile write the skill tree under+ // /opt/weknora/tenant/skills rather than /workspace, and exist only for+ // the built-in skill installer. They are scoped to the one skill being+ // installed; see internal/agent/tools/skill_file.go.+ //+ // Deliberately absent from AvailableToolDefinitions: these write the+ // shared snapshot image, so they are granted by install mode alone and+ // must not become selectable on a tenant-editable agent config.+ ToolWriteSkillFile = "write_skill_file"+ ToolEditSkillFile = "edit_skill_file"// ToolShellExec lets the LLM execute ad-hoc shell commands inside the// current session's sandbox (dependency installs, environment probing).// Registered only when the resolved backend advertises the session shelldiff --git a/internal/agent/tools/python_syntax.go b/internal/agent/tools/python_syntax.goindex ce82f9d8a..5792c05f5 100644--- a/internal/agent/tools/python_syntax.go+++ b/internal/agent/tools/python_syntax.go@@ -28,7 +28,10 @@ var pythonKeywords = map[string]bool{"while": true, "with": true, "yield": true,}-func pythonScriptSyntaxHint(filePath, src string) string {+// pythonScriptSyntaxHint reports the nested-quote failure, if any, in a file+// just written. editTool names the tool that can repair it: the same guidance+// serves /workspace writes and skill-tree writes, which have different editors.+func pythonScriptSyntaxHint(filePath, src, editTool string) string {switch strings.ToLower(path.Ext(filePath)) {case ".py":default:@@ -42,9 +45,9 @@ func pythonScriptSyntaxHint(filePath, src string) string {"Python syntax looks broken around line %d: an ASCII quote inside a "+"string of the same kind closed the literal early "+"(e.g. (\"这不是一个\"大干快上\"...\")). The file was written. "+- "Fix it with edit_sandbox_file: wrap that text in the other quote, "++ "Fix it with %s: wrap that text in the other quote, "+"or use 「」 / \\\" for the inner quotation. Do not execute the script until it parses.",- line,+ line, editTool,)}diff --git a/internal/agent/tools/python_syntax_test.go b/internal/agent/tools/python_syntax_test.goindex 876d0bc66..eb8f71ab9 100644--- a/internal/agent/tools/python_syntax_test.go+++ b/internal/agent/tools/python_syntax_test.go@@ -49,8 +49,11 @@ func TestFirstBrokenPythonQuoteReportsUnclosed(t *testing.T) {func TestPythonScriptSyntaxHintOnlyForPy(t *testing.T) {src := "(\"这不是一个\"大干快上\"的夜晚\")\n"- assert.NotEmpty(t, pythonScriptSyntaxHint("/workspace/output/x.py", src))- assert.Empty(t, pythonScriptSyntaxHint("/workspace/output/x.md", src))+ assert.Contains(t, pythonScriptSyntaxHint("/workspace/output/x.py", src, ToolEditSandboxFile),+ ToolEditSandboxFile, "the hint must name the tool that can repair this file")+ assert.Contains(t, pythonScriptSyntaxHint(testSkillDir+"/run.py", src, ToolEditSkillFile),+ ToolEditSkillFile, "a skill-tree file is not repairable with edit_sandbox_file")+ assert.Empty(t, pythonScriptSyntaxHint("/workspace/output/x.md", src, ToolEditSandboxFile))}func TestPythonSyntaxErrorHint(t *testing.T) {diff --git a/internal/agent/tools/sandbox_edit.go b/internal/agent/tools/sandbox_edit.goindex e7d34dd3c..8944601f3 100644--- a/internal/agent/tools/sandbox_edit.go+++ b/internal/agent/tools/sandbox_edit.go@@ -229,7 +229,7 @@ func (t *EditSandboxFileTool) Execute(ctx context.Context, args json.RawMessage)logger.Infof(ctx, "[Tool][EditSandboxFile] session=%s path=%s replacements=%d bytes=%d",sessionID, clean, replacements, len(content))- if hint := pythonScriptSyntaxHint(clean, updated); hint != "" {+ if hint := pythonScriptSyntaxHint(clean, updated, ToolEditSandboxFile); hint != "" {return &types.ToolResult{Success: false,Error: hint,diff --git a/internal/agent/tools/sandbox_write.go b/internal/agent/tools/sandbox_write.goindex 1de40aa60..d63165d65 100644--- a/internal/agent/tools/sandbox_write.go+++ b/internal/agent/tools/sandbox_write.go@@ -180,7 +180,7 @@ func (t *WriteSandboxFileTool) Execute(ctx context.Context, args json.RawMessagelogger.Infof(ctx, "[Tool][WriteSandboxFile] session=%s path=%s bytes=%d",sessionID, clean, len(content))- if hint := pythonScriptSyntaxHint(clean, input.Content); hint != "" {+ if hint := pythonScriptSyntaxHint(clean, input.Content, ToolEditSandboxFile); hint != "" {return &types.ToolResult{Success: false,Error: hint,diff --git a/internal/agent/tools/shell_exec.go b/internal/agent/tools/shell_exec.goindex bba36e7bf..e3562b5dc 100644--- a/internal/agent/tools/shell_exec.go+++ b/internal/agent/tools/shell_exec.go@@ -295,6 +295,13 @@ type ShellExecTool struct {// workDirRoots are the directories work_dir may point inside. Ordinary// sessions get /workspace only; install mode adds the skills image root.workDirRoots []string+ // defaultWorkDir is where a call that omits work_dir lands. Empty means+ // /workspace, which is right for an ordinary session and wrong for an+ // install: an install works in one skill directory and is told not to+ // touch /workspace at all (it is wiped before the snapshot). Leaving the+ // default there made the model prefix `cd <skill-dir> &&` onto command+ // after command, since that is the spelling guaranteed to work.+ defaultWorkDir string// defaultTimeout is applied when the caller omits timeout_sec. Ordinary// sessions keep the 120s default; install mode uses the 10-minute cap// because dependency installs routinely exceed two minutes.@@ -329,13 +336,24 @@ func NewShellExecTool(executor SandboxCommandExecutor, envResolver skills.SkillE// NewInstallShellExecTool constructs the install-mode variant: commands run as// root and may work inside the skills image root. It is registered only for// the built-in skill installer agent (see AgentConfig.SkillInstallMode).-func NewInstallShellExecTool(executor SandboxInstallCommandExecutor) *ShellExecTool {+//+// skillDir becomes the default working directory, because every command an+// install runs belongs there. A validated directory is required for that: an+// empty or unrecognised one falls back to /workspace rather than guessing.+func NewInstallShellExecTool(+ executor SandboxInstallCommandExecutor, skillDir string,+) *ShellExecTool {base := shellExecTool- base.description = installShellExecDescription()+ defaultWorkDir, ok := sandbox.ValidatedImageSkillDir(skillDir)+ if !ok {+ defaultWorkDir = defaultShellExecWorkDir+ }+ base.description = installShellExecDescription(defaultWorkDir)return &ShellExecTool{BaseTool: base,executor: installShellExecutor{inner: executor},workDirRoots: []string{defaultShellExecWorkDir, sandbox.SkillsImageRoot},+ defaultWorkDir: defaultWorkDir,defaultTimeout: shellExecMaxTimeout,}}@@ -344,24 +362,32 @@ func NewInstallShellExecTool(executor SandboxInstallCommandExecutor) *ShellExecT// guidance. That tool is not registered in install mode, and the files this// agent must write sit under the skills image root, which write_sandbox_file// cannot accept.-func installShellExecDescription() string {+func installShellExecDescription(defaultWorkDir string) string {return `Run a shell command as root inside the skill-install sandbox.+## Working Directory+- Every command already starts in ` + "`" + defaultWorkDir + "`" + `, the skill+ you are installing. Use RELATIVE paths: ` + "`ls -la scripts/`" + `,+ ` + "`cat requirements.txt`" + `, ` + "`uv venv --seed .venv`" + `.+- Do NOT prefix ` + "`cd " + defaultWorkDir + " && `" + ` onto your commands.+ You are already there, and the prefix wastes a line on every call.+- Pass ` + "`work_dir`" + ` only to leave that directory, which an install+ rarely needs.+## Usage-- This is your only tool. write_sandbox_file / edit_sandbox_file /- list_sandbox_files / read_sandbox_file are not available.-- work_dir may be the skill directory under ` + "`/opt/weknora/tenant/skills`" + `.-- Write small files (including ` + "`.weknora/requirements.json`" + `) with a- short redirect: ` + "`mkdir -p .weknora && cat > .weknora/requirements.json <<'EOF'`" + `.- Do not try write_sandbox_file — it only accepts ` + "`/workspace`" + `, which- is wiped before the snapshot.+- Run commands with this tool. Create or change files in the skill directory+ with ` + "`write_skill_file`" + ` / ` + "`edit_skill_file`" + ` instead of+ ` + "`cat`" + ` or a heredoc: a shell redirect truncates at the+ 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`" + `.-- ` + "`work_dir`" + ` (optional): defaults to ` + "`/workspace`" + `; the skill- directory is allowed.+- ` + "`work_dir`" + ` (optional): defaults to ` + "`" + defaultWorkDir + "`" + `.- ` + "`timeout_sec`" + ` (optional): defaults to 600 seconds.## Returns@@ -437,7 +463,7 @@ func (t *ShellExecTool) Execute(ctx context.Context, args json.RawMessage) (*typworkDir := strings.TrimSpace(input.WorkDir)if workDir == "" {- workDir = defaultShellExecWorkDir+ workDir = t.effectiveDefaultWorkDir()}cleanWorkDir := path.Clean(workDir)if !t.workDirAllowed(cleanWorkDir) {@@ -677,6 +703,15 @@ func (t *ShellExecTool) isInstallMode() bool {return false}+// effectiveDefaultWorkDir keeps a zero-value tool on the ordinary /workspace+// contract; only the install-mode constructor sets anything else.+func (t *ShellExecTool) effectiveDefaultWorkDir() string {+ if strings.TrimSpace(t.defaultWorkDir) == "" {+ return defaultShellExecWorkDir+ }+ return t.defaultWorkDir+}+// allowedWorkDirRoots defaults to /workspace so a zero-value tool (or one// built before install mode existed) keeps the ordinary contract.func (t *ShellExecTool) allowedWorkDirRoots() []string {diff --git a/internal/agent/tools/shell_exec_test.go b/internal/agent/tools/shell_exec_test.goindex 0944a5af4..94356fd95 100644--- a/internal/agent/tools/shell_exec_test.go+++ b/internal/agent/tools/shell_exec_test.go@@ -72,6 +72,7 @@ func TestShellExecTimeoutHonorsAndCapsRequestedValue(t *testing.T) {type fakeInstallShellExecutor struct {timeout time.Duration+ workDir stringcalls int}@@ -79,24 +80,81 @@ func (f *fakeInstallShellExecutor) ExecShellCommandWithOptions(_ context.Context, _ string, _ string, opts sandbox.ShellExecOptions,) (*sandbox.ExecuteResult, error) {f.timeout = opts.Timeout+ f.workDir = opts.WorkDirf.calls++return &sandbox.ExecuteResult{ExitCode: 0}, nil}+// installShellSkillDir is the directory an install owns, and the working+// directory its shell must default to.+const installShellSkillDir = sandbox.SkillsImageRoot + "/pdf-tools"+func TestInstallShellExecDescriptionDoesNotPointAtWriteSandboxFile(t *testing.T) {- description := NewInstallShellExecTool(&fakeInstallShellExecutor{}).Description()+ description := NewInstallShellExecTool(&fakeInstallShellExecutor{}, installShellSkillDir).Description()- assert.Contains(t, description, "only tool")- assert.Contains(t, description, "requirements.json")- assert.Contains(t, description, sandbox.SkillsImageRoot)+ assert.Contains(t, description, ToolWriteSkillFile,+ "the writer for this tree is write_skill_file, not a heredoc")+ assert.Contains(t, description, installShellSkillDir)assert.NotContains(t, description, "Do NOT dump large files through")assert.NotContains(t, NewShellExecTool(&fakeShellExecutor{}, nil).Description(),"write_sandbox_file is not available")}+// The model reached for `cd <skill-dir> && …` on command after command because+// the default landed it in /workspace — a directory an install is told not to+// touch, since it is wiped before the snapshot. Naming the skill directory as+// the default is what removes the prefix.+func TestInstallShellExecDefaultsToTheSkillDirectory(t *testing.T) {+ inner := &fakeInstallShellExecutor{}+ tool := NewInstallShellExecTool(inner, installShellSkillDir)++ result, err := tool.Execute(shellExecTestContext(), json.RawMessage(+ `{"command":"ls -la scripts/"}`,+ ))++ require.NoError(t, err)+ require.True(t, result.Success, result.Error)+ assert.Equal(t, installShellSkillDir, inner.workDir)+ assert.Equal(t, installShellSkillDir, result.Data["work_dir"],+ "the transcript must show where the command actually ran")++ assert.Contains(t, tool.Description(), "Do NOT prefix",+ "the default alone did not stop the model; it has to be told")+}++// An explicit work_dir still wins: an install occasionally has to leave its own+// directory, and the allowed roots have not changed.+func TestInstallShellExecStillHonoursAnExplicitWorkDir(t *testing.T) {+ inner := &fakeInstallShellExecutor{}++ result, err := NewInstallShellExecTool(inner, installShellSkillDir).Execute(+ shellExecTestContext(),+ json.RawMessage(`{"command":"ls","work_dir":"/workspace"}`),+ )++ require.NoError(t, err)+ require.True(t, result.Success, result.Error)+ assert.Equal(t, "/workspace", inner.workDir)+}++// A run that somehow carries no valid skill directory must not invent one, and+// must not send commands to a path outside the allowed roots.+func TestInstallShellExecFallsBackToWorkspaceWithoutAValidSkillDir(t *testing.T) {+ for _, dir := range []string{"", sandbox.SkillsImageRoot, "/etc", "/opt/weknora/tenant/skills/a/b"} {+ inner := &fakeInstallShellExecutor{}++ result, err := NewInstallShellExecTool(inner, dir).Execute(+ shellExecTestContext(), json.RawMessage(`{"command":"ls"}`))++ require.NoError(t, err)+ require.True(t, result.Success, result.Error)+ assert.Equal(t, "/workspace", inner.workDir, "skillDir %q must not become a default", dir)+ }+}+func TestInstallShellExecDefaultsToTheTenMinuteBudget(t *testing.T) {inner := &fakeInstallShellExecutor{}- tool := NewInstallShellExecTool(inner)+ tool := NewInstallShellExecTool(inner, installShellSkillDir)result, err := tool.Execute(shellExecTestContext(), json.RawMessage(`{"command":"pip install -r requirements.txt"}`,@@ -357,7 +415,7 @@ func TestShellExecDoesNotCaptureWhenExecutorErrors(t *testing.T) {func TestInstallShellExecDoesNotCapture(t *testing.T) {recorder := &recordedCapture{}- tool := NewInstallShellExecTool(&fakeInstallShellExecutor{}).WithEnvCapture(recorder.capture)+ tool := NewInstallShellExecTool(&fakeInstallShellExecutor{}, installShellSkillDir).WithEnvCapture(recorder.capture)result, err := tool.Execute(shellExecTestContext(), json.RawMessage(`{"command":"export USER_TOKEN=x; pip install x","skill_name":"pdf-tools"}`,@@ -454,7 +512,7 @@ func TestShellExecAllowsOverlayInstallThatMentionsTheSkillTree(t *testing.T) {func TestInstallShellExecStillPipsIntoTheSkillTree(t *testing.T) {inner := &fakeInstallShellExecutor{}- tool := NewInstallShellExecTool(inner)+ tool := NewInstallShellExecTool(inner, installShellSkillDir)result, err := tool.Execute(shellExecTestContext(), json.RawMessage(`{"command":"pip install python-docx","work_dir":"/opt/weknora/tenant/skills/律师助手"}`,diff --git a/internal/agent/tools/skill_file.go b/internal/agent/tools/skill_file.gonew file mode 100644index 000000000..e375a00a9--- /dev/null+++ b/internal/agent/tools/skill_file.go@@ -0,0 +1,413 @@+// Package tools — write_skill_file / edit_skill_file.+//+// The installer agent's only writer used to be `shell_exec` with a heredoc.+// That caps every file at the shell's command-length limit and puts the+// content through two levels of quoting, so a requirements.json or a small+// patch script routinely arrived truncated or mangled. These two tools write+// the same bytes over the file API instead.+//+// They are separate from write_sandbox_file / edit_sandbox_file rather than a+// loosening of them. Those write /workspace, which is wiped before the+// snapshot; the skill tree lives under /opt/weknora/tenant/skills and is what+// the snapshot keeps. Sharing one tool would mean one path guard covering both+// a per-session scratch area and the shared image.+//+// Scope: one install writes one skill. The tool is constructed with that+// skill's directory and refuses everything outside it, so an installer cannot+// reach a neighbouring skill in the shared image even though its shell runs as+// root. The prompt asks for the same thing; this enforces it.+package tools++import (+ "context"+ "encoding/json"+ "fmt"+ "path"+ "strings"++ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/utils"+)++// SkillFileStore is the write surface these tools need. Production uses+// *sandbox.SessionBoundManager, whose WriteSessionFile already refuses any+// path outside the skills image root; the per-skill scope below narrows that+// to the one directory this install owns.+type SkillFileStore interface {+ StatSessionFile(ctx context.Context, sessionID, filePath string) (*sandbox.RemoteStatEntry, error)+ ReadSessionFile(ctx context.Context, sessionID, filePath string) ([]byte, error)+ WriteSessionFile(ctx context.Context, sessionID, filePath string, content []byte) error+}++var writeSkillFileTool = BaseTool{+ name: ToolWriteSkillFile,+ description: `Create or overwrite a text file inside the skill directory being installed.++## Usage+- This is the way to write a file into the skill tree. Do NOT use+ ` + "`shell_exec`" + ` with ` + "`cat`" + `, a heredoc, or ` + "`python -c`" + `:+ those hit a command-length cap and mangle quoting.+- Use it for ` + "`.weknora/requirements.json`" + `, a small wrapper script, or a+ patch to a shipped file.+- ` + pythonQuoteGuidance + `++## When NOT to Use+- To change a few lines of an existing file, call ` + "`edit_skill_file`" + `.+- To write scratch files — the skill directory is snapshotted; keep it clean.+- Binary content. Have a script produce binary files instead.++## Path Rules+- ` + "`path`" + ` MUST be absolute and inside this install's skill directory.+ A relative path is resolved against that directory.+- Any path outside it is refused, including another skill's directory.++## Size Handling+- Content is capped at 262144 bytes per call.++## Returns+- The absolute path and byte count. File contents are not echoed back.`,+ schema: utils.GenerateSchema[WriteSkillFileInput](),+}++// WriteSkillFileInput defines the input parameters for write_skill_file.+type WriteSkillFileInput struct {+ Path string `json:"path" jsonschema:"Path of the file to write, inside the skill directory being installed. Absolute, or relative to that directory."`+ Content string `json:"content" jsonschema:"Full text contents of the file. Overwrites any existing file at path. Maximum 262144 bytes. Do not send binary bytes."`+}++// WriteSkillFileTool writes a text file into the skill directory under install.+type WriteSkillFileTool struct {+ BaseTool+ store SkillFileStore+ skillDir string+}++// NewWriteSkillFileTool constructs the tool. `store` MUST NOT be nil and+// `skillDir` MUST be the directory of the skill this install owns.+func NewWriteSkillFileTool(store SkillFileStore, skillDir string) *WriteSkillFileTool {+ return &WriteSkillFileTool{+ BaseTool: writeSkillFileTool,+ store: store,+ skillDir: skillDir,+ }+}++// Execute writes the file after confirming it lands inside the skill directory.+func (t *WriteSkillFileTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) {+ logger.Infof(ctx, "[Tool][WriteSkillFile] Execute started")++ var input WriteSkillFileInput+ if err := json.Unmarshal(args, &input); err != nil {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("Failed to parse args: %v", err),+ }, nil+ }+ if t.store == nil {+ return &types.ToolResult{+ Success: false,+ Error: "skill file writing is not available in this deployment",+ }, nil+ }++ sessionID := resolveSessionID(ctx)+ if sessionID == "" {+ return &types.ToolResult{+ Success: false,+ Error: "no session ID in context; write_skill_file must run inside an agent turn",+ }, nil+ }++ clean, err := resolveSkillFilePath(t.skillDir, input.Path)+ if err != nil {+ return &types.ToolResult{Success: false, Error: err.Error()}, nil+ }++ content := []byte(input.Content)+ if len(content) > maxWriteSandboxBytes {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf(+ "content too large (%d bytes; max %d). Split the file",+ len(content), maxWriteSandboxBytes,+ ),+ }, nil+ }+ if isBinaryShellOutput(input.Content) {+ return &types.ToolResult{+ Success: false,+ Error: "binary content is not accepted; write a text file instead",+ }, nil+ }++ if err := t.store.WriteSessionFile(ctx, sessionID, clean, content); err != nil {+ logger.Warnf(ctx, "[Tool][WriteSkillFile] write failed: session=%s path=%s err=%v",+ sessionID, clean, err)+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("failed to write %s: %v", clean, err),+ }, nil+ }++ logger.Infof(ctx, "[Tool][WriteSkillFile] session=%s path=%s bytes=%d",+ sessionID, clean, len(content))++ data := map[string]interface{}{+ "display_type": ToolWriteSkillFile,+ "session_id": sessionID,+ "path": clean,+ "root": t.skillDir,+ "name": path.Base(clean),+ "size": len(content),+ }+ if hint := pythonScriptSyntaxHint(clean, input.Content, ToolEditSkillFile); hint != "" {+ data["syntax_error"] = true+ return &types.ToolResult{+ Success: false,+ Error: hint,+ Output: fmt.Sprintf("=== Wrote skill file with syntax problems: %s ===\n\n%s\n", clean, hint),+ Data: data,+ }, nil+ }+ return &types.ToolResult{+ Success: true,+ Output: fmt.Sprintf("=== Wrote skill file: %s ===\n\nbytes=%d\n", clean, len(content)),+ Data: data,+ }, nil+}++// Cleanup releases any resources.+func (t *WriteSkillFileTool) Cleanup(ctx context.Context) error {+ return nil+}++var editSkillFileTool = BaseTool{+ name: ToolEditSkillFile,+ description: `Replace exact text in a file inside the skill directory being installed.++## Usage+- Use this when only a few lines of an existing file need to change — a wrong+ path, an import, a constant.+- ` + "`old_string`" + ` must match the file exactly, including whitespace and+ quotes. Include a few surrounding lines so the match is unique.+- Default: the snippet must occur exactly once. Set ` + "`replace_all=true`" + `+ only when you intentionally want every occurrence changed.+- ` + pythonQuoteGuidance + `++## When NOT to Use+- Creating a new file — use ` + "`write_skill_file`" + `.+- Replacing most of the file — rewrite it with ` + "`write_skill_file`" + `.+- Binary files.++## Path Rules+- ` + "`path`" + ` MUST be inside this install's skill directory. Absolute, or+ relative to that directory.++## Size Handling+- The file (and the result) must stay within 262144 bytes.++## Returns+- The path, how many replacements were made, and the new byte count.`,+ schema: utils.GenerateSchema[EditSkillFileInput](),+}++// EditSkillFileInput defines the input parameters for edit_skill_file.+type EditSkillFileInput struct {+ Path string `json:"path" jsonschema:"Path of an existing text file inside the skill directory being installed. Absolute, or relative to that directory."`+ OldString string `json:"old_string" jsonschema:"Exact text to find. Include enough surrounding lines so the match is unique unless replace_all is true."`+ NewString string `json:"new_string" jsonschema:"Replacement text. Use an empty string to delete the matched text."`+ ReplaceAll bool `json:"replace_all,omitempty" jsonschema:"If true, replace every occurrence. If false (default), old_string must match exactly once."`+}++// EditSkillFileTool applies an exact string replacement inside the skill tree.+type EditSkillFileTool struct {+ BaseTool+ store SkillFileStore+ skillDir string+}++// NewEditSkillFileTool constructs the tool. `store` MUST NOT be nil and+// `skillDir` MUST be the directory of the skill this install owns.+func NewEditSkillFileTool(store SkillFileStore, skillDir string) *EditSkillFileTool {+ return &EditSkillFileTool{+ BaseTool: editSkillFileTool,+ store: store,+ skillDir: skillDir,+ }+}++// Execute reads the file, applies the replacement, and writes it back.+func (t *EditSkillFileTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) {+ logger.Infof(ctx, "[Tool][EditSkillFile] Execute started")++ var input EditSkillFileInput+ if err := json.Unmarshal(args, &input); err != nil {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("Failed to parse args: %v", err),+ }, nil+ }+ if t.store == nil {+ return &types.ToolResult{+ Success: false,+ Error: "skill file editing is not available in this deployment",+ }, nil+ }++ sessionID := resolveSessionID(ctx)+ if sessionID == "" {+ return &types.ToolResult{+ Success: false,+ Error: "no session ID in context; edit_skill_file must run inside an agent turn",+ }, nil+ }++ clean, err := resolveSkillFilePath(t.skillDir, input.Path)+ if err != nil {+ return &types.ToolResult{Success: false, Error: err.Error()}, nil+ }++ stat, statErr := t.store.StatSessionFile(ctx, sessionID, clean)+ if statErr != nil {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("failed to stat %s: %v", clean, statErr),+ }, nil+ }+ if stat != nil && stat.Type == sandbox.RemoteEntryDir {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("%s is a directory; edit_skill_file only edits files", clean),+ }, nil+ }+ if stat != nil && stat.Size > int64(maxWriteSandboxBytes) {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf(+ "file too large to edit (%d bytes; max %d). Rewrite a smaller file with write_skill_file",+ stat.Size, maxWriteSandboxBytes,+ ),+ }, nil+ }++ raw, err := t.store.ReadSessionFile(ctx, sessionID, clean)+ if err != nil {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("failed to read %s: %v", clean, err),+ }, nil+ }+ if len(raw) > maxWriteSandboxBytes {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("file too large to edit (%d bytes; max %d)", len(raw), maxWriteSandboxBytes),+ }, nil+ }+ if isBinaryShellOutput(string(raw)) {+ return &types.ToolResult{+ Success: false,+ Error: "binary files cannot be edited",+ }, nil+ }++ updated, replacements, err := applySandboxEdit(+ string(raw), input.OldString, input.NewString, input.ReplaceAll)+ if err != nil {+ return &types.ToolResult{Success: false, Error: err.Error()}, nil+ }+ content := []byte(updated)+ if len(content) > maxWriteSandboxBytes {+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf(+ "result too large (%d bytes; max %d). Shrink new_string or split the file",+ len(content), maxWriteSandboxBytes,+ ),+ }, nil+ }+ if isBinaryShellOutput(updated) {+ return &types.ToolResult{+ Success: false,+ Error: "replacement would introduce binary content, which is not accepted",+ }, nil+ }++ if err := t.store.WriteSessionFile(ctx, sessionID, clean, content); err != nil {+ logger.Warnf(ctx, "[Tool][EditSkillFile] write failed: session=%s path=%s err=%v",+ sessionID, clean, err)+ return &types.ToolResult{+ Success: false,+ Error: fmt.Sprintf("failed to write %s: %v", clean, err),+ }, nil+ }++ logger.Infof(ctx, "[Tool][EditSkillFile] session=%s path=%s replacements=%d bytes=%d",+ sessionID, clean, replacements, len(content))++ data := map[string]interface{}{+ "display_type": ToolEditSkillFile,+ "session_id": sessionID,+ "path": clean,+ "root": t.skillDir,+ "name": path.Base(clean),+ "size": len(content),+ "replacements": replacements,+ }+ if hint := pythonScriptSyntaxHint(clean, updated, ToolEditSkillFile); hint != "" {+ data["syntax_error"] = true+ return &types.ToolResult{+ Success: false,+ Error: hint,+ Output: fmt.Sprintf("=== Edited skill file with syntax problems: %s ===\n\n%s\n", clean, hint),+ Data: data,+ }, nil+ }+ return &types.ToolResult{+ Success: true,+ Output: fmt.Sprintf("=== Edited skill file: %s ===\n\nreplacements=%d\nbytes=%d\n",+ clean, replacements, len(content)),+ Data: data,+ }, nil+}++// Cleanup releases any resources.+func (t *EditSkillFileTool) Cleanup(ctx context.Context) error {+ return nil+}++// resolveSkillFilePath turns a model-supplied path into an absolute path+// proven to sit inside skillDir.+//+// A relative path is resolved against skillDir, which is what the model+// reaches for after being told the directory once. Everything is then cleaned+// and re-checked against the prefix, so "..", a symlink-looking spelling or an+// absolute path into a neighbouring skill all fail here rather than reaching+// the image. The directory itself is refused: it is not a file.+func resolveSkillFilePath(skillDir, requested string) (string, error) {+ dir := path.Clean(strings.TrimSpace(skillDir))+ if dir == "" || dir == "." || dir == "/" {+ return "", fmt.Errorf("this tool is not bound to a skill directory")+ }+ trimmed := strings.TrimSpace(requested)+ if trimmed == "" {+ return "", fmt.Errorf("path is required; write a file inside %s", dir)+ }+ if strings.ContainsRune(trimmed, 0) {+ return "", fmt.Errorf("path %q is not a valid file path", requested)+ }+ candidate := trimmed+ if !path.IsAbs(candidate) {+ candidate = path.Join(dir, candidate)+ }+ clean := path.Clean(candidate)+ if clean == dir || !strings.HasPrefix(clean, dir+"/") {+ return "", fmt.Errorf(+ "path %q is outside this install's skill directory (%s); "++ "an install may only write its own skill",+ requested, dir,+ )+ }+ return clean, nil+}diff --git a/internal/agent/tools/skill_file_test.go b/internal/agent/tools/skill_file_test.gonew file mode 100644index 000000000..92c3574a4--- /dev/null+++ b/internal/agent/tools/skill_file_test.go@@ -0,0 +1,195 @@+package tools++import (+ "context"+ "encoding/json"+ "errors"+ "strings"+ "testing"++ "github.com/Tencent/WeKnora/internal/sandbox"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++const testSkillDir = sandbox.SkillsImageRoot + "/pdf-tools"++type fakeSkillFileStore struct {+ existing map[string][]byte+ stat *sandbox.RemoteStatEntry+ statErr error+ writeErr error++ writes []string+ last []byte+}++func (f *fakeSkillFileStore) StatSessionFile(+ _ context.Context, _, filePath string,+) (*sandbox.RemoteStatEntry, error) {+ if f.statErr != nil {+ return nil, f.statErr+ }+ if f.stat != nil {+ return f.stat, nil+ }+ if _, ok := f.existing[filePath]; !ok {+ return nil, errors.New("no such file")+ }+ return &sandbox.RemoteStatEntry{Path: filePath, Type: sandbox.RemoteEntryFile}, nil+}++func (f *fakeSkillFileStore) ReadSessionFile(+ _ context.Context, _, filePath string,+) ([]byte, error) {+ raw, ok := f.existing[filePath]+ if !ok {+ return nil, errors.New("no such file")+ }+ return append([]byte(nil), raw...), nil+}++func (f *fakeSkillFileStore) WriteSessionFile(+ _ context.Context, _, filePath string, content []byte,+) error {+ if f.writeErr != nil {+ return f.writeErr+ }+ f.writes = append(f.writes, filePath)+ f.last = append([]byte(nil), content...)+ if f.existing == nil {+ f.existing = map[string][]byte{}+ }+ f.existing[filePath] = append([]byte(nil), content...)+ return nil+}++// The reason these tools exist: the installer's only writer was `cat` with a+// heredoc, so anything past the shell's command-length cap arrived truncated.+func TestWriteSkillFileWritesAFileTooLargeForAHeredoc(t *testing.T) {+ content := strings.Repeat("# a line of a generated wrapper script\n", 500)+ require.Greater(t, len(content), 8*1024)+ store := &fakeSkillFileStore{}++ result, err := NewWriteSkillFileTool(store, testSkillDir).Execute(+ sandboxFileTestContext(),+ mustWriteSandboxArgs(testSkillDir+"/.weknora/requirements.json", content),+ )++ require.NoError(t, err)+ require.True(t, result.Success, result.Error)+ assert.Equal(t, []string{testSkillDir + "/.weknora/requirements.json"}, store.writes)+ assert.Equal(t, content, string(store.last))+ assert.NotContains(t, result.Output, content, "the model already has these bytes")+}++// The model is told the skill directory once, then reaches for paths relative+// to it. Resolving them beats refusing a call that meant the right file.+func TestWriteSkillFileResolvesARelativePathAgainstTheSkillDirectory(t *testing.T) {+ store := &fakeSkillFileStore{}++ result, err := NewWriteSkillFileTool(store, testSkillDir).Execute(+ sandboxFileTestContext(),+ mustWriteSandboxArgs(".weknora/requirements.json", `{"env":[]}`),+ )++ require.NoError(t, err)+ require.True(t, result.Success, result.Error)+ assert.Equal(t, []string{testSkillDir + "/.weknora/requirements.json"}, store.writes)+}++// One install writes one skill. The installer's shell runs as root in an image+// every session of the config inherits, so reaching a neighbouring skill has to+// fail in the tool rather than be discouraged by the prompt.+func TestSkillFileToolsRefuseEveryPathOutsideTheirOwnSkill(t *testing.T) {+ for _, requested := range []string{+ sandbox.SkillsImageRoot + "/other-skill/SKILL.md",+ sandbox.SkillsImageRoot + "/.manifest.json",+ sandbox.SkillsImageRoot,+ testSkillDir + "/../other-skill/run.py",+ testSkillDir + "/./../.manifest.json",+ "../other-skill/run.py",+ "/etc/passwd",+ "/workspace/output/run.py",+ testSkillDir,+ "",+ } {+ t.Run(requested, func(t *testing.T) {+ store := &fakeSkillFileStore{}++ result, err := NewWriteSkillFileTool(store, testSkillDir).Execute(+ sandboxFileTestContext(), mustWriteSandboxArgs(requested, "x = 1\n"))++ require.NoError(t, err)+ require.False(t, result.Success,+ "an install must not be able to write %q", requested)+ assert.Empty(t, store.writes, "the refusal must happen before any write")+ })+ }+}++func TestEditSkillFileReplacesASnippetInPlace(t *testing.T) {+ store := &fakeSkillFileStore{existing: map[string][]byte{+ testSkillDir + "/scripts/run.py": []byte("import sys\nLIB = '/wrong/path'\n"),+ }}++ args, err := json.Marshal(map[string]any{+ "path": "scripts/run.py",+ "old_string": "'/wrong/path'",+ "new_string": "'" + testSkillDir + "/lib'",+ })+ require.NoError(t, err)++ result, err := NewEditSkillFileTool(store, testSkillDir).Execute(+ sandboxFileTestContext(), args)++ require.NoError(t, err)+ require.True(t, result.Success, result.Error)+ assert.Equal(t, 1, result.Data["replacements"])+ assert.Contains(t, string(store.last), testSkillDir+"/lib")+}++// A nested-quote break is reported but the write still lands, so the next call+// can be an edit rather than a rewrite of the whole file. The hint has to name+// edit_skill_file: edit_sandbox_file cannot reach this tree.+func TestWriteSkillFileFlagsNestedPythonQuotesAndStillWrites(t *testing.T) {+ store := &fakeSkillFileStore{}++ result, err := NewWriteSkillFileTool(store, testSkillDir).Execute(+ sandboxFileTestContext(),+ mustWriteSandboxArgs("scripts/run.py",+ "title = \"这不是一个\"大干快上\"的夜晚\"\n"))++ require.NoError(t, err)+ require.False(t, result.Success)+ assert.Equal(t, true, result.Data["syntax_error"])+ assert.Contains(t, result.Error, ToolEditSkillFile)+ assert.Len(t, store.writes, 1, "edit_skill_file needs the file to exist")+}++// These write the shared snapshot image, so they are granted by install mode+// alone. A checkbox for them in the settings UI would turn "can edit an agent"+// into "can write the image every session of this config inherits", which is a+// different permission from "can upload a skill".+func TestSkillFileToolsAreNotSelectableOnATenantAgent(t *testing.T) {+ for _, name := range []string{ToolWriteSkillFile, ToolEditSkillFile} {+ require.NotContains(t, DefaultAllowedTools(), name)+ for _, definition := range AvailableToolDefinitions() {+ require.NotEqual(t, name, definition.Name,+ "a tenant-editable agent must not be able to request %s", name)+ }+ }+}++func TestSkillFileToolsRefuseToWriteWhenBoundToNoSkillDirectory(t *testing.T) {+ for _, dir := range []string{"", "/", "."} {+ store := &fakeSkillFileStore{}++ result, err := NewWriteSkillFileTool(store, dir).Execute(+ sandboxFileTestContext(), mustWriteSandboxArgs("/etc/passwd", "x"))++ require.NoError(t, err)+ require.False(t, result.Success, "skillDir %q must not authorise any write", dir)+ assert.Empty(t, store.writes)+ }+}diff --git a/internal/agent/tools/tool_policy_coverage_test.go b/internal/agent/tools/tool_policy_coverage_test.goindex 546a97c00..f4a6932ca 100644--- a/internal/agent/tools/tool_policy_coverage_test.go+++ b/internal/agent/tools/tool_policy_coverage_test.go@@ -34,6 +34,8 @@ func TestEveryBuiltInToolDeclaresAModelHandlePolicy(t *testing.T) {ToolReadSandboxFile,ToolWriteSandboxFile,ToolEditSandboxFile,+ ToolWriteSkillFile,+ ToolEditSkillFile,ToolShellExec,ToolWikiReadPage,ToolWikiWritePage,diff --git a/internal/application/service/agent_service.go b/internal/application/service/agent_service.goindex ce7f84fcf..85d72b758 100644--- a/internal/application/service/agent_service.go+++ b/internal/application/service/agent_service.go@@ -398,7 +398,9 @@ func (s *agentService) resolveKBAndDocInfos(// /opt/weknora/tenant/skills, and its prompt forbids touching /workspace// (that tree is wiped before the snapshot). Offering the file tools made// the first write of every install fail, then fall back to a shell heredoc.-// Install mode uses shell_exec alone.+// Install mode gets write_skill_file / edit_skill_file instead, which write+// the image tree and are scoped to the one skill being installed —+// see registerSkillFileTools.func (s *agentService) registerSandboxFileTools(ctx context.Context,toolRegistry *tools.ToolRegistry,@@ -407,6 +409,7 @@ func (s *agentService) registerSandboxFileTools() {if config != nil && config.SkillInstallMode() {logger.Infof(ctx, "Skipping session file tools in skill install mode")+ s.registerSkillFileTools(ctx, toolRegistry, sessionID, config)return}sandboxMgr, err := s.resolveWorkspaceSandbox(ctx, sessionID, config)@@ -429,6 +432,55 @@ func (s *agentService) registerSandboxFileTools(}}+// registerSkillFileTools registers write_skill_file / edit_skill_file for the+// built-in skill installer, and for nothing else.+//+// The installer's shell already runs as root inside the skills image root, so+// these tools grant no reach it does not have. They exist because its only+// writer was `cat` with a heredoc: every file went through the shell's+// command-length cap and two levels of quoting, which truncated or mangled+// anything larger than a few lines.+//+// Two conditions gate registration, and both are checked here rather than+// trusted from the caller. SkillInstallMode is settable only through+// EnableSkillInstallMode, which refuses every agent but the built-in+// installer. The skill directory is re-validated against the image path rules,+// so a run that somehow carried a bad scope gets no writer at all instead of+// one pointed somewhere unintended.+func (s *agentService) registerSkillFileTools(+ ctx context.Context,+ toolRegistry *tools.ToolRegistry,+ sessionID string,+ config *types.AgentConfig,+) {+ if config == nil || !config.SkillInstallMode() {+ return+ }+ skillDir, ok := sandbox.ValidatedImageSkillDir(config.SkillInstallDir())+ if !ok {+ logger.Warnf(ctx, "Install mode carries no valid skill directory (%q); "++ "write_skill_file/edit_skill_file not registered", config.SkillInstallDir())+ return+ }+ sandboxMgr, err := s.resolveWorkspaceSandbox(ctx, sessionID, config)+ if err != nil {+ logger.Warnf(ctx, "Failed to resolve sandbox for skill file tools: %v", err)+ return+ }+ if sandboxMgr == nil {+ return+ }+ store, ok := sandboxMgr.(tools.SkillFileStore)+ if !ok {+ logger.Infof(ctx, "Sandbox backend cannot write the skills image root; "++ "write_skill_file/edit_skill_file not registered")+ return+ }+ toolRegistry.RegisterTool(tools.NewWriteSkillFileTool(store, skillDir))+ toolRegistry.RegisterTool(tools.NewEditSkillFileTool(store, skillDir))+ logger.Infof(ctx, "Registered write_skill_file and edit_skill_file scoped to %s", skillDir)+}+// registerSandboxShellIfAllowed registers shell_exec when this run is// entitled to a sandbox shell: SkillsEnabled, or the built-in skill// installer. It does not require a ready skill to already exist, so a@@ -735,8 +787,10 @@ func (s *agentService) registerSandboxShellTool() {if config.SkillInstallMode() {if executor := sessionSandboxInstallShellExecutor(sandboxMgr); executor != nil {- toolRegistry.RegisterTool(tools.NewInstallShellExecTool(executor))- logger.Infof(ctx, "Registered install-mode shell_exec tool")+ skillDir := config.SkillInstallDir()+ toolRegistry.RegisterTool(tools.NewInstallShellExecTool(executor, skillDir))+ logger.Infof(ctx, "Registered install-mode shell_exec tool (work_dir defaults to %s)",+ skillDir)} else {logger.Warnf(ctx, "Sandbox backend does not advertise install-mode shell; skill install cannot run")}diff --git a/internal/application/service/agent_service_install_shell_test.go b/internal/application/service/agent_service_install_shell_test.goindex ab9634746..1b1c617c8 100644--- a/internal/application/service/agent_service_install_shell_test.go+++ b/internal/application/service/agent_service_install_shell_test.go@@ -38,7 +38,7 @@ func TestInstallerAgentGetsTheRootShellWithTheSkillsRoot(t *testing.T) {installShell: privileged,}config := &types.AgentConfig{}- config.EnableSkillInstallMode(types.BuiltinSkillInstallerID)+ config.EnableSkillInstallMode(types.BuiltinSkillInstallerID, sandbox.SkillsImageRoot+"/pptx")registry := tools.NewToolRegistry()(&agentService{}).registerSandboxShellTool(context.Background(), registry, mgr, config)@@ -86,7 +86,7 @@ func TestOrdinaryAgentKeepsTheUnprivilegedShell(t *testing.T) {func TestInstallModeIsRefusedToEveryAgentButTheInstaller(t *testing.T) {config := &types.AgentConfig{}- config.EnableSkillInstallMode("some-tenant-agent")+ config.EnableSkillInstallMode("some-tenant-agent", sandbox.SkillsImageRoot+"/pptx")require.False(t, config.SkillInstallMode())}@@ -105,7 +105,7 @@ func TestInstallerAgentConfigTurnsOnInstallMode(t *testing.T) {config := installerAgentConfig(&types.CustomAgent{ID: types.BuiltinSkillInstallerID,Config: types.CustomAgentConfig{AllowedTools: []string{tools.ToolShellExec}},- }, "cfg-1")+ }, "cfg-1", sandbox.SkillsImageRoot+"/pptx")require.True(t, config.SkillInstallMode())require.Equal(t, "none", config.MCPSelectionMode,@@ -126,7 +126,7 @@ func TestInstallerAgentConfigKeepsMCPOffWhenThePlatformYAMLEnablesIt(t *testing.WebSearchEnabled: true,MemoryEnabled: &memoryOn,},- }, "cfg-1")+ }, "cfg-1", sandbox.SkillsImageRoot+"/pptx")require.Equal(t, "none", config.MCPSelectionMode)require.False(t, config.WebSearchEnabled)@@ -138,7 +138,7 @@ func TestInstallerAgentConfigLeavesInstallModeOffForAnotherAgent(t *testing.T) {config := installerAgentConfig(&types.CustomAgent{ID: "agent-42",Config: types.CustomAgentConfig{AllowedTools: []string{tools.ToolShellExec}},- }, "cfg-1")+ }, "cfg-1", sandbox.SkillsImageRoot+"/pptx")require.False(t, config.SkillInstallMode())}diff --git a/internal/application/service/agent_service_test.go b/internal/application/service/agent_service_test.goindex cc2fd420d..44df91b38 100644--- a/internal/application/service/agent_service_test.go+++ b/internal/application/service/agent_service_test.go@@ -155,7 +155,7 @@ func TestCreateAgentEngineOpensSandboxToolsOnlyForInstallMode(t *testing.T) {SkillsEnabled: false,AllowedTools: []string{tools.ToolShellExec},}- config.EnableSkillInstallMode(types.BuiltinSkillInstallerID)+ config.EnableSkillInstallMode(types.BuiltinSkillInstallerID, sandbox.SkillsImageRoot+"/pptx")engine, err := svc.CreateAgentEngine(ctx, config, chatModel, nil, nil, "sess-1", "msg-1")diff --git a/internal/application/service/tenant_skill_install.go b/internal/application/service/tenant_skill_install.goindex 3bc08bea2..e3b5970c2 100644--- a/internal/application/service/tenant_skill_install.go+++ b/internal/application/service/tenant_skill_install.go@@ -731,7 +731,7 @@ type installerJob struct {func (s *TenantSkillService) installDependenciesAndVerify(ctx context.Context, job installerJob,) (err error) {- run, err := s.openInstallerRun(ctx, job.tenantID, job.sess, job.transcript)+ run, err := s.openInstallerRun(ctx, job.tenantID, job.sess, job.skillDir, job.transcript)if err != nil {job.transcript.Finish(context.WithoutCancel(ctx), err)return err@@ -805,7 +805,11 @@ type installerRun struct {// AgentQA swallows engine failures (it emits an error event and returns nil)// and we need a reliable signal before switching the image.func (s *TenantSkillService) openInstallerRun(- ctx context.Context, tenantID uint64, sess *types.Session, transcript *installTranscript,+ ctx context.Context,+ tenantID uint64,+ sess *types.Session,+ skillDir string,+ transcript *installTranscript,) (*installerRun, error) {if s.installerAgents == nil {return nil, errors.New("custom agent service is not configured")@@ -821,7 +825,8 @@ func (s *TenantSkillService) openInstallerRun(if err != nil {return nil, fmt.Errorf("load installer agent: %w", err)}- agentConfig := installerAgentConfig(installerAgentDefaults(ctx, tenantID), sess.SandboxConfigID)+ agentConfig := installerAgentConfig(+ installerAgentDefaults(ctx, tenantID), sess.SandboxConfigID, skillDir)chatModel, err := s.resolveInstallerModel(ctx, tenantID, record)if err != nil {@@ -904,12 +909,11 @@ func (s *TenantSkillService) reopenSkillDirForRepair(// buildRepairPrompt turns the gate's own findings into the next round's brief.//-// It carries no analysis of its own, deliberately. The reason a first round can-// fail on a working skill is that SKILL.md and the imports its files execute are-// two different descriptions of what the skill needs; a third description-// written here would reintroduce exactly that gap. The only thing added is the-// import-name-to-distribution mapping, which is a property of PyPI rather than-// of this skill.+// It carries no analysis of its own, deliberately: the gate is the only+// authority on what has to resolve in this image, and a second description+// written here could disagree with it. Every repairable finding names a+// distribution one of the skill's manifests declares and pip did not land, so+// the brief is short — install what the lines name, change nothing else.func buildRepairPrompt(skillDir string, gate *skillVerificationError) string {var findings strings.Builderfor _, problem := range gate.Problems {@@ -921,20 +925,15 @@ func buildRepairPrompt(skillDir string, gate *skillVerificationError) string {The %s check reported:%s-Every line above is a dependency this image cannot resolve. The names were read-from the imports the skill's own files execute when they load, which is why some-of them appear nowhere in SKILL.md — install them anyway.+Every line above names a dependency one of this skill's own manifests declares+and that is not installed in this image. Install it.- Python packages go into %s/.venv (`+"`uv pip install`"+`, or%s/.venv/bin/python -m pip install). Node packages go under %s/node_modules.-- The name in each line is an IMPORT name; install the distribution that- provides it. Common cases where they differ: PIL -> pillow, yaml -> pyyaml,- docx -> python-docx, pptx -> python-pptx, cv2 -> opencv-python-headless,- bs4 -> beautifulsoup4, sklearn -> scikit-learn, fitz -> pymupdf.-- Do NOT edit, move or delete any of the skill's own files, and do NOT edit- SKILL.md or requirements.txt to make the check pass. The uploaded archive is- what read_skill serves, so a source edit here makes the installed skill differ- from what everyone else sees.+- Do NOT edit SKILL.md, requirements.txt, pyproject.toml or package.json to+ make the check pass. Those files are what read_skill serves, so weakening a+ declaration here makes the installed skill differ from what everyone else+ sees — and the dependency would still be missing at run time.- If a package genuinely cannot be installed in this image, say so plainly inyour summary rather than working around it.@@ -1738,14 +1737,19 @@ Hard requirements:- Install dependencies for exactly this one skill.- Python dependencies must go into %s/.venv. Do not install into system Python.- Node dependencies must go under %s/node_modules. Do not install global packages unless no local alternative exists.-- Use shell_exec only (write_sandbox_file is not available and cannot write- this tree). You may set work_dir to %s. Write .weknora/requirements.json- with a short shell redirect after mkdir -p.+- shell_exec already starts every command in %s. Use relative paths+ (`+"`ls -la scripts/`"+`, `+"`uv venv --seed .venv`"+`) and do NOT prefix+ `+"`cd <skill-dir> &&`"+` onto them.+- To create or change a file in this tree use write_skill_file /+ edit_skill_file, NOT a shell heredoc or `+"`cat`"+`: those truncate at the+ command-length cap and mangle quoting.+ write_sandbox_file only writes /workspace, which is wiped before the+ snapshot, so it cannot help you here.- Each command has a 10-minute budget; you do not need to set timeout_sec.- When finished, report what you installed and any global/system packages you changed.- Declare the environment variables this skill needs AT RUN TIME. Decide from the SKILL.md textat the end of this message: declare what it documents as needed to run the skill. Ignore- anything only the installation itself needed. Run mkdir -p on the directory first, then write the declaration to %s as JSON of this exact shape:+ anything only the installation itself needed. Write the declaration with write_skill_file to %s, as JSON of this exact shape:{"env":[{"name":"TAVILY_API_KEY","description":"what the skill uses it for","required":true}]}Each name must be UPPER_SNAKE_CASE and must appear literally somewhere in the skill's own files.Never write any value, placeholder or example credential: this file declares what is needed, and@@ -1768,11 +1772,24 @@ already in the venv.%s- If an installer script needs --yes / --all / every extra flag, pass them.%s-The server verifies the result itself before the image is kept, so report what-you did rather than whether it passed. Verification parses every script with-the interpreter that would run it, resolves the imports each one executes on-load, and checks every distribution named in requirements.txt is present in the-venv. It never runs the skill's code.+Before you finish, PROVE the skill's imports resolve. Do not reason about it —+run it. The server's own check cannot: it parses files without executing them,+so it never learns whether an import would have worked. You have the real+interpreter, so this is your job and yours only.+- For each script the skill offers, run the import the way the skill would:+ `+"`%s/.venv/bin/python -c 'import x'`"+`, or the script's own+ `+"`--help`"+` if it has one.+- A failure here is usually one of two things. A missing distribution: install+ it. Or a module the skill ships that Python cannot find — then the script+ needs the directory on sys.path, and you fix the script with edit_skill_file+ rather than installing anything.+- Do not declare success until every entry point imports cleanly.++The server then checks what it can before the image is kept, so report what you+did rather than whether it passed. It confirms every file parses with the+interpreter that would run it, and that every distribution named in+requirements.txt / pyproject.toml is installed in the venv. It never runs the+skill's code and never judges an import.Lazy imports and install_deps.py extras are invisible to that check — you stillhave to install them.@@ -1780,7 +1797,7 @@ SKILL.md:%s`, skillDir, formatToolchainSection(tools), skillDir, skillDir, skillDir,requirementsPath, skillDir, formatOnDemandInstallers(bundle),- formatFrontmatterRepairNote(bundle), skillMD)+ formatFrontmatterRepairNote(bundle), skillDir, skillMD)}// formatOnDemandInstallers names bundle files that install extras at first@@ -1920,12 +1937,22 @@ func installerAgentDefaults(ctx context.Context, tenantID uint64) *types.CustomA// the shared sandbox image": that is a different permission from "can upload a// skill". The model is the one choice still taken from the stored record, in// resolveInstallerModel.-func installerAgentConfig(defaults *types.CustomAgent, configID string) *types.AgentConfig {+//+// skillDir scopes the skill file tools to the one skill this install owns. The+// installer's shell already runs as root in the shared image, so the tools add+// no reach — they replace `cat` with a heredoc, whose command-length cap and+// double quoting truncated or mangled every file the agent tried to write.+func installerAgentConfig(+ defaults *types.CustomAgent, configID, skillDir string,+) *types.AgentConfig {memoryOff := falsethinkingOff := false+ installTools := []string{+ tools.ToolShellExec, tools.ToolWriteSkillFile, tools.ToolEditSkillFile,+ }cfg := &types.AgentConfig{MaxIterations: 30,- AllowedTools: []string{tools.ToolShellExec},+ AllowedTools: append([]string(nil), installTools...),Temperature: 0.2,WebSearchEnabled: false,MCPSelectionMode: "none",@@ -1942,16 +1969,17 @@ func installerAgentConfig(defaults *types.CustomAgent, configID string) *types.A// The installer's shell_exec must run as root inside the skills image// root; the prompt below asks for exactly that. The grant is keyed on the// built-in agent ID and refused for anything else.- cfg.EnableSkillInstallMode(defaults.ID)+ cfg.EnableSkillInstallMode(defaults.ID, skillDir)custom := defaults.Configcfg.MaxIterations = custom.MaxIterationsif cfg.MaxIterations == 0 {cfg.MaxIterations = 30}- cfg.AllowedTools = append([]string(nil), custom.AllowedTools...)- if len(cfg.AllowedTools) == 0 {- cfg.AllowedTools = []string{tools.ToolShellExec}- }+ // The install tools are unioned in rather than read off the registry entry.+ // An install that cannot write its own skill directory cannot record what+ // it did, and the platform YAML predates these tools — a deployment that+ // has not re-synced it must not silently lose them.+ cfg.AllowedTools = unionTools(custom.AllowedTools, installTools)cfg.Temperature = custom.Temperaturecfg.SystemPrompt = custom.SystemPromptcfg.UseCustomSystemPrompt = custom.SystemPrompt != ""@@ -1964,6 +1992,25 @@ func installerAgentConfig(defaults *types.CustomAgent, configID string) *types.Areturn cfg}+// unionTools returns configured plus every name in required that it is missing,+// preserving the configured order so a deployment's own list still reads as it+// was written.+func unionTools(configured, required []string) []string {+ seen := make(map[string]struct{}, len(configured)+len(required))+ out := make([]string, 0, len(configured)+len(required))+ for _, name := range append(append([]string(nil), configured...), required...) {+ if name = strings.TrimSpace(name); name == "" {+ continue+ }+ if _, ok := seen[name]; ok {+ continue+ }+ seen[name] = struct{}{}+ out = append(out, name)+ }+ return out+}+// resolveInstallerModel prefers the model the installer agent is configured// with. Whoever set that model chose it for this job; the workspace default is// only the fallback for a record that names no model or names one thisdiff --git a/internal/application/service/tenant_skill_install_test.go b/internal/application/service/tenant_skill_install_test.goindex 0a03a38e4..49b7cb2ca 100644--- a/internal/application/service/tenant_skill_install_test.go+++ b/internal/application/service/tenant_skill_install_test.go@@ -622,12 +622,46 @@ func TestBuildInstallPromptAsksForADeclarationWithoutValues(t *testing.T) {require.Contains(t, prompt, "On-demand / optional extras MUST be installed now")require.Contains(t, prompt, "uv venv --seed")require.Contains(t, prompt, "install_deps.py")- require.Contains(t, prompt, "write_sandbox_file is not available")- require.Contains(t, prompt, "short shell redirect")+ require.Contains(t, prompt, "write_skill_file",+ "a heredoc truncates at the command-length cap; the file tools are the writer")+ require.Contains(t, prompt, "write_sandbox_file only writes /workspace",+ "the installer must be told why the workspace writer cannot help it")require.Contains(t, prompt, "- uv: /root/.local/bin/uv","the prompt hands over absolute paths instead of a PATH gamble")}+// shell_exec used to default to /workspace, so the installer opened command+// after command with `cd <skill-dir> &&` — the one spelling guaranteed to land+// somewhere useful. The default is now the skill directory, and the prompt has+// to say so, because a model that is not told keeps paying for the prefix.+func TestBuildInstallPromptSaysCommandsAlreadyStartInTheSkillDirectory(t *testing.T) {+ fx := newInstallFixture(t)++ prompt := buildInstallPrompt(installSkillDir, fx.bundle, nil)++ require.Contains(t, prompt, "shell_exec already starts every command in "+installSkillDir)+ require.Contains(t, prompt, "do NOT prefix")+ require.Contains(t, prompt, "cd <skill-dir> &&")+}++// Import resolution is the agent's job because it is nobody else's: the server+// parses files without executing them, so it never learns whether an import+// would have worked. The prompt has to say so, or the one party holding a real+// interpreter reasons about imports instead of running them.+func TestBuildInstallPromptDemandsImportsBeProvenByRunningThem(t *testing.T) {+ fx := newInstallFixture(t)++ prompt := buildInstallPrompt(installSkillDir, fx.bundle, nil)++ require.Contains(t, prompt, "PROVE the skill's imports resolve")+ require.Contains(t, prompt, "Do not reason about it")+ require.Contains(t, prompt, installSkillDir+"/.venv/bin/python -c 'import x'")+ require.Contains(t, prompt, "never judges an import",+ "the agent must not expect the server to catch an unresolved import")+ require.Contains(t, prompt, "edit_skill_file",+ "a shipped module Python cannot find is fixed in the script, not with pip")+}+func TestBuildInstallPromptNamesOnDemandInstallerInTheArchive(t *testing.T) {fx := newInstallFixture(t)fx.bundle.Files["scripts/install_deps.py"] = []byte("print(1)\n")@@ -1487,10 +1521,19 @@ func TestInstallSessionIgnoresATenantOverrideOfTheInstallerAgent(t *testing.T) {require.Equal(t, platform.Config.SystemPrompt, fx.engineConfig.SystemPrompt,"the prompt that drives a root shell is the platform's, not the tenant's")require.NotContains(t, fx.engineConfig.SystemPrompt, "/root/.ssh")- require.Equal(t, platform.Config.AllowedTools, fx.engineConfig.AllowedTools)+ require.Subset(t, fx.engineConfig.AllowedTools, platform.Config.AllowedTools,+ "the tool set is the platform's, plus what an install structurally needs")require.NotContains(t, fx.engineConfig.AllowedTools, tools.ToolWebSearch)+ require.NotContains(t, fx.engineConfig.AllowedTools, tools.ToolReadSkill)+ // Unioned in rather than read off the registry entry: an install that+ // cannot write its own skill directory cannot record what it did, and a+ // deployment whose platform YAML predates these tools must not lose them.+ require.Contains(t, fx.engineConfig.AllowedTools, tools.ToolWriteSkillFile)+ require.Contains(t, fx.engineConfig.AllowedTools, tools.ToolEditSkillFile)require.Equal(t, platform.Config.MaxIterations, fx.engineConfig.MaxIterations)require.True(t, fx.engineConfig.SkillInstallMode())+ require.Equal(t, installSkillDir, fx.engineConfig.SkillInstallDir(),+ "the file tools must be scoped to this install's own skill directory")require.Equal(t, "model-agent", fx.engineModel.GetModelID(),"the model is the one choice the tenant record still makes")}diff --git a/internal/application/service/tenant_skill_verify.go b/internal/application/service/tenant_skill_verify.goindex c7b8d0033..2e417f8fe 100644--- a/internal/application/service/tenant_skill_verify.go+++ b/internal/application/service/tenant_skill_verify.go@@ -63,22 +63,24 @@ func (e *skillVerificationError) Error() string {// verifySkill is the server's own check, and the last gate before the image// pointer moves: a broken install must leave the previous snapshot serving.//-// It proves loadability, not behaviour, and not "every file can be used as-// python this_file.py". A skill ships scripts and library packages together;-// execute_skill_script names files, but those files are also imported by each-// other. The Python pass resolves each file's imports against the prefixes-// Python itself would use — the file's own directory and every ancestor up to-// the skill root — plus the venv. Guessing a single entry script, or treating-// every .py as an isolated __main__, both fail real skills.+// It checks only what a file can settle, never what a runtime decides. Every+// pass here is deterministic: the files the bundle named are present, the+// isolated dependency trees the installer was told to create exist, every+// source parses with the interpreter that would run it, and every distribution+// the manifests name is installed.+//+// Import resolution is deliberately absent. Whether `import helper` resolves+// depends on what a script does to sys.path before the import runs, which no+// static evaluator can enumerate — and every approximation of it refused+// skills that run perfectly. That proof belongs to the installer agent, which+// holds a root shell and the real interpreter and can simply run the import.+// See the header of tenant_skill_verify.py.//// Findings are graded rather than uniformly fatal. Refusing an install costs// the minutes of dependency work that already succeeded, so only evidence that-// the install itself is broken may do it: a file nothing the skill offers ever-// loads, or a requirement pip would have skipped, is returned as a note.-//-// Not executing is the point, not a limitation. The previous implementation-// ran one guessed script with --help; skills that do not parse arguments-// simply ran their whole main path inside the tree about to be snapshotted.+// the install itself is broken may do it: a finding in a file nothing the+// skill offers ever loads, or a requirement pip would have skipped, is+// returned as a note.func (s *TenantSkillService) verifySkill(ctx context.Context, mgr sandbox.Manager, sessionID, skillDir string, bundle *SkillBundle,) ([]string, error) {@@ -88,7 +90,7 @@ func (s *TenantSkillService) verifySkill(if err := s.verifyDeclaredDependencies(ctx, mgr, sessionID, skillDir, bundle); err != nil {return nil, err}- return s.verifyScriptsLoad(ctx, mgr, sessionID, skillDir, bundle)+ return s.verifyScriptsParse(ctx, mgr, sessionID, skillDir, bundle)}// verifySkillTree confirms the files the agent was given are still the files@@ -180,15 +182,20 @@ func (s *TenantSkillService) verifyDeclaredDependencies(return nil}-// verifyScriptsLoad runs one pass per language present in the bundle. Each-// pass covers every file of that language: syntax and imports are properties-// of the file, not of a guessed entry point.+// verifyScriptsParse runs one pass per language present in the bundle. Each+// pass covers every file of that language: parsing is a property of the file,+// not of a guessed entry point.+//+// All three passes are parse-only — `ast.parse`, `node --check`, `bash -n`.+// None of them executes the skill's code and none of them decides whether an+// import resolves. The Python pass additionally checks the manifests against+// what pip actually landed, which is the one finding here another installer+// round can still fix.//-// Only the Python pass takes the auxiliary split. Its findings depend on what-// the image carries, so a bundled tests/ directory can fail an install that-// works; `node --check` and `bash -n` only state whether a file parses, which-// no amount of installing changes either way.-func (s *TenantSkillService) verifyScriptsLoad(+// Only the Python pass takes the auxiliary split, because it is the only one+// whose findings depend on what the image carries: a bundled tests/ directory+// naming a package the venv does not have must not fail an install that works.+func (s *TenantSkillService) verifyScriptsParse(ctx context.Context, mgr sandbox.Manager, sessionID, skillDir string, bundle *SkillBundle,) ([]string, error) {var notes []string@@ -282,7 +289,7 @@ func verificationProblems(stderr string) []string {return problems}-// skillPythonVerifyCommand pipes the verifier into the same interpreter a+// skillPythonVerifyCommand pipes the parser into the same interpreter a// runtime skill call would use, and names the files to check on the command// line. The list is explicit rather than a directory walk so the pass covers// exactly the uploaded sources — never .venv, node_modules or anything elsediff --git a/internal/application/service/tenant_skill_verify.py b/internal/application/service/tenant_skill_verify.pyindex 7e95daed3..aad856ec0 100644--- a/internal/application/service/tenant_skill_verify.py+++ b/internal/application/service/tenant_skill_verify.py@@ -1,32 +1,36 @@-"""Verify that an installed skill's Python sources can be loaded in this image.+"""Verify that an installed skill's Python sources are well-formed in this image.Run inside the sandbox, by the interpreter a real skill call would use, as theordinary execution user, after the tree has been given its final permissions:python3 - <skill-dir> <script> [<script> ...] [--optional <script> ...]-Nothing here executes the skill's own code. Everything it reports is decided-from the parse tree and from what the environment can resolve, so a skill that-writes files or calls the network on import cannot do either while being-checked, and a script that never learned --help cannot be failed for it.+Nothing here executes the skill's own code, and nothing here decides whether an+import will resolve.-Loadability follows Python's import rules, not "this file as isolated-__main__". A file's import prefixes are its own directory plus every ancestor-up to the skill root, because any of those can be sys.path[0]: either the-bundle ships a script there (the runtime hands `python <file>` a directory),-or the file put it there itself. A sibling subtree is never an ancestor, so-vendor/requests.py still cannot make `import requests` look satisfied to a-script under scripts/.+Import resolution used to live in this file, and it is gone on purpose. Whether+`import helper` works depends on what the script does to sys.path before it+runs — an idiom no static evaluator can enumerate: a guarded insert, a path+constant imported from a sibling module, a value read from the environment, a+mutation inside a helper function. Every approximation of that rejected skills+that run perfectly, and a rejected install throws away the dependency work that+succeeded and leaves the previous image serving. The installer agent has a root+shell and the real interpreter, so proving an import resolves is its job: it can+run the import instead of guessing at it.-Findings are graded, because rejecting an install is expensive: it throws away-minutes of dependency work and leaves the previous image serving.+What remains is what a file, not a runtime, can settle:++ - the execution user can read every source file+ - every source file parses+ - every distribution the manifests name is installed in the venv++Findings are graded, because rejecting an install is expensive.stdout `note: ...` lines - reported, image keptstderr problem lines - the install is refusedexit 0 the image may be kept- exit 1 a problem no installer round can fix: a syntax error, a file the- execution user cannot read, a relative import that can never- resolve, a shipped module the import cannot reach+ exit 1 a problem no installer round can fix: a syntax error, or a file the+ execution user cannot readexit 2 every problem is a dependency missing from this image, so handingthese lines back to the installer is worth a round@@ -36,7 +40,6 @@ tests/ directory must not decide whether the skill installs."""import ast-import importlib.utilimport osimport reimport sys@@ -67,45 +70,6 @@ notes = []# help or if the bundle itself has to change.unrepairable = False-# The directories the bundle actually ships a script in. A prefix that is one-# of these is reachable on its own, because the runtime can be asked to execute-# a file there; any other prefix is only on sys.path if the skill puts it there.-script_dirs = {os.path.dirname(os.path.join(root, rel)) for rel in all_scripts}--# ----------------------------------------------------------------------------# Third resolution tier: modules the tree itself ships, reached by the-# script's own sys.path bootstrap.-#-# A sibling subtree is never an ancestor, so static resolution cannot see-# lib/image_video.py from scripts/generate.py - and that is the runtime truth-# too, until the script puts lib/ on sys.path itself. The scan below records-# what the tree ships; the evaluator further down decides whether the-# bootstrap provably reaches it. Only a proven bridge turns a missing import-# into a note; anything unprovable stays a problem, which is what keeps-# vendor/requests.py from satisfying `import requests` for a script that-# never bridges to it.--skip_tree_dirs = {".venv", "node_modules", "__pycache__", ".weknora"}--# name -> root-relative paths of the files providing it ("lib/image_video.py",-# "scripts/__init__.py"). Built from the uploaded sources only: .venv and the-# other install-created directories are pruned, because packages pip placed-# there are not the skill's own code and must not count as shipped.-shipped_modules = {}-for _dirpath, _dirnames, _filenames in os.walk(root):- _dirnames[:] = sorted(- d for d in _dirnames if d not in skip_tree_dirs and not d.startswith(".")- )- for _filename in _filenames:- _stem, _ext = os.path.splitext(_filename)- if _ext != ".py":- continue- _rel = os.path.relpath(os.path.join(_dirpath, _filename), root).replace(os.sep, "/")- if _stem == "__init__":- shipped_modules.setdefault(os.path.basename(_dirpath), []).append(_rel)- else:- shipped_modules.setdefault(_stem, []).append(_rel)-def add_problem(message, repairable=False):global unrepairable@@ -129,309 +93,6 @@ def note_instead_of_problem(message, repairable=False):add_note("%s (auxiliary file; this does not fail the install)" % message)-def under_root(candidate):- return candidate == root or candidate.startswith(root + os.sep)---def is_package(directory):- """Whether directory is a regular Python package.-- Only __init__.py counts, and only the relative-import check needs it: a- `from . import x` in a directory without one can never resolve when the- file is run directly. Absolute imports do not consult this, because a- PEP 420 namespace package has no __init__.py and is still importable.- """- return os.path.isfile(os.path.join(directory, "__init__.py"))---def module_exists(base, dotted):- """Whether a dotted name resolves to a file or package under base."""- target = os.path.join(base, *dotted.split(".")) if dotted else base- return os.path.isfile(target + ".py") or os.path.isfile(- os.path.join(target, "__init__.py")- )---def import_search_dirs(script_path):- """Every directory that could be sys.path[0] when this file is loaded.-- Its own directory comes first: execute_skill_script runs `python <file>`.- Each ancestor up to the skill root follows, because that is what makes a- neighbouring entry script's imports resolve - Python puts the directory of- the script it was handed on the path, and a package below that directory,- regular or namespace, is importable from there. It is also where the- `sys.path.insert(0, parent)` idiom lands, which cannot be seen without- executing the file.-- Over-approximating here rejects nothing that works. Under-approximating- rejected the official office toolkit, whose library modules import their- sibling packages by short name.- """- current = os.path.dirname(os.path.abspath(script_path))- dirs = []- while under_root(current):- if current not in dirs:- dirs.append(current)- parent = os.path.dirname(current)- if parent == current:- break- current = parent- return dirs---def find_spec_with(name, prefixes):- """Whether find_spec resolves name with prefixes ahead of sys.path.-- find_spec consults the finders without importing, so a missing dependency- is reported without the side effects of loading a present one. Only- top-level names are ever queried: find_spec on a dotted name imports the- parent package, which would run the skill's own module body.- """- saved = sys.path[:]- try:- for directory in reversed(prefixes):- sys.path.insert(0, directory)- return importlib.util.find_spec(name) is not None- except Exception:- return False- finally:- sys.path[:] = saved---def resolve_top_level(name, script_path):- """How a top-level name resolves for this file.-- "image" the venv, the standard library, or a directory the bundle- ships a script in - something the runtime reaches on its own.- "unattested" only a directory that ships no script of its own can provide- it, so it is on sys.path only if the file puts it there. That- is unprovable without executing, so it is reported rather- than trusted or refused.- "" nothing in this image can provide it.- """- dirs = import_search_dirs(script_path)- attested = [directory for directory in dirs if directory in script_dirs]- if find_spec_with(name, attested):- return "image"- if len(attested) != len(dirs) and find_spec_with(name, dirs):- return "unattested"- return ""---def dotted_name(node):- """'os.path.join' for a Name/Attribute chain, else None."""- parts = []- while isinstance(node, ast.Attribute):- parts.append(node.attr)- node = node.value- if isinstance(node, ast.Name):- parts.append(node.id)- return ".".join(reversed(parts))- return None---def static_path_of(node, script_path, env):- """Evaluate an expression that is supposed to name a directory.-- Accepts only the shapes a sys.path bootstrap is written with in practice:- string literals, __file__, os.path.dirname/abspath/realpath/join, pathlib- Path(...).resolve()/absolute()/parent chains with / joins, str(...), and- plain names previously assigned one of those. A relative literal is fine- as a join component ('..', 'lib'); only the final sys.path entry must be- absolute, which bootstrap_push enforces. Everything else - variables the- scan cannot see, os.environ, any other call - returns None. The evaluator- must never guess: a wrong guess turns a broken import into a passing- install.- """- if isinstance(node, ast.Constant) and isinstance(node.value, str):- return os.path.normpath(node.value)- if isinstance(node, ast.Name):- if node.id == "__file__":- return os.path.normpath(os.path.abspath(script_path))- return env.get(node.id)- if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):- left = static_path_of(node.left, script_path, env)- right = static_path_of(node.right, script_path, env)- if left is None or right is None:- return None- return os.path.normpath(os.path.join(left, right))- if isinstance(node, ast.Call):- if node.keywords:- return None- name = dotted_name(node.func)- args = node.args- if name == "os.path.join" and args:- parts = [static_path_of(a, script_path, env) for a in args]- if any(part is None for part in parts):- return None- return os.path.normpath(os.path.join(*parts))- if name in ("os.path.dirname", "os.path.abspath", "os.path.realpath") and len(args) == 1:- base = static_path_of(args[0], script_path, env)- if base is None:- return None- return os.path.dirname(base) if name == "os.path.dirname" else base- if name in ("str", "Path", "pathlib.Path") and len(args) == 1:- return static_path_of(args[0], script_path, env)- if (- isinstance(node.func, ast.Attribute)- and not args- and node.func.attr in ("resolve", "absolute")- ):- return static_path_of(node.func.value, script_path, env)- return None- if isinstance(node, ast.Attribute) and node.attr == "parent":- base = static_path_of(node.value, script_path, env)- return None if base is None else os.path.dirname(base)- return None---def bootstrap_push(node, script_path, env, out):- """Record the directory a top-level sys.path.insert/append call adds.-- append(path) and insert(index, path) both push args[-1]. A call whose- argument cannot be evaluated records None - an unverified bridge, which- the caller must treat as reaching nothing.- """- if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call):- return- call = node.value- func = call.func- if not (isinstance(func, ast.Attribute) and func.attr in ("insert", "append")):- return- target = func.value- if not (- isinstance(target, ast.Attribute)- and target.attr == "path"- and isinstance(target.value, ast.Name)- and target.value.id == "sys"- ):- return- if call.keywords or not call.args:- out.append(None)- return- path = static_path_of(call.args[-1], script_path, env)- # A relative result would resolve against the runtime's cwd, which the- # scan cannot know - as unknowable as an unevaluable expression.- out.append(path if path is not None and os.path.isabs(path) else None)---def check_imports(rel, tree, script_path, report):- """Check the imports that loading this file is guaranteed to execute.-- Only statements at module level are checked, and only unconditionally: an- import nested in try/except, in an `if`, or inside a function is how a- skill declares an optional or lazily loaded dependency, and failing an- install over one would reject a working skill.-- The single ordered pass matters: a sys.path bootstrap only helps imports- that come after it, so each import is checked against the bridges the- statements before it have raised. Plain string assignments are tracked- too, because the idiomatic bootstrap names its path in a variable first- (script_dir = ...; lib_dir = ...; sys.path.insert(0, lib_dir)).- """- script_dir = os.path.dirname(script_path)- env = {}- bootstraps = []- for node in tree.body:- if (- isinstance(node, ast.Assign)- and len(node.targets) == 1- and isinstance(node.targets[0], ast.Name)- ):- value = static_path_of(node.value, script_path, env)- if value is not None:- env[node.targets[0].id] = value- continue- bootstrap_push(node, script_path, env, bootstraps)- if isinstance(node, ast.Import):- for alias in node.names:- check_absolute_import(rel, alias.name, script_path, bootstraps, report)- elif isinstance(node, ast.ImportFrom):- if node.level:- check_relative_import(rel, node, script_dir, report)- elif node.module:- check_absolute_import(rel, node.module, script_path, bootstraps, report)---def check_absolute_import(rel, dotted, script_path, bootstraps, report):- name = dotted.split(".")[0]- origin = resolve_top_level(name, script_path)- if origin == "image":- return- if origin == "unattested":- add_note(- "%s imports %s, which the skill ships but no directory it executes "- "scripts from can reach; it resolves only if the file puts that "- "directory on sys.path itself" % (rel, name)- )- return- providers = shipped_modules.get(name)- if not providers:- report(- "%s imports %s, which is not available in this image" % (rel, name),- repairable=True,- )- return- # The tree itself provides the module; whether the import resolves at- # runtime depends solely on the script's own bootstrap. Only a bootstrap- # proven to raise one of the providing directories counts.- bridged_dirs = {- os.path.relpath(b, root).replace(os.sep, "/")- for b in bootstraps- if b is not None- }- reached = [p for p in providers if os.path.dirname(p) in bridged_dirs]- if reached:- add_note(- "%s imports %s, which the skill ships at %s and reaches via its "- "own sys.path bootstrap" % (rel, name, ", ".join(reached))- )- return- if not bootstraps:- why = "the file puts no directory on sys.path"- elif any(b is None for b in bootstraps):- why = "its sys.path bootstrap cannot be verified statically"- else:- why = "its sys.path bootstrap reaches elsewhere"- # Unrepairable on purpose. The repair round installs packages and is- # forbidden from editing the skill's own files, so neither of its moves- # can fix a shipped module the import cannot reach - installing a- # same-named distribution would only shadow the skill's own code, and a- # source edit would diverge the installed tree from the uploaded archive.- # The bundle has to change, and this line says exactly where.- report(- "%s imports %s, which the skill ships at %s, but the import cannot "- "resolve at runtime (%s); no package install provides a skill's own "- "module - fix the import's reachability in the archive and re-upload"- % (rel, name, ", ".join(providers), why),- )---def check_relative_import(rel, node, script_dir, report):- spelling = "." * node.level + (node.module or "")- if not is_package(script_dir):- report(- "%s uses the relative import '%s' but its directory has no "- "__init__.py, so the import can never resolve when the script is "- "run directly" % (rel, spelling)- )- return- base = script_dir- for _ in range(node.level - 1):- base = os.path.dirname(base)- if not under_root(base):- report(- "%s uses the relative import '%s', which reaches outside the "- "skill directory" % (rel, spelling)- )- return- # A bare `from . import name` may be pulling something the package's- # __init__ defines rather than a submodule, so only the package itself is- # checked in that case.- if node.module and not module_exists(base, node.module):- report("%s imports '%s', which does not exist in the skill" % (rel, spelling))--def distribution_name(raw):"""The distribution a requirement line names, or '' if it cannot be read.@@ -572,13 +233,9 @@ for relative in all_scripts:report("%s cannot be read by the skill execution user (%s)" % (relative, exc))continuetry:- parsed = ast.parse(code, filename=relative)+ ast.parse(code, filename=relative)except SyntaxError as exc:- report(- "%s has a syntax error on line %s: %s" % (relative, exc.lineno, exc.msg)- )- continue- check_imports(relative, parsed, script, report)+ report("%s has a syntax error on line %s: %s" % (relative, exc.lineno, exc.msg))check_declared_requirements()diff --git a/internal/application/service/tenant_skill_verify_python_test.go b/internal/application/service/tenant_skill_verify_python_test.goindex 4d419bba0..718a1aadc 100644--- a/internal/application/service/tenant_skill_verify_python_test.go+++ b/internal/application/service/tenant_skill_verify_python_test.go@@ -45,66 +45,6 @@ func TestSkillPythonVerifier(t *testing.T) {// reported without refusing the install.wantNote string}{{- name: "a package whose __init__ imports its own submodules",- files: map[string]string{- "scripts/__init__.py": "from .chart_generator import ChartGenerator\n",- "scripts/chart_generator.py": "class ChartGenerator:\n pass\n",- },- }, {- // The shape that failed a real install: sys.path is rearranged at run- // time, so the absolute import of the skill's own package resolves- // only once the file executes. Deciding it statically is not possible,- // and guessing wrong rejects a working skill. It is reported, because- // the only directory that can satisfy it ships no script of its own.- name: "a script that puts the skill root on sys.path and imports its own package",- files: map[string]string{- "scripts/__init__.py": "",- "scripts/helper.py": "def go():\n pass\n",- "scripts/ux_regression_check.py": "import sys\n" +- "from pathlib import Path\n" +- "sys.path.insert(0, str(Path(__file__).resolve().parent.parent))\n" +- "from scripts.helper import go\n",- },- wantNote: "imports scripts, which the skill ships but no directory it " +- "executes scripts from can reach",- }, {- name: "a script importing a sibling module directly",- files: map[string]string{- "scripts/run.py": "import helper\n",- "scripts/helper.py": "x = 1\n",- "scripts/README.txt": "not python\n",- },- }, {- // scripts/ is both a package (relative imports in __init__) and a- // directory of files the runtime executes with python file.py.- // Loadability is the union of those prefixes, so a sibling import- // still resolves when the package marker is present.- name: "a packaged scripts directory whose files also import siblings",- files: map[string]string{- "scripts/__init__.py": "",- "scripts/run.py": "import helper\n",- "scripts/helper.py": "x = 1\n",- },- }, {- name: "an optional dependency behind try/except",- files: map[string]string{- "scripts/run.py": "try:\n import matplotlib\nexcept ImportError:\n" +- " matplotlib = None\n",- },- }, {- name: "a dependency imported lazily inside a function",- files: map[string]string{- "scripts/run.py": "def render():\n import matplotlib\n return matplotlib\n",- },- }, {- name: "a dependency the installer never installed",- files: map[string]string{- "scripts/run.py": "import totally_absent_package\n",- },- wantProblem: "scripts/run.py imports totally_absent_package, " +- "which is not available in this image",- wantExit: 2,- }, {name: "a syntax error",files: map[string]string{"scripts/run.py": "def broken(:\n pass\n",@@ -112,33 +52,25 @@ func TestSkillPythonVerifier(t *testing.T) {wantProblem: "scripts/run.py has a syntax error on line 1",wantExit: 1,}, {- // The exit code is the whole verdict, so one unfixable finding among- // fixable ones has to sink the batch: sending the installer back for a- // package it can install would only delay a failure it cannot.- name: "a syntax error alongside a missing dependency",+ // Every file is parsed, not a guessed entry point: a library module the+ // runtime only ever imports is just as fatal when it does not parse.+ name: "a syntax error in a library module rather than an entry script",files: map[string]string{- "scripts/bad.py": "def broken(:\n",- "scripts/run.py": "import totally_absent_package\n",+ "scripts/run.py": "x = 1\n",+ "scripts/helper.py": "def broken(:\n",},- wantProblem: "scripts/bad.py has a syntax error",+ wantProblem: "scripts/helper.py has a syntax error",wantExit: 1,}, {- name: "a relative import in a directory that is not a package",+ // The exit code is the whole verdict, so one unfixable finding among+ // fixable ones has to sink the batch: sending the installer back for a+ // package it can install would only delay a failure it cannot.+ name: "a syntax error alongside a missing requirement",files: map[string]string{- "scripts/run.py": "from .helper import go\n",- "scripts/helper.py": "def go():\n pass\n",- "scripts/notinit.py": "",+ "requirements.txt": "pandas==3.0.1\n",+ "scripts/bad.py": "def broken(:\n",},- wantProblem: "has no __init__.py",- wantExit: 1,- }, {- name: "a relative import of a module the skill does not ship",- files: map[string]string{- "pkg/__init__.py": "",- "pkg/sub/__init__.py": "",- "pkg/sub/run.py": "from ..missing import go\n",- },- wantProblem: "pkg/sub/run.py imports '..missing', which does not exist in the skill",+ wantProblem: "scripts/bad.py has a syntax error",wantExit: 1,}, {name: "a requirement the venv does not carry",@@ -179,60 +111,6 @@ func TestSkillPythonVerifier(t *testing.T) {"totally_absent_package = { version = \"^1.0\", optional = true }\n","scripts/run.py": "x = 1\n",},- }, {- // The vendor guarantee: a sibling module sharing an import's name does- // not make the import resolve. The wording names the shipped file so a- // repair round knows no package install will help.- name: "a nested file name is not treated as a first-party import",- files: map[string]string{- "vendor/totally_absent_package.py": "x = 1\n",- "scripts/run.py": "import totally_absent_package\n",- },- wantProblem: "scripts/run.py imports totally_absent_package, " +- "which the skill ships at vendor/totally_absent_package.py",- wantExit: 1,- }, {- // The official Anthropic office toolkit (xlsx/docx/pptx): a non-package- // directory holds entry scripts plus sibling packages. Library modules- // import those siblings by short name (`from helpers import ...`).- // Treating every .py as isolated __main__ rejects this layout; Python's- // package path root is scripts/office/, which is where helpers lives.- name: "a library package importing a sibling package by short name",- files: map[string]string{- "scripts/recalc.py": "from office.soffice import run_soffice\n",- "scripts/office/soffice.py": "def run_soffice():\n pass\n",- "scripts/office/validate.py": "from helpers import safe_extract\n" +- "from validators import BaseSchemaValidator\n",- "scripts/office/helpers/__init__.py": "def safe_extract():\n pass\n",- "scripts/office/validators/__init__.py": "from .base import BaseSchemaValidator\n",- "scripts/office/validators/base.py": "from helpers import safe_extract\n" +- "class BaseSchemaValidator:\n pass\n",- "scripts/office/validators/docx.py": "from helpers import safe_extract\n",- },- }, {- name: "a library package importing a dependency the installer never installed",- files: map[string]string{- "scripts/office/validate.py": "x = 1\n",- "scripts/office/helpers/__init__.py": "x = 1\n",- "scripts/office/validators/__init__.py": "",- "scripts/office/validators/base.py": "import totally_absent_package\n",- },- wantProblem: "scripts/office/validators/base.py imports totally_absent_package, " +- "which is not available in this image",- wantExit: 2,- }, {- // The same layout without __init__.py anywhere. PEP 420 makes those- // directories namespace packages, so a neighbouring entry script still- // resolves the short-name import - which is why prefixes are every- // ancestor and not only the ones a package marker chains together.- name: "a namespace package importing a sibling by short name",- files: map[string]string{- "scripts/office/validate.py": "from helpers import safe_extract\n",- "scripts/office/helpers/__init__.py": "def safe_extract():\n pass\n",- "scripts/office/validators/base.py": "from helpers import safe_extract\n",- "scripts/pkg/sub/mod.py": "from util import go\n",- "scripts/pkg/util.py": "def go():\n pass\n",- },}, {name: "a pyproject.toml dependency the venv does not carry",files: map[string]string{@@ -242,22 +120,6 @@ func TestSkillPythonVerifier(t *testing.T) {},wantProblem: "pyproject.toml declares totally_absent_package but it is not installed",wantExit: 2,- }, {- // Skills ship their tests. Nothing the skill offers loads them, so a- // bundled tests/ directory must not decide whether the skill installs -- // and refusing over one throws away the dependency work that succeeded.- name: "a bundled test file importing a package the image does not carry",- files: map[string]string{- "scripts/run.py": "x = 1\n",- "tests/test_run.py": "import pytest\nimport totally_absent_package\n",- "examples/demo.py": "import totally_absent_package\n",- "tests/conftest.py": "def broken(:\n",- "scripts/helper.py": "x = 1\n",- },- optional: []string{- "examples/demo.py", "tests/conftest.py", "tests/test_run.py",- },- wantNote: "auxiliary file; this does not fail the install",}, {// Lines that name a distribution only indirectly cannot be checked by// name, and inventing one from the URL would fail installs whose@@ -271,91 +133,17 @@ func TestSkillPythonVerifier(t *testing.T) {"scripts/run.py": "x = 1\n",},}, {- // The lib/ + sys.path bootstrap layout - the shape that failed a real- // install. Static resolution cannot see the bridge, but the script's- // own bootstrap provably raises the directory that ships the module,- // so the install passes with a note instead of a missing dependency.- name: "a script that bootstraps a sibling lib directory and imports from it",- files: map[string]string{- "lib/image_video.py": "def generate_image():\n pass\n",- "scripts/generate.py": "import sys\nimport os\n" +- "script_dir = os.path.dirname(os.path.abspath(__file__))\n" +- "lib_dir = os.path.join(script_dir, '..', 'lib')\n" +- "sys.path.insert(0, lib_dir)\n" +- "from image_video import generate_image\n",- },- wantNote: "which the skill ships at lib/image_video.py",- }, {- // The pathlib idiom must evaluate to the same bridge.- name: "a pathlib bootstrap reaching a sibling module",- files: map[string]string{- "lib/helper.py": "x = 1\n",- "scripts/runner.py": "import sys\n" +- "from pathlib import Path\n" +- "sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'lib'))\n" +- "import helper\n",- },- wantNote: "which the skill ships at lib/helper.py",- }, {- // The same shape without the bridge cannot resolve at runtime, and no- // package install provides a skill's own module - the finding names- // the shipped file instead of pretending a dependency is missing, and- // fails the install outright: a repair round can neither install a- // fix nor edit the tree.- name: "a script importing a lib module without a sys.path bootstrap",- files: map[string]string{- "lib/image_video.py": "def generate_image():\n pass\n",- "scripts/generate.py": "from image_video import generate_image\n",- },- wantProblem: "which the skill ships at lib/image_video.py",- wantExit: 1,- }, {- // The vendor guarantee holds inside the new tier: a sibling module- // sharing a dependency's name is still unresolvable unless the- // script's own bootstrap provably reaches it. (A neutral name keeps- // the case immune to whatever happens to be importable in the- // environment running the tests.)- name: "a vendored module must not satisfy an import without a bootstrap",- files: map[string]string{- "vendor/bridge_helper.py": "x = 1\n",- "scripts/run.py": "import bridge_helper\n",- },- wantProblem: "which the skill ships at vendor/bridge_helper.py",- wantExit: 1,- }, {- // ...and when the bootstrap does reach the vendored copy, the script- // genuinely works: reported, not refused.- name: "a bootstrap that reaches the vendored copy is a note",- files: map[string]string{- "vendor/bridge_helper.py": "x = 1\n",- "scripts/run.py": "import sys, os\n" +- "sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'vendor'))\n" +- "import bridge_helper\n",- },- wantNote: "which the skill ships at vendor/bridge_helper.py",- }, {- // A bridge the evaluator cannot prove stays a problem: guessing would- // be exactly the false pass the vendor rule exists to prevent.- name: "an unprovable bootstrap stays a problem",- files: map[string]string{- "lib/image_video.py": "def generate_image():\n pass\n",- "scripts/generate.py": "import sys, os\n" +- "sys.path.insert(0, os.environ['LIB_DIR'])\n" +- "from image_video import generate_image\n",- },- wantProblem: "cannot be verified statically",- wantExit: 1,- }, {- // Packages pip placed under .venv are not the skill's own code; the- // scan must not turn a genuinely missing dependency into a shipped- // note.- name: "a module that only exists under .venv is still missing",+ // Skills ship their tests. Nothing the skill offers loads them, so a+ // bundled tests/ directory must not decide whether the skill installs -+ // and refusing over one throws away the dependency work that succeeded.+ name: "a bundled test file that does not parse",files: map[string]string{- ".venv/lib/python3.11/site-packages/ghost_mod.py": "x = 1\n",- "scripts/run.py": "import ghost_mod\n",+ "scripts/run.py": "x = 1\n",+ "tests/conftest.py": "def broken(:\n",+ "examples/demo.py": "def also_broken(:\n",},- wantProblem: "not available in this image",- wantExit: 2,+ optional: []string{"examples/demo.py", "tests/conftest.py"},+ wantNote: "auxiliary file; this does not fail the install",}}for _, tc := range cases {@@ -440,12 +228,88 @@ func TestSkillPythonVerifierReportsAnUnreadableScript(t *testing.T) {"a file the execution user cannot read is not something installing a package fixes")}+// The contract this checker now keeps: an import shape is never a verdict.+//+// Whether `import helper` resolves depends on what the file does to sys.path+// before the import runs, and no static evaluator can enumerate those idioms —+// a guarded insert, a path constant imported from a sibling module, a value+// read from the environment, a mutation inside a helper function. Every+// approximation refused skills that run perfectly. Proving an import resolves+// belongs to the installer agent, which has a root shell and the real+// interpreter; this pass only proves the file parses.+//+// Each case below was once a refused install. All of them must now install.+func TestSkillPythonVerifierNeverJudgesImports(t *testing.T) {+ shapes := map[string]map[string]string{+ "a package the image genuinely does not carry": {+ "scripts/run.py": "import totally_absent_package\n",+ },+ "a sibling module reached only by a sys.path bootstrap": {+ "lib/image_video.py": "def generate_image():\n pass\n",+ "scripts/generate.py": "import sys, os\n" ++ "sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'lib'))\n" ++ "from image_video import generate_image\n",+ },+ "a sibling module with no bootstrap at all": {+ "lib/image_video.py": "def generate_image():\n pass\n",+ "scripts/generate.py": "from image_video import generate_image\n",+ },+ "a bootstrap whose argument cannot be evaluated statically": {+ "lib/helper.py": "x = 1\n",+ "scripts/run.py": "import sys, os\n" ++ "sys.path.insert(0, os.environ['LIB_DIR'])\n" ++ "import helper\n",+ },+ "a bootstrap written inside a helper function": {+ "lib/helper.py": "x = 1\n",+ "scripts/run.py": "import sys\n" ++ "from pathlib import Path\n" ++ "def _setup():\n" ++ " sys.path.insert(0, str(Path(__file__).parent.parent / 'lib'))\n" ++ "_setup()\n" ++ "import helper\n",+ },+ "a path constant imported from a sibling module": {+ "scripts/paths.py": "from pathlib import Path\n" ++ "LIB = Path(__file__).resolve().parent.parent / 'lib'\n",+ "lib/helper.py": "x = 1\n",+ "scripts/run.py": "import sys\n" ++ "from paths import LIB\n" ++ "if str(LIB) not in sys.path:\n" ++ " sys.path.insert(0, str(LIB))\n" ++ "import helper\n",+ },+ "a vendored module sharing a distribution's name": {+ "vendor/totally_absent_package.py": "x = 1\n",+ "scripts/run.py": "import totally_absent_package\n",+ },+ "a relative import in a directory with no __init__.py": {+ "scripts/run.py": "from .helper import go\n",+ "scripts/helper.py": "def go():\n pass\n",+ },+ "a relative import reaching a module the skill does not ship": {+ "pkg/__init__.py": "",+ "pkg/sub/__init__.py": "",+ "pkg/sub/run.py": "from ..missing import go\n",+ },+ }++ for name, files := range shapes {+ t.Run(name, func(t *testing.T) {+ root := writeSkillTree(t, files)++ stdout, stderr, err := runSkillPythonVerifier(t, root, pythonFiles(files), nil)++ require.NoError(t, err,+ "an import shape must not refuse an install; stderr: %s", stderr)+ require.Contains(t, stdout, "verified")+ })+ }+}+// The layout that started this: the official office toolkit ships entry scripts// beside sibling packages, and its library modules import those siblings by-// short name. Treating every .py as an isolated __main__ rejected it outright.-// The imports it cannot resolve here are the third-party ones it genuinely-// needs — including two its SKILL.md never mentions — and that is the list the-// installer gets handed back.+// short name. It parses, so it installs.func TestSkillPythonVerifierAcceptsTheOfficeToolkitLayout(t *testing.T) {files := map[string]string{"SKILL.md": "# xlsx\n",diff --git a/internal/modelcontext/tool_policy.go b/internal/modelcontext/tool_policy.goindex 3577eb09a..9f6229488 100644--- a/internal/modelcontext/tool_policy.go+++ b/internal/modelcontext/tool_policy.go@@ -158,6 +158,10 @@ var toolHandlePolicies = map[string]toolHandlePolicy{"read_sandbox_file": {},"write_sandbox_file": {},"edit_sandbox_file": {},+ // Installer-only writers for the skill image tree. Same unknown-shape+ // caveat: they echo paths and byte counts, never knowledge identifiers.+ "write_skill_file": {},+ "edit_skill_file": {},}// HasToolPolicy reports whether a tool has an explicit model-handle policy.diff --git a/internal/types/agent.go b/internal/types/agent.goindex cdbb16293..c20621045 100644--- a/internal/types/agent.go+++ b/internal/types/agent.go@@ -146,16 +146,30 @@ type AgentConfig struct {// assign it. EnableSkillInstallMode is the only way in and it refuses// every agent except the built-in skill installer.skillInstallMode bool++ // skillInstallDir is the one skill directory this install owns. The skill+ // file tools are scoped to it, so an installer cannot write a neighbouring+ // skill in the shared image. Unexported for the same reason as+ // skillInstallMode: the scope of a privilege must not be settable by+ // anything a tenant can store or send.+ skillInstallDir string}// EnableSkillInstallMode grants install-mode shell execution to the built-in-// skill installer agent and to nothing else. The agent ID is checked here-// rather than at the call site so there is exactly one place to audit.-func (c *AgentConfig) EnableSkillInstallMode(agentID string) {+// skill installer agent and to nothing else, scoped to the skill directory it+// was started for. The agent ID is checked here rather than at the call site+// so there is exactly one place to audit.+//+// The privilege and its scope are granted together: a caller cannot obtain the+// root shell without naming the directory the file tools will be confined to.+// skillDir is stored verbatim and validated where the tools are constructed —+// types cannot import the sandbox package that owns the path rules.+func (c *AgentConfig) EnableSkillInstallMode(agentID, skillDir string) {if c == nil || agentID != BuiltinSkillInstallerID {return}c.skillInstallMode = true+ c.skillInstallDir = skillDir}// SkillInstallMode reports whether this run may use the privileged@@ -164,6 +178,15 @@ func (c *AgentConfig) SkillInstallMode() bool {return c != nil && c.skillInstallMode}+// SkillInstallDir is the skill directory this install may write, or "" when+// this run is not an install.+func (c *AgentConfig) SkillInstallDir() string {+ if c == nil || !c.skillInstallMode {+ return ""+ }+ return c.skillInstallDir+}+// CitationsEnabled preserves citation output for legacy runtime configs that// predate the setting and therefore have a nil CitationEnabled value.func (c *AgentConfig) CitationsEnabled() bool {