Multiplayer agent harness for work.
import { externalSlackRequestAllowed } from "../resolution/external-slack.ts";
import { availableRuntimeError, runtimeConfigBody } from "./runtime-config.ts";
import type { Run } from "../runs/run-store.ts";
import { userRuntimeConfigBody } from "./runtime-config.ts";
import { isSubagentThreadRef, stopSessionTree } from "../sessions/session-syscalls.ts";
import type { Conversation, Principal, TurnRequest, TurnResult } from "../types.ts";
import { orgId as orgIdOf } from "../config.ts";
import { scopeId } from "../types.ts";
import { rosterAdmits } from "../resolution/scope-membership.ts";
import { isHalt, routeWake, type Wake } from "../wake/wake.ts";
import type { OrchestratorInput } from "../core/orchestrator.ts";
import { desktopClientForTurn, isPersonAuthored, isSessionTurn, resolveTurnOrigin } from "../core/turn-origin.ts";
import { conversationScope } from "../resolution/resolution-service.ts";
import { isTerminal, leaseLapsed } from "../runs/run-store.ts";
import type { SessionStateEvent } from "../runs/session-state-bus.ts";
import { turnModelOptions, turnRuntimePurpose, validateWebTurnModelOptions } from "../core/turn-options.ts";
import { isProjectGroupRef, projectIdFromGroupRef } from "../projects/project-store.ts";
import { samePerson } from "../directory/person.ts";
import {
defaultModelForHarness,
harnessIdOrPi,
isHarnessId,
modelProviderAvailabilityFor,
modelServiceable,
modelOfferedInWebui,
modelUnavailableReason,
resolveModel,
} from "../model/pi-models.ts";
import { selectableCatalogForHarness, selectableModelCatalog } from "../model/model-catalog.ts";
import { resolveRuntimeChoiceDurable } from "../harness/harness-router.ts";
import { swallow, swallowAs } from "../util/errors.ts";
import { sleep } from "../util/async.ts";
import { pgTextSafe } from "../util/text.ts";
import { GENERIC_FAILURE_CLAUSE } from "../../plugins/chassis/src/failure-copy.ts";
import type { App, AppDeps } from "./app-types.ts";
import { STALE_LEASE_GRACE_MS } from "./app-types.ts";
const PARTICIPANT_REHYDRATE_TIMEOUT_MS = 5_000;
import { unscreenedNotice } from "../security/security-posture.ts";
import type { AppHelpers } from "./app-helpers.ts";
import type { AmbientHelpers } from "./app-ambient.ts";
const USER_STOP = "by user";
export function attributedSteerText(
steerer: { id: string; displayName?: string | undefined },
runOwnerId: string | null,
text: string,
): string {
if (runOwnerId !== null && samePerson(steerer.id, runOwnerId)) return text;
return `${steerer.displayName?.trim() || steerer.id}: ${text}`;
}
export function createTurnMethods(
deps: AppDeps,
h: AppHelpers,
ambient: AmbientHelpers,
): Pick<
App,
| "turn"
| "getApproval"
| "subscribeSessionStates"
| "subscribeLedgerEvents"
| "listSessionApprovals"
| "pendingApprovalForThread"
| "getRun"
| "getRunToolEntries"
| "subscribeRun"
| "syncRunStream"
| "activeRunForThread"
| "stopConversation"
| "withdrawRun"
| "editQueuedRun"
| "signalRun"
| "replayOrphanedRunSignals"
> {
const {
withAdminLink,
drive,
approvalRecordIsCurrent,
approvalResumable,
approvalVisibleToViewer,
pendingApprovalForSession,
pendingApprovalResultForThread,
mayUseSharedScope,
viewerMayUseRun,
sessionForViewer,
replayOrphanedRunSignals,
} = h;
const { shouldRouteToSpine, markTriggerHandled, addressedWakeText } = ambient;
async function stopRunTree(run: Run): Promise<boolean> {
if (!deps.signals) return false;
const signals = deps.signals;
const stop = async () => {
const session = await deps.sessions.getByThread(run.sessionId);
if (session) return stopSessionTree({ sessions: deps.sessions, runs: deps.runs, signals }, session, USER_STOP);
await signals.send(run.id, { kind: "abort", reason: USER_STOP });
if (run.status === "pending") await deps.runs.withdraw(run.id);
return true;
};
return deps.advisoryLock ? deps.advisoryLock.withLock("session-tree-admission", stop) : stop();
}
return {
async turn(req: TurnRequest, replay?: { signalDedupKey: string }): Promise<TurnResult> {
const startedAt = performance.now();
const historicalSlack = Object.keys(deps.externalSlackPolicies ?? {}).length
? (await deps.sessions.getByThread(req.conversation.threadRef))?.surface === "slack"
: false;
if (!externalSlackRequestAllowed(req, deps.externalSlackPolicies, historicalSlack))
return {
status: "refused",
reason: "External Slack requests require their current authenticated source context.",
};
await deps.refreshModels?.();
await deps.identity.refresh();
const actor: Principal = deps.identity.resolve(req.actor);
if (!deps.identity.isInternal(actor)) {
return {
status: "refused",
refusalKind: "internal_only",
reason: "internal-only: non-internal principals cannot interact",
};
}
let projectAudience: Principal[] | undefined;
let projectName: string | undefined;
let projectVersion: string | undefined;
let sessionParticipantIds: string[] | undefined;
const conversationRef = req.conversation.channelRef;
const projectGroup = req.conversation.kind === "group" && !!conversationRef && isProjectGroupRef(conversationRef);
const projectId = projectGroup ? projectIdFromGroupRef(conversationRef) : null;
if (projectGroup) {
if (!projectId) return { status: "refused", reason: "you're not a member of that context" };
const project = await deps.projects?.get(projectId);
if (
!project ||
project.orgId !== orgIdOf() ||
!deps.identity.isInternal(deps.identity.classify(project.ownerId))
) {
return { status: "refused", reason: "you're not a member of that context" };
}
const roster = (await deps.projects?.members(conversationRef)) ?? [];
const activeMemberIds = roster.filter((memberId) => deps.identity.isInternal(deps.identity.classify(memberId)));
if (!rosterAdmits(activeMemberIds, actor.id, scopeId("group", conversationRef)))
return { status: "refused", reason: "you're not a member of that context" };
projectAudience = await Promise.all(
activeMemberIds.map(async (memberId) => {
if (memberId === actor.id) return actor;
const principal = deps.identity.classify(memberId);
const member = await deps.directory.get(memberId).catch(() => null);
return member?.displayName ? { ...principal, displayName: member.displayName } : principal;
}),
);
projectName = project.name;
projectVersion = String(project.updatedAt);
sessionParticipantIds = [...activeMemberIds];
} else if (req.surface === "web" && req.conversation.kind !== "dm") {
if (!conversationRef || !(await mayUseSharedScope(req.conversation.kind, conversationRef, actor))) {
return { status: "refused", reason: "you're not a member of that context" };
}
}
if (req.surface === "webhook" && req.triggered && !sessionParticipantIds) {
sessionParticipantIds = [actor.id];
}
if (isSubagentThreadRef(req.conversation.threadRef)) {
const target = await deps.sessions.getByThread(req.conversation.threadRef);
if (
!target?.spawnMeta ||
target.scopeId !== conversationScope(req.conversation, actor.id) ||
!(await deps.sessions.getForParticipant(target.id, actor.id)) ||
!(await h.principalCanWriteScope(actor.id, target.scopeId))
)
return { status: "refused", reason: "you cannot continue that subagent session" };
}
const orgRuntimeScope = scopeId("org", orgIdOf());
const turnRuntimeScope =
req.conversation.kind === "dm"
? scopeId("personal", actor.id)
: scopeId(req.conversation.kind, req.conversation.channelRef ?? req.conversation.threadRef);
const [storedOrgRuntime, storedTurnRuntime] = await Promise.all([
deps.config.getRuntimeSelectionDurable(orgRuntimeScope),
turnRuntimeScope === orgRuntimeScope ? null : deps.config.getRuntimeSelectionDurable(turnRuntimeScope),
]);
const needsOpenRouterCatalog = [storedOrgRuntime?.modelId, storedTurnRuntime?.modelId].some(
(modelId) => modelId && !resolveModel(modelId),
);
if (needsOpenRouterCatalog && deps.modelCredentials && (await deps.modelCredentials.availability()).openrouter) {
await selectableModelCatalog(deps.modelCredentialFetch);
}
async function withCurrentProjectRoster<T>(fn: () => Promise<T>): Promise<T | null> {
if (!projectId || !deps.projects) return fn();
if (!conversationRef || !projectVersion) return null;
return (await deps.projects.withVersion(conversationRef, projectVersion, fn)) ?? null;
}
const approvedRequest = req.approval ? (await deps.approvals?.get(req.approval.requestId))?.request : undefined;
const sameApprovedMessage =
approvedRequest?.text === req.text &&
approvedRequest.actor.externalId === req.actor.externalId &&
approvedRequest.conversation.threadRef === req.conversation.threadRef;
let privateRequest = req.privateSessionMessage ? req : undefined;
if (approvedRequest?.privateSessionMessage) privateRequest = approvedRequest;
const origin = resolveTurnOrigin(privateRequest ?? req);
const sessionTurn =
(req.spawned && isSessionTurn(req)) ||
(sameApprovedMessage && approvedRequest && isSessionTurn(approvedRequest));
const modelAccount =
!req.externalSlack && deps.userModelCredentials && origin.kind === "human" && !sessionTurn
? await deps.config.getModelAccountDurable(actor.id)
: "company";
const individualAuth = modelAccount !== "company";
const runtimePurpose = turnRuntimePurpose(req, isSubagentThreadRef(req.conversation.threadRef));
if (req.triggered && (req.model || req.harness)) {
const choices = await runtimeConfigBody(
{ deps },
conversationScope(req.conversation, actor.id),
undefined,
runtimePurpose,
{
...(req.harness && isHarnessId(req.harness) ? { harnessId: req.harness } : {}),
...(req.model ? { modelId: req.model } : {}),
...(req.thinkingLevel ? { effortLevel: req.thinkingLevel } : {}),
...(typeof req.fastMode === "boolean" ? { fastMode: req.fastMode } : {}),
},
);
const harness = req.harness ?? choices.effective.harnessId;
const model = req.model ?? choices.effective.modelId;
const error = !isHarnessId(harness)
? "harness_not_approved"
: await availableRuntimeError(
{ deps },
conversationScope(req.conversation, actor.id),
{
harnessId: harness,
modelId: model,
effortLevel: req.thinkingLevel,
fastMode: req.fastMode,
},
runtimePurpose,
);
if (error) return { status: "refused", reason: error };
}
let requestedModel = req.model;
let requestedHarness = req.harness;
if (req.surface === "web") {
const threadRef = req.conversation.threadRef;
const existing = await deps.sessions.getByThread(threadRef);
if (existing) {
const claimed = conversationScope(req.conversation, actor.id);
if (existing.scopeId !== claimed) {
return { status: "refused", reason: "that conversation lives in a different context" };
}
if (!(await h.mayWriteSession(actor.id, existing)))
return { status: "refused", reason: "you can't continue that conversation from the web" };
} else if (threadRef.startsWith("web:") && !threadRef.startsWith(`web:${actor.id}:`)) {
return { status: "refused", reason: "you can only start a new conversation on your own thread" };
}
const org = scopeId("org", orgIdOf());
const targetScope = conversationScope(req.conversation, actor.id);
const fallbackHarness = harnessIdOrPi(deps.harnessId);
const runtimeFallback = deps.runtimeFallback ?? {
harnessId: fallbackHarness,
modelId: defaultModelForHarness(fallbackHarness),
};
if (individualAuth && (req.model || req.harness)) {
const available = await userRuntimeConfigBody({ deps }, targetScope, actor.id);
const harness = req.harness ?? available.effective.harnessId;
const model = req.model ?? available.effective.modelId;
if (!available.modelsByHarness[harness]?.includes(model))
return { status: "refused", reason: "Your connected AI account cannot serve this model on that harness." };
const invalidModelOption = validateWebTurnModelOptions(
{ ...req, model },
available.modelsByHarness[harness] ?? [],
);
if (invalidModelOption) return { status: "refused", reason: invalidModelOption };
requestedModel = model;
requestedHarness = harness;
}
if (!individualAuth) {
const configuredKeys = deps.providerKeys ??
deps.modelProviders ?? { anthropic: false, openai: false, openrouter: false };
const managedKeys = deps.modelCredentials ? await deps.modelCredentials.availability() : configuredKeys;
let orgRuntime;
let runtime;
try {
const orgModel =
storedOrgRuntime?.modelId ?? (await deps.config.getBaseModelOwnDurable(org)) ?? runtimeFallback.modelId;
orgRuntime = modelUnavailableReason(orgModel)
? { harnessId: storedOrgRuntime?.harnessId ?? runtimeFallback.harnessId, modelId: orgModel }
: await resolveRuntimeChoiceDurable(deps.config, org, org, runtimeFallback);
runtime = await resolveRuntimeChoiceDurable(
deps.config,
org,
targetScope,
runtimeFallback,
{
...(req.harness && isHarnessId(req.harness) ? { harnessId: req.harness } : {}),
...(req.model ? { modelId: req.model } : {}),
...(req.thinkingLevel ? { effortLevel: req.thinkingLevel } : {}),
...(typeof req.fastMode === "boolean" ? { fastMode: req.fastMode } : {}),
},
undefined,
runtimePurpose,
);
} catch (error) {
swallow("turn: runtime resolution", error);
return { status: "refused", reason: `I couldn't set up that runtime choice — ${GENERIC_FAILURE_CLAUSE}` };
}
if (req.harness && !isHarnessId(req.harness)) {
return { status: "refused", reason: `runtime ${req.harness} is not approved` };
}
let providers = deps.modelProviders;
if (deps.modelCredentials) {
providers = modelProviderAvailabilityFor(runtime.harnessId, configuredKeys, managedKeys);
} else if (deps.providerKeys) {
providers = modelProviderAvailabilityFor(runtime.harnessId, configuredKeys);
}
if (providers && !modelServiceable(runtime.modelId, providers)) {
return {
status: "refused",
reason: "that model isn't available on this deployment (its provider isn't configured)",
};
}
const configuredWebuiModels = await deps.config.getWebuiModelsDurable(org);
let enabledWebuiModels: string[] | null = null;
if (configuredWebuiModels != null) {
enabledWebuiModels = configuredWebuiModels.length
? [...new Set([...configuredWebuiModels, orgRuntime.modelId])]
: [];
} else if (providers?.openrouter) {
enabledWebuiModels = [
...new Set([
...selectableCatalogForHarness(
await selectableModelCatalog(deps.modelCredentialFetch),
runtime.harnessId,
)
.filter((model) => modelOfferedInWebui(model.id))
.map((model) => model.id),
...(orgRuntime.harnessId === runtime.harnessId ? [orgRuntime.modelId] : []),
]),
];
}
const invalidModelOption = validateWebTurnModelOptions(req, enabledWebuiModels, providers);
if (invalidModelOption) return { status: "refused", reason: invalidModelOption };
}
}
const rawAudience = req.conversation.audience ?? [req.actor];
const audience: Principal[] =
projectAudience ??
rawAudience.map((a) => {
const p = deps.identity.classify(a.externalId, a.isExternalGuest);
if (p.id === actor.id) return actor;
return a.displayName ? { ...p, displayName: a.displayName } : p;
});
if (!audience.some((p) => p.id === actor.id)) audience.push(actor);
const publishMembers =
projectAudience ??
req.conversation.publishMembers?.map((a) => deps.identity.classify(a.externalId, a.isExternalGuest));
const conversation: Conversation = {
kind: req.conversation.kind,
threadRef: req.conversation.threadRef,
...(req.conversation.channelRef ? { channelRef: req.conversation.channelRef } : {}),
...(projectName || req.conversation.channelName
? { channelName: projectName ?? req.conversation.channelName }
: {}),
audience,
...(req.conversation.isPrivate !== undefined ? { isPrivate: req.conversation.isPrivate } : {}),
...(req.conversation.isMpim !== undefined ? { isMpim: req.conversation.isMpim } : {}),
...(publishMembers ? { publishMembers } : {}),
};
const input = {
surface: req.surface,
...(req.slackSource ? { slackSource: req.slackSource } : {}),
...(req.externalSlack ? { externalSlack: req.externalSlack } : {}),
...(req.spawned && req.sessionSenderId ? { sessionSenderId: req.sessionSenderId } : {}),
...(req.spawned && req.delegatingRunId ? { delegatingRunId: req.delegatingRunId } : {}),
...(sameApprovedMessage && approvedRequest?.sessionSenderId
? { sessionSenderId: approvedRequest.sessionSenderId }
: {}),
...(sameApprovedMessage && approvedRequest?.delegatingRunId
? { delegatingRunId: approvedRequest.delegatingRunId }
: {}),
...(req.deliveryTarget ? { deliveryTarget: req.deliveryTarget } : {}),
...(req.deliveryCandidates?.length ? { deliveryCandidates: req.deliveryCandidates } : {}),
actor,
conversation,
origin,
modelAccount: origin.kind === "human" ? modelAccount : ("company" as const),
text: req.text,
...(req.gatewayContext ? { gatewayContext: req.gatewayContext } : {}),
...(req.proactiveOpener ? { proactiveOpener: true } : {}),
...(req.analyticsSuppressed || (sameApprovedMessage && approvedRequest?.analyticsSuppressed)
? { analyticsSuppressed: true }
: {}),
...(req.conversationHeader ? { conversationHeader: req.conversationHeader } : {}),
...(req.priorTurns?.length ? { priorTurns: req.priorTurns } : {}),
...(req.overheard?.length ? { overheard: req.overheard } : {}),
...(req.detectContext ? { detectContext: req.detectContext } : {}),
...(req.detectOpener ? { detectOpener: req.detectOpener } : {}),
...(req.attachments?.length ? { attachments: req.attachments } : {}),
...(req.inboundNotes?.length ? { inboundNotes: req.inboundNotes } : {}),
...((!individualAuth || req.surface === "web") && requestedHarness ? { harness: requestedHarness } : {}),
...((!individualAuth || req.surface === "web") && requestedModel ? { model: requestedModel } : {}),
...turnModelOptions(req),
...(req.readOnly ? { readOnly: true } : {}),
...(privateRequest
? {
privateSessionMessage: true as const,
sessionMessageDepth: privateRequest.sessionMessageDepth,
readOnly: true,
}
: {}),
...(req.skipMemory ? { skipMemory: true } : {}),
...(req.unattendedGrants?.length ? { unattendedGrants: req.unattendedGrants } : {}),
...(req.botActor ? { botActor: true } : {}),
...(req.surfaceTools ? { surfaceTools: true } : {}),
...(req.clientTools?.length ? { clientTools: req.clientTools } : {}),
desktopClientId: desktopClientForTurn({ ...req, origin }),
...(req.envelopeWrapped ? { envelopeWrapped: true } : {}),
...(typeof req.displayText === "string" && req.displayText ? { displayText: req.displayText } : {}),
...(req.addressed || origin.kind === "human" ? { addressed: true } : {}),
...(typeof req.turnWallClockMs === "number" ? { turnWallClockMs: req.turnWallClockMs } : {}),
...(typeof req.timezone === "string" && req.timezone ? { timezone: req.timezone } : {}),
...(req.approval ? { approval: req.approval } : {}),
...(sessionParticipantIds ? { sessionParticipantIds } : {}),
...(projectVersion ? { scopeVersion: projectVersion } : {}),
};
if (projectGroup && req.approval) {
const [approval, approvalSession] = await Promise.all([
deps.approvals?.get(req.approval.requestId),
deps.sessions.getByThread(conversation.threadRef),
]);
if (!approvalSession || (await approvalResumable(approvalSession, actor.id, approval)) !== "ok") {
return { status: "refused", reason: "approval isn't visible in your project tenure" };
}
}
const blocked = await pendingApprovalResultForThread(conversation.threadRef, actor.id, { alwaysBlock: true });
let request = input;
if (blocked) {
const record = req.approval ? await deps.approvals?.get(req.approval.requestId) : undefined;
const blockedSession = blocked.sessionId ? await deps.sessions.get(blocked.sessionId) : null;
let cause: Awaited<ReturnType<typeof approvalResumable>> | "no_session" | "nonblocking" = blockedSession
? await approvalResumable(blockedSession, actor.id, record)
: "no_session";
if (cause === "ok" && record?.blocksInput === false) cause = "nonblocking";
if (cause !== "ok") {
if (req.approval) {
deps.auditLog.record({
at: Date.now(),
principalId: actor.id,
action: `command_approval.${req.approval.approved ? "approve" : "deny"}`,
resource: req.approval.requestId,
scopeLabel: blockedSession?.scopeId ?? conversation.threadRef,
status: "refused",
detail: JSON.stringify({ approvalOutcome: "sealed_thread", cause }),
});
}
return blocked;
}
}
const redeliveryKey = req.approval ? undefined : req.redeliveryKey;
if (redeliveryKey && deps.signals) {
const prior = await deps.runs.getByDedupKey(redeliveryKey);
if (prior) {
if (prior.request.conversation.threadRef !== conversation.threadRef)
console.error(
`[turn] redelivery ${redeliveryKey} names ${conversation.threadRef} but its run lives in ${prior.request.conversation.threadRef}`,
);
return { status: "silent" };
}
if (await deps.signals.hasDedupeKey(redeliveryKey)) return { status: "silent" };
}
let dedupKey: string | undefined = redeliveryKey;
if (req.idempotencyKey) {
dedupKey =
projectVersion === undefined ? req.idempotencyKey : `${req.idempotencyKey}:project-${projectVersion}`;
if (req.approval) dedupKey = `${dedupKey}:approval:${req.approval.requestId}:${req.approval.approved}`;
}
if (replay) dedupKey = replay.signalDedupKey;
if (origin.kind === "human" && !isSessionTurn(input) && !req.approval) deps.reaperPoke?.();
if (
req.surface !== "web" &&
deps.signals &&
(origin.kind === "human" || origin.kind === "ambient") &&
!req.approval &&
!req.spawned &&
!req.idempotencyKey
) {
const live = await deps.runs.activeForThread(conversation.threadRef);
const liveOriginKind = live ? resolveTurnOrigin(live.request).kind : undefined;
const personIntoAutomation =
liveOriginKind === "automation" &&
(origin.kind === "human" || (origin.kind === "ambient" && origin.live === true)) &&
!(origin.kind === "human" && isHalt(req.text));
if (live && redeliveryKey && live.dedupKey === redeliveryKey) return { status: "silent" };
const sameAccount =
live?.request.modelAccount !== undefined &&
live.request.modelAccount === input.modelAccount &&
(input.modelAccount === "company" || live.request.actor.id === actor.id);
const cancel = origin.kind === "human" && isHalt(req.text);
if (live && !isTerminal(live.status) && !personIntoAutomation && (cancel || sameAccount)) {
const targetRun = live;
const steerText = attributedSteerText(
actor,
origin.kind === "ambient" ? null : targetRun.request.actor.id,
req.text,
);
let injectedText = steerText;
if (origin.kind === "ambient") {
const session = await deps.sessions.getByThread(conversation.threadRef);
const decision = await deps.orchestrator.screenSecuritySteer({
payload: steerText,
actor,
conversation,
...(session ? { sessionId: session.id } : {}),
});
if (decision === "block")
return req.async ? { status: "queued", runId: targetRun.id, steered: true } : drive(targetRun.id);
if (decision === "unscreened") injectedText = `${unscreenedNotice("mid-turn message")}\n${steerText}`;
}
const fileNames = (req.attachments ?? []).map((a) =>
a.sourceId
? `${a.name} (fetch via surface-file, ts ${origin.kind === "human" ? (origin.messageTs ?? origin.entryTs) : origin.entryTs})`
: a.name,
);
const wake: Wake = {
situation: origin.kind === "ambient" ? "ambientUpdate" : "addressed",
ts: String(Date.now()),
text: injectedText,
halt: origin.kind === "human" && isHalt(req.text),
...(fileNames.length ? { fileNames } : {}),
};
const route = routeWake(wake, true, resolveTurnOrigin(targetRun.request).kind === "ambient");
if (route.kind === "steer" || route.kind === "drop") {
const steerTs = origin.kind === "human" ? (origin.messageTs ?? origin.entryTs) : origin.entryTs;
let redelivered = false;
const routedRunId = await withCurrentProjectRoster(async () => {
if (route.kind === "steer" && route.signal === "abort") {
await stopRunTree(targetRun);
} else if (route.kind === "steer")
redelivered = !(await deps.signals!.send(targetRun.id, {
kind: route.signal,
...(route.text ? { text: route.text } : {}),
...(steerTs ? { ts: steerTs } : {}),
...(route.signal === "steer" ? { request: req } : {}),
...(redeliveryKey ? { dedupeKey: redeliveryKey } : {}),
}));
return targetRun.id;
});
if (!routedRunId)
return { status: "refused", reason: "project membership changed; retry from the current project" };
if (redelivered)
return req.async ? { status: "queued", runId: routedRunId, steered: true } : drive(routedRunId);
if (route.kind === "steer") {
const after = await deps.runs.get(targetRun.id);
if (!after || isTerminal(after.status)) {
const own = (await replayOrphanedRunSignals(targetRun.id)).find(
(d) =>
(d.signal.text === route.text ||
(route.text !== undefined && d.signal.text === pgTextSafe(route.text))) &&
d.signal.ts === steerTs,
);
if (own?.replayRunId)
return req.async ? { status: "queued", runId: own.replayRunId } : drive(own.replayRunId);
}
}
return req.async ? { status: "queued", runId: routedRunId, steered: true } : drive(routedRunId);
}
}
}
const spineRouted = !req.externalSlack && !req.approval && shouldRouteToSpine(request as OrchestratorInput);
if (spineRouted) {
request = { ...input, surfaceTools: true };
if (origin.kind !== "ambient")
request = {
...request,
text: await addressedWakeText(input as OrchestratorInput),
displayText: input.text,
envelopeWrapped: true,
};
}
if (spineRouted && origin.kind === "human" && !req.spawned && !req.idempotencyKey && origin.messageTs) {
const container = conversation.channelRef ?? conversation.threadRef;
const ambientRef = `${req.surface}:${container}:ambient:${origin.messageTs}`;
const ambientSession = await deps.sessions.getByThread(ambientRef);
if (ambientSession) {
const liveAmbient = await deps.runs.activeForThread(ambientRef);
if (
liveAmbient &&
!isTerminal(liveAmbient.status) &&
input.modelAccount === "company" &&
liveAmbient.request.modelAccount === "company"
) {
const routedRunId = await withCurrentProjectRoster(async () => {
if (deps.signals)
await deps.signals.send(liveAmbient.id, {
kind: "steer",
text: req.text,
ts: origin.messageTs,
request: req,
...(redeliveryKey ? { dedupeKey: redeliveryKey } : {}),
});
return liveAmbient.id;
});
if (!routedRunId)
return { status: "refused", reason: "project membership changed; retry from the current project" };
const after = await deps.runs.get(liveAmbient.id);
if (!after || isTerminal(after.status)) {
const own = (await replayOrphanedRunSignals(liveAmbient.id)).find(
(d) =>
(d.signal.text === req.text || d.signal.text === pgTextSafe(req.text)) &&
d.signal.ts === origin.messageTs,
);
if (own?.replayRunId)
return req.async ? { status: "queued", runId: own.replayRunId } : drive(own.replayRunId);
}
// Deliberately NOT flagged `steered`. Unlike the mid-turn branch above, this run's owner
// is the UNPROMPTED ambient handler, which stays silent on a refusal or failure
// (bystander restraint) and whose recovery copy is suppressed for the same reason. The
// addressed caller is the only one that would ever report that, so standing it down
// would trade a duplicate reply for silence on a message someone actually addressed.
return req.async ? { status: "queued", runId: routedRunId } : drive(routedRunId);
}
}
}
const enqueue = () =>
deps.runs.enqueue({
sessionId: conversation.threadRef,
request,
maxAttempts: deps.maxAttempts,
...(dedupKey ? { dedupKey } : {}),
});
const enqueueStartedAt = performance.now();
const enqueued = await withCurrentProjectRoster(enqueue);
if (!enqueued) return { status: "refused", reason: "project membership changed; retry from the current project" };
const { run, deduped } = enqueued;
console.info("[turn] queued", {
runId: run.id,
preEnqueueMs: Math.round(enqueueStartedAt - startedAt),
enqueueMs: Math.round(performance.now() - enqueueStartedAt),
});
if (deduped && redeliveryKey && run.dedupKey === redeliveryKey) return { status: "silent" };
if (spineRouted && !deduped) markTriggerHandled(input as OrchestratorInput);
if (spineRouted) deps.engaged?.engage(conversation.threadRef);
if (deduped && run.result && isTerminal(run.status)) return withAdminLink(run.result);
if (req.async) return { status: "queued", runId: run.id };
return drive(run.id);
},
subscribeSessionStates(cb, opts) {
if (!deps.sessionStateBus) return () => {};
const lookupParticipants = async (threadRef: string): Promise<string[]> => {
const session = await deps.sessions.getByThread(threadRef);
return session ? deps.sessions.participantsOf(session.id) : [];
};
const rehydrate = async (event: SessionStateEvent): Promise<SessionStateEvent> => {
if (!event.participantsShed) return event;
const { participantsShed: _shed, ...bare } = event;
const participants = await Promise.race([
lookupParticipants(event.threadRef),
sleep(PARTICIPANT_REHYDRATE_TIMEOUT_MS, { unref: true }).then(() => null),
]).catch(swallowAs("session-state: rehydrate participants", null));
return participants?.length ? { ...bare, participants } : bare;
};
let tail: Promise<void> = Promise.resolve();
const queue = (step: () => void | Promise<void>): void => {
tail = tail.then(step).catch(swallowAs("session-state: subscriber", undefined));
};
const onResync = opts?.onResync;
return deps.sessionStateBus.subscribe(
(event) => queue(async () => cb(await rehydrate(event))),
onResync ? { onResync: () => queue(onResync) } : undefined,
);
},
subscribeLedgerEvents(cb, opts) {
return deps.ledgerEventBus?.subscribe(cb, opts) ?? (() => {});
},
async getApproval(requestId, viewer) {
const record = await deps.approvals?.get(requestId);
if (!record || !(await approvalRecordIsCurrent(record))) return null;
if (viewer) {
const session = await deps.sessions.get(record.sessionId);
if (!session || !(await approvalVisibleToViewer(session, viewer, record))) return null;
}
return { requestId, ...record };
},
async listSessionApprovals(sessionId, viewer) {
if (!(await sessionForViewer(sessionId, viewer))) return [];
return pendingApprovalForSession(sessionId, { blockingOnly: false, viewer });
},
pendingApprovalForThread(threadRef, viewer) {
return pendingApprovalResultForThread(threadRef, viewer);
},
subscribeRun(runId, listener, onResync) {
return (
deps.runStreamEvents?.subscribe(
(event) => {
if (event.runId === runId) listener(event);
},
{ onResync },
) ?? (() => {})
);
},
syncRunStream(runId, offset, reasoning) {
deps.runStreamEvents?.emit({ runId, kind: "sync", offset, reasoning });
},
async getRun(runId, viewer) {
const run = await deps.runs.get(runId);
if (!run) return null;
if (viewer && !(await viewerMayUseRun(run, viewer))) return null;
const partial = deps.turnStream?.snapshot(runId);
const goal = deps.turnStream?.goal(runId);
const runtime = deps.turnStream?.runtime(runId) ?? run.result?.runtime;
const firstBlock = deps.turnStream?.firstBlock(runId);
const surfacePosted = deps.turnStream?.surfacePosted(runId) ?? false;
const alive = run.status === "running" && !leaseLapsed(run, Date.now());
const replying = deps.turnStream?.replying(runId) ?? false;
const replyComplete = deps.turnStream?.isReplyDone(runId) ?? false;
const activity = await deps.runActivity?.list(runId);
const reasoning = deps.turnStream?.reasoning(runId) ?? [];
const stale =
run.status === "pending" ? run.attempts > 0 : !alive && leaseLapsed(run, Date.now() - STALE_LEASE_GRACE_MS);
return {
desktopClientId: desktopClientForTurn({ ...run.request, attempt: run.attempts }),
status: run.status,
attempt: run.attempts,
result: run.result ? await withAdminLink(run.result) : run.result,
...(run.request.surface === "web" &&
!run.request.approval &&
!run.request.envelopeWrapped &&
!(run.request.proactiveOpener && !run.request.text.trim()) &&
isPersonAuthored(resolveTurnOrigin(run.request).kind)
? {
input: {
runId: run.id,
seq: run.turnUserSeq,
text: run.request.displayText ?? run.request.text ?? "",
createdAt: run.createdAt,
...(run.request.attachments?.length
? {
attachments: run.request.attachments.map(({ name, mimetype, sizeBytes }) => ({
name,
mimetype,
sizeBytes,
})),
}
: {}),
},
}
: {}),
startedAt: run.startedAt,
finishedAt: run.finishedAt,
...(goal ? { goal } : {}),
...(runtime ? { runtime } : {}),
...(partial ? { partial, partialStartOffset: deps.turnStream!.startOffset(runId) } : {}),
...(firstBlock
? { firstBlock: firstBlock.text, ...(firstBlock.closed ? { firstBlockClosed: true } : {}) }
: {}),
...(surfacePosted ? { surfacePosted: true } : {}),
...(alive ? { alive: true } : {}),
...(stale ? { stale: true } : {}),
...(replying ? { replying: true } : {}),
...(replyComplete ? { replyComplete: true } : {}),
...(activity && activity.length ? { activity } : {}),
...(reasoning.length ? { reasoning } : {}),
};
},
async getRunToolEntries(runId, viewer, afterSeq) {
const run = await deps.runs.get(runId);
if (!run || run.turnUserSeq === null) return [];
if (viewer && !(await viewerMayUseRun(run, viewer))) return [];
const session = await deps.sessions.getByThread(run.sessionId);
if (!session) return [];
const entries = await deps.sessions.getEntries(session.id, {
sinceSeq: Math.max(run.turnUserSeq, (afterSeq ?? -1) + 1),
});
const nextRun = entries.findIndex((e) => {
const owner = (e.payload as { runId?: unknown } | null)?.runId;
return e.type === "user" && typeof owner === "string" && owner !== runId;
});
return entries
.slice(0, nextRun < 0 ? undefined : nextRun)
.filter((e) => e.type === "tool_call" || e.type === "tool_result");
},
async stopConversation(threadRef, viewer) {
const stop = async () => {
const session = await deps.sessions.getByThread(threadRef);
if (!session || !deps.signals || (viewer && !(await sessionForViewer(session.id, viewer)))) return false;
return stopSessionTree({ sessions: deps.sessions, runs: deps.runs, signals: deps.signals }, session, USER_STOP);
};
return deps.advisoryLock ? deps.advisoryLock.withLock("session-tree-admission", stop) : stop();
},
async activeRunForThread(threadRef, viewer) {
const inFlight = await deps.runs.inFlightForThread(threadRef);
const visible: typeof inFlight = [];
for (const run of inFlight) if (!viewer || (await viewerMayUseRun(run, viewer))) visible.push(run);
const live = visible[0];
if (!live) return null;
const queued = visible
.slice(1)
.filter((run) => isPersonAuthored(resolveTurnOrigin(run.request).kind))
.map((run) => ({
runId: run.id,
text: run.request.displayText ?? run.request.text ?? "",
...(run.request.attachments?.length ? { hasAttachments: true } : {}),
}));
return { runId: live.id, ...(queued.length ? { queued } : {}) };
},
async editQueuedRun(runId, text, expectedText, viewer) {
const run = await deps.runs.get(runId);
if (!run || (viewer && (!samePerson(run.request.actor.id, viewer) || !(await viewerMayUseRun(run, viewer)))))
return { edited: false, reason: "not_found" };
if (
run.request.surface !== "web" ||
run.request.envelopeWrapped ||
!isPersonAuthored(resolveTurnOrigin(run.request).kind)
)
return { edited: false, reason: "not_editable" };
if (!text.trim() && !run.request.attachments?.length) return { edited: false, reason: "empty_text" };
return (await deps.runs.editPendingText(runId, text, expectedText))
? { edited: true }
: { edited: false, reason: "changed_or_started" };
},
async withdrawRun(runId, viewer) {
const run = await deps.runs.get(runId);
if (!run) return { withdrawn: false, reason: "not_found" };
if (viewer && !(await viewerMayUseRun(run, viewer))) return { withdrawn: false, reason: "not_found" };
return (await deps.runs.withdraw(runId)) ? { withdrawn: true } : { withdrawn: false, reason: "started" };
},
async signalRun(runId, signal, viewer) {
if (!deps.signals) return { accepted: false, reason: "signals_unavailable" };
const run = await deps.runs.get(runId);
if (!run) return { accepted: false, reason: "not_found" };
if (viewer && !(await viewerMayUseRun(run, viewer))) return { accepted: false, reason: "not_found" };
if (
signal.kind === "steer" &&
run.request.surface === "web" &&
/^web:.+:inbox$/.test(run.request.conversation.threadRef) &&
!signal.request
)
return { accepted: false, reason: "conversation_mismatch" };
const queuedKey = signal.queuedRunId
? `queued-steer:${run.request.conversation.threadRef}:${signal.queuedRunId}`
: undefined;
if (queuedKey && (await deps.signals.hasDedupeKey(queuedKey))) return { accepted: true };
if (isTerminal(run.status)) return { accepted: false, reason: "terminal" };
if (signal.kind === "abort") {
const accepted = await stopRunTree(run);
return accepted ? { accepted: true } : { accepted: false, reason: "terminal" };
}
if (signal.kind === "client_result") {
if (viewer && !samePerson(run.request.actor.id, viewer)) return { accepted: false, reason: "not_found" };
if (!run.request.clientTools?.length && !run.request.desktopClientId)
return { accepted: false, reason: "no_client_tools" };
const sent = await deps.signals.send(runId, {
kind: "client_result",
callId: signal.callId,
result: signal.result,
dedupeKey: `client:${runId}:${signal.callId}`,
});
return sent ? { accepted: true } : { accepted: false, reason: "duplicate" };
}
if (signal.queuedRunId) {
const queued = await deps.runs.get(signal.queuedRunId);
if (!queued || (viewer && !(await viewerMayUseRun(queued, viewer))))
return { accepted: false, reason: "not_found" };
if (
signal.kind !== "steer" ||
!signal.request ||
queued.request.conversation.threadRef !== run.request.conversation.threadRef
)
return { accepted: false, reason: "conversation_mismatch" };
if (queued.id === run.id || queued.status !== "pending") return { accepted: false, reason: "queued_started" };
const text = queued.request.displayText ?? queued.request.text;
signal = {
...signal,
text,
ts: queuedKey,
dedupeKey: queuedKey,
request: { ...signal.request, text, attachments: queued.request.attachments, idempotencyKey: queuedKey },
};
}
if (signal.kind === "steer" && !signal.text?.trim() && !signal.request?.attachments?.length) {
return { accepted: false, reason: "text_required" };
}
if (signal.request && signal.request.conversation.threadRef !== run.request.conversation.threadRef) {
return { accepted: false, reason: "conversation_mismatch" };
}
if (signal.kind === "steer") {
const principal = viewer ?? signal.request?.actor.externalId ?? run.request.actor.id;
const account = principal ? await deps.config.getModelAccountDurable(principal) : undefined;
if (
!account ||
run.request.modelAccount !== account ||
(account !== "company" && run.request.actor.id !== principal)
) {
return { accepted: false, reason: "account_changed: send a new message to use your selected AI account" };
}
}
let outbound = signal;
if (signal.kind === "steer") {
const requestActor = signal.request?.actor;
let steerer: { id: string; displayName?: string | undefined } | undefined;
if (requestActor) steerer = { id: requestActor.externalId, displayName: requestActor.displayName };
else if (viewer) {
steerer = { id: viewer, displayName: (await deps.directory.get(viewer).catch(() => null))?.displayName };
}
outbound = {
...signal,
ts: signal.ts ?? `${Date.now()}.${crypto.randomUUID().slice(0, 8)}`,
...(steerer ? { text: attributedSteerText(steerer, run.request.actor.id, signal.text ?? "") } : {}),
};
}
if (signal.queuedRunId) {
if (!(await deps.runs.steerQueued(signal.queuedRunId, runId, outbound, deps.signals))) {
if (await deps.signals.hasDedupeKey(queuedKey!)) return { accepted: true };
const queued = await deps.runs.get(signal.queuedRunId);
return { accepted: false, reason: queued?.status === "pending" ? "queued_changed" : "queued_started" };
}
} else await deps.signals.send(runId, outbound);
const after = await deps.runs.get(runId);
if (!after || isTerminal(after.status)) {
const drained = await replayOrphanedRunSignals(runId);
if (signal.kind !== "steer") return { accepted: false, reason: "terminal" };
// The steer was stored before the run went terminal, so its text is replayed as
// a fresh turn (by this drain, the onTerminal hook, or the orphan sweeper —
// whoever drains first). Tell the caller so it attaches to the fresh run
// instead of treating the message as lost.
const own = drained.find((d) => d.signal.ts === outbound.ts);
if (own && !own.replayRunId) return { accepted: false, reason: "terminal" };
return { accepted: false, reason: "terminal", replayed: true };
}
return { accepted: true };
},
replayOrphanedRunSignals(runId) {
return replayOrphanedRunSignals(runId).then(() => undefined);
},
};
}