@theokit/agents 9.4.0 → 10.1.0

package/dist/session.d.ts

@@ -1,5 +1,36 @@
 import { TheokitAgentError } from '@theokit/sdk/errors';
 
+/**
+ * Bounding an injected registry remover, in one place.
+ *
+ * ## Why this file exists, written after it was needed
+ *
+ * `deleteSession` and `runTranscriptGC` both take a `removeFromRegistry` and both must await it —
+ * the only agent registry in the ecosystem is `Agent.delete(id): Promise<void>`. The plan named this
+ * file (*"session/gc/registry-remover.ts (NEW) — the shared awaiting helper"*) and the first
+ * implementation skipped it, putting the bound inside `deleteSession` and leaving the sweep with a
+ * bare `await`.
+ *
+ * The divergence was not theoretical. A remover that never settled hung `runTranscriptGC`
+ * indefinitely — not one session, every session after it, with no error, no timeout and no output.
+ * The single-session path was already tested against exactly that; the sweep, which is the path that
+ * runs unattended over a whole project, was not. That is `system-design-guardrails.md` § G12 in its
+ * most expensive form: one rule, two call sites, and the one nobody was watching was the one that
+ * mattered.
+ */
+
+/**
+ * The registry did not answer in time.
+ *
+ * T2.2 — this used to mean "you passed a Promise to a synchronous seam". The seam now awaits, so the
+ * only thing left that a caller cannot fix by awaiting is a registry that does not respond.
+ */
+declare class SessionRegistryRemoverError extends TheokitAgentError {
+    readonly name = "SessionRegistryRemoverError";
+    readonly sessionId: string;
+    constructor(sessionId: string, timeoutMs: number);
+}
+
 /**
  * M71 — the session LIFECYCLE vocabulary: list, delete, protect, fork.
  *
@@ -29,19 +60,32 @@ import { TheokitAgentError } from '@theokit/sdk/errors';
  * The seam is synchronous by contract because `deleteSession` is. A caller whose registry is async
  * (which, measured, is every real one) awaits its own removal and then calls this with the outcome.
  */
