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

package/lib/schema.d.ts

@@ -0,0 +1,539 @@
+/**
+ * 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 type { InferArgs, InferValue } from '@deepseek-ai/dsh-tools';
+import { SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_OPERATIONS } from 'dsh-plugin-sessiongraph-service';
+import type { SessiongraphOperation } 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 declare const SESSIONGRAPH_TOOL_OPERATIONS: readonly ["search", "session", "timeline", "workspaces", "status", "index"];
+/** One operation across the tool family. */
+export type SessiongraphToolOperation = (typeof SESSIONGRAPH_TOOL_OPERATIONS)[number];
+/** One query-side operation, i.e. everything `sessiongraph` answers and `sessiongraph_index` does not. */
+export type SessiongraphQueryOperation = SessiongraphOperation;
+/**
+ * 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 declare const SESSIONGRAPH_DEFAULT_LIMITS: {
+    readonly search: 10;
+    readonly session: 200;
+    readonly timeline: 20;
+    readonly workspaces: 50;
+};
+/** The canonical value every `sessiongraph` or `sessiongraph_index` call returns, keyed on `operation`. */
+export declare const SESSIONGRAPH_OUTPUT_SCHEMA: {
+    readonly oneOf: readonly [{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "search";
+            };
+        } & {
+            readonly stale: {
+                readonly type: "boolean";
+            };
+            readonly total: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+            readonly hits: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly session_id: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly title: {
+                            readonly type: "string";
+                        };
+                        readonly workspace: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly time: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly seq: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly turn: {
+                            readonly type: "integer";
+                        };
+                        readonly snippet: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly length: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                    };
+                };
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "session";
+            };
+        } & {
+            readonly stale: {
+                readonly type: "boolean";
+            };
+            readonly session: {
+                readonly required: true;
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly session_id: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly workspace: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly created_at: {
+                        readonly type: "integer";
+                        readonly required: true;
+                    };
+                    readonly last_at: {
+                        readonly type: "integer";
+                        readonly required: true;
+                    };
+                    readonly turns: {
+                        readonly type: "integer";
+                        readonly required: true;
+                    };
+                    readonly entries: {
+                        readonly type: "integer";
+                        readonly required: true;
+                    };
+                    readonly parent_session: {
+                        readonly type: "string";
+                    };
+                    readonly origin: {
+                        readonly type: "string";
+                    };
+                    readonly agent_preset: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly entries: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly seq: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly time: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly turn: {
+                            readonly type: "integer";
+                        };
+                        readonly text: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly clipped: {
+                            readonly type: "boolean";
+                            readonly required: true;
+                        };
+                    };
+                };
+            };
+            readonly children: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "timeline";
+            };
+        } & {
+            readonly stale: {
+                readonly type: "boolean";
+            };
+            readonly sessions: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly session_id: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly title: {
+                            readonly type: "string";
+                        };
+                        readonly workspace: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly created_at: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly last_at: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly turns: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly entries: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly parent_session: {
+                            readonly type: "string";
+                        };
+                        readonly origin: {
+                            readonly type: "string";
+                        };
+                        readonly agent_preset: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly truncated: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "workspaces";
+            };
+        } & {
+            readonly stale: {
+                readonly type: "boolean";
+            };
+            readonly workspaces: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly workspace: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly sessions: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly entries: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly first_at: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                        readonly last_at: {
+                            readonly type: "integer";
+                            readonly required: true;
+                        };
+                    };
+                };
+            };
+            readonly total: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "status";
+            };
+        } & {
+            readonly indexed: {
+                readonly type: "boolean";
+                readonly required: true;
+            };
+            readonly index_path: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly sessions: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly entries: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly workspaces: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly live_sessions: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly indexed_at: {
+                readonly type: "integer";
+            };
+            readonly bytes: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "index";
+            };
+        } & {
+            readonly status: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "started";
+            };
+            readonly job_id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly operation: {
+                readonly type: "string";
+                readonly required: true;
+                readonly const: "index";
+            };
+        } & {
+            readonly index_path: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly added: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly updated: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly skipped: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly removed: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly discovered: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly failed: {
+                readonly type: "array";
+                readonly required: true;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly path: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                        readonly reason: {
+                            readonly type: "string";
+                            readonly required: true;
+                        };
+                    };
+                };
+            };
+            readonly live_sessions: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly entries: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly sessions: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly workspaces: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly bytes: {
+                readonly type: "integer";
+                readonly required: true;
+            };
+            readonly elapsed_ms: {
+                readonly type: "integer";
+                readonly 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 declare const SESSIONGRAPH_PARAMETERS: {
+    readonly operation: {
+        readonly type: "string";
+        readonly required: true;
+        readonly enum: readonly ["search", "session", "timeline", "workspaces", "status"];
+        readonly description: "search（跨会话全文检索）、session（按 id 或唯一前缀读一个会话）、timeline（按时间列会话，新→旧）、workspaces（工作区清单与统计）、status（索引自身状态）。status 是唯一在还没有索引时也能回答的操作；要建或刷新索引请调用 sessiongraph_index 工具。";
+    };
+    readonly query: {
+        readonly type: "string";
+        readonly description: "search 必填：检索词。中文按双字切分，两字词即可命中（例如「广告」）。";
+    };
+    readonly session_id: {
+        readonly type: "string";
+        readonly description: "session 必填：完整会话 id，或长到只指向一个会话的前缀。";
+    };
+    readonly workspace: {
+        readonly type: "string";
+        readonly description: "只看某个工作区：精确的 cwd，或不带结尾斜杠的路径前缀。";
+    };
+    readonly after: {
+        readonly type: "number";
+        readonly description: "只要这个 epoch 毫秒时间点之后（含）的条目/会话。";
+    };
+    readonly before: {
+        readonly type: "number";
+        readonly description: "只要这个 epoch 毫秒时间点之前（含）的条目/会话。";
+    };
+    readonly kinds: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+            readonly enum: readonly ["user", "assistant", "tool", "title"];
+        };
+        readonly description: "只看这些条目类型：user（人真正打的字）、assistant（模型可见回复）、tool（工具调用的名字与参数）、title（会话标题）。省略即全部。";
+    };
+    readonly limit: {
+        readonly type: "number";
+        readonly description: "最多返回多少条；超出配置上限会被截断。省略按操作给默认值：search 10、timeline 20、workspaces 50、session 200 条 entries。";
+    };
+    readonly offset: {
+        readonly type: "number";
+        readonly 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 declare const SESSIONGRAPH_INDEX_PARAMETERS: {
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "全量重建：不跳过源文件自上次索引后没有变化的会话。";
+    };
+    readonly workspace: {
+        readonly type: "string";
+        readonly description: "只索引 cwd 匹配这个工作区（精确，或不带结尾斜杠的路径前缀）的会话。";
+    };
+    readonly session_id: {
+        readonly type: "string";
+        readonly description: "只索引一个会话，按完整 id 或唯一前缀。";
+    };
+};
+/** The canonical value, inferred from {@link SESSIONGRAPH_OUTPUT_SCHEMA} so the two cannot drift. */
+export type SessiongraphToolValue = InferValue<typeof SESSIONGRAPH_OUTPUT_SCHEMA>;
+/** The validated arguments, inferred from {@link SESSIONGRAPH_PARAMETERS}. */
+export type SessiongraphToolArgs = InferArgs<typeof SESSIONGRAPH_PARAMETERS>;
+/** The validated arguments, inferred from {@link SESSIONGRAPH_INDEX_PARAMETERS}. */
+export type SessiongraphIndexToolArgs = InferArgs<typeof SESSIONGRAPH_INDEX_PARAMETERS>;
+/** The canonical value for one operation. */
+export type SessiongraphValueFor<O extends SessiongraphToolOperation> = Extract<SessiongraphToolValue, {
+    operation: O;
+}>;
+//# sourceMappingURL=schema.d.ts.map