@qilin-agent/client-test-runtime 0.0.0-stage → 3.1.4

package/lib/types/remote.d.ts

@@ -0,0 +1,66 @@
+/** Test-owned Remote face: `$on` subscriptions with an explicit test event driver. */
+import type { Context } from '@qilin-agent/kylin';
+export { RemoteError } from '@qilin-agent/typert-protocol';
+/**
+ * Remote service test double for the forwarded-event path. Feature specs need
+ * `ctx.remote.$on` to exist (their plugins inject `remote`) and need forwarded
+ * Host events to reach those subscribers, but not the wire — so this double
+ * implements subscription plus an explicit `emit` driver available only on the
+ * concrete test object. A spec that also calls one namespace scripts it through
+ * the constructor rather than reaching the real Client Remote service.
+ *
+ * `$mount` rejects: a spec that needs a real generated contribution installed —
+ * codecs, descriptors, and the wire — has outgrown this double and needs the
+ * real Client Remote service.
+ *
+ * One deliberate asymmetry with production: a throwing listener propagates out
+ * of the emit instead of being contained and logged, so a spec cannot lean on
+ * this double for the containment guarantee `$on` documents — assert that
+ * against the real service.
+ */
+export declare class TestRemote {
+    private readonly ctx;
+    private readonly subscriptions;
+    /**
+     * Fixed Host facts mirrored from the production `ctx.remote.$host`. Plain
+     * mutable field: a spec assigns it to script a non-loopback or homed Host.
+     */
+    $host: {
+        home: string | undefined;
+        isLoopback: boolean;
+    };
+    /**
+     * Register the double as `ctx.remote`, plus one service per scripted
+     * namespace so a plugin injecting `remote.<name>` also unparks.
+     * @param ctx - the spec's root Context.
+     * @param namespaces - scripted namespace faces reached as `ctx.remote.<name>`.
+     */
+    constructor(ctx: Context, namespaces?: Readonly<Record<string, object>>);
+    /**
+     * Add scripted namespace faces to this Remote service.
+     * @param namespaces - scripted namespace faces reached as `ctx.remote.<name>`.
+     */
+    provideNamespaces(namespaces: Readonly<Record<string, object>>): void;
+    private validateNamespaces;
+    private installNamespaces;
+    /**
+     * Deliver one forwarded host event to its subscribers, standing in for the
+     * carrier that owns the frame sink.
+     * @param event - forwarded host event name.
+     * @param args - the Host argument list, verbatim.
+     */
+    emit(event: string, args: readonly unknown[]): void;
+    /**
+     * Subscribe to one forwarded host event.
+     * @param event - forwarded host event name.
+     * @param listener - receives the Host argument list verbatim.
+     * @returns disposer removing this subscription.
+     */
+    $on(event: string, listener: (...args: never[]) => void): () => void;
+    /**
+     * Generated-namespace mount, unsupported by this double.
+     * @returns never; always rejects.
+     */
+    $mount(): Promise<() => Promise<void>>;
+}
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/sessions.d.ts

