@agent-native/core 0.16.1 → 0.16.3

package/dist/server/agent-teams.d.ts

@@ -15,8 +15,11 @@
  * serverless cold starts and works across multiple processes.
  */
 import type { AgentChatEvent } from "../agent/types.js";
-import type { ActionEntry } from "../agent/production-agent.js";
+import type { ActionEntry, AgentLoopFinalResponseGuard } from "../agent/production-agent.js";
 import type { AgentEngine } from "../agent/engine/types.js";
+import type { RunEvent } from "../agent/types.js";
+import type { BackgroundAgentRun, BackgroundAgentRunStatus, BackgroundAgentTranscriptEvent } from "../code-agents/background-run.js";
+import type { BackgroundAgentController } from "../code-agents/index.js";
 export interface AgentTask {
     taskId: string;
     threadId: string;
@@ -27,6 +30,53 @@ export interface AgentTask {
     currentStep: string;
     createdAt: number;
 }
+export type AgentTeamBackgroundRun = Omit<BackgroundAgentRun, "kind" | "source" | "sourceRecord" | "status" | "cwd" | "goalId" | "transcriptPath" | "artifactRoot"> & {
+    kind: "agent-team";
+    source: "hosted-agent-team";
+    sourceRecord: {
+        type: "agent-team-task";
+        id: string;
+        threadId: string;
+    };
+    status: BackgroundAgentRunStatus;
+    cwd?: string;
+    goalId: "agent-team";
+    transcriptPath?: string;
+    artifactRoot?: string;
+};
+export type AgentTeamBackgroundTranscriptEvent = Omit<BackgroundAgentTranscriptEvent, "kind" | "source" | "sourceRecord"> & {
+    kind: "user" | "system" | "note" | "artifact" | "status";
+    source: "hosted-agent-team";
+    sourceRecord: {
+        type: "agent-team-run-event";
+        id: string;
+        seq: number;
+    };
+};
+export interface SendToAgentTeamBackgroundRunResult {
+    ok: boolean;
+    error?: string;
+    messageId?: string;
+    queuedCount?: number;
+}
+export interface ControlAgentTeamBackgroundRunResult {
+    ok: boolean;
+    error?: string;
+}
+export declare function createAgentTeamBackgroundAgentController(): BackgroundAgentController;
+export declare const agentTeamBackgroundAgentController: BackgroundAgentController;
+export interface QueuedTaskMessage {
+    id: string;
+    from: "orchestrator";
+    message: string;
+    timestamp: number;
+}
+declare function formatQueuedTaskMessages(messages: QueuedTaskMessage[]): string;
+declare function drainQueuedTaskMessages(taskId: string): Promise<QueuedTaskMessage[]>;
+declare function createMessageAwareActions(taskId: string, actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
+declare function createTaskMessageFinalGuard(taskId: string): AgentLoopFinalResponseGuard;
+export declare function toAgentTaskBackgroundRun(task: AgentTask): AgentTeamBackgroundRun;
+export declare function toAgentTaskBackgroundTranscriptEvent(runId: string, event: RunEvent): AgentTeamBackgroundTranscriptEvent | null;
 export interface SpawnTaskOptions {
     /** Description of what the sub-agent should do */
     description: string;
@@ -60,11 +110,26 @@ export declare function getTask(taskId: string): Promise<AgentTask | undefined>;
 export declare function getTaskByThread(threadId: string): Promise<AgentTask | undefined>;
 /** List all tasks (most recent first) */
 export declare function listTasks(): Promise<AgentTask[]>;
+export declare function listAgentTeamBackgroundRuns(): Promise<AgentTeamBackgroundRun[]>;
+export declare function getAgentTeamBackgroundRun(runId: string): Promise<AgentTeamBackgroundRun | null>;
+export declare function listAgentTeamBackgroundTranscriptEvents(runId: string): Promise<AgentTeamBackgroundTranscriptEvent[]>;
+export declare function subscribeToAgentTeamBackgroundRun(runId: string, fromSeq?: number): ReadableStream<Uint8Array> | null;
 /** Send a message/update to a running sub-agent via application state */
 export declare function sendToTask(taskId: string, message: string): Promise<{
     ok: boolean;
     error?: string;
+    messageId?: string;
+    queuedCount?: number;
 }>;
+export declare function sendToAgentTeamBackgroundRun(runId: string, message: string): Promise<SendToAgentTeamBackgroundRunResult>;
+export declare function stopAgentTeamBackgroundRun(runId: string, reason?: string): Promise<ControlAgentTeamBackgroundRunResult>;
 /** Mark a task as errored */
 export declare function markTaskErrored(taskId: string, error: string): Promise<void>;
+export declare const _agentTeamsQueueForTests: {
+    createMessageAwareActions: typeof createMessageAwareActions;
+    createTaskMessageFinalGuard: typeof createTaskMessageFinalGuard;
+    drainQueuedTaskMessages: typeof drainQueuedTaskMessages;
+    formatQueuedTaskMessages: typeof formatQueuedTaskMessages;
+};
+export {};
 //# sourceMappingURL=agent-teams.d.ts.map

package/dist/server/agent-teams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-teams.d.ts","sourceRoot":"","sources":["../../src/server/agent-teams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAc3E,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AA8BD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,mFAAmF;IACnF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,UAAU,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC5C,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4R1E;AAED,qBAAqB;AACrB,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAG5E;AAED,4BAA4B;AAC5B,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGhC;AAED,yCAAyC;AACzC,wBAAsB,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAItD;AAED,yEAAyE;AACzE,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB1C;AAED,6BAA6B;AAC7B,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAOf"}
+{"version":3,"file":"agent-teams.d.ts","sourceRoot":"","sources":["../../src/server/agent-teams.ts"],"names":[],"mappings":"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"}

package/dist/server/agent-teams.js

@@ -17,15 +17,164 @@
 import { actionsToEngineTools } from "../agent/production-agent.js";
 import { createAnthropicEngine } from "../agent/engine/anthropic-engine.js";
 import { createThread } from "../chat-threads/store.js";
-import { startRun } from "../agent/run-manager.js";
+import { abortRun, getRun, startRun, subscribeToRun, } from "../agent/run-manager.js";
+import { getRunEventsSince } from "../agent/run-store.js";
 import { runAgentLoop } from "../agent/production-agent.js";
 import { buildAssistantMessage } from "../agent/thread-data-builder.js";
-import { readAppState, writeAppState, listAppState, } from "../application-state/script-helpers.js";
+import { readAppState, writeAppState, listAppState, deleteAppState, } from "../application-state/script-helpers.js";
 import { getRequestUserEmail } from "./request-context.js";
+export function createAgentTeamBackgroundAgentController() {
+    return {
+        async list(options) {
+            if (options?.goalId && options.goalId !== "agent-team")
+                return [];
+            return listAgentTeamBackgroundRuns();
+        },
+        get: getAgentTeamBackgroundRun,
+        transcript: listAgentTeamBackgroundTranscriptEvents,
+        sendFollowUp: sendAgentTeamBackgroundAgentFollowUp,
+        control: controlAgentTeamBackgroundAgentRun,
+    };
+}
+export const agentTeamBackgroundAgentController = createAgentTeamBackgroundAgentController();
 /** Key prefix for task records: agent-task:{taskId} */
 const TASK_PREFIX = "agent-task:";
 /** Key prefix for thread→task reverse lookup: agent-task-thread:{threadId} */
 const THREAD_PREFIX = "agent-task-thread:";
+/** Key prefix for queued orchestrator→sub-agent messages. */
+const TASK_MESSAGE_PREFIX = "task-message:";
+function taskMessageQueuePrefix(taskId) {
+    return `${TASK_MESSAGE_PREFIX}${taskId}:`;
+}
+function generateTaskMessageId() {
+    return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function normalizeQueuedTaskMessage(value, fallbackId) {
+    if (typeof value.message !== "string" || value.message.trim().length === 0) {
+        return null;
+    }
+    const timestamp = typeof value.timestamp === "number" && Number.isFinite(value.timestamp)
+        ? value.timestamp
+        : Date.now();
+    return {
+        id: typeof value.id === "string" ? value.id : fallbackId,
+        from: "orchestrator",
+        message: value.message,
+        timestamp,
+    };
+}
+function formatQueuedTaskMessages(messages) {
+    const label = messages.length === 1
+        ? "Orchestrator message received while you were working"
+        : "Orchestrator messages received while you were working";
+    const body = messages
+        .map((message) => {
+        const sentAt = new Date(message.timestamp).toISOString();
+        return `[${sentAt}] ${message.message}`;
+    })
+        .join("\n\n");
+    return `${label}:\n\n${body}\n\nAdjust your next steps to account for this update.`;
+}
+const taskMessageDrainLocks = new Map();
+async function withTaskMessageDrainLock(taskId, fn) {
+    const previous = taskMessageDrainLocks.get(taskId) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => (release = resolve));
+    taskMessageDrainLocks.set(taskId, current);
+    await previous.catch(() => { });
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (taskMessageDrainLocks.get(taskId) === current) {
+            taskMessageDrainLocks.delete(taskId);
+        }
+    }
+}
+async function listQueuedTaskMessages(taskId) {
+    const queuePrefix = taskMessageQueuePrefix(taskId);
+    const entries = await listAppState(queuePrefix);
+    const messages = entries
+        .map((entry) => {
+        const id = entry.key.slice(queuePrefix.length);
+        const message = normalizeQueuedTaskMessage(entry.value, id);
+        return message ? { key: entry.key, message } : null;
+    })
+        .filter((entry) => Boolean(entry));
+    // Backward compatibility for messages queued by the old implementation.
+    const legacyKey = `${TASK_MESSAGE_PREFIX}${taskId}`;
+    const legacy = await readAppState(legacyKey);
+    const legacyMessage = legacy
+        ? normalizeQueuedTaskMessage(legacy, "legacy")
+        : null;
+    if (legacyMessage) {
+        messages.push({ key: legacyKey, message: legacyMessage });
+    }
+    return messages.sort((a, b) => {
+        const byTimestamp = a.message.timestamp - b.message.timestamp;
+        return byTimestamp || a.message.id.localeCompare(b.message.id);
+    });
+}
+async function drainQueuedTaskMessages(taskId) {
+    return withTaskMessageDrainLock(taskId, async () => {
+        const entries = await listQueuedTaskMessages(taskId);
+        if (entries.length === 0)
+            return [];
+        for (const entry of entries) {
+            await deleteAppState(entry.key);
+        }
+        return entries.map((entry) => entry.message);
+    });
+}
+async function appendQueuedTaskMessage(taskId, message) {
+    const messageId = generateTaskMessageId();
+    await writeAppState(`${taskMessageQueuePrefix(taskId)}${messageId}`, {
+        id: messageId,
+        from: "orchestrator",
+        message,
+        timestamp: Date.now(),
+    });
+    const queuedCount = (await listQueuedTaskMessages(taskId)).length;
+    return { messageId, queuedCount };
+}
+function createMessageAwareActions(taskId, actions) {
+    return Object.fromEntries(Object.entries(actions).map(([name, entry]) => [
+        name,
+        {
+            ...entry,
+            run: async (args, context) => {
+                const result = await entry.run(args, context);
+                const queuedMessages = await drainQueuedTaskMessages(taskId);
+                if (queuedMessages.length === 0)
+                    return result;
+                // Tool results are already the next safe model-visible boundary:
+                // the loop records all tool output, then asks the model to continue.
+                // Attaching queued updates here avoids mutating message history while
+                // an assistant tool-call turn is still being resolved.
+                const formatted = formatQueuedTaskMessages(queuedMessages);
+                const resultText = typeof result === "string"
+                    ? result
+                    : JSON.stringify(result, null, 2);
+                return `${resultText}\n\n${formatted}`;
+            },
+        },
+    ]));
+}
+function createTaskMessageFinalGuard(taskId) {
+    return async () => {
+        const queuedMessages = await drainQueuedTaskMessages(taskId);
+        if (queuedMessages.length === 0)
+            return null;
+        // This is queued delivery, not a live interrupt: if the sub-agent is
+        // already producing a final answer, the guard asks the loop for one more
+        // continuation that includes the orchestrator update as a fresh user turn.
+        return {
+            retryMessage: formatQueuedTaskMessages(queuedMessages),
+            fallbackMessage: "I received an orchestrator update while finishing, but could not continue from it. Please check the task status and send the update again if needed.",
+        };
+    };
+}
 async function saveTask(task) {
     await writeAppState(`${TASK_PREFIX}${task.taskId}`, task);
     await writeAppState(`${THREAD_PREFIX}${task.threadId}`, {
@@ -45,6 +194,174 @@ async function loadTaskByThread(threadId) {
 function generateTaskId() {
     return `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
+function taskRunId(taskId) {
+    return `run-task-${taskId}`;
+}
+function taskIdFromBackgroundRunId(runId) {
+    return runId.startsWith("run-task-")
+        ? runId.slice("run-task-".length)
+        : runId;
+}
+function mapTaskStatusToBackgroundStatus(status) {
+    return status;
+}
+function taskTimestampToIso(timestamp) {
+    const date = new Date(timestamp);
+    return Number.isFinite(date.getTime())
+        ? date.toISOString()
+        : new Date(0).toISOString();
+}
+function latestTaskText(task) {
+    return task.summary || task.preview || task.currentStep || undefined;
+}
+export function toAgentTaskBackgroundRun(task) {
+    const createdAt = taskTimestampToIso(task.createdAt);
+    return {
+        schemaVersion: 1,
+        id: taskRunId(task.taskId),
+        kind: "agent-team",
+        source: "hosted-agent-team",
+        sourceLabel: "Agent Teams",
+        sourceRecord: {
+            type: "agent-team-task",
+            id: task.taskId,
+            threadId: task.threadId,
+        },
+        title: task.description,
+        subtitle: task.currentStep || undefined,
+        status: mapTaskStatusToBackgroundStatus(task.status),
+        phase: task.currentStep || task.status,
+        createdAt,
+        updatedAt: createdAt,
+        goalId: "agent-team",
+        needsInput: false,
+        needsApproval: false,
+        details: [
+            { label: "Task", value: task.taskId },
+            { label: "Thread", value: task.threadId },
+        ],
+        surfaceUrl: `agent-native://threads/${task.threadId}`,
+        metadata: {
+            taskId: task.taskId,
+            threadId: task.threadId,
+            description: task.description,
+            preview: task.preview,
+            summary: task.summary,
+            currentStep: task.currentStep,
+            latestText: latestTaskText(task),
+        },
+    };
+}
+function summarizeAgentChatEvent(event) {
+    const payload = event.event;
+    switch (payload.type) {
+        case "text":
+            return { kind: "note", message: payload.text };
+        case "activity":
+            return {
+                kind: "status",
+                message: payload.label,
+                metadata: payload.tool ? { tool: payload.tool } : undefined,
+            };
+        case "tool_start":
+            return {
+                kind: "status",
+                message: `Running ${payload.tool}`,
+                metadata: { tool: payload.tool, input: payload.input },
+            };
+        case "tool_done":
+            return {
+                kind: "artifact",
+                message: payload.result,
+                metadata: { tool: payload.tool },
+            };
+        case "agent_task":
+            return {
+                kind: "status",
+                message: `${payload.description} (${payload.status})`,
+                metadata: {
+                    taskId: payload.taskId,
+                    threadId: payload.threadId,
+                    status: payload.status,
+                },
+            };
+        case "agent_task_update":
+            return {
+                kind: "status",
+                message: payload.preview || payload.currentStep || "Task updated",
+                metadata: {
+                    taskId: payload.taskId,
+                    currentStep: payload.currentStep,
+                },
+            };
+        case "agent_task_complete":
+            return {
+                kind: "status",
+                message: payload.summary,
+                metadata: { taskId: payload.taskId },
+            };
+        case "error":
+            return {
+                kind: "status",
+                message: payload.error,
+                metadata: {
+                    errorCode: payload.errorCode,
+                    upgradeUrl: payload.upgradeUrl,
+                },
+            };
+        case "missing_api_key":
+            return {
+                kind: "status",
+                message: "Missing API key",
+            };
+        case "done":
+            return { kind: "status", message: "Run completed" };
+        case "loop_limit":
+            return { kind: "status", message: "Run stopped at the loop limit" };
+        case "auto_continue":
+            return {
+                kind: "status",
+                message: "Run reached its continuation boundary",
+                metadata: { reason: payload.reason },
+            };
+        case "clear":
+            return null;
+        case "agent_call":
+            return {
+                kind: "status",
+                message: `${payload.agent} ${payload.status}`,
+                metadata: { agent: payload.agent, status: payload.status },
+            };
+        case "agent_call_text":
+            return {
+                kind: "note",
+                message: payload.text,
+                metadata: { agent: payload.agent },
+            };
+        default:
+            return null;
+    }
+}
+export function toAgentTaskBackgroundTranscriptEvent(runId, event) {
+    const summary = summarizeAgentChatEvent(event);
+    if (!summary)
+        return null;
+    return {
+        schemaVersion: 1,
+        id: `${runId}:${event.seq}`,
+        runId,
+        kind: summary.kind,
+        source: "hosted-agent-team",
+        sourceRecord: {
+            type: "agent-team-run-event",
+            id: `${runId}:${event.seq}`,
+            seq: event.seq,
+        },
+        message: summary.message,
+        createdAt: new Date().toISOString(),
+        metadata: summary.metadata,
+    };
+}
 /**
  * Spawn a sub-agent task. Creates a thread, starts a background agent run,
  * and emits agent_task events to the parent chat stream.
@@ -126,7 +443,8 @@ You are a focused sub-agent with a specific task. You have been given a curated
     const engine = opts.engine ?? createAnthropicEngine({ apiKey: opts.apiKey });
     const model = opts.model ?? engine.defaultModel;
     // Build tools from actions using the normalized EngineTool format
-    const tools = actionsToEngineTools(opts.actions);
+    const messageAwareActions = createMessageAwareActions(taskId, opts.actions);
+    const tools = actionsToEngineTools(messageAwareActions);
     const messages = [
         { role: "user", content: [{ type: "text", text: opts.description }] },
     ];
@@ -177,9 +495,10 @@ You are a focused sub-agent with a specific task. You have been given a curated
             systemPrompt,
             tools,
             messages,
-            actions: opts.actions,
+            actions: messageAwareActions,
             send: wrappedSend,
             signal,
+            finalResponseGuard: createTaskMessageFinalGuard(taskId),
         });
     }, 
     // onComplete callback — called when the run finishes (success or error)
@@ -307,6 +626,42 @@ export async function listTasks() {
     const tasks = entries.map((e) => e.value);
     return tasks.sort((a, b) => b.createdAt - a.createdAt);
 }
+export async function listAgentTeamBackgroundRuns() {
+    return (await listTasks()).map(toAgentTaskBackgroundRun);
+}
+export async function getAgentTeamBackgroundRun(runId) {
+    const task = await loadTask(taskIdFromBackgroundRunId(runId));
+    return task ? toAgentTaskBackgroundRun(task) : null;
+}
+export async function listAgentTeamBackgroundTranscriptEvents(runId) {
+    const normalizedRunId = taskRunId(taskIdFromBackgroundRunId(runId));
+    const activeRun = getRun(normalizedRunId);
+    const events = activeRun
+        ? activeRun.events
+        : await getPersistedRunEvents(normalizedRunId);
+    return events
+        .map((event) => toAgentTaskBackgroundTranscriptEvent(normalizedRunId, event))
+        .filter((event) => Boolean(event));
+}
+export function subscribeToAgentTeamBackgroundRun(runId, fromSeq = 0) {
+    return subscribeToRun(taskRunId(taskIdFromBackgroundRunId(runId)), fromSeq);
+}
+async function getPersistedRunEvents(runId) {
+    const rows = await getRunEventsSince(runId, 0);
+    return rows
+        .map((row) => {
+        try {
+            return {
+                seq: row.seq,
+                event: JSON.parse(row.eventData),
+            };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((event) => Boolean(event));
+}
 /** Send a message/update to a running sub-agent via application state */
 export async function sendToTask(taskId, message) {
     const task = await loadTask(taskId);
@@ -314,23 +669,79 @@ export async function sendToTask(taskId, message) {
         return { ok: false, error: "Task not found" };
     if (task.status !== "running")
         return { ok: false, error: "Task is not running" };
-    // Write the message to application state so the sub-agent can read it
-    // on its next tool call or iteration
+    if (message.trim().length === 0)
+        return { ok: false, error: "Message is required" };
+    // Append to a durable per-task queue. Running sub-agents drain this queue
+    // after tool batches and immediately before a final response. This does not
+    // interrupt an in-flight model stream or tool call; it guarantees the next
+    // safe continuation sees the update.
     try {
-        const { appStatePut } = await import("../application-state/store.js");
+        const queued = await appendQueuedTaskMessage(taskId, message);
+        return { ok: true, ...queued };
+    }
+    catch {
         const sessionId = getRequestUserEmail();
-        if (!sessionId) {
+        if (!sessionId)
             return { ok: false, error: "no authenticated user" };
-        }
-        await appStatePut(sessionId, `task-message:${taskId}`, {
-            from: "orchestrator",
-            message,
-            timestamp: Date.now(),
-        });
+        return { ok: false, error: "Unable to queue message" };
     }
-    catch {
-        // Application state not available — best effort
+}
+export async function sendToAgentTeamBackgroundRun(runId, message) {
+    return sendToTask(taskIdFromBackgroundRunId(runId), message);
+}
+async function sendAgentTeamBackgroundAgentFollowUp(input) {
+    const prompt = input.prompt.trim();
+    if (!prompt) {
+        return {
+            ok: false,
+            runId: input.runId,
+            run: await getAgentTeamBackgroundRun(input.runId),
+            error: "Follow-up prompt is required.",
+        };
+    }
+    const result = await sendToAgentTeamBackgroundRun(input.runId, prompt);
+    return {
+        ok: result.ok,
+        runId: input.runId,
+        run: await getAgentTeamBackgroundRun(input.runId),
+        queued: result.ok,
+        message: result.ok
+            ? "Follow-up queued for the Agent Teams background run."
+            : undefined,
+        error: result.error,
+    };
+}
+async function controlAgentTeamBackgroundAgentRun(input) {
+    if (input.command !== "stop") {
+        return {
+            ok: false,
+            runId: input.runId,
+            run: await getAgentTeamBackgroundRun(input.runId),
+            error: "Agent Teams background runs currently support stop through the shared controller.",
+        };
+    }
+    const result = await stopAgentTeamBackgroundRun(input.runId);
+    return {
+        ok: result.ok,
+        runId: input.runId,
+        run: await getAgentTeamBackgroundRun(input.runId),
+        message: result.ok ? "Agent Teams background run stopped." : undefined,
+        error: result.error,
+    };
+}
+export async function stopAgentTeamBackgroundRun(runId, reason = "user") {
+    const taskId = taskIdFromBackgroundRunId(runId);
+    const task = await loadTask(taskId);
+    if (!task)
+        return { ok: false, error: "Task not found" };
+    if (task.status !== "running") {
+        return { ok: false, error: "Task is not running" };
     }
+    abortRun(taskRunId(taskId), reason);
+    task.status = "errored";
+    task.summary =
+        reason === "user" ? "Task stopped." : `Task stopped: ${reason}`;
+    await saveTask(task);
     return { ok: true };
 }
 /** Mark a task as errored */
@@ -342,4 +753,10 @@ export async function markTaskErrored(taskId, error) {
         await saveTask(task);
     }
 }
+export const _agentTeamsQueueForTests = {
+    createMessageAwareActions,
+    createTaskMessageFinalGuard,
+    drainQueuedTaskMessages,
+    formatQueuedTaskMessages,
+};
 //# sourceMappingURL=agent-teams.js.map