@diffexai/diffex 0.2.6 → 0.3.0

package/dist/core/subagents/controller.js

@@ -1,6 +1,6 @@
 import { NOOP_TELEMETRY_CONTEXT, uuidv7 } from "@diffexai/diffex-agent-core";
 import { startCodingAgentSpan } from "../telemetry.js";
-import { createAgentActionTool, createAgentsTool, createSpawnAgentTool } from "../tools/subagents.js";
+import { createAgentActionTool, createAgentStatusTool, createSpawnAgentTool } from "../tools/subagents.js";
 import { reportSubagentRuntimeWarning } from "./runtime-diagnostics.js";
 import { SUBAGENT_NAME_PATTERN } from "./types.js";
 function normalizeError(error) {
@@ -57,6 +57,9 @@ function captureSpawnOrigin(parent, toolCallId) {
 const MAX_TIMER_MS = 2_147_483_647;
 export class SubagentController {
     #maxConcurrent;
+    #leaseMs;
+    #supervisionIntervalMs;
+    #parentDeadline;
     #captureSession;
     #persistRoster;
     #restoreRoster;
@@ -83,6 +86,20 @@ export class SubagentController {
             throw new RangeError("maxConcurrent must be a positive integer");
         }
         this.#maxConcurrent = options.maxConcurrent;
+        this.#leaseMs = options.leaseMs ?? 15 * 60_000;
+        this.#supervisionIntervalMs = options.supervisionIntervalMs ?? 120_000;
+        for (const [name, value] of [
+            ["leaseMs", this.#leaseMs],
+            ["supervisionIntervalMs", this.#supervisionIntervalMs],
+        ]) {
+            if (!Number.isInteger(value) || value <= 0 || value > MAX_TIMER_MS)
+                throw new RangeError(`${name} must be a positive timer-safe integer`);
+        }
+        if (options.parentDeadline !== undefined &&
+            (!Number.isSafeInteger(options.parentDeadline) || options.parentDeadline <= 0)) {
+            throw new RangeError("parentDeadline must be a positive Unix timestamp in milliseconds");
+        }
+        this.#parentDeadline = options.parentDeadline;
         this.#captureSession = options.captureSession;
         this.#telemetryContext = options.telemetryContext ?? NOOP_TELEMETRY_CONTEXT;
         this.#persistRoster = options.persistRoster;
@@ -102,12 +119,14 @@ export class SubagentController {
             }, () => this.#assertParentPolicyCompatible()),
             createAgentActionTool((request) => {
                 const parent = this.#getBoundParent();
+                if (request.action === "renew")
+                    return this.renew(request.target, request.reason);
                 return request.action === "message"
-                    ? this.message(request.target, request.message, request.wake, parent.isStreaming)
+                    ? this.message(request.target, request.message, request.wake, parent.isStreaming, request.delivery)
                     : this.interrupt(request.target);
             }),
-            createAgentsTool(async (options) => {
-                const result = await this.queryAgents(options);
+            createAgentStatusTool(async (options) => {
+                const result = await this.queryAgents({ ...options, timeoutMs: 0 });
                 this.#consumeTerminalQueryResults(result);
                 return result;
             }),
@@ -236,14 +255,84 @@ export class SubagentController {
         });
         this.#scheduleRun(record, task);
     }
-    message(name, message, wake = false, coordinated = false) {
+    message(name, message, wake = false, coordinated = false, delivery = "steer") {
         if (message.trim().length === 0) {
             return Promise.reject(new Error("Subagent message must be non-empty"));
         }
-        return this.#serializeAction(name, () => this.#traceAction(name, "message", () => this.#message(name, message, wake, coordinated)));
+        return this.#serializeAction(name, () => this.#traceAction(name, "message", () => this.#message(name, message, wake, coordinated, delivery)));
     }
     interrupt(name) {
-        return this.#serializeAction(name, () => this.#traceAction(name, "interrupt", () => this.#interrupt(name)));
+        // Cancellation must not wait behind a message waiting for construction or a permit.
+        return this.#traceAction(name, "interrupt", () => this.#interrupt(name));
+    }
+    async renew(name, reason) {
+        const record = this.#getRecordForAction(name);
+        if (!reason.trim())
+            throw new Error("Lease renewal requires a justification");
+        const supervision = record.supervision;
+        if (!supervision ||
+            isTerminalStatus(record.status) ||
+            record.interruptionRequested ||
+            supervision.deadline <= Date.now()) {
+            throw new Error(`Cannot renew inactive or expired subagent: ${name}`);
+        }
+        const deadline = Math.min(supervision.deadline + this.#leaseMs, this.#parentDeadline ?? Infinity);
+        if (deadline > supervision.deadline) {
+            supervision.deadline = deadline;
+            supervision.checkpointRequested = false;
+            this.#armLease(record);
+        }
+        return { target: name, action: "renew", status: record.status, deadline: supervision.deadline };
+    }
+    #armLease(record) {
+        const supervision = record.supervision;
+        if (!supervision)
+            return;
+        clearTimeout(supervision.leaseTimer);
+        supervision.leaseTimer = setTimeout(() => {
+            if (record.supervision !== supervision || isTerminalStatus(record.status))
+                return;
+            if (supervision.deadline > Date.now()) {
+                this.#armLease(record);
+                return;
+            }
+            record.runtimeWarning = "Subagent lease or parent deadline expired; cancellation requested";
+            void this.interrupt(record.name).catch((error) => {
+                record.runtimeWarning = `Subagent cancellation failed: ${normalizeError(error)}`;
+            });
+        }, Math.min(MAX_TIMER_MS, Math.max(0, supervision.deadline - Date.now())));
+        supervision.leaseTimer.unref();
+    }
+    #stopSupervision(record) {
+        clearTimeout(record.supervision?.leaseTimer);
+        clearInterval(record.supervision?.reportTimer);
+    }
+    async #reportActivity(record) {
+        const supervision = record.supervision;
+        if (!supervision || supervision.reporting || isTerminalStatus(record.status) || this.#closed || this.#resetting)
+            return;
+        supervision.reporting = true;
+        try {
+            const now = Date.now();
+            const remaining = Math.max(0, supervision.deadline - now);
+            await this.#deliverEscalation?.(record.name, `Runtime supervision: ${JSON.stringify({
+                status: record.status,
+                elapsed_ms: now - supervision.startedAt,
+                inactive_ms: now - supervision.lastActivityAt,
+            })}`);
+            if (!supervision.checkpointRequested &&
+                remaining <= Math.max(this.#supervisionIntervalMs * 2, this.#leaseMs / 5) &&
+                record.status === "running") {
+                supervision.checkpointRequested = true;
+                await record.session?.steer("Your work allowance is nearly exhausted. If needed work remains, call escalate_to_parent with a concise checkpoint: current progress, remaining work, the goal, and the decision or extension needed. Otherwise finish.");
+            }
+        }
+        catch (error) {
+            record.runtimeWarning = `Subagent supervision delivery failed: ${normalizeError(error)}`;
+        }
+        finally {
+            supervision.reporting = false;
+        }
     }
     attachSession(name, session) {
         const record = this.#getRecordForUpdate(name);
@@ -424,7 +513,11 @@ export class SubagentController {
             (options.until !== undefined && this.#queryConditionMet(result.agents, options.until))) {
             return result;
         }
-        const deadline = performance.now() + options.timeoutMs;
+        // Return control periodically so supervision can reach a parent inside a long wait tool.
+        const timeoutMs = this.#deliverEscalation
+            ? Math.min(options.timeoutMs, this.#supervisionIntervalMs)
+            : options.timeoutMs;
+        const deadline = performance.now() + timeoutMs;
         while (true) {
             const remainingMs = Math.min(deadline - performance.now(), MAX_TIMER_MS);
             if (remainingMs <= 0) {
@@ -703,6 +796,7 @@ export class SubagentController {
             record.error = undefined;
         }
         else {
+            this.#stopSupervision(record);
             record.completedAt = timestamp;
             record.finalText = fields.finalText;
             record.error = status === "failed" ? fields.error : undefined;
@@ -1030,8 +1124,9 @@ export class SubagentController {
             }
         });
     }
-    async #message(name, message, wake, coordinated) {
+    async #message(name, message, wake, coordinated, delivery) {
         const record = this.#getRecordForAction(name);
+        const admittedRun = record.runController;
         while (record.status === "queued" && record.session) {
             const snapshot = this.snapshot();
             if (record.status !== "queued")
@@ -1045,6 +1140,9 @@ export class SubagentController {
             await record.run;
             this.#assertOpen();
         }
+        admittedRun?.signal.throwIfAborted();
+        if (admittedRun && record.interruptionRequested)
+            throw new Error(`Subagent interrupted: ${name}`);
         if (wake && isTerminalStatus(record.status) && record.coordinatedRun?.delivery === "frozen") {
             throw new Error(`Cannot wake subagent while its coordinated result is pending delivery: ${name}`);
         }
@@ -1055,6 +1153,9 @@ export class SubagentController {
             if (!wake)
                 throw new Error(`Cannot message restored subagent without wake: ${name}`);
             const prepared = await record.prepareWake();
+            admittedRun?.signal.throwIfAborted();
+            if (admittedRun && record.interruptionRequested)
+                throw new Error(`Subagent interrupted: ${name}`);
             record.createSession = prepared.createSession;
             record.sessionManager = prepared.sessionManager;
             record.persistenceConfig = prepared.config;
@@ -1076,13 +1177,15 @@ export class SubagentController {
                 record.coordinatedRun = this.#createCoordinatedRun("retry");
             }
             else {
-                record.coordinatedRun = undefined;
+                record.coordinatedRun =
+                    coordinated && record.coordinatedRun ? this.#createCoordinatedRun("initial") : undefined;
             }
             this.#scheduleRun(record, message);
             return { target: name, action: "message", status: "queued", delivery: "prompt" };
         }
         if (record.status === "idle" && wake) {
-            record.coordinatedRun = undefined;
+            record.coordinatedRun =
+                coordinated && record.coordinatedRun ? this.#createCoordinatedRun("initial") : undefined;
             this.#scheduleRun(record, message);
             return { target: name, action: "message", status: "queued", delivery: "prompt" };
         }
@@ -1091,10 +1194,12 @@ export class SubagentController {
             throw new Error(`Subagent session is unavailable: ${name}`);
         }
         if (record.status === "idle") {
+            if (delivery === "steer")
+                throw new Error(`Cannot steer idle subagent without wake: ${name}`);
             await session.followUp(message);
             return { target: name, action: "message", status: "idle", delivery: "follow_up" };
         }
-        if (wake) {
+        if (delivery === "steer") {
             await session.steer(message);
             return { target: name, action: "message", status: "running", delivery: "steer" };
         }
@@ -1113,12 +1218,7 @@ export class SubagentController {
         }
         record.interruptionRequested = true;
         const run = record.run;
-        try {
-            await this.#requestRunCancellation(record, new Error(`Subagent interrupted: ${name}`));
-        }
-        catch {
-            // The captured run still determines the settled controller state.
-        }
+        await this.#requestRunCancellation(record, new Error(`Subagent interrupted: ${name}`));
         await run;
         if (record.status === "queued" || record.status === "running") {
             this.markInterrupted(name);
@@ -1134,6 +1234,23 @@ export class SubagentController {
         const runController = new AbortController();
         record.runController = runController;
         record.runCancellation = undefined;
+        const now = Date.now();
+        record.supervision = {
+            deadline: Math.min(now + this.#leaseMs, this.#parentDeadline ?? Infinity),
+            startedAt: now,
+            lastActivityAt: now,
+            checkpointRequested: false,
+            reporting: false,
+        };
+        if (record.supervision.deadline <= now) {
+            record.interruptionRequested = true;
+            runController.abort(new Error("Parent deadline has already expired"));
+        }
+        this.#armLease(record);
+        record.supervision.reportTimer = setInterval(() => {
+            void this.#reportActivity(record);
+        }, this.#supervisionIntervalMs);
+        record.supervision.reportTimer.unref();
         const run = this.#runPrompt(record, prompt, runController);
         record.run = run;
         void run.catch(() => { });
@@ -1164,6 +1281,7 @@ export class SubagentController {
         let session = record.session;
         let createdSession;
         const assistantMessages = [];
+        let shellTerminationFailed = false;
         let unsubscribe;
         try {
             permit = await this.acquirePermit(runController.signal);
@@ -1193,10 +1311,22 @@ export class SubagentController {
             const activeSession = session;
             let running = false;
             unsubscribe = activeSession.subscribe((event) => {
+                const supervision = record.supervision;
+                if (supervision) {
+                    if ([
+                        "message_update",
+                        "message_end",
+                        "tool_execution_start",
+                        "tool_execution_update",
+                        "tool_execution_end",
+                    ].includes(event.type))
+                        supervision.lastActivityAt = Date.now();
+                }
                 if (event.type === "agent_start" && !running) {
                     running = true;
-                    if (runController.signal.aborted) {
-                        void activeSession.abort().catch(() => { });
+                    if (runController.signal.aborted || record.interruptionRequested) {
+                        if (!record.runCancellation)
+                            void activeSession.abort().catch(() => { });
                     }
                     else {
                         this.markRunning(record.name);
@@ -1206,7 +1336,18 @@ export class SubagentController {
                     assistantMessages.push(event.message);
                 }
             });
-            await activeSession.prompt(prompt, { signal: runController.signal });
+            const [promptResult] = await Promise.allSettled([
+                activeSession.prompt(prompt, { signal: runController.signal }),
+            ]);
+            try {
+                await activeSession.terminateOwnedShellProcesses();
+            }
+            catch (error) {
+                shellTerminationFailed = true;
+                throw error;
+            }
+            if (promptResult.status === "rejected")
+                throw promptResult.reason;
             if (this.#closed)
                 return;
             const terminalMessage = assistantMessages.at(-1);
@@ -1230,7 +1371,7 @@ export class SubagentController {
         catch (error) {
             if (!this.#closed) {
                 const finalText = getAssistantText(assistantMessages.at(-1));
-                if (record.interruptionRequested) {
+                if (record.interruptionRequested && !shellTerminationFailed) {
                     this.markInterrupted(record.name, finalText);
                 }
                 else {
@@ -1270,6 +1411,7 @@ export class SubagentController {
     #detachRecords(reason) {
         const records = [...this.#records.values()];
         for (const record of records) {
+            this.#stopSupervision(record);
             void this.#requestRunCancellation(record, reason);
         }
         this.#records.clear();
@@ -1278,23 +1420,17 @@ export class SubagentController {
     #requestRunCancellation(record, reason) {
         if (record.runCancellation)
             return record.runCancellation;
+        record.interruptionRequested = true;
         let cancellation;
-        // AgentSession marks streaming before awaiting agent_start hooks, while this record can still be queued.
-        if (record.runController && !record.session?.isStreaming) {
-            record.runController.abort(reason);
-            cancellation = Promise.resolve();
-        }
-        else if (record.session) {
-            try {
-                cancellation = record.session.abort();
-            }
-            catch (error) {
-                cancellation = Promise.reject(error);
-            }
+        try {
+            // Active prompts own their cancellation and verification. Abort the run signal
+            // only during construction/preflight, avoiding a second abort via its listener.
+            if (!record.session?.isStreaming)
+                record.runController?.abort(reason);
+            cancellation = record.session?.abort() ?? Promise.resolve();
         }
-        else {
-            record.runController?.abort(reason);
-            cancellation = Promise.resolve();
+        catch (error) {
+            cancellation = Promise.reject(error);
         }
         record.runCancellation = cancellation;
         void cancellation.catch(() => {

package/dist/core/subagents/types.d.ts

@@ -3,6 +3,14 @@ import type { AgentSession } from "../agent-session.ts";
 import type { SessionManager } from "../session-manager.ts";
 import type { ToolName } from "../tools/index.ts";
 export declare const SUBAGENT_NAME_PATTERN: RegExp;
+export interface SubagentSupervisionOptions {
+    /** Renewable allowance per child run, including queueing. Default: 15 minutes. */
+    leaseMs?: number;
+    /** Runtime activity reports to the parent. Default: 2 minutes. */
+    supervisionIntervalMs?: number;
+    /** Absolute parent deadline, in milliseconds since the Unix epoch. */
+    parentDeadline?: number;
+}
 export type SubagentStatus = "queued" | "running" | "idle" | "failed" | "interrupted";
 export interface SubagentSummary {
     readonly name: string;
@@ -41,6 +49,11 @@ export type SubagentSpawnOrigin = {
 export type CaptureSubagentSession = (parent: AgentSession, childName: string, origin: SubagentSpawnOrigin) => CapturedSubagentSession;
 export type SubagentMessageDelivery = "steer" | "follow_up" | "prompt";
 export type SubagentActionResult = {
+    readonly target: string;
+    readonly action: "renew";
+    readonly status: SubagentStatus;
+    readonly deadline: number;
+} | {
     readonly target: string;
     readonly action: "message";
     readonly status: SubagentStatus;

package/dist/core/tools/bash.d.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@diffexai/diffex-agent-core";
 import { type Static, Type } from "typebox";
+import type { OwnedShellProcesses } from "../../utils/owned-shell-processes.ts";
 import type { ToolDefinition } from "../extensions/types.ts";
 import { type TruncationResult } from "./truncate.ts";
 declare const bashSchema: Type.TObject<{
@@ -44,6 +45,7 @@ export interface BashOperations {
  */
 export declare function createLocalBashOperations(options?: {
     shellPath?: string;
+    owner?: OwnedShellProcesses;
 }): BashOperations;
 export interface BashSpawnContext {
     command: string;
@@ -52,6 +54,8 @@ export interface BashSpawnContext {
 }
 export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
 export interface BashToolOptions {
+    /** Session ownership for cancellation of background shell jobs. */
+    owner?: OwnedShellProcesses;
     /** Custom operations for command execution. Default: local shell */
     operations?: BashOperations;
     /** Command prefix prepended to every command (for example shell setup commands) */

package/dist/core/tools/bash.js

@@ -54,6 +54,7 @@ export function createLocalBashOperations(options) {
             catch {
                 throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
             }
+            signal?.throwIfAborted();
             const commandFromStdin = shellConfig.commandTransport === "stdin";
             const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
                 cwd,
@@ -66,8 +67,12 @@ export function createLocalBashOperations(options) {
                 child.stdin?.on("error", () => { });
                 child.stdin?.end(command);
             }
-            if (child.pid)
-                trackDetachedChildPid(child.pid);
+            if (child.pid) {
+                if (options?.owner)
+                    options.owner.track(child.pid);
+                else
+                    trackDetachedChildPid(child.pid);
+            }
             let timedOut = false;
             let timeoutHandle;
             const onAbort = () => {
@@ -105,8 +110,12 @@ export function createLocalBashOperations(options) {
                 return { exitCode };
             }
             finally {
-                if (child.pid)
-                    untrackDetachedChildPid(child.pid);
+                if (child.pid) {
+                    if (options?.owner)
+                        options.owner.releaseIfExited(child.pid);
+                    else
+                        untrackDetachedChildPid(child.pid);
+                }
                 if (timeoutHandle)
                     clearTimeout(timeoutHandle);
                 if (signal)
@@ -223,7 +232,7 @@ function rebuildBashResultRenderComponent(component, result, options, showImages
     }
 }
 export function createBashToolDefinition(cwd, options) {
-    const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });
+    const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath, owner: options?.owner });
     const commandPrefix = options?.commandPrefix;
     const exposeSessionEnvironment = options?.exposeSessionEnvironment ?? true;
     const spawnHook = options?.spawnHook;

package/dist/core/tools/subagents.d.ts

@@ -10,35 +10,37 @@ declare const escalateToParentSchema: Type.TObject<{
 }>;
 declare const agentActionSchema: Type.TObject<{
     target: Type.TString;
-    action: Type.TUnsafe<"interrupt" | "message">;
+    reason: Type.TOptional<Type.TString>;
+    action: Type.TUnsafe<"interrupt" | "message" | "renew">;
     message: Type.TOptional<Type.TString>;
     wake: Type.TOptional<Type.TBoolean>;
+    delivery: Type.TOptional<Type.TUnion<[Type.TLiteral<"steer">, Type.TLiteral<"follow_up">]>>;
 }>;
-declare const agentsSchema: Type.TObject<{
-    timeout_ms: Type.TInteger;
+declare const agentStatusSchema: Type.TObject<{
     targets: Type.TOptional<Type.TArray<Type.TString>>;
-    until: Type.TOptional<Type.TUnion<[Type.TLiteral<"any">, Type.TLiteral<"all">]>>;
 }>;
 export type AgentActionRequest = {
     readonly target: string;
     readonly action: "message";
     readonly message: string;
     readonly wake?: boolean;
+    readonly delivery?: "steer" | "follow_up";
 } | {
     readonly target: string;
     readonly action: "interrupt";
+} | {
+    readonly target: string;
+    readonly action: "renew";
+    readonly reason: string;
 };
 export interface SpawnAgentDetails {
     readonly name: string;
     readonly status: "queued";
 }
-export interface AgentsRequest {
-    readonly timeout_ms: number;
+export interface AgentStatusRequest {
     readonly targets?: string[];
-    readonly until?: "any" | "all";
 }
-export interface AgentsDetails {
-    readonly timed_out: boolean;
+export interface AgentStatusDetails {
     readonly agents: readonly SubagentResultView[];
 }
 export interface EscalateToParentDetails {
@@ -47,5 +49,5 @@ export interface EscalateToParentDetails {
 export declare function createEscalateToParentTool(escalate: SubagentEscalationCallback): ToolDefinition<typeof escalateToParentSchema, EscalateToParentDetails>;
 export declare function createSpawnAgentTool(spawn: (name: string, task: string, toolCallId: string) => void, assertCanSpawn?: () => void): ToolDefinition<typeof spawnAgentSchema, SpawnAgentDetails>;
 export declare function createAgentActionTool(action: (request: AgentActionRequest) => Promise<SubagentActionResult>): ToolDefinition<typeof agentActionSchema, SubagentActionResult>;
-export declare function createAgentsTool(query: (options: SubagentQueryOptions) => Promise<SubagentQueryResult>): ToolDefinition<typeof agentsSchema, AgentsDetails>;
+export declare function createAgentStatusTool(query: (options: Pick<SubagentQueryOptions, "targets" | "signal">) => Promise<SubagentQueryResult>): ToolDefinition<typeof agentStatusSchema, AgentStatusDetails>;
 export {};