Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

46.2 KB
Raw Blame
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);
    },
  };
}