@crazx/dsh-api-session-controller 0.1.6-alpha.1.zw.2 → 0.1.6-alpha.2.zw.1

package/lib/types/client/sessions/service.d.ts

@@ -1,30 +1,15 @@
-/**
- * ClientSessions: root sessions service — list snapshot store (manager
- * projection; carries `current`, the persisted selection every
- * session-scoped surface keys off), Agent scope tree (mintScope pattern: no-op plugin
- * Fiber + ctx.extend scope tag; one scope per session, agent id === session
- * id), stable SessionBinding cache, breadcrumb-route projection.
- *
- * Scope lifecycle is stage-driven: a scope is minted lazily on first
- * resolution (pure — resolution has no side effects and is render-safe);
- * the event window and deferred teardown key off the STAGED session, which
- * follows `list.current` exactly. Staging is the open signal: the window
- * opens ⟺ the session is on stage (the stage is `current`; the staged
- * state can widen to a multi-pane list later). A session leaving the list
- * tears its scope down immediately unless it is the staged one, whose scope
- * survives frozen (read-only view) until the stage moves on.
- */
+/** Client catalog and source-labelled ownership of exact Session generations. */
 import type { Context } from '@deepseek-ai/cordis';
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client';
 import { type SessionId } from '@deepseek-ai/dsh-session/types';
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
 import type { SessionJob as JobView } from '../../types.ts';
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
-import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import { type ObservableSnapshot, type SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionEventSource } from '../contract/events.ts';
 import type { SessionFace } from '../contract/session.ts';
-import type { AgentContext, ISessions } from '../contract/sessions.ts';
+import type { AgentContext, ISessions, SessionReference, SessionRetainInfo, SessionRetainOptions, SessionTarget } from '../contract/sessions.ts';
 import { SessionManager } from './manager.ts';
 import type { SessionRemotes } from './remotes.ts';
 import type { SessionListPhase, SessionSearchResultItem, SubagentCatalogSnapshot } from './manager.ts';
@@ -40,8 +25,8 @@ export interface SessionSummary {
     /** Coarse durable origin for navigation filtering; not a continuation capability. */
     origin?: 'subagent';
     running: boolean;
-    /** Finished while not selected and not yet opened — the sidebar's green "done" reminder. Absent = false. */
-    completed?: boolean;
+    /** Local ownership counts; Host metadata refreshes cannot overwrite them. */
+    readonly retainedBy: SessionRetainInfo['retainedBy'];
     /**
      * Empty-log bit (host summary derivation mirror). New Session reuses a blank
      * one targeting the same workspace. Filtering stays with the consumer: the
@@ -53,17 +38,12 @@ export interface SessionSummary {
     /** Current host-computed projection values retained by the object layer. */
     projectionValues?: Readonly<Partial<SessionProjectionMap>>;
 }
