pando-ai 0.6.1 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pando-ai",
-  "version": "0.6.1",
+  "version": "0.6.5",
   "description": "AI coding firewall for Codex and Claude Code: supervised launchers, Pando MCP, policy enforcement, Claude hooks, and local provider gateway.",
   "bin": {
     "pando-ai": "bin/pando-ai.js"

package/resources/tools/generated_pando-tools.json

@@ -47,11 +47,10 @@
     "replace-body(path, expectedHash, with, forceReplaceWillBreakSyntax)",
     "change-signature(path, expectedHash, parameters, returnType, makeAsync, makeSyncFromAsync, forceChangeWillBreakSyntax, boundary, batchSaves)",
     "filter-map-reduce(query, transforms, apply)",
-    "shell-command(command, reason, timeoutMs, shell, maxOutputBytes)",
+    "shell-command(command, reasonWhyNotUsingPandoNativeTools, timeoutMs, shell, maxOutputBytes)",
     "list-snapshots(offset, limit)",
     "diff-snapshots(head, base, page)",
     "get-snapshot-trailers(snapshotId, keys)",
-    "get-snapshot-file(snapshotId, path, oid)",
     "snapshot-worktree(message, trailers)",
     "restore-snapshot(snapshotId, trailers, page, shouldCreateNewSnapshot, deleteSnapshotId)",
     "restore-files(snapshotId, files, page, trailers)",
@@ -64,7 +63,7 @@
       "name": "read-this-first",
       "category": "pando",
       "signature": "read-this-first()",
-      "description": "Pando is an AST-aware code navigation and editing layer for large repos. It keeps a light index of supported source files, uses that index to narrow candidate files, then parses exact AST details at query or edit time.\n\nFiles do not need to be indexed first. To work in a file that is not yet in the index, pass its workspace-relative path directly: as scope.files or scope.node on find-nodes, or as the target path of a writer. Pando indexes that file just-in-time, in any supported language. The light index only limits workspace-wide discovery (scope.workspace); an explicit file path always works even if the file has never been indexed. This means you can edit any AST node in any supported file without a separate indexing step.\n\nUse Pando for source-code search, navigation, references, callers, exports, renames, inserts, replacements, and deletes. Use shell/text tools for builds, tests, generated files, non-code files, and unsupported languages.\n\nRead next:\n- workspace-overview: quick inventory of indexed files and symbols.\n- find-nodes: search by language, scope, and Datalog; request include.self/topN when you need paths and hashes for edits.\n- get-content: read files or node paths returned by search tools.\n- list-exports, find-references, and find-callers: follow symbols before changing them.\n- Writers: rename, replace, replace-body, insert, and delete. Re-run find-nodes first if a path or hash is stale.\n\nUnnamed nodes can and should still be edited with Pando. Statements, returns, calls, arguments, branches, literals, and other unnamed syntax are normal AST nodes; find them by starting from a named entity or file, then narrowing by kind, text, role, parent, or child index.\n\nExamples:\n- In one find-nodes call, search for a function by name within the workspace and request include.self/topN to get the exact node path and hash.\n- To edit a statement inside a named function, find the function with include.self, then call find-nodes again with scope.node set to { path, expectedHash } for that function. Use predicates such as :node/kind \"ReturnStatement\" or :node/text \"oldValue\", then pass the returned statement path and hash without @ to replace or insert; delete uses expectedHashes.\n- For scripts or top-level code, scope find-nodes to the file path instead of a named node, find the statement by kind/text/role/index, then edit that returned node with a writer.\n- Insert code is literal: include the newline and indentation you want when inserting before or after a statement anchor.\n- Edit an unnamed node end to end: find the enclosing function with find-nodes include.self to get its { path, expectedHash }; re-run find-nodes with scope.node set to that path+hash and a predicate like :node/kind \"ReturnStatement\" or :node/text \"return null\" to get the exact statement's path and hash; then call replace with that path and expectedHash (no @) to rewrite it, or insert with an anchor to add code beside it. No indexing step is needed even if the file was never indexed.",
+      "description": "Pando is an AST-aware code navigation and editing layer for large repos. It keeps a light index of supported source files, uses that index to narrow candidate files, then parses exact AST details at query or edit time.\n\nFiles do not need to be indexed first. To work in a file that is not yet in the index, pass its workspace-relative path directly: as scope.files or scope.node on find-nodes, or as the target path of a writer. Pando indexes that file just-in-time, in any supported language. The light index only limits workspace-wide discovery (scope.workspace); an explicit file path always works even if the file has never been indexed. This means you can edit any AST node in any supported file without a separate indexing step.\n\nUse Pando for supported source-code search, navigation, references, callers, exports, renames, inserts, replacements, and deletes. Use find-nodes for structural code search and edit targets, find-references/find-callers for usages, list-exports/analyze-imports for module shape, query-db for indexed metadata, and workspace-overview for inventory. Use shell/text tools for builds, tests, package managers, git, generated files, non-code files, unsupported languages/file types, and anything Pando itself does not support. Pando AST writers are for supported source-code and AST-addressable edits; use shell-based patching for unsupported non-code files such as Markdown docs.\n\nRead next:\n- workspace-overview: quick inventory of indexed files and symbols.\n- find-nodes: structural code search and edit target discovery by language, scope, and Datalog; request include.self/topN when you need paths and hashes for edits.\n- get-content: read files or node paths returned by search tools.\n- list-exports, find-references, and find-callers: follow symbols before changing them.\n- Writers: rename, replace, replace-body, insert, and delete. Re-run find-nodes first if a path or hash is stale.\n\nUnnamed nodes can and should still be edited with Pando. Statements, returns, calls, arguments, branches, literals, and other unnamed syntax are normal AST nodes; find them by starting from a named entity or file, then narrowing by kind, text, role, parent, or child index.\n\nExamples:\n- In one find-nodes call, search for a function by name within the workspace and request include.self/topN to get the exact node path and hash.\n- To edit a statement inside a named function, find the function with include.self, then call find-nodes again with scope.node set to { path, expectedHash } for that function. Use predicates such as :node/kind \"ReturnStatement\" or :node/text \"oldValue\", then pass the returned statement path and hash without @ to replace or insert; delete uses expectedHashes.\n- For scripts or top-level code, scope find-nodes to the file path instead of a named node, find the statement by kind/text/role/index, then edit that returned node with a writer.\n- Insert code is literal: include the newline and indentation you want when inserting before or after a statement anchor.\n- Edit an unnamed node end to end: find the enclosing function with find-nodes include.self to get its { path, expectedHash }; re-run find-nodes with scope.node set to that path+hash and a predicate like :node/kind \"ReturnStatement\" or :node/text \"return null\" to get the exact statement's path and hash; then call replace with that path and expectedHash (no @) to rewrite it, or insert with an anchor to add code beside it. No indexing step is needed even if the file was never indexed.",
       "parameters": {
         "type": "object",
         "properties": {},
@@ -2020,8 +2019,8 @@
     {
       "name": "shell-command",
       "category": "pando",
-      "signature": "shell-command(command, reason, timeoutMs, shell, maxOutputBytes)",
-      "description": "Strongly discouraged: prefer Pando AST/index tools before raw shell for code search, navigation, references, and edits. Use shell freely for tests, builds/compiles, package managers, git, generated or non-code files, unsupported languages, and anything Pando itself does not support. Every operation that goes through Pando, including this shell command, is snapshotted before and after; snapshots are not touchable by the agent. If needed, read ../../../pando-backend/docs/tools.md for tool behavior details. Shell results repeat this reminder so agents reconsider Pando-native tools before the next shell call. Run a shell command with cwd fixed to the selected Pando project root, then synchronously snapshot any worktree changes before another modifying Pando operation can run. The project-root confinement is also enforced by the host environment. reason is required and is written into the snapshot receipt/trailers for auditability. Command failures are returned to the agent with exit code, stdout, stderr, timeout state, and snapshot metadata. Example: { command:'npm test', reason:'Verify the current change.' }",
+      "signature": "shell-command(command, reasonWhyNotUsingPandoNativeTools, timeoutMs, shell, maxOutputBytes)",
+      "description": "Strongly discouraged: prefer Pando AST/index tools before raw shell for code search, navigation, references, and supported source-code edits. Use find-nodes for structural code search and edit targets, find-references/find-callers for usages, list-exports/analyze-imports for module shape, query-db for indexed metadata, and workspace-overview for inventory. Use shell freely for tests, builds/compiles, package managers, git, generated files, non-code files, unsupported languages/file types, and anything Pando itself does not support. Pando AST writers are for supported source-code and AST-addressable edits; use shell-based patching for unsupported non-code files such as Markdown docs. Every operation that goes through Pando, including this shell command, is snapshotted before and after; snapshots are not touchable by the agent. If needed, read ../../../pando-backend/docs/tools.md for tool behavior details. Shell results repeat this reminder so agents reconsider Pando-native tools before the next shell call. Run a shell command with cwd fixed to the selected Pando project root, then synchronously snapshot any worktree changes before another modifying Pando operation can run. The project-root confinement is also enforced by the host environment. reasonWhyNotUsingPandoNativeTools is required and is written into the snapshot receipt/trailers for auditability. Command failures are returned to the agent with exit code, stdout, stderr, timeout state, and snapshot metadata. Example: { command:'npm test', reasonWhyNotUsingPandoNativeTools:'Run the project test suite; this is execution, not code navigation.' }",
       "parameters": {
         "type": "object",
         "properties": {
@@ -2029,10 +2028,6 @@
             "type": "string",
             "description": "Shell command to execute. It always runs with cwd set to the selected project root."
           },
-          "reason": {
-            "type": "string",
-            "description": "Required audit reason for running this command. State why shell is appropriate instead of a Pando AST/index tool. This is persisted in the snapshot metadata."
-          },
           "timeoutMs": {
             "type": "number",
             "description": "Optional timeout in milliseconds. Must be 1000..600000. Defaults to 120000."
@@ -2044,18 +2039,22 @@
           "maxOutputBytes": {
             "type": "number",
             "description": "Optional combined stdout/stderr output cap in bytes. Must be 1024..1000000. Defaults to 200000."
+          },
+          "reasonWhyNotUsingPandoNativeTools": {
+            "type": "string",
+            "description": "Required audit reason for running this command. Explain why a Pando-native tool is not appropriate: use find-nodes for code search/edit targets, find-references/find-callers for usages, list-exports/analyze-imports for module shape, and shell for tests/builds/package managers/git/generated files/non-code files/unsupported languages. This is persisted in snapshot metadata."
           }
         },
         "required": [
           "command",
-          "reason"
+          "reasonWhyNotUsingPandoNativeTools"
         ],
         "additionalProperties": false
       },
       "examples": [
         {
           "command": "npm test",
-          "reason": "Verify the current change."
+          "reasonWhyNotUsingPandoNativeTools": "Run the project test suite; this is execution, not code navigation."
         }
       ]
     },
@@ -2188,40 +2187,6 @@
         }
       ]
     },
-    {
-      "name": "get-snapshot-file",
-      "category": "pando",
-      "signature": "get-snapshot-file(snapshotId, path, oid)",
-      "description": "Read a file at a snapshot. Provide (snapshotId + path) or a direct blob oid (with or without 'blob:' prefix). Examples: { snapshotId:'S_prev', path:'src/app.ts' } or { oid:'blob:1234...' }",
-      "parameters": {
-        "type": "object",
-        "properties": {
-          "snapshotId": {
-            "type": "string",
-            "description": "SnapshotId."
-          },
-          "path": {
-            "type": "string",
-            "description": "Repo-relative file path."
-          },
-          "oid": {
-            "type": "string",
-            "description": "Blob oid (40 hex), optionally prefixed with 'blob:'"
-          }
-        },
-        "required": [],
-        "additionalProperties": false
-      },
-      "examples": [
-        {
-          "snapshotId": "S_previous",
-          "path": "src/app.ts"
-        },
-        {
-          "oid": "blob:1234abcdef1234abcdef1234abcdef1234abcd"
-        }
-      ]
-    },
     {
       "name": "snapshot-worktree",
       "category": "pando",