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.

4.5 KB
Raw Blame
import type { ExecutionContextRef } from "./context-ref.js";
import type {
  RuntimeHistoryInspection,
  RuntimeHistoryOptions,
} from "./history.js";
import type {
  LocalTurnObservation,
  AgentId,
  Message,
  NonEmptyReadonlyArray,
  RunCancellationStatus,
  AgentManagerStatus,
  AgentUpdateOptions,
  RegisteredAgent,
} from "./types.js";
import type { AgentUpdate, Ghost, GhostRegistration } from "./ghost.js";

export interface ExecutionContextMessageDelivery {
  readonly target: ExecutionContextRef;
  readonly messages: NonEmptyReadonlyArray<Message>;
}

export interface AgentRegistrationIdentityReservation {
  readonly agentId: AgentId;
}

export interface AgentDeletionOptions {
  readonly beforeIdentityRemoval?: () => Promise<void>;
}

export interface AgentManagerApi<TRuntimeSettings> {
  cancelLocalRun(
    ref: ExecutionContextRef,
    runId: string,
  ): Promise<RunCancellationStatus>;

  getGhost(agentId: AgentId): Promise<Readonly<Ghost<TRuntimeSettings>> | null>;

  /**
   * Reads the Agent's registration from TeamHub again after TeamHub committed
   * a change to it. Returns null when the Agent is no longer active. Loaded
   * Contexts adopt a new revision at their next input.
   */
  refreshAgent(
    agentId: AgentId,
  ): Promise<Readonly<Ghost<TRuntimeSettings>> | null>;

  deleteAgent(
    agentId: AgentId,
    options?: AgentDeletionOptions,
  ): Promise<"deleted" | "not_found">;
}

export interface AgentDebugInspectionApi {
  inspectDebugContextHistory(
    ref: ExecutionContextRef,
    options: RuntimeHistoryOptions,
  ): Promise<RuntimeHistoryInspection>;
}

export type AgentIdentityResolutionErrorKind =
  | "transient"
  | "not_found"
  | "permanent";

export class AgentIdentityResolutionError extends Error {
  constructor(
    readonly kind: AgentIdentityResolutionErrorKind,
    message: string,
  ) {
    super(message);
    this.name = "AgentIdentityResolutionError";
  }
}

export type AgentManagerErrorCode =
  | "agent_registration_conflict"
  | "agent_deleting"
  | "agent_not_registered"
  | "agent_busy"
  | "agent_activation_pending"
  | "agent_activation_rejected"
  | "agent_revision_conflict"
  | "binding_not_found"
  | "identity_resolution_failed"
  | "identity_unavailable"
  | "invalid_runtime"
  | "invalid_state"
  | "message_conflict"
  | "manager_closed";

export class AgentManagerError extends Error {
  constructor(
    readonly code: AgentManagerErrorCode,
    message: string,
  ) {
    super(message);
    this.name = "AgentManagerError";
  }
}

/** The Agent registration is not yet active at the Context's revision. */
export function isActivationPending(error: unknown): boolean {
  return (
    error instanceof AgentManagerError &&
    error.code === "agent_activation_pending"
  );
}

export interface AgentManager<TRuntimeSettings>
  extends AgentManagerApi<TRuntimeSettings>, AgentDebugInspectionApi {
  /** Writes a Ghost into a process-local store; TeamHub-backed stores only check it. */
  registerAgent(
    ghost: GhostRegistration<TRuntimeSettings>,
    identity: AgentRegistrationIdentityReservation,
  ): Promise<RegisteredAgent>;

  updateAgent?(
    agentId: AgentId,
    update: AgentUpdate<TRuntimeSettings>,
    options?: AgentUpdateOptions,
  ): Promise<RegisteredAgent>;

  restore(options?: { readonly onlyUnmaterialized?: boolean }): Promise<void>;

  ensureBinding(ref: ExecutionContextRef): Promise<void>;

  ensureAgentIdentity(agentId: AgentId): Promise<void>;

  submitTrustedTurn(
    delivery: ExecutionContextMessageDelivery,
  ): Promise<{ readonly agentRunRef: string }>;

  cancelTrustedTurn(delivery: ExecutionContextMessageDelivery): Promise<{
    readonly agentRunRef: string;
    readonly cancelStatus: RunCancellationStatus;
  }>;

  /**
   * Puts one trusted message into the Context's running turn. Returns the
   * steered Run, or null when no turn is running in this process; the caller
   * then submits the message as the next turn instead.
   */
  steerActiveTurn(delivery: {
    readonly target: ExecutionContextRef;
    readonly message: Message;
  }): Promise<{ readonly agentRunRef: string } | null>;

  observeTurn(
    ref: ExecutionContextRef,
    agentRunRef: string,
  ): Promise<LocalTurnObservation | null>;

  getContextStatus(
    ref: ExecutionContextRef,
  ): Promise<AgentManagerStatus | null>;

  startContext(ref: ExecutionContextRef): Promise<void>;
  resumeContext(ref: ExecutionContextRef): Promise<void>;
  suspendContext(ref: ExecutionContextRef): Promise<void>;
  stopContext(ref: ExecutionContextRef): Promise<void>;

  close(options?: { readonly runGracePeriodMs?: number }): Promise<void>;
}