agent.libx.js 0.94.23 → 0.94.25

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { a as AgentOptions, H as Hooks, h as RunResult, A as Agent } from './Agent-DmsB5hzp.js';
-export { C as ChatFragment, D as DEFAULT_MUTATING, b as Decision, P as PermissionOptions, c as PermissionPolicy, d as PermissionRule, e as PreToolUseDecision, R as ReasoningEffort, f as RecordingHooks, g as RecordingLifecycle, T as ToolUse, i as ToolUseMeta, j as composeHooks, p as planMode, r as reasoningToChatFragment } from './Agent-DmsB5hzp.js';
+import { a as AgentOptions, H as Hooks, h as RunResult, A as Agent } from './Agent-BA-rueWn.js';
+export { C as ChatFragment, D as DEFAULT_MUTATING, b as Decision, P as PermissionOptions, c as PermissionPolicy, d as PermissionRule, e as PreToolUseDecision, R as ReasoningEffort, f as RecordingHooks, g as RecordingLifecycle, T as ToolUse, i as ToolUseMeta, j as composeHooks, p as planMode, r as reasoningToChatFragment } from './Agent-BA-rueWn.js';
 import { IFilesystem, FileMetadata } from '@livx.cc/wcli/core';
 export { CommandExecutor, FileMetadata, IFilesystem, IndexedDbFilesystem, MemFilesystem, registerHeadlessCommands } from '@livx.cc/wcli/core';
 import { BodDB } from '@bod.ee/db';
-import { A as AgentTool, C as ChatLike, a as ChatOptions, b as ChatResponse, h as ToolCall, H as HostBridge, U as UserQuestion, e as MessageContent } from './tools-9AUK6SG2.js';
-export { c as ContentPart, d as HostEvent, M as Message, R as Role, S as SandboxJobRegistry, f as StreamChunk, T as TodoItem, g as Tool, i as ToolContext, j as bashTool, k as contentText, l as defaultTools, m as editTool, n as exitSessionTool, o as imagePart, p as makeContext, q as makeJobTools, r as readTool, t as toWireTools, s as todoWriteTool, u as toolRegistry, v as toolsByName } from './tools-9AUK6SG2.js';
-export { M as McpCall, a as McpImage, b as McpRoute, c as McpRouteResolver, d as McpToolResult, e as McpToolSearchOptions, f as McpToolSpec, g as MountedMcpLike, h as buildMcpCatalog, m as makeLazyMcpToolSearch, i as makeMcpToolSearch, j as makeMcpToolSearchFromMounted, k as mcpToolToAgentTool, l as mcpToolsToAgentTools } from './mcp-D00OuccC.js';
+import { A as AgentTool, C as ChatLike, a as ChatOptions, b as ChatResponse, h as ToolCall, H as HostBridge, U as UserQuestion, e as MessageContent } from './tools-DtpN8Agv.js';
+export { c as ContentPart, d as HostEvent, M as Message, R as Role, S as SandboxJobRegistry, f as StreamChunk, T as TodoItem, g as Tool, i as ToolContext, j as bashTool, k as contentText, l as defaultTools, m as editTool, n as exitSessionTool, o as imagePart, p as makeContext, q as makeJobTools, r as readTool, t as toWireTools, s as todoWriteTool, u as toolRegistry, v as toolsByName } from './tools-DtpN8Agv.js';
+export { M as McpCall, a as McpImage, b as McpRoute, c as McpRouteResolver, d as McpToolResult, e as McpToolSearchOptions, f as McpToolSpec, g as MountedMcpLike, h as buildMcpCatalog, m as makeLazyMcpToolSearch, i as makeMcpToolSearch, j as makeMcpToolSearchFromMounted, k as mcpToolToAgentTool, l as mcpToolsToAgentTools } from './mcp-CnzmQ8JE.js';
 import * as libx_js_src_modules_log from 'libx.js/src/modules/log';
 export { log } from 'libx.js/src/modules/log';
 
