relay-dsh-plugin-events 0.1.0-internal.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yangbobo2021 and Relay contributors
+
+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,28 @@
+# Relay Events for DeepSeek Harness
+
+`relay-dsh-plugin-events` is the durable, provider-neutral Wait/Event/Delivery
+core for official DeepSeek Harness. It adds Agent tools, generic JSON ingress,
+delivery to the owning existing Session, recovery, and a Waiting Events settings
+surface without adding an execution backend.
+
+```bash
+# After building this repository (see below):
+dsh plugin --profile web add ./relay-dsh-plugin-events-0.1.0.tgz
+dsh web
+```
+
+Semantic routing and Monitor execution are separate plugins. Without a Router,
+Events uses exact event-type matching. Without Monitors, Wait-only registration
+and external ingress remain fully usable.
+
+See [SPEC.md](SPEC.md) and
+[delivery scenarios](docs/acceptance-scenarios.md).
+
+Set `DSH_ROOT` to the prepared immutable official DSH checkout, then run
+`npm ci --ignore-scripts && npm run verify && npm pack`.
+The tarball includes built runtime files. A raw GitHub checkout intentionally does
+not track `lib/`; do not install `#main` as if it were a built release. This delivery
+does not claim an npm registry publication.
+
+Tested official DSH reference:
+`b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`.

package/SPEC.md

@@ -0,0 +1,82 @@
+# Relay DSH Events Plugin Specification
+
+Status: Accepted for `0.1.0`
+
+## Purpose
+
+`relay-dsh-plugin-events` is the provider-neutral durable event core for official
+DeepSeek Harness. It stores Waits and Events, selects a registered Router (or an
+exact fallback), creates idempotent Deliveries, and admits each Delivery through
+the owning existing DSH Session.
+
+## Boundary
+
+The plugin owns:
+
+- Wait, Event, routing-attempt, routing-decision, Delivery, Activation, and Monitor
+  persistence in one local SQLite database;
+- the `relayEvents` Cordis service and its versioned Router/Monitor provider slots;
+- exact event-type fallback routing when no Router provider is registered;
+- delivery to the existing DSH Session, stable Activation identity, and background
+  recovery of queued Deliveries;
+- `relay_register_waits` and `relay_cancel_waits` Agent tools;
+- generic JSON ingress at `POST /api/relay/events`;
+- the Waiting Events management Remote and Settings section.
+
+The plugin does not own:
+
+- model calls or semantic routing policy;
+- Monitor observation, detection, scheduling, or generated code;
+- email, CI, or provider-specific Webhook normalization;
+- conversation creation or an execution backend;
+- notification delivery for escalated Events.
+
+## Public Service Contract
+
+`ctx.relayEvents.apiVersion` is `1`. The public service exposes high-level event
+operations and two replaceable provider registrations:
+
+- `registerRouter(provider)` accepts exactly one active Router with stable `id` and
+  `route({ event, eventRecord, sessions })`;
+- `registerMonitorProvider(provider)` accepts exactly one active Monitor provider
+  with `prepare`, `checkMonitor`, and lifecycle-safe disposal;
+- Wait/Event operations: `registerWaits`, `cancelWaits`, `listWaits`,
+  `handleEvent`, and `dispatchSession`;
+- Monitor persistence operations: `beginMonitorCheck`, `completeMonitorCheck`,
+  `failMonitorCheck`, `abandonMonitorCheck`, and `listDueMonitors`. No SQLite
+  handle, mutable map, or DSH Agent object crosses the service boundary.
+
+Provider registration is owned by the registering Cordis fiber. Duplicate active
+providers fail closed. Unloading a provider restores the exact fallback Router or
+the Monitor-unavailable state without unloading Events.
+
+## Reliability
+
+- Event ingestion is idempotent by source identity and fingerprint.
+- Routing decisions are validated against the current Wait snapshot and committed
+  once.
+- Delivery creation and Wait claim are atomic.
+- Failed admission keeps the same Event, Delivery, and Activation IDs queued.
+- Admission succeeds when the stable inbox message has been flushed to DSH
+  persistence, not when the model turn finishes. A retry recognizes the persisted
+  Activation message and does not enqueue another follow-up.
+- Reappearing Monitor trigger keys do not create another Delivery or pause a
+  rearmed Monitor; its replacement Wait stays active.
+- A background recovery scan retries queued Deliveries after failure or Host restart.
+- Events never create DSH Sessions and never switch the selected Web Session.
+- Shutdown stops new operations, waits for in-flight work, disposes routes/listeners,
+  and closes SQLite last.
+
+## Security
+
+- Loopback ingress may omit a token. Non-loopback ingress requires an exact Bearer
+  token and fails closed when no token is configured.
+- Event fields remain untrusted content in the injected DSH envelope.
+- Payload size is bounded before JSON parsing.
+- Provider-specific signatures are outside this generic ingress boundary.
+
+## Delivery Acceptance
+
+The release must pass unit, contract, packed-package, official-DSH, and composition
+acceptance. The executable scenario list is in
+[`docs/acceptance-scenarios.md`](docs/acceptance-scenarios.md).

