@soffits/dsh-deltachat-bot 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release: a Delta Chat bot for DSH on several chatmail relays, with a key-fingerprint allowlist, one session per chat (groups included), steering, mirrored turns, pictures, files, voice transcription, quotes, reactions, agent questions and tool approvals, Telegram-style commands, `DeltaChat-<person>-<task>` session titles, the `deltachatChats` send service, the `deltachat_send` tool and the `dsh-deltachat` command.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sakina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# dsh-deltachat-bot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use [Delta Chat](https://delta.chat) to reach sessions in your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). Within DSH, the plugin runs a Delta Chat bot: it creates its own chatmail address (end-to-end encrypted; no phone number or sign-up needed), keeps that address on several relays so it stays reachable when a relay goes down, and ties each Delta Chat chat to a DSH session. Message it just as you would in the Web UI; answers, files and images come back to you as messages.
+
+## Installation
+
+Use the DSH Plugins page, or install from a shell:
+
+```sh
+dsh plugin --profile web add @soffits/dsh-deltachat-bot
+```
+
+You need Node.js 22 or newer. A prebuilt npm binary (`@deltachat/stdio-rpc-server`) provides the Delta Chat core for Linux, macOS and Windows on x64 and arm64; nothing is compiled.
+
+The bundle adds two plugin rows: `deltachat-bot` (the bot itself) and `deltachat-bot-tools` (which gives agents the `deltachat_send` tool).
+
+## First start
+
+On the first start, the bot creates a Delta Chat profile on the relays named in `relays` (by default [nine.testrun.org](https://nine.testrun.org), the usual relay for Delta Chat apps, and [chtml.ca](https://chtml.ca)). This takes a few seconds. It then produces a QR code plus an invite link:
+
+```sh
+dsh-deltachat invite          # prints the link; the QR code is $DSH_HOME/deltachat/invite.svg
+```
+
+Open the link on a phone that has Delta Chat installed, or scan the QR code on the app's "New chat" screen. The app and the bot exchange keys, and the chat appears.
+
+## Who may talk to it
+
+Nobody can, unless you allow it. Only keys listed in `allowedUsers` get replies from the bot; all others are ignored and receive nothing. People are identified by their key fingerprint, not their address, because an address changes when someone adds a relay or switches to another.
+
+To give yourself access, message the bot once, then ask it which contacts it ignored:
+
+```sh
+dsh-deltachat status          # "pending" lists ignored contacts with their fingerprints
+dsh-deltachat allow "3C1F 9E0A 5B7D 2468 ACE0 1357 9BDF 0246 8ACE 1357" --name Alex
+```
+
+`allow` stores the entry through DSH's configuration editor, exactly as the settings page would. You can also add it to the profile by hand:
+
+```yaml
+- id: deltachat-bot
+  config:
+    allowedUsers:
+      - fingerprint: 3C1F9E0A5B7D2468ACE013579BDF02468ACE1357
+        name: Alex
+```
+
+Your fingerprint is also the part after `#` in the invite link for your own Delta Chat account. If you want the bot to start the chat, supply your invite link after your key is allowed:
+
+```sh
+dsh-deltachat join "https://i.delta.chat/#3C1F9E0A...&a=you%40relay.example&n=Alex"
+```
+
+Every message the agent receives starts with a line the bot adds from the sender's verified key, such as `[Delta Chat message from Alex (key 3C1F…, chat 10, message 42)]`. No text in the message can change that line.
+
+## Chats and sessions
+
+- The first message in a chat starts a new session in `cwd`. Each group you create with the bot gets its own session, much like a separate topic.
+- Session titles use `DeltaChat-<person>-<task>`: the other party in the chat (a group's name, for a group) plus either the conversation title DSH produces or the chat's name until that title exists. A person's name comes from `peopleFile` when configured, else from `allowedUsers`, else from their Delta Chat profile.
+- If a message arrives while a turn is running, it joins that turn, as in the Web UI (`busyMessages: steer`; the message gets a 👀 reaction). With `busyMessages: queue`, it waits for the turn to finish.
+- Turns started elsewhere (scheduled tasks, the Web UI) also show up in the chat unless `mirrorTurns` is off.
+- When the turn ends, replies arrive as plain text: Delta Chat apps do not render Markdown, so the bot turns it into readable text. Files the agent presents, and local images inside an answer, are sent as files. An answer that is exactly `[SILENT]` sends nothing.
+- The model receives images you send as images; other files come through as attachments. Voice messages are transcribed by DSH's speech-to-text service (or by a command you choose; see `transcriber`) and attached.
+- Quoting a message tells the agent what you are replying to. A reaction to the bot's message is saved in the session but does not begin a turn.
+- When the agent asks a question, the options show as a numbered list: answer with a number or in your own words. A tool that needs approval waits for `/allow` or `/deny`.
+
+### Commands
+
+Send these as messages; Delta Chat apps make them tappable.
+
+| Command | Result |
+|---|---|
+| `/help` | List commands |
+| `/new` | Start a fresh session here; the old one stays in DSH |
+| `/stop` | Stop the running turn |
+| `/clear` | Drop any messages waiting in the session queue |
+| `/status` | Bot, relay and session status |
+| `/current` | Show this chat's session |
+| `/last [1-5]` | Show the latest answers |
+| `/sessions` | List workspaces; `/sessions 2` displays workspace 2's sessions; `/sessions 2 3` brings session 3 into this chat (`0` opens a new one) |
+| `/workspace <n>` | Open a fresh session in workspace n |
+| `/fork [name]` | Make a new group with the same people and fork the session there |
+| `/rename <name>` | In a group chat, change the group's name; in a one-to-one chat, change the session title |
+| `/goal …` | Goal actions: `/goal <objective>`, `/goal edit <objective>`, `pause`, `resume`, `clear` |
+| `/menu` | See the model, effort level, access setting and context together |
+| `/model` | List providers; `/model 2` lists models from that provider; `/model 2 5` picks one |
+| `/effort`, `/mode` | Works the same way for effort level and access setting |
+| `/context` | Context use for the session |
+| `/allow`, `/deny` | Answer a tool approval that is waiting |
+| `/invite` | Show the invite link for the bot |
+| `/id` | Show your key, the bot's key and the chat id |
+| `/ping` | Check whether the bot answers |
+| `/restart` | Reconnect to Delta Chat |
+
+A message that starts with `/` yet matches no command above (a path, for example) goes to the session as normal text.
+
+## Sending from scripts, agents and additional plugins
+
+Other plugins send through the `deltachatChats` Host service:
+
+```js
+await ctx.get('deltachatChats').send({
+  to: 10,                       // chat id (/id in the chat shows it)
+  text: 'Build finished',       // Markdown; made plain
+  files: ['/abs/path/log.txt'],
+  from: { job: 'nightly build' }, // or { sessionId } or { label }
+  replyTo: 42,                  // optional: quote a message
+})
+```
+
+Errors a retry cannot solve carry `retryable: false`. The message is also recorded in the session tied to that chat, without starting a turn, so the agent knows it went out; if the person quotes it later, the agent can tell which job or session sent it. `chats()` lists chats bound to sessions, and `invite()` returns the invite link.
+
+Agents can use the `deltachat_send` tool, which offers the same options (plus `reaction` to react to a message). From a shell:
+
+```sh
+dsh-deltachat send --chat 10 --job backup "Backup done"
+dsh-deltachat send --chat 10 --file /tmp/report.pdf
+dsh-deltachat react --chat 10 --reply-to 42 👍
+dsh-deltachat chats
+```
+
+The command line talks to the running bot through a spool directory under `$DSH_HOME/deltachat`, so it needs no network access to DSH. A send made while DSH is stopped waits there and is delivered when the bot starts.
+
+## Configuration
+
+| Field | Default | |
+|---|---|---|
+| `enabled` | `true` | Whether the bot is active |
+| `displayName` | `DSH` | Name shown in Delta Chat |
+| `avatar` | | Full path of an image to use as the bot avatar |
+| `relays` | `[nine.testrun.org, chtml.ca]` | Chatmail relays, given by domain. A relay added here joins the bot's profile; one removed here stays in the profile |
+| `allowedUsers` | `[]` | Items shaped like `{ fingerprint, name }` |
+| `peopleFile` | | JSON file with a `deltachat_keys` object mapping fingerprints to names, for session titles |
+| `cwd` | DSH's directory | Directory where new sessions start |
+| `agentPreset` | | Preset for new sessions; blank uses the default |
+| `mirrorTurns` | `true` | Show turns started elsewhere |
+| `busyMessages` | `steer` | `steer` or `queue` |
+| `transcriber` | `dsh` | `dsh`, `command` or `off` |
+| `transcribeLanguage` | | Language hint for DSH speech-to-text |
+| `transcribeCommand` | `[]` | Program and arguments; `{file}` is the recording |
+| `ffmpegPath` | `ffmpeg` | Decodes audio for DSH speech-to-text |
+
+Every field applies live: changing one needs no DSH restart. Relays, name and avatar take effect at once.
+
+Pick relays you expect to stay up; the [chatmail relay list](https://chatmail.at/relays) has many. Relays remove accounts after about 90 days without a login, which a running bot never allows to happen.
+
+## Where files live
+
+Everything is stored under `$DSH_HOME/deltachat/`:
+
+- `accounts/` holds the Delta Chat profile, with the bot's private key and its message database. Keep it out of shared backups outside your control, and keep it when moving DSH: otherwise the bot gets a fresh address and key, and people have to scan a fresh invite.
+- `state.json`: chat-to-session bindings, ignored contacts, and a log of messages sent by jobs and sessions.
+- `status.json`: the bot's state and latest error, for diagnostics.
+- `invite.txt`, `invite.svg`: the invite link and its QR code.
+- `spool/`: requests that come from the command line.
+
+The bot's log lines appear in DSH's output prefixed with `[dsh-deltachat-bot]`.
+
+## Updates and removal
+
+Update it like any DSH plugin. Every release locks the Delta Chat core at a tested version.
+
+To remove it, remove the bundle from DSH, then delete `$DSH_HOME/deltachat/` unless you want to keep the bot's identity. Anyone who chatted with it can remove the chat in their app.
+
+## Troubleshooting
+
+- **No reply from the bot.** `dsh-deltachat status` shows whether it runs and lists ignored contacts; the common cause is an entry missing from `allowedUsers`. DSH's log contains lines prefixed `[dsh-deltachat-bot]`.
+- **"no relay could create the Delta Chat profile".** None of the relays in `relays` could be reached or would take a new account. Try a different relay from the [relay list](https://chatmail.at/relays).
+- **Core stopped.** The bot restarts it with a growing delay (5 s up to 5 min) and logs why it stopped.
+
+## Development
+
+```sh
+npm install
+npm test          # unit and bridge tests against a fake core and a fake Host
+npm run e2e       # real relays: a bot and two throwaway accounts, all deleted afterwards
+```
+
+Each `npm run e2e` run creates fresh accounts on public relays; run it when message handling or the core changes, not over and over. Set `E2E_BOT_RELAYS` and `E2E_TESTER_RELAY` to choose other relays.
+
+## License
+
+MIT. The core packages from Delta Chat use MPL-2.0.

package/bin/dsh-deltachat.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Talk to the running DSH Delta Chat bot from a shell: send messages, show
+ * its invite link, join someone's invite, list chats, allow a contact.
+ *
+ * Requests go through the plugin's file spool under $DSH_HOME/deltachat, so
+ * no network access to DSH is needed, and a send waits there while DSH is
+ * not running.
+ */
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { dataDir } from '../src/constants.js'
+import { enqueue, waitForResult, withdraw } from '../src/spool.js'
+
+const usage = `Usage: dsh-deltachat <command> [options]
+
+Commands:
+  send --chat <id> [--file <path>]... [--reply-to <msg>] [--job <name>] [text...]
+        Send text (from the arguments, or stdin when none are given) and files
+        into a chat. The message is also recorded in the chat's session.
+  react --chat <id> --reply-to <msg> <emoji>
+        React to a message (an empty emoji removes the reaction).
+  invite
+        Print the bot's invite link; its QR code is in ${join('$DSH_HOME', 'deltachat', 'invite.svg')}.
+  join <invite-link>
+        Join someone's invite link (their key must be in allowedUsers).
+  allow <fingerprint> [--name <label>]
+        Add a key to allowedUsers (writes the profile's configuration).
+  chats
+        List the chats bound to sessions.
+  status
+        Show the bot's state, relays and the contacts it ignored.
+
+Options:
+  --timeout <seconds>   how long to wait for the bot (default 30)
+  --no-wait             queue a send and return at once
+
+Exit codes: 0 done, 1 failed, 2 bad arguments, 3 the bot did not answer in time.`
+
+function fail(message, code = 2) {
+  process.stderr.write(`${message}\n`)
+  process.exit(code)
+}
+
+let parsed
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      chat: { type: 'string', short: 'c' },
+      file: { type: 'string', short: 'f', multiple: true },
+      'reply-to': { type: 'string' },
+      job: { type: 'string', short: 'j' },
+      'from-session': { type: 'string' },
+      name: { type: 'string' },
+      timeout: { type: 'string' },
+      'no-wait': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  })
+} catch (error) {
+  fail(`${error.message}\n\n${usage}`)
+}
+const { values, positionals } = parsed
+const [command, ...rest] = positionals
+if (values.help || command === undefined) {
+  process.stdout.write(`${usage}\n`)
+  process.exit(values.help ? 0 : 2)
+}
+const timeoutMs = Math.max(1, Number(values.timeout ?? 30)) * 1000
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+let request
+if (command === 'send' || command === 'react') {
+  if (values.chat === undefined || !/^\d+$/u.test(values.chat.trim())) fail('--chat takes the numeric chat id (/id in the chat shows it).')
+  const sessionId = values['from-session'] ?? process.env.DSH_SESSION_ID
+  const from = {
+    ...(values.job ? { job: values.job } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    ...(!values.job && !sessionId ? { label: 'dsh-deltachat' } : {}),
+  }
+  if (command === 'react') {
+    if (values['reply-to'] === undefined) fail('react needs --reply-to <message id>.')
+    request = { op: 'send', to: values.chat.trim(), replyTo: values['reply-to'], reaction: rest.join(' '), from }
+  } else {
+    const text = rest.length > 0 ? rest.join(' ') : (values.file?.length ? '' : readStdin())
+    request = {
+      op: 'send',
+      to: values.chat.trim(),
+      text,
+      files: (values.file ?? []).map((path) => resolve(path)),
+      ...(values['reply-to'] === undefined ? {} : { replyTo: values['reply-to'] }),
+      from,
+    }
+  }
+} else if (command === 'invite' || command === 'chats' || command === 'status') {
+  request = { op: command }
+} else if (command === 'join') {
+  if (rest.length !== 1) fail('join takes one invite link.')
+  request = { op: 'join', link: rest[0] }
+} else if (command === 'allow') {
+  if (rest.length !== 1) fail('allow takes one fingerprint (quote it if it has spaces).')
+  request = { op: 'allow', fingerprint: rest[0], name: values.name ?? '' }
+} else {
+  fail(`Unknown command ${command}.\n\n${usage}`)
+}
+
+const id = await enqueue(request)
+if (values['no-wait'] && request.op === 'send') {
+  process.stdout.write(`queued ${id}\n`)
+  process.exit(0)
+}
+const result = await waitForResult(id, timeoutMs)
+if (result === undefined) {
+  // Only sends keep waiting for the bot; other requests are withdrawn.
+  if (request.op !== 'send') await withdraw(id)
+  let state = ''
+  try {
+    const status = JSON.parse(readFileSync(join(dataDir(), 'status.json'), 'utf8'))
+    state = ` (last state: ${status.state}${status.detail ? `, ${status.detail}` : ''})`
+  } catch {
+    // No status yet.
+  }
+  process.stderr.write(`The Delta Chat bot did not answer in time${state}.${request.op === 'send' ? ' The message stays queued and goes out when the bot runs.' : ''}\n`)
+  process.exit(3)
+}
+if (!result.ok) {
+  process.stderr.write(`${result.error}\n`)
+  process.exit(1)
+}
+if (command === 'invite') process.stdout.write(`${result.result.link}\nQR code: ${result.result.svgPath}\n`)
+else process.stdout.write(`${JSON.stringify(result.result, null, 2)}\n`)

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Bundle layer for @soffits/dsh-deltachat-bot. The bot row's id is also its
+# settings namespace. The tools row registers deltachat_send for every agent;
+# disable it, or mount `@soffits/dsh-deltachat-bot/tools` in one agent preset,
+# to limit who gets it.
+- insert:
+    - id: deltachat-bot
+      name: '@soffits/dsh-deltachat-bot'
+    - id: deltachat-bot-tools
+      name: '@soffits/dsh-deltachat-bot/tools'

package/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Delta Chat bot">
+  <defs>
+    <linearGradient id="ddb-bg" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#3D6FD9"/>
+      <stop offset="1" stop-color="#2A4FA8"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="15" fill="url(#ddb-bg)"/>
+  <path d="M14 18c0-3.3 2.7-6 6-6h24c3.3 0 6 2.7 6 6v18c0 3.3-2.7 6-6 6H28l-9 8v-8h-1c-2.2 0-4-1.8-4-4z" fill="#fff"/>
+  <path d="M32 18.5 41.5 35h-19z" fill="none" stroke="#2A4FA8" stroke-width="3.2" stroke-linejoin="round"/>
+  <circle cx="48" cy="48" r="9" fill="#fff"/>
+  <rect x="44.6" y="46.4" width="6.8" height="5.6" rx="1.2" fill="#2A4FA8"/>
+  <path d="M45.9 46.6v-1.9a2.1 2.1 0 0 1 4.2 0v1.9" fill="none" stroke="#2A4FA8" stroke-width="1.5"/>
+</svg>

package/index.js

@@ -0,0 +1,4 @@
+/** Host entry point; the implementation lives in src/. */
+export { apply } from './src/app.js'
+export { Config } from './src/config.js'
+export { name } from './src/constants.js'

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Delta Chat Bot",
+    "description": "Chat with DSH sessions over Delta Chat: an end-to-end encrypted chatmail bot on several relays, one session per chat, commands, files and voice messages."
+  }
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@soffits/dsh-deltachat-bot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Delta Chat bot for DeepSeek Harness: an end-to-end encrypted chatmail bot on several relays, one DSH session per chat, commands, files, voice messages and a send service for other plugins.",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "dsh-deltachat": "./bin/dsh-deltachat.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./tools": "./tools.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "index.js",
+    "tools.js",
+    "src/*.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
+  },
+  "scripts": {
+    "test": "NODE_ENV=test node --import ./test/home.js --test \"test/*.test.js\"",
+    "check": "for f in index.js tools.js bin/*.js src/*.js test/*.js scripts/*.js; do node --check \"$f\" || exit 1; done",
+    "e2e": "node scripts/e2e.js"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@deltachat/jsonrpc-client": "2.69.0",
+    "@deltachat/stdio-rpc-server": "2.69.0"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "deltachat",
+    "chatmail",
+    "bot"
+  ],
+  "author": "Sakina",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soffits/dsh-deltachat-bot.git"
+  },
+  "homepage": "https://github.com/soffits/dsh-deltachat-bot#readme",
+  "bugs": {
+    "url": "https://github.com/soffits/dsh-deltachat-bot/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}