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.

22.3 KB
Raw Blame
import type { RunKind, CapacityPriority } from "../../model-tasks.js";
import type { RuntimeHistoryOptions, RuntimeHistoryPage } from "./history.js";

export interface McpServerResource {
  name: string;
  url: string;
  toolNames: readonly string[];
  httpHeaders?: Readonly<Record<string, string>>;
}

export interface ProviderResourceBundle {
  mcpServers: readonly McpServerResource[];
  /** Exact package names of the Skills loaded for this activation. */
  skillNames?: readonly string[];
}

export type SandboxMode =
  | "read-only"
  | "workspace-write"
  | "danger-full-access";

export interface SessionFilesystemAccess {
  readonly readOnlyRoots: readonly string[];
  readonly readWriteRoots: readonly string[];
}

export interface SessionCommandEnvironment {
  readonly homeDirectory: string;
  readonly temporaryDirectory: string;
  readonly additionalPathEntries?: readonly string[];
  readonly mambaRootPrefix?: string;
  readonly condaPrefix?: string;
  readonly teamhubCli?: {
    readonly configPath: string;
    readonly profile?: string;
    readonly binDirectory?: string;
    readonly nodeDirectory?: string;
  };
}

export interface SessionSpec {
  workingDirectory: string;
  threadName: string;
  model?: string;
  reasoningEffort?: string;
  sandboxMode: SandboxMode;
  additionalWritableRoots?: readonly string[];
  filesystemAccess?: SessionFilesystemAccess;
  commandEnvironment?: SessionCommandEnvironment;
  networkAccess?: boolean;
  /** Exact destinations permitted for commands when general network access is denied. */
  networkAllowedDomains?: readonly string[];
  ephemeral?: boolean;
  baseInstructions?: string;
  developerInstructions?: string;
}

export type RuntimeSession = unknown;

/** A pending native identity must never be written to Runtime State. */
export const runtimeSessionAwaitsFirstRun = (
  session: RuntimeSession,
): boolean =>
  typeof session === "object" &&
  session !== null &&
  Object.hasOwn(session, "threadId") &&
  (session as { readonly threadId?: unknown }).threadId === "";

/**
 * The next Run on this session starts its native conversation. Claude/Pi can
 * checkpoint a reserved identity during warmup; its materialization flag
 * survives restart, so no separate handoff state is needed.
 */
export const runtimeSessionStartsFresh = (session: RuntimeSession): boolean =>
  runtimeSessionAwaitsFirstRun(session) ||
  (typeof session === "object" &&
    session !== null &&
    "lingerMaterialized" in session &&
    session.lingerMaterialized === false);

export const requireRuntimeSessionThreadId = (
  session: RuntimeSession,
): string => {
  if (
    typeof session !== "object" ||
    session === null ||
    !("threadId" in session) ||
    typeof (session as { readonly threadId?: unknown }).threadId !== "string" ||
    !(session as { readonly threadId: string }).threadId.trim()
  ) {
    throw new TypeError("RuntimeSession.threadId must be a non-empty string");
  }
  return (session as { readonly threadId: string }).threadId;
};

/** Per-run Agent CLI fields the Computer writes to `.teamhub/cli/run.json`. */
export interface CliRunContext {
  readonly run_id?: string;
  /** The Context the CLI acts for; the Computer writes it to config.json. */
  readonly scope: {
    readonly kind: "room" | "task" | "document";
    readonly id: string;
  };
}

export interface AgentInput {
  type: "text";
  text: string;
  /** Per-run CLI fields for the Computer's `run.json`; never sent inside the wire input. */
  cliRunContext?: CliRunContext;
}

export interface ProviderRunContext {
  readonly cancellationRequested?: boolean;
  /** The durable claim attempt; old attempts cannot acquire a new execution binding. */
  readonly executionAttemptCount?: number;
  /** The Agent Service epoch that claimed the Run. */
  readonly executionEpoch?: string;
  readonly executionRunRef: string;
  readonly messageIds?: readonly string[];
  readonly documentReferences?: readonly {
    readonly documentId: string;
    readonly documentVersionId?: string;
  }[];
  readonly sourceInboxIds: readonly string[];
}

