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

package/lib/schema.js

@@ -0,0 +1,267 @@
+/**
+ * The `sessiongraph` tool family's model-facing schemas: the parameters the model fills in, the
+ * per-operation defaults the seam refuses to guess, and the canonical value each operation returns.
+ *
+ * The query vocabulary itself is owned by the seam (`SESSIONGRAPH_OPERATIONS`,
+ * `SESSIONGRAPH_ENTRY_KINDS`) and re-exported here rather than copied, so adding an entry kind in the
+ * service package cannot leave the model's `kinds` filter behind. The output is a closed `oneOf` keyed
+ * on `operation`, not one loose object with every field optional, so a Code Mode program that switches
+ * on `operation` gets exactly the fields that operation produces and nothing it must test for.
+ * @module dsh-plugin-sessiongraph-tool/schema
+ */
+import { SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_OPERATIONS } from 'dsh-plugin-sessiongraph-service';
+export { SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_OPERATIONS };
+/**
+ * Every operation the tool family exposes: the seam's five query operations plus `index`, which lives
+ * on the dedicated `sessiongraph_index` tool because a full index run needs its own, much larger
+ * timeout budget than a query.
+ */
+export const SESSIONGRAPH_TOOL_OPERATIONS = [...SESSIONGRAPH_OPERATIONS, 'index'];
+/**
+ * Results returned per operation when the model names no `limit`.
+ *
+ * The seam requires a `limit` on every list request and has no opinion on its value, so the consumer
+ * owns the defaults: a search answers with a short, scannable list, a session with enough entries to
+ * be worth opening, and a workspace census with the whole machine in one page.
+ */
+export const SESSIONGRAPH_DEFAULT_LIMITS = {
+    search: 10,
+    session: 200,
+    timeline: 20,
+    workspaces: 50,
+};
+/** One session's metadata, as the timeline and session operations report it. */
+const SESSION_SUMMARY = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        session_id: { type: 'string', required: true },
+        title: { type: 'string' },
+        workspace: { type: 'string', required: true },
+        created_at: { type: 'integer', required: true },
+        last_at: { type: 'integer', required: true },
+        turns: { type: 'integer', required: true },
+        entries: { type: 'integer', required: true },
+        parent_session: { type: 'string' },
+        origin: { type: 'string' },
+        agent_preset: { type: 'string' },
+    },
+};
+/** The session object a `session` answer carries, marked required by its holder. */
+const REQUIRED_SESSION_SUMMARY = { ...SESSION_SUMMARY, required: true };
+/** One matched entry, with enough context to recognize it without a second query. */
+const HIT = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        session_id: { type: 'string', required: true },
+        title: { type: 'string' },
+        workspace: { type: 'string', required: true },
+        time: { type: 'integer', required: true },
+        kind: { type: 'string', required: true },
+        seq: { type: 'integer', required: true },
+        turn: { type: 'integer' },
+        snippet: { type: 'string', required: true },
+        length: { type: 'integer', required: true },
+    },
+};
+/** One indexed entry inside a session. */
+const ENTRY = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        seq: { type: 'integer', required: true },
+        time: { type: 'integer', required: true },
+        kind: { type: 'string', required: true },
+        turn: { type: 'integer' },
+        text: { type: 'string', required: true },
+        clipped: { type: 'boolean', required: true },
+    },
+};
+/** One workspace's coverage. */
+const WORKSPACE_STAT = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        workspace: { type: 'string', required: true },
+        sessions: { type: 'integer', required: true },
+        entries: { type: 'integer', required: true },
+        first_at: { type: 'integer', required: true },
+        last_at: { type: 'integer', required: true },
+    },
+};
+/** One source session an index run could not parse. */
+const FAILED_SESSION = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        path: { type: 'string', required: true },
+        reason: { type: 'string', required: true },
+    },
+};
+/** Bounds every truncatable member reports, so a capped answer is never read as a complete one. */
+const COUNTS = {
+    total: { type: 'integer', required: true },
+    truncated: { type: 'boolean', required: true },
+};
+/**
+ * Optional "this answer may predate the conversation" marker, set only when the query path tried an
+ * incremental refresh and could not finish one (it failed, or was handed to a background job). An
+ * answer from an index that is merely a little old keeps it absent: a boolean on every result that is
+ * almost always false is noise a model learns to ignore.
+ */
+const STALE = {
+    stale: { type: 'boolean' },
+};
+/**
+ * Build one `oneOf` member for a fixed operation name.
+ *
+ * Both type parameters are `const` so the member keeps its literal types: without them the helper
+ * would widen `operation` to the whole union and erase each member's own fields, and `InferValue`
+ * would produce one shapeless object instead of a discriminated union.
+ * @param operation - the literal `operation` value discriminating this member.
+ * @param properties - the fields this operation returns beyond the discriminant.
+ * @returns the member's value schema.
+ */
+function member(operation, properties) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            operation: { type: 'string', required: true, const: operation },
+            ...properties,
+        },
+    };
+}
+/** The canonical value every `sessiongraph` or `sessiongraph_index` call returns, keyed on `operation`. */
+export const SESSIONGRAPH_OUTPUT_SCHEMA = {
+    oneOf: [
+        member('search', {
+            hits: { type: 'array', required: true, items: HIT },
+            ...COUNTS,
+            ...STALE,
+        }),
+        member('session', {
+            session: REQUIRED_SESSION_SUMMARY,
+            entries: { type: 'array', required: true, items: ENTRY },
+            children: { type: 'array', required: true, items: { type: 'string' } },
+            truncated: { type: 'boolean', required: true },
+            ...STALE,
+        }),
+        member('timeline', {
+            sessions: { type: 'array', required: true, items: SESSION_SUMMARY },
+            truncated: { type: 'boolean', required: true },
+            ...STALE,
+        }),
+        member('workspaces', {
+            workspaces: { type: 'array', required: true, items: WORKSPACE_STAT },
+            total: { type: 'integer', required: true },
+            ...STALE,
+        }),
+        member('status', {
+            indexed: { type: 'boolean', required: true },
+            index_path: { type: 'string', required: true },
+            sessions: { type: 'integer', required: true },
+            entries: { type: 'integer', required: true },
+            workspaces: { type: 'integer', required: true },
+            // Always present: a store that cannot distinguish live sessions omits the seam field, and the
+            // tool answers `0` for it, which is what "nothing is running that this index covers" means.
+            live_sessions: { type: 'integer', required: true },
+            indexed_at: { type: 'integer' },
+            bytes: { type: 'integer', required: true },
+        }),
+        // An index run on a store large enough to outlive the call is handed to the host's background
+        // job registry, and the call answers before it has a report to give. `index` is therefore two
+        // members rather than one object with optional counts: the started member carries only what the
+        // call honestly knows — a job id — while the report member keeps every count required, so a
+        // renderer never invents a zero for a run that has not finished. "0 added" and "not run yet" are
+        // different answers and must stay distinguishable.
+        member('index', {
+            status: { type: 'string', required: true, const: 'started' },
+            job_id: { type: 'string', required: true },
+        }),
+        member('index', {
+            index_path: { type: 'string', required: true },
+            added: { type: 'integer', required: true },
+            updated: { type: 'integer', required: true },
+            skipped: { type: 'integer', required: true },
+            removed: { type: 'integer', required: true },
+            discovered: { type: 'integer', required: true },
+            failed: { type: 'array', required: true, items: FAILED_SESSION },
+            // Always present and normalized to 0 by the tool; the renderer omits the line at 0 so a routine
+            // incremental run does not print "replayed 0 live sessions" every time.
+            live_sessions: { type: 'integer', required: true },
+            entries: { type: 'integer', required: true },
+            sessions: { type: 'integer', required: true },
+            workspaces: { type: 'integer', required: true },
+            bytes: { type: 'integer', required: true },
+            elapsed_ms: { type: 'integer', required: true },
+        }),
+    ],
+};
+/**
+ * The parameters the model fills in for the query tool. Which ones apply depends on `operation`; the
+ * conditional requirements (`query` for `search`, `session_id` for `session`) are enforced when the
+ * request is built, because the parameter DSL has no per-operation conditionals.
+ */
+export const SESSIONGRAPH_PARAMETERS = {
+    operation: {
+        type: 'string',
+        required: true,
+        enum: [...SESSIONGRAPH_OPERATIONS],
+        description: 'search（跨会话全文检索）、session（按 id 或唯一前缀读一个会话）、timeline（按时间列会话，新→旧）、workspaces（工作区清单与统计）、status（索引自身状态）。status 是唯一在还没有索引时也能回答的操作；要建或刷新索引请调用 sessiongraph_index 工具。',
+    },
+    query: {
+        type: 'string',
+        description: 'search 必填：检索词。中文按双字切分，两字词即可命中（例如「广告」）。',
+    },
+    session_id: {
+        type: 'string',
+        description: 'session 必填：完整会话 id，或长到只指向一个会话的前缀。',
+    },
+    workspace: {
+        type: 'string',
+        description: '只看某个工作区：精确的 cwd，或不带结尾斜杠的路径前缀。',
+    },
+    after: {
+        type: 'number',
+        description: '只要这个 epoch 毫秒时间点之后（含）的条目/会话。',
+    },
+    before: {
+        type: 'number',
+        description: '只要这个 epoch 毫秒时间点之前（含）的条目/会话。',
+    },
+    kinds: {
+        type: 'array',
+        items: { type: 'string', enum: [...SESSIONGRAPH_ENTRY_KINDS] },
+        description: '只看这些条目类型：user（人真正打的字）、assistant（模型可见回复）、tool（工具调用的名字与参数）、title（会话标题）。省略即全部。',
+    },
+    limit: {
+        type: 'number',
+        description: '最多返回多少条；超出配置上限会被截断。省略按操作给默认值：search 10、timeline 20、workspaces 50、session 200 条 entries。',
+    },
+    offset: {
+        type: 'number',
+        description: '跳过前多少条，用于翻页。',
+    },
+};
+/**
+ * The parameters the dedicated `sessiongraph_index` tool takes: what to (re)build. It needs no
+ * `operation` — building the index is the only thing this tool does — and none of the query-side
+ * fields (`query`, `limit`, …), which an index run has no use for.
+ */
+export const SESSIONGRAPH_INDEX_PARAMETERS = {
+    force: {
+        type: 'boolean',
+        description: '全量重建：不跳过源文件自上次索引后没有变化的会话。',
+    },
+    workspace: {
+        type: 'string',
+        description: '只索引 cwd 匹配这个工作区（精确，或不带结尾斜杠的路径前缀）的会话。',
+    },
+    session_id: {
+        type: 'string',
+        description: '只索引一个会话，按完整 id 或唯一前缀。',
+    },
+};
+//# sourceMappingURL=schema.js.map

