Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

42.3 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { asError, isRecord } from "@linger/service-kit";

import type { AgentManager } from "../executor/agent-manager-api.js";
import {
  assertExecutionContextRef,
  type ExecutionContextRef,
} from "../executor/context-ref.js";
import {
  createAgentLogger,
  type AgentLogger,
} from "../observability/agent-log.js";
import type {
  LocalTurnObservation,
  LocalTurnTerminal,
} from "../executor/types.js";
import type { Message, MessageSegment } from "../executor/types.js";
import type {
  TaskEffect,
  TaskExecution,
  TaskWorkerExecution,
  TaskWorkerLease,
  TeamHubTaskWorkerClient,
} from "./teamhub-task-worker-client.js";

const DEFAULT_LEASE_SECONDS = 15;
const DEFAULT_POLL_INTERVAL_MS = 500;
// TeamHub wakes the Worker through the Agent wake stream when a commit may
// make a Task claimable, and reports when a pending Task becomes due; this
// cap only recovers a lost wake.
const IDLE_CLAIM_WAIT_MS = 60_000;
// A due Task whose row another claim transaction has locked at that instant
// is skipped by the locking claim and reported with no delay; this floor
// retries it shortly instead of spinning.
const MIN_CLAIM_DELAY_MS = 100;
const MIN_HEARTBEAT_INTERVAL_MS = 1_000;
// A participant Run finishing makes its running Task due in TeamHub, and the
// Attempt deadline caps the scheduled time; this only recovers a lost update.
const RUNNING_RECONCILE_SAFETY_NET_SECONDS = 60;
// An unclassified submit failure is retried soon.
const SUBMIT_FAILURE_RETRY_SECONDS = 1;

type TaskAgentManager = Pick<
  AgentManager<unknown>,
  | "cancelLocalRun"
  | "cancelTrustedTurn"
  | "observeTurn"
  | "steerActiveTurn"
  | "submitTrustedTurn"
>;

export interface TaskWorkerOptions {
  readonly agentManager: TaskAgentManager;
  readonly client: TeamHubTaskWorkerClient;
  readonly workerId?: string;
  readonly leaseSeconds?: number;
  /** Backoff after a failed claim or drive. */
  readonly pollIntervalMs?: number;
  readonly logger?: AgentLogger;
}

export interface TaskWorker {
  start(): void;
  runOnce(signal?: AbortSignal): Promise<boolean>;
  wake(): void;
  close(): Promise<void>;
}

interface ParticipantRun {
  readonly actor_id: string;
  readonly agent_management_id: string;
  readonly agent_run_ref: string;
}

interface ParticipantTerminal {
  readonly agent_run_ref: string;
  readonly status: "succeeded" | "failed" | "canceled";
  readonly terminal_code?: string;
  readonly terminal_message?: string;
}

interface SubmitAgentTurnPayload {
  readonly taskId: string;
  readonly recipientActorIds: readonly string[];
  readonly inputManifest?: Readonly<Record<string, unknown>>;
  readonly feedbackMessageId?: string;
  readonly message: Message;
  readonly recipientWakes?: ReadonlyMap<string, ParticipantMetaWake>;
  /** A Meta's task send --steer: join the running turn when it can. */
  readonly steer: boolean;
}

interface PublicTurnMessage {
  readonly message: Message;
  readonly author: {
    readonly actorId: string;
    readonly kind: "human" | "agent";
    readonly displayName: string;
  };
}

interface ParticipantMetaWake {
  readonly actorId: string;
  readonly authorActorId: string;
  readonly metaSeq: number;
  readonly publicMessageIds: readonly string[];
  readonly message: Message;
}

interface AgentTurnObservation {
  readonly participantRuns: readonly ParticipantRun[];
  readonly participantTerminals: readonly ParticipantTerminal[];
}

interface RuntimeCleanupPayload {
  readonly actorId: string;
  readonly agentManagementId: string;
  readonly agentRunRef?: string;
  readonly executionContextRef: ExecutionContextRef;
  readonly reconcileSubmit?: {
    readonly sourceEffectId: string;
    readonly rootOperationId: string;
    readonly submit: SubmitAgentTurnPayload;
  };
}

