@wangmo-bit/ds-link 0.0.0-stage → 0.8.18

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "@wangmo-bit/ds-link",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.18",
+  "description": "DS-link: local session collaboration with bubble and card views for DeepSeek Harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wangmo-bit/DS-link.git"
+  },
+  "homepage": "https://github.com/Wangmo-bit/DS-link#readme",
+  "bugs": {
+    "url": "https://github.com/Wangmo-bit/DS-link/issues"
+  },
+  "author": "Wangmo-bit",
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "session-collaboration",
+    "chat",
+    "multi-agent"
+  ],
+  "icon": "assets/icon.svg",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24",
+    "dsh": "0.2.1-rc.5 || 0.2.2-rc.1"
+  },
+  "exports": {
+    ".": "./src/host/entry-0.8.18.js",
+    "./runtime-0.8.18": "./src/host/entry-0.8.18.js",
+    "./package.json": "./package.json",
+    "./client": "./dist/client.js"
+  },
+  "files": [
+    "src/core",
+    "src/host",
+    "dist",
+    "cordis.patch.yml",
+    "THIRD_PARTY_NOTICES.md",
+    "TESTING.md",
+    "assets/icon.svg"
+  ],
+  "scripts": {
+    "test": "node scripts/run-tests.mjs",
+    "build": "node scripts/build.mjs",
+    "check": "npm run build && npm test",
+    "prepack": "node scripts/build.mjs",
+    "check:public": "node scripts/check-public.mjs",
+    "docs:assets": "node scripts/render-doc-assets.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-tool",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5 || ~4.1.0",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/schemastery": "~3.18.5 || ~3.19.0",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
+    "esbuild": "^0.25.0",
+    "playwright-core": "1.64.1",
+    "react": "^18.2.0",
+    "react-dom": "18.3.1",
+    "zod": "4.4.3"
+  }
+}

package/src/core/constants.js

