dsh-interconnect 0.1.0

package/lib/types/interconnect/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Wire contracts for `@deepseek-ai/dsh-interconnect`.
+ * The transport reuses the Connection RPC envelope (`ClientRequest` /
+ * `ServerResponse` from `@deepseek-ai/dsh-host-apiproxy/api`); this module
+ * defines only the business payloads that ride inside that envelope.
+ * @module @deepseek-ai/dsh-interconnect
+ */
+/**
+ * Logical HTTP route prefix this service owns. Requests reach endpoints as
+ * `<baseURL>/interconnect/<endpoint>`.
+ */
+export declare const INTERCONNECT_CHANNEL = "/interconnect";
+/**
+ * Credential reference holding the shared auth token. Both halves of a link
+ * must resolve the same value: inbound requests are rejected unless their
+ * `Authorization: Bearer <token>` matches this secret, and outbound requests
+ * send it. An unconfigured token fails closed on the inbound side.
+ */
+export declare const INTERCONNECT_TOKEN_REF = "DSH_INTERCONNECT_TOKEN";
+/**
+ * Business payload for the `send` endpoint: deliver one text message to one
+ * live session of the receiving instance.
+ */
+export interface SendPayload {
+    /** Target session id on the receiving instance. */
+    readonly sessionId: string;
+    /** Message text delivered to the peer session's inbox. */
+    readonly text: string;
+}
+/** Business result of a `send` endpoint call. */
+export interface SendResult {
+    /** True when the target session is live on the receiving instance and the message was delivered. */
+    readonly delivered: boolean;
+    /** Echoed receiver instance id (diagnostic; never trusted for routing). */
+    readonly instance: string;
+}
+/** Business result of a `ping` endpoint call. */
+export interface PingResult {
+    /** Always true for an authenticated, live receiver. */
+    readonly pong: true;
+    /** The receiving instance's self-reported id. */
+    readonly instance: string;
+}
+/** Outbound delivery request: receiver origin plus a `send` business payload. */
+export interface SendRequest {
+    /** Receiver origin, e.g. `http://127.0.0.1:3080`. */
+    readonly baseUrl: string;
+    readonly sessionId: string;
+    readonly text: string;
+}
+/**
+ * One serializable lifecycle fact pushed from an emitting instance to its
+ * peers. `kind` discriminates the union; the remaining fields are the compact
+ * facts extractable from the source event without serializing live objects.
+ */
+export type EventNotification = {
+    readonly kind: 'agent/created';
+    readonly sessionId: string;
+} | {
+    readonly kind: 'agent/disposed';
+    readonly sessionId: string;
+} | {
+    readonly kind: 'agent/status';
+    readonly sessionId: string;
+    readonly status: 'idle' | 'running';
+} | {
+    readonly kind: 'session/created';
+    readonly sessionId: string;
+    readonly parentSessionId?: string;
+} | {
+    readonly kind: 'session/disposed';
+    readonly sessionId: string;
+} | {
+    readonly kind: 'subagent/end';
+    readonly provider: string;
+    readonly childSessionId: string;
+    readonly stopReason: string;
+};
+/**
+ * Wire payload for the `event` endpoint: the pushed fact plus the emitting
+ * instance's self-reported id, so a many-upstream receiver can attribute it.
+ */
+export interface EventPayload {
+    /** Emitting instance's self-reported id. */
+    readonly sender: string;
+    /** The serialized lifecycle fact. */
+    readonly notification: EventNotification;
+}
+/**
+ * One text frame exchanged over a persistent WebSocket peer link. `hello`
+ * opens a link with the dialing side's identity; `event` pushes one
+ * notification in either direction. Native ws ping/pong carries the heartbeat,
+ * so no application-level keepalive frame exists.
+ */
+export type LinkFrame = {
+    readonly type: 'hello';
+    readonly sender: string;
+} | {
+    readonly type: 'event';
+    readonly notification: EventNotification;
+};
+/**
+ * Handle to one established outbound WebSocket peer link. `close` tears the
+ * socket down and cancels reconnection; `peer` records the dialed receiver.
+ */
+export interface WebSocketLinkHandle {
+    /** The dialed peer origin. */
+    readonly peer: string;
+    /** Terminate the socket and stop reconnect attempts. */
+    close(): void;
+}
+/** Service config bound by the Composition loader. */
+export interface Config {
+    /** Self-reported id of this instance, echoed in ping/send results for diagnostics. */
+    readonly instanceId: string;
+    /** Request timeout for outbound deliveries, in milliseconds. */
+    readonly requestTimeoutMs: number;
+    /**
+     * Peer instance origins to fan local events out to at startup. A runtime
+     * `subscribe` can extend the set without restart; an unset list fans nothing
+     * out until a peer subscribes.
+     */
+    readonly peers?: string[];
+    /**
+     * How an inbound `send` message reaches its target session.
+     * - `followup` wakes the target agent into a new turn carrying the message.
+     * - `inject` seeds model-facing context without waking the agent (it is
+     *   claimed at the next step boundary, and may miss a step already claimed).
+     */
+    readonly delivery?: 'followup' | 'inject';
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/interconnect/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/interconnect/types.ts"],"names":[],"mappings":"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"}

package/lib/types/tool-interconnect/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Model-facing tools for cross-instance message handoff: `interconnect_send`
+ * delivers one text message to a live session on a peer DSH instance, and
+ * `interconnect_ping` probes a peer's liveness and identity.
+ *
+ * The tools consume the host-plane `interconnect` service and publish nothing
+ * themselves, so this row sits as an ordinary tool plugin in a preset while
+ * the service it reaches stays host-side (the same split `tool-goal` uses
+ * against `goals`).
+ * @module @deepseek-ai/dsh-tool-interconnect
+ */
+import { Context } from '@deepseek-ai/cordis';
+/** Services required before the tools can register. */
+export declare const inject: string[];
+/**
+ * Register the two tool surfaces. Registration is idempotent per fiber; the
+ * tools unregister with the owning fiber.
+ * @param ctx - connection context carrying the interconnect service and the tool registry.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/tool-interconnect/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tool-interconnect/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAK7C,uDAAuD;AACvD,eAAO,MAAM,MAAM,UAA4B,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAoFxC"}

package/lib/types/tool-interconnect/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-interconnect`.
+ * @module @deepseek-ai/dsh-tool-interconnect/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-interconnect-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/tool-interconnect/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../../src/tool-interconnect/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,gCAAgC,CAAA;AACjD,0DAA0D;AAC1D,eAAO,MAAM,MAAM,UAAiB,CAAA;AAWpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "dsh-interconnect",
+  "description": "Cross-instance message/event handoff plugins for DeepSeek Harness (DSH): interconnect service + model-facing tools",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./interconnect": {
+      "types": "./lib/types/interconnect/index.d.ts",
+      "default": "./lib/interconnect/index.js"
+    },
+    "./tool-interconnect": {
+      "types": "./lib/types/tool-interconnect/index.d.ts",
+      "default": "./lib/tool-interconnect/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-agent": "*",
+    "@deepseek-ai/dsh-credentials": "*",
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/dsh-session": "*",
+    "@deepseek-ai/dsh-subagent": "*",
+    "@deepseek-ai/dsh-host-apiproxy": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/dsh-invariants": "*",
+    "@deepseek-ai/schemastery": "*",
+    "ws": "*"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "link:../dsh/vendor/cordis",
+    "@deepseek-ai/schemastery": "link:../dsh/vendor/schemastery",
+    "@deepseek-ai/dsh-agent": "link:../dsh/packages/core/agent",
+    "@deepseek-ai/dsh-credentials": "link:../dsh/packages/credentials/credentials",
+    "@deepseek-ai/dsh-llm": "link:../dsh/packages/llm/llm",
+    "@deepseek-ai/dsh-session": "link:../dsh/packages/core/session",
+    "@deepseek-ai/dsh-subagent": "link:../dsh/packages/subagent/subagent",
+    "@deepseek-ai/dsh-host-apiproxy": "link:../dsh/packages/host/apiproxy",
+    "@deepseek-ai/dsh-host-webserver": "link:../dsh/packages/host/webserver",
+    "@deepseek-ai/dsh-tools": "link:../dsh/packages/core/tools",
+    "@deepseek-ai/dsh-invariants": "link:../dsh/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/dsh-system-prompt": "link:../dsh/packages/core/system-prompt",
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.25.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8",
+    "ws": "^8.21.0"
+  }
+}