dsh-session-messenger 0.4.2

package/schemas.generated.js

@@ -0,0 +1,290 @@
+// GENERATED by extract-specs.mjs from the host defineTool compiler. Do not edit by hand.
+// Regenerate: node extract-specs.mjs --write   Verify: node extract-specs.mjs --check
+
+export const CLAIM_FILES_PARAMETERS = {
+  "type": "object",
+  "properties": {
+    "paths": {
+      "type": "array",
+      "description": "File paths you intend to modify (at most 50). Workspace-relative paths resolve against this session cwd; absolute and ~/ paths are kept.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "ttl_seconds": {
+      "type": "number",
+      "description": "Claim lifetime in seconds; default 1800, clamped to [30, 86400]."
+    },
+    "note": {
+      "type": "string",
+      "description": "Short intent note shown to a conflicting session, e.g. \"refactoring exports\"."
+    },
+    "cwd": {
+      "type": "string",
+      "description": "Optional explicit absolute workspace root used to resolve relative paths; defaults to the calling session cwd."
+    }
+  },
+  "required": [
+    "paths"
+  ]
+};
+
+export const CLAIM_FILES_OUTPUT = {
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "sessionId": {
+      "type": "string"
+    },
+    "registered": {
+      "type": "boolean"
+    },
+    "expiresAt": {
+      "type": "integer"
+    },
+    "conflicts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "ownerSessionId": {
+            "type": "string"
+          },
+          "ownerLabel": {
+            "type": "string"
+          },
+          "ownerOrigin": {
+            "type": "string"
+          },
+          "expiresAt": {
+            "type": "integer"
+          },
+          "note": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path",
+          "ownerSessionId",
+          "ownerLabel",
+          "ownerOrigin",
+          "expiresAt",
+          "note"
+        ]
+      }
+    },
+    "hint": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "sessionId",
+    "registered",
+    "expiresAt",
+    "conflicts",
+    "hint"
+  ]
+};
+
+export const RELEASE_FILES_PARAMETERS = {
+  "type": "object",
+  "properties": {
+    "paths": {
+      "type": "array",
+      "description": "Specific paths to release (absolute or relative to this session cwd). Omit to release everything claimed by this session.",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+};
+
+export const RELEASE_FILES_OUTPUT = {
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "sessionId": {
+      "type": "string"
+    },
+    "released": {
+      "type": "integer"
+    },
+    "hint": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "sessionId",
+    "released",
+    "hint"
+  ]
+};
+
+export const SEND_TO_SESSION_PARAMETERS = {
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "description": "Target session id (exact, or a unique id prefix of at least 4 characters). On failure the tool lists reachable live sessions."
+    },
+    "content": {
+      "type": "string",
+      "description": "Message body for the target session. Be concrete: what you need, which files, and what you propose."
+    },
+    "mode": {
+      "type": "string",
+      "description": "'queue' (default) = appended as the target's next input, waiting for its current turn to end; 'steer' = inserted into the target's current step when it is running. Either mode starts a turn when the target is idle.",
+      "enum": [
+        "queue",
+        "steer"
+      ]
+    },
+    "topic": {
+      "type": "string",
+      "description": "Optional short topic label, e.g. \"claim conflict on src/x.ts\"."
+    }
+  },
+  "required": [
+    "target",
+    "content"
+  ]
+};
+
+export const SEND_TO_SESSION_OUTPUT = {
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "target": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string"
+    },
+    "delivered": {
+      "type": "boolean"
+    },
+    "detail": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "target",
+    "mode",
+    "delivered",
+    "detail"
+  ]
+};
+
+export const NEGOTIATE_PARAMETERS = {
+  "type": "object",
+  "properties": {
+    "action": {
+      "type": "string",
+      "description": "offer/counter = propose resolution terms; accept = accept the pending offer of the peer; decline = refuse to negotiate; escalate = ask for human arbitration; status = read-only view of your open negotiations.",
+      "enum": [
+        "offer",
+        "counter",
+        "accept",
+        "decline",
+        "escalate",
+        "status"
+      ]
+    },
+    "path": {
+      "type": "string",
+      "description": "Contested file path (absolute or workspace-relative to this session cwd)."
+    },
+    "corr": {
+      "type": "string",
+      "description": "Negotiation id from a [[DSH session-messenger · negotiate]] message; required when several negotiations are open for the same path."
+    },
+    "terms": {
+      "type": "object",
+      "description": "Resolution terms. Only the current claim holder may offer release-now / release-at; the writer may offer wait-until.",
+      "additionalProperties": false,
+      "properties": {
+        "action": {
+          "type": "string",
+          "description": "release-now = holder frees the claim immediately; release-at = holder frees it at terms.at (ISO-8601); wait-until = writer commits to wait until terms.at and is reminded then.",
+          "enum": [
+            "release-now",
+            "release-at",
+            "wait-until"
+          ]
+        },
+        "at": {
+          "type": "string",
+          "description": "ISO-8601 timestamp (required for release-at / wait-until, within 60 minutes)."
+        }
+      },
+      "required": [
+        "action"
+      ]
+    },
+    "message": {
+      "type": "string",
+      "description": "Optional free-text note delivered to the peer with this intent."
+    }
+  },
+  "required": [
+    "action",
+    "path"
+  ]
+};
+
+export const NEGOTIATE_OUTPUT = {
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "negId": {
+      "type": "string"
+    },
+    "path": {
+      "type": "string"
+    },
+    "state": {
+      "type": "string"
+    },
+    "rounds": {
+      "type": "integer"
+    },
+    "deadline": {
+      "type": "integer"
+    },
+    "released": {
+      "type": "boolean"
+    },
+    "detail": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "negId",
+    "path",
+    "state",
+    "rounds",
+    "deadline",
+    "released",
+    "detail"
+  ]
+};