package/contracts/decision.mjs

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+
+const BASE_DISPOSITIONS = new Set(["deliver", "escalate", "dismiss"]);
+
+export function validateRoutingDecision({
+  decision,
+  sessions,
+  allowDeduplicate = false,
+  canDeduplicate = false,
+  label = "routing decision",
+}) {
+  assert.ok(decision && typeof decision === "object", `${label}: decision is required`);
+  const dispositions = allowDeduplicate
+    ? new Set([...BASE_DISPOSITIONS, "deduplicate"])
+    : BASE_DISPOSITIONS;
+  assert.ok(
+    dispositions.has(decision.disposition),
+    `${label}: invalid disposition ${decision.disposition}`,
+  );
+  assert.ok(Array.isArray(decision.deliveries), `${label}: deliveries must be an array`);
+
+  if (decision.disposition === "deduplicate") {
+    assert.ok(canDeduplicate, `${label}: deduplicate requires an existing event`);
+    assert.equal(decision.deliveries.length, 0, `${label}: duplicate cannot create deliveries`);
+    return decision;
+  }
+
+  assert.equal(typeof decision.actionable, "boolean", `${label}: actionable must be boolean`);
+  assert.ok(Array.isArray(decision.evidence), `${label}: evidence must be an array`);
+  assert.equal(typeof decision.summary, "string", `${label}: summary must be a string`);
+
+  if (decision.disposition === "deliver") {
+    assert.equal(decision.actionable, true, `${label}: delivered event must be actionable`);
+    assert.ok(decision.deliveries.length > 0, `${label}: deliver requires a target`);
+  } else {
+    assert.equal(decision.deliveries.length, 0, `${label}: ${decision.disposition} cannot deliver`);
+    assert.equal(
+      decision.actionable,
+      decision.disposition === "escalate",
+      `${label}: actionable conflicts with ${decision.disposition}`,
+    );
+  }
+
+  const sessionsById = new Map(sessions.map((session) => [session.session_id, session]));
+  const deliveredSessionIds = decision.deliveries.map((delivery) => delivery.session_id);
+  assertUnique(deliveredSessionIds, `${label}: delivered session IDs`);
+
+  const selectedWaits = [];
+  for (const delivery of decision.deliveries) {
+    const session = sessionsById.get(delivery.session_id);
+    assert.ok(session, `${label}: unknown session ${delivery.session_id}`);
+    assert.ok(Array.isArray(delivery.wait_ids), `${label}: wait_ids must be an array`);
+    assertUnique(delivery.wait_ids, `${label}: delivered wait IDs`);
+    assert.equal(typeof delivery.relation, "string", `${label}: relation must be a string`);
+    assert.ok(
+      Number.isFinite(delivery.confidence) &&
+        delivery.confidence >= 0 &&
+        delivery.confidence <= 1,
+      `${label}: confidence must be between 0 and 1`,
+    );
+
+    for (const waitId of delivery.wait_ids) {
+      const wait = session.waits.find((candidate) => candidate.wait_id === waitId);
+      assert.ok(wait, `${label}: wait ${waitId} does not belong to ${session.session_id}`);
+      assert.equal(wait.status, "active", `${label}: wait ${waitId} is not active`);
+      selectedWaits.push(wait);
+    }
+  }
+
+  if (decision.deliveries.length > 1) {
+    assert.ok(selectedWaits.length > 0, `${label}: multi-session delivery needs matched waits`);
+    assert.ok(
+      selectedWaits.every((wait) => wait.exclusive === false),
+      `${label}: exclusive event cannot target multiple sessions`,
+    );
+  }
+
+  return decision;
+}
+
+function assertUnique(values, label) {
+  assert.equal(new Set(values).size, values.length, `${label} must be unique`);
+}

