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.

35.3 KB
Raw Blame
import { queuedMetaRunKind } from "./run-kind.js";
import type { RunKind } from "../../model-tasks.js";
import { logAgentEvent } from "../observability/agent-log.js";
import { acceptedNotificationInput } from "../prompt/accepted-notification.js";
import {
  encodeExecutionContextRef,
  type ExecutionContextRef,
} from "./context-ref.js";
import { materializeGhostResources, type SkillDescriptor } from "./ghost.js";
import type {
  RuntimeExecutionFailure,
  RuntimeSession as ProviderRuntimeSession,
} from "./provider.js";
import type {
  LocalTurnStatus,
  LocalTurnTerminal,
  Message,
  NonEmptyReadonlyArray,
  RunCancellationStatus,
} from "./types.js";
import {
  TeamHubRuntimeStateError,
  runtimeClaimId,
  type AcceptedContextState,
  type RuntimeInput,
  type RuntimeSession as TeamHubRuntimeSession,
  type RuntimeSessionCheckpoint,
  type TeamHubRuntimeStateClient,
  isTeamHubNotFound,
} from "./teamhub-runtime-state-client.js";
import { isRecord } from "@linger/service-kit";

export type RuntimeStateAwaitable<T> = T | PromiseLike<T>;

export interface ClaimedLocalRun {
  /** The Context received input before this Run's first input. */
  readonly continuesContext?: boolean;
  /** Process-local only; absent for Runs queued before this process. */
  readonly acceptedAtMonotonicMs?: number;
  /** Earliest TeamHub input `created_at` as epoch ms; absent on old TeamHub. */
  readonly inputReceivedAtMs?: number;
  readonly cancellationRequested?: boolean;
  /**
   * The Agent's current profile when this Context's Session started under an
   * older one; it precedes this Run's input once.
   */
  readonly profileUpdate?: ProfileUpdate;
  runId: string;
  attemptCount: number;
  messages: NonEmptyReadonlyArray<Message>;
}

export interface ProfileUpdate {
  readonly configurationRevision: number;
  readonly name: string;
  readonly instructions: string;
}

/**
 * A steer a Message transaction queued for this Context: a targeted Message
 * for the running Run that reads its Inbox, or a native question's answer for
 * the Run that asked it (runId set, message.runtimeResponses present).
 */
export interface MessageSteer {
  readonly groupId: string;
  readonly inputId: string;
  readonly inboxId?: string;
  readonly runId?: string;
  readonly message: Message;
}

export type TrustedNotificationAcceptance =
  | { readonly status: "already_accepted" }
  | { readonly status: "committed"; readonly groupId: string };

export type LocalRunStatus = LocalTurnStatus;

/** The observed Turn terminal, plus the failure detail Runtime State keeps. */
export type LocalRunTerminal =
  | Exclude<LocalTurnTerminal, { readonly type: "failed" }>
  | (Extract<LocalTurnTerminal, { readonly type: "failed" }> & {
      readonly failure?: RuntimeExecutionFailure;
    });

export interface LocalRun {
  cancellationRequested?: boolean;
  runId: string;
  initialMessageIds: NonEmptyReadonlyArray<string>;
  steerMessageIds: readonly string[];
  status: LocalRunStatus;
  attemptCount: number;
  terminal?: LocalRunTerminal;
}

