dsh-plugin-sessiongraph-tool 0.0.0-stage → 0.1.1

package/lib/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Model-facing `sessiongraph` tool family over `ctx.sessiongraph`. The `sessiongraph` tool is
+ * read-only, with five operations — `search`, `session`, `timeline`, `workspaces`, `status` — that
+ * answer from a pre-built index of every local conversation. A second tool, `sessiongraph_index`,
+ * builds or refreshes that index on explicit request; it is separate so it can carry its own, much
+ * larger timeout budget than a query, because `defineTool`'s `timeoutMs` is fixed per registration,
+ * not per call, and one budget cannot fit both a millisecond query and a whole-machine index run.
+ *
+ * The tools own every default the seam refuses to guess — the per-operation result limits, the cap on
+ * a snippet — so the seam's requests stay fully specified and a deployment can retune what the model
+ * reads without touching a store. They inject only `tools`, `sessiongraph`, and `systemPrompt`, and
+ * import no store: which index answers is the seam's routing decision.
+ *
+ * Namespace plugin (named exports, no default export).
+ * @module dsh-plugin-sessiongraph-tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { SessiongraphRequest, SessiongraphService } from 'dsh-plugin-sessiongraph-service';
+import type { SessiongraphToolArgs } from './schema.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sessiongraph: SessiongraphService;
+    }
+}
+export { SESSIONGRAPH_DEFAULT_LIMITS, SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_INDEX_PARAMETERS, SESSIONGRAPH_OPERATIONS, SESSIONGRAPH_OUTPUT_SCHEMA, SESSIONGRAPH_PARAMETERS, SESSIONGRAPH_TOOL_OPERATIONS, type SessiongraphIndexToolArgs, type SessiongraphQueryOperation, type SessiongraphToolArgs, type SessiongraphToolOperation, type SessiongraphToolValue, type SessiongraphValueFor, } from './schema.ts';
+export { clipText, formatBytes, formatDuration, formatLiveReplay, formatLiveSessions, formatTime, renderSessiongraph, STALE_NOTE, } from './render.ts';
+export type { RenderOptions } from './render.ts';
+export { LazyIndexRefresher } from './refresh.ts';
+export type { LazyRefreshDeps, RefreshOutcome, SynchronousIndexOptions } from './refresh.ts';
+export { COMMAND_DEFINITION_ID, COMMAND_DESCRIPTION, COMMAND_INPUT_HINT, COMMAND_NAME, COMMAND_USAGE, INJECTED_NOTICE_PLUGIN, indexReportText, invocationWorkspace, parseCommand, registerCommands, runCommand, searchText, statusText, workspacesText, } from './command.ts';
+export type { CommandDefinition, CommandDefinitionId, CommandInvocation, CommandOptions, CommandPlan, CommandRegistry, CommandResult, } from './command.ts';
+export { indexStatusHint, readIndexStatus } from './status-hint.ts';
+export type { IndexStatusFile } from './status-hint.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "tool-sessiongraph";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Default directory the index lives in, before `~` expansion. */
+export declare const DEFAULT_INDEX_ROOT = "~/.dsh/sessiongraph";
+/** Default tool-call timeout budget (ms) for the query-side `sessiongraph` tool. */
+export declare const DEFAULT_SESSIONGRAPH_TOOL_TIMEOUT_MS = 30000;
+/** Default timeout budget (ms) for the `sessiongraph_index` tool. Indexing every local session is a different order of work than a query. */
+export declare const DEFAULT_SESSIONGRAPH_INDEX_TIMEOUT_MS = 300000;
+/** Largest `limit` honored when the plugin config names none. */
+export declare const DEFAULT_MAX_LIMIT = 100;
+/** Default character cap for one rendered snippet or session entry. */
+export declare const DEFAULT_MAX_SNIPPET_CHARS = 600;
+/**
+ * Default age (ms) at which a query refreshes the index before answering. The indexer keeps a
+ * brand-new *session* cheap to find by refreshing on session creation, but the session currently
+ * being written has no successor yet; five minutes is the point where "did we just say that" would
+ * otherwise land on an index that predates the conversation.
+ */
+export declare const DEFAULT_FRESHNESS_THRESHOLD_MS = 300000;
+/** The stable system-prompt guidance positioning the session index against grepping session files. */
+export declare const SESSIONGRAPH_PROMPT_TEXT: string;
+/** Plugin configuration: the defaults and caps the seam requires the consumer to own. */
+export interface Config {
+    /** Directory holding the index (default `~/.dsh/sessiongraph`). `~` is expanded at load. */
+    indexRoot?: string;
+    /** Largest `limit` honored, whatever the model asks for (default 100). */
+    maxLimit?: number;
+    /** Longest snippet or session entry shown per item before it is clipped with `…` (default 600). */
+    maxSnippetChars?: number;
+    /**
+     * Age (ms) past which a query runs one incremental index before answering (default 300000). `0`
+     * disables the lazy refresh entirely: queries then trust the indexer's own schedule.
+     */
+    freshnessThresholdMs?: number;
+    /** Tool-call timeout budget in ms for the query-side `sessiongraph` tool (default 30000). */
+    timeoutMs?: number;
+    /** Tool-call timeout budget in ms for the `sessiongraph_index` tool (default 300000). */
+    indexTimeoutMs?: number;
+}
+export declare const Config: z<Config>;
+/**
+ * Register both tools and the system-prompt guidance.
+ * @param ctx - the plugin context (must inject `tools`, `sessiongraph`, `systemPrompt`).
+ * @param config - the resolved plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+/**
+ * The one-line label a pending call shows.
+ * @param args - the validated tool arguments.
+ * @returns the card title naming the operation and whichever subject the operation takes.
+ */
+export declare function callTitle(args: SessiongraphToolArgs): string;
+/**
+ * Turn the model's snake_case arguments into the seam's camelCase request, applying the per-operation
+ * defaults the seam refuses to guess.
+ *
+ * Conditional requirements live here rather than in the parameter schema, because the parameter DSL
+ * has no per-operation conditionals: `search` needs `query`, `session` needs `session_id`, and a call
+ * missing either is rejected before it can reach a store.
+ * @param args - the validated tool arguments.
+ * @param indexRoot - absolute directory the index lives in.
+ * @param maxLimit - largest `limit` honored, whatever the model asked for.
+ * @returns the normalized request.
+ */
+export declare function buildRequest(args: SessiongraphToolArgs, indexRoot: string, maxLimit: number): SessiongraphRequest;
+//# sourceMappingURL=index.d.ts.map