@circuitwall/jarela 1.2.0 → 1.3.0

package/.next/standalone/.next/server/app/api/v1/builtin-tools/route.js

@@ -74,6 +74,8 @@ __webpack_require__.d(__webpack_exports__, {
 var schemas = __webpack_require__(49883);
 // EXTERNAL MODULE: ./node_modules/@langchain/core/dist/tools/index.js
 var tools = __webpack_require__(71890);
+// EXTERNAL MODULE: ./lib/tools/async-results.ts
+var async_results = __webpack_require__(95579);
 ;// ./lib/tools/wallclock.ts
 // Per-call wall-clock budgets for tools.
 //
@@ -98,19 +100,43 @@ var tools = __webpack_require__(71890);
 // mechanism.
 
 
+
 const DEFAULT_DEADLINE_MS = 120000;
-const DEADLINE_DESCRIPTION = "Optional wall-clock budget for this tool call in milliseconds (default 120000). " + "When the budget is exceeded the call returns a structured timeout result " + "and the turn continues so you can recover — pick a value that matches " + "the expected duration (5000-15000 for fast local ops, 30000-90000 for " + "network/web calls, larger for shell commands that may build or install).";
+// Hard ceiling so a runaway `deadline_ms` from the LLM (or a typo of
+// "10 minutes" as 100_000_000) can't park a single turn for hours. The
+// operator can raise or lower this with JARELA_TOOL_MAX_DEADLINE_MS
+// (integer milliseconds). Anything above the ceiling is clamped and a
+// warning is logged once per call.
+const DEFAULT_MAX_DEADLINE_MS = 30 * 60 * 1000;
+function getMaxDeadlineMs() {
+    const raw = process.env.JARELA_TOOL_MAX_DEADLINE_MS;
+    if (!raw) return DEFAULT_MAX_DEADLINE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_MAX_DEADLINE_MS;
+}
+const DEADLINE_DESCRIPTION = "Optional wall-clock budget for this tool call in milliseconds (default 120000, hard ceiling 1800000 / 30 min). " + "When the budget is exceeded the call returns a structured timeout result " + "and the turn continues so you can recover — pick a value that matches " + "the expected duration (5000-15000 for fast local ops, 30000-90000 for " + "network/web calls, larger for shell commands that may build or install). " + "Values above the ceiling are clamped; use `async_run: true` for work that genuinely needs more.";
+const ASYNC_RUN_DESCRIPTION = "Optional. Set true to fire this tool in the background and get back a " + "tracking key immediately instead of waiting for the result. Use for " + "long-running calls (large fetches, slow shell builds) when you want to " + "keep the conversation moving. Retrieve the result later by calling " + "`tool_result_get` with the returned key. The original `deadline_ms` " + "still applies — it just runs in the background.";
 function wrapWithWallclock(t) {
     // Only zod-object schemas can be extended with `deadline_ms`. Other
     // schema shapes (raw JSON Schema, ZodString) pass through unchanged.
     // Those tools still get the wallclock race using the default budget.
     const schema = t.schema;
     const extendedSchema = schema instanceof schemas/* ZodObject */.bv ? schema.extend({
-        deadline_ms: schemas/* number */.ai().int().positive().optional().describe(DEADLINE_DESCRIPTION)
+        deadline_ms: schemas/* number */.ai().int().positive().optional().describe(DEADLINE_DESCRIPTION),
+        async_run: schemas/* boolean */.zM().optional().describe(ASYNC_RUN_DESCRIPTION)
     }) : null;
     const wrappedFunc = async (args, config)=>{
-        const deadlineMs = readDeadlineMs(args) ?? DEFAULT_DEADLINE_MS;
-        const innerArgs = stripDeadline(args);
+        const requested = readDeadlineMs(args) ?? DEFAULT_DEADLINE_MS;
+        const ceiling = getMaxDeadlineMs();
+        const deadlineMs = Math.min(requested, ceiling);
+        if (requested > ceiling) {
+            console.warn(`[wallclock] tool="${t.name}" requested deadline_ms=${requested} exceeds ceiling ${ceiling}; clamped. ` + `Use async_run: true for work that genuinely needs more, or raise JARELA_TOOL_MAX_DEADLINE_MS.`);
+        }
+        const asyncRun = readAsyncRun(args);
+        const innerArgs = stripWrapperFields(args);
+        if (asyncRun) {
+            return runAsync(t, innerArgs, config, deadlineMs);
+        }
         let timer;
         const timeoutPromise = new Promise((resolve)=>{
             timer = setTimeout(()=>{
@@ -152,12 +178,56 @@ function readDeadlineMs(args) {
     const v = args.deadline_ms;
     return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
 }
-function stripDeadline(args) {
+function readAsyncRun(args) {
+    if (!args || typeof args !== "object") return false;
+    return args.async_run === true;
+}
+function stripWrapperFields(args) {
     if (!args || typeof args !== "object") return args;
-    const { deadline_ms: _ignore, ...rest } = args;
-    void _ignore;
+    const { deadline_ms: _d, async_run: _a, ...rest } = args;
+    void _d;
+    void _a;
     return rest;
 }
+/**
+ * Fire the tool detached and return a pointer the agent can poll via
+ * `tool_result_get`. The same `deadline_ms` still applies — when the
+ * timer wins, the slot is marked errored with a timeout message.
+ */ function runAsync(t, innerArgs, config, deadlineMs) {
+    const key = (0,async_results/* startAsyncCall */.f3)(t.name);
+    const startedAt = Date.now();
+    let settled = false;
+    const timer = setTimeout(()=>{
+        if (settled) return;
+        settled = true;
+        (0,async_results/* failAsyncCall */.zc)(key, `Tool "${t.name}" exceeded its background wall-clock budget of ${deadlineMs}ms. ` + "The underlying operation may still be running but its result is discarded.");
+    }, deadlineMs);
+    timer.unref?.();
+    void (async ()=>{
+        try {
+            const work = t.invoke(innerArgs, config);
+            const result = await work;
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            (0,async_results/* completeAsyncCall */.eN)(key, typeof result === "string" ? result : JSON.stringify(result));
+        } catch (err) {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            (0,async_results/* failAsyncCall */.zc)(key, err);
+        }
+    })();
+    return JSON.stringify({
+        ok: true,
+        async: true,
+        key,
+        tool: t.name,
+        started_at: startedAt,
+        deadline_ms: deadlineMs,
+        hint: `Call tool_result_get with key="${key}" to retrieve the result. Pass wait_ms to short-poll.`
+    });
+}
 /** Exposed for the tests. */ const __DEFAULT_DEADLINE_MS = (/* unused pure expression or super */ null && (DEFAULT_DEADLINE_MS));
 
 ;// ./lib/tools/registry.ts
@@ -1438,6 +1508,147 @@ module.exports = require("next/dist/shared/lib/no-fallback-error.external");
 
 module.exports = require("events");
 
+/***/ }),
+
+/***/ 95579:
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   H0: () => (/* binding */ listAsyncResults),
+/* harmony export */   Ss: () => (/* binding */ getAsyncResult),
+/* harmony export */   eN: () => (/* binding */ completeAsyncCall),
+/* harmony export */   f3: () => (/* binding */ startAsyncCall),
+/* harmony export */   m3: () => (/* binding */ consumeAsyncResult),
+/* harmony export */   zc: () => (/* binding */ failAsyncCall)
+/* harmony export */ });
+/* unused harmony exports DEFAULT_TTL_MS, MAX_ENTRIES, sweepExpired, __resetStore, __backdateFinished */
+/* harmony import */ var node_crypto__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(77598);
+/* harmony import */ var node_crypto__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(node_crypto__WEBPACK_IMPORTED_MODULE_0__);
+// In-process keyed store for async tool results.
+//
+// When the wallclock wrapper sees `async_run: true` on a tool call it
+// returns immediately with a key, kicks the real invocation off in the
+// background, and parks the eventual result here. The agent later
+// retrieves the result via the `tool_result_get` built-in.
+//
+// Scope is deliberately per-process, in-memory:
+//   - The data lives only as long as the Next.js server process. A
+//     restart wipes both the agent's in-context keys and these results
+//     simultaneously, so we can't end up with the LLM holding a key
+//     that survived the value.
+//   - No on-disk persistence means no schema migration, no PII spill,
+//     no risk of leaking long-running secrets between sessions.
+//
+// Memory hygiene:
+//   - TTL (DEFAULT_TTL_MS) caps how long a finished result hangs around
+//     unread. A background sweeper runs on a slow interval.
+//   - Cap on concurrent entries (MAX_ENTRIES). When exceeded, the
+//     oldest *finished* entry is evicted first; if none, the oldest
+//     pending entry is dropped (with a console warn).
+
+/** How long a finished result stays around if nobody reads it. */ const DEFAULT_TTL_MS = 10 * 60 * 1000;
+/** Soft cap on total entries (pending + finished). */ const MAX_ENTRIES = 256;
+/** How often the background sweeper runs. */ const SWEEP_INTERVAL_MS = 60 * 1000;
+const STORE = new Map();
+let sweeper = null;
+function ensureSweeper() {
+    if (sweeper) return;
+    sweeper = setInterval(()=>{
+        sweepExpired(DEFAULT_TTL_MS);
+    }, SWEEP_INTERVAL_MS);
+    sweeper.unref?.();
+}
+/**
+ * Carve out a slot for a new async tool call and return its key.
+ * The key is opaque and URL-safe — the agent treats it as a token.
+ */ function startAsyncCall(tool) {
+    ensureSweeper();
+    enforceCap();
+    const key = `async_${node_crypto__WEBPACK_IMPORTED_MODULE_0___default().randomBytes(8).toString("hex")}`;
+    STORE.set(key, {
+        key,
+        tool,
+        status: "pending",
+        started_at: Date.now(),
+        finished_at: null,
+        result: null,
+        error: null
+    });
+    return key;
+}
+/** Mark a pending call as completed successfully. */ function completeAsyncCall(key, result) {
+    const rec = STORE.get(key);
+    if (!rec) return;
+    rec.status = "done";
+    rec.result = result;
+    rec.finished_at = Date.now();
+}
+/** Mark a pending call as failed. */ function failAsyncCall(key, err) {
+    const rec = STORE.get(key);
+    if (!rec) return;
+    rec.status = "error";
+    rec.error = err instanceof Error ? err.message : String(err);
+    rec.finished_at = Date.now();
+}
+/** Read a record without consuming it. */ function getAsyncResult(key) {
+    return STORE.get(key) ?? null;
+}
+/** Read and immediately delete a record. */ function consumeAsyncResult(key) {
+    const rec = STORE.get(key);
+    if (!rec) return null;
+    STORE.delete(key);
+    return rec;
+}
+/** Snapshot of all current records (newest first). For tool_result_list. */ function listAsyncResults() {
+    return [
+        ...STORE.values()
+    ].sort((a, b)=>b.started_at - a.started_at);
+}
+/**
+ * Drop finished entries older than `ttlMs` (measured from `finished_at`).
+ * Pending entries are never expired here — a stuck tool would otherwise
+ * vanish out from under the agent.
+ */ function sweepExpired(ttlMs) {
+    const now = Date.now();
+    let removed = 0;
+    for (const [k, r] of STORE){
+        if (r.status === "pending") continue;
+        if (r.finished_at == null) continue;
+        if (now - r.finished_at >= ttlMs) {
+            STORE.delete(k);
+            removed++;
+        }
+    }
+    return removed;
+}
+function enforceCap() {
+    if (STORE.size < MAX_ENTRIES) return;
+    // Prefer evicting finished entries (oldest first). Only if every entry
+    // is pending do we drop a pending one.
+    const sorted = [
+        ...STORE.values()
+    ].sort((a, b)=>a.started_at - b.started_at);
+    const finished = sorted.find((r)=>r.status !== "pending");
+    const victim = finished ?? sorted[0];
+    if (!victim) return;
+    STORE.delete(victim.key);
+    if (!finished) {
+        console.warn(`[async-results] evicted pending entry ${victim.key} (tool=${victim.tool}) ` + `to make room — STORE cap of ${MAX_ENTRIES} hit.`);
+    }
+}
+/** Test-only helper. */ function __resetStore() {
+    STORE.clear();
+    if (sweeper) {
+        clearInterval(sweeper);
+        sweeper = null;
+    }
+}
+/** Test-only helper. */ function __backdateFinished(key, finishedAt) {
+    const rec = STORE.get(key);
+    if (rec) rec.finished_at = finishedAt;
+}
+
+
 /***/ })
 
 };