@lazyingart/agintiflow 0.20.329 → 0.20.331

package/docs/supervision-campaign-ledger.md

@@ -700,3 +700,43 @@ status" prompt, triggers a DeepSeek quota handoff, and verifies that LocalLLM is
 called only after compaction. The run completes without `session.failed`, keeps
 the provider handoff active on the same session, and records the compaction
 events as durable evidence.
+
+### Harmless tool-call annotations during repository discovery
+
+`inspect-project-annotation-093` covers a DeepSeek-first tool-loop boundary
+that was still under-tested after the provider handoff work. Recent runtime
+evidence showed ordinary project-inspection tasks stopping with
+`tool_contract_violation` before dispatch because the model included a
+non-executable `reason` field in an otherwise valid `inspect_project` call.
+The strict per-turn schema correctly rejected unknown executable fields, but
+the existing benign-annotation normalizer only recognized `description`.
+
+AgInTiFlow now treats a bounded string `reason` exactly like `description`: it
+is removed before schema validation only when the offered tool schema forbids
+additional properties and the schema does not define that field. Structured,
+non-string, oversized, or executable unknown fields still fail closed.
+
+The regression uses a normal weak prompt asking the agent to look over a small
+repository and report whether a README exists. The scripted DeepSeek-shaped
+response calls `inspect_project` with `reason` plus a real `limit`; the persisted
+runtime dispatches the inspection, records zero tool-contract failures, and
+finishes with the verified README status without mutating the workspace.
+
+### Native tmux recovery from generic shell aliases
+
+`tmux-run-command-native-recovery-094` covers a reusable coordination-tool
+handoff gap seen in recent retained runtime evidence. A normal supervision
+prompt selected the host tmux tool bundle, but the provider tried the native
+tool name `tmux_list_sessions` and later `tmux list-sessions` through
+`run_command`. AgInTiFlow treated those as generic shell commands, producing a
+host permission pause or shell failure instead of using the already offered
+native tmux listing tool.
+
+The runtime now auto-corrects only exact read-only tmux session-list aliases
+from `run_command` to `tmux_list_sessions` before shell guardrails run. It
+records `tool.auto_corrected`, preserves the original requested tool in
+`tool.started`, dispatches no generic shell command, and leaves arbitrary tmux
+startup/send/mutation shell commands blocked by the existing permission policy.
+The focused persisted-runtime regression verifies both exact aliases and the
+negative mutating command case; the tmux guardrail, progressive-tool,
+provider-handoff, syntax, package-audit, dry-pack, and full npm suites pass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.329",
+  "version": "0.20.331",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",

package/scripts/smoke-progressive-tool-selection.js

@@ -7238,6 +7238,54 @@ assert(
   ).ok,
   "valid offered tool call did not satisfy its exact schema"
 );