package/contracts/decision.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["disposition", "actionable", "deliveries", "evidence", "summary"],
+  "properties": {
+    "disposition": {
+      "enum": ["deliver", "escalate", "dismiss"]
+    },
+    "actionable": {
+      "type": "boolean"
+    },
+    "deliveries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["session_id", "wait_ids", "relation", "confidence"],
+        "properties": {
+          "session_id": {
+            "type": "string"
+          },
+          "wait_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "relation": {
+            "type": "string"
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          }
+        }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "summary": {
+      "type": "string"
+    }
+  }
+}

package/contracts/index.mjs

@@ -0,0 +1,23 @@
+export { validateRoutingDecision } from "./decision.mjs";
+
+export const RELAY_EVENTS_API_VERSION = 1;
+
+export function validateRouterProvider(provider) {
+  if (!provider || typeof provider !== "object") throw new TypeError("router provider is required");
+  if (!/^[a-z][a-z0-9._-]{0,63}$/u.test(provider.id ?? "")) {
+    throw new TypeError("router provider requires a lowercase stable id");
+  }
+  if (typeof provider.route !== "function") throw new TypeError("router provider requires route()");
+  return provider;
+}
+
+export function validateMonitorProvider(provider) {
+  if (!provider || typeof provider !== "object") throw new TypeError("monitor provider is required");
+  if (!/^[a-z][a-z0-9._-]{0,63}$/u.test(provider.id ?? "")) {
+    throw new TypeError("monitor provider requires a lowercase stable id");
+  }
+  for (const method of ["prepare", "checkMonitor"]) {
+    if (typeof provider[method] !== "function") throw new TypeError(`monitor provider requires ${method}()`);
+  }
+  return provider;
+}

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: relay-events-host
+      name: 'relay-dsh-plugin-events'
+      config:
+        dispatchPollIntervalMs: 1000

package/docs/acceptance-scenarios.md

@@ -0,0 +1,24 @@
+# Events Delivery Acceptance Scenarios
+
+Official DSH reference: `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`
+
+| ID | Scenario | Required result | Evidence |
+| --- | --- | --- | --- |
+| EVT-001 | Events-only boot | Packed plugin installs into a pristine official DSH profile and Host boots without Codex, Claude, Router, or Monitors. | package acceptance |
+| EVT-002 | Exact fallback delivery | An Event whose type equals one active Wait is delivered once to that existing Session. | unit + Host contract |
+| EVT-003 | Unmatched fallback | An unmatched Event is durably dismissed with an inspectable reason and starts no Session. | unit |
+| EVT-004 | Duplicate ingress | Repeating the same provider identity/fingerprint returns the original Event and creates no second Delivery. | unit + HTTP |
+| EVT-005 | Router substitution | A fake registered Router receives the compact snapshot; unload restores exact fallback. | service contract |
+| EVT-006 | Duplicate Router | A second active Router registration fails without replacing the first. | service contract |
+| EVT-007 | Monitor provider absence | Wait-only registration works; registration containing Monitors fails before replacing prior Waits. | service contract |
+| EVT-008 | Atomic prepared Monitor registration | A fake Monitor provider baseline succeeds and Wait/Monitor records commit together; baseline failure changes neither. | integration |
+| EVT-009 | Delivery retry identity | First admission fails, background recovery succeeds, and Event/Delivery/Activation IDs remain unchanged. | fake clock integration |
+| EVT-010 | Restart recovery | A database with queued Delivery is reopened and recovered without re-routing or duplicate injection. | integration |
+| EVT-011 | Ingress authorization | Loopback is accepted; non-loopback missing/wrong token is rejected; valid token succeeds. | HTTP unit |
+| EVT-012 | Ingress bounds | Wrong method/content type, malformed JSON, and oversized bodies receive stable errors. | HTTP unit |
+| EVT-013 | DSH tool ownership | Tools attach to every root Agent and use the authenticated Session ID rather than a model-supplied ID. | Host contract |
+| EVT-014 | Management operations | List, open, cancel, and provider-backed run-now operate through the typed Remote. | Host/client contract |
+| EVT-015 | Clean unload | New operations fail during shutdown; in-flight work settles; listeners, Remote, service, timers, and SQLite are released. | lifecycle integration |
+| EVT-016 | Backend neutrality | Events-only, Events+Codex, and Events+Claude compositions contain no backend import or backend-name branch in Events. | static + official DSH |
+| EVT-017 | Package boundary | Tarball contains built/public artifacts only and imports in a clean directory. | `npm pack` acceptance |
+

