dsh-reference-anything 0.3.1 → 0.3.2

package/lib/sources/local-agent/index.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Reference source over transcripts other coding agents leave on disk.
+ *
+ * Claude Code and Codex both write every session to a JSONL file under the home
+ * directory. Those files are the record of work the user already did, and until
+ * now the only way to bring one into a DSH session was to copy it in by hand.
+ * This registers them as referenceable items instead: the `@` menu lists them,
+ * and the body is read only when the model asks for it by reference.
+ *
+ * Reference-only by design. Nothing here writes into DSH's session store —
+ * importing a transcript is a different feature with different failure modes,
+ * and conflating the two would make every listed transcript a pending mutation.
+ *
+ * @module dsh-reference-anything/local-agent
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ReferenceRef, ReferenceSnapshot, ReferenceSource, ReferenceSummary, ReferenceWindow } from '../../types.ts';
+import type { AgentKind, ToolCallMode } from './types.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "reference-local-agent";
+/** The services this source is built on. */
+export declare const inject: string[];
+/** Registry id, and the `source` half of every reference this source owns. */
+export declare const LOCAL_AGENT_SOURCE_ID = "local-agent";
+/** Deployment settings for the local agent source. */
+export interface Config {
+    /** Agents whose default locations are searched. */
+    agents?: AgentKind[];
+    /** Extra directories to search, as `~/`-prefixed or absolute paths. */
+    extraRoots?: {
+        kind: AgentKind;
+        path: string;
+    }[];
+    /** Whether discovery is limited to transcripts recorded in this workspace. */
+    scope?: 'workspace' | 'all';
+    /** Transcripts a directory scan will consider. */
+    maxTranscripts?: number;
+    /** Turns one read may return, however many the caller asks for. */
+    maxReadTurns?: number;
+    /** Bytes a read may stream before falling back to a tail-anchored pass. */
+    maxScanBytes?: number;
+    /** Records wanted from the start of a transcript when probing for metadata. */
+    headLines?: number;
+    /** Records wanted from its end, where the newest title lives. */
+    tailLines?: number;
+    /** How far a probe may read chasing those records before giving up. */
+    maxProbeBytes?: number;
+    /** Longest single record that will be materialized; longer ones are skipped. */
+    maxLineBytes?: number;
+    /** How long one directory scan is reused across a typing burst. */
+    directoryTtlMs?: number;
+    /** Whether the model sees the other agent's reasoning. */
+    includeThinking?: boolean;
+    /** How a tool call and its result are projected into a turn. */
+    toolCalls?: ToolCallMode;
+    /** Whether subagent branches are projected alongside the main thread. */
+    includeSidechains?: boolean;
+    /** Whether harness-injected preambles are removed from user turns. */
+    stripEnvironmentPreamble?: boolean;
+    /** Whether the database-backed formats may be read at all. */
+    sqlite?: boolean;
+    /** Message rows one database read may materialize, counted from the end. */
+    maxSessionRecords?: number;
+}
+/**
+ * Runtime schema for {@link Config}.
+ *
+ * Roots are `~/`-prefixed strings expanded against the process's own home
+ * rather than paths resolved at authoring time, so a profile written on one
+ * machine still points somewhere sensible on another — and so an external
+ * overlay describing them cannot smuggle in an evaluated expression.
+ */
+export declare const Config: z<Config>;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        referenceLocalAgents: LocalAgentService;
+    }
+}
+/** Lists and reads other agents' transcripts from the local filesystem. */
+export declare class LocalAgentService extends Service implements ReferenceSource {
+    static inject: string[];
+    static Config: z<Config>;
+    readonly id = "local-agent";
+    /**
+     * Gated: these are other sessions' conversations, often from other projects.
+     * The model may read one only after its user named it.
+     */
+    readonly requiresGrant = true;
+    private readonly settings;
+    private readonly adapters;
+    private roots;
+    private readonly convert;
+    private cache;
+    private store;
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * @returns whether any configured root is a readable directory.
+     */
+    available(): Promise<boolean>;
+    /** Replace UI-managed extra roots while retaining every deployment root. */
+    setAgentDirectories(directories: Partial<Record<AgentKind, string>>): void;
+    /** Count transcripts recognized by the current roots, grouped by format. */
+    stats(signal?: AbortSignal): Promise<Array<{
+        kind: AgentKind;
+        conversations: number;
+    }>>;
+    /**
+     * List transcripts whose title or opening prompt matches `query`.
+     *
+     * Matching never touches a transcript's body. Ranking on body text would
+     * require reading every candidate on a keystroke, and an excerpt of one would
+     * put a conversation the user has not named in front of the model — the same
+     * invariant the web-chat source holds.
+     * @param query - case-insensitive substring; empty means the most recent.
+     * @param limit - maximum items to return.
+     * @param signal - cancellation from the caller.
+     * @returns matching transcripts, most relevant first, at most `limit`.
+     */
+    list(query: string, limit: number, signal?: AbortSignal): Promise<ReferenceSummary[]>;
+    /**
+     * The same discovery, for a caller that knows whose workspace it is asking on.
+     *
+     * {@link list} has nowhere to learn that from and falls back to the host
+     * process's own directory, which is right for a CLI started inside the project
+     * and wrong for a Web server serving sessions rooted anywhere on the machine.
+     * The `@` menu comes through here instead and passes the session's own cwd, so
+     * `scope: 'workspace'` means the user's workspace rather than the server's.
+     * @param query - case-insensitive substring; empty means the most recent.
+     * @param limit - maximum items to return.
+     * @param cwd - the asking session's working directory.
+     * @param signal - cancellation from the caller.
+     * @returns matching transcripts, most relevant first, at most `limit`.
+     */
+    listForWorkspace(query: string, limit: number, cwd: string, signal?: AbortSignal): Promise<ReferenceSummary[]>;
+    private listIn;
+    /** Durable discovery policy. Reads stay independent so granted old refs work. */
+    private enabledAgentKinds;
+    /**
+     * Read one window of turns from a transcript.
+     * @param ref - a reference this source owns; `ref.id` is `kind:relPath`.
+     * @param window - which turns to return.
+     * @param signal - cancellation from the caller.
+     * @returns the requested turns and their position in the conversation.
+     */
+    read(ref: ReferenceRef, window: ReferenceWindow, signal?: AbortSignal): Promise<ReferenceSnapshot>;
+    /**
+     * Read one window of turns out of a database-backed session.
+     *
+     * A database is not streamable the way a JSONL file is: there is no byte
+     * offset that means "the turn before this one", so the whole conversation is
+     * materialized under a record cap and then sliced. That is affordable for the
+     * same reason the cap exists — the cap is what bounds the memory, and it
+     * counts from the *end*, so the turns nearest the present are the ones kept.
+     * @param adapter - the adapter that knows this schema.
+     * @param descriptor - the database and session to read.
+     * @param sessionId - which conversation inside the database.
+     * @param limit - turns to return.
+     * @param before - exclusive upper bound in turn indices.
+     * @param signal - cancellation from the caller.
+     * @returns the same page shape a streamed read produces.
+     */
+    private readSession;
+    /** Reuse one directory scan across a typing burst. */
+    private scan;
+    /**
+     * Drop bookmarks whose transcripts are gone, but only after a complete scan.
+     *
+     * A scan that hit `maxTranscripts` reports the newest files, not all of
+     * them. Treating that list as everything on disk would evict the bookmark of
+     * every older transcript that is still there, and each would be re-probed
+     * the next time it surfaced — turning a cap on listing into a cache that can
+     * never warm.
+     */
+    private prune;
+    /**
+     * Pair each transcript with what is known about it, probing a bounded few.
+     *
+     * A transcript with no bookmark yet renders under a fallback label and is
+     * picked up by a later call, because probing all of them at once would put an
+     * unbounded read behind a keystroke.
+     */
+    private describe;
+    /** Read a transcript's two ends and fold them into a bookmark. */
+    private probe;
+    private summarize;
+    /**
+     * Resolve a reference id to a transcript inside a configured root.
+     *
+     * Containment is checked against the resolved real path, so neither a `..`
+     * segment nor a symlink out of a root can reach a file the deployment never
+     * offered.
+     */
+    private locate;
+}
+/**
+ * Register the local agent reference source.
+ * @param ctx - the mounting context.
+ * @param config - validated deployment settings.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+/** Compose the reference id from the two parts that identify a transcript. */
+export declare function referenceId(kind: AgentKind, relPath: string): string;
+/**
+ * Split a database-backed relative path into the file and the session in it.
+ *
+ * Only the last separator counts: a database's own filename is far more likely
+ * to contain a `#` than a session id is, and taking the last one keeps the id
+ * unambiguous either way.
+ * @param relPath - the relative path half of a reference id.
+ * @returns the database path and session id, or undefined when none was named.
+ */
+export declare function splitSession(relPath: string): {
+    relPath: string;
+    sessionId: string;
+} | undefined;
+/** Split a reference id back into its parts, or undefined when it is not one. */
+export declare function parseReferenceId(id: string): {
+    kind: AgentKind;
+    relPath: string;
+} | undefined;