@nanhara/hara 0.70.0 → 0.89.0

package/dist/agent/route.js

@@ -0,0 +1,47 @@
+// Words that signal real coding/action work → keep the primary (strong) model. Broad on purpose: routing
+// should fire only on clearly trivial, non-actionable turns (questions, lookups, chit-chat).
+const COMPLEX = /\b(debug|refactor|implement|fix(es|ed|ing)?|build|test|deploy|migrat\w*|optimi[sz]e|architect|design|review|trace|profile|benchmark|docker|kubernetes|compile|exception|error|bug|patch|diff|commit|merge|rebase|rename|add|remove|delete|update|change|write|create|edit|run|install|generate|convert|parse|format|lint|setup|configure|wire|hook|render|fetch|query|schema|class|function|async|await|import|export)\b/i;
+/** The text of the most recent genuine user message (tool results are role:"tool", so this is stable
+ *  across a turn's tool rounds). */
+export function lastUserText(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const m = history[i];
+        if (m.role === "user")
+            return typeof m.content === "string" ? m.content : "";
+    }
+    return "";
+}
+/** True if a turn is trivial enough to hand to the cheap/general model: short, single-line, no code,
+ *  no URL, and no coding/action keyword. Defaults to FALSE (stay on the strong model) when unsure. */
+export function isTrivialTurn(text) {
+    const t = (text ?? "").trim();
+    if (!t)
+        return false;
+    if (t.length > 160)
+        return false; // long → probably substantive
+    if (t.split(/\s+/).length > 28)
+        return false;
+    if (t.includes("\n"))
+        return false; // multi-line / paste
+    if (t.includes("`"))
+        return false; // inline code / fences
+    if (/https?:\/\//i.test(t))
+        return false; // a URL to act on
+    if (/[{}();=]|=>|::|\/|\\/.test(t))
+        return false; // code-ish / a path
+    if (COMPLEX.test(t))
+        return false; // an action/coding verb
+    return true;
+}
+/** Wrap a primary + alternate provider so each turn routes to the alternate when the latest user message is
+ *  trivial, else the primary. Decided per turn from history (stable across tool rounds). */
+export function routingProvider(primary, alt) {
+    return {
+        id: primary.id,
+        model: primary.model, // reported model = primary; routing is transparent
+        turn(args) {
+            const useAlt = isTrivialTurn(lastUserText(args.history));
+            return (useAlt ? alt : primary).turn(args);
+        },
+    };
+}

package/dist/checkpoints.js

@@ -0,0 +1,91 @@
+// File-state checkpoints via a SHADOW git repo — durable "undo the agent's file changes" beyond the
+// edit-only in-memory undo (which misses bash-made changes). The shadow repo lives OUTSIDE the project
+// (~/.hara/checkpoints/<hash>/git) with GIT_DIR there + GIT_WORK_TREE = the project root, so it captures the
+// WHOLE tree, NEVER touches the user's real .git/index, and the model never sees it. Restore is
+// snapshot-then-checkout: SAFE — it reverts changed/deleted files to the checkpoint and never deletes files
+// created since (so a stray restore can't nuke new work; it's also itself undoable via the auto-snapshot).
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { findProjectRoot } from "./context/agents-md.js";
+// Heavy/derived dirs the shadow repo must never snapshot (in addition to the project's own .gitignore).
+const EXCLUDES = ["node_modules/", ".git/", "dist/", "build/", "out/", ".next/", "target/", ".venv/", "venv/", "__pycache__/", ".hara/", ".cache/", ".turbo/", "coverage/", "*.log", ".DS_Store"];
+function shadowGitDir(root) {
+    return join(homedir(), ".hara", "checkpoints", createHash("sha256").update(root).digest("hex").slice(0, 16), "git");
+}
+function git(root, gitDir, args) {
+    return execFileSync("git", args, {
+        cwd: root,
+        env: { ...process.env, GIT_DIR: gitDir, GIT_WORK_TREE: root, GIT_AUTHOR_NAME: "hara", GIT_AUTHOR_EMAIL: "hara@local", GIT_COMMITTER_NAME: "hara", GIT_COMMITTER_EMAIL: "hara@local" },
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+    }).toString();
+}
+function ensureRepo(root, gitDir) {
+    try {
+        if (!existsSync(join(gitDir, "HEAD"))) {
+            mkdirSync(gitDir, { recursive: true });
+            git(root, gitDir, ["init", "-q"]);
+            mkdirSync(join(gitDir, "info"), { recursive: true });
+            writeFileSync(join(gitDir, "info", "exclude"), EXCLUDES.join("\n") + "\n");
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Snapshot the current working tree into the shadow repo. Returns the short sha, or null on failure. */
+export function checkpoint(cwd, label) {
+    const root = findProjectRoot(cwd);
+    const gitDir = shadowGitDir(root);
+    if (!ensureRepo(root, gitDir))
+        return null;
+    try {
+        git(root, gitDir, ["add", "-A"]);
+        git(root, gitDir, ["commit", "-q", "--allow-empty", "--no-gpg-sign", "-m", (label || "checkpoint").slice(0, 120)]);
+        return git(root, gitDir, ["rev-parse", "--short", "HEAD"]).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Recent checkpoints, newest first. */
+export function listCheckpoints(cwd, n = 15) {
+    const gitDir = shadowGitDir(findProjectRoot(cwd));
+    if (!existsSync(join(gitDir, "HEAD")))
+        return [];
+    try {
+        const out = git(findProjectRoot(cwd), gitDir, ["log", `-n${n}`, "--format=%h\x1f%ct\x1f%s"]).trim();
+        if (!out)
+            return [];
+        return out.split("\n").map((l) => {
+            const [sha, ct, ...rest] = l.split("\x1f");
+            return { sha, when: Number(ct) * 1000, label: rest.join("\x1f") };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/** Restore the working tree's changed/deleted files to a checkpoint (snapshots current first, so it's
+ *  undoable). Files created AFTER the checkpoint are left in place — nothing is deleted. Returns the count of
+ *  files restored, or null on failure. */
+export function restoreCheckpoint(cwd, ref) {
+    const root = findProjectRoot(cwd);
+    const gitDir = shadowGitDir(root);
+    if (!existsSync(join(gitDir, "HEAD")))
+        return null;
+    try {
+        checkpoint(cwd, `before restore to ${ref}`); // make the restore itself undoable
+        const changed = git(root, gitDir, ["diff", "--name-only", ref, "--"]).trim(); // files differing now vs ref
+        git(root, gitDir, ["checkout", ref, "--", "."]);
+        return changed ? changed.split("\n").length : 0;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config.js

@@ -12,7 +12,7 @@ const PROVIDER_DEFAULTS = {
     openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
     "hara-gateway": { model: "", envKey: "HARA_GATEWAY_TOKEN" }, // B-end: enrolled device → token in ~/.hara/org.json, routed by the gateway
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "notify", "vimMode"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
 const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
@@ -112,6 +112,9 @@ export function loadConfig(opts = {}) {
     const embedModel = process.env.HARA_EMBED_MODEL ?? merged.embedModel;
     const embedBaseURL = process.env.HARA_EMBED_BASE_URL ?? merged.embedBaseURL;
     const embedApiKey = process.env.HARA_EMBED_API_KEY ?? merged.embedApiKey;
+    const routeModel = process.env.HARA_ROUTE_MODEL ?? merged.routeModel;
+    const routeBaseURL = process.env.HARA_ROUTE_BASE_URL ?? merged.routeBaseURL;
+    const routeApiKey = process.env.HARA_ROUTE_API_KEY ?? merged.routeApiKey;
     const mcpServers = {
         ...(globalBase.mcpServers ?? {}),
         ...(project.mcpServers ?? {}),
@@ -120,7 +123,12 @@ export function loadConfig(opts = {}) {
     const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
     const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
     const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, hooks, notify, vimMode, mcpServers, cwd: process.cwd() };
+    const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
+    const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
+    const fallbackModel = process.env.HARA_FALLBACK_MODEL ?? merged.fallbackModel;
+    const fallbackBaseURL = process.env.HARA_FALLBACK_BASE_URL ?? merged.fallbackBaseURL;
+    const fallbackApiKey = process.env.HARA_FALLBACK_API_KEY ?? merged.fallbackApiKey;
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/context/subdir-hints.js

@@ -0,0 +1,76 @@
+// Lazy per-directory project docs — when a tool touches a directory we haven't seen yet, surface that dir's
+// AGENTS.md / CLAUDE.md (the local conventions for that package) by appending it to the tool result, so a
+// monorepo's per-package rules reach the model exactly when work moves into that package. Startup already
+// loads root→cwd (agents-md.ts); this covers the subdirs the agent navigates INTO. Each dir loaded once.
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, dirname, resolve, relative, isAbsolute } from "node:path";
+import { findProjectRoot } from "./agents-md.js";
+const FILENAMES = ["AGENTS.override.md", "AGENTS.md", "CLAUDE.md"];
+const MAX = 8 * 1024;
+const loaded = new Set(); // dirs whose local doc we've already injected (per process / session)
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Candidate file/dir paths referenced by a tool call (its `path`, or path-like tokens in a shell command). */
+function pathsFrom(input) {
+    const out = [];
+    if (typeof input?.path === "string")
+        out.push(input.path);
+    if (typeof input?.command === "string")
+        for (const m of input.command.matchAll(/[\w.@~+-]*\/[\w./@+-]+/g))
+            out.push(m[0]);
+    return out;
+}
+/** Project docs for any NEW directory (strictly under cwd) this tool call touches — appendable to the tool
+ *  result. Returns "" when nothing new. Each directory is checked/loaded at most once per session. */
+export function subdirHint(input, cwd) {
+    const base = resolve(cwd);
+    const root = findProjectRoot(cwd);
+    const parts = [];
+    for (const raw of pathsFrom(input)) {
+        const absPath = isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+        const startDir = isDir(absPath) ? absPath : dirname(absPath);
+        const rel = relative(base, startDir);
+        if (!rel || rel.startsWith("..") || isAbsolute(rel))
+            continue; // not strictly under cwd → startup already covered it
+        // collect unseen dirs from startDir up to (but excluding) cwd
+        const chain = [];
+        let d = startDir;
+        while (d.startsWith(base) && d !== base) {
+            if (!loaded.has(d))
+                chain.unshift(d);
+            if (d === root)
+                break;
+            const parent = dirname(d);
+            if (parent === d)
+                break;
+            d = parent;
+        }
+        for (const cd of chain) {
+            loaded.add(cd); // mark checked even if no doc here, so we don't re-scan it
+            for (const name of FILENAMES) {
+                const fp = join(cd, name);
+                if (!existsSync(fp))
+                    continue;
+                try {
+                    let txt = readFileSync(fp, "utf8").trim();
+                    if (!txt)
+                        break;
+                    if (Buffer.byteLength(txt, "utf8") > MAX)
+                        txt = txt.slice(0, MAX) + "\n…[truncated]";
+                    parts.push(`<!-- ${name} @ ${cd} — local conventions for this directory -->\n${txt}`);
+                }
+                catch {
+                    /* ignore unreadable */
+                }
+                break; // first filename match per dir
+            }
+        }
+    }
+    return parts.length ? "\n\n" + parts.join("\n\n") : "";
+}

package/dist/cron/runner.js

@@ -10,11 +10,14 @@ import { isDue } from "./schedule.js";
 export function dueJobs(jobs, nowMs) {
     return jobs.filter((j) => j.enabled && isDue(j, nowMs));
 }
-/** How to invoke hara again — handles both `node dist/index.js` (argv[1] is a script) and the compiled
- *  single-binary (argv[1] is a user arg, so re-invoke the binary directly). Used by the tick + by install. */
+/** How to invoke hara again. Under node, argv[1] is the entry to hand back to node — either `dist/index.js`
+ *  OR the installed `hara` bin symlink (node runs both); as a compiled single-binary, execPath itself IS hara
+ *  (argv[1] is a user arg), so re-invoke the binary directly. Used by the cron tick + the chat gateway.
+ *  Discriminator is whether execPath is node — NOT argv[1]'s extension (the bin symlink has no `.js`). */
 export function selfArgv() {
-    const a1 = process.argv[1];
-    return a1 && /\.[cm]?js$|\.ts$/.test(a1) ? [process.execPath, a1] : [process.execPath];
+    const exec = process.execPath;
+    const underNode = /(^|[\\/])node(\.exe)?$/i.test(exec);
+    return underNode && process.argv[1] ? [exec, process.argv[1]] : [exec];
 }
 const lockPath = () => join(cronDir(), ".tick.lock");
 // Generous: a live-PID owner is respected this long (so a genuinely long job isn't double-fired); past it

package/dist/exec/jobs.js

@@ -0,0 +1,82 @@
+// Background shell jobs — run long-lived commands (dev servers, `tsc --watch`, long builds) WITHOUT blocking
+// the agent, then tail/kill them. Pipe-based (no PTY yet; a true interactive PTY can come later behind an
+// optional dep). Same sandbox write-confinement as runShell (shared `shellCommand`). Jobs are the agent's
+// own child processes and are terminated when hara exits.
+import { spawn } from "node:child_process";
+import { shellCommand } from "../sandbox.js";
+const MAX_BUF = 64 * 1024; // retain only the tail of each job's combined output
+const jobs = new Map();
+let seq = 0;
+let hooked = false;
+function ensureExitCleanup() {
+    if (hooked)
+        return;
+    hooked = true;
+    process.on("exit", killAllJobs); // sync; runs on normal quit so background jobs don't orphan
+}
+/** Start a background shell job; returns its id immediately. Output is captured to a capped tail buffer. */
+export function startJob(command, cwd, mode) {
+    ensureExitCleanup();
+    const { cmd, args } = shellCommand(command, cwd, mode);
+    const child = spawn(cmd, args, { cwd });
+    const job = { id: "j" + ++seq, command, child, status: "running", code: null, startedAt: Date.now(), buf: "" };
+    const onData = (d) => {
+        job.buf = (job.buf + d.toString()).slice(-MAX_BUF);
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("close", (code) => {
+        if (job.status === "running") {
+            job.status = "exited";
+            job.code = code;
+        }
+    });
+    child.on("error", (e) => {
+        if (job.status === "running") {
+            job.status = "exited";
+            job.code = -1;
+            job.buf = (job.buf + `\n[spawn error] ${e.message}`).slice(-MAX_BUF);
+        }
+    });
+    jobs.set(job.id, job);
+    return job.id;
+}
+export function listJobs() {
+    const now = Date.now();
+    return [...jobs.values()].map((j) => ({ id: j.id, command: j.command, status: j.status, code: j.code, ageMs: now - j.startedAt }));
+}
+/** Last `lines` lines of a job's output buffer, or null if there is no such job. */
+export function tailJob(id, lines = 40) {
+    const j = jobs.get(id);
+    if (!j)
+        return null;
+    return j.buf.split("\n").slice(-lines).join("\n");
+}
+/** Terminate a running job (SIGTERM). Returns true only if it was running. */
+export function killJob(id) {
+    const j = jobs.get(id);
+    if (!j || j.status !== "running")
+        return false;
+    try {
+        j.child.kill("SIGTERM");
+    }
+    catch {
+        /* already gone */
+    }
+    j.status = "killed";
+    return true;
+}
+/** Terminate every running job — registered on process exit so dev servers don't outlive hara. */
+export function killAllJobs() {
+    for (const j of jobs.values()) {
+        if (j.status === "running") {
+            try {
+                j.child.kill("SIGTERM");
+            }
+            catch {
+                /* ignore */
+            }
+            j.status = "killed";
+        }
+    }
+}

package/dist/gateway/dingtalk.js

@@ -0,0 +1,209 @@
+// DingTalk (钉钉) adapter for `hara gateway` — connects to DingTalk's Stream Mode over Node's native global
+// WebSocket (zero new dep on Node ≥ 22) so the LOCAL daemon dials OUT (no public webhook endpoint needed, like
+// Feishu's long-connection). Creds from HARA_DINGTALK_CLIENT_ID / HARA_DINGTALK_CLIENT_SECRET (the app's
+// AppKey/AppSecret on open.dingtalk.com). Replies go to the per-message `sessionWebhook` the inbound payload
+// carries. Same ChatAdapter shape as Telegram/Discord/Feishu, so all the cross-platform gateway plumbing
+// (system context, stuck-guard, allowlist) works unchanged. v1 limitations: file send is not supported (DingTalk
+// bot replies via sessionWebhook only do text/markdown cards) and inbound images are noted but not downloaded.
+import { chunkText } from "./telegram.js";
+// Open a Stream connection here → response gives the WS endpoint + a ticket; then we dial endpoint?ticket=…
+const OPEN_CONNECTION = "https://api.dingtalk.com/v1.0/gateway/connections/open";
+const BOT_TOPIC = "/v1.0/im/bot/messages/get"; // the CALLBACK topic that carries a bot chat message
+const WSImpl = globalThis.WebSocket;
+const sleep = (ms, signal) => new Promise((r) => {
+    if (signal?.aborted)
+        return r();
+    const t = setTimeout(r, ms);
+    signal?.addEventListener?.("abort", () => { clearTimeout(t); r(); }, { once: true });
+});
+/** Parse a DingTalk bot message payload (the JSON.parse'd `data` field of a CALLBACK frame) → InboundMsg plus the
+ *  per-message sessionWebhook used to reply (pure). Accepts text (and picture, marked "[图片]"); null otherwise.
+ *  conversationId routes group/DM; senderStaffId is preferred for the allowlist (the org staff id), else senderId. */
+export function parseDingtalkMessage(msg) {
+    if (!msg)
+        return null;
+    const chatId = String(msg.conversationId || msg.senderId || "");
+    if (!chatId)
+        return null;
+    const userId = String(msg.senderStaffId || msg.senderId || "");
+    const userName = String(msg.senderNick || userId);
+    const sessionWebhook = typeof msg.sessionWebhook === "string" ? msg.sessionWebhook : null;
+    const type = String(msg.msgtype || "");
+    let text = "";
+    if (type === "text")
+        text = String(msg.text?.content ?? "").trim();
+    else if (type === "picture")
+        text = "[图片]"; // v1: inbound image not downloaded (downloadCode in content)
+    else if (type === "richText")
+        text = flattenRichText(msg.content?.richText).trim();
+    if (!text)
+        return null; // unsupported type (audio/file/etc.) or empty
+    return { msg: { chatId, userId, userName, text }, sessionWebhook };
+}
+/** Flatten a DingTalk richText message (an array of {text}/{type} runs) into plain text (pure). */
+function flattenRichText(runs) {
+    if (!Array.isArray(runs))
+        return "";
+    return runs.map((r) => (r && typeof r.text === "string" ? r.text : "")).join(" ").trim();
+}
+export function dingtalkAdapter(clientId, clientSecret) {
+    // chatId → the latest sessionWebhook seen for it (expires ~ a few hours; refreshed on each inbound message).
+    const webhooks = new Map();
+    return {
+        name: "dingtalk",
+        async send(chatId, text) {
+            const url = webhooks.get(String(chatId));
+            if (!url)
+                return; // no inbound seen yet → no webhook to reply through (replies must follow a message)
+            for (const part of chunkText(text || "(empty)")) {
+                await fetch(url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ msgtype: "text", text: { content: part } }),
+                }).catch(() => { });
+            }
+        },
+        // sendFile intentionally omitted: DingTalk bot replies (sessionWebhook) can't upload arbitrary files in v1.
+        // The gateway surfaces "(this platform can't send files yet)" when the agent queues a file.
+        async start(onMessage, signal) {
+            if (!WSImpl) {
+                console.error("hara gateway: DingTalk needs Node ≥ 22 (global WebSocket). Upgrade Node.");
+                return;
+            }
+            while (!signal.aborted) {
+                await connectOnce(clientId, clientSecret, webhooks, onMessage, signal);
+                if (!signal.aborted)
+                    await sleep(3000, signal); // reconnect backoff
+            }
+        },
+    };
+}
+/** One Stream connection: register → open the WS to the returned endpoint?ticket=…, then ACK every frame and
+ *  dispatch bot messages. Resolves on close/abort; the caller reconnects (fresh registration each time). */
+async function connectOnce(clientId, clientSecret, webhooks, onMessage, signal) {
+    let endpoint;
+    let ticket;
+    try {
+        const res = await fetch(OPEN_CONNECTION, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                clientId,
+                clientSecret,
+                subscriptions: [
+                    { type: "EVENT", topic: "*" },
+                    { type: "CALLBACK", topic: BOT_TOPIC },
+                ],
+                ua: "hara-cli/stream",
+                localIp: "127.0.0.1",
+            }),
+            signal,
+        });
+        if (!res.ok) {
+            console.error(`hara gateway: DingTalk connection register failed (HTTP ${res.status}) — check HARA_DINGTALK_CLIENT_ID/SECRET and that Stream mode is enabled.`);
+            return;
+        }
+        const j = (await res.json());
+        if (!j.endpoint || !j.ticket) {
+            console.error("hara gateway: DingTalk register returned no endpoint/ticket.");
+            return;
+        }
+        endpoint = j.endpoint;
+        ticket = j.ticket;
+    }
+    catch {
+        if (!signal.aborted)
+            console.error("hara gateway: DingTalk connection register error (network).");
+        return;
+    }
+    return new Promise((resolve) => {
+        const ws = new WSImpl(`${endpoint}?ticket=${encodeURIComponent(ticket)}`);
+        let hb = null;
+        const cleanup = () => {
+            if (hb)
+                clearInterval(hb);
+            signal.removeEventListener("abort", stop);
+        };
+        const stop = () => {
+            cleanup();
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closing */
+            }
+            resolve();
+        };
+        signal.addEventListener("abort", stop, { once: true });
+        ws.addEventListener("open", () => {
+            // Application-level keepalive: a SYSTEM/ping frame keeps the connection registered between messages.
+            hb = setInterval(() => {
+                try {
+                    ws.send(JSON.stringify({ type: "SYSTEM", headers: { topic: "ping" }, data: "{}" }));
+                }
+                catch {
+                    /* socket gone — close handler resolves */
+                }
+            }, 30000);
+        });
+        ws.addEventListener("close", () => {
+            cleanup();
+            resolve();
+        });
+        ws.addEventListener("error", () => { });
+        ws.addEventListener("message", async (ev) => {
+            let frame;
+            try {
+                frame = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            const headers = frame?.headers ?? {};
+            const topic = String(headers.topic ?? "");
+            // ACK every frame with its messageId per the Stream ack protocol; reply data is a JSON-string `response`.
+            const ack = (response) => {
+                if (!headers.messageId)
+                    return;
+                try {
+                    ws.send(JSON.stringify({
+                        code: 200,
+                        headers: { messageId: headers.messageId, contentType: "application/json" },
+                        message: "OK",
+                        data: JSON.stringify({ response: response ?? {} }),
+                    }));
+                }
+                catch {
+                    /* socket gone */
+                }
+            };
+            if (frame?.type === "SYSTEM") {
+                if (topic === "disconnect") {
+                    stop(); // server asked us to drop → close and let the caller re-register
+                    return;
+                }
+                ack({}); // ping / connected / other system frames → just acknowledge
+                return;
+            }
+            if (topic === BOT_TOPIC) {
+                let payload;
+                try {
+                    payload = JSON.parse(String(frame.data ?? "{}")); // CALLBACK data is a JSON string
+                }
+                catch {
+                    ack({});
+                    return;
+                }
+                ack({}); // ack first (DingTalk expects a prompt ack; the actual reply goes via sessionWebhook)
+                const parsed = parseDingtalkMessage(payload);
+                if (parsed) {
+                    if (parsed.sessionWebhook)
+                        webhooks.set(String(parsed.msg.chatId), parsed.sessionWebhook);
+                    await onMessage(parsed.msg).catch(() => { });
+                }
+                return;
+            }
+            ack({}); // any other EVENT frame → acknowledge so DingTalk doesn't retry
+        });
+    });
+}