export interface ContextRuntimeStatePort {
  /** The Agent Service epoch a Runner execution checkpoint names. */
  executionEpoch?(): string;
  acceptTrustedNotification(
    executionRunRef: string,
    message: Message,
  ): RuntimeStateAwaitable<TrustedNotificationAcceptance>;
  enqueueTrustedTurn(
    messages: NonEmptyReadonlyArray<Message>,
  ): RuntimeStateAwaitable<string>;
  cancelTrustedTurn(
    messages: NonEmptyReadonlyArray<Message>,
  ): RuntimeStateAwaitable<{
    readonly runId: string;
    readonly status: RunCancellationStatus;
  }>;
  claimLocalRun(): RuntimeStateAwaitable<ClaimedLocalRun | null>;
  requeueLocalRun(runId: string): RuntimeStateAwaitable<void>;
  /**
   * Resolves to "upstream_canceled" when TeamHub had already canceled the Run
   * for a reason and kept that terminal instead of this one.
   */
  finishLocalRun(
    runId: string,
    terminal: LocalRunTerminal,
    session?: ProviderRuntimeSession,
    stopSignal?: AbortSignal,
  ): RuntimeStateAwaitable<"upstream_canceled" | void>;
  /** Resolve only a confirmed upstream cancellation of this revoked execution. */
  reconcileRevokedLocalRun?(
    runId: string,
    error: unknown,
  ): RuntimeStateAwaitable<Extract<
    LocalRunTerminal,
    { type: "canceled" }
  > | null>;
  /** Re-read queued Local Runs after MCP resolve can make a Document Run claimable. */
  refreshWorkState?(): RuntimeStateAwaitable<void>;
  /** Message steers the last work-state read listed, each handed out once. */
  takeMessageSteers?(): readonly MessageSteer[];
  /** A run.queued hint proves queued work without another read. */
  noteQueuedRun?(): void;
  cancelLocalRun(runId: string): RuntimeStateAwaitable<RunCancellationStatus>;
  getLocalRun(runId: string): RuntimeStateAwaitable<LocalRun | null>;
  /**
   * Reports whether TeamHub persisted a visible reply for the Run, so an
   * apparent missing reply from activity classification can be confirmed
   * before failing the Run.
   */
  hasLocalRunReplied(
    runId: string,
    signal?: AbortSignal,
  ): RuntimeStateAwaitable<boolean>;
  enqueueSteer(
    groupId: string,
    messages: NonEmptyReadonlyArray<Message>,
  ): RuntimeStateAwaitable<string>;
  assignSteerRun(groupId: string, runId: string): RuntimeStateAwaitable<void>;
  completeSteer(
    groupId: string,
    runId: string,
    outcome: "applied" | "uncertain",
  ): RuntimeStateAwaitable<void>;
  queuedMetaKind?(signal: AbortSignal): Promise<RunKind>;
  hasQueuedRuns(): boolean;
  hasPendingWork(): boolean;
  /** Inputs accepted by this process that are not yet claimed or settled. */
  acceptedInputPending?(): boolean;
  earliestAcceptedInputMs?(): number | undefined;
  getRuntimeSession(): RuntimeStateAwaitable<ProviderRuntimeSession>;
  setRuntimeSession(
    session: ProviderRuntimeSession,
    executionResources?: ExecutionResources | null,
  ): RuntimeStateAwaitable<void>;
  getExecutionResources(): RuntimeStateAwaitable<ExecutionResources | null>;
  setExecutionResources(
    resources: ExecutionResources,
  ): RuntimeStateAwaitable<void>;
  clearRuntimeSession(): RuntimeStateAwaitable<boolean>;
  /**
   * Drop a RuntimeSession checkpointed under an older configuration revision.
   * Runtime activation calls this; read-only inspection must not, so Debug
   * History keeps reading the last session until the Context runs again.
   */
  discardStaleRuntimeSession?(): RuntimeStateAwaitable<boolean>;
  close(): RuntimeStateAwaitable<void>;
}

/** Exact loaded versions, never a permission grant or a package credential. */
export interface ExecutionSkillDescriptor extends SkillDescriptor {
  readonly manifestId: string;
  readonly source: "default" | "explicit";
}

export interface ExecutionResources {
  readonly version: 1;
  readonly effectiveSha256: string;
  readonly skills: readonly ExecutionSkillDescriptor[];
}

const SHA256 = /^[a-f0-9]{64}$/u;
const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,511}$/u;
const CREDENTIAL = /(?:mcp_ctx_|cli_ctx_)[A-Za-z0-9_-]{43}/u;

export const parseExecutionResources = (value: unknown): ExecutionResources => {
  if (!isRecord(value)) throw new TypeError("Invalid execution resources");
  assertKeys(value, ["version", "effectiveSha256", "skills"]);
  if (
    value.version !== 1 ||
    typeof value.effectiveSha256 !== "string" ||
    !SHA256.test(value.effectiveSha256) ||
    !Array.isArray(value.skills) ||
    value.skills.length > 100
  )
    throw new TypeError("Invalid execution resources");
  const skillIds = new Set<string>();
  const manifestIds = new Set<string>();
  const packageNames = new Set<string>();
  const skills = value.skills.map((item) => {
    if (!isRecord(item)) throw new TypeError("Invalid execution Skill");
    assertKeys(item, [
      "skillId",
      "manifestId",
      "manifestVersion",
      "name",
      "packageName",
      "packageSha256",
      "config",
      "source",
    ]);
    if (
      typeof item.manifestId !== "string" ||
      !IDENTIFIER.test(item.manifestId) ||
      (item.source !== "default" && item.source !== "explicit")
    )
      throw new TypeError("Invalid execution Skill version");
    const { manifestId, source, ...descriptor } = item;
    const skill = materializeGhostResources({
      skills: [descriptor as unknown as SkillDescriptor],
    }).skills[0]!;
    if (
      skillIds.has(skill.skillId) ||
      manifestIds.has(manifestId) ||
      packageNames.has(skill.packageName)
    )
      throw new TypeError("Duplicate execution Skill");
    skillIds.add(skill.skillId);
    manifestIds.add(manifestId);
    packageNames.add(skill.packageName);
    return Object.freeze({ ...skill, manifestId, source });
  });
  const resources: ExecutionResources = {
    version: 1,
    effectiveSha256: value.effectiveSha256,
    skills: Object.freeze(skills),
  };
  assertNoCredentials(resources);
  return Object.freeze(resources);
};

