import { sourceText } from "@openbot/i18n/source";
import { Duration, Effect, Exit, Schedule, Scope } from "effect";
import type { HostMemory } from "../host-memory";
import type { ProviderClientOperationError } from "../provider-client-effects";
export interface MemoryHoldHooks {
scheduleAll(): void;
* Tries the agents that wait for a turn slot again. A slot can free on a path that schedules no
* drain, so each sample is also a retry.
*/
retryWaiting(): void;
* Closes the provider threads that have no turn. They open again from their session. Called at each
* sample while a delivery is held, so a call with no idle thread must do nothing.
*/
releaseIdleThreads(): Effect.Effect<void, ProviderClientOperationError>;
* Closes the provider threads that only background work holds, when that work sent nothing for a
* long time. Called at each low sample, so a call with no such thread must do nothing.
*/
releaseQuietBackgroundThreads(): Effect.Effect<void, ProviderClientOperationError>;
emitError(code: string, error: unknown, agentId?: string): void;
}
export interface MemoryHoldOptions {
memory: HostMemory | null;
* The total that an owner or admin set, "unlimited" for no limit, or null for automatic: the memory
* sets it on a server, and a desktop computer has no limit. A set total can be above the automatic
* one; low memory still holds a new turn.
*/
chosenTurnLimit?: () => number | "unlimited" | null;
hooks: MemoryHoldHooks;
}
* Owns the memory clause of the queue drain. While the machine is low on memory no new turn starts,
* and the delivery stays queued: a message to a busy machine waits, as it does for a busy agent. Each
* held agent is told one time in each low period. At a critical level, and while a delivery is held,
* the idle provider threads close. At each low sample, the threads that only quiet background work
* holds close.
* It never imports the service.
*/
const SLOT_RETRY_INTERVAL = Duration.seconds(5);
export class MemoryHold {
readonly #memory: HostMemory | null;
readonly #chosenTurnLimit: () => number | "unlimited" | null;
readonly #hooks: MemoryHoldHooks;
#scope = Scope.makeUnsafe();
readonly #told = new Set<string>();
* A failed release is reported one time in each low period, and at each change to critical: a held
* delivery retries it at each sample.
*/
#releaseFailed = false;
#releasing = false;
#criticalReleased = false;
#unsubscribe: (() => void) | null = null;
constructor(options: MemoryHoldOptions) {
this.#memory = options.memory;
this.#chosenTurnLimit = options.chosenTurnLimit ?? (() => null);
this.#hooks = options.hooks;
}
start(): void {
if (this.#unsubscribe) return;
if (!this.#memory) {
const retry = Effect.sync(() => {
if (typeof this.#chosenTurnLimit() === "number") this.#hooks.retryWaiting();
}).pipe(
Effect.repeat(Schedule.spaced(SLOT_RETRY_INTERVAL)),
Effect.forkIn(this.#scope, { startImmediately: true }),
);
Effect.runFork(retry);
this.#unsubscribe = () => {};
return;
}
this.#unsubscribe = this.#memory.subscribe(() =>
Effect.runFork(this.#sampled().pipe(Effect.forkIn(this.#scope, { startImmediately: true }))),
);
}
readonly dispose = Effect.fn("MemoryHold.dispose")(function* (this: MemoryHold) {
this.#unsubscribe?.();
this.#unsubscribe = null;
yield* Scope.close(this.#scope, Exit.void);
this.#scope = Scope.makeUnsafe();
}).bind(this);
mayDrain(_agentId: string): boolean {
return (this.#memory?.level() ?? "ok") === "ok";
}
held(agentId: string): void {
if (this.#told.has(agentId)) return;
this.#told.add(agentId);
const message = this.#memory?.hostedPlan
? sourceText("error.agent.lowMemory")
: sourceText("error.agent.lowMemoryServer");
this.#hooks.emitError("host_memory_low", new Error(message), agentId);
}
reserveTurn(): () => void {
return this.#memory?.reserveTurn() ?? (() => {});
}
turnLimit(): number | null {
const chosen = this.#chosenTurnLimit();
if (chosen === "unlimited") return null;
return chosen ?? this.#memory?.turnLimit() ?? null;
}
readonly #sampled = Effect.fn("MemoryHold.sampled")(function* (this: MemoryHold) {
this.#hooks.retryWaiting();
const level = this.#memory?.level() ?? "ok";
if (level !== "critical") this.#criticalReleased = false;
const critical = level === "critical" && !this.#criticalReleased;
if (!this.#releasing && level !== "ok") {
this.#releasing = true;
const releases = [this.#hooks.releaseQuietBackgroundThreads()];
if (critical || this.#told.size > 0) releases.push(this.#hooks.releaseIdleThreads());
if (critical) this.#criticalReleased = true;
yield* Effect.forEach(
releases,
(release) =>
release.pipe(
Effect.catch((failure) =>
Effect.sync(() => {
if (this.#releaseFailed && !critical) return;
this.#releaseFailed = true;
this.#hooks.emitError("idle_thread_release_failed", failure.cause);
}),
),
),
{ discard: true },
).pipe(Effect.ensuring(Effect.sync(() => (this.#releasing = false))));
}
if (level === "ok") this.#releaseFailed = false;
if (level === "ok" && this.#told.size > 0) {
this.#told.clear();
this.#hooks.scheduleAll();
}
});
}