@xirang-ai/dsh-teamflow 0.1.1 → 0.1.2

package/lib/store/model.js

@@ -41,6 +41,10 @@ export const BUG_SEVERITIES = ['blocker', 'critical', 'major', 'minor', 'trivial
 export const DOC_KINDS = ['flow', 'data', 'interface', 'page', 'rule'];
 /** Why a requirement is linked to a conversation. */
 export const REQUIREMENT_SESSION_KINDS = ['create', 'design', 'detail', 'split'];
+/** Which kind of record a discussion conversation belongs to. */
+export const DISCUSSION_SUBJECT_TYPES = ['requirement', 'story', 'bug'];
+/** Discussion kind used by stories and defects; requirements keep their own kinds. */
+export const GENERAL_DISCUSSION_KIND = 'discuss';
 /** A rejected domain operation, separate from SQLite or Host failures. */
 export class WorkflowError extends Error {
     /** Machine-readable reason for tools and the Web UI. */

package/lib/store/paths.d.ts

@@ -2,6 +2,8 @@
 export declare const PLUGIN_HOME_SEGMENTS: readonly ["xirang-ai", "dsh-teamflow"];
 /** Database file name inside the plugin data directory. */
 export declare const DATABASE_FILENAME = "teamflow.sqlite";
+/** Directory name of the markdown documents below the plugin data directory. */
+export declare const DOCS_DIRNAME = "docs";
 /** Human-readable directory of the durable data, e.g. `$DSH_HOME/xirang-ai/dsh-teamflow`. */
 export declare function defaultDataDir(): string;
 /**
@@ -13,6 +15,24 @@ export declare function defaultDataDir(): string;
  * @returns the absolute data directory.
  */
 export declare function resolveDataDir(configured?: string): string;
+/** Default document root: `<dataDir>/docs`, next to the database. */
+export declare function defaultDocsDir(dataDir: string): string;
+/**
+ * Resolve the document root: an explicit `Config.docsDir` wins, otherwise
+ * `<dataDir>/docs`. Relative overrides resolve against the process working
+ * directory and `~/` is expanded, mirroring {@link resolveDataDir}.
+ *
+ * Validation is loud on purpose: a malformed override or a path that is
+ * already a file fails plugin load with the field name and the accepted forms
+ * instead of silently falling back to the default directory.
+ *
+ * @param configured - `Config.docsDir`, possibly empty.
+ * @param dataDir - the resolved data directory.
+ * @returns the absolute document root.
+ */
+export declare function resolveDocsDir(configured: string | undefined, dataDir: string): string;
+/** Create the document root (owner-only) and return it. */
+export declare function ensureDocsDir(docsDir: string): string;
 /** Absolute database file path for a resolved data directory. */
 export declare function databaseFile(dataDir: string): string;
 /** Create the data directory (owner-only) and return it. */

package/lib/store/paths.js

@@ -9,13 +9,16 @@
  * @module
  */
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
-import { mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
+import { describeError } from "../errors.js";
 /** Path segments below `$DSH_HOME` that this plugin owns. */
 export const PLUGIN_HOME_SEGMENTS = ['xirang-ai', 'dsh-teamflow'];
 /** Database file name inside the plugin data directory. */
 export const DATABASE_FILENAME = 'teamflow.sqlite';
+/** Directory name of the markdown documents below the plugin data directory. */
+export const DOCS_DIRNAME = 'docs';
 /** Human-readable directory of the durable data, e.g. `$DSH_HOME/xirang-ai/dsh-teamflow`. */
 export function defaultDataDir() {
     return dshHomePath(...PLUGIN_HOME_SEGMENTS);
@@ -38,6 +41,56 @@ export function resolveDataDir(configured) {
         return join(homedir(), trimmed.slice(2));
     return resolve(trimmed);
 }
+/** Default document root: `<dataDir>/docs`, next to the database. */
+export function defaultDocsDir(dataDir) {
+    return join(dataDir, DOCS_DIRNAME);
+}
+/**
+ * Resolve the document root: an explicit `Config.docsDir` wins, otherwise
+ * `<dataDir>/docs`. Relative overrides resolve against the process working
+ * directory and `~/` is expanded, mirroring {@link resolveDataDir}.
+ *
+ * Validation is loud on purpose: a malformed override or a path that is
+ * already a file fails plugin load with the field name and the accepted forms
+ * instead of silently falling back to the default directory.
+ *
+ * @param configured - `Config.docsDir`, possibly empty.
+ * @param dataDir - the resolved data directory.
+ * @returns the absolute document root.
+ */
+export function resolveDocsDir(configured, dataDir) {
+    const trimmed = configured?.trim() ?? '';
+    if (trimmed === '')
+        return defaultDocsDir(dataDir);
+    const expected = 'an absolute path, a path relative to the working directory, or a path starting with "~/"';
+    if (trimmed.includes('\0')) {
+        throw new Error(`teamflow: config "docsDir" must be ${expected}, got ${JSON.stringify(configured)}`);
+    }
+    let absolute;
+    if (trimmed === '~') {
+        absolute = homedir();
+    }
+    else if (trimmed.startsWith(`~${sep}`) || trimmed.startsWith('~/')) {
+        absolute = join(homedir(), trimmed.slice(2));
+    }
+    else {
+        absolute = resolve(trimmed);
+    }
+    if (existsSync(absolute) && !statSync(absolute).isDirectory()) {
+        throw new Error(`teamflow: config "docsDir" must point to a directory, but ${toDisplayPath(absolute)} is a file`);
+    }
+    return absolute;
+}
+/** Create the document root (owner-only) and return it. */
+export function ensureDocsDir(docsDir) {
+    try {
+        mkdirSync(docsDir, { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        throw new Error(`teamflow: could not create the docs directory ${toDisplayPath(docsDir)} (config "docsDir"): ${describeError(error)}`, { cause: error });
+    }
+    return docsDir;
+}
 /** Absolute database file path for a resolved data directory. */
 export function databaseFile(dataDir) {
     return join(dataDir, DATABASE_FILENAME);

package/lib/store/schema.js

@@ -22,7 +22,12 @@
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { DOC_ROOT } from "./docs.js";
+/**
+ * Document root of the released v10 migration. Migrations are a historical
+ * contract: v10 moved bodies into the workspace, and that path must stay
+ * exactly as published even though current documents live elsewhere.
+ */
+const LEGACY_DOC_ROOT = '.xirang-ai/dsh-teamflow';
 /**
  * Roles every fresh database starts with. `name` is the default label; the
  * Workbench UI localizes built-in keys through its locale dictionaries, so a
@@ -564,7 +569,7 @@ function relocateV10Bodies(db, designs, docs) {
             updateRequirement.run(primary.contentPath, requirementId);
             continue;
         }
-        const target = `${DOC_ROOT}/requirements/${requirementId}/requirement.md`;
+        const target = `${LEGACY_DOC_ROOT}/requirements/${requirementId}/requirement.md`;
         try {
             let body = readFileSync(absolute(root, primary.contentPath), 'utf8');
             for (const extra of group.slice(1)) {
@@ -589,7 +594,7 @@ function relocateV10Bodies(db, designs, docs) {
         const root = roots.get(requirementId);
         if (root === undefined || doc.contentPath === '')
             continue;
-        const target = `${DOC_ROOT}/requirements/${requirementId}/docs/${doc.id}.md`;
+        const target = `${LEGACY_DOC_ROOT}/requirements/${requirementId}/docs/${doc.id}.md`;
         try {
             if (!existsSync(absolute(root, doc.contentPath)))
                 continue;
@@ -809,6 +814,50 @@ const SCHEMA_V16 = `
 ALTER TABLE stories ADD COLUMN create_session_id TEXT;  -- 创建该故事的 DSH 会话 id；历史数据为 NULL
 ALTER TABLE bugs ADD COLUMN create_session_id TEXT;  -- 创建该缺陷的 DSH 会话 id；历史数据为 NULL
 `;
+/**
+ * v17：讨论会话登记泛化为需求 / 故事 / 缺陷三类对象。
+ *
+ * 需求专属的 `requirement_sessions` 只能挂需求，而故事与缺陷也要能从详情页
+ * 发起讨论并回写正文。这里换成一张按 `(subject_type, subject_id, session_id)`
+ * 唯一的通用表：需求侧原有的 kind（create/design/detail/split）原样迁入，
+ * 故事与缺陷用 `discuss`。时间列沿用旧表的 TEXT ISO-8601，迁移不换算。
+ * 对象删除不再级联：列表按 `(subject_type, subject_id)` 查询，孤儿行不进任何列表。
+ */
+const SCHEMA_V17 = `
+CREATE TABLE discussion_sessions (                 -- 讨论对象与宿主会话的登记关系表
+  subject_type TEXT NOT NULL,                      -- 讨论对象类型：requirement / story / bug
+  subject_id   TEXT NOT NULL,                      -- 讨论对象 id（需求 / 故事 / 缺陷的业务 id）
+  session_id   TEXT NOT NULL,                      -- 宿主会话 id
+  kind         TEXT NOT NULL DEFAULT 'discuss',    -- 讨论类型：discuss 为通用讨论；需求侧沿用既有取值
+  prepared_at  TEXT,                               -- 两段式登记第一段：客户端写入的「待开始」时刻（ISO-8601 UTC）；创建会话行为 NULL
+  linked_at    TEXT,                               -- 两段式登记第二段：Agent 确认后的「已登记」时刻（ISO-8601 UTC）；NULL = 待开始
+  created_at   TEXT NOT NULL,                      -- 行首次创建时刻（ISO-8601 UTC）
+  PRIMARY KEY (subject_type, subject_id, session_id)
+);
+
+CREATE INDEX idx_discussion_sessions_subject
+  ON discussion_sessions (subject_type, subject_id, linked_at DESC);
+`;
+/** Copy every legacy requirement row into the generic table and drop it. */
+function migrateRequirementSessions(db) {
+    db.exec(SCHEMA_V17);
+    db.exec(`
+INSERT INTO discussion_sessions
+  (subject_type, subject_id, kind, session_id, prepared_at, linked_at, created_at)
+SELECT 'requirement', requirement_id, kind, session_id, prepared_at, linked_at, created_at
+FROM requirement_sessions;
+`);
+    const before = db.prepare('SELECT COUNT(*) AS count FROM requirement_sessions').get();
+    const after = db
+        .prepare("SELECT COUNT(*) AS count FROM discussion_sessions WHERE subject_type = 'requirement'")
+        .get();
+    const copied = Number(after?.['count'] ?? 0);
+    const expected = Number(before?.['count'] ?? 0);
+    if (copied !== expected) {
+        throw new Error(`teamflow: schema migration 17 copied ${copied} requirement session row(s) but the legacy table held ${expected}; rolling back`);
+    }
+    db.exec('DROP TABLE requirement_sessions');
+}
 export const MIGRATIONS = [
     {
         version: 1,
@@ -944,6 +993,13 @@ export const MIGRATIONS = [
             db.exec(SCHEMA_V16);
         },
     },
+    {
+        version: 17,
+        description: 'generalize discussion sessions to requirements, stories and bugs',
+        up: (db) => {
+            migrateRequirementSessions(db);
+        },
+    },
 ];
 /** Schema version this build expects; the last migration's version. */
 export const TARGET_SCHEMA_VERSION = MIGRATIONS.at(-1)?.version ?? 0;
@@ -985,24 +1041,25 @@ export const SCHEMA_COMMENTS = [
     { table: 'requirements', column: 'workspace_id', description: '所属 DSH 工作区 id（ctx.workspaces 的 WorkspaceView.workspaceId）；空串表示 v4 迁移之前写入的历史数据。' },
     { table: 'requirements', column: 'title', description: '需求标题。' },
     { table: 'requirements', column: 'summary', description: '澄清并总结后的一句话结论，供详细设计和故事引用。' },
-    { table: 'requirements', column: 'content_path', description: '正文（需求 + 概要设计）相对路径（工作区内，如 .xirang-ai/dsh-teamflow/requirements/<id>/requirement.md）。' },
+    { table: 'requirements', column: 'content_path', description: '正文（需求 + 概要设计）相对路径（文档根内，如 requirements/<id>/requirement.md）。' },
     { table: 'requirements', column: 'status', description: '状态：draft=进行中（仍在收集或修改），completed=用户确认完成，archived=已归档；完成不会自动发生。' },
     { table: 'requirements', column: 'created_at', description: '创建时间（ISO-8601 UTC）。' },
     { table: 'requirements', column: 'updated_at', description: '最后更新时间（ISO-8601 UTC）。' },
     { table: 'requirements', column: 'completed_at', description: '用户确认完成需求的时间（ISO-8601 UTC），未完成为 NULL。' },
-    { table: 'requirement_sessions', column: '', description: '需求与会话：创建需求（create）、概要设计讨论（design）、详细设计讨论（detail）和故事拆分讨论（split）都记在这里。' },
-    { table: 'requirement_sessions', column: 'requirement_id', description: '所属需求；删除需求时级联清理关联。' },
-    { table: 'requirement_sessions', column: 'session_id', description: 'DSH 会话 id，唯一；一个会话只属于一个需求。' },
-    { table: 'requirement_sessions', column: 'kind', description: '会话类型：create=创建需求，design=讨论概要设计，detail=讨论详细设计，split=讨论故事拆分。' },
-    { table: 'requirement_sessions', column: 'prepared_at', description: '浏览器创建讨论会话后写入待登记的时间（ISO-8601 UTC）；创建需求的会话为 NULL。' },
-    { table: 'requirement_sessions', column: 'linked_at', description: 'Agent 调用登记工具确认的时间（ISO-8601 UTC）；NULL 表示待开始，不进入历史列表。' },
-    { table: 'requirement_sessions', column: 'created_at', description: '首次绑定时间（ISO-8601 UTC）。' },
+    { table: 'discussion_sessions', column: '', description: '讨论对象与宿主会话的登记关系：需求、故事、缺陷的讨论会话都记在这里，两段式登记（浏览器准备、Agent 确认）。' },
+    { table: 'discussion_sessions', column: 'subject_type', description: '讨论对象类型：requirement=需求，story=故事，bug=缺陷；与 subject_id 一起标识对象。' },
+    { table: 'discussion_sessions', column: 'subject_id', description: '讨论对象 id（需求 / 故事 / 缺陷的业务 id）；对象删除时不级联清理。' },
+    { table: 'discussion_sessions', column: 'session_id', description: 'DSH 会话 id；同一对象与同一会话只有一行。' },
+    { table: 'discussion_sessions', column: 'kind', description: '讨论类型：create=创建需求，design=讨论概要设计，detail=讨论详细设计，split=讨论故事拆分，discuss=故事/缺陷的通用讨论。' },
+    { table: 'discussion_sessions', column: 'prepared_at', description: '浏览器创建讨论会话后写入待登记的时间（ISO-8601 UTC）；创建需求的会话为 NULL。' },
+    { table: 'discussion_sessions', column: 'linked_at', description: 'Agent 调用登记工具确认的时间（ISO-8601 UTC）；NULL 表示待开始，不进入历史列表。' },
+    { table: 'discussion_sessions', column: 'created_at', description: '首次绑定时间（ISO-8601 UTC）。' },
     { table: 'stories', column: '', description: '故事：可独立开发与交付的单元；父级是需求，也可以独立存在。' },
     { table: 'stories', column: 'id', description: 'nanoid 业务主键（sty_ 前缀）。' },
     { table: 'stories', column: 'workspace_id', description: '所属 DSH 工作区 id：有父级时继承并校验一致，独立故事创建时指定。' },
     { table: 'stories', column: 'requirement_id', description: '所属需求；为空表示用户直接提出的独立故事。' },
     { table: 'stories', column: 'title', description: '故事标题。' },
-    { table: 'stories', column: 'content_path', description: '故事正文相对路径：说明与验收标准写在同一份 story.md 里。' },
+    { table: 'stories', column: 'content_path', description: '故事正文相对路径（文档根内，如 stories/<id>/story.md）：说明与验收标准写在同一份 story.md 里。' },
     { table: 'stories', column: 'status', description: '状态：ready=待开发，developing=开发中，self_testing=自测中，done=执行完毕（未完成），completed=用户确认完成，cancelled=已取消。' },
     { table: 'stories', column: 'size', description: '拆分时的工作量档位：xs/s/m/l/xl。' },
     { table: 'stories', column: 'sort_order', description: '同一需求下的展示顺序，升序；新建取当前最大值 + 1，运行与状态流转不改它。' },
@@ -1013,7 +1070,7 @@ export const SCHEMA_COMMENTS = [
     { table: 'design_docs', column: 'requirement_id', description: '所属需求；删除需求时一并删除其文档。' },
     { table: 'design_docs', column: 'kind', description: '文档主题：flow=流程，data=数据，interface=接口，page=页面，rule=规则。' },
     { table: 'design_docs', column: 'title', description: '文档标题，工作台列表中一行显示。' },
-    { table: 'design_docs', column: 'content_path', description: '详设正文相对路径；正文很长，只落盘不进库。' },
+    { table: 'design_docs', column: 'content_path', description: '详设正文相对路径（文档根内，如 requirements/<req>/docs/<doc>.md）；正文很长，只落盘不进库。' },
     { table: 'design_docs', column: 'sort_order', description: '同一需求下的展示顺序，升序；新建取当前最大值 + 1，页面只按它渲染。' },
     { table: 'design_docs', column: 'created_at', description: '创建时间（ISO-8601 UTC）。' },
     { table: 'design_docs', column: 'updated_at', description: '最后更新时间（ISO-8601 UTC）。' },
@@ -1028,7 +1085,7 @@ export const SCHEMA_COMMENTS = [
     { table: 'bugs', column: 'id', description: 'nanoid 业务主键（bug_ 前缀）。' },
     { table: 'bugs', column: 'workspace_id', description: '所属 DSH 工作区 id：bug 独立存在，创建时必须显式给出。' },
     { table: 'bugs', column: 'title', description: 'bug 标题。' },
-    { table: 'bugs', column: 'content_path', description: '缺陷正文相对路径：描述、复现、期望、实际、环境都在这份 bug.md 里。' },
+    { table: 'bugs', column: 'content_path', description: '缺陷正文相对路径（文档根内，如 bugs/<id>/bug.md）：描述、复现、期望、实际、环境都在这份 bug.md 里。' },
     { table: 'bugs', column: 'severity', description: '严重程度：blocker/critical/major/minor/trivial。' },
     { table: 'bugs', column: 'status', description: '状态：reported=待修复，fixing=修复中，fixed=执行完毕（未完成），completed=用户确认完成，wontfix=不修复。' },
     { table: 'bugs', column: 'resolution', description: '修复结论、不修复原因或关闭说明。' },

package/lib/store/workflow.d.ts

@@ -19,17 +19,16 @@
  */
 import type { DatabaseSync } from 'node:sqlite';
 import { type PermissionTier } from '../permission-tier.ts';
-import { type Bug, type BugFilter, type BoardRows, type DeletePreview, type DeleteReport, type DeleteTarget, type CreateBugInput, type CreateDesignDocInput, type CreateRequirementInput, type CreateStoryInput, type DesignDoc, type FinishRunInput, type Requirement, type RequirementSession, type RequirementSessionKind, type UpdateDesignDocInput, type RequirementFilter, type Run, type RunFilter, type StartRunInput, type Story, type StoryFilter, type StoryReadiness, type UpdateBugInput, type UpdateRequirementInput, type UpdateStoryInput } from './model.ts';
+import { type Bug, type BugFilter, type BoardRows, type DeletePreview, type DeleteReport, type DeleteTarget, type DiscussionSession, type DiscussionSubjectType, type CreateBugInput, type CreateDesignDocInput, type CreateRequirementInput, type CreateStoryInput, type DesignDoc, type FinishRunInput, type Requirement, type RequirementSession, type RequirementSessionKind, type UpdateDesignDocInput, type RequirementFilter, type Run, type RunFilter, type StartRunInput, type Story, type StoryFilter, type StoryReadiness, type UpdateBugInput, type UpdateRequirementInput, type UpdateStoryInput } from './model.ts';
 /** Cap one batch so a single call cannot scan an unbounded id list. */
 export declare const MAX_DELETE_TARGETS = 50;
 /** Construction options for {@link WorkflowStore}. */
 export interface WorkflowStoreOptions {
     /**
-     * Root that holds `requirements/`, `stories/` and `bugs/` when a workspace
-     * directory is not known yet. Production wiring passes the
-     * workspace path instead (see {@link WorkflowStore.registerWorkspace}).
+     * Absolute document root that holds `requirements/`, `stories/` and
+     * `bugs/`. Every body lives here; records only store the root-relative path.
      */
-    readonly docsRoot?: string;
+    readonly docsRoot: string;
     /** Resolver used before the registry; lets the Host provide the live path. */
     readonly workspaceRoot?: (workspaceId: string) => string | undefined;
     /** Clock override for tests; must return an ISO-8601 UTC string. */
@@ -45,52 +44,78 @@ export interface WorkflowStoreOptions {
  */
 export declare class WorkflowStore {
     #private;
-    constructor(db: DatabaseSync, options?: WorkflowStoreOptions);
+    constructor(db: DatabaseSync, options: WorkflowStoreOptions);
     /**
-     * Remember where a workspace lives on disk. Documents are written into that
-     * directory, so this must be called before the first file-backed write;
-     * repeated calls with the same path are no-ops.
+     * Remember where a workspace lives on disk. Document bodies no longer live
+     * there, but the path is still recorded for display and for future
+     * workspace-scoped features; repeated calls with the same path are no-ops.
      */
     registerWorkspace(workspaceId: string, path: string): void;
-    /** Directory a workspace's documents live in, or null when unknown. */
+    /** Directory a registered workspace lives in, or null when unknown. */
     workspacePath(workspaceId: string): string | null;
     /**
-     * Read a document body by its workspace-relative path.
+     * Read a document body by its document-root-relative path.
      *
      * `null` means the file does not exist; `''` means it exists and is empty.
-     * A workspace without a directory is a configuration error, not a missing
-     * document, so it is reported as `file_error` instead of being folded into
-     * either empty result.
+     * Every record resolves against the one configured document root, so a
+     * legacy path simply misses instead of falling back to a workspace.
      */
-    readContent(workspaceId: string, relativePath: string): string | null;
+    readContent(relativePath: string): string | null;
     /** Rewrite a document body; the path comes from the row, so it is always current. */
-    writeContent(workspaceId: string, relativePath: string, body: string): void;
+    writeContent(relativePath: string, body: string): void;
     getRequirement(id: string): Requirement | null;
     listRequirements(filter?: RequirementFilter): Requirement[];
     /**
      * Register a browser-created session as a pending discussion for a requirement.
      *
+     * Kept as a thin wrapper over {@link prepareDiscussionSession} so the
+     * requirement page and its tests keep their existing shape.
+     */
+    prepareRequirementSession(requirementId: string, sessionId: string, kind?: RequirementSessionKind): RequirementSession;
+    /**
+     * Register a browser-created session as a pending discussion for a subject.
+     *
      * The browser creates the session first, then calls this before the user can
      * send the first message. The row stays invisible in `listBoard` until the
-     * Agent confirms it through {@link linkRequirementSession}.
+     * Agent confirms it through `teamflow_link_session`; this method never writes
+     * `linked_at`, so the client cannot skip Agent confirmation.
      */
-    prepareRequirementSession(requirementId: string, sessionId: string, kind?: RequirementSessionKind): RequirementSession;
+    prepareDiscussionSession(subjectType: DiscussionSubjectType, subjectId: string, sessionId: string, kind: string): DiscussionSession;
     /**
-     * Confirm the current session as a discussion of the requirement prepared for it.
+     * Confirm the current session as the discussion it was prepared for.
      *
-     * Called by `teamflow_link_requirement_session`; repeated calls are idempotent
-     * so a model retry cannot create duplicate history rows.
+     * Called by `teamflow_link_session`; repeated calls are idempotent so a model
+     * retry cannot rewrite the confirmation time.
+     */
+    linkDiscussionSession(sessionId: string): DiscussionSession;
+    /**
+     * Confirm the current session as a requirement discussion.
+     *
+     * Kept for `teamflow_link_requirement_session`; new callers use
+     * {@link linkDiscussionSession}.
      */
     linkRequirementSession(sessionId: string): RequirementSession;
-    /** Pending or linked conversation prepared for one session, or null. */
+    /** Pending or linked requirement conversation prepared for one session, or null. */
     getRequirementSession(sessionId: string): RequirementSession | null;
     /** The requirement linked to a session, whichever kind of link it is. */
     getRequirementBySession(sessionId: string): Requirement | null;
+    /** The discussion row bound to one session, or null when none exists. */
+    getDiscussionSession(sessionId: string): DiscussionSession | null;
+    /**
+     * Discussions under one subject, newest linked first.
+     *
+     * Pending rows are excluded by default so the workbench never shows a session
+     * the Agent has not started; tests and diagnostics can opt in.
+     */
+    listDiscussionSessions(subjectType: DiscussionSubjectType, subjectId: string, options?: {
+        readonly includeUnlinked?: boolean;
+        readonly kinds?: readonly string[];
+    }): DiscussionSession[];
     /**
-     * Conversations under one requirement, newest linked first.
+     * Requirement conversations under one requirement, newest linked first.
      *
-     * Pending design rows are excluded by default so the workbench never shows a
-     * session the Agent has not started; tests and diagnostics can opt in.
+     * The `create` row is always included: it explains where the requirement came
+     * from even though the Agent never confirms it.
      */
     listRequirementSessions(requirementId: string, options?: {
         readonly includePending?: boolean;