Multiplayer agent harness for work.
import { composeSoul } from "../resolution/resolution-service.ts";
import { createCurrentScopeMembers } from "../resolution/scope-membership.ts";
import { notifyDeploymentShared } from "../deploy/share-notice.ts";
import { deploymentShareScope } from "../deploy/email-access.ts";
import { workingSessionThreadRefs } from "../sessions/session-syscalls.ts";
import type { ParticipantPageQuery } from "../sessions/session-store.ts";
import type { PendingApprovalRecord, Session } from "../types.ts";
import { orgId as orgIdOf } from "../config.ts";
import { parseScopeId, scopeId } from "../types.ts";
import { fileArtifactId, artifactPath } from "../files/file-artifact-store.ts";
import { acquireLeaseWithin, entryWithinTenure, windowedTranscript } from "../sessions/session-store.ts";
import { createTranscriptSource } from "../sessions/transcript-source.ts";
import { cancelGoal, goalCancelledPayload, openGoal } from "../harness/goal.ts";
import { goalView } from "../runs/turn-stream.ts";
import { SEARCH_HIT_LIMIT, entrySearchText, searchSnippet, searchTerms } from "../sessions/entry-search.ts";
import { supportsProcessSessions } from "../sandbox/sandbox.ts";
import { ProcessSessionGoneError } from "../sandbox/exec-process-session.ts";
import { cronIsActive, cronTiedTo } from "../cron/cron-store.ts";
import { cronRef, deployRef, encodeRef, fileRef, parseRef, skillRef } from "../acl/resource-ref.ts";
import { samePerson } from "../directory/person.ts";
import { AdminError } from "../admin/admin-service.ts";
import { swallowAs } from "../util/errors.ts";
import { type ArtifactHome } from "./artifact-share.ts";
import { randomUUID } from "node:crypto";
import { isOpenScopeMember } from "../resolution/sharing-access.ts";
import { MAX_ATTACHMENT_BYTES, mimeFromName, safeAttachmentName } from "../core/attachments.ts";
import { projectIdFromGroupRef, projectScopeId } from "../projects/project-store.ts";
import type { App, AppDeps } from "./app-types.ts";
import {
SoulUpdateDeniedError,
SoulVersionConflictError,
toFileItem,
type ScopeDeployment,
type SessionPinView,
type SessionSearchHit,
} from "./app-types.ts";
import type { AppHelpers } from "./app-helpers.ts";
const MAX_SESSION_PINS = 50;
const MAX_PIN_TEXT_CHARS = 2000;
const PIN_PREVIEW_CHARS = 240;
const ENTRIES_PER_TURN_ESTIMATE = 40;
const TAIL_WINDOW_ENTRY_CAP = 2000;
interface TranscriptWindow {
tailTurns?: number;
sinceSeq?: number;
beforeSeq?: number;
}
function tailWindowLimit(window?: TranscriptWindow): number | undefined {
if (window?.tailTurns === undefined || window.sinceSeq !== undefined) return undefined;
return Math.min(window.tailTurns * ENTRIES_PER_TURN_ESTIMATE, TAIL_WINDOW_ENTRY_CAP);
}
function coversTailWindow(entries: readonly { type: string }[], tailTurns: number): boolean {
return entries.filter((e) => e.type === "user").length >= tailTurns;
}
const GOAL_CANCEL_LEASE_WAIT_MS = 30_000;
const MAX_LISTED_CHILDREN = 500;
export function createSessionMethods(
deps: AppDeps,
h: AppHelpers,
): Pick<
App,
| "getSession"
| "getSessionForViewer"
| "canViewSessionSnapshot"
| "getSessionEntryForViewer"
| "pinConversationItem"
| "listConversationPins"
| "unpinConversationItem"
| "listFilesForViewer"
| "uploadFileForViewer"
| "openFileForViewer"
| "listSessions"
| "listSessionPage"
| "sessionChildren"
| "sessionRow"
| "searchSessions"
| "sessionBackground"
| "readSessionBackgroundOutput"
| "listContexts"
| "listProjects"
| "createProject"
| "addProjectMember"
| "removeProjectMember"
| "renameProject"
| "setProjectSlackChannel"
| "listScopeResources"
| "managesScope"
| "isOpenScopeMember"
| "isCurrentSharedScopeMember"
| "currentScopeMembers"
| "membershipControlsScope"
| "authorizesCapabilityScope"
| "updateSession"
| "detachSession"
| "cancelSessionGoal"
| "regenerateTitle"
| "spawnSession"
| "discardSession"
| "forkSession"
| "grant"
| "revokeGrant"
| "promoteSkill"
| "belongsToScope"
| "canManageArtifactHome"
| "artifactGrantPermission"
| "getArtifactHome"
| "moveArtifactHome"
| "getSoul"
| "updateSoul"
> {
const {
sessionsForViewer,
sessionForViewer,
mayWriteSession,
managedProjectMembership,
filesForViewer,
canUseContext,
currentResourceScopesForViewer,
contextsFor,
projectsForViewer,
projectView,
reconcileProjectMember,
syncProjectChannelRoster,
approvalRecordIsCurrent,
principalCanAccessCurrentScope,
principalCanWriteScope,
canContinueOnWeb,
principalGitPermission,
principalCanManageScope,
membershipControlsScope,
authorizesCapabilityScope,
principalManagesArtifactHome,
artifactAuthor,
} = h;
const transcripts = createTranscriptSource(deps.sessions);
const pinView = (
rec: { id: string; text?: string; entrySeq?: number; addedBy: string; createdAt: number },
entry?: { payload: unknown },
): SessionPinView => {
const preview = entry ? entrySearchText(entry.payload) : null;
return {
id: rec.id,
...(rec.text ? { text: rec.text } : {}),
...(rec.entrySeq !== undefined ? { entrySeq: rec.entrySeq } : {}),
...(preview ? { preview: preview.slice(0, PIN_PREVIEW_CHARS) } : {}),
addedBy: rec.addedBy,
createdAt: rec.createdAt,
};
};
const decoratedPins = async (
pins: readonly { id: string; text?: string; entrySeq?: number; addedBy: string; createdAt: number }[],
visibleToReader: readonly { seq: number; payload: unknown }[],
resolveMissing: (seq: number) => Promise<{ payload: unknown } | undefined>,
): Promise<SessionPinView[]> => {
if (!pins.length) return [];
const bySeq = new Map(visibleToReader.map((e) => [e.seq, e]));
return Promise.all(
pins.map(async (p) => {
const entry =
p.entrySeq !== undefined ? (bySeq.get(p.entrySeq) ?? (await resolveMissing(p.entrySeq))) : undefined;
return pinView(p, entry);
}),
);
};
const storedEntryAt = async (sessionId: string, seq: number) => {
const entry = await deps.sessions.getEntry(sessionId, seq);
return entry;
};
const viewerStoredEntryAt = async (sessionId: string, principalId: string, seq: number) => {
const window = (await deps.sessions.participantWindowsOf(sessionId)).find((w) => w.principalId === principalId);
if (!window) return undefined;
const entry = await storedEntryAt(sessionId, seq);
return entry && entryWithinTenure(entry, window) ? entry : undefined;
};
const viewerEntryAt = async (sessionId: string, principalId: string, seq: number) => {
const latest = await deps.sessions.latestEntrySeq(sessionId);
if (seq > latest) return undefined;
let scoped = (await transcripts.forViewer(sessionId, principalId, { limit: latest - seq + 1 })).entries;
if (scoped.length && scoped[0]!.seq > seq) {
scoped = (await transcripts.forViewer(sessionId, principalId)).entries;
}
return scoped.find((e) => e.seq === seq) ?? (await viewerStoredEntryAt(sessionId, principalId, seq));
};
const renderedEntryAt = async (sessionId: string, seq: number) => {
const latest = await deps.sessions.latestEntrySeq(sessionId);
if (seq > latest) return undefined;
let scoped = (await transcripts.forRender(sessionId, { limit: latest - seq + 1 })).entries;
if (scoped.length && scoped[0]!.seq > seq) scoped = (await transcripts.forRender(sessionId)).entries;
return scoped.find((e) => e.seq === seq) ?? (await storedEntryAt(sessionId, seq));
};
const slackDmChannel = (session: { surface?: string; threadRef: string }): string | null => {
if (session.surface !== "slack" || !session.threadRef.startsWith("dm:")) return null;
return session.threadRef.split(":")[1] || null;
};
const mirrorNativePin = async (
session: { id: string; surface?: string; threadRef: string },
pinId: string,
entrySeq: number | undefined,
remove: boolean,
): Promise<void> => {
if (entrySeq === undefined || !deps.deliveries) return;
const channel = slackDmChannel(session);
if (!channel) return;
const entry = await renderedEntryAt(session.id, entrySeq);
const ts = (entry?.payload as { ts?: unknown } | undefined)?.ts;
if (typeof ts !== "string" || !ts) return;
await deps.deliveries.enqueue({
destination: { type: "slack", target: channel, pin: { messageTs: ts, ...(remove ? { remove: true } : {}) } },
text: "",
idempotencyKey: `session-pin:${pinId}:${remove ? "remove" : "add"}`,
});
};
/** Sessions whose title matches the query — the entry index only covers message text. */
const titleSearchHits = async (principalId: string, query: string, capped: number): Promise<SessionSearchHit[]> => {
const matches = await deps.sessions.searchSessionTitles(principalId, query, capped);
if (!matches.length) return [];
const allowed = new Map(
await Promise.all(
[...new Set(matches.map((s) => s.scopeId))].map(
async (scope) => [scope, (await managedProjectMembership(scope, principalId)) !== false] as const,
),
),
);
return matches
.filter((s) => allowed.get(s.scopeId))
.map((s) => ({
sessionId: s.id,
title: s.title ?? null,
scopeId: s.scopeId,
...(s.channelName ? { channelName: s.channelName } : {}),
...(s.surface ? { surface: s.surface } : {}),
seq: 0,
entryType: "title",
snippet: s.title ?? s.id,
createdAt: s.lastActivityAt ?? s.createdAt,
...(s.archived ? { archived: true } : {}),
}));
};
async function decorateSessions(principalId: string, all: Session[]): Promise<Session[]> {
const visibleById = new Map(all.map((session) => [session.id, session]));
const roots = all.map((session) => session.id);
const descendants = roots.length ? await deps.sessions.descendantsOf(roots) : [];
const descendantIds = new Set(descendants.map((d) => d.id));
const approvalRows: PendingApprovalRecord[] = [];
const approvalIds = [...visibleById.keys(), ...descendantIds];
const approvals = approvalIds.length
? await deps.approvals?.selectEntries({ where: { field: "sessionId", anyOfFold: approvalIds } })
: [];
for (const [, record] of approvals ?? []) {
const session = visibleById.get(record.sessionId);
if (
session
? await approvalRecordIsCurrent(record, session)
: descendantIds.has(record.sessionId) && (await approvalRecordIsCurrent(record))
)
approvalRows.push(record);
}
const waiting = new Set(approvalRows.filter((r) => r.blocksInput !== false).map((r) => r.sessionId));
const workingThreadRefs = await workingSessionThreadRefs(deps.sessions, deps.runs, waiting);
const sharedAccess = new Map<string, Promise<boolean>>(
all
.filter((s) => {
const { kind, ref } = parseScopeId(s.scopeId);
return kind === "group" && projectIdFromGroupRef(ref);
})
.map((s) => [s.scopeId, Promise.resolve(true)]),
);
const sessions = await Promise.all(
all
.filter(
(s) =>
s.hasEntries !== false ||
Boolean(s.title?.trim()) ||
workingThreadRefs.has(s.threadRef) ||
waiting.has(s.id),
)
.map(async ({ hasEntries: _hasEntries, ...s }) => ({
...s,
canContinue: await canContinueOnWeb(principalId, s, sharedAccess),
})),
);
const now = Date.now();
const jobCounts = new Map<string, number>();
for (const rec of (await deps.processes?.listLive(now)) ?? []) {
if (rec.kind !== "background" || !rec.sessionRef) continue;
jobCounts.set(rec.sessionRef, (jobCounts.get(rec.sessionRef) ?? 0) + 1);
}
const watchCounts = new Map<string, number>();
for (const m of (await deps.monitors?.enabled()) ?? []) {
if (m.expiresAt <= now) continue;
watchCounts.set(m.threadRef, (watchCounts.get(m.threadRef) ?? 0) + 1);
}
const cronCounts = new Map<string, number>();
for (const c of await deps.crons.list()) {
if (!cronIsActive(c)) continue;
for (const ref of new Set([c.destination?.target, c.sessionRef])) {
if (ref) cronCounts.set(ref, (cronCounts.get(ref) ?? 0) + 1);
}
}
const working = sessions.filter((s) => workingThreadRefs.has(s.threadRef));
const idleChildren = sessions.filter(
(s) => s.parentSessionId && !workingThreadRefs.has(s.threadRef) && !waiting.has(s.id),
);
const [latestRuns, sessionGoals] = await Promise.all([
deps.runs.latestForThreads([...working, ...idleChildren].map((s) => s.threadRef)),
deps.sessions.goals(working.map((s) => s.id)),
]);
const failedChildren = new Set<string>();
for (const s of idleChildren) {
const run = latestRuns.get(s.threadRef);
if (run?.status === "failed" || run?.result?.status === "failed") failedChildren.add(s.id);
}
const goals = new Map<
string,
{ objective: string; activeMs: number; runningSince?: number; floor?: Record<string, number> }
>();
for (const s of working) {
const goal = openGoal(sessionGoals.get(s.id));
if (!goal) continue;
const runningSince = latestRuns.get(s.threadRef)?.startedAt ?? undefined;
if (goal.status === "active")
goals.set(s.id, {
objective: goal.objective,
activeMs: goal.activeMs ?? 0,
...(runningSince ? { runningSince: Math.max(runningSince, goal.activeSince ?? goal.createdAt) } : {}),
...(goal.floor ? { floor: { ...goal.floor } } : {}),
});
}
const subagents = new Map<string, { running: number; waiting: number }>();
for (const d of descendants) {
const isWaiting = waiting.has(d.id);
if (!isWaiting && !workingThreadRefs.has(d.threadRef)) continue;
const counts = subagents.get(d.rootId) ?? { running: 0, waiting: 0 };
counts[isWaiting ? "waiting" : "running"]++;
subagents.set(d.rootId, counts);
}
if (
subagents.size === 0 &&
workingThreadRefs.size === 0 &&
waiting.size === 0 &&
failedChildren.size === 0 &&
jobCounts.size === 0 &&
watchCounts.size === 0 &&
cronCounts.size === 0
)
return sessions;
return sessions.map((s) => ({
...s,
...(workingThreadRefs.has(s.threadRef) ? { working: true } : {}),
...(waiting.has(s.id) ? { awaitingInput: true } : {}),
...(failedChildren.has(s.id) ? { lastTurnFailed: true } : {}),
...(jobCounts.has(s.threadRef) ? { backgroundJobs: jobCounts.get(s.threadRef)! } : {}),
...(watchCounts.has(s.threadRef) ? { watches: watchCounts.get(s.threadRef)! } : {}),
...(cronCounts.has(s.threadRef) ? { crons: cronCounts.get(s.threadRef)! } : {}),
...(goals.has(s.id) ? { goal: goals.get(s.id)! } : {}),
...(subagents.has(s.id) ? { subagents: subagents.get(s.id)! } : {}),
}));
}
return {
async getSession(sessionId, window) {
const session = await deps.sessions.get(sessionId);
if (!session) return null;
let limit = tailWindowLimit(window);
const [initialRead, pinRecords] = await Promise.all([
transcripts.forRender(sessionId, { limit, beforeSeq: window?.beforeSeq, sinceSeq: window?.sinceSeq }),
deps.sessions.listPins(sessionId),
]);
let read = initialRead;
let all = read.entries;
while (limit !== undefined && read.earlier > 0 && !coversTailWindow(all, window!.tailTurns!)) {
limit *= 2;
read = await transcripts.forRender(sessionId, { limit, beforeSeq: window?.beforeSeq });
all = read.entries;
}
const w = windowedTranscript(all, window);
const earlier = w.earlier + read.earlier;
const pins = await decoratedPins(pinRecords, all, (seq) => storedEntryAt(sessionId, seq));
return {
session,
entries: w.entries,
...(earlier > 0 ? { earlierEntries: earlier } : {}),
...(pins.length ? { pins } : {}),
};
},
async canViewSessionSnapshot(sessionId, principalId, visibility) {
if (
!visibility ||
![visibility.minSeq, visibility.maxSeq, visibility.minCreatedAt, visibility.maxCreatedAt].every(
Number.isFinite,
) ||
visibility.minSeq > visibility.maxSeq ||
visibility.minCreatedAt > visibility.maxCreatedAt
)
return false;
if (!(await sessionForViewer(sessionId, principalId))) return false;
const window = (await deps.sessions.participantWindowsOf(sessionId)).find((w) => w.principalId === principalId);
return (
!!window &&
entryWithinTenure({ seq: visibility.minSeq, createdAt: visibility.minCreatedAt }, window) &&
entryWithinTenure({ seq: visibility.maxSeq, createdAt: visibility.maxCreatedAt }, window)
);
},
async getSessionForViewer(sessionId, principalId, window) {
const found = await sessionForViewer(sessionId, principalId);
if (!found) return null;
const session = { ...found, canContinue: await canContinueOnWeb(principalId, found) };
let limit = tailWindowLimit(window);
const [initialRead, pinRecords, goals, latestRuns] = await Promise.all([
transcripts.forViewer(sessionId, principalId, {
limit,
beforeSeq: window?.beforeSeq,
sinceSeq: window?.sinceSeq,
}),
deps.sessions.listPins(sessionId),
deps.sessions.goals([sessionId]),
window?.beforeSeq === undefined ? deps.runs.latestForThreads([found.threadRef]) : undefined,
]);
const goal = openGoal(goals.get(sessionId));
const runtime = latestRuns?.get(found.threadRef)?.result?.runtime;
let read = initialRead;
let visible = read.entries;
while (limit !== undefined && read.earlier > 0 && !coversTailWindow(visible, window!.tailTurns!)) {
limit *= 2;
read = await transcripts.forViewer(sessionId, principalId, { limit, beforeSeq: window?.beforeSeq });
visible = read.entries;
}
const w = windowedTranscript(visible, window);
const earlier = w.earlier + read.earlier;
const pins = await decoratedPins(pinRecords, visible, (seq) => viewerStoredEntryAt(sessionId, principalId, seq));
return {
session,
entries: w.entries,
...(earlier > 0 ? { earlierEntries: earlier } : {}),
...(pins.length ? { pins } : {}),
...(goal ? { goal: goalView(goal) } : {}),
...(runtime ? { runtime } : {}),
};
},
async pinConversationItem(threadRef, addedBy, pin) {
const session = await deps.sessions.getByThread(threadRef);
if (!session) return { error: "not_found" };
const text = pin.text?.trim().slice(0, MAX_PIN_TEXT_CHARS);
if (pin.entrySeq !== undefined) {
const exists = (await viewerEntryAt(session.id, addedBy, pin.entrySeq)) !== undefined;
if (!exists) return { error: "bad_entry" };
}
const rec = await deps.sessions.addPin(
session.id,
{
...(text ? { text } : {}),
...(pin.entrySeq !== undefined ? { entrySeq: pin.entrySeq } : {}),
addedBy,
},
MAX_SESSION_PINS,
);
if (!rec) return (await deps.sessions.get(session.id)) ? { error: "limit" } : { error: "not_found" };
await mirrorNativePin(session, rec.id, rec.entrySeq, false);
const pinned = rec.entrySeq !== undefined ? await viewerEntryAt(session.id, addedBy, rec.entrySeq) : undefined;
return { pin: pinView(rec, pinned) };
},
async listConversationPins(threadRef, reader) {
const session = await deps.sessions.getByThread(threadRef);
if (!session) return null;
const pinRecords = await deps.sessions.listPins(session.id);
if (!pinRecords.length) return [];
const seqs = pinRecords.filter((p) => p.entrySeq !== undefined).map((p) => p.entrySeq!);
const resolveMissing = (seq: number) => viewerStoredEntryAt(session.id, reader, seq);
if (!seqs.length) return decoratedPins(pinRecords, [], resolveMissing);
const latest = await deps.sessions.latestEntrySeq(session.id);
const minSeq = Math.min(...seqs);
const visible = (await transcripts.forViewer(session.id, reader, { limit: Math.max(1, latest - minSeq + 1) }))
.entries;
return decoratedPins(pinRecords, visible, resolveMissing);
},
async unpinConversationItem(threadRef, pinId) {
const session = await deps.sessions.getByThread(threadRef);
if (!session) return null;
const rec = (await deps.sessions.listPins(session.id)).find((p) => p.id === pinId);
const removed = await deps.sessions.removePin(session.id, pinId);
if (removed && rec) await mirrorNativePin(session, rec.id, rec.entrySeq, true);
return removed;
},
async getSessionEntryForViewer(sessionId, principalId, seq) {
const session = await sessionForViewer(sessionId, principalId);
if (!session) return null;
const entry = await viewerEntryAt(sessionId, principalId, seq);
return entry ? { entry } : null;
},
listFilesForViewer(principalId, opts, inScope) {
return filesForViewer(principalId, opts, inScope);
},
async uploadFileForViewer(principalId, input) {
const ownerScopeId = scopeId("personal", principalId);
const createdInScope = input.scopeId ?? ownerScopeId;
if (!(await canUseContext(principalId, createdInScope))) return null;
const name = safeAttachmentName(input.name);
const mimetype = (input.mimetype ?? mimeFromName(name)).split(";")[0]!.trim().toLowerCase() || mimeFromName(name);
const id = fileArtifactId(`upload:${principalId}:${createdInScope}:${Date.now()}:${randomUUID()}`, "in", 0);
const path = artifactPath(id, name);
const { artifact } = await deps.files.put({
id,
ownerScopeId,
createdBy: principalId,
name,
path,
mimetype,
data: input.data,
direction: "in",
createdInScope,
maxBytes: MAX_ATTACHMENT_BYTES,
});
if (createdInScope !== ownerScopeId) {
await deps.acl.grant({
ownerScopeId,
ref: artifact.id,
granteeScopeId: createdInScope,
permission: "read",
grantedBy: principalId,
});
}
deps.auditLog?.record({
at: Date.now(),
principalId,
action: "file.upload",
resource: path,
scopeLabel: createdInScope,
});
return toFileItem(artifact);
},
async openFileForViewer(id, principalId) {
const art = await deps.files.get(id);
if (!art) return null;
const myScopes = await currentResourceScopesForViewer(principalId);
let allowed = myScopes.includes(art.ownerScopeId);
if (!allowed) {
const grants = await deps.acl.grantsFor(art.ownerScopeId, art.id);
allowed = grants.some((g) => myScopes.includes(g.granteeScopeId));
}
if (!allowed) return null;
const opened = await deps.files.open(id);
if (!opened) return null;
return { name: art.name, mimetype: art.mimetype, sizeBytes: opened.sizeBytes, stream: opened.stream };
},
async listSessions(principalId) {
return decorateSessions(principalId, await sessionsForViewer(principalId));
},
async listSessionPage(principalId, query) {
const filter: ParticipantPageQuery = {
limit: Math.max(1, Math.min(query.limit, 200)),
archived: query.status === "archived",
...(query.before ? { before: query.before } : {}),
...(query.surface ? { surface: query.surface } : {}),
...(query.scopeId ? { scopeId: query.scopeId } : {}),
...(query.titleQuery ? { titleQuery: query.titleQuery } : {}),
};
if (query.status === "waiting") {
const pending = ((await deps.approvals?.all()) ?? []).filter((record) => record.blocksInput !== false);
filter.sessionIds = [...new Set(pending.map((record) => record.sessionId))];
}
const firstPage = !query.before && query.status !== "archived";
const [page, pinned, archived] = await Promise.all([
deps.sessions.listParticipantPage(principalId, {
...filter,
...(query.status === "archived" ? {} : { pinned: false }),
}),
firstPage ? deps.sessions.listParticipantPage(principalId, { ...filter, pinned: true, limit: 200 }) : null,
firstPage ? deps.sessions.listParticipantPage(principalId, { ...filter, archived: true, limit: 1 }) : null,
]);
const viewable = async (rows: Session[]) => {
const allowed = await Promise.all(
rows.map(async (row) => (await managedProjectMembership(row.scopeId, principalId)) !== false),
);
return rows.filter((_, index) => allowed[index]);
};
const rows = await viewable([...(pinned?.sessions ?? []), ...page.sessions]);
let decorated = await decorateSessions(principalId, rows);
if (query.status === "waiting") decorated = decorated.filter((s) => s.awaitingInput);
const pinnedIds = new Set(pinned?.sessions.map((s) => s.id) ?? []);
return {
sessions: decorated.filter((s) => !pinnedIds.has(s.id)),
...(pinned ? { pinned: decorated.filter((s) => pinnedIds.has(s.id)) } : {}),
...(archived ? { hasArchived: archived.sessions.length > 0 } : {}),
next: page.next,
};
},
async sessionChildren(principalId, sessionId) {
const root = await sessionForViewer(sessionId, principalId);
if (!root) return null;
const children = await deps.sessions.listDescendantsForParticipant(root.id, principalId, MAX_LISTED_CHILDREN);
return decorateSessions(principalId, children);
},
async sessionRow(principalId, ref) {
const id = ref.id ?? (ref.threadRef ? (await deps.sessions.getByThread(ref.threadRef))?.id : undefined);
if (!id) return null;
const session = await sessionForViewer(id, principalId);
if (!session) return null;
const { spawnMeta: _spawnMeta, clientTools: _clientTools, ...row } = session;
const [decorated] = await decorateSessions(principalId, [row]);
return decorated ?? null;
},
async searchSessions(principalId, query, limit = SEARCH_HIT_LIMIT): Promise<SessionSearchHit[]> {
const capped = Math.max(1, Math.min(Math.floor(limit), 100));
const hits = await deps.sessions.searchEntries(principalId, query, capped);
const titleHits = await titleSearchHits(principalId, query, capped);
if (!hits.length) return titleHits;
const allowed = new Map(
await Promise.all(
[...new Set(hits.map((hit) => hit.scopeId))].map(
async (scope) => [scope, (await managedProjectMembership(scope, principalId)) !== false] as const,
),
),
);
const terms = searchTerms(query);
const entryHits: SessionSearchHit[] = hits.flatMap((hit) => {
if (!allowed.get(hit.scopeId)) return [];
const session = hit;
return [
{
sessionId: hit.sessionId,
title: session.title ?? null,
scopeId: session.scopeId,
...(session.channelName ? { channelName: session.channelName } : {}),
...(session.surface ? { surface: session.surface } : {}),
seq: hit.seq,
entryType: hit.type,
...(hit.author ? { author: hit.author } : {}),
snippet: searchSnippet(hit.text, terms),
createdAt: hit.createdAt,
...(session.archived ? { archived: true } : {}),
},
];
});
const entryHitSessions = new Set(entryHits.map((hit) => hit.sessionId));
return [...titleHits.filter((hit) => !entryHitSessions.has(hit.sessionId)), ...entryHits].slice(0, capped);
},
async sessionBackground(sessionId, viewer) {
const session = await sessionForViewer(sessionId, viewer);
if (!session) return null;
const now = Date.now();
const jobs = ((await deps.processes?.listLive(now)) ?? [])
.filter((r) => r.kind === "background" && r.sessionRef === session.threadRef)
.sort((a, b) => b.startedAt - a.startedAt)
.map((r) => ({
processId: r.processId,
command: r.command,
...(r.purpose ? { purpose: r.purpose } : {}),
startedAt: r.startedAt,
expiresAt: r.expiresAt,
}));
const watches = ((await deps.monitors?.enabled()) ?? [])
.filter((m) => m.threadRef === session.threadRef && m.expiresAt > now)
.sort((a, b) => b.createdAt - a.createdAt)
.map((m) => ({
id: m.id,
processId: m.processId,
command: m.command,
...(m.pattern !== undefined ? { pattern: m.pattern } : {}),
...(m.instructions !== undefined ? { instructions: m.instructions } : {}),
createdAt: m.createdAt,
expiresAt: m.expiresAt,
...(m.lastFiredAt !== undefined ? { lastFiredAt: m.lastFiredAt } : {}),
}));
const crons = await Promise.all(
(await deps.crons.list())
.filter((c) => cronIsActive(c) && cronTiedTo(c, session.threadRef))
.sort((a, b) => b.createdAt - a.createdAt)
.map(async (c) => {
const last = (await deps.crons.listFires(c.id, { limit: 1 })).runs[0];
return {
id: c.id,
...(c.title !== undefined ? { title: c.title } : {}),
...(c.nextFireAt !== undefined ? { nextFireAt: c.nextFireAt } : {}),
...(last ? { lastFire: { firedAt: last.firedAt, ...(last.status ? { status: last.status } : {}) } } : {}),
};
}),
);
return { jobs, watches, crons };
},
async readSessionBackgroundOutput(sessionId, processId, viewer, sinceCursor) {
const session = await sessionForViewer(sessionId, viewer);
if (!session || !deps.processes || !deps.sandbox || !supportsProcessSessions(deps.sandbox)) return null;
const sandbox = deps.sandbox;
const rec = await deps.processes.get(processId);
if (!rec || rec.kind !== "background" || rec.sessionRef !== session.threadRef) return null;
const handle = await sandbox.provision(
[{ scopeId: rec.scopeId, mode: "rw", mountPath: "" }],
rec.sandboxId ? { sandboxId: rec.sandboxId } : undefined,
);
try {
const read = await sandbox.readProcess(handle, processId, { sinceCursor, maxBytes: 65_536, waitMs: 0 });
return {
chunk: read.chunks,
cursor: read.cursor,
state: read.status.state,
...(read.status.state === "exited" ? { exitCode: read.status.code } : {}),
};
} catch (e) {
if (e instanceof ProcessSessionGoneError) return { chunk: "", cursor: sinceCursor, state: "exited" };
throw e;
} finally {
await sandbox
.teardown(handle, { keepWarm: true })
.catch(swallowAs("app sessions: release process sandbox", undefined));
}
},
listContexts(principalId) {
return contextsFor(principalId);
},
async listProjects(principalId) {
return projectsForViewer(principalId);
},
async createProject(principalId, name) {
const principal = deps.identity.classify(principalId);
if (!deps.projects || !deps.identity.isInternal(principal) || !name.trim()) return null;
const project = await deps.projects.create({ name, ownerId: principalId });
deps.auditLog.record({
at: Date.now(),
principalId,
action: "project.create",
resource: project.id,
scopeLabel: projectScopeId(project.id),
});
return projectView(project);
},
async addProjectMember(id, principalId, memberId) {
if (!deps.projects) return { status: "not_found" };
if (!deps.identity.isInternal(deps.identity.classify(principalId))) return { status: "forbidden" };
const existing = await deps.projects.get(id);
if (!existing || existing.orgId !== orgIdOf()) return { status: "not_found" };
const directoryMember = await h.directoryMember(memberId);
const principal = deps.identity.classify(memberId);
if (!directoryMember || directoryMember.type !== "internal" || !deps.identity.isInternal(principal))
return { status: "invalid_member" };
const result = await deps.projects.addMember(id, principalId, memberId, async ({ project, changed }) => {
if (changed)
deps.auditLog.record({
at: Date.now(),
principalId,
action: "project.member.add",
resource: memberId,
scopeLabel: projectScopeId(project.id),
});
await reconcileProjectMember(project, memberId, true);
});
if (result.status === "ok") {
return { ...result, project: await projectView(result.project) };
}
return result;
},
async removeProjectMember(id, principalId, memberId) {
if (!deps.projects) return { status: "not_found" };
if (!deps.identity.isInternal(deps.identity.classify(principalId))) return { status: "forbidden" };
const existing = await deps.projects.get(id);
if (!existing || existing.orgId !== orgIdOf()) return { status: "not_found" };
const result = await deps.projects.removeMember(id, principalId, memberId, async ({ project, changed }) => {
if (changed)
deps.auditLog.record({
at: Date.now(),
principalId,
action: "project.member.remove",
resource: memberId,
scopeLabel: projectScopeId(project.id),
});
await reconcileProjectMember(project, memberId, false);
});
if (result.status === "ok") {
return { ...result, project: await projectView(result.project) };
}
return result;
},
async setProjectSlackChannel(id, principalId, channel) {
if (!deps.projects) return { status: "not_found" };
if (!deps.identity.isInternal(deps.identity.classify(principalId))) return { status: "forbidden" };
const existing = await deps.projects.get(id);
if (!existing || existing.orgId !== orgIdOf()) return { status: "not_found" };
let link: { channelId: string; channelName: string } | null = null;
if (channel !== null) {
const wanted = channel.trim().replace(/^#/, "");
if (!wanted) return { status: "invalid_channel" };
const findChannel = async () => {
const reachable = await deps.directory.listChannelsFor(principalId).catch(() => []);
return (
reachable.find((c) => c.channelId === wanted) ??
reachable.find((c) => c.name.toLowerCase() === wanted.toLowerCase())
);
};
let match = await findChannel();
if (!match) {
// The synced directory may not have caught up with a just-created channel;
// ask the surface for a fresh sync and look once more before giving up.
await h.refreshSurfaceDirectory().catch(() => undefined);
match = await findChannel();
}
if (!match) return { status: "invalid_channel" };
const channelScope = scopeId("channel", match.channelId);
if (await deps.sessions.scopeHasSessions(channelScope)) return { status: "channel_in_use" };
link = { channelId: match.channelId, channelName: match.name };
}
const prevDerived = existing.channelMemberIds ?? [];
const manual = new Set([existing.ownerId, ...existing.memberIds]);
const result = await deps.projects.setSlackChannel(id, principalId, link, async ({ project, changed }) => {
if (changed)
deps.auditLog.record({
at: Date.now(),
principalId,
action: link ? "project.slack_channel.link" : "project.slack_channel.unlink",
resource: link?.channelId ?? existing.slackChannel?.channelId ?? "",
scopeLabel: projectScopeId(project.id),
});
if (!link) {
for (const m of prevDerived) {
if (manual.has(m)) continue;
deps.auditLog.record({
at: Date.now(),
principalId,
action: "project.member.remove",
resource: m,
scopeLabel: projectScopeId(project.id),
});
await reconcileProjectMember(project, m, false);
}
}
});
if (result.status !== "ok") return result;
if (link) await syncProjectChannelRoster(result.project, principalId);
const fresh = (await deps.projects.get(id)) ?? result.project;
return { ...result, project: await projectView(fresh) };
},
async renameProject(id, principalId, name) {
if (!deps.projects) return { status: "not_found" };
if (!deps.identity.isInternal(deps.identity.classify(principalId))) return { status: "forbidden" };
const existing = await deps.projects.get(id);
if (!existing || existing.orgId !== orgIdOf()) return { status: "not_found" };
const result = await deps.projects.rename(id, principalId, name, async ({ project, changed }) => {
if (changed)
deps.auditLog.record({
at: Date.now(),
principalId,
action: "project.rename",
resource: project.id,
scopeLabel: projectScopeId(project.id),
});
});
if (result.status === "ok") {
return { ...result, project: await projectView(result.project) };
}
return result;
},
async listScopeResources(principalId, scope) {
if (!(await principalCanAccessCurrentScope(principalId, scope))) return null;
const [page, allCrons, allWebhooks, allDeployments, allSkills] = await Promise.all([
filesForViewer(principalId, undefined, scope),
deps.crons.list(),
deps.webhooks.list(),
deps.deploy.listDeployments(),
deps.skills.list(),
]);
const files = [...page.owned, ...page.shared];
let cursor = page.nextCursor;
while (cursor) {
const next = await filesForViewer(principalId, { limit: 200, cursor }, scope);
files.push(...next.owned, ...next.shared);
cursor = next.nextCursor;
}
files.sort((a, b) => b.createdAt - a.createdAt);
const deployments = (
await Promise.all(
allDeployments
.filter((d) => d.createdInScope === scope || d.ownerScopeId === scope)
.map(async (d): Promise<ScopeDeployment | null> => {
const permission = await principalGitPermission(d, principalId);
return permission
? {
id: d.id,
name: d.displayName ?? d.name ?? d.id,
status: d.status,
permission,
currentVersion: d.currentVersion,
}
: null;
}),
)
).filter((d): d is ScopeDeployment => d != null);
const skills = allSkills
.filter((s) => s.scopeId === scope)
.map((s) => ({ id: s.id, name: s.manifest.name, description: s.manifest.description, status: s.status }));
return {
files,
webhooks: allWebhooks.filter((w) => w.ownerScopeId === scope),
crons: allCrons.filter((c) => c.ownerScopeId === scope),
deployments,
skills,
manageable: await principalCanManageScope(principalId, scope),
};
},
managesScope(principalId, scope) {
return principalCanManageScope(principalId, scope);
},
currentScopeMembers: createCurrentScopeMembers(
{
managedGroups: deps.projects,
directory: deps.directory,
identity: deps.identity,
},
true,
),
isCurrentSharedScopeMember(principalId, scope) {
const { kind } = parseScopeId(scope);
return kind === "channel" || kind === "group"
? principalCanWriteScope(principalId, scope)
: Promise.resolve(false);
},
isOpenScopeMember(principalId, scope) {
return isOpenScopeMember({
actorId: principalId,
scope,
config: deps.config,
isCurrentSharedScopeMember: principalCanWriteScope,
});
},
membershipControlsScope(scope) {
return membershipControlsScope(scope);
},
async authorizesCapabilityScope(claims) {
return authorizesCapabilityScope(claims);
},
async updateSession(sessionId, principalId, patch) {
const session = await sessionForViewer(sessionId, principalId);
if (!session) return null;
await deps.sessions.updateParticipantView(sessionId, principalId, patch);
const updated = await sessionForViewer(sessionId, principalId);
return updated && { ...updated, canContinue: await canContinueOnWeb(principalId, updated) };
},
async detachSession(sessionId, principalId) {
const detach = async () => {
const session = await sessionForViewer(sessionId, principalId);
if (!session?.parentSessionId || !(await principalCanWriteScope(principalId, session.scopeId))) return null;
await deps.sessions.setParentSession(sessionId, null);
return { detached: true as const };
};
return deps.advisoryLock
? deps.advisoryLock.withLock("session-tree-admission", () =>
deps.advisoryLock!.withLock("session-run-admission", detach),
)
: detach();
},
async cancelSessionGoal(sessionId, principalId) {
const session = await sessionForViewer(sessionId, principalId);
if (!session || !(await mayWriteSession(principalId, session))) return null;
const currentGoal = async () => openGoal((await deps.sessions.goals([session.id])).get(session.id));
const before = await currentGoal();
if (!before) return { cancelled: false as const, reason: "no_open_goal" as const };
let { lease } = await deps.sessions.acquireLease(session.id, "backfill");
if (!lease) {
if (before.status === "active")
for (const run of await deps.runs.inFlightForThread(session.threadRef))
if (run.status === "running")
await deps.signals?.send(run.id, { kind: "abort", reason: "because its goal was cancelled" });
({ lease } = await acquireLeaseWithin(deps.sessions, session.id, "backfill", GOAL_CANCEL_LEASE_WAIT_MS));
}
if (!lease) return { cancelled: false as const, reason: "busy" as const };
try {
const goal = await currentGoal();
if (!goal) return { cancelled: false as const, reason: "no_open_goal" as const };
cancelGoal(goal, "Cancelled from the goal bar.");
await deps.sessions.setGoal(lease, goal, [
{ type: "system", payload: goalCancelledPayload(goal, principalId), scopeLabel: session.scopeId },
]);
return { cancelled: true as const };
} finally {
await deps.sessions.releaseLease(lease);
}
},
async regenerateTitle(sessionId, principalId) {
const session = await sessionForViewer(sessionId, principalId);
if (!session) return null;
const parsed = parseScopeId(session.scopeId);
const projectMembers = parsed.kind === "group" ? await deps.projects?.members(parsed.ref) : undefined;
return deps.orchestrator.regenerateTitle(sessionId, principalId, projectMembers);
},
async forkSession(sessionId, principalId, opts) {
if (!(await sessionForViewer(sessionId, principalId))) return null;
const source = await deps.sessions.get(sessionId);
if (!source) return null;
const parsed = parseScopeId(source.scopeId);
const fork = async (projectMembers?: readonly string[]) => {
let visible = (await transcripts.forViewer(sessionId, principalId)).entries;
if (projectMembers?.length) {
const views = await Promise.all(
projectMembers.map(async (memberId) => (await transcripts.forViewer(sessionId, memberId)).entries),
);
const common = new Set(views[0]!.map((entry) => entry.seq));
for (const view of views.slice(1)) {
const seqs = new Set(view.map((entry) => entry.seq));
for (const seq of common) if (!seqs.has(seq)) common.delete(seq);
}
visible = visible.filter((entry) => common.has(entry.seq));
}
const upToSeq = opts?.upToSeq;
const copied = upToSeq === undefined ? visible : visible.filter((entry) => entry.seq <= upToSeq);
const threadRef = `web:${principalId}:${randomUUID()}`;
const forked = await deps.sessions.getOrCreateByThread(
threadRef,
source.type,
source.scopeId,
source.channelName,
"web",
);
await Promise.all(
(projectMembers ?? [principalId]).map((memberId) => deps.sessions.addParticipant(forked.id, memberId)),
);
const { lease } = await deps.sessions.acquireLease(forked.id, "fork");
if (!lease) throw new Error(`fork: could not lease fresh session ${forked.id}`);
let forkBoundarySeq: number | null;
try {
const copiedEntries = await deps.sessions.appendMany(
lease,
copied.map((entry) => ({ type: entry.type, payload: entry.payload, scopeLabel: entry.scopeLabel })),
);
forkBoundarySeq = copiedEntries.at(-1)?.seq ?? null;
} finally {
await deps.sessions.releaseLease(lease);
}
if (forkBoundarySeq !== null) {
await deps.sessions.updateForkProvenance(forked.id, {
forkedFrom: { sessionId, title: source.title ?? null },
forkBoundarySeq,
});
}
const sourceTitle = source.title?.trim();
if (sourceTitle && projectMembers === undefined)
await deps.sessions.updateTitle(forked.id, `${sourceTitle} (fork)`);
deps.auditLog.record({
at: Date.now(),
principalId,
action: "session.fork",
resource: sessionId,
scopeLabel: source.scopeId,
});
const stored = (await deps.sessions.get(forked.id)) ?? forked;
const session = { ...stored, canContinue: await canContinueOnWeb(principalId, stored) };
return { session, entries: (await transcripts.forRender(forked.id)).entries };
};
const projectId = parsed.kind === "group" ? projectIdFromGroupRef(parsed.ref) : null;
if (!projectId) return fork();
const projects = deps.projects;
if (!projects) return null;
return projects.withRosterLock(projectId, async (project) => {
if (project.orgId !== orgIdOf()) return null;
const members = await projects.members(parsed.ref);
if (!members?.includes(principalId)) return null;
return fork(members);
});
},
async spawnSession(principalId, opts) {
const scope = opts.scopeId;
const parsed = parseScopeId(scope);
const create = async (projectMembers?: readonly string[], channelName?: string) => {
const threadRef = `web:${principalId}:${randomUUID()}`;
let kind: "group" | "channel" | "dm" = "dm";
if (parsed.kind === "group") kind = "group";
else if (parsed.kind === "channel") kind = "channel";
const session = await deps.sessions.getOrCreateByThread(threadRef, kind, scope, channelName, "web");
await Promise.all(
(projectMembers ?? [principalId]).map((memberId) => deps.sessions.addParticipant(session.id, memberId)),
);
if (opts.title?.trim()) await deps.sessions.updateTitle(session.id, opts.title.trim());
deps.auditLog.record({
at: Date.now(),
principalId,
action: "session.spawn",
resource: session.id,
scopeLabel: scope,
});
const stored = (await deps.sessions.get(session.id)) ?? session;
return { session: { ...stored, canContinue: await canContinueOnWeb(principalId, stored) } };
};
if (parsed.kind === "personal") {
return parsed.ref === principalId ? create() : null;
}
const projectId = parsed.kind === "group" ? projectIdFromGroupRef(parsed.ref) : null;
if (projectId) {
const projects = deps.projects;
if (!projects) return null;
return projects.withRosterLock(projectId, async (project) => {
if (project.orgId !== orgIdOf()) return null;
const members = await projects.members(parsed.ref);
if (!members?.includes(principalId)) return null;
return create(members, project.name);
});
}
if (!(await principalCanAccessCurrentScope(principalId, scope))) return null;
return create();
},
async discardSession(sessionId, principalId) {
const session = await sessionForViewer(sessionId, principalId);
if (!session) return false;
if (!(await deps.sessions.deleteSessionIfEmpty(sessionId))) return false;
deps.auditLog.record({
at: Date.now(),
principalId,
action: "session.discard",
resource: sessionId,
scopeLabel: session.scopeId,
});
return true;
},
async grant(g) {
if (parseRef(g.ref).kind === "deploy") {
g = {
...g,
granteeScopeId: await deploymentShareScope(
g.granteeScopeId,
g.permission,
async (email) =>
deps.identity.isInternal(deps.identity.classify(email)) &&
(await h.directoryMember(email))?.type === "internal",
),
};
await deps.deploy.assertShareAllowed(g.ownerScopeId, g.granteeScopeId, g.permission);
}
await deps.acl.grant(g, await artifactAuthor(g.ownerScopeId, g.ref));
deps.auditLog.record({
at: Date.now(),
principalId: g.grantedBy,
action: "grant",
resource: g.ref,
scopeLabel: g.granteeScopeId,
});
const ref = parseRef(g.ref);
if (ref.kind === "deploy")
await notifyDeploymentShared(
deps,
deps.deploy.getDeployment(ref.id),
g.granteeScopeId,
g.permission,
g.grantedBy,
);
},
async revokeGrant(ownerScopeId, ref, granteeScopeId, revokedBy) {
await deps.acl.revoke(ownerScopeId, ref, granteeScopeId, revokedBy, await artifactAuthor(ownerScopeId, ref));
deps.auditLog.record({
at: Date.now(),
principalId: revokedBy,
action: "revoke",
resource: ref,
scopeLabel: granteeScopeId,
});
},
async promoteSkill(id, targetScopeId, actorId, liveActor) {
if (parseScopeId(targetScopeId).kind !== "org")
throw new Error("promote targets the org scope — use share or move for anything narrower");
if (liveActor !== true)
throw new AdminError(403, "promoting a skill org-wide takes a live person, never an autonomous trigger");
if (!deps.admin) throw new Error("org promotion requires an admin service");
const status = await deps.admin.adminStatusOf({ id: actorId, type: "internal" });
if (!status.isAdmin) throw new AdminError(403, "only an org admin can promote a skill org-wide");
const promoted = await deps.skills.promote(id, targetScopeId);
deps.auditLog.record({
at: Date.now(),
principalId: actorId,
action: "skill_promote",
resource: id,
scopeLabel: targetScopeId,
});
return promoted;
},
belongsToScope(principalId, scope) {
return principalCanAccessCurrentScope(principalId, scope);
},
canManageArtifactHome(homeScopeId, createdBy, principalId) {
return principalManagesArtifactHome(homeScopeId, createdBy, principalId);
},
artifactGrantPermission(ownerScopeId, ref, principalId) {
return h.artifactGrantPermission(ownerScopeId, ref, principalId);
},
async getArtifactHome(type, idOrName): Promise<ArtifactHome | null> {
if (type === "skill") {
const s = await deps.skills.get(idOrName);
return s
? { id: s.id, ownerScopeId: s.scopeId, createdBy: s.createdBy, grantRef: encodeRef(skillRef(s.id)) }
: null;
}
if (type === "cron") {
const c = await deps.crons.get(idOrName);
return c
? { id: c.id, ownerScopeId: c.ownerScopeId, createdBy: c.createdBy, grantRef: encodeRef(cronRef(c.id)) }
: null;
}
if (type === "file") {
const f = await deps.files.get(idOrName);
return f
? { id: f.id, ownerScopeId: f.ownerScopeId, createdBy: f.createdBy, grantRef: encodeRef(fileRef(f.id)) }
: null;
}
const d = (await deps.deploy.listDeployments()).find((x) => x.id === idOrName || x.name === idOrName);
return d
? { id: d.id, ownerScopeId: d.ownerScopeId, createdBy: d.createdBy, grantRef: encodeRef(deployRef(d.id)) }
: null;
},
async moveArtifactHome(type, id, toScope, movedBy) {
if (type === "deploy") {
await deps.deploy.transferDeploymentOwner(id, toScope, { callerId: movedBy });
return;
}
if (type !== "skill") {
throw new Error(`moving a ${type}'s home isn't supported — share it instead (add a grant)`);
}
await deps.skills.move(id, toScope);
deps.auditLog.record({
at: Date.now(),
principalId: movedBy,
action: "skill_move",
resource: id,
scopeLabel: toScope,
});
},
getSoul(scopeIdValue) {
const orgScopeId = scopeId("org", orgIdOf());
const orgSoul = deps.config.getSoul(orgScopeId);
const soul = deps.config.getSoul(scopeIdValue);
return {
scopeId: scopeIdValue,
soul,
soulVersion: deps.config.soulVersion(scopeIdValue),
orgScopeId,
orgSoul,
orgSoulVersion: deps.config.soulVersion(orgScopeId),
effectiveSoul: composeSoul(orgSoul, scopeIdValue === orgScopeId ? null : soul),
};
},
async updateSoul(scopeIdValue, content, actorId, opts) {
const { kind, ref } = parseScopeId(scopeIdValue);
const allowedPersonal = kind === "personal" && samePerson(ref, actorId);
const allowedShared = opts?.allowSharedScope && (kind === "channel" || kind === "group");
if (!allowedPersonal && !allowedShared) {
throw new SoulUpdateDeniedError();
}
const write = async (): Promise<number> => {
let snapshot: Awaited<ReturnType<typeof deps.config.captureSoulSnapshot>> | undefined;
try {
await deps.config.refreshScope(scopeIdValue);
snapshot = await deps.config.captureSoulSnapshot(scopeIdValue);
const version =
opts?.expectedVersion === undefined
? await deps.config.setSoul(scopeIdValue, content, actorId)
: await deps.config.setSoulIfVersion(scopeIdValue, opts.expectedVersion, content, actorId);
if (version === null) throw new SoulVersionConflictError();
deps.auditLog.record({
at: Date.now(),
principalId: actorId,
action: "soul_update",
resource: scopeIdValue,
scopeLabel: scopeIdValue,
});
return version;
} catch (error) {
if (snapshot !== undefined) deps.config.restoreSoulCacheSnapshot(scopeIdValue, snapshot);
if (opts?.expectedVersion !== undefined) await deps.config.refreshScope(scopeIdValue);
throw error;
}
};
return deps.advisoryLock?.withLock(`admin-governance:${scopeIdValue}`, write) ?? write();
},
};
}