/** The provider receives only its native object; schema 1 remains readable. */
export const readRuntimeSessionCheckpoint = (checkpoint: {
  readonly schema_version: string;
  readonly session: Record<string, unknown>;
  readonly thread_id?: string;
}): {
  nativeSession: Record<string, unknown> | null;
  executionResources: ExecutionResources | null;
} => {
  if (checkpoint.schema_version === "1") {
    return { nativeSession: checkpoint.session, executionResources: null };
  }
  if (checkpoint.schema_version !== "2" || !isRecord(checkpoint.session))
    throw new TypeError("Unsupported RuntimeSession schema");
  assertKeys(checkpoint.session, ["nativeSession", "executionResources"]);
  const { nativeSession } = checkpoint.session;
  if (nativeSession !== null && !isRecord(nativeSession))
    throw new TypeError("Invalid native RuntimeSession");
  if (
    nativeSession === null
      ? checkpoint.thread_id !== undefined
      : nativeSession.threadId !== checkpoint.thread_id
  )
    throw new TypeError("RuntimeSession thread identity mismatch");
  return {
    nativeSession,
    executionResources: parseExecutionResources(
      checkpoint.session.executionResources,
    ),
  };
};

const assertKeys = (
  value: Record<string, unknown>,
  allowed: readonly string[],
): void => {
  if (Object.keys(value).some((key) => !allowed.includes(key)))
    throw new TypeError("Unexpected execution resource metadata");
};

const assertNoCredentials = (value: unknown): void => {
  if (typeof value === "string" && CREDENTIAL.test(value))
    throw new TypeError("Execution resources must not contain credentials");
  if (Array.isArray(value)) value.forEach(assertNoCredentials);
  else if (isRecord(value))
    for (const [key, item] of Object.entries(value)) {
      if (
        ["authorization", "httpheaders"].includes(
          key.toLowerCase().replaceAll("_", ""),
        )
      )
        throw new TypeError("Execution resources must not contain credentials");
      assertNoCredentials(item);
    }
};

export interface TeamHubContextRuntimeStateOptions {
  readonly client: TeamHubRuntimeStateClient;
  readonly ref: ExecutionContextRef;
  readonly configurationRevision: string;
  readonly providerKind: string;
  /** The Context state an acceptance committed, for the Context record. */
  readonly onInputCommitted?: (state: AcceptedContextState) => void;
  /**
   * Called before a write that advances the Context revision
   * without returning it; the result runs once that write committed.
   */
  readonly trackOwnRevisionAdvance?: () => () => void;
}

/**
 * TeamHub-backed implementation of the executor's durable state port. The only
 * values retained locally are the last Session read, execution resources not
 * yet checkpointed and bounded work observations; every mutation names this
 * process's Agent Service epoch and goes through a generated TeamHub API.
 */
export const createTeamHubContextRuntimeState = async (
  options: TeamHubContextRuntimeStateOptions,
): Promise<ContextRuntimeStatePort> => {
  const state = new TeamHubContextRuntimeState(options);
  await state.initialize();
  return state;
};

