@sakikotgw/pad-gateway-jump 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @sakikotgw/pad-gateway-jump
 
-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.
+PAD 的 **0.2.x 跳转专用 carrier**：在 DSH host 里起一个 loopback HTTP，只服务会话跳转通道，写与完整 `pad-gateway` 相同的 `<DSH_HOME>/pad-gateway.json` 广告，供 `@sakikotgw/pad-session-jump` 长轮询。
+
+## 为什么单独一个包
+
+完整 `@sakikotgw/pad-gateway` 会挂官方 apiproxy（`/api`），依赖 `@deepseek-ai/dsh-host-apiproxy` 并要求 `engines.dsh >=0.1.0-rc.7 <0.2.0`。但 **0.2.x 没有对应的 npm apiproxy**：装不上、bundle patch 里的 apiproxy 行也加载不了。本包只带跳转通道，`engines.dsh` 放宽到 `>=0.1.0-rc.7`，用于 0.2.x（也兼容 0.1.x，但 0.1.x 应用完整版 gateway 以保留 `/api`）。
+
+## 端点
+
+| 方法 | 路径 | 鉴权 | 说明 |
+|---|---|---|---|
+| GET | `/pad/ping` | Bearer | `{ok, pid, profile, schema, capabilities:{jump:true,api:false}}` |
+| POST | `/pad/jump` | Bearer | 入队：`{sessionId}` → `{ok, seq}` |
+| GET | `/pad/jump?since=N` | Bearer | 长轮询（25s 超时 204） |
+| POST | `/pad/jump/ack` | Bearer | 消费回执 |
+| * | `/api/*` | — | 固定 503：本包不代理 apiproxy |
+
+CORS 只放行 loopback origin 与 `dsh-app://app`。队列语义（TTL 30s、容量 20、seq 单调）与完整版一致。
+
+## 安装（0.2.x 实例）
+
+```powershell
+dsh plugin --profile web add file:E:\pack-agent\agent-pack-dsh\gateway-jump
+```
+
+装完重启 `dsh web`；`<DSH_HOME>/pad-gateway.json` 会出现，`capabilities.api=false`。
+
+## 测试与同步
+
+```powershell
+node --test test/jump.test.mjs        # 7 pass（与完整版共用实现）
+node scripts/sync-from-gateway.mjs    # 从 ../gateway 同步 lib/jump.mjs 与测试
+```
+
+`lib/jump.mjs` / `test/jump.test.mjs` 是生成的副本，改实现请改 `../gateway` 后跑 sync。
+
+## 与完整 gateway 的选择
+
+| 实例 DSH | 用哪个 |
+|---|---|
+| `0.1.x` | `@sakikotgw/pad-gateway`（含 `/api` 代理 + 跳转） |
+| `0.2.x` | `@sakikotgw/pad-gateway-jump`（仅跳转；`/api` 不可用） |
+
+PAD 侧按实例钉的 DSH 版本选择安装哪个包（待 M1 接线）。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# pad-gateway-jump bundle patch: mounts the jump-only carrier row.
+# Deliberately does NOT insert apiproxy / directory-picker rows: dsh 0.2.x
+# has no matching npm package for them, and the jump channel needs neither.
+- insert:
+    - id: pad-gateway-jump
+      name: '@sakikotgw/pad-gateway-jump'

package/lib/index.js

