@molecule/api-ai-tools 1.16.5 → 1.16.6

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-11-05T15:09:26.641Z
+Generated: 2026-11-05T22:20:21.693Z
 -->
 
 # @molecule/api-ai-tools
@@ -5655,6 +5655,11 @@ Peer dependencies:
 - `@molecule/api-ai`
 
 - **`yieldOnFirstFailureFor`** can yield one still-running deployed task's concrete diagnostic; callers opt out after a prior wait result or unknown history.
+- **`wait_for_task` state probes report current progress without guessing log growth.**
+  A call shorter than one normal two-second poll omits both growth and no-growth
+  claims; task age, log counters and time-left estimates remain available.
+  Full waits still report whether the log grew. Hosts that cap a wait should
+  allow its final result read to finish before replacing it with a state probe.
 - **This package only defines the tools — it runs no model loop.** Hand them to
   the bonded AI provider (`chat({ tools, … })`) or to an
   `@molecule/api-ai-agents` run.

package/dist/index.d.ts

@@ -13,6 +13,11 @@
  *
  * @remarks
  * - **`yieldOnFirstFailureFor`** can yield one still-running deployed task's concrete diagnostic; callers opt out after a prior wait result or unknown history.
+ * - **`wait_for_task` state probes report current progress without guessing log growth.**
+ *   A call shorter than one normal two-second poll omits both growth and no-growth
+ *   claims; task age, log counters and time-left estimates remain available.
+ *   Full waits still report whether the log grew. Hosts that cap a wait should
+ *   allow its final result read to finish before replacing it with a state probe.
  * - **This package only defines the tools — it runs no model loop.** Hand them to
  *   the bonded AI provider (`chat({ tools, … })`) or to an
  *   `@molecule/api-ai-agents` run.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6IG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -13,6 +13,11 @@
  *
  * @remarks
  * - **`yieldOnFirstFailureFor`** can yield one still-running deployed task's concrete diagnostic; callers opt out after a prior wait result or unknown history.
+ * - **`wait_for_task` state probes report current progress without guessing log growth.**
+ *   A call shorter than one normal two-second poll omits both growth and no-growth
+ *   claims; task age, log counters and time-left estimates remain available.
+ *   Full waits still report whether the log grew. Hosts that cap a wait should
+ *   allow its final result read to finish before replacing it with a state probe.
  * - **This package only defines the tools — it runs no model loop.** Hand them to
  *   the bonded AI provider (`chat({ tools, … })`) or to an
  *   `@molecule/api-ai-agents` run.

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA2B9C,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAA;AAsC/B;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,KAAK,CAAC,EACnD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAmB9B;AAuLD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAwdD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAkInE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA0DlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAypGxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA2B9C,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAA;AAsC/B;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,KAAK,CAAC,EACnD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAmB9B;AAuLD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkeD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAkInE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA0DlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA0pGxF"}

package/dist/tools.js

@@ -273,6 +273,8 @@ export async function taskStopCommand(backend, taskId) {
  * ended in 20).
  */
 const TASK_END_LOOK_MS = 3_000;
+/** A normal task poll; shorter state probes cannot establish log growth during their wait. */
+const TASK_POLL_MS = 2_000;
 /** How much of a task's own output the end test reads — a runner's tally is its last lines. */
 const TASK_OUTPUT_END_BYTES = 4_000;
 /**
@@ -530,8 +532,11 @@ function secondSuiteWalk(slice) {
  * @param o - The wait's facts: `taskId`, the `slice` of the log it read,
  *   `stillWriting` (the log grew during this wait), `bytes` (the log's size, null
  *   when unreadable), `ceilingMs` (this call's ceiling, for "one more wait"), and
- *   `waitedMs` (this call's own wait, the elapsed figure when the id carries no
- *   start stamp).
+ *   `waitedMs` (the elapsed floor when the id carries no start stamp), and
+ *   `observationMs` (this call's own polling interval, excluding earlier waits).
+ *   Growth clauses require at least one normal poll: a near-zero state probe
+ *   observes the log's contents, not whether it grew during the preceding wait.
+ *   Task age, progress counters and rate estimates remain valid for those probes.
  * @returns The clauses in reading order. The first states the elapsed time, so a
  *   sentence built from them always says something.
  */
@@ -549,10 +554,12 @@ function waitProgressClauses(o) {
     // A log that already finished one walk and started another says so instead of "slow, not
     // stuck": the growth is the SECOND walk printing, and its counter is not this run's progress.
     const secondWalk = secondSuiteWalk(o.slice);
-    if (o.stillWriting && !secondWalk)
-        clauses.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
-    else if (o.bytes !== null && !secondWalk)
-        clauses.push(`its log has not grown during this wait (${o.bytes} bytes)`);
+    if (o.observationMs >= TASK_POLL_MS && !secondWalk) {
+        if (o.stillWriting)
+            clauses.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
+        else if (o.bytes !== null)
+            clauses.push(`its log has not grown during this wait (${o.bytes} bytes)`);
+    }
     if (secondWalk)
         clauses.push(`the first walk in this command has finished (${secondWalk.tally}); the command started a ` +
             'SECOND walk of the same suite — stop it (it measures nothing new) and read the first tally');
@@ -680,6 +687,7 @@ async function backgroundTaskState(backend, command, seconds, ceilingMs) {
             bytes: null,
             ceilingMs,
             waitedMs: 0,
+            observationMs: 0,
         });
         const failures = slice.trim() ? '; the failures already in its log are in outputSoFar' : '';
         return {
@@ -3602,7 +3610,7 @@ export function buildTools(backend, config) {
             let endedWithoutCode = false;
             let exitCode = await readExit();
             while (exitCode === null && Date.now() - startedAt < budgetMs) {
-                await new Promise((r) => setTimeout(r, Math.min(2_000, budgetMs - (Date.now() - startedAt))));
+                await new Promise((r) => setTimeout(r, Math.min(TASK_POLL_MS, budgetMs - (Date.now() - startedAt))));
                 exitCode = await readExit();
                 // The exit file is read first, so a run that finishes between two looks still returns
                 // its real result instead of a note about it.
@@ -3794,6 +3802,7 @@ export function buildTools(backend, config) {
                     bytes: grownTo,
                     ceilingMs: ceiling,
                     waitedMs: waitedBefore + waitedMs,
+                    observationMs: Math.min(budgetMs, waitedMs),
                 }));
                 const sliceField = soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {};
                 // What this wait found mid-run, when it was not a reason to end early: it rides the result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.16.5",
+  "version": "1.16.6",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",