class TeamHubContextRuntimeState implements ContextRuntimeStatePort {
  readonly #client: TeamHubRuntimeStateClient;
  readonly #contextKey: string;
  readonly #configurationRevision: string;
  readonly #providerKind: string;
  readonly #epoch: string;
  readonly #onInputCommitted:
    | ((state: AcceptedContextState) => void)
    | undefined;
  readonly #trackOwnRevisionAdvance: (() => () => void) | undefined;
  #session: TeamHubRuntimeSession | null = null;
  // Resources the Runtime loaded for its next turn; they reach TeamHub with
  // the next Session checkpoint instead of a write of their own.
  #pendingResources: ExecutionResources | undefined;
  #queuedKind?: RunKind;
  #hasQueuedRuns = false;
  #hasPendingWork = false;
  #messageSteers: readonly MessageSteer[] = [];
  // Steers handed to the executor stay here until a later read no longer lists
  // them, so overlapping reads never hand one steer out twice.
  readonly #takenSteerGroups = new Set<string>();
  // Bumped whenever a committed TeamHub command proves queued work. A
  // work-state read that started before the bump may predate that commit.
  #queuedWorkMark = 0;
  readonly #acceptedAt = new Map<string, number>();
  #closed = false;
  readonly #terminalRecoveryStop = new AbortController();

