Multiplayer agent harness for work.
import type { CapabilityClaims } from "../../auth/capability-token.ts";
import { memoryForRequest } from "./memory-access.ts";
import type { MemoryEdit, MemoryService } from "../../memory/memory-service.ts";
import { suggestedActivityRoutes } from "./suggested-activities.ts";
import { runtimeFallback, runtimeConfigBody, userRuntimeConfigBody, webuiModelEnabled } from "../runtime-config.ts";
import { canReadNotebook, searchAcrossScopes } from "../../memory/cross-scope.ts";
import { sessionSharingRoutes } from "./session-sharing.ts";
import type { Grant, PendingApproval, ScopeId, Session } from "../../types.ts";
import { parseScopeId, scopeId as makeScopeId } from "../../types.ts";
import type { Skill, SkillResolution } from "../../skills/skill-store.ts";
import { ByteSourceTooLargeError } from "../../files/durable-byte-store.ts";
import {
defaultModelForHarness,
isHarnessId,
modelSupportedByHarness,
modelOfferedInWebui,
thinkingLevelsForHarness,
fastModeModelIds,
} from "../../model/pi-models.ts";
import { builtInModelCatalog, selectableCatalogForHarness, selectableModelCatalog } from "../../model/model-catalog.ts";
import { errMessage } from "../../util/errors.ts";
import { SoulUpdateDeniedError, type SessionPageStatus } from "../app-types.ts";
import { renderAgentApis } from "../agent-api-catalog.ts";
import { mintCapabilityToken, CAPABILITY_TTL_MS } from "../../auth/capability-token.ts";
import { contentTypeWithUtf8Charset, pipeToResponse, sendJson } from "../http.ts";
import { resolveBranding } from "../../resolution/branding.ts";
import { audit, isObj, orgScope } from "./shared.ts";
import {
UI_STATE_KEY_PATTERN,
UI_STATE_MAX_BYTES,
UI_STATE_MAX_FUTURE_SKEW_MS,
storeUiState,
uiStateId,
} from "../../surfaces/ui-state.ts";
import { redactWebhook } from "./webhooks.ts";
import { withActor, type ApiCtx, type Route } from "./route.ts";
import {
ARTIFACT_TYPES,
isArtifactType,
livePersonCapability,
splitToScope,
SHARED_SKILL_TRIGGER_REFUSAL,
} from "../artifact-share.ts";
function isGrant(b: unknown): b is Grant {
return (
isObj(b) &&
typeof b.ownerScopeId === "string" &&
typeof b.ref === "string" &&
typeof b.granteeScopeId === "string" &&
(b.permission === "read" || b.permission === "write") &&
typeof b.grantedBy === "string"
);
}
function sharedSkillCreateBlock(capability: ApiCtx["capability"]): string | null {
if (!capability) return null;
if (parseScopeId(capability.scopeId).kind === "personal") return null;
if (livePersonCapability(capability)) return null;
return SHARED_SKILL_TRIGGER_REFUSAL;
}
function isConversationColor(value: unknown): value is string | null {
return value === null || (typeof value === "string" && /^#[0-9a-fA-F]{6}$/.test(value));
}
async function regenerateSessionTitle(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
const principalId = (body as { principalId?: unknown }).principalId;
if (typeof principalId !== "string" || !principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
const out = await app.regenerateTitle(id, principalId);
if (!out) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, out);
}
async function detachSession(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
const principalId = (body as { principalId?: unknown }).principalId;
if (typeof principalId !== "string" || !principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
const out = await app.detachSession(id, principalId);
if (!out) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, out);
}
async function cancelSessionGoal(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const principalId = (body as { principalId?: unknown }).principalId;
if (typeof principalId !== "string" || !principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
const out = await app.cancelSessionGoal(ctx.params.id!, principalId);
if (!out) return sendJson(res, 404, { error: "not_found" });
if (!out.cancelled)
return sendJson(res, 409, {
error: out.reason,
message:
out.reason === "busy"
? "The conversation is still finishing a reply. Try again in a moment."
: "This conversation has no active or paused goal to cancel.",
});
return sendJson(res, 200, out);
}
async function forkSession(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
const b = body as { principalId?: unknown; upToSeq?: unknown };
if (typeof b.principalId !== "string" || !b.principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
if (b.upToSeq !== undefined && (typeof b.upToSeq !== "number" || !Number.isInteger(b.upToSeq) || b.upToSeq < 0)) {
return sendJson(res, 400, { error: "bad_request", message: "upToSeq must be a non-negative integer" });
}
const out = await app.forkSession(id, b.principalId, b.upToSeq !== undefined ? { upToSeq: b.upToSeq } : undefined);
if (!out) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, out);
}
function agentConversation(session: Session) {
return {
id: session.id,
title: session.title,
type: session.type,
scopeId: session.scopeId,
threadRef: session.threadRef,
surface: session.surface,
createdAt: session.createdAt,
archived: session.archived === true,
pinned: session.pinned === true,
color: session.color ?? null,
unread: session.unread === true,
lastActivityAt: session.lastActivityAt ?? session.createdAt,
};
}
function transcriptWindow(
url: URL,
defaultTailTurns?: number,
): { tailTurns?: number; sinceSeq?: number; beforeSeq?: number } | null {
const windowParam = (name: "tailTurns" | "sinceSeq" | "beforeSeq", min: number): number | undefined | null => {
const raw = url.searchParams.get(name);
if (raw === null) return undefined;
const n = Number(raw);
return Number.isInteger(n) && n >= min ? n : null;
};
const requestedTailTurns = windowParam("tailTurns", 1);
const sinceSeq = windowParam("sinceSeq", 0);
const beforeSeq = windowParam("beforeSeq", 1);
if (requestedTailTurns === null || sinceSeq === null || beforeSeq === null) return null;
const tailTurns = requestedTailTurns ?? (sinceSeq === undefined ? defaultTailTurns : undefined);
if (tailTurns === undefined && sinceSeq === undefined && beforeSeq === undefined) return {};
return {
...(tailTurns !== undefined ? { tailTurns } : {}),
...(sinceSeq !== undefined ? { sinceSeq } : {}),
...(beforeSeq !== undefined ? { beforeSeq } : {}),
};
}
async function getSession(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const id = ctx.params.id!;
const viewer = url.searchParams.get("viewer");
if (!viewer) return sendJson(res, 400, { error: "bad_request", message: "viewer required" });
const window = transcriptWindow(url);
if (!window) {
return sendJson(res, 400, {
error: "bad_request",
message: "tailTurns and beforeSeq must be positive integers, sinceSeq a non-negative one",
});
}
const found = await app.getSessionForViewer(id, viewer, Object.keys(window).length ? window : undefined);
if (!found) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, found);
}
async function getAgentConversation(ctx: ApiCtx): Promise<void> {
const { res, app, url, capability } = ctx;
if (!capability) {
return sendJson(res, 401, { error: "capability_required", message: "this endpoint is for the agent self-API" });
}
if (url.searchParams.has("sinceSeq")) {
return sendJson(res, 400, {
error: "bad_request",
message: "agent transcript paging supports tailTurns and beforeSeq",
});
}
const window = transcriptWindow(url, 20);
if (!window) {
return sendJson(res, 400, {
error: "bad_request",
message: "tailTurns and beforeSeq must be positive integers, sinceSeq a non-negative one",
});
}
const found = await app.getSessionForViewer(ctx.params.id!, capability.actorId, window);
if (!found) return sendJson(res, 404, { error: "not_found", message: "not a conversation you can see" });
return sendJson(res, 200, {
session: agentConversation(found.session),
entries: found.entries.filter((entry) => entry.type !== "system"),
...(found.earlierEntries ? { earlierEntries: found.earlierEntries } : {}),
});
}
async function getSessionEntry(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const id = ctx.params.id!;
const viewer = url.searchParams.get("viewer");
if (!viewer) return sendJson(res, 400, { error: "bad_request", message: "viewer required" });
const seq = Number(ctx.params.seq);
if (!Number.isInteger(seq) || seq < 0) {
return sendJson(res, 400, { error: "bad_request", message: "seq must be a non-negative integer" });
}
const found = await app.getSessionEntryForViewer(id, viewer, seq);
if (!found) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, found);
}
async function listSessionApprovals(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const id = ctx.params.id!;
const viewer = url.searchParams.get("viewer");
if (!viewer) return sendJson(res, 400, { error: "bad_request", message: "viewer required" });
const approvals = await app.listSessionApprovals(id, viewer);
return sendJson(res, 200, { approvals: [...approvals, ...(await credentialApprovals(ctx, id, viewer))] });
}
// Pending credential requests from this session or any of its sub-agents, shown inline to their owner.
async function credentialApprovals(ctx: ApiCtx, sessionId: string, viewer: string): Promise<PendingApproval[]> {
const kc = ctx.deps.keychain;
const approvals = ctx.deps.keychainApprovals;
if (!kc || !approvals) return [];
const out: PendingApproval[] = [];
for (const ask of await kc.listAsks({ ownerId: viewer })) {
if (ask.status !== "pending") continue;
const view = await approvals.get(ask.id, viewer);
if (!view || (view.sessionId !== sessionId && view.requesterSessionId !== sessionId)) continue;
out.push({
requestId: `keychain:${ask.id}`,
command: view.accountLabel ? `${view.service} (${view.accountLabel})` : view.service,
summary: `Use your ${view.service} credential in ${view.conversation}`,
reason: "Credential approval",
grantModes: { session: false, always: true },
blocksInput: false,
});
}
return out;
}
async function getSessionBackground(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const id = ctx.params.id!;
const viewer = url.searchParams.get("viewer");
if (!viewer) return sendJson(res, 400, { error: "bad_request", message: "viewer required" });
const view = await app.sessionBackground(id, viewer);
if (!view) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, view);
}
async function getSessionBackgroundOutput(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const id = ctx.params.id!;
const processId = ctx.params.pid!;
const viewer = url.searchParams.get("viewer");
if (!viewer) return sendJson(res, 400, { error: "bad_request", message: "viewer required" });
const sinceCursor = Math.max(0, Number(url.searchParams.get("sinceCursor") ?? "0") || 0);
const read = await app.readSessionBackgroundOutput(id, processId, viewer, sinceCursor);
if (!read) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, read);
}
async function getFileContent(ctx: ApiCtx): Promise<void> {
const { res, app, capability, actor } = ctx;
const id = ctx.params.id!;
const viewer = capability?.actorId ?? actor?.p;
if (!viewer) return sendJson(res, 401, { error: "capability_required" });
const opened = await app.openFileForViewer(id, viewer);
if (!opened) return sendJson(res, 404, { error: "not_found" });
res.writeHead(200, {
"content-type": contentTypeWithUtf8Charset(opened.mimetype || "application/octet-stream"),
"content-length": String(opened.sizeBytes),
"content-disposition": `inline; filename*=UTF-8''${encodeURIComponent(opened.name)}`,
});
pipeToResponse(res, opened.stream, "file read failed");
return;
}
async function listFiles(ctx: ApiCtx): Promise<void> {
const { res, app, url, capability, actor } = ctx;
const viewer = capability?.actorId ?? actor?.p;
if (!viewer) return sendJson(res, 401, { error: "capability_required" });
const limitRaw = url.searchParams.get("limit");
const cursor = url.searchParams.get("cursor");
const scope = url.searchParams.get("scope");
const page = await app.listFilesForViewer(
viewer,
{
...(limitRaw ? { limit: Number(limitRaw) } : {}),
...(cursor ? { cursor } : {}),
},
scope ? (scope as ScopeId) : undefined,
);
return sendJson(res, 200, page);
}
async function uploadFile(ctx: ApiCtx): Promise<void> {
const { res, app, deps, body } = ctx;
if (!deps.blobTransfer)
return sendJson(res, 501, { error: "not_configured", message: "blob transfer store not wired" });
const b = isObj(body) ? body : {};
const principalId = typeof b.principalId === "string" ? b.principalId.trim() : "";
const blobId = typeof b.blobId === "string" ? b.blobId.trim() : "";
const name = typeof b.name === "string" ? b.name : "";
const mimetype = typeof b.mimetype === "string" ? b.mimetype : undefined;
const scopeId = typeof b.scopeId === "string" && b.scopeId ? (b.scopeId as ScopeId) : undefined;
if (!principalId || !blobId || !name)
return sendJson(res, 400, { error: "bad_request", message: "principalId, blobId, and name required" });
const opened = await deps.blobTransfer.open(blobId);
if (!opened) return sendJson(res, 404, { error: "not_found", message: "staged blob not found" });
try {
const file = await app.uploadFileForViewer(principalId, {
...(scopeId ? { scopeId } : {}),
name,
...(mimetype ? { mimetype } : {}),
data: opened.stream,
});
if (!file) {
opened.stream.destroy();
return sendJson(res, 403, { error: "forbidden", message: "you can only upload to your own contexts" });
}
return sendJson(res, 200, { file });
} catch (e) {
if (e instanceof ByteSourceTooLargeError)
return sendJson(res, 413, { error: "payload_too_large", message: e.message });
throw e;
} finally {
await deps.blobTransfer.delete(blobId);
}
}
async function patchSession(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const id = ctx.params.id!;
const b = body as {
principalId?: unknown;
title?: unknown;
archived?: unknown;
pinned?: unknown;
color?: unknown;
unread?: unknown;
};
const principalId = typeof b.principalId === "string" ? b.principalId : null;
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const patch: {
title?: string | null;
archived?: boolean;
pinned?: boolean;
color?: string | null;
readAt?: number;
} = {};
if ("unread" in b) {
if (typeof b.unread !== "boolean") {
return sendJson(res, 400, { error: "bad_request", message: "unread must be a boolean" });
}
patch.readAt = b.unread ? 0 : Date.now();
}
if ("title" in b) {
if (b.title !== null && typeof b.title !== "string") {
return sendJson(res, 400, { error: "bad_request", message: "title must be a string or null" });
}
const trimmed = typeof b.title === "string" ? b.title.trim().slice(0, 200) : null;
patch.title = trimmed ? trimmed : null;
}
if ("archived" in b) {
if (typeof b.archived !== "boolean") {
return sendJson(res, 400, { error: "bad_request", message: "archived must be a boolean" });
}
patch.archived = b.archived;
}
if ("pinned" in b) {
if (typeof b.pinned !== "boolean") {
return sendJson(res, 400, { error: "bad_request", message: "pinned must be a boolean" });
}
patch.pinned = b.pinned;
}
if ("color" in b) {
if (!isConversationColor(b.color)) {
return sendJson(res, 400, { error: "bad_request", message: "color must be '#rrggbb' or null" });
}
patch.color = typeof b.color === "string" ? b.color.toLowerCase() : null;
}
if (
patch.title === undefined &&
patch.archived === undefined &&
patch.pinned === undefined &&
patch.color === undefined &&
patch.readAt === undefined
) {
return sendJson(res, 400, {
error: "bad_request",
message: "title, archived, pinned, color, or unread required",
});
}
const session = await app.updateSession(id, principalId, patch);
if (!session) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, { session });
}
async function listAgentConversations(ctx: ApiCtx): Promise<void> {
const { res, app, capability } = ctx;
if (!capability) {
return sendJson(res, 401, { error: "capability_required", message: "this endpoint is for the agent self-API" });
}
const sessions = await app.listSessions(capability.actorId);
return sendJson(res, 200, {
conversations: sessions.map(agentConversation),
});
}
async function patchAgentConversation(ctx: ApiCtx): Promise<void> {
const { res, app, capability, body } = ctx;
if (!capability) {
return sendJson(res, 401, { error: "capability_required", message: "this endpoint is for the agent self-API" });
}
const b = isObj(body) ? body : {};
const patch: {
title?: string | null;
archived?: boolean;
pinned?: boolean;
color?: string | null;
} = {};
if ("archived" in b) {
if (typeof b.archived !== "boolean") {
return sendJson(res, 400, { error: "bad_request", message: "archived must be a boolean" });
}
patch.archived = b.archived;
}
if ("pinned" in b) {
if (typeof b.pinned !== "boolean") {
return sendJson(res, 400, { error: "bad_request", message: "pinned must be a boolean" });
}
patch.pinned = b.pinned;
}
if ("title" in b) {
if (b.title !== null && typeof b.title !== "string") {
return sendJson(res, 400, { error: "bad_request", message: "title must be a string or null" });
}
const trimmed = typeof b.title === "string" ? b.title.trim().slice(0, 200) : null;
patch.title = trimmed ? trimmed : null;
}
if ("color" in b) {
if (!isConversationColor(b.color)) {
return sendJson(res, 400, { error: "bad_request", message: "color must be '#rrggbb' or null" });
}
patch.color = typeof b.color === "string" ? b.color.toLowerCase() : null;
}
if (
patch.archived === undefined &&
patch.pinned === undefined &&
patch.title === undefined &&
patch.color === undefined
) {
return sendJson(res, 400, { error: "bad_request", message: "archived, pinned, title, or color required" });
}
const session = await app.updateSession(ctx.params.id!, capability.actorId, patch);
if (!session) return sendJson(res, 404, { error: "not_found", message: "not a conversation you can see" });
audit(ctx.deps, {
principalId: capability.actorId,
action: "conversation.update",
resource: session.id,
scopeLabel: session.scopeId,
detail: JSON.stringify(patch),
});
return sendJson(res, 200, {
conversation: {
...agentConversation(session),
...(patch.title !== undefined ? { title: patch.title } : {}),
},
});
}
const DEFAULT_SESSION_PAGE = 50;
async function listSessions(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const principalId = url.searchParams.get("principalId");
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const n = Number(url.searchParams.get("limit") ?? DEFAULT_SESSION_PAGE);
const before = parseSessionCursor(url.searchParams.get("before"));
const status = url.searchParams.get("status") ?? "active";
if (!Number.isInteger(n) || n < 1 || before === null || !isSessionPageStatus(status))
return sendJson(res, 400, {
error: "bad_request",
message: "limit must be a positive integer, before a cursor, status active, archived or waiting",
});
const page = await app.listSessionPage(principalId, {
limit: n,
...(before ? { before } : {}),
status,
...(url.searchParams.get("surface") ? { surface: url.searchParams.get("surface")! } : {}),
...(url.searchParams.get("scope") ? { scopeId: url.searchParams.get("scope")! } : {}),
...(url.searchParams.get("q")?.trim() ? { titleQuery: url.searchParams.get("q")!.trim() } : {}),
});
return sendJson(res, 200, {
sessions: page.sessions,
...(page.pinned ? { pinned: page.pinned } : {}),
...(page.hasArchived !== undefined ? { hasArchived: page.hasArchived } : {}),
nextCursor: page.next ? `${page.next.activity}.${page.next.id}` : null,
});
}
function isSessionPageStatus(value: string): value is SessionPageStatus {
return value === "active" || value === "archived" || value === "waiting";
}
function parseSessionCursor(raw: string | null): { activity: number; id: string } | undefined | null {
if (raw === null || raw === "") return undefined;
const dot = raw.indexOf(".");
const activity = Number(raw.slice(0, dot));
const id = raw.slice(dot + 1);
return dot > 0 && Number.isSafeInteger(activity) && id ? { activity, id } : null;
}
async function listSessionChildren(ctx: ApiCtx): Promise<void> {
const { res, app, url, params } = ctx;
const principalId = url.searchParams.get("principalId");
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const children = await app.sessionChildren(principalId, params.id!);
if (!children) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, { sessions: children });
}
async function getSessionRow(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const principalId = url.searchParams.get("principalId");
const id = url.searchParams.get("id") ?? undefined;
const threadRef = url.searchParams.get("threadRef") ?? undefined;
if (!principalId || (!id && !threadRef))
return sendJson(res, 400, { error: "bad_request", message: "principalId and id or threadRef required" });
const session = await app.sessionRow(principalId, id ? { id } : { threadRef });
if (!session) return sendJson(res, 404, { error: "not_found" });
return sendJson(res, 200, { session: session });
}
async function searchResources(ctx: ApiCtx): Promise<void> {
const principalId = ctx.actor?.p ?? ctx.url.searchParams.get("principalId");
if (!principalId) return sendJson(ctx.res, 400, { error: "bad_request" });
const query = (ctx.url.searchParams.get("q") ?? "").slice(0, 500);
return sendJson(ctx.res, 200, await ctx.app.searchResources(principalId, query));
}
async function searchSessions(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const principalId = url.searchParams.get("principalId");
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const query = url.searchParams.get("q") ?? "";
const rawLimit = Number(url.searchParams.get("limit") ?? "");
const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : undefined;
return sendJson(res, 200, { hits: await app.searchSessions(principalId, query, limit) });
}
async function listContexts(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const principalId = url.searchParams.get("principalId");
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
return sendJson(res, 200, { contexts: await app.listContexts(principalId) });
}
async function listScopeResources(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const principalId = url.searchParams.get("principalId");
const scope = url.searchParams.get("scope");
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
if (!scope) return sendJson(res, 400, { error: "bad_request", message: "scope required" });
const out = await app.listScopeResources(principalId, scope as ScopeId);
if (!out) return sendJson(res, 404, { error: "not_found", message: "not a context you can see" });
return sendJson(res, 200, {
files: out.files,
crons: out.crons,
webhooks: out.webhooks.map(redactWebhook),
deployments: out.deployments,
skills: out.skills,
manageable: out.manageable,
});
}
async function getUiState(ctx: ApiCtx): Promise<void> {
const { res, deps, url } = ctx;
const principalId = url.searchParams.get("principalId");
const key = url.searchParams.get("key") ?? "";
if (!principalId || !UI_STATE_KEY_PATTERN.test(key))
return sendJson(res, 400, { error: "bad_request", message: "principalId and a valid key required" });
if (!deps.uiState) return sendJson(res, 404, { error: "not_found" });
const rec = await deps.uiState.get(uiStateId(principalId, key));
return sendJson(res, 200, rec ?? { value: null, updatedAt: 0 });
}
async function putUiState(ctx: ApiCtx): Promise<void> {
const { res, deps, body } = ctx;
const b = body as { principalId?: unknown; key?: unknown; value?: unknown; updatedAt?: unknown };
const principalId = typeof b.principalId === "string" ? b.principalId : "";
const key = typeof b.key === "string" ? b.key : "";
if (!principalId || !UI_STATE_KEY_PATTERN.test(key))
return sendJson(res, 400, { error: "bad_request", message: "principalId and a valid key required" });
if (b.value === undefined) return sendJson(res, 400, { error: "bad_request", message: "value required" });
if (Buffer.byteLength(JSON.stringify(b.value)) > UI_STATE_MAX_BYTES)
return sendJson(res, 413, { error: "payload_too_large", message: "ui state too large" });
if (!deps.uiState) return sendJson(res, 404, { error: "not_found" });
const claimed = typeof b.updatedAt === "number" && Number.isFinite(b.updatedAt) ? b.updatedAt : Date.now();
const updatedAt = Math.min(claimed, Date.now() + UI_STATE_MAX_FUTURE_SKEW_MS);
const result = await storeUiState(deps.uiState, uiStateId(principalId, key), { value: b.value, updatedAt });
return sendJson(res, 200, result);
}
export async function memoryFacts(memory: MemoryService, scope: ScopeId) {
return ((await memory.facts?.(scope)) ?? []).map(({ id, text, createdAt, updatedAt }) => ({
id,
text,
createdAt,
updatedAt,
}));
}
export function parseEdits(body: unknown): MemoryEdit[] | string {
const facts = (isObj(body) ? body : {}).facts;
if (!Array.isArray(facts) || !facts.length) return "facts (non-empty array of {id, text}) required";
const edits = facts.flatMap((fact): MemoryEdit[] =>
isObj(fact) && typeof fact.id === "string" && typeof fact.text === "string" && fact.text.trim()
? [{ id: fact.id, text: fact.text }]
: [],
);
return edits.length === facts.length ? edits : "every fact needs a string id and non-empty text";
}
export function parseIds(body: unknown): string[] | string {
const ids = (isObj(body) ? body : {}).ids;
return Array.isArray(ids) && ids.length && ids.every((id) => typeof id === "string" && id.trim())
? (ids as string[])
: "ids (non-empty string array) required";
}
async function selfMemory(ctx: ApiCtx): Promise<void> {
const { res, deps, url, method, body } = ctx;
const principalId =
method === "GET" ? url.searchParams.get("principalId") : (body as { principalId?: unknown }).principalId;
if (typeof principalId !== "string" || !principalId)
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const memory = memoryForRequest(ctx, principalId);
if (!memory) return sendJson(res, 404, { error: "not_found" });
const scope = makeScopeId("personal", principalId);
if (method === "PATCH") {
const edits = parseEdits(body);
if (typeof edits === "string") return sendJson(res, 400, { error: "bad_request", message: edits });
await memory.edit?.(scope, edits, principalId);
} else if (method === "DELETE") {
const ids = parseIds(body);
if (typeof ids === "string") return sendJson(res, 400, { error: "bad_request", message: ids });
await memory.delete?.(scope, ids, principalId);
}
const action = method === "GET" ? "memory.self.read" : "memory.self.update";
audit(deps, { principalId, action, resource: "memory", scopeLabel: scope });
return sendJson(res, 200, { scopeId: scope, facts: await memoryFacts(memory, scope) });
}
async function sessionCapability(ctx: ApiCtx): Promise<void> {
const { res, deps, actor } = ctx;
if (!actor) return sendJson(res, 401, { error: "unauthorized", message: "portal identity required" });
const secret = deps.capabilitySecret ?? ctx.secret;
if (!secret) return sendJson(res, 503, { error: "not_configured", message: "capability secret not set" });
const token = await mintCapabilityToken(
{ actorId: actor.p, scopeId: makeScopeId("personal", actor.p), exp: Date.now() + CAPABILITY_TTL_MS },
secret,
deps.capabilityTokenCompression,
);
return sendJson(res, 200, { token });
}
async function listAgentApis(ctx: ApiCtx): Promise<void> {
const { res, deps, capability } = ctx;
if (!capability) return sendJson(res, 401, { error: "unauthorized", message: "agent capability token required" });
const admin: { isAdmin: boolean; role?: string } = deps.admin
? await deps.admin.adminStatusOf({ id: capability.actorId, type: "internal" }).catch(() => ({ isAdmin: false }))
: { isAdmin: false };
audit(deps, {
principalId: capability.actorId,
action: "apis.list",
resource: "apis",
scopeLabel: capability.scopeId,
});
return sendJson(
res,
200,
renderAgentApis(
capability,
{ isAdmin: admin.isAdmin, ...(admin.role ? { role: admin.role } : {}) },
{ swarmsEnabled: Boolean(await ctx.app.swarms?.enabledFor(capability.actorId)) },
),
);
}
export function parseFacts(body: unknown): string[] | string {
const b = (isObj(body) ? body : {}) as { facts?: unknown };
const facts = Array.isArray(b.facts)
? b.facts.filter((f): f is string => typeof f === "string" && f.trim() !== "")
: [];
if (facts.length === 0) return "facts (non-empty string array) required";
if (facts.length > 20) return "at most 20 facts per call";
return facts;
}
type AgentMemoryHandler = (
ctx: ApiCtx,
memory: NonNullable<ReturnType<typeof memoryForRequest>>,
capability: CapabilityClaims,
) => Promise<void>;
const agentMemory =
(handle: AgentMemoryHandler) =>
async (ctx: ApiCtx): Promise<void> => {
const memory = memoryForRequest(ctx);
const { res, body, capability } = ctx;
if (!capability) return sendJson(res, 401, { error: "unauthorized", message: "agent capability token required" });
if (!memory) return sendJson(res, 404, { error: "not_found" });
if (isObj(body) && ["recipient", "channel", "participants"].some((key) => key in body)) {
return sendJson(res, 400, {
error: "bad_request",
message: "memory can only be changed from its own conversation",
});
}
return handle(ctx, memory, capability);
};
const searchMemory = agentMemory(async (ctx, memory, capability) => {
const { res, deps, body } = ctx;
const b = body as { query?: unknown; limit?: unknown; scope?: unknown };
if (typeof b.query !== "string" || !b.query.trim()) {
return sendJson(res, 400, { error: "bad_request", message: "query (string) required" });
}
const allowed = capability.memory?.read ?? [];
if (b.scope !== undefined && typeof b.scope !== "string")
return sendJson(res, 400, { error: "bad_request", message: "scope must be a string" });
if (typeof b.scope === "string" && !allowed.includes(b.scope))
return sendJson(res, 403, { error: "forbidden", message: "notebook is not readable here" });
const scopes = typeof b.scope === "string" ? [b.scope] : allowed;
if (scopes.length === 0) {
return sendJson(res, 403, { error: "forbidden", message: "memory recall is not enabled for this conversation" });
}
const results = await searchAcrossScopes(memory, scopes, b.query, typeof b.limit === "number" ? b.limit : 20, {
actorId: capability.actorId,
});
audit(deps, {
principalId: capability.actorId,
action: "memory.agent.search",
resource: "memory",
scopeLabel: scopes.join(","),
});
return sendJson(res, 200, { results });
});
const readOwnNotebook = agentMemory(async (ctx, memory, capability) => {
const { res, deps } = ctx;
const requested = ctx.url.searchParams.get("scope");
const read = capability.memory?.read ?? [];
const target =
requested === "org"
? (capability.memory?.orgWrite ?? read.find((scope) => scope.startsWith("org:")))
: (requested ?? capability.memory?.write ?? capability.scopeId);
if (!target || !canReadNotebook({ ...capability.memory, read }, target)) {
return sendJson(res, 403, { error: "forbidden", message: "notebook is not readable here" });
}
audit(deps, {
principalId: capability.actorId,
action: "memory.agent.read",
resource: "memory",
scopeLabel: target,
});
return sendJson(res, 200, { scopeId: target, facts: await memoryFacts(memory, target) });
});
const writeMemory = (handle: (...args: [...Parameters<AgentMemoryHandler>, write: string]) => Promise<void>) =>
agentMemory(async (ctx, memory, capability) => {
const requestedScope = (ctx.body as { scope?: unknown } | undefined)?.scope;
if (requestedScope !== undefined && requestedScope !== "org") {
return sendJson(ctx.res, 400, { error: "bad_request", message: 'scope must be "org" when present' });
}
const write = requestedScope === "org" ? capability.memory?.orgWrite : capability.memory?.write;
if (!write) {
return sendJson(ctx.res, 403, {
error: "forbidden",
message:
requestedScope === "org"
? "org memory writes require an org admin"
: "memory capture is not enabled for this conversation",
});
}
return handle(ctx, memory, capability, write);
});
const captureFacts = writeMemory(async ({ res, deps, body }, memory, capability, write) => {
const facts = parseFacts(body);
if (typeof facts === "string") return sendJson(res, 400, { error: "bad_request", message: facts });
const added = await memory.capture(write, facts, Date.now(), capability.actorId, {
mode: "explicit",
actorId: capability.actorId,
conversationScopeId: capability.scopeId,
...(capability.sessionId ? { sessionId: capability.sessionId } : {}),
});
audit(deps, {
principalId: capability.actorId,
action: "memory.agent.capture",
resource: "memory",
scopeLabel: write,
});
return sendJson(res, 200, { ok: true, added, scopeId: write });
});
const editFacts = writeMemory(async ({ res, deps, body }, memory, capability, write) => {
const edits = parseEdits(body);
if (typeof edits === "string") return sendJson(res, 400, { error: "bad_request", message: edits });
await memory.edit?.(write, edits, capability.actorId, { conversationScopeId: capability.scopeId });
audit(deps, {
principalId: capability.actorId,
action: "memory.agent.edit",
resource: "memory",
scopeLabel: write,
});
return sendJson(res, 200, { ok: true, scopeId: write });
});
const deleteFacts = writeMemory(async ({ res, deps, body }, memory, capability, write) => {
const ids = parseIds(body);
if (typeof ids === "string") return sendJson(res, 400, { error: "bad_request", message: ids });
await memory.delete?.(write, ids, capability.actorId);
audit(deps, {
principalId: capability.actorId,
action: "memory.agent.delete",
resource: "memory",
scopeLabel: write,
});
return sendJson(res, 200, { ok: true, scopeId: write });
});
async function listSkills(ctx: ApiCtx): Promise<void> {
const { res, app, url } = ctx;
const principalId = url.searchParams.get("principalId");
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const includeShadowed = url.searchParams.get("includeShadowed") === "1";
const resolved = (await app.listVisibleSkills(principalId)).filter(
(r): r is SkillResolution & { skill: Skill } => r.skill !== null,
);
const archivedChecks = await Promise.all(
(await app.listSkills())
.filter((skill) => skill.status === "archived")
.map(async (skill) => ({ skill, manageable: await app.canManageSkill(skill, principalId) })),
);
const archived = archivedChecks.filter((row) => row.manageable).map(({ skill }) => ({ skill, shadowed: [] }));
const visible = resolved.flatMap((row) => [
{ skill: row.skill, shadowed: row.shadowed },
...(includeShadowed ? row.shadowed.map((skill) => ({ skill, shadowed: [] })) : []),
]);
const skills = await Promise.all(
[...visible, ...archived].map(async (r) => ({
id: r.skill.id,
name: r.skill.manifest.name,
description: r.skill.manifest.description,
scope: parseScopeId(r.skill.scopeId).kind ?? r.skill.scopeId,
scopeId: r.skill.scopeId,
shadowed: r.shadowed.length > 0,
status: r.skill.status,
version: r.skill.version,
source: r.skill.pack ? "pack" : "native",
pack: r.skill.pack,
assetCount: r.skill.manifest.files?.length ?? 0,
requiredCapabilities: r.skill.manifest.requiredCapabilities,
editable: await app.canManageSkill(r.skill, principalId),
})),
);
return sendJson(res, 200, { skills });
}
async function getSkillDetail(ctx: ApiCtx): Promise<void> {
const { res, app, url, capability, actor } = ctx;
const principalId = capability?.actorId ?? actor?.p ?? url.searchParams.get("principalId");
if (!capability && !actor && ctx.secret) {
return sendJson(res, 401, { error: "capability_required" });
}
if (!principalId) return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
const skill = await app.getSkill(ctx.params.id!);
if (
!skill ||
(!(await app.canManageSkill(skill, principalId)) &&
!(await app.listVisibleSkills(principalId)).some((row) => row.skill?.id === skill.id))
) {
return sendJson(res, 404, { error: "not_found" });
}
return sendJson(res, 200, {
skill: {
id: skill.id,
name: skill.manifest.name,
description: skill.manifest.description,
body: skill.manifest.body,
scope: parseScopeId(skill.scopeId).kind ?? skill.scopeId,
scopeId: skill.scopeId,
status: skill.status,
version: skill.version,
createdBy: skill.createdBy,
pack: skill.pack,
files: (skill.manifest.files ?? []).map((file) => ({ path: file.path, executable: file.executable === true })),
requiredCapabilities: skill.manifest.requiredCapabilities,
grantedCapabilities: skill.grantedCapabilities,
createdAt: skill.createdAt,
updatedAt: skill.updatedAt,
editable: await app.canManageSkill(skill, principalId),
},
});
}
async function restoreSkill(ctx: ApiCtx): Promise<void> {
const b = (ctx.body ?? {}) as { principalId?: unknown };
const principalId =
ctx.capability?.actorId ?? ctx.actor?.p ?? (typeof b.principalId === "string" ? b.principalId : "");
if (!ctx.capability && !ctx.actor && ctx.secret) {
return sendJson(ctx.res, 401, { error: "capability_required" });
}
if (!principalId) return sendJson(ctx.res, 400, { error: "bad_request", message: "principalId required" });
const restored = await ctx.app.restoreOwnedSkill(ctx.params.id!, principalId);
return restored ? sendJson(ctx.res, 200, { ok: true }) : sendJson(ctx.res, 404, { error: "not_found" });
}
async function updateSkill(ctx: ApiCtx): Promise<void> {
const { res, app, body, capability } = ctx;
const id = ctx.params.id!;
const b = (body ?? {}) as { principalId?: unknown; description?: unknown; body?: unknown };
let principalId: string;
if (capability) {
principalId = capability.actorId;
} else {
if (typeof b.principalId !== "string" || !b.principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
principalId = b.principalId;
}
if (b.description !== undefined && typeof b.description !== "string") {
return sendJson(res, 400, { error: "bad_request", message: "description must be a string" });
}
if (b.body !== undefined && typeof b.body !== "string") {
return sendJson(res, 400, { error: "bad_request", message: "body must be a string" });
}
const patch: { description?: string; body?: string } = {};
if (typeof b.description === "string") patch.description = b.description;
if (typeof b.body === "string") patch.body = b.body;
const liveActor = capability ? livePersonCapability(capability) : true;
const updated = await app.updateOwnedSkill(id, principalId, patch, { liveActor });
if (updated === "trigger_blocked")
return sendJson(res, 403, { error: "forbidden", message: SHARED_SKILL_TRIGGER_REFUSAL });
if (!updated) return sendJson(res, 404, { error: "not_found", message: "no such skill, or it isn't yours to edit" });
return sendJson(res, 200, {
skill: {
id: updated.id,
name: updated.manifest.name,
description: updated.manifest.description,
body: updated.manifest.body,
status: updated.status,
version: updated.version,
},
});
}
async function deleteSkill(ctx: ApiCtx): Promise<void> {
const { res, app, body, capability } = ctx;
const id = ctx.params.id!;
const b = (body ?? {}) as { principalId?: unknown };
let principalId: string;
if (capability) {
principalId = capability.actorId;
} else {
if (typeof b.principalId !== "string" || !b.principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
principalId = b.principalId;
}
const liveActor = capability ? livePersonCapability(capability) : true;
const outcome = await app.deleteOwnedSkill({ principalId, id, liveActor });
if (outcome === "missing") return sendJson(res, 404, { error: "not_found", message: "no such skill" });
if (outcome === "trigger_blocked")
return sendJson(res, 403, { error: "forbidden", message: SHARED_SKILL_TRIGGER_REFUSAL });
if (outcome === "forbidden")
return sendJson(res, 403, { error: "forbidden", message: "that skill isn't yours to archive" });
return sendJson(res, 200, { ok: true });
}
async function createSkill(ctx: ApiCtx): Promise<void> {
const { res, app, body, capability } = ctx;
const b = (body ?? {}) as {
principalId?: unknown;
scopeId?: unknown;
name?: unknown;
description?: unknown;
body?: unknown;
};
const blocked = sharedSkillCreateBlock(capability);
if (blocked) return sendJson(res, 403, { error: "forbidden", message: blocked });
let principalId: string;
let homeScope: ScopeId | undefined;
if (capability) {
principalId = capability.actorId;
homeScope = capability.scopeId;
} else {
if (typeof b.principalId !== "string" || !b.principalId) {
return sendJson(res, 400, { error: "bad_request", message: "principalId required" });
}
principalId = b.principalId;
if (typeof b.scopeId === "string" && b.scopeId !== makeScopeId("personal", principalId)) {
if (!(await app.managesScope(principalId, b.scopeId as ScopeId))) {
return sendJson(res, 403, { error: "forbidden", message: "you cannot create a skill in that context" });
}
homeScope = b.scopeId as ScopeId;
}
}
if (homeScope && (parseScopeId(homeScope).kind === "org" || parseScopeId(homeScope).kind === "team")) {
return sendJson(res, 403, {
error: "forbidden",
message: "a skill cannot be created in an org or team scope — promote a published skill instead",
});
}
if (typeof b.name !== "string" || !b.name.trim()) {
return sendJson(res, 400, { error: "bad_request", message: "name required" });
}
if (typeof b.description !== "string" || !b.description.trim()) {
return sendJson(res, 400, { error: "bad_request", message: "description required" });
}
if (typeof b.body !== "string" || !b.body.trim()) {
return sendJson(res, 400, { error: "bad_request", message: "body required" });
}
const created = await app.createOwnedSkill({
principalId,
...(homeScope ? { homeScope } : {}),
name: b.name,
description: b.description,
body: b.body,
});
if (!created)
return sendJson(res, 409, {
error: "exists",
message: "a skill of that name already exists here — edit it instead",
});
return sendJson(res, 201, {
skill: {
id: created.id,
name: created.manifest.name,
description: created.manifest.description,
body: created.manifest.body,
status: created.status,
version: created.version,
},
});
}
async function createGrant(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
if (!isGrant(body)) return sendJson(res, 400, { error: "bad_request", message: "expected a Grant" });
try {
await app.grant(body);
return sendJson(res, 200, { ok: true });
} catch (e) {
return sendJson(res, 400, { error: "grant_failed", message: errMessage(e) });
}
}
async function revokeGrant(ctx: ApiCtx): Promise<void> {
const { res, app, body } = ctx;
const b = body as { ownerScopeId?: string; ref?: string; granteeScopeId?: string; revokedBy?: string };
if (!b.ownerScopeId || !b.ref || !b.granteeScopeId || typeof b.revokedBy !== "string" || !b.revokedBy) {
return sendJson(res, 400, {
error: "bad_request",
message: "ownerScopeId, ref, granteeScopeId, revokedBy required",
});
}
try {
await app.revokeGrant(b.ownerScopeId, b.ref, b.granteeScopeId, b.revokedBy);
return sendJson(res, 200, { ok: true });
} catch (e) {
return sendJson(res, 400, { error: "revoke_failed", message: errMessage(e) });
}
}
const SHARE_ERROR_STATUS: Record<string, number> = {
bad_request: 400,
not_found: 404,
forbidden: 403,
recipient_not_found: 404,
ambiguous_recipient: 409,
share_failed: 400,
};
export async function shareArtifact(ctx: ApiCtx): Promise<void> {
const { res, deps, body, capability } = ctx;
if (!capability)
return sendJson(res, 403, { error: "forbidden", message: "sharing requires an agent capability token" });
const b = (isObj(body) ? body : {}) as {
type?: unknown;
id?: unknown;
toScope?: unknown;
email?: unknown;
permission?: unknown;
move?: unknown;
};
if (typeof b.type !== "string" || !isArtifactType(b.type)) {
return sendJson(res, 400, { error: "bad_request", message: `type must be one of: ${ARTIFACT_TYPES.join(", ")}` });
}
if (typeof b.id !== "string" || !b.id.trim())
return sendJson(res, 400, { error: "bad_request", message: "id required" });
if (
b.email !== undefined &&
(typeof b.email !== "string" || b.toScope !== undefined || b.type !== "deploy" || b.move === true)
)
return sendJson(res, 400, {
error: "bad_request",
message: "email is only supported for app sharing, instead of toScope",
});
if (b.email === undefined && (typeof b.toScope !== "string" || !b.toScope.trim())) {
return sendJson(res, 400, {
error: "bad_request",
message: 'toScope required ("org", a scope id, or a teammate\'s name)',
});
}
if (b.permission !== undefined && b.permission !== "read" && b.permission !== "write") {
return sendJson(res, 400, { error: "bad_request", message: 'permission must be "read" or "write"' });
}
const result = await deps.control.shareArtifact(
{
type: b.type,
id: b.id,
...(typeof b.toScope === "string" ? splitToScope(b.toScope) : {}),
...(typeof b.email === "string" ? { email: b.email } : {}),
...(b.permission === "read" || b.permission === "write" ? { permission: b.permission } : {}),
...(b.move === true ? { move: true } : {}),
},
capability,
);
if (!result.ok) {
return sendJson(res, SHARE_ERROR_STATUS[result.code] ?? 400, {
error: result.code,
message: result.message,
...(result.candidates ? { candidates: result.candidates } : {}),
});
}
return sendJson(res, 200, {
ok: true,
verb: result.verb,
type: result.type,
id: result.id,
target: result.target,
permission: result.permission,
...(result.invitation ? { invitation: result.invitation } : {}),
});
}
async function getSurfaceConfig(ctx: ApiCtx): Promise<void> {
await ctx.deps.refreshModels?.();
const { res, deps } = ctx;
if (!deps.config) return sendJson(res, 404, { error: "not_found" });
const [webuiModels, baseModel, externalSlackParticipants, branding] = await Promise.all([
deps.config.getWebuiModelsDurable(orgScope(deps)),
deps.config.getBaseModelDurable(orgScope(deps)),
deps.config.getExternalSlackParticipantsDurable(orgScope(deps)),
resolveBranding(deps.config, orgScope(deps), deps.brandingDefault),
]);
const harnessId = deps.harnessId ?? "pi";
const managedKeys = deps.modelCredentials ? await deps.modelCredentials.availability() : null;
const configuredKeys = deps.providerKeys ?? managedKeys;
const providerStatus = harnessId === "pi" && managedKeys ? managedKeys : configuredKeys;
const catalog = managedKeys?.openrouter
? await selectableModelCatalog(deps.modelCredentialFetch)
: builtInModelCatalog();
const allowed = selectableCatalogForHarness(catalog, harnessId)
.filter((model) => modelOfferedInWebui(model.id))
.map((model) => model.id);
const configuredPicker = webuiModels?.filter((id) => modelSupportedByHarness(id, harnessId)) ?? [];
const resolvedBase = modelSupportedByHarness(baseModel ?? undefined, harnessId)
? baseModel!
: defaultModelForHarness(harnessId, deps.baseModelDefault);
const resolvedBranding = {
...(branding.orgName ? { orgName: branding.orgName } : {}),
...(branding.accent ? { accent: branding.accent } : {}),
...(branding.mark ? { mark: branding.mark } : {}),
...(branding.markUrl ? { markUrl: branding.markUrl } : {}),
...(branding.selfLabel ? { selfLabel: branding.selfLabel } : {}),
};
return sendJson(res, 200, {
webuiModels: webuiModels != null ? configuredPicker : allowed,
baseModel: resolvedBase,
harnessId,
...(providerStatus && {
modelProviderConfigured: Boolean(
providerStatus.anthropic ||
providerStatus.openai ||
providerStatus.openrouter ||
providerStatus.modelIds?.size ||
deps.harnessCarriedModelAuth,
),
}),
externalSlackParticipants,
...(Object.keys(resolvedBranding).length ? { branding: resolvedBranding } : {}),
});
}
async function runtimeTarget(ctx: ApiCtx): Promise<{ actorId: string; scope: ScopeId } | null> {
const actorId =
ctx.capability?.actorId ??
(isObj(ctx.body) && typeof ctx.body.principalId === "string"
? ctx.body.principalId
: ctx.url.searchParams.get("principalId"));
const scope =
ctx.capability?.scopeId ??
(isObj(ctx.body) && typeof ctx.body.scopeId === "string" ? ctx.body.scopeId : ctx.url.searchParams.get("scopeId"));
if (!actorId || !scope) return null;
const parsed = parseScopeId(scope);
if (parsed.kind === "personal" && parsed.ref === actorId) return { actorId, scope: scope as ScopeId };
if (ctx.capability && parsed.kind !== "org") return { actorId, scope: scope as ScopeId };
if (parsed.kind !== "org" && (await ctx.app.belongsToScope(actorId, scope as ScopeId)))
return { actorId, scope: scope as ScopeId };
return null;
}
async function getRuntimeConfig(ctx: ApiCtx): Promise<void> {
const account = ctx.url.searchParams.get("account");
if (account !== null && account !== "company") return sendJson(ctx.res, 400, { error: "invalid_account" });
if (!ctx.deps.config) return sendJson(ctx.res, 404, { error: "not_found" });
const target = await runtimeTarget(ctx);
if (!target) return sendJson(ctx.res, 403, { error: "forbidden" });
await ctx.deps.refreshModels?.();
return sendJson(
ctx.res,
200,
ctx.url.searchParams.get("account") === "company"
? await runtimeConfigBody(ctx, target.scope)
: await userRuntimeConfigBody(ctx, target.scope, target.actorId),
);
}
async function putRuntimeConfig(ctx: ApiCtx): Promise<void> {
if (!ctx.deps.config || !isObj(ctx.body)) return sendJson(ctx.res, 400, { error: "bad_request" });
if (ctx.capability && !livePersonCapability(ctx.capability))
return sendJson(ctx.res, 403, { error: "live_actor_required" });
const target = await runtimeTarget(ctx);
if (!target) return sendJson(ctx.res, 403, { error: "forbidden" });
await ctx.deps.refreshModels?.();
const config = ctx.deps.config;
if (ctx.body.inherit === true) await config.setRuntimeSelection(target.scope, null);
else if (ctx.body.keep === true) {
const runtime = await config.getRuntimeSelectionDurable(target.scope);
if (runtime) await config.acknowledgeRuntimeSelection(target.scope);
else {
const legacyModel = await config.getBaseModelOwnDurable(target.scope);
const fallback = runtimeFallback(ctx);
const approved = (await config.getApprovedHarnessesDurable()) ?? [fallback.harnessId];
if (
legacyModel &&
approved.includes(fallback.harnessId) &&
modelSupportedByHarness(legacyModel, fallback.harnessId) &&
(await webuiModelEnabled(ctx, legacyModel))
) {
await config.setRuntimeSelection(target.scope, { harnessId: fallback.harnessId, modelId: legacyModel });
}
}
} else {
const harnessId = ctx.body.harnessId;
const modelId = ctx.body.modelId;
const fallback = runtimeFallback(ctx);
const approved = (await config.getApprovedHarnessesDurable()) ?? [fallback.harnessId];
if (!isHarnessId(harnessId) || !approved.includes(harnessId))
return sendJson(ctx.res, 400, { error: "harness_not_approved" });
if (typeof modelId !== "string" || !modelSupportedByHarness(modelId, harnessId))
return sendJson(ctx.res, 400, { error: "model_not_supported" });
if (!(await webuiModelEnabled(ctx, modelId))) return sendJson(ctx.res, 400, { error: "model_not_enabled" });
const effortLevel = ctx.body.effortLevel ?? "auto";
if (typeof effortLevel !== "string" || !thinkingLevelsForHarness(harnessId, modelId).includes(effortLevel))
return sendJson(ctx.res, 400, { error: "effort_not_supported" });
const fastMode = ctx.body.fastMode ?? false;
if (typeof fastMode !== "boolean") return sendJson(ctx.res, 400, { error: "fast_mode_invalid" });
const choice = { harnessId, modelId, effortLevel, fastMode: fastMode && fastModeModelIds().includes(modelId) };
if ((await config.getModelAccountDurable(target.actorId)) !== "company") {
const available = await userRuntimeConfigBody(ctx, target.scope, target.actorId);
if (!available.modelsByHarness[harnessId]?.includes(modelId))
return sendJson(ctx.res, 400, { error: "account_runtime_unavailable" });
}
await config.setRuntimeSelection(target.scope, choice);
}
audit(ctx.deps, {
principalId: target.actorId,
action: "runtime-config.update",
resource: "runtime-config",
scopeLabel: target.scope,
});
return sendJson(ctx.res, 200, await userRuntimeConfigBody(ctx, target.scope, target.actorId));
}
async function getChannelHeaderPin(ctx: ApiCtx): Promise<void> {
if (!ctx.deps.config) return sendJson(ctx.res, 404, { error: "not_found" });
const target = await runtimeTarget(ctx);
if (!target) return sendJson(ctx.res, 403, { error: "forbidden" });
const [on, configured, def] = await Promise.all([
ctx.deps.config.getChannelHeaderPinDurable(target.scope),
ctx.deps.config.getChannelHeaderPinOverrideDurable(target.scope),
ctx.deps.config.getChannelHeaderPinDefaultDurable(),
]);
return sendJson(ctx.res, 200, { scopeId: target.scope, on, configured, default: def });
}
async function putChannelHeaderPin(ctx: ApiCtx): Promise<void> {
if (!ctx.deps.config || !isObj(ctx.body)) return sendJson(ctx.res, 400, { error: "bad_request" });
if (ctx.capability && !livePersonCapability(ctx.capability))
return sendJson(ctx.res, 403, { error: "live_actor_required" });
const target = await runtimeTarget(ctx);
if (!target) return sendJson(ctx.res, 403, { error: "forbidden" });
if (typeof ctx.body.on !== "boolean" && ctx.body.on !== null)
return sendJson(ctx.res, 400, {
error: "bad_request",
message: "expected { on: boolean | null } (null reverts to the org default)",
});
await ctx.deps.config.setChannelHeaderPin(target.scope, ctx.body.on);
audit(ctx.deps, {
principalId: target.actorId,
action: "channel-header-pin.update",
resource: "channel-header-pin",
scopeLabel: target.scope,
});
return sendJson(ctx.res, 200, {
scopeId: target.scope,
on: ctx.body.on ?? (await ctx.deps.config.getChannelHeaderPinDefaultDurable()),
configured: ctx.body.on,
});
}
function getSoul(ctx: ApiCtx): void {
const { res, app, url, capability } = ctx;
const scopeIdVal = capability?.scopeId ?? url.searchParams.get("scopeId");
if (!scopeIdVal) return sendJson(res, 400, { error: "bad_request", message: "scopeId required" });
return sendJson(res, 200, app.getSoul(scopeIdVal));
}
export async function postSoul(ctx: ApiCtx): Promise<void> {
const { res, app, body, capability } = ctx;
let scopeIdVal: string;
let content: string;
let actorId: string;
if (capability) {
const b = body as { content?: unknown };
if (typeof b.content !== "string")
return sendJson(res, 400, { error: "bad_request", message: "content (string) required" });
actorId = capability.actorId;
scopeIdVal = capability.scopeId;
content = b.content;
} else {
const b = body as { scopeId?: string; content?: string; actorId?: string };
if (typeof b.scopeId !== "string" || typeof b.content !== "string" || typeof b.actorId !== "string") {
return sendJson(res, 400, { error: "bad_request", message: "scopeId, content, actorId required" });
}
scopeIdVal = b.scopeId;
content = b.content;
actorId = b.actorId;
}
const allowSharedScope =
Boolean(capability) ||
(parseScopeId(scopeIdVal).kind !== "personal" && (await app.managesScope(actorId, scopeIdVal as ScopeId)));
try {
const version = await app.updateSoul(
scopeIdVal,
content,
actorId,
allowSharedScope ? { allowSharedScope: true } : undefined,
);
return sendJson(res, 200, { ok: true, version });
} catch (e) {
if (e instanceof SoulUpdateDeniedError)
return sendJson(res, 403, { error: "soul_update_denied", message: e.message });
return sendJson(res, 500, { error: "soul_update_failed", message: errMessage(e) });
}
}
export const surfaceRoutes: ReadonlyArray<Route<ApiCtx>> = [
...sessionSharingRoutes,
...suggestedActivityRoutes,
{ method: "POST", path: "/v1/session-cap", actor: "system", auth: "source", handle: sessionCapability },
{ method: "GET", path: "/v1/conversations", auth: "either", handle: listAgentConversations },
{ method: "GET", path: "/v1/conversations/:id", auth: "either", handle: getAgentConversation },
{ method: "POST", path: "/v1/conversations/:id", auth: "either", handle: patchAgentConversation },
{ method: "GET", path: "/v1/ui-state", auth: "source", handle: getUiState },
{ method: "PUT", path: "/v1/ui-state", auth: "source", handle: putUiState },
{ method: "GET", path: "/v1/apis", auth: "either", handle: listAgentApis },
{ method: "GET", path: "/v1/memory/self", auth: "either", handle: readOwnNotebook },
{ method: "POST", path: "/v1/memory/facts", auth: "either", handle: captureFacts },
{ method: "PATCH", path: "/v1/memory/facts", auth: "either", handle: editFacts },
{ method: "DELETE", path: "/v1/memory/facts", auth: "either", handle: deleteFacts },
{ method: "POST", path: "/v1/memory/search", auth: "either", allowedInStrict: true, handle: searchMemory },
{ method: "POST", path: "/v1/grants", actor: "system", auth: "source", handle: createGrant },
{ method: "POST", path: "/v1/grants/revoke", actor: "system", auth: "source", handle: revokeGrant },
{ method: "POST", path: "/v1/share", auth: "either", handle: shareArtifact },
{ method: "GET", path: "/v1/surface-config", auth: "source", handle: getSurfaceConfig },
{ method: "GET", path: "/v1/runtime-config", auth: "either", handle: getRuntimeConfig },
{ method: "PUT", path: "/v1/runtime-config", auth: "either", handle: putRuntimeConfig },
{ method: "GET", path: "/v1/channel-header-pin", auth: "either", handle: getChannelHeaderPin },
{ method: "PUT", path: "/v1/channel-header-pin", auth: "either", handle: putChannelHeaderPin },
{ method: "GET", path: "/v1/soul", auth: "either", handle: getSoul },
{ method: "POST", path: "/v1/soul", actor: "body.actorId", auth: "either", handle: postSoul },
...withActor("body.principalId", [
{ method: "POST", path: "/v1/sessions/:id/title", auth: "source", handle: regenerateSessionTitle },
{ method: "POST", path: "/v1/sessions/:id/fork", auth: "source", handle: forkSession },
{ method: "POST", path: "/v1/sessions/:id/detach", auth: "source", handle: detachSession },
{ method: "POST", path: "/v1/sessions/:id/goal/cancel", auth: "source", handle: cancelSessionGoal },
{ method: "POST", path: "/v1/files/upload", auth: "source", handle: uploadFile },
{ method: "POST", path: "/v1/sessions/:id", auth: "source", handle: patchSession },
{ method: "PATCH", path: "/v1/memory", auth: "source", handle: selfMemory },
{ method: "DELETE", path: "/v1/memory", auth: "source", handle: selfMemory },
{ method: "POST", path: "/v1/skills", auth: "either", handle: createSkill },
{ method: "PUT", path: "/v1/skills/:id", auth: "either", handle: updateSkill },
{ method: "DELETE", path: "/v1/skills/:id", auth: "either", handle: deleteSkill },
{ method: "POST", path: "/v1/skills/:id/restore", auth: "either", allowedInStrict: true, handle: restoreSkill },
]),
...withActor("query.principalId", [
{ method: "GET", path: "/v1/resources/search", auth: "source", handle: searchResources },
{ method: "GET", path: "/v1/sessions/search", auth: "source", handle: searchSessions },
{ method: "GET", path: "/v1/sessions", auth: "source", handle: listSessions },
{ method: "GET", path: "/v1/sessions/row", auth: "source", handle: getSessionRow },
{ method: "GET", path: "/v1/sessions/:id/children", auth: "source", handle: listSessionChildren },
{ method: "GET", path: "/v1/contexts", auth: "source", handle: listContexts },
{ method: "GET", path: "/v1/scope-resources", auth: "source", handle: listScopeResources },
{ method: "GET", path: "/v1/memory", auth: "source", handle: selfMemory },
{ method: "GET", path: "/v1/skills", auth: "source", handle: listSkills },
{ method: "GET", path: "/v1/skills/:id", auth: "either", handle: getSkillDetail },
]),
...withActor("query.viewer", [
{ method: "GET", path: "/v1/sessions/:id/approvals", auth: "source", handle: listSessionApprovals },
{ method: "GET", path: "/v1/sessions/:id/background", auth: "source", handle: getSessionBackground },
{
method: "GET",
path: "/v1/sessions/:id/background/:pid/output",
auth: "source",
handle: getSessionBackgroundOutput,
},
{ method: "GET", path: "/v1/sessions/:id/entries/:seq", auth: "source", handle: getSessionEntry },
{ method: "GET", path: "/v1/sessions/:id", auth: "source", handle: getSession },
{ method: "GET", path: "/v1/files/:id/content", auth: "either", handle: getFileContent },
{ method: "GET", path: "/v1/files", auth: "either", handle: listFiles },
]),
];