export const createTaskWorker = (options: TaskWorkerOptions): TaskWorker => {
  const workerId =
    options.workerId?.trim() || `agent-task-worker-${randomUUID()}`;
  const leaseSeconds = options.leaseSeconds ?? DEFAULT_LEASE_SECONDS;
  if (
    !Number.isSafeInteger(leaseSeconds) ||
    leaseSeconds < 5 ||
    leaseSeconds > 300
  ) {
    throw new TypeError("leaseSeconds must be an integer between 5 and 300");
  }
  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
  if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1) {
    throw new TypeError("pollIntervalMs must be a positive safe integer");
  }
  const logger =
    options.logger ?? createAgentLogger({ component: "task-worker", workerId });
  const closeController = new AbortController();
  let loop: Promise<void> | null = null;
  let closePromise: Promise<void> | null = null;
  let wakeController = new AbortController();

  const wake = (): void => {
    wakeController.abort();
    wakeController = new AbortController();
  };

  /** Resolves 0 after driving a claimed Task, else the wait before the next claim. */
  const claimAndDrive = async (signal?: AbortSignal): Promise<number> => {
    const operationSignal = combineSignals(closeController.signal, signal);
    operationSignal.throwIfAborted();
    const { claimed, nextClaimDelayMs } = await options.client.claim({
      workerId,
      leaseSeconds,
      signal: operationSignal,
    });
    if (!claimed) {
      return Math.min(
        Math.max(nextClaimDelayMs ?? IDLE_CLAIM_WAIT_MS, MIN_CLAIM_DELAY_MS),
        IDLE_CLAIM_WAIT_MS,
      );
    }
    const lease = requireClaimLease(claimed);
    await driveWithHeartbeat(
      options.client,
      lease,
      leaseSeconds,
      operationSignal,
      (currentLease, driveSignal) =>
        driveClaim(options, currentLease, claimed.execution, driveSignal),
    );
    return 0;
  };

  const runOnce = async (signal?: AbortSignal): Promise<boolean> =>
    (await claimAndDrive(signal)) === 0;

  const start = (): void => {
    if (closePromise) throw new Error("Task Worker is closed");
    if (loop) return;
    loop = (async () => {
      logger.log("info", "task_worker.started");
      while (!closeController.signal.aborted) {
        // Taken before claiming, so a wake during the claim is not lost.
        const wakeSignal = wakeController.signal;
        let waitMs = pollIntervalMs;
        try {
          waitMs = await claimAndDrive(closeController.signal);
          if (waitMs === 0) continue;
        } catch (error) {
          if (closeController.signal.aborted) break;
          logger.log("warn", "task_worker.drive_failed", { error });
        }
        await waitForWake(
          waitMs,
          combineSignals(closeController.signal, wakeSignal),
        );
      }
      logger.log("info", "task_worker.stopped");
    })();
  };

  return Object.freeze({
    start,
    runOnce,
    wake,
    close() {
      closePromise ??= (async () => {
        closeController.abort();
        wake();
        await loop;
      })();
      return closePromise;
    },
  });
};

const driveClaim = async (
  options: Pick<TaskWorkerOptions, "agentManager" | "client">,
  lease: TaskWorkerLease,
  initialExecution: TaskExecution,
  signal: AbortSignal,
): Promise<void> => {
  let execution = initialExecution;
  let acquiredRuntimeCleanupEffectId: string | undefined;
  for (;;) {
    signal.throwIfAborted();
    const advanced = await options.client.transition({
      lease,
      execution,
      transition: "advance",
      expectedControlRevision: execution.control_revision,
      signal,
    });
    if (!advanced.lease) return;
    execution = advanced.execution;

    const cleanup = nextRuntimeCleanupEffect(execution.pending_effects);
    if (cleanup) {
      if (cleanup.id !== acquiredRuntimeCleanupEffectId) {
        execution = (
          await options.client.transition({
            lease,
            execution,
            transition: "begin_effect_dispatch",
            payload: { effect_id: cleanup.id },
            signal,
          })
        ).execution;
        acquiredRuntimeCleanupEffectId = cleanup.id;
        continue;
      }
      const completed = await dispatchRuntimeCleanup(
        options,
        lease,
        execution,
        cleanup,
        signal,
      );
      if (!completed.lease) return;
      execution = completed.execution;
      continue;
    }
    // Only a running Task has turns to drive; other states only drain cleanup.
    if (execution.status !== "running") return;

    const terminalTransition = await observeAgentTerminals(
      options.agentManager,
      execution,
      signal,
    );
    if (terminalTransition) {
      execution = (
        await options.client.transition({
          lease,
          execution,
          transition: "record_agent_terminal",
          payload: terminalTransition,
          signal,
        })
      ).execution;
      continue;
    }

    const liveEffect = nextLiveEffect(execution.pending_effects);
    if (liveEffect) {
      if (liveEffect.status === "pending") {
        execution = (
          await options.client.transition({
            lease,
            execution,
            transition: "begin_effect_dispatch",
            payload: { effect_id: liveEffect.id },
            signal,
          })
        ).execution;
        continue;
      }
      if (liveEffect.operation === "submit_agent_turn") {
        const dispatched = await dispatchAgentTurn(
          options,
          lease,
          execution,
          liveEffect,
          signal,
        );
        if (!dispatched.lease) return;
        execution = dispatched.execution;
        continue;
      }
    }

    await options.client.transition({
      lease,
      execution,
      transition: "schedule_reconcile",
      expectedControlRevision: execution.control_revision,
      payload: {
        reconcile_after_seconds: RUNNING_RECONCILE_SAFETY_NET_SECONDS,
      },
      signal,
    });
    return;
  }
};

