dsh-weave 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xiang Bai
+
+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

@@ -0,0 +1,78 @@
+# DSH Weave
+
+> A private, peer-to-peer fabric for connecting DeepSeek Harness nodes across machines.
+
+**DSH Weave** turns a collection of local DSH installations into an intentional network: nodes can discover trusted peers, exchange session-aware events, hand off work, and recover after a connection drops — without placing a central server in the execution path.
+
+| Status | Transport | Scope |
+| --- | --- | --- |
+| `0.1.0-rc.0` design preview | Iroh + QUIC | Trusted DSH nodes |
+
+## Why Mesh?
+
+`dsh-bridge` is the local contract: it normalizes events between DSH, a CLI, and other local runtimes. `dsh-weave` carries that same contract across machines.
+
+```text
+DSH node A ── dsh-bridge ── dsh-weave ── Iroh ── Iroh ── dsh-weave ── dsh-bridge ── DSH node B
+```
+
+Iroh supplies authenticated, encrypted QUIC connections, direct peer-to-peer paths where possible, and relay fallback where required. Mesh owns the parts specific to DSH: membership, capabilities, task approval, event ordering, and durable delivery.
+
+## Install
+
+This first release publishes the public protocol contract and architecture documents. The executable transport is not included yet.
+
+```bash
+npm install dsh-weave@next
+```
+
+```js
+import {
+  DSH_WEAVE_ALPN,
+  DSH_WEAVE_PROTOCOL_VERSION,
+  DSH_WEAVE_STAGE,
+} from "dsh-weave";
+
+console.log(DSH_WEAVE_ALPN);             // dsh-weave/1
+console.log(DSH_WEAVE_PROTOCOL_VERSION); // 1
+console.log(DSH_WEAVE_STAGE);            // design-preview
+```
+
+## The first protocol
+
+| Plane | What it carries | Delivery rule |
+| --- | --- | --- |
+| Control | invite, membership, heartbeat, capability updates | request/acknowledgement |
+| Task | offer, accept, progress, result, cancellation | idempotent at-least-once |
+| Session | user-approved context or trajectory references | explicit sharing only |
+
+Every node has a persistent network identity. Joining a mesh requires an expiring invite and an explicit local approval. A transport connection alone never grants permission to execute a task.
+
+## Security posture
+
+- End-to-end encryption is supplied by Iroh's authenticated QUIC transport.
+- A mesh allowlist and capability grants sit above transport identity.
+- Remote work is denied by default until the receiving node approves it.
+- Secrets, provider credentials, and raw filesystem access never travel as ordinary session events.
+- A self-hosted relay/discovery deployment is the production path; public relays are for development only.
+
+See [architecture](./docs/ARCHITECTURE.md), [wire protocol](./docs/PROTOCOL.md), and [security model](./docs/SECURITY.md).
+
+## Roadmap
+
+- [x] Publish the v1 protocol contract
+- [ ] `dsh-bridge` local event adapter
+- [ ] Iroh endpoint adapter and pair-by-invite flow
+- [ ] Remote task request / approval / result streams
+- [ ] Durable outbox and reconnect replay
+- [ ] Self-hosted relay and discovery guidance
+
+## Development
+
+```bash
+npm run check
+```
+
+## License
+
+MIT © Xiang Bai

package/docs/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# DSH Weave architecture
+
+## Goal
+
+DSH Weave connects trusted DeepSeek Harness nodes across hosts while preserving a local-first execution model. It is not a shared shell, a credential synchronizer, or an unauthenticated agent swarm.
+
+## Layers
+
+```text
+DSH plugin surface
+  └─ dsh-bridge: local event and task adapter
+       └─ dsh-weave core: membership, policy, outbox, routing
+            └─ Iroh adapter: Endpoint, discovery, QUIC streams, relay fallback
+```
+
+Iroh is responsible for encrypted connectivity and endpoint authentication. Mesh is responsible for application membership and authorization. The two identities are deliberately separate: an Iroh endpoint key proves a peer is the same peer; a Mesh membership record determines what that peer may request.
+
+## Node identity and membership
+
+Each node stores a long-lived Iroh key and a Mesh node record:
+
+```ts
+type MeshNode = {
+  nodeId: string;
+  endpointId: string;
+  displayName: string;
+  publicKey: string;
+  roles: ("operator" | "worker" | "observer")[];
+  capabilities: string[];
+  joinedAt: string;
+  revokedAt?: string;
+};
+```
+
+An invite contains a mesh identifier, intended roles, a short expiry, and a signature from an existing operator. The joining node must show the invite locally and require an approval action before storing membership.
+
+## Data flow
+
+1. A user approves a task handoff from DSH node A.
+2. `dsh-bridge` emits a normalized task request to mesh core.
+3. Weave core persists the request to an outbox and opens an Iroh bidirectional stream using `dsh-weave/1`.
+4. Node B validates membership and the requested capability, then asks its local DSH policy for approval.
+5. Node B sends an acknowledgement, emits progress events, and finally returns a result reference.
+6. Node A de-duplicates events by message id and records the terminal outcome.
+
+## Operational choices
+
+- Use Iroh's standard discovery and relay services for local development.
+- Use a dedicated relay map and controlled discovery service for production meshes.
+- Keep an encrypted local outbox; do not rely on relay delivery as durable storage.
+- Treat a missing heartbeat as a reachability signal, never as proof that a task failed.

