summaryrefslogtreecommitdiffhomepage
path: root/packages
diff options
context:
space:
mode:
authorAdam Malczewski <[email protected]>2026-06-01 01:46:13 +0900
committerAdam Malczewski <[email protected]>2026-06-01 01:46:13 +0900
commit8b9533c22a47bbf6f916667e2c25d8e8e419da37 (patch)
tree715a6a3d6f43781395e7dc7c8cdb519cef46a870 /packages
parent1853dd1d40308deb829bc621beb79c5d39b9c57f (diff)
downloaddispatch-8b9533c22a47bbf6f916667e2c25d8e8e419da37.tar.gz
dispatch-8b9533c22a47bbf6f916667e2c25d8e8e419da37.zip
feat(tabs): tab-to-tab agent communication via short handles
Add send_to_tab / read_tab tools so an agent can message or read another tab by a git-style short handle (shortest unique prefix of the tab UUID, min 4 chars), shown in the tab bar. - core/db/tabs: resolveTabPrefix + shortestUniquePrefix (open tabs only, LIKE-sanitized prefix matching) - new tools read-tab.ts / send-to-tab.ts (+ tests) decoupled from the DB TabRow via a minimal ResolvedTabRef projection - agent-manager: unified deliverMessage routing (busy -> queue, idle -> new turn) shared by POST /chat and send_to_tab; agent->agent auto-wake budget (MAX_AGENT_AUTO_WAKES) to bound ping-pong loops - summon/loader: send_to_tab + read_tab as grantable tools - frontend: shortHandleFor + handle badge in TabBar; perm toggles - notes: tab-comm / user-agents / todo-redesign plans - chore: biome format fixes (debug-logger, summon.test) Refs notes/plan-tab-comm.md
Diffstat (limited to 'packages')
-rw-r--r--packages/api/src/agent-manager.ts263
-rw-r--r--packages/api/src/app.ts25
-rw-r--r--packages/api/tests/agent-manager.test.ts365
-rw-r--r--packages/api/tests/routes.test.ts28
-rw-r--r--packages/core/src/agents/loader.ts4
-rw-r--r--packages/core/src/db/tabs.ts75
-rw-r--r--packages/core/src/index.ts11
-rw-r--r--packages/core/src/llm/debug-logger.ts21
-rw-r--r--packages/core/src/tools/read-tab.ts95
-rw-r--r--packages/core/src/tools/send-to-tab.ts147
-rw-r--r--packages/core/src/tools/summon.ts8
-rw-r--r--packages/core/tests/agents/loader.test.ts28
-rw-r--r--packages/core/tests/db/tabs.test.ts119
-rw-r--r--packages/core/tests/tools/read-tab.test.ts101
-rw-r--r--packages/core/tests/tools/send-to-tab.test.ts142
-rw-r--r--packages/core/tests/tools/summon.test.ts10
-rw-r--r--packages/frontend/src/lib/components/TabBar.svelte2
-rw-r--r--packages/frontend/src/lib/components/ToolPermissions.svelte10
-rw-r--r--packages/frontend/src/lib/settings.svelte.ts4
-rw-r--r--packages/frontend/src/lib/tabs.svelte.ts24
20 files changed, 1442 insertions, 40 deletions
diff --git a/packages/api/src/agent-manager.ts b/packages/api/src/agent-manager.ts
index 111237c..517c661 100644
--- a/packages/api/src/agent-manager.ts
+++ b/packages/api/src/agent-manager.ts
@@ -15,8 +15,10 @@ import {
createListFilesTool,
createReadFileSliceTool,
createReadFileTool,
+ createReadTabTool,
createRetrieveTool,
createRunShellTool,
+ createSendToTabTool,
createSkillsWatcher,
createSummonTool,
createTaskListTool,
@@ -32,6 +34,8 @@ import {
getClaudeAccountsFromDB,
getMessagesForTab,
getSetting,
+ getTab,
+ listOpenTabs,
loadAgent,
loadAgents,
loadConfig,
@@ -41,8 +45,11 @@ import {
refreshAccountCredentials,
refreshAccountCredentialsAsync,
resolveApiKey,
+ resolveTabPrefix,
type SkillDefinition,
type SystemChunkKind,
+ shortestUniquePrefix,
+ type TabResolution,
type TabStatusSnapshot,
TaskList,
toAvailableSubagents,
@@ -73,6 +80,16 @@ const TOOL_DESCRIPTIONS: Record<string, string> = {
"Fetch the transcript/subtitles for a YouTube video. Set background=true to start in the background and get a job_id for later retrieval.",
};
+/**
+ * Maximum number of CONSECUTIVE agent-to-agent auto-wakes a tab will accept
+ * before it stops auto-responding and waits for a human. Each `send_to_tab`
+ * that would wake an idle tab consumes one unit; any human-originated message
+ * (e.g. via `POST /chat`) refills the budget to full. This bounds runaway
+ * agent ping-pong loops (A wakes B wakes A ...) that would otherwise spend
+ * tokens unbounded with no human in the loop. See notes/plan-tab-comm.md.
+ */
+const MAX_AGENT_AUTO_WAKES = 6;
+
const DEFAULT_SYSTEM_PROMPT =
"You are Dispatch, an agent designed to help with any task that the user asks for. Be helpful and concise.";
@@ -197,6 +214,14 @@ interface TabAgent {
* rows. Set at the start of `processMessage`, cleared when the turn ends.
*/
currentTurnId: string | null;
+ /**
+ * Remaining consecutive agent-to-agent auto-wakes this tab will accept
+ * before requiring human intervention (see `MAX_AGENT_AUTO_WAKES`).
+ * Refilled to the max by any human-originated `deliverMessage`; decremented
+ * each time an agent-originated `send_to_tab` wakes this tab from idle. When
+ * it hits 0, further agent messages are queued but do NOT start a turn.
+ */
+ autoWakeBudget: number;
}
export class AgentManager {
@@ -343,6 +368,7 @@ export class AgentManager {
currentChunks: null,
currentAssistantId: null,
currentTurnId: null,
+ autoWakeBudget: MAX_AGENT_AUTO_WAKES,
};
this.tabAgents.set(tabId, tabAgent);
}
@@ -366,10 +392,12 @@ export class AgentManager {
const permBash = getSetting("perm_bash") === "allow";
const permSummon = getSetting("perm_summon") === "allow";
const permUserAgent = getSetting("perm_user_agent") === "allow";
+ const permSendToTab = getSetting("perm_send_to_tab") === "allow";
+ const permReadTab = getSetting("perm_read_tab") === "allow";
const permWebSearch = getSetting("perm_web_search") === "allow";
const permYoutubeTranscribe = getSetting("perm_youtube_transcribe") === "allow";
const sysPrompt = getSetting("system_prompt") ?? "";
- const permKey = `${permRead}:${permEdit}:${permBash}:${permSummon}:${permUserAgent}:${permWebSearch}:${permYoutubeTranscribe}:${sysPrompt}`;
+ const permKey = `${permRead}:${permEdit}:${permBash}:${permSummon}:${permUserAgent}:${permSendToTab}:${permReadTab}:${permWebSearch}:${permYoutubeTranscribe}:${sysPrompt}`;
// If the override differs or permissions changed, invalidate the cached agent
if (
@@ -504,6 +532,12 @@ export class AgentManager {
}),
});
}
+ // Tab-to-tab communication — gated on the child whitelist.
+ if (allowed.has("send_to_tab") || allowed.has("read_tab")) {
+ for (const entry of this.buildTabCommToolEntries(tabId)) {
+ if (allowed.has(entry.name)) toolEntries.push(entry);
+ }
+ }
} else {
// Parent agent: use permission settings from DB
if (permRead) {
@@ -581,6 +615,14 @@ export class AgentManager {
}),
});
}
+ if (permSendToTab || permReadTab) {
+ const tabCommAllowed = new Set<string>();
+ if (permSendToTab) tabCommAllowed.add("send_to_tab");
+ if (permReadTab) tabCommAllowed.add("read_tab");
+ for (const entry of this.buildTabCommToolEntries(tabId)) {
+ if (tabCommAllowed.has(entry.name)) toolEntries.push(entry);
+ }
+ }
}
const tools = toolEntries.map((e) => e.tool);
@@ -971,14 +1013,18 @@ export class AgentManager {
if (!agentDef) {
const allDefs = loadAgents(parentEffectiveDir);
if (options.topLevel) {
- const userAgents = allDefs.filter((d) => !d.is_subagent).map((d) => `${d.slug} (${d.name})`);
+ const userAgents = allDefs
+ .filter((d) => !d.is_subagent)
+ .map((d) => `${d.slug} (${d.name})`);
const hint =
userAgents.length > 0
? ` Available user agents: ${userAgents.join(", ")}.`
: " No user agent definitions exist yet.";
throw new Error(`Agent definition not found: "${options.agentSlug}".${hint}`);
} else {
- const subagents = allDefs.filter((d) => d.is_subagent).map((d) => `${d.slug} (${d.name})`);
+ const subagents = allDefs
+ .filter((d) => d.is_subagent)
+ .map((d) => `${d.slug} (${d.name})`);
const hint =
subagents.length > 0
? ` Available subagents: ${subagents.join(", ")}.`
@@ -1147,7 +1193,8 @@ export class AgentManager {
if (tabAgent.status === "running") {
return {
status: "error",
- error: "This is a user agent (top-level tab) and cannot be retrieved. User agents are fire-and-forget.",
+ error:
+ "This is a user agent (top-level tab) and cannot be retrieved. User agents are fire-and-forget.",
};
}
return {
@@ -1159,6 +1206,214 @@ export class AgentManager {
return tabAgent.completionPromise;
}
+ // ─── Tab-to-tab communication ───────────────────────────────────
+ //
+ // `send_to_tab` / `read_tab` let an agent message a peer tab by its short
+ // handle (a git-style prefix of the tab UUID). Delivery reuses the exact
+ // running→queue / idle→new-turn routing that `POST /chat` uses (see
+ // `deliverMessage`), so an agent message behaves identically to a user one.
+
+ /**
+ * Build the `send_to_tab` + `read_tab` tool entries for `tabId`. Shared by
+ * both tool-construction paths (child whitelist + permission-gated parent).
+ * `selfHandle` is computed once so the calling tab can stamp provenance and
+ * reject self-sends.
+ */
+ private buildTabCommToolEntries(
+ tabId: string,
+ ): Array<{ name: string; tool: ReturnType<typeof createSendToTabTool> }> {
+ const selfHandle = shortestUniquePrefix(tabId);
+ return [
+ {
+ name: "send_to_tab",
+ tool: createSendToTabTool({
+ resolveShortId: (prefix) => this.resolveTabHandle(prefix),
+ // origin: "agent" subjects this to the receiver's auto-wake
+ // budget so agent↔agent loops are bounded (see deliverMessage).
+ deliver: (targetId, message) =>
+ this.deliverMessage(targetId, message, { origin: "agent" }),
+ listOpenHandles: () => this.listOpenHandles(tabId),
+ self: { id: tabId, handle: selfHandle },
+ }),
+ },
+ {
+ name: "read_tab",
+ tool: createReadTabTool({
+ resolveShortId: (prefix) => this.resolveTabHandle(prefix),
+ getLastResponse: (targetId) => this.getLastTabResponse(targetId),
+ listOpenHandles: () => this.listOpenHandles(tabId),
+ }),
+ },
+ ];
+ }
+
+ /**
+ * Project a core `ResolveTabPrefixResult` down to the tool-facing
+ * `TabResolution` (minimal `{ id, title, handle }` refs). Each match's
+ * `handle` is recomputed via `shortestUniquePrefix` so the value the tool
+ * echoes back always matches what the UI currently shows.
+ */
+ private resolveTabHandle(prefix: string): TabResolution {
+ const res = resolveTabPrefix(prefix);
+ if (res.status === "none") return { status: "none" };
+ if (res.status === "ok") {
+ return {
+ status: "ok",
+ tab: {
+ id: res.tab.id,
+ title: res.tab.title,
+ handle: shortestUniquePrefix(res.tab.id),
+ },
+ };
+ }
+ return {
+ status: "ambiguous",
+ matches: res.matches.map((t) => ({
+ id: t.id,
+ title: t.title,
+ handle: shortestUniquePrefix(t.id),
+ })),
+ };
+ }
+
+ /** Snapshot of open tabs as `{ handle, title }`, excluding `exceptId`
+ * (typically the caller's own tab). Drives the "available tabs" hints. */
+ private listOpenHandles(exceptId?: string): Array<{ handle: string; title: string }> {
+ return listOpenTabs()
+ .filter((t) => t.id !== exceptId)
+ .map((t) => ({ handle: shortestUniquePrefix(t.id), title: t.title }));
+ }
+
+ /**
+ * Return a tab's most recent COMPLETED assistant turn as flat text, plus
+ * its current status. Reads the persisted chunk log (source of truth) and
+ * grabs the last `role === "assistant"` group's text chunks. `text` is null
+ * when no completed assistant turn exists yet.
+ */
+ getLastTabResponse(tabId: string): { text: string | null; status: AgentStatus } {
+ const status = this.getTabStatus(tabId);
+ try {
+ const messages = getMessagesForTab(tabId);
+ for (let i = messages.length - 1; i >= 0; i--) {
+ const msg = messages[i];
+ if (!msg || msg.role !== "assistant") continue;
+ const text = msg.chunks
+ .filter((c): c is { type: "text"; text: string } => c.type === "text")
+ .map((c) => c.text)
+ .join("")
+ .trim();
+ if (text.length > 0) return { text, status };
+ }
+ } catch {
+ // DB unavailable / tab unknown — fall through to null.
+ }
+ return { text: null, status };
+ }
+
+ /**
+ * Deliver `message` to `tabId`, choosing the SAME routing as `POST /chat`:
+ * - target running → queue it (consumed like a user interrupt).
+ * - target idle/errored → wake it and start a new turn.
+ *
+ * Returns quickly; does NOT block on the turn. Both the HTTP `/chat` path
+ * and the `send_to_tab` tool call through here so the running/idle decision
+ * lives in exactly one place.
+ *
+ * `opts` carries the per-request knobs `/chat` forwards (key/model, agent
+ * fallback chain, reasoning effort, working dir, an explicit queue id). The
+ * `send_to_tab` tool passes none of these — for a cold wake (a tab not in
+ * `tabAgents`, e.g. after a server restart) the key/model are hydrated from
+ * the live `TabAgent` if present, else from the persisted tab row. (A cold
+ * tab keeps its stored key/model but not its full agent-definition fallback
+ * chain — see plan notes.)
+ */
+ deliverMessage(
+ tabId: string,
+ message: string,
+ opts: {
+ keyId?: string;
+ modelId?: string;
+ agentModels?: Array<{ key_id: string; model_id: string }>;
+ reasoningEffort?: "none" | "low" | "medium" | "high" | "max";
+ workingDirectory?: string;
+ queueId?: string;
+ /**
+ * Who is sending this message. `"human"` (default) is unrestricted
+ * and REFILLS the target's agent-to-agent auto-wake budget. `"agent"`
+ * (from the `send_to_tab` tool) is governed by that budget: an
+ * agent-originated wake of an idle tab consumes one unit, and once the
+ * budget is exhausted the message is queued WITHOUT starting a turn
+ * (returned as `suppressed`) so a runaway A↔B loop can't spend tokens
+ * forever with no human in the loop.
+ */
+ origin?: "human" | "agent";
+ } = {},
+ ): { status: "queued"; messageId: string } | { status: "started" } | { status: "suppressed" } {
+ const origin = opts.origin ?? "human";
+
+ // A human touching the tab clears any accumulated agent-wake throttle:
+ // the conversation is back under human supervision, so peers get a fresh
+ // budget of auto-wakes again.
+ if (origin === "human") {
+ this._getOrCreateTabAgent(tabId).autoWakeBudget = MAX_AGENT_AUTO_WAKES;
+ }
+
+ if (this.getTabStatus(tabId) === "running") {
+ // Busy target → always queue (consumed like a user interrupt),
+ // regardless of origin. Queuing does not itself start a turn, so it
+ // can't drive a runaway loop; we don't spend budget here.
+ const { messageId } = this.queueMessage(tabId, message, opts.queueId);
+ return { status: "queued", messageId };
+ }
+
+ // Idle/errored target → this delivery would WAKE the tab (start a turn).
+ // For agent-originated wakes, enforce the auto-wake budget first.
+ if (origin === "agent") {
+ const target = this._getOrCreateTabAgent(tabId);
+ if (target.autoWakeBudget <= 0) {
+ // Budget exhausted: preserve the message (queue it, never drop)
+ // but do NOT wake the tab. A human message will refill the budget
+ // and the queued message will be seen on the next human turn.
+ this.queueMessage(tabId, message, opts.queueId);
+ const notice =
+ `Automatic agent-to-agent message limit reached for this tab ` +
+ `(${MAX_AGENT_AUTO_WAKES} consecutive). Further messages from other tabs ` +
+ `are held until you send a message here.`;
+ this.emit({ type: "notice", message: notice }, tabId);
+ this.routeSystemEventToTab(tabId, "notice", notice);
+ return { status: "suppressed" };
+ }
+ target.autoWakeBudget -= 1;
+ }
+
+ // Resolve key/model: explicit opts win, then the live tab agent's, then
+ // the persisted row's.
+ const tabAgent = this.tabAgents.get(tabId);
+ let keyId = opts.keyId ?? tabAgent?.keyId ?? undefined;
+ let modelId = opts.modelId ?? tabAgent?.modelId ?? undefined;
+ const agentModels = opts.agentModels ?? tabAgent?.agentModels;
+ if (!keyId || !modelId) {
+ const row = getTab(tabId);
+ if (row) {
+ keyId = keyId ?? row.keyId ?? undefined;
+ modelId = modelId ?? row.modelId ?? undefined;
+ }
+ }
+
+ this.processMessage(
+ tabId,
+ message,
+ keyId,
+ modelId,
+ opts.reasoningEffort,
+ opts.workingDirectory,
+ agentModels,
+ ).catch((err) => {
+ console.error(`[dispatch] deliverMessage processMessage error for tab ${tabId}:`, err);
+ });
+ return { status: "started" };
+ }
+
async processMessage(
tabId: string,
message: string,
diff --git a/packages/api/src/app.ts b/packages/api/src/app.ts
index 73d3de5..19cc193 100644
--- a/packages/api/src/app.ts
+++ b/packages/api/src/app.ts
@@ -56,28 +56,33 @@ app.post("/chat", async (c) => {
return c.json({ error: "message must be a non-empty string" }, 400);
}
- if (agentManager.getTabStatus(tabId) === "running") {
- const queueId = typeof body.queueId === "string" ? body.queueId : undefined;
- const { messageId } = agentManager.queueMessage(tabId, message, queueId);
- return c.json({ status: "queued", messageId });
- }
-
const keyId = typeof body.keyId === "string" ? body.keyId : undefined;
const modelId = typeof body.modelId === "string" ? body.modelId : undefined;
const agentModels = Array.isArray(body.agentModels) ? body.agentModels : undefined;
const workingDirectory =
typeof body.workingDirectory === "string" ? body.workingDirectory : undefined;
+ const queueId = typeof body.queueId === "string" ? body.queueId : undefined;
const validEfforts = ["none", "low", "medium", "high", "max"];
const reasoningEffort =
typeof body.reasoningEffort === "string" && validEfforts.includes(body.reasoningEffort)
? (body.reasoningEffort as "none" | "low" | "medium" | "high" | "max")
: undefined;
- // Non-blocking — let the agent run in the background
- agentManager
- .processMessage(tabId, message, keyId, modelId, reasoningEffort, workingDirectory, agentModels)
- .catch(console.error);
+ // Single routing decision (queue if busy, new turn if idle) shared with the
+ // `send_to_tab` tool via `AgentManager.deliverMessage`. Non-blocking — a
+ // started turn runs in the background.
+ const outcome = agentManager.deliverMessage(tabId, message, {
+ ...(keyId ? { keyId } : {}),
+ ...(modelId ? { modelId } : {}),
+ ...(agentModels ? { agentModels } : {}),
+ ...(reasoningEffort ? { reasoningEffort } : {}),
+ ...(workingDirectory !== undefined ? { workingDirectory } : {}),
+ ...(queueId ? { queueId } : {}),
+ });
+ if (outcome.status === "queued") {
+ return c.json({ status: "queued", messageId: outcome.messageId });
+ }
return c.json({ status: "ok" });
});
diff --git a/packages/api/tests/agent-manager.test.ts b/packages/api/tests/agent-manager.test.ts
index 4415bbb..1358eb1 100644
--- a/packages/api/tests/agent-manager.test.ts
+++ b/packages/api/tests/agent-manager.test.ts
@@ -24,6 +24,39 @@ function resetFakeMessages(): void {
function setFakeMessages(tabId: string, rows: FakeMessageRow[]): void {
fakeMessagesByTab.set(tabId, rows);
}
+
+// Configurable stub for the tabs DB (getTab / listOpenTabs). Tests can seed
+// rows to exercise deliverMessage cold-hydration and handle resolution.
+interface FakeTabRow {
+ id: string;
+ title: string;
+ keyId: string | null;
+ modelId: string | null;
+ parentTabId: string | null;
+ status: string;
+ isOpen: boolean;
+ position: number;
+ createdAt: number;
+ updatedAt: number;
+}
+const fakeTabs = new Map<string, FakeTabRow>();
+function resetFakeTabs(): void {
+ fakeTabs.clear();
+}
+function setFakeTab(row: Partial<FakeTabRow> & { id: string }): void {
+ fakeTabs.set(row.id, {
+ title: "Tab",
+ keyId: null,
+ modelId: null,
+ parentTabId: null,
+ status: "idle",
+ isOpen: true,
+ position: 0,
+ createdAt: 0,
+ updatedAt: 0,
+ ...row,
+ });
+}
function makeRow(
tabId: string,
seq: number,
@@ -42,11 +75,22 @@ function makeRow(
// because the production code reassigns `agent.messages =
// rows.slice(...)` AFTER `new Agent()` returns — capturing a
// reference at construction would yield a stale empty array.
-const constructedAgents: Array<{ initialMessages: unknown[] }> = [];
+const constructedAgents: Array<{ initialMessages: unknown[]; toolNames: string[] }> = [];
function resetConstructedAgents(): void {
constructedAgents.length = 0;
}
+// Configurable settings store so tests can toggle tool permissions
+// (perm_send_to_tab / perm_read_tab / ...) and assert which tools the
+// constructed Agent receives. Defaults to empty (getSetting → null).
+const fakeSettings = new Map<string, string>();
+function resetFakeSettings(): void {
+ fakeSettings.clear();
+}
+function setFakeSetting(key: string, value: string): void {
+ fakeSettings.set(key, value);
+}
+
// Allow tests to swap in a custom `run` generator (e.g. to simulate
// a fallback failure mid-stream). Returning to undefined restores
// the default.
@@ -87,12 +131,19 @@ vi.mock("@dispatch/core", () => ({
Agent: class MockAgent {
status = "idle";
messages: unknown[] = [];
+ toolNames: string[] = [];
+ constructor(config: { tools?: Array<{ name: string }> }) {
+ this.toolNames = (config?.tools ?? []).map((t) => t.name);
+ }
async *run(message: string): AsyncGenerator<unknown> {
// Snapshot the post-construction pre-populated message list
// the first thing `run()` does, before the real `Agent.run`
// would push the current user message at line 546. Tests
// inspect this to verify history was loaded correctly.
- constructedAgents.push({ initialMessages: [...this.messages] });
+ constructedAgents.push({
+ initialMessages: [...this.messages],
+ toolNames: [...this.toolNames],
+ });
if (runImpl) {
for await (const ev of runImpl(message)) yield ev;
return;
@@ -244,6 +295,41 @@ vi.mock("@dispatch/core", () => ({
};
},
createTab() {},
+ getTab(id: string) {
+ return fakeTabs.get(id) ?? null;
+ },
+ listOpenTabs() {
+ return [...fakeTabs.values()].filter((t) => t.isOpen);
+ },
+ resolveTabPrefix(prefix: string) {
+ const sanitized = (prefix ?? "").toLowerCase().replace(/[^0-9a-f-]/g, "");
+ if (sanitized.length < 4) return { status: "none" };
+ const matches = [...fakeTabs.values()].filter(
+ (t) => t.isOpen && t.id.toLowerCase().startsWith(sanitized),
+ );
+ if (matches.length === 0) return { status: "none" };
+ if (matches.length === 1) return { status: "ok", tab: matches[0] };
+ return { status: "ambiguous", matches };
+ },
+ shortestUniquePrefix(id: string) {
+ return (id ?? "").slice(0, 4);
+ },
+ createSendToTabTool(_callbacks: unknown): ToolDefinition {
+ return {
+ name: "send_to_tab",
+ description: "send to tab",
+ parameters: { _type: "z.ZodObject", shape: {} } as unknown as ToolDefinition["parameters"],
+ execute: async () => "mock",
+ };
+ },
+ createReadTabTool(_callbacks: unknown): ToolDefinition {
+ return {
+ name: "read_tab",
+ description: "read tab",
+ parameters: { _type: "z.ZodObject", shape: {} } as unknown as ToolDefinition["parameters"],
+ execute: async () => "mock",
+ };
+ },
getClaudeAccountsFromDB() {
return [];
},
@@ -256,8 +342,8 @@ vi.mock("@dispatch/core", () => ({
resolveApiKey() {
return null;
},
- getSetting(_key: string) {
- return null;
+ getSetting(key: string) {
+ return fakeSettings.get(key) ?? null;
},
appendChunks() {
return [];
@@ -316,6 +402,8 @@ describe("AgentManager", () => {
beforeEach(() => {
resetFakeMessages();
resetConstructedAgents();
+ resetFakeTabs();
+ resetFakeSettings();
setRunImpl(null);
appendEventToChunksSpy.mockClear();
});
@@ -849,4 +937,273 @@ describe("AgentManager", () => {
expect(snap["tab-early"]).not.toHaveProperty("currentChunks");
expect(snap["tab-early"]).not.toHaveProperty("currentAssistantId");
});
+
+ // ─── Tab-to-tab communication ─────────────────────────────────
+
+ describe("deliverMessage", () => {
+ it("starts a new turn when the target tab is idle", async () => {
+ const manager = new AgentManager();
+ const events: AgentEvent[] = [];
+ manager.onEvent((e) => events.push(e));
+
+ const outcome = manager.deliverMessage("tab-idle", "wake up");
+ expect(outcome.status).toBe("started");
+
+ // Let the background turn run to completion.
+ await new Promise<void>((r) => setTimeout(r, 60));
+ expect(events.some((e) => e.type === "text-delta")).toBe(true);
+ expect(manager.getTabStatus("tab-idle")).toBe("idle");
+ });
+
+ it("queues the message when the target tab is running", () => {
+ const manager = new AgentManager();
+ const inner = manager as unknown as {
+ tabAgents: Map<string, Record<string, unknown>>;
+ };
+ // Seed a running tab agent directly.
+ inner.tabAgents.set("tab-busy", {
+ agent: null,
+ status: "running",
+ keyId: null,
+ modelId: null,
+ taskList: { onChange: () => {} },
+ messageQueue: [],
+ queueListeners: [],
+ shellStore: {},
+ transcriptStore: {},
+ currentChunks: null,
+ currentAssistantId: null,
+ currentTurnId: null,
+ });
+
+ const outcome = manager.deliverMessage("tab-busy", "queued msg");
+ expect(outcome.status).toBe("queued");
+ if (outcome.status === "queued") {
+ expect(typeof outcome.messageId).toBe("string");
+ }
+ // The message landed on the running tab's queue.
+ const agent = inner.tabAgents.get("tab-busy") as { messageQueue: unknown[] };
+ expect(agent.messageQueue).toHaveLength(1);
+ });
+
+ it("hydrates key/model from the persisted tab row for a cold wake", () => {
+ const manager = new AgentManager();
+ setFakeTab({ id: "tab-cold", keyId: "persisted-key", modelId: "persisted-model" });
+
+ // Spy on processMessage to capture the key/model deliverMessage
+ // forwarded — asserting the hydration decision directly rather than
+ // downstream tabAgent state (which the mocked ModelRegistry rewrites).
+ const spy = vi.spyOn(manager, "processMessage").mockResolvedValue(undefined);
+
+ const outcome = manager.deliverMessage("tab-cold", "hello");
+ expect(outcome.status).toBe("started");
+
+ expect(spy).toHaveBeenCalledTimes(1);
+ const args = spy.mock.calls[0] ?? [];
+ expect(args[0]).toBe("tab-cold"); // tabId
+ expect(args[1]).toBe("hello"); // message
+ expect(args[2]).toBe("persisted-key"); // keyId hydrated from row
+ expect(args[3]).toBe("persisted-model"); // modelId hydrated from row
+ });
+
+ it("prefers explicit opts over the persisted row on a cold wake", () => {
+ const manager = new AgentManager();
+ setFakeTab({ id: "tab-cold2", keyId: "row-key", modelId: "row-model" });
+ const spy = vi.spyOn(manager, "processMessage").mockResolvedValue(undefined);
+
+ manager.deliverMessage("tab-cold2", "hello", {
+ keyId: "explicit-key",
+ modelId: "explicit-model",
+ });
+
+ const args = spy.mock.calls[0] ?? [];
+ expect(args[2]).toBe("explicit-key");
+ expect(args[3]).toBe("explicit-model");
+ });
+ });
+
+ describe("deliverMessage — agent auto-wake budget", () => {
+ it("allows up to 6 consecutive agent wakes, then suppresses further ones", () => {
+ const manager = new AgentManager();
+ const spy = vi.spyOn(manager, "processMessage").mockResolvedValue(undefined);
+
+ // 6 agent-originated wakes of an idle tab should all start turns.
+ for (let i = 0; i < 6; i++) {
+ const outcome = manager.deliverMessage("tab-pp", `msg ${i}`, { origin: "agent" });
+ expect(outcome.status).toBe("started");
+ }
+ expect(spy).toHaveBeenCalledTimes(6);
+
+ // The 7th is suppressed: no new turn, message preserved on the queue.
+ const seventh = manager.deliverMessage("tab-pp", "msg 7", { origin: "agent" });
+ expect(seventh.status).toBe("suppressed");
+ expect(spy).toHaveBeenCalledTimes(6); // unchanged — no wake
+
+ const inner = manager as unknown as {
+ tabAgents: Map<string, { messageQueue: unknown[]; autoWakeBudget: number }>;
+ };
+ const agent = inner.tabAgents.get("tab-pp");
+ expect(agent?.autoWakeBudget).toBe(0);
+ // Suppressed message is queued, not dropped.
+ expect(agent?.messageQueue).toHaveLength(1);
+ });
+
+ it("a human message refills the budget and re-enables agent wakes", () => {
+ const manager = new AgentManager();
+ vi.spyOn(manager, "processMessage").mockResolvedValue(undefined);
+
+ // Exhaust the budget with agent wakes.
+ for (let i = 0; i < 6; i++) {
+ manager.deliverMessage("tab-refill", `a${i}`, { origin: "agent" });
+ }
+ expect(manager.deliverMessage("tab-refill", "blocked", { origin: "agent" }).status).toBe(
+ "suppressed",
+ );
+
+ // A human message refills the budget...
+ const humanOutcome = manager.deliverMessage("tab-refill", "human here", {
+ origin: "human",
+ });
+ expect(humanOutcome.status).toBe("started");
+
+ const inner = manager as unknown as {
+ tabAgents: Map<string, { autoWakeBudget: number }>;
+ };
+ expect(inner.tabAgents.get("tab-refill")?.autoWakeBudget).toBe(6);
+
+ // ...so an agent can wake it again.
+ expect(manager.deliverMessage("tab-refill", "again", { origin: "agent" }).status).toBe(
+ "started",
+ );
+ });
+
+ it("does not consume budget when the message is merely queued (busy target)", () => {
+ const manager = new AgentManager();
+ const inner = manager as unknown as {
+ tabAgents: Map<string, Record<string, unknown>>;
+ };
+ inner.tabAgents.set("tab-busy-budget", {
+ agent: null,
+ status: "running",
+ keyId: null,
+ modelId: null,
+ taskList: { onChange: () => {} },
+ messageQueue: [],
+ queueListeners: [],
+ shellStore: {},
+ transcriptStore: {},
+ currentChunks: null,
+ currentAssistantId: null,
+ currentTurnId: null,
+ autoWakeBudget: 6,
+ });
+
+ const outcome = manager.deliverMessage("tab-busy-budget", "queued one", {
+ origin: "agent",
+ });
+ expect(outcome.status).toBe("queued");
+ // Budget untouched — queuing can't drive a runaway loop.
+ const agent = inner.tabAgents.get("tab-busy-budget") as { autoWakeBudget: number };
+ expect(agent.autoWakeBudget).toBe(6);
+ });
+
+ it("human-originated wakes are never throttled", () => {
+ const manager = new AgentManager();
+ const spy = vi.spyOn(manager, "processMessage").mockResolvedValue(undefined);
+
+ // Far more than the budget, all human-originated → all start turns.
+ for (let i = 0; i < 10; i++) {
+ const outcome = manager.deliverMessage("tab-human", `h${i}`, { origin: "human" });
+ expect(outcome.status).toBe("started");
+ }
+ expect(spy).toHaveBeenCalledTimes(10);
+ });
+
+ it("defaults origin to human when unspecified (POST /chat path)", () => {
+ const manager = new AgentManager();
+ const spy = vi.spyOn(manager, "processMessage").mockResolvedValue(undefined);
+ for (let i = 0; i < 8; i++) {
+ expect(manager.deliverMessage("tab-default", `d${i}`).status).toBe("started");
+ }
+ expect(spy).toHaveBeenCalledTimes(8);
+ });
+ });
+
+ describe("getLastTabResponse", () => {
+ it("returns the most recent assistant turn's text and current status", () => {
+ const manager = new AgentManager();
+ setFakeMessages("tab-hist", [
+ makeRow("tab-hist", 1, "user", [{ type: "text", text: "hi" }]),
+ makeRow("tab-hist", 2, "assistant", [{ type: "text", text: "first answer" }]),
+ makeRow("tab-hist", 3, "user", [{ type: "text", text: "again" }]),
+ makeRow("tab-hist", 4, "assistant", [
+ { type: "text", text: "second " },
+ { type: "text", text: "answer" },
+ ]),
+ ]);
+
+ const res = manager.getLastTabResponse("tab-hist");
+ expect(res.text).toBe("second answer");
+ expect(res.status).toBe("idle");
+ });
+
+ it("returns null text when the tab has no assistant turn yet", () => {
+ const manager = new AgentManager();
+ setFakeMessages("tab-empty", [
+ makeRow("tab-empty", 1, "user", [{ type: "text", text: "hi" }]),
+ ]);
+ const res = manager.getLastTabResponse("tab-empty");
+ expect(res.text).toBeNull();
+ });
+
+ it("skips assistant turns that contain no text chunks", () => {
+ const manager = new AgentManager();
+ setFakeMessages("tab-toolonly", [
+ makeRow("tab-toolonly", 1, "assistant", [{ type: "text", text: "real answer" }]),
+ // A later assistant turn with only non-text chunks should be skipped.
+ makeRow("tab-toolonly", 2, "assistant", [{ type: "thinking", text: "hmm" }]),
+ ]);
+ const res = manager.getLastTabResponse("tab-toolonly");
+ expect(res.text).toBe("real answer");
+ });
+ });
+
+ describe("send_to_tab / read_tab permission split", () => {
+ // Drives the real parent-path tool construction in getOrCreateAgentForTab
+ // by toggling the new split permissions and inspecting which tools the
+ // constructed Agent received.
+ async function toolsForPerms(tabId: string, perms: Record<string, string>): Promise<string[]> {
+ for (const [k, v] of Object.entries(perms)) setFakeSetting(k, v);
+ const manager = new AgentManager();
+ await manager.processMessage(tabId, "go");
+ return constructedAgents.at(-1)?.toolNames ?? [];
+ }
+
+ it("grants only send_to_tab when only perm_send_to_tab is allowed", async () => {
+ const tools = await toolsForPerms("tab-send-only", { perm_send_to_tab: "allow" });
+ expect(tools).toContain("send_to_tab");
+ expect(tools).not.toContain("read_tab");
+ });
+
+ it("grants only read_tab when only perm_read_tab is allowed", async () => {
+ const tools = await toolsForPerms("tab-read-only", { perm_read_tab: "allow" });
+ expect(tools).toContain("read_tab");
+ expect(tools).not.toContain("send_to_tab");
+ });
+
+ it("grants both when both permissions are allowed", async () => {
+ const tools = await toolsForPerms("tab-both", {
+ perm_send_to_tab: "allow",
+ perm_read_tab: "allow",
+ });
+ expect(tools).toContain("send_to_tab");
+ expect(tools).toContain("read_tab");
+ });
+
+ it("grants neither when both permissions are off", async () => {
+ const tools = await toolsForPerms("tab-neither", {});
+ expect(tools).not.toContain("send_to_tab");
+ expect(tools).not.toContain("read_tab");
+ });
+ });
});
diff --git a/packages/api/tests/routes.test.ts b/packages/api/tests/routes.test.ts
index 4b8dd40..9ab2afe 100644
--- a/packages/api/tests/routes.test.ts
+++ b/packages/api/tests/routes.test.ts
@@ -166,6 +166,34 @@ vi.mock("@dispatch/core", () => ({
};
},
createTab() {},
+ getTab() {
+ return null;
+ },
+ listOpenTabs() {
+ return [];
+ },
+ resolveTabPrefix() {
+ return { status: "none" };
+ },
+ shortestUniquePrefix(id: string) {
+ return (id ?? "").slice(0, 4);
+ },
+ createSendToTabTool(_callbacks: unknown) {
+ return {
+ name: "send_to_tab",
+ description: "send to tab",
+ parameters: { _type: "z.ZodObject", shape: {} },
+ execute: async () => "mock",
+ };
+ },
+ createReadTabTool(_callbacks: unknown) {
+ return {
+ name: "read_tab",
+ description: "read tab",
+ parameters: { _type: "z.ZodObject", shape: {} },
+ execute: async () => "mock",
+ };
+ },
getClaudeAccountsFromDB() {
return [];
},
diff --git a/packages/core/src/agents/loader.ts b/packages/core/src/agents/loader.ts
index 333716e..f4a6c5a 100644
--- a/packages/core/src/agents/loader.ts
+++ b/packages/core/src/agents/loader.ts
@@ -108,8 +108,8 @@ export function expandAgentToolNames(tools: string[]): string[] {
default:
// Pass through tool names that aren't permission-group
// aliases (summon, retrieve, web_search, youtube_transcribe,
- // todo, and the granular file tools themselves if a user
- // hand-wrote them in a TOML).
+ // send_to_tab, read_tab, todo, and the granular file tools
+ // themselves if a user hand-wrote them in a TOML).
expanded.add(t);
}
}
diff --git a/packages/core/src/db/tabs.ts b/packages/core/src/db/tabs.ts
index 928f434..8b290d2 100644
--- a/packages/core/src/db/tabs.ts
+++ b/packages/core/src/db/tabs.ts
@@ -159,3 +159,78 @@ export function getDescendantIds(rootId: string): string[] {
}
return order.reverse();
}
+
+/**
+ * Minimum length of a tab-handle prefix accepted by `resolveTabPrefix`.
+ * Mirrors the frontend's minimum DISPLAY length (4 hex chars). Anything
+ * shorter is rejected as too broad — an agent must echo at least the 4-char
+ * handle shown in the UI.
+ */
+export const MIN_TAB_PREFIX_LENGTH = 4;
+
+/**
+ * Outcome of resolving a short tab handle (a git-style prefix of a tab's
+ * UUID) back to a concrete open tab.
+ *
+ * - `ok` — exactly one open tab matched; `tab` is it.
+ * - `none` — no open tab matched (bad/stale handle, or too-short prefix).
+ * - `ambiguous` — more than one open tab shares the prefix; `matches` lists
+ * them so the caller can ask for one more character (the same
+ * UX as `git checkout <ambiguous-sha>`).
+ */
+export type ResolveTabPrefixResult =
+ | { status: "ok"; tab: TabRow }
+ | { status: "none" }
+ | { status: "ambiguous"; matches: TabRow[] };
+
+/**
+ * Resolve a short tab handle to a single OPEN tab by prefix match — the
+ * git-short-hash model. The handle is NEVER stored: it is always derived from
+ * (and matched against) the canonical lowercase UUID in `tabs.id`.
+ *
+ * Sanitization is mandatory because the SQLite `LIKE` operator treats `%` and
+ * `_` as wildcards: an unsanitized prefix like `a%` would match broadly. We
+ * lowercase the input (UUIDs are canonical lowercase; SQLite `LIKE` is also
+ * ASCII-case-insensitive by default) and strip everything outside the UUID
+ * alphabet `[0-9a-f-]` so no wildcard can survive into the query.
+ *
+ * A prefix shorter than `MIN_TAB_PREFIX_LENGTH` after sanitization returns
+ * `none` rather than matching a large swath of tabs.
+ *
+ * Only OPEN tabs (`is_open = 1`) are addressable — a closed tab's UUID prefix
+ * must not cause phantom ambiguity or resolve to a dead conversation.
+ */
+export function resolveTabPrefix(prefix: string): ResolveTabPrefixResult {
+ const sanitized = (prefix ?? "").toLowerCase().replace(/[^0-9a-f-]/g, "");
+ if (sanitized.length < MIN_TAB_PREFIX_LENGTH) {
+ return { status: "none" };
+ }
+ const db = getDatabase();
+ const rows = db
+ .query("SELECT * FROM tabs WHERE is_open = 1 AND id LIKE $prefix ORDER BY position ASC")
+ .all({ $prefix: `${sanitized}%` }) as Array<Record<string, unknown>>;
+ if (rows.length === 0) return { status: "none" };
+ if (rows.length === 1) return { status: "ok", tab: rowToTab(rows[0] as Record<string, unknown>) };
+ return { status: "ambiguous", matches: rows.map(rowToTab) };
+}
+
+/**
+ * Compute the shortest unique prefix (minimum `MIN_TAB_PREFIX_LENGTH` chars)
+ * that identifies `tabId` among the currently OPEN tabs — the backend twin of
+ * the frontend's display helper. Used when a tool needs to echo a tab's own
+ * handle (e.g. provenance prefixes, "available tabs" hints) without trusting a
+ * value from the wire.
+ *
+ * Returns the full id if no shorter unique prefix exists (degenerate — only if
+ * two open tabs share an entire id, which UUID uniqueness precludes).
+ */
+export function shortestUniquePrefix(tabId: string): string {
+ const db = getDatabase();
+ const rows = db.query("SELECT id FROM tabs WHERE is_open = 1").all() as Array<{ id: string }>;
+ const others = rows.map((r) => r.id).filter((id) => id !== tabId);
+ for (let len = MIN_TAB_PREFIX_LENGTH; len < tabId.length; len++) {
+ const candidate = tabId.slice(0, len);
+ if (!others.some((id) => id.startsWith(candidate))) return candidate;
+ }
+ return tabId;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index a3816ea..b1b17cc 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -49,6 +49,10 @@ export {
createTab,
getTab,
listOpenTabs,
+ MIN_TAB_PREFIX_LENGTH,
+ type ResolveTabPrefixResult,
+ resolveTabPrefix,
+ shortestUniquePrefix,
type TabRow,
updateTabModel,
updateTabStatus,
@@ -78,9 +82,16 @@ export { prefix as bashArityPrefix } from "./tools/bash-arity.js";
export { createListFilesTool } from "./tools/list-files.js";
export { createReadFileTool } from "./tools/read-file.js";
export { createReadFileSliceTool } from "./tools/read-file-slice.js";
+export { createReadTabTool, type ReadTabCallbacks } from "./tools/read-tab.js";
export { createToolRegistry } from "./tools/registry.js";
export { createRetrieveTool, type RetrieveCallbacks } from "./tools/retrieve.js";
export { BackgroundShellStore, createRunShellTool } from "./tools/run-shell.js";
+export {
+ createSendToTabTool,
+ type ResolvedTabRef,
+ type SendToTabCallbacks,
+ type TabResolution,
+} from "./tools/send-to-tab.js";
export { analyzeCommand } from "./tools/shell-analyze.js";
export {
type AvailableAgent,
diff --git a/packages/core/src/llm/debug-logger.ts b/packages/core/src/llm/debug-logger.ts
index 2b7420c..072a7a1 100644
--- a/packages/core/src/llm/debug-logger.ts
+++ b/packages/core/src/llm/debug-logger.ts
@@ -281,11 +281,7 @@ export function logStepLifecycle(data: {
* Log agent loop-level events (loop start, break conditions, etc.).
* Only logs at verbosity >= 3.
*/
-export function logAgentLoop(data: {
- tabId?: string;
- event: string;
- detail?: unknown;
-}): void {
+export function logAgentLoop(data: { tabId?: string; event: string; detail?: unknown }): void {
if (!ENABLED || VERBOSITY < 3) return;
const detail = data.detail !== undefined ? ` ${JSON.stringify(data.detail)}` : "";
console.error(`[dispatch-debug] AGENT tab=${data.tabId ?? "?"} ${data.event}${detail}`);
@@ -308,16 +304,14 @@ export function logAgentLoop(data: {
* we just clone and read once via `.text()` — simpler and safe because
* non-streaming bodies are bounded.
*/
-export function wrapFetchWithLogging<
- F extends (...args: never[]) => Promise<Response> | Response,
->(baseFetch: F, opts: { tabId?: string; modelHint?: string }): F {
+export function wrapFetchWithLogging<F extends (...args: never[]) => Promise<Response> | Response>(
+ baseFetch: F,
+ opts: { tabId?: string; modelHint?: string },
+): F {
if (!ENABLED) return baseFetch;
const wrapped = async (...args: Parameters<F>) => {
const requestId = ++seq;
- const [input, init] = args as unknown as [
- RequestInfo | URL,
- RequestInit | undefined,
- ];
+ const [input, init] = args as unknown as [RequestInfo | URL, RequestInit | undefined];
const url =
typeof input === "string"
? input
@@ -325,7 +319,8 @@ export function wrapFetchWithLogging<
? input.toString()
: (input as Request).url;
const method =
- init?.method ?? (typeof input === "object" && "method" in input ? (input as Request).method : "POST");
+ init?.method ??
+ (typeof input === "object" && "method" in input ? (input as Request).method : "POST");
// Snapshot headers as a plain object for logging.
const headerObj: Record<string, string> = {};
diff --git a/packages/core/src/tools/read-tab.ts b/packages/core/src/tools/read-tab.ts
new file mode 100644
index 0000000..e80dbd0
--- /dev/null
+++ b/packages/core/src/tools/read-tab.ts
@@ -0,0 +1,95 @@
+import { z } from "zod";
+import type { AgentStatus, ToolDefinition } from "../types/index.js";
+import type { TabResolution } from "./send-to-tab.js";
+
+export interface ReadTabCallbacks {
+ /** Resolve a (possibly short) handle to one open tab. */
+ resolveShortId(prefix: string): TabResolution;
+ /**
+ * Return the target tab's most recent COMPLETED assistant turn as plain
+ * text, plus its current status. `text` is null when the tab has no
+ * completed assistant turn yet.
+ */
+ getLastResponse(tabId: string): { text: string | null; status: AgentStatus };
+ /** Snapshot of currently-open tabs, for "available tabs" error hints. */
+ listOpenHandles(): Array<{ handle: string; title: string }>;
+}
+
+/** Render the "available tabs" hint shared by the none/ambiguous branches. */
+function renderOpenHandles(handles: Array<{ handle: string; title: string }>): string {
+ if (handles.length === 0) return "No other tabs are currently open.";
+ const lines = handles.map((h) => ` - ${h.handle}: ${h.title}`);
+ return ["Currently open tabs:", ...lines].join("\n");
+}
+
+export function createReadTabTool(callbacks: ReadTabCallbacks): ToolDefinition {
+ return {
+ name: "read_tab",
+ description: [
+ "Read the most recent completed response from another tab (agent) by its short ID.",
+ "",
+ "Returns a SNAPSHOT — it does NOT block or wait for the target to finish.",
+ " - If the target is idle, you get its just-finished turn.",
+ " - If the target is still running, you get its PREVIOUS completed turn (if any);",
+ " call read_tab again later to get the newest one.",
+ "",
+ "Use this after send_to_tab to collect another agent's reply. IDs are git-style",
+ "prefixes: pass any length that uniquely identifies the target (min 4 chars).",
+ ].join("\n"),
+ parameters: z.object({
+ tab_id: z
+ .string()
+ .describe(
+ "The short ID (handle) of the tab to read, as shown in the tab bar. Any unique-length prefix works (min 4 chars).",
+ ),
+ }),
+ execute: async (args: Record<string, unknown>): Promise<string> => {
+ const rawId = (args.tab_id as string | undefined)?.trim() ?? "";
+
+ if (!rawId) {
+ return `Error: tab_id is required.\n\n${renderOpenHandles(callbacks.listOpenHandles())}`;
+ }
+
+ const resolution = callbacks.resolveShortId(rawId);
+
+ if (resolution.status === "none") {
+ return [
+ `Error: no open tab matches the ID "${rawId}".`,
+ "",
+ renderOpenHandles(callbacks.listOpenHandles()),
+ ].join("\n");
+ }
+ if (resolution.status === "ambiguous") {
+ const matches = resolution.matches.map((m) => ` - ${m.handle}: ${m.title}`).join("\n");
+ return [
+ `Error: the ID "${rawId}" is ambiguous — it matches multiple open tabs:`,
+ matches,
+ "",
+ "Add one or more characters to disambiguate.",
+ ].join("\n");
+ }
+
+ const target = resolution.tab;
+ const { text, status } = callbacks.getLastResponse(target.id);
+
+ const runningNote =
+ status === "running"
+ ? " (this tab is still running; the response below is its previous completed turn — read again later for the newest)"
+ : "";
+
+ if (text === null) {
+ const reason =
+ status === "running"
+ ? "it is still working on its first turn"
+ : "it has no assistant responses yet";
+ return `Tab ${target.handle} (${target.title}) has no completed response — ${reason}.`;
+ }
+
+ return [
+ `<tab_response tab="${target.handle}" status="${status}"${runningNote}>`,
+ text,
+ "</tab_response>",
+ ].join("\n");
+ },
+ };
+}
diff --git a/packages/core/src/tools/send-to-tab.ts b/packages/core/src/tools/send-to-tab.ts
new file mode 100644
index 0000000..eb86b7e
--- /dev/null
+++ b/packages/core/src/tools/send-to-tab.ts
@@ -0,0 +1,147 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../types/index.js";
+
+/**
+ * A tab reference surfaced to the `send_to_tab` / `read_tab` tools. The tools
+ * are intentionally decoupled from the DB `TabRow` shape — the AgentManager
+ * maps `resolveTabPrefix(...)` results down to this minimal projection so the
+ * tools (and their unit tests) never depend on the persistence layer.
+ */
+export interface ResolvedTabRef {
+ /** The tab's canonical full UUID. */
+ id: string;
+ /** The tab's display title (for disambiguation hints). */
+ title: string;
+ /** The tab's current short handle (shortest unique prefix). */
+ handle: string;
+}
+
+/**
+ * Outcome of resolving a short tab handle. Mirrors core's
+ * `ResolveTabPrefixResult` but over the minimal `ResolvedTabRef` projection.
+ */
+export type TabResolution =
+ | { status: "ok"; tab: ResolvedTabRef }
+ | { status: "none" }
+ | { status: "ambiguous"; matches: ResolvedTabRef[] };
+
+export interface SendToTabCallbacks {
+ /** Resolve a (possibly short) handle to one open tab. */
+ resolveShortId(prefix: string): TabResolution;
+ /**
+ * Deliver `message` to `tabId`. If the target is mid-turn the message is
+ * queued (same path as a user message); if idle/errored it wakes the tab
+ * and starts a new turn. Returns quickly — does NOT block on the turn.
+ */
+ deliver(
+ tabId: string,
+ message: string,
+ ):
+ | Promise<{ status: "queued" | "started" | "suppressed" }>
+ | { status: "queued" | "started" | "suppressed" };
+ /** Snapshot of currently-open tabs, for "available tabs" error hints. */
+ listOpenHandles(): Array<{ handle: string; title: string }>;
+ /** The calling tab's own id + handle — used to block self-sends and to
+ * stamp provenance onto the delivered message. */
+ self: { id: string; handle: string };
+}
+
+/** Render the "available tabs" hint shared by the none/ambiguous branches. */
+function renderOpenHandles(handles: Array<{ handle: string; title: string }>): string {
+ if (handles.length === 0) return "No other tabs are currently open.";
+ const lines = handles.map((h) => ` - ${h.handle}: ${h.title}`);
+ return ["Currently open tabs:", ...lines].join("\n");
+}
+
+export function createSendToTabTool(callbacks: SendToTabCallbacks): ToolDefinition {
+ return {
+ name: "send_to_tab",
+ description: [
+ "Send a message to another tab (agent) by its short ID — the handle shown in the tab bar.",
+ "",
+ "Behaviour mirrors a user sending a message:",
+ " - If the target tab is mid-turn (busy), your message is QUEUED and picked up next.",
+ " - If the target tab is idle, your message WAKES it and starts a new turn.",
+ "",
+ "This is fire-and-forget: it returns immediately and does NOT wait for a reply.",
+ "Use the 'read_tab' tool with the same ID later to read the target's latest response.",
+ "",
+ "Your tab ID is auto-added to the top of the message so the recipient can reply to you.",
+ "IDs are git-style prefixes: pass any length that uniquely identifies the target (min 4 chars).",
+ "If the ID is ambiguous you'll be asked to add a character.",
+ ].join("\n"),
+ parameters: z.object({
+ tab_id: z
+ .string()
+ .describe(
+ "The short ID (handle) of the target tab, as shown in the tab bar. Any unique-length prefix of the tab's id works (min 4 chars).",
+ ),
+ message: z
+ .string()
+ .describe("The message to deliver to the target tab, exactly as a user would type it."),
+ }),
+ execute: async (args: Record<string, unknown>): Promise<string> => {
+ const rawId = (args.tab_id as string | undefined)?.trim() ?? "";
+ const message = (args.message as string | undefined) ?? "";
+
+ if (!rawId) {
+ return `Error: tab_id is required.\n\n${renderOpenHandles(callbacks.listOpenHandles())}`;
+ }
+ if (!message.trim()) {
+ return "Error: message must not be empty.";
+ }
+
+ const resolution = callbacks.resolveShortId(rawId);
+
+ if (resolution.status === "none") {
+ return [
+ `Error: no open tab matches the ID "${rawId}".`,
+ "",
+ renderOpenHandles(callbacks.listOpenHandles()),
+ ].join("\n");
+ }
+ if (resolution.status === "ambiguous") {
+ const matches = resolution.matches.map((m) => ` - ${m.handle}: ${m.title}`).join("\n");
+ return [
+ `Error: the ID "${rawId}" is ambiguous — it matches multiple open tabs:`,
+ matches,
+ "",
+ "Add one or more characters to disambiguate.",
+ ].join("\n");
+ }
+
+ const target = resolution.tab;
+
+ if (target.id === callbacks.self.id) {
+ return "Error: cannot send a message to your own tab.";
+ }
+
+ // Stamp provenance so the recipient (and the watching user) can see
+ // which tab the message came from and reply back via its handle.
+ const delivered = `[message from tab ${callbacks.self.handle}]\n\n${message}`;
+
+ try {
+ const result = await callbacks.deliver(target.id, delivered);
+ if (result.status === "suppressed") {
+ // The target hit its automatic agent-to-agent wake limit. The
+ // message was preserved (queued) but did NOT start a turn — a
+ // human must step in. Tell the sender plainly so it stops
+ // hammering the target and creating a runaway loop.
+ return [
+ `Message HELD for tab ${target.handle} (${target.title}) — it was NOT delivered as a wake.`,
+ `That tab has reached its automatic agent-to-agent message limit, so it will not`,
+ `auto-respond again until a human sends it a message. Do not keep resending:`,
+ `your message is already queued and will be seen when a human resumes that tab.`,
+ ].join("\n");
+ }
+ const verb =
+ result.status === "queued"
+ ? "queued (target is busy; it will be picked up next turn)"
+ : "delivered (target was idle; a new turn has started)";
+ return `Message ${verb}. Target tab: ${target.handle} (${target.title}). Use read_tab with "${target.handle}" to read its reply later.`;
+ } catch (err) {
+ return `Error delivering message: ${err instanceof Error ? err.message : String(err)}`;
+ }
+ },
+ };
+}
diff --git a/packages/core/src/tools/summon.ts b/packages/core/src/tools/summon.ts
index d40f0ca..4820e89 100644
--- a/packages/core/src/tools/summon.ts
+++ b/packages/core/src/tools/summon.ts
@@ -177,6 +177,8 @@ export function createSummonTool(
" - retrieve: Collect results from its children (required if summon is given)",
" - web_search: Search the web",
" - youtube_transcribe: Fetch YouTube video transcripts",
+ " - send_to_tab: Send a message to another tab/agent by its ID",
+ " - read_tab: Read another tab/agent's latest response by its ID",
"",
"The 'agent' parameter is required — every spawned agent must use a definition.",
"Tools default to the agent definition's tools, intersected with your own tools (you can't grant capabilities you don't have).",
@@ -232,6 +234,8 @@ export function createSummonTool(
"retrieve",
"web_search",
"youtube_transcribe",
+ "send_to_tab",
+ "read_tab",
]),
)
.optional()
@@ -262,7 +266,9 @@ export function createSummonTool(
const tools = args.tools as string[] | undefined;
const workingDirectory = args.working_directory as string | undefined;
const background = (args.background as boolean | undefined) ?? false;
- const topLevel = userAgentEnabled ? ((args.top_level as boolean | undefined) ?? false) : false;
+ const topLevel = userAgentEnabled
+ ? ((args.top_level as boolean | undefined) ?? false)
+ : false;
try {
const agentId = await callbacks.spawn({
diff --git a/packages/core/tests/agents/loader.test.ts b/packages/core/tests/agents/loader.test.ts
index 88173ea..35ab0cf 100644
--- a/packages/core/tests/agents/loader.test.ts
+++ b/packages/core/tests/agents/loader.test.ts
@@ -22,10 +22,34 @@ describe("expandAgentToolNames", () => {
expect(out).toContain("run_shell");
});
+ it("passes through the tab tools as independent names (no tab_comm group)", () => {
+ const out = expandAgentToolNames(["send_to_tab", "read_tab"]);
+ expect(out).toContain("send_to_tab");
+ expect(out).toContain("read_tab");
+ // Granting only one must not pull in the other.
+ const onlySend = expandAgentToolNames(["send_to_tab"]);
+ expect(onlySend).toContain("send_to_tab");
+ expect(onlySend).not.toContain("read_tab");
+ });
+
it("passes through non-group tool names unchanged", () => {
- const out = expandAgentToolNames(["summon", "retrieve", "web_search", "youtube_transcribe"]);
+ const out = expandAgentToolNames([
+ "summon",
+ "retrieve",
+ "web_search",
+ "youtube_transcribe",
+ "send_to_tab",
+ "read_tab",
+ ]);
expect(out).toEqual(
- expect.arrayContaining(["summon", "retrieve", "web_search", "youtube_transcribe"]),
+ expect.arrayContaining([
+ "summon",
+ "retrieve",
+ "web_search",
+ "youtube_transcribe",
+ "send_to_tab",
+ "read_tab",
+ ]),
);
});
diff --git a/packages/core/tests/db/tabs.test.ts b/packages/core/tests/db/tabs.test.ts
index e1c9bf8..67533dc 100644
--- a/packages/core/tests/db/tabs.test.ts
+++ b/packages/core/tests/db/tabs.test.ts
@@ -73,6 +73,22 @@ class FakeDatabase {
return [{ max_pos: maxPos }];
}
+ // resolveTabPrefix: open tabs whose id starts with a sanitized prefix.
+ // The production query binds `$prefix` as `<sanitized>%`; emulate SQLite
+ // LIKE prefix semantics here (case-insensitive, `%` = "rest of string").
+ if (norm === "SELECT * FROM tabs WHERE is_open = 1 AND id LIKE $prefix ORDER BY position ASC") {
+ const raw = String(params?.$prefix ?? "");
+ const needle = raw.endsWith("%") ? raw.slice(0, -1) : raw;
+ return this.rows
+ .filter((r) => r.is_open === 1 && r.id.toLowerCase().startsWith(needle.toLowerCase()))
+ .sort((a, b) => a.position - b.position);
+ }
+
+ // shortestUniquePrefix: all open tab ids.
+ if (norm === "SELECT id FROM tabs WHERE is_open = 1") {
+ return this.rows.filter((r) => r.is_open === 1).map((r) => ({ id: r.id }));
+ }
+
throw new Error(`FakeDatabase: unsupported SELECT: ${norm}`);
}
@@ -134,7 +150,8 @@ vi.mock("../../src/db/index.js", () => ({
// Dynamic import AFTER `vi.mock` registers (vitest hoists `vi.mock` to
// the very top of the file, so by the time this line runs the mock is
// active for `./index.js` resolution inside `tabs.ts`).
-const { archiveTab, createTab, getDescendantIds, getTab } = await import("../../src/db/tabs.js");
+const { archiveTab, createTab, getDescendantIds, getTab, resolveTabPrefix, shortestUniquePrefix } =
+ await import("../../src/db/tabs.js");
beforeAll(() => {
fakeDb = new FakeDatabase();
@@ -234,3 +251,103 @@ describe("getDescendantIds", () => {
expect(ids2).toEqual(["b1", "a1"]);
});
});
+
+// ---------------------------------------------------------------------------
+// resolveTabPrefix — git-style short-handle resolution
+// ---------------------------------------------------------------------------
+describe("resolveTabPrefix", () => {
+ it("returns none when the prefix is shorter than the minimum length", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "A");
+ // 3 chars < MIN_TAB_PREFIX_LENGTH (4)
+ expect(resolveTabPrefix("abc").status).toBe("none");
+ });
+
+ it("returns none when no open tab matches", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "A");
+ expect(resolveTabPrefix("ffff").status).toBe("none");
+ });
+
+ it("resolves a unique 4-char prefix to the single matching tab", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "Alpha");
+ createTab("9999aaaa-0000-4000-8000-000000000000", "Beta");
+ const res = resolveTabPrefix("abcd");
+ expect(res.status).toBe("ok");
+ if (res.status === "ok") {
+ expect(res.tab.id).toBe("abcd1234-0000-4000-8000-000000000000");
+ expect(res.tab.title).toBe("Alpha");
+ }
+ });
+
+ it("resolves the full UUID (a maximal prefix)", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "Alpha");
+ const res = resolveTabPrefix("abcd1234-0000-4000-8000-000000000000");
+ expect(res.status).toBe("ok");
+ });
+
+ it("reports ambiguity when multiple open tabs share the prefix", () => {
+ createTab("abcd1111-0000-4000-8000-000000000000", "One");
+ createTab("abcd2222-0000-4000-8000-000000000000", "Two");
+ const res = resolveTabPrefix("abcd");
+ expect(res.status).toBe("ambiguous");
+ if (res.status === "ambiguous") {
+ expect(res.matches).toHaveLength(2);
+ expect(res.matches.map((m) => m.title).sort()).toEqual(["One", "Two"]);
+ }
+ });
+
+ it("disambiguates when one more character is supplied", () => {
+ createTab("abcd1111-0000-4000-8000-000000000000", "One");
+ createTab("abcd2222-0000-4000-8000-000000000000", "Two");
+ const res = resolveTabPrefix("abcd1");
+ expect(res.status).toBe("ok");
+ if (res.status === "ok") expect(res.tab.title).toBe("One");
+ });
+
+ it("matches case-insensitively (UUIDs are lowercase; LIKE is ASCII-CI)", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "Alpha");
+ const res = resolveTabPrefix("ABCD");
+ expect(res.status).toBe("ok");
+ });
+
+ it("sanitizes LIKE wildcards so they cannot broaden the match", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "Alpha");
+ createTab("9999aaaa-0000-4000-8000-000000000000", "Beta");
+ // `%` would match everything if not stripped; after sanitization the
+ // query is effectively `abcd%` which matches only Alpha.
+ const res = resolveTabPrefix("ab%d");
+ // "ab%d" -> sanitized "abd" (3 chars) -> below min length -> none.
+ expect(res.status).toBe("none");
+ });
+
+ it("excludes archived (closed) tabs from matches", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "Alpha");
+ archiveTab("abcd1234-0000-4000-8000-000000000000");
+ expect(resolveTabPrefix("abcd").status).toBe("none");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// shortestUniquePrefix — display-handle derivation
+// ---------------------------------------------------------------------------
+describe("shortestUniquePrefix", () => {
+ it("returns a 4-char prefix when no other open tab collides", () => {
+ createTab("abcd1234-0000-4000-8000-000000000000", "Alpha");
+ expect(shortestUniquePrefix("abcd1234-0000-4000-8000-000000000000")).toBe("abcd");
+ });
+
+ it("grows the prefix one char at a time on a collision", () => {
+ createTab("abcd1111-0000-4000-8000-000000000000", "One");
+ createTab("abcd2222-0000-4000-8000-000000000000", "Two");
+ // First differing char is at index 4, so a 5-char prefix is unique.
+ expect(shortestUniquePrefix("abcd1111-0000-4000-8000-000000000000")).toBe("abcd1");
+ expect(shortestUniquePrefix("abcd2222-0000-4000-8000-000000000000")).toBe("abcd2");
+ });
+
+ it("ignores closed tabs when computing uniqueness", () => {
+ createTab("abcd1111-0000-4000-8000-000000000000", "One");
+ createTab("abcd2222-0000-4000-8000-000000000000", "Two");
+ archiveTab("abcd2222-0000-4000-8000-000000000000");
+ // With Two closed, One no longer collides → back to 4 chars.
+ expect(shortestUniquePrefix("abcd1111-0000-4000-8000-000000000000")).toBe("abcd");
+ });
+});
diff --git a/packages/core/tests/tools/read-tab.test.ts b/packages/core/tests/tools/read-tab.test.ts
new file mode 100644
index 0000000..71e419c
--- /dev/null
+++ b/packages/core/tests/tools/read-tab.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { createReadTabTool, type ReadTabCallbacks } from "../../src/tools/read-tab.js";
+import type { TabResolution } from "../../src/tools/send-to-tab.js";
+
+function makeCallbacks(overrides: Partial<ReadTabCallbacks> = {}): ReadTabCallbacks {
+ return {
+ resolveShortId: (): TabResolution => ({
+ status: "ok",
+ tab: { id: "target-id", title: "Target", handle: "targ" },
+ }),
+ getLastResponse: () => ({ text: "the answer is 42", status: "idle" }),
+ listOpenHandles: () => [{ handle: "targ", title: "Target" }],
+ ...overrides,
+ };
+}
+
+describe("createReadTabTool — schema & description", () => {
+ it("is a non-blocking snapshot read", () => {
+ const tool = createReadTabTool(makeCallbacks());
+ expect(tool.name).toBe("read_tab");
+ expect(tool.description).toContain("SNAPSHOT");
+ expect(tool.description.toLowerCase()).toContain("does not block");
+ });
+});
+
+describe("createReadTabTool — execute()", () => {
+ it("returns the last assistant response wrapped in a tab_response tag", async () => {
+ const tool = createReadTabTool(makeCallbacks());
+ const out = await tool.execute({ tab_id: "targ" });
+ expect(out).toContain("<tab_response");
+ expect(out).toContain('tab="targ"');
+ expect(out).toContain('status="idle"');
+ expect(out).toContain("the answer is 42");
+ expect(out).toContain("</tab_response>");
+ });
+
+ it("notes that a running tab's response is its previous completed turn", async () => {
+ const tool = createReadTabTool(
+ makeCallbacks({
+ getLastResponse: () => ({ text: "older turn", status: "running" }),
+ }),
+ );
+ const out = await tool.execute({ tab_id: "targ" });
+ expect(out).toContain("still running");
+ expect(out).toContain("older turn");
+ });
+
+ it("explains when a tab has no completed response yet (idle)", async () => {
+ const tool = createReadTabTool(
+ makeCallbacks({
+ getLastResponse: () => ({ text: null, status: "idle" }),
+ }),
+ );
+ const out = await tool.execute({ tab_id: "targ" });
+ expect(out).toContain("no completed response");
+ expect(out).toContain("no assistant responses yet");
+ });
+
+ it("explains when a tab is still on its first turn (running, no prior text)", async () => {
+ const tool = createReadTabTool(
+ makeCallbacks({
+ getLastResponse: () => ({ text: null, status: "running" }),
+ }),
+ );
+ const out = await tool.execute({ tab_id: "targ" });
+ expect(out).toContain("no completed response");
+ expect(out).toContain("still working on its first turn");
+ });
+
+ it("rejects an empty tab_id and lists open handles", async () => {
+ const tool = createReadTabTool(makeCallbacks());
+ const out = await tool.execute({ tab_id: "" });
+ expect(out).toContain("Error");
+ expect(out).toContain("targ");
+ });
+
+ it("returns a helpful error when the id is unknown", async () => {
+ const tool = createReadTabTool(makeCallbacks({ resolveShortId: () => ({ status: "none" }) }));
+ const out = await tool.execute({ tab_id: "zzzz" });
+ expect(out).toContain("no open tab matches");
+ expect(out).toContain("Currently open tabs:");
+ });
+
+ it("asks for more characters when the id is ambiguous", async () => {
+ const tool = createReadTabTool(
+ makeCallbacks({
+ resolveShortId: () => ({
+ status: "ambiguous",
+ matches: [
+ { id: "a1", title: "One", handle: "abcd1" },
+ { id: "a2", title: "Two", handle: "abcd2" },
+ ],
+ }),
+ }),
+ );
+ const out = await tool.execute({ tab_id: "abcd" });
+ expect(out).toContain("ambiguous");
+ expect(out).toContain("abcd1");
+ expect(out).toContain("abcd2");
+ });
+});
diff --git a/packages/core/tests/tools/send-to-tab.test.ts b/packages/core/tests/tools/send-to-tab.test.ts
new file mode 100644
index 0000000..4450fc5
--- /dev/null
+++ b/packages/core/tests/tools/send-to-tab.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+ createSendToTabTool,
+ type SendToTabCallbacks,
+ type TabResolution,
+} from "../../src/tools/send-to-tab.js";
+
+function makeCallbacks(overrides: Partial<SendToTabCallbacks> = {}): SendToTabCallbacks {
+ return {
+ resolveShortId: (): TabResolution => ({
+ status: "ok",
+ tab: { id: "target-id", title: "Target", handle: "targ" },
+ }),
+ deliver: () => ({ status: "started" }),
+ listOpenHandles: () => [{ handle: "targ", title: "Target" }],
+ self: { id: "self-id", handle: "self" },
+ ...overrides,
+ };
+}
+
+describe("createSendToTabTool — schema & description", () => {
+ it("exposes tab_id and message params and a fire-and-forget description", () => {
+ const tool = createSendToTabTool(makeCallbacks());
+ expect(tool.name).toBe("send_to_tab");
+ expect(tool.description).toContain("fire-and-forget");
+ expect(tool.description.toLowerCase()).toContain("queued");
+ });
+});
+
+describe("createSendToTabTool — execute()", () => {
+ it("delivers to a resolved target and reports the started status", async () => {
+ const deliver = vi.fn(() => ({ status: "started" as const }));
+ const tool = createSendToTabTool(makeCallbacks({ deliver }));
+ const out = await tool.execute({ tab_id: "targ", message: "hello there" });
+ expect(deliver).toHaveBeenCalledTimes(1);
+ const [targetId, delivered] = deliver.mock.calls[0] ?? [];
+ expect(targetId).toBe("target-id");
+ // Provenance prefix names the sending tab's handle.
+ expect(delivered).toContain("[message from tab self]");
+ expect(delivered).toContain("hello there");
+ expect(out).toContain("idle");
+ expect(out).toContain("targ");
+ });
+
+ it("reports the queued status when the target is busy", async () => {
+ const deliver = vi.fn(() => ({ status: "queued" as const }));
+ const tool = createSendToTabTool(makeCallbacks({ deliver }));
+ const out = await tool.execute({ tab_id: "targ", message: "ping" });
+ expect(out.toLowerCase()).toContain("queued");
+ expect(out.toLowerCase()).toContain("busy");
+ });
+
+ it("reports a HELD message when delivery is suppressed (auto-wake limit hit)", async () => {
+ const deliver = vi.fn(() => ({ status: "suppressed" as const }));
+ const tool = createSendToTabTool(makeCallbacks({ deliver }));
+ const out = await tool.execute({ tab_id: "targ", message: "ping again" });
+ expect(out).toContain("HELD");
+ expect(out.toLowerCase()).toContain("limit");
+ // It must steer the sender away from retrying in a loop.
+ expect(out.toLowerCase()).toContain("do not keep resending");
+ expect(out.toLowerCase()).toContain("human");
+ });
+
+ it("rejects an empty tab_id and lists open handles", async () => {
+ const tool = createSendToTabTool(makeCallbacks());
+ const out = await tool.execute({ tab_id: " ", message: "hi" });
+ expect(out).toContain("Error");
+ expect(out).toContain("targ");
+ });
+
+ it("rejects an empty message", async () => {
+ const deliver = vi.fn(() => ({ status: "started" as const }));
+ const tool = createSendToTabTool(makeCallbacks({ deliver }));
+ const out = await tool.execute({ tab_id: "targ", message: " " });
+ expect(out).toContain("Error");
+ expect(deliver).not.toHaveBeenCalled();
+ });
+
+ it("returns a helpful error and open-tab list when the id is unknown", async () => {
+ const deliver = vi.fn(() => ({ status: "started" as const }));
+ const tool = createSendToTabTool(
+ makeCallbacks({
+ resolveShortId: () => ({ status: "none" }),
+ deliver,
+ }),
+ );
+ const out = await tool.execute({ tab_id: "zzzz", message: "hi" });
+ expect(out).toContain("no open tab matches");
+ expect(out).toContain("Currently open tabs:");
+ expect(deliver).not.toHaveBeenCalled();
+ });
+
+ it("asks for more characters when the id is ambiguous", async () => {
+ const deliver = vi.fn(() => ({ status: "started" as const }));
+ const tool = createSendToTabTool(
+ makeCallbacks({
+ resolveShortId: () => ({
+ status: "ambiguous",
+ matches: [
+ { id: "a1", title: "One", handle: "abcd1" },
+ { id: "a2", title: "Two", handle: "abcd2" },
+ ],
+ }),
+ deliver,
+ }),
+ );
+ const out = await tool.execute({ tab_id: "abcd", message: "hi" });
+ expect(out).toContain("ambiguous");
+ expect(out).toContain("abcd1");
+ expect(out).toContain("abcd2");
+ expect(deliver).not.toHaveBeenCalled();
+ });
+
+ it("refuses to send to its own tab", async () => {
+ const deliver = vi.fn(() => ({ status: "started" as const }));
+ const tool = createSendToTabTool(
+ makeCallbacks({
+ resolveShortId: () => ({
+ status: "ok",
+ tab: { id: "self-id", title: "Me", handle: "self" },
+ }),
+ deliver,
+ }),
+ );
+ const out = await tool.execute({ tab_id: "self", message: "hi" });
+ expect(out).toContain("cannot send a message to your own tab");
+ expect(deliver).not.toHaveBeenCalled();
+ });
+
+ it("surfaces a thrown delivery error instead of crashing", async () => {
+ const tool = createSendToTabTool(
+ makeCallbacks({
+ deliver: () => {
+ throw new Error("boom");
+ },
+ }),
+ );
+ const out = await tool.execute({ tab_id: "targ", message: "hi" });
+ expect(out).toContain("Error delivering message");
+ expect(out).toContain("boom");
+ });
+});
diff --git a/packages/core/tests/tools/summon.test.ts b/packages/core/tests/tools/summon.test.ts
index 6597c21..f59f345 100644
--- a/packages/core/tests/tools/summon.test.ts
+++ b/packages/core/tests/tools/summon.test.ts
@@ -39,9 +39,13 @@ describe("createSummonTool — description content", () => {
path: "/home/u/.config/dispatch/agents/researcher.toml",
},
];
- const tool = createSummonTool("/tmp/work", noopCallbacks, agents, [], [
- "/home/u/.config/dispatch/agents",
- ]);
+ const tool = createSummonTool(
+ "/tmp/work",
+ noopCallbacks,
+ agents,
+ [],
+ ["/home/u/.config/dispatch/agents"],
+ );
expect(tool.description).toContain("programmer");
expect(tool.description).toContain("Programmer");
expect(tool.description).toContain("Implements code from a plan");
diff --git a/packages/frontend/src/lib/components/TabBar.svelte b/packages/frontend/src/lib/components/TabBar.svelte
index feb1e5b..3cbd849 100644
--- a/packages/frontend/src/lib/components/TabBar.svelte
+++ b/packages/frontend/src/lib/components/TabBar.svelte
@@ -56,6 +56,7 @@ const activeUserTabId = $derived(
>
<span class="flex items-center gap-1.5">
<span class="w-1.5 h-1.5 rounded-full shrink-0 {statusColor(tab.agentStatus)}"></span>
+ <span class="font-mono text-[10px] px-1 py-0.5 rounded bg-base-300 text-base-content/60 shrink-0" title="Tab ID — agents address this tab by this handle">{tabStore.shortHandleFor(tab.id)}</span>
<span class="max-w-32 truncate text-xs">{tab.title}</span>
</span>
<button
@@ -89,6 +90,7 @@ const activeUserTabId = $derived(
>
<span class="flex items-center gap-1">
<span class="w-1 h-1 rounded-full shrink-0 {statusColor(tab.agentStatus)}"></span>
+ <span class="font-mono text-[10px] px-1 rounded bg-base-300 text-base-content/60 shrink-0" title="Tab ID — agents address this tab by this handle">{tabStore.shortHandleFor(tab.id)}</span>
<span class="max-w-28 truncate text-xs">{tab.title}</span>
</span>
{#if tab.persistent}
diff --git a/packages/frontend/src/lib/components/ToolPermissions.svelte b/packages/frontend/src/lib/components/ToolPermissions.svelte
index d64eaf9..0caf0fa 100644
--- a/packages/frontend/src/lib/components/ToolPermissions.svelte
+++ b/packages/frontend/src/lib/components/ToolPermissions.svelte
@@ -28,6 +28,16 @@ const toolPermissions: ToolPermission[] = [
description: "Allow the AI to open new independent top-level tabs",
},
{
+ id: "send_to_tab",
+ label: "Message other tabs",
+ description: "Allow the AI to send messages to other tabs by their ID",
+ },
+ {
+ id: "read_tab",
+ label: "Read other tabs",
+ description: "Allow the AI to read other tabs' latest responses by their ID",
+ },
+ {
id: "web_search",
label: "Web search",
description: "Allow the AI to search the web via Firecrawl",
diff --git a/packages/frontend/src/lib/settings.svelte.ts b/packages/frontend/src/lib/settings.svelte.ts
index 11eb79c..123008d 100644
--- a/packages/frontend/src/lib/settings.svelte.ts
+++ b/packages/frontend/src/lib/settings.svelte.ts
@@ -9,6 +9,8 @@ let toolPerms = $state<Record<string, boolean>>({
bash: false,
summon: false,
user_agent: false,
+ send_to_tab: false,
+ read_tab: false,
external_directory: false,
web_search: false,
youtube_transcribe: false,
@@ -19,6 +21,8 @@ let savedToolPerms = $state<Record<string, boolean>>({
bash: false,
summon: false,
user_agent: false,
+ send_to_tab: false,
+ read_tab: false,
external_directory: false,
web_search: false,
youtube_transcribe: false,
diff --git a/packages/frontend/src/lib/tabs.svelte.ts b/packages/frontend/src/lib/tabs.svelte.ts
index e303c80..317de8d 100644
--- a/packages/frontend/src/lib/tabs.svelte.ts
+++ b/packages/frontend/src/lib/tabs.svelte.ts
@@ -232,6 +232,29 @@ export function createTabStore() {
return tabs.find((t) => t.id === id);
}
+ /**
+ * Minimum display length of a tab handle (git-style short id). Mirrors
+ * `MIN_TAB_PREFIX_LENGTH` in core's `db/tabs.ts` so the handle the user sees
+ * is always resolvable by the backend's `resolveTabPrefix`.
+ */
+ const MIN_HANDLE_LENGTH = 4;
+
+ /**
+ * Compute the shortest unique prefix (≥ MIN_HANDLE_LENGTH chars) of `tabId`
+ * among all currently-open tabs — the displayed "handle" agents use to
+ * address each other. Purely DERIVED from the UUIDs already in `tabs`; never
+ * stored. Grows by one char only when another open tab shares the prefix, and
+ * shrinks back when that sibling closes.
+ */
+ function shortHandleFor(tabId: string): string {
+ const others = tabs.map((t) => t.id).filter((id) => id !== tabId);
+ for (let len = MIN_HANDLE_LENGTH; len < tabId.length; len++) {
+ const candidate = tabId.slice(0, len);
+ if (!others.some((id) => id.startsWith(candidate))) return candidate;
+ }
+ return tabId;
+ }
+
async function createNewTab(): Promise<Tab> {
const id = generateId();
const title = "New Tab";
@@ -1926,6 +1949,7 @@ export function createTabStore() {
get configReloaded() {
return configReloaded;
},
+ shortHandleFor,
createNewTab,
switchTab,
closeTab,