export interface ExecutionSpec {
  /** Process-local monotonic acceptance time; never persisted or sent over the wire. */
  acceptedAtMonotonicMs?: number;
  /** What queued the Run, for model scheduling; never sent over the wire. */
  runKind?: RunKind;
  /** Revalidate the live claim after readmission and before resuming its native session. */
  beforeYieldResume?: () => Promise<void>;
  signal?: AbortSignal;
  resources?: ProviderResourceBundle;
  runContext?: ProviderRunContext;
}

export type RunPlanStepStatus =
  | "pending"
  | "in_progress"
  | "completed"
  | "canceled";

export interface RunPlanStep {
  content: string;
  status: RunPlanStepStatus;
}

/** Token counts of one model request, in the Run usage buckets. */
export interface ModelRequestUsage {
  input: number;
  cacheRead: number;
  cacheWrite: number;
  output: number;
  reasoning?: number;
}

/**
 * One completed model request. `startedAtUnixMs` is when the Runtime had the
 * request's inputs; `firstItemAtUnixMs` is its first observable output at
 * `granularity`, which is not a time to first token.
 */
export interface ModelRespondedEvent {
  type: "model.responded";
  respondedAtUnixMs: number;
  startedAtUnixMs: number;
  firstItemAtUnixMs?: number;
  granularity: "item" | "block" | "delta";
  model?: string;
  messageId?: string;
  usage: ModelRequestUsage;
  /** Present for a sub-agent's request. */
  agent?: { id: string; parentCallId?: string };
}

export type RunActivityStatus = "working" | "thinking";
export type RunActivityKind =
  | "command"
  | "tool"
  | "file_change"
  | "search"
  | "read"
  | "browse"
  | "message"
  | "message_read"
  | "image"
  | "delegation"
  | "response"
  | "interaction"
  | "recovery"
  | "review";
export type RunActivityOutcome =
  | "succeeded"
  | "failed"
  | "canceled"
  | "declined";

export interface RunActivityContentBlock {
  content: string;
  format: "text" | "code" | "json";
  label?: string;
}

export type RunEvent =
  | { type: "run.started" }
  | {
      type: "status.changed";
      status: RunActivityStatus;
      title?: string;
    }
  | {
      type: "plan.updated";
      explanation?: string;
      steps: readonly RunPlanStep[];
    }
  | {
      type: "activity.started";
      activityId: string;
      kind: RunActivityKind;
      title: string;
      content?: readonly RunActivityContentBlock[];
    }
  | {
      type: "activity.updated";
      activityId: string;
      detail: string;
    }
  | {
      type: "activity.finished";
      activityId: string;
      outcome: RunActivityOutcome;
      content?: readonly RunActivityContentBlock[];
    }
  | {
      type: "message.delta";
      messageId: string;
      delta: string;
      /** Unix ms the Computer observed the native output; absent when unreported. */
      observedAtUnixMs?: number;
    }
  | {
      type: "tool.called";
      callId: string;
      toolName: string;
      input: unknown;
      /** Unix ms the Computer observed the native output; absent when unreported. */
      observedAtUnixMs?: number;
    }
  | {
      type: "tool.returned";
      callId: string;
      toolName: string;
      output: unknown;
      isError: boolean;
      /** Unix ms the Computer observed the native result; absent when unreported. */
      observedAtUnixMs?: number;
    }
  | ModelRespondedEvent
  | { type: "file.created"; path: string }
  | { type: "file.updated"; path: string }
  | { type: "file.deleted"; path: string }
  | { type: "run.completed" }
  | { type: "run.failed"; message: string };

export interface RunResult {
  finalResponse: string;
}