package/lib/status-hint.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The one line of index state this plugin contributes to the system prompt on every request.
+ *
+ * A model that has to call `status` before every query spends a tool round-trip learning something the
+ * host could have told it at assembly time. `ctx.systemPrompt.section` takes a function for exactly
+ * this case (`packages/tool/src/index.ts` passes one), and that function runs synchronously on every
+ * assembly — so this module must never reach the store: opening SQLite once per model request would
+ * put a database on the prompt-assembly path. It does one `stat` of the index file, plus (when an
+ * indexer left one) one small `status.json` read beside it.
+ *
+ * Nothing here is authoritative: the file system says an index exists, the index says what is in it.
+ * Three outcomes are deliberately distinguished — a summary, an index without a summary (built by a
+ * run that recorded no sidecar), and no index at all. Collapsing the middle case into "no index" would
+ * invite rebuilding an index that is already there.
+ * @module dsh-plugin-sessiongraph-tool/status-hint
+ */
+/** The facts a `status.json` sidecar carries, as this module reads them. */
+export interface IndexStatusFile {
+    /** Epoch milliseconds of the run that wrote the index. */
+    indexedAt: number;
+    /** Sessions in the index after that run. */
+    sessions: number;
+    /** Searchable entries after that run. */
+    entries: number;
+    /** Distinct workspaces after that run. */
+    workspaces: number;
+    /** Bytes the index file occupies. */
+    bytes: number;
+}
+/**
+ * Read an indexing run's persisted summary.
+ * @param indexRoot - the directory the index lives in.
+ * @returns the summary, or `undefined` when the file is absent, unreadable, or not shaped like one.
+ */
+export declare function readIndexStatus(indexRoot: string): IndexStatusFile | undefined;
+/**
+ * The state of the session index, phrased for a system prompt.
+ * @param indexRoot - the absolute directory holding the index (`~` already expanded by the caller).
+ * @returns one sentence naming the state, or what the model should do about it.
+ */
+export declare function indexStatusHint(indexRoot: string): string;
+//# sourceMappingURL=status-hint.d.ts.map