@@ -0,0 +1,283 @@
+/** Test-owned Session Controller faces over declarative fixtures. */
+import type { Context } from '@qilin-agent/kylin';
+import type { AttachmentIdType } from '@qilin-agent/attachment';
+import { MutableSessionEventSource } from '@qilin-agent/api-session-controller/client';
+import type { AgentContext, ISessions, ProjectionsFace, SessionBinding, SessionFace, SessionListState, SessionEventLikeEntry, SessionLiveEventEntry, SessionSearchResultItem, SessionReference, SessionRetainInfo, SessionRetainOptions, SessionSnapshot, SessionSummary, SessionTarget, SubmissionHandle } from '@qilin-agent/api-session-controller/client';
+import type { SubagentAddress } from '@qilin-agent/subagent/client';
+import type { ObservableSnapshot, SnapshotStore } from '@qilin-agent/client-store';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { SessionFixture, SessionFixtureSnapshot, Stabilizer } from './fixtures.ts';
+declare module '@qilin-agent/api-session-controller/client' {
+    interface SessionReferenceSourceMap {
+        testFixture: unknown;
+        testView: unknown;
+        testOperation: unknown;
+    }
+}
+/**
+ * The fixture-backed session face: lifecycle reads delegate to the fixture's
+ * snapshot store; Session verbs are fail-loud stubs unless the
+ * fixture supplies them (the runtime never fakes behavior a test did not
+ * declare — an unstubbed call names itself instead of half-working). Extra
+ * fixture methods are grafted verbatim for feature-side casts.
+ */
+export declare class FixtureSession implements SessionFace {
+    readonly sessionId: SessionId;
+    private readonly store;
+    /** Mutable event source consumed only by Conversation assembly. */
+    readonly eventSource: MutableSessionEventSource;
+    /**
+     * Identity-stable per-key faces over fixture-controlled projection values.
+     */
+    readonly projections: ProjectionsFace & {
+        set(key: string, value: unknown): void;
+    };
+    /**
+     * @param sessionId - host identity (branded view of the fixture id).
+     * @param store - Session Controller snapshot store.
+     * @param overrides - fixture-declared behavior face, grafted over the stubs.
+     */
+    constructor(sessionId: SessionId, store: SnapshotStore<SessionFixtureSnapshot>, overrides: Record<string, unknown>);
+    /** @returns the fixture Session Controller snapshot (useSession read side). */
+    getSnapshot(): SessionSnapshot;
+    /**
+     * Subscribe to fixture snapshot changes.
+     * @param fn - change callback.
+     * @returns unsubscribe.
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Fail-loud stub; supply `prompt` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    prompt(): never;
+    /**
+     * Minimal local-echo registration: mints an identity without touching the
+     * fixture snapshot (submission echoes are client-only presentation state).
+     * Supply `beginSubmission` on the fixture's session face to observe echoes.
+     * @returns a handle whose abandon is a no-op.
+     */
+    beginSubmission(): SubmissionHandle;
+    private submissionSeq;
+    /**
+     * Fail-loud stub; supply `readAttachment` on the fixture's session face to exercise it.
+     * @param _attachmentId - opaque durable attachment id.
+     * @returns never — always throws.
+     */
+    readAttachment(_attachmentId: AttachmentIdType): never;
+    /**
+     * Fail-loud stub; supply `updateQueue` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    updateQueue(): never;
+    /**
+     * Fail-loud stub; supply `cancel` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    cancel(): never;
+    /**
+     * Fail-loud stub; supply `command` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    command(): never;
+    /**
+     * Fail-loud stub; supply `loadOlder` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    loadOlder(): never;
+    /**
+     * Fail-loud stub; supply `loadThrough` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    loadThrough(): never;
+    /**
+     * Fail-loud stub; supply `rename` on the fixture's session face to exercise it.
+     * @returns never — always throws.
+     */
+    rename(): never;
+}
+/**
+ * Sessions test double behind the renderer host and feature injects: owns the
+ * catalog observable, scope minting through the production `createScope`,
+ * stable Controller bindings, and the session behavior face supplied per
+ * fixture. `ui-session` owns standard-source materialization.
+ *
+ * Implements the same ISessions face features receive as `ctx.sessions`, so
+ * a production face change breaks this double at compile time; the extra
+ * members (add/updateSessionSnapshot/event-window drivers/remove/
+ * behavior/calls/stubs) are bench-only surface.
+ */
+export declare class TestSessions implements ISessions {
+    private readonly stabilize;
+    private readonly rootCtx;
+    /** The useSessions catalog feed, independent of view ownership. */
+    readonly list: SnapshotStore<SessionListState>;
+    private readonly records;
+    private readonly generations;
+    private readonly addresses;
+    private readonly retentionStores;
+    private readonly pendingDrops;
+    private closed;
+    /** Calls observed on the service-level face, newest last. */
+    readonly calls: {
+        method: 'create' | 'refreshProjections' | 'refresh' | 'search' | 'fork';
+        args: unknown[];
+    }[];
+    /** The wire schema's `session.search` result bound (production parity). */
+    readonly searchResultLimit = 20;
+    /** Replaceable search behavior (see {@link TestSessions.stubSearch}). */
+    private searchStub;
+    private createStub;
+    /**
+     * @param stabilize - the owning runtime's act wrapper.
+     * @param rootCtx - the runtime's Cordis root; scope fibers mount under it.
+     */
+    constructor(stabilize: Stabilizer, rootCtx: Context);
+    /**
+     * Add a Session fixture to the catalog without retaining a generation.
+     * @param fixture - identity + snapshot/summary overrides + behavior face.
+     * @returns the stable session id (branded view of `fixture.id`).
+     */
+    add(fixture: SessionFixture): Promise<SessionId>;
+    /**
+     * Update Session Controller lifecycle state through an immer draft.
+     * @param id - session id.
+     * @param mutate - draft mutator.
+     */
+    updateSessionSnapshot(id: string, mutate: (draft: SessionFixtureSnapshot) => void): Promise<void>;
+    /**
+     * Publish one complete projection value through the fixture Session face.
+     * @param id - session id.
+     * @param key - registered projection key.
+     * @param value - complete value for that key.
+     */
+    setProjection(id: string, key: string, value: unknown): Promise<void>;
+    /**
+     * Replace a Session's complete contiguous event window.
+     * @param id - Session identity.
+     * @param entries - complete event window.
+     * @param hasMore - whether older history remains.
+     */
+    replaceEvents(id: string, entries: readonly SessionEventLikeEntry[], hasMore?: boolean): Promise<void>;
+    /**
+     * Prepend one older contiguous event page.
+     * @param id - Session identity.
+     * @param entries - older entries.
+     * @param hasMore - whether another older page remains.
+     */
+    prependEvents(id: string, entries: readonly SessionEventLikeEntry[], hasMore?: boolean): Promise<void>;
+    /**
+     * Append one live event to a Session's contiguous window.
+     * @param id - Session identity.
+     * @param entry - live event entry.
+     */
+    appendEvent(id: string, entry: SessionLiveEventEntry): Promise<void>;
+    /**
+     * Update a session's list row (the wire-echo stand-in: title settles,
+     * running flips — components subscribed via useSessions re-render).
+     * @param id - session id.
+     * @param patch - summary fields to merge over the row.
+     */
+    updateSummary(id: string, patch: Partial<Omit<SessionSummary, 'id'>>): Promise<void>;
+    /**
+     * Remove a catalog row and mark its retained Session removed without releasing owners.
+     * @param id - session id.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Borrow the already-retained session-scoped Cordis context.
+     * @param id - session id.
+     * @returns the scoped context, or undefined without a live reference.
+     */
+    scope(id: string): AgentContext | undefined;
+    /**
+     * Session assembly binding (inject factories and provide resolvers receive it).
+     * @param id - session id.
+     * @returns the live generation's binding, or undefined without a reference.
+     */
+    binding(id: string): SessionBinding | undefined;
+    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>;
+    /**
+     * Retain one fixture Session until the supplied Cordis owner stops.
+     * @param ownerCtx - context whose disposal releases the reference.
+     * @param target - fixture Session identity or subagent address.
+     * @param options - reference source and optional readiness cancellation.
+     * @returns the owned reference immediately.
+     */
+    retainFor(ownerCtx: Context, target: SessionTarget, options?: SessionRetainOptions): SessionReference;
+    /**
+     * Read the session scope tag off a context (service-method boundary mirror).
+     * @param ctx - any client context.
+     * @returns the session id, or undefined on root contexts.
+     */
+    scopeOf(ctx: Context): SessionId | undefined;
+    /**
+     * Resolve the scoped session face off a context (production `sessionOf`
+     * mirror).
+     * @param ctx - any client context.
+     * @returns the fixture session face, or undefined off-scope.
+     */
+    sessionOf(ctx: Context): SessionFace | undefined;
+    /**
+     * Install Session creation behavior for navigation tests.
+     * @param impl - implementation that must return an already-added fixture id.
+     */
+    stubCreate(impl: (opts: Parameters<ISessions['create']>[0]) => Promise<SessionId>): void;
+    /** Create through the installed test behavior and require a catalogued fixture. */
+    create(opts?: Parameters<ISessions['create']>[0]): Promise<SessionId>;
+    /** Resolve a retained or catalog-derived address independently of a view. */
+    subagentAddress(id: SessionId): SubagentAddress | undefined;
+    /** Record a projection refresh; fixture callers drive snapshots explicitly. */
+    refreshProjections(sessionId: SessionId): Promise<void>;
+    /** Record a list refresh; fixture callers publish list state explicitly. */
+    refresh(): Promise<void>;
+    /**
+     * Replace the sidebar-search result page (the call is still recorded).
+     * @param impl - hits for a query, as the Host would rank them.
+     */
+    stubSearch(impl: (query: string, signal: AbortSignal) => {
+        items: SessionSearchResultItem[];
+        hasMore: boolean;
+    }): void;
+    /**
+     * Content search over the fixture corpus (recorded). The default answers an
+     * empty page: content ranking is Host behavior, so a scenario that asserts
+     * hits declares them through {@link TestSessions.stubSearch}.
+     * @param query - non-blank literal phrase.
+     * @param signal - cancellation for a superseded search (recorded and forwarded).
+     * @returns the stubbed or empty result page.
+     */
+    search(query: string, signal: AbortSignal): ReturnType<ISessions['search']>;
+    /**
+     * Recorded fork stub: no child materializes (benches asserting the full
+     * fork flow drive the production service; this face only proves the call).
+     * @param opts - source session id, optional cut anchor, and client title policy.
+     * @returns the source id (no child record is created).
+     */
+    fork(opts: {
+        sessionId: SessionId;
+        atSeq?: number;
+        increaseTitle?: boolean;
+    }): Promise<SessionId>;
+    /**
+     * The session face of a fixture (typed view for assertions; fixture
+     * behavior methods are grafted onto it).
+     * @param id - session id.
+     * @returns the FixtureSession carried by the Controller binding.
+     */
+    behavior(id: string): FixtureSession;
+    /** Dispose minted scope fibers (runtime dispose path). */
+    disposeScopes(): Promise<void>;
+    private resolveTarget;
+    private retainGeneration;
+    private retentionSnapshot;
+    private publishRetention;
+    private materialize;
+    private startOpening;
+    private drop;
+    private drainDrops;
+    private require;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/lib/types/settings-remote.d.ts

@@ -0,0 +1,83 @@
+/** Test double for the `settings` Remote namespace a bench's plugins inject. */
+import { vi } from 'vitest';
+/** The minimum a scripted namespace view carries for the double's own bookkeeping. */
+export interface ScriptedNamespace {
+    /** Namespace key the write addresses. */
+    ns: string;
+}
+/** One scripted `settings` namespace face plus the controls a bench drives it with. */
+export interface ScriptedSettingsRemote<View extends ScriptedNamespace> {
+    /**
+     * The namespace face handed to `TestRemote` as `settings`. A plugin injecting
+     * `remote.settings` unparks on it, which is what most benches need; the
+     * describe answer is the same one the shared mirror would read.
+     */
+    settings: {
+        describe(): Promise<{
+            ok: true;
+            value: {
+                writable: boolean;
+                hasDocument: boolean;
+                namespaces: readonly View[];
+            };
+        }>;
+        update(ns: string, patch: unknown, expectedRevision: number | undefined): Promise<{
+            ok: true;
+            value: View;
+        } | {
+            ok: false;
+            error: {
+                code: string;
+                message: string;
+                details: object;
+            };
+        }>;
+        replace(ns: string, section: unknown, expectedRevision: number | undefined): Promise<{
+            ok: true;
+            value: View;
+        } | {
+            ok: false;
+            error: {
+                code: string;
+                message: string;
+                details: object;
+            };
+        }>;
+        mutate(ns: string, ops: unknown, expectedRevision: number | undefined): Promise<{
+            ok: true;
+            value: View;
+        } | {
+            ok: false;
+            error: {
+                code: string;
+                message: string;
+                details: object;
+            };
+        }>;
+    };
+    /** Spy behind `settings.update`, for argument assertions. */
+    update: ReturnType<typeof vi.fn>;
+    /** Spy behind `settings.replace`, for argument assertions. */
+    replace: ReturnType<typeof vi.fn>;
+    /** Spy behind `settings.mutate`, for argument assertions. */
+    mutate: ReturnType<typeof vi.fn>;
+    /**
+     * Replace what the next describe answers with, as a Host commit would.
+     * @param namespaces - the namespace views to serve from now on.
+     */
+    publish(namespaces: readonly View[]): void;
+}
+/**
+ * Build a scripted `settings` Remote namespace for a bench. Each write answers
+ * with the addressed namespace unchanged, so a bench that only needs its
+ * plugins to activate scripts nothing; one asserting a write reads the
+ * corresponding spy or replaces the face.
+ * @param namespaces - namespace views the first describe answers with.
+ * @param options - deployment facts the describe answer reports.
+ * @returns the face and its controls.
+ */
+export declare function scriptedSettingsRemote<View extends ScriptedNamespace>(namespaces?: readonly View[], options?: {
+    writable?: boolean;
+    hasDocument?: boolean;
+}): ScriptedSettingsRemote<View>;
+//# sourceMappingURL=settings-remote.d.ts.map

package/lib/types/snapshot.d.ts

@@ -0,0 +1,14 @@
+import type { SnapshotSerializer } from 'vitest';
+/**
+ * The serializer plugin. Matches DOM elements whose subtree carries a scoped
+ * class or svg internals; serializes a normalized clone, which no longer
+ * matches, so printing falls through to the built-in DOM element serializer.
+ */
+export declare const domSnapshotSerializer: SnapshotSerializer;
+/**
+ * Register {@link domSnapshotSerializer} with vitest's expect (idempotent).
+ * SlotTestRuntime.create() calls this; specs that snapshot DOM outside the
+ * runtime import and call it themselves.
+ */
+export declare function registerDomSnapshotSerializer(): void;
+//# sourceMappingURL=snapshot.d.ts.map

package/lib/types/translate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Test double of the locale lookup chain: a translate stub over plain
+ * dictionaries, mirroring LocaleRuntime's resolution order (first dictionary
+ * that owns the key wins, then the key itself stays visible) and its
+ * `{name}` template interpolation. Specs stub the framework-injected `t`
+ * seat with `makeTranslate(zh, commonZh)` instead of re-implementing the
+ * chain per suite.
+ */
+/**
+ * Build a translate stub resolving through `dicts` in order (namespace
+ * first, then the shared common vocabulary), falling back to the key.
+ * @param dicts - dictionaries consulted in order.
+ * @returns the translate function (assignable to any `XxxProps['t']` seat).
+ */
+export declare function makeTranslate(...dicts: readonly Record<string, string>[]): (key: string, params?: Record<string, unknown>) => string;
+//# sourceMappingURL=translate.d.ts.map

