@animalabs/agent-framework 0.22.0 → 0.22.1

package/dist/src/provider-waits.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Provider waits: a provider's stated `retry-after`, kept as a deadline that
+ * outlives the process.
+ *
+ * When a provider answers "retry after N", calling the same model again
+ * before then adds traffic the provider has said will fail. The framework
+ * therefore records the wait per (agent, model) and admits no call to that
+ * model for that agent until it passes. The wait is a fact about the provider,
+ * not about the conversation, so it is kept in typed Chronicle records
+ * (RecordJournal): a restart honours it, and a branch switch or rollback
+ * does not rewind it.
+ *
+ * - A later, shorter wait for the same (agent, model) never shortens an
+ *   outstanding longer one: the binding deadline is the maximum. Requests
+ *   that finish at different times can carry different hints.
+ * - A negative wait is already over (a provider's "retry now", or an HTTP
+ *   date already past), -Infinity included: it binds nothing, the same as 0.
+ * - A wait that cannot be represented as an instant (NaN, +Infinity, or past
+ *   the last instant a Date can hold) becomes an indefinite wait rather than
+ *   a shorter one, held until explicitly released.
+ * - A wait ends when its instant passes (nothing is written), or when an
+ *   operator releases it (recorded). Selecting a different model is not a
+ *   release: that model proceeds, and the old model's wait still applies if it
+ *   is selected again before the wait passes.
+ *
+ * One writer per record type (RecordJournal's contract): the framework that
+ * owns the store.
+ */
+import type { JsStore } from '@animalabs/chronicle';
+export declare const PROVIDER_WAIT_RECORD_TYPE = "framework/provider-wait";
+export interface ProviderWait {
+    agent: string;
+    model: string;
+    /** Epoch ms before which no call is admitted; null holds until released. */
+    until: number | null;
+    /** Why, in the provider's words (bounded by the caller). */
+    reason: string;
+    /** When the binding wait was recorded. */
+    setAt: number;
+}
+/**
+ * The instant a stated wait ends, or null when it cannot be represented:
+ * the wait is then held until released, never shortened. A negative wait
+ * ends at `now`: it is already over, never indefinite.
+ */
+export declare function waitDeadline(retryAfterMs: unknown, now: number): number | null;
+export interface ProviderWaitChange {
+    /** The binding wait after this call; for a wait already over with nothing
+     *  binding, that wait as stated, which binds nothing and isn't recorded. */
+    wait: ProviderWait;
+    /** False when an outstanding longer (or indefinite) wait already binds, or
+     *  when the wait is already over and nothing binds. */
+    changed: boolean;
+}
+/**
+ * One wait a release lifted. `release` says how far that reaches:
+ * - 'recorded': the release is durably recorded, so a restart keeps it;
+ * - 'pending': it binds in this process, but its record has not landed yet
+ *   and is offered again at the next act (a restart before then restores the
+ *   wait). Once the journal can't be written again (an append that threw
+ *   inside the store), it is offered no more in this process;
+ * - 'in-process override': the hold that stands for unreadable recorded
+ *   waits, lifted for this process only (a restart that still cannot read
+ *   them holds again). The release itself is still offered to the journal,
+ *   so once the history can be read it applies there, in order.
+ */
+export interface ProviderWaitRelease {
+    wait: ProviderWait;
+    release: 'recorded' | 'pending' | 'in-process override';
+}
+/**
+ * The model that stands for every model: how list() shows the hold for
+ * unreadable records, and what release() takes as "every model" (the same as
+ * omitting it). No provider model is named that.
+ */
+export declare const EVERY_MODEL = "*";
+/** Text from a caller or a provider, with each control character a space, so
+ *  it can't forge a log line where it is printed. */
+export declare function withoutControls(text: string): string;
+/**
+ * Whether a release's `model`, as an operator surface receives it, names a
+ * scope: omitted or EVERY_MODEL for every model, any other nonempty string
+ * without a control character for that model. Anything else is malformed and
+ * is refused, never taken as "every model" (and never logged).
+ */
+export declare function isReleaseModel(model: unknown): model is string | undefined;
+export declare class ProviderWaits {
+    /**
+     * The reduction of exactly what the journal holds: its latest checkpoint and
+     * every entry after it, as loaded or as appended and synced. A checkpoint
+     * records this, so it covers the same ordered acts the journal does.
+     */
+    private durable;
+    /**
+     * Acts of this process not yet known to be durably recorded, in the order
+     * they were made. They bind here from the moment they are made, and are
+     * offered to the journal, in order, at every later act until one lands.
+     * Once the journal can't be written again (an append that threw inside the
+     * store: RecordJournal.needsReopen), they are offered no more: the act that
+     * threw may still be in the store's log, where the next start finds it,
+     * and every later one holds in this process only.
+     */
+    private readonly pending;
+    /** What binds in this process: `durable` with `pending` applied in order. */
+    private view;
+    /**
+     * Set while the recorded waits cannot be read. Their absence is then
+     * unknown, not "no waits": every (agent, model) is held (fail closed) until
+     * they can be read or an operator releases the agent's waits. Releases made
+     * meanwhile are kept in `waived` (agent, model or EVERY_MODEL) for this
+     * process; a restart that still cannot read them holds again.
+     */
+    private unreadable;
+    private lastWriteTry;
+    /**
+     * How often unreadable recorded waits are read again. The hold that stands
+     * for them ends without any act (the records read again), so whoever holds
+     * on a wait with no deadline asks active() again this often.
+     */
+    readonly retryReadMs: number;
+    private readonly store;
+    private readonly journal;
+    private readonly now;
+    private readonly log;
+    private readonly onUnreadable;
+    /**
+     * `store` null keeps waits in memory only (a framework without a store has
+     * no restart to survive). `onUnreadable` hears each time the recorded waits
+     * become unreadable, once per episode (a restart that still cannot read them
+     * is a new one): every (agent, model) is then held until they read again or
+     * an operator releases, and a cause that persists (a malformed or newer
+     * record) never reads again, so a person has to hear of it.
+     */
+    constructor(store: JsStore | null, opts?: {
+        now?: () => number;
+        log?: (line: string) => void;
+        retryReadMs?: number;
+        onUnreadable?: (error: string) => void;
+    });
+    /**
+     * The wait binding (agent, model) now, if any. While the recorded waits
+     * cannot be read, an indefinite wait saying so, unless an operator released
+     * this agent's waits since.
+     */
+    active(agent: string, model: string): ProviderWait | undefined;
+    /**
+     * Whether a recorded wait binds this agent now, unreadable history aside:
+     * the agent of a wait the listing shows, even one the framework no longer
+     * has (a disposed conversation fork), which a release can then name.
+     */
+    recorded(agent: string): boolean;
+    /**
+     * Every wait binding now, for one agent or all. While the recorded waits
+     * cannot be read, it leads with an indefinite wait on EVERY_MODEL saying
+     * so (for the agent asked about, or for EVERY_MODEL agents).
+     */
+    list(agent?: string): ProviderWait[];
+    /** Record a provider's stated wait for (agent, model). */
+    set(agent: string, model: string, retryAfterMs: unknown, reason: string): ProviderWaitChange;
+    /**
+     * Release (agent, model)'s wait, or every wait of the agent when `model` is
+     * omitted; recorded. While the recorded waits cannot be read, it also lifts
+     * the hold that stands for them, exactly as far as the release names (that
+     * model, or every model), in this process only. Each lifted wait says how
+     * far its release reaches (ProviderWaitRelease). A release that finds
+     * nothing binding lifts and records nothing, and lists nothing. That
+     * includes a replay of an earlier release. It still offers this process's
+     * unrecorded acts to the journal again.
+     */
+    release(agent: string, model: string | undefined, by: string): ProviderWaitRelease[];
+    private waived;
+    private unreadableWait;
+    /** Make an act bind in this process, ahead of its record. */
+    private apply;
+    /** Rebuild what binds from the journal's reduction and this process's pending acts, in order. */
+    private rebuildView;
+    /**
+     * Read the journal into `durable`. A failure leaves the history unreadable
+     * (fail closed, reported once), never empty. So does a record that parses
+     * but cannot be read as provider waits: a checkpoint also stands for every
+     * entry before it, so a malformed one read as empty would drop them all.
+     */
+    private load;
+    /** Reconcile an ambiguous write before deciding anything against the journal. */
+    private reconcile;
+    /** Offer unrecorded acts and unreadable history again, at most every so often, absent other acts. */
+    private retry;
+    /**
+     * Record pending acts in order, each durable before the next: a lost wait
+     * would admit an early call after a crash. The first that fails stays
+     * pending with every act after it (they still bind in this process) and is
+     * reported; an ambiguous one is reconciled before the next attempt, so an
+     * act may be recorded twice, which reduces the same. An append or
+     * checkpoint that throws inside the store leaves the journal unwritable
+     * until the store is reopened (RecordJournal.needsReopen), so nothing is
+     * written after it: that is said once, where it happens, and the acts stay
+     * pending, binding in this process. A checkpoint records the
+     * journal's own reduction, never this process's unrecorded acts, and never
+     * while the history is unreadable (it would cover entries that were never
+     * reduced).
+     */
+    private flush;
+    /**
+     * Say that the journal can't be written again: the store's append threw
+     * inside the store, and only a reopen (as at the next start) reads its log
+     * back. Called where that first happens; flush() writes nothing after it,
+     * so it is said once for the journal's life. What `writing` names may still
+     * be in the store's log, and the next start loads it if so. A stated wait
+     * still holds here, which is always safe; a later act loses only its
+     * record, so after a restart the agent's next call goes to the provider,
+     * and a wait it states again starts a new hold. No alert: a failed write
+     * is log-only.
+     */
+    private reportUnwritable;
+}
+//# sourceMappingURL=provider-waits.d.ts.map

package/dist/src/provider-waits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-waits.d.ts","sourceRoot":"","sources":["../../src/provider-waits.ts"],"names":[],"mappings":"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"}