sailfork / t3code-github / apps/ server/ src/ peer/ PeerLinkRequests.ts

/**
 * Links an agent asks the user to make. The user picks the machine and access in a card, and
 * their client answers with its addresses and a pairing code that goes straight to
 * `PeerLinks.link`, never into the transcript or the agent's context. Asking does not wait
 * (provider CLIs abandon a long tool call): the answer reaches the agent as a notification.
 */
import {
  CommandId,
  type EnvironmentId,
  MessageId,
  type NodeId,
  type OrchestrationV2Notification,
  type OrchestrationV2TurnItem,
  type OrchestratorMcpEnvironmentLinkInput,
  type OrchestratorMcpEnvironmentLinkResult,
  OrchestratorMcpFailure,
  type PeerLink,
  PeerLinkError,
  PeerLinkRequestError,
  type PeerLinkRequestAnswerInput,
  type RunId,
  type ThreadId,
  TurnItemId,
} from "@t3tools/contracts";
import * as Context from "effect/Context";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as KeyedLock from "@t3tools/shared/KeyedLock";

import * as McpInvocationContext from "../mcp/McpInvocationContext.ts";
import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
import * as PeerLinks from "./PeerLinks.ts";

type LinkRequestItem = Extract<OrchestrationV2TurnItem, { readonly type: "link_request" }>;

/** The request as it was asked, which every update of its card repeats. */
type LinkRequestAsk = Pick<
  LinkRequestItem,
  "id" | "threadId" | "url" | "reason" | "environmentId" | "label" | "hint" | "requestedAccess"
> & { readonly runId: RunId; readonly nodeId: NodeId };

/** The notification that tells the agent how its card ended. */
type LinkRequestWake = {
  readonly messageId: MessageId;
  readonly text: string;
  readonly notification: OrchestrationV2Notification;
};

/** What a card update may change. */
type LinkRequestOutcome = Pick<
  LinkRequestItem,
  "linkStatus" | "linkedEnvironmentId" | "linkedLabel" | "linkedAccess" | "failure"
>;

const errorMessage = (error: unknown) =>
  error instanceof Error ? error.message : typeof error === "string" ? error : "unknown error";

export class PeerLinkRequests extends Context.Service<
  PeerLinkRequests,
  {
    /**
     * Shows a link card in the calling thread and returns at once. A retry
     * with the same clientRequestId and MCP credential returns the card's
     * current outcome.
     */
    readonly request: (
      scope: McpInvocationContext.McpInvocationScope,
      input: OrchestratorMcpEnvironmentLinkInput,
    ) => Effect.Effect<OrchestratorMcpEnvironmentLinkResult, OrchestratorMcpFailure>;
    /**
     * Answers a pending card and tells the agent. Linking uses the pairing
     * code once; a link the other environment refuses closes the card as
     * failed, with its reason.
     */
    readonly answer: (
      input: PeerLinkRequestAnswerInput,
    ) => Effect.Effect<void, PeerLinkRequestError>;
  }
>()("t3/peer/PeerLinkRequests") {}

