Multiplayer agent harness for work.
import { z } from "zod";
import type { Cron, Loop, LoopItem, LoopSourcePayload } from "../../types.ts";
import { isAccountType } from "../../connectors/oauth.ts";
import { canonicalJson } from "../../../cli/src/canonical-json.ts";
import { errMessage } from "../../util/errors.ts";
import { sendJson } from "../http.ts";
import { isObj } from "./shared.ts";
import { withActor, type ApiCtx, type Route } from "./route.ts";
import {
requireLoopAuthority,
canAdministerLoop,
loadAdministrable,
loopDeps,
actingPrincipal,
type LoopServiceDeps,
} from "./loops.ts";
import { scopeId, parseScopeId } from "../../types.ts";
import { isResolved, isLedgerState, ledgerItemView, ledgerState, sortLedgerItems } from "../../loops/ledger-view.ts";
import { loopItemId, type IngestEntryInput } from "../../loops/item-ledger.ts";
import { LOOP_ITEM_PRIORITIES, removeFromGroup, settleGroup } from "../../loops/triage.ts";
import { addressList } from "../../loops/sources/adapter.ts";
import { adapterForItem, sourceAdapter } from "../../loops/sources/index.ts";
import {
ensureDefaultInboxLoops,
renderSourceInboxTask,
findInboxLoop,
INBOX_LEDGER_MAX_ITEMS,
INBOX_LEDGER_RETENTION_MS,
INBOX_SYNC_DEFAULT_EVERY_MS,
} from "../../loops/inbox-loop.ts";
import { migrateInbox } from "../../loops/inbox-migration.ts";
import { THINKING_LEVELS, isHarnessId } from "../../model/pi-models.ts";
import { principalDestination } from "../../reach/reach.ts";
const MAX_ITEMS_PER_INGEST = 50;
const MAX_SOURCE_PAYLOAD_BYTES = 64_000;
const MAX_PROPOSAL_BYTES = 32_000;
const MAX_FOLLOWUP_CHARS = 4_000;
function jsonSize(value: unknown): number {
return JSON.stringify(value)?.length ?? 0;
}
function parseIngestEntry(loop: Loop, raw: unknown): IngestEntryInput | { error: string } {
if (!isObj(raw)) return { error: "item must be an object" };
const adapter = sourceAdapter(raw.source);
if (adapter) {
if (loop.sources && !loop.sources.includes(adapter.id)) {
return { error: `this loop does not accept "${adapter.id}" items` };
}
const parsed = adapter.parse(raw);
if ("error" in parsed) return parsed;
return {
loopId: loop.id,
dedupeKey: parsed.dedupeKey,
source: adapter.id,
summary: parsed.summary,
sourcePayload: parsed.sourcePayload,
sourceAt: parsed.sourceAt,
...(parsed.proposal ? { proposal: { ...parsed.proposal, by: "agent" as const } } : {}),
};
}
if (typeof raw.source === "string" && raw.source.trim()) {
return { error: `unknown source "${raw.source}"` };
}
const dedupeKey = typeof raw.dedupeKey === "string" ? raw.dedupeKey.trim() : "";
if (!dedupeKey || dedupeKey.length > 300) return { error: "dedupeKey (<=300 chars) required" };
if (!isObj(raw.sourcePayload)) return { error: "sourcePayload must be an object" };
if (jsonSize(raw.sourcePayload) > MAX_SOURCE_PAYLOAD_BYTES) {
return { error: `sourcePayload must be under ${MAX_SOURCE_PAYLOAD_BYTES} bytes of JSON` };
}
const sourceAt =
typeof raw.sourceAt === "number" && Number.isFinite(raw.sourceAt) && raw.sourceAt > 0 ? raw.sourceAt : undefined;
const summary = typeof raw.summary === "string" && raw.summary.trim() ? raw.summary.trim().slice(0, 500) : undefined;
let proposal: { data: LoopSourcePayload } | undefined;
if (raw.proposal !== undefined) {
const data = isObj(raw.proposal) && isObj(raw.proposal.data) ? raw.proposal.data : raw.proposal;
if (!isObj(data)) return { error: "proposal must be an object" };
if (jsonSize(data) > MAX_PROPOSAL_BYTES) {
return { error: `proposal must be under ${MAX_PROPOSAL_BYTES} bytes of JSON` };
}
proposal = { data };
}
return {
loopId: loop.id,
dedupeKey,
sourcePayload: raw.sourcePayload,
...(summary !== undefined ? { summary } : {}),
...(sourceAt !== undefined ? { sourceAt } : {}),
...(proposal ? { proposal: { ...proposal, by: "agent" as const } } : {}),
};
}
function readableItems(ctx: ApiCtx, loop: Loop): boolean {
if (!ctx.capability || parseScopeId(loop.ownerScopeId).kind !== "personal") return true;
if (ctx.capability.privateScope === true) return true;
sendJson(ctx.res, 403, {
error: "forbidden",
message: "a personal loop's items are reachable only from its owner's own scope",
});
return false;
}
async function listItems(ctx: ApiCtx): Promise<void> {
const loaded = await loadAdministrable(ctx);
if (!loaded) return;
const { deps, loop } = loaded;
if (!readableItems(ctx, loop)) return;
const wanted = ctx.url.searchParams.get("state");
if (wanted !== null && !isLedgerState(wanted)) {
return sendJson(ctx.res, 400, { error: "bad_request", message: "unknown state filter" });
}
if ((loop.surface === "inbox" || loop.surface?.startsWith("inbox:")) && loop.owner === loaded.acting.actorId) {
const openMail = (await deps.items.byLoop(loop.id)).filter(
(item) => !isResolved(item) && (item.source ?? item.sourcePayload?.source) === "gmail",
);
await ctx.deps.inboxSourceRefresh?.(loop.owner, openMail);
}
const all = sortLedgerItems(await deps.items.byLoop(loop.id), loop);
const items = wanted === null ? all : all.filter((item) => ledgerState(item) === wanted);
const counts: Record<string, number> = {};
for (const item of all) {
const state = ledgerState(item);
counts[state] = (counts[state] ?? 0) + 1;
}
sendJson(ctx.res, 200, { loop, items: items.map((item) => ledgerItemView(item, loop, !!ctx.capability)), counts });
}
async function ingestItems(ctx: ApiCtx): Promise<void> {
const loaded = await loadAdministrable(ctx);
if (!loaded) return;
const { deps, loop } = loaded;
if (loop.surface === "inbox" && loop.state !== "enabled")
return sendJson(ctx.res, 409, {
error: "migration_pending",
message: "This Inbox producer has been retired or paused for migration.",
});
if (!ctx.capability) {
return sendJson(ctx.res, 403, { error: "forbidden", message: "ledger items are ingested by the agent" });
}
if (!readableItems(ctx, loop)) return;
const body = isObj(ctx.body) ? ctx.body : {};
if (!Array.isArray(body.items) || body.items.length === 0) {
return sendJson(ctx.res, 400, { error: "bad_request", message: "items (non-empty array) required" });
}
if (body.items.length > MAX_ITEMS_PER_INGEST) {
return sendJson(ctx.res, 400, { error: "bad_request", message: `at most ${MAX_ITEMS_PER_INGEST} items per call` });
}
const sessionId = ctx.capability.threadRef
? ((await ctx.deps.sessions?.getByThread(ctx.capability.threadRef))?.id ?? undefined)
: undefined;
const classifyInboxEmail =
(loop.surface === "inbox" || loop.surface === "inbox:gmail") &&
loop.ownerScopeId === scopeId("personal", loop.owner) &&
(await ctx.deps.featureFlags?.enabled("inbox_loops", scopeId("personal", loop.owner))) === true;
const entries: IngestEntryInput[] = [];
const existingItems = await deps.items.byLoop(loop.id);
for (const [at, raw] of body.items.entries()) {
const parsed = parseIngestEntry(loop, raw);
if ("error" in parsed) {
return sendJson(ctx.res, 400, { error: "bad_request", message: `items[${at}]: ${parsed.error}` });
}
if (classifyInboxEmail && parsed.source === "gmail" && isObj(raw)) {
for (const key of ["automated", "probablyResolved"])
if (typeof raw[key] === "boolean") parsed.sourcePayload[key] = raw[key];
}
if (parsed.source === "slack") {
const adapter = sourceAdapter("slack")!;
const existing = existingItems.find(
(item) =>
(item.source ?? item.sourcePayload?.source) === "slack" && adapter.matchesEvent(item, parsed.dedupeKey),
);
// Retain the ID, human edits and resolution watermark of legacy channel-keyed cards.
if (existing) parsed.dedupeKey = existing.sourceKey;
}
entries.push(sessionId && parsed.proposal ? { ...parsed, proposal: { ...parsed.proposal, sessionId } } : parsed);
}
const outcome = await deps.items.ingest(entries);
await deps.items.prune(loop.id, { maxItems: INBOX_LEDGER_MAX_ITEMS, retentionMs: INBOX_LEDGER_RETENTION_MS });
sendJson(ctx.res, 200, outcome);
}
async function loadItem(
ctx: ApiCtx,
): Promise<{ deps: LoopServiceDeps; loop: Loop; item: LoopItem; actorId: string } | null> {
const loaded = await loadAdministrable(ctx);
if (!loaded) return null;
if (!readableItems(ctx, loaded.loop)) return null;
const item = await loaded.deps.items.get(ctx.params.itemId ?? "");
if (item && item.loopId !== loaded.loop.id && item.previousLoopId === loaded.loop.id) {
const target = await loaded.deps.store.get(item.loopId);
if (target && (await canAdministerLoop(ctx, target, loaded.acting)))
return { deps: loaded.deps, loop: target, item, actorId: loaded.acting.actorId };
}
if (!item || item.loopId !== loaded.loop.id) {
sendJson(ctx.res, 404, { error: "not_found", message: "no such ledger item" });
return null;
}
return { deps: loaded.deps, loop: loaded.loop, item, actorId: loaded.acting.actorId };
}
const IMAGE_MAX_BYTES = 8_000_000;
function imageUrlFromItem(item: LoopItem, ctxIndex: number, imageIndex: number): string | null {
const payload = item.sourcePayload ?? {};
let list: unknown;
if (ctxIndex === -1) {
list = payload.images;
} else if (Array.isArray(payload.context) && isObj(payload.context[ctxIndex])) {
list = (payload.context[ctxIndex] as { images?: unknown }).images;
}
if (!Array.isArray(list)) return null;
const url = list[imageIndex];
return typeof url === "string" && url.startsWith("https://") ? url : null;
}
async function serveItemImage(ctx: ApiCtx): Promise<void> {
const loaded = await loadItem(ctx);
if (!loaded) return;
const { loop, item } = loaded;
const ctxIndex = Number.parseInt(ctx.url.searchParams.get("ctx") ?? "", 10);
const imageIndex = Number.parseInt(ctx.url.searchParams.get("i") ?? "", 10);
if (!Number.isInteger(ctxIndex) || !Number.isInteger(imageIndex) || imageIndex < 0 || ctxIndex < -1) {
return sendJson(ctx.res, 400, { error: "bad_request", message: "ctx and i required" });
}
const url = imageUrlFromItem(item, ctxIndex, imageIndex);
if (!url) return sendJson(ctx.res, 404, { error: "not_found", message: "no such image on this item" });
const host = new URL(url).hostname;
const slackHosted = host === "slack.com" || host.endsWith(".slack.com");
let authHeader: Record<string, string> = {};
if (slackHosted) {
const tokens = ctx.deps.loopSourceTokens;
const token = tokens
? ((await tokens.connectorAccessToken("slack.com", loop.owner, "personal")) ??
(await tokens.connectorAccessToken("slack.com", loop.owner)))
: null;
if (!token) return sendJson(ctx.res, 502, { error: "not_connected", message: "Slack is not connected" });
authHeader = { authorization: `Bearer ${token}` };
}
let upstream: Response;
try {
upstream = await fetch(url, { headers: authHeader, redirect: "follow" });
} catch (e) {
return sendJson(ctx.res, 502, { error: "upstream", message: errMessage(e) });
}
const type = upstream.headers.get("content-type") ?? "";
if (!upstream.ok || !upstream.body || !type.startsWith("image/")) {
return sendJson(ctx.res, 502, { error: "upstream", message: `upstream returned ${upstream.status} ${type}` });
}
const bytes = Buffer.from(await upstream.arrayBuffer());
if (bytes.length > IMAGE_MAX_BYTES) return sendJson(ctx.res, 502, { error: "upstream", message: "image too large" });
ctx.res.writeHead(200, {
"content-type": type,
"content-length": String(bytes.length),
"cache-control": "private, max-age=3600",
});
ctx.res.end(bytes);
}
async function getItem(ctx: ApiCtx): Promise<void> {
const loaded = await loadItem(ctx);
if (!loaded) return;
if (
ctx.url.searchParams.get("refreshSource") === "1" &&
(loaded.loop.surface === "inbox" || loaded.loop.surface?.startsWith("inbox:")) &&
loaded.loop.owner === loaded.actorId
)
await ctx.deps.inboxSourceRefresh?.(loaded.loop.owner, [loaded.item]);
sendJson(ctx.res, 200, {
item: ledgerItemView((await loaded.deps.items.get(loaded.item.id)) ?? loaded.item, loaded.loop, !!ctx.capability),
outputs: (await loaded.deps.outputs.byItem(loaded.item.id)).filter((output) => output.loopId === loaded.loop.id),
});
}
function sameProposalData(item: LoopItem, data: LoopSourcePayload): boolean {
return item.proposal !== undefined && canonicalJson(item.proposal.data) === canonicalJson(data);
}
function proposalFrom(item: LoopItem, raw: unknown): LoopSourcePayload | null {
const adapter = adapterForItem(item);
const data = isObj(raw) && isObj(raw.data) ? raw.data : raw;
if (!isObj(data)) return null;
if (jsonSize(data) > MAX_PROPOSAL_BYTES) return null;
return adapter ? adapter.parseProposal(data) : data;
}
async function actOnItem(ctx: ApiCtx): Promise<void> {
const loaded = await loadItem(ctx);
if (!loaded) return;
const { deps, loop } = loaded;
let item = loaded.item;
const body = isObj(ctx.body) ? ctx.body : {};
const kind = typeof body.kind === "string" ? body.kind.trim() : "";
const proposalAuthor = ctx.capability ? ("agent" as const) : ("human" as const);
if (!kind) return sendJson(ctx.res, 400, { error: "bad_request", message: "kind required" });
const args = isObj(body.args) ? body.args : {};
const expectedAt = typeof args.expectedProposalAt === "number" ? args.expectedProposalAt : undefined;
const draftChanged = (): void =>
sendJson(ctx.res, 409, {
error: "draft_changed",
message: "the draft changed since you last saw it; review the new draft before sending",
});
if (kind === "edit") {
const data = proposalFrom(item, args.proposal ?? args);
if (!data) return sendJson(ctx.res, 400, { error: "bad_request", message: "proposal is not valid for this item" });
if (expectedAt !== undefined && item.proposal && item.proposal.at !== expectedAt) return draftChanged();
if (sameProposalData(item, data))
return sendJson(ctx.res, 200, { item: ledgerItemView(item, loop, !!ctx.capability) });
const next = await deps.items.setProposal(
item.id,
{ data, by: proposalAuthor },
expectedAt !== undefined ? { expectedAt } : undefined,
);
if (!next && expectedAt !== undefined) return draftChanged();
if (!next) return sendJson(ctx.res, 409, { error: "conflict", message: "this item is already actioned" });
return sendJson(ctx.res, 200, { item: ledgerItemView(next, loop, !!ctx.capability) });
}
if (kind === "dismiss") {
const next = await deps.items.recordAction(item.id, { kind, outcome: "dismissed" });
if (!next) return sendJson(ctx.res, 409, { error: "conflict", message: "this item is already actioned" });
if (args.group === true && !ctx.capability) await settleGroup(deps.items, next);
return sendJson(ctx.res, 200, { item: ledgerItemView(next, loop, !!ctx.capability) });
}
if (kind === "prioritize" || kind === "ungroup") {
if (ctx.capability)
return sendJson(ctx.res, 403, { error: "forbidden", message: "only a person can override triage" });
const priority = LOOP_ITEM_PRIORITIES.find((value) => value === args.priority);
if (kind === "prioritize" && !priority)
return sendJson(ctx.res, 400, { error: "bad_request", message: "priority must be urgent, high, normal, or low" });
const next =
kind === "prioritize"
? await deps.items.setTriage(item.id, { priority }, "human")
: await removeFromGroup(deps.items, item);
if (!next) return sendJson(ctx.res, 409, { error: "conflict", message: "this item is already actioned" });
return sendJson(ctx.res, 200, { item: ledgerItemView(next, loop, !!ctx.capability) });
}
if (kind === "reply") {
if (!ctx.actor?.p || item.sourcePayload?.sentChat !== true) return sendJson(ctx.res, 403, { error: "forbidden" });
const next = await deps.items.reopen(item.id, { sentReply: true });
if (!next) return sendJson(ctx.res, 409, { error: "conflict", message: "a reply is already being drafted" });
return sendJson(ctx.res, 200, { item: ledgerItemView(next, loop, !!ctx.capability) });
}
if (kind === "reopen") {
const next = await deps.items.reopen(item.id);
if (!next) return sendJson(ctx.res, 409, { error: "conflict", message: "this item is not dismissed" });
return sendJson(ctx.res, 200, { item: ledgerItemView(next, loop, !!ctx.capability) });
}
if (kind === "send" && item.status !== "ready") {
return sendJson(ctx.res, 409, { error: "not_ready", message: "This item needs a fresh draft before sending" });
}
if (ledgerState(item) === "actioned") {
return sendJson(ctx.res, 409, { error: "already_actioned", message: "this item was already actioned" });
}
if (expectedAt !== undefined && item.proposal && item.proposal.at !== expectedAt) return draftChanged();
if (args.proposal !== undefined) {
const data = proposalFrom(item, args.proposal);
if (!data) return sendJson(ctx.res, 400, { error: "bad_request", message: "proposal is not valid for this item" });
if (!sameProposalData(item, data)) {
const revised = await deps.items.setProposal(
item.id,
{ data, by: proposalAuthor },
expectedAt !== undefined ? { expectedAt } : undefined,
);
if (!revised && expectedAt !== undefined) return draftChanged();
item = revised ?? item;
}
}
const adapter = adapterForItem(item);
if (adapter?.actions.includes(kind)) {
const tokens = ctx.deps.loopSourceTokens;
if (!tokens) return sendJson(ctx.res, 404, { error: "not_found", message: "connectors are not wired" });
const decisionToken = await deps.items.acquireDecision(item.id);
if (!decisionToken)
return sendJson(ctx.res, 409, { error: "conflict", message: "an action is already in progress" });
try {
const current = await deps.items.get(item.id);
if (!current || ledgerState(current) === "actioned")
return sendJson(ctx.res, 409, { error: "already_actioned", message: "this item was already actioned" });
if (current.proposal?.at !== item.proposal?.at) return draftChanged();
item = current;
const slackClient = ctx.deps.loopSlackClient;
const result = await adapter.act(
{ owner: loop.owner, actor: proposalAuthor, tokens, ...(slackClient ? { slackClient } : {}) },
item,
kind,
args,
);
if (!result.ok) {
if (result.partial) await deps.items.appendThread(item.id, [{ role: "system", text: result.message }]);
const statusByReason = { not_connected: 409, bad_item: 400, upstream: 502 } as const;
return sendJson(ctx.res, statusByReason[result.reason], { error: result.reason, message: result.message });
}
if (result.payloadPatch) item = (await deps.items.annotate(item.id, result.payloadPatch)) ?? item;
if (result.resolves === false)
return sendJson(ctx.res, 200, { item: ledgerItemView(item, loop, !!ctx.capability) });
const next = await deps.items.recordAction(item.id, { kind, outcome: "actioned", result: result.result });
return sendJson(ctx.res, 200, { item: ledgerItemView(next ?? item, loop, !!ctx.capability) });
} finally {
await deps.items.releaseDecision(item.id, decisionToken);
}
}
if (!deps.fire) return sendJson(ctx.res, 404, { error: "not_found", message: "loop firing is not wired" });
if (!(await requireLoopAuthority(ctx, deps, loop))) return;
const turn = await deps.fire.itemAction(loop, item, kind, args, loaded.actorId);
if (!turn.ok) {
return sendJson(ctx.res, 502, { error: "action_failed", message: turn.userNote ?? "the agent turn did not run" });
}
await deps.items.appendThread(item.id, [{ role: "agent", text: turn.reply ?? `Did "${kind}".` }]);
const next = await deps.items.recordAction(item.id, {
kind,
outcome: "actioned",
...(turn.reply ? { result: turn.reply } : {}),
});
sendJson(ctx.res, 200, { item: ledgerItemView(next ?? item, loop, !!ctx.capability) });
}
const followUpOptionsSchema = z.object({
model: z.string().trim().min(1).optional(),
harness: z.string().trim().refine(isHarnessId, "unsupported harness").optional(),
thinkingLevel: z.string().trim().pipe(z.enum(THINKING_LEVELS)).optional(),
fastMode: z.boolean().optional(),
attachments: z
.array(
z.object({
name: z.string().min(1),
blobId: z.string().min(1),
mimetype: z.string(),
sizeBytes: z.int().min(1).max(1_000_000_000),
}),
)
.max(10)
.optional(),
});
async function followUpOnItem(ctx: ApiCtx): Promise<void> {
const loaded = await loadItem(ctx);
if (!loaded) return;
const { deps, loop, item } = loaded;
if (!(await requireLoopAuthority(ctx, deps, loop))) return;
const body = isObj(ctx.body) ? ctx.body : {};
const parsed = followUpOptionsSchema.safeParse(body);
if (!parsed.success)
return sendJson(ctx.res, 400, { error: "bad_request", message: parsed.error.issues[0]?.message });
const options = parsed.data;
const message = typeof body.message === "string" ? body.message.trim() : "";
if (!message && !options.attachments?.length)
return sendJson(ctx.res, 400, { error: "bad_request", message: "message required" });
if (message.length > MAX_FOLLOWUP_CHARS) {
return sendJson(ctx.res, 400, {
error: "bad_request",
message: `message must be under ${MAX_FOLLOWUP_CHARS} chars`,
});
}
if (typeof body.expectedProposalAt === "number" && item.proposal?.at !== body.expectedProposalAt) {
return sendJson(ctx.res, 409, {
error: "draft_changed",
message: "the draft changed; review it before continuing",
});
}
if (!deps.fire) return sendJson(ctx.res, 404, { error: "not_found", message: "loop firing is not wired" });
try {
const next = await deps.fire.followUp(
loop,
item,
message || "Please review the attached files.",
loaded.actorId,
options,
);
sendJson(ctx.res, 200, { item: ledgerItemView(next ?? item, loop, !!ctx.capability) });
} catch (e) {
sendJson(ctx.res, 502, { error: "followup_failed", message: errMessage(e) });
}
}
export function cronSummary(cron: Cron | null): {
id: string;
enabled: boolean;
schedule: Cron["schedule"];
lastFiredAt?: number;
} | null {
if (!cron) return null;
return {
id: cron.id,
enabled: cron.enabled,
schedule: cron.schedule,
...(cron.lastFiredAt !== undefined ? { lastFiredAt: cron.lastFiredAt } : {}),
};
}
async function getInboxLoop(ctx: ApiCtx): Promise<void> {
const deps = loopDeps(ctx);
if (!deps) return sendJson(ctx.res, 404, { error: "not_found", message: "loops are not wired on this deployment" });
const acting = actingPrincipal(ctx);
if (!acting) return;
const loop =
(await deps.store.list()).find(
(candidate) => candidate.owner === acting.actorId && candidate.surface === "inbox:gmail",
) ?? (await findInboxLoop(deps.store, acting.actorId));
const cron = loop?.cronId ? await ctx.app.getCron(loop.cronId) : null;
sendJson(ctx.res, 200, { loop, syncCron: cronSummary(cron) });
}
export async function ensureSentChat(ctx: ApiCtx): Promise<void> {
const owner = ctx.actor?.p;
if (!owner) return sendJson(ctx.res, 403, { error: "forbidden" });
if (!(await ctx.deps.featureFlags?.enabled("inbox_loops", scopeId("personal", owner))))
return sendJson(ctx.res, 403, { error: "feature_disabled" });
const deps = loopDeps(ctx);
if (!deps) return sendJson(ctx.res, 404, { error: "not_found" });
const body = isObj(ctx.body) ? ctx.body : {};
const threadId = typeof body.threadId === "string" ? body.threadId.trim() : "";
if (!threadId || threadId.length > 200 || jsonSize(body) > MAX_SOURCE_PAYLOAD_BYTES)
return sendJson(ctx.res, 400, { error: "bad_request" });
const text = (key: string, max: number): string => (typeof body[key] === "string" ? body[key].slice(0, max) : "");
const accountType = body.accountType === undefined ? "default" : body.accountType;
const to = addressList(body.to === undefined ? [] : [body.to]);
const cc = addressList(body.cc === undefined ? [] : [body.cc]);
if (!isAccountType(accountType) || to === null || cc === null)
return sendJson(ctx.res, 400, { error: "bad_request", message: "invalid account or recipient headers" });
const payload = {
title: text("subject", 300),
from: text("from", 500),
snippet: text("text", 50000),
gmail: {
threadId,
accountType,
messageId: text("messageId", 200),
subject: text("subject", 300),
to: to ?? [],
cc: cc ?? [],
rfcMessageId: text("rfcMessageId", 400),
},
sentChat: true,
} as LoopSourcePayload;
const defaults = await ensureDefaultInboxLoops(deps.store, owner);
const loop = defaults.find((entry) => entry.sources?.includes("gmail"))!;
const dedupeKey = accountType === "default" ? `sent-chat:${threadId}` : `sent-chat:${accountType}:${threadId}`;
let item = (await deps.items.byLoop(loop.id)).find((entry) => entry.sourceKey === dedupeKey);
const id = item?.id ?? loopItemId(loop.id, dedupeKey);
if (!item) {
await deps.items.ingest([
{
loopId: loop.id,
dedupeKey,
source: "gmail",
summary: text("subject", 300),
proposal: { data: { body: "" }, by: "human" },
sourcePayload: payload,
},
]);
item = (await deps.items.get(id)) ?? undefined;
}
if (!item) return sendJson(ctx.res, 500, { error: "chat_unavailable" });
item = (await deps.items.annotate(id, payload, { summary: text("subject", 300) })) ?? item;
if (item.actionKind === "sent") item = (await deps.items.reopen(id, { sentReply: true })) ?? item;
ctx.res.setHeader("Cache-Control", "no-store");
sendJson(ctx.res, 200, { item: ledgerItemView(item, loop, !!ctx.capability) });
}
async function ensureInboxSyncCron(ctx: ApiCtx): Promise<void> {
const deps = loopDeps(ctx);
if (!deps) return sendJson(ctx.res, 404, { error: "not_found", message: "loops are not wired on this deployment" });
const acting = actingPrincipal(ctx);
if (!acting) return;
if (!(await ctx.deps.featureFlags?.enabled("inbox_loops", scopeId("personal", acting.actorId))))
return sendJson(ctx.res, 403, { error: "feature_disabled" });
const body = isObj(ctx.body) ? ctx.body : {};
const everyMs =
typeof body.everyMs === "number" && Number.isFinite(body.everyMs)
? Math.max(5 * 60 * 1000, Math.min(24 * 60 * 60 * 1000 - 1, Math.floor(body.everyMs)))
: INBOX_SYNC_DEFAULT_EVERY_MS;
const enable = body.enabled !== false;
const owner = acting.actorId;
try {
const defaults = await ensureDefaultInboxLoops(deps.store, owner);
const legacy = await findInboxLoop(deps.store, owner);
if (legacy && (!ctx.deps.uiState || !(await migrateInbox(deps, ctx.deps.uiState, legacy, defaults))))
return sendJson(ctx.res, 409, {
error: "migration_pending",
message: "The existing Inbox is still being migrated. Sync remains paused.",
});
const requested = typeof body.loopId === "string" ? body.loopId : null;
const targets = defaults.filter((loop) => !requested || loop.id === requested);
if (!targets.length) return sendJson(ctx.res, 404, { error: "not_found" });
const results: Array<{ loop: Loop | null; syncCron: ReturnType<typeof cronSummary> }> = [];
for (const loop of targets) {
const sync = async () => {
const current = (await deps.store.get(loop.id)) ?? loop;
const source = current.sources![0]!;
const task = renderSourceInboxTask(loop.id, source);
let cron = current.cronId ? await ctx.app.getCron(current.cronId) : null;
if (!cron && enable) {
cron = await ctx.app.createCron({
loopId: loop.id,
ownerScopeId: loop.ownerScopeId,
owner,
createdBy: owner,
destination: principalDestination(owner, owner),
schedule: { everyMs },
title: `${loop.name} sync`,
action: task,
});
await deps.store.update(loop.id, { cronId: cron.id });
}
if (cron) {
if (enable && cron.action !== task)
await ctx.app.updateCron(cron.id, {
action: task,
title: `${loop.name} sync`,
});
await ctx.app.setCronEnabled(cron.id, enable);
if (enable && current.state === "paused") await deps.store.setState(loop.id, "enabled");
}
results.push({
loop: await deps.store.get(loop.id),
syncCron: cronSummary(cron ? await ctx.app.getCron(cron.id) : null),
});
};
if (deps.lock) await deps.lock.withLock(`loop-lifecycle:${loop.id}`, sync);
else await sync();
}
sendJson(ctx.res, 200, { ...results[0], loops: results });
} catch (err) {
sendJson(ctx.res, 400, { error: "bad_request", message: errMessage(err) });
}
}
function serializeItemAction(handler: (ctx: ApiCtx) => Promise<void>): (ctx: ApiCtx) => Promise<void> {
return (ctx) => {
const lock = loopDeps(ctx)?.lock;
return lock && !ctx.capability
? lock.withLock(`loop-lifecycle:${ctx.params.id ?? ""}`, async () => {
const loaded = await loadItem(ctx);
if (!loaded) return;
return loaded.loop.id === ctx.params.id
? handler(ctx)
: lock.withLock(`loop-lifecycle:${loaded.loop.id}`, () => handler(ctx));
})
: handler(ctx);
};
}
export const loopItemRoutes: ReadonlyArray<Route<ApiCtx>> = [
{ method: "POST", path: "/v1/loops/inbox/sent-chat", auth: "source", handle: ensureSentChat },
{ method: "GET", path: "/v1/loops/:id/items/:itemId/image", auth: "source", handle: serveItemImage },
...withActor("query.principalId", [
{ method: "GET", path: "/v1/loops/inbox", auth: "either", handle: getInboxLoop },
{ method: "POST", path: "/v1/loops/inbox/sync-cron", auth: "source", handle: ensureInboxSyncCron },
{ method: "GET", path: "/v1/loops/:id/items", auth: "either", handle: listItems },
{ method: "POST", path: "/v1/loops/:id/items", auth: "either", handle: ingestItems },
{ method: "GET", path: "/v1/loops/:id/items/:itemId", auth: "either", handle: getItem },
{
method: "POST",
path: "/v1/loops/:id/items/:itemId/action",
auth: "either",
handle: serializeItemAction(actOnItem),
},
{
method: "POST",
path: "/v1/loops/:id/items/:itemId/followup",
auth: "either",
handle: serializeItemAction(followUpOnItem),
},
]),
];