@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/tools/builtins/sandbox/task-list.js

@@ -0,0 +1,130 @@
+import { formatElapsed, lostReasonText } from "../../../background/render.js";
+import { clip, display, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+import { outputFile, taskEnv } from "./task-output.js";
+/** How many finished background tasks (and finished sub-agents) `TaskList` lists at most. */
+export const TASK_LIST_FINISHED_LIMIT = 20;
+const SPEC = {
+    name: "TaskList",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["status"],
+    description: "List this conversation's background tasks (started with Bash and run_in_background) and the " +
+        "sub-agents it dispatched. Running tasks come first, then the most recently finished ones " +
+        "(at most 20); each has its id, description, status (running, " +
+        "completed, failed, timed_out, stopped or lost), elapsed time, exit code once finished and " +
+        "output file. Sub-agents are listed with their agentId, description and status. Use it to " +
+        "find a task id you lost track of, for example after a long run; then use TaskOutput to read " +
+        "a task's output or TaskStop to stop it. Statuses are as last checked: TaskOutput checks a " +
+        "task now. It only reads, and lists nothing from other conversations.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            status: {
+                type: "string",
+                enum: ["running", "all"],
+                description: `"running" lists only what is still running; "all" (the default) also lists the ${TASK_LIST_FINISHED_LIMIT} most recently finished tasks and sub-agents.`,
+            },
+        },
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+};
+/** `running for 2m05s`, `failed, exit code 3, after 4m12s`, `lost (the sandbox was suspended), after 3s`. */
+function taskState(task, now) {
+    const end = task.status === "running" ? now : (task.finishedAt ?? now);
+    const elapsed = formatElapsed(end.getTime() - task.startedAt.getTime());
+    if (task.status === "running") {
+        return task.sandboxCreatedAt === null ? "starting" : `running for ${elapsed}`;
+    }
+    let s = task.status;
+    if (task.lostReason !== null)
+        s += ` (${lostReasonText(task.lostReason)})`;
+    if (task.exitCode !== null)
+        s += `, exit code ${task.exitCode}`;
+    return `${s}, after ${elapsed}`;
+}
+function taskEntry(task, now) {
+    const output = task.sandboxCreatedAt === null && task.status !== "running"
+        ? "none (the command never started)"
+        : outputFile(task);
+    return `- ${task.id} ${taskState(task, now)}: ${JSON.stringify(task.description)}\n  Output: ${output}`;
+}
+const ACTIVE_AGENT = new Set(["queued", "running", "waiting"]);
+const agentStatus = (s) => (s === "aborted" ? "stopped" : s);
+const agentEntry = (a) => `- ${a.id} ${agentStatus(a.status)}: ${JSON.stringify(clip(a.description, 200))}`;
+/** `1 running, 2 finished` (a zero count left out; `none` when both are). */
+function counts(running, finished, onlyRunning) {
+    const parts = [];
+    if (running > 0)
+        parts.push(`${running} running`);
+    if (finished > 0)
+        parts.push(`${finished} finished`);
+    if (parts.length === 0)
+        return onlyRunning ? "none running" : "none";
+    return parts.join(", ");
+}
+/**
+ * Built-in `TaskList`: the calling conversation's own background tasks (never its sub-agents' or
+ * another conversation's: owner `conversation_id`, as `TaskOutput` checks) and the sub-agents it
+ * dispatched itself. Running entries first (oldest first), then with `status: "all"` the
+ * {@link TASK_LIST_FINISHED_LIMIT} most recently finished. Reads PG only: it never checks a task in
+ * its sandbox, so a status is the poller's or a tool's last one.
+ */
+export function taskListTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
+        async run(input, ctx) {
+            const onlyRunning = input.status === "running";
+            const env = await taskEnv(deps, ctx);
+            const store = deps.background;
+            const [running, finished, agents] = await Promise.all([
+                store.runningOwnedBy(ctx.conversationId),
+                onlyRunning
+                    ? { rows: [], total: 0 }
+                    : store.finishedOwnedBy(ctx.conversationId, TASK_LIST_FINISHED_LIMIT),
+                env.subagents?.childrenOf(ctx.orgId, ctx.conversationId) ?? [],
+            ]);
+            const now = new Date();
+            const activeAgents = agents.filter((a) => ACTIVE_AGENT.has(a.status));
+            const doneAgents = onlyRunning
+                ? []
+                : agents
+                    .filter((a) => !ACTIVE_AGENT.has(a.status))
+                    .sort((a, b) => (b.finishedAt?.getTime() ?? 0) - (a.finishedAt?.getTime() ?? 0));
+            const listedDone = doneAgents.slice(0, TASK_LIST_FINISHED_LIMIT);
+            if (running.length + finished.total + activeAgents.length + doneAgents.length === 0) {
+                return result(onlyRunning
+                    ? "No background tasks or sub-agents are running in this conversation."
+                    : "No background tasks or sub-agents in this conversation.");
+            }
+            const lines = [
+                `Background tasks: ${counts(running.length, finished.total, onlyRunning)}.`,
+                ...running.map((t) => taskEntry(t, now)),
+                ...finished.rows.map((t) => taskEntry(t, now)),
+            ];
+            const olderTasks = finished.total - finished.rows.length;
+            if (olderTasks > 0)
+                lines.push(`(${olderTasks} older finished tasks are not listed.)`);
+            if (agents.length > 0) {
+                lines.push("", `Sub-agents: ${counts(activeAgents.length, doneAgents.length, onlyRunning)}.`, ...activeAgents.map(agentEntry), ...listedDone.map(agentEntry));
+                const olderAgents = doneAgents.length - listedDone.length;
+                if (olderAgents > 0)
+                    lines.push(`(${olderAgents} older finished sub-agents are not listed.)`);
+            }
+            lines.push("", "Statuses are as last checked. Use TaskOutput to check a task now and read its output, TaskStop to stop it." +
+                (agents.length > 0
+                    ? " A sub-agent's report arrives on its own; use SendMessage to give it more instructions."
+                    : ""));
+            return result(lines.join("\n"));
+        },
+    };
+}
+function result(text) {
+    return {
+        content: [{ type: "text", text }],
+        isError: false,
+        display: display("列出后台任务", "List background tasks"),
+    };
+}