const dispatchAgentTurn = async (
  options: Pick<TaskWorkerOptions, "agentManager" | "client">,
  lease: TaskWorkerLease,
  execution: TaskExecution,
  effect: TaskEffect,
  signal: AbortSignal,
): Promise<TaskWorkerExecution> => {
  const payload = parseSubmitAgentTurnPayload(
    effect.payload,
    execution.task_id,
  );
  const recipients = exactRecipientParticipants(
    execution,
    payload.recipientActorIds,
  );
  requiredString(payload.inputManifest?.room_id, "Task Room ID");

  let participantRuns: ParticipantRun[];
  try {
    participantRuns = await Promise.all(
      recipients.map(async (participant): Promise<ParticipantRun> => {
        signal.throwIfAborted();
        const target = executionContextRef(participant.execution_context_ref);
        if (
          target.kind !== "alter_ego" ||
          target.agentId !== participant.agent_id ||
          target.taskId !== execution.task_id
        ) {
          throw new TaskWorkerProtocolError(
            `Task participant ${participant.actor_id} has a mismatched Execution Context`,
          );
        }
        const trustedMessage = trustedMessageForActor(
          payload,
          participant.actor_id,
        );
        signal.throwIfAborted();
        // A steered message joins the running turn and shares its Run; when
        // no turn can take it, it runs as the next turn.
        const submitted =
          (payload.steer
            ? await options.agentManager.steerActiveTurn({
                target,
                message: trustedMessage,
              })
            : null) ??
          (await options.agentManager.submitTrustedTurn({
            target,
            messages: [trustedMessage],
          }));
        return Object.freeze({
          actor_id: participant.actor_id,
          agent_management_id: participant.agent_id,
          agent_run_ref: requiredString(
            submitted.agentRunRef,
            "Agent Run reference",
          ),
        });
      }),
    );
  } catch (error) {
    signal.throwIfAborted();
    const activationFailure = classifiedContextActivationFailure(error);
    if (activationFailure) {
      return options.client.transition({
        lease,
        execution,
        transition: "record_agent_turn_failure",
        operationId: `${effect.root_operation_id}:activation-failed`,
        payload: {
          effect_id: effect.id,
          failure_code: activationFailure.code,
          retryable: activationFailure.retryable,
        },
        signal,
      });
    }
    return options.client.transition({
      lease,
      execution,
      transition: "schedule_reconcile",
      expectedControlRevision: execution.control_revision,
      payload: { reconcile_after_seconds: SUBMIT_FAILURE_RETRY_SECONDS },
      signal,
    });
  }
  participantRuns.sort((left, right) =>
    left.actor_id.localeCompare(right.actor_id),
  );
  return options.client.transition({
    lease,
    execution,
    transition: "record_agent_turn",
    operationId: effect.root_operation_id,
    payload: {
      effect_id: effect.id,
      participant_runs: participantRuns,
    },
    signal,
  });
};

const classifiedContextActivationFailure = (
  error: unknown,
): { readonly code: string; readonly retryable: boolean } | null => {
  if (
    !(error instanceof Error) ||
    error.name !== "ContextActivationError" ||
    !("code" in error) ||
    typeof error.code !== "string" ||
    !/^CONTEXT_ACTIVATION_[A-Z_]+_FAILED$/.test(error.code) ||
    !("retryable" in error) ||
    typeof error.retryable !== "boolean"
  ) {
    return null;
  }
  return { code: error.code, retryable: error.retryable };
};

const dispatchRuntimeCleanup = async (
  options: Pick<TaskWorkerOptions, "agentManager" | "client">,
  lease: TaskWorkerLease,
  execution: TaskExecution,
  effect: TaskEffect,
  signal: AbortSignal,
): Promise<TaskWorkerExecution> => {
  const payload = parseRuntimeCleanupPayload(effect.payload, execution.task_id);
  const participant = execution.participants.find(
    ({ actor_id }) => actor_id === payload.actorId,
  );
  if (!participant || participant.agent_id !== payload.agentManagementId) {
    throw new TaskWorkerProtocolError(
      `Runtime cleanup actor ${payload.actorId} is not a matching Task participant`,
    );
  }
  signal.throwIfAborted();
  const recovered = payload.agentRunRef
    ? null
    : await reconcileSubmittedLocalRun(options, execution, payload, signal);
  const agentRunRef =
    payload.agentRunRef ??
    requiredString(recovered?.agentRunRef, "Recovered cleanup Local Run ID");
  const cancelStatus =
    recovered?.cancelStatus ??
    (await options.agentManager.cancelLocalRun(
      payload.executionContextRef,
      agentRunRef,
    ));
  let runStatus: "succeeded" | "failed" | "canceled" | undefined;
  if (cancelStatus === "canceled") {
    runStatus = "canceled";
  } else if (
    cancelStatus === "cancel_requested" ||
    cancelStatus === "already_terminal"
  ) {
    for (;;) {
      signal.throwIfAborted();
      const observed = await options.agentManager.observeTurn(
        payload.executionContextRef,
        agentRunRef,
      );
      const terminal = observedTerminal(observed);
      if (terminal) {
        runStatus = localTerminalStatus(terminal);
        break;
      }
      if (cancelStatus === "already_terminal") {
        throw new TaskWorkerProtocolError(
          `Terminal Local Run ${agentRunRef} has no observation`,
        );
      }
      await waitForWake(DEFAULT_POLL_INTERVAL_MS, signal);
    }
  }
  return options.client.transition({
    lease,
    execution,
    transition: "complete_runtime_cleanup",
    expectedControlRevision: execution.control_revision,
    operationId: effect.root_operation_id,
    payload: {
      effect_id: effect.id,
      agent_run_ref: agentRunRef,
      cancel_status: cancelStatus,
      ...(runStatus === undefined ? {} : { run_status: runStatus }),
    },
    signal,
  });
};

