Multiplayer agent harness for work.
import { isSubagentThreadRef } from "../sessions/session-syscalls.ts";
import type {
PendingApproval,
PendingApprovalRecord,
Permission,
Principal,
ScopeId,
Session,
TurnResult,
} from "../types.ts";
import { orgId as orgIdOf } from "../config.ts";
import { isManageableCreationScope, parseScopeId, scopeId } from "../types.ts";
import { type ListOwnedOptions } from "../files/file-artifact-store.ts";
import { isTerminal, type Run } from "../runs/run-store.ts";
import { sleep } from "../util/async.ts";
import type { RunSignal } from "../runs/run-signal-store.ts";
import { processRun } from "../runs/worker.ts";
import { deployRef, encodeRef, parseRef } from "../acl/resource-ref.ts";
import type { Skill } from "../skills/skill-store.ts";
import type { CapabilityClaims } from "../auth/capability-token.ts";
import {
createCanReadScope,
createCanManageScope,
createCanWriteScope,
createIsCurrentSharedScopeMember,
createManagesArtifactHome,
createMembershipControlsScope,
} from "../resolution/scope-membership.ts";
import { samePerson } from "../directory/person.ts";
import { actorAssertionActive } from "../identity/identity-service.ts";
import type { Deployment } from "../deploy/deploy-store.ts";
import { reportFailureAs, swallow } from "../util/errors.ts";
import { adminSessionUrl } from "../util/admin-links.ts";
import {
openGroupViaSurface,
resolveReachTarget,
type ReachOpts,
type ReachResolution,
type ReachTarget,
type ReachDirectory,
} from "../reach/reach.ts";
import { createSurfaceContextPuller } from "./surface-context-puller.ts";
import {
isProjectGroupRef,
projectGroupRef,
projectIdFromGroupRef,
projectScopeId,
type Project,
} from "../projects/project-store.ts";
import type { ParticipantScope } from "../sessions/session-store.ts";
import type { App, AppDeps, ContextSummary, ProjectView, FileListPage } from "./app-types.ts";
import { toFileItem } from "./app-types.ts";
export function createAppHelpers(deps: AppDeps, app: App) {
const adminBase = deps.publicWebUrl?.replace(/\/$/, "");
const adminLink = (sessionId: string): string | undefined =>
adminBase ? adminSessionUrl(adminBase, sessionId) : undefined;
const surfaceContext = createSurfaceContextPuller(app);
const directoryRefresher = createSurfaceContextPuller(app, { waitMs: 4_000 });
async function refreshSurfaceDirectory(): Promise<void> {
await directoryRefresher.pull("slack", { syncDirectory: true, count: 1 });
}
const reachDir: ReachDirectory = {
resolveRecipient: (q) => deps.directory.resolve(q),
resolveChannel: (q) => deps.directory.resolveChannel(q),
channelMember: (c, p) => deps.directory.channelMember(c, p),
resolveGroup: (parts) => deps.directory.resolveGroupByParticipants(parts),
groupMember: (g, p) => deps.directory.groupMember(g, p),
directoryMember: (p) => deps.directory.get(p),
openGroup: (parts) => openGroupViaSurface((query) => surfaceContext.pull("slack", query), parts),
registerGroup: (g, parts) => deps.directory.upsertGroup(g, parts),
};
const resolveReachTargetFor = (
target: ReachTarget,
authorityId: string,
opts?: ReachOpts,
): Promise<ReachResolution> => resolveReachTarget(reachDir, target, authorityId, opts);
async function withAdminLink(result: TurnResult): Promise<TurnResult> {
if (!result.sessionId) return result;
const byThread = await deps.sessions.getByThread(result.sessionId);
let sessionId: string | undefined;
if (byThread) sessionId = byThread.id;
else if (await deps.sessions.get(result.sessionId)) sessionId = result.sessionId;
if (!sessionId) return { ...result, sessionId: undefined };
const adminUrl = adminLink(sessionId);
return { ...result, sessionId, ...(adminUrl ? { adminUrl } : {}) };
}
async function approvalCurrentForSession(session: Session, record: PendingApprovalRecord): Promise<boolean> {
if (!actorAssertionActive(deps.identity, record.request?.actor)) return false;
const parsed = parseScopeId(session.scopeId);
if (parsed.kind !== "group" || !isProjectGroupRef(parsed.ref)) return true;
return authorizesCapabilityScope({
actorId: record.request!.actor.externalId,
scopeId: session.scopeId,
scopeVersion: record.request?.scopeVersion,
});
}
async function approvalRecordIsCurrent(record: PendingApprovalRecord, knownSession?: Session): Promise<boolean> {
const session = knownSession ?? (await deps.sessions.get(record.sessionId));
return !!session && approvalCurrentForSession(session, record);
}
async function approvalsVisibleToViewer<T extends { record: PendingApprovalRecord }>(
session: Session,
viewer: string,
candidates: T[],
): Promise<T[]> {
const own = candidates.filter(({ record }) => samePerson(record.request?.actor.externalId, viewer));
if (!own.length) return [];
if ((await managedProjectMembership(session.scopeId, viewer)) === false) return [];
const parsed = parseScopeId(session.scopeId);
if (parsed.kind !== "group" || !isProjectGroupRef(parsed.ref)) return own;
const window = (await deps.sessions.participantWindowsOf(session.id)).find((candidate) =>
samePerson(candidate.principalId, viewer),
);
if (!window) return [];
return own.filter(
({ record }) =>
record.createdAt !== undefined &&
record.createdAt >= window.validFrom &&
(window.validTo === null || record.createdAt < window.validTo),
);
}
async function approvalVisibleToViewer(
session: Session,
viewer: string,
record: PendingApprovalRecord,
): Promise<boolean> {
return (await approvalsVisibleToViewer(session, viewer, [{ record }])).length === 1;
}
async function approvalResumable(
session: Session,
actorId: string,
record: PendingApprovalRecord | null | undefined,
): Promise<"ok" | "expired" | "foreign_session" | "stale" | "not_requester"> {
if (!record) return "expired";
if (record.sessionId !== session.id) return "foreign_session";
if (!(await approvalRecordIsCurrent(record, session))) return "stale";
if (!(await approvalVisibleToViewer(session, actorId, record))) return "not_requester";
return "ok";
}
async function pendingApprovalForSession(
sessionId: string,
opts: { blockingOnly: boolean; viewer?: string },
): Promise<PendingApproval[]> {
if (!deps.approvals) return [];
const [entries, session] = await Promise.all([
deps.approvals.selectEntries({ where: { field: "sessionId", anyOfFold: [sessionId] } }),
deps.sessions.get(sessionId),
]);
if (!session) return [];
const candidates: Array<{ key: string; record: PendingApprovalRecord }> = [];
for (const [key, record] of entries) {
if (record.sessionId !== sessionId || (opts.blockingOnly && record.blocksInput === false)) continue;
if (await approvalRecordIsCurrent(record, session)) candidates.push({ key, record });
}
const visible = opts.viewer ? await approvalsVisibleToViewer(session, opts.viewer, candidates) : candidates;
return visible.map(({ key, record: r }) => ({
requestId: key,
command: r.command,
reason: r.reason ?? "requires approval",
...(r.matched ? { matched: r.matched } : {}),
...(r.purpose ? { purpose: r.purpose } : {}),
...(r.summary ? { summary: r.summary } : {}),
...(r.summaryDetail ? { summaryDetail: r.summaryDetail } : {}),
...(r.grantModes ? { grantModes: r.grantModes } : {}),
blocksInput: r.blocksInput !== false,
...(r.kind === "approval" ? { kind: r.kind } : {}),
}));
}
async function pendingApprovalResultForThread(
threadRef: string,
viewer?: string,
opts: { alwaysBlock?: boolean } = {},
): Promise<TurnResult | null> {
const session = await deps.sessions.getByThread(threadRef);
if (!session) return null;
if (!opts.alwaysBlock && viewer && !(await sessionForViewer(session.id, viewer))) return null;
const all = await pendingApprovalForSession(session.id, { blockingOnly: true });
if (!all.length) return null;
const approvals = viewer ? await pendingApprovalForSession(session.id, { blockingOnly: true, viewer }) : all;
if (!approvals.length) {
return {
status: "pending_approval",
sessionId: session.id,
reason: "This conversation is waiting for someone else to resolve a pending approval.",
};
}
return {
status: "pending_approval",
sessionId: session.id,
reason: "Approve or deny the pending command to continue.",
pendingApprovals: approvals,
};
}
async function drive(runId: string): Promise<TurnResult> {
const timeoutMs = deps.runWaitMs ?? 60_000;
const deadline = performance.now() + timeoutMs;
for (;;) {
const run = await deps.runs.get(runId);
if (!run) throw new Error(`run ${runId} not found`);
if (isTerminal(run.status)) {
return withAdminLink(
run.result ?? { status: "failed", sessionId: run.sessionId, reason: "run produced no result" },
);
}
const shutdown = deps.shutdown?.();
if (shutdown?.aborted) return { status: "queued", sessionId: run.sessionId, runId };
const claimed =
run.status === "running" ? null : await deps.runs.claimForSession(run.sessionId, "inline", deps.leaseTtlMs);
if (claimed) {
try {
const result = await processRun(
{ runs: deps.runs, orchestrator: deps.orchestrator, leaseTtlMs: deps.leaseTtlMs },
claimed,
{ shutdown },
);
if (claimed.id === runId && !shutdown?.aborted) return withAdminLink(result);
} catch (error) {
if (claimed.id === runId && !shutdown?.aborted) throw error;
swallow("inline run did not complete", error);
}
continue;
}
const remaining = deadline - performance.now();
if (remaining <= 0) throw new Error(`run ${runId} did not finish within ${timeoutMs}ms`);
await sleep(Math.min(100, remaining));
}
}
async function mayUseSharedScope(kind: "channel" | "group", ref: string, actor: Principal): Promise<boolean> {
if (!deps.identity.isInternal(actor)) return false;
return principalCanAccessCurrentScope(actor.id, scopeId(kind, ref));
}
async function viewerMayUseRun(run: Run, viewer: string): Promise<boolean> {
const conversation = run.request.conversation;
if (conversation.kind === "dm") return samePerson(run.request.actor.id, viewer);
if (!conversation.channelRef) return false;
const scope = scopeId(conversation.kind, conversation.channelRef);
if (await principalIsCurrentSharedScopeMember(viewer, scope)) {
if (conversation.kind !== "group" || !isProjectGroupRef(conversation.channelRef)) return true;
return run.request.scopeVersion === (await deps.projects?.version(conversation.channelRef));
}
if (conversation.kind !== "channel") return false;
const isPublic = (await deps.directory.channelPrivacy?.(conversation.channelRef).catch(() => undefined)) === false;
const active = deps.identity.isInternal(deps.identity.classify(viewer));
return isPublic && active && principalCanReadScope(viewer, scope);
}
async function projectView(project: Project): Promise<ProjectView> {
const memberIds = (await deps.projects?.members(projectGroupRef(project.id))) ?? project.memberIds;
const manual = new Set([project.ownerId, ...project.memberIds]);
const members = await Promise.all(
memberIds.map(async (principalId) => {
const member = await deps.directory.get(principalId).catch(() => null);
return {
principalId,
displayName: member?.displayName?.trim() || principalId,
...(member?.avatarUrl ? { avatarUrl: member.avatarUrl } : {}),
...(manual.has(principalId) ? {} : { viaChannel: true }),
};
}),
);
return { ...project, memberIds, scopeId: projectScopeId(project.id), members };
}
async function projectsForViewer(principalId: string): Promise<ProjectView[]> {
if (!deps.projects || !deps.identity.isInternal(deps.identity.classify(principalId))) return [];
const projects = (await deps.projects.listForMember(principalId)).filter((project) =>
deps.identity.isInternal(deps.identity.classify(project.ownerId)),
);
return Promise.all(projects.map(projectView));
}
async function managedProjectMembership(scope: ScopeId, principalId: string): Promise<boolean | undefined> {
const { kind, ref } = parseScopeId(scope);
if (kind !== "group" || projectIdFromGroupRef(ref) === null) return undefined;
if (!deps.projects) return false;
const project = await deps.projects.get(projectIdFromGroupRef(ref)!);
if (!project || project.orgId !== orgIdOf()) return false;
if (!deps.identity.isInternal(deps.identity.classify(project.ownerId))) return false;
if (!deps.identity.isInternal(deps.identity.classify(principalId))) return false;
return (await deps.projects.membership(ref, principalId).catch(() => false)) === true;
}
async function sessionsForViewer(principalId: string): Promise<Session[]> {
const sessions = await deps.sessions.listByParticipant(principalId);
const allowed = new Map(
await Promise.all(
[...new Set(sessions.map((session) => session.scopeId))].map(
async (scope) => [scope, await managedProjectMembership(scope, principalId)] as const,
),
),
);
return sessions.filter((session) => allowed.get(session.scopeId) !== false);
}
async function scopesForViewer(principalId: string): Promise<ParticipantScope[]> {
const scopes = await deps.sessions.participantScopes(principalId);
const allowed = await Promise.all(
scopes.map(async (scope) => (await managedProjectMembership(scope.scopeId, principalId)) !== false),
);
return scopes.filter((_, index) => allowed[index]);
}
async function sessionForViewer(sessionId: string, principalId: string): Promise<Session | null> {
const session = await deps.sessions.getForParticipant(sessionId, principalId);
if (!session) return null;
return (await managedProjectMembership(session.scopeId, principalId)) === false ? null : session;
}
async function contextsFor(principalId: string): Promise<ContextSummary[]> {
const personal = scopeId("personal", principalId);
const byScope = new Map<ScopeId, ContextSummary>();
byScope.set(personal, { scopeId: personal, kind: "personal", name: null, sessionCount: 0, lastActivityAt: null });
if (deps.identity.isInternal(deps.identity.classify(principalId))) {
for (const c of await deps.directory.listChannelsFor(principalId)) {
const sid = scopeId("channel", c.channelId);
byScope.set(sid, {
scopeId: sid,
kind: "channel",
name: c.name,
...(c.isPrivate !== undefined ? { isPrivate: c.isPrivate } : {}),
sessionCount: 0,
lastActivityAt: null,
});
}
}
for (const project of await projectsForViewer(principalId)) {
const sid = projectScopeId(project.id);
byScope.set(sid, {
scopeId: sid,
kind: "group",
name: project.name,
sessionCount: 0,
lastActivityAt: null,
project,
});
}
for (const scope of await scopesForViewer(principalId)) {
const { kind, ref } = parseScopeId(scope.scopeId);
if (scope.scopeId !== personal && kind !== "channel" && kind !== "group") continue;
let ctx = byScope.get(scope.scopeId);
if (!ctx && kind === "group" && (await deps.directory.groupMember(ref, principalId))) {
ctx = {
scopeId: scope.scopeId,
kind: "group",
name: scope.channelName ?? null,
sessionCount: 0,
lastActivityAt: null,
};
}
if (!ctx) continue;
if (!ctx.name && scope.channelName) ctx.name = scope.channelName;
ctx.sessionCount += scope.sessionCount;
if (scope.lastActivityAt !== null) ctx.lastActivityAt = Math.max(ctx.lastActivityAt ?? 0, scope.lastActivityAt);
byScope.set(scope.scopeId, ctx);
}
return [...byScope.values()].sort((a, b) => {
if (a.kind === "personal") return -1;
if (b.kind === "personal") return 1;
return (b.lastActivityAt ?? 0) - (a.lastActivityAt ?? 0);
});
}
async function filesForViewer(
principalId: string,
opts?: ListOwnedOptions,
inScope?: ScopeId,
): Promise<FileListPage> {
const myScopes = await currentResourceScopesForViewer(principalId);
const handles = await deps.acl.handlesFor(myScopes);
const page = await deps.files.listDocuments(
myScopes,
handles.map((h) => ({ ownerScopeId: h.ownerScopeId, id: h.fileId })),
{
...opts,
...(inScope ? { createdInScope: inScope } : {}),
},
);
return {
owned: page.files.filter((f) => myScopes.includes(f.ownerScopeId)).map(toFileItem),
shared: page.files.filter((f) => !myScopes.includes(f.ownerScopeId)).map(toFileItem),
...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
};
}
async function currentResourceScopesForViewer(principalId: string): Promise<ScopeId[]> {
const actor = deps.identity?.classify(principalId);
if (actor && !deps.identity?.isInternal(actor)) return [];
const scopes = new Set<ScopeId>([
scopeId("personal", principalId),
...(actor?.teamIds ?? []).map((teamId) => scopeId("team", teamId)),
scopeId("org", orgIdOf()),
]);
try {
const [sessionScopes, channels, groups, projects] = await Promise.all([
deps.sessions ? scopesForViewer(principalId) : Promise.resolve([]),
deps.directory ? deps.directory.listChannelsFor(principalId) : Promise.resolve([]),
deps.directory?.listGroupsFor?.(principalId) ?? Promise.resolve([]),
projectsForViewer(principalId),
]);
const historical = new Set(sessionScopes.map((scope) => scope.scopeId));
for (const channel of channels) {
const scope = scopeId("channel", channel.channelId);
if (channel.isPrivate === true || historical.has(scope)) scopes.add(scope);
}
for (const groupId of groups) scopes.add(scopeId("group", groupId));
for (const project of projects) scopes.add(project.scopeId);
} catch (error) {
swallow("app: current resource scopes for viewer", error);
}
return [...scopes];
}
async function canUseContext(principalId: string, targetScope: ScopeId): Promise<boolean> {
return principalCanAccessCurrentScope(principalId, targetScope);
}
const scopeMembershipDeps = {
...(deps.projects ? { managedGroups: deps.projects } : {}),
...(deps.directory ? { directory: deps.directory } : {}),
...(deps.identity ? { identity: deps.identity } : {}),
...(deps.teams ? { teams: deps.teams } : {}),
};
const principalCanReadScope = createCanReadScope(scopeMembershipDeps);
const principalCanWriteScope = createCanWriteScope(scopeMembershipDeps);
async function mayWriteSession(
principalId: string,
session: Pick<Session, "threadRef" | "scopeId">,
sharedAccess = new Map<string, Promise<boolean>>(),
): Promise<boolean> {
const actor = deps.identity.classify(principalId);
if (!deps.identity.isInternal(actor)) return false;
const { kind, ref } = parseScopeId(session.scopeId);
if (kind === "personal") return session.scopeId === scopeId("personal", actor.id);
if (kind !== "channel" && kind !== "group") return false;
const subagent = isSubagentThreadRef(session.threadRef);
const key = subagent ? `subagent ${session.scopeId}` : session.scopeId;
if (!sharedAccess.has(key))
sharedAccess.set(
key,
subagent ? principalCanWriteScope(actor.id, session.scopeId) : mayUseSharedScope(kind, ref, actor),
);
return sharedAccess.get(key)!;
}
async function canContinueOnWeb(
principalId: string,
session: Pick<Session, "threadRef" | "scopeId">,
sharedAccess?: Map<string, Promise<boolean>>,
): Promise<boolean> {
if (!session.threadRef.startsWith("web:") && !isSubagentThreadRef(session.threadRef)) return false;
return mayWriteSession(principalId, session, sharedAccess);
}
async function principalCanAccessCurrentScope(principalId: string, targetScope: ScopeId): Promise<boolean> {
if (await principalCanWriteScope(principalId, targetScope)) return true;
const { kind, ref } = parseScopeId(targetScope);
if (kind !== "channel") return false;
if (!deps.identity.isInternal(deps.identity.classify(principalId))) return false;
if ((await deps.directory.channelPrivacy?.(ref).catch(() => undefined)) !== false) return false;
return principalCanReadScope(principalId, targetScope);
}
async function principalCanUseWriteGrant(principalId: string, targetScope: ScopeId): Promise<boolean> {
const { kind, ref } = parseScopeId(targetScope);
const publicChannel =
kind === "channel" && (await deps.directory.channelPrivacy?.(ref).catch(() => undefined)) === false;
return publicChannel
? principalCanAccessCurrentScope(principalId, targetScope)
: principalCanWriteScope(principalId, targetScope);
}
const principalIsCurrentSharedScopeMember = createIsCurrentSharedScopeMember(scopeMembershipDeps);
const principalCanManageScope = createCanManageScope(scopeMembershipDeps);
const membershipControlsScope = createMembershipControlsScope(scopeMembershipDeps);
async function authorizesCapabilityScope(
claims: Pick<CapabilityClaims, "actorId" | "scopeId" | "scopeVersion" | "botActor" | "liveActor" | "members">,
): Promise<boolean> {
const { kind, ref } = parseScopeId(claims.scopeId);
if (kind === "channel" && !deps.identity.isInternal(deps.identity.classify(claims.actorId))) return false;
const privateChannel =
kind === "channel" && (await deps.directory.channelPrivacy?.(ref).catch(() => undefined)) === true;
const capabilityMembership = privateChannel
? await deps.directory.channelMembership(ref, claims.actorId).catch(() => undefined)
: undefined;
const attestedBot =
privateChannel &&
claims.botActor === true &&
claims.liveActor === true &&
claims.members?.some((member) => member.id === claims.actorId && member.type === "internal") === true;
if (
(kind === "channel" &&
!(
attestedBot ||
(capabilityMembership ?? (await principalCanAccessCurrentScope(claims.actorId, claims.scopeId)))
)) ||
(kind === "group" && !(await principalCanWriteScope(claims.actorId, claims.scopeId)))
) {
return false;
}
if (kind !== "group" || deps.projects?.recognizes(ref) !== true) return true;
return (
(await principalCanManageScope(claims.actorId, claims.scopeId)) &&
claims.scopeVersion === (await deps.projects.version(ref))
);
}
const principalManagesArtifactHome = createManagesArtifactHome(scopeMembershipDeps, principalCanManageScope);
async function artifactAuthor(ownerScopeId: ScopeId, ref: string): Promise<string | undefined> {
const { kind } = parseScopeId(ownerScopeId);
if (kind !== "channel" && kind !== "group") return undefined;
const r = parseRef(ref);
if (r.kind === "skill") return (await deps.skills.get(r.id))?.createdBy;
if (r.kind === "cron") return (await deps.crons.get(r.id))?.createdBy;
if (r.kind === "deploy") return (await deps.deploy.listDeployments()).find((d) => d.id === r.id)?.createdBy;
if (r.kind === "file") return (await deps.files.resolveByIds([{ ownerScopeId, id: r.id }]))[0]?.createdBy;
return undefined;
}
function canManageSkill(skill: Pick<Skill, "scopeId" | "createdBy">, principalId: string): Promise<boolean> {
return principalManagesArtifactHome(skill.scopeId, skill.createdBy, principalId);
}
async function republishIfShared(skill: Skill, editorId: string): Promise<Skill> {
if (skill.status === "published") return skill;
const { kind } = parseScopeId(skill.scopeId);
if (kind !== "channel" && kind !== "group") return skill;
await deps.skills.review(skill.id, "system:skill-authoring", skill.manifest.requiredCapabilities);
const published = await deps.skills.publish(skill.id);
deps.auditLog.record({
at: Date.now(),
principalId: editorId,
action: "skill_review",
resource: skill.id,
scopeLabel: skill.scopeId,
});
return published;
}
async function artifactGrantPermission(
ownerScopeId: ScopeId,
ref: string,
principalId: string,
): Promise<Permission | null> {
let best: Permission | null = null;
const grants = (await deps.acl?.grantsFor(ownerScopeId, ref).catch(reportFailureAs("artifact grants", []))) ?? [];
for (const g of grants) {
if (g.permission !== "read" && g.permission !== "write") continue;
if (
g.permission === "read" &&
principalId.includes("@") &&
g.granteeScopeId === `personal:${principalId.trim().toLowerCase()}`
) {
best = "read";
continue;
}
if (!(await principalCanAccessCurrentScope(principalId, g.granteeScopeId))) continue;
if (g.permission === "write" && (await principalCanUseWriteGrant(principalId, g.granteeScopeId))) return "write";
best = "read";
}
return best;
}
async function effectiveDeploymentPermission(d: Deployment, principalId: string): Promise<Permission | null> {
if (!principalId || deps.identity.deactivationSource?.(principalId) === "manual") return null;
if (await principalCanWriteScope(principalId, d.ownerScopeId)) return "write";
const granted = await artifactGrantPermission(d.ownerScopeId, encodeRef(deployRef(d.id)), principalId);
if (granted) return granted;
return (await principalCanAccessCurrentScope(principalId, d.ownerScopeId)) ? "read" : null;
}
async function principalCanReadDeployment(d: Deployment, principalId: string): Promise<boolean> {
return (await effectiveDeploymentPermission(d, principalId)) != null;
}
async function principalGitPermission(
d: Pick<Deployment, "id" | "ownerScopeId" | "createdBy" | "createdInScope">,
principalId: string,
): Promise<"read" | "write" | null> {
if (!principalId) return null;
const { kind } = parseScopeId(d.ownerScopeId);
if (await principalManagesArtifactHome(d.ownerScopeId, d.createdBy, principalId)) return "write";
if (isManageableCreationScope(d.createdInScope) && (await principalCanWriteScope(principalId, d.createdInScope!)))
return "write";
let canRead = kind === "org" && (await principalCanAccessCurrentScope(principalId, d.ownerScopeId));
const grants = (await deps.acl?.grantsFor(d.ownerScopeId, encodeRef(deployRef(d.id))).catch(() => [])) ?? [];
for (const g of grants) {
if (g.permission !== "read" && g.permission !== "write") continue;
if (!(await principalCanAccessCurrentScope(principalId, g.granteeScopeId))) continue;
if (g.permission === "write" && (await principalCanUseWriteGrant(principalId, g.granteeScopeId))) return "write";
canRead = true;
}
if (canRead) return "read";
return (await principalCanAccessCurrentScope(principalId, d.ownerScopeId)) ? "read" : null;
}
async function syncProjectChannelRoster(project: Project, actorId: string): Promise<void> {
const link = project.slackChannel;
if (!link || !deps.projects) return;
const roster = await deps.directory.channelMemberIds(link.channelId).catch(() => undefined);
if (roster === undefined) return;
const derived = roster.filter((m) => deps.identity.isInternal(deps.identity.classify(m)));
const channel = (await deps.directory.listChannels().catch(() => [])).find((c) => c.channelId === link.channelId);
const prev = project.channelMemberIds ?? [];
const manual = new Set([project.ownerId, ...project.memberIds]);
const prevSet = new Set(prev);
const nextSet = new Set(derived);
await deps.projects.syncChannelMembers(project.id, derived, channel?.name, async ({ project: p, changed }) => {
if (!changed) return;
for (const m of derived) {
if (prevSet.has(m) || manual.has(m)) continue;
deps.auditLog.record({
at: Date.now(),
principalId: actorId,
action: "project.member.add",
resource: m,
scopeLabel: projectScopeId(p.id),
});
await reconcileProjectMember(p, m, true);
}
for (const m of prev) {
if (nextSet.has(m) || manual.has(m)) continue;
deps.auditLog.record({
at: Date.now(),
principalId: actorId,
action: "project.member.remove",
resource: m,
scopeLabel: projectScopeId(p.id),
});
await reconcileProjectMember(p, m, false);
}
});
}
async function syncLinkedProjectRosters(): Promise<void> {
if (!deps.projects) return;
for (const project of await deps.projects.listLinked().catch(() => [])) {
await syncProjectChannelRoster(project, "directory-sync").catch((err) =>
swallow(`projects: channel roster sync for ${project.id}`, err),
);
}
}
async function reconcileProjectMember(project: Project, memberId: string, add: boolean): Promise<void> {
const sessions = await deps.sessions.listByScope(projectScopeId(project.id));
for (const session of sessions) {
if (add) await deps.sessions.addParticipant(session.id, memberId, undefined, { includeHistory: true });
else await deps.sessions.removeParticipant(session.id, memberId);
}
}
async function replayOrphanedRunSignals(runId: string): Promise<Array<{ signal: RunSignal; replayRunId?: string }>> {
if (!deps.signals) return [];
const drained: Array<{ signal: RunSignal; replayRunId?: string }> = [];
const completed = await deps.runs.get(runId);
if (completed && isSubagentThreadRef(completed.sessionId)) {
for (const { id, signal } of await deps.signals.pending(runId)) {
if (signal.kind === "abort" || signal.kind === "client_result" || !signal.text?.trim()) {
await deps.signals.acknowledge(runId, id);
continue;
}
let replayRunId: string | undefined;
const dedupKey = `session-signal:${runId}:${id}`;
if (signal.sessionRequest) {
const {
clientTools: _clientTools,
desktopClientId: _desktopClientId,
...sessionRequest
} = signal.sessionRequest;
const { run } = await deps.runs.enqueue({
sessionId: completed.sessionId,
request: sessionRequest,
dedupKey,
maxAttempts: deps.maxAttempts,
});
replayRunId = run.id;
} else if (signal.request) {
const {
approval: _ap,
redeliveryKey: _redeliveryKey,
clientTools: _clientTools,
desktopClientId: _desktopClientId,
...base
} = signal.request;
const prior = completed.request;
const inheritedOptions = {
...(base.model === undefined && prior.model !== undefined ? { model: prior.model } : {}),
...(base.harness === undefined && prior.harness !== undefined ? { harness: prior.harness } : {}),
...(base.thinkingLevel === undefined && prior.thinkingLevel !== undefined
? { thinkingLevel: prior.thinkingLevel }
: {}),
...(base.fastMode === undefined && prior.fastMode !== undefined ? { fastMode: prior.fastMode } : {}),
...(base.timezone === undefined && prior.timezone !== undefined ? { timezone: prior.timezone } : {}),
};
const replayed = await app.turn(
{ ...base, ...inheritedOptions, async: true, idempotencyKey: dedupKey },
{ signalDedupKey: dedupKey },
);
replayRunId = replayed.runId;
if (!replayRunId && replayed.status !== "refused") continue;
} else {
const {
approval: _approval,
attachments: _attachments,
displayText: _display,
clientTools: _clientTools,
desktopClientId: _desktopClientId,
...request
} = completed.request;
const { run } = await deps.runs.enqueue({
sessionId: completed.sessionId,
request: { ...request, text: signal.text, origin: { kind: "automation", screenData: signal.text } },
dedupKey,
maxAttempts: deps.maxAttempts,
});
replayRunId = run.id;
}
await deps.signals.acknowledge(runId, id);
drained.push({ signal, ...(replayRunId ? { replayRunId } : {}) });
}
return drained;
}
for (const signal of await deps.signals.takePending(runId)) {
if (signal.kind === "abort" || signal.kind === "client_result") continue;
let replayRunId: string | undefined;
let replayOutcomeKnown = true;
if (signal.request) {
try {
const {
approval: _ap,
redeliveryKey: _redeliveryKey,
clientTools: _clientTools,
desktopClientId: _desktopClientId,
...base
} = signal.request;
const prior = (await deps.runs.get(runId))?.request;
const inheritedOptions = {
...(base.model === undefined && prior?.model !== undefined ? { model: prior.model } : {}),
...(base.harness === undefined && prior?.harness !== undefined ? { harness: prior.harness } : {}),
...(base.thinkingLevel === undefined && prior?.thinkingLevel !== undefined
? { thinkingLevel: prior.thinkingLevel }
: {}),
...(base.fastMode === undefined && prior?.fastMode !== undefined ? { fastMode: prior.fastMode } : {}),
...(base.timezone === undefined && prior?.timezone !== undefined ? { timezone: prior.timezone } : {}),
};
const replayed = await app.turn({ ...base, ...inheritedOptions, async: true });
replayRunId = replayed.runId;
} catch (err) {
replayOutcomeKnown = false;
swallow(`signals: orphaned-signal replay for run ${runId}`, err);
}
}
if (!replayRunId && replayOutcomeKnown && signal.text?.trim()) {
const orphanRun = await deps.runs.get(runId);
if (orphanRun) {
try {
const {
displayText: _d,
attachments: _a,
approval: _ap,
clientTools: _clientTools,
desktopClientId: _desktopClientId,
...base
} = orphanRun.request;
const { run: fresh } = await deps.runs.enqueue({
sessionId: orphanRun.sessionId,
request: { ...base, text: signal.text },
});
replayRunId = fresh.id;
} catch (err) {
swallow(`signals: requestless orphaned-steer replay for run ${runId}`, err);
}
}
}
if (!replayRunId) {
console.warn(
`[signals] orphaned ${signal.kind} for terminal run ${runId} could not be replayed — dropped: ${signal.text?.slice(0, 120) ?? ""}`,
);
}
drained.push({ signal, ...(replayRunId ? { replayRunId } : {}) });
}
return drained;
}
return {
adminBase,
adminLink,
directoryMember: (principalId: string) => app.directoryMember(principalId),
withAdminLink,
resolveReachTargetFor,
approvalRecordIsCurrent,
approvalResumable,
approvalVisibleToViewer,
pendingApprovalForSession,
pendingApprovalResultForThread,
drive,
mayUseSharedScope,
viewerMayUseRun,
projectView,
projectsForViewer,
managedProjectMembership,
sessionsForViewer,
sessionForViewer,
contextsFor,
filesForViewer,
currentResourceScopesForViewer,
canUseContext,
principalCanAccessCurrentScope,
principalCanWriteScope,
canContinueOnWeb,
mayWriteSession,
principalCanManageScope,
membershipControlsScope,
authorizesCapabilityScope,
principalManagesArtifactHome,
artifactAuthor,
canManageSkill,
republishIfShared,
effectiveDeploymentPermission,
artifactGrantPermission,
principalCanReadDeployment,
principalGitPermission,
refreshSurfaceDirectory,
reconcileProjectMember,
syncProjectChannelRoster,
syncLinkedProjectRosters,
replayOrphanedRunSignals,
};
}
export type AppHelpers = ReturnType<typeof createAppHelpers>;