@tintinweb/pi-subagents 0.6.3 → 0.7.1

package/dist/index.js

@@ -23,30 +23,36 @@ import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { SubagentScheduler } from "./schedule.js";
+import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
 import { AgentWidget, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
+import { showSchedulesMenu } from "./ui/schedule-menu.js";
+import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 // ---- Shared helpers ----
 /** Tool execute return value for a text response. */
 function textResult(msg, details) {
     return { content: [{ type: "text", text: msg }], details: details };
 }
-/** Safe token formatting — wraps session.getSessionStats() in try-catch. */
-function safeFormatTokens(session) {
-    if (!session)
-        return "";
-    try {
-        return formatTokens(session.getSessionStats().tokens.total);
-    }
-    catch {
-        return "";
-    }
+/** Format an agent's lifetime token total, or "" when zero. */
+function formatLifetimeTokens(o) {
+    const t = getLifetimeTotal(o.lifetimeUsage);
+    return t > 0 ? formatTokens(t) : "";
 }
 /**
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
  * Used by both foreground and background paths to avoid duplication.
  */
 function createActivityTracker(maxTurns, onStreamUpdate) {
-    const state = { activeTools: new Map(), toolUses: 0, turnCount: 1, maxTurns, tokens: "", responseText: "", session: undefined };
+    const state = {
+        activeTools: new Map(),
+        toolUses: 0,
+        turnCount: 1,
+        maxTurns,
+        responseText: "",
+        session: undefined,
+        lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+    };
     const callbacks = {
         onToolActivity: (activity) => {
             if (activity.type === "start") {
@@ -61,7 +67,6 @@ function createActivityTracker(maxTurns, onStreamUpdate) {
                 }
                 state.toolUses++;
             }
-            state.tokens = safeFormatTokens(state.session);
             onStreamUpdate?.();
         },
         onTextDelta: (_delta, fullText) => {
@@ -75,6 +80,10 @@ function createActivityTracker(maxTurns, onStreamUpdate) {
         onSessionCreated: (session) => {
             state.session = session;
         },
+        onAssistantUsage: (usage) => {
+            addUsage(state.lifetimeUsage, usage);
+            onStreamUpdate?.();
+        },
     };
     return { state, callbacks };
 }
@@ -105,14 +114,10 @@ function escapeXml(s) {
 function formatTaskNotification(record, resultMaxLen) {
     const status = getStatusLabel(record.status, record.error);
     const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
-    let totalTokens = 0;
-    try {
-        if (record.session) {
-            const stats = record.session.getSessionStats();
-            totalTokens = stats.tokens?.total ?? 0;
-        }
-    }
-    catch { /* session stats unavailable */ }
+    const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+    const contextPercent = getSessionContextPercent(record.session);
+    const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+    const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
     const resultPreview = record.result
         ? record.result.length > resultMaxLen
             ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
@@ -126,7 +131,7 @@ function formatTaskNotification(record, resultMaxLen) {
         `<status>${escapeXml(status)}</status>`,
         `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
         `<result>${escapeXml(resultPreview)}</result>`,
-        `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
+        `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
         `</task-notification>`,
     ].filter(Boolean).join('\n');
 }
@@ -135,7 +140,7 @@ function buildDetails(base, record, activity, overrides) {
     return {
         ...base,
         toolUses: record.toolUses,
-        tokens: safeFormatTokens(record.session),
+        tokens: formatLifetimeTokens(record),
         turnCount: activity?.turnCount,
         maxTurns: activity?.maxTurns,
         durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
@@ -147,12 +152,7 @@ function buildDetails(base, record, activity, overrides) {
 }
 /** Build notification details for the custom message renderer. */
 function buildNotificationDetails(record, resultMaxLen, activity) {
-    let totalTokens = 0;
-    try {
-        if (record.session)
-            totalTokens = record.session.getSessionStats().tokens?.total ?? 0;
-    }
-    catch { }
+    const totalTokens = getLifetimeTotal(record.lifetimeUsage);
     return {
         id: record.id,
         description: record.description,
@@ -235,7 +235,10 @@ export default function (pi) {
         cancelNudge(key);
         pendingNudges.set(key, setTimeout(() => {
             pendingNudges.delete(key);
-            send();
+            try {
+                send();
+            }
+            catch { /* ignore stale completion side-effect errors */ }
         }, delay));
     }
     function cancelNudge(key) {
@@ -299,18 +302,15 @@ export default function (pi) {
     /** Helper: build event data for lifecycle events from an AgentRecord. */
     function buildEventData(record) {
         const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
-        let tokens;
-        try {
-            if (record.session) {
-                const stats = record.session.getSessionStats();
-                tokens = {
-                    input: stats.tokens?.input ?? 0,
-                    output: stats.tokens?.output ?? 0,
-                    total: stats.tokens?.total ?? 0,
-                };
-            }
-        }
-        catch { /* session stats unavailable */ }
+        // All three fields are lifetime-accumulated (Σ over every assistant message_end),
+        // so they survive compaction together — input + output ≤ total always.
+        // tokens is omitted when nothing was ever produced (e.g. agent errored before
+        // any message_end fired), preserving prior payload shape.
+        const u = record.lifetimeUsage;
+        const total = getLifetimeTotal(u);
+        const tokens = total > 0
+            ? { input: u.input, output: u.output, total }
+            : undefined;
         return {
             id: record.id,
             type: record.type,
@@ -367,6 +367,16 @@ export default function (pi) {
             type: record.type,
             description: record.description,
         });
+    }, (record, info) => {
+        // Emit compacted event when agent's session compacts (preserves count on record).
+        pi.events.emit("subagents:compacted", {
+            id: record.id,
+            type: record.type,
+            description: record.description,
+            reason: info.reason,
+            tokensBefore: info.tokensBefore,
+            compactionCount: record.compactionCount,
+        });
     });
     // Expose manager via Symbol.for() global registry for cross-package access.
     // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
@@ -379,12 +389,38 @@ export default function (pi) {
     };
     // --- Cross-extension RPC via pi.events ---
     let currentCtx;
-    // Capture ctx from session_start for RPC spawn handler
+    // ---- Subagent scheduler ----
+    // Session-scoped: store is constructed inside session_start once sessionId
+    // is available. Mirrors pi-chonky-tasks's session-scoped task store —
+    // schedules reset on /new, restore on /resume.
+    const scheduler = new SubagentScheduler();
+    function startScheduler(ctx) {
+        try {
+            const sessionId = ctx.sessionManager?.getSessionId?.();
+            if (!sessionId)
+                return; // sessionId not yet available — try again on next event
+            const path = resolveStorePath(ctx.cwd, sessionId);
+            const store = new ScheduleStore(path);
+            scheduler.start(pi, ctx, manager, store);
+            pi.events.emit("subagents:scheduler_ready", { sessionId, jobCount: store.list().length });
+        }
+        catch (err) {
+            // Scheduling is non-essential — log and move on so the rest of the
+            // extension keeps working if e.g. .pi/ is unwritable.
+            console.warn("[pi-subagents] Failed to start scheduler:", err);
+        }
+    }
+    // Capture ctx from session_start for RPC spawn handler + start the scheduler.
     pi.on("session_start", async (_event, ctx) => {
         currentCtx = ctx;
-        manager.clearCompleted(); // preserve existing behavior
+        manager.clearCompleted();
+        if (isSchedulingEnabled() && !scheduler.isActive())
+            startScheduler(ctx);
+    });
+    pi.on("session_before_switch", () => {
+        manager.clearCompleted();
+        scheduler.stop();
     });
-    pi.on("session_before_switch", () => { manager.clearCompleted(); });
     const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
         events: pi.events,
         pi,
@@ -401,6 +437,7 @@ export default function (pi) {
         unsubPingRpc();
         currentCtx = undefined;
         delete globalThis[MANAGER_KEY];
+        scheduler.stop();
         manager.abortAll();
         for (const timer of pendingNudges.values())
             clearTimeout(timer);
@@ -413,6 +450,15 @@ export default function (pi) {
     let defaultJoinMode = 'smart';
     function getDefaultJoinMode() { return defaultJoinMode; }
     function setDefaultJoinMode(mode) { defaultJoinMode = mode; }
+    // Master switch for the schedule subagent feature. Defaults to enabled.
+    // Read once at extension init (before tool registration) so the Agent tool's
+    // param schema reflects the persisted setting. Runtime toggles via /agents
+    // → Settings short-circuit the menu entry + the execute-time addJob path
+    // immediately, but the schema-level removal only takes effect on next
+    // extension load (next pi session). Documented in CHANGELOG/README.
+    let schedulingEnabled = true;
+    function isSchedulingEnabled() { return schedulingEnabled; }
+    function setSchedulingEnabled(b) { schedulingEnabled = b; }
     // ---- Batch tracking for smart join mode ----
     // Collects background agent IDs spawned in the current turn for smart grouping.
     // Uses a debounced timer: each new agent resets the 100ms window so that all
@@ -497,8 +543,25 @@ export default function (pi) {
         setDefaultMaxTurns,
         setGraceTurns,
         setDefaultJoinMode,
+        setSchedulingEnabled,
     }, (event, payload) => pi.events.emit(event, payload));
     // ---- Agent tool ----
+    // Schedule param + its guideline are gated on `schedulingEnabled` (read once
+    // at registration; flipping the setting later requires next pi session for
+    // the schema to update). Defining the shape once and spreading it via Partial
+    // preserves Type.Object's inference when present and produces a
+    // `schedule`-free schema when absent — zero LLM-context cost in disabled mode.
+    const scheduleParamShape = {
+        schedule: Type.Optional(Type.String({
+            description: 'Opt-in only — fire later instead of now. Omit to run immediately (the default, almost always correct). ' +
+                'Formats: 6-field cron ("0 0 9 * * 1" = 9am Mon), interval ("5m"/"1h"), one-shot ("+10m" or ISO). ' +
+                'Forces run_in_background; incompatible with inherit_context and resume. Returns job ID.',
+        })),
+    };
+    const scheduleParam = isSchedulingEnabled() ? scheduleParamShape : {};
+    const scheduleGuideline = isSchedulingEnabled()
+        ? `\n- Use \`schedule\` only when the user explicitly asked for scheduled / recurring / delayed execution (e.g. "every Monday", "in an hour"). Don't auto-schedule from vague intent like "monitor X" — run once now or ask.`
+        : "";
     pi.registerTool(defineTool({
         name: "Agent",
         label: "Agent",
@@ -522,7 +585,7 @@ Guidelines:
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).`,
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).${scheduleGuideline}`,
         parameters: Type.Object({
             prompt: Type.String({
                 description: "The task for the agent to perform.",
@@ -558,6 +621,7 @@ Guidelines:
             isolation: Type.Optional(Type.Literal("worktree", {
                 description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
             })),
+            ...scheduleParam,
         }),
         // ---- Custom rendering: Claude Code style ----
         renderCall(args, theme) {
@@ -700,6 +764,45 @@ Guidelines:
                 modelName: agentModelName,
                 tags: agentTags.length > 0 ? agentTags : undefined,
             };
+            // ---- Schedule: register a job, don't spawn now ----
+            if (params.schedule) {
+                if (!isSchedulingEnabled()) {
+                    return textResult("Scheduling is disabled in this project. Enable via /agents → Settings → Scheduling.");
+                }
+                if (params.resume) {
+                    return textResult("Cannot combine `schedule` with `resume` — schedules create fresh agents.");
+                }
+                if (params.inherit_context) {
+                    return textResult("Cannot combine `schedule` with `inherit_context` — there is no parent conversation at fire time.");
+                }
+                if (params.run_in_background === false) {
+                    return textResult("Cannot combine `schedule` with `run_in_background: false` — scheduled jobs always run in background.");
+                }
+                if (!scheduler.isActive()) {
+                    return textResult("Scheduler is not active in this session yet. Try again after the session has fully started.");
+                }
+                try {
+                    const job = scheduler.addJob({
+                        name: params.description,
+                        description: params.description,
+                        schedule: params.schedule,
+                        subagent_type: subagentType,
+                        prompt: params.prompt,
+                        model: params.model,
+                        thinking: thinking,
+                        max_turns: effectiveMaxTurns,
+                        isolated: isolated,
+                        isolation: isolation,
+                    });
+                    const next = scheduler.getNextRun(job.id);
+                    return textResult(`Scheduled "${job.name}" (id: ${job.id}, type: ${job.scheduleType}). ` +
+                        `Next run: ${next ?? "(unknown)"}. ` +
+                        `Manage via /agents → Scheduled jobs.`);
+                }
+                catch (err) {
+                    return textResult(err instanceof Error ? err.message : String(err));
+                }
+            }
             // Resume existing agent
             if (params.resume) {
                 const existing = manager.getRecord(params.resume);
@@ -730,17 +833,22 @@ Guidelines:
                         rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
                     }
                 };
-                id = manager.spawn(pi, ctx, subagentType, params.prompt, {
-                    description: params.description,
-                    model,
-                    maxTurns: effectiveMaxTurns,
-                    isolated,
-                    inheritContext,
-                    thinkingLevel: thinking,
-                    isBackground: true,
-                    isolation,
-                    ...bgCallbacks,
-                });
+                try {
+                    id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+                        description: params.description,
+                        model,
+                        maxTurns: effectiveMaxTurns,
+                        isolated,
+                        inheritContext,
+                        thinkingLevel: thinking,
+                        isBackground: true,
+                        isolation,
+                        ...bgCallbacks,
+                    });
+                }
+                catch (err) {
+                    return textResult(err instanceof Error ? err.message : String(err));
+                }
                 // Set output file + join mode synchronously after spawn, before the
                 // event loop yields — onSessionCreated is async so this is safe.
                 const joinMode = resolveJoinMode(defaultJoinMode, true);
@@ -792,7 +900,7 @@ Guidelines:
                 const details = {
                     ...detailBase,
                     toolUses: fgState.toolUses,
-                    tokens: fgState.tokens,
+                    tokens: formatLifetimeTokens(fgState),
                     turnCount: fgState.turnCount,
                     maxTurns: fgState.maxTurns,
                     durationMs: Date.now() - startedAt,
@@ -825,16 +933,24 @@ Guidelines:
                 streamUpdate();
             }, 80);
             streamUpdate();
-            const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
-                description: params.description,
-                model,
-                maxTurns: effectiveMaxTurns,
-                isolated,
-                inheritContext,
-                thinkingLevel: thinking,
-                isolation,
-                ...fgCallbacks,
-            });
+            let record;
+            try {
+                record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+                    description: params.description,
+                    model,
+                    maxTurns: effectiveMaxTurns,
+                    isolated,
+                    inheritContext,
+                    thinkingLevel: thinking,
+                    isolation,
+                    signal,
+                    ...fgCallbacks,
+                });
+            }
+            catch (err) {
+                clearInterval(spinnerInterval);
+                return textResult(err instanceof Error ? err.message : String(err));
+            }
             clearInterval(spinnerInterval);
             // Clean up foreground agent from widget
             if (fgId) {
@@ -842,7 +958,7 @@ Guidelines:
                 widget.markFinished(fgId);
             }
             // Get final token count
-            const tokenText = safeFormatTokens(fgState.session);
+            const tokenText = formatLifetimeTokens(fgState);
             const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
             const fallbackNote = fellBack
                 ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
@@ -890,10 +1006,18 @@ Guidelines:
             }
             const displayName = getDisplayName(record.type);
             const duration = formatDuration(record.startedAt, record.completedAt);
-            const tokens = safeFormatTokens(record.session);
-            const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
+            const tokens = formatLifetimeTokens(record);
+            const contextPercent = getSessionContextPercent(record.session);
+            const statsParts = [`Tool uses: ${record.toolUses}`];
+            if (tokens)
+                statsParts.push(tokens);
+            if (contextPercent !== null)
+                statsParts.push(`Context: ${Math.round(contextPercent)}%`);
+            if (record.compactionCount)
+                statsParts.push(`Compactions: ${record.compactionCount}`);
+            statsParts.push(`Duration: ${duration}`);
             let output = `Agent: ${record.id}\n` +
-                `Type: ${displayName} | Status: ${record.status} | ${toolStats} | Duration: ${duration}\n` +
+                `Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
                 `Description: ${record.description}\n\n`;
             if (record.status === "running") {
                 output += "Agent is still running. Use wait: true or check back later.";
@@ -952,7 +1076,18 @@ Guidelines:
             try {
                 await steerAgent(record.session, params.message);
                 pi.events.emit("subagents:steered", { id: record.id, message: params.message });
-                return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.`);
+                const tokens = formatLifetimeTokens(record);
+                const contextPercent = getSessionContextPercent(record.session);
+                const stateParts = [];
+                if (tokens)
+                    stateParts.push(tokens);
+                stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
+                if (contextPercent !== null)
+                    stateParts.push(`context ${Math.round(contextPercent)}% full`);
+                if (record.compactionCount)
+                    stateParts.push(`${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`);
+                return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+                    `Current state: ${stateParts.join(" · ")}`);
             }
             catch (err) {
                 return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
@@ -1000,6 +1135,11 @@ Guidelines:
         if (allNames.length > 0) {
             options.push(`Agent types (${allNames.length})`);
         }
+        // Scheduled jobs entry (always present when scheduler is active)
+        if (scheduler.isActive()) {
+            const jobCount = scheduler.list().length;
+            options.push(`Scheduled jobs (${jobCount})`);
+        }
         // Actions
         options.push("Create new agent");
         options.push("Settings");
@@ -1022,6 +1162,10 @@ Guidelines:
             await showAllAgentsList(ctx);
             await showAgentsMenu(ctx);
         }