const reconcileSubmittedLocalRun = async (
  options: Pick<TaskWorkerOptions, "agentManager">,
  execution: TaskExecution,
  payload: RuntimeCleanupPayload,
  signal: AbortSignal,
): Promise<{
  readonly agentRunRef: string;
  readonly cancelStatus:
    | "canceled"
    | "cancel_requested"
    | "already_terminal"
    | "not_found";
}> => {
  const reconcile = payload.reconcileSubmit;
  if (!reconcile) {
    throw new TaskWorkerProtocolError(
      "Runtime cleanup has neither a Local Run reference nor submit reconciliation data",
    );
  }
  if (!reconcile.submit.recipientActorIds.includes(payload.actorId)) {
    throw new TaskWorkerProtocolError(
      `Cleanup submit ${reconcile.sourceEffectId} does not address ${payload.actorId}`,
    );
  }
  signal.throwIfAborted();
  const canceled = await options.agentManager.cancelTrustedTurn({
    target: payload.executionContextRef,
    messages: [trustedMessageForActor(reconcile.submit, payload.actorId)],
  });
  return Object.freeze({
    agentRunRef: requiredString(
      canceled.agentRunRef,
      `Cleanup submit ${reconcile.rootOperationId} Local Run reference`,
    ),
    cancelStatus: canceled.cancelStatus,
  });
};

const observeAgentTerminals = async (
  agentManager: TaskAgentManager,
  execution: TaskExecution,
  signal: AbortSignal,
): Promise<Readonly<Record<string, unknown>> | null> => {
  for (const effect of execution.pending_effects) {
    if (
      effect.operation !== "submit_agent_turn" ||
      effect.status !== "succeeded"
    ) {
      continue;
    }
    const observation = parseAgentTurnObservation(effect.observation);
    const recorded = new Set(
      observation.participantTerminals.map(
        ({ agent_run_ref }) => agent_run_ref,
      ),
    );
    const byAgent = new Map(
      execution.participants.map((participant) => [
        participant.agent_id,
        participant,
      ]),
    );
    const terminals: ParticipantTerminal[] = [];
    for (const run of observation.participantRuns) {
      if (recorded.has(run.agent_run_ref)) continue;
      const participant = byAgent.get(run.agent_management_id);
      if (!participant || participant.actor_id !== run.actor_id) {
        throw new TaskWorkerProtocolError(
          `Agent Run ${run.agent_run_ref} does not match a Task participant`,
        );
      }
      signal.throwIfAborted();
      const observed = await agentManager.observeTurn(
        executionContextRef(participant.execution_context_ref),
        run.agent_run_ref,
      );
      const terminal = observedTerminal(observed);
      if (terminal)
        terminals.push(toParticipantTerminal(run.agent_run_ref, terminal));
    }
    if (terminals.length > 0) {
      terminals.sort((left, right) =>
        left.agent_run_ref.localeCompare(right.agent_run_ref),
      );
      return {
        effect_id: effect.id,
        participant_terminals: terminals,
      };
    }
  }
  return null;
};

const nextLiveEffect = (effects: readonly TaskEffect[]): TaskEffect | null =>
  effects.find(
    (effect) =>
      (effect.status === "pending" || effect.status === "dispatching") &&
      effect.operation === "submit_agent_turn",
  ) ?? null;

const nextRuntimeCleanupEffect = (
  effects: readonly TaskEffect[],
): TaskEffect | null =>
  effects.find(
    (effect) =>
      effect.operation === "cleanup_runtime" &&
      (effect.status === "pending" || effect.status === "dispatching"),
  ) ?? null;

const parseRuntimeCleanupPayload = (
  value: Readonly<Record<string, unknown>>,
  taskId: string,
): RuntimeCleanupPayload => {
  const actorId = requiredString(value.actor_id, "Cleanup Actor ID");
  const agentManagementId = requiredString(
    value.agent_management_id,
    "Cleanup Agent Management ID",
  );
  const agentRunRef = optionalString(value.agent_run_ref);
  const executionContextRef = executionContextRefForTask(
    value.execution_context_ref,
    taskId,
    agentManagementId,
  );
  const reconcileValue = optionalRecord(value.reconcile_submit);
  const reconcileSubmit = reconcileValue
    ? Object.freeze({
        sourceEffectId: requiredString(
          reconcileValue.source_effect_id,
          "Cleanup source Effect ID",
        ),
        rootOperationId: requiredString(
          reconcileValue.root_operation_id,
          "Cleanup source root operation ID",
        ),
        submit: parseSubmitAgentTurnPayload(
          requiredRecord(
            reconcileValue.submit_payload,
            "Cleanup submit payload",
          ),
          taskId,
        ),
      })
    : undefined;
  if ((agentRunRef === undefined) === (reconcileSubmit === undefined)) {
    throw new TaskWorkerProtocolError(
      "Runtime cleanup must have exactly one Local Run recovery mode",
    );
  }
  return Object.freeze({
    actorId,
    agentManagementId,
    ...(agentRunRef ? { agentRunRef } : {}),
    executionContextRef,
    ...(reconcileSubmit ? { reconcileSubmit } : {}),
  });
};

const executionContextRefForTask = (
  value: unknown,
  taskId: string,
  agentManagementId: string,
): ExecutionContextRef => {
  const ref = executionContextRef(value);
  if (
    ref.kind !== "alter_ego" ||
    ref.taskId !== taskId ||
    ref.agentId !== agentManagementId
  ) {
    throw new TaskWorkerProtocolError(
      "Runtime cleanup has a mismatched Execution Context",
    );
  }
  return ref;
};

