@hydraharness/harness-client-runtime 0.0.0-stage → 0.1.1-rc.6

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser runtime exported from `./client` and `./loader`. */
+/** Host plugin body — no host-side behavior for the runtime plugin. */
+function apply(_ctx) {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,36 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-client-runtime`.
+* @module @hydraharness/harness-client-runtime/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-client-runtime";
+/** Cordis companion plugin name. */
+const name = "client-runtime-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* Owned relation: every 'slots/changed'(key) emission must observe the
+* mutation already applied — SlotCore bumps the key's version synchronously
+* before the service re-emits, so a zero version at dispatch time means the
+* event fired without (or ahead of) its mutation.
+*/
+const install = (ctx, fail) => {
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "slots/changed") return;
+		const key = args[0];
+		if (typeof key !== "string" || key === "") {
+			fail("'slots/changed' dispatched without a slot key argument");
+			return;
+		}
+		const slots = ctx.get("slots");
+		if (slots !== void 0 && slots.getVersion(key) === 0) fail(`'slots/changed' fired for "${key}" before any mutation bumped its version — emission must follow the applied mutation`);
+	}, { global: true });
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/agents/scope.d.ts

@@ -0,0 +1,35 @@
+import type { Context, Fiber } from '@hydraharness/cordis';
+import type { SessionId } from '@hydraharness/harness-api-remotes/client';
+import type { TypertClientRemote, TypertRemoteScopeApi } from '@hydraharness/harness-typert-protocol';
+/** Client Cordis Context carrying one Agent identity and its scoped Remote namespaces. */
+export type AgentContext = Omit<Context, 'remote'> & {
+    readonly remote: TypertClientRemote & TypertRemoteScopeApi<'agent'>;
+};
+/** A minted Agent scope and its disposal boundary. */
+export interface AgentScopeHandle {
+    /**
+     * Tagged context: scope-owned registrations and scoped dispatch both go
+     * through it (passing it as the dispatch subject routes to this agent's
+     * tagged listeners plus every untagged one).
+     */
+    ctx: AgentContext;
+    /** Backing fiber (dispose tears down every scope-owned registration). */
+    fiber: Fiber;
+}
+/**
+ * Mint an Agent scope under `ctx`: a no-op plugin fiber whose context
+ * carries the agent tag and the dispatch filter — untagged listeners are
+ * admitted globally, tagged listeners only for a matching agent.
+ * Registrations through the returned ctx dispose with the fiber.
+ * @param ctx - client root context the scope fiber mounts under.
+ * @param key - owning agent identity (the routing tag; agent id === session id).
+ * @returns the tagged context and its backing fiber.
+ */
+export declare function createScope(ctx: Context, key: SessionId): AgentScopeHandle;
+/**
+ * Read the nearest agent tag inherited by a context.
+ * @param ctx - any client context.
+ * @returns its agent identity (the session id), or undefined for root contexts.
+ */
+export declare function scopeOf(ctx: Context): SessionId | undefined;
+//# sourceMappingURL=scope.d.ts.map

package/lib/types/client/contract/conversation.d.ts

@@ -0,0 +1,242 @@
+import type { SessionEvent } from '@hydraharness/harness-session/types';
+import type { ToolEventView } from '@hydraharness/harness-api-remotes/client';
+/** One raw log event plus its optional envelope-level presentation view. */
+export interface ConversationEventInput {
+    readonly event: SessionEvent;
+    readonly view: ToolEventView | undefined;
+}
+/** Definition-local identity and lifecycle role extracted from one event. */
+export interface ConversationMatchResult {
+    readonly id: string;
+    readonly role: 'start' | 'update';
+}
+/** Merge-extensible business values published against one Turn. */
+export interface ConversationTurnDataMap {
+}
+/** Merge-extensible business values published against one Step. */
+export interface ConversationStepDataMap {
+}
+/** Stable keyed reader for independently owned Location business values. */
+export interface ConversationLocationDataStore<DataMap extends object> {
+    /**
+     * Read one business value without exposing another owner's mutable State.
+     * @param key - declaration-merged business key.
+     * @returns latest immutable value, when its owning Context has published one.
+     */
+    get<Key extends keyof DataMap & string>(key: Key): Readonly<DataMap[Key]> | undefined;
+}
+interface ConversationLocationDataValue {
+    readonly kind: 'turn' | 'step';
+    readonly turn: number;
+    readonly step?: number;
+    readonly key: string;
+    readonly value: unknown;
+}
+type RegisteredTurnData = {
+    [Key in keyof ConversationTurnDataMap & string]: {
+        readonly kind: 'turn';
+        readonly turn: number;
+        readonly key: Key;
+        readonly value: ConversationTurnDataMap[Key];
+    };
+}[keyof ConversationTurnDataMap & string];
+type RegisteredStepData = {
+    [Key in keyof ConversationStepDataMap & string]: {
+        readonly kind: 'step';
+        readonly turn: number;
+        readonly step: number;
+        readonly key: Key;
+        readonly value: ConversationStepDataMap[Key];
+    };
+}[keyof ConversationStepDataMap & string];
+/** One Definition-owned value attached to an Engine-owned Turn or Step. */
+export type ConversationLocationData = [
+    keyof ConversationTurnDataMap | keyof ConversationStepDataMap
+] extends [never] ? ConversationLocationDataValue : RegisteredTurnData | RegisteredStepData;
+/** Immutable resolved boundary for one Agent step. */
+export interface StepLocation {
+    readonly turn: number;
+    readonly step: number;
+    readonly start: SessionEvent<'step/start'> | undefined;
+    readonly end: SessionEvent<'step/end'> | undefined;
+    readonly status: 'open' | 'closed' | 'unknown';
+    /** Stable reader for Step-scoped business values. */
+    readonly data: ConversationLocationDataStore<ConversationStepDataMap>;
+}
+/** Immutable resolved boundary for one Agent turn. */
+export interface TurnLocation {
+    readonly turn: number;
+    readonly start: SessionEvent<'turn/start'> | undefined;
+    readonly end: SessionEvent<'turn/end'> | undefined;
+    readonly status: 'open' | 'closed' | 'unknown';
+    readonly steps: readonly StepLocation[];
+    /** Stable reader for Turn-scoped business values. */
+    readonly data: ConversationLocationDataStore<ConversationTurnDataMap>;
+}
+/** Engine-owned placement of one matched event in the Session hierarchy. */
+export type ConversationLocation = {
+    readonly kind: 'session';
+} | {
+    readonly kind: 'turn';
+    readonly turn: TurnLocation;
+} | {
+    readonly kind: 'step';
+    readonly turn: TurnLocation;
+    readonly step: StepLocation;
+} | {
+    readonly kind: 'unresolved';
+};
+/** One event accepted by a Definition, with its current resolved Location. */
+export interface ConversationMatch extends ConversationEventInput {
+    readonly role: 'start' | 'update';
+    readonly location: ConversationLocation;
+}
+/** Target-neutral identity returned by a business Definition. */
+export interface ConversationViewNode {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly target: string;
+    readonly data: unknown;
+}
+/** Merge-extensible immutable snapshots published by registered view targets. */
+export interface ConversationViewSnapshotMap {
+}
+/** Stable reader over the latest snapshot of every registered view target. */
+export interface ConversationViewSnapshotStore {
+    /** @param target - registered view target. @returns its current snapshot. */
+    get<Target extends Extract<keyof ConversationViewSnapshotMap, string>>(target: Target): ConversationViewSnapshotMap[Target] | undefined;
+}
+/** Final Chat render unit produced directly by a business Definition. */
+export interface ChatConversationViewNode extends ConversationViewNode {
+    readonly target: 'chat';
+    readonly anchorSeq: number;
+    readonly location: ConversationLocation;
+    readonly visibility: 'visible' | 'hidden';
+}
+/** Immutable public view of an assembled business Context. */
+export interface ConversationNodeContext<State = unknown> {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly matches: readonly ConversationMatch[];
+    readonly start: ConversationMatch | undefined;
+    readonly state: State | undefined;
+    readonly current: ReadonlyMap<string, ConversationViewNode | null>;
+}
+/** Read-only predecessor returned to a Definition's start function. */
+export interface ConversationPreviousContext<State = unknown> {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly startSeq: number;
+    readonly state: Readonly<State>;
+    readonly matches: readonly ConversationMatch[];
+}
+/** Strictly-backward Context lookup available while a start is evaluated. */
+export interface ConversationContextReader {
+    /**
+     * Find the active Context of `kind` with the greatest start seq below the
+     * current start event.
+     * @param kind - Definition kind to query.
+     * @returns the nearest predecessor, or undefined when absent in the current window.
+     */
+    previous<State>(kind: string): ConversationPreviousContext<State> | undefined;
+}
+/** Requested cadence for materializing updated business State into view Nodes. */
+export type ConversationPublication = 'none' | 'animation-frame' | 'immediate';
+/** Engine-owned Location data publication phase. */
+export type ConversationLocationDataScope = 'step' | 'turn';
+/** One independently registered business Event-to-Node state machine. */
+export interface ConversationNodeDefinition<State = unknown> {
+    readonly kind: string;
+    /** Sole view target owned by this Definition; omitted for state-only Contexts. */
+    readonly target?: string;
+    /**
+     * Extract this Definition's stable business identity from one event.
+     * @param event - raw Session event; no Context or history access is available.
+     * @returns identity and lifecycle role, or null when unrelated.
+     */
+    match(event: SessionEvent): ConversationMatchResult | null;
+    /**
+     * Create State from the unique start Match.
+     * @param context - complete evidence currently collected for the Context.
+     * @param match - the start Match.
+     * @param reader - strictly-backward read-only Context lookup.
+     * @returns the State adopted by the engine.
+     */
+    start(context: ConversationNodeContext<State>, match: ConversationMatch, reader: ConversationContextReader): State;
+    /**
+     * Apply one post-start update Match.
+     * @param context - Context with its current State.
+     * @param match - update Match in ascending log order.
+     * @returns the State adopted by the engine.
+     */
+    update(context: ConversationNodeContext<State> & {
+        readonly state: State;
+    }, match: ConversationMatch): State;
+    /**
+     * Select publication cadence for one accepted Match.
+     * @param match - accepted Match.
+     * @returns requested cadence; omission defaults to immediate.
+     */
+    publication?(match: ConversationMatch): ConversationPublication;
+    /**
+     * Publish this Definition's read-only business value for one Location phase.
+     * The Engine evaluates every Definition first for Step and then for Turn,
+     * owns replacement/removal, and rejects another Context trying to publish
+     * the same Location key.
+     * @param context - latest complete Context.
+     * @param scope - Location hierarchy level currently being materialized.
+     * @returns current Location value, or null while unavailable.
+     */
+    buildLocationData?(context: ConversationNodeContext<State>, scope: ConversationLocationDataScope): ConversationLocationData | null;
+    /**
+     * Materialize one final Node for this Definition's declared view target.
+     * @param context - latest complete Context.
+     * @returns final Node, or null when this Context is not currently visible.
+     */
+    buildViewNode?(context: ConversationNodeContext<State>): ConversationViewNode | null;
+}
+/** Reference-stable Turn/Step facts published beside view Nodes. */
+export interface ConversationTimelineSnapshot {
+    readonly turnOrder: readonly number[];
+    readonly turns: ReadonlyMap<number, TurnLocation>;
+}
+/** Per-Session incremental builder for one view target. */
+export interface ConversationViewBuilder<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+    readonly empty: Snapshot;
+    /**
+     * Replace the low-frequency complete materialized Node set.
+     * @param input - complete Nodes and current timeline.
+     * @returns next view snapshot.
+     */
+    replace(input: {
+        readonly nodes: readonly Node[];
+        readonly timeline: ConversationTimelineSnapshot;
+    }): Snapshot;
+    /**
+     * Apply only Nodes whose materialized values changed in this transaction.
+     * @param input - changed Nodes and current timeline.
+     * @returns next view snapshot.
+     */
+    apply(input: {
+        readonly upserts: readonly Node[];
+        readonly timeline: ConversationTimelineSnapshot;
+    }): Snapshot;
+}
+/** Registry contribution that creates one isolated view builder per Session. */
+export interface ConversationViewDefinition<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+    readonly target: string;
+    /** @returns a new Session-owned incremental builder. */
+    create(): ConversationViewBuilder<Node, Snapshot>;
+}
+/**
+ * Build a stable collision-free key for one Definition-local business identity.
+ * @param kind - Definition kind.
+ * @param id - Definition-local business identity.
+ * @returns engine-owned Context key.
+ */
+export declare function conversationContextKey(kind: string, id: string): string;
+export {};
+//# sourceMappingURL=conversation.d.ts.map

package/lib/types/client/contract/session.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The outward session face. Feature packages never see the concrete Session
+ * class: components read conversation state through `useSession` (the
+ * ObservableSnapshot half), and orchestration code calls the behavior verbs
+ * below — nothing else. Widening this interface is the explicit act of
+ * widening what features may do to a session (and what every test fixture
+ * must stub); runtime-internal entry points (history staging, wire-frame
+ * dispatch) stay on the class, invisible out here.
+ */
+import type { AttachmentIdType, ImageAttachmentRef, VideoAttachmentRef } from '@hydraharness/harness-attachment';
+import type { MessageId, PromptContentPart, QueueAction, RpcResult, SessionId } from '@hydraharness/harness-api-remotes/client';
+import type { RemoteResult } from '@hydraharness/harness-typert-protocol';
+import type { ConversationSnapshot } from '../sessions/conversation.ts';
+import type { ObservableSnapshot } from './store.ts';
+/** Key-addressed projection read face (the useProjection resolution path; see ProjectionValueStore). */
+export interface ProjectionsFace {
+    /**
+     * The identity-stable bare observable for one projection key (absence is
+     * an `undefined` snapshot, never a missing face).
+     * @param key - projection key.
+     * @returns the key's value face.
+     */
+    faceOf(key: string): ObservableSnapshot<unknown>;
+}
+/** Identity plus the behavior verbs features may invoke on a session. */
+export interface ISession {
+    /** The session's host identity (agent id — same axis). */
+    readonly sessionId: SessionId;
+    /** Host-computed projection values by key (the useProjection seat). */
+    readonly projections: ProjectionsFace;
+    /**
+     * Send a prompt into the session.
+     * @param content - text plus browser-owned temporary image uploads.
+     * @param mode - 'queue' appends a turn; 'steer' interrupts the running one.
+     * @returns acceptance, or the business error (also mirrored into snapshot.promptError).
+     */
+    prompt(content: PromptContentPart[], mode: 'queue' | 'steer', signal?: AbortSignal): Promise<RpcResult<{
+        accepted: true;
+    }>>;
+    /**
+     * Resolve durable image or video bytes referenced by this session.
+     * @param attachmentId - opaque id found in the folded session log.
+     * @returns the authenticated reference and decoded bytes.
+     */
+    readAttachment(attachmentId: AttachmentIdType): Promise<RpcResult<{
+        attachment: ImageAttachmentRef | VideoAttachmentRef;
+        data: Uint8Array;
+    }>>;
+    /**
+     * Apply one edit, remove, or strict steer action to a still-pending queue occurrence.
+     * @param itemId - agent-owned inbox occurrence identity.
+     * @param action - requested queue operation.
+     * @returns acceptance, or a business/transport error.
+     */
+    updateQueue(itemId: MessageId, action: QueueAction): Promise<RpcResult<{
+        accepted: true;
+    }>>;
+    /**
+     * Cancel the running turn. Pending queued work remains and resumes in FIFO
+     * order after the Host reaches cancellation quiescence.
+     * @returns acceptance, or the business error.
+     */
+    cancel(): Promise<RpcResult<{
+        accepted: true;
+    }>>;
+    /**
+     * Rename this session (explicit user title; pins it against automatic
+     * regeneration).
+     * @param title - raw title text (the host normalizes acceptance).
+     * @returns the normalized accepted title and its event seq, or the business error.
+     */
+    rename(title: string): Promise<RpcResult<{
+        title: string;
+        seq: number;
+    }>>;
+    /**
+     * Extend the history window backwards (older messages pagination).
+     * @returns completion; failures land in snapshot.openState/loadingOlder.
+     */
+    loadOlder(): Promise<void>;
+    /**
+     * Execute one slash-command line against this session's agent — pure
+     * admission semantics (the host executor durably logs the lifecycle).
+     * @param line - the full command line, leading slash included.
+     * @returns the admission result, or the Remote face's error branch.
+     */
+    command(line: string): Promise<RemoteResult<{
+        matched: boolean;
+    }>>;
+}
+/**
+ * The full outward face: behavior verbs plus the conversation read side
+ * (the `useSession` hook source). This is the type carried by
+ * `SessionBinding.session` and the provide channel.
+ */
+export type SessionFace = ISession & ObservableSnapshot<ConversationSnapshot>;
+//# sourceMappingURL=session.d.ts.map

package/lib/types/client/contract/sessions-port.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cross-domain sessions face: the contract surface sibling domains (today:
+ * workspaces) consume instead of the sessions implementation. The sessions
+ * domain satisfies it structurally — SessionRuntime is assignable, checked
+ * wherever the assembly layer or a test injects the real service — so
+ * widening this face is the explicit act of widening the inter-domain
+ * dependency.
+ */
+import type { SessionId, WorkspaceId } from '@hydraharness/harness-api-remotes/client';
+import type { ObservableSnapshot } from './store.ts';
+/** Session-list row facts sibling domains read: recency, blank-reuse eligibility, and its cwd canon. */
+export interface SessionsPortSummary {
+    id: SessionId;
+    /** Empty-log bit (blank sessions are reused by New Session instead of minting another). */
+    blank: boolean;
+    cwd?: string;
+    updatedAt: number;
+}
+/** Session-list facts sibling domains read: readiness, selection, and the row map. */
+export interface SessionsPortList {
+    ids: SessionId[];
+    byId: Record<SessionId, SessionsPortSummary>;
+    current: SessionId | undefined;
+    phase: 'pending' | 'ready';
+}
+/** The sessions-service face injected into sibling domains. */
+export interface SessionsPort {
+    /** Observable list snapshot (read face only; writes stay inside the sessions domain). */
+    readonly list: ObservableSnapshot<SessionsPortList>;
+    /**
+     * Create or explicitly adopt a session on the host.
+     * @param opts - target workspace and optional confirmed blank-reuse id.
+     * @returns the created or adopted session id.
+     */
+    create(opts: {
+        workspaceId: WorkspaceId;
+        sessionId?: SessionId;
+        reuseWorkspaceBlank?: true;
+        /**
+         * Local list-row cwd fill for the create echo. The Host derives cwd from
+         * the Workspace and this value is not sent on the wire; New Session
+         * supplies the Workspace path so the hero composer can resolve ownership
+         * before `host/session-added` arrives.
+         */
+        cwd?: string;
+    }): Promise<SessionId>;
+    /**
+     * Select a session as current.
+     * @param id - session id (must exist in the list store).
+     */
+    open(id: SessionId): void;
+    /** Clear the current selection into the no-session view state. */
+    clear(): void;
+}
+//# sourceMappingURL=sessions-port.d.ts.map

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

@@ -0,0 +1,164 @@
+/**
+ * The outward sessions-service face — what `ctx.sessions` exposes to feature
+ * packages and the renderer host, and therefore exactly what the test
+ * runtime's sessions double must implement. Wire-pump entry points
+ * (handleMuxEnvelope/handleConnected) and runtime internals stay on the
+ * concrete class; cross-domain consumers keep the narrower
+ * [SessionsPort](./sessions-port.ts). Widening this interface is the
+ * explicit act of widening what features may do to the sessions domain.
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { RpcResult, SessionId, SubagentAddress } from '@hydraharness/harness-api-remotes/client';
+import type { PromptRevisionRequest } from '@hydraharness/harness-host-apiproxy/api';
+import type { HostObservable, SessionMaybeProvideInfo, SessionProvideInfo } from '@hydraharness/harness-client-ui-slots';
+import type { AgentContext } from '../agents/scope.ts';
+import type { SessionSearchResultItem } from '../sessions/manager.ts';
+import type { SessionBinding, SessionListState, SessionProvideDescriptor } from '../sessions/service.ts';
+import type { SessionFace } from './session.ts';
+import type { ObservableSnapshot } from './store.ts';
+export type { AgentContext } from '../agents/scope.ts';
+/** The sessions-service face injected as `ctx.sessions`. */
+export interface ISessions {
+    /** The useSessions standard feed (list rows + current selection; read face — writes stay inside the domain). */
+    readonly list: ObservableSnapshot<SessionListState>;
+    /** Atomic current-session provide projection (the renderer host's `sessions.provideInfo` feed). */
+    readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>;
+    /** Resolve one session's render bundle without selecting it as current. */
+    provideInfo(id: string): SessionProvideInfo | undefined;
+    /**
+     * The `session.search` result bound the wire schema fixes, exposed to
+     * presentation as injected data. Not per-connection state: every transport
+     * (fixture included) reports the same number.
+     */
+    readonly searchResultLimit: number;
+    /** Create or adopt a session without selecting it as current. */
+    create(opts?: {
+        workspaceId?: import('@hydraharness/harness-api-remotes/client').WorkspaceId;
+        cwd?: string;
+        sessionId?: SessionId;
+        reuseWorkspaceBlank?: true;
+    }): Promise<SessionId>;
+    /** Permanently delete a session after the UI confirmation step. */
+    delete(sessionId: SessionId): Promise<void>;
+    /**
+     * Select a session as current.
+     * @param id - session id (must exist in the list; unknown ids fail loud).
+     */
+    open(id: SessionId): void;
+    /**
+     * Open a healthy catalog child through its exact direct-parent address.
+     * @param address - catalog-derived parent and child ids.
+     */
+    openSubagent(address: SubagentAddress): void;
+    /**
+     * Resolve an already discovered direct-parent address without opening it.
+     * @param id - possible addressed child id.
+     * @returns the retained address, when present.
+     */
+    subagentAddress(id: SessionId): SubagentAddress | undefined;
+    /**
+     * Mark whether a catalog menu is consuming live membership updates.
+     * @param parentSessionId - catalog owner.
+     * @param open - current menu state.
+     */
+    setSubagentCatalogOpen(parentSessionId: SessionId, open: boolean): void;
+    /**
+     * Refresh one direct-child catalog.
+     * @param parentSessionId - catalog owner.
+     * @returns completion of the current or newly started refresh.
+     */
+    refreshSubagents(parentSessionId: SessionId): Promise<void>;
+    /**
+     * Refresh the session-list baseline, reusing an in-flight pull. A page that
+     * aggregates cold list rows (Settings Usage) calls this on mount so those
+     * rows carry the Host's latest projection cut instead of the last baseline's.
+     * @returns completion of the current or newly started baseline pull.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Record the composition one session now runs. The agent-preset seat calls
+     * this after a successful blank-session switch, so the header label moves
+     * with the composition instead of waiting for the next full list refresh.
+     * @param sessionId - the switched session.
+     * @param agentPreset - the preset id the host confirmed.
+     */
+    noteAgentPreset(sessionId: SessionId, agentPreset: string): void;
+    /** Clear the current selection into the no-session view state. */
+    clear(): void;
+    /**
+     * Search the Host's visible message-content index. Results stay
+     * request-local; the list snapshot remains the metadata authority.
+     * @param query - non-blank literal phrase.
+     * @param signal - cancellation for a superseded search.
+     * @returns bounded results, or a business/transport error.
+     */
+    search(query: string, signal: AbortSignal): Promise<RpcResult<{
+        items: SessionSearchResultItem[];
+        hasMore: boolean;
+    }>>;
+    /**
+     * Fork a session from a completed-turn prefix of the source; on resolution
+     * the child is in the list store and `open()` can target it.
+     * @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),
+     *   and whether to increment an inherited durable title before resolving.
+     *   `beforeSeq` excludes the selected turn-opening user message's entire turn
+     *   and cannot accompany `atSeq`; the first and active turns are supported.
+     * @returns the child session id.
+     * @throws when the fork fails, or when a requested child-title rename fails after creation.
+     */
+    fork(opts: {
+        sessionId: SessionId;
+        atSeq?: number;
+        beforeSeq?: number;
+        increaseTitle?: boolean;
+    }): Promise<SessionId>;
+    /**
+     * Admit a prompt revision or retry and make its attempt synchronously addressable.
+     * @param input - Host-validated source, workspace, edit, and stable retry key.
+     * @returns the new attempt session id; rejection leaves selection unchanged.
+     */
+    revise(input: PromptRevisionRequest): Promise<SessionId>;
+    /**
+     * View or reference a stored path in the same session.
+     * @param sessionId - Owning session.
+     * @param versionId - Stored path.
+     * @param mode - View selection or logged reference injection.
+     * @returns Host acknowledgement and refreshed session metadata.
+     */
+    selectVersion(sessionId: SessionId, versionId: import('@hydraharness/harness-session/types').SessionVersionId, mode?: 'view' | 'reference'): Promise<void>;
+    /**
+     * Register a per-session standard-props provider (hooks become `use<Name>`
+     * selector hooks on the render side; props spread verbatim).
+     * @param descriptor - static member roster plus per-session resolver.
+     * @returns disposer removing the provider.
+     */
+    provide(descriptor: SessionProvideDescriptor): () => void;
+    /**
+     * Resolve an Agent-scoped context view (use-and-discard).
+     * @param id - session id.
+     * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+     */
+    scope(id: SessionId): AgentContext | undefined;
+    /**
+     * Read the Agent scope tag off a context (service-method boundary: fetch
+     * bundles must reach scope resolution through ctx.sessions).
+     * @param ctx - any client context.
+     * @returns the session id, or undefined on root contexts.
+     */
+    scopeOf(ctx: Context): SessionId | undefined;
+    /**
+     * Resolve the session face behind an Agent-scoped context.
+     * @param ctx - an Agent-scoped context.
+     * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
+     */
+    sessionOf(ctx: Context): SessionFace | undefined;
+    /**
+     * Resolve the stable session binding (scope-addressed assembly feed).
+     * @param id - session id.
+     * @returns binding, or undefined for a session neither listed nor already scoped.
+     */
+    binding(id: SessionId): SessionBinding | undefined;
+}
+//# sourceMappingURL=sessions.d.ts.map