-declare class SessionRegistryRemoverError extends TheokitAgentError {
-    readonly name = "SessionRegistryRemoverError";
-    readonly sessionId: string;
-    constructor(sessionId: string);
-}
 declare class SessionInUseError extends TheokitAgentError {
     readonly sessionId: string;
     /** Why it is protected — a writer lease, the resumable pointer, or being the most recent. */
     readonly reason: string;
+    /**
+     * Whether the registry half already happened before the refusal.
+     *
+     * `true` only when the session became protected DURING the registry removal — the re-check
+     * fires after the await, so the entry is already gone while the transcript stays. The caller
+     * needs this: retrying a removal that is already done returns `false` ("no entry to remove"),
+     * which reads as a failure and is not one.
+     */
+    readonly registryRemoved: boolean;
     readonly name = "SessionInUseError";
     constructor(sessionId: string, 
     /** Why it is protected — a writer lease, the resumable pointer, or being the most recent. */
-    reason: string);
+    reason: string, 
+    /**
+     * Whether the registry half already happened before the refusal.
+     *
+     * `true` only when the session became protected DURING the registry removal — the re-check
+     * fires after the await, so the entry is already gone while the transcript stays. The caller
+     * needs this: retrying a removal that is already done returns `false` ("no entry to remove"),
+     * which reads as a failure and is not one.
+     */
+    registryRemoved?: boolean);
 }
 /** One session as the lifecycle vocabulary sees it. */
 interface SessionSummary {
@@ -74,14 +118,34 @@ interface DeleteSessionResult {
     readonly registryRemoved: boolean;
     /** Whether the transcript file was removed. */
     readonly transcriptRemoved: boolean;
+    /**
+     * Why the registry removal failed, when it did.
+     *
+     * Kept SEPARATE from `registryRemoved` on purpose: collapsing the two outcomes into one boolean is
+     * exactly how the original silent success hid. A caller that only checks `registryRemoved` sees
+     * `false` and can still surface the reason.
+     */
+    readonly registryError?: unknown;
 }
 interface DeleteSessionOptions {
     readonly cwd: string;
     readonly root?: string;
     /** Delete even when protected. The refusal is the default because the damage is unrecoverable. */
     readonly force?: boolean;
-    /** Remove the registry entry too. Injected (DIP) — the registry is the runtime's, not ours. */
-    readonly removeFromRegistry?: (sessionId: string) => boolean;
+    /**
+     * Remove the registry entry too. Injected (DIP) — the registry is the runtime's, not ours.
+     *
+     * T2.2 — MAY be async. `Agent.delete(id): Promise<void>` is the only agent registry in this
+     * ecosystem, so a sync-only seam could be satisfied honestly by nobody. Returning `false` means
+     * "no entry to remove" and is not a failure; THROWING (or rejecting) is, and it stops the delete
+     * with the transcript still on disk.
+     */
+    readonly removeFromRegistry?: (sessionId: string) => unknown;
+    /**
+     * Ceiling on the injected remover. A registry that never answers must not hang a sweep; the
+     * timeout surfaces as `registryError` and the transcript is left alone.
+     */
+    readonly registryTimeoutMs?: number;
 }
 /**
  * Delete a session, refusing by default when it is protected.
@@ -92,7 +156,7 @@ interface DeleteSessionOptions {
  *
  * @throws {SessionInUseError} when the session is protected and `force` is not set.
  */
-declare function deleteSession(sessionId: string, options: DeleteSessionOptions): DeleteSessionResult;
+declare function deleteSession(sessionId: string, options: DeleteSessionOptions): Promise<DeleteSessionResult>;
 /**
  * Fork `srcId` into `newId`, keeping everything BEFORE the `nth` user turn.
  *
@@ -108,6 +172,7 @@ declare function forkBeforeUserTurn(srcId: string, newId: string, nth: number, o
 }): {
     readonly transcript: string;
     readonly recordIndex: number;
+    readonly selectedText: string;
 };
 
 /** Where the pointer for `cwd` lives. */
@@ -281,6 +346,178 @@ declare function runTranscriptGC(plan: TranscriptGCPlan, options: {
     readonly apply: boolean;
     /** Same additive, fail-closed contract as on the plan — see `TranscriptGCOptions.protectedIds`. */
     readonly protectedIds?: () => ReadonlyMap<string, string>;
-}): RunTranscriptGCResult;
+    /**
+     * T2.2 — remove the registry entry as well as the transcript file.
+     *
+     * Without it this function deleted transcripts and left the agent registry pointing at files
+     * that no longer exist. Nothing repaired that: GC works FROM transcripts, so an entry whose
+     * transcript is gone is never seen again. `deleteSession` has had this seam; the sweep did not.
+     *
+     * Same contract as `deleteSession`: may be async (`Agent.delete` is the only registry there is),
+     * runs BEFORE the unlink, and a throw leaves the transcript on disk for the next sweep rather
+     * than producing an entry no run can repair.
+     */
+    readonly removeFromRegistry?: (sessionId: string) => unknown;
+    /**
+     * How long to wait for the registry per session before giving up on it and keeping the
+     * transcript. Absent means wait indefinitely — the pre-existing behaviour, kept as the default
+     * so adding the bound cannot change what a current caller experiences.
+     */
+    readonly registryTimeoutMs?: number;
+}): Promise<RunTranscriptGCResult>;
+
+/**
+ * A sentence explaining an empty session list, or `undefined` when there is nothing true to say.
+ *
+ * Returns `undefined` in every case where the hint would be noise or a guess: sessions were found,
+ * the root was not overridden, the override equals the previous root, the previous root cannot be
+ * read, or it holds no projects. A hint that fires spuriously is worse than none — people stop
+ * reading the ones that matter.
+ *
+ * @param found - how many sessions the caller's own listing returned.
+ * @param previousRoot - the root to look in, typically the default before the override.
+ * @param env - injected so a test needs no global mutation; defaults to the real environment.
+ */
+declare function transcriptRootHint(found: number, previousRoot: string, env?: NodeJS.ProcessEnv): string | undefined;
+
+/**
+ * Does the project behind `projects/<encoded>/` still exist?
+ *
+ * The question is hard because of a decision this package's layout made:
+ * `encodeProjectDir(cwd)` is `cwd.replace(/[^a-zA-Z0-9]/g, '-')`, a one-way street. `/a/b` and
+ * `/a-b` produce the same name, so a directory name cannot be turned back into a path — it can only
+ * be CHECKED against candidates. Every product that retains or garbage-collects transcripts has to
+ * answer this, and until now each one wrote the search itself: the consumer's 188 lines, whose own
+ * docstring measured 13.269 project directories, ~3.200 falling through to filesystem search, and
+ * ~64M syscalls without a shared budget.
+ *
+ * ## What is injected, and why exactly that
+ *
+ * `candidatePaths` — which directories are even candidates is PRODUCT policy (workspaces, ignore
+ * rules, mounted volumes). This module must not guess it. It returns REAL ABSOLUTE PATHS, and the
+ * name says so because the previous one (`listProjects`) did not: the only consumer's function of
+ * that name returns ENCODED DIRECTORY NAMES, and wiring one to the other classified 6 of 6 live
+ * projects `dead`.
+ *
+ * `fs` — so the budget is countable and the caller can supply a stat that matches its own retry and
+ * timeout posture. Every call is one operation.
+ *
+ * What is NOT injected is the encoding, because that is the thing this package owns and the whole
+ * reason the question exists.
+ *
+ * ## Two properties do the work
+ *
+ * **The result is three-valued and `undetermined` is not a soft `dead`.** Callers DELETE on `dead`.
+ * Every way of failing to find out — budget spent, unreadable directory, enumeration threw —
+ * resolves to `undetermined`, because deleting on "could not tell" is data loss and the fail-safe
+ * direction is not symmetric here (`rules/error-handling.md`).
+ *
+ * **The budget is shared across the whole sweep, not per project.** A bound that resets each
+ * iteration is not a bound; that is precisely what produced the 64M figure.
+ */
+
+/**
+ * The filesystem, as this module needs it. Every call is ONE operation against the budget, and any
+ * of them may throw (EACCES) — a throw is a third outcome, never "absent".
+ */
+interface FsSeam {
+    /**
+     * Does `path` exist? **Three-valued**: `undefined` means "could not determine", and it is NOT the
+     * same answer as `false`.
+     *
+     * The third state is in the RETURN TYPE rather than in prose because that is the only place an
+     * adapter author reliably reads it. The consumer's scar (B-020) is exactly this: its adapter
+     * mapped every `statSync` failure to `false`, and since the verdict branches on that value, a cwd
+     * that exists but cannot be stat-ed — EACCES on a non-traversable parent, ENOTDIR mid-path, EMFILE
+     * under a wide sweep — was classified DEAD, which is a deletion. A signature of `=> boolean`
+     * invites `try { return existsSync(p) } catch { return false }`, which reintroduces it silently.
+     *
+     * ENOENT is the only errno that means absence. Everything else is `undefined`. Throwing is also
+     * accepted and treated as `undefined`, so an adapter that does neither still cannot cause a
+     * deletion.
+     */
+    exists: (path: string) => boolean | undefined;
+    /** Entry names directly under `dir`. Used to find a transcript to read the recorded cwd from. */
+    listEntries: (dir: string) => readonly string[];
+    /** The first line of `file`. The transcript's first record carries the `cwd` it was written in. */
+    firstLine: (file: string) => string;
+}
+type Liveness = 'alive' | 'dead' | 'undetermined';
+interface LivenessVerdict {
+    readonly liveness: Liveness;
+    /** Why — carried on every verdict, so an operator reading a GC log is never left guessing. */
+    readonly reason: string;
+    /**
+     * The cwd this verdict is ABOUT — present on `alive` and `dead`, absent on `undetermined`.
+     *
+     * `alive` reports the member of the collision class that was found to EXIST, not the first one
+     * read: the class can hold a gone path and a live one, and sending a caller's registry lookup to
+     * the gone sibling would defeat the point. `dead` reports the recorded cwd that was checked and
+     * found missing. `undetermined` established no path, so the field is absent rather than an empty
+     * string a caller might mistake for one.
+     *
+     * Added because the verdict was dropping the one fact a caller acts on. This function PROBES the
+     * path to decide `alive` — it has it in hand at the moment it returns — and kept only a prose
+     * `reason`. The consumer this was absorbed from uses the resolved cwd to consult the agent
+     * registry and the resumable pointer for that project (`all-sessions.ts:161,175`), so a verdict
+     * without it could not replace the function it exists to replace. Recovering it by string-matching
+     * `reason` would be the fragile coupling this module exists to remove: a sentence is not an API.
+     */
+    readonly cwd?: string;
+}
+interface ClassifyProjectsOptions {
+    /**
+     * Where `projects/<encoded>/` lives, so the recorded-cwd read can find a transcript.
+     * Use {@link projectsRoot} rather than joining the segment by hand — that segment had three
+     * owners once, and a wrong one makes every project look empty rather than erroring.
+     */
+    projectsRoot: string;
+    /**
+     * REAL ABSOLUTE PATHS that might be the project — not encoded directory names.
+     *
+     * The name is explicit because the previous one was not, and the ambiguity was a defect rather
+     * than a documentation gap: the only consumer's `listProjects` returns ENCODED NAMES (it keeps
+     * classification in a separate injected seam), so wiring the two together fed encoded names to a
+     * function expecting paths. Measured 2026-08-16: 6 of 6 live projects classified `dead`, on the
+     * path where the caller DELETES.
+     *
+     * PRODUCT policy: which directories are even candidates (workspaces, ignore rules, mounted
+     * volumes) is not this module's to guess. It is also only a HEURISTIC — see the fall-through in
+     * `searchPool`, which is why exhausting it can never prove absence.
+     */
+    candidatePaths: () => readonly string[];
+    /** Total filesystem operations allowed for the ENTIRE sweep. */
+    budget: number;
+    fs: FsSeam;
+    /** How many transcripts to read per project before giving up on the recorded cwd. Default 3. */
+    transcriptSamples?: number;
+}
+/**
+ * REMOVED 2026-08-16 — `likelyPath`, which turned every `-` back into `/` and was documented as
+ * "correct for the overwhelming majority of real paths". It is correct for no path containing a
+ * hyphen, which is most of them:
+ *
+ *     encode('/home/op/Projetos/theo/theokit-framework')
+ *       → '-home-op-Projetos-theo-theokit-framework'
+ *     likelyPath(that)
+ *       → '/home/op/Projetos/theo/theokit/framework'   ← not the input
+ *
+ * The encoding is lossy on purpose (`/a/b` and `/a-b` collide), so no string transform can invert
+ * it. What replaces it is not a better guess but the actual answer: the transcript records the cwd
+ * it was written in, and reading it costs one line of one file.
+ */
+/**
+ * Raised when `budget` cannot bound anything. Refusing beats clamping, for the same reason
+ * `transcript-gc.ts` states as its invariant 1: an operator who asked for a policy must not be
+ * silently given a different one.
+ */
+declare class LivenessBudgetError extends TheokitAgentError {
+    constructor(budget: number);
+}
+/**
+ * Classify each encoded project directory. Every input appears in the output: a missing key would
+ * read to a caller as "not dead", which is safe only by accident.
+ */
+declare function classifyProjects(encoded: readonly string[], opts: ClassifyProjectsOptions): Map<string, LivenessVerdict>;
 