const parseSubmitAgentTurnPayload = (
  value: Readonly<Record<string, unknown>>,
  taskId: string,
): SubmitAgentTurnPayload => {
  const recipients = requiredStringArray(
    value.recipient_actor_ids,
    "Agent-turn recipient Actor IDs",
  );
  const inputManifest = optionalRecord(value.input_manifest);
  const feedbackMessageId =
    value.feedback_message_id === undefined
      ? undefined
      : requiredString(
          value.feedback_message_id,
          "Agent-turn feedback Message ID",
        );
  const messageValue = requiredRecord(value.message, "Agent-turn Message");
  const hasPublicContext = value.public_context_message !== undefined;
  const hasRecipientWakes = value.recipient_wakes !== undefined;
  if (hasPublicContext !== hasRecipientWakes) {
    throw new TaskWorkerProtocolError(
      "Agent-turn public context and recipient wakes must be present together",
    );
  }
  const routed = hasPublicContext
    ? parseAndVerifyRoutedTurn(value, inputManifest, recipients, taskId)
    : undefined;
  if (!routed && inputManifestHasRoutedWitness(inputManifest)) {
    throw new TaskWorkerProtocolError(
      "Agent-turn Input Manifest route has no matching effect route",
    );
  }
  const recipientWakes = routed?.recipientWakes;
  if (recipientWakes && feedbackMessageId) {
    throw new TaskWorkerProtocolError(
      "Agent-turn cannot combine public Task routing with private feedback routing",
    );
  }
  if (!recipientWakes && !feedbackMessageId) {
    throw new TaskWorkerProtocolError(
      "Agent-turn has no private Meta Inbox ingress",
    );
  }
  const replayPublicMessage = routed
    ? parsePublicTurnMessage(messageValue, taskId)
    : undefined;
  const message = replayPublicMessage
    ? replayPublicMessage.message
    : parseTurnMessage(messageValue, `meta:${taskId}`);
  if (
    routed &&
    (!replayPublicMessage ||
      !samePublicTurnMessage(replayPublicMessage, routed.publicContextMessage))
  ) {
    throw new TaskWorkerProtocolError(
      "Agent-turn replay Message does not match its frozen public context",
    );
  }
  if (feedbackMessageId && message.messageId !== feedbackMessageId) {
    throw new TaskWorkerProtocolError(
      "Agent-turn feedback Message ID does not match its Meta Inbox correlation",
    );
  }
  return Object.freeze({
    taskId,
    recipientActorIds: recipients,
    ...(inputManifest ? { inputManifest } : {}),
    ...(feedbackMessageId ? { feedbackMessageId } : {}),
    message,
    ...(recipientWakes ? { recipientWakes } : {}),
    steer: value.steer === true,
  });
};

const parseAndVerifyRoutedTurn = (
  effect: Readonly<Record<string, unknown>>,
  inputManifest: Readonly<Record<string, unknown>> | undefined,
  recipients: readonly string[],
  taskId: string,
): {
  readonly publicContextMessage: PublicTurnMessage;
  readonly recipientWakes: ReadonlyMap<string, ParticipantMetaWake>;
} => {
  if (!inputManifest) {
    throw new TaskWorkerProtocolError(
      "Agent-turn routed effect has no frozen Input Manifest",
    );
  }
  const effectPublicMessage = parsePublicTurnMessage(
    requiredRecord(
      effect.public_context_message,
      "Agent-turn public context Message",
    ),
    taskId,
  );
  const manifestPublicMessage = parsePublicTurnMessage(
    requiredRecord(
      inputManifest.public_context_message,
      "Agent-turn Input Manifest public context Message",
    ),
    taskId,
  );
  const manifestPublicMessageIds = requiredStringArray(
    inputManifest.public_message_ids,
    "Agent-turn Input Manifest public Message IDs",
  );
  if (
    manifestPublicMessageIds.length !== 1 ||
    manifestPublicMessageIds[0] !== manifestPublicMessage.message.messageId
  ) {
    throw new TaskWorkerProtocolError(
      "Agent-turn Input Manifest public Message IDs do not match its public context",
    );
  }
  const effectWakes = parseParticipantMetaWakes(
    effect.recipient_wakes,
    effectPublicMessage.message,
    taskId,
    "Agent-turn effect",
  );
  const manifestWakes = parseParticipantMetaWakes(
    inputManifest.recipient_wakes,
    manifestPublicMessage.message,
    taskId,
    "Agent-turn Input Manifest",
  );
  assertExactWakeRecipients(effectWakes, recipients, "Agent-turn recipient");
  assertExactWakeRecipients(
    manifestWakes,
    recipients,
    "Agent-turn Input Manifest recipient",
  );
  const wakeAuthorActorId = requiredString(
    inputManifest.wake_author_actor_id,
    "Agent-turn Input Manifest wake author Actor ID",
  );
  assertWakeAuthor(effectWakes, wakeAuthorActorId, "Agent-turn effect");
  assertWakeAuthor(
    manifestWakes,
    wakeAuthorActorId,
    "Agent-turn Input Manifest",
  );
  if (!samePublicTurnMessage(effectPublicMessage, manifestPublicMessage)) {
    throw new TaskWorkerProtocolError(
      "Agent-turn public context does not match its frozen Input Manifest",
    );
  }
  for (const actorId of recipients) {
    const effectWake = effectWakes.get(actorId);
    const manifestWake = manifestWakes.get(actorId);
    if (
      !effectWake ||
      !manifestWake ||
      !sameParticipantMetaWake(effectWake, manifestWake)
    ) {
      throw new TaskWorkerProtocolError(
        `Agent-turn wake ${actorId} does not match its frozen Input Manifest`,
      );
    }
  }
  return Object.freeze({
    publicContextMessage: effectPublicMessage,
    recipientWakes: effectWakes,
  });
};