@@ -0,0 +1,138 @@
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createJumpHttpHandler, createJumpStore } from "./jump.mjs";
+
+/**
+ * Jump-only loopback carrier for DeepSeek Harness 0.2.x.
+ *
+ * The full `@sakikotgw/pad-gateway` mounts the official apiproxy too; on 0.2.x
+ * apiproxy has no matching npm package, so installing it is refused and its
+ * bundle patch cannot load. This carrier serves only the jump channel:
+ *
+ *   GET  /pad/ping
+ *   POST /pad/jump
+ *   GET  /pad/jump?since=N
+ *   POST /pad/jump/ack
+ *
+ * It writes the same `<DSH_HOME>/pad-gateway.json` ad shape (url points to
+ * `/api` for compatibility with PAD's ad reader; endpoints live on the origin).
+ */
+const name = "pad-gateway-jump";
+const inject = [];
+const GATEWAY_FILE = "pad-gateway.json";
+const GATEWAY_LOG = "pad-gateway.log";
+const GATEWAY_SCHEMA = "pack-agent.pad-gateway/v1";
+
+function tokenOk(got, expected) {
+  const a = Buffer.from(got);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function bearer(req) {
+  const raw = req.headers.authorization;
+  if (typeof raw !== "string") return "";
+  return raw.startsWith("Bearer ") ? raw.slice(7).trim() : "";
+}
+
+function apply(ctx, config = {}) {
+  const home = (config.home ?? process.env.DSH_HOME ?? "").trim();
+  const trace = (line) => {
+    const stamped = `${new Date().toISOString()} ${line}\n`;
+    ctx.logger?.info?.(line);
+    if (!home) {
+      process.stderr.write(`[pad-gateway-jump] ${stamped}`);
+      return;
+    }
+    try {
+      appendFileSync(join(home, GATEWAY_LOG), stamped);
+    } catch {}
+  };
+  if (!home) {
+    trace("no DSH_HOME, pad gateway-jump not started");
+    return;
+  }
+  const token = randomBytes(32).toString("hex");
+  const file = join(home, GATEWAY_FILE);
+  const jumpStore = createJumpStore({
+    ttlMs: Number(process.env.PAD_GATEWAY_JUMP_TTL_MS ?? 0) || undefined,
+    timeoutMs: Number(process.env.PAD_GATEWAY_JUMP_TIMEOUT_MS ?? 0) || undefined,
+  });
+  const handleJump = createJumpHttpHandler({ store: jumpStore, token });
+  let server;
+  trace(`apply() in pid ${process.pid}`);
+  const boot = async () => {
+    server = createServer((req, res) => {
+      (async () => {
+        try {
+          if (await handleJump(req, res)) return;
+          if (!tokenOk(bearer(req), token)) {
+            res.writeHead(401, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "unauthorized" }));
+            return;
+          }
+          const path = (req.url ?? "/").split("?")[0];
+          if (path === "/pad/ping") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                ok: true,
+                pid: process.pid,
+                profile: process.env.DSH_PROFILE ?? null,
+                schema: GATEWAY_SCHEMA,
+                capabilities: { jump: true, api: false },
+              }),
+            );
+            return;
+          }
+          res.writeHead(503, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "apiproxy not part of pad-gateway-jump" }));
+        } catch (err) {
+          if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+          res.end(String(err instanceof Error ? err.message : err));
+        }
+      })();
+    });
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === "string") throw new Error("pad gateway-jump failed to bind");
+    const ad = {
+      schema: GATEWAY_SCHEMA,
+      url: `http://127.0.0.1:${addr.port}/api`,
+      token,
+      pid: process.pid,
+      capabilities: { jump: true, api: false },
+      ...(process.env.DSH_PROFILE ? { profile: process.env.DSH_PROFILE } : {}),
+    };
+    writeFileSync(file, `${JSON.stringify(ad, null, 2)}\n`, { encoding: "utf8", mode: 384 });
+    try {
+      chmodSync(file, 384);
+    } catch {}
+    trace(`listening on ${ad.url} (jump channel ready, api disabled)`);
+  };
+  boot().catch((err) => {
+    const detail = err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err);
+    trace(`boot failed: ${detail}`);
+    ctx.logger?.warn?.(`[pack-agent] pad gateway-jump failed: ${detail}`);
+  });
+  ctx.on?.("dispose", () => {
+    jumpStore.dispose();
+    server?.close();
+    try {
+      if (existsSync(file)) {
+        const cur = JSON.parse(readFileSync(file, "utf8"));
+        if (cur.pid === process.pid && cur.token === token) rmSync(file, { force: true });
+      }
+    } catch {
+      rmSync(file, { force: true });
+    }
+  });
+}
+
+export { apply, inject, name, GATEWAY_SCHEMA, GATEWAY_FILE, GATEWAY_LOG };
+export default apply;

