nolo-cli 0.38.0-alpha.3 → 0.47.0-alpha.2

package/{chunk-VOXNBPLB.js → chunk-MUIJYGYW.js}

@@ -7,7 +7,7 @@ import {
   providerHttpFailure,
   readSseFrames,
   throwIfChatCompletionStreamFailed
-} from "./chunk-MZZZYUZS.js";
+} from "./chunk-AV2CELZZ.js";
 import {
   FRESH_TOOL_OUTPUT_MAX_CHARS,
   MAX_HISTORICAL_TOOL_CONTENT_CHARS,
@@ -17,17 +17,10 @@ import {
   resolveHistoricalToolContentCap,
   resolveToolOutputProfile,
   stripImagePartsFromMessages
-} from "./chunk-64KIQZA2.js";
+} from "./chunk-XO3G35OV.js";
 import {
   sanitizeForOutbound
 } from "./chunk-T27IEBNQ.js";
-import {
-  EMPTY_ASSISTANT_REPAIR_PROMPT,
-  formatLengthTruncatedReasoningTail,
-  hasAssistantVisibleOutput,
-  resolveEmptyAssistantFallbackMessage,
-  resolveEmptyAssistantOutcome
-} from "./chunk-P66M7LSQ.js";
 import {
   createThinkParserState,
   createToolCallAccumulator,
@@ -39,10 +32,11 @@ import {
   buildCurrentTimeBlock,
   buildIdentityBlock,
   buildRuntimeGuidanceBlocks,
+  normalizeChatCompletionsBodyForProvider,
   requiresBareImageUrl,
   resolveToolGuidedSections,
   toBareImageUrlMessages
-} from "./chunk-T2BZICLK.js";
+} from "./chunk-G46DB6KG.js";
 import {
   convertMessagesToResponsesInput,
   extractReasoningFromResponseOutput,
@@ -52,11 +46,11 @@ import {
   shouldStripReasoningContentForOutbound,
   toOpenAiCompatibleMessages,
   toResponsesTools
-} from "./chunk-BMB563Y6.js";
+} from "./chunk-6BYAXNH5.js";
 import {
   buildProviderAuthHeaders,
   buildProviderExecutionPlan
-} from "./chunk-GKHV4UH5.js";
+} from "./chunk-5UOBIU5G.js";
 import {
   NOLO_WORKSPACE_TOOL_NAMES,
   buildNoloWorkspaceCommandArgs,
@@ -64,13 +58,18 @@ import {
   noloStringArg,
   parseNoloWorkspaceToolArguments,
   resolveNoloDialogInput
-} from "./chunk-IZCHPD7T.js";
+} from "./chunk-TNPCQNGQ.js";
 import {
   buildDialogFallbackTitleFromUserInput
 } from "./chunk-2MBTWINN.js";
 import {
-  getModelContextWindow
-} from "./chunk-WRP5TTM6.js";
+  EMPTY_ASSISTANT_REPAIR_PROMPT,
+  getModelContextWindow,
+  hasAssistantVisibleOutput,
+  resolveEmptyAssistantFallbackMessage,
+  resolveEmptyAssistantOutcome,
+  resolveTruncatedReasoningTailLog
+} from "./chunk-4MXGXSYN.js";
 import {
   COMPACTION_SUMMARY_SCHEMA_VERSION,
   COMPACTION_SUMMARY_SYSTEM_PROMPT,
@@ -84,7 +83,7 @@ import {
   formatMessagesForSummaryWithTruncation,
   planCompression,
   planContextUsage
-} from "./chunk-FGLKRJDI.js";
+} from "./chunk-GK74OOFT.js";
 import {
   resolveNoloStateDir
 } from "./chunk-FD36SCCD.js";
@@ -107,13 +106,13 @@ import {
 import {
   dialogMessageKey,
   dialogMessageRange
-} from "./chunk-2WKUUY2E.js";
-import {
-  asTrimmedNonEmptyStringArray
-} from "./chunk-I42VC5KR.js";
+} from "./chunk-SVEUG45B.js";
 import {
   asOptionalFiniteNumber
 } from "./chunk-WWC7I6TA.js";
+import {
+  asTrimmedNonEmptyStringArray
+} from "./chunk-I42VC5KR.js";
 import {
   asTrimmedLowercaseString
 } from "./chunk-QSJ3HFEF.js";
@@ -447,6 +446,15 @@ function spillToolOutput(options) {
     hash
   };
 }
+function formatToolOverflowMarker(args) {
+  const { spillRef, totalChars, totalLines, omittedChars } = args;
+  const omittedNote = omittedChars !== void 0 && omittedChars > 0 ? ` omitted: ${omittedChars} chars;` : "";
+  return `
+
+[TOOL-OVERFLOW: full output spilled to ${spillRef} (total: ${totalChars} chars, ${totalLines} lines;${omittedNote} inspect via readFile or grep)]
+
+`;
+}
 
 // packages/agent-runtime/localAutoCompaction.ts
 import { createHash as createHash2 } from "node:crypto";
@@ -1770,22 +1778,32 @@ async function runLocalAgentTurn(input) {
           if (!!result.reasoning_content) reasoningEmptyRepairCount += 1;
           continue;
         }