package/lib/status-hint.js

@@ -0,0 +1,100 @@
+/**
+ * The one line of index state this plugin contributes to the system prompt on every request.
+ *
+ * A model that has to call `status` before every query spends a tool round-trip learning something the
+ * host could have told it at assembly time. `ctx.systemPrompt.section` takes a function for exactly
+ * this case (`packages/tool/src/index.ts` passes one), and that function runs synchronously on every
+ * assembly — so this module must never reach the store: opening SQLite once per model request would
+ * put a database on the prompt-assembly path. It does one `stat` of the index file, plus (when an
+ * indexer left one) one small `status.json` read beside it.
+ *
+ * Nothing here is authoritative: the file system says an index exists, the index says what is in it.
+ * Three outcomes are deliberately distinguished — a summary, an index without a summary (built by a
+ * run that recorded no sidecar), and no index at all. Collapsing the middle case into "no index" would
+ * invite rebuilding an index that is already there.
+ * @module dsh-plugin-sessiongraph-tool/status-hint
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { INDEX_RELATIVE_PATH } from 'dsh-plugin-sessiongraph-service';
+import { formatBytes, formatTime } from "./render.js";
+/**
+ * Optional summary an indexer may leave beside `index.db` after a successful run.
+ *
+ * The design contract only requires the `meta` table inside the index, which cannot be read without
+ * opening the database — exactly what prompt assembly must not do. A writer that wants the richer
+ * prompt line therefore persists the same facts as JSON here; a writer that does not leaves it absent,
+ * and the hint degrades to the honest "index exists, no status record" wording instead of guessing.
+ */
+const STATUS_RELATIVE_PATH = 'status.json';
+/**
+ * Read an indexing run's persisted summary.
+ * @param indexRoot - the directory the index lives in.
+ * @returns the summary, or `undefined` when the file is absent, unreadable, or not shaped like one.
+ */
+export function readIndexStatus(indexRoot) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(indexRoot, STATUS_RELATIVE_PATH), 'utf8'));
+    }
+    catch {
+        // Absent, unreadable, or not JSON: all three mean "no summary to trust", which the caller renders
+        // as the weaker statement rather than as an error. A prompt line must never fail an assembly.
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const indexedAt = numberField(record, 'indexedAt');
+    const sessions = numberField(record, 'sessions');
+    const entries = numberField(record, 'entries');
+    const workspaces = numberField(record, 'workspaces');
+    const bytes = numberField(record, 'bytes');
+    if (indexedAt === undefined || sessions === undefined || entries === undefined
+        || workspaces === undefined || bytes === undefined)
+        return undefined;
+    return { indexedAt, sessions, entries, workspaces, bytes };
+}
+/**
+ * One numeric field of a parsed object, or `undefined` when it is absent or not a finite number.
+ * @param record - the parsed object.
+ * @param field - the field name to read.
+ * @returns the number, or `undefined`.
+ */
+function numberField(record, field) {
+    const value = record[field];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** The size and modification time of one file, or `undefined` when it does not exist. */
+function statFile(path) {
+    try {
+        const stats = statSync(path);
+        return { size: stats.size, mtimeMs: stats.mtimeMs };
+    }
+    catch {
+        // Missing, or a directory in the way, or no permission: all mean "cannot claim an index here".
+        return undefined;
+    }
+}
+/**
+ * The state of the session index, phrased for a system prompt.
+ * @param indexRoot - the absolute directory holding the index (`~` already expanded by the caller).
+ * @returns one sentence naming the state, or what the model should do about it.
+ */
+export function indexStatusHint(indexRoot) {
+    const indexPath = join(indexRoot, INDEX_RELATIVE_PATH);
+    const index = statFile(indexPath);
+    if (index === undefined) {
+        return `这台机器还没有 sessiongraph 索引（${indexPath}）。要检索过去的对话就先调用 sessiongraph_index 建一次：`
+            + '它会扫描 ~/.dsh/sessions 下的全部会话，首次可能要几分钟，走它自己的 300 秒预算。';
+    }
+    const status = readIndexStatus(indexRoot);
+    if (status !== undefined) {
+        return `索引就绪（${indexPath}）：${status.sessions} 个会话、${status.entries} 条可检索条目、`
+            + `${status.workspaces} 个工作区、${formatBytes(status.bytes)}；`
+            + `最近一次建索引 ${formatTime(status.indexedAt)}。`;
+    }
+    return `索引文件已存在（${indexPath}，${formatBytes(index.size)}，${formatTime(index.mtimeMs)} 更新），`
+        + '但没有 status 记录——规模与新鲜度用 sessiongraph status 查；怀疑过期时用 sessiongraph_index 刷新。';
+}
+//# sourceMappingURL=status-hint.js.map

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "dsh-plugin-sessiongraph-tool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Model-facing sessiongraph tools for DeepSeek Harness — a read-only sessiongraph tool that searches the whole local conversation history, plus a sessiongraph_index tool that builds or refreshes the index on its own, much larger timeout budget",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "session",
+    "session-history",
+    "conversation",
+    "search",
+    "fts",
+    "ai-agent",
+    "llm-tools",
+    "agent-tools"
+  ],
+  "license": "MIT",
+  "author": "CC ZHAO",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CC19990113/dsh-plugin-sessiongraph.git",
+    "directory": "packages/tool"
+  },
+  "homepage": "https://github.com/CC19990113/dsh-plugin-sessiongraph#readme",
+  "bugs": "https://github.com/CC19990113/dsh-plugin-sessiongraph/issues",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "dsh-plugin-sessiongraph-service": "^0.1.1",
+    "dsh-plugin-sessiongraph-sessions": "^0.1.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/dsh-invariants": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-timeout": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-timeout": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.