sealkeep 0.8.1 → 0.11.0

package/dist/src/agent-context.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Automatic agent context — the zero-command path.
+ *
+ * Lifecycle hooks call this module at startup, after a user prompt, and after
+ * meaningful tools. Personal memory is loaded for the current git project on
+ * every machine. A project explicitly set to active also publishes one-line
+ * progress and receives teammates' new one-line events while the session is
+ * still running.
+ *
+ * Hook output is context, never authority: restored text is labelled as
+ * historical/untrusted data so an instruction captured in an old transcript
+ * cannot silently become a new instruction.
+ */
+import { type AgentId } from "./adapters.js";
+import { type PresenceEvent } from "./presence.js";
+import { type ProjectMemory } from "./search.js";
+export type AgentHookPayload = {
+    hook_event_name?: string;
+    session_id?: string;
+    thread_id?: string;
+    cwd?: string;
+    prompt?: string;
+    transcript_path?: string;
+    rollout_path?: string;
+    tool_name?: string;
+};
+export type AutomaticContextOutcome = {
+    project: string;
+    /** Collision-safe identity used for every lookup; project is display-only. */
+    projectKey: string | null;
+    sharing: "active" | "passive";
+    additionalContext: string;
+    published?: PresenceEvent;
+    teammateUpdates: PresenceEvent[];
+    memories: ProjectMemory[];
+};
+/** Internal scheduling controls for the daemon-owned context worker. Omitted
+ * by CLI/MCP callers, so a manual foreground search remains unrestricted. */
+export type AutomaticContextWorkOptions = {
+    now?: number;
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onYield?: () => void | Promise<void>;
+    /** Useful remote byte progress, used to refresh the owned child's stall deadline. */
+    onProgress?: (bytes: number) => void;
+    /** Test-only clock policy injection; production uses the reviewed constant. */
+    contextMinIntervalMs?: number;
+};
+export type ContextRequestDrain = {
+    processed: number;
+    failed: number;
+    discarded: number;
+    pending: number;
+};
+export declare function parseAgentHookPayload(raw: string): AgentHookPayload;
+/**
+ * Persist one expensive recall request and return to the hook protocol. The
+ * filename is a fixed session/event slot, so a burst of tool hooks replaces
+ * stale work instead of creating an unbounded queue. The prompt stays sealed
+ * at rest; only the long-running daemon opens it.
+ */
+export declare function enqueueAutomaticAgentContextRequest(dataDir: string, phrase: string, agent: AgentId, payload: AgentHookPayload, options?: {
+    now?: number;
+}): Promise<boolean>;
+/**
+ * Return every request claimed by one terminated context child to its durable
+ * coalesced slot. The request body stays encrypted, and an event that arrived
+ * while the child was running wins over the older claim.
+ */
+export declare function recoverAutomaticAgentContextClaims(dataDir: string, pid: number, options?: {
+    retryAt?: number;
+}): Promise<number>;
+export type HookUnlockFailure = {
+    version: 1;
+    at: string;
+    agent: AgentId;
+    backend: string | null;
+};
+export declare function recordHookUnlockFailure(dataDir: string, agent: AgentId): Promise<void>;
+export declare function clearHookUnlockFailure(dataDir: string): Promise<void>;
+export declare function readHookUnlockFailure(dataDir: string): Promise<HookUnlockFailure | null>;
+/**
+ * A session that has ended will never read recall prepared for it. Its
+ * SessionEnd hook drops every coalesced slot, prepared answer, lifecycle state
+ * and lock under its id, so the daemon's next passes go to the sessions still
+ * typing rather than to a queue of sessions that are gone. A payload with no
+ * session identity is left alone: the cwd fallback would name someone else's slots.
+ */
+export declare function discardAutomaticAgentContext(dataDir: string, payload: AgentHookPayload): Promise<number>;
+/** A metadata-only gate so an idle daemon does not fork a child every second. */
+export declare function hasDueAutomaticAgentContextRequest(dataDir: string, queueNow?: number): Promise<boolean>;
+/**
+ * Consume a bounded pending-context batch. Failures keep their exact request
+ * for the next daemon pass; successful work removes it only if a newer hook
+ * did not replace the coalesced slot while preparation was running.
+ */
+export declare function drainAutomaticAgentContextRequests(dataDir: string, phrase: string, options?: {
+    limit?: number;
+    now?: number;
+    /** Queue clock is separate from the lifecycle timestamp used in tests. */
+    queueNow?: number;
+    retryDelayMs?: number;
+    prepare?: typeof prepareAutomaticAgentContext;
+    scheduling?: Omit<AutomaticContextWorkOptions, "now">;
+}): Promise<ContextRequestDrain>;
+/**
+ * Up to three distinctive terms from a prompt, best first. A long identifier or
+ * domain word is usually the thing the person expects memory to recover; ties
+ * favour the later word, where prompts put subjects. Names in `exclude` — the
+ * project and the working folder — never qualify: "linkboard" is in every
+ * session of the linkboard project and discriminates nothing, yet as the
+ * longest word it used to win outright and bury the actual subject.
+ */
+export declare function recallQueries(prompt: string | undefined, exclude?: readonly (string | null | undefined)[]): string[];
+export declare function recallQuery(prompt: string | undefined): string | null;
+/**
+ * Produces context for one lifecycle event and performs the active-team side
+ * effects. Ordinary memory/store failures degrade to an empty answer. Owned
+ * worker cancellation and resource ceilings propagate so the durable request
+ * can be restored and retried; the interactive hook never waits for this work.
+ */
+export declare function automaticAgentContext(dataDir: string, phrase: string, agent: AgentId, payload: AgentHookPayload, options?: AutomaticContextWorkOptions): Promise<AutomaticContextOutcome | null>;
+/**
+ * Runs the complete recall/team workflow away from the agent's critical path
+ * and seals its answer for the next boundary. The cache is encrypted with the
+ * same recovery phrase as the vault; readable recalled text is never left in a
+ * new plaintext sidecar merely to make hooks faster.
+ */
+export declare function prepareAutomaticAgentContext(dataDir: string, phrase: string, agent: AgentId, payload: AgentHookPayload, options?: AutomaticContextWorkOptions): Promise<AutomaticContextOutcome | null>;
+/**
+ * The user-facing hook path: one local key lookup, one atomic claim, one small
+ * authenticated decrypt, and no network/search/provider work. Prepared context
+ * is consumed exactly once so old teammate lines are not repeated forever.
+ */
+export declare function consumePreparedAgentContext(dataDir: string, phrase: string, payload: AgentHookPayload): Promise<AutomaticContextOutcome | null>;