package/docs/PROTOCOL.md

@@ -0,0 +1,51 @@
+# DSH Weave wire protocol v1
+
+## Transport
+
+- ALPN: `dsh-weave/1`
+- Transport: Iroh endpoint over authenticated QUIC
+- Encoding: length-prefixed UTF-8 JSON for the preview protocol
+- Streams: one control stream and one stream per task request
+
+## Envelope
+
+```ts
+type MeshEnvelope<T> = {
+  version: 1;
+  meshId: string;
+  messageId: string;
+  sentAt: string;
+  sender: string;
+  kind: string;
+  payload: T;
+};
+```
+
+`messageId` is globally unique for a node. Receivers persist recently processed ids and acknowledge duplicate messages without re-running their effects.
+
+## Control messages
+
+| Kind | Direction | Purpose |
+| --- | --- | --- |
+| `hello` | both | confirm node identity, protocol revision, and membership |
+| `heartbeat` | both | report reachability and current capacity |
+| `membership.revoke` | operator → member | revoke a node's mesh access |
+| `capability.update` | operator → member | update approved remote capabilities |
+
+## Task messages
+
+| Kind | Required response |
+| --- | --- |
+| `task.offer` | `task.accept` or `task.reject` |
+| `task.progress` | optional acknowledgement |
+| `task.result` | terminal acknowledgement |
+| `task.cancel` | `task.cancelled` or terminal result |
+
+Task payloads carry a minimal, user-approved context reference. They never include provider credentials, a blanket filesystem token, or an implicit command-execution grant.
+
+## Reliability
+
+- Sender writes each non-terminal message to the outbox before sending.
+- Receiver acknowledges after durable de-duplication, before expensive work begins.
+- Sender retries with exponential backoff until acknowledgement or expiry.
+- Task execution must be idempotent by `taskId`; a duplicate offer must return its existing state.

package/docs/SECURITY.md

@@ -0,0 +1,26 @@
+# DSH Weave security model
+
+## Trust boundaries
+
+1. Iroh transport authentication proves possession of an endpoint key.
+2. Mesh membership binds that endpoint to a named, approved node.
+3. Capability grants constrain the actions a member may request.
+4. Local DSH policy makes the final execution decision.
+
+No layer can bypass the next one.
+
+## Defaults
+
+- Unknown endpoint: reject.
+- Known endpoint without Mesh membership: reject.
+- Known member without requested capability: reject.
+- Authorized task with no local approval rule: ask the local operator.
+- Network loss: retain the outbox; do not guess task success.
+
+## Secrets and privacy
+
+Credentials remain local to their DSH installation. Session sharing is opt-in and should use redacted, bounded context objects. Operators who need control over metadata exposure should run dedicated Iroh relay and discovery infrastructure.
+
+## Review triggers
+
+Revisit this model before adding unattended execution, third-party node invitations, shared file transfer, or a central management service.

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+/** The application-layer protocol negotiated by dsh-weave peers. */
+export declare const DSH_WEAVE_ALPN: "dsh-weave/1";
+
+/** This package publishes the protocol contract before the transport runtime. */
+export declare const DSH_WEAVE_STAGE: "design-preview";
+
+/** The first public protocol revision. */
+export declare const DSH_WEAVE_PROTOCOL_VERSION: 1;

package/lib/index.js

@@ -0,0 +1,8 @@
+/** The application-layer protocol negotiated by dsh-weave peers. */
+export const DSH_WEAVE_ALPN = "dsh-weave/1";
+
+/** This package publishes the protocol contract before the transport runtime. */
+export const DSH_WEAVE_STAGE = "design-preview";
+
+/** The first public protocol revision. */
+export const DSH_WEAVE_PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "dsh-weave",
+  "version": "0.1.0-rc.0",
+  "description": "A private, peer-to-peer weave protocol for connecting DeepSeek Harness nodes across machines.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check lib/index.js && npm pack --dry-run"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "agent",
+    "mesh",
+    "iroh",
+    "p2p",
+    "quic"
+  ],
+  "author": "Xiang Bai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baixianger/dsh-weave.git"
+  },
+  "bugs": {
+    "url": "https://github.com/baixianger/dsh-weave/issues"
+  },
+  "homepage": "https://github.com/baixianger/dsh-weave#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}