@animalabs/agent-framework 0.29.0 → 0.31.0

package/dist/src/dendrite/registry.d.ts

@@ -0,0 +1,260 @@
+/**
+ * AgentRegistry — the one place that knows which agents exist, what they
+ * are for, how they relate and what ends them.
+ *
+ * Pure bookkeeping: it never touches a stream, a context manager or a
+ * channel. Lifecycle methods return what changed (who ended, who was
+ * orphaned, which mail became deliverable) and the framework performs the
+ * side effects. That split keeps every rule here testable without a store
+ * and keeps the framework from re-deriving policy at each call site.
+ */
+import type { AgentEndReason, AgentName, AgentRecord, AgentRef, AgentSpec, EndOutcome, HeldMail, RegistrySnapshot } from './types.js';
+/** Thrown for a spec the registry refuses to load. */
+export declare class AgentSpecError extends Error {
+    constructor(agent: string, problem: string);
+}
+export interface AgentRegistryOptions {
+    now?: () => number;
+    /** Called after every durable mutation with the state to persist. */
+    persist?: (snapshot: RegistrySnapshot) => void;
+    /**
+     * Called once per ended record. Ended records are append-only history,
+     * kept out of the snapshot so a mutation never rewrites them.
+     */
+    appendEnded?: (record: AgentRecord) => void;
+    /** How many ended records stay inspectable in memory (oldest dropped first). */
+    endedRetention?: number;
+    /**
+     * Told when a write that records something that has already happened — a
+     * release, a held mark, a message path — fails. The change stays in memory
+     * and the next write carries it; the call that made it is not failed, since
+     * what it records is done (nissa's #546 review, round 2). Absent, the
+     * failure is logged.
+     */
+    onRecordWriteFailed?: (what: string, error: unknown) => void;
+    /** Told after a change that failed was put back in memory (a requested change, or a hold): the host rewrites what it wrote alongside to match. */
+    onRollback?: () => void;
+    /**
+     * Asked for an ended record no longer in memory (past `endedRetention`):
+     * the host reads its durable ended log, so an agent that ended long ago
+     * can still be inspected, resumed and named.
+     */
+    findEnded?: (name: AgentName) => AgentRecord | undefined;
+}
+/** What a restore found that the previous process left unfinished. */
+export interface RestoreOutcome {
+    /** Non-persistent agents that were live when the previous process stopped. */
+    interrupted: AgentRecord[];
+}
+/** What boot reconciliation concluded once configuration was applied. */
+export interface ReconcileOutcome {
+    /** Persistent agents the previous process ran that this configuration no longer declares. */
+    unconfigured: EndOutcome[];
+}
+export declare class AgentRegistry {
+    private readonly live;
+    /** Ended records, oldest first. */
+    private ended;
+    /** Persistent records from the previous process, not yet re-declared. */
+    private readonly awaiting;
+    /**
+     * Bounded work the previous process left live, ended by this restart in
+     * memory but kept in the snapshot as it was until the host has told each
+     * recipient (settleInterrupted), so a crash before then owes the same
+     * notices at the next boot rather than none.
+     */
+    private readonly interruptedPending;
+    private readonly incarnations;
+    private mail;
+    private readonly now;
+    private readonly persistFn?;
+    private readonly appendEndedFn?;
+    private readonly endedRetention;
+    private readonly onRecordWriteFailed;
+    private readonly onRollback?;
+    private readonly findEnded?;
+    /** Above zero while a record of what happened is being written: its writes alert rather than throw. */
+    private recordingDepth;
+    constructor(options?: AgentRegistryOptions);
+    /**
+     * Admit an agent. Refuses a spec that breaks a registry invariant — an
+     * unbounded task, a second default-delivery owner, a relationship that
+     * names nobody — so a malformed agent fails at load, not mid-run.
+     *
+     * `resume` admits a new incarnation of an identity that ended: where its
+     * context came from is then history, so the context source no longer has
+     * to be live. Who it reports to still does. A spawner that has ended, and
+     * a result route to it, are admitted: the agent registers as that
+     * spawner's orphan, as if it had been live when the spawner ended.
+     * `after` is the incarnation a resumption continues from: the new one is
+     * past it, since the counter of a name that aged out of memory isn't kept.
+     */
+    register(spec: AgentSpec, options?: {
+        resume?: boolean;
+        after?: number;
+    }): AgentRecord;
+    private registerUnguarded;
+    private validate;
+    /** A live agent's record. */
+    get(name: AgentName): AgentRecord | undefined;
+    has(name: AgentName): boolean;
+    /** The live record, else the most recent ended one with that name, from memory or the host's ended log. */
+    inspect(name: AgentName): AgentRecord | undefined;
+    /** Flat list of agents — the discovery surface. Ended ones on request. */
+    list(options?: {
+        includeEnded?: boolean;
+    }): AgentRecord[];
+    /**
+     * An agent other than `except` whose own context a namespace holds, among
+     * the records in memory: live, awaiting re-declaration, or ended. A shared
+     * fork's record names its parent's namespace, where it owns only a branch,
+     * so it holds none.
+     * @internal For the framework's namespace check in
+     * `createEphemeralAgent()`; not a host API.
+     */
+    namespaceHolder(namespace: string, except: AgentName): AgentName | undefined;
+    /** Provenance stamp for a live agent (or its last incarnation). */
+    ref(name: AgentName): AgentRef;
+    /** The agent that owns default delivery, if any. */
+    primary(): AgentName | null;
+    /** Recipients of untargeted inbound, in registration order. */
+    untargetedRecipients(): AgentName[];
+    /** Recipients of host-wide gate fan-out, in registration order. */
+    gateRecipients(): AgentName[];
+    ownsProviderScheduling(name: AgentName): boolean;
+    /** Agents reading the residents' shared message slot. */
+    sharedSlotReaders(): AgentName[];
+    readsSharedSlot(name: AgentName): boolean;
+    /** The channel an agent is bound to, if it has one. */
+    homeChannel(name: AgentName): AgentRecord['homeChannel'];
+    /** Live agents of one preset label. Discovery only — see {@link AgentKind}. */
+    ofKind(kind: string): AgentRecord[];
+    private namesWhere;
+    /** Live agents this one spawned. */
+    children(name: AgentName): AgentRecord[];
+    /** Live spawn ancestors, nearest first. */
+    ancestors(name: AgentName): AgentName[];
+    /** Live agents whose completed work returns to `name`. */
+    resultSources(name: AgentName): AgentRecord[];
+    /** Record that `from` used an explicit message path to `to`. */
+    noteMessagePath(from: AgentName, to: AgentName): void;
+    /**
+     * End an agent identity. Attention tenants it spawned end with it; task
+     * work it spawned is orphaned, with reparenting candidates. Result routes
+     * that pointed at it are left in place — delivery holds the mail instead
+     * of dropping it, so a later adoption can still receive the result.
+     */
+    /**
+     * End an agent. A stop a caller asks for is a requested change: a write that
+     * fails puts memory back and fails the call. A run's own end or an idle
+     * reap (`record: true`) records what has already happened: a write that
+     * fails alerts, and the next write carries it (nissa's #546 review, round 3).
+     */
+    end(name: AgentName, reason: AgentEndReason, by?: string, options?: {
+        record?: boolean;
+    }): EndOutcome | null;
+    private endUnguarded;
+    private endRecursive;
+    /** Who could take over an ending agent's children: nearest live ancestor, then the primary. */
+    private adoptionCandidates;
+    /**
+     * Give an agent a new spawner. Clears orphan state. A result route whose
+     * recipient is gone follows the new parent, and mail the agent already
+     * produced for the lost recipient is re-addressed and returned so the
+     * caller can deliver it.
+     */
+    reparent(name: AgentName, newParent: AgentName): {
+        record: AgentRecord;
+        deliverable: HeldMail[];
+    };
+    private reparentUnguarded;
+    /**
+     * An ended agent's held mail finds a new recipient: every item it produced
+     * for a recipient that is gone (a result or a message, as `reparent`
+     * moves for a live agent) is re-addressed to `newParent` and returned for
+     * delivery. Its record stays as it ended, since history isn't reparented.
+     * @internal For the framework's `reparentAgent()` of an ended agent; not a host API.
+     */
+    readdressHeldMail(name: AgentName, newParent: AgentName): {
+        record: AgentRecord;
+        deliverable: HeldMail[];
+    };
+    /** Record a communication durably BEFORE attempting delivery. */
+    holdMail(mail: Omit<HeldMail, 'id' | 'createdAt'> & {
+        id?: string;
+    }): HeldMail;
+    /** Delivery confirmed: forget the held copy. */
+    releaseMail(id: string): void;
+    /** Mark why an item is still held (delivery attempted and not possible yet). */
+    markMailHeld(id: string, because: NonNullable<HeldMail['heldBecause']>): void;
+    listMail(filter?: {
+        to?: AgentName;
+        from?: AgentName;
+    }): HeldMail[];
+    snapshot(): RegistrySnapshot;
+    /**
+     * Load what the previous process persisted. Restart behaviour follows
+     * from lifetime: a persistent agent waits to be re-declared by
+     * configuration (see {@link reconcile}); every other agent that was live
+     * is ended here as interrupted, in memory, and returned so its result
+     * recipient can be told. It stays in the snapshot as it was, and its end
+     * is written, once the host has told the recipients (settleInterrupted).
+     * Held mail is kept for redelivery.
+     *
+     * A bounded record the ended history already holds, by name and
+     * incarnation, ended before the previous process could write the snapshot
+     * without it: it is dropped, not ended again. A persistent record waits to
+     * be re-declared whatever that history says, since the end there may be one
+     * a stop left that failed and was put back (an append can't be taken
+     * back); configuration then declares it again or ends it.
+     *
+     * `endedHistory` is the tail of the ended-record log, oldest first.
+     */
+    restore(snapshot: RegistrySnapshot | null | undefined, endedHistory?: AgentRecord[]): RestoreOutcome;
+    /**
+     * The host has told each interrupted job's recipient (restore's
+     * `interrupted`): their ends are written now, and the snapshot no longer
+     * lists them. Each pending entry carries its own end, as memory keeps only
+     * the newest `endedRetention`. An end whose write fails is reported and
+     * stays pending, so the snapshot still lists it and a later settlement (the
+     * next boot's) writes it; a failed snapshot write is reported too.
+     * @internal For the framework's boot, once the interrupted jobs'
+     * recipients are told; not a host API.
+     */
+    settleInterrupted(): void;
+    /**
+     * Call once configuration has declared its agents. A persistent agent the
+     * previous process ran but this configuration omits is ended, with the
+     * usual consequences for what it spawned.
+     */
+    reconcile(): ReconcileOutcome;
+    private recordEnded;
+    /** Mark a record ended and keep it in memory, without writing the end. */
+    private pushEnded;
+    /** Write an ended record through the host's append hook. */
+    private appendEndedRecord;
+    /**
+     * Run a change a caller asks for — a registration, an end, a reparent, a
+     * hold — so that a write failing on the way puts memory back as it was:
+     * the call fails and changes nothing, and a retry does it once (nissa's
+     * #546 review, round 2: a stop whose write failed left the agent recorded
+     * as stopped while it kept running).
+     */
+    private requested;
+    /** Memory is as it was before a change that failed: the host rewrites its copies to match. The caller hears why
+     *  its change failed, not why the put-back did. */
+    private putBack;
+    /** Run a record of something that has already happened: its writes alert and stay in memory rather than throw. */
+    private recording;
+    /** The ended records in memory, newest last. */
+    endedHistory(): AgentRecord[];
+    /** Persist a record of something that has already happened: a failure
+     *  alerts and leaves the change in memory for the next write to carry. */
+    private persistRecord;
+    /** Write the snapshot through the host's persist hook. A write that fails
+     *  fails the change that made it (nissa's #546 finding 2): the change is in
+     *  memory, and the caller is told it is not durable, rather than told it
+     *  succeeded while a restart would lose it. */
+    private persist;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/dendrite/registry.d.ts.map

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