@wrongstack/core 0.313.0 → 0.316.1

package/dist/session-catalog/protocol.d.ts

@@ -1,5 +1,6 @@
-import type { SessionRegistryEntry } from './session-registry-types.js';
 import type { SessionSummary } from '../types/session.js';
+import type { SessionAgentRecord } from './session-agents.js';
+import type { SessionRegistryEntry } from './session-registry-types.js';
 export declare const SESSION_CATALOG_PROTOCOL_VERSION = 1;
 export declare const SESSION_CATALOG_MAX_FRAME_CHARS: number;
 export declare const SESSION_CATALOG_DEFAULT_LEASE_MS = 30000;
@@ -126,6 +127,25 @@ export interface SessionCatalogOperations {
         };
         result: SessionLeaseCredential;
     };
+    /**
+     * Extend a reservation that is still being worked on.
+     *
+     * A resume reserves ownership BEFORE it can know how long the transcript
+     * takes to open, and the default window is 15s. Hydrating a large journal
+     * (load + summary + file-observation validation + opening the append
+     * handle, all of which can also wait on this daemon) routinely outruns it,
+     * and `activate_reservation` then fails with "reservation expired" after
+     * the expensive work is already done. Renewal keeps the reservation alive
+     * for exactly as long as the caller is demonstrably still hydrating.
+     */
+    renew_reservation: {
+        args: {
+            reservationId: string;
+            requesterInstanceId: string;
+            reservationMs?: number;
+        };
+        result: ResumeReservation;
+    };
     cancel_reservation: {
         args: {
             reservationId: string;
@@ -210,6 +230,17 @@ export interface SessionCatalogOperations {
         };
         result: CatalogSessionRecord | null;
     };
+    /**
+     * Agent roster of one session, derived from its journal. Read-only: there
+     * is no write op, because the rows are a projection of the transcript and
+     * a writer would create a second authority that can disagree with it.
+     */
+    list_session_agents: {
+        args: {
+            sessionId: string;
+        };
+        result: SessionAgentRecord[];
+    };
     rename: {
         args: {
             sessionId: string;

package/dist/session-catalog/registry.d.ts

@@ -1,8 +1,22 @@
-import type { AgentEntry, SessionRegistryEntry } from './session-registry-types.js';
 import type { ResumeReservation, SessionCatalogEvent } from './protocol.js';
+import type { AgentEntry, SessionRegistryEntry } from './session-registry-types.js';
 export interface SessionResumeClaim {
     reservation: ResumeReservation;
     activate(entry: SessionRegistryRegistration): Promise<void>;
+    /**
+     * Push the reservation deadline out while the caller is still hydrating.
+     *
+     * The reservation is taken before the transcript is opened, so its window
+     * has to cover work whose duration nobody knows yet. Callers that do slow
+     * work between reserve and activate must call this periodically; without it
+     * a large journal simply outlives its own reservation and `activate` fails
+     * after the expensive part already succeeded.
+     *
+     * Resolves to `false` when the reservation is already settled (activated or
+     * cancelled) — renewal is then a no-op, not an error. Rejects when the
+     * daemon refuses (expired, or owned by someone else).
+     */
+    renew(reservationMs?: number): Promise<boolean>;
     cancel(): Promise<void>;
 }
 export type SessionRegistryRegistration = Omit<SessionRegistryEntry, 'status' | 'lastHeartbeatAt' | 'agentCount' | 'agents'> & {
@@ -36,6 +50,8 @@ export declare class ProjectSessionRegistry {
         sessionId: string;
         projectSlug: string;
         projectRoot: string;
+        /** Initial reservation window. Callers doing slow hydration should also `renew()`. */
+        reservationMs?: number | undefined;
     }): Promise<SessionResumeClaim>;
     updateAgents(agents: AgentEntry[]): Promise<void>;
     private flushAgents;

package/dist/session-catalog/session-agents.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Derive the agent roster of one session from its journal.
+ *
+ * The journal is the source of truth and this is a pure projection over it —
+ * deliberately, because the alternative (agents writing their own rows as they
+ * spawn) creates a second authority that drifts the first time a process dies
+ * between the append and the row. A projection cannot drift: re-run it and it
+ * agrees with the file by construction.
+ *
+ * Three records feed a row, and they do NOT arrive in a fixed order.
+ * `agent_session_linked` is appended by the subagent factory, which runs
+ * INSIDE `coordinator.spawn()`, while `agent_spawned` is appended by the fleet
+ * layer only after that call returns — so the link normally lands first. Every
+ * merge here is therefore an upsert keyed on `agentId`, never a lookup that
+ * assumes the row already exists.
+ */
+import type { Usage } from '../types/provider.js';
+import type { SessionEvent } from '../types/session.js';
+export type SessionAgentStatus = 'running' | 'completed' | 'failed';
+export interface SessionAgentRecord {
+    agentId: string;
+    /** Role the agent was spawned as, from `agent_spawned`. */
+    role?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+    /** The agent's own journal id, when it has one of its own. */
+    agentSessionId?: string | undefined;
+    /** Absolute path of the agent's own JSONL, when it has one. */
+    transcriptPath?: string | undefined;
+    /** Set when another agent — not the leader — spawned this one. */
+    parentAgentId?: string | undefined;
+    spawnedAt?: string | undefined;
+    endedAt?: string | undefined;
+    status: SessionAgentStatus;
+    error?: string | undefined;
+    /**
+     * Events in THIS journal stamped with this agent's id.
+     *
+     * Non-zero only for agents running on the parent-interleaved writer, whose
+     * events land in the leader's file. An agent with its own transcript writes
+     * nothing here, so a `0` means "look in `transcriptPath`", not "did nothing".
+     */
+    interleavedEventCount: number;
+    usage?: Usage | undefined;
+}
+/**
+ * Project a session's events into one record per agent, ordered by first
+ * appearance so the roster reads in spawn order.
+ *
+ * Tolerates truncated journals: an agent that never got a terminal record
+ * stays `running`, which is exactly what a crashed-mid-fleet session should
+ * report. Callers that need "running or just never finished" must compare
+ * against the session's own liveness, which this function has no view of.
+ */
+export declare function deriveSessionAgents(events: Iterable<SessionEvent>): SessionAgentRecord[];
+//# sourceMappingURL=session-agents.d.ts.map

package/dist/session-catalog/store-rebuild.d.ts

@@ -1,5 +1,19 @@
 import type { DatabaseSync } from 'node:sqlite';
 import type { SessionSummary } from '../types/session.js';
+/**
+ * Collect the transcript/summary files this catalog indexes.
+ *
+ * Skips exactly what `DefaultSessionStore`'s own directory scan skips — see
+ * `shouldSkipSessionDirectoryEntry`. The two disagreed: the store excluded
+ * `subagents/` (and `shared/`, `attachments/`) from what counts as a session,
+ * while this walk descended into them, so a full rebuild pushed subagent
+ * transcripts into the table backing the user's session list. On a real project
+ * that is 3,156 worker transcripts against 170 actual sessions; the five
+ * subagent rows found in a live catalog were this leak already in progress.
+ *
+ * Subagent transcripts are not unindexed — each director run maintains its own
+ * `_index.jsonl` beside them. They just are not user-resumable sessions.
+ */
 export declare function walkSessionFiles(root: string, suffix: string): string[];
 export declare function summarizeTranscriptFile(transcriptFilePath: string, id: string): SessionSummary;
 export declare function rebuildCatalogIndex(db: DatabaseSync, sessionsDir: string, containedPathFn: (relative: string) => string, transactionFn: <T>(run: () => T) => T, bumpGenerationFn: () => number): {

package/dist/session-catalog/store-schema.d.ts

@@ -1,5 +1,14 @@
 import type { DatabaseSync } from 'node:sqlite';
 import type { SessionRegistryEntry } from './session-registry-types.js';
+/**
+ * Bumped ONLY for breaking changes — a mismatch throws and takes the catalog
+ * with it (`initializeCatalogSchema`), and there is no downgrade path.
+ *
+ * Purely additive tables do not qualify and must not bump it: every statement
+ * below is `IF NOT EXISTS`, so a new binary adds what it needs on open and an
+ * older binary reading the same file simply never queries the extra tables.
+ * `session_agents` / `session_agent_index` were added this way.
+ */
 export declare const SCHEMA_VERSION = 1;
 export declare const MAX_LEASE_MS = 120000;
 export declare const MAX_RESERVATION_MS = 60000;
@@ -25,6 +34,23 @@ export interface ReservationRow {
     current_session_id: string | null;
     expires_at: number;
 }
+export interface SessionAgentRow {
+    session_id: string;
+    agent_id: string;
+    role: string | null;
+    provider: string | null;
+    model: string | null;
+    agent_session_id: string | null;
+    transcript_path: string | null;
+    parent_agent_id: string | null;
+    spawned_at: string | null;
+    ended_at: string | null;
+    status: string;
+    error: string | null;
+    interleaved_event_count: number;
+    usage_json: string | null;
+    ordinal: number;
+}
 export interface CatalogRow {
     session_id: string;
     transcript_relative_path: string;

package/dist/session-catalog/store.d.ts

@@ -1,6 +1,7 @@
-import type { SessionRegistryEntry } from './session-registry-types.js';
 import type { SessionSummary } from '../types/session.js';
 import type { CatalogSessionRecord, MaintenanceLease, ResumeReservation, SessionCatalogHealth, SessionCatalogListArgs, SessionLeaseCredential } from './protocol.js';
+import { type SessionAgentRecord } from './session-agents.js';
+import type { SessionRegistryEntry } from './session-registry-types.js';
 export declare class SessionCatalogStore {
     readonly projectDir: string;
     readonly databasePath: string;
@@ -24,6 +25,15 @@ export declare class SessionCatalogStore {
     reconnectLease(credential: SessionLeaseCredential): SessionLeaseCredential;
     reserveResume(targetSessionId: string, requesterInstanceId: string, currentSessionId?: string, reservationMs?: number): ResumeReservation;
     activateReservation(reservation: ResumeReservation, entry: SessionRegistryEntry, leaseMs?: number): SessionLeaseCredential;
+    /**
+     * Extend a live reservation the requester still owns.
+     *
+     * Deliberately does NOT call `reapExpired()` first: reaping would delete an
+     * already-expired row and turn the accurate "expired" answer into the
+     * indistinguishable "not owned by this requester". The caller needs to know
+     * which of the two happened.
+     */
+    renewReservation(reservationId: string, requesterInstanceId: string, reservationMs?: number): ResumeReservation;
     cancelReservation(reservationId: string, requesterInstanceId: string): void;
     heartbeat(credential: SessionLeaseCredential, status?: SessionRegistryEntry['status']): SessionLeaseCredential;
     publishAgents(credential: SessionLeaseCredential, revision: number, agents: SessionRegistryEntry['agents']): {
@@ -39,6 +49,22 @@ export declare class SessionCatalogStore {
     private catalogRecord;
     listCatalog(criteria?: SessionCatalogListArgs): CatalogSessionRecord[];
     getSummary(sessionId: string): CatalogSessionRecord | null;
+    /**
+     * The agent roster of one session, derived from its journal.
+     *
+     * Cached in `session_agents`, keyed to the transcript's size and mtime: the
+     * journal is the authority, so the cache is a memo of a pure function over
+     * it rather than a second place agents get recorded. When the file has grown
+     * (the usual case — a live session) the rows are re-derived from scratch, so
+     * a partial read can never leave a half-updated roster behind.
+     *
+     * Returns `[]` for a session with no transcript on disk. A caller cannot
+     * distinguish that from "a real session that spawned nothing", and should
+     * not need to: both mean there is no agent to show.
+     */
+    listSessionAgents(sessionId: string): SessionAgentRecord[];
+    private readSessionAgentRows;
+    private writeSessionAgentRows;
     resolveId(query: string): string;
     rename(sessionId: string, name: string): Promise<CatalogSessionRecord>;
     acquireMaintenance(sessionId: string, operation: MaintenanceLease['operation'], holderId: string, leaseMs?: number, holderPid?: number): MaintenanceLease;

package/dist/session-note-attach.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Bind a running agent to the same-session note hub so peers can reach it
+ * without mailbox. Unregisters via the agent hook on teardown.
+ *
+ * @module session-note-attach
+ */
+import type { AgentInternals } from './core/agent-internals.js';
+export declare function attachSessionNotes(a: AgentInternals): void;
+//# sourceMappingURL=session-note-attach.d.ts.map