+        if (outcome.kind === "ok_with_warning") {
+          result = {
+            ...result,
+            errorMessage: resolveEmptyAssistantFallbackMessage(outcome.reason),
+            emptyAssistantFallbackReason: outcome.reason,
+            emptyAssistantRepairUsed
+          };
+          break;
+        }
         if (outcome.kind === "fallback") {
-          if (outcome.reason === "length_truncated" && result.reasoning_content) {
-            const reasoningTailLog = formatLengthTruncatedReasoningTail(result.reasoning_content);
-            if (reasoningTailLog) {
-              console.warn(`
+          const reasoningTailLog = resolveTruncatedReasoningTailLog(outcome.reason, result.reasoning_content);
+          if (reasoningTailLog) {
+            console.warn(`
 ${reasoningTailLog}
 `);
-            }
           }
+          const fallbackMessage = resolveEmptyAssistantFallbackMessage(outcome.reason);
           result = {
             ...result,
-            content: resolveEmptyAssistantFallbackMessage(outcome.reason),
+            content: fallbackMessage,
             // 只打标记不抛错：交互侧仍照常显示诊断文案（零行为变化）。
             // 上层（后台 run 编排者）据 emptyAssistantFallbackReason 判断
             // 是否把本轮结算为 failed。见 LocalAgentTurnResult 注释。
-            emptyAssistantFallbackReason: outcome.reason
+            errorMessage: fallbackMessage,
+            emptyAssistantFallbackReason: outcome.reason,
+            emptyAssistantRepairUsed
           };
           break;
         }
@@ -2009,12 +2027,17 @@ ${reasoningTailLog}
   }
   result = result;
   if (!skipFinalAppend) {
+    const truncatedReasoningTailLog = resolveTruncatedReasoningTailLog(
+      result.emptyAssistantFallbackReason,
+      result.reasoning_content
+    );
     messages.push({
       role: "assistant",
       content: result.content,
       // 与中间轮(:561)一致带上 reasoning_content,让 saveTurn 持久化思维链,
       // 空轮/异常排查时能回看模型实际想了什么。
-      ...result.reasoning_content ? { reasoning_content: result.reasoning_content } : {}
+      ...result.reasoning_content ? { reasoning_content: result.reasoning_content } : {},
+      ...truncatedReasoningTailLog ? { thinkContent: truncatedReasoningTailLog } : {}
     });
   }
   const turnMessages = applyPersistedTurnInput(
@@ -2105,7 +2128,12 @@ function buildResponsesRequestBody(body, model) {
     messages: void 0,
     max_tokens: void 0,
     reasoning_effort: void 0,
-    tool_choice: void 0
+    tool_choice: void 0,
+    // stream_options 是 chat.completions 专属参数；客户端按 chat 线构建的 body
+    // 携带它（旧版本 runtime 或 wire 分流窗口期）经此处转 Responses 上游时必须
+    // 剥离，否则 OpenAI 直接 400 Unknown parameter: 'stream_options.include_usage'。
+    // Responses 线天然在流末返回 usage，无需 include_usage。
+    stream_options: void 0
   };
 }
 
@@ -2276,9 +2304,13 @@ function buildOpenAiCompatibleChatCompletionRequest(args) {
     stream: args.stream ?? false,
     ...args.providerConfig.requestOptions,
     ...args.tools && args.tools.length > 0 ? { tools: args.tools } : {},
-    ...!isResponses && args.stream ? getUsageRequestOptions(args.providerConfig.provider, { api: "chat-completions" }) : {}
+    ...!isResponses && args.stream ? getUsageRequestOptions(args.providerConfig.usageProvider ?? args.providerConfig.provider, { api: "chat-completions" }) : {}
   };
-  const body = isResponses ? buildResponsesRequestBody(rawBody, args.providerConfig.model) : rawBody;
+  const body = isResponses ? buildResponsesRequestBody(rawBody, args.providerConfig.model) : normalizeChatCompletionsBodyForProvider({
+    body: rawBody,
+    provider: args.providerConfig.provider,
+    model: args.providerConfig.model
+  });
   const endpoint = args.providerConfig.endpoint;
   const headers = {
     "Content-Type": "application/json",
@@ -2342,6 +2374,11 @@ function parseOpenAiCompatibleChatCompletionResponse(args) {
 }
 function processOpenAiCompatibleSseEvent(event, state) {
   for (const line of event.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("data:") && trimmed.slice(5).trim() === "[DONE]") {
+      state.sawDone = true;
+      continue;
+    }
     const parsed = parseSseDataLineJson(line);
     if (parsed == null) continue;
     applyChatCompletionDelta(parsed, state);
@@ -2356,7 +2393,8 @@ async function readOpenAiCompatibleSseCompletion(args) {
     thinkState: createThinkParserState(),
     toolCallTextState: createToolCallTextParserState(),
     onTextDelta: args.onTextDelta,
-    onReasoningDelta: args.onReasoningDelta
+    onReasoningDelta: args.onReasoningDelta,
+    sawDone: false
   };
   for await (const frame of readSseFrames(args.response)) {
     processOpenAiCompatibleSseEvent(frame, state);
@@ -2364,11 +2402,13 @@ async function readOpenAiCompatibleSseCompletion(args) {
   flushChatCompletionStream(state);
   throwIfChatCompletionStreamFailed(state);
   const tool_calls = finalizeAccumulatedToolCalls(state.accumulatedToolCalls);
+  const streamComplete = state.sawDone || !!state.usage || !!state.finishReason;
   return {
     content: state.content,
     ...state.reasoning ? { reasoning_content: state.reasoning } : {},
     ...tool_calls.length > 0 ? { tool_calls } : {},
-    ...state.usage ? { usage: state.usage, stream_complete: true } : {},
+    ...state.usage ? { usage: state.usage } : {},
+    ...streamComplete ? { stream_complete: true } : {},
     ...state.finishReason ? { finish_reason: state.finishReason } : {}
   };
 }
@@ -2493,7 +2533,8 @@ async function resolveOpenAiCompatibleProviderConfig(args) {
     apiKey: plan.apiKey,
     ...plan.apiKeyHeader ? { apiKeyHeader: plan.apiKeyHeader } : {},
     provider: plan.provider,
-    requestOptions: plan.requestOptions
+    requestOptions: plan.requestOptions,
+    ...plan.usageProvider ? { usageProvider: plan.usageProvider } : {}
   };
 }
 
@@ -2753,6 +2794,9 @@ function buildDialogMessageWriteOps(args) {
         // 持久化思维链(reasoning):空轮/异常排查的关键证据,
         // 回读由 dialogMessageRecordToAgentRuntimeMessage 还原。
         ...typeof message.reasoning_content === "string" ? { reasoning_content: message.reasoning_content } : {},
+        // web 思考折叠可读的截断 reasoning 尾部（带 marker）。仅在截断
+        // 兜底/告警轮由 localLoop 附加，正常轮无此字段。
+        ...typeof message.thinkContent === "string" ? { thinkContent: message.thinkContent } : {},
         ...message.role === "user" ? { userId: args.userId } : {},
         ...message.role === "assistant" ? {
           agentKey: args.input.agentKey,
@@ -2767,6 +2811,20 @@ function buildDialogMessageWriteOps(args) {
     };
   });
 }
+function buildEmptyAssistantWoundFields(result, existingDialog) {
+  const reason = result.emptyAssistantFallbackReason;
+  if (reason) {
+    return {
+      ...result.errorMessage ? { errorMessage: result.errorMessage } : {},
+      fallbackReason: reason,
+      ...typeof result.emptyAssistantRepairUsed === "boolean" ? { repairUsed: result.emptyAssistantRepairUsed } : {}
+    };
+  }
+  if (existingDialog?.fallbackReason || existingDialog?.errorMessage) {
+    return { errorMessage: null, fallbackReason: null, repairUsed: null };
+  }
+  return {};
+}
 function buildRuntimeCheckpointField(args) {
   if (args.runtimeToolSurface) {
     return {
@@ -2806,6 +2864,10 @@ function buildAgentRuntimeDialogWritePlan(args) {
   const titleChanged = typeof args.titleOverride === "string" && args.titleOverride.trim().length > 0;
   const titleUpdatedAtIso = titleChanged ? nowIso : existingTitleUpdatedAtMs > 0 ? new Date(existingTitleUpdatedAtMs).toISOString() : args.existingDialog?.createdAt ?? nowIso;
   const { availableToolNames: _deprecatedAvailableToolNames, ...cleanExistingCheckpoint } = asRecordOrEmpty(args.existingDialog?.runtimeCheckpoint);
+  const woundFields = buildEmptyAssistantWoundFields(
+    args.input.result,
+    args.existingDialog
+  );
   const dialogRecord = {
     ...asRecordOrEmpty(args.existingDialog),
     id: dialogId,
@@ -2817,6 +2879,7 @@ function buildAgentRuntimeDialogWritePlan(args) {
     titleSource: pickedTitle.titleSource,
     titleUpdatedAt: titleUpdatedAtIso,
     status: args.input.result.error === true ? "failed" : "done",
+    ...woundFields,
     triggerType: `${args.runtimeHost}-local`,
     executionMode: args.existingDialog?.executionMode ?? "foreground",
     createdAt: args.existingDialog?.createdAt ?? nowIso,
@@ -3294,6 +3357,13 @@ var DEFAULT_LOCAL_TOOLS = /* @__PURE__ */ new Set([
   "execShell",
   "launchProcess",
   "listProcesses",
+  // ProcessTask follow-up tools (Phase 1). Same tier as listProcesses: they
+  // observe/stop tasks the agent itself already spawned, so their blast radius
+  // is strictly narrower than launchProcess (which is default-enabled).
+  "taskWait",
+  "taskLogs",
+  "taskStop",
+  "tasks",
   // Scheduling tools: forking/observing sub-agents is a declared capability
   // of capable agents, and the blast radius is strictly narrower than
   // execShell (already default-enabled). Requiring an env allowlist for these
@@ -3609,10 +3679,44 @@ function spawnToWebStreams(options) {
 }
 
 // packages/agent-runtime/processTask.ts
+var PROCESS_TASK_TERMINAL_STATUSES = [
+  "stopped",
+  "exited",
+  "failed"
+];
+function isProcessTaskTerminalStatus(status) {
+  return typeof status === "string" && PROCESS_TASK_TERMINAL_STATUSES.includes(status);
+}
+function reportedTaskStatus(source, exitCode) {
+  if (source === "killed") {
+    return "stopped";
+  }
+  if (source === "exited") {
+    return exitCode !== void 0 && exitCode !== 0 ? "failed" : "exited";
+  }
+  if (source === "started" || source === "promoted") {
+    return "running";
+  }
+  return source;
+}
+var DEFAULT_TASK_EVENT_RETENTION_MS = 5 * 60 * 1e3;
+var DEFAULT_MAX_TASK_EVENTS_TASKS = 200;
 var ProcessTaskEventLog = class {
   events = /* @__PURE__ */ new Map();
+  terminalTasks = /* @__PURE__ */ new Map();
+  retentionMs;
+  maxTasks;
+  now;
+  evictedCount = 0;
+  activeOverflowCount = 0;
+  constructor(options) {
+    this.retentionMs = options?.retentionMs ?? DEFAULT_TASK_EVENT_RETENTION_MS;
+    this.maxTasks = options?.maxTasks ?? DEFAULT_MAX_TASK_EVENTS_TASKS;
+    this.now = options?.now ?? Date.now;
+  }
   /** Append one event; assigns the next monotonic seq for the task. */
   append(input) {
+    const currentTime = this.now();
     const list = this.events.get(input.taskId) ?? [];
     const lastSeq = list.length > 0 ? list[list.length - 1].seq : 0;
     const event = Object.freeze({
@@ -3620,23 +3724,79 @@ var ProcessTaskEventLog = class {
       seq: lastSeq + 1,
       type: input.type,
       pid: input.pid,
-      createdAt: Date.now(),
+      createdAt: currentTime,
       ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {}
     });
     list.push(event);
     this.events.set(input.taskId, list);
+    if (input.type === "exited" || input.type === "killed") {
+      this.terminalTasks.set(input.taskId, currentTime);
+    }
+    this.evict(currentTime);
     return { ...event };
   }
-  /** All events of the task with `seq > cursor` (default 0 = from the start). */
+  /**
+   * All events of the task with `seq > cursor` (default 0 = from the start).
+   *
+   * NOTE for cursor consumers (Phase 1 taskWait/taskLogs): an empty array is
+   * ambiguous — it means either "no new events yet" or "the whole task was
+   * evicted" (retention is per-taskId, never partial, so a cursor can never
+   * land in a hole). Do NOT treat empty as "still running and idle": pair the
+   * read with `hasTask(taskId)` to tell the two apart, otherwise a wait loop
+   * can hang forever on an evicted task. Eviction only ever happens after a
+   * terminal event plus the retention delay, so a live task is always readable.
+   */
   read(taskId, cursor = 0) {
     return (this.events.get(taskId) ?? []).filter((event) => event.seq > cursor).map((event) => ({ ...event }));
   }
+  /**
+   * Whether the task's event trail is still retained. Lets a cursor consumer
+   * disambiguate the empty result of `read()` (see its note).
+   */
+  hasTask(taskId) {
+    return this.events.has(taskId);
+  }
   latestSeq(taskId) {
     const list = this.events.get(taskId);
     return list && list.length > 0 ? list[list.length - 1].seq : 0;
   }
+  getStats() {
+    return {
+      taskCount: this.events.size,
+      terminalTaskCount: this.terminalTasks.size,
+      activeTaskCount: this.events.size - this.terminalTasks.size,
+      evictedCount: this.evictedCount,
+      activeOverflowCount: this.activeOverflowCount
+    };
+  }
   clear() {
     this.events.clear();
+    this.terminalTasks.clear();
+    this.evictedCount = 0;
+    this.activeOverflowCount = 0;
+  }
+  evict(currentTime) {
+    for (const [taskId, terminalTime] of this.terminalTasks.entries()) {
+      if (currentTime - terminalTime >= this.retentionMs) {
+        this.events.delete(taskId);
+        this.terminalTasks.delete(taskId);
+        this.evictedCount += 1;
+      }
+    }
+    if (this.events.size > this.maxTasks) {
+      const sortedTerminal = Array.from(this.terminalTasks.entries()).sort((a, b) => a[1] - b[1]);
+      for (const [taskId] of sortedTerminal) {
+        if (this.events.size <= this.maxTasks) {
+          break;
+        }
+        this.events.delete(taskId);
+        this.terminalTasks.delete(taskId);
+        this.evictedCount += 1;
+      }
+      if (this.events.size > this.maxTasks) {
+        this.activeOverflowCount += 1;
+      }
+    }
   }
 };
 
@@ -3649,7 +3809,10 @@ function mintTaskId(pid) {
 var ProcessRegistry = class {
   processes = /* @__PURE__ */ new Map();
   byTaskId = /* @__PURE__ */ new Map();
-  eventLog = new ProcessTaskEventLog();
+  eventLog;
+  constructor(eventLogOptions) {
+    this.eventLog = new ProcessTaskEventLog(eventLogOptions);
+  }
   /**
    * Pre-register an envelope right after a successful spawn and emit the
    * `started` event. Returns the stored record (with its stable taskId).
@@ -3704,6 +3867,15 @@ var ProcessRegistry = class {
   latestTaskSeq(taskId) {
     return this.eventLog.latestSeq(taskId);
   }
+  /**
+   * Whether the task's event trail is still retained. Cursor consumers MUST
+   * pair this with getTaskEvents(): an empty read means either "no new events"
+   * or "the whole trail was evicted" (§1.1), and only this call tells them
+   * apart — without it a wait loop hangs forever on an evicted task.
+   */
+  hasTaskEvents(taskId) {
+    return this.eventLog.hasTask(taskId);
+  }
   /**
    * Timeout-detach promotion: mark the pre-registered envelope as a background
    * task. Same record, same taskId, no re-execution, no second registration.
@@ -3718,9 +3890,19 @@ var ProcessRegistry = class {
     }
     return { ...item };
   }
+  /**
+   * Terminate a background process group and update its status to "stopped".
+   *
+   * Invariant (§1.3): Transient foreground envelopes (workspaceShell grace
+   * period before timeout detach) are NOT stoppable through this entry point;
+   * their lifecycle belongs to the foreground runner (abort/timeout). Calling
+   * kill() on a transient entry does not signal the process, does not emit a
+   * "killed" event, and returns false.
+   */
   kill(pid, signal = "SIGTERM") {
     const item = this.processes.get(pid);
     if (!item) return false;
+    if (item.transient) return false;
     if (item.status === "running") {
       try {
         process.kill(-item.pgid, signal);
@@ -4313,6 +4495,242 @@ ${stderr.trim()}` : "",
   };
 }
 
+// packages/agent-runtime/processTaskTools.ts
+var TASK_WAIT_DEFAULT_TIMEOUT_MS = 6e4;
+var TASK_WAIT_MAX_TIMEOUT_MS = 5 * 6e4;
+var TASK_WAIT_POLL_INTERVAL_MS = 250;
+var TASK_STOP_GRACE_MS = 2e3;
+var TERMINAL_EVENT_TYPES = /* @__PURE__ */ new Set(["exited", "killed"]);
+function defaultSleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+function defaultSignalSender(pid, signal) {
+  process.kill(pid, signal);
+}
+function statusOf(record) {
+  return reportedTaskStatus(record.status, record.exitCode);
+}
+function inspectTask(registry2, taskId) {
+  const record = registry2.getByTaskId(taskId);
+  const hasEvents = registry2.hasTaskEvents(taskId);
+  return { record, hasEvents, known: hasEvents || record !== void 0 };
+}
+function notFoundDetail(taskId) {
+  return `No task ${taskId} is known: it was never started, or both its envelope and its event trail have been dropped. Call tasks to list current handles.`;
+}
+function evictedDetail(taskId) {
+  return `Event trail of ${taskId} is gone (retention window elapsed). No further events will appear; do not wait again.`;
+}
+function lastTerminalEvent(events) {
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i];
+    if (TERMINAL_EVENT_TYPES.has(event.type)) return event;
+  }
+  return void 0;
+}
+function resolveTaskWaitTimeoutMs(raw) {
+  const value = typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() !== "" ? Number(raw) : Number.NaN;
+  if (!Number.isFinite(value)) {
+    return { timeoutMs: TASK_WAIT_DEFAULT_TIMEOUT_MS, clamped: false };
+  }
+  if (value <= 0) return { timeoutMs: 0, clamped: value < 0 };
+  if (value > TASK_WAIT_MAX_TIMEOUT_MS) {
+    return { timeoutMs: TASK_WAIT_MAX_TIMEOUT_MS, clamped: true };
+  }
+  return { timeoutMs: value, clamped: false };
+}
+async function runTaskWait(args) {
+  const { registry: registry2, taskId } = args;
+  const now = args.now ?? Date.now;
+  const sleep = args.sleep ?? defaultSleep;
+  const pollIntervalMs = Math.max(1, args.pollIntervalMs ?? TASK_WAIT_POLL_INTERVAL_MS);
+  const { timeoutMs, clamped } = resolveTaskWaitTimeoutMs(args.timeoutMs);
+  const initial = inspectTask(registry2, taskId);
+  if (!initial.known) {
+    return { outcome: "not-found", taskId, detail: notFoundDetail(taskId) };
+  }
+  const startedAt = now();
+  const deadline = startedAt + timeoutMs;
+  const maxPolls = Math.ceil(timeoutMs / pollIntervalMs) + 2;
+  for (let poll = 0; poll < maxPolls; poll += 1) {
+    const events = registry2.getTaskEvents(taskId, 0);
+    if (!registry2.hasTaskEvents(taskId)) {
+      const record = registry2.getByTaskId(taskId);
+      return {
+        outcome: "evicted",
+        taskId,
+        cursor: 0,
+        events: [],
+        ...record ? { status: statusOf(record) } : {},
+        detail: evictedDetail(taskId)
+      };
+    }
+    const terminal = lastTerminalEvent(events);
+    if (terminal) {
+      return {
+        outcome: "terminal",
+        taskId,
+        status: reportedTaskStatus(terminal.type, terminal.exitCode),
+        ...terminal.exitCode !== void 0 ? { exitCode: terminal.exitCode } : {},
+        cursor: registry2.latestTaskSeq(taskId),
+        events,
+        waitedMs: Math.max(0, now() - startedAt)
+      };
+    }
+    if (now() >= deadline) {
+      return {
+        outcome: "timeout",
+        taskId,
+        status: "running",
+        cursor: registry2.latestTaskSeq(taskId),
+        events,
+        waitedMs: Math.max(0, now() - startedAt),
+        timeoutMs,
+        ...clamped ? { timeoutClamped: true } : {}
+      };
+    }
+    await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - now())));
+  }
+  return {
+    outcome: "timeout",
+    taskId,
+    status: "running",
+    cursor: registry2.latestTaskSeq(taskId),
+    events: registry2.getTaskEvents(taskId, 0),
+    waitedMs: Math.max(0, now() - startedAt),
+    timeoutMs,
+    ...clamped ? { timeoutClamped: true } : {}
+  };
+}
+function runTaskLogs(args) {
+  const { registry: registry2, taskId } = args;
+  const cursorRaw = typeof args.cursor === "number" ? args.cursor : typeof args.cursor === "string" && args.cursor.trim() !== "" ? Number(args.cursor) : Number.NaN;
+  const cursor = Number.isFinite(cursorRaw) && cursorRaw > 0 ? Math.floor(cursorRaw) : 0;
+  const { record, hasEvents, known } = inspectTask(registry2, taskId);
+  if (!known) {
+    return { outcome: "not-found", taskId, detail: notFoundDetail(taskId) };
+  }
+  if (!hasEvents) {
+    return {
+      outcome: "evicted",
+      taskId,
+      cursor: 0,
+      events: [],
+      ...record ? { status: statusOf(record) } : {},
+      detail: evictedDetail(taskId)
+    };
+  }
+  const events = registry2.getTaskEvents(taskId, cursor);
+  const allEvents = registry2.getTaskEvents(taskId, 0);
+  const terminal = lastTerminalEvent(allEvents);
+  const status = terminal ? reportedTaskStatus(terminal.type, terminal.exitCode) : record ? statusOf(record) : "running";
+  return {
+    outcome: "ok",
+    taskId,
+    cursor: registry2.latestTaskSeq(taskId),
+    events,
+    status,
+    terminal: isProcessTaskTerminalStatus(status)
+  };
+}
+function formatTaskLogsContent(result, options) {
+  const full = JSON.stringify(result);
+  const limit = options?.outputLimit && options.outputLimit > 0 ? options.outputLimit : void 0;
+  const effectiveLimit = limit ?? 2e4;
+  if (full.length <= effectiveLimit) return { content: full };
+  try {
+    const spill = spillToolOutput({
+      content: full,
+      toolName: "taskLogs",
+      workspaceRoot: options?.workspaceRoot
+    });
+    const omitted = result.outcome === "ok" ? result.events.length : 0;
+    const head = JSON.stringify({
+      ...result,
+      events: [],
+      eventsOmitted: omitted,
+      logRef: spill.displayPath
+    });
+    return {
+      content: `${head}${formatToolOverflowMarker({
+        spillRef: spill.displayPath,
+        totalChars: spill.totalChars,
+        totalLines: spill.totalLines,
+        omittedChars: Math.max(0, full.length - head.length),
+        toolName: "taskLogs"
+      })}`.trimEnd(),
+      logRef: spill.displayPath
+    };
+  } catch {
+    return { content: truncateToolOutput(full, effectiveLimit) };
+  }
+}
+function isProcessGroupAlive(pgid, kill = defaultSignalSender) {
+  try {
+    kill(-pgid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+async function runTaskStop(args) {
+  const { registry: registry2, taskId } = args;
+  const sleep = args.sleep ?? defaultSleep;
+  const kill = args.kill ?? defaultSignalSender;
+  const graceMs = Math.max(0, args.graceMs ?? TASK_STOP_GRACE_MS);
+  const record = registry2.getByTaskId(taskId);
+  if (!record) {
+    return { outcome: "not-found", taskId, detail: notFoundDetail(taskId) };
+  }
+  const termed = registry2.kill(record.pid, "SIGTERM");
+  if (!termed) {
+    const reason = record.transient ? "transient-foreground" : record.status !== "running" ? "already-terminal" : "kill-refused";
+    const detail = reason === "transient-foreground" ? `${taskId} is a foreground command still inside its grace window, not a background task; its lifecycle belongs to the running execShell call.` : reason === "already-terminal" ? `${taskId} is already ${statusOf(record)}; nothing to stop.` : `Registry refused to stop ${taskId}.`;
+    return {
+      outcome: "not-stoppable",
+      taskId,
+      pid: record.pid,
+      status: statusOf(record),
+      reason,
+      detail
+    };
+  }
+  if (graceMs > 0) await sleep(graceMs);
+  if (!isProcessGroupAlive(record.pgid, kill)) {
+    return {
+      outcome: "stopped",
+      taskId,
+      pid: record.pid,
+      status: reportedTaskStatus("killed"),
+      signal: "SIGTERM",
+      escalated: false
+    };
+  }
+  try {
+    kill(-record.pgid, "SIGKILL");
+  } catch {
+  }
+  return {
+    outcome: "stopped",
+    taskId,
+    pid: record.pid,
+    status: reportedTaskStatus("killed"),
+    signal: "SIGKILL",
+    escalated: true
+  };
+}
+function runTasks(args) {
+  const tasks = args.registry.listBackground().map((record) => ({
+    taskId: record.taskId,
+    pid: record.pid,
+    label: record.label,
+    status: statusOf(record),
+    startedAt: record.startedAt,
+    persist: record.persist
+  }));
+  return { tasks, count: tasks.length };
+}
+
 // packages/agent-runtime/capabilities/execShellCapability.ts
 function buildExecShellToolDefinition(toolName = "execShell") {
   return {
@@ -4452,9 +4870,21 @@ var WORKSPACE_TOOL_NAMES = [
   "captureVisualState",
   "execShell",
   "launchProcess",
-  "listProcesses"
+  "listProcesses",
+  "taskWait",
+  "taskLogs",
+  "taskStop",
+  "tasks"
+];
+var SHELL_TOOL_NAMES = [
+  "execShell",
+  "launchProcess",
+  "listProcesses",
+  "taskWait",
+  "taskLogs",
+  "taskStop",
+  "tasks"
 ];
-var SHELL_TOOL_NAMES = ["execShell", "launchProcess", "listProcesses"];
 var WORKSPACE_TOOL_NAME_SET = new Set(WORKSPACE_TOOL_NAMES);
 function buildWorkspacePathProperty() {
   return {
@@ -4678,6 +5108,87 @@ function buildListProcessesTool() {
     }
   };
 }
+function buildTaskWaitTool() {
+  return {
+    type: "function",
+    function: {
+      name: "taskWait",
+      description: 'Block until a background task (from launchProcess, or an execShell command that detached) reaches a terminal state, or until timeoutMs elapses. Returns {outcome, status, exitCode?, cursor, events}: outcome "terminal" with status exited|failed|stopped when it finished, outcome "timeout" with status "running" when it is still going (call again to keep waiting), outcome "not-found" for an unknown taskId, or outcome "evicted" when the event trail aged out (never wait again in that case). `cursor` is the highest event seq covered by this response \u2014 pass it to taskLogs to read only newer events.',
+      parameters: {
+        type: "object",
+        properties: {
+          taskId: {
+            type: "string",
+            minLength: 1,
+            description: "Task id returned by launchProcess or by a detached execShell result."
+          },
+          timeoutMs: {
+            type: "number",
+            description: "Wait budget in milliseconds. Defaults to 60000; values above 300000 are clamped to 300000."
+          }
+        },
+        required: ["taskId"]
+      }
+    }
+  };
+}
+function buildTaskLogsTool() {
+  return {
+    type: "function",
+    function: {
+      name: "taskLogs",
+      description: "Read a background task's lifecycle events incrementally. Returns {outcome, status, cursor, events} where events are the started|promoted|exited|killed records with seq greater than the cursor you passed, and the returned `cursor` is the new high-water mark to pass next time (omit cursor to read from the beginning; repeating the same cursor is idempotent). Oversized output is spilled to a file and reported as `logRef`, which you can open with readFile.",
+      parameters: {
+        type: "object",
+        properties: {
+          taskId: {
+            type: "string",
+            minLength: 1,
+            description: "Task id returned by launchProcess or by a detached execShell result."
+          },
+          cursor: {
+            type: "number",
+            description: "Last event seq you already consumed; only events with a higher seq are returned. Defaults to 0 (all retained events)."
+          }
+        },
+        required: ["taskId"]
+      }
+    }
+  };
+}
+function buildTaskStopTool() {
+  return {
+    type: "function",
+    function: {
+      name: "taskStop",
+      description: 'Stop a background task: SIGTERM to its process group, then SIGKILL if it is still alive after a short grace window. Returns {outcome, status, signal, escalated}: outcome "stopped" with status "stopped" on success, or outcome "not-stoppable" (already finished, or a foreground command that is not a background task) or "not-found". Never reports success without signalling.',
+      parameters: {
+        type: "object",
+        properties: {
+          taskId: {
+            type: "string",
+            minLength: 1,
+            description: "Task id returned by launchProcess or by a detached execShell result."
+          }
+        },
+        required: ["taskId"]
+      }
+    }
+  };
+}
+function buildTasksTool() {
+  return {
+    type: "function",
+    function: {
+      name: "tasks",
+      description: "List background tasks you can still wait on, read logs from, or stop. Returns {count, tasks: {taskId, pid, label, status, startedAt, persist}[]}. Use it to recover a taskId you lost track of; foreground commands still running inside execShell are not listed.",
+      parameters: {
+        type: "object",
+        properties: {}
+      }
+    }
+  };
+}
 function buildWorkspaceToolDefinition(toolName) {
   if (toolName === "readFile") {
     return buildReadWorkspaceFileTool();
@@ -4695,6 +5206,10 @@ function buildWorkspaceToolDefinition(toolName) {
   if (toolName === "execShell") return buildExecShellTool(toolName);
   if (toolName === "launchProcess") return buildLaunchProcessTool();
   if (toolName === "listProcesses") return buildListProcessesTool();
+  if (toolName === "taskWait") return buildTaskWaitTool();
+  if (toolName === "taskLogs") return buildTaskLogsTool();
+  if (toolName === "taskStop") return buildTaskStopTool();
+  if (toolName === "tasks") return buildTasksTool();
   return null;
 }
 function filterDeclaredWorkspaceToolNames(args) {
@@ -6097,6 +6612,91 @@ async function listProcessesTool(args) {
     }
   };
 }
+function requireTaskId(parsed) {
+  return readTrimmedString2(parsed.taskId);
+}
+function missingTaskIdResult(toolName) {
+  return {
+    content: JSON.stringify({
+      outcome: "invalid-arguments",
+      detail: `${toolName} requires a taskId (see tasks for current handles).`
+    }),
+    metadata: { status: "invalid-arguments", tool: toolName }
+  };
+}
+async function taskWaitTool(args) {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const taskId = requireTaskId(parsed);
+  if (!taskId) return missingTaskIdResult(args.call.name);
+  const result = await runTaskWait({
+    taskId,
+    timeoutMs: parsed.timeoutMs,
+    registry: getProcessRegistry(),
+    ...args.pollIntervalMs !== void 0 ? { pollIntervalMs: args.pollIntervalMs } : {}
+  });
+  return {
+    content: JSON.stringify(result),
+    metadata: {
+      taskId,
+      outcome: result.outcome,
+      ..."status" in result && result.status ? { status: result.status } : {},
+      ..."cursor" in result ? { cursor: result.cursor } : {},
+      ..."exitCode" in result && result.exitCode !== void 0 ? { exitCode: result.exitCode } : {}
+    }
+  };
+}
+async function taskLogsTool(args) {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const taskId = requireTaskId(parsed);
+  if (!taskId) return missingTaskIdResult(args.call.name);
+  const result = runTaskLogs({
+    taskId,
+    cursor: parsed.cursor,
+    registry: getProcessRegistry()
+  });
+  const rendered = formatTaskLogsContent(result, {
+    ...args.commandOutputLimit !== void 0 ? { outputLimit: args.commandOutputLimit } : {},
+    workspaceRoot: args.workspaceRoot
+  });
+  return {
+    content: rendered.content,
+    metadata: {
+      taskId,
+      outcome: result.outcome,
+      ..."status" in result && result.status ? { status: result.status } : {},
+      ..."cursor" in result ? { cursor: result.cursor } : {},
+      ..."events" in result ? { eventCount: result.events.length } : {},
+      ...rendered.logRef ? { logRef: rendered.logRef } : {}
+    }
+  };
+}
+async function taskStopTool(args) {
+  const parsed = parseWorkspaceToolArguments(args.call.arguments);
+  const taskId = requireTaskId(parsed);
+  if (!taskId) return missingTaskIdResult(args.call.name);
+  const result = await runTaskStop({
+    taskId,
+    registry: getProcessRegistry(),
+    ...args.graceMs !== void 0 ? { graceMs: args.graceMs } : {}
+  });
+  return {
+    content: JSON.stringify(result),
+    metadata: {
+      taskId,
+      outcome: result.outcome,
+      ..."status" in result ? { status: result.status } : {},
+      ..."pid" in result ? { pid: result.pid } : {},
+      ..."signal" in result ? { signal: result.signal } : {}
+    }
+  };
+}
+async function tasksTool(_args) {
+  const result = runTasks({ registry: getProcessRegistry() });
+  return {
+    content: JSON.stringify(result),
+    metadata: { count: result.count, tasks: result.tasks }
+  };
+}
 function createLocalWorkspaceToolExecutors(args) {
   const fileAccess = args.confirmExternalFileAccess ? { confirmExternalFileAccess: args.confirmExternalFileAccess } : {};
   const readFileLedger = /* @__PURE__ */ new Map();
@@ -6151,7 +6751,15 @@ function createLocalWorkspaceToolExecutors(args) {
     }),
     listProcesses: (call) => listProcessesTool({
       call
-    })
+    }),
+    taskWait: (call) => taskWaitTool({ call }),
+    taskLogs: (call) => taskLogsTool({
+      call,
+      workspaceRoot: args.workspaceRoot,
+      ...args.commandOutputLimit !== void 0 ? { commandOutputLimit: args.commandOutputLimit } : {}
+    }),
+    taskStop: (call) => taskStopTool({ call }),
+    tasks: (call) => tasksTool({ call })
   };
 }
 
@@ -6289,7 +6897,7 @@ function buildLoadSkillExecutor(args) {
     const { resolveSkillByName } = await import("./skillDiscovery-COX56OBO.js");
     const resolved = resolveSkillByName(args.cwd, name);
     if (!resolved) {
-      const { resolveCodingBuiltinSlug, buildCodingSkillContentBySlug } = await import("./codingSkills-H6N5EKSX.js");
+      const { resolveCodingBuiltinSlug, buildCodingSkillContentBySlug } = await import("./codingSkills-BYQI6EPT.js");
       const builtinSlug = resolveCodingBuiltinSlug(name);
       if (builtinSlug) {
         const body = buildCodingSkillContentBySlug(builtinSlug);