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.
import type {
RuntimeViewPlan,
AgentContextHost,
StagedDocumentProjection,
} from "./workspace.js";
import type { SkillDescriptor, GhostResources } from "./ghost.js";
import {
type ExecutionContextRef,
encodeExecutionContextRef,
type SharedTaskScope,
} from "./context-ref.js";
import {
type AgentLogger,
claimAgentFailureAlert,
} from "../observability/agent-log.js";
import {
type AgentInput,
type AgentProvider,
type ProviderSessionOptions,
type ProviderRunContext,
type RuntimeSession,
ProviderRunInterruptedError,
ProviderRunAdmissionUnavailableError,
ProviderRunStartError,
type AgentRun,
type ExecutionSpec,
type ProviderSteerAck,
type ProviderSteerOptions,
runtimeSessionStartsFresh,
} from "./provider.js";
import type { ToolRunContext, AgentDefinition, AgentType } from "./types.js";
import type { BuiltinAgentFeatures } from "../agent-features/builtin.js";
import type { ComposedActivationFeatures } from "../agent-features/compose.js";
import type {
ActivationFeatureView,
ContextInstructionFacts,
} from "../agent-features/contracts.js";
import {
isLocalComputerOfflineError,
LocalRuntimeAdmissionUnavailableError,
} from "../runner-gateway/local-computer-management.js";
import type {
AgentEffectiveResources,
DocumentCommentRuntimeProjection,
AgentResourcesResolver,
McpContextResolver,
} from "./teamhub-context-resolvers.js";
import type { ExecutionResources } from "./context-runtime-state.js";
/** Cleanup did not prove that the old Runtime resources are safely retired. */
export class ContextRuntimeCleanupError extends AggregateError {
constructor(errors: readonly unknown[]) {
super(errors, "Context Runtime cleanup is unavailable or unconfirmed");
this.name = "ContextRuntimeCleanupError";
}
}
/** A physical retirement failure is a safety fence, including inside a combined cleanup failure. */
export const isUnconfirmedContextRuntimeCleanup = (error: unknown): boolean =>
error instanceof ContextRuntimeCleanupError ||
(error instanceof AggregateError &&
error.errors.some(isUnconfirmedContextRuntimeCleanup));
export interface ContextRuntimeBackendRequest<TRuntimeSettings> {
readonly ref: ExecutionContextRef;
readonly tenantId: string;
readonly actorId: string;
readonly runtimeInstanceKey: string;
readonly executionEpoch?: ProviderRunContext["executionEpoch"];
/**
* Runs review Runtime permission prompts through TeamHub's judge. Absent,
* a Run declares no review and the Runtime's own rules decide alone.
*/
readonly permissionReview?: true;
/**
* The developer instructions are the compact version, so the Runtime's own
* instruction wrapper uses its compact version too.
*/
readonly compactInstructions?: true;
readonly previousSession?: RuntimeSession;
readonly viewPlan: RuntimeViewPlan;
readonly agent: AgentDefinition;
readonly runtime: TRuntimeSettings;
readonly resources: {
readonly skills: readonly ContextRuntimeSkillDescriptor[];
};
readonly signal: AbortSignal;
readonly logger: AgentLogger;
}
/** A Skill the Context View names; the Computer fetches it by manifest. */
export interface ContextRuntimeSkillDescriptor extends SkillDescriptor {
readonly manifestId?: string;
}
export interface ContextRuntimeBackendPreflightRequest<TRuntimeSettings> {
readonly ref: ExecutionContextRef;
readonly runtime: TRuntimeSettings;
readonly signal: AbortSignal;
}
/** What preflight learned about the placed Runtime model. */
export interface ContextRuntimeBackendPreflight {
/** The model's context window calls for the compact instructions. */
readonly compactInstructions: boolean;
}
export interface ContextRuntimeBackendActivation {
readonly provider: AgentProvider;
readonly runtimeName: string;
readonly sessionSpec: ProviderSessionOptions;
setActiveRunContext(context: ToolRunContext | null): void;
/** Installs the Agent CLI credential and attaches the per-Run CLI context. */
prepareRunInput?(input: AgentInput, signal: AbortSignal): Promise<AgentInput>;
synchronize(
viewPlan: RuntimeViewPlan,
signal?: AbortSignal,
session?: RuntimeSession,
): Promise<void>;
deactivate(): Promise<void>;
}
export interface ContextRuntimeBackend<TRuntimeSettings> {
preflight?(
request: ContextRuntimeBackendPreflightRequest<TRuntimeSettings>,
):
| void
| ContextRuntimeBackendPreflight
| Promise<void | ContextRuntimeBackendPreflight>;
activate(
request: ContextRuntimeBackendRequest<TRuntimeSettings>,
): Promise<ContextRuntimeBackendActivation>;
}
/**
* One health signal per Context activation. It aborts when the activation
* releases its session or the service closes, which cancels the activation's
* Runs and refuses its next ones.
*/
export interface ContextViewSession {
readonly healthSignal: AbortSignal;
release(): void;
}
export interface ContextViewSessions {
open(signal: AbortSignal): ContextViewSession;
close(): void;
}
export function createContextViewSessions(): ContextViewSessions {
const serviceController = new AbortController();
return {
open(signal) {
serviceController.signal.throwIfAborted();
signal.throwIfAborted();
const controller = new AbortController();
return {
healthSignal: AbortSignal.any([
signal,
controller.signal,
serviceController.signal,
]),
release() {
controller.abort(new Error("Context View released"));
},
};
},
close() {
serviceController.abort(new Error("Context View sessions closed"));
},
};
}
type ContextActivationStage =
| "validate"
| "preflight_backend"
| "resolve_mcp_context"
| "stage_document_projection"
| "prepare_runtime_view"
| "activate_backend"
| "create_session"
| "resume_session"
| "bind_mcp_context";
export class ContextActivationError extends Error {
readonly code: string;
readonly retryable: boolean;
readonly stage: ContextActivationStage;
constructor(stage: ContextActivationStage, cause: unknown) {
super("Context Runtime activation failed", { cause });
this.name = "ContextActivationError";
this.code = contextActivationFailureCode(stage);
this.retryable = stage === "prepare_runtime_view";
this.stage = stage;
}
}
export interface ContextRuntimeActivationRequest<TRuntimeSettings> {
readonly ref: ExecutionContextRef;
/** TeamHub-trusted shared Task directory identity of this Context. */
readonly sharedTaskScope?: SharedTaskScope;
readonly tenantId: string;
readonly actorId: string;
/**
* Trusted Agent type forwarded to activation/run feature matching. Only
* callers whose features never declare `agentTypes` matching may omit it.
*/
readonly agentType?: AgentType;
/** Runs review Runtime permission prompts through TeamHub's judge. */
readonly permissionReview?: true;
/**
* Renders `agent.developerInstructions` with the facts this activation reads
* from the Agent's effective resources.
*/
readonly renderDeveloperInstructions?: (
facts: ContextInstructionFacts,
) => string | undefined;
/** Correlates all activation, provider, and native-session timing events. */
readonly activationId?: string;
readonly mode: "start" | "resume";
readonly previousSession?: RuntimeSession;
/**
* Monotonic accept time of the earliest real input this process accepted and
* has not yet claimed, or undefined. Read after the Provider session resolves.
*/
readonly acceptedInputSinceMs?: () => number | undefined;
readonly executionEpoch?: ProviderRunContext["executionEpoch"];
readonly agent: AgentDefinition;
readonly runtime: TRuntimeSettings;
readonly resources: GhostResources;
readonly checkpointRuntimeSession?: (
session: RuntimeSession,
) => void | Promise<void>;
readonly signal?: AbortSignal;
}
export interface ActivatedContextRuntime {
readonly ref: ExecutionContextRef;
readonly provider: AgentProvider;
readonly runtimeName: string;
readonly runtimeSession: RuntimeSession;
readonly sessionSpec: ProviderSessionOptions;
readonly executionResources?: ExecutionResources;
/** Called only before claiming a new ordinary Run, never during steer. */
prepareNextRun?(signal: AbortSignal): Promise<boolean>;
setActiveRunContext(context: ToolRunContext | null): void;
deactivate(): Promise<void>;
}
/** What a caller names when it runs backend preflight ahead of activation. */
interface ContextRuntimePreflightRequest<TRuntimeSettings> {
readonly ref: ExecutionContextRef;
readonly runtime: TRuntimeSettings;
readonly signal: AbortSignal;
readonly activationId?: string;
}
export interface ContextRuntimeActivator<TRuntimeSettings> {
activate(
request: ContextRuntimeActivationRequest<TRuntimeSettings>,
): Promise<ActivatedContextRuntime>;
/** Runs backend preflight before the caller commits to an activation. */
preflight?(
request: ContextRuntimePreflightRequest<TRuntimeSettings>,
): Promise<void>;
}
interface ContextRuntimeActivatorOptions<TRuntimeSettings> {
/**
* Assembled builtin feature ports. `composeActivation` runs once per
* activation; `composeRun` binds that activation's own backend — never an
* earlier Runtime's — so each activation gets a fresh feature state.
*/
readonly features: Pick<
BuiltinAgentFeatures,
"composeActivation" | "composeRun"
>;
readonly contextHost: Pick<
AgentContextHost,
"prepareRuntimeView" | "releaseRuntimeView"
> &
Partial<Pick<AgentContextHost, "stageDocumentProjection">>;
readonly viewSessions: ContextViewSessions;
readonly resolveBackend: (
runtime: TRuntimeSettings,
ref: ExecutionContextRef,
) => ContextRuntimeBackend<TRuntimeSettings>;
readonly mcpContextResolver?: McpContextResolver;
readonly agentResourcesResolver?: AgentResourcesResolver;
readonly logger: AgentLogger;
}
export const createContextRuntimeActivator = <TRuntimeSettings>(
options: ContextRuntimeActivatorOptions<TRuntimeSettings>,
): ContextRuntimeActivator<TRuntimeSettings> => ({
preflight: (request) => preflightContextRuntime(options, request),
activate: (request) => activateContextRuntime(options, request),
});
const activationLogger = (
logger: AgentLogger,
ref: ExecutionContextRef,
activationId: string | undefined,
): AgentLogger =>
logger.child({
agentId: ref.agentId,
contextKey: encodeExecutionContextRef(ref),
contextKind: ref.kind,
...(activationId ? { activationId } : {}),
});
async function preflightContextRuntime<TRuntimeSettings>(
options: ContextRuntimeActivatorOptions<TRuntimeSettings>,
request: ContextRuntimePreflightRequest<TRuntimeSettings>,
): Promise<void> {
const logger = activationLogger(
options.logger,
request.ref,
request.activationId,
);
const startedAt = performance.now();
await options.resolveBackend(request.runtime, request.ref).preflight?.({
ref: request.ref,
runtime: request.runtime,
signal: request.signal,
});
logger.log("info", "context_activation.preflight_finished", {
durationMs: Math.round(performance.now() - startedAt),
});
}
/** Resources one activation acquired so far; a failed activation retires them. */
interface ActivationAcquisitions {
backendActivation: ContextRuntimeBackendActivation | null;
viewSession: ContextViewSession | null;
runtimeViewPrepared: boolean;
documentProjection: StagedDocumentProjection | null;
documentProjectionActivated: boolean;
activationFeatures: ComposedActivationFeatures | null;
}
async function activateContextRuntime<TRuntimeSettings>(
options: ContextRuntimeActivatorOptions<TRuntimeSettings>,
request: ContextRuntimeActivationRequest<TRuntimeSettings>,
): Promise<ActivatedContextRuntime> {
const signal = request.signal ?? new AbortController().signal;
const runtimeInstanceKey = encodeExecutionContextRef(request.ref);
const logger = activationLogger(
options.logger,
request.ref,
request.activationId,
);
const startedAt = Date.now();
let stage: ContextActivationStage = "validate";
let stageStartedAt = performance.now();
const logStageFinished = () =>
logger.log("info", "context_activation.stage_finished", {
stage,
durationMs: Math.round(performance.now() - stageStartedAt),
totalDurationMs: Date.now() - startedAt,
mode: request.mode,
});
const enterStage = (next: ContextActivationStage) => {
logStageFinished();
stageStartedAt = performance.now();
stage = next;
};
const acquired: ActivationAcquisitions = {
backendActivation: null,
viewSession: null,
runtimeViewPrepared: false,
documentProjection: null,
documentProjectionActivated: false,
activationFeatures: null,
};
// Stops early Memory and memory.md work when this activation fails.
const earlyWorkController = new AbortController();
// Every Context loads the Agent's effective Skills. Every Context except
// ordinary Meta is also resolved by TeamHub before activation.
const ordinaryMeta = request.ref.kind === "meta";
const contextResolutionRequired = !(
options.agentResourcesResolver && ordinaryMeta
);
logger.log("info", "context_activation.started", {
mcpContextMode: options.mcpContextResolver ? "resolved" : "disabled",
mode: request.mode,
skillCount: request.resources.skills.length,
});
try {
if (request.mode === "resume") {
requirePreviousSession(request.previousSession);
}
signal.throwIfAborted();
enterStage("activate_backend");
const backend = options.resolveBackend(request.runtime, request.ref);
enterStage("preflight_backend");
const preflight = await backend.preflight?.({
ref: request.ref,
runtime: request.runtime,
signal,
});
const compactInstructions = preflight?.compactInstructions === true;
signal.throwIfAborted();
// A-class activation features own memory.md resolution and
// Agent Memory projection. They do not depend on the resource,
// MCP, or Document steps below, so they start now. The no-op catch
// keeps an early failure from being unhandled; the await below still
// surfaces it.
const earlyWorkSignal = AbortSignal.any([
signal,
earlyWorkController.signal,
]);
const activationView: ActivationFeatureView = {
ref: request.ref,
runtime: request.runtime,
agentId: request.ref.agentId,
actorId: request.actorId,
tenantId: request.tenantId,
...(request.agentType ? { agentType: request.agentType } : {}),
};
acquired.activationFeatures = options.features.composeActivation({
view: activationView,
logger: (level, event, fields) => logger.log(level, event, fields),
});
const featurePreparationPromise = acquired.activationFeatures.prepare({
signal: earlyWorkSignal,
newSession:
request.mode === "start" ||
runtimeSessionStartsFresh(request.previousSession),
});
void featurePreparationPromise.catch(() => undefined);
const {
executionResources,
connectedApps,
connectedAppKeys,
connectableAppKeys,
} = await resolveActivationInputs({
options,
request,
acquired,
signal,
earlyWorkSignal,
logger,
enterStage,
runtimeInstanceKey,
ordinaryMeta,
contextResolutionRequired,
});
signal.throwIfAborted();
const featurePreparation = await featurePreparationPromise;
enterStage("prepare_runtime_view");
const backendRequest = activationBackendRequest(request, {
runtimeInstanceKey,
compactInstructions,
agent: instructedAgent(
request,
featurePreparation.developerInstructions,
connectedApps,
connectedAppKeys,
connectableAppKeys,
compactInstructions,
),
executionResources,
signal,
logger,
});
const viewPlan = await prepareActivationRuntimeView(
options,
request,
acquired,
featurePreparation.runtimeViewMappings,
signal,
logger,
);
enterStage("activate_backend");
const backendActivation = await backend.activate({
...backendRequest,
viewPlan,
});
acquired.backendActivation = backendActivation;
signal.throwIfAborted();
enterStage(request.mode === "resume" ? "resume_session" : "create_session");
const runtimeSession =
request.mode === "resume"
? await backendActivation.provider.resumeSession(
request.previousSession,
backendActivation.sessionSpec,
)
: await backendActivation.provider.createSession(
backendActivation.sessionSpec,
);
signal.throwIfAborted();
startAcceptedInputPrepare(
request,
backendActivation.provider,
runtimeSession,
logger,
);
logger.log("info", "context_activation.completed", {
durationMs: Date.now() - startedAt,
mode: request.mode,
runtimeName: backendActivation.runtimeName,
});
return createActivatedContextRuntime({
options,
request,
signal,
logger,
runtimeInstanceKey,
contextResolutionRequired,
ordinaryMeta,
activationView,
backend: backendActivation,
activationFeatures: acquired.activationFeatures,
featureChecks: featurePreparation.checks,
viewSession: acquired.viewSession!,
viewPlan,
runtimeSession,
documentProjection: acquired.documentProjection,
executionResources,
});
} catch (error) {
earlyWorkController.abort();
throw await retireFailedActivation({
error,
stage,
acquired,
options,
ref: request.ref,
logger,
startedAt,
});
} finally {
logStageFinished();
}
}
interface ActivationInputsRequest<TRuntimeSettings> {
readonly options: ContextRuntimeActivatorOptions<TRuntimeSettings>;
readonly request: ContextRuntimeActivationRequest<TRuntimeSettings>;
readonly acquired: ActivationAcquisitions;
readonly signal: AbortSignal;
readonly earlyWorkSignal: AbortSignal;
readonly logger: AgentLogger;
readonly enterStage: (next: ContextActivationStage) => void;
readonly runtimeInstanceKey: string;
readonly ordinaryMeta: boolean;
readonly contextResolutionRequired: boolean;
}
/**
* Reads the Agent's effective resources and, when TeamHub must resolve this
* Context, its MCP Context and Document Comment projection.
*/
async function resolveActivationInputs<TRuntimeSettings>({
options,
request,
acquired,
signal,
earlyWorkSignal,
logger,
enterStage,
runtimeInstanceKey,
ordinaryMeta,
contextResolutionRequired,
}: ActivationInputsRequest<TRuntimeSettings>): Promise<{
readonly executionResources: ExecutionResources | undefined;
readonly connectedApps: boolean | undefined;
readonly connectedAppKeys: readonly string[];
readonly connectableAppKeys: readonly string[];
}> {
const agentResourcesResolver = options.agentResourcesResolver;
const mcpContextResolver = options.mcpContextResolver;
// Read with the Agent's effective resources; renders the instructions.
let connectedApps: boolean | undefined;
let connectedAppKeys: readonly string[] = [];
let connectableAppKeys: readonly string[] = [];
const readAgentResources = async (resolveSignal: AbortSignal) => {
const resourcesResolveStartedAt = performance.now();
const current = await agentResourcesResolver!.resolve({
agentId: request.ref.agentId,
signal: resolveSignal,
});
logger.log("info", "context_activation.agent_resources_resolved", {
durationMs: performance.now() - resourcesResolveStartedAt,
});
connectedApps = current.connectedApps;
connectedAppKeys = current.connectedAppKeys;
connectableAppKeys = current.connectableAppKeys;
return current;
};
let executionResources: ExecutionResources | undefined;
let pendingExecutionResources: Promise<ExecutionResources> | undefined;
if (agentResourcesResolver && ordinaryMeta) {
executionResources = currentExecutionResources(
await readAgentResources(signal),
);
} else if (agentResourcesResolver) {
// Read the Skills while TeamHub resolves the Context.
pendingExecutionResources = readAgentResources(earlyWorkSignal).then(
currentExecutionResources,
);
void pendingExecutionResources.catch(() => undefined);
}
if (mcpContextResolver && contextResolutionRequired) {
if (!request.checkpointRuntimeSession) {
throw new Error(
"Resolved MCP Context requires Runtime Session checkpointing",
);
}
enterStage("resolve_mcp_context");
const resolution = await mcpContextResolver.resolve({
ref: request.ref,
signal,
});
logger.log("info", "context_activation.mcp_context_resolved");
if (request.ref.kind === "document" && resolution.documentCommentRuntime) {
if (!options.contextHost.stageDocumentProjection) {
throw new Error(
"Resolved MCP Context requires Document projection staging",
);
}
enterStage("stage_document_projection");
acquired.documentProjection =
await options.contextHost.stageDocumentProjection(
documentCommentStaging(
request.ref.agentId,
runtimeInstanceKey,
resolution.documentCommentRuntime,
),
);
await acquired.documentProjection.activate();
acquired.documentProjectionActivated = true;
}
}
if (pendingExecutionResources) {
executionResources = await pendingExecutionResources;
}
return {
executionResources,
connectedApps,
connectedAppKeys,
connectableAppKeys,
};
}
const currentExecutionResources = (
current: AgentEffectiveResources,
): ExecutionResources =>
Object.freeze({
version: 1 as const,
effectiveSha256: current.effectiveSha256,
skills: current.skills,
});
const documentCommentStaging = (
agentId: string,
runtimeInstanceKey: string,
documentCommentRuntime: DocumentCommentRuntimeProjection,
): Parameters<AgentContextHost["stageDocumentProjection"]>[0] => ({
agentId,
runtimeInstanceKey,
documentComment: {
commentsMarkdown: documentCommentRuntime.commentsMarkdown,
currentDocument: documentCommentRuntime.currentDocument,
},
});
/**
* The bound instructions render again with this activation's facts; feature
* instructions follow them.
*/
const instructedAgent = <TRuntimeSettings>(
request: ContextRuntimeActivationRequest<TRuntimeSettings>,
featureInstructions: readonly string[],
connectedApps: boolean | undefined,
connectedAppKeys: readonly string[],
connectableAppKeys: readonly string[],
compactInstructions: boolean,
): AgentDefinition => {
const instructed =
request.renderDeveloperInstructions &&
(connectedApps !== undefined || compactInstructions)
? request.renderDeveloperInstructions({
connectedApps: connectedApps ?? true,
connectedAppKeys,
connectableAppKeys,
compactInstructions,
})
: request.agent.developerInstructions;
return {
...request.agent,
developerInstructions:
[instructed, ...featureInstructions].filter(Boolean).join("\n\n") ||
request.agent.developerInstructions,
};
};
const activationBackendRequest = <TRuntimeSettings>(
request: ContextRuntimeActivationRequest<TRuntimeSettings>,
activation: {
readonly runtimeInstanceKey: string;
readonly compactInstructions: boolean;
readonly agent: AgentDefinition;
readonly executionResources: ExecutionResources | undefined;
readonly signal: AbortSignal;
readonly logger: AgentLogger;
},
): Omit<ContextRuntimeBackendRequest<TRuntimeSettings>, "viewPlan"> => ({
ref: request.ref,
tenantId: request.tenantId,
actorId: request.actorId,
runtimeInstanceKey: activation.runtimeInstanceKey,
...(request.executionEpoch ? { executionEpoch: request.executionEpoch } : {}),
...(request.permissionReview ? { permissionReview: true as const } : {}),
...(activation.compactInstructions
? { compactInstructions: true as const }
: {}),
...(request.mode === "resume"
? { previousSession: request.previousSession }
: {}),
agent: activation.agent,
runtime: request.runtime,
resources: activation.executionResources
? Object.freeze({ skills: activation.executionResources.skills })
: request.resources,
signal: activation.signal,
logger: activation.logger,
});
async function prepareActivationRuntimeView<TRuntimeSettings>(
options: ContextRuntimeActivatorOptions<TRuntimeSettings>,
request: ContextRuntimeActivationRequest<TRuntimeSettings>,
acquired: ActivationAcquisitions,
featureMappings: RuntimeViewPlan["mappings"],
signal: AbortSignal,
logger: AgentLogger,
): Promise<RuntimeViewPlan> {
const phaseStartedAt = performance.now();
let baseViewPlan: RuntimeViewPlan;
try {
baseViewPlan = await options.contextHost.prepareRuntimeView(
request.ref,
request.sharedTaskScope,
);
} finally {
logger.log("info", "context_activation.runtime_view_phase", {
phase: "prepare_runtime_view",
durationMs: Math.round(performance.now() - phaseStartedAt),
});
}
acquired.runtimeViewPrepared = true;
logger.log("debug", "context_activation.runtime_view_prepared", {
mappingCount: baseViewPlan.mappings.length,
});
const viewPlan: RuntimeViewPlan = featureMappings.length
? {
...baseViewPlan,
mappings: [...baseViewPlan.mappings, ...featureMappings],
}
: baseViewPlan;
acquired.viewSession = options.viewSessions.open(signal);
signal.throwIfAborted();
return viewPlan;
}
/**
* Only a real accepted input may start a Provider prepare. Fire and forget:
* the Provider contains its own failures, so activation never waits for or
* fails on it.
*/
const startAcceptedInputPrepare = <TRuntimeSettings>(
request: ContextRuntimeActivationRequest<TRuntimeSettings>,
provider: AgentProvider,
runtimeSession: RuntimeSession,
logger: AgentLogger,
): void => {
const acceptedInputSinceMs = request.acceptedInputSinceMs?.();
if (acceptedInputSinceMs === undefined) return;
try {
provider.prepareForAcceptedInput?.(runtimeSession, {
acceptedInputSinceMs,
});
} catch (error) {
logger.log("warn", "context_activation.provider_prepare_failed", {
error,
});
}
};
/** Everything one completed activation hands to its live Runtime. */
interface ActiveContextRuntimeScope<TRuntimeSettings> {
readonly options: ContextRuntimeActivatorOptions<TRuntimeSettings>;
readonly request: ContextRuntimeActivationRequest<TRuntimeSettings>;
readonly signal: AbortSignal;
readonly logger: AgentLogger;
readonly runtimeInstanceKey: string;
readonly contextResolutionRequired: boolean;
readonly ordinaryMeta: boolean;
readonly activationView: ActivationFeatureView;
readonly backend: ContextRuntimeBackendActivation;
readonly activationFeatures: ComposedActivationFeatures | null;
readonly featureChecks: readonly ((
signal: AbortSignal,
) => Promise<boolean>)[];
readonly viewSession: ContextViewSession;
readonly viewPlan: RuntimeViewPlan;
readonly runtimeSession: RuntimeSession;
readonly documentProjection: StagedDocumentProjection | null;
readonly executionResources: ExecutionResources | undefined;
}
/** Mutable state shared by synchronization and deactivation of one Runtime. */
interface ActiveContextRuntimeState {
documentProjection: StagedDocumentProjection | null;
synchronizationTail: Promise<void>;
readonly synchronizationController: AbortController;
deactivationPromise: Promise<void> | null;
deactivationSteps:
| Array<{ run: () => Promise<void>; completed?: boolean }>
| undefined;
}
function createActivatedContextRuntime<TRuntimeSettings>(
scope: ActiveContextRuntimeScope<TRuntimeSettings>,
): ActivatedContextRuntime {
const {
options,
request,
logger,
backend,
viewSession,
executionResources,
ordinaryMeta,
} = scope;
const agentResourcesResolver = options.agentResourcesResolver;
const state: ActiveContextRuntimeState = {
documentProjection: scope.documentProjection,
synchronizationTail: Promise.resolve(),
synchronizationController: new AbortController(),
deactivationPromise: null,
deactivationSteps: undefined,
};
const synchronize = (
callerSignal?: AbortSignal,
phase: ContextSynchronizationPhase = "before_run",
executionRunRef?: string,
): Promise<void> =>
synchronizeContextRuntime(
scope,
state,
callerSignal,
phase,
executionRunRef,
);
// Run features bind THIS activation's backend activation: the
// composed prepare installs each new Run's Agent CLI credential and
// per-Run CLI context, and is an identity when no Run feature matched.
const runFeatures = options.features.composeRun({
view: scope.activationView,
backend,
logger: (level, event, fields) => logger.log(level, event, fields),
});
const provider = new SynchronizedContextProvider(
backend.provider,
synchronize,
viewSession.healthSignal,
logger,
(input, runSignal) => runFeatures.prepareRunInput(input, runSignal),
);
return Object.freeze({
ref: request.ref,
provider,
runtimeName: backend.runtimeName,
runtimeSession: scope.runtimeSession,
sessionSpec: backend.sessionSpec,
...(executionResources ? { executionResources } : {}),
...(agentResourcesResolver && ordinaryMeta && executionResources
? {
async prepareNextRun(nextSignal: AbortSignal): Promise<boolean> {
const current = await agentResourcesResolver.resolve({
agentId: request.ref.agentId,
signal: nextSignal,
});
// Feature-owned next-Run checks (e.g. the memory.md refresh)
// keep their accept-time snapshot as the comparison basis.
for (const check of scope.featureChecks) {
if (!(await check(nextSignal))) return false;
}
return (
current.effectiveSha256 === executionResources.effectiveSha256
);
},
}
: {}),
setActiveRunContext: (context) => backend.setActiveRunContext(context),
deactivate: () => deactivateContextRuntime(scope, state),
}) satisfies ActivatedContextRuntime;
}
function synchronizeContextRuntime<TRuntimeSettings>(
scope: ActiveContextRuntimeScope<TRuntimeSettings>,
state: ActiveContextRuntimeState,
callerSignal: AbortSignal | undefined,
phase: ContextSynchronizationPhase,
executionRunRef: string | undefined,
): Promise<void> {
const { options, logger } = scope;
const synchronizeSignal = AbortSignal.any([
scope.signal,
state.synchronizationController.signal,
scope.viewSession.healthSignal,
...(callerSignal ? [callerSignal] : []),
]);
const enqueuedAt = performance.now();
const synchronized = state.synchronizationTail
.catch(() => undefined)
.then(async () => {
let stageStartedAt = performance.now();
const queueMs = Math.round(stageStartedAt - enqueuedAt);
const startedAtUnixMs = Date.now();
const stages: Record<string, number> = {};
const recordStage = (stage: string) => {
stages[stage] = Math.round(performance.now() - stageStartedAt);
stageStartedAt = performance.now();
};
logger.log("info", "context_runtime.synchronize_started", {
executionRunRef,
phase,
queueMs,
startedAtUnixMs,
});
synchronizeSignal?.throwIfAborted();
// The Context is re-resolved before a Run, never within one.
const refreshMcpContext =
options.mcpContextResolver &&
scope.contextResolutionRequired &&
phase === "before_run";
if (refreshMcpContext) {
await refreshMcpContextAndSynchronize(
scope,
state,
options.mcpContextResolver,
synchronizeSignal,
recordStage,
);
} else {
await scope.backend.synchronize(
scope.viewPlan,
synchronizeSignal,
scope.runtimeSession ?? undefined,
);
recordStage("backend_synchronize");
}
recordStage("settle");
const elapsedMs = performance.now() - enqueuedAt;
logger.log("info", "context_runtime.synchronize_finished", {
executionRunRef,
phase,
queueMs,
stages,
elapsedMs: Math.round(elapsedMs),
startedAtUnixMs,
finishedAtUnixMs: Date.now(),
});
});
state.synchronizationTail = synchronized.then(
() => undefined,
() => undefined,
);
return synchronized;
}
/**
* Re-resolves the MCP Context and swaps in its new Document Comment
* projection; on failure the previous projection is restored before the
* refresh error fails the Run.
*/
async function refreshMcpContextAndSynchronize<TRuntimeSettings>(
scope: ActiveContextRuntimeScope<TRuntimeSettings>,
state: ActiveContextRuntimeState,
mcpContextResolver: McpContextResolver,
synchronizeSignal: AbortSignal,
recordStage: (stage: string) => void,
): Promise<void> {
const { options, request, backend, viewPlan } = scope;
const runtimeSession = scope.runtimeSession ?? undefined;
const previousProjection = state.documentProjection;
state.documentProjection = null;
let nextProjection: StagedDocumentProjection | null = null;
let nextProjectionActivated = false;
try {
const resolution = await mcpContextResolver.resolve({
ref: request.ref,
signal: synchronizeSignal,
});
recordStage("mcp_resolve");
if (request.ref.kind === "document" && resolution.documentCommentRuntime) {
if (!options.contextHost.stageDocumentProjection) {
throw new Error(
"Resolved MCP Context requires Document projection staging",
);
}
nextProjection = await options.contextHost.stageDocumentProjection(
documentCommentStaging(
request.ref.agentId,
scope.runtimeInstanceKey,
resolution.documentCommentRuntime,
),
);
await nextProjection.activate();
nextProjectionActivated = true;
}
recordStage("document_prepare");
await backend.synchronize(viewPlan, synchronizeSignal, runtimeSession);
recordStage("backend_synchronize");
synchronizeSignal.throwIfAborted();
state.documentProjection = nextProjection;
} catch (error) {
if (previousProjection) {
await previousProjection.activate().catch(() => undefined);
try {
await backend.synchronize(viewPlan, synchronizeSignal, runtimeSession);
} catch {
// The refresh error below still fails this Run.
}
}
if (nextProjection) {
await (
nextProjectionActivated
? nextProjection.release()
: nextProjection.discard()
).catch(() => undefined);
}
await previousProjection?.release().catch(() => undefined);
throw safeMcpContextError(error, "Resolved MCP Context refresh failed");
}
await previousProjection?.release().catch(() => undefined);
scope.logger.log("debug", "context_runtime.mcp_context_refreshed");
}
function deactivateContextRuntime<TRuntimeSettings>(
scope: ActiveContextRuntimeScope<TRuntimeSettings>,
state: ActiveContextRuntimeState,
): Promise<void> {
const { options, request, logger, backend, viewSession } = scope;
const protectsMcpContextCredentials =
options.mcpContextResolver !== undefined;
if (!state.deactivationPromise) {
const deactivationStartedAt = Date.now();
logger.log("info", "context_deactivation.started", {
continuingCleanup: state.deactivationSteps !== undefined,
});
if (!state.deactivationSteps) {
const projectionToRelease = state.documentProjection;
state.documentProjection = null;
state.synchronizationController.abort(
new Error("Context Runtime is deactivating"),
);
state.deactivationSteps = [
() => backend.deactivate(),
async () => viewSession.release(),
...(projectionToRelease ? [() => projectionToRelease.release()] : []),
() => scope.activationFeatures?.release() ?? Promise.resolve(),
() => options.contextHost.releaseRuntimeView(request.ref),
].map((run) => ({ run }));
}
const deactivationSteps = state.deactivationSteps;
state.deactivationPromise = Promise.allSettled([state.synchronizationTail])
.then(async () => {
const failures: unknown[] = [];
for (const step of deactivationSteps) {
if (step.completed) continue;
try {
await step.run();
step.completed = true;
} catch (error) {
failures.push(
protectsMcpContextCredentials
? safeMcpContextError(
error,
"Resolved MCP Context deactivation failed",
)
: error,
);
}
}
if (failures.length === 1) throw failures[0];
if (failures.length > 1) {
throw new AggregateError(
failures,
"Context Runtime deactivation failed",
);
}
})
.then(
() => {
logger.log("info", "context_deactivation.completed", {
durationMs: Date.now() - deactivationStartedAt,
});
},
(error: unknown) => {
logger.log("error", "context_deactivation.failed", {
durationMs: Date.now() - deactivationStartedAt,
error,
});
if (!isUnconfirmedContextRuntimeCleanup(error))
state.deactivationPromise = null;
throw error;
},
);
}
return state.deactivationPromise;
}
/**
* Retires every resource a failed activation acquired and returns the error
* the activation throws.
*/
async function retireFailedActivation<TRuntimeSettings>({
error,
stage,
acquired,
options,
ref,
logger,
startedAt,
}: {
readonly error: unknown;
readonly stage: ContextActivationStage;
readonly acquired: ActivationAcquisitions;
readonly options: ContextRuntimeActivatorOptions<TRuntimeSettings>;
readonly ref: ExecutionContextRef;
readonly logger: AgentLogger;
readonly startedAt: number;
}): Promise<unknown> {
const protectsMcpContextCredentials =
options.mcpContextResolver !== undefined;
const safeActivationError = protectsMcpContextCredentials
? safeMcpContextError(
error,
"Resolved MCP Context Runtime activation failed",
)
: error;
const activationError =
stage === "prepare_runtime_view"
? new ContextActivationError(stage, safeActivationError)
: safeActivationError;
let failure: unknown = activationError;
let cleanupErrorCount = 0;
if (acquired.backendActivation) {
try {
await acquired.backendActivation.deactivate();
} catch (cleanupError) {
const cleanupErrors =
cleanupError instanceof AggregateError
? cleanupError.errors
: [cleanupError];
cleanupErrorCount += cleanupErrors.length;
failure = new AggregateError(
[
failure,
...cleanupErrors.map((cleanupError) =>
protectsMcpContextCredentials
? safeMcpContextError(
cleanupError,
"Resolved MCP Context Runtime cleanup failed",
)
: cleanupError,
),
],
"Context Runtime activation failed",
);
}
}
if (acquired.activationFeatures) {
try {
await acquired.activationFeatures.release();
} catch (cleanupError) {
cleanupErrorCount += 1;
failure = new AggregateError(
[failure, cleanupError],
"Context Runtime activation failed",
);
}
}
acquired.viewSession?.release();
if (acquired.documentProjection) {
try {
if (acquired.documentProjectionActivated) {
await acquired.documentProjection.release();
} else {
await acquired.documentProjection.discard();
}
} catch (cleanupError) {
cleanupErrorCount += 1;
failure = new AggregateError(
[failure, cleanupError],
"Context Runtime activation failed",
);
}
}
if (acquired.runtimeViewPrepared) {
try {
await options.contextHost.releaseRuntimeView(ref);
} catch (cleanupError) {
cleanupErrorCount += 1;
const safeCleanupError = protectsMcpContextCredentials
? safeMcpContextError(
cleanupError,
"Resolved MCP Context Runtime view cleanup failed",
)
: cleanupError;
failure = new AggregateError(
[failure, safeCleanupError],
"Context Runtime activation failed",
);
logger.log("warn", "context_activation.runtime_view_release_failed", {
error: safeCleanupError,
});
}
}
// Keep cleanup classification after credential sanitization. An aborted
// activation is benign only when every acquired resource was retired.
if (cleanupErrorCount > 0 || error instanceof ContextRuntimeCleanupError)
failure = new ContextRuntimeCleanupError(
failure instanceof AggregateError ? failure.errors : [failure],
);
const waitingForComputer =
cleanupErrorCount === 0 && isLocalComputerOfflineError(failure);
const ownsFailureAlert = waitingForComputer
? false
: claimAgentFailureAlert(failure);
logger.log(
waitingForComputer ? "info" : ownsFailureAlert ? "error" : "warn",
waitingForComputer
? "context_activation.waiting_for_computer"
: "context_activation.failed",
{
cleanupErrorCount,
durationMs: Date.now() - startedAt,
error: activationError,
...(waitingForComputer
? {}
: {
...(ownsFailureAlert ? {} : { alertAggregated: true }),
failureCode: contextActivationFailureCode(stage),
}),
stage,
},
);
return failure;
}
const contextActivationFailureCode = (stage: ContextActivationStage): string =>
`CONTEXT_ACTIVATION_${stage.toUpperCase()}_FAILED`;
/** No Provider input was sent; the executor can defer this steer to a later Run. */
class SteerAdmissionDeferredError extends Error {
readonly effect = "definitely_not_applied";
constructor(cause: LocalRuntimeAdmissionUnavailableError) {
super("Local Runtime admission diagnostic is unavailable during steer", {
cause,
});
this.name = "SteerAdmissionDeferredError";
}
}
type ContextSynchronizationPhase = "before_run" | "within_run";
class SynchronizedContextProvider implements AgentProvider {
readonly #provider: AgentProvider;
readonly #synchronize: (
signal?: AbortSignal,
phase?: ContextSynchronizationPhase,
executionRunRef?: string,
) => Promise<void>;
readonly clearRunResources?: (session: RuntimeSession) => Promise<void>;
readonly inspectHistory?: NonNullable<AgentProvider["inspectHistory"]>;
readonly compactSession?: NonNullable<AgentProvider["compactSession"]>;
readonly #healthSignal: AbortSignal;
readonly #logger: AgentLogger;
readonly #prepareRunInput: NonNullable<
ContextRuntimeBackendActivation["prepareRunInput"]
>;
readonly #sourceRuns = new WeakMap<AgentRun, AgentRun>();
readonly #runGuards = new WeakMap<AgentRun, InterruptibleRun>();
#steerTail: Promise<void> = Promise.resolve();
readonly acquireRunCapacity?: AgentProvider["acquireRunCapacity"];
constructor(
provider: AgentProvider,
synchronize: (
signal?: AbortSignal,
phase?: ContextSynchronizationPhase,
executionRunRef?: string,
) => Promise<void>,
healthSignal: AbortSignal,
logger: AgentLogger,
prepareRunInput: NonNullable<
ContextRuntimeBackendActivation["prepareRunInput"]
>,
) {
this.#provider = provider;
if (provider.acquireRunCapacity)
this.acquireRunCapacity = provider.acquireRunCapacity.bind(provider);
this.#synchronize = synchronize;
this.#healthSignal = healthSignal;
this.#logger = logger;
this.#prepareRunInput = prepareRunInput;
if (provider.clearRunResources) {
this.clearRunResources = (session) =>
provider.clearRunResources!(session);
}
if (provider.inspectHistory) {
this.inspectHistory = async (session, options) => {
options.signal?.throwIfAborted();
this.#healthSignal.throwIfAborted();
const history = await provider.inspectHistory!(session, options);
options.signal?.throwIfAborted();
this.#healthSignal.throwIfAborted();
return history;
};
}
if (provider.compactSession) {
this.compactSession = async (session, options) => {
this.#healthSignal.throwIfAborted();
const result = await provider.compactSession!(session, {
...options,
signal: AbortSignal.any([options.signal, this.#healthSignal]),
});
this.#healthSignal.throwIfAborted();
return result;
};
}
}
prepareForPresence(session: RuntimeSession): void {
if (!this.#healthSignal.aborted)
this.#provider.prepareForPresence?.(session);
}
async createSession(
options: ProviderSessionOptions,
): Promise<RuntimeSession> {
this.#healthSignal.throwIfAborted();
const session = await this.#provider.createSession(options);
this.#healthSignal.throwIfAborted();
return session;
}
async resumeSession(
session: RuntimeSession,
options: ProviderSessionOptions,
): Promise<RuntimeSession> {
this.#healthSignal.throwIfAborted();
const resumed = await this.#provider.resumeSession(session, options);
this.#healthSignal.throwIfAborted();
return resumed;
}
async startRun(
session: RuntimeSession,
input: AgentInput,
spec: ExecutionSpec,
): Promise<AgentRun> {
let preparedInput = input;
try {
await this.#synchronize(
spec.signal,
"before_run",
spec.runContext?.executionRunRef,
);
spec.signal?.throwIfAborted();
this.#healthSignal.throwIfAborted();
preparedInput = await this.#prepareRunInput(
preparedInput,
AbortSignal.any([
this.#healthSignal,
...(spec.signal ? [spec.signal] : []),
]),
);
spec.signal?.throwIfAborted();
this.#healthSignal.throwIfAborted();
} catch (error) {
if (spec.signal?.aborted) throw error;
if (
error instanceof LocalRuntimeAdmissionUnavailableError &&
!this.#healthSignal.aborted
) {
throw new ProviderRunAdmissionUnavailableError({ cause: error });
}
throw new ProviderRunStartError(
"definitely_not_started",
error instanceof Error ? error.message : String(error),
{ cause: error },
);
}
const run = await this.#provider.startRun(session, preparedInput, spec);
const runGuard = new InterruptibleRun(run);
const healthSignal = this.#healthSignal;
const onHealthFailure = () => run.cancel();
healthSignal.addEventListener("abort", onHealthFailure, { once: true });
if (healthSignal.aborted) onHealthFailure();
const synchronizedRun = Object.freeze({
...(run.respond
? {
respond: async (
operationId: string,
requestId: string,
payload: Record<string, unknown>,
) => {
healthSignal.throwIfAborted();
await run.respond!(operationId, requestId, payload);
},
}
: {}),
...(run.processReused === undefined
? {}
: { processReused: run.processReused }),
...(run.dispatchedAtUnixMs === undefined
? {}
: { dispatchedAtUnixMs: run.dispatchedAtUnixMs }),
events: run.events,
async wait() {
try {
return await runGuard.wait();
} finally {
healthSignal.removeEventListener("abort", onHealthFailure);
}
},
cancel: () => {
healthSignal.removeEventListener("abort", onHealthFailure);
run.cancel();
},
});
this.#sourceRuns.set(synchronizedRun, run);
this.#runGuards.set(synchronizedRun, runGuard);
return synchronizedRun;
}
async steer(
run: AgentRun,
options: ProviderSteerOptions,
): Promise<ProviderSteerAck> {
const enqueuedAt = performance.now();
const steer = this.#steerTail
.catch(() => undefined)
.then(async () => {
const sourceRun = this.#sourceRuns.get(run) ?? run;
const runGuard = this.#runGuards.get(run);
const preparedInput = options.input;
try {
await this.#synchronize(
options.signal,
"within_run",
options.runContext?.executionRunRef,
);
options.signal?.throwIfAborted();
this.#healthSignal.throwIfAborted();
} catch (error) {
// The daemon's new-Run diagnostic can fail while this Turn remains
// healthy. The input has not reached the Provider yet: defer it,
// without cancelling the active Run. Real fences and other
// synchronization errors still interrupt as before.
if (
error instanceof LocalRuntimeAdmissionUnavailableError &&
runGuard &&
!this.#healthSignal.aborted &&
!options.signal?.aborted
) {
throw new SteerAdmissionDeferredError(error);
}
if (runGuard) runGuard.interrupt();
else sourceRun.cancel();
throw error;
}
return this.#provider.steer(sourceRun, {
...options,
input: preparedInput,
});
});
this.#steerTail = steer.then(
() => undefined,
() => undefined,
);
const recordOutcome = (outcome: "accepted" | "rejected") =>
this.#logger.log("info", "context_runtime.steer_admission_finished", {
executionRunRef: options.runContext?.executionRunRef,
elapsedMs: Math.round(performance.now() - enqueuedAt),
outcome,
});
return steer.then(
(ack) => {
recordOutcome("accepted");
return ack;
},
(error: unknown) => {
recordOutcome("rejected");
throw error;
},
);
}
close(): Promise<void> {
return this.#provider.close();
}
}
/** Reports a Run cancelled by a failed steer synchronization as interrupted. */
class InterruptibleRun {
readonly #run: AgentRun;
#interrupted = false;
constructor(run: AgentRun) {
this.#run = run;
}
interrupt(): void {
if (this.#interrupted) return;
this.#interrupted = true;
try {
this.#run.cancel();
} catch {
// The interruption owns the terminal error; provider cancellation is best effort.
}
}
async wait() {
try {
const result = await this.#run.wait();
if (this.#interrupted) throw interruptedRun();
return result;
} catch (error) {
if (this.#interrupted) throw interruptedRun();
throw error;
}
}
}
const interruptedRun = (): ProviderRunInterruptedError =>
new ProviderRunInterruptedError(
"Provider Run was interrupted because Context synchronization failed",
);
const requirePreviousSession = (session: RuntimeSession): RuntimeSession => {
if (session === undefined || session === null) {
throw new TypeError("Context Runtime resume requires a previous Session");
}
return session;
};
const safeMcpContextError = (error: unknown, message: string): unknown =>
containsMcpContextCredential(error) ? new Error(message) : error;
const containsMcpContextCredential = (value: unknown): boolean => {
const seen = new Set<object>();
const visit = (current: unknown): boolean => {
if (typeof current === "string") {
return /(?:mcp_ctx_|cli_ctx_)[A-Za-z0-9_-]{43}/u.test(current);
}
if (typeof current !== "object" || current === null || seen.has(current)) {
return false;
}
seen.add(current);
if (Array.isArray(current)) return current.some(visit);
for (const property of Object.getOwnPropertyNames(current)) {
const descriptor = Object.getOwnPropertyDescriptor(current, property);
if (descriptor && "value" in descriptor && visit(descriptor.value)) {
return true;
}
}
return false;
};
return visit(value);
};