@tranhoangnguyen0310/pi-flow-external 2.4.0-external.0 → 2.4.1-external.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.4.1-external.0] - 2026-09-23
+
+### Fixed
+
+- Muse rejects effective `thinking: off` before process launch because its `meta` provider does not support `--reasoning-effort none`. The error explains supported profile/parent levels without silently changing reasoning (#60).
+- Grok runtime-socket symlink sandbox failures include actionable guidance while retaining the original error, requested permissions, and fail-closed behavior. No socket changes, retries, or sandbox downgrade (#61).
+- Added an offline test of the actual Pi `openai-completions` provider payload for optional tool selectors. Client optionality is preserved; the downstream model-facing conversion remains unresolved and tracked in #62. See `docs/tool-schema-compatibility.md`.
+
 ## [2.4.0-external.0] - 2026-09-21
 
 Adds `muse` as a fifth external CLI backend, delegating to Muse Code alongside Claude Code, Codex CLI, Antigravity, and Grok Build CLI. Investigation notes: `docs/plans/muse-backend-prep.md`; ex-ante design issue: none filed — additive backend addition following the same shape as the Grok backend.

package/docs/field-testing.md

@@ -51,7 +51,9 @@ Defaults:
 
 Override with `--model`/`--thinking`. Use `--keep` only when evidence inspection is necessary; it preserves sensitive output and the temporary profile path printed by the runner.
 
-Grok's `readonly`/`edit` tiers run under its own kernel sandbox (`--sandbox read-only`/`workspace`). On a macOS host where `/var/run/docker.sock` resolves to a symlink, sandbox startup can fail closed before the child even runs the prompt — that is expected fail-closed behavior, not a bug; verify enforcement on Linux, or adjust the host's Docker socket if you need to reproduce it locally on macOS.
+Grok's `readonly`/`edit` tiers run under its own kernel sandbox (`--sandbox read-only`/`workspace`). Grok 1.0.40 on macOS can refuse startup with `sandbox could not be applied: socket deny resolution failed: could not resolve runtime-socket deny path /var/run/docker.sock: endpoint is a symlink`. This is an upstream CLI/environment incompatibility, not proof that the adapter's sandbox flags are wrong. The failed receipt retains the diagnostic and requested permission metadata; the adapter never retries with sandbox off. Do **not** remove or alter the Docker socket as a runner workaround. Verify sandbox enforcement on a compatible host or check a newer Grok version with an actual sandboxed invocation, not just `--help`. An explicitly requested `danger` run has no OS isolation and does not validate readonly delegation. Track compatibility and any confirmed upstream fix in [#61](https://github.com/tranhoangnguyen03/pi-flow-external/issues/61); no fixed upstream version has been verified.
+
+Muse Code 1.3.0 accepts `none` in help text but its `meta` provider rejects `--reasoning-effort none`. Effective `thinking: off` (including the parent session's inherited default) therefore fails before launch with remediation; it is never silently mapped to minimal. Pin the Muse profile to `minimal`, `low`, `medium`, `high`, or `xhigh`, or select a supported parent thinking level. Removing a profile pin alone does not help when the parent still inherits `off`. Compatibility probes must invoke provider validation, not merely inspect `--help`.
 
 Muse's `meta` provider performs its own internal retries (observed up to 10 attempts with growing backoff on transient 503/504 errors) entirely inside the `muse` process; this is unrelated to and invisible from this extension's own no-auto-retry contract, and shows up only as activity narration (e.g. "retrying meta model stream in 60000ms (attempt 3/10)"). A run that never reports usage/cost is expected — Muse has never been observed to report either.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.4.0-external.0",
+  "version": "2.4.1-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, and Muse Code delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/grok.ts

@@ -274,6 +274,29 @@ export function extractGrokError(event: Record<string, unknown>): string | undef
   return undefined;
 }
 
+/**
+ * Produces an actionable diagnosis when Grok's kernel sandbox refuses to start
+ * because a runtime socket deny path is a symlink.
+ *
+ * Preserves the exact stderr and explains:
+ * - Upstream Grok sandbox initialization failed because a runtime socket deny path is a symlink.
+ * - The socket must NOT be removed or altered as a runner workaround.
+ * - pi-flow-external preserves requested sandbox permissions and will never automatically downgrade
+ *   or retry with protections disabled.
+ * - Recommends running on a compatible host or upgrading to an upstream Grok release.
+ */
+export function diagnoseGrokSandboxError(stderr: string): string | undefined {
+  if (!stderr.includes("runtime-socket deny path") || !stderr.includes("endpoint is a symlink")) {
+    return undefined;
+  }
+  return (
+    "Grok sandbox initialization failed because a runtime socket deny path is a symlink. " +
+    "Do not remove or alter the socket as a runner workaround. " +
+    "pi-flow-external preserves requested sandbox permissions and will not automatically downgrade or retry with protections disabled. " +
+    "Run on a compatible host or upgrade to an upstream Grok release that resolves socket symlinks."
+  );
+}
+
 function getPreviewFromRecord(record: Record<string, unknown>): string {
   const candidates = [
     record.command,
@@ -560,8 +583,10 @@ export async function spawnGrokSubagent(params: {
     }
     if (closeResult.code !== 0) {
       const stderr = stderrBuffer.text().trim();
+      const diagnostic = diagnoseGrokSandboxError(stderr);
+      const diagnosticSuffix = diagnostic ? `\n\nDiagnostic: ${diagnostic}` : "";
       throw new Error(
-        `grok exited with code ${closeResult.code}${closeResult.signal ? ` (signal ${closeResult.signal})` : ""}${stderr ? `: ${stderr}` : ""}`,
+        `grok exited with code ${closeResult.code}${closeResult.signal ? ` (signal ${closeResult.signal})` : ""}${stderr ? `: ${stderr}` : ""}${diagnosticSuffix}`,
       );
     }
 

package/src/core/muse.ts

@@ -21,6 +21,7 @@ import { abortChildTree } from "./process-tree.ts";
 import { selectorHarness } from "../profiles.ts";
 
 const MUSE_COMMAND = "muse";
+const MUSE_PROVIDER = "meta";
 
 export type MuseReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
@@ -49,6 +50,38 @@ export function normalizeMuseReasoningEffort(thinkingLevel: ThinkingLevel | unde
   return undefined;
 }
 
+/**
+ * `muse exec --help` syntactically lists `none` as a valid `--reasoning-effort`
+ * value, but `--provider meta` rejects it at launch (verified against
+ * installed Muse Code 1.3.0: `--reasoning-effort none is not supported with
+ * --provider meta; choose minimal|low|medium|high|xhigh|max|ultra`, exit 2).
+ * `thinking: "off"` therefore has no representable effort for this provider —
+ * and it is not a rare edge case. `off` is the pinned `pi-agent-core` SDK's
+ * own session-level thinking default (`agent.js`/`agent-harness.js`/
+ * `session.js`), so any muse call whose profile leaves `thinking` unset
+ * inherits `"off"` from the parent session unless a user has explicitly
+ * raised it; `pi-subagent.ts`/`workflow/tool.ts` resolve
+ * `profile.thinking ?? <session thinking level>` before ever reaching
+ * {@link buildMuseArgs}, so a profile pinning `thinking: off` in its own
+ * frontmatter reaches this same check the same way. `buildMuseArgs` applies
+ * one more `thinkingLevel ?? profile.thinking` fallback of its own (for
+ * direct/test callers), so this is checked once on that fully merged,
+ * already-normalized value — inherited-default and profile-pinned `off`
+ * are indistinguishable by the time they get here, and both are rejected
+ * rather than one silently downgraded to `minimal` (a different, undisclosed
+ * reasoning level from what was actually requested or inherited).
+ */
+function assertMuseReasoningEffortSupported(effort: MuseReasoningEffort | undefined, profileName: string): void {
+  if (effort !== "none") {
+    return;
+  }
+  throw new Error(
+    `Muse profile "${profileName}" resolved thinking "off", which has no --reasoning-effort equivalent under --provider ${MUSE_PROVIDER} ` +
+      `(muse rejects "--reasoning-effort none"). Pin this Muse profile's thinking to minimal, low, medium, high, or xhigh, ` +
+      `or select a supported parent thinking level. An unset profile inherits the parent's level, which may still be off.`,
+  );
+}
+
 export function buildMuseArgs({
   promptFilePath,
   schemaFilePath,
@@ -66,7 +99,10 @@ export function buildMuseArgs({
   permission?: PermissionTier;
   resumeSessionId?: string;
 }): string[] {
-  const args: string[] = ["exec", "--json", "--provider", "meta", "--workspace", workspace, "--prompt-file", promptFilePath];
+  const effort = normalizeMuseReasoningEffort(thinkingLevel ?? profile.thinking);
+  assertMuseReasoningEffortSupported(effort, profile.name);
+
+  const args: string[] = ["exec", "--json", "--provider", MUSE_PROVIDER, "--workspace", workspace, "--prompt-file", promptFilePath];
   if (schemaFilePath) {
     args.push("--output-schema", schemaFilePath);
   }
@@ -77,7 +113,6 @@ export function buildMuseArgs({
   if (profile.model) {
     args.push("--model", profile.model);
   }
-  const effort = normalizeMuseReasoningEffort(thinkingLevel ?? profile.thinking);
   if (effort) {
     args.push("--reasoning-effort", effort);
   }