@operatingtag/dsh-unclesam 0.0.0-stage → 1.0.0

package/install.cmd

@@ -0,0 +1,43 @@
+@echo off
+REM Uncle Sam - DeepSeek Harness plugin installer
+REM
+REM Double-click this file. It runs install.ps1 next to it in a visible console,
+REM so the person can read what happened instead of watching a window flash past.
+REM
+REM Nothing here decides anything: all checks, backups and prompts live in
+REM install.ps1, so there is exactly one place to review what gets written.
+
+setlocal
+cd /d "%~dp0"
+
+if not exist "install.ps1" (
+    echo.
+    echo   install.ps1 is missing.
+    echo   Keep this file and install.ps1 in the same folder.
+    echo.
+    pause
+    exit /b 1
+)
+
+echo.
+echo   Uncle Sam - DeepSeek Harness plugin installer
+echo.
+echo   This will look for your DeepSeek Harness profile, back it up,
+echo   and add the Uncle Sam plugin to it.
+echo.
+
+set /p CONFIRM=  Continue? [Y/n] 
+if /i "%CONFIRM%"=="n" (
+    echo   Cancelled. Nothing was changed.
+    pause
+    exit /b 0
+)
+
+REM -ExecutionPolicy Bypass applies to this one process only. It does not change
+REM any machine or user setting, which matters: the installer should not need
+REM permanent permission to run scripts just to install a plugin.
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" %*
+
+echo.
+echo   Finished. Read the output above for the result.
+pause

package/install.ps1

