Multiplayer agent harness for work.
import { fromJSONSchema, z, ZodObject } from "zod";
import type { ClientToolDeclaration, TurnOrigin, TurnRequest } from "../../types.ts";
import { resolveTurnOrigin } from "../../core/turn-origin.ts";
import { samePerson } from "../../directory/person.ts";
import { sendJson } from "../http.ts";
import { isObj } from "./shared.ts";
import { type ApiCtx, type Route } from "./route.ts";
function isTurnRequest(body: unknown): body is TurnRequest {
return (
isObj(body) &&
typeof body.text === "string" &&
isObj(body.actor) &&
typeof body.actor.externalId === "string" &&
body.actor.externalId !== "" &&
isObj(body.conversation)
);
}
const MAX_CLIENT_TOOL_SCHEMA_CHARS = 16_000;
function convertsToObjectSchema(schema: Record<string, unknown>): boolean {
try {
return fromJSONSchema(schema as Parameters<typeof fromJSONSchema>[0]) instanceof ZodObject;
} catch {
return false;
}
}
const clientToolInputSchema = z
.looseObject({
type: z.literal("object"),
properties: z.record(z.string(), z.unknown()).optional(),
required: z.array(z.string()).optional(),
})
.refine((schema) => JSON.stringify(schema).length <= MAX_CLIENT_TOOL_SCHEMA_CHARS, {
message: `must be at most ${MAX_CLIENT_TOOL_SCHEMA_CHARS} characters of JSON`,
abort: true,
})
.refine(convertsToObjectSchema, { message: "must convert to a plain object schema" });
const clientToolsSchema = z
.array(
z.object({
name: z.string().regex(/^ui__[a-z0-9_]{1,60}$/),
description: z
.string()
.max(2_000)
.refine((description) => description.trim() !== "", { message: "must not be blank" }),
inputSchema: clientToolInputSchema,
timeoutMs: z.int().min(1_000).max(60_000).optional(),
}),
)
.max(32)
.refine((tools) => new Set(tools.map((tool) => tool.name)).size === tools.length, {
message: "names must be unique",
});
const clientResultSchema = z.object({
callId: z.string().min(1).max(256),
result: z.object({
content: z.string(),
structured: z.unknown().optional(),
isError: z.boolean().optional(),
images: z
.array(
z.object({
data: z.string().max(4_000_000).base64(),
mimeType: z.enum(["image/png", "image/jpeg"]),
}),
)
.max(4)
.optional(),
}),
});
function zodMessage(field: string, error: z.ZodError): string {
const issue = error.issues[0]!;
return `${[field, ...issue.path.map(String)].join(".")}: ${issue.message}`;
}
function publicOrigin(origin: TurnOrigin | undefined): TurnOrigin | undefined {
if (origin?.kind !== "automation") return origin;
const { useOwnerKeychain: _internalOnly, ...safe } = origin;
return safe;
}
function publicTurnOrigin(body: TurnRequest): { origin?: TurnOrigin; error?: string } {
const typed = publicOrigin(body.origin);
if (
typed?.kind === "automation" &&
body.triggered === true &&
typed.screenData !== undefined &&
body.securityScreenData !== undefined &&
typed.screenData !== body.securityScreenData
) {
return { error: "conflicting typed and legacy automation screen data" };
}
return { origin: resolveTurnOrigin({ ...body, ...(typed ? { origin: typed } : { origin: undefined }) }) };
}
function sanitizedTurnRequest(body: TurnRequest): { request: TurnRequest } | { error: string } {
const {
slackSource: _slackSource,
externalSlack: _externalSlack,
ownerKeychainUnion: _ownerKeychainUnion,
spawned: _spawned,
unattendedGrants: _unattendedGrants,
redeliveryKey: _redeliveryKey,
...safeBody
} = body;
if (typeof safeBody.idempotencyKey === "string" && safeBody.idempotencyKey.startsWith("slack:"))
return { error: "idempotencyKey must not use the reserved slack: prefix" };
const resolvedOrigin = publicTurnOrigin(safeBody);
if (resolvedOrigin.error) return { error: resolvedOrigin.error };
const origin = resolvedOrigin.origin;
const { clientTools: rawClientTools, ...rest } = safeBody;
if (rest.desktopClientId !== undefined && !z.uuid().safeParse(rest.desktopClientId).success)
return { error: "desktopClientId must be a UUID" };
let clientTools: ClientToolDeclaration[] | undefined;
if (rawClientTools !== undefined) {
const parsed = clientToolsSchema.safeParse(rawClientTools);
if (!parsed.success) return { error: zodMessage("clientTools", parsed.error) };
clientTools = parsed.data;
}
return { request: { ...rest, ...(origin ? { origin } : {}), ...(clientTools?.length ? { clientTools } : {}) } };
}
async function postTurn(ctx: ApiCtx): Promise<void> {
const { res, app, url, body } = ctx;
if (!isTurnRequest(body)) {
return sendJson(res, 400, { error: "bad_request", message: "expected a TurnRequest" });
}
const wantAsync = url.searchParams.get("async") === "1" || body.async === true;
const sanitized = sanitizedTurnRequest(body);
if ("error" in sanitized) return sendJson(res, 400, { error: "bad_request", message: sanitized.error });
const result = await app.turn({ ...sanitized.request, async: wantAsync });
if (result.status === "queued") return sendJson(res, 202, result);
const status = result.status === "refused" ? 403 : 200;
return sendJson(res, status, result);
}
async function getApproval(ctx: ApiCtx): Promise<void> {
const { res, app, actor } = ctx;
const id = ctx.params.id!;
if (!id || id.includes("/")) return sendJson(res, 404, { error: "not_found" });
const record = await app.getApproval(id, actor?.p);
return record ? sendJson(res, 200, record) : sendJson(res, 404, { error: "not_found" });
}
async function getPendingApproval(ctx: ApiCtx): Promise<void> {
const { res, app, url, actor } = ctx;
const threadRef = url.searchParams.get("threadRef") ?? "";
if (!threadRef) return sendJson(res, 400, { error: "bad_request", message: "threadRef required" });
return sendJson(res, 200, { pending: await app.pendingApprovalForThread(threadRef, actor?.p) });
}
async function postRunDeliveryState(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
const editRef = isObj(body) && typeof body.editRef === "string" ? body.editRef : "";
if (!id || !editRef) return sendJson(res, 400, { error: "bad_request", message: "editRef required" });
const found = await app.setRunDeliveryState(id, { editRef });
if (!found) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, { ok: true });
}
async function postRunSignal(ctx: ApiCtx): Promise<void> {
const { res, app, body, actor } = ctx;
const id = ctx.params.id!;
const kind = isObj(body) && typeof body.kind === "string" ? body.kind : "";
if (kind !== "abort" && kind !== "steer" && kind !== "client_result") {
return sendJson(res, 400, { error: "bad_request", message: "kind must be abort, steer or client_result" });
}
if (kind === "client_result") {
const run = await ctx.deps.runs?.get(id);
if (run?.request.desktopClientId && (!isObj(body) || body.desktopClientId !== run.request.desktopClientId))
return sendJson(res, 403, { error: "wrong_desktop_client" });
const parsed = clientResultSchema.safeParse(body);
if (!parsed.success)
return sendJson(res, 400, { error: "bad_request", message: zodMessage("client_result", parsed.error) });
const outcome = await app.signalRun(id, { kind, ...parsed.data }, actor?.p);
if (outcome.accepted) return sendJson(res, 200, outcome);
if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 409, outcome);
}
const text = isObj(body) && typeof body.text === "string" ? body.text : undefined;
const queuedRunId = isObj(body) && typeof body.queuedRunId === "string" ? body.queuedRunId : undefined;
const ts = isObj(body) && typeof body.ts === "string" && body.ts ? body.ts : undefined;
let request: TurnRequest | undefined;
if (isObj(body) && body.request !== undefined) {
if (!isTurnRequest(body.request)) {
return sendJson(res, 400, { error: "bad_request", message: "request must be a TurnRequest" });
}
if (actor && !samePerson(body.request.actor.externalId, actor.p)) {
return sendJson(res, 403, { error: "forbidden", message: "portal identity does not match the requested actor" });
}
const sanitized = sanitizedTurnRequest(body.request);
if ("error" in sanitized) return sendJson(res, 400, { error: "bad_request", message: sanitized.error });
request = sanitized.request;
}
const outcome = await app.signalRun(
id,
{
kind,
...(text !== undefined ? { text } : {}),
...(ts ? { ts } : {}),
...(request ? { request } : {}),
...(queuedRunId ? { queuedRunId } : {}),
},
actor?.p,
);
if (outcome.accepted) return sendJson(res, 200, outcome);
if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
if (outcome.reason === "text_required")
return sendJson(res, 400, { error: "bad_request", message: "text required", ...outcome });
if (outcome.reason === "conversation_mismatch")
return sendJson(res, 400, {
error: "bad_request",
message: "request conversation does not match the run",
...outcome,
});
return sendJson(res, 409, outcome);
}
async function getRun(ctx: ApiCtx): Promise<void> {
const { res, app, actor } = ctx;
const id = ctx.params.id!;
const run = await app.getRun(id, actor?.p);
if (!run) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, run);
}
async function getActiveRunForThread(ctx: ApiCtx): Promise<void> {
const { res, app, url, actor } = ctx;
const threadRef = url.searchParams.get("threadRef") ?? "";
if (!threadRef) return sendJson(res, 400, { error: "bad_request", message: "threadRef required" });
const active = await app.activeRunForThread(threadRef, actor?.p);
return sendJson(res, 200, { runId: active?.runId ?? null, ...(active?.queued ? { queued: active.queued } : {}) });
}
async function patchQueuedRun(ctx: ApiCtx): Promise<void> {
const { res, app, actor, body } = ctx;
if (!isObj(body) || typeof body.text !== "string" || typeof body.expectedText !== "string")
return sendJson(res, 400, { error: "bad_request", message: "text and expectedText required" });
const outcome = await app.editQueuedRun(ctx.params.id!, body.text, body.expectedText, actor?.p);
if (outcome.edited) return sendJson(res, 200, outcome);
if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
return sendJson(res, outcome.reason === "empty_text" ? 400 : 409, outcome);
}
async function postRunWithdraw(ctx: ApiCtx): Promise<void> {
const { res, app, actor } = ctx;
const outcome = await app.withdrawRun(ctx.params.id!, actor?.p);
if (outcome.withdrawn) return sendJson(res, 200, outcome);
if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 409, outcome);
}
async function listDeliveries(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const type = url.searchParams.get("type") ?? "";
const claimMsRaw = Number(url.searchParams.get("claimMs") ?? 0);
const claimMs = Number.isFinite(claimMsRaw) && claimMsRaw > 0 ? claimMsRaw : 0;
return sendJson(res, 200, { deliveries: await app.pendingDeliveries(type, claimMs) });
}
async function ackDelivery(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
const recipientThreadRef =
isObj(body) && typeof body.recipientThreadRef === "string" ? body.recipientThreadRef : undefined;
const slackApiMs =
isObj(body) && typeof body.slackApiMs === "number" && Number.isFinite(body.slackApiMs) && body.slackApiMs >= 0
? body.slackApiMs
: undefined;
if (recipientThreadRef) await app.recordPrincipalDelivery(id, recipientThreadRef);
await app.ackDelivery(id, slackApiMs);
return sendJson(res, 200, { ok: true });
}
async function ackDeliveryByKey(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const idempotencyKey = isObj(body) && typeof body.idempotencyKey === "string" ? body.idempotencyKey : "";
if (!idempotencyKey) return sendJson(res, 400, { error: "bad_request", message: "idempotencyKey required" });
await app.ackDeliveryByKey(idempotencyKey);
return sendJson(res, 200, { ok: true });
}
export const turnRoutes: ReadonlyArray<Route<ApiCtx>> = [
{ method: "POST", path: "/v1/turns", actor: "system", auth: "source", handle: postTurn },
{ method: "GET", path: "/v1/approvals/pending", actor: "person", auth: "source", handle: getPendingApproval },
{ method: "GET", path: "/v1/approvals/:id", actor: "person", auth: "source", handle: getApproval },
{
method: "POST",
path: "/v1/runs/:id/delivery-state",
actor: "system",
auth: "source",
handle: postRunDeliveryState,
},
{ method: "POST", path: "/v1/runs/:id/signal", auth: "source", maxBodyBytes: 6_000_000, handle: postRunSignal },
{ method: "PATCH", path: "/v1/runs/:id/input", auth: "source", handle: patchQueuedRun },
{ method: "POST", path: "/v1/runs/:id/withdraw", auth: "source", handle: postRunWithdraw },
{ method: "GET", path: "/v1/runs/:id", actor: "person", auth: "source", handle: getRun },
{ method: "GET", path: "/v1/runs", actor: "person", auth: "source", handle: getActiveRunForThread },
{ method: "GET", path: "/v1/deliveries", auth: "source", handle: listDeliveries },
{ method: "POST", path: "/v1/deliveries/:id/ack", actor: "system", auth: "source", handle: ackDelivery },
{ method: "POST", path: "/v1/deliveries/ack-by-key", actor: "system", auth: "source", handle: ackDeliveryByKey },
];