const parseParticipantMetaWakes = (
  value: unknown,
  publicContextMessage: Message,
  taskId: string,
  name: string,
): ReadonlyMap<string, ParticipantMetaWake> => {
  const values = requiredArray(value, `${name} recipient wakes`);
  if (values.length === 0) {
    throw new TaskWorkerProtocolError(
      `${name} recipient wakes must not be empty`,
    );
  }
  const wakes = new Map<string, ParticipantMetaWake>();
  for (const item of values) {
    const wake = requiredRecord(item, `${name} recipient wake`);
    const actorId = requiredString(wake.actor_id, `${name} wake Actor ID`);
    const publicMessageIds = requiredStringArray(
      wake.public_message_ids,
      `${name} wake public Message IDs`,
    );
    if (
      publicMessageIds.length !== 1 ||
      publicMessageIds[0] !== publicContextMessage.messageId
    ) {
      throw new TaskWorkerProtocolError(
        `${name} wake ${actorId} does not reference its public Task context`,
      );
    }
    const parsed = Object.freeze({
      actorId,
      authorActorId: requiredString(
        wake.author_actor_id,
        `${name} wake author Actor ID`,
      ),
      metaSeq: positiveSafeInteger(wake.meta_seq, `${name} wake Meta sequence`),
      publicMessageIds,
      message: parseTurnMessage(
        requiredRecord(wake.message, `${name} wake Message`),
        canonicalMetaInboxId(actorId, taskId),
      ),
    });
    if (wakes.has(actorId)) {
      throw new TaskWorkerProtocolError(
        `${name} recipient wakes contain duplicate Actor IDs`,
      );
    }
    wakes.set(actorId, parsed);
  }
  return wakes;
};

const assertExactWakeRecipients = (
  wakes: ReadonlyMap<string, ParticipantMetaWake>,
  recipients: readonly string[],
  name: string,
): void => {
  if (
    wakes.size !== recipients.length ||
    recipients.some((actorId) => !wakes.has(actorId))
  ) {
    throw new TaskWorkerProtocolError(
      `${name} wakes do not exactly match frozen recipients`,
    );
  }
};

const assertWakeAuthor = (
  wakes: ReadonlyMap<string, ParticipantMetaWake>,
  authorActorId: string,
  name: string,
): void => {
  if (
    [...wakes.values()].some((wake) => wake.authorActorId !== authorActorId)
  ) {
    throw new TaskWorkerProtocolError(
      `${name} wake author does not match its frozen Input Manifest`,
    );
  }
};

const inputManifestHasRoutedWitness = (
  inputManifest: Readonly<Record<string, unknown>> | undefined,
): boolean =>
  inputManifest !== undefined &&
  (inputManifest.public_message_ids !== undefined ||
    inputManifest.public_context_message !== undefined ||
    inputManifest.recipient_wakes !== undefined ||
    inputManifest.wake_author_actor_id !== undefined);

const sameParticipantMetaWake = (
  left: ParticipantMetaWake,
  right: ParticipantMetaWake,
): boolean =>
  left.actorId === right.actorId &&
  left.authorActorId === right.authorActorId &&
  left.metaSeq === right.metaSeq &&
  sameStringArray(left.publicMessageIds, right.publicMessageIds) &&
  sameTurnMessage(left.message, right.message);

const sameTurnMessage = (left: Message, right: Message): boolean =>
  left.messageId === right.messageId &&
  left.rawMessage === right.rawMessage &&
  JSON.stringify(left.segments) === JSON.stringify(right.segments);

const samePublicTurnMessage = (
  left: PublicTurnMessage,
  right: PublicTurnMessage,
): boolean =>
  sameTurnMessage(left.message, right.message) &&
  left.author.actorId === right.author.actorId &&
  left.author.kind === right.author.kind &&
  left.author.displayName === right.author.displayName;

const sameStringArray = (
  left: readonly string[],
  right: readonly string[],
): boolean =>
  left.length === right.length &&
  left.every((value, index) => value === right[index]);

const parseTurnMessage = (
  value: Readonly<Record<string, unknown>>,
  sourceInboxId: string,
): Message =>
  Object.freeze({
    messageId: requiredString(value.message_id, "Agent-turn Message ID"),
    rawMessage: requiredString(value.raw_message, "Agent-turn raw Message"),
    segments: parseMessageSegments(value.segments),
    sourceInboxIds: [sourceInboxId],
  });

const parsePublicTurnMessage = (
  value: Readonly<Record<string, unknown>>,
  taskId: string,
): PublicTurnMessage => {
  const author = requiredRecord(
    value.author,
    "Agent-turn public Message author",
  );
  const kind = author.kind;
  if (kind !== "human" && kind !== "agent") {
    throw new TaskWorkerProtocolError(
      "Agent-turn public Message author kind is invalid",
    );
  }
  return Object.freeze({
    message: parseTurnMessage(value, `task:${taskId}`),
    author: Object.freeze({
      actorId: requiredString(
        author.actor_id,
        "Agent-turn public Message author Actor ID",
      ),
      kind,
      displayName: requiredString(
        author.display_name,
        "Agent-turn public Message author display name",
      ),
    }),
  });
};

const exactRecipientParticipants = (
  execution: TaskExecution,
  recipientActorIds: readonly string[],
): readonly TaskExecution["participants"][number][] => {
  const byActor = new Map(
    execution.participants.map((participant) => [
      participant.actor_id,
      participant,
    ]),
  );
  const recipients = recipientActorIds.map((actorId) => {
    const participant = byActor.get(actorId);
    if (!participant) {
      throw new TaskWorkerProtocolError(
        `Agent-turn recipient ${actorId} is not a frozen Task participant`,
      );
    }
    return participant;
  });
  if (new Set(recipientActorIds).size !== recipients.length) {
    throw new TaskWorkerProtocolError(
      "Agent-turn recipients contain duplicates",
    );
  }
  return Object.freeze(recipients);
};