@@ -0,0 +1,311 @@
+#Requires -Version 5.1
+<#
+    Copyright (c) 2026 Operating Tag. All rights reserved.
+    @license CC-BY-NC-ND-4.0
+    @author  Operating Tag (@operatingtag)
+
+.SYNOPSIS
+    Uncle Sam installer for DeepSeek Harness.
+
+.DESCRIPTION
+    Installs the Uncle Sam plugin into a DeepSeek Harness profile.
+
+    It does the same two things the plugin manager does: link the package into the
+    profile, and add the row that tells the harness to load it.
+
+    Design rules, because this edits somebody's working harness:
+
+      * Nothing is changed until the profile has been found, checked and backed up.
+      * -DryRun prints every action and writes nothing at all.
+      * Every write is preceded by a backup of the file it is about to touch.
+      * If anything looks wrong it stops and says what, rather than guessing.
+
+.PARAMETER Profile
+    Profile name to install into. Defaults to "desktop".
+
+.PARAMETER DryRun
+    Show what would happen, change nothing.
+
+.PARAMETER Uninstall
+    Remove the plugin from the profile instead of adding it.
+
+.EXAMPLE
+    .\install.ps1 -DryRun
+    .\install.ps1
+    .\install.ps1 -Uninstall
+
+.NOTES
+    @file    install.ps1
+    @version 3.9.11
+    @author  Operating Tag (@operatingtag)
+    @license CC-BY-NC-ND-4.0
+#>
+
+[CmdletBinding()]
+param(
+    [string]$Profile = 'desktop',
+    [switch]$DryRun,
+    [switch]$Uninstall
+)
+
+$ErrorActionPreference = 'Stop'
+
+$PACKAGE_ID = 'dsh-unclesam'
+$PACKAGE_NAME = '@operatingtag/dsh-unclesam'
+$ROOT = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+function Write-Step($text) { Write-Host "  $text" }
+function Write-Ok($text) { Write-Host "  [ok]   $text" -ForegroundColor Green }
+function Write-Warn2($text) { Write-Host "  [warn] $text" -ForegroundColor Yellow }
+function Write-Fail($text) { Write-Host "  [fail] $text" -ForegroundColor Red }
+function Write-Act($text) {
+    if ($DryRun) { Write-Host "  [dry]  $text" -ForegroundColor Cyan }
+    else { Write-Host "  [do]   $text" -ForegroundColor Cyan }
+}
+
+Write-Host ''
+Write-Host '  Uncle Sam - DeepSeek Harness plugin installer' -ForegroundColor White
+Write-Host "  $PACKAGE_NAME"
+if ($DryRun) { Write-Host '  DRY RUN - nothing will be written' -ForegroundColor Cyan }
+Write-Host ''
+
+# ---------------------------------------------------------------- 1. the files
+Write-Step 'Checking the plugin files'
+
+$required = @('package.json', 'index.js', 'client.js', 'cordis.patch.yml')
+$missing = $required | Where-Object { -not (Test-Path (Join-Path $ROOT $_)) }
+if ($missing) {
+    Write-Fail "this folder is missing: $($missing -join ', ')"
+    Write-Step 'Run the installer from inside the uncle-sam folder.'
+    exit 1
+}
+
+$manifest = Get-Content (Join-Path $ROOT 'package.json') -Raw | ConvertFrom-Json
+if ($manifest.name -ne $PACKAGE_NAME) {
+    Write-Fail "package.json says '$($manifest.name)', expected '$PACKAGE_NAME'"
+    exit 1
+}
+Write-Ok "plugin files present, version $($manifest.version)"
+
+# ---------------------------------------------------------------- 2. node / pnpm
+Write-Step 'Checking node'
+
+$node = Get-Command node -ErrorAction SilentlyContinue
+if (-not $node) {
+    Write-Fail 'node was not found on PATH.'
+    Write-Step 'Install Node.js 22 or newer from https://nodejs.org and run this again.'
+    exit 1
+}
+Write-Ok "node $(& node --version)"
+
+$pnpm = Get-Command pnpm -ErrorAction SilentlyContinue
+if (-not $pnpm) {
+    Write-Warn2 'pnpm was not found - falling back to npm'
+}
+
+# ---------------------------------------------------------------- 3. the profile
+Write-Step 'Looking for the DeepSeek Harness profile'
+
+$profilesRoot = Join-Path $env:USERPROFILE '.dsh\profiles'
+if (-not (Test-Path $profilesRoot)) {
+    Write-Fail "no profiles folder at $profilesRoot"
+    Write-Step 'Is DeepSeek Harness installed and has it been started once?'
+    exit 1
+}
+
+$profileDir = Join-Path $profilesRoot $Profile
+$profileManifest = Join-Path $profileDir 'package.json'
+$profilePatch = Join-Path $profileDir 'cordis.patch.yml'
+
+if (-not (Test-Path $profileDir)) {
+    Write-Fail "profile '$Profile' does not exist"
+    $available = Get-ChildItem $profilesRoot -Directory | Select-Object -ExpandProperty Name
+    Write-Step "available profiles: $($available -join ', ')"
+    exit 1
+}
+if (-not (Test-Path $profileManifest)) {
+    Write-Fail "profile '$Profile' has no package.json - it may be incomplete"
+    exit 1
+}
+if (-not (Test-Path $profilePatch)) {
+    Write-Fail "profile '$Profile' has no cordis.patch.yml"
+    exit 1
+}
+Write-Ok "profile '$Profile' at $profileDir"
+
+# ---------------------------------------------------------------- 4. already there?
+$profileJson = Get-Content $profileManifest -Raw | ConvertFrom-Json
+$alreadyLinked = $false
+if ($profileJson.dependencies -and $profileJson.dependencies.PSObject.Properties.Name -contains $PACKAGE_NAME) {
+    $alreadyLinked = $true
+}
+
+$patchText = Get-Content $profilePatch -Raw
+$alreadyPatched = $patchText -match [regex]::Escape($PACKAGE_NAME)
+
+# ---------------------------------------------------------------- uninstall
+if ($Uninstall) {
+    Write-Host ''
+    Write-Step 'Removing Uncle Sam from the profile'
+
+    if (-not $alreadyPatched -and -not $alreadyLinked) {
+        Write-Ok 'it is not installed here - nothing to do'
+        exit 0
+    }
+
+    $stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+    $backup = "$profilePatch.$stamp.bak"
+    Write-Act "back up cordis.patch.yml -> $(Split-Path -Leaf $backup)"
+    if (-not $DryRun) { Copy-Item $profilePatch $backup -Force }
+
+    # Remove the entry that names this package.
+    #
+    # The previous version walked forward from the matching line and stopped at the next
+    # top-level dash, which removed the name and config but left the "- insert:" header
+    # behind - a half-deleted entry, which is worse than none because the YAML still parses
+    # and silently does nothing. This finds the whole block first, then cuts it.
+    #
+    # A block starts at the nearest line above the package name that begins with "- ", and
+    # runs until the next line that begins with "- " at the same or shallower indentation.
+    $lines = $patchText -split "`r?`n"
+    $remove = New-Object 'bool[]' $lines.Count
+
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -notmatch [regex]::Escape($PACKAGE_NAME)) { continue }
+
+        # walk back to the entry header
+        $start = $i
+        while ($start -gt 0 -and $lines[$start] -notmatch '^-\s') { $start-- }
+        if ($lines[$start] -notmatch '^-\s') { $start = $i }
+
+        # walk forward to the end of that entry
+        $end = $i
+        for ($j = $i + 1; $j -lt $lines.Count; $j++) {
+            if ($lines[$j] -match '^-\s') { break }
+            $end = $j
+        }
+
+        # including the comment lines the installer itself added, just above the entry
+        $cStart = $start
+        while ($cStart -gt 0 -and $lines[$cStart - 1] -match '^\s*#') { $cStart-- }
+
+        for ($k = $cStart; $k -le $end; $k++) { $remove[$k] = $true }
+    }
+
+    $kept = New-Object System.Collections.Generic.List[string]
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if (-not $remove[$i]) { $kept.Add($lines[$i]) }
+    }
+
+    # collapse any run of blank lines the removal left behind
+    $clean = New-Object System.Collections.Generic.List[string]
+    $blank = $false
+    foreach ($line in $kept) {
+        $isBlank = [string]::IsNullOrWhiteSpace($line)
+        if ($isBlank -and $blank) { continue }
+        $clean.Add($line)
+        $blank = $isBlank
+    }
+
+    $removed = ($remove | Where-Object { $_ }).Count
+    Write-Act "remove the plugin entry from cordis.patch.yml ($removed line(s))"
+    if (-not $DryRun) {
+        ($clean -join "`r`n").TrimEnd() + "`r`n" | Set-Content $profilePatch -Encoding UTF8
+    }
+
+    Write-Act "run pnpm remove $PACKAGE_NAME"
+    if (-not $DryRun) {
+        Push-Location $profileDir
+        try {
+            if ($pnpm) { & pnpm remove $PACKAGE_NAME 2>&1 | Out-Null }
+            else { & npm remove $PACKAGE_NAME 2>&1 | Out-Null }
+        } finally { Pop-Location }
+    }
+
+    Write-Host ''
+    Write-Ok 'removed. Restart the harness to unload it.'
+    exit 0
+}
+
+# ---------------------------------------------------------------- 5. install
+Write-Host ''
+
+if ($alreadyLinked -and $alreadyPatched) {
+    Write-Ok 'already installed in this profile'
+    Write-Step 'Restart the harness if you have not since installing.'
+    exit 0
+}
+
+# Back up before touching anything.
+$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+$patchBackup = "$profilePatch.$stamp.bak"
+$manifestBackup = "$profileManifest.$stamp.bak"
+
+Write-Step 'Backing up the profile'
+Write-Act "cordis.patch.yml -> $(Split-Path -Leaf $patchBackup)"
+Write-Act "package.json     -> $(Split-Path -Leaf $manifestBackup)"
+if (-not $DryRun) {
+    Copy-Item $profilePatch $patchBackup -Force
+    Copy-Item $profileManifest $manifestBackup -Force
+}
+
+Write-Host ''
+Write-Step "Installing into profile '$Profile'"
+
+# The package link. pnpm is the harness's own package manager, so it is preferred.
+if (-not $alreadyLinked) {
+    Write-Act "link the package into the profile"
+    if (-not $DryRun) {
+        Push-Location $profileDir
+        try {
+            $spec = "file:$ROOT"
+            if ($pnpm) { & pnpm add $spec 2>&1 | Out-Null } else { & npm install $spec 2>&1 | Out-Null }
+            if ($LASTEXITCODE -ne 0) {
+                Write-Fail 'the package manager refused the install'
+                Write-Step "restore from $(Split-Path -Leaf $manifestBackup) if the profile looks wrong"
+                exit 1
+            }
+        } finally { Pop-Location }
+    }
+} else {
+    Write-Ok 'package already linked'
+}
+
+# The profile row. Appended, so nothing already there is rewritten.
+if (-not $alreadyPatched) {
+    $block = @"
+
+# Uncle Sam - answers through chat.deepseek.com in a real browser instead of the paid API.
+# Added by install.ps1. Remove with install.ps1 -Uninstall.
+- insert:
+    - id: $PACKAGE_ID
+      name: '$PACKAGE_NAME'
+      config:
+        port: 9222
+        defaultModel: deepseek-chat
+        autoMinimise: true
+"@
+    Write-Act 'add the plugin row to cordis.patch.yml'
+    if (-not $DryRun) {
+        Add-Content -Path $profilePatch -Value $block -Encoding UTF8
+    }
+} else {
+    Write-Ok 'profile row already present'
+}
+
+Write-Host ''
+if ($DryRun) {
+    Write-Host '  Dry run finished. Nothing was written.' -ForegroundColor Cyan
+    Write-Host '  Run again without -DryRun to install.' -ForegroundColor Cyan
+} else {
+    Write-Ok 'installed'
+    Write-Host ''
+    Write-Step 'Next:'
+    Write-Step '  1. Restart DeepSeek Harness'
+    Write-Step '  2. Open Settings -> Uncle Sam'
+    Write-Step '  3. Click "Sign in / open chat"'
+    Write-Step ''
+    Write-Step "To remove: .\install.ps1 -Uninstall"
+    Write-Step "Backups:   $patchBackup"
+}
+Write-Host ''