/** A delegated Task's native Operation stopped and its session can continue. */
export class ProviderRunYieldedError extends Error {
  constructor(readonly session: Record<string, string | boolean>) {
    super("Task yielded its model slot");
  }
}

export class ProviderRunCleanupError extends Error {
  constructor(options?: ErrorOptions) {
    super("Provider cancellation cleanup is unconfirmed", options);
    this.name = "ProviderRunCleanupError";
  }
}

export class ProviderRunInterruptedError extends Error {
  constructor(
    message = "Provider run was interrupted",
    options?: ErrorOptions,
  ) {
    super(message, options);
    this.name = "ProviderRunInterruptedError";
  }
}

export class ProviderRunStartError extends Error {
  constructor(
    readonly effect: "definitely_not_started",
    message: string,
    options?: ErrorOptions,
  ) {
    super(message, options);
    this.name = "ProviderRunStartError";
  }
}

/** No provider input was sent; a transient local diagnostic can be rechecked. */
export class ProviderRunAdmissionUnavailableError extends ProviderRunStartError {
  override readonly name = "ProviderRunAdmissionUnavailableError";

  constructor(options?: ErrorOptions) {
    super(
      "definitely_not_started",
      "Local Runtime admission diagnostic is unavailable",
      options,
    );
  }
}

export class ProviderSessionInspectionError extends Error {
  override readonly name = "ProviderSessionInspectionError";

  constructor(
    readonly status: "unsupported" | "unavailable",
    message: string,
  ) {
    super(message);
  }
}

export interface AgentRun {
  respond?(
    operationId: string,
    requestId: string,
    payload: Record<string, unknown>,
  ): Promise<void>;
  /** Single-consumer stream with bounded buffering. */
  readonly events: AsyncIterable<RunEvent>;
  /** The turn an accepted steer joins, when the Runtime reports it. */
  readonly steerTarget?: ProviderSteerAck;
  /** Whether the Computer reused a warm native process; absent when unreported. */
  readonly processReused?: boolean;
  /** Unix ms the Computer handed the turn to the model; absent when unreported. */
  readonly dispatchedAtUnixMs?: number;
  wait(): Promise<RunResult>;
  cancel(): void;
}

export interface ProviderSessionOptions extends SessionSpec {
  resources: ProviderResourceBundle;
}

export interface AgentProvider {
  /** Reserve execution capacity before claiming a durable Run. Always release. */
  acquireRunCapacity?(
    signal: AbortSignal,
    priority?: CapacityPriority,
  ): Promise<() => void>;

  createSession(options: ProviderSessionOptions): Promise<RuntimeSession>;

  resumeSession(
    session: RuntimeSession,
    options: ProviderSessionOptions,
  ): Promise<RuntimeSession>;

  /**
   * Advisory: starts Runtime-side preparation for a resumed session after a
   * real input was accepted. Never throws, waits, or fails activation.
   */
  prepareForAcceptedInput?(
    session: RuntimeSession,
    options: { readonly acceptedInputSinceMs: number },
  ): void;
  /**
   * Advisory and never throws: after a Room-presence activation without input,
   * start the Provider process early so the first Run adopts it. Every call is
   * an independent hint; the Runtime keeps a prepared process like a parked one.
   */
  prepareForPresence?(session: RuntimeSession): void;

  /** Replaces the exact filesystem roots authorized for the next Run. */
  replaceSessionFilesystemAccess?(
    session: RuntimeSession,
    filesystemAccess: SessionFilesystemAccess,
  ): Promise<void>;

  /** Reads a sanitized page from the provider's persisted history source. */
  inspectHistory?(
    session: RuntimeSession,
    options: RuntimeHistoryOptions,
  ): Promise<RuntimeHistoryPage>;

  /**
   * Compacts an idle session with the Runtime's native compaction. The session
   * identity is unchanged; a provider whose session value changes updates it
   * in place, as after a Run, and the caller then checkpoints it. Aborting the
   * signal interrupts compaction and leaves history unchanged.
   */
  compactSession?(
    session: RuntimeSession,
    options: ProviderCompactOptions,
  ): Promise<ProviderCompactResult>;