const make = Effect.gen(function* () {
  const threadManagement = yield* ThreadManagementService.ThreadManagementService;
  const peerLinks = yield* PeerLinks.PeerLinks;
  const random = yield* SecureRandom.SecureRandom;

  const readCard = (threadId: ThreadId, turnItemId: TurnItemId) =>
    threadManagement
      .getThreadRecords(threadId, ["turnItems"], {
        turnItemTypes: ["link_request"],
        messageRoles: [],
      })
      .pipe(
        Effect.map((records) => {
          const item = records.turnItems.find((candidate) => candidate.id === turnItemId);
          // A deleted thread's cards went with it.
          return item?.type === "link_request" && records.thread.deletedAt === null
            ? item
            : undefined;
        }),
      );

  /**
   * The stored link to `environmentId`, or nothing once it has expired: an
   * expired link needs a new pairing code, which only the card asks for.
   */
  const usableLink = (environmentId: EnvironmentId) =>
    Effect.all([peerLinks.get(environmentId), DateTime.now]).pipe(
      Effect.map(([linked, now]) =>
        Option.filter(linked, (link) => DateTime.isGreaterThan(link.expiresAt, now)),
      ),
    );

  const record = (
    card: LinkRequestAsk,
    outcome: LinkRequestOutcome,
    commandId: CommandId,
    wake?: LinkRequestWake,
  ) =>
    threadManagement.dispatch({
      type: "link_request.record",
      commandId,
      threadId: card.threadId,
      runId: card.runId,
      nodeId: card.nodeId,
      turnItemId: card.id,
      ...(card.url === undefined ? {} : { url: card.url }),
      reason: card.reason,
      ...(card.environmentId === undefined ? {} : { environmentId: card.environmentId }),
      ...(card.label === undefined ? {} : { label: card.label }),
      ...(card.hint === undefined ? {} : { hint: card.hint }),
      ...(card.requestedAccess === undefined ? {} : { requestedAccess: card.requestedAccess }),
      ...outcome,
      ...(wake === undefined ? {} : { wake }),
    });

  const linkedOutcome = (linked: PeerLink): LinkRequestOutcome => ({
    linkStatus: "linked",
    linkedEnvironmentId: linked.environmentId,
    linkedLabel: linked.label,
    linkedAccess: linked.access,
  });

  // One answer per card at a time: two answers racing on one card must not
  // both link. Other cards go on while a slow peer holds one.
  const answerLocks = yield* KeyedLock.make<TurnItemId>();

  /**
   * Closes a card still waiting when its agent retries naming a machine linked
   * meanwhile. Nothing wakes the agent: the retry itself returns the link.
   */
  const closeAsLinked = (threadId: ThreadId, turnItemId: TurnItemId, linked: PeerLink) =>
    answerLocks.withLock(
      turnItemId,
      Effect.gen(function* () {
        const card = yield* readCard(threadId, turnItemId);
        if (
          card === undefined ||
          card.linkStatus !== "pending" ||
          card.runId === null ||
          card.nodeId === null
        ) {
          return;
        }
        yield* record(
          { ...card, runId: card.runId, nodeId: card.nodeId },
          linkedOutcome(linked),
          CommandId.make(`link-request:${card.id}:linked-on-retry`),
        );
      }),
    );

  const request: PeerLinkRequests["Service"]["request"] = Effect.fn("PeerLinkRequests.request")(
    function* (scope, input) {
      // The card is shown in, and answered from, the caller's own thread.
      const threadScope = yield* McpInvocationContext.requireThreadScope(
        scope,
        "t3_environment_link",
      );
      const threadId = threadScope.thread.threadId;
      if (!(yield* peerLinks.enabled)) {
        return yield* new OrchestratorMcpFailure({
          code: "capability_denied",
          message: PeerLinks.LINKED_ENVIRONMENTS_OFF,
        });
      }
      const unreadable = (error: unknown) =>
        new OrchestratorMcpFailure({
          code: "orchestration_error",
          message: `Unable to read the link request: ${errorMessage(error)}`,
        });
      if (input.url !== undefined && input.environmentId !== undefined) {
        return yield* new OrchestratorMcpFailure({
          code: "invalid_request",
          message:
            "Pass either environmentId or url, not both. Pass neither to let the user pick the machine.",
        });
      }
      // A machine already linked needs no card: the agent can use it now.
      if (input.environmentId !== undefined) {
        const linked = yield* usableLink(input.environmentId).pipe(
          Effect.mapError(
            (error) =>
              new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message }),
          ),
        );
        if (Option.isSome(linked)) {
          if (input.clientRequestId !== undefined) {
            yield* closeAsLinked(
              threadId,
              cardId(threadId, scope.requestNamespace, input.clientRequestId),
              linked.value,
            ).pipe(
              Effect.mapError(
                (error) =>
                  new OrchestratorMcpFailure({
                    code: "orchestration_error",
                    message: `Could not close the link request: ${errorMessage(error)}`,
                  }),
              ),
            );
          }
          return {
            status: "linked",
            environmentId: linked.value.environmentId,
            label: linked.value.label,
            access: linked.value.access,
          } as const;
        }
      }
      const key = input.clientRequestId ?? (yield* random.uuidV4());
      // A retry with the same clientRequestId finds this card and records nothing.
      const turnItemId = cardId(threadId, scope.requestNamespace, key);
      if (input.clientRequestId !== undefined) {
        const existing = yield* readCard(threadId, turnItemId).pipe(Effect.mapError(unreadable));
        if (existing !== undefined) return resultOf(existing);
      }
      const parent = yield* threadManagement
        .getThreadRecords(threadId, ["runs"], { messageRoles: [] })
        .pipe(Effect.mapError(unreadable));
      const run = ThreadManagementService.latestActiveRun(parent);
      if (
        run === undefined ||
        run.rootNodeId === null ||
        run.providerInstanceId !== threadScope.thread.providerInstanceId
      ) {
        return yield* new OrchestratorMcpFailure({
          code: "parent_not_active",
          message:
            "Asking to link an environment requires an active run owned by this MCP provider session.",
        });
      }
      // Best effort: the card names the machine at an address the agent was
      // given, and the client finds it by id.
      const peer = input.url === undefined ? Option.none() : yield* peerLinks.describe(input.url);
      yield* record(
        {
          id: turnItemId,
          threadId,
          runId: run.id,
          nodeId: run.rootNodeId,
          ...(input.url === undefined ? {} : { url: input.url }),
          reason: input.reason ?? "",
          ...(Option.isSome(peer)
            ? { environmentId: peer.value.environmentId, label: peer.value.label }
            : input.environmentId === undefined
              ? {}
              : { environmentId: input.environmentId }),
          ...(input.hint === undefined ? {} : { hint: input.hint }),
          ...(input.requestedAccess === undefined
            ? {}
            : { requestedAccess: input.requestedAccess }),
        },
        { linkStatus: "pending" },
        CommandId.make(
          `command:mcp:${encodeURIComponent(scope.requestNamespace)}:link-pending:${encodeURIComponent(key)}`,
        ),
      ).pipe(
        Effect.mapError(
          (error) =>
            new OrchestratorMcpFailure({
              code: "orchestration_error",
              message: `Could not record the link request: ${errorMessage(error)}`,
            }),
        ),
      );
      return pendingResult(turnItemId);
    },
    Effect.withSpan("PeerLinkRequests.request"),
  );

  /** Links the machine the user picked, or finds the link they chose to keep. */
  const answerOutcome = (
    answer: PeerLinkRequestAnswerInput["answer"],
  ): Effect.Effect<LinkRequestOutcome> => {
    switch (answer.type) {
      case "decline":
        return Effect.succeed({ linkStatus: "declined" });
      case "use-existing":
        return usableLink(answer.environmentId).pipe(
          Effect.flatMap(
            Option.match({
              onNone: () =>
                Effect.fail(
                  new PeerLinkError({
                    reason: "unknown_link",
                    message:
                      "That environment is no longer linked here, or its link expired. Link it again.",
                  }),
                ),
              onSome: (linked) => Effect.succeed(linkedOutcome(linked)),
            }),
          ),
          Effect.catch((error) =>
            Effect.succeed<LinkRequestOutcome>({ linkStatus: "failed", failure: error.message }),
          ),
        );
      case "link": {
        const [url, ...alternateUrls] = answer.urls;
        return peerLinks
          .link({
            url,
            ...(alternateUrls.length === 0 ? {} : { alternateUrls }),
            pairingCode: answer.pairingCode,
            access: answer.access,
            ...(answer.environmentId === undefined
              ? {}
              : { expectedEnvironmentId: answer.environmentId }),
            ...(answer.label === undefined ? {} : { expectedLabel: answer.label }),
          })
          .pipe(
            Effect.map(linkedOutcome),
            Effect.catch((error) =>
              Effect.succeed<LinkRequestOutcome>({ linkStatus: "failed", failure: error.message }),
            ),
          );
      }
    }
  };

  const answer: PeerLinkRequests["Service"]["answer"] = Effect.fn("PeerLinkRequests.answer")(
    function* (input) {
      yield* Effect.annotateCurrentSpan({
        "orchestration_v2.thread_id": input.threadId,
        "link_request.answer": input.answer.type,
      });
      const card = yield* readCard(input.threadId, input.turnItemId).pipe(
        Effect.mapError((cause) => new PeerLinkRequestError({ reason: "load_failed", cause })),
      );
      if (card === undefined || card.runId === null || card.nodeId === null) {
        return yield* new PeerLinkRequestError({ reason: "not_found" });
      }
      // Any time while the card is open: the agent hears the answer as a
      // notification, whether or not its run is still going.
      if (card.linkStatus !== "pending") {
        return yield* new PeerLinkRequestError({ reason: "already_answered" });
      }
      const outcome = yield* answerOutcome(input.answer);
      // If Stop closed the card while linking, the card keeps that; the link
      // itself stands and Settings lists it.
      yield* record(
        { ...card, runId: card.runId, nodeId: card.nodeId },
        outcome,
        CommandId.make(`link-request:${card.id}:${outcome.linkStatus}`),
        {
          messageId: MessageId.make(`message:link-request:${card.id}`),
          ...outcomeNotice(card, outcome),
        },
      ).pipe(
        Effect.mapError((cause) => new PeerLinkRequestError({ reason: "record_failed", cause })),
      );
    },
    (effect, input) =>
      effect.pipe(
        (effect) => answerLocks.withLock(input.turnItemId, effect),
        Effect.withSpan("PeerLinkRequests.answer"),
      ),
  );

  return PeerLinkRequests.of({ request, answer });
});