package/lib/cdp.mjs

@@ -0,0 +1,247 @@
+/**
+ * A minimal Chrome DevTools Protocol client with no dependencies.
+ *
+ * @file    cdp.mjs
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * WHY THIS IS HAND-WRITTEN
+ *     Every other route to the browser has a cost: puppeteer-core drags a 3 MB dependency tree into a
+ *     plugin that otherwise needs nothing, and shelling out to a helper process adds an IPC hop to the
+ *     hot path of every single token. Node 24 ships a global `WebSocket` and a global `fetch`, which is
+ *     exactly the two things CDP needs, so the whole client is a couple of hundred lines and the token
+ *     stream never leaves this process.
+ *
+ * WHAT CDP ACTUALLY IS
+ *     A WebSocket to a page, carrying JSON messages: `{id, method, params}` out, `{id, result}` or
+ *     `{method, params}` back. Requests are matched to replies by `id`; events arrive unasked and are
+ *     dispatched to listeners. That is the entire protocol surface used here.
+ *
+ * WHY EVERY CALL HAS A TIMEOUT
+ *     A CDP socket that half-dies leaves a promise pending forever. In an LLM adapter that becomes a
+ *     hung model call with no error, which is the worst failure shape: the user watches a spinner and
+ *     nothing is logged. Every await here is bounded and rejects with a named timeout instead.
+ */
+
+const DEFAULT_TIMEOUT = 30000;
+
+export class CdpTimeout extends Error {
+  constructor(method, ms) {
+    super(`CDP ${method} timed out after ${ms}ms`);
+    this.name = 'CdpTimeout';
+    this.method = method;
+  }
+}
+
+export class Cdp {
+  #ws;
+  #nextId = 1;
+  #pending = new Map();
+  #listeners = new Map();
+  #closed = false;
+
+  constructor(ws) {
+    this.#ws = ws;
+    ws.addEventListener('message', (ev) => this.#onMessage(ev));
+    ws.addEventListener('close', () => this.#onClose());
+    ws.addEventListener('error', () => this.#onClose());
+  }
+
+  static async #list(port) {
+    const res = await fetch(`http://127.0.0.1:${port}/json/list`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) throw new Error(`CDP /json/list returned ${res.status}`);
+    return res.json();
+  }
+
+  /** Every page target currently exposed on a debugging port. */
+  static async targets(port) {
+    const all = await Cdp.#list(port);
+    return all.filter((t) => t.type === 'page' && t.webSocketDebuggerUrl);
+  }
+
+  /** Find a page whose URL matches, or the first page at all. */
+  static async findTarget(port, match) {
+    const pages = await Cdp.targets(port);
+    if (pages.length === 0) return undefined;
+    if (!match) return pages[0];
+    return (
+      pages.find((p) => String(p.url || '').includes(match)) ??
+      pages.find((p) => String(p.url || '').startsWith('http')) ??
+      pages[0]
+    );
+  }
+
+  static async open(port) {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) throw new Error(`CDP /json/version returned ${res.status}`);
+    return res.json();
+  }
+
+  /** Connect to a target id, or to the browser-level socket when no id is given. */
+  static async attach(port, targetId) {
+    const url = targetId
+      ? `ws://127.0.0.1:${port}/devtools/page/${targetId}`
+      : (await Cdp.open(port)).webSocketDebuggerUrl;
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('CDP websocket open timed out')), 10000);
+      ws.addEventListener('open', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener('error', () => {
+        clearTimeout(timer);
+        reject(new Error(`CDP websocket failed to open: ${url}`));
+      });
+    });
+    return new Cdp(ws);
+  }
+
+  get closed() {
+    return this.#closed;
+  }
+
+  #onClose() {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const [, pending] of this.#pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('CDP socket closed'));
+    }
+    this.#pending.clear();
+  }
+
+  #onMessage(ev) {
+    let msg;
+    try {
+      msg = JSON.parse(typeof ev.data === 'string' ? ev.data : String(ev.data));
+    } catch {
+      return;
+    }
+    if (msg.id !== undefined) {
+      const pending = this.#pending.get(msg.id);
+      if (!pending) return;
+      this.#pending.delete(msg.id);
+      clearTimeout(pending.timer);
+      if (msg.error) pending.reject(new Error(`${pending.method}: ${msg.error.message}`));
+      else pending.resolve(msg.result);
+      return;
+    }
+    if (msg.method) {
+      const set = this.#listeners.get(msg.method);
+      if (set) for (const fn of set) {
+        try {
+          fn(msg.params);
+        } catch {
+          /* a listener must never take the socket down */
+        }
+      }
+    }
+  }
+
+  on(method, fn) {
+    let set = this.#listeners.get(method);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(method, set);
+    }
+    set.add(fn);
+    return () => set.delete(fn);
+  }
+
+  send(method, params = {}, timeout = DEFAULT_TIMEOUT) {
+    if (this.#closed) return Promise.reject(new Error('CDP socket closed'));
+    const id = this.#nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new CdpTimeout(method, timeout));
+      }, timeout);
+      this.#pending.set(id, { resolve, reject, timer, method });
+      try {
+        this.#ws.send(JSON.stringify({ id, method, params }));
+      } catch (err) {
+        clearTimeout(timer);
+        this.#pending.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Evaluate an expression in the page and return its JSON value.
+   *
+   * `returnByValue` is on, so a function returning a plain object arrives as data rather than as an
+   * object handle the caller then has to release.
+   */
+  async evaluate(expression, { awaitPromise = false, timeout = DEFAULT_TIMEOUT } = {}) {
+    const res = await this.send(
+      'Runtime.evaluate',
+      {
+        expression,
+        returnByValue: true,
+        awaitPromise,
+        userGesture: true,
+        includeCommandLineAPI: false,
+      },
+      timeout,
+    );
+    if (res.exceptionDetails) {
+      const d = res.exceptionDetails;
+      const text =
+        d.exception?.description ?? d.exception?.value ?? d.text ?? 'evaluation threw';
+      throw new Error(`page evaluation failed: ${String(text).slice(0, 400)}`);
+    }
+    return res.result?.value;
+  }
+
+  async navigate(url, timeout = 45000) {
+    await this.send('Page.enable');
+    await this.send('Page.navigate', { url }, timeout);
+  }
+
+  async bringToFront() {
+    try {
+      await this.send('Page.bringToFront', {}, 5000);
+    } catch {
+      /* headless and unfocused targets refuse this; it is only cosmetic */
+    }
+  }
+
+  close() {
+    try {
+      this.#ws.close();
+    } catch {
+      /* already gone */
+    }
+    this.#onClose();
+  }
+}
+
+/**
+ * Poll `fn` until it returns a truthy value or the budget runs out.
+ *
+ * A throwing poll is treated as "not ready yet", not as failure. The first version let the throw
+ * escape, so waiting for a browser to open its debug port died on the first `fetch failed` - which is
+ * the normal state for the several seconds before the port exists.
+ */
+export async function waitFor(fn, { timeout = 20000, interval = 120, label = 'condition' } = {}) {
+  const started = Date.now();
+  let lastError;
+  while (Date.now() - started < timeout) {
+    try {
+      const value = await fn();
+      if (value) return value;
+    } catch (err) {
+      lastError = err;
+    }
+    await new Promise((r) => setTimeout(r, interval));
+  }
+  const detail = lastError ? ` (last error: ${lastError.message})` : '';
+  throw new Error(`timed out waiting for ${label} after ${timeout}ms${detail}`);
+}