@@ -0,0 +1,188 @@
+/**
+ * Shared vocabulary and technical formats for dsh-session-link 0.3.
+ *
+ * The values in LIMITS are protocol/format protections and storage envelopes,
+ * never per-day or per-peer business quotas. Owner-editable daily settings are
+ * limited to DEFAULT_SETTINGS.
+ */
+
+export const PLUGIN_NAME = 'session-link'
+export const PLUGIN_VERSION = '0.8.18'
+export const API_VERSION = 3
+export const SOURCE_KIND = 'agent-message'
+export const SOURCE_FORM = 'relay'
+
+export const STATE_VERSION = 3
+export const V1_STATE_VERSION = 1
+export const LEDGER_FILE = 'ledger.json'
+export const LOCK_FILE = 'writer.lock'
+export const LOCK_DB_FILE = 'writer.sqlite'
+export const V1_BACKUP_PREFIX = 'ledger.v1-backup.'
+/** Exact pre-upgrade v2 bytes kept before the v2 -> v3 schema conversion. */
+export const V2_BACKUP_PREFIX = 'ledger.v2-backup.'
+/** Exact current v3 bytes kept before an offline v3 -> v2 restore. */
+export const V3_ROLLBACK_BACKUP_PREFIX = 'ledger.v3-before-rollback.'
+export const V2_ROLLBACK_BACKUP_PREFIX = 'ledger.v2-before-rollback.'
+
+export const TOOL_NAMES = Object.freeze({
+  operation: 'session_link_operation',
+  list: 'session_link_list',
+  history: 'session_link_history',
+  send: 'session_link_send',
+  reply: 'session_link_reply',
+  status: 'session_link_status',
+  control: 'session_link_control',
+  create: 'session_link_create',
+})
+
+/** Durable settings presented by the settings page (exactly five keys). */
+export const DEFAULT_SETTINGS = Object.freeze({
+  enabled: true,
+  paused: false,
+  maxConcurrent: 3,
+  requestTimeoutMs: 30 * 60 * 1000,
+  retentionDays: 30,
+})
+
+export const SETTINGS_KEYS = Object.freeze(Object.keys(DEFAULT_SETTINGS))
+
+/** v1 keys that must be rejected as a whole rather than silently ignored. */
+export const LEGACY_SETTINGS_KEYS = Object.freeze([
+  'autoCollaborate',
+  'maxMessages',
+  'maxHops',
+  'maxTextChars',
+  'emergencyPaused',
+])
+
+export const SETTINGS_BOUNDS = Object.freeze({
+  maxConcurrent: { min: 1, max: 10 },
+})
+
+/**
+ * Technical format limits and storage envelopes. There is deliberately no
+ * message-count, chain, pair, window, daily, or per-source quota here.
+ */
+export const LIMITS = Object.freeze({
+  MAX_REFERENCES: 5,
+  MAX_REFERENCE_CHARS: 2000,
+  MAX_REFERENCE_SESSION_ID_CHARS: 256,
+  MAX_PATHS: 10,
+  MAX_PATH_CHARS: 1024,
+  /** One message content payload (text + references + paths). */
+  MAX_CONTENT_BYTES: 64 * 1024,
+  /** One send/reply call as received from the model tool arguments. */
+  MAX_CALL_BYTES: 1024 * 1024,
+  /** Deterministic display excerpt when a sender omitted the subject. */
+  SUBJECT_EXCERPT_CHARS: 120,
+  /** Deterministic session-title excerpt derived from the task text. */
+  TITLE_EXCERPT_CHARS: 60,
+  /** One owner card_lookup batch; a technical page bound, not a quota. */
+  MAX_CARD_LOOKUP_IDS: 100,
+  /** New-inbound active JSON ledger envelope. */
+  MAX_LEDGER_BYTES: 50 * 1024 * 1024,
+  /** New-inbound undelivered payload envelope (pending + held + dispatching). */
+  MAX_QUEUED_BYTES: 16 * 1024 * 1024,
+  MAX_PAGE: 50,
+  MAX_SNAPSHOT_PAGE: 100,
+  HISTORY_MAX_MESSAGES: 20,
+  HISTORY_MAX_CHARS: 16000,
+  HISTORY_SNIPPET_CHARS: 500,
+  /** Fixed metadata tombstone horizon; body retention is owner-editable. */
+  MESSAGE_RETENTION_MS: 90 * 24 * 60 * 60 * 1000,
+  OPERATION_RETENTION_MS: 90 * 24 * 60 * 60 * 1000,
+  /** operationId timestamp acceptance window. */
+  OPERATION_PAST_MS: 24 * 60 * 60 * 1000,
+  OPERATION_FUTURE_MS: 5 * 60 * 1000,
+  /** Largest instant representable by a JavaScript Date. */
+  MAX_DATE_MS: 8_640_000_000_000_000,
+  /** Forced dispose waits at most this long before refusing the handoff. */
+  DISPOSE_DRAIN_MS: 5000,
+  /** Bound one tick's read-only receipt catch-up retries and transfer pass. */
+  RECEIPT_RETRY_TARGETS: 16,
+  TRANSFER_TARGETS_PER_PASS: 16,
+  /** A prepared journal that keeps failing its synchronous move becomes uncertain. */
+  TRANSFER_MAX_ATTEMPTS: 3,
+})
+
+export const DISPATCH_STATUSES = Object.freeze([
+  'held',
+  'pending',
+  'dispatching',
+  'accepted',
+  'failed',
+  'unknown',
+  'cancelled',
+])
+
+export const REPLY_STATUSES = Object.freeze([
+  'none',
+  'waiting',
+  'answered',
+  'timed_out',
+])
+
+export const MESSAGE_KINDS = Object.freeze(['notification', 'request', 'reply'])
+
+/**
+ * Durable phases of one create journal. `creating` means an external effect
+ * may be in flight; `uncertain` is only set when its result cannot be proven.
+ * Terminal phases are eligible for the 90-day operation retention window.
+ */
+export const CREATE_PHASES = Object.freeze([
+  'creating',
+  'created',
+  'attach_failed',
+  'renamed',
+  'rename_failed',
+  'sending',
+  'sent',
+  'uncertain',
+  'failed',
+])
+
+/** Phases a completed create operation may never leave again. */
+export const CREATE_TERMINAL_PHASES = Object.freeze(['sent', 'attach_failed', 'failed'])
+
+/** Rename attempts are one-shot: a failure is reported, never auto-repeated. */
+export const CREATE_RENAME_STATUSES = Object.freeze(['not_attempted', 'pending', 'renamed', 'rename_failed'])
+
+export const CHAIN_STATES = Object.freeze(['open', 'paused', 'closed'])
+
+export const SNAPSHOT_FILTERS = Object.freeze([
+  'all',
+  'received',
+  'sent',
+  'pending_reply',
+  'abnormal',
+  'unknown',
+  'held',
+  'chain',
+])
+
+export const CONTROL_ACTIONS = Object.freeze([
+  'cancel',
+  'pause',
+  'resume',
+  'close',
+  'release',
+  'recheck',
+  'resolve_unknown',
+  'resume_budget',
+])
+
+/** Held reasons that are automatic consequences of broad settings. */
+export const AUTO_HELD_REASONS = Object.freeze([
+  'paused',
+  'disabled',
+  'emergency_paused',
+  'auto_collaborate_off',
+  'held_full',
+])
+
+/** Chain pause reasons retired by the v1 -> v2 migration. */
+export const RETIRED_CHAIN_PAUSE_REASONS = Object.freeze([
+  'hop_exceeded',
+  'chain_budget',
+  'budget_latched',
+])