  constructor(options: TeamHubContextRuntimeStateOptions) {
    this.#client = options.client;
    this.#contextKey = encodeExecutionContextRef(options.ref);
    this.#configurationRevision = parsePositiveInt64(
      options.configurationRevision,
      "configurationRevision",
    );
    if (!options.providerKind.trim()) {
      throw new TypeError("providerKind must not be empty");
    }
    this.#providerKind = options.providerKind;
    this.#epoch = options.client.epoch;
    this.#onInputCommitted = options.onInputCommitted;
    this.#trackOwnRevisionAdvance = options.trackOwnRevisionAdvance;
  }

  async initialize(): Promise<void> {
    this.#assertOpen();
    const [, session] = await Promise.all([
      this.#refreshWorkState(),
      this.#client.getSession(this.#contextKey),
    ]);
    this.#session = session.available ? (session.session ?? null) : null;
  }

  async discardStaleRuntimeSession(): Promise<boolean> {
    this.#assertOpen();
    // Compatibility is a current server observation, never a cached Session or
    // provider claim. Failed reads leave the last checkpoint intact.
    const current = await this.#client.getSession(this.#contextKey);
    this.#session = current.available ? (current.session ?? null) : null;
    if (
      !this.#session ||
      this.#session.configuration_revision === this.#configurationRevision ||
      (this.#session.provider_kind === this.#providerKind &&
        this.#session.compatible_configuration_revision ===
          this.#configurationRevision)
    ) {
      return false;
    }
    const cleared = await this.#clearRuntimeSession(
      this.#configurationRevision,
    );
    if (!cleared) {
      throw new Error("Stale Runtime Session could not be cleared");
    }
    return true;
  }

  async acceptTrustedNotification(
    executionRunRef: string,
    message: Message,
  ): Promise<TrustedNotificationAcceptance> {
    this.#assertOpen();
    const result = await this.#client.acceptTrustedNotification({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      execution_run_ref: executionRunRef,
      input: toRuntimeInput(message, "internal"),
    });
    if (result.status === "already_accepted") {
      return { status: "already_accepted" };
    }
    if (!result.steer_group_id) {
      throw new Error(
        "TeamHub accepted trusted notification without a steer group ID",
      );
    }
    this.#hasPendingWork = true;
    return { status: "committed", groupId: result.steer_group_id };
  }

  async enqueueTrustedTurn(
    messages: NonEmptyReadonlyArray<Message>,
  ): Promise<string> {
    this.#assertOpen();
    const result = await this.#client.submitTrustedTurn({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      inputs: messages.map((message) =>
        toRuntimeInput(message, "trusted_turn"),
      ),
    });
    if (result.created) {
      this.#recordAcceptedRun(result.run_id);
      // A freshly created Run is authoritative queued work. A repeated
      // submission adds no new information: the original commit or the last
      // refresh already set the truthful local pending state.
      this.#recordQueuedWork();
    }
    if (result.context) this.#onInputCommitted?.(result.context);
    return result.run_id;
  }

  async cancelTrustedTurn(messages: NonEmptyReadonlyArray<Message>): Promise<{
    readonly runId: string;
    readonly status: RunCancellationStatus;
  }> {
    this.#assertOpen();
    const submitted = await this.#client.submitTrustedTurn({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      inputs: messages.map((message) =>
        toRuntimeInput(message, "trusted_turn"),
      ),
    });
    const result = await this.#client.cancelRun({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      run_id: submitted.run_id,
    });
    if (result.status === "canceled" || result.status === "already_terminal")
      this.#acceptedAt.delete(submitted.run_id);
    await this.#refreshWorkState();
    return { runId: submitted.run_id, status: result.status };
  }

  executionEpoch(): string {
    return this.#epoch;
  }

  async claimLocalRun(): Promise<ClaimedLocalRun | null> {
    this.#assertOpen();
    const revisionAdvanced = this.#trackOwnRevisionAdvance?.();
    const result = await this.#client.claimRun({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      claim_id: runtimeClaimId(),
    });
    if (!result.claimed || !result.run) {
      await this.#refreshWorkState();
      return null;
    }
    revisionAdvanced?.();
    // The claim response is the durable handoff. Finish/requeue refresh latest
    // work, and racing notifications retain their own refresh request.
    this.#hasQueuedRuns = false;
    this.#hasPendingWork = true;
    return {
      runId: result.run.run_id,
      continuesContext: result.run.continues_context,
      acceptedAtMonotonicMs: this.#acceptedAt.get(result.run.run_id),
      inputReceivedAtMs: earliestInputReceivedAtMs(result.run.inputs),
      attemptCount: result.run.attempt_count,
      cancellationRequested: result.run.cancellation_requested,
      ...(result.run.profile_update
        ? {
            profileUpdate: {
              configurationRevision:
                result.run.profile_update.configuration_revision,
              name: result.run.profile_update.name,
              instructions: result.run.profile_update.instructions,
            },
          }
        : {}),
      messages: asNonEmpty(
        result.run.inputs.map((input) => toMessage(input.payload)),
      ),
    };
  }

  async requeueLocalRun(runId: string): Promise<void> {
    this.#assertOpen();
    await this.#client.requeueRun({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      run_id: runId,
    });
    await this.#refreshWorkState();
  }

  async finishLocalRun(
    runId: string,
    terminal: LocalRunTerminal,
    session?: ProviderRuntimeSession,
    stopSignal?: AbortSignal,
  ): Promise<"upstream_canceled" | void> {
    this.#assertOpen();
    const signal = stopSignal
      ? AbortSignal.any([stopSignal, this.#terminalRecoveryStop.signal])
      : this.#terminalRecoveryStop.signal;
    let body: Parameters<TeamHubRuntimeStateClient["finishRun"]>[0] | undefined;
    let delayMs = 1_000;
    let retry = false;
    let writeAttempt = 0;
    let upstreamCanceled: boolean;
    for (;;) {
      this.#assertOpen();
      try {
        if (!body) {
          const checkpoint =
            session === undefined
              ? undefined
              : await this.#toCheckpoint(session);
          body = {
            context_key: this.#contextKey,
            epoch: this.#epoch,
            run_id: runId,
            terminal: terminal,
            ...(checkpoint ? { session: checkpoint } : {}),
          };
        }
        // Even during stop, allow one bounded attempt to record cancellation.
        // Subsequent attempts are interruptible and repeat the exact request.
        writeAttempt += 1;
        logAgentEvent("info", "local_run.finish_requested", {
          runId,
          writeAttempt,
          resultCode: terminal.type,
          observedAtUnixMs: Date.now(),
        });
        const result = await this.#client.finishRun(
          body,
          retry ? signal : undefined,
        );
        logAgentEvent("info", "local_run.finish_acknowledged", {
          runId,
          writeAttempt,
          resultCode: terminal.type,
          observedAtUnixMs: Date.now(),
        });
        if (result.session) {
          this.#session = result.session;
          this.#pendingResources = undefined;
        }
        this.#acceptedAt.delete(runId);
        // TeamHub keeps a cancellation it wrote for a reason and returns it.
        upstreamCanceled =
          result.run.status === "canceled" && terminal.type !== "canceled";
        break;
      } catch (error) {
        // A rejected Session must not keep the Run running forever: the
        // terminal is what the Human waits on. Finish once more without the
        // Session; the Context then starts its next Run without one.
        if (body?.session !== undefined && isRuntimeStateConflict(error)) {
          logAgentEvent("warn", "local_run.session_checkpoint_rejected", {
            runId,
            writeAttempt,
            error,
          });
          const { session: _rejected, ...withoutSession } = body;
          body = withoutSession;
          continue;
        }
        if (!isTransientTerminalFailure(error) || signal.aborted) throw error;
        try {
          await waitForTerminalRetry(delayMs, signal);
        } catch {
          throw error;
        }
        retry = true;
        delayMs = Math.min(delayMs * 2, 5_000);
      }
    }
    // The terminal is already acknowledged. A failed read cannot undo it or
    // cause the executor to submit a contradictory failed terminal.
    try {
      await this.#refreshWorkState();
    } catch (error) {
      if (!isTransientTerminalFailure(error)) throw error;
    }
    return upstreamCanceled ? "upstream_canceled" : undefined;
  }

  async reconcileRevokedLocalRun(
    runId: string,
    error: unknown,
  ): Promise<Extract<LocalRunTerminal, { type: "canceled" }> | null> {
    this.#assertOpen();
    const runtimeConflict =
      error instanceof TeamHubRuntimeStateError &&
      error.status === 409 &&
      (error.code === "AGENT_RUNTIME_CONFLICT" ||
        error.code === "CONTEXT_FENCED");
    if (!runtimeConflict) return null;
    const context = await this.#client.getContext(this.#contextKey);
    const run = await this.#client.getRun(this.#contextKey, runId);
    // A remote conflict alone cannot settle a Run.
    if (run.status !== "canceled" || run.terminal?.type !== "canceled")
      return null;
    this.#acceptedAt.delete(runId);
    if (context.terminal_reason) return { type: "canceled" };
    // TeamHub records why it canceled a Run (Task archive or completion,
    // membership revocation, Context deletion). The executor's own cancellation
    // never carries a reason.
    if (typeof run.terminal.reason === "string" && run.terminal.reason !== "")
      return { type: "canceled" };
    return null;
  }

  async cancelLocalRun(runId: string): Promise<RunCancellationStatus> {
    this.#assertOpen();
    const result = await this.#client.cancelRun({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      run_id: runId,
    });
    if (result.status === "canceled" || result.status === "already_terminal")
      this.#acceptedAt.delete(runId);
    await this.#refreshWorkState();
    return result.status;
  }

  async getLocalRun(runId: string): Promise<LocalRun | null> {
    this.#assertOpen();
    let result;
    try {
      result = await this.#client.getRun(this.#contextKey, runId);
    } catch (error) {
      if (isTeamHubNotFound(error)) return null;
      throw error;
    }
    if (
      result.status === "succeeded" ||
      result.status === "failed" ||
      result.status === "canceled"
    )
      this.#acceptedAt.delete(runId);
    const terminal = result.terminal as LocalRunTerminal | undefined;
    return {
      runId: result.run_id,
      cancellationRequested: result.cancellation_requested,
      initialMessageIds: asNonEmpty(result.initial_input_ids),
      steerMessageIds: result.steer_input_ids,
      status: result.status,
      attemptCount: result.attempt_count,
      ...(terminal ? { terminal } : {}),
    };
  }

  async hasLocalRunReplied(
    runId: string,
    signal?: AbortSignal,
  ): Promise<boolean> {
    this.#assertOpen();
    const result = await this.#client.getRunReplyStatus(
      this.#contextKey,
      runId,
      signal,
    );
    return result.replied;
  }

  async enqueueSteer(
    groupId: string,
    _messages: NonEmptyReadonlyArray<Message>,
  ): Promise<string> {
    this.#assertOpen();
    const result = await this.#client.enqueueSteer({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      group_id: groupId,
    });
    this.#recordAcceptedRun(result.run_id);
    await this.#refreshWorkState();
    return result.run_id;
  }

  async assignSteerRun(groupId: string, runId: string): Promise<void> {
    this.#assertOpen();
    await this.#client.assignSteerRun({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      group_id: groupId,
      run_id: runId,
    });
  }

  async completeSteer(
    groupId: string,
    runId: string,
    outcome: "applied" | "uncertain",
  ): Promise<void> {
    this.#assertOpen();
    await this.#client.completeSteer({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      group_id: groupId,
      run_id: runId,
      outcome,
    });
    await this.#refreshWorkState();
  }

  async queuedMetaKind(signal: AbortSignal): Promise<RunKind> {
    if (this.#queuedKind) return this.#queuedKind;
    const state = await this.#client.getWorkState(this.#contextKey, signal);
    return queuedMetaRunKind(state.next_run_origins ?? []);
  }

  hasQueuedRuns(): boolean {
    return this.#hasQueuedRuns;
  }

  hasPendingWork(): boolean {
    return this.#hasPendingWork;
  }

  /** Whether an input accepted by this process is still unclaimed or unsettled. */
  acceptedInputPending(): boolean {
    return this.#acceptedAt.size > 0;
  }

  /** Earliest monotonic accept time among pending inputs, for latency evidence. */
  earliestAcceptedInputMs(): number | undefined {
    let earliest: number | undefined;
    for (const acceptedAt of this.#acceptedAt.values()) {
      if (earliest === undefined || acceptedAt < earliest)
        earliest = acceptedAt;
    }
    return earliest;
  }

  async getRuntimeSession(): Promise<ProviderRuntimeSession> {
    this.#assertOpen();
    const result = await this.#client.getSession(this.#contextKey);
    this.#session = result.available ? (result.session ?? null) : null;
    return this.#session
      ? readRuntimeSessionCheckpoint(this.#session).nativeSession
      : null;
  }

  getExecutionResources(): ExecutionResources | null {
    this.#assertOpen();
    if (this.#pendingResources) return this.#pendingResources;
    return this.#session
      ? readRuntimeSessionCheckpoint(this.#session).executionResources
      : null;
  }

  /**
   * Records the resources the Runtime loaded for its next turn. They are
   * checkpointed with the next Session, so starting a Run writes nothing.
   */
  setExecutionResources(resources: ExecutionResources): void {
    this.#assertOpen();
    this.#pendingResources = parseExecutionResources(resources);
  }

  async setRuntimeSession(
    session: ProviderRuntimeSession,
    executionResources?: ExecutionResources | null,
  ): Promise<void> {
    this.#assertOpen();
    const checkpoint = await this.#toCheckpoint(session, executionResources);
    const revisionAdvanced = this.#trackOwnRevisionAdvance?.();
    this.#session = await this.#client.checkpointSession({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      checkpoint,
    });
    this.#pendingResources = undefined;
    revisionAdvanced?.();
  }

  async clearRuntimeSession(): Promise<boolean> {
    return this.#clearRuntimeSession();
  }

  async #clearRuntimeSession(
    expectedCurrentConfigurationRevision?: string,
  ): Promise<boolean> {
    this.#assertOpen();
    this.#pendingResources = undefined;
    if (!this.#session) return false;
    const result = await this.#client.clearSession({
      context_key: this.#contextKey,
      epoch: this.#epoch,
      configuration_revision: this.#session.configuration_revision,
      ...(expectedCurrentConfigurationRevision
        ? {
            expected_current_configuration_revision:
              expectedCurrentConfigurationRevision,
          }
        : {}),
    });
    if (result.cleared) this.#session = null;
    return result.cleared;
  }

  async close(): Promise<void> {
    this.#closed = true;
    this.#acceptedAt.clear();
    this.#terminalRecoveryStop.abort();
  }

  #recordAcceptedRun(runId: string): void {
    if (!this.#closed && !this.#acceptedAt.has(runId))
      this.#acceptedAt.set(runId, performance.now());
  }

  async #toCheckpoint(
    session: ProviderRuntimeSession,
    executionResources?: ExecutionResources | null,
  ): Promise<RuntimeSessionCheckpoint> {
    if (!this.#session) {
      const current = await this.#client.getSession(this.#contextKey);
      this.#session = current.available ? (current.session ?? null) : null;
    }
    return this.#buildCheckpoint(session, executionResources);
  }

  #buildCheckpoint(
    session: ProviderRuntimeSession,
    executionResources?: ExecutionResources | null,
  ): RuntimeSessionCheckpoint {
    const resources =
      executionResources === undefined
        ? (this.#pendingResources ??
          (this.#session
            ? readRuntimeSessionCheckpoint(this.#session).executionResources
            : null))
        : executionResources === null
          ? null
          : parseExecutionResources(executionResources);
    if (!isRecord(session) && !(session === null && resources))
      throw new TypeError("RuntimeSession must be an object");
    const threadId = isRecord(session)
      ? stringValue(session.threadId)
      : undefined;
    if (isRecord(session) && session.threadId === "")
      throw new TypeError(
        "Pending native RuntimeSession must not be checkpointed",
      );
    return {
      expected_revision: this.#session?.revision ?? "0",
      provider_kind: this.#providerKind,
      schema_version: resources ? "2" : "1",
      session: resources
        ? { nativeSession: session, executionResources: resources }
        : (session as Record<string, unknown>),
      ...(threadId ? { thread_id: threadId } : {}),
      configuration_revision: this.#configurationRevision,
    };
  }

  async refreshWorkState(): Promise<void> {
    this.#assertOpen();
    await this.#refreshWorkState();
  }

  async #refreshWorkState(): Promise<void> {
    const mark = this.#queuedWorkMark;
    const state = await this.#client.getWorkState(this.#contextKey);
    // Queued work committed while this read was in flight stays visible; a
    // stale positive only costs one empty claim, which refreshes again.
    const queuedMeanwhile = mark !== this.#queuedWorkMark;
    this.#queuedKind = queuedMeanwhile
      ? undefined
      : queuedMetaRunKind(state.next_run_origins ?? []);
    this.#hasQueuedRuns = state.has_queued_runs || queuedMeanwhile;
    this.#hasPendingWork = state.has_pending_work || queuedMeanwhile;
    const steers = (state.message_steers ?? []).flatMap((input) =>
      input.steer_group_id
        ? [
            Object.freeze({
              groupId: input.steer_group_id,
              ...(input.local_run_id ? { runId: input.local_run_id } : {}),
              ...(input.source_inbox_id
                ? { inboxId: input.source_inbox_id }
                : {}),
              inputId: input.input_id,
              message: toMessage(input.payload),
            }),
          ]
        : [],
    );
    const listed = new Set(steers.map((steer) => steer.groupId));
    for (const groupId of this.#takenSteerGroups)
      if (!listed.has(groupId)) this.#takenSteerGroups.delete(groupId);
    this.#messageSteers = steers;
  }

  takeMessageSteers(): readonly MessageSteer[] {
    const steers = this.#messageSteers.filter(
      (steer) => !this.#takenSteerGroups.has(steer.groupId),
    );
    for (const steer of steers) this.#takenSteerGroups.add(steer.groupId);
    return steers;
  }

  /**
   * A Message transaction queued a Run of this Context; the hint proves it,
   * so the execution loop claims without reading work state first.
   */
  noteQueuedRun(): void {
    this.#recordQueuedWork();
  }

  #recordQueuedWork(): void {
    this.#queuedKind = undefined;
    this.#queuedWorkMark += 1;
    this.#hasQueuedRuns = true;
    this.#hasPendingWork = true;
  }

  #assertOpen(): void {
    if (this.#closed) throw new Error("TeamHub Runtime state is closed");
  }
}