@@ -25,6 +25,8 @@ declare class NodeDiskFilesystem implements IFilesystem {
     /** Ensure the root dir exists. */
     init(): Promise<void>;
     private real;
+    private verified;
+    private static VERIFY_TTL_MS;
     /** Throw if any existing component of `real` is a symlink (escape vector). */
     private assertNoSymlink;
     resolvePath(path: string, cwd?: string): string;
@@ -384,7 +386,32 @@ declare class Scheduler {
     destroy(): void;
 }
 
-declare function makeScheduleTools(scheduler: Scheduler): AgentTool[];
+/** Narrow seam to an OS-level scheduler backend (jobs that survive quit/reboot). Node hosts wire
+ *  the CLI's `OsScheduler` (launchd/cron/at); absent => everything stays in-process. Edge-safe:
+ *  this module only sees the interface. */
+interface OsBackend {
+    sessionId: string;
+    cwd: string;
+    /** 'os' when the trigger should outlive the session (per hint/heuristic). */
+    route(trigger: Trigger, backendHint?: string): 'session' | 'os';
+    /** Register with the OS. Returns a mechanism description (e.g. 'launchd:…'). Throws on failure. */
+    schedule(spec: {
+        id: string;
+        prompt: string;
+        sessionId: string;
+        cwd: string;
+        trigger: Trigger;
+        label?: string;
+    }): string;
+    cancel(id: string): boolean;
+    list(): Array<{
+        id: string;
+        label?: string;
+        mechanism: string;
+        trigger: Trigger;
+    }>;
+}
+declare function makeScheduleTools(scheduler: Scheduler, os?: OsBackend): AgentTool[];
 
 /** Sandbox mode: an in-memory VFS — the real disk is never read or written. Edge/browser/test/dry-run. */
 declare function sandboxAgentOptions(opts?: Partial<AgentOptions>): Partial<AgentOptions>;
@@ -829,6 +856,9 @@ declare class DuplexAgentOptions {
     askRelay: boolean;
     /** Parked questions auto-resolve empty after this long (callers map '' to deny/best-judgment). */
     askTimeoutMs: number;
+    /** Max retained task records: oldest SETTLED tasks (and their activity tails) are evicted past this,
+     *  bounding memory over a long-lived session. Running tasks are never evicted. */
+    maxTaskRecords: number;
     /** Host overrides for QuickLook lookups (keyed by `what`). The engine's defaults go through the
      *  (possibly jailed) fs — e.g. `.git/**` is deny-listed, so the CLI supplies 'branch' itself. */
     quickLook?: Record<string, (path?: string) => string | Promise<string>>;

package/dist/index.js

@@ -253,12 +253,14 @@ var init_tools_structured = __esm({
         const ctxN = Math.max(0, Number(context ?? 0));
         const out = [];
         const matched = [];
+        let skipped = 0;
         for (const path of files) {
           ckAbort(ctx.signal);
           let content;
           try {
             content = await ctx.fs.readFile(path);
           } catch {
+            skipped++;
             continue;
           }
           const lines = content.split("\n");
@@ -273,8 +275,10 @@ var init_tools_structured = __esm({
           }
           if (fileHit) matched.push(path);
         }
-        if (filesOnly) return matched.length ? matched.join("\n") : "(no matches)";
-        return out.length ? out.join("\n") : "(no matches)";
+        const note = skipped ? `
+[skipped ${skipped} unreadable file${skipped === 1 ? "" : "s"}]` : "";
+        if (filesOnly) return (matched.length ? matched.join("\n") : "(no matches)") + note;
+        return (out.length ? out.join("\n") : "(no matches)") + note;
       }
     };
     SIG_RE = /^\s*(export\b|(?:export\s+)?(?:async\s+)?function\s+\*?\w|(?:export\s+)?(?:abstract\s+)?class\s+\w|(?:export\s+)?interface\s+\w|(?:export\s+)?type\s+\w|(?:export\s+)?enum\s+\w)/;
@@ -963,7 +967,7 @@ var init_tools = __esm({
     IMG_MIME = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" };
     readTool = {
       name: "Read",
-      description: "Read a file. Text files return 1-indexed numbered lines (with optional `offset`/`limit` and a re-Read pointer for partial reads). Image files (png/jpg/jpeg/gif/webp) return the picture itself so you can SEE it. Always Read a file before Editing it.",
+      description: "Read a file. Text files return 1-indexed numbered lines (with optional `offset`/`limit` and a re-Read pointer for partial reads). Image files (png/jpg/jpeg/gif/webp) return the picture itself so you can SEE it. PDFs return their extracted text. Always Read a file before Editing it.",
       parameters: {
         type: "object",
         required: ["path"],
@@ -975,6 +979,12 @@ var init_tools = __esm({
       },
       async run({ path, offset, limit }, ctx) {
         const ext = String(path).toLowerCase().split(".").pop() ?? "";
+        if (ext === "pdf") {
+          if (!ctx.pdfText) return `[${path} is a PDF \u2014 text extraction isn't available in this environment (install poppler's pdftotext and run on disk).]`;
+          if (!await ctx.fs.exists(path)) return `Error: File not found: ${path}`;
+          const text = (await ctx.pdfText(ctx.fs.resolvePath(path))).trim();
+          return text ? numberLines(text, Math.max(0, offset ?? 0), limit) : `[${path}: no extractable text (scanned/image-only PDF?)]`;
+        }
         if (IMG_MIME[ext]) {
           const fs = ctx.fs;
           if (typeof fs.readFileBytes !== "function") {
@@ -1052,7 +1062,7 @@ var NodeDiskFilesystem;
 var init_NodeDiskFilesystem = __esm({
   "src/NodeDiskFilesystem.ts"() {
     "use strict";
-    NodeDiskFilesystem = class {
+    NodeDiskFilesystem = class _NodeDiskFilesystem {
       constructor(baseDir, opts = {}) {
         this.baseDir = baseDir;
         this.opts = { denySymlinks: true, ...opts };
@@ -1067,14 +1077,24 @@ var init_NodeDiskFilesystem = __esm({
       real(vpath) {
         return np.join(this.baseDir, "." + vpath);
       }
+      // Verified non-symlink DIRECTORY components, with a short TTL: tree walks (Glob/Grep) hit the same
+      // parents thousands of times; re-lstat'ing each per op is the dominant syscall cost. The 1s window
+      // is an accepted race only against an out-of-band symlink swap mid-walk (this FS can't create
+      // symlinks itself); leaf components are never cached.
+      verified = /* @__PURE__ */ new Map();
+      static VERIFY_TTL_MS = 1e3;
       /** Throw if any existing component of `real` is a symlink (escape vector). */
       async assertNoSymlink(real) {
         if (!this.opts.denySymlinks) return;
         const rel = np.relative(this.baseDir, real);
         if (rel === "" || rel.startsWith("..")) return;
+        const parts = rel.split(np.sep);
         let cur = this.baseDir;
-        for (const part of rel.split(np.sep)) {
-          cur = np.join(cur, part);
+        const now4 = Date.now();
+        for (let i = 0; i < parts.length; i++) {
+          cur = np.join(cur, parts[i]);
+          const isLeaf = i === parts.length - 1;
+          if (!isLeaf && (this.verified.get(cur) ?? 0) > now4) continue;
           let st;
           try {
             st = await fsp.lstat(cur);
@@ -1082,6 +1102,10 @@ var init_NodeDiskFilesystem = __esm({
             return;
           }
           if (st.isSymbolicLink()) throw new Error("File not found: symlink not permitted");
+          if (!isLeaf) {
+            if (this.verified.size > 1e4) this.verified.clear();
+            this.verified.set(cur, now4 + _NodeDiskFilesystem.VERIFY_TTL_MS);
+          }
         }
       }
       resolvePath(path, cwd) {
@@ -1446,6 +1470,15 @@ __export(tools_shell_exports, {
   makeRealShellTool: () => makeRealShellTool,
   makeShellJobTools: () => makeShellJobTools
 });
+function killGroup(proc, signal) {
+  if (!proc?.pid) return false;
+  try {
+    process.kill(-proc.pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function spawnArgvFor(command, cwd, osSandbox) {
   if (!osSandbox) return { bin: "/bin/sh", args: ["-c", command] };
   const opts = osSandbox === true ? {} : osSandbox;
@@ -1468,7 +1501,7 @@ function makeRealShellTool(options) {
   const timeoutMs = options.timeoutMs ?? 12e4;
   return {
     name: "Shell",
-    description: "Run a shell command via /bin/sh in the working directory. Executes any installed binary \u2014 ls, cat, grep, git, bun, node, curl, scripts, etc. Returns combined stdout+stderr; non-zero exits are prefixed `[exit N]`. Set `background:true` for long-running processes (servers, watchers) \u2014 returns a job id immediately; poll with ShellOutput, stop with ShellKill.",
+    description: "Run a shell command via /bin/sh in the working directory. Executes any installed binary \u2014 ls, cat, grep, git, bun, node, curl, scripts, etc. Returns combined stdout+stderr; non-zero exits are prefixed `[exit N]`. Runs non-interactively with no terminal (stdin is /dev/null): commands that prompt for input fail fast rather than hang \u2014 for privileged actions use a non-interactive flag (e.g. `sudo -n`), or ask the user to run the command themselves. Set `background:true` for long-running processes (servers, watchers) \u2014 returns a job id immediately; poll with ShellOutput, stop with ShellKill.",
     parameters: {
       type: "object",
       required: ["command"],
@@ -1528,10 +1561,12 @@ function makeRealShellTool(options) {
           };
           let proc;
           try {
-            proc = spawn(argv.bin, argv.args, { cwd: options.cwd, env: childEnv(options), signal: ctl.signal });
+            proc = spawn(argv.bin, argv.args, { cwd: options.cwd, env: childEnv(options), signal: ctl.signal, ...DETACHED });
           } catch (e) {
             return finish(`[exit 1] failed to spawn shell: ${e?.message ?? e}`);
           }
+          if (ctl.signal.aborted) killGroup(proc, "SIGKILL");
+          else ctl.signal.addEventListener("abort", () => killGroup(proc, "SIGKILL"), { once: true });
           const collect = (chunk) => {
             const s = typeof chunk === "string" ? chunk : chunk?.toString?.("utf8") ?? "";
             out += s;
@@ -1607,7 +1642,7 @@ ${clean(out) || "(no output yet)"}`;
     }
   ];
 }
-var log4, clean, SECRET_ENV_RE, _spawn, ShellJobRegistry, NO_JOB2;
+var log4, clean, DETACHED, SECRET_ENV_RE, _spawn, ShellJobRegistry, NO_JOB2;
 var init_tools_shell = __esm({
   "src/tools.shell.ts"() {
     "use strict";
@@ -1617,6 +1652,7 @@ var init_tools_shell = __esm({
     init_shell_sandbox();
     log4 = forComponent("shell");
     clean = (s) => truncateOutput(redactSecrets(s.replace(/\n+$/, "")));
+    DETACHED = { stdio: ["ignore", "pipe", "pipe"], detached: true };
     SECRET_ENV_RE = /(_API_KEY|_TOKEN|_SECRET|_PASSWORD|_PRIVATE_KEY|^AWS_|^GITHUB_TOKEN$|^OPENAI_|^ANTHROPIC_|^GOOGLE_|^GEMINI_|^GROQ_|^NPM_TOKEN$)/i;
     ShellJobRegistry = class {
       constructor(cfg) {
@@ -1637,7 +1673,7 @@ var init_tools_shell = __esm({
         try {
           const spawn = this.cfg.spawn ?? await nodeSpawn();
           const argv = this.cfg.osSandbox ? await spawnArgvFor(command, this.cfg.cwd, this.cfg.osSandbox) : { bin: "/bin/sh", args: ["-c", command] };
-          const proc = spawn(argv.bin, argv.args, { cwd: this.cfg.cwd, env: childEnv(this.cfg) });
+          const proc = spawn(argv.bin, argv.args, { cwd: this.cfg.cwd, env: childEnv(this.cfg), ...DETACHED });
           job.proc = proc;
           proc.stdout?.on("data", append);
           proc.stderr?.on("data", append);
@@ -1676,9 +1712,11 @@ var init_tools_shell = __esm({
         const j = this.jobs.get(id);
         if (!j) return false;
         if (j.status === "running") {
-          try {
-            j.proc?.kill("SIGTERM");
-          } catch {
+          if (!killGroup(j.proc, "SIGTERM")) {
+            try {
+              j.proc?.kill("SIGTERM");
+            } catch {
+            }
           }
           j.status = "killed";
         }
@@ -2835,6 +2873,8 @@ var AgentOptions = class {
   permissions;
   /** Opt-in syntax guardrail: refuse to persist a syntactically-broken code-file write/edit. Default off. */
   lintOnWrite;
+  /** Optional PDF text extraction for Read on .pdf files (node hosts wire pdftotext); absent => Read explains. */
+  pdfText;
   /** Opt-in: after a write-class tool runs, run `command` over the VFS and append any failure to the tool result.
    *  `tools` defaults to ['Write','Edit','MultiEdit','ApplyEdits']. */
   autoTest;
@@ -2885,8 +2925,12 @@ var Agent = class _Agent {
   reprepare() {
     this.prepared = false;
   }
-  /** Inject tools into a running agent (e.g. dynamically mounted MCP servers). Takes effect on the next turn. */
+  /** Tools injected via addTools(); kept separate from options.tools so prepare() rebuilds don't drop them. */
+  injectedTools = [];
+  /** Inject tools into a running agent (e.g. dynamically mounted MCP servers). Takes effect on the next turn
+   *  and survives prepare() rebuilds (reprepare(), new conversations). */
   addTools(tools) {
+    this.injectedTools.push(...tools);
     this.activeTools.push(...tools);
   }
   /** Remove tools by name from a running agent. Returns the count removed. */
@@ -2894,6 +2938,7 @@ var Agent = class _Agent {
     const s = names instanceof Set ? names : new Set(names);
     const before = this.activeTools.length;
     this.activeTools = this.activeTools.filter((t) => !s.has(t.name));
+    this.injectedTools = this.injectedTools.filter((t) => !s.has(t.name));
     return before - this.activeTools.length;
   }
   constructor(options) {
@@ -2905,6 +2950,7 @@ var Agent = class _Agent {
     this.ctx = makeContext(this.options.fs, this.options.host);
     this.ctx.signal = this.options.signal;
     if (this.options.lintOnWrite) this.ctx.lint = checkSyntax;
+    if (this.options.pdfText) this.ctx.pdfText = this.options.pdfText;
     this.ctx.ai = this.options.ai;
     this.ctx.model = this.options.model;
     this.ctx.parkHuman = (p) => this.park(p);
@@ -2977,7 +3023,7 @@ var Agent = class _Agent {
     const plan = o.planMode ? planMode({ host: o.host }) : void 0;
     if (plan) tools = [...tools, plan.tool];
     this.activeHooks = composeHooks(o.hooks, plan?.hooks, o.permissions?.hooks());
-    this.activeTools = tools;
+    this.activeTools = [...tools, ...this.injectedTools];
     this.systemPromptCache = systemPrompt;
     this.prepared = true;
     return systemPrompt;
@@ -3112,7 +3158,15 @@ var Agent = class _Agent {
       } catch (err) {
         if (err?.code === "budget") return kill("budget");
         if (o.signal?.aborted || isAbortError(err)) return kill("aborted");
-        log3.error(`chat() failed: ${err?.message ?? err}`, err);
+        const body = err?.body ?? err?.response?.data ?? err?.error;
+        let bodyStr;
+        try {
+          bodyStr = body && typeof body !== "string" ? JSON.stringify(body).slice(0, 2e3) : body;
+        } catch {
+          bodyStr = void 0;
+        }
+        if (bodyStr && err instanceof Error && !err.message.includes(bodyStr)) err.detail = bodyStr;
+        log3.error(`chat() failed: ${err?.message ?? err}${bodyStr ? ` \u2014 ${bodyStr}` : ""}`, err);
         return { text: "", steps, finishReason: "error", messages: this.transcript, usage, usageEstimated, error: err };
       }
       if (o.signal?.aborted) return kill("aborted");
@@ -3343,20 +3397,28 @@ function stubOldToolResults(messages, keep) {
     return { ...x, content: `[${x.name ?? "tool"}${where ? ` ${where}` : ""} output elided \u2014 ${lines} lines; re-run the tool to view]` };
   });
 }
-var hasCallFor = (msgs, id) => msgs.some((m) => m.role === "assistant" && m.tool_calls?.some((tc) => tc.id === id));
+var callIdSet = (msgs) => {
+  const ids = /* @__PURE__ */ new Set();
+  for (const m of msgs) if (m.role === "assistant") for (const tc of m.tool_calls ?? []) ids.add(tc.id);
+  return ids;
+};
 function dropOrphanToolResults(messages) {
-  const ok = (m) => m.role !== "tool" || hasCallFor(messages, m.tool_call_id);
+  const ids = callIdSet(messages);
+  const ok = (m) => m.role !== "tool" || ids.has(m.tool_call_id ?? "");
   return messages.every(ok) ? messages : messages.filter(ok);
 }
 function fitTokenBudget(messages, maxTokens) {
-  if (estimateTokens(messages) <= maxTokens) return messages;
+  const per = messages.map((x) => estimateTokens([x]));
+  let total = per.reduce((a, b) => a + b, 0);
+  if (total <= maxTokens) return messages;
   const head = messages[0]?.role === "system" ? [messages[0]] : [];
-  let body = messages.slice(head.length);
-  while (body.length && estimateTokens([...head, ...body]) > maxTokens) body = body.slice(1);
-  while (body.length && body[0].role === "tool" && !hasCallFor(body, body[0].tool_call_id)) body = body.slice(1);
-  if (estimateTokens([...head, ...body]) > maxTokens)
-    log3.warn(`context ~${estimateTokens([...head, ...body])} tok still over maxContextTokens=${maxTokens} after trimming (system head can't be dropped)`);
-  return [...head, ...body];
+  let from = head.length;
+  while (from < messages.length && total > maxTokens) total -= per[from++];
+  const ids = callIdSet(messages.slice(from));
+  while (from < messages.length && messages[from].role === "tool" && !ids.has(messages[from].tool_call_id ?? "")) total -= per[from++];
+  if (total > maxTokens)
+    log3.warn(`context ~${total} tok still over maxContextTokens=${maxTokens} after trimming (system head can't be dropped)`);
+  return [...head, ...messages.slice(from)];
 }
 function compact(m, max, focus) {
   const hasSystem = m[0]?.role === "system";
@@ -3899,11 +3961,11 @@ var Scheduler = class {
     this.jobs.clear();
   }
 };
-function makeScheduleTools(scheduler) {
+function makeScheduleTools(scheduler, os) {
   return [
     {
       name: "ScheduleTask",
-      description: 'Schedule a prompt to fire automatically while this session is alive.\nModes:\n  \u2022 One-off:   {at: <epoch_ms>}        \u2014 fires once at that time, then done.\n  \u2022 Interval:  {everyMs: <ms>}          \u2014 fires repeatedly (\u22651s).\n  \u2022 Cron:      {cron: "min hr dom mon dow"} \u2014 standard 5-field cron.\nReturns the job id. Jobs only fire while the CLI session is running \u2014 they do NOT survive quitting.',
+      description: 'Schedule a prompt to fire automatically.\nModes:\n  \u2022 One-off:   {at: <epoch_ms>}        \u2014 fires once at that time, then done.\n  \u2022 Interval:  {everyMs: <ms>}          \u2014 fires repeatedly (\u22651s).\n  \u2022 Cron:      {cron: "min hr dom mon dow"} \u2014 standard 5-field cron.\nBackend: "session" fires while this CLI session is alive (default for recurring + near one-offs); "os" registers with the OS scheduler so the job survives quitting \u2014 it headless-resumes this session when it fires (auto-chosen for one-offs \u226530min out when available). Pass backend:"os" explicitly for recurring jobs that must outlive the session.',
       parameters: {
         type: "object",
         required: ["prompt", "trigger"],
@@ -3918,15 +3980,22 @@ function makeScheduleTools(scheduler) {
               cron: { type: "string" }
             }
           },
-          label: { type: "string", description: "Short label for display (optional)." }
+          label: { type: "string", description: "Short label for display (optional)." },
+          backend: { type: "string", enum: ["auto", "session", "os"], description: "Where the job lives (default auto)." }
         }
       },
-      async run({ prompt, trigger, label }) {
+      async run({ prompt, trigger, label, backend }) {
         try {
+          if (os && os.route(trigger, backend) === "os") {
+            const id2 = `os-${Date.now().toString(36)}`;
+            const mechanism = os.schedule({ id: id2, prompt, sessionId: os.sessionId, cwd: os.cwd, trigger, label });
+            return `Scheduled ${id2}${label ? ` (${label})` : ""} on the OS scheduler (${mechanism}) \u2014 survives quitting; fires \`agentx --resume ${os.sessionId}\` headless.`;
+          }
+          if (backend === "os") return "Error: no OS scheduler available on this platform \u2014 job not created (use the default in-session backend).";
           const id = scheduler.add({ prompt, trigger, label });
           const job = scheduler.get(id);
           const next = scheduler.nextFire(job);
-          return `Scheduled ${id}${label ? ` (${label})` : ""}. Next fire: ${next ? new Date(next).toLocaleString() : "now"}.`;
+          return `Scheduled ${id}${label ? ` (${label})` : ""}. Next fire: ${next ? new Date(next).toLocaleString() : "now"}. (In-session: does not survive quitting.)`;
         } catch (e) {
           return `Error: ${e?.message ?? e}`;
         }
@@ -3934,24 +4003,28 @@ function makeScheduleTools(scheduler) {
     },
     {
       name: "ScheduleList",
-      description: "List all scheduled jobs and their next fire time.",
+      description: "List all scheduled jobs (in-session + OS-backed) and their next fire time.",
       parameters: { type: "object", properties: {} },
       async run() {
+        const osJobs = os?.list() ?? [];
+        const osLines = osJobs.map((j) => `${j.id}  os  ${j.mechanism}${j.label ? "  " + j.label : ""}`);
         const jobs = scheduler.list();
-        if (!jobs.length) return "(no scheduled jobs)";
-        return jobs.map((j) => {
+        if (!jobs.length && !osLines.length) return "(no scheduled jobs)";
+        return [...osLines, ...jobs.map((j) => {
           const next = scheduler.nextFire(j);
           const trig = "at" in j.trigger ? `once @ ${new Date(j.trigger.at).toLocaleString()}` : "everyMs" in j.trigger ? `every ${(j.trigger.everyMs / 1e3).toFixed(0)}s` : `cron: ${j.trigger.cron}`;
           return `${j.id}  ${j.status}  ${trig}  runs:${j.runs}  next:${next ? new Date(next).toLocaleTimeString() : "\u2014"}${j.label ? "  " + j.label : ""}`;
-        }).join("\n");
+        })].join("\n");
       }
     },
     {
       name: "ScheduleCancel",
-      description: "Cancel a scheduled job by id.",
+      description: "Cancel a scheduled job by id (in-session or OS-backed).",
       parameters: { type: "object", required: ["id"], properties: { id: { type: "string" } } },
       async run({ id }) {
-        return scheduler.cancel(String(id)) ? `Cancelled ${id}.` : `Error: no scheduled job '${id}'. Use ScheduleList to see jobs.`;
+        const key = String(id);
+        if (key.startsWith("os-")) return os?.cancel(key) ? `Cancelled ${key} (OS job removed).` : `Error: no OS job '${key}'.`;
+        return scheduler.cancel(key) ? `Cancelled ${key}.` : `Error: no scheduled job '${key}'. Use ScheduleList to see jobs.`;
       }
     },
     {
@@ -4262,6 +4335,9 @@ var DuplexAgentOptions = class {
   askRelay = false;
   /** Parked questions auto-resolve empty after this long (callers map '' to deny/best-judgment). */
   askTimeoutMs = 12e4;
+  /** Max retained task records: oldest SETTLED tasks (and their activity tails) are evicted past this,
+   *  bounding memory over a long-lived session. Running tasks are never evicted. */
+  maxTaskRecords = 50;
   /** Host overrides for QuickLook lookups (keyed by `what`). The engine's defaults go through the
    *  (possibly jailed) fs — e.g. `.git/**` is deny-listed, so the CLI supplies 'branch' itself. */
   quickLook;
@@ -4552,6 +4628,11 @@ ${recent}` : brief) + verify;
     };
     const promise = new Agent(agentOpts).run(briefText).then((res) => this.maybeVerify(id, briefText, res, tier, agentOpts)).then((res) => this.onWorkerSettled(id, res)).catch((err) => this.onWorkerFailed(id, err));
     this.tasks.set(id, { id, label, status: "running", controller, promise, tail });
+    if (this.tasks.size > this.options.maxTaskRecords)
+      for (const [tid, rec] of this.tasks) {
+        if (this.tasks.size <= this.options.maxTaskRecords) break;
+        if (rec.status !== "running") this.tasks.delete(tid);
+      }
   }
   /** Fresh-context check of a successful Act task: a NEW agent (same model/fs/tools, but NO shared
    *  conversation context) re-reads the file state against the brief and fixes any gap. The fix lands