/**
 * Turn item ids are global; scope the key to this thread and provider session,
 * since a later session may reuse it.
 */
const cardId = (threadId: ThreadId, requestNamespace: string, key: string) =>
  TurnItemId.make(
    `turn-item:link-request:${encodeURIComponent(threadId)}:${encodeURIComponent(requestNamespace)}:${encodeURIComponent(key)}`,
  );

const pendingResult = (turnItemId: TurnItemId): OrchestratorMcpEnvironmentLinkResult => ({
  status: "pending",
  turnItemId,
});

/** What a retry hears: the card's outcome, without anything the user typed. */
const resultOf = (card: LinkRequestItem): OrchestratorMcpEnvironmentLinkResult => {
  switch (card.linkStatus) {
    case "pending":
      return pendingResult(card.id);
    case "linked":
      return {
        status: "linked",
        environmentId: card.linkedEnvironmentId!,
        label: card.linkedLabel ?? linkTarget(card),
        access: card.linkedAccess!,
      };
    case "failed":
      return { status: "failed", message: card.failure ?? "The link could not be made." };
    case "declined":
    case "cancelled":
      return { status: card.linkStatus };
  }
};

/** What the agent's words call the target: its name, its address, or the user's pick. */
const linkTarget = (card: Pick<LinkRequestItem, "url" | "label" | "environmentId">) =>
  card.label ?? card.url ?? card.environmentId ?? "a machine";