-/**
- * Session list store shape. `current` rides the same snapshot (arbitrated:
- * the single useSessions standard hook reads list and selection together —
- * sidebar highlighting and current-session consumers share one fact source).
- */
+/** Catalog metadata and local source counts; catalog membership owns no Client generation. */
 export interface SessionListState {
     /** Host-list order; addressed breadcrumb-only rows are excluded. */
     ids: SessionId[];
-    /** Host rows plus the current addressed subagent route used by navigation. */
+    /** Host/catalog rows plus local fallback rows for live Client generations; only `ids` expresses Host-list membership. */
     byId: Record<SessionId, SessionSummary>;
-    current: SessionId | undefined;
     /** Arrival lifecycle projected 1:1 from the manager snapshot (see SessionListPhase): empty-with-ready means "truly no sessions". */
     phase: SessionListPhase;
     /** Direct durable catalogs keyed by their selected parent address. */
@@ -74,8 +54,6 @@ export interface SessionListState {
      * set, so consumers read absence rather than a sentinel.
      */
     jobsBySession: Readonly<Record<SessionId, readonly JobView[]>>;
-    /** Current session's catalog-derived address, absent on ordinary navigation. */
-    currentAddress: SubagentAddress | undefined;
 }
 /** Structured session-create failure. */
 export declare class SessionCreateError extends Error {
@@ -109,7 +87,7 @@ export interface SessionBinding {
     readonly ctx: AgentContext;
 }
 export { scopeOf } from '../scope.ts';
-/** Root sessions service: list store, current selection, object-layer manager, scope tree, bindings, and breadcrumb routes. */
+/** Host catalog and local reference allocator; view selection remains outside the Controller. */
 export declare class ClientSessions implements ISessions {
     private readonly rootCtx;
     /**
@@ -119,46 +97,23 @@ export declare class ClientSessions implements ISessions {
      * reports the same number.
      */
     readonly searchResultLimit = 20;
-    /** List snapshot store (list RPC + host stream increments; re-pulled on reconnect) — the useSessions standard feed, current included. */
+    /** Catalog metadata and local reference-source projection. */
     readonly list: SnapshotStore<SessionListState>;
     /** The object-layer instance cluster and frame dispatch entry. */
     private readonly manager;
-    /**
-     * Persisted selection cell (the durable half of `list.current`). Private on
-     * purpose: reads go through the list snapshot; writes through {@link
-     * ClientSessions.open} / {@link ClientSessions.clear}. Projection
-     * validates it against the live list instead of destructively pruning, so a
-     * selection survives transient list states (reconnect re-pull) and
-     * resurfaces when its session returns.
-     */
-    private readonly selection;
     private readonly scopes;
-    /** In-flight scope drops remain here after records leave `scopes`, so root disposal can await quiescence. */
+    /** Stable per-id sources retained for the Client root lifetime, including across generation replacement. */
+    private readonly retainObservers;
     private readonly scopeDrops;
-    /**
-     * The staged session id — follows `list.current` exactly, holding its last
-     * defined value across masked gaps (a transiently absent selection blanks
-     * `current` without moving the stage, so reconnect re-pulls and removals
-     * keep the staged scope's frozen view alive until the stage moves on).
-     */
-    private watched;
-    /** Removed-while-staged sessions whose teardown waits for the stage to move away. */
-    private readonly deferredRemovals;
+    private closed;
     /**
      * @param ctx - client root context (scope fibers mount under it).
      * @param remote - generated Remote namespaces shared with every Session.
      */
     constructor(rootCtx: Context, remote: SessionRemotes);
-    /**
-     * Select a listed or retained catalog-addressed session as current.
-     * @param id - listed or addressed session id.
-     */
-    open(id: SessionId): void;
-    /**
-     * Open a healthy catalog child through its direct-parent address.
-     * @param address - catalog-derived parent and child ids.
-     */
-    openSubagent(address: SubagentAddress): void;
+    retain(target: SessionTarget, options: SessionRetainOptions): SessionReference;
+    using<T>(target: SessionTarget, options: SessionRetainOptions, operation: (reference: SessionReference) => T | Promise<T>): Promise<T>;
+    retainInfo(id: SessionId): ObservableSnapshot<SessionRetainInfo>;
     /**
      * Resolve an already discovered direct-parent address without opening it.
      * Feature plugins use this to avoid Agent-bound RPCs in persisted child views.
@@ -177,14 +132,6 @@ export declare class ClientSessions implements ISessions {
      * @param parentSessionId - catalog owner.
      */
     refreshSubagents(parentSessionId: SessionId): Promise<void>;
-    /**
-     * Clear the current selection so the layout shows the no-session empty
-     * state (new-session affordance and the workspace preselection flow).
-     * Wipes the persisted selection too — a reload stays on empty until the
-     * user opens or starts a session. The staged scope keeps its frozen view
-     * per the masked-gap contract until the next open() moves the stage.
-     */
-    clear(): void;
     /**
      * Refresh the real Session baseline, reusing an in-flight pull.
      * @returns completion of the current or newly started baseline pull.
@@ -234,12 +181,8 @@ export declare class ClientSessions implements ISessions {
     /** Rebuild the Session baseline and every opened window after connection. */
     handleConnected(): void;
     /**
-     * Create a session on the host. Resolution guarantee: by the time the
-     * promise resolves, the created session is in the list store and
-     * {@link ClientSessions.binding} resolves it — callers (New Session
-     * draft hand-off) may address the scope synchronously, without waiting a
-     * notifier flush. The synchronous projection below makes this structural
-     * rather than an accident of microtask ordering.
+     * Create a Host Session and publish its catalog row before resolving.
+     * Callers retain the returned identity before borrowing its binding.
      * @param opts - target workspace or directory and an optional preallocated id.
      * @returns the new session id.
      * @throws {SessionCreateError} with the requested id.
@@ -250,9 +193,8 @@ export declare class ClientSessions implements ISessions {
         sessionId?: SessionId;
     }): Promise<SessionId>;
     /**
-     * Fork a session from a completed-turn prefix of the source (same
-     * synchronous-addressability guarantee as {@link ClientSessions.create}:
-     * on resolution the child is in the list store and open() can target it).
+     * Fork a Session from a completed-turn prefix of the source and publish
+     * the child in the catalog before resolving.
      * @param opts - source session id, the optional event seq anchoring the
      *   cut (the boundary is the first turn/end at or after it; an in-log
      *   anchor in an open turn is unavailable rather than clipped backward),
@@ -270,20 +212,17 @@ export declare class ClientSessions implements ISessions {
         increaseTitle?: boolean;
     }): Promise<SessionId>;
     /**
-     * Resolve an Agent-scoped context view (use-and-discard).
+     * Borrow an already-retained Agent-scoped Context.
      * @param id - session id (the agent identity — 1:1 same axis).
-     * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+     * @returns the scoped Context, or undefined without a retained generation.
      */
     scope(id: SessionId): AgentContext | undefined;
     /**
-     * Materialize the Agent scope named by a validated Host Remote Event.
-     * The first successful Session-list baseline becomes authoritative for its
-     * lifetime; until then, transport streams may address the scope in either
-     * arrival order.
-     * @param id - Host-projected Agent identity (the matching Session id).
-     * @returns the identity-stable Agent Context.
+     * Retain a validated Gateway identity synchronously, without history or catalog I/O.
+     * @param id - Host-projected Session identity, possibly not yet catalogued.
+     * @returns a Gateway-source reference owned by the invocation.
      */
-    resolveAgentScope(id: SessionId): AgentContext;
+    retainAgentScope(id: SessionId): SessionReference;
     /**
      * Read the Agent scope tag off a context. Service-method boundary: fetch
      * bundles must reach scope resolution through ctx.sessions — a cross-bundle
@@ -300,50 +239,26 @@ export declare class ClientSessions implements ISessions {
      * `agent.session`). Same service-method boundary as
      * {@link ClientSessions.scopeOf}.
      * @param ctx - an Agent-scoped context.
-     * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
+     * @returns the matching live Session, or undefined for an untagged or ended generation.
      */
     sessionOf(ctx: Context): SessionFace | undefined;
     /**
-     * Resolve the stable session binding (scope-addressed assembly feed). Pure
-     * resolution — no staging, no window side effects.
-     * @param id - session id.
-     * @returns binding, or undefined for a session neither listed nor already scoped.
+     * Borrow an already-retained binding without extending its lifetime.
+     * @param id - Session identity.
+     * @returns the live binding, or undefined without a retained generation.
      */
     binding(id: SessionId): SessionBinding | undefined;
-    /**
-     * Move the stage to the list's current session: sweep teardowns deferred
-     * behind the previous occupant and pull the new occupant's history window.
-     * Staging IS the open signal — the window opens ⟺ the session is on stage
-     * — and open() is idempotent (an in-flight or completed open no-ops; a
-     * failed one retries the next time current is touched).
-     */
-    private followCurrent;
-    /**
-     * Lazily mint the scope + binding for an eligible session. Eligibility and
-     * prune share one predicate: listed on the host or selected
-     * through a retained subagent address. Breadcrumb-only ancestors remain
-     * summary data and do not keep scopes alive.
-     */
-    private resolve;
+    private retainScope;
+    private retentionSnapshot;
+    private publishRetention;
+    private retireScope;
     /** Materialize one scope after its caller establishes that the id may be addressed. */
     private materializeScope;
-    /** The one aliveness predicate shared by scope mint and prune: host-listed or currently addressed. */
-    private eligible;
     /** Project the manager's list snapshot into the store (title derivation is display-only). */
     private projectList;
-    /** Tear down scope + instance for no-longer-eligible sessions off stage; the staged one defers until the stage moves. */
-    private pruneScopes;
     private startScopeDrop;
     private drainScopeDrops;
-    /**
-     * One teardown for the whole per-session axis: the scope
-     * fiber (cascading every actx-registered effect: input shell, slash
-     * controller, popup, plugin stores, listeners), the session-keyed slot
-     * registrations and the Session instance itself — the host session log is the
-     * durable truth, a reopen lazily rebuilds and backfills via open().
-     */
+    /** Await the already-withdrawn Session and scoped cleanup to quiescence. */
     private dropScope;
-    /** Run deferred teardowns whose session is no longer staged (called when the stage moves). */
-    private sweepDeferred;
 }
 //# sourceMappingURL=service.d.ts.map