+        else if (choice.startsWith("Scheduled jobs (")) {
+            await showSchedulesMenu(ctx, scheduler);
+            await showAgentsMenu(ctx);
+        }
         else if (choice === "Create new agent") {
             await showCreateWizard(ctx);
         }
@@ -1480,6 +1624,7 @@ ${systemPrompt}
             defaultMaxTurns: getDefaultMaxTurns() ?? 0,
             graceTurns: getGraceTurns(),
             defaultJoinMode: getDefaultJoinMode(),
+            schedulingEnabled: isSchedulingEnabled(),
         };
     }
     async function showSettings(ctx) {
@@ -1488,6 +1633,7 @@ ${systemPrompt}
             `Default max turns (current: ${getDefaultMaxTurns() ?? "unlimited"})`,
             `Grace turns (current: ${getGraceTurns()})`,
             `Join mode (current: ${getDefaultJoinMode()})`,
+            `Scheduling (current: ${isSchedulingEnabled() ? "enabled" : "disabled"})`,
         ]);
         if (!choice)
             return;
@@ -1546,6 +1692,24 @@ ${systemPrompt}
                 notifyApplied(ctx, `Default join mode set to ${mode}`);
             }
         }
+        else if (choice.startsWith("Scheduling")) {
+            const val = await ctx.ui.select("Schedule subagent feature", [
+                "enabled — Agent tool accepts a `schedule` param; /agents → Scheduled jobs visible",
+                "disabled — `schedule` removed from Agent tool spec (no LLM-context cost); menu hidden",
+            ]);
+            if (val) {
+                const enabled = val.startsWith("enabled");
+                if (enabled === isSchedulingEnabled()) {
+                    ctx.ui.notify(`Scheduling already ${enabled ? "enabled" : "disabled"}.`, "info");
+                }
+                else {
+                    setSchedulingEnabled(enabled);
+                    if (!enabled)
+                        scheduler.stop(); // immediate kill — outstanding fires stop ticking
+                    notifyApplied(ctx, `Scheduling ${enabled ? "enabled" : "disabled"}. Tool spec change takes effect on next pi session.`);
+                }
+            }
+        }
     }
     // Persist the current snapshot, emit `subagents:settings_changed`, and surface
     // the right toast. Successful saves show info; persistence failures downgrade

package/dist/schedule-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+import type { ScheduledSubagent } from "./types.js";
+/** Resolve the storage path for a session-scoped store. */
+export declare function resolveStorePath(cwd: string, sessionId: string): string;
+export declare class ScheduleStore {
+    private filePath;
+    private lockPath;
+    private jobs;
+    constructor(filePath: string);
+    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    private load;
+    /** Atomic write via temp file + rename (POSIX-atomic). */
+    private save;
+    /** Acquire lock → reload → mutate → save → release. */
+    private withLock;
+    /** Read-only — returns a snapshot of the in-memory cache. */
+    list(): ScheduledSubagent[];
+    /** Read-only check — uses the cache. */
+    hasName(name: string, exceptId?: string): boolean;
+    get(id: string): ScheduledSubagent | undefined;
+    add(job: ScheduledSubagent): void;
+    update(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined;
+    remove(id: string): boolean;
+    /** Delete the backing file (used when no jobs remain, optional cleanup). */
+    deleteFileIfEmpty(): void;
+}