+const strictInspectDescriptor = {
+  type: "function",
+  function: {
+    name: "inspect_project",
+    description: "Inspect the project.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        maxDepth: { type: "integer" },
+        limit: { type: "integer" },
+        includeFiles: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+};
+const recoveredInspectReason = resolveDispatchableToolCallBatch(
+  [
+    contractCall("inspect-with-reason", "inspect_project", {
+      reason: "Orient before answering the user's project question.",
+      limit: 120,
+    }),
+  ],
+  createToolContract([strictInspectDescriptor])
+);
+assert(
+  recoveredInspectReason.ok && recoveredInspectReason.recoveredToolCallAnnotations,
+  "a harmless inspect_project reason annotation was not stripped before schema validation"
+);
+assertStrict.deepEqual(
+  JSON.parse(recoveredInspectReason.acceptedToolCalls[0].function.arguments),
+  { limit: 120 },
+  "inspect_project reason annotation recovery changed executable arguments"
+);
+const rejectedStructuredInspectReason = resolveDispatchableToolCallBatch(
+  [
+    contractCall("inspect-structured-reason", "inspect_project", {
+      reason: { intent: "orient" },
+      limit: 120,
+    }),
+  ],
+  createToolContract([strictInspectDescriptor])
+);
+assert(
+  !rejectedStructuredInspectReason.ok,
+  "a structured inspect_project reason annotation was stripped even though it is not a bounded text note"
+);
 
 const safeReadDescriptors = [
   {
@@ -7877,6 +7925,73 @@ assert(
   "authoritative routine flow still dispatched private/raw exploratory commands"
 );
 
+let annotatedInspectStep = 0;
+const annotatedInspectRun = await runToolContractCase({
+  id: "inspect-project-reason-annotation",
+  provider: "deepseek",
+  profile: "code",
+  goal: "Please look over this little repo and tell me whether it has a README. Keep it short.",
+  toolCalls: [
+    contractCall("unused-annotated-inspect", "finish", { result: "unused" }),
+  ],
+  expectSuccess: true,
+  expectedContractFailures: 0,
+  setupWorkspace: async (workspace) => {
+    await fs.writeFile(
+      path.join(workspace, "README.md"),
+      "# Demo\nThis workspace has a README.\n",
+      "utf8"
+    );
+  },
+  responseFactory: ({ payload }) => {
+    annotatedInspectStep += 1;
+    const offered = Array.isArray(payload.tools) ? names(payload.tools) : [];
+    if (annotatedInspectStep === 1) {
+      assert(
+        offered.includes("inspect_project"),
+        "normal repository orientation did not offer inspect_project"
+      );
+      return assistantWithToolCalls([
+        contractCall("inspect-with-natural-reason", "inspect_project", {
+          reason: "Orient before answering the user's project question.",
+          limit: 120,
+        }),
+      ]);
+    }
+    return assistantWithToolCalls([
+      contractCall("finish-after-annotated-inspect", "finish", {
+        result: "README.md is present.",
+      }),
+    ]);
+  },
+});
+assertStrict.equal(
+  annotatedInspectRun.requests.length,
+  2,
+  "annotated inspect_project recovery used extra model turns"
+);
+assert(
+  annotatedInspectRun.events.some(
+    (event) =>
+      event.type === "tool.completed" &&
+      event.data?.toolName === "inspect_project" &&
+      event.data?.ok === true
+  ),
+  "annotated inspect_project call was not dispatched through the real runtime"
+);
+assert(
+  !annotatedInspectRun.events.some(
+    (event) =>
+      event.type === "tool.failed" &&
+      event.data?.category === "tool-contract-violation"
+  ),
+  "annotated inspect_project still produced a tool-contract violation"
+);
+assert(
+  /README\.md is present/.test(String(annotatedInspectRun.result?.result || "")),
+  "annotated inspect_project run did not finish with the promised repository status"
+);
+
 const hiddenDryRun = await runToolContractCase({
   id: "native-hidden-dry-run",
   goal: "Create hidden-dry-run.txt containing unsafe if this tool dispatches.",

package/scripts/smoke-truthful-completion.js

@@ -19,6 +19,7 @@ import {
   evaluateSourceFreeResponseClaims,
   finishResultClaimsIncompleteWork,
 } from "../src/scs-evidence.js";
+import { tmuxAvailable } from "../src/tmux-tools.js";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-truthful-completion-"));
@@ -860,6 +861,118 @@ try {
     "permission blocker triggered an SCS replan instead of waiting for approval"
   );
 
+  if (await tmuxAvailable()) {
+    const tmuxAliasRecovery = await runCase({
+      id: "tmux-shell-alias-recovery",
+      goal: "Check durable host tmux sessions and report whether any sessions exist.",
+      taskProfile: "auto",
+      executionTier: "focused",
+      allowShellTool: true,
+      responses: [
+        assistant("", [toolCall("tmux-as-shell", "run_command", { command: "tmux_list_sessions" })]),
+        assistant("", [
+          toolCall("finish-tmux-alias", "finish", {
+            result: "Checked durable host tmux sessions through the native tmux listing tool.",
+          }),
+        ]),
+      ],
+    });
+    assert.equal(tmuxAliasRecovery.calls.length, 2);
+    assert.equal(tmuxAliasRecovery.result.stopped, undefined);
+    assert(
+      tmuxAliasRecovery.events.some(
+        (event) =>
+          event.type === "tool.auto_corrected" &&
+          event.data?.requestedToolName === "run_command" &&
+          event.data?.toolName === "tmux_list_sessions" &&
+          event.data?.originalCommand === "tmux_list_sessions"
+      ),
+      "run_command tmux_list_sessions alias was not recovered to the native tmux tool"
+    );
+    assert(
+      tmuxAliasRecovery.events.some(
+        (event) =>
+          event.type === "tool.started" &&
+          event.data?.toolName === "tmux_list_sessions" &&
+          event.data?.requestedToolName === "run_command"
+      ),
+      "native tmux listing was not started with original requested tool evidence"
+    );
+    assert(
+      tmuxAliasRecovery.events.some(
+        (event) =>
+          event.type === "tool.completed" &&
+          event.data?.toolName === "tmux_list_sessions"
+      ),
+      "native tmux listing did not complete after alias recovery"
+    );
+    assert(
+      !tmuxAliasRecovery.events.some(
+        (event) => event.type === "tool.started" && event.data?.toolName === "run_command"
+      ),
+      "tmux alias recovery still dispatched the generic shell command"
+    );
+    assert(
+      !tmuxAliasRecovery.events.some(
+        (event) => event.type === "session.stopped" && event.data?.reason === "permission_required"
+      ),
+      "tmux alias recovery still paused on shell permission"
+    );
+
+    const tmuxReadonlyCommandRecovery = await runCase({
+      id: "tmux-readonly-command-recovery",
+      goal: "List durable host tmux sessions using the available coordination tool.",
+      taskProfile: "auto",
+      executionTier: "focused",
+      allowShellTool: true,
+      responses: [
+        assistant("", [toolCall("tmux-command-as-shell", "run_command", { command: "tmux list-sessions" })]),
+        assistant("", [
+          toolCall("finish-tmux-command", "finish", {
+            result: "Checked durable host tmux sessions through the native tmux listing tool.",
+          }),
+        ]),
+      ],
+    });
+    assert.equal(tmuxReadonlyCommandRecovery.result.stopped, undefined);
+    assert(
+      tmuxReadonlyCommandRecovery.events.some(
+        (event) =>
+          event.type === "tool.auto_corrected" &&
+          event.data?.toolName === "tmux_list_sessions" &&
+          event.data?.originalCommand === "tmux list-sessions"
+      ),
+      "exact tmux list-sessions shell command was not recovered"
+    );
+    assert(
+      !tmuxReadonlyCommandRecovery.events.some(
+        (event) => event.type === "tool.started" && event.data?.toolName === "run_command"
+      ),
+      "exact tmux list-sessions recovery still dispatched run_command"
+    );
+
+    const tmuxMutationStillBlocked = await runCase({
+      id: "tmux-mutating-command-still-blocked",
+      goal: "Try to create a tmux session through the generic shell.",
+      taskProfile: "auto",
+      executionTier: "focused",
+      allowShellTool: true,
+      responses: [
+        assistant("", [
+          toolCall("tmux-mutating-shell", "run_command", {
+            command: "tmux new-session -d -s should-not-autocorrect",
+          }),
+        ]),
+      ],
+    });
+    assert.equal(tmuxMutationStillBlocked.result.stopped, true);
+    assert.equal(tmuxMutationStillBlocked.result.reason, "permission_required");
+    assert(
+      !tmuxMutationStillBlocked.events.some((event) => event.type === "tool.auto_corrected"),
+      "mutating tmux shell command was incorrectly auto-corrected"
+    );
+  }
+
   const reasoningTruncation = await runCase({
     id: "reasoning-only-tool-continuation",
     goal: "Run pwd and report the verified working directory.",

package/src/agent-runner.js

@@ -5058,6 +5058,58 @@ export function normalizeNoMatchQueryResult(result = {}, policy = {}) {
   };
 }
 
+function runtimeFlagDisabled(value) {
+  if (value === false || value === 0) return true;
+  return /^(false|off|no|0)$/i.test(String(value ?? "").trim());
+}
+
+function exactTmuxListSessionsShellAlias(command = "") {
+  const canonical = canonicalizeShellCommand(command);
+  if (!canonical || canonical.includes("\n")) return null;
+  const sequence = parseTopLevelShellSequence(canonical);
+  if (
+    sequence.openQuote ||
+    sequence.trailingEscape ||
+    sequence.trailingSeparator ||
+    sequence.commands.length !== 1
+  ) {
+    return null;
+  }
+  const tokens = tokenizeShellWords(sequence.commands[0]).map((token) =>
+    String(token || "")
+  );
+  if (tokens.length === 1 && tokens[0] === "tmux_list_sessions") {
+    return { command: canonical, alias: "tool-name-as-shell-command" };
+  }
+  if (
+    tokens.length === 2 &&
+    tokens[0] === "tmux" &&
+    (tokens[1] === "list-sessions" || tokens[1] === "ls")
+  ) {
+    return { command: canonical, alias: "tmux-readonly-list-command" };
+  }
+  return null;
+}
+
+function recoverRunCommandTmuxListAlias(requestedToolName, args = {}, config = {}) {
+  if (requestedToolName !== "run_command") return null;
+  if (
+    runtimeFlagDisabled(config.allowShellTool) ||
+    runtimeFlagDisabled(config.allowTmuxTools) ||
+    runtimeFlagDisabled(config.allowCoordinationTools)
+  ) {
+    return null;
+  }
+  const alias = exactTmuxListSessionsShellAlias(args.command);
+  if (!alias) return null;
+  return {
+    requestedToolName,
+    toolName: "tmux_list_sessions",
+    reason: alias.alias,
+    originalCommand: alias.command,
+  };
+}
+
 function hashForLog(value) {
   return crypto.createHash("sha256").update(String(value ?? "")).digest("hex");
 }
@@ -20506,6 +20558,14 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
           prompt: "Inspect this exact generated image as verification evidence. Describe the visible content, readability, clipping, labels, scale, and any defects that require repair.",
         };
   }
+  const tmuxListAliasCorrection = !autoCorrection
+    ? recoverRunCommandTmuxListAlias(requestedToolName, args, config)
+    : null;
+  if (tmuxListAliasCorrection) {
+    toolName = tmuxListAliasCorrection.toolName;
+    args = { includePanes: true };
+    autoCorrection = tmuxListAliasCorrection;
+  }
   const repositoryCommitPaths = [
     ...(Array.isArray(config.repositoryStateRepairCommitPaths)
       ? config.repositoryStateRepairCommitPaths

package/src/tool-contract.js

@@ -30,7 +30,7 @@ const MAX_VALIDATION_ERRORS = 8;
 const MAX_VALIDATION_NODES = 50_000;
 const MAX_SAFE_SEQUENTIAL_READ_CALLS = 4;
 const MAX_REPORTED_SEQUENTIAL_CALLS = 12;
-const BENIGN_TOOL_CALL_ANNOTATION_KEYS = new Set(["description"]);
+const BENIGN_TOOL_CALL_ANNOTATION_KEYS = new Set(["description", "reason"]);
 
 function cloneValue(value) {
   return structuredClone(value);