@pi-archimedes/sudo 2.10.3 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/sudo",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -19,16 +19,16 @@
     "./guard": "./src/guard.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.10.3"
+    "@pi-archimedes/core": "2.11.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": ">=1.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "typebox": "^1.1.38",
     "typescript": "^6.0.0"
   },

package/src/tool-declarations.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Task 11 item 3 — what pi's callers are told about `sudo_exec`.
+ *
+ * `annotations` are author-declared hints with MCP's meaning, and pi documents
+ * them as unverified — the input for a permission gate that decides which calls
+ * to confirm, not a guarantee (`pi: dist/core/extensions/types.d.ts`,
+ * `ToolAnnotations`). So this test pins the declaration, nothing more: `sudo_exec`
+ * runs arbitrary privileged commands, so it is destructive and not read-only.
+ */
+
+import { describe, it, expect } from "vitest";
+import { createSudoExecTool } from "./tool.js";
+
+const tool = createSudoExecTool() as unknown as {
+  name: string;
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean };
+  exposure?: string;
+};
+
+describe("sudo_exec annotations", () => {
+  it("says it is destructive", () => {
+    expect(tool.annotations?.destructiveHint).toBe(true);
+  });
+
+  it("says it is not read-only", () => {
+    expect(tool.annotations?.readOnlyHint).toBe(false);
+  });
+
+  it("leaves the hints it has not earned undeclared", () => {
+    // idempotentHint would be a lie — a second `sudo rm` is not a no-op — and
+    // openWorldHint belongs to the tools that reach the web, not this one.
+    expect(tool.annotations?.idempotentHint).toBeUndefined();
+    expect(tool.annotations?.openWorldHint).toBeUndefined();
+  });
+
+  it("stays reachable by default (direct exposure, active on registration)", () => {
+    expect(tool.exposure ?? "direct").toBe("direct");
+  });
+});

package/src/tool.ts

@@ -385,6 +385,16 @@ export function createSudoExecTool(options: {
 		label: "sudo",
 		description: SUDO_EXEC_DESCRIPTION,
 		parameters: SudoExecParamsSchema,
+		/**
+		 * Author-declared hints with MCP's meaning, which pi passes to whatever a
+		 * permission extension does with them and documents as unverified
+		 * (`pi: dist/core/extensions/types.d.ts`, `ToolAnnotations`). This one is
+		 * worth declaring: the tool runs an arbitrary command as root, so it may
+		 * overwrite or delete rather than only add, and it is not read-only. The
+		 * confirmation this package does in its own handler is unchanged — a hint
+		 * is not a gate.
+		 */
+		annotations: { destructiveHint: true, readOnlyHint: false },
 
 		// NOTE: no return-type annotation on execute — pi reads `isError` at
 		// runtime though AgentToolResult omits it; the inferred union escapes