  startRun(
    session: RuntimeSession,
    input: AgentInput,
    spec: ExecutionSpec,
  ): Promise<AgentRun>;

  clearRunResources?(session: RuntimeSession): Promise<void>;

  steer(
    run: AgentRun,
    options: ProviderSteerOptions,
  ): Promise<ProviderSteerAck>;

  close(): Promise<void>;
}

export interface ProviderCompactOptions {
  /** Extra keep-requirements; Runtimes without a custom prompt ignore them. */
  readonly instructions?: string;
  readonly signal: AbortSignal;
}

export type ProviderCompactResult =
  | {
      readonly status: "compacted";
      /** Context size before compaction, when the Runtime reports it. */
      readonly preTokens?: number;
    }
  | { readonly status: "nothing_to_compact" }
  /** The Runtime cannot compact this session right now, e.g. no parked process. */
  | { readonly status: "unavailable" };

export interface ProviderSteerOptions {
  input: AgentInput;
  runContext?: ProviderRunContext;
  signal?: AbortSignal;
}

export interface ProviderSteerAck {
  turnId: string;
}

/** Public diagnostic metadata only; native error text never belongs here. */
export interface RuntimeExecutionFailure {
  code:
    | "session_not_found"
    | "protocol_incompatible"
    | "authentication_required"
    | "network_error"
    | "rate_limited"
    | "model_unavailable"
    | "model_not_offered"
    | "context_too_long"
    | "model_service_error"
    | "timeout"
    | "execution_failed"
    | "execution_outcome_unknown"
    | "reply_undelivered"
    | "reply_not_sent"
    | "interrupted"
    | "computer_unavailable"
    | "cleanup_unconfirmed"
    | "response_too_large"
    | "unclassified";
  /** Absent when the failure was observed without a selected Runtime. */
  runtime_type?: "codex" | "claude" | "pi" | "antigravity";
  runtime_version?: string;
}

/** Logging-only metadata; never include this object in public failure state. */
export interface RuntimeFailureDiagnostics {
  code?: string;
  statusCode?: number;
  exitCode?: number;
  signal?: string;
}

export class RuntimeExecutionError extends Error {
  readonly diagnostics?: RuntimeFailureDiagnostics;

  constructor(
    readonly failure: RuntimeExecutionFailure,
    options?: ErrorOptions & { diagnostics?: RuntimeFailureDiagnostics },
  ) {
    super(
      `${failure.runtime_type ?? "runtime"} execution failed (${failure.code})`,
      options,
    );
    this.name = "RuntimeExecutionError";
    this.diagnostics = options?.diagnostics;
  }
}

export const STREAMING_AGENT_RUN_EVENT_BUFFER_LIMIT = 64;
export const STREAMING_AGENT_RUN_EVENT_BUFFER_BYTES = 4 * 1024 * 1024;
export const STREAMING_AGENT_RUN_MAX_RESPONSE_BYTES = 1_000_000;
export const STREAMING_AGENT_RUN_MAX_RESPONSE_MESSAGES = 1_024;
export const STREAMING_AGENT_RUN_FAILURE_MESSAGE = "Agent run failed";

export class StreamingAgentRun implements AgentRun {
  readonly events: AsyncIterable<RunEvent>;
  readonly steerTarget: ProviderSteerAck | undefined;

  readonly #abortController: AbortController;
  readonly #eventStream: BoundedRunEventStream;
  readonly #source: AsyncIterable<RunEvent>;
  #result: Promise<RunResult> | undefined;