package/dist/tools/builtins/sandbox/task-output.d.ts

@@ -16,6 +16,7 @@ export interface TaskEnv {
     ifRunning: SandboxService["ifRunning"];
     devices: SandboxToolDeps["devices"];
     log: SandboxToolDeps["log"];
+    subagents?: SandboxToolDeps["subagents"];
 }
 /**
  * The task tools' dependencies; throws the tool's error when they are missing, or when the
@@ -23,9 +24,15 @@ export interface TaskEnv {
  * ruling R8).
  */
 export declare function taskEnv(deps: SandboxToolDeps, ctx: BuiltinCallContext): Promise<TaskEnv>;
+/**
+ * A sub-agent's agentId passed as a task id (as Claude Code's TaskOutput allows for background
+ * agents): its report arrives on its own, so polling or sleeping for it only wastes the run.
+ */
+export declare const subagentNotTaskText: (id: string) => string;
 /**
  * The task `id` when it belongs to the calling conversation; a task of another conversation (a
- * sub-agent's, when called from its parent) is not found, the same as an unknown id.
+ * sub-agent's, when called from its parent) is not found, the same as an unknown id. A sub-agent's
+ * agentId gets its own text ({@link subagentNotTaskText}).
  */
 export declare function ownedTask(env: TaskEnv, ctx: BuiltinCallContext, id: string): Promise<BackgroundTaskRow>;
 /**

package/dist/tools/builtins/sandbox/task-output.js

@@ -67,16 +67,34 @@ export async function taskEnv(deps, ctx) {
         ifRunning: deps.sandbox.ifRunning.bind(deps.sandbox),
         devices: deps.devices,
         log: deps.log,
+        ...(deps.subagents !== undefined && { subagents: deps.subagents }),
     };
 }
-const notFound = (id) => new ToolError(`No background task ${clip(id, 40)} in this conversation. Pass a task id that Bash with run_in_background returned in this conversation.`);
+const notFound = (id) => new ToolError(`No background task ${clip(id, 40)} in this conversation. Pass a task id that Bash with run_in_background returned in this conversation; call TaskList to see this conversation's tasks.`);
+/**
+ * A sub-agent's agentId passed as a task id (as Claude Code's TaskOutput allows for background
+ * agents): its report arrives on its own, so polling or sleeping for it only wastes the run.
+ */
+export const subagentNotTaskText = (id) => `${clip(id, 40)} is a sub-agent, not a background task. Its report arrives in this conversation as a notification when it hands back or finishes. Don't poll or sleep for it: keep working or end your turn. Use SendMessage to give it more instructions.`;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** {@link notFound}, or {@link subagentNotTaskText} when `id` is a sub-agent of the caller's tree. */
+async function missingTask(env, ctx, id) {
+    const trimmed = id.trim();
+    if (env.subagents !== undefined &&
+        UUID_RE.test(trimmed) &&
+        (await env.subagents.inTree(sandboxConversationOf(ctx), trimmed.toLowerCase()))) {
+        return new ToolError(subagentNotTaskText(trimmed));
+    }
+    return notFound(id);
+}
 /**
  * The task `id` when it belongs to the calling conversation; a task of another conversation (a
- * sub-agent's, when called from its parent) is not found, the same as an unknown id.
+ * sub-agent's, when called from its parent) is not found, the same as an unknown id. A sub-agent's
+ * agentId gets its own text ({@link subagentNotTaskText}).
  */
 export async function ownedTask(env, ctx, id) {
     if (!TASK_ID_RE.test(id))
-        throw notFound(id);
+        throw await missingTask(env, ctx, id);
     const task = await env.store.get(id);
     if (!task || task.conversationId !== ctx.conversationId)
         throw notFound(id);

package/dist/tools/builtins/web/extract.d.ts

@@ -4,7 +4,6 @@ import type { KernelConfigService } from "../../../infra/config/kernel-config.se
 import { type ModelPurposesService } from "../../../models/purposes.js";
 import { type HookRunner } from "../../../runtime/hook-calls.js";
 import type { StepLog } from "../../../runtime/step-log.js";
-import type { UsageReporter } from "../../../runtime/usage-report.js";
 import type { BuiltinCallContext } from "../../registry.js";
 /**
  * The `WebFetch` extraction call (web tools spec §5): the fetched page and the model's prompt go to
@@ -33,13 +32,12 @@ export declare const WEB_FETCH_DENIED_TEXT = "An org policy blocked reading this
 /** What {@link extractAnswer} needs. */
 export interface WebFetchExtractDeps {
     purposes: Pick<ModelPurposesService, "chat" | "chatLimits">;
-    eventLog: Pick<EventLog, "append" | "notify" | "latestOfType">;
-    stepLog: Pick<StepLog, "appendCounted" | "appendAudited">;
+    eventLog: Pick<EventLog, "notify" | "latestOfType">;
+    stepLog: Pick<StepLog, "appendCounted" | "appendReported" | "appendAudited">;
     config: Pick<KernelConfigService, "get">;
     log: Pick<Logger, "warn">;
     /** Extension hooks (absent: none fire). */
     hooks?: HookRunner | undefined;
-    usageReport?: Pick<UsageReporter, "enqueue"> | undefined;
 }
 /**
  * The user message of the extraction call: the URL, then the page (title, markdown) between

package/dist/tools/builtins/web/extract.js

@@ -192,7 +192,7 @@ export async function extractAnswer(deps, ctx, page, prompt) {
 }
 /**
  * Appends the call's `usage` event (the tool call's run and step, `callId`; idempotent per call)
- * and queues its `usage.report`. A sub-agent's call also counts on its parent run's
+ * and owes its `usage.report` delivery in the same transaction. A sub-agent's call also counts on its parent run's
  * `subagent_tokens_used`, in the same transaction ({@link appendCounted}).
  */
 async function logUsage(deps, ctx, runId, step, u) {
@@ -209,14 +209,11 @@ async function logUsage(deps, ctx, runId, step, u) {
             callId: ctx.callId,
         },
     };
-    const written = await appendCounted(deps, {
+    await appendCounted(deps, {
         conversationId: ctx.conversationId,
         parentRunId: ctx.parentRunId,
         budgetRunId: ctx.budgetRunId,
     }, [event]);
-    const usage = written.find((e) => e.type === "usage");
-    if (usage)
-        void deps.usageReport?.enqueue(ctx.conversationId, usage.seq);
 }
 /**
  * Records a `model.request` denial of the extraction call: the `hook_denied` event (the tool call's

package/dist/tools/pipeline.d.ts

@@ -1,4 +1,4 @@
-import { type FormAnswer, type InputForm, type Logger } from "@capybara-hq/plugin-sdk";
+import { type ConversationSource, type FormAnswer, type InputForm, type Logger } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
 import { EventLog } from "../conversations/event-log.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
@@ -222,8 +222,17 @@ export interface ToolStepContext {
     /** 运行所用的 agent 版本（审计链记录）。 */
     agentVersion: number;
     agent: AgentDefinition;
-    /** 对话发起人（取个人凭据、审计 actor）。 */
+    /** The run's trigger account (personal credentials, the audit actor). */
     accountId: string;
+    /**
+     * The conversation's source (memory plugin spec §6.2): extension tools limited by
+     * `spec.sources` are resolved with it, and plugin handlers receive it.
+     */
+    source: ConversationSource;
+    /** The conversation's owner (`conversations.account_id`), given to plugin handlers. */
+    ownerAccountId: string;
+    /** The trigger account's current org role, given to plugin handlers. */
+    role: OrgRole;
     /** run 的中止信号（用户中止 / 截止时间）。 */
     signal: AbortSignal;
     /** run 的截止时间（epoch 毫秒）；传给内置工具（沙箱命令据此收紧超时，Ruling M20）。 */
@@ -310,7 +319,7 @@ export declare class ToolPipeline {
     runStep(given: ToolStepContext): Promise<ToolStepOutcome>;
     /**
      * Writes, in the caller's transaction (`mandatory`), what a run that is being stopped (a person,
-     * its deadline, a failure, the wait sweep) still owes its log: the report of its fork invocation
+     * its deadline, a failure, an orphan repair) still owes its log: the report of its fork invocation
      * (phase D, `pairStoppedForks`; a still active fork child is stopped by the caller after its
      * commit). An `Agent` call has its result from its dispatch (agent map spec §4.1), so there is
      * nothing to write for it. Returns the fork's call id (the caller must not write a "not executed"

package/dist/tools/pipeline.js

@@ -314,6 +314,7 @@ let ToolPipeline = class ToolPipeline {
                     forkChild: ctx.parent?.forSkill === true,
                     sandboxConversationId: ctx.parent?.rootConversationId ?? ctx.conversationId,
                     replay: ctx.conversationKind === "eval",
+                    source: ctx.source,
                 });
             }
             return resolved;
@@ -331,7 +332,7 @@ let ToolPipeline = class ToolPipeline {
     }
     /**
      * Writes, in the caller's transaction (`mandatory`), what a run that is being stopped (a person,
-     * its deadline, a failure, the wait sweep) still owes its log: the report of its fork invocation
+     * its deadline, a failure, an orphan repair) still owes its log: the report of its fork invocation
      * (phase D, `pairStoppedForks`; a still active fork child is stopped by the caller after its
      * commit). An `Agent` call has its result from its dispatch (agent map spec §4.1), so there is
      * nothing to write for it. Returns the fork's call id (the caller must not write a "not executed"
@@ -1001,6 +1002,10 @@ let ToolPipeline = class ToolPipeline {
             conversationId: ctx.conversationId,
             callId,
             ...(resume !== undefined && { resume }),
+            // who and where (memory plugin spec §6.2): `accountId` stays the trigger account
+            source: ctx.source,
+            ownerAccountId: ctx.ownerAccountId,
+            role: ctx.role,
             ...(tool.source.kind === "builtin" && stepTools !== undefined && { tools: stepTools }),
             ...(tool.source.kind === "builtin" && { runId: ctx.runId }),
             ...(tool.source.kind === "builtin" &&

package/dist/tools/questions.service.d.ts

@@ -4,6 +4,7 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
+import { RunResume } from "../runtime/run-jobs.js";
 export type QuestionStatus = "pending" | "answered" | "skipped" | "expired" | "cancelled";
 /** 一条输入请求（`AskUserQuestion`、插件工具的 `input_required`、MCP elicitation 共用）。 */
 export interface QuestionRecord {
@@ -44,9 +45,11 @@ export type QuestionView = Omit<QuestionRecord, "state">;
  * 状态全部在 PG：回答 / 超时 / 取消都在事务里 `SELECT … FOR UPDATE` 该行，多副本并发时恰好一个生效，
  * 只有生效的那次写 `question_answered`。HTTP 接口见 questions.controller.ts。
  *
- * An answer is announced after the commit as the domain event `question.answered` (exactly once),
- * which the run's waits follow to resume it (spec §3b; the wait sweep resumes a run whose resume was
- * lost). Events are appended in the context's transaction (`EventLog.appendIn`).
+ * An answer resumes its waiting run in the answer's transaction (`RunResume.resumeIn`, after the
+ * question row: lock order conversation, question, then run; transactional outbox spec §6). It is
+ * announced after the commit as the domain event `question.answered` (exactly once; no kernel
+ * subscriber: the IM card update is owed by the `question_answered` append, transactional outbox
+ * spec §8.1). Events are appended in the context's transaction (`EventLog.appendIn`).
  */
 export declare class QuestionsService {
     private readonly db;
@@ -54,7 +57,11 @@ export declare class QuestionsService {
     private readonly eventLog;
     private readonly events;
     readonly txHost: TransactionHost;
-    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, eventLog: Pick<EventLog, "appendIn" | "notify">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost);
+    /** An answer resumes its waiting run in the answer's transaction. */
+    private readonly resumes;
+    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, eventLog: Pick<EventLog, "appendIn" | "notify">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost, 
+    /** An answer resumes its waiting run in the answer's transaction. */
+    resumes: Pick<RunResume, "resumeIn">);
     /**
      * 新建 pending 输入请求（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `question_asked`，同一事务。
      * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录，事件按 `question_asked:<id>` 幂等。
@@ -98,11 +105,22 @@ export declare class QuestionsService {
      */
     cancelPendingIn(runId: string): Promise<QuestionRecord[]>;
     /**
-     * 在调用方的事务内（`mandatory`）取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
-     * 即「其作为处理人」的提问；成员离职时调用），走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、
-     * 写 `question_answered{cancelled}`。返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件。
+     * The conversations of `orgId` holding a pending question of a run `accountId` started (only the
+     * run's starter answers), read without locks: offboarding locks them, by tree root first
+     * (`lockConversationTrees`), before {@link cancelPendingFor}.
      */
-    cancelPendingFor(orgId: string, accountId: string): Promise<{
+    pendingConversationsFor(orgId: string, accountId: string): Promise<string[]>;
+    /**
+     * In the caller's transaction (`mandatory`; offboarding): cancels every pending question of a run
+     * `accountId` started in `orgId` within `conversationIds`, the conversations the caller already
+     * locked (by tree root first, `lockConversationTrees`; lock order D7: conversation, then question
+     * rows), along the same path as {@link cancelPendingIn}: `cancelled`,
+     * `question_answered{cancelled}`. A question asked meanwhile in another conversation waits for
+     * its run's stop (offboarding owes it), so no conversation is locked after a row. Returns the
+     * cancelled records and the highest seq written per conversation; the caller publishes after the
+     * commit.
+     */
+    cancelPendingFor(orgId: string, accountId: string, conversationIds: readonly string[]): Promise<{
         records: QuestionRecord[];
         seqs: Map<string, number>;
     }>;
@@ -113,8 +131,10 @@ export declare class QuestionsService {
      * by a run of it that is `running` or `waiting` and was started by `accountId`. The caller holds
      * the conversation row lock (its `appendIn`), so only questions logged before the message are
      * seen. Each becomes `skipped` with `question_answered { outcome: "skipped", skippedBySeq }`.
-     * Returns the records and the highest seq written (null: none); the caller notifies and emits
-     * `question.answered` after the commit.
+     * The caller resumes their waiting runs in this transaction after it locked every row it skips
+     * (`ConversationsService.skipWaitsIn`: conversations, decided rows, runs). Returns the records and
+     * the highest seq written (null: none); the caller notifies and emits `question.answered` after
+     * the commit.
      */
     skipPendingIn(conversationId: string, accountId: string, messageSeq: number): Promise<{
         records: QuestionRecord[];

package/dist/tools/questions.service.js

@@ -18,6 +18,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
+import { RunResume } from "../runtime/run-jobs.js";
 const notFound = () => new ApiError("question.not_found", "Question not found");
 const notInitiator = () => new ApiError("forbidden", "Only the user who started the run can answer this question");
 const toView = ({ state: _state, ...rest }) => rest;
@@ -49,9 +50,11 @@ const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArr
  * 状态全部在 PG：回答 / 超时 / 取消都在事务里 `SELECT … FOR UPDATE` 该行，多副本并发时恰好一个生效，
  * 只有生效的那次写 `question_answered`。HTTP 接口见 questions.controller.ts。
  *
- * An answer is announced after the commit as the domain event `question.answered` (exactly once),
- * which the run's waits follow to resume it (spec §3b; the wait sweep resumes a run whose resume was
- * lost). Events are appended in the context's transaction (`EventLog.appendIn`).
+ * An answer resumes its waiting run in the answer's transaction (`RunResume.resumeIn`, after the
+ * question row: lock order conversation, question, then run; transactional outbox spec §6). It is
+ * announced after the commit as the domain event `question.answered` (exactly once; no kernel
+ * subscriber: the IM card update is owed by the `question_answered` append, transactional outbox
+ * spec §8.1). Events are appended in the context's transaction (`EventLog.appendIn`).
  */
 let QuestionsService = class QuestionsService {
     db;
@@ -59,12 +62,16 @@ let QuestionsService = class QuestionsService {
     eventLog;
     events;
     txHost;
-    constructor(db, config, eventLog, events, txHost) {
+    resumes;
+    constructor(db, config, eventLog, events, txHost, 
+    /** An answer resumes its waiting run in the answer's transaction. */
+    resumes) {
         this.db = db;
         this.config = config;
         this.eventLog = eventLog;
         this.events = events;
         this.txHost = txHost;
+        this.resumes = resumes;
     }
     /**
      * 新建 pending 输入请求（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `question_asked`，同一事务。
@@ -163,7 +170,7 @@ let QuestionsService = class QuestionsService {
     async answer(questionId, accountId, answer, orgId) {
         const { record, toSeq } = await this.answerIn(questionId, accountId, answer, orgId);
         await this.eventLog.notify(record.conversationId, toSeq);
-        // waits resume the run and its IM delivery is enqueued (handler failures are logged)
+        // its IM delivery is enqueued (handler failures are logged); the run resumed in the answer
         await this.events.emit("question.answered", {
             id: record.id,
             orgId: record.orgId,
@@ -246,6 +253,8 @@ let QuestionsService = class QuestionsService {
             .returningAll()
             .executeTakeFirstOrThrow();
         const toSeq = await this.answeredEvent(before, answer, accountId, "answered");
+        // the run last; a still-running run is resumed by its suspend's re-check
+        await this.resumes.resumeIn(before.runId, questionId);
         return { record: toRecord(updated), toSeq };
     }
     /**
@@ -315,14 +324,12 @@ let QuestionsService = class QuestionsService {
         return out;
     }
     /**
-     * 在调用方的事务内（`mandatory`）取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
-     * 即「其作为处理人」的提问；成员离职时调用），走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、
-     * 写 `question_answered{cancelled}`。返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件。
+     * The conversations of `orgId` holding a pending question of a run `accountId` started (only the
+     * run's starter answers), read without locks: offboarding locks them, by tree root first
+     * (`lockConversationTrees`), before {@link cancelPendingFor}.
      */
-    async cancelPendingFor(orgId, accountId) {
-        const t = this.db.db;
-        // the conversations first, in id order (lock order D7: conversation, then question rows)
-        const convs = await t
+    async pendingConversationsFor(orgId, accountId) {
+        const rows = await this.db
             .selectFrom("questions")
             .select("conversation_id")
             .distinct()
@@ -330,24 +337,28 @@ let QuestionsService = class QuestionsService {
             .where("status", "=", "pending")
             .where("run_id", "in", (eb) => eb.selectFrom("runs").select("id").where("trigger_account_id", "=", accountId))
             .execute();
-        if (convs.length > 0) {
-            await t
-                .selectFrom("conversations")
-                .select("id")
-                .where("id", "in", convs.map((c) => c.conversation_id))
-                .orderBy("id")
-                .forUpdate()
-                .execute();
-        }
-        // only the conversations locked above: a question asked meanwhile in another one waits for
-        // the run's stop (offboarding aborts it) or the sweep, so no conversation is locked after a row
+        return rows.map((r) => r.conversation_id);
+    }
+    /**
+     * In the caller's transaction (`mandatory`; offboarding): cancels every pending question of a run
+     * `accountId` started in `orgId` within `conversationIds`, the conversations the caller already
+     * locked (by tree root first, `lockConversationTrees`; lock order D7: conversation, then question
+     * rows), along the same path as {@link cancelPendingIn}: `cancelled`,
+     * `question_answered{cancelled}`. A question asked meanwhile in another conversation waits for
+     * its run's stop (offboarding owes it), so no conversation is locked after a row. Returns the
+     * cancelled records and the highest seq written per conversation; the caller publishes after the
+     * commit.
+     */
+    async cancelPendingFor(orgId, accountId, conversationIds) {
+        const t = this.db.db;
+        const convs = [...conversationIds];
         if (convs.length === 0)
             return { records: [], seqs: new Map() };
         const rows = await t
             .selectFrom("questions")
             .selectAll()
             .where("org_id", "=", orgId)
-            .where("conversation_id", "in", convs.map((c) => c.conversation_id))
+            .where("conversation_id", "in", convs)
             .where("status", "=", "pending")
             .where("run_id", "in", (eb) => eb.selectFrom("runs").select("id").where("trigger_account_id", "=", accountId))
             .orderBy("created_at")
@@ -375,8 +386,10 @@ let QuestionsService = class QuestionsService {
      * by a run of it that is `running` or `waiting` and was started by `accountId`. The caller holds
      * the conversation row lock (its `appendIn`), so only questions logged before the message are
      * seen. Each becomes `skipped` with `question_answered { outcome: "skipped", skippedBySeq }`.
-     * Returns the records and the highest seq written (null: none); the caller notifies and emits
-     * `question.answered` after the commit.
+     * The caller resumes their waiting runs in this transaction after it locked every row it skips
+     * (`ConversationsService.skipWaitsIn`: conversations, decided rows, runs). Returns the records and
+     * the highest seq written (null: none); the caller notifies and emits `question.answered` after
+     * the commit.
      */
     async skipPendingIn(conversationId, accountId, messageSeq) {
         const t = this.db.db;
@@ -451,6 +464,7 @@ QuestionsService = __decorate([
     __param(1, Inject(KernelConfigService)),
     __param(2, Inject(EventLog)),
     __param(3, Inject(KernelEvents)),
-    __param(4, Inject(TransactionHost))
+    __param(4, Inject(TransactionHost)),
+    __param(5, Inject(RunResume))
 ], QuestionsService);
 export { QuestionsService };

package/dist/tools/registry.d.ts

@@ -1,4 +1,4 @@
-import type { Connector, HookParentScope, InputRequired, NetworkBlockedHost, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { Connector, ConversationSource, HookParentScope, InputRequired, NetworkBlockedHost, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
 import { type AgentDefinition, type DisabledToolRef, type SubagentTools } from "../agents/definition.js";
 import type { ToolView } from "../conversations/events.js";
 import { EffectiveConfigs } from "../extensions/effective-config.js";
@@ -40,6 +40,8 @@ export interface BuiltinCallContext extends ToolCallContext {
     /**
      * 本次运行的截止时间（epoch 毫秒，`runtime.maxRunSeconds` 起算，Ruling M20）。到点运行被中止；
      * 沙箱命令按它收紧超时，赶在截止前自己超时、给模型可执行的说明。
+     * Absent when the run has no duration limit (`runtime.maxRunSeconds` 0): commands are then limited
+     * only by `sandbox.limits.maxCommandSeconds` and the tool timeouts.
      */
     runDeadline?: number;
     /**
@@ -211,6 +213,8 @@ export declare function withoutDisplayFields<T>(spec: T): T;
 export declare function specHash(spec: unknown): string;
 /** 由注解推导默认策略：只读 → allow；其余（破坏性 / 无注解）→ ask。 */
 export declare function policyFromAnnotations(a: ToolAnnotations | undefined): "allow" | "ask";
+/** Why an extension tool limited by `spec.sources` is not offered in a `source` conversation. */
+export declare const sourceHiddenReason: (source: ConversationSource) => string;
 /** `forAgent` 的结果。 */
 export interface AgentTools {
     tools: ResolvedTool[];
@@ -236,7 +240,7 @@ export interface AgentTools {
  *
  * What is offered:
  * - builtins: every {@link AGENT_BUILTIN_NAMES} entry registered here that can run (`unavailable`
- *   says why not), `TaskOutput` / `TaskStop` with `Bash`, `Agent` while its roster is not empty;
+ *   says why not), `TaskOutput` / `TaskStop` / `TaskList` with `Bash`, `Agent` while its roster is not empty;
  * - extension tools: every tool registered by an extension loaded on this replica and enabled in
  *   the org (`extension_org_configs.enabled`; required bootstrap plugins are enabled in every org,
  *   `enabled.ts`), whose effective config for the org is valid (layering spec A §6) and that the
@@ -360,6 +364,11 @@ export declare class ToolRegistry {
         sandboxConversationId?: string;
         /** An eval replay's listing: its calls are never executed (the sandbox tools are listed). */
         replay?: boolean;
+        /**
+         * The conversation's source (memory plugin spec §6.2): an extension tool whose
+         * `spec.sources` leaves it out is hidden. Required, so nothing defaults to the widest.
+         */
+        source: ConversationSource;
     }): Promise<AgentTools>;
     /** 是否启用 `ToolSearch`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     private searchActive;
@@ -380,7 +389,7 @@ export declare class ToolRegistry {
 }
 /**
  * `tools` narrowed by a sub-agent's key filter (tools default-on spec §4): `deny` keys removed,
- * and with `allow` only its keys kept. `TaskOutput` / `TaskStop` follow `Bash`, as they come with
+ * and with `allow` only its keys kept. `TaskOutput` / `TaskStop` / `TaskList` follow `Bash`, as they come with
  * it. Without a filter the list is returned as it is.
  */
 export declare function filterSubagentTools(tools: ResolvedTool[], filter: SubagentTools | undefined): ResolvedTool[];

package/dist/tools/registry.js

@@ -59,6 +59,8 @@ export function specHash(spec) {
 export function policyFromAnnotations(a) {
     return a?.readOnlyHint === true ? "allow" : "ask";
 }
+/** Why an extension tool limited by `spec.sources` is not offered in a `source` conversation. */
+export const sourceHiddenReason = (source) => `Not available in ${source} conversations`;
 // `ToolSearch` is added by the registry by org setting and threshold, `Skill` when the log has a
 // skills catalog snapshot; neither comes from agent definitions (`./builtin-names.ts`).
 /** 工具定义（模型可见三项）的估算 token 数（与请求估算同一口径）。 */
@@ -92,7 +94,7 @@ const builtinTool = (b, spec) => ({
  *
  * What is offered:
  * - builtins: every {@link AGENT_BUILTIN_NAMES} entry registered here that can run (`unavailable`
- *   says why not), `TaskOutput` / `TaskStop` with `Bash`, `Agent` while its roster is not empty;
+ *   says why not), `TaskOutput` / `TaskStop` / `TaskList` with `Bash`, `Agent` while its roster is not empty;
  * - extension tools: every tool registered by an extension loaded on this replica and enabled in
  *   the org (`extension_org_configs.enabled`; required bootstrap plugins are enabled in every org,
  *   `enabled.ts`), whose effective config for the org is valid (layering spec A §6) and that the
@@ -348,6 +350,7 @@ let ToolRegistry = class ToolRegistry {
     }
     async resolve(orgId, def) {
         const disabled = def.disabledTools ?? [];
+        const { source } = def;
         const scope = {
             orgId,
             ...(def.sandboxConversationId !== undefined && {
@@ -396,7 +399,8 @@ let ToolRegistry = class ToolRegistry {
                 spec = agentToolSpec(roster, await this.maxConcurrentSubagents(orgId));
             }
             add(builtinTool(b, spec));
-            // `TaskOutput` and `TaskStop` come with an available `Bash` (background Bash spec §2)
+            // `TaskOutput`, `TaskStop` and `TaskList` come with an available `Bash` (background Bash
+            // spec §2)
             if (name === BUILTIN.Bash) {
                 for (const companion of BASH_COMPANION_TOOLS) {
                     const c = this.builtins.find((x) => x.spec.name === companion);
@@ -434,6 +438,12 @@ let ToolRegistry = class ToolRegistry {
                     hidden.push({ ref: key, reason: toolTurnedOffReason(key) });
                     continue;
                 }
+                // offered only in some conversation sources; the source never changes, so this also
+                // refuses a resumed call (the pipeline resolves the step's tools with the same source)
+                if (t.spec.sources !== undefined && !t.spec.sources.includes(source)) {
+                    hidden.push({ ref: key, reason: sourceHiddenReason(source) });
+                    continue;
+                }
                 if (!(await configuredIn(t.plugin))) {
                     hidden.push({ ref: key, reason: `Plugin ${t.plugin} ${NEEDS_CONFIG_REASON}` });
                     continue;
@@ -585,7 +595,7 @@ ToolRegistry = __decorate([
 export { ToolRegistry };
 /**
  * `tools` narrowed by a sub-agent's key filter (tools default-on spec §4): `deny` keys removed,
- * and with `allow` only its keys kept. `TaskOutput` / `TaskStop` follow `Bash`, as they come with
+ * and with `allow` only its keys kept. `TaskOutput` / `TaskStop` / `TaskList` follow `Bash`, as they come with
  * it. Without a filter the list is returned as it is.
  */
 export function filterSubagentTools(tools, filter) {