@theokit/sdk-tools 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 6dc0e26: Add `withShellExitGuidance` — a guidance wrapper for `shell_exec` soft failures.
+
+  `injectGuidance`/`withDefaultGuidance` inject an actionable `guidance` hint only on `{ ok:false, error }` results (by design). But `shell_exec` returns `{ ok:true, exit_code }` — a non-zero `exit_code` is a SOFT failure (the tool ran, the command failed) that the ok:false-only injector does not cover. `withShellExitGuidance(tool)` wraps `shell_exec` so a `{ ok:true, exit_code≠0 }` result gains a `guidance` hint ("The command exited N. Read the stderr above, fix the cause, then retry."). ADDITIVE, IDEMPOTENT, NEVER-THROW; a no-op for any other tool, for `exit_code 0`, and for non-JSON output. Composes after `withDefaultGuidance` (disjoint domains — no double-injection). Lets consumers drop app-side shell-exit guidance reimplementations.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1029,6 +1029,28 @@ function withToolResultGuidance(tool, guidance) {
 function withDefaultGuidance(tool) {
   return withToolResultGuidance(tool, DEFAULT_TOOL_GUIDANCE);
 }
+function withShellExitGuidance(tool) {
+  if (tool.name !== "shell_exec") return tool;
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: async (input) => {
+      const out = await tool.handler(input);
+      let parsed;
+      try {
+        parsed = JSON.parse(out);
+      } catch {
+        return out;
+      }
+      if (isRecord(parsed) && parsed.ok === true && typeof parsed.exit_code === "number" && parsed.exit_code !== 0 && !("guidance" in parsed)) {
+        const guidance = `The command exited ${parsed.exit_code}. Read the stderr above, fix the cause, then retry.`;
+        return JSON.stringify({ ...parsed, guidance });
+      }
+      return out;
+    }
+  };
+}
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
@@ -1978,6 +2000,7 @@ exports.todoItemsToPlanNodes = todoItemsToPlanNodes;
 exports.truncateOutput = truncateOutput;
 exports.withDefaultGuidance = withDefaultGuidance;
 exports.withDescription = withDescription;
+exports.withShellExitGuidance = withShellExitGuidance;
 exports.withToolResultGuidance = withToolResultGuidance;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map