  constructor(
    source: AsyncIterable<RunEvent>,
    abortController: AbortController,
    steerTarget?: ProviderSteerAck,
  ) {
    this.#abortController = abortController;
    this.#source = source;
    this.steerTarget = steerTarget;
    this.#eventStream = new BoundedRunEventStream(() => {
      void this.#start().catch(() => undefined);
    }, abortController.signal);
    this.events = this.#eventStream;
  }

  wait(): Promise<RunResult> {
    return this.#start();
  }

  cancel(): void {
    this.#abortController.abort();
  }

  #start(): Promise<RunResult> {
    this.#result ??= this.#consume(this.#source);
    void this.#result.catch(() => undefined);
    return this.#result;
  }

  async #consume(source: AsyncIterable<RunEvent>): Promise<RunResult> {
    const messages = new Map<string, string>();
    let finalMessageId: string | null = null;
    let responseStorageBytes = 0;
    let failurePublished = false;
    try {
      for await (const event of source) {
        if (event.type === "run.failed") {
          failurePublished = await this.#eventStream.publish({
            type: "run.failed",
            message: STREAMING_AGENT_RUN_FAILURE_MESSAGE,
          });
          throw new ReportedAgentRunFailure(
            STREAMING_AGENT_RUN_FAILURE_MESSAGE,
          );
        }
        await this.#eventStream.publish(event);
        if (event.type === "message.delta") {
          const isNewMessage = !messages.has(event.messageId);
          if (
            isNewMessage &&
            messages.size >= STREAMING_AGENT_RUN_MAX_RESPONSE_MESSAGES
          ) {
            throw new StreamingAgentRunLimitError(
              "Agent run response message limit exceeded",
            );
          }
          responseStorageBytes += encodedByteLength(event.delta);
          if (isNewMessage) {
            responseStorageBytes += encodedByteLength(event.messageId);
          }
          if (responseStorageBytes > STREAMING_AGENT_RUN_MAX_RESPONSE_BYTES) {
            throw new StreamingAgentRunLimitError(
              "Agent run response byte limit exceeded",
            );
          }
          messages.set(
            event.messageId,
            `${messages.get(event.messageId) ?? ""}${event.delta}`,
          );
          finalMessageId = event.messageId;
        }
      }
      return {
        finalResponse: finalMessageId
          ? (messages.get(finalMessageId) ?? "")
          : "",
      };
    } catch (error) {
      const sourceFailure = error instanceof Error ? error : new Error();
      const failure =
        sourceFailure instanceof StreamingAgentRunLimitError ||
        sourceFailure instanceof ReportedAgentRunFailure ||
        sourceFailure instanceof RuntimeExecutionError
          ? sourceFailure
          : new Error(STREAMING_AGENT_RUN_FAILURE_MESSAGE, {
              cause: sourceFailure,
            });
      if (sourceFailure instanceof StreamingAgentRunLimitError) {
        this.#abortController.abort(sourceFailure);
      }
      if (!failurePublished) {
        this.#eventStream.publishTerminal({
          type: "run.failed",
          message: STREAMING_AGENT_RUN_FAILURE_MESSAGE,
        });
      }
      throw failure;
    } finally {
      this.#eventStream.close();
    }
  }
}

interface BufferedRunEvent {
  readonly event: RunEvent;
  readonly bytes: number;
}

class BoundedRunEventStream implements AsyncIterable<RunEvent> {
  readonly #queue: BufferedRunEvent[] = [];
  readonly #dataWaiters = new Set<() => void>();
  readonly #spaceWaiters = new Set<() => void>();
  #bufferedBytes = 0;
  #claimed = false;
  #consumerActive = false;
  #closed = false;

  readonly #onAbort = (): void => notify(this.#spaceWaiters);