-export { type DeleteSessionOptions, type DeleteSessionResult, type GCCandidate, type GCError, GCFloorError, type GCKept, GCProtectionUnavailableError, type RunTranscriptGCResult, SessionInUseError, SessionRegistryRemoverError, type SessionSummary, type TranscriptGCOptions, type TranscriptGCPlan, deleteSession, forkBeforeUserTurn, listSessions, loadOrCreateSessionId, persistSessionId, planTranscriptGC, projectDirFor, projectDirMatches, projectsRoot, protectedTranscripts, recordProjectDir, resolveProjectDir, runTranscriptGC, sessionPointerPath };
+export { type ClassifyProjectsOptions, type DeleteSessionOptions, type DeleteSessionResult, type FsSeam, type GCCandidate, type GCError, GCFloorError, type GCKept, GCProtectionUnavailableError, type Liveness, LivenessBudgetError, type LivenessVerdict, type RunTranscriptGCResult, SessionInUseError, SessionRegistryRemoverError, type SessionSummary, type TranscriptGCOptions, type TranscriptGCPlan, classifyProjects, deleteSession, forkBeforeUserTurn, listSessions, loadOrCreateSessionId, persistSessionId, planTranscriptGC, projectDirFor, projectDirMatches, projectsRoot, protectedTranscripts, recordProjectDir, resolveProjectDir, runTranscriptGC, sessionPointerPath, transcriptRootHint };