const toRuntimeInput = (
  message: Message,
  sourceKind: RuntimeInput["source_kind"],
  sourceInboxId?: string,
): RuntimeInput => ({
  input_id: message.messageId,
  payload: message as unknown as Record<string, unknown>,
  source_kind: sourceKind,
  source_message_id: message.messageId,
  ...(sourceInboxId ? { source_inbox_id: sourceInboxId } : {}),
});

const toMessage = (payload: Record<string, unknown>): Message => {
  if (typeof payload.messageId !== "string") {
    throw new Error("TeamHub Runtime input payload is not a Message");
  }
  // Canonical authority only: body, references, and identities come from the
  // durable payload. The executor's input preparation renders the text with the
  // feature contributions, inside the execution failure boundary.
  return acceptedNotificationInput(payload);
};

const asNonEmpty = <T>(values: readonly T[]): NonEmptyReadonlyArray<T> => {
  const first = values[0];
  if (first === undefined) throw new Error("Expected a non-empty collection");
  return [first, ...values.slice(1)];
};

const parsePositiveInt64 = (value: string, field: string): string => {
  if (!/^[1-9][0-9]*$/.test(value))
    throw new TypeError(`${field} must be a positive decimal string`);
  return value;
};

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

const isTransientTerminalFailure = (error: unknown): boolean =>
  error instanceof TeamHubRuntimeStateError &&
  error.retryable &&
  (error.status === null || error.status >= 500);

const isRuntimeStateConflict = (error: unknown): boolean =>
  error instanceof TeamHubRuntimeStateError &&
  error.status === 409 &&
  error.code === "AGENT_RUNTIME_CONFLICT";

const waitForTerminalRetry = (
  delayMs: number,
  signal: AbortSignal,
): Promise<void> =>
  new Promise((resolve, reject) => {
    signal.throwIfAborted();
    const abort = () => {
      clearTimeout(timer);
      reject(signal.reason);
    };
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", abort);
      resolve();
    }, delayMs);
    signal.addEventListener("abort", abort, { once: true });
  });

/** Earliest TeamHub `created_at` (epoch ms) among a claimed Run's inputs. */
export function earliestInputReceivedAtMs(
  inputs: readonly { readonly created_at?: string }[],
): number | undefined {
  let earliest: number | undefined;
  for (const input of inputs) {
    const at =
      input.created_at === undefined
        ? Number.NaN
        : Date.parse(input.created_at);
    if (Number.isFinite(at) && (earliest === undefined || at < earliest))
      earliest = at;
  }
  return earliest;
}