Concepts
Error taxonomy
Every failure is a FoomtimeError subclass — discriminate with instanceof.
All failures surface at the Promise/exception boundary as subclasses of
FoomtimeError. Catch the base to handle everything, or a specific subclass to
react to one cause. Never parse an error message.
Repairable agent faults — bad foom_call arguments, a call to an unexposed
method, or a foom_return whose value fails its schema (or never comes) — are
not thrown when they happen. The runtime feeds each back to the model in-band
and re-prompts, up to repairAttempts. They surface as a single exception only
once repair is exhausted: FoomtimeRepairExhaustedError, whose .channel
("args" | "return" | "dispatch") names the fault.
import {
FoomtimeError,
FoomtimeThrowError,
FoomtimeRepairExhaustedError,
FoomtimeBudgetExceededError,
} from "@microfoom/core";
try {
const result = await runProgram(MyProgram, input, opts);
} catch (err) {
if (err instanceof FoomtimeThrowError) {
// A deliberate foom_throw in a prompt — always carries `code`.
console.error(err.code, err.message);
} else if (err instanceof FoomtimeBudgetExceededError) {
// Hit maxBudgetUsd.
} else if (err instanceof FoomtimeRepairExhaustedError) {
// The agent's output couldn't be repaired in time; err.channel says which fault.
console.error("repair exhausted:", err.channel);
} else if (err instanceof FoomtimeError) {
// Anything else in the taxonomy.
}
}The hierarchy
FoomtimeError
├─ FoomtimeThrowError deliberate foom_throw (always carries `code`)
├─ FoomtimeAbortError run ended early
│ ├─ FoomtimeTimeoutError exceeded maxTurnDuration / maxProgramDuration
│ └─ FoomtimeCancelledError aborted via signal / .abort()
├─ FoomtimeBudgetExceededError exceeded maxBudgetUsd
├─ FoomtimeTokenLimitExceededError exceeded maxOutputTokens
├─ FoomtimeCallDepthError exceeded maxCallDepth
├─ FoomtimeRepairExhaustedError repair loop gave up; `.channel` names the fault
├─ FoomtimeHarnessError harness/backend boundary failure
│ ├─ FoomtimeHarnessUnavailableError transient — retryable
│ └─ FoomtimeHarnessRejectedError non-transient
├─ FoomtimeConfigError bad config (no such model, invalid cap, …)
├─ FoomtimeInputError /run input failed the program's input schema
├─ FoomtimeDispatchError exposed method has no implementation (a defect)
└─ FoomtimeConcurrencyError overlapping turns on one session