package/docs/test-review.md

@@ -0,0 +1,68 @@
+# Events Test Review
+
+## Review 1 — service extraction
+
+- Preserved Runtime tests for replacement Waits, multi-Session delivery,
+  escalation, cancellation, ordering, and Activation identity.
+- Added Router substitution/duplicate/disposal, Monitor baseline failure,
+  restart recovery, and shutdown drain coverage.
+- The first run exposed an unhandled rejected Promise created by cleanup tracking;
+  handled success/error branches now remove in-flight Promises, and the regression
+  test passes without asynchronous activity warnings.
+
+## Review 2 — Agent bridge
+
+- Verified tools derive Session ownership from authenticated Agent context.
+- Verified Events owns only Wait registration/cancellation tools; timer ownership
+  moved to Monitors.
+- Extended and asserted Monitor proposal fields without accepting a model-supplied
+  Session id.
+
+Packed official-DSH boot/composition and browser checks run in Relay's cross-plugin
+delivery harness.
+
+## Review 3 — independent checkout execution
+
+- Verified a fresh plugin checkout can run `npm test` without relying on a parent
+  workspace installation.
+- Added the same official-DSH peer-link preparation used by typecheck and build to
+  the test lifecycle; this prevents a false local pass caused by hoisted packages.
+
+## Review 4 — composed Router audit identity
+
+- The cross-plugin test showed that a substituted Router delivered correctly while
+  its routing attempt was attributed to an internal slot name.
+- Events now reads `name` and `model` dynamically from the active provider, and the
+  service test asserts provider attribution before fallback restoration.
+
+## Review 5 — submodule workspace type identity
+
+- Running the plugin inside Relay exposed duplicate branded DSH types resolved from
+  the parent workspace instead of the pinned official checkout.
+- The original wildcard peer-directory mapping did **not** fix package subpath
+  exports. The continuation replaces it with a generated map of official declaration
+  exports (including `/types` and transitive brands). Both typecheck and build now pass;
+  `dsh-type-paths.test.mjs` covers this resolution rule without suppressing errors.
+
+## Review 6 — real composition and admission lifecycle
+
+- Persisted Observer identity in the Monitor manifest and restored it on hydration;
+  otherwise every non-clock observation failed after baseline despite passing fake-store tests.
+- Grouped multiple matching Waits per Session in exact routing (one Delivery per Session).
+- Agent tool disposers now belong to the plugin as well as the Agent, preventing stale tools after unload.
+- Admission acknowledges inbox flush, not whole model-turn completion. Stable message IDs and
+  persisted inbox/message lookup prevent duplicate follow-ups after an acknowledgement retry.
+- Added real SQLite composition regressions for recurring rearm, Observer failure, lease exclusion,
+  atomic baseline rollback and overdue restart; added background recovery and inbox retry unit tests.
+
+## Review 7 — packed delivery and composition
+
+- Clean-directory tarball installation imports all public entries without parent
+  source or private runtime packages. Host-only Router/Monitors need no browser entry.
+- Added real Cordis dependency appearance/removal/reappearance coverage; surviving
+  Agents retain no stale tools after plugin unload.
+- Replaced misleading raw GitHub installation instructions with build-and-pack
+  instructions, since generated `lib/` is intentionally not tracked.
+- A rearmed recurring Monitor now ignores already committed trigger keys without
+  pausing again. The regression checks disappearance/reappearance and the still-active
+  replacement Wait. Shutdown lease release is tested against real SQLite.