@themoltnet/pi-runtime 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -43,6 +43,9 @@ export declare interface AllowedToolsClient {
         }) => Promise<{
             enforcement: ToolEnforcement;
             allowedTools: string[];
+            allowedShellCommands: Array<{
+                argvPrefix: string[];
+            }>;
         }>;
     };
 }
@@ -591,12 +594,16 @@ export declare function findMainWorktree(startPath?: string): string;
  */
 export declare type GateDecision = {
     allow: true;
+    matchedShellCommands?: MatchedShellCommand[];
 } | {
     allow: false;
     reason: string;
+    missing?: string[];
+    missingShellCommands?: MissingShellCommand[];
 } | {
     audit: string;
     missing?: string[];
+    missingShellCommands?: MissingShellCommand[];
 };
 
 export declare interface GateInput {
@@ -607,6 +614,8 @@ export declare interface GateInput {
     enforcement: ToolEnforcement;
     /** Names the policy allows (structured tool names + shell executable names). */
     allowedTools: ReadonlySet<string>;
+    /** Shell argv rules. Each rule matches the first N statically known tokens. */
+    allowedShellCommands: readonly ShellCommandRule[];
     /**
      * Synchronous shell analyzer (`ShellCommandAnalyzer.analyze`). Injected so the
      * decision stays pure and testable; the analyzer's async WASM init happens
@@ -694,6 +703,12 @@ export declare interface ManagedVm {
     agentDir: string;
 }
 
+declare interface MatchedShellCommand {
+    executable: string;
+    argvPrefixFingerprint: string;
+    argvPrefixLength: number;
+}
+
 export declare function materializePiExtensions(input: {
     runtime: PiRuntimeDefinition;
     context: PiToolContext;
@@ -714,6 +729,18 @@ export declare function materializePiTools(input: {
     };
 }): Promise<ToolDefinition[]>;
 
+/**
+ * Literal-free metadata for a shell invocation that did not match policy.
+ * argv values are deliberately omitted; the fingerprint distinguishes
+ * invocations without placing literal arguments in the decision.
+ */
+declare interface MissingShellCommand {
+    executable: string;
+    argvFingerprint: string;
+    argvLength: number;
+    dynamicTokenCount: number;
+}
+
 export declare const MOLTNET_TOOL_NAMES: readonly ["moltnet_pack_get", "moltnet_pack_create", "moltnet_pack_provenance", "moltnet_pack_render", "moltnet_rendered_pack_list", "moltnet_rendered_pack_get", "moltnet_diary_tags", "moltnet_list_entries", "moltnet_get_entry", "moltnet_search_entries", "moltnet_create_entry", "moltnet_get_task", "moltnet_list_task_attempts", "moltnet_list_task_messages", "moltnet_upload_task_artifact", "moltnet_list_task_artifacts", "moltnet_download_task_artifact", "moltnet_review_session_errors", "moltnet_host_exec"];
 
 declare type MoltNetAgent = Awaited<ReturnType<typeof connect>>;
@@ -1183,6 +1210,7 @@ export declare interface SandboxConfig {
 export declare interface SessionToolPolicy {
     enforcement: ToolEnforcement;
     allowedTools: ReadonlySet<string>;
+    allowedShellCommands: readonly ShellCommandRule[];
     /**
      * `true` when the allow-set is a **degraded fallback** — the allowed-tools
      * fetch failed or timed out and this policy is the fail-closed/fail-open
@@ -1195,6 +1223,10 @@ export declare interface SessionToolPolicy {
     degraded: boolean;
 }
 
+declare interface ShellCommandRule {
+    argvPrefix: readonly [string, string, ...string[]];
+}
+
 /** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
 export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
 

package/dist/index.js

@@ -30549,6 +30549,10 @@ var FIND_EXEC_FLAGS = new Set([
 	"-okdir"
 ]);
 var ESCAPE_FLAG_SPECS = new Map([
+	["env", {
+		separate: ["-S", "--split-string"],
+		inline: [{ flag: "--split-string" }]
+	}],
 	["tar", { inline: [{ flag: "--to-command" }, {
 		flag: "--checkpoint-action",
 		valuePrefix: "exec="
@@ -30611,6 +30615,7 @@ function resolveDefaultBashWasm() {
 var DEFAULT_MAX_COMMAND_LENGTH = 1e5;
 var ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
 var GLOB_RE = /[*?[\]]/;
+var WHITESPACE_RE = /\s/u;
 var SUBSTITUTION_TYPES = ["command_substitution", "process_substitution"];
 /** Guards against pathological nesting of escape-flag values. */
 var MAX_ESCAPE_DEPTH = 3;
@@ -30620,11 +30625,22 @@ function baseName(raw) {
 	const slash = raw.lastIndexOf("/");
 	return slash === -1 ? raw : raw.slice(slash + 1);
 }
+/** Build the public argv vector for one resolved invocation. */
+function invocationFor(words) {
+	const head = words[0]?.name;
+	if (head === null || head === void 0) return null;
+	const name = baseName(head);
+	return {
+		name,
+		argv: [name, ...words.slice(1).map((word) => word.name)]
+	};
+}
 /** Classify one AST node into a {@link Word}. */
 function classifyToken(node) {
 	const raw = node.text;
 	switch (node.type) {
-		case "word": return {
+		case "word":
+		case "number": return {
 			raw,
 			name: raw.includes("\\") ? null : raw
 		};
@@ -30736,7 +30752,12 @@ function advancePastWrapper(words, start, spec) {
 * span (up to the `;`/`+` terminator).
 */
 function resolveFind(words, wrapperDepth) {
-	const executables = ["find"];
+	const find = invocationFor(words);
+	if (!find) return {
+		ok: false,
+		reason: "non-literal find invocation"
+	};
+	const invocations = [find];
 	const escapes = [];
 	for (let i = 1; i < words.length; i++) {
 		if (!FIND_EXEC_FLAGS.has(words[i].raw)) continue;
@@ -30753,13 +30774,13 @@ function resolveFind(words, wrapperDepth) {
 		};
 		const inner = resolveWords(cmd, wrapperDepth);
 		if (!inner.ok) return inner;
-		executables.push(...inner.executables);
+		invocations.push(...inner.invocations);
 		escapes.push(...inner.escapes);
 		i = k - 1;
 	}
 	return {
 		ok: true,
-		executables,
+		invocations,
 		escapes
 	};
 }
@@ -30772,7 +30793,7 @@ function resolveWords(words, wrapperDepth = 0) {
 	const head = words[0];
 	if (!head) return {
 		ok: true,
-		executables: [],
+		invocations: [],
 		escapes: []
 	};
 	if (head.name === null) return {
@@ -30780,11 +30801,20 @@ function resolveWords(words, wrapperDepth = 0) {
 		reason: `non-literal command name: ${head.raw}`
 	};
 	const name = head.name;
+	if (WHITESPACE_RE.test(name)) return {
+		ok: false,
+		reason: "literal command name contains whitespace"
+	};
 	if (GLOB_RE.test(name)) return {
 		ok: false,
-		reason: `command name contains a glob: ${name}`
+		reason: "command name contains a glob"
 	};
 	const exe = baseName(name);
+	const invocation = invocationFor(words);
+	if (!invocation) return {
+		ok: false,
+		reason: `non-literal command name: ${head.raw}`
+	};
 	if (exe === "eval") return {
 		ok: false,
 		reason: "eval executes a dynamically built command"
@@ -30797,26 +30827,27 @@ function resolveWords(words, wrapperDepth = 0) {
 			reason: "wrapper nesting too deep"
 		};
 		const advance = advancePastWrapper(words, 1, spec);
+		const wrapperEscapes = escapeFlagCommands(exe, words);
 		if (advance.kind === "deny") return {
 			ok: false,
 			reason: advance.reason
 		};
 		if (advance.kind === "none") return {
 			ok: true,
-			executables: [exe],
-			escapes: []
+			invocations: [invocation],
+			escapes: wrapperEscapes
 		};
 		const inner = resolveWords(words.slice(advance.index), wrapperDepth + 1);
 		if (!inner.ok) return inner;
 		return {
 			ok: true,
-			executables: [exe, ...inner.executables],
-			escapes: inner.escapes
+			invocations: [invocation, ...inner.invocations],
+			escapes: [...wrapperEscapes, ...inner.escapes]
 		};
 	}
 	return {
 		ok: true,
-		executables: [exe],
+		invocations: [invocation],
 		escapes: escapeFlagCommands(exe, words)
 	};
 }
@@ -30965,6 +30996,10 @@ var ShellCommandAnalyzer = class ShellCommandAnalyzer {
 		try {
 			const root = tree.rootNode;
 			const ast = root.toString();
+			const hasOutputRedirection = root.descendantsOfType("file_redirect").some((redirect) => {
+				const text = redirect?.text.trimStart() ?? "";
+				return /^(?:\d+)?(?:>|>>|>\||&>|&>>|<>)/u.test(text);
+			});
 			if (root.hasError) return {
 				ok: false,
 				command,
@@ -30995,12 +31030,16 @@ var ShellCommandAnalyzer = class ShellCommandAnalyzer {
 					ast
 				};
 				const raw = node.text;
-				for (const name of resolution.executables) tools.push({
-					name,
-					risk: classifyRisk(name),
-					capabilities: gtfobinsFunctions(name),
-					raw
-				});
+				for (const invocation of resolution.invocations) {
+					const { name } = invocation;
+					tools.push({
+						name,
+						argv: invocation.argv,
+						risk: classifyRisk(name),
+						capabilities: gtfobinsFunctions(name),
+						raw
+					});
+				}
 				for (const sub of resolution.escapes) {
 					if (depth >= MAX_ESCAPE_DEPTH) return {
 						ok: false,
@@ -31012,7 +31051,7 @@ var ShellCommandAnalyzer = class ShellCommandAnalyzer {
 					if (!nested.ok) return {
 						ok: false,
 						command,
-						reason: `in escape flag (${sub}): ${nested.reason}`,
+						reason: `unresolvable command in escape flag: ${nested.reason}`,
 						ast
 					};
 					tools.push(...nested.tools);
@@ -31028,7 +31067,8 @@ var ShellCommandAnalyzer = class ShellCommandAnalyzer {
 				ok: true,
 				command,
 				tools,
-				ast
+				ast,
+				hasOutputRedirection
 			};
 		} finally {
 			tree.delete();
@@ -32389,26 +32429,72 @@ function createGondolinBashOps(vm, localCwd, guestWorkspace) {
 function decideToolCall(input) {
 	if (input.enforcement === "off") return { allow: true };
 	const resolved = resolveNames(input);
-	if (resolved.kind === "unresolvable") return fenced(input.enforcement, `shell command could not be statically authorized: ${resolved.reason}`, `unresolvable shell command (watch): ${resolved.reason}`);
+	if (resolved.kind === "unresolvable") return fenced(input.enforcement, "shell command could not be statically authorized", "unresolvable shell command (watch)");
 	const arbitraryCode = [...new Set(resolved.tools.filter((tool) => tool.risk === "arbitrary-code").map((tool) => tool.name))];
 	if (arbitraryCode.length > 0) return fenced(input.enforcement, `arbitrary-code interpreter not authorizable by tool policy: ${arbitraryCode.join(", ")}`, `would block — arbitrary-code interpreter (watch): ${arbitraryCode.join(", ")}`, arbitraryCode);
-	const missing = [...new Set(resolved.tools.map((tool) => tool.name))].filter((name) => !input.allowedTools.has(name));
-	if (missing.length === 0) return { allow: true };
-	return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing);
+	if (input.toolName !== "bash") {
+		const missing = resolved.tools.map((tool) => tool.name).filter((name) => !input.allowedTools.has(name));
+		if (missing.length === 0) return { allow: true };
+		return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing);
+	}
+	const matchedShellCommands = [];
+	const missingShellCommands = resolved.tools.filter((tool) => {
+		if (input.allowedTools.has(tool.name)) return false;
+		const matched = input.allowedShellCommands.find((rule) => matchesArgvPrefix(tool.argv, rule.argvPrefix));
+		if (!matched) return true;
+		matchedShellCommands.push(toMatchedShellCommand(tool.name, matched.argvPrefix));
+		return false;
+	}).map(toMissingShellCommand);
+	if (missingShellCommands.length === 0 && resolved.hasOutputRedirection && matchedShellCommands.length > 0) return fenced(input.enforcement, "shell output redirection requires broad executable permission", "would block shell output redirection under scoped command policy", [...new Set(matchedShellCommands.map(({ executable }) => executable))], matchedShellCommands.map(({ executable, argvPrefixFingerprint, argvPrefixLength }) => ({
+		executable,
+		argvFingerprint: argvPrefixFingerprint,
+		argvLength: argvPrefixLength,
+		dynamicTokenCount: 0
+	})));
+	if (missingShellCommands.length === 0) return matchedShellCommands.length > 0 ? {
+		allow: true,
+		matchedShellCommands
+	} : { allow: true };
+	const missing = [...new Set(missingShellCommands.map(({ executable }) => executable))];
+	return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing, missingShellCommands);
+}
+function fingerprintArgv(argv) {
+	return `sha256:${createHash$1("sha256").update(JSON.stringify(argv.map((token) => token === null ? { dynamic: true } : token))).digest("hex").slice(0, 16)}`;
+}
+function toMatchedShellCommand(executable, argvPrefix) {
+	return {
+		executable,
+		argvPrefixFingerprint: fingerprintArgv(argvPrefix),
+		argvPrefixLength: argvPrefix.length
+	};
+}
+function toMissingShellCommand(tool) {
+	return {
+		executable: tool.name,
+		argvFingerprint: fingerprintArgv(tool.argv),
+		argvLength: tool.argv.length,
+		dynamicTokenCount: tool.argv.filter((token) => token === null).length
+	};
+}
+function matchesArgvPrefix(argv, prefix) {
+	return argv.length >= prefix.length && prefix.every((token, index) => argv[index] !== null && argv[index] === token);
 }
 /**
 * Shared enforce/watch branch: block in `enforce`, audit-and-allow in `watch`.
 * `enforcement` is never `off` here (short-circuited by the caller).
 */
-function fenced(enforcement, blockReason, auditReason, missing) {
+function fenced(enforcement, blockReason, auditReason, missing, missingShellCommands) {
 	if (enforcement === "enforce") return {
 		allow: false,
-		reason: blockReason
+		reason: blockReason,
+		...missing ? { missing } : {},
+		...missingShellCommands?.length ? { missingShellCommands } : {}
 	};
-	return missing ? {
+	return {
 		audit: auditReason,
-		missing
-	} : { audit: auditReason };
+		...missing ? { missing } : {},
+		...missingShellCommands?.length ? { missingShellCommands } : {}
+	};
 }
 /**
 * The authorization targets for a tool call. For structured tools it is the tool
@@ -32421,6 +32507,7 @@ function resolveNames(input) {
 		kind: "names",
 		tools: [{
 			name: input.toolName,
+			argv: [input.toolName],
 			risk: "unknown"
 		}]
 	};
@@ -32434,8 +32521,10 @@ function resolveNames(input) {
 		kind: "names",
 		tools: analysis.tools.map((tool) => ({
 			name: tool.name,
+			argv: tool.argv,
 			risk: tool.risk
-		}))
+		})),
+		hasOutputRedirection: analysis.hasOutputRedirection === true
 	} : {
 		kind: "unresolvable",
 		reason: analysis.reason
@@ -32463,14 +32552,20 @@ async function resolveSessionToolPolicy(input) {
 	if (input.enforcement === "off") return {
 		enforcement: "off",
 		allowedTools: /* @__PURE__ */ new Set(),
+		allowedShellCommands: [],
 		degraded: false
 	};
 	const timeoutMs = input.timeoutMs ?? 5e3;
 	try {
 		const resolved = await withTimeout$1(input.agent.runtimeProfiles.allowedTools(input.profileId, { teamId: input.teamId }), timeoutMs);
+		const shellCommands = resolved.allowedShellCommands ?? [];
 		return {
 			enforcement: resolved.enforcement,
 			allowedTools: new Set(resolved.allowedTools),
+			allowedShellCommands: shellCommands.map((rule) => {
+				if (rule.argvPrefix.length < 2 || rule.argvPrefix.length > 8 || rule.argvPrefix.some((token) => !token)) throw new Error("runtime returned an invalid shell command rule");
+				return { argvPrefix: rule.argvPrefix };
+			}),
 			degraded: false
 		};
 	} catch (err) {
@@ -32485,6 +32580,7 @@ async function resolveSessionToolPolicy(input) {
 		return {
 			enforcement: input.enforcement,
 			allowedTools: /* @__PURE__ */ new Set(),
+			allowedShellCommands: [],
 			degraded: true
 		};
 	}
@@ -32526,6 +32622,7 @@ function decideForEvent(event, policy, analyze) {
 		command,
 		enforcement: policy.enforcement,
 		allowedTools: policy.allowedTools,
+		allowedShellCommands: policy.allowedShellCommands,
 		analyze
 	});
 }
@@ -32539,7 +32636,14 @@ function createToolPolicyExtension(deps) {
 		if (deps.policy.enforcement === "off") return;
 		pi.on("tool_call", (event) => {
 			const decision = decideForEvent(event, deps.policy, (command) => deps.analyzer.analyze(command));
-			if ("allow" in decision && decision.allow) return;
+			if ("allow" in decision && decision.allow) {
+				if (decision.matchedShellCommands?.length) deps.logger.debug({
+					toolName: event.toolName,
+					toolCallId: event.toolCallId,
+					matchedShellCommands: decision.matchedShellCommands
+				}, "tool_policy.shell_command_allowed");
+				return;
+			}
 			if ("audit" in decision) {
 				deps.logger.info({
 					toolName: event.toolName,
@@ -32553,7 +32657,9 @@ function createToolPolicyExtension(deps) {
 				toolName: event.toolName,
 				toolCallId: event.toolCallId,
 				degraded: deps.policy.degraded,
-				reason: decision.reason
+				reason: decision.reason,
+				missingExecutables: decision.missing,
+				missingShellCommands: decision.missingShellCommands
 			}, "tool_policy.blocked");
 			return {
 				block: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Composable MoltNet runtime kernel for Pi agents in Gondolin VMs",
@@ -27,8 +27,8 @@
     "@opentelemetry/api": "^1.9.0",
     "typebox": "^1.2.8",
     "@themoltnet/agent-runtime": "0.38.0",
-    "@themoltnet/sdk": "0.128.0",
-    "@themoltnet/shell-command-analyzer": "0.2.0"
+    "@themoltnet/shell-command-analyzer": "0.3.0",
+    "@themoltnet/sdk": "0.128.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.74.0",
@@ -45,8 +45,8 @@
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.0.0",
-    "@moltnet/crypto-service": "0.1.0",
     "@moltnet/models": "0.1.0",
+    "@moltnet/crypto-service": "0.1.0",
     "@moltnet/tasks": "0.1.0"
   },
   "engines": {