package/lib/types/workspaces.d.ts

@@ -0,0 +1,107 @@
+import type { IWorkspaces, WorkspaceId, WorkspaceSnapshot, WorkspaceView } from '@qilin-agent/api-workspace-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { SnapshotStore } from '@qilin-agent/client-store';
+import type { FixtureSnapshot, Stabilizer } from './fixtures.ts';
+/** Writable test representation of the immutable Workspace Controller snapshot. */
+type WorkspaceFixtureSnapshot = FixtureSnapshot<WorkspaceSnapshot>;
+/** Callable command names on the production Workspace Controller face. */
+type WorkspaceAction = {
+    [Key in keyof IWorkspaces]: IWorkspaces[Key] extends (...args: never[]) => unknown ? Key : never;
+}[keyof IWorkspaces];
+/** Test replacement retaining one Controller command's parameters and result. */
+type WorkspaceStub<Key extends WorkspaceAction> = (...args: Parameters<IWorkspaces[Key]>) => ReturnType<IWorkspaces[Key]>;
+/**
+ * Workspaces test double. Implements the same IWorkspaces face features
+ * receive as `ctx.workspaces`, so a production face change breaks this
+ * double at compile time. Every action records into {@link
+ * TestWorkspaces.calls}; defaults are inert echoes — feature tests needing
+ * richer behavior replace them via {@link TestWorkspaces.stub}.
+ */
+export declare class TestWorkspaces implements IWorkspaces {
+    private readonly stabilize;
+    /** The useWorkspaces standard feed. */
+    readonly list: SnapshotStore<WorkspaceFixtureSnapshot>;
+    /** Calls observed on the action face, newest last. */
+    readonly calls: {
+        method: string;
+        args: unknown[];
+    }[];
+    /** Replaceable action seat: feature tests may stub richer behavior. */
+    private readonly stubs;
+    /**
+     * @param stabilize - the owning runtime's act wrapper.
+     */
+    constructor(stabilize: Stabilizer);
+    /**
+     * Update the workspace list state through an immer draft.
+     * @param mutate - draft mutator.
+     */
+    update(mutate: (draft: WorkspaceFixtureSnapshot) => void): Promise<void>;
+    /**
+     * Replace an action's behavior (the recorded call is still appended first).
+     * @param method - Controller action name (e.g. 'create').
+     * @param impl - replacement behavior.
+     */
+    stub<Key extends WorkspaceAction>(method: Key, impl: WorkspaceStub<Key>): void;
+    /**
+     * Create a Workspace (recorded). The default echoes a view derived from
+     * the input; stub for failure or list-coupled flows.
+     * @param input - the Host create payload.
+     * @returns the created Workspace view.
+     */
+    create(input: {
+        path: string;
+    }): Promise<WorkspaceView>;
+    /**
+     * Rename a Workspace (recorded). The default echoes a minimal view.
+     * @param workspaceId - target workspace.
+     * @param title - new title.
+     * @returns the updated view.
+     */
+    rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView>;
+    /**
+     * Delete a Workspace (recorded; default no-op).
+     * @param workspaceId - target workspace.
+     */
+    delete(workspaceId: WorkspaceId): Promise<void>;
+    /**
+     * Move a Workspace in display order (recorded; default no-op).
+     * @param workspaceId - Workspace to move.
+     * @param beforeWorkspaceId - Anchor; omitted appends.
+     */
+    insertBefore(workspaceId: WorkspaceId, beforeWorkspaceId?: WorkspaceId): Promise<void>;
+    /**
+     * Move an accounted session (recorded). The default echoes a minimal view.
+     * @param workspaceId - target workspace.
+     * @param sessionId - session to move.
+     * @param beforeSessionId - anchor; omitted appends.
+     * @returns the updated view.
+     */
+    insertSessionBefore(workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId): Promise<WorkspaceView>;
+    /**
+     * Archive a session (recorded). The default mirrors the production face's
+     * observable effect: the id joins the list state's archive set.
+     * @param sessionId - session to archive.
+     */
+    archiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unarchive a session (recorded). The default mirrors the production face's
+     * observable effect: the id leaves the list state's archive set.
+     * @param sessionId - session to unarchive.
+     */
+    unarchiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Pin a session (recorded). The default mirrors the production face's
+     * observable effect: the id leads the list state's pin set.
+     * @param sessionId - session to pin.
+     */
+    pinSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unpin a session (recorded). The default mirrors the production face's
+     * observable effect: the id leaves the list state's pin set.
+     * @param sessionId - session to unpin.
+     */
+    unpinSession(sessionId: SessionId): Promise<void>;
+}
+export {};
+//# sourceMappingURL=workspaces.d.ts.map