package/storage.js

@@ -0,0 +1,205 @@
+/**
+ * 插件自有存储：数据目录解析、单宿主进程所有权锁、原子 JSON 合并写。
+ *
+ * - 绝不写 session event（自定义事件类型会让 Session 拒绝重开），状态落在
+ *   ~/.dsh/plugin-data/dsh-session-messenger/<profile>/。
+ * - 每个宿主进程的内存是真相；多个宿主进程（如 desktop 与 dsh web）若共享同一目录会
+ *   互相覆盖，因此用 owner.lock（O_EXCL + pid 存活检查）确保同一目录只有一个写入进程；
+ *   抢不到锁的进程退到 host-<pid>/ 隔离子目录并告警（它本来也看不到对方宿主的会话）。
+ * - 所有落盘统一走 JsonFile.write()：tmp（随机名）+ rename 原子替换，飞行中再脏则
+ *   跑第二轮（合并写），保证最终落盘的是最后一次内存状态。
+ */
+import { promises as fsp, openSync, writeSync, closeSync, readFileSync, unlinkSync, mkdirSync, existsSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+export function defaultDataDir(config) {
+  if (config && typeof config.dataDir === 'string' && config.dataDir) return config.dataDir;
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  const profile = String(process.env.DSH_PROFILE || (config && config.profile) || 'default').replace(/[^\w.-]/g, '_');
+  return path.join(home, 'plugin-data', 'dsh-session-messenger', profile);
+}
+
+/**
+ * v0.3 把状态放在 plugin-data/dsh-session-messenger/ 根目录；v0.4 按 profile 分目录。
+ * 首次激活时把旧文件**复制**（不移动，便于回滚）到新目录，已存在则不覆盖。
+ */
+export function migrateLegacyData(baseDir, logger) {
+  try {
+    const legacyDir = path.dirname(baseDir);
+    if (path.basename(legacyDir) !== 'dsh-session-messenger') return;
+    mkdirSync(baseDir, { recursive: true });
+    for (const file of ['claims.json', 'negotiations.json']) {
+      const from = path.join(legacyDir, file);
+      const to = path.join(baseDir, file);
+      if (existsSync(from) && !existsSync(to)) {
+        copyFileSync(from, to);
+        logger?.info?.(`[session-messenger] migrated legacy ${file} into ${baseDir}`);
+      }
+    }
+  } catch (error) {
+    logger?.warn?.(`[session-messenger] legacy data migration skipped: ${(error && error.message) || error}`);
+  }
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !!(error && error.code === 'EPERM');
+  }
+}
+
+/**
+ * 取得目录所有权。返回 { dir, release }：dir 是本进程实际使用的数据目录。
+ * 同步实现：激活路径只调用一次，且必须在任何读写之前确定目录。
+ */
+export function acquireDataDir(baseDir, logger) {
+  mkdirSync(baseDir, { recursive: true });
+  const lockFile = path.join(baseDir, 'owner.lock');
+  const body = JSON.stringify({ pid: process.pid, at: Date.now() });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = openSync(lockFile, 'wx');
+      writeSync(fd, body);
+      closeSync(fd);
+      return { dir: baseDir, release: () => releaseLock(lockFile) };
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+    }
+    let owner = 0;
+    try {
+      owner = Number(JSON.parse(readFileSync(lockFile, 'utf8')).pid) || 0;
+    } catch {
+      owner = 0;
+    }
+    if (owner === process.pid || !pidAlive(owner)) {
+      // 自己（HMR 重新激活）或已死进程留下的锁：接管。
+      try {
+        unlinkSync(lockFile);
+      } catch {
+        /* raced; retry once */
+      }
+      continue;
+    }
+    const isolated = path.join(baseDir, `host-${process.pid}`);
+    mkdirSync(isolated, { recursive: true });
+    logger?.warn?.(
+      `[session-messenger] data dir ${baseDir} is owned by live host pid ${owner}; this host uses isolated ${isolated} (claims are not shared across host processes)`
+    );
+    return { dir: isolated, release: () => undefined };
+  }
+  throw new Error(`could not acquire ${lockFile}`);
+}
+
+function releaseLock(lockFile) {
+  try {
+    const owner = Number(JSON.parse(readFileSync(lockFile, 'utf8')).pid) || 0;
+    if (owner === process.pid) unlinkSync(lockFile);
+  } catch {
+    /* already gone */
+  }
+}
+
+export class JsonFile {
+  constructor(file) {
+    this.file = file;
+    this.running = undefined;
+    this.dirty = false;
+  }
+
+  async read() {
+    try {
+      return JSON.parse(await fsp.readFile(this.file, 'utf8'));
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return undefined;
+      throw error;
+    }
+  }
+
+  async writeOnce(snapshot) {
+    const tmp = `${this.file}.${process.pid}.${randomUUID()}.tmp`;
+    await fsp.mkdir(path.dirname(this.file), { recursive: true });
+    try {
+      await fsp.writeFile(tmp, JSON.stringify(snapshot(), null, 2), 'utf8');
+      await fsp.rename(tmp, this.file);
+    } catch (error) {
+      await fsp.rm(tmp, { force: true }).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  /**
+   * 合并写：snapshot 在每一轮写入时才求值，因此返回的 Promise 兑现时，
+   * 磁盘上已是「调用时刻或更新」的内存状态。
+   */
+  write(snapshot) {
+    if (this.running) {
+      this.dirty = true;
+      this.pendingSnapshot = snapshot;
+      return this.running;
+    }
+    this.pendingSnapshot = snapshot;
+    this.running = (async () => {
+      try {
+        do {
+          this.dirty = false;
+          await this.writeOnce(this.pendingSnapshot);
+        } while (this.dirty);
+      } finally {
+        this.running = undefined;
+      }
+    })();
+    return this.running;
+  }
+}
+
+/**
+ * 运行状态文件（灰度观察用）：status.json 记录版本、启动时间、设置与累计指标。
+ * 指标跨重启累计（启动时读回旧值，按 bootId 区分本次与历史），便于算误冻结率等比率。
+ */
+export class StatusFile {
+  constructor(dataDir, { version, settings, logger }) {
+    this.file = new JsonFile(path.join(dataDir, 'status.json'));
+    this.version = version;
+    this.settings = settings;
+    this.logger = logger;
+    this.startedAt = Date.now();
+    this.bootId = randomUUID().slice(0, 8);
+    this.previous = {};
+  }
+
+  async load() {
+    try {
+      const parsed = await this.file.read();
+      this.previous = parsed && parsed.lifetime && typeof parsed.lifetime === 'object' ? parsed.lifetime : {};
+    } catch {
+      this.previous = {};
+    }
+  }
+
+  snapshot(metrics, extra = {}) {
+    const lifetime = { ...this.previous };
+    for (const [k, v] of Object.entries(metrics)) lifetime[k] = (Number(this.previous[k]) || 0) + v;
+    return {
+      version: this.version,
+      pid: process.pid,
+      bootId: this.bootId,
+      startedAt: new Date(this.startedAt).toISOString(),
+      savedAt: new Date().toISOString(),
+      settings: this.settings,
+      boot: { ...metrics },
+      lifetime,
+      ...extra
+    };
+  }
+
+  write(metrics, extra) {
+    return this.file.write(() => this.snapshot(metrics, extra)).catch((error) => {
+      this.logger?.warn?.(`[session-messenger] status write failed: ${(error && error.message) || error}`);
+    });
+  }
+}