Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat: unified session resume via context_key (#11)

Gener25efebca090d
diff --git a/src/cli/daemon/execenv/__tests__/timeline.test.ts b/src/cli/daemon/execenv/__tests__/timeline.test.ts
index e7742f60a..26945dbc6 100644
--- a/src/cli/daemon/execenv/__tests__/timeline.test.ts
+++ b/src/cli/daemon/execenv/__tests__/timeline.test.ts
@@ -14,6 +14,7 @@ import {
updateEntry,
createTimelineEntry,
findResumableSessionId,
+ findResumableSessionByContextKey,
_todayFilename,
_localISOString,
_filenameForDate,
@@ -253,7 +254,7 @@ describe("timeline", () => {
function makeEntry(overrides: Partial<ContextTimelineEntry>): ContextTimelineEntry {
return {
task_id: "t_1",
- conversation_id: null,
+ context_key: null,
session_id: null,
pid: null,
status: "running",
@@ -489,70 +490,143 @@ describe("timeline", () => {
expect(findResumableSessionId(dir, "user_dm_message", "codex")).toBe("sess_codex");
});
- it("createTimelineEntry includes conversation_id when provided", () => {
- const entry = createTimelineEntry("t_c1", "test", "user_dm_message", "sess_1", 1234, "claude", "conv_abc");
- expect(entry.conversation_id).toBe("conv_abc");
+ it("createTimelineEntry includes context_key when provided", () => {
+ const entry = createTimelineEntry("t_c1", "test", "user_dm_message", "sess_1", 1234, "claude", "dm:conv_abc");
+ expect(entry.context_key).toBe("dm:conv_abc");
});
- it("createTimelineEntry sets conversation_id to null when not provided", () => {
+ it("createTimelineEntry sets context_key to null when not provided", () => {
const entry = createTimelineEntry("t_c2", "test", "user_dm_message");
- expect(entry.conversation_id).toBeNull();
+ expect(entry.context_key).toBeNull();
});
+ });
+
+ describe("findResumableSessionByContextKey", () => {
+ function writeEntry(filename: string, entry: ContextTimelineEntry) {
+ const filePath = join(dir, filename);
+ let existing = "";
+ try { existing = readFileSync(filePath, "utf-8"); } catch { /* new file */ }
+ writeFileSync(filePath, existing + JSON.stringify(entry) + "\n");
+ }
+
+ function makeEntry(overrides: Partial<ContextTimelineEntry>): ContextTimelineEntry {
+ return {
+ task_id: "t_1",
+ context_key: null,
+ session_id: null,
+ pid: null,
+ status: "running",
+ datetime: new Date().toISOString(),
+ type: "user_dm_message",
+ prompt: "test",
+ agent_responses: [],
+ errmsg: null,
+ provider: "claude",
+ ...overrides,
+ };
+ }
- it("filters by conversationId when provided", () => {
+ it("returns session_id from a completed entry matching context_key", () => {
writeEntry(_todayFilename(), makeEntry({
- task_id: "t_conv1",
+ task_id: "t_1",
status: "completed",
- session_id: "sess_conv1",
- conversation_id: "conv_1",
+ session_id: "sess_abc",
+ context_key: "dm:conv_1",
datetime: new Date().toISOString(),
}));
+
+ expect(findResumableSessionByContextKey(dir, "dm:conv_1", "claude")).toBe("sess_abc");
+ });
+
+ it("returns null when context_key does not match", () => {
writeEntry(_todayFilename(), makeEntry({
- task_id: "t_conv2",
+ task_id: "t_1",
status: "completed",
- session_id: "sess_conv2",
- conversation_id: "conv_2",
+ session_id: "sess_abc",
+ context_key: "dm:conv_1",
datetime: new Date().toISOString(),
}));
- expect(findResumableSessionId(dir, "user_dm_message", "claude", undefined, "conv_1")).toBe("sess_conv1");
- expect(findResumableSessionId(dir, "user_dm_message", "claude", undefined, "conv_2")).toBe("sess_conv2");
+ expect(findResumableSessionByContextKey(dir, "dm:conv_2", "claude")).toBeNull();
+ });
+
+ it("returns null when no entries exist", () => {
+ expect(findResumableSessionByContextKey(dir, "dm:conv_1", "claude")).toBeNull();
+ });
+
+ it("uses 3h max age for dm: context keys", () => {
+ const fourHoursAgo = new Date(Date.now() - 4 * 60 * 60 * 1000);
+ writeEntry(_todayFilename(), makeEntry({
+ task_id: "t_old",
+ status: "completed",
+ session_id: "sess_old",
+ context_key: "dm:conv_1",
+ datetime: fourHoursAgo.toISOString(),
+ }));
+
+ expect(findResumableSessionByContextKey(dir, "dm:conv_1", "claude")).toBeNull();
});
- it("returns null when conversationId doesn't match any entry", () => {
+ it("uses 48h max age for email: context keys", () => {
+ const twentyFourHoursAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
writeEntry(_todayFilename(), makeEntry({
- task_id: "t_conv1",
+ task_id: "t_email",
status: "completed",
- session_id: "sess_conv1",
- conversation_id: "conv_1",
- datetime: new Date().toISOString(),
+ session_id: "sess_email",
+ context_key: "email:<[email protected]>",
+ datetime: twentyFourHoursAgo.toISOString(),
+ }));
+
+ expect(findResumableSessionByContextKey(dir, "email:<[email protected]>", "claude")).toBe("sess_email");
+ });
+
+ it("email: context key expires after 48h", () => {
+ const fiftyHoursAgo = new Date(Date.now() - 50 * 60 * 60 * 1000);
+ writeEntry(_filenameForDate(fiftyHoursAgo), makeEntry({
+ task_id: "t_email_old",
+ status: "completed",
+ session_id: "sess_email_old",
+ context_key: "email:<[email protected]>",
+ datetime: fiftyHoursAgo.toISOString(),
}));
- expect(findResumableSessionId(dir, "user_dm_message", "claude", undefined, "conv_other")).toBeNull();
+ expect(findResumableSessionByContextKey(dir, "email:<[email protected]>", "claude")).toBeNull();
});
- it("ignores conversationId filter when not provided (backward compat)", () => {
+ it("filters by provider", () => {
writeEntry(_todayFilename(), makeEntry({
- task_id: "t_conv1",
+ task_id: "t_1",
status: "completed",
- session_id: "sess_conv1",
- conversation_id: "conv_1",
+ session_id: "sess_claude",
+ context_key: "dm:conv_1",
+ provider: "claude",
datetime: new Date().toISOString(),
}));
- expect(findResumableSessionId(dir, "user_dm_message", "claude")).toBe("sess_conv1");
+ expect(findResumableSessionByContextKey(dir, "dm:conv_1", "codex")).toBeNull();
+ expect(findResumableSessionByContextKey(dir, "dm:conv_1", "claude")).toBe("sess_claude");
});
- it("matches entries with null conversation_id when conversationId filter not provided", () => {
+ it("returns the latest matching entry", () => {
+ const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000);
+ const oneHourAgo = new Date(Date.now() - 1 * 60 * 60 * 1000);
+
writeEntry(_todayFilename(), makeEntry({
- task_id: "t_old",
+ task_id: "t_older",
status: "completed",
- session_id: "sess_old",
- conversation_id: null,
- datetime: new Date().toISOString(),
+ session_id: "sess_older",
+ context_key: "dm:conv_1",
+ datetime: twoHoursAgo.toISOString(),
+ }));
+ writeEntry(_todayFilename(), makeEntry({
+ task_id: "t_newer",
+ status: "completed",
+ session_id: "sess_newer",
+ context_key: "dm:conv_1",
+ datetime: oneHourAgo.toISOString(),
}));
- expect(findResumableSessionId(dir, "user_dm_message", "claude")).toBe("sess_old");
+ expect(findResumableSessionByContextKey(dir, "dm:conv_1", "claude")).toBe("sess_newer");
});
});
});
diff --git a/src/cli/daemon/execenv/timeline.ts b/src/cli/daemon/execenv/timeline.ts
index e2156e1e4..e29bfbbea 100644
--- a/src/cli/daemon/execenv/timeline.ts
+++ b/src/cli/daemon/execenv/timeline.ts
@@ -22,7 +22,7 @@ function readJsonl(filePath: string): ContextTimelineEntry[] {
export interface ContextTimelineEntry {
task_id: string;
- conversation_id: string | null;
+ context_key: string | null;
session_id: string | null;
pid: number | null;
status: "running" | "completed" | "failed" | "killed";
@@ -196,11 +196,11 @@ export function createTimelineEntry(
sessionId?: string,
pid?: number,
provider?: string,
- conversationId?: string,
+ contextKey?: string | null,
): ContextTimelineEntry {
return {
task_id: taskId,
- conversation_id: conversationId || null,
+ context_key: contextKey ?? null,
session_id: sessionId || null,
pid: pid ?? null,
status: "running",
@@ -220,7 +220,6 @@ export function findResumableSessionId(
type: string,
provider: string,
maxAgeMs: number = DEFAULT_RESUME_MAX_AGE_MS,
- conversationId?: string,
): string | null {
const now = new Date();
const cutoff = new Date(now.getTime() - maxAgeMs);
@@ -240,8 +239,7 @@ export function findResumableSessionId(
entry.type === type &&
entry.provider === provider &&
entry.session_id &&
- new Date(entry.datetime) >= cutoff &&
- (!conversationId || entry.conversation_id === conversationId)
+ new Date(entry.datetime) >= cutoff
) {
return entry.session_id;
}
@@ -250,6 +248,38 @@ export function findResumableSessionId(
return null;
}
+const EMAIL_RESUME_MAX_AGE_MS = 48 * 60 * 60 * 1000;
+
+export function findResumableSessionByContextKey(
+ timelineDir: string,
+ contextKey: string,
+ provider: string,
+): string | null {
+ const maxAgeMs = contextKey.startsWith("email:")
+ ? EMAIL_RESUME_MAX_AGE_MS
+ : DEFAULT_RESUME_MAX_AGE_MS;
+ const now = new Date();
+ const cutoff = new Date(now.getTime() - maxAgeMs);
+ const daysToScan = Math.ceil(maxAgeMs / 86_400_000) + 1;
+ const entries: ContextTimelineEntry[] = [];
+ for (const filename of recentFilenames(daysToScan)) {
+ entries.push(...readJsonl(join(timelineDir, filename)));
+ }
+ entries.sort((a, b) => new Date(b.datetime).getTime() - new Date(a.datetime).getTime());
+ for (const entry of entries) {
+ if (
+ entry.status === "completed" &&
+ entry.context_key === contextKey &&
+ entry.provider === provider &&
+ entry.session_id &&
+ new Date(entry.datetime) >= cutoff
+ ) {
+ return entry.session_id;
+ }
+ }
+ return null;
+}
+
export { localISOString };
// Exported for testing
diff --git a/src/cli/daemon/session-runner.test.ts b/src/cli/daemon/session-runner.test.ts
index 266bf292c..3932f3b24 100644
--- a/src/cli/daemon/session-runner.test.ts
+++ b/src/cli/daemon/session-runner.test.ts
@@ -38,10 +38,10 @@ const mockCreateTimelineEntry = vi.fn(
sessionId?: string,
pid?: number,
provider?: string,
- conversationId?: string,
+ contextKey?: string | null,
) => ({
task_id: taskId,
- conversation_id: conversationId || null,
+ context_key: contextKey ?? null,
session_id: sessionId || null,
pid: pid ?? null,
status: "running",
@@ -53,12 +53,12 @@ const mockCreateTimelineEntry = vi.fn(
provider: provider || null,
}),
);
-const mockFindResumableSessionId = vi.fn(() => null);
+const mockFindResumableSessionByContextKey = vi.fn(() => null);
vi.mock("./execenv/timeline.js", () => ({
initEntryAsync: (...args: any[]) => mockInitEntryAsync(...args),
updateEntry: (...args: any[]) => mockUpdateEntry(...args),
createTimelineEntry: (...args: any[]) => mockCreateTimelineEntry(...args),
- findResumableSessionId: (...args: any[]) => mockFindResumableSessionId(...args),
+ findResumableSessionByContextKey: (...args: any[]) => mockFindResumableSessionByContextKey(...args),
localISOString: () => "2026-04-16T10:00:00-05:00",
}));
@@ -98,6 +98,7 @@ function makeInput(overrides?: Partial<SessionRunnerInput>): SessionRunnerInput
status: "dispatched",
priority: 0,
type: "user_dm_message",
+ contextKey: "dm:c1",
createdAt: "2026-01-01T00:00:00Z",
},
provider: "claude",
@@ -215,7 +216,7 @@ describe("session-runner runSession", () => {
"sess-1",
process.pid,
"claude",
- "c1",
+ "dm:c1",
);
expect(mockInitEntryAsync).toHaveBeenCalledWith(
"/tmp/ws/ws1/agent1/workdir/.context_timeline",
@@ -326,8 +327,8 @@ describe("session-runner runSession", () => {
expect(totalReported).toBe(25);
});
- it("uses findResumableSessionId and passes to backend for user_dm_message tasks", async () => {
- mockFindResumableSessionId.mockReturnValueOnce("prev-session-123");
+ it("uses findResumableSessionByContextKey and passes to backend for user_dm_message tasks", async () => {
+ mockFindResumableSessionByContextKey.mockReturnValueOnce("prev-session-123");
setupBackend([], {
status: "completed",
@@ -339,12 +340,10 @@ describe("session-runner runSession", () => {
await runSession(makeInput());
- expect(mockFindResumableSessionId).toHaveBeenCalledWith(
+ expect(mockFindResumableSessionByContextKey).toHaveBeenCalledWith(
"/tmp/ws/ws1/agent1/workdir/.context_timeline",
- "user_dm_message",
+ "dm:c1",
"claude",
- undefined,
- "c1",
);
expect(mockBackendExecute).toHaveBeenCalledWith(
expect.any(String),
@@ -352,7 +351,7 @@ describe("session-runner runSession", () => {
);
});
- it("skips findResumableSessionId entirely for calendar_event tasks (always fresh session)", async () => {
+ it("skips findResumableSessionByContextKey for calendar_event tasks (no contextKey)", async () => {
setupBackend([], {
status: "completed",
output: "Done",
@@ -378,7 +377,7 @@ describe("session-runner runSession", () => {
}),
);
- expect(mockFindResumableSessionId).not.toHaveBeenCalled();
+ expect(mockFindResumableSessionByContextKey).not.toHaveBeenCalled();
expect(mockBackendExecute).toHaveBeenCalledWith(
expect.any(String),
expect.objectContaining({ resumeSessionId: undefined }),
@@ -581,11 +580,11 @@ describe("session-runner runSession", () => {
"sess-1",
process.pid,
"codex",
- "c1",
+ "dm:c1",
);
});
- it("passes provider to findResumableSessionId", async () => {
+ it("passes provider to findResumableSessionByContextKey", async () => {
setupBackend([], {
status: "completed",
output: "Done",
@@ -596,17 +595,15 @@ describe("session-runner runSession", () => {
await runSession(makeInput({ provider: "codex" }));
- expect(mockFindResumableSessionId).toHaveBeenCalledWith(
+ expect(mockFindResumableSessionByContextKey).toHaveBeenCalledWith(
"/tmp/ws/ws1/agent1/workdir/.context_timeline",
- "user_dm_message",
+ "dm:c1",
"codex",
- undefined,
- "c1",
);
});
- it("session resume works when findResumableSessionId returns a session for matching provider", async () => {
- mockFindResumableSessionId.mockReturnValueOnce("prev-sess-codex");
+ it("session resume works when findResumableSessionByContextKey returns a session for matching provider", async () => {
+ mockFindResumableSessionByContextKey.mockReturnValueOnce("prev-sess-codex");
setupBackend([], {
status: "completed",
@@ -625,7 +622,7 @@ describe("session-runner runSession", () => {
});
it("session starts fresh when provider has no matching prior entry", async () => {
- mockFindResumableSessionId.mockReturnValueOnce(null);
+ mockFindResumableSessionByContextKey.mockReturnValueOnce(null);
setupBackend([], {
status: "completed",
@@ -637,12 +634,10 @@ describe("session-runner runSession", () => {
await runSession(makeInput({ provider: "opencode" }));
- expect(mockFindResumableSessionId).toHaveBeenCalledWith(
+ expect(mockFindResumableSessionByContextKey).toHaveBeenCalledWith(
"/tmp/ws/ws1/agent1/workdir/.context_timeline",
- "user_dm_message",
+ "dm:c1",
"opencode",
- undefined,
- "c1",
);
expect(mockBackendExecute).toHaveBeenCalledWith(
expect.any(String),
diff --git a/src/cli/daemon/session-runner.ts b/src/cli/daemon/session-runner.ts
index 2fb341c2c..3431e38f2 100644
--- a/src/cli/daemon/session-runner.ts
+++ b/src/cli/daemon/session-runner.ts
@@ -15,12 +15,11 @@ import {
updateEntry,
createTimelineEntry,
localISOString,
- findResumableSessionId,
+ findResumableSessionByContextKey,
} from "./execenv/timeline.js";
import { buildPrompt } from "./prompt.js";
import { log } from "../lib/logger.js";
import type { SessionRunnerInput } from "./types.js";
-import { TASK_TYPES } from "@alook/shared";
export async function runSession(input: SessionRunnerInput): Promise<void> {
const { task, provider, cliPath, model, serverURL, token, workspacesRoot, agentTimeout } = input;
@@ -34,12 +33,11 @@ export async function runSession(input: SessionRunnerInput): Promise<void> {
task,
);
- const resumeSessionId =
- task.type === TASK_TYPES.USER_DM_MESSAGE
- ? findResumableSessionId(timelineDir, task.type, provider, undefined, task.conversationId) ?? undefined
- : undefined;
+ const resumeSessionId = task.contextKey
+ ? findResumableSessionByContextKey(timelineDir, task.contextKey, provider) ?? undefined
+ : undefined;
if (resumeSessionId) {
- log.info(`Task ${task.id} resuming session ${resumeSessionId}`);
+ log.info(`Task ${task.id} resuming session ${resumeSessionId} (context_key: ${task.contextKey})`);
}
const session = backend.execute(prompt, {
@@ -57,7 +55,7 @@ export async function runSession(input: SessionRunnerInput): Promise<void> {
const earlySessionId = await session.sessionId;
await initEntryAsync(
timelineDir,
- createTimelineEntry(task.id, task.prompt, task.type, earlySessionId, process.pid, provider, task.conversationId),
+ createTimelineEntry(task.id, task.prompt, task.type, earlySessionId, process.pid, provider, task.contextKey),
);
// Message batching
diff --git a/src/cli/daemon/types.ts b/src/cli/daemon/types.ts
index 5c5e972ed..caa545683 100644
--- a/src/cli/daemon/types.ts
+++ b/src/cli/daemon/types.ts
@@ -8,6 +8,7 @@ export interface Task {
status: string;
priority: number;
type: string;
+ contextKey?: string | null;
agent?: TaskAgentData;
repos?: RepoData[];
createdAt: string;
@@ -101,6 +102,7 @@ export function fromApiTask(api: import("@alook/shared").TaskApi): Task {
status: api.status,
priority: api.priority,
type: api.type,
+ contextKey: api.context_key ?? null,
agent: api.agent
? { name: api.agent.name, instructions: api.agent.instructions, emailHandle: api.agent.email_handle ?? undefined, userEmail: api.agent.user_email ?? undefined, runtimeConfig: api.agent.runtime_config ?? undefined }
: undefined,
diff --git a/src/shared/src/db/queries/task.ts b/src/shared/src/db/queries/task.ts
index 5ddbc5138..cd3c0db79 100644
--- a/src/shared/src/db/queries/task.ts
+++ b/src/shared/src/db/queries/task.ts
@@ -13,6 +13,7 @@ export async function createTask(
conversationId: string;
prompt: string;
type?: string;
+ contextKey?: string | null;
priority?: number;
}
) {
@@ -25,6 +26,7 @@ export async function createTask(
conversationId: data.conversationId,
prompt: data.prompt,
type: data.type ?? TASK_TYPES.USER_DM_MESSAGE,
+ contextKey: data.contextKey ?? null,
priority: data.priority ?? 0,
})
.returning();
diff --git a/src/shared/src/db/schema.ts b/src/shared/src/db/schema.ts
index 85807fc7e..80a043579 100644
--- a/src/shared/src/db/schema.ts
+++ b/src/shared/src/db/schema.ts
@@ -229,6 +229,7 @@ export const agentTaskQueue = sqliteTable(
.references(() => conversation.id),
prompt: text("prompt").notNull(),
type: text("type").notNull().default(TASK_TYPES.USER_DM_MESSAGE),
+ contextKey: text("context_key"),
status: text("status").notNull().default("queued"),
priority: integer("priority").notNull().default(0),
result: text("result", { mode: "json" }),
diff --git a/src/shared/src/index.ts b/src/shared/src/index.ts
index 18292f70e..919d072a8 100644
--- a/src/shared/src/index.ts
+++ b/src/shared/src/index.ts
@@ -135,6 +135,7 @@ export type { LogLevel, LoggerOptions } from "./logger"
// Lib
export { isEmptyHtml } from "./lib/html";
+export { buildContextKey, extractThreadId } from "./lib/context-key";
export {
addRepeatInterval,
computeNextScheduledAt,
diff --git a/src/shared/src/lib/context-key.test.ts b/src/shared/src/lib/context-key.test.ts
new file mode 100644
index 000000000..cb1491e03
--- /dev/null
+++ b/src/shared/src/lib/context-key.test.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+import { extractThreadId, buildContextKey } from "./context-key";
+import { TASK_TYPES } from "../constants";
+
+describe("extractThreadId", () => {
+ it("returns first message-id from references when available", () => {
+ expect(
+ ).toBe("<[email protected]>");
+ });
+
+ it("falls back to inReplyTo when references is empty", () => {
+ expect(extractThreadId("", "<[email protected]>", "<[email protected]>")).toBe("<[email protected]>");
+ });
+
+ it("falls back to inReplyTo when references is undefined", () => {
+ expect(extractThreadId(undefined, "<[email protected]>", "<[email protected]>")).toBe(
+ );
+ });
+
+ it("falls back to messageId when references and inReplyTo are empty", () => {
+ expect(extractThreadId("", "", "<[email protected]>")).toBe("<[email protected]>");
+ });
+
+ it("falls back to messageId when references and inReplyTo are undefined", () => {
+ expect(extractThreadId(undefined, undefined, "<[email protected]>")).toBe("<[email protected]>");
+ });
+
+ it("returns null when all inputs are empty strings", () => {
+ expect(extractThreadId("", "", "")).toBeNull();
+ });
+
+ it("returns null when all inputs are undefined", () => {
+ expect(extractThreadId(undefined, undefined, undefined)).toBeNull();
+ });
+
+ it("returns null when no arguments provided", () => {
+ expect(extractThreadId()).toBeNull();
+ });
+
+ it("trims whitespace from inReplyTo", () => {
+ expect(extractThreadId(undefined, " <[email protected]> ")).toBe("<[email protected]>");
+ });
+
+ it("trims whitespace from messageId", () => {
+ expect(extractThreadId(undefined, undefined, " <[email protected]> ")).toBe(
+ );
+ });
+});
+
+describe("buildContextKey", () => {
+ it("returns dm:{conversationId} for USER_DM_MESSAGE with conversationId", () => {
+ expect(
+ buildContextKey(TASK_TYPES.USER_DM_MESSAGE, { conversationId: "conv_123" }),
+ ).toBe("dm:conv_123");
+ });
+
+ it("returns null for USER_DM_MESSAGE without conversationId", () => {
+ expect(buildContextKey(TASK_TYPES.USER_DM_MESSAGE, {})).toBeNull();
+ });
+
+ it("returns email:{threadId} for EMAIL_NOTIFICATION with threadId", () => {
+ expect(
+ buildContextKey(TASK_TYPES.EMAIL_NOTIFICATION, { threadId: "<[email protected]>" }),
+ ).toBe("email:<[email protected]>");
+ });
+
+ it("returns null for EMAIL_NOTIFICATION without threadId", () => {
+ expect(buildContextKey(TASK_TYPES.EMAIL_NOTIFICATION, {})).toBeNull();
+ });
+
+ it("returns null for EMAIL_NOTIFICATION with null threadId", () => {
+ expect(buildContextKey(TASK_TYPES.EMAIL_NOTIFICATION, { threadId: null })).toBeNull();
+ });
+
+ it("returns null for CALENDAR_EVENT", () => {
+ expect(buildContextKey(TASK_TYPES.CALENDAR_EVENT, {})).toBeNull();
+ });
+
+ it("returns null for CALENDAR_EVENT even with conversationId", () => {
+ expect(
+ buildContextKey(TASK_TYPES.CALENDAR_EVENT, { conversationId: "conv_123" }),
+ ).toBeNull();
+ });
+
+ it("returns null for unknown type", () => {
+ expect(buildContextKey("unknown_type", { conversationId: "conv_123" })).toBeNull();
+ });
+});
diff --git a/src/shared/src/lib/context-key.ts b/src/shared/src/lib/context-key.ts
new file mode 100644
index 000000000..da3fe55e0
--- /dev/null
+++ b/src/shared/src/lib/context-key.ts
@@ -0,0 +1,39 @@
+import { TASK_TYPES } from "../constants";
+
+/**
+ * Extract a stable thread identifier from email headers (RFC 2822).
+ * Priority: first message-id in References > In-Reply-To > own Message-ID.
+ */
+export function extractThreadId(
+ references?: string,
+ inReplyTo?: string,
+ messageId?: string,
+): string | null {
+ if (references) {
+ const first = references.trim().split(/\s+/)[0];
+ if (first) return first;
+ }
+ if (inReplyTo) return inReplyTo.trim();
+ if (messageId) return messageId.trim();
+ return null;
+}
+
+/**
+ * Build a unified context key for session resumption.
+ * Returns null when the task type should never resume (e.g. calendar events).
+ */
+export function buildContextKey(
+ type: string,
+ opts: { conversationId?: string; threadId?: string | null },
+): string | null {
+ switch (type) {
+ case TASK_TYPES.USER_DM_MESSAGE:
+ return opts.conversationId ? `dm:${opts.conversationId}` : null;
+ case TASK_TYPES.EMAIL_NOTIFICATION:
+ return opts.threadId ? `email:${opts.threadId}` : null;
+ case TASK_TYPES.CALENDAR_EVENT:
+ return null;
+ default:
+ return null;
+ }
+}
diff --git a/src/shared/src/schemas.ts b/src/shared/src/schemas.ts
index 0ead95fbd..e9efbca42 100644
--- a/src/shared/src/schemas.ts
+++ b/src/shared/src/schemas.ts
@@ -30,6 +30,7 @@ export const ClaimedTaskRowSchema = z.object({
result: z.unknown().nullable(),
context: z.unknown().nullable(),
type: z.string().default(TASK_TYPES.USER_DM_MESSAGE),
+ contextKey: z.string().nullable().optional(),
sessionId: z.string().nullable(),
createdAt: z.coerce.date(),
dispatchedAt: z.coerce.date().nullable(),
@@ -72,6 +73,7 @@ export const TaskApiBaseSchema = z.object({
error: z.string().nullable(),
created_at: z.string(),
type: z.string(),
+ context_key: z.string().nullable().optional(),
});
export type TaskApiBase = z.infer<typeof TaskApiBaseSchema>;
diff --git a/src/web/migrations/0002_add_task_context_key.sql b/src/web/migrations/0002_add_task_context_key.sql
new file mode 100644
index 000000000..dc4de9b11
--- /dev/null
+++ b/src/web/migrations/0002_add_task_context_key.sql
@@ -0,0 +1,2 @@
+-- Add context_key column to agent_task_queue for unified session resumption
+ALTER TABLE agent_task_queue ADD COLUMN context_key TEXT;
diff --git a/src/web/src/app/api/conversations/[id]/messages/route.test.ts b/src/web/src/app/api/conversations/[id]/messages/route.test.ts
index f1b95a553..6913c8d83 100644
--- a/src/web/src/app/api/conversations/[id]/messages/route.test.ts
+++ b/src/web/src/app/api/conversations/[id]/messages/route.test.ts
@@ -18,6 +18,13 @@ vi.mock("@alook/shared", () => {
return {
createDb: vi.fn(() => ({})),
createLogger: () => log,
+ TASK_TYPES: {
+ USER_DM_MESSAGE: "user_dm_message",
+ EMAIL_NOTIFICATION: "email_notification",
+ CALENDAR_EVENT: "calendar_event",
+ },
+ buildContextKey: (type: string, opts: { conversationId?: string }) =>
+ type === "user_dm_message" && opts.conversationId ? `dm:${opts.conversationId}` : null,
queries: {
conversation: {
getConversation: (...args: any[]) => mockGetConversation(...args),
@@ -173,7 +180,7 @@ describe("POST /api/conversations/[id]/messages", () => {
expect(res.status).toBe(201);
expect(body.message).toEqual({ id: "m1", content: "Hi there" });
expect(body.task).toEqual({ id: "t1", status: "pending" });
- expect(mockEnqueueTask).toHaveBeenCalledWith("a1", "c1", "w1", "Hi there");
+ expect(mockEnqueueTask).toHaveBeenCalledWith("a1", "c1", "w1", "Hi there", "user_dm_message", { contextKey: "dm:c1" });
});
it("auto-titles conversation with truncated first message", async () => {
diff --git a/src/web/src/app/api/conversations/[id]/messages/route.ts b/src/web/src/app/api/conversations/[id]/messages/route.ts
index 5b8972d6d..301f659de 100644
--- a/src/web/src/app/api/conversations/[id]/messages/route.ts
+++ b/src/web/src/app/api/conversations/[id]/messages/route.ts
@@ -1,6 +1,6 @@
import { NextRequest } from "next/server";
import { getCloudflareContext } from "@opennextjs/cloudflare"
-import { createDb, queries } from "@alook/shared"
+import { createDb, queries, TASK_TYPES, buildContextKey } from "@alook/shared"
import { withAuth } from "@/lib/middleware/auth";
import { withWorkspaceMember } from "@/lib/middleware/workspace";
import { writeJSON, writeError } from "@/lib/middleware/helpers";
@@ -83,13 +83,16 @@ export const POST = withAuth(async (req: NextRequest, ctx) => {
// Auto-title: conditional WHERE title = '' ensures only the first message sets it
queries.conversation.updateConversationTitle(db, id, truncateTitle(content)).catch(() => {});
+ const contextKey = buildContextKey(TASK_TYPES.USER_DM_MESSAGE, { conversationId: id });
const taskService = new TaskService(db);
try {
const task = await taskService.enqueueTask(
conversation.agentId,
id,
ws.workspaceId,
- content
+ content,
+ TASK_TYPES.USER_DM_MESSAGE,
+ { contextKey },
);
broadcastToUser(ctx.userId, { type: "task.updated", taskId: task.id, status: "queued" }).catch(() => {});
return writeJSON(
diff --git a/src/web/src/app/api/email/notify/route.ts b/src/web/src/app/api/email/notify/route.ts
index cf6bb6a06..15713ce4b 100644
--- a/src/web/src/app/api/email/notify/route.ts
+++ b/src/web/src/app/api/email/notify/route.ts
@@ -1,6 +1,6 @@
import { NextRequest } from "next/server"
import { getCloudflareContext } from "@opennextjs/cloudflare"
-import { createDb, queries, TASK_TYPES } from "@alook/shared"
+import { createDb, queries, TASK_TYPES, buildContextKey, extractThreadId } from "@alook/shared"
import { writeJSON, writeError } from "@/lib/middleware/helpers"
import { TaskService } from "@/lib/services/task"
import { broadcastToUser } from "@/lib/broadcast"
@@ -36,8 +36,10 @@ export async function POST(req: NextRequest) {
title: `Email: ${body.subject}`.slice(0, 50),
type: TASK_TYPES.EMAIL_NOTIFICATION,
})
+ const threadId = extractThreadId(body.references, body.inReplyTo, body.messageId);
+ const contextKey = buildContextKey(TASK_TYPES.EMAIL_NOTIFICATION, { threadId });
const taskService = new TaskService(db)
- await taskService.enqueueTask(agent.id, conv.id, agent.workspaceId, `New email from ${body.from}: ${body.subject}`, TASK_TYPES.EMAIL_NOTIFICATION)
+ await taskService.enqueueTask(agent.id, conv.id, agent.workspaceId, `New email from ${body.from}: ${body.subject}`, TASK_TYPES.EMAIL_NOTIFICATION, { contextKey })
}
// Notify UI for all emails (whitelisted or not)
diff --git a/src/web/src/lib/api/responses.ts b/src/web/src/lib/api/responses.ts
index ef5e8938d..a65e7363a 100644
--- a/src/web/src/lib/api/responses.ts
+++ b/src/web/src/lib/api/responses.ts
@@ -75,6 +75,7 @@ export function taskToResponse(t: {
workspaceId: string;
prompt: string;
type?: string;
+ contextKey?: string | null;
status: string;
priority: number;
dispatchedAt: Date | string | null;
@@ -92,6 +93,7 @@ export function taskToResponse(t: {
workspace_id: t.workspaceId,
prompt: t.prompt,
type: t.type ?? TASK_TYPES.USER_DM_MESSAGE,
+ context_key: t.contextKey ?? null,
status: t.status,
priority: t.priority,
dispatched_at: formatTimestampNullable(t.dispatchedAt),
diff --git a/src/web/src/lib/services/task.test.ts b/src/web/src/lib/services/task.test.ts
index 00ac9b74d..e0ce29c8a 100644
--- a/src/web/src/lib/services/task.test.ts
+++ b/src/web/src/lib/services/task.test.ts
@@ -81,6 +81,7 @@ describe("TaskService", () => {
conversationId: "c1",
prompt: "do stuff",
type: "user_dm_message",
+ contextKey: null,
priority: 0,
});
expect(result).toEqual({ id: "t1" });
diff --git a/src/web/src/lib/services/task.ts b/src/web/src/lib/services/task.ts
index ff917c7eb..1d849e5cf 100644
--- a/src/web/src/lib/services/task.ts
+++ b/src/web/src/lib/services/task.ts
@@ -15,6 +15,7 @@ export class TaskService {
workspaceId: string,
prompt: string,
type: string = TASK_TYPES.USER_DM_MESSAGE,
+ opts?: { contextKey?: string | null },
) {
const agent = await agentQueries.getAgent(this.db, agentId, workspaceId);
if (!agent) {
@@ -31,6 +32,7 @@ export class TaskService {
conversationId,
prompt,
type,
+ contextKey: opts?.contextKey ?? null,
priority: 0,
});
}
diff --git a/src/web/src/test/e2e/task-lifecycle.test.ts b/src/web/src/test/e2e/task-lifecycle.test.ts
index b66c300c1..583eea133 100644
--- a/src/web/src/test/e2e/task-lifecycle.test.ts
+++ b/src/web/src/test/e2e/task-lifecycle.test.ts
@@ -61,6 +61,7 @@ describe("task lifecycle", () => {
expect(data.tasks[0].id).toBe(taskId)
expect(data.tasks[0].status).toBe("dispatched")
expect(data.tasks[0].prompt).toBe("Run the e2e tests")
+ expect(data.tasks[0].context_key).toBe(`dm:${conversationId}`)
// Poll response includes agent data
expect(data.tasks[0].agent).toBeTruthy()
const agent = data.tasks[0].agent as Record<string, unknown>
@@ -157,6 +158,200 @@ describe("task lifecycle", () => {
})
})
+describe("context_key resume contract", () => {
+ let conv2Id: string
+ let task2Id: string
+
+ it("same conversation produces same context_key (DM resume)", async () => {
+ // Complete the first task from the main beforeAll
+ // (already completed above in the lifecycle tests)
+
+ // Send another message in the SAME conversation
+ const msgRes = await tokenRequest(
+ `/api/conversations/${conversationId}/messages?workspace_id=${seed.workspaceId}`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ content: "Second message same conv" }),
+ },
+ )
+ const msgData = await msgRes.json() as { task?: { id: string } | null }
+ expect(msgData.task).toBeTruthy()
+ task2Id = msgData.task!.id
+
+ // Poll to claim
+ const pollRes = await tokenRequest(
+ `/api/daemon/tasks/poll`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ daemon_id: seed.daemonId, max_tasks: 1 }),
+ },
+ )
+ const pollData = await pollRes.json() as { tasks: Array<Record<string, unknown>> }
+ expect(pollData.tasks).toHaveLength(1)
+ // Same conversation → same context_key
+ expect(pollData.tasks[0].context_key).toBe(`dm:${conversationId}`)
+
+ // Clean up: start + complete this task
+ await tokenRequest(`/api/daemon/tasks/${task2Id}/start`, seed.machineToken, { method: "POST" })
+ await tokenRequest(`/api/daemon/tasks/${task2Id}/complete`, seed.machineToken, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ output: "done", session_id: "sess_2" }),
+ })
+ })
+
+ it("different conversation produces different context_key (DM reset)", async () => {
+ // Create a NEW conversation (simulates reset)
+ const convRes = await tokenRequest(
+ `/api/conversations?workspace_id=${seed.workspaceId}`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ agent_id: seed.agentId }),
+ },
+ )
+ const convData = await convRes.json() as { id: string }
+ conv2Id = convData.id
+
+ const msgRes = await tokenRequest(
+ `/api/conversations/${conv2Id}/messages?workspace_id=${seed.workspaceId}`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ content: "Message in new conv" }),
+ },
+ )
+ const msgData = await msgRes.json() as { task?: { id: string } | null }
+ expect(msgData.task).toBeTruthy()
+
+ const pollRes = await tokenRequest(
+ `/api/daemon/tasks/poll`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ daemon_id: seed.daemonId, max_tasks: 1 }),
+ },
+ )
+ const pollData = await pollRes.json() as { tasks: Array<Record<string, unknown>> }
+ expect(pollData.tasks).toHaveLength(1)
+ // Different conversation → different context_key
+ expect(pollData.tasks[0].context_key).toBe(`dm:${conv2Id}`)
+ expect(pollData.tasks[0].context_key).not.toBe(`dm:${conversationId}`)
+
+ // Clean up
+ const tid = pollData.tasks[0].id as string
+ await tokenRequest(`/api/daemon/tasks/${tid}/start`, seed.machineToken, { method: "POST" })
+ await tokenRequest(`/api/daemon/tasks/${tid}/complete`, seed.machineToken, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ output: "done", session_id: "sess_3" }),
+ })
+ })
+
+ it("email notify with same thread root produces same context_key", async () => {
+ const threadRoot = `<root-${Date.now()}@e2e.test>`
+
+ // First email in thread
+ const res1 = await tokenRequest(
+ `/api/email/notify?workspace_id=${seed.workspaceId}`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ agentId: seed.agentId,
+ workspaceId: seed.workspaceId,
+ r2Key: "emails/fake1/raw",
+ from: `${seed.userId}@test.local`,
+ subject: "Thread email 1",
+ isWhitelisted: true,
+ messageId: threadRoot,
+ inReplyTo: "",
+ references: "",
+ }),
+ },
+ )
+ expect(res1.status).toBe(200)
+
+ // Poll to get first task
+ const poll1 = await tokenRequest(
+ `/api/daemon/tasks/poll`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ daemon_id: seed.daemonId, max_tasks: 1 }),
+ },
+ )
+ const poll1Data = await poll1.json() as { tasks: Array<Record<string, unknown>> }
+ expect(poll1Data.tasks).toHaveLength(1)
+ const emailKey1 = poll1Data.tasks[0].context_key as string
+ expect(emailKey1).toBe(`email:${threadRoot}`)
+
+ // Complete it
+ const tid1 = poll1Data.tasks[0].id as string
+ await tokenRequest(`/api/daemon/tasks/${tid1}/start`, seed.machineToken, { method: "POST" })
+ await tokenRequest(`/api/daemon/tasks/${tid1}/complete`, seed.machineToken, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ output: "replied", session_id: "sess_email_1" }),
+ })
+
+ // Second email in same thread (references contains thread root)
+ const res2 = await tokenRequest(
+ `/api/email/notify?workspace_id=${seed.workspaceId}`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ agentId: seed.agentId,
+ workspaceId: seed.workspaceId,
+ r2Key: "emails/fake2/raw",
+ from: `${seed.userId}@test.local`,
+ subject: "Re: Thread email 1",
+ isWhitelisted: true,
+ messageId: `<reply-${Date.now()}@e2e.test>`,
+ inReplyTo: threadRoot,
+ references: `${threadRoot} <reply-${Date.now()}@e2e.test>`,
+ }),
+ },
+ )
+ expect(res2.status).toBe(200)
+
+ // Poll second task
+ const poll2 = await tokenRequest(
+ `/api/daemon/tasks/poll`,
+ seed.machineToken,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ daemon_id: seed.daemonId, max_tasks: 1 }),
+ },
+ )
+ const poll2Data = await poll2.json() as { tasks: Array<Record<string, unknown>> }
+ expect(poll2Data.tasks).toHaveLength(1)
+ // Same thread root → same context_key
+ expect(poll2Data.tasks[0].context_key).toBe(emailKey1)
+
+ // Clean up
+ const tid2 = poll2Data.tasks[0].id as string
+ await tokenRequest(`/api/daemon/tasks/${tid2}/start`, seed.machineToken, { method: "POST" })
+ await tokenRequest(`/api/daemon/tasks/${tid2}/complete`, seed.machineToken, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ output: "replied again", session_id: "sess_email_2" }),
+ })
+ })
+})
+
describe("task failure", () => {
let failTaskId: string