package/lib/jump.mjs

@@ -0,0 +1,238 @@
+/**
+ * pad-gateway jump channel (host side).
+ *
+ * A tiny authenticated queue used by PAD to hand a session target to the page
+ * runtime: PAD POSTs an event, the page's client plugin long-polls it, then
+ * calls `sessions.open()`. Reuses the gateway's loopback HTTP carrier + bearer
+ * token — no extra port, no extra process.
+ *
+ * Transport contract (see agent-pack-dsh/docs/session-jump.md §7.1):
+ *   POST /pad/jump        {sessionId}            -> {ok, seq}
+ *   GET  /pad/jump?since=N                        -> event JSON | 204 (timeout)
+ *   POST /pad/jump/ack    {seq, ok}               -> {ok:true}
+ *   OPTIONS /pad/jump*                            -> CORS preflight
+ *
+ * The page origin may be a loopback http(s) origin (browser) or `dsh-app://app`
+ * (official desktop renderer); anything else is rejected.
+ */
+import { timingSafeEqual } from "node:crypto";
+
+export const JUMP_SCHEMA = "pack-agent.pad-jump/v1";
+export const JUMP_DEFAULT_TTL_MS = 30_000;
+export const JUMP_DEFAULT_TIMEOUT_MS = 25_000;
+export const JUMP_MAX_QUEUE = 20;
+export const JUMP_SESSION_ID = /^session-[A-Za-z0-9][A-Za-z0-9-]{7,63}$/;
+
+const LOOPBACK_ORIGIN = /^https?:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/;
+const DESKTOP_ORIGIN = "dsh-app://app";
+
+/**
+ * @param {string} id raw session id
+ * @returns {boolean} whether it is a canonical DSH session id
+ */
+export function isSessionId(id) {
+  return typeof id === "string" && JUMP_SESSION_ID.test(id);
+}
+
+/**
+ * @param {string} origin request Origin header
+ * @returns {boolean} whether the origin may read jump responses
+ */
+export function isAllowedOrigin(origin) {
+  if (typeof origin !== "string" || origin === "") return false;
+  return origin === DESKTOP_ORIGIN || LOOPBACK_ORIGIN.test(origin);
+}
+
+/**
+ * Create the in-memory jump queue.
+ * @param {{ttlMs?: number, timeoutMs?: number, now?: () => number}} [options]
+ */
+export function createJumpStore(options = {}) {
+  const ttlMs = options.ttlMs ?? JUMP_DEFAULT_TTL_MS;
+  const timeoutMs = options.timeoutMs ?? JUMP_DEFAULT_TIMEOUT_MS;
+  const now = options.now ?? Date.now;
+  /** @type {{schema: string, seq: number, sessionId: string, at: number}[]} */
+  const events = [];
+  const waiters = new Set();
+  let seq = 0;
+
+  function prune(at) {
+    while (events.length > 0 && at - events[0].at > ttlMs) events.shift();
+  }
+
+  /**
+   * Enqueue one jump event and wake every waiting long-poll.
+   * @param {string} sessionId canonical session id
+   */
+  function publish(sessionId) {
+    if (!isSessionId(sessionId)) throw new Error("pad-jump: invalid session id");
+    const at = now();
+    prune(at);
+    const event = { schema: JUMP_SCHEMA, seq: ++seq, sessionId, at };
+    events.push(event);
+    if (events.length > JUMP_MAX_QUEUE) events.splice(0, events.length - JUMP_MAX_QUEUE);
+    for (const waiter of [...waiters]) waiter.settle(event);
+    return event;
+  }
+
+  /**
+   * Long-poll for the first event after `since`.
+   * @param {number} since last consumed seq
+   * @returns {Promise<object|null>} event, or null on timeout/dispose
+   */
+  function wait(since) {
+    const at = now();
+    prune(at);
+    const found = events.find((event) => event.seq > since);
+    if (found !== undefined) return Promise.resolve(found);
+    return new Promise((resolve) => {
+      const waiter = {
+        settle(event) {
+          clearTimeout(timer);
+          waiters.delete(waiter);
+          resolve(event);
+        },
+      };
+      const timer = setTimeout(() => {
+        waiters.delete(waiter);
+        resolve(null);
+      }, timeoutMs);
+      timer.unref?.();
+      waiters.add(waiter);
+    });
+  }
+
+  function dispose() {
+    for (const waiter of [...waiters]) waiter.settle(null);
+    events.length = 0;
+  }
+
+  return {
+    publish,
+    wait,
+    dispose,
+    get lastSeq() {
+      return seq;
+    },
+    get size() {
+      return events.length;
+    },
+  };
+}
+
+/**
+ * Build the HTTP handler for the jump endpoints.
+ * @param {{store: ReturnType<typeof createJumpStore>, token: string}} options
+ * @returns {(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => Promise<boolean>}
+ */
+export function createJumpHttpHandler({ store, token }) {
+  return async function handleJump(req, res) {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (!url.pathname.startsWith("/pad/jump")) return false;
+
+    const origin = req.headers.origin;
+    if (typeof origin === "string" && origin !== "") {
+      if (!isAllowedOrigin(origin)) {
+        sendJson(res, 403, { error: "origin not allowed" });
+        return true;
+      }
+      res.setHeader("access-control-allow-origin", origin);
+      res.setHeader("vary", "origin");
+      res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+      res.setHeader("access-control-allow-headers", "authorization, content-type");
+      res.setHeader("access-control-max-age", "600");
+    }
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return true;
+    }
+    if (!authorized(req.headers.authorization, token)) {
+      sendJson(res, 401, { error: "unauthorized" });
+      return true;
+    }
+
+    if (url.pathname === "/pad/jump" && req.method === "POST") {
+      let body;
+      try {
+        body = await readJson(req);
+      } catch {
+        sendJson(res, 400, { error: "invalid json" });
+        return true;
+      }
+      const sessionId = body?.sessionId;
+      if (!isSessionId(sessionId)) {
+        sendJson(res, 400, { error: "invalid session id" });
+        return true;
+      }
+      const event = store.publish(sessionId);
+      sendJson(res, 200, { ok: true, seq: event.seq });
+      return true;
+    }
+
+    if (url.pathname === "/pad/jump" && req.method === "GET") {
+      const since = Number(url.searchParams.get("since") ?? "0");
+      const event = await store.wait(Number.isFinite(since) ? since : 0);
+      if (event === null) {
+        res.writeHead(204);
+        res.end();
+        return true;
+      }
+      sendJson(res, 200, event);
+      return true;
+    }
+
+    if (url.pathname === "/pad/jump/ack" && req.method === "POST") {
+      try {
+        await readJson(req);
+      } catch {
+        sendJson(res, 400, { error: "invalid json" });
+        return true;
+      }
+      sendJson(res, 200, { ok: true });
+      return true;
+    }
+
+    sendJson(res, 404, { error: "not found" });
+    return true;
+  };
+}
+
+function authorized(header, token) {
+  if (typeof header !== "string" || !header.startsWith("Bearer ")) return false;
+  const got = header.slice(7).trim();
+  const a = Buffer.from(got);
+  const b = Buffer.from(token);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function sendJson(res, status, value) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(value));
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > 64 * 1024) {
+        reject(new Error("body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf8").trim();
+      if (raw === "") return resolve({});
+      try {
+        resolve(JSON.parse(raw));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on("error", reject);
+  });
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@sakikotgw/pad-gateway-jump",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "PAD jump-only loopback carrier for DeepSeek Harness 0.2.x: session jump events over the same pad-gateway.json contract (no apiproxy).",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "license": "MIT",
+  "author": "sakikotgw",
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "dsh": ">=0.1.0-rc.7"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/jump.test.mjs",
+    "sync": "node scripts/sync-from-gateway.mjs"
+  }
+}