dsh-plugin-sessiongraph-sessions 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CC ZHAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Session-log indexer for the session-graph seam: turns `~/.dsh/sessions` into the SQLite index
+ * `dsh-plugin-sessiongraph-sqlite` reads.
+ *
+ * Registers **only an indexer**, never a store. Indexing is caller-initiated (`sessiongraph_index`)
+ * and never runs from a query: a full machine is hundreds of logs and more than a gigabyte of
+ * decompressed JSON, so it has its own timeout budget and the query path stays millisecond-fast.
+ *
+ * The index root is an opaque directory the caller names; `indexRoot` is where `index.db` lives, and
+ * `sessionsRoot` (the harness's own log directory) is a separate, configurable input. That split is
+ * what lets a test build a fixture-driven index without a real `~/.dsh`.
+ *
+ * A run is incremental by default — only logs whose mtime or size moved are re-read — and `force`
+ * rebuilds every log into a temporary file that replaces the old index atomically. A single bad log
+ * is reported in `failed` and never aborts the run.
+ *
+ * Every session creation also refreshes an **existing** index in the background (`agent/created`,
+ * `autoIndex`): a machine that already has one stays fresh without the model remembering to ask. A
+ * missing index is deliberately left alone — the first build reads every log on the machine and is
+ * the caller's explicit decision (`sessiongraph_index`), not something to trigger on a session start.
+ *
+ * Sessions the host still holds in memory (`ctx.sessionQuery`) are indexed as well, in a second pass
+ * after the file-path transaction commits: a conversation that is still running has no log on disk
+ * yet, and "where did I say X" has to include what was just typed. That pass is optional — a host
+ * without the service leaves the file-path result exactly as it was, and one that fails degrades to
+ * it instead of failing the run.
+ *
+ * An explicit run is handed to the host's background-job registry too once the store is large enough
+ * (`backgroundIndexThreshold`), because a run that grows past a tool's timeout budget must not hold
+ * that call open. The seam types `index()` as returning a report, so a delegated run comes back as a
+ * report carrying `jobId` — see {@link isBackgroundIndexReport} for the discrimination a consumer
+ * needs, and {@link SessiongraphBackgroundIndexReport} for what its other fields then mean.
+ * @module dsh-plugin-sessiongraph-sessions
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { SessiongraphIndexer, SessiongraphIndexOptions, SessiongraphIndexReport } from 'dsh-plugin-sessiongraph-service';
+export { decompressSessionLog, parseSessionLog } from './parse.ts';
+export type { ParsedEntry, ParsedSession, SessionParseLimits } from './parse.ts';
+export { scanSessions } from './scan.ts';
+export type { SessionFile } from './scan.ts';
+export { LIVE_SOURCE_PREFIX } from './live.ts';
+export type { LiveIndexOptions, LiveIndexResult, SessionQueryService } from './live.ts';
+export { readIndexState, STATUS_RELATIVE_PATH, writeIndex } from './write.ts';
+export type { ExistingSession, IndexWritePlan, IndexWriteResult, IndexedSession } from './write.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "sessiongraph-sessions";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Default branded identity this indexer reserves on the seam. */
+export declare const DEFAULT_INDEXER_ID = "sessiongraph-sessions";
+/** Default harness session directory. */
+export declare const DEFAULT_SESSIONS_ROOT: string;
+/**
+ * Default index root, matching the tool's own default so a stock profile's automatic refresh writes
+ * where its queries read. A deployment that moves one must move the other.
+ */
+export declare const DEFAULT_INDEX_ROOT: string;
+/** Stable job kind of a background index run, used for retention and diagnostics. */
+export declare const AUTO_INDEX_JOB_KIND = "sessiongraph-index";
+/** Default number of session logs at which a manual index run becomes a background job. */
+export declare const DEFAULT_BACKGROUND_INDEX_THRESHOLD = 1000;
+/**
+ * Default cap on live sessions rebuilt per run. A host normally reports one or two; the cap exists
+ * because replaying a live log is not incremental and a host could report many.
+ */
+export declare const DEFAULT_MAX_LIVE_SESSIONS = 8;
+/** Engine selection: prefer the native kernel, only the TypeScript indexer, or decide per machine. */
+export type SessiongraphEngineSetting = 'auto' | 'native' | 'typescript';
+/** Which engine produced one run's report. */
+export type SessiongraphIndexEngine = 'native' | 'typescript';
+/** Default engine selection. */
+export declare const DEFAULT_ENGINE: SessiongraphEngineSetting;
+/** Default cap on stored message text, in characters. */
+export declare const DEFAULT_MAX_ENTRY_CHARS = 4000;
+/** Default cap on stored tool-invocation text, in characters. */
+export declare const DEFAULT_TOOL_CALL_CHARS = 2000;
+/**
+ * Default cap on one compressed log file, in bytes. The largest session on a real machine is ~42MB
+ * decompressed from ~13MB compressed, so 64MB leaves room for a long-running session without
+ * letting a pathological log exhaust memory in one decompress.
+ */
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+/** Plugin configuration. */
+export interface Config {
+    /** Directory the harness writes its session logs to (default `~/.dsh/sessions`). */
+    sessionsRoot?: string;
+    /**
+     * Index root the automatic refresh reads and refreshes (default `~/.dsh/sessiongraph`). Queries
+     * route on the root the tool passes, so this must name the same directory as the tool's
+     * `indexRoot` or the refresh maintains an index nothing reads.
+     */
+    indexRoot?: string;
+    /** Longest message text stored whole; longer text is clipped (default 4000). */
+    maxEntryChars?: number;
+    /** Longest tool invocation (name plus arguments) stored whole (default 2000). */
+    toolCallChars?: number;
+    /** Logs larger than this are skipped and reported in `failed` (default 67108864). */
+    maxFileBytes?: number;
+    /**
+     * Refresh an existing index in the background whenever a session is created (default true). A
+     * machine with no index yet is skipped on purpose — see {@link DEFAULT_INDEX_ROOT}.
+     */
+    autoIndex?: boolean;
+    /**
+     * Hand an explicit index run to the host's background-job registry once the session store holds at
+     * least this many logs (default 1000). Below it the run is synchronous, because a small index is
+     * faster than the round-trip through `job_output`.
+     */
+    backgroundIndexThreshold?: number;
+    /**
+     * Most live (still-running) sessions to rebuild per run (default 8). They come from the host's
+     * `ctx.sessionQuery` and are always rebuilt in full, so the cap bounds the replay cost.
+     */
+    maxLiveSessions?: number;
+    /**
+     * Which index engine to run (default `auto`): the native Rust kernel when this machine has a
+     * loadable build, else the TypeScript indexer. `native` asks for the kernel explicitly and logs
+     * once when it cannot be used before falling back; `typescript` never probes the kernel at all.
+     */
+    engine?: SessiongraphEngineSetting;
+}
+export declare const Config: z<Config>;
+/** Configuration after the schema filled in every default. */
+export type ResolvedConfig = Required<Config>;
+/**
+ * Register the session-log indexer.
+ * @param ctx - the plugin context (must inject `sessiongraph`).
+ * @param config - the resolved plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+/**
+ * Build the indexer object this plugin registers.
+ * @param ctx - the plugin context; only its optional `jobs` service is consulted.
+ * @param config - the resolved plugin configuration.
+ * @returns the seam provider.
+ */
+export declare function createIndexer(ctx: Context, config: ResolvedConfig): SessiongraphIndexer;
+/**
+ * The report a backgrounded index run returns. The seam types `index()` as returning a report, which
+ * is what a caller awaits; a run that was delegated instead comes back with this extra field, and a
+ * consumer distinguishes the two cases through {@link isBackgroundIndexReport}.
+ */
+export interface SessiongraphBackgroundIndexReport extends SessiongraphIndexReport {
+    /** Id of the background job that owns the run. */
+    readonly jobId: string;
+}
+/**
+ * Whether an index result came from a delegated run rather than a completed one.
+ *
+ * The seam's return type is the completed report, so a job id can only arrive as an extension of it;
+ * every other field of a delegated result describes the index as it stood when the job started.
+ * @param report - the value `ctx.sessiongraph.index()` resolved with.
+ * @returns true when the run is still going in the host's job registry.
+ */
+export declare function isBackgroundIndexReport(report: SessiongraphIndexReport): report is SessiongraphBackgroundIndexReport;
+/**
+ * Build or refresh one index.
+ * @param indexRoot - directory to write `index.db` into.
+ * @param options - scope and rebuild switches.
+ * @param signal - aborts between sessions.
+ * @param config - the resolved plugin configuration.
+ * @param ctx - the plugin context, consulted for the optional live-session source. Omitted by
+ *   callers that only exercise the file path, which then behave exactly as an older host would.
+ * @returns what the run did.
+ */
+export declare function runIndex(indexRoot: string, options: SessiongraphIndexOptions, signal: AbortSignal | undefined, config: ResolvedConfig, ctx?: Context): Promise<SessiongraphIndexReport>;
+/**
+ * Whether a session's workspace matches an optional workspace filter.
+ *
+ * An exact match always counts. A value without a trailing separator is also a path prefix, which is
+ * how one indexed root serves the whole `~/www` subtree; a value with the trailing separator is the
+ * exact directory only.
+ * @param filter - configured workspace filter, or undefined for "every workspace".
+ * @param workspace - the session's working directory.
+ * @returns whether the session is in scope.
+ */
+export declare function matchesWorkspace(filter: string | undefined, workspace: string): boolean;
+/**
+ * Whether a session id matches an optional id filter (full id or any prefix).
+ * @param filter - configured session filter, or undefined for "every session".
+ * @param id - the session's id.
+ * @returns whether the session is in scope.
+ */
+export declare function matchesSession(filter: string | undefined, id: string): boolean;
+//# sourceMappingURL=index.d.ts.map