const trustedMessageForActor = (
  payload: SubmitAgentTurnPayload,
  actorId: string,
): Message => {
  const wake = payload.recipientWakes?.get(actorId);
  if (payload.recipientWakes && !wake) {
    throw new TaskWorkerProtocolError(
      `Agent-turn recipient ${actorId} has no private Meta Inbox wake`,
    );
  }
  if (wake) return wake.message;
  if (payload.feedbackMessageId) {
    return Object.freeze({
      ...payload.message,
      sourceInboxIds: [canonicalMetaInboxId(actorId, payload.taskId)],
    });
  }
  throw new TaskWorkerProtocolError(
    `Agent-turn recipient ${actorId} has no private Meta Inbox ingress`,
  );
};

const canonicalMetaInboxId = (actorId: string, taskId: string): string =>
  `meta:${actorId}:${taskId}`;

const parseAgentTurnObservation = (value: unknown): AgentTurnObservation => {
  const record = requiredRecord(value, "Agent-turn observation");
  const runs = requiredArray(
    record.participant_runs,
    "Agent-turn participant runs",
  ).map((item): ParticipantRun => {
    const run = requiredRecord(item, "Agent-turn participant run");
    return Object.freeze({
      actor_id: requiredString(run.actor_id, "Agent-turn Actor ID"),
      agent_management_id: requiredString(
        run.agent_management_id,
        "Agent-turn management ID",
      ),
      agent_run_ref: requiredString(
        run.agent_run_ref,
        "Agent-turn run reference",
      ),
    });
  });
  const terminals = optionalArray(record.participant_terminals).map(
    (item): ParticipantTerminal => {
      const terminal = requiredRecord(item, "Agent-turn participant terminal");
      const status = terminal.status;
      if (
        status !== "succeeded" &&
        status !== "failed" &&
        status !== "canceled"
      ) {
        throw new TaskWorkerProtocolError(
          "Agent-turn terminal status is invalid",
        );
      }
      return Object.freeze({
        agent_run_ref: requiredString(
          terminal.agent_run_ref,
          "Agent-turn terminal run reference",
        ),
        status,
        ...(optionalString(terminal.terminal_code)
          ? { terminal_code: optionalString(terminal.terminal_code) }
          : {}),
        ...(optionalString(terminal.terminal_message)
          ? { terminal_message: optionalString(terminal.terminal_message) }
          : {}),
      });
    },
  );
  return Object.freeze({
    participantRuns: Object.freeze(runs),
    participantTerminals: Object.freeze(terminals),
  });
};

const observedTerminal = (
  observation: LocalTurnObservation | null,
): LocalTurnTerminal | null => {
  if (!observation) return null;
  if (
    observation.status === "succeeded" ||
    observation.status === "failed" ||
    observation.status === "canceled"
  ) {
    if (!observation.terminal) {
      throw new TaskWorkerProtocolError(
        `Local Run ${observation.runId} is terminal without terminal detail`,
      );
    }
    return observation.terminal;
  }
  return null;
};

const toParticipantTerminal = (
  agentRunRef: string,
  terminal: LocalTurnTerminal,
): ParticipantTerminal => {
  switch (terminal.type) {
    case "succeeded":
      return Object.freeze({ agent_run_ref: agentRunRef, status: "succeeded" });
    case "failed":
      return Object.freeze({
        agent_run_ref: agentRunRef,
        status: "failed",
        terminal_message: terminal.error,
      });
    case "canceled":
      return Object.freeze({ agent_run_ref: agentRunRef, status: "canceled" });
  }
};

const localTerminalStatus = (
  terminal: LocalTurnTerminal,
): "succeeded" | "failed" | "canceled" => terminal.type;

const executionContextRef = (value: unknown): ExecutionContextRef => {
  assertExecutionContextRef(value);
  return Object.freeze({ ...value });
};

