@stratusagent/gateway 0.14.1 → 0.14.3

package/dist/memory-passes.d.ts

@@ -0,0 +1,137 @@
+import { type AgentMemoryStore, type MemoryAuditEntry, type MemoryEntry, type MemoryPassHandle, type Message, type Session, type StratusEvent, type Tool, type TrustLevel } from '@stratusagent/core';
+import { type MemoryPassSlice, type MemoryPassSummary, type MemoryShadowEntry } from '@stratusagent/state';
+/** What the host hands a pass's one model run. */
+export interface MemoryPassModelRun {
+    agentId: string;
+    passId: string;
+    /** The pass's own session, never stored: `memoryPassSessionId(passId)`. */
+    sessionId: string;
+    /** Exactly this model, with no fallback. */
+    model: string | undefined;
+    /** The one message: the request, the conversation, the instruction. */
+    prompt: string;
+    /** The label the pass session starts at: the slice's. */
+    trust: TrustLevel;
+    /** Only these: the pass's recall and remember. */
+    tools: Tool[];
+    signal: AbortSignal;
+}
+/** What the memory pass host needs from the gateway. */
+export interface MemoryPassHostOptions {
+    stateDir: string;
+    /** The home, so the ledger and shadow files are owner-only. */
+    stateHome?: string;
+    /** This daemon run's id, written on every ledger record. */
+    run: string;
+    memory: AgentMemoryStore | undefined;
+    /**
+     * Whether the selected store takes a list in `supersedes`, so a pass may
+     * merge several facts into one. Asked per pass: the store is chosen once
+     * the plugins have loaded. Default: no.
+     */
+    supersedesMany?: () => boolean;
+    sessions: {
+        get(id: string): Promise<Session | undefined>;
+    };
+    /**
+     * The session's single-flight chain: whether it is idle now, and a way
+     * to queue one step on it. The idle check and the queueing happen in
+     * the same tick, so nothing gets between them.
+     */
+    chain: {
+        idle(sessionId: string): boolean;
+        queue<T>(sessionId: string, work: () => Promise<T>): Promise<T>;
+    };
+    hasAgent(agentId: string): boolean;
+    isSubAgentSession(session: Session): boolean;
+    /** The model the agent runs on, for a request that names none. */
+    defaultModel(agentId: string): Promise<string | undefined>;
+    /** Runs the pass's model turn; rejects when it fails. */
+    runModel(run: MemoryPassModelRun): Promise<void>;
+    emit(event: StratusEvent): void;
+    log(line: string): void;
+    now?: () => Date;
+    passId?: () => string;
+}
+/** One pass and the facts it wrote, or in shadow would have, oldest first. */
+export interface MemoryPassDetail {
+    pass: MemoryPassSummary;
+    /** Write mode: from the agent's memory, forgotten ones included. Shadow: from `memory-shadow.jsonl`. */
+    entries: Array<MemoryAuditEntry | MemoryShadowEntry>;
+}
+export interface MemoryPassHost {
+    handle: MemoryPassHandle;
+    /** The agent's passes from its ledger, newest first. No ledger reads as none. */
+    passes(agentId: string): Promise<MemoryPassSummary[]>;
+    /** One pass and what it wrote; undefined when the ledger has no claim for it. */
+    pass(agentId: string, passId: string): Promise<MemoryPassDetail | undefined>;
+    /**
+     * The daemon has loaded its agents and chosen its memory store. Plugins
+     * are set up before either, and the spec has the upkeep plugin call
+     * `start` from its setup, so until this a start takes any well-formed
+     * agent id, writes its start record, and leaves the claims a crash left
+     * open to be settled here: settling reads what a claim wrote, from the
+     * store this daemon uses, which is not chosen until now. A save pass asked
+     * for before this is skipped as `not-started`. Resolves once those
+     * settles are written; never rejects.
+     */
+    ready(): Promise<void>;
+    /**
+     * The daemon is stopping: refuse new passes, abort running ones (they are
+     * low priority and do not hold the drain), settle them, then write a stop
+     * record for every agent and mode started in this run.
+     */
+    close(): Promise<void>;
+}
+export interface SaveSlice {
+    /** The rendered entries, oldest first. */
+    entries: string[];
+    slice: MemoryPassSlice;
+    /** Counted messages wait past this slice. */
+    more: boolean;
+}
+/**
+ * The messages a save pass reads next (spec 962): after the watermark,
+ * written while upkeep was on, oldest first, up to about
+ * `MEMORY_PASS_SLICE_MAX_BYTES`. A message alone over the cap goes in a
+ * slice of its own, cut to fit, and the slice says how much was left out,
+ * so the watermark always moves. Undefined when nothing is new.
+ */
+export declare const takeSaveSlice: (messages: readonly Message[], watermark: string | undefined, counts: (createdAt: string) => boolean, maxBytes?: number) => SaveSlice | undefined;
+/** The save pass's one message: the request, the conversation in tags, the instruction after it. */
+export declare const saveSlicePrompt: (entries: readonly string[]) => string;
+export interface TidyChunk {
+    /** `kind/label/about`, the about key folded: what the ledger names the group by. */
+    key: string;
+    /** The group's label: the pass starts at it, recalls only it, and writes it. */
+    trust: TrustLevel;
+    /** The facts handed over, oldest first. */
+    members: MemoryEntry[];
+    /** One JSON object a line, for the `<facts>` tags. */
+    lines: string[];
+    /** SHA-256 of the sorted member ids: what a later pass of the mode skips. */
+    hash: string;
+    /** Another chunk, of this group or another, waits after this one. */
+    more: boolean;
+}
+/**
+ * The chunk a tidy pass is handed next (spec 962). A group is at least
+ * `MEMORY_TIDY_GROUP_MIN` live facts sharing an about key, a kind and a
+ * label, leaving out episodic facts (#961 retires those), pinned ones and
+ * operator-asserted ones (no pass may supersede either). A fact with two
+ * about keys counts in both groups. The largest group goes first; a group
+ * over `MEMORY_TIDY_CHUNK_MAX_BYTES` goes in chunks, oldest facts first.
+ * A chunk whose member ids a pass of this mode already looked at
+ * (`claimed`) is passed over for the next, so a chunk that merges nothing
+ * still moves the tidy on, while a merge changes the members and so the
+ * chunks. Undefined when no chunk is left.
+ */
+export declare const takeTidyChunk: (live: readonly MemoryEntry[], pinned: ReadonlySet<string>, claimed: ReadonlySet<string>, maxBytes?: number) => TidyChunk | undefined;
+/** The tidy pass's one message: the request, the facts in tags, the instruction after them. */
+export declare const tidyChunkPrompt: (lines: readonly string[]) => string;
+/**
+ * The gateway's `PluginContext.memoryPasses` (spec 962). A plugin decides
+ * when to ask; everything a pass may read and write is decided here.
+ */
+export declare const createMemoryPassHost: (options: MemoryPassHostOptions) => MemoryPassHost;
+//# sourceMappingURL=memory-passes.d.ts.map

package/dist/memory-passes.d.ts.map

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