Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

15.6 KB
Raw Blame
import type { DeliveryProvenance, Destination, Principal, ScopeId, TurnRequest, TurnResult } from "../types.ts";
import { actsAsScope, parseScopeId } from "../types.ts";
import type { IdentityService } from "../identity/identity-service.ts";
import type { DeliveryStore } from "../delivery/delivery-store.ts";
import type { IdempotencyStore } from "../idempotency/idempotency-store.ts";
import { turnModelOptions } from "../core/turn-options.ts";
import { userFacingFailureClause } from "../core/failure-copy.ts";
import { reachEnqueue } from "../reach/reach.ts";
import { isVisible, type VisibilityDirectory } from "../directory/visibility.ts";
import type { DirectoryMember, DirectoryStore, RecipientResolution } from "../directory/directory-store.ts";
import { samePerson } from "../directory/person.ts";
import { grantsStayWithOwner } from "../cron/authority.ts";
import type { CurrentScopeMembers } from "../resolution/scope-membership.ts";
import { isProjectGroupRef } from "../projects/project-store.ts";
import { reportFailureAs, swallowAs } from "../util/errors.ts";

const MEMBERSHIP_SKIP_NOTE = "the acting person is no longer a member of this trigger's home scope — run skipped";
const UNKNOWN_HOME_SKIP_NOTE =
  "this trigger's home scope is missing from the directory snapshot (roster sync gap) and the acting person has no session there — run skipped";

export interface TriggerDeps {
  deliveries: DeliveryStore;
  idempotency: IdempotencyStore;
  identity: IdentityService;
  run: (req: TurnRequest) => Promise<TurnResult>;
  currentScopeMembers?: CurrentScopeMembers;
  directory?: VisibilityDirectory & {
    get(principalId: string): Promise<{ displayName: string; principalId?: string; slackId?: string } | null>;
    channelPrivacy?(channelId: string): Promise<boolean | undefined>;
    groupMembership?(groupId: string, principalId: string): Promise<boolean | undefined>;
    conversationMembers?: DirectoryStore["conversationMembers"];
  };
  sessions?: { participantScopes(principalId: string): Promise<readonly { scopeId: ScopeId }[]> };
  resolveRecipient?: (query: string) => Promise<RecipientResolution>;
}

export interface TriggerSpec extends Pick<TurnRequest, "model" | "harness" | "fastMode" | "attachments"> {
  runtime?: import("../harness/harness.ts").RuntimeChoice | null;
  title?: string;
  owner: string;
  ownerScopeId: ScopeId;
  input: string | ((homeRoster: DirectoryMember[] | undefined) => string);
  securityScreenData?: string;
  fireKey: string;
  surface: string;
  destination?: Destination;
  message?: string;
  threadRef?: string;
  unattendedGrants?: string[];
  shadow?: boolean;
  thinkingLevel?: string;
  readOnly?: boolean;
  turnWallClockMs?: number;
  errorNotice?: (noteOrStatus: string) => string;
  onClaimed?: () => Promise<void>;
  deferWhenBusy?: boolean;
}

export interface TriggerOutcome {
  authzFailed: boolean;
  ownerLeft?: boolean;
  ran: boolean;
  deferred?: boolean;
  status?: TurnResult["status"];
  errorCode?: string;
  note?: string;
  userNote?: string;
  reply?: string;
  sessionId?: string;
}

class FireDeferred extends Error {
  constructor() {
    super("fire deferred: session busy");
  }
}

function isTriggerFailure(outcome: TriggerOutcome): boolean {
  return outcome.ran && outcome.status !== undefined && outcome.status !== "ok" && outcome.status !== "silent";
}

const POLL_SURFACES = new Set(["cron", "webhook", "monitor"]);
export const isPollSurface = (surface: string): boolean => POLL_SURFACES.has(surface);

function deliveryProvenance(spec: TriggerSpec, threadRef: string, res?: TurnResult): DeliveryProvenance {
  return {
    trigger: spec.surface,
    surface: spec.surface,
    fireKey: spec.fireKey,
    sourceScopeId: spec.ownerScopeId,
    sourceThreadRef: threadRef,
    ...(spec.title ? { sourceTitle: spec.title } : {}),
    ...(res?.sessionId ? { sourceSessionId: res.sessionId } : {}),
    ...(res?.sourceUserSeq !== undefined ? { sourceUserSeq: res.sourceUserSeq } : {}),
    ...(res?.sourceAssistantEntrySeq !== undefined ? { sourceAssistantEntrySeq: res.sourceAssistantEntrySeq } : {}),
  };
}