const parseMessageSegments = (
  value: unknown,
): readonly [MessageSegment, ...MessageSegment[]] => {
  const values = requiredArray(value, "Agent-turn Message segments");
  if (values.length === 0) {
    throw new TaskWorkerProtocolError(
      "Agent-turn Message segments must not be empty",
    );
  }
  const segments = values.map((item): MessageSegment => {
    const segment = requiredRecord(item, "Agent-turn Message segment");
    switch (segment.type) {
      case "text":
        return {
          type: "text",
          content: requiredTextSegmentContent(segment.content),
        };
      case "html_fragment":
        return {
          type: "html_fragment",
          content: requiredTextSegmentContent(segment.content),
        };
      case "meeting_notes":
        // A recording's quick notes reach an Agent as their text.
        return {
          type: "text",
          content: requiredTextSegmentContent(segment.content),
        };
      case "reference": {
        const content = requiredString(
          segment.content,
          "Message segment content",
        );
        const targetType = segment.target_type;
        if (targetType !== "agent" && targetType !== "user") {
          throw new TaskWorkerProtocolError(
            "Reference Message segment target type is invalid",
          );
        }
        return {
          type: "reference",
          content,
          target: requiredString(segment.target, "Reference target"),
          target_type: targetType,
        };
      }
      case "file":
        return {
          type: "file",
          content: requiredString(segment.content, "Message segment content"),
          document_id: requiredString(
            segment.document_id,
            "Message Document ID",
          ),
          document_version_id: requiredString(
            segment.document_version_id,
            "Message Document Version ID",
          ),
        };
      case "document":
        if (
          segment.presentation !== undefined &&
          segment.presentation !== "card" &&
          segment.presentation !== "inline"
        ) {
          throw new TaskWorkerProtocolError(
            "Document Message segment presentation is invalid",
          );
        }
        return {
          type: "document",
          content: requiredString(segment.content, "Message segment content"),
          document_id: requiredString(
            segment.document_id,
            "Message Document ID",
          ),
          ...(segment.presentation === undefined
            ? {}
            : { presentation: segment.presentation }),
        };
      case "skill":
        return {
          type: "skill",
          content: requiredString(segment.content, "Message segment content"),
          target: requiredString(segment.target, "Skill target"),
          skill_id: requiredString(segment.skill_id, "Skill ID"),
          manifest_version: requiredString(
            segment.manifest_version,
            "Skill manifest version",
          ),
        };
      default:
        throw new TaskWorkerProtocolError(
          "Agent-turn Message segment type is invalid",
        );
    }
  });
  return Object.freeze([segments[0]!, ...segments.slice(1)]);
};

const driveWithHeartbeat = async (
  client: TeamHubTaskWorkerClient,
  initialLease: TaskWorkerLease,
  leaseSeconds: number,
  signal: AbortSignal,
  operation: (lease: TaskWorkerLease, signal: AbortSignal) => Promise<void>,
): Promise<void> => {
  const heartbeatController = new AbortController();
  const heartbeatSignal = combineSignals(signal, heartbeatController.signal);
  const driveController = new AbortController();
  const driveSignal = combineSignals(signal, driveController.signal);
  let currentLease = initialLease;
  let heartbeatFailure: unknown;
  const intervalMs = Math.max(
    MIN_HEARTBEAT_INTERVAL_MS,
    Math.floor((leaseSeconds * 1_000) / 3),
  );
  const heartbeat = (async () => {
    while (!heartbeatSignal.aborted) {
      await waitForWake(intervalMs, heartbeatSignal);
      if (heartbeatSignal.aborted) return;
      try {
        currentLease = await client.heartbeat({
          lease: currentLease,
          leaseSeconds,
          signal: heartbeatSignal,
        });
      } catch (error) {
        heartbeatFailure = error;
        driveController.abort(error);
        return;
      }
    }
  })();
  try {
    await operation(currentLease, driveSignal);
    if (heartbeatFailure) throw asError(heartbeatFailure);
  } finally {
    heartbeatController.abort();
    driveController.abort();
    await heartbeat;
  }
};

const requireClaimLease = (bundle: TaskWorkerExecution): TaskWorkerLease => {
  if (!bundle.lease) {
    throw new TaskWorkerProtocolError("Claimed Task omitted its Worker lease");
  }
  return bundle.lease;
};

const combineSignals = (
  first: AbortSignal,
  second?: AbortSignal,
): AbortSignal => (second ? AbortSignal.any([first, second]) : first);

const waitForWake = async (
  delayMs: number,
  signal: AbortSignal,
): Promise<void> => {
  if (signal.aborted) return;
  await new Promise<void>((resolve) => {
    const done = (): void => {
      clearTimeout(timer);
      signal.removeEventListener("abort", done);
      resolve();
    };
    const timer = setTimeout(done, delayMs);
    signal.addEventListener("abort", done, { once: true });
  });
};

const requiredStringArray = (value: unknown, name: string): readonly string[] =>
  Object.freeze(
    requiredArray(value, name).map((item) => requiredString(item, name)),
  );

const requiredArray = (value: unknown, name: string): readonly unknown[] => {
  if (!Array.isArray(value))
    throw new TaskWorkerProtocolError(`${name} is invalid`);
  return value;
};

const optionalArray = (value: unknown): readonly unknown[] =>
  value === undefined ? [] : requiredArray(value, "optional array");

const requiredRecord = (
  value: unknown,
  name: string,
): Readonly<Record<string, unknown>> => {
  if (!isRecord(value)) throw new TaskWorkerProtocolError(`${name} is invalid`);
  return value;
};

const optionalRecord = (
  value: unknown,
): Readonly<Record<string, unknown>> | undefined =>
  value === undefined ? undefined : requiredRecord(value, "optional object");

const requiredString = (value: unknown, name: string): string => {
  if (typeof value !== "string" || value.trim() === "") {
    throw new TaskWorkerProtocolError(`${name} must be a non-empty string`);
  }
  return value;
};

const requiredTextSegmentContent = (value: unknown): string => {
  if (typeof value !== "string" || value.length === 0) {
    throw new TaskWorkerProtocolError(
      "Message segment content must be a non-empty string",
    );
  }
  return value;
};

const optionalString = (value: unknown): string | undefined =>
  typeof value === "string" && value.trim() !== "" ? value : undefined;

const positiveSafeInteger = (value: unknown, name: string): number => {
  if (!Number.isSafeInteger(value) || (value as number) < 1) {
    throw new TaskWorkerProtocolError(
      `${name} must be a positive safe integer`,
    );
  }
  return value as number;
};

export class TaskWorkerProtocolError extends Error {
  override readonly name = "TaskWorkerProtocolError";
}