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 { AsyncLocalStorage } from "node:async_hooks";
import { randomUUID } from "node:crypto";
import { logAgentEvent } from "../observability/agent-log.js";
import {
createTeamHubAgentRuntimeStateClient,
type TeamHubAgentCallbackFetch,
} from "@linger/wire-contracts/teamhub-internal/client";
import type { components } from "@linger/wire-contracts/teamhub-internal/types";
import { isRecord } from "@linger/service-kit";
export type RuntimeStateSchemas = components["schemas"];
export type RuntimeConfigSnapshot =
RuntimeStateSchemas["AgentRuntimeConfigSnapshot"];
export type RuntimeDeletionSnapshot =
RuntimeStateSchemas["AgentRuntimeDeletionSnapshot"];
export type RuntimeContext = RuntimeStateSchemas["AgentExecutionContext"];
export type AcceptedContextState =
RuntimeStateSchemas["AgentRuntimeAcceptedContextState"];
export type RuntimeInput = RuntimeStateSchemas["AgentRuntimeInput"];
export type RuntimeSession = RuntimeStateSchemas["AgentRuntimeSession"];
export type RuntimeSessionCheckpoint =
RuntimeStateSchemas["AgentRuntimeSessionCheckpoint"];
type RuntimeLocalRun = RuntimeStateSchemas["AgentLocalRun"];
/** Each process start opens a new epoch; its start time only helps reading logs. */
const newAgentServiceEpoch = (): string =>
`agent-epoch-v1:${Date.now()}:${randomUUID().replaceAll("-", "")}`;
export interface TeamHubRuntimeStateClientOptions {
readonly baseUrl: string;
readonly serviceToken: string;
readonly fetch?: TeamHubAgentCallbackFetch;
readonly requestTimeoutMs?: number;
readonly epoch?: string;
}
export class TeamHubRuntimeStateError extends Error {
override readonly name = "TeamHubRuntimeStateError";
constructor(
readonly status: number | null,
message: string,
readonly code?: string,
readonly retryable = status === null || status >= 500,
readonly priorAttemptOutcomeUnknown = false,
) {
super(message);
}
}
/** True when a TeamHub runtime-state call answered 404. */
export function isTeamHubNotFound(error: unknown): boolean {
return isRecord(error) && error.status === 404;
}
export interface TeamHubRuntimeStateClient {
/** The Agent Service epoch every Runtime write of this process names. */
readonly epoch: string;
/**
* Opens this process's epoch: TeamHub interrupts the Runs of the previous
* one and lists the Contexts with queued work.
*/
startEpoch(
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentServiceEpochStart"]>;
getConfig(
agentId: string,
revision?: string,
signal?: AbortSignal,
configReadId?: string,
): Promise<RuntimeConfigSnapshot>;
getDeletionSnapshot(
agentId: string,
signal?: AbortSignal,
): Promise<RuntimeDeletionSnapshot>;
listContexts(
agentId?: string,
signal?: AbortSignal,
): Promise<RuntimeContext[]>;
reconcileContexts(
body: RuntimeStateSchemas["ReconcileAgentExecutionContextsRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["ReconcileAgentExecutionContextsResult"]>;
/** Read only: lists recently run Context keys without activating them. */
listRecentlyUsedContexts(signal?: AbortSignal): Promise<readonly string[]>;
getContext(contextKey: string, signal?: AbortSignal): Promise<RuntimeContext>;
ensureContext(
body: RuntimeStateSchemas["EnsureAgentExecutionContextRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["EnsureAgentExecutionContextResult"]>;
setContextResidency(
body: RuntimeStateSchemas["SetAgentExecutionContextResidencyRequest"],
signal?: AbortSignal,
): Promise<RuntimeContext>;
deleteContext(
body: RuntimeStateSchemas["DeleteAgentExecutionContextRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeDeletedResult"]>;
acceptTrustedNotification(
body: RuntimeStateSchemas["AcceptAgentTrustedNotificationRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AcceptAgentTrustedNotificationResult"]>;
submitTrustedTurn(
body: RuntimeStateSchemas["SubmitAgentTrustedTurnRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["SubmitAgentTrustedTurnResult"]>;
getRun(
contextKey: string,
runId: string,
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentLocalRun"]>;
getRunReplyStatus(
contextKey: string,
runId: string,
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentLocalRunReplyStatus"]>;
/** Contexts whose queued Run or Message steer waited past its wake hint. */
listWaitingContexts(signal?: AbortSignal): Promise<readonly string[]>;
claimRun(
body: RuntimeStateSchemas["ClaimAgentLocalRunRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["ClaimAgentLocalRunResult"]>;
requeueRun(
body: RuntimeStateSchemas["RequeueAgentLocalRunRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>;
finishRun(
body: RuntimeStateSchemas["FinishAgentLocalRunRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["FinishAgentLocalRunResult"]>;
cancelRun(
body: RuntimeStateSchemas["CancelAgentLocalRunRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["CancelAgentLocalRunResult"]>;
enqueueSteer(
body: RuntimeStateSchemas["EnqueueAgentSteerRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["EnqueueAgentSteerResult"]>;
assignSteerRun(
body: RuntimeStateSchemas["AssignAgentSteerRunRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>;
completeSteer(
body: RuntimeStateSchemas["CompleteAgentSteerRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>;
getSession(
contextKey: string,
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["GetAgentRuntimeSessionResult"]>;
checkpointSession(
body: RuntimeStateSchemas["CheckpointAgentRuntimeSessionRequest"],
signal?: AbortSignal,
): Promise<RuntimeSession>;
clearSession(
body: RuntimeStateSchemas["ClearAgentRuntimeSessionRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["ClearAgentRuntimeSessionResult"]>;
getWorkState(
contextKey: string,
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeWorkState"]>;
openStatus(
body: RuntimeStateSchemas["OpenAgentRuntimeStatusRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["OpenAgentRuntimeStatusResult"]>;
offerPresentationEvents(
body: RuntimeStateSchemas["OfferAgentRuntimePresentationEventsRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["OfferAgentRuntimePresentationEventsResult"]>;
getLocalComputer(
computerId: string,
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeLocalComputer"]>;
connectLocalComputer(
body: RuntimeStateSchemas["ConnectAgentRuntimeLocalComputerRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["ConnectAgentRuntimeLocalComputerResult"]>;
touchLocalComputer(
body: RuntimeStateSchemas["TouchAgentRuntimeLocalComputerRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeLocalComputer"]>;
removeLocalComputer(
body: RuntimeStateSchemas["AgentRuntimeLocalComputerCredentialRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeLocalComputerRemovalResult"]>;
recordLocalModels(
body: RuntimeStateSchemas["RecordLocalModelsRequest"],
signal?: AbortSignal,
): Promise<void>;
recordRunOperation(
body: RuntimeStateSchemas["RecordAgentLocalRunOperationRequest"],
signal?: AbortSignal,
): Promise<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>;
}
export const createTeamHubRuntimeStateClient = (
options: TeamHubRuntimeStateClientOptions,
): TeamHubRuntimeStateClient => {
const timeout = options.requestTimeoutMs ?? 10_000;
if (!Number.isSafeInteger(timeout) || timeout <= 0) {
throw new TypeError("requestTimeoutMs must be a positive safe integer");
}
const fetchRequest = options.fetch ?? globalThis.fetch;
const responsesAfterUnknownAttempt = new WeakSet<Response>();
const retryingFetch: TeamHubAgentCallbackFetch = async (input, init) => {
const retryableRequest =
init?.method === "GET" ||
requestBodyIsRepeatable(init?.body) ||
isRepeatableRequest(input, init);
const attempts = retryableRequest ? 3 : 1;
let lastError: unknown;
let priorAttemptOutcomeUnknown = false;
for (let attempt = 1; attempt <= attempts; attempt += 1) {
const configRead = recordRuntimeConfigFetchAttempt();
const timeoutSignal = AbortSignal.timeout(timeout);
const signal = init?.signal
? AbortSignal.any([init.signal, timeoutSignal])
: timeoutSignal;
try {
const response = await Promise.race([
fetchRequest(input, { ...init, signal }),
rejectWhenAborted(signal),
]);
if (configRead) configRead.httpStatus = response.status;
if (response.status >= 500 && attempt < attempts) {
priorAttemptOutcomeUnknown = true;
await response.body?.cancel().catch(() => undefined);
lastError = new Error(`HTTP ${response.status}`);
continue;
}
const result = retryableRequest
? await bufferResponse(response, signal)
: response;
if (priorAttemptOutcomeUnknown)
responsesAfterUnknownAttempt.add(result);
return result;
} catch (error) {
priorAttemptOutcomeUnknown = true;
lastError = error;
if (init?.signal?.aborted || attempt === attempts) throw error;
}
}
throw lastError;
};
const raw = createTeamHubAgentRuntimeStateClient({
baseUrl: options.baseUrl,
serviceToken: options.serviceToken,
fetch: retryingFetch,
});
const epoch = options.epoch?.trim() || newAgentServiceEpoch();
const request = async <T>(
responsePromise: Promise<Response>,
_signal?: AbortSignal,
): Promise<T> => {
let response: Response;
try {
response = await responsePromise;
} catch (error) {
throw new TeamHubRuntimeStateError(
null,
`TeamHub Runtime State request failed: ${errorMessage(error)}`,
);
}
if (!response.ok) {
const detail = await readErrorDetail(response);
throw new TeamHubRuntimeStateError(
response.status,
`TeamHub Runtime State returned HTTP ${response.status}${detail.text ? `: ${detail.text}` : ""}`,
detail.code,
detail.retryable,
responsesAfterUnknownAttempt.has(response),
);
}
if (response.status === 204) return undefined as T;
try {
return (await response.json()) as T;
} catch (error) {
throw new TeamHubRuntimeStateError(
response.status,
`TeamHub Runtime State response JSON could not be read: ${errorMessage(error)}`,
undefined,
// Response headers may arrive before a transport failure. The claim
// caller must reconcile ownership, not treat this as invalid wire data.
error instanceof Error &&
["AbortError", "TimeoutError", "TypeError"].includes(error.name),
);
}
};
return {
epoch,
startEpoch: (signal) =>
request<RuntimeStateSchemas["AgentServiceEpochStart"]>(
raw.startEpoch({ epoch }, signal),
signal,
),
getConfig: (agentId, revision, signal, configReadId = randomUUID()) =>
timeRuntimeConfigRead(agentId, signal, configReadId, () =>
request<RuntimeConfigSnapshot>(
raw.getConfig(agentId, revision, signal),
signal,
),
),
getDeletionSnapshot: (agentId, signal) =>
request<RuntimeDeletionSnapshot>(
raw.getDeletionSnapshot(agentId, signal),
signal,
),
listContexts: async (agentId, signal) =>
(
await request<RuntimeStateSchemas["AgentExecutionContextList"]>(
raw.listContexts(agentId, signal),
signal,
)
).contexts,
listRecentlyUsedContexts: async (signal) =>
(
await request<
RuntimeStateSchemas["ListRecentlyUsedAgentRuntimeContextsResult"]
>(raw.listRecentlyUsedContexts(signal), signal)
).contexts.map(({ context_key }) => context_key),
reconcileContexts: (body, signal) =>
request<RuntimeStateSchemas["ReconcileAgentExecutionContextsResult"]>(
raw.reconcileContexts(body, signal),
signal,
),
getContext: (contextKey, signal) =>
request<RuntimeContext>(raw.getContext(contextKey, signal), signal),
ensureContext: (body, signal) =>
request<RuntimeStateSchemas["EnsureAgentExecutionContextResult"]>(
raw.ensureContext(body, signal),
signal,
),
setContextResidency: (body, signal) =>
request<RuntimeContext>(raw.setContextResidency(body, signal), signal),
deleteContext: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeDeletedResult"]>(
raw.deleteContext(body, signal),
signal,
),
acceptTrustedNotification: (body, signal) =>
request<RuntimeStateSchemas["AcceptAgentTrustedNotificationResult"]>(
raw.acceptTrustedNotification(body, signal),
signal,
),
submitTrustedTurn: (body, signal) =>
request<RuntimeStateSchemas["SubmitAgentTrustedTurnResult"]>(
raw.submitTrustedTurn(body, signal),
signal,
),
getRun: (contextKey, runId, signal) =>
request<RuntimeLocalRun>(raw.getRun(contextKey, runId, signal), signal),
getRunReplyStatus: (contextKey, runId, signal) =>
request<RuntimeStateSchemas["AgentLocalRunReplyStatus"]>(
raw.getRunReplyStatus(contextKey, runId, signal),
signal,
),
listWaitingContexts: async (signal) =>
(
await request<RuntimeStateSchemas["AgentRuntimeWaitingContexts"]>(
raw.listWaitingContexts(signal),
signal,
)
).context_keys,
claimRun: (body, signal) =>
request<RuntimeStateSchemas["ClaimAgentLocalRunResult"]>(
raw.claimRun(body, signal),
signal,
),
requeueRun: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>(
raw.requeueRun(body, signal),
signal,
),
finishRun: (body, signal) =>
request<RuntimeStateSchemas["FinishAgentLocalRunResult"]>(
raw.finishRun(body, signal),
signal,
),
cancelRun: (body, signal) =>
request<RuntimeStateSchemas["CancelAgentLocalRunResult"]>(
raw.cancelRun(body, signal),
signal,
),
enqueueSteer: (body, signal) =>
request<RuntimeStateSchemas["EnqueueAgentSteerResult"]>(
raw.enqueueSteer(body, signal),
signal,
),
assignSteerRun: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>(
raw.assignSteerRun(body, signal),
signal,
),
completeSteer: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>(
raw.completeSteer(body, signal),
signal,
),
getSession: (contextKey, signal) =>
request<RuntimeStateSchemas["GetAgentRuntimeSessionResult"]>(
raw.getSession(contextKey, signal),
signal,
),
checkpointSession: (body, signal) =>
request<RuntimeSession>(raw.checkpointSession(body, signal), signal),
clearSession: (body, signal) =>
request<RuntimeStateSchemas["ClearAgentRuntimeSessionResult"]>(
raw.clearSession(body, signal),
signal,
),
getWorkState: (contextKey, signal) =>
request<RuntimeStateSchemas["AgentRuntimeWorkState"]>(
raw.getWorkState(contextKey, signal),
signal,
),
openStatus: (body, signal) =>
request<RuntimeStateSchemas["OpenAgentRuntimeStatusResult"]>(
raw.openStatus(body, signal),
signal,
),
offerPresentationEvents: (body, signal) =>
request<RuntimeStateSchemas["OfferAgentRuntimePresentationEventsResult"]>(
raw.offerPresentationEvents(body, signal),
signal,
),
getLocalComputer: (computerId, signal) =>
request<RuntimeStateSchemas["AgentRuntimeLocalComputer"]>(
raw.getLocalComputer(computerId, signal),
signal,
),
connectLocalComputer: (body, signal) =>
request<RuntimeStateSchemas["ConnectAgentRuntimeLocalComputerResult"]>(
raw.connectLocalComputer(body, signal),
signal,
),
touchLocalComputer: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeLocalComputer"]>(
raw.touchLocalComputer(body, signal),
signal,
),
removeLocalComputer: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeLocalComputerRemovalResult"]>(
raw.removeLocalComputer(body, signal),
signal,
),
recordLocalModels: (body, signal) =>
request<void>(raw.recordLocalModels(body, signal), signal),
recordRunOperation: (body, signal) =>
request<RuntimeStateSchemas["AgentRuntimeSuccessResult"]>(
raw.recordRunOperation(body, signal),
signal,
),
};
};
/** Names one claim, so a claim repeated after a lost response gets its Run. */
export const runtimeClaimId = (): string =>
`claim-${randomUUID().replaceAll("-", "")}`;
const readErrorDetail = async (
response: Response,
): Promise<{ code?: string; retryable: boolean; text: string }> => {
try {
const value = (await response.json()) as unknown;
if (isRecord(value) && isRecord(value.error)) {
return {
code:
typeof value.error.code === "string" ? value.error.code : undefined,
retryable:
typeof value.error.retryable === "boolean"
? value.error.retryable
: response.status >= 500,
text:
typeof value.error.message === "string" ? value.error.message : "",
};
}
} catch {
// Fall through to the bounded text body for non-JSON responses.
}
return { retryable: response.status >= 500, text: "" };
};
// Runtime writes name the epoch and are idempotent; presentation events carry
// their own command identity.
const requestBodyIsRepeatable = (body: RequestInit["body"]): boolean => {
if (typeof body !== "string") return false;
try {
const value = JSON.parse(body) as unknown;
if (!isRecord(value)) return false;
if (typeof value.epoch === "string" && value.epoch.trim().length > 0)
return true;
return (
typeof value.command_id === "string" && value.command_id.trim().length > 0
);
} catch {
return false;
}
};
// Context identity and Runtime registration writes converge on a repeat.
const REPEATABLE_POST_PATHS = [
"/v0/agent-runtime/contexts",
"/v0/agent-runtime/contexts/reconcile",
"/v0/agent-runtime/contexts/residency",
"/v0/agent-runtime/contexts/delete",
"/v0/agent-runtime/computer-daemon-identity/bind",
"/v0/agent-runtime/local-runtime-registrations/observe",
"/v0/agent-runtime/assignments/set",
];
const isRepeatableRequest = (
input: string | URL | Request,
init?: RequestInit,
): boolean => {
if (init?.method !== "POST") return false;
try {
const url = new URL(input instanceof Request ? input.url : String(input));
return REPEATABLE_POST_PATHS.some((path) => url.pathname.endsWith(path));
} catch {
return false;
}
};
const bufferResponse = async (
response: Response,
signal: AbortSignal,
): Promise<Response> => {
if (!response.body) return response;
let body: ArrayBuffer;
try {
body = await Promise.race([
response.arrayBuffer(),
rejectWhenAborted(signal),
]);
} catch (error) {
await response.body?.cancel().catch(() => undefined);
throw error;
}
return new Response(body.byteLength === 0 ? null : body, {
headers: response.headers,
status: response.status,
statusText: response.statusText,
});
};
const rejectWhenAborted = (signal: AbortSignal): Promise<never> =>
new Promise((_, reject) => {
if (signal.aborted) {
reject(signal.reason);
return;
}
signal.addEventListener("abort", () => reject(signal.reason), {
once: true,
});
});
const errorMessage = (error: unknown): string =>
error instanceof Error ? error.message : String(error);
export interface RuntimeConfigTimingContext {
readonly agentId: string;
readonly contextKey: string;
readonly contextKind: string;
readonly phase: "create" | "preaccept" | "activation" | "unscoped";
}
// Diagnostic context follows only the current async call chain. It is neither
// registration authority nor a completed configuration/readiness cache.
const configTimingContext = new AsyncLocalStorage<{
readonly context?: RuntimeConfigTimingContext & {
readonly configTraceId: string;
};
readonly read?: { attemptCount: number; httpStatus: number | null };
}>();
export const withRuntimeConfigTimingContext = <T>(
context: RuntimeConfigTimingContext,
operation: () => T,
newTrace = false,
): T => {
const scope = configTimingContext.getStore();
const parent = scope?.context;
const configTraceId =
!newTrace &&
parent?.agentId === context.agentId &&
parent.contextKey === context.contextKey
? parent.configTraceId
: randomUUID();
return configTimingContext.run(
{ ...scope, context: { ...context, configTraceId } },
operation,
);
};
const runtimeConfigReadFields = (agentId: string, configReadId: string) => {
const context = configTimingContext.getStore()?.context;
return {
component: "runtime-state",
...(context?.agentId === agentId
? context
: { agentId, phase: "unscoped", configTraceId: configReadId }),
configReadId,
method: "GET",
endpoint: "getConfig",
};
};
export const recordRuntimeConfigFetchAttempt = () => {
const read = configTimingContext.getStore()?.read;
if (read) {
read.attemptCount += 1;
read.httpStatus = null;
}
return read;
};
export const timeRuntimeConfigRead = async <T>(
agentId: string,
signal: AbortSignal | undefined,
configReadId: string,
operation: () => Promise<T>,
): Promise<T> => {
const fields = runtimeConfigReadFields(agentId, configReadId);
const read = { attemptCount: 0, httpStatus: null as number | null };
const startedAt = new Date().toISOString();
const startedMonotonic = performance.now();
try {
const snapshot = await configTimingContext.run(
{ ...configTimingContext.getStore(), read },
operation,
);
logConfigRead("completed", {
...fields,
...read,
startedAt,
durationMs: performance.now() - startedMonotonic,
outcome: "success",
});
return snapshot;
} catch (error) {
logConfigRead("completed", {
...fields,
...read,
startedAt,
durationMs: performance.now() - startedMonotonic,
outcome: signal?.aborted ? "cancelled" : "failed",
});
throw error;
}
};
export const logIgnoredRuntimeConfigRead = (
agentId: string,
configReadId: string,
): void => {
logConfigRead("ignored", {
...runtimeConfigReadFields(agentId, configReadId),
reason: "superseded",
});
};
const logConfigRead = (
event: "completed" | "ignored",
fields: Readonly<Record<string, unknown>>,
): void => {
try {
logAgentEvent("info", `runtime_config.get_config_${event}`, fields);
} catch {
// Diagnostics never change the result or the caller's freshness fence.
}
};