async function relayAttribution(deps: TriggerDeps, spec: TriggerSpec): Promise<string | undefined> {
  if (spec.message === undefined || !deps.directory) return undefined;
  const member = await deps.directory.get(spec.owner).catch(() => null);
  return member?.displayName;
}

async function participatesInScope(deps: TriggerDeps, actorId: string, scope: ScopeId): Promise<boolean> {
  const scopes = await deps.sessions?.participantScopes(actorId).catch(swallowAs("trigger: participant scopes", []));
  return scopes?.some((s) => s.scopeId === scope) === true;
}

async function actorMayReadScope(
  deps: TriggerDeps,
  actorId: string,
  kind: string | null,
  ref: string,
  scope: ScopeId,
  snapshotGap: boolean,
): Promise<{ ok: boolean; note?: string }> {
  if (!ref) return { ok: false, note: MEMBERSHIP_SKIP_NOTE };
  if (kind === "personal") return samePerson(actorId, ref) ? { ok: true } : { ok: false, note: MEMBERSHIP_SKIP_NOTE };
  if (!deps.directory)
    return kind !== "group" && kind !== "channel" ? { ok: true } : { ok: false, note: MEMBERSHIP_SKIP_NOTE };
  if (kind === "group") {
    if (await isVisible(deps.directory, actorId, { kind: "group", groupId: ref })) return { ok: true };
    if (snapshotGap) {
      if (await participatesInScope(deps, actorId, scope)) return { ok: true };
      return { ok: false, note: UNKNOWN_HOME_SKIP_NOTE };
    }
    const known = await deps.directory.groupMembership?.(ref, actorId).catch(() => undefined);
    if (known === undefined && (await participatesInScope(deps, actorId, scope))) return { ok: true };
    return { ok: false, note: MEMBERSHIP_SKIP_NOTE };
  }
  if (kind !== "channel") return { ok: true };
  const isPrivate = await deps.directory.channelPrivacy?.(ref);
  if (isPrivate === undefined) {
    if (await participatesInScope(deps, actorId, scope)) return { ok: true };
    return { ok: false, note: UNKNOWN_HOME_SKIP_NOTE };
  }
  if (await isVisible(deps.directory, actorId, { kind: "channel", channelId: ref, isPrivate })) return { ok: true };
  return { ok: false, note: MEMBERSHIP_SKIP_NOTE };
}

export async function destinationVisible(
  deps: TriggerDeps,
  actorId: string,
  destination: Destination,
): Promise<boolean> {
  if (!deps.directory) return true;
  const id = destination.target.split(":")[0]!;
  if (destination.type === "slack") {
    const audience = destination.audienceScopeId ? parseScopeId(destination.audienceScopeId) : undefined;
    if (audience?.kind === "personal") return isVisible(deps.directory, actorId, { kind: "dm", ownerId: audience.ref });
    if (audience?.kind === "group") return isVisible(deps.directory, actorId, { kind: "group", groupId: id });
    return isVisible(deps.directory, actorId, { kind: "channel", channelId: id });
  }
  if (destination.type === "group") return isVisible(deps.directory, actorId, { kind: "group", groupId: id });
  if (destination.type !== "principal" || samePerson(destination.target, actorId) || !deps.resolveRecipient)
    return true;
  const recipient = await deps.resolveRecipient(destination.target);
  return (
    recipient.kind === "one" &&
    (samePerson(recipient.member.principalId, destination.target) || recipient.member.slackId === destination.target)
  );
}

const SCHEDULED_SURFACES = new Set(["cron", "loop", "keychain-ask"]);

function homeRoster(
  kind: string | null,
  ref: string,
  isPrivate: boolean | undefined,
  roster: DirectoryMember[] | undefined,
  currentMembers: Principal[] | undefined,
): string[][] | undefined {
  if (kind === "channel" && isPrivate !== true) return undefined;
  const ids =
    roster?.map((m) => [m.principalId, ...(m.slackId ? [m.slackId] : [])]) ??
    (kind === "group" && isProjectGroupRef(ref) ? currentMembers?.map((m) => [m.id]) : undefined);
  return ids?.length ? ids : undefined;
}

export async function runTrigger(deps: TriggerDeps, spec: TriggerSpec): Promise<TriggerOutcome> {
  await deps.identity.refresh();
  const runsAsScope = actsAsScope(spec.owner, spec.ownerScopeId);
  const scheduled = SCHEDULED_SURFACES.has(spec.surface);
  const currentMembers = await deps.currentScopeMembers?.(spec.ownerScopeId);
  const actorId = spec.owner;
  if (!runsAsScope && deps.identity.classify(spec.owner).type !== "internal") {
    return { authzFailed: true, ran: false, note: "owner is no longer an internal principal" };
  }
  const audience =
    runsAsScope && currentMembers?.length
      ? currentMembers.map((m) => ({ externalId: m.id, ...(m.teamIds ? { teamIds: m.teamIds } : {}) }))
      : undefined;
  const { kind: ownerKind, ref: ownerRef } = parseScopeId(spec.ownerScopeId);
  const threadRef = spec.threadRef ?? spec.fireKey;
  let conversation: TurnRequest["conversation"] = { kind: "dm", threadRef };
  let roster: DirectoryMember[] | undefined;
  let isPrivate: boolean | undefined;
  if (ownerKind === "channel" || ownerKind === "group") {
    roster = await deps.directory
      ?.conversationMembers?.(ownerKind, ownerRef)
      .catch(reportFailureAs("trigger home roster", undefined));
    isPrivate =
      ownerKind === "channel"
        ? await deps.directory?.channelPrivacy?.(ownerRef).catch(reportFailureAs("trigger home privacy", undefined))
        : undefined;
    conversation = {
      kind: ownerKind,
      channelRef: ownerRef,
      threadRef,
      ...(isPrivate !== undefined ? { isPrivate } : {}),
      ...(audience ? { audience } : {}),
      ...(roster ? { publishMembers: roster.map((m) => ({ externalId: m.principalId })) } : {}),
    };
  }

  const members = runsAsScope ? undefined : homeRoster(ownerKind, ownerRef, isPrivate, roster, currentMembers);
  const ownerIsMember = members?.some((ids) => ids.some((id) => samePerson(id, actorId)));
  if (scheduled && ownerIsMember === false)
    return { authzFailed: true, ownerLeft: true, ran: false, note: "the owner left this conversation" };
  let homeAccess: { ok: boolean; note?: string };
  if (runsAsScope || ownerIsMember) {
    homeAccess = { ok: true };
  } else if (ownerIsMember === false) {
    homeAccess = { ok: false, note: MEMBERSHIP_SKIP_NOTE };
  } else if (currentMembers !== undefined) {
    homeAccess = currentMembers.some((member) => samePerson(member.id, actorId))
      ? { ok: true }
      : { ok: false, note: MEMBERSHIP_SKIP_NOTE };
  } else if (!deps.directory) {
    homeAccess = { ok: true };
  } else {
    homeAccess = await actorMayReadScope(
      deps,
      actorId,
      ownerKind,
      ownerRef,
      spec.ownerScopeId,
      deps.currentScopeMembers !== undefined,
    );
  }
  const destinationIsHome = spec.destination?.audienceScopeId === spec.ownerScopeId;
  const deliverable = spec.destination
    ? (destinationIsHome && homeAccess.ok) || (await destinationVisible(deps, actorId, spec.destination))
    : true;
  const notVisibleNote = "destination is no longer visible to the cron owner — delivery skipped";
  const liveDelivery = spec.surface === "monitor" && Boolean(spec.destination) && deliverable;

  let status: TurnResult["status"] | undefined;
  let errorCode: string | undefined;
  let note: string | undefined;
  let userNote: string | undefined;
  let reply: string | undefined;
  let sessionId: string | undefined;
  let deferred = false;
  const ran = await deps.idempotency
    .once(spec.fireKey, async () => {
      await spec.onClaimed?.();
      if (spec.message !== undefined) {
        status = "ok";
        if (!spec.destination) return;
        if (!deliverable) {
          status = "refused";
          note = notVisibleNote;
          return;
        }
        const attributeAs = await relayAttribution(deps, spec);
        await reachEnqueue({
          deliveries: deps.deliveries,
          destination: spec.destination,
          text: spec.message,
          idempotencyKey: spec.fireKey,
          provenance: deliveryProvenance(spec, threadRef),
          ...(attributeAs ? { attributeAs } : {}),
          ...(spec.shadow ? { shadow: true } : {}),
        });
        return;
      }
      if (!homeAccess.ok) {
        note = homeAccess.note ?? MEMBERSHIP_SKIP_NOTE;
        return;
      }
      const res = await deps.run({
        surface: spec.surface,
        actor: { externalId: actorId },
        conversation,
        text: typeof spec.input === "string" ? spec.input : spec.input(roster),
        ...(spec.securityScreenData !== undefined ? { securityScreenData: spec.securityScreenData } : {}),
        triggered: true,
        ...(spec.unattendedGrants && grantsStayWithOwner(spec) ? { unattendedGrants: spec.unattendedGrants } : {}),
        ...(spec.runtime ? { model: spec.runtime.modelId, harness: spec.runtime.harnessId } : {}),
        ...turnModelOptions({
          triggered: true,
          surface: spec.surface,
          thinkingLevel: spec.runtime?.effortLevel ?? spec.thinkingLevel,
          fastMode: spec.fastMode ?? spec.runtime?.fastMode,
        }),
        ...(spec.model ? { model: spec.model } : {}),
        ...(spec.harness ? { harness: spec.harness } : {}),
        ...(spec.attachments?.length ? { attachments: spec.attachments } : {}),
        ...(spec.readOnly ? { readOnly: true } : {}),
        ...(typeof spec.turnWallClockMs === "number" ? { turnWallClockMs: spec.turnWallClockMs } : {}),
        ...(spec.destination ? { triggerDestination: spec.destination } : {}),
        ...(liveDelivery ? { surfaceTools: true, addressed: true } : {}),
        ...(scheduled && !runsAsScope && conversation.kind !== "dm" ? { ownerKeychainUnion: true } : {}),
        idempotencyKey: spec.fireKey,
      });
      if (spec.deferWhenBusy && res.refusalKind === "session_busy") throw new FireDeferred();
      status = res.status;
      errorCode = res.errorCode;
      reply = res.reply;
      sessionId = res.sessionId;
      if (res.status === "silent") return;
      if (res.status === "pending_approval") {
        note = "hit a require_approval command — failed closed (no human at fire/event time)";
        console.warn(`[trigger] ${spec.surface} ${spec.fireKey} ${note}`);
        return;
      }
      if (res.status === "ok" && (res.reply || res.attachments?.length)) {
        if (!spec.destination) return;
        if (liveDelivery) return;
        if (!deliverable) {
          status = "refused";
          note = notVisibleNote;
          return;
        }
        await reachEnqueue({
          deliveries: deps.deliveries,
          destination: spec.destination,
          text: res.reply ?? "",
          ...(res.attachments?.length ? { attachments: res.attachments } : {}),
          idempotencyKey: spec.fireKey,
          provenance: deliveryProvenance(spec, threadRef, res),
          ...(spec.shadow ? { shadow: true } : {}),
        });
        return;
      }
      if (res.status === "ok") note = "produced no reply";
      else {
        note = res.reason ? `${res.status}: ${res.reason}` : res.status;
        userNote = userFacingFailureClause(res);
      }
    })
    .catch((e: unknown) => {
      if (!(e instanceof FireDeferred)) throw e;
      deferred = true;
      return false;
    });

  const outcome: TriggerOutcome = {
    authzFailed: false,
    ran,
    ...(deferred ? { deferred } : {}),
    ...(status ? { status } : {}),
    ...(errorCode ? { errorCode } : {}),
    ...(note ? { note } : {}),
    ...(userNote ? { userNote } : {}),
    ...(reply !== undefined ? { reply } : {}),
    ...(sessionId ? { sessionId } : {}),
  };

  if (spec.errorNotice && spec.destination && deliverable && isTriggerFailure(outcome)) {
    await deps.deliveries.enqueue({
      destination: spec.destination,
      text: spec.errorNotice(userNote ?? note ?? status!),
      idempotencyKey: `${spec.fireKey}:err`,
      provenance: deliveryProvenance(spec, threadRef),
      ...(spec.shadow ? { shadow: true } : {}),
    });
  }

  return outcome;
}