  constructor(
    private readonly onClaim: () => void,
    private readonly signal: AbortSignal,
  ) {
    signal.addEventListener("abort", this.#onAbort, { once: true });
  }

  [Symbol.asyncIterator](): AsyncIterator<RunEvent> {
    if (this.#claimed) {
      return {
        next: () =>
          Promise.reject(
            new Error("Agent run events support exactly one consumer"),
          ),
      };
    }
    this.#claimed = true;
    this.#consumerActive = true;
    this.onClaim();
    const iterator = this.#iterate();
    return {
      next: () => iterator.next(),
      return: () => {
        this.#releaseConsumer();
        return iterator.return(undefined);
      },
    };
  }

  async publish(event: RunEvent): Promise<boolean> {
    if (!this.#consumerActive || this.#closed) {
      return false;
    }
    const bytes = encodedEventBytes(event);
    if (bytes > STREAMING_AGENT_RUN_EVENT_BUFFER_BYTES) {
      throw new StreamingAgentRunLimitError(
        "Agent run event exceeds the buffer byte limit",
      );
    }
    while (
      this.#consumerActive &&
      !this.#closed &&
      !this.signal.aborted &&
      (this.#queue.length >= STREAMING_AGENT_RUN_EVENT_BUFFER_LIMIT ||
        this.#bufferedBytes + bytes > STREAMING_AGENT_RUN_EVENT_BUFFER_BYTES)
    ) {
      await waitForNotification(this.#spaceWaiters);
    }
    if (!this.#consumerActive || this.#closed || this.signal.aborted) {
      return false;
    }
    this.#queue.push({ event, bytes });
    this.#bufferedBytes += bytes;
    notify(this.#dataWaiters);
    return true;
  }

  publishTerminal(event: RunEvent): void {
    if (!this.#consumerActive || this.#closed) {
      return;
    }
    const bytes = encodedEventBytes(event);
    if (bytes > STREAMING_AGENT_RUN_EVENT_BUFFER_BYTES) {
      return;
    }
    while (
      this.#queue.length >= STREAMING_AGENT_RUN_EVENT_BUFFER_LIMIT ||
      this.#bufferedBytes + bytes > STREAMING_AGENT_RUN_EVENT_BUFFER_BYTES
    ) {
      const discarded = this.#queue.shift();
      if (!discarded) break;
      this.#bufferedBytes -= discarded.bytes;
    }
    this.#queue.push({ event, bytes });
    this.#bufferedBytes += bytes;
    notify(this.#dataWaiters);
  }

  close(): void {
    this.#closed = true;
    this.signal.removeEventListener("abort", this.#onAbort);
    notify(this.#dataWaiters);
    notify(this.#spaceWaiters);
  }

  async *#iterate(): AsyncGenerator<RunEvent> {
    try {
      while (
        this.#consumerActive &&
        (this.#queue.length > 0 || !this.#closed)
      ) {
        const next = this.#queue.shift();
        if (!next) {
          await waitForNotification(this.#dataWaiters);
          continue;
        }
        this.#bufferedBytes -= next.bytes;
        notify(this.#spaceWaiters);
        yield next.event;
      }
    } finally {
      this.#releaseConsumer();
    }
  }

  #releaseConsumer(): void {
    if (!this.#consumerActive) return;
    this.#consumerActive = false;
    this.#queue.length = 0;
    this.#bufferedBytes = 0;
    notify(this.#dataWaiters);
    notify(this.#spaceWaiters);
  }
}

/** The Run's reply exceeded what a Room message may hold. */
export class StreamingAgentRunLimitError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "StreamingAgentRunLimitError";
  }
}

class ReportedAgentRunFailure extends Error {
  constructor(message: string) {
    super(message);
    this.name = "ReportedAgentRunFailure";
  }
}

const waitForNotification = (waiters: Set<() => void>): Promise<void> =>
  new Promise((resolve) => waiters.add(resolve));

const notify = (waiters: Set<() => void>): void => {
  for (const waiter of waiters) {
    waiter();
  }
  waiters.clear();
};

const encodedByteLength = (value: string): number =>
  new TextEncoder().encode(value).byteLength;

const encodedEventBytes = (event: RunEvent): number => {
  try {
    return encodedByteLength(JSON.stringify(event));
  } catch {
    throw new Error("Agent run event cannot be buffered safely");
  }
};