/**
 * The notification an answer sends the agent: what the card says, and what
 * to do next. It carries the outcome only, never the pairing code.
 */
const outcomeNotice = (
  card: Pick<LinkRequestItem, "url" | "label" | "environmentId">,
  outcome: LinkRequestOutcome,
): Omit<LinkRequestWake, "messageId"> => {
  const target = linkTarget(card);
  switch (outcome.linkStatus) {
    case "linked": {
      const label = outcome.linkedLabel ?? target;
      return {
        text: `The user linked ${label} with ${outcome.linkedAccess} access. Pass environmentId ${outcome.linkedEnvironmentId} to act there.`,
        notification: {
          source: { kind: "background_task" },
          outcome: "completed",
          summary: `Linked ${label}`,
        },
      };
    }
    case "failed":
      return {
        text: `Linking ${target} failed: ${outcome.failure ?? "the other environment refused"}. Call t3_environment_link again if the user still wants it.`,
        notification: {
          source: { kind: "background_task" },
          outcome: "failed",
          summary: `Could not link ${target}`,
        },
      };
    default:
      return {
        text: `The user declined to link ${target}.`,
        notification: {
          source: { kind: "background_task" },
          outcome: "cancelled",
          summary: `Declined to link ${target}`,
        },
      };
  }
};

export const layer = Layer.effect(PeerLinkRequests, make);