package/src/core/downgrade.js

@@ -0,0 +1,80 @@
+/**
+ * Read-only 0.4 -> 0.3 downgrade readiness check for THIS plugin's ledger
+ * data. It never mutates, installs, migrates, or deletes anything.
+ *
+ * Strict full-ledger validation runs FIRST on a structured clone (validators
+ * normalize `settings` in place, so the caller's state is never touched), and
+ * a malformed or incomplete ledger fails closed instead of being mistaken for
+ * "no0.4 constructs". Only a validated state is then checked for the three
+ * hard blockers:
+ * - `state.creates` (even terminal):0.3 ignores the region, so the same root
+ *   operationId could be reused by send/reply and break deduplication;
+ * - a non-null `message.subject`:0.3 redaction never clears it, changing body
+ *   retention semantics;
+ * - sealed `s2:` operation fingerprints:0.3 recomputes raw canonical JSON and
+ *   would conflict on a legitimate replay.
+ *
+ * A clean, validated state only establishes the plugin data-shape necessary
+ * condition. It does not claim Host HMR/GUI compatibility, full rollback
+ * completeness, or retention safety, and it must not be used to run a
+ * production change without the user's explicit consent.
+ *
+ * This module deliberately lives outside `migration.js`: `ledger.js` imports
+ * migration helpers, so importing the ledger validator from migration would
+ * create an import cycle.
+ * @param {{ currentState?: Record<string, any> } | Record<string, any>} request
+ * @returns {{ ok: boolean, reasons: string[], notes?: string[] }}
+ */
+import { STATE_VERSION } from './constants.js'
+import { validateV3State } from './ledger.js'
+import { isPlainObject } from './validation.js'
+
+export function v04DowngradePreflight(request) {
+  const state = request?.currentState ?? request
+  if (!isPlainObject(state) || state.version !== STATE_VERSION) {
+    return { ok: false, reasons: ['current state is not a v3 ledger'] }
+  }
+  let candidate
+  try {
+    candidate = structuredClone(state)
+  } catch {
+    return { ok: false, reasons: ['current state cannot be cloned for validation'] }
+  }
+  try {
+    validateV3State(candidate)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, reasons: [`ledger failed strict validation: ${message.slice(0, 300)}`] }
+  }
+  const reasons = []
+  const creates = isPlainObject(candidate.creates) ? Object.keys(candidate.creates) : []
+  if (creates.length > 0) {
+    reasons.push(
+      `state.creates holds ${creates.length} create journal(s):0.3 ignores this region, so a root operationId could be reused by send/reply and break deduplication (terminal and unknown records included)`,
+    )
+  }
+  const withSubject = candidate.messages.filter(
+    (message) => message?.subject !== undefined && message.subject !== null,
+  ).length
+  if (withSubject > 0) {
+    reasons.push(
+      `${withSubject} message(s) carry a subject:0.3 redaction never clears it, so body retention semantics differ`,
+    )
+  }
+  const sealed = Object.values(candidate.operations).filter(
+    (operation) => typeof operation?.fingerprint === 'string' && operation.fingerprint.startsWith('s2:'),
+  ).length
+  if (sealed > 0) {
+    reasons.push(
+      `${sealed} operation record(s) use sealed s2 fingerprints:0.3 recomputes raw canonical JSON and would conflict on a legitimate replay`,
+    )
+  }
+  if (reasons.length > 0) return { ok: false, reasons }
+  return {
+    ok: true,
+    reasons: [],
+    notes: [
+      'only the session-link data-shape necessary condition is established; Host HMR/GUI compatibility and full rollback/retention safety are not verified',
+    ],
+  }
+}