zcode-acp-server 0.50.0 → 0.51.1

package/dist/push/config.js

@@ -0,0 +1,82 @@
+/**
+ * WeCom push configuration + the single shared ACTIVE predicate
+ * (push-backend-requirements §6/§8/§10).
+ *
+ * Precedence mirrors `mergeCommon` (file > env): the `push` section of
+ * ~/.config/zcode-acp/config.json wins over the ZCODE_ACP_PUSH_* env vars.
+ * ACTIVE = enabled AND complete credentials (corpId/agentId/secret) — a push
+ * that cannot summon anyone must not hold an offline interaction either, so
+ * `pushIfOffline` and the interaction hold read the SAME predicate. An
+ * OPTIONAL relay (static-IP proxy for the WeCom API) rides along when both
+ * url+token are present; a half-configured relay warns once and pushes direct.
+ *
+ * Resolved lazily ONCE per process: an enabled-but-incomplete setup logs one
+ * warning at first resolution and every hook then no-ops (silent degradation).
+ */
+import { loadUserConfig } from "../config/user-config.js";
+import { warn } from "../utils.js";
+/** Same truthy set as `remoteEnabledLive` (remote/config.ts). */
+const TRUTHY = ["1", "true", "yes", "on"];
+export function resolvePushConfig(env) {
+    const file = loadUserConfig(env).push ?? {};
+    const enabled = file.enabled !== undefined
+        ? file.enabled
+        : TRUTHY.includes((env.ZCODE_ACP_PUSH_ENABLED ?? "").trim().toLowerCase());
+    if (!enabled)
+        return null;
+    const corpId = file.corpId ?? (env.ZCODE_ACP_PUSH_CORP_ID ?? "").trim();
+    const secret = file.secret ?? (env.ZCODE_ACP_PUSH_SECRET ?? "").trim();
+    const toUser = file.toUser ?? ((env.ZCODE_ACP_PUSH_TO_USER ?? "").trim() || "@all");
+    const agentId = file.agentId ?? Number.parseInt((env.ZCODE_ACP_PUSH_AGENT_ID ?? "").trim(), 10);
+    if (!corpId || !Number.isInteger(agentId) || agentId < 1 || !secret) {
+        warn("push: enabled but corpId/agentId/secret incomplete " +
+            "(config file or ZCODE_ACP_PUSH_* env) — push stays inactive");
+        return null;
+    }
+    const relayUrl = trimTrailingSlashes(file.relay?.url ?? env.ZCODE_ACP_PUSH_RELAY_URL ?? "");
+    const relayToken = file.relay?.token ?? (env.ZCODE_ACP_PUSH_RELAY_TOKEN ?? "").trim();
+    const notify = {
+        turn: file.notify?.turn !== false,
+        goal: file.notify?.goal !== false,
+        run: file.notify?.run !== false,
+        task: file.notify?.task !== false,
+    };
+    if (relayUrl && relayToken) {
+        return {
+            corpId,
+            agentId,
+            secret,
+            toUser,
+            contentDetail: file.contentDetail ?? "full",
+            relay: { url: relayUrl, token: relayToken },
+            notify,
+        };
+    }
+    if (relayUrl || relayToken) {
+        warn("push: relay needs BOTH url and token (config file push.relay or " +
+            "ZCODE_ACP_PUSH_RELAY_* env) — pushing direct from this host");
+    }
+    return { corpId, agentId, secret, toUser, contentDetail: file.contentDetail ?? "full", notify };
+}
+function trimTrailingSlashes(s) {
+    return s.trim().replace(/\/+$/, "");
+}
+/** undefined = not yet resolved; null = resolved inactive. */
+let cached;
+/** The shared ACTIVE predicate (resolve-once per process). */
+export function pushActive() {
+    if (cached === undefined)
+        cached = resolvePushConfig(process.env);
+    return cached !== null;
+}
+/** The resolved config when ACTIVE, null otherwise (resolves on first use). */
+export function pushConfig() {
+    if (cached === undefined)
+        cached = resolvePushConfig(process.env);
+    return cached ?? null;
+}
+/** Test hook: forget the process-wide resolution. */
+export function resetPushConfigForTests() {
+    cached = undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/push/config.js.map

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

package/dist/push/push.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Offline push dispatch (push-backend-requirements §5): one helper gates every
+ * event hook. Push fires only when the bridge has ZERO connected clients (an
+ * online client renders the event live) and push is ACTIVE — the single
+ * predicate from push/config.ts. Fire-and-forget: send failures warn and never
+ * reach the event path.
+ */
+import type { ZcodeAcpServer } from "../server.js";
+import { type WeComSender } from "./wecom.js";
+export type PushKind = "permission" | "question" | "run" | "task" | "test" | "turn" | "goal";
+/** Settled kinds routed through {@link pushSettled} (§5.2 — per-kind switches). */
+export type PushSettledKind = Extract<PushKind, "turn" | "goal" | "run" | "task">;
+/**
+ * "<project> / <session-title>" source label for settled pushes. It rides the
+ * leading bracket (never the body — `contentDetail: "minimal"` strips bodies),
+ * replacing the kind prefix whose information the title tail already carries.
+ * TOTAL (never throws): the push path is fire-and-forget by contract, and the
+ * server handle may be a partial object in tests.
+ */
+export declare function pushSourceLabel(server: ZcodeAcpServer, acpSid?: string): string;
+export interface PushEventData {
+    kind: PushKind;
+    title: string;
+    body?: string;
+    /**
+     * Source label (`<project> / <session>`, see {@link pushSourceLabel}). When
+     * present it REPLACES the kind in the leading bracket — `[kind] title`
+     * would duplicate what the title tail already says (e.g. "turn completed"),
+     * and the bracket is the one slot minimal mode never strips.
+     */
+    label?: string;
+}
+/** Test hook: forget the process-wide sender. */
+export declare function resetPushSenderForTests(): void;
+/** Test hook: inject a fake sender (null = inactive). */
+export declare function setPushSenderForTests(s: WeComSender | null): void;
+/**
+ * Render the contracted WeCom text: `[<kind or label>] <title>` + optional
+ * body line. A `label` replaces the kind in the leading bracket (see
+ * {@link PushEventData.label}). Under `contentDetail: "minimal"` the body
+ * carries no business strings (§4 — content transits Tencent) — the bracket
+ * prefix + title identify the event.
+ */
+export declare function renderPushContent(cfg: {
+    contentDetail: "full" | "minimal";
+}, data: PushEventData): string;
+/** §5: the single gated dispatch helper — offline + ACTIVE or nothing. */
+export declare function pushIfOffline(server: ZcodeAcpServer, data: PushEventData): void;
+/**
+ * §5.2 settled-event dispatch (turn end / goal loop stop / workflow run /
+ * background task): NO client-presence gate — an online client renders the
+ * event live but cannot wake the user's phone, and the settled event itself
+ * IS the "come back" signal. Each kind is individually switchable via
+ * `push.notify.<kind>` (default on); the shared ACTIVE predicate still applies.
+ */
+export declare function pushSettled(server: ZcodeAcpServer, data: PushEventData & {
+    kind: PushSettledKind;
+}): void;
+/**
+ * §5.1: derive the permission/question payload at the zero-clients branch of
+ * `requestAny` (broadcast.ts) — the single hook covering permission requests,
+ * AskUserQuestion, and elicitation.
+ */
+export declare function pushInteractionIfOffline(server: ZcodeAcpServer, method: string, params?: unknown): void;
+/**
+ * §7 test push — sends REGARDLESS of client presence (it verifies the channel,
+ * not an offline event). Structured result for the REST route.
+ */
+export declare function sendTestPush(title: string): Promise<{
+    ok: true;
+    sent: number;
+} | {
+    ok: false;
+    error: "push_disabled" | "send_failed";
+    message?: string;
+}>;
+//# sourceMappingURL=push.d.ts.map

package/dist/push/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../src/push/push.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7F,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAI/E;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAaD,iDAAiD;AACjD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE;IAAE,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAC1C,IAAI,EAAE,aAAa,GAClB,MAAM,CAIR;AAiBD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAO/E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,aAAa,GAAG;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GAC9C,IAAI,CAON;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,GACf,IAAI,CAiBN;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,GACZ,OAAO,CACN;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAC1E,CAeA"}

package/dist/push/push.js

@@ -0,0 +1,139 @@
+/**
+ * Offline push dispatch (push-backend-requirements §5): one helper gates every
+ * event hook. Push fires only when the bridge has ZERO connected clients (an
+ * online client renders the event live) and push is ACTIVE — the single
+ * predicate from push/config.ts. Fire-and-forget: send failures warn and never
+ * reach the event path.
+ */
+import path from "node:path";
+import { appendDiary } from "../crash-guards.js";
+import { log, warn } from "../utils.js";
+import { pushConfig } from "./config.js";
+import { createWeComSender } from "./wecom.js";
+/**
+ * "<project> / <session-title>" source label for settled pushes. It rides the
+ * leading bracket (never the body — `contentDetail: "minimal"` strips bodies),
+ * replacing the kind prefix whose information the title tail already carries.
+ * TOTAL (never throws): the push path is fire-and-forget by contract, and the
+ * server handle may be a partial object in tests.
+ */
+export function pushSourceLabel(server, acpSid) {
+    const project = path.basename(server.projectCwd?.() ?? process.cwd());
+    const title = acpSid !== undefined ? server.sessionTitles?.get(acpSid) : undefined;
+    return title ? `${project} / ${title}` : project;
+}
+/** undefined = not yet built; null = push inactive. */
+let sender;
+function pushSender() {
+    if (sender === undefined) {
+        const cfg = pushConfig();
+        sender = cfg ? createWeComSender(cfg) : null;
+    }
+    return sender;
+}
+/** Test hook: forget the process-wide sender. */
+export function resetPushSenderForTests() {
+    sender = undefined;
+}
+/** Test hook: inject a fake sender (null = inactive). */
+export function setPushSenderForTests(s) {
+    sender = s;
+}
+/**
+ * Render the contracted WeCom text: `[<kind or label>] <title>` + optional
+ * body line. A `label` replaces the kind in the leading bracket (see
+ * {@link PushEventData.label}). Under `contentDetail: "minimal"` the body
+ * carries no business strings (§4 — content transits Tencent) — the bracket
+ * prefix + title identify the event.
+ */
+export function renderPushContent(cfg, data) {
+    const body = cfg.contentDetail === "minimal" ? undefined : data.body;
+    const prefix = `[${data.label ?? data.kind}]`;
+    return body ? `${prefix} ${data.title}\n${body}` : `${prefix} ${data.title}`;
+}
+/** Fire-and-forget send tail shared by both dispatch helpers. */
+function dispatchPush(cfg, s, data) {
+    const content = renderPushContent(cfg, data);
+    s.sendText(content).then(() => {
+        log(`push: ${data.kind} "${data.title}" sent via WeCom`);
+        // The success trail must outlive stderr (a closed window eats log()):
+        // "did the push leave this bridge?" is the first question a
+        // missed-notification report asks (observed 2026-09-29).
+        appendDiary(`push: ${data.kind} "${data.title}" delivered via WeCom`);
+    }, (e) => warn(`push: WeCom send failed: ${e instanceof Error ? e.message : String(e)}`));
+}
+/** §5: the single gated dispatch helper — offline + ACTIVE or nothing. */
+export function pushIfOffline(server, data) {
+    if (server.clients.size > 0)
+        return;
+    const cfg = pushConfig();
+    if (!cfg)
+        return;
+    const s = pushSender();
+    if (!s)
+        return;
+    dispatchPush(cfg, s, data);
+}
+/**
+ * §5.2 settled-event dispatch (turn end / goal loop stop / workflow run /
+ * background task): NO client-presence gate — an online client renders the
+ * event live but cannot wake the user's phone, and the settled event itself
+ * IS the "come back" signal. Each kind is individually switchable via
+ * `push.notify.<kind>` (default on); the shared ACTIVE predicate still applies.
+ */
+export function pushSettled(server, data) {
+    void server; // presence deliberately NOT checked (see above)
+    const cfg = pushConfig();
+    if (!cfg || !cfg.notify[data.kind])
+        return;
+    const s = pushSender();
+    if (!s)
+        return;
+    dispatchPush(cfg, s, data);
+}
+/**
+ * §5.1: derive the permission/question payload at the zero-clients branch of
+ * `requestAny` (broadcast.ts) — the single hook covering permission requests,
+ * AskUserQuestion, and elicitation.
+ */
+export function pushInteractionIfOffline(server, method, params) {
+    const p = (params ?? {});
+    if (method === "session/request_permission") {
+        const detail = typeof p.toolCall?.title === "string" ? p.toolCall.title.trim() : "";
+        pushIfOffline(server, {
+            kind: "permission",
+            title: "Approval requested",
+            body: detail || undefined,
+        });
+        return;
+    }
+    const question = typeof p.message === "string" ? p.message.trim() : "";
+    pushIfOffline(server, {
+        kind: "question",
+        title: "Agent question",
+        body: question || undefined,
+    });
+}
+/**
+ * §7 test push — sends REGARDLESS of client presence (it verifies the channel,
+ * not an offline event). Structured result for the REST route.
+ */
+export async function sendTestPush(title) {
+    const cfg = pushConfig();
+    const s = pushSender();
+    if (!cfg || !s)
+        return { ok: false, error: "push_disabled" };
+    try {
+        await s.sendText(renderPushContent(cfg, { kind: "test", title }));
+        appendDiary(`push: test "${title}" delivered via WeCom`);
+        return { ok: true, sent: 1 };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: "send_failed",
+            message: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+//# sourceMappingURL=push.js.map

package/dist/push/push.js.map

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

package/dist/push/wecom.d.ts

@@ -0,0 +1,45 @@
+/**
+ * WeCom (企业微信) self-built-app push client — the whole outbound surface is
+ * two HTTP endpoints (push-backend-requirements §9):
+ *
+ *   GET  /cgi-bin/gettoken?corpid=&corpsecret=  → {access_token, expires_in}
+ *   POST /cgi-bin/message/send?access_token=    → {errcode: 0}
+ *
+ * Zero dependencies: platform `fetch`, injectable for tests. The access token
+ * is cached with a 5-minute expiry margin; errcode 40014/42001 (invalid /
+ * expired token) triggers ONE refresh + ONE send retry — a second failure is
+ * final for that push. Callers are fire-and-forget and only warn.
+ *
+ * With `relay` configured both calls go through that base URL instead (with an
+ * `x-relay-token` header) — a reverse proxy on a static-IP host, so WeCom's
+ * 企业可信IP check (errcode 60020) only ever sees that host's egress IP.
+ */
+export interface WeComSender {
+    sendText(content: string): Promise<void>;
+}
+/** Minimal fetch surface — the platform fetch satisfies it; tests fake it. */
+export interface WeComFetch {
+    (url: string, init?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    }>;
+}
+export declare function createWeComSender(cfg: {
+    corpId: string;
+    agentId: number;
+    secret: string;
+    toUser: string;
+    /** Route both API calls through a static-IP relay (see file header). */
+    relay?: {
+        url: string;
+        token: string;
+    };
+}, fetchImpl?: WeComFetch): WeComSender;
+/** Truncate to a byte cap without splitting a UTF-8 sequence. */
+export declare function truncateUtf8(s: string, maxBytes: number): string;
+//# sourceMappingURL=wecom.d.ts.map

package/dist/push/wecom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wecom.d.ts","sourceRoot":"","sources":["../../src/push/wecom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,CACE,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC;QACT,EAAE,EAAE,OAAO,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;KAC1B,CAAC,CAAC;CACJ;AAUD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE;IACH,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC,EACD,SAAS,GAAE,UAAgC,GAC1C,WAAW,CA2Eb;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKhE"}

package/dist/push/wecom.js

@@ -0,0 +1,91 @@
+/**
+ * WeCom (企业微信) self-built-app push client — the whole outbound surface is
+ * two HTTP endpoints (push-backend-requirements §9):
+ *
+ *   GET  /cgi-bin/gettoken?corpid=&corpsecret=  → {access_token, expires_in}
+ *   POST /cgi-bin/message/send?access_token=    → {errcode: 0}
+ *
+ * Zero dependencies: platform `fetch`, injectable for tests. The access token
+ * is cached with a 5-minute expiry margin; errcode 40014/42001 (invalid /
+ * expired token) triggers ONE refresh + ONE send retry — a second failure is
+ * final for that push. Callers are fire-and-forget and only warn.
+ *
+ * With `relay` configured both calls go through that base URL instead (with an
+ * `x-relay-token` header) — a reverse proxy on a static-IP host, so WeCom's
+ * 企业可信IP check (errcode 60020) only ever sees that host's egress IP.
+ */
+const API_BASE = "https://qyapi.weixin.qq.com";
+/** Refresh before expiry so a send never rides a token about to die. */
+const TOKEN_MARGIN_MS = 5 * 60_000;
+/** errcode 40014 = invalid token, 42001 = expired — both mean "refresh once". */
+const INVALID_TOKEN_CODES = new Set([40014, 42001]);
+/** WeCom text content cap — truncate from the end of the body. */
+const MAX_CONTENT_BYTES = 2048;
+export function createWeComSender(cfg, fetchImpl = fetch) {
+    const base = cfg.relay?.url ?? API_BASE;
+    const relayHeaders = cfg.relay ? { "x-relay-token": cfg.relay.token } : undefined;
+    let token = null;
+    async function readJson(resp) {
+        try {
+            return (await resp.json());
+        }
+        catch {
+            return { errcode: resp.status, errmsg: `HTTP ${resp.status} (non-JSON body)` };
+        }
+    }
+    async function fetchToken() {
+        const url = `${base}/cgi-bin/gettoken?corpid=${encodeURIComponent(cfg.corpId)}` +
+            `&corpsecret=${encodeURIComponent(cfg.secret)}`;
+        const body = await readJson(await fetchImpl(url, { headers: relayHeaders }));
+        if (body.errcode !== undefined && body.errcode !== 0) {
+            throw new Error(`wecom gettoken failed: ${body.errcode} ${body.errmsg ?? ""}`.trim());
+        }
+        if (!body.access_token)
+            throw new Error("wecom gettoken returned no access_token");
+        const ttl = typeof body.expires_in === "number" ? body.expires_in * 1000 : 7200_000;
+        token = {
+            value: body.access_token,
+            expiresAt: Date.now() + Math.max(ttl - TOKEN_MARGIN_MS, 60_000),
+        };
+        return body.access_token;
+    }
+    async function currentToken(force = false) {
+        if (!force && token && Date.now() < token.expiresAt)
+            return token.value;
+        return fetchToken();
+    }
+    async function postSend(t, content) {
+        const resp = await fetchImpl(`${base}/cgi-bin/message/send?access_token=${encodeURIComponent(t)}`, {
+            method: "POST",
+            headers: relayHeaders,
+            body: JSON.stringify({
+                touser: cfg.toUser,
+                msgtype: "text",
+                agentid: cfg.agentId,
+                text: { content },
+            }),
+        });
+        return readJson(resp);
+    }
+    async function sendText(content) {
+        const bounded = truncateUtf8(content, MAX_CONTENT_BYTES);
+        let resp = await postSend(await currentToken(), bounded);
+        if (resp.errcode !== undefined && INVALID_TOKEN_CODES.has(resp.errcode)) {
+            resp = await postSend(await currentToken(true), bounded);
+        }
+        if (resp.errcode !== undefined && resp.errcode !== 0) {
+            throw new Error(`wecom message/send failed: ${resp.errcode} ${resp.errmsg ?? ""}`.trim());
+        }
+    }
+    return { sendText };
+}
+/** Truncate to a byte cap without splitting a UTF-8 sequence. */
+export function truncateUtf8(s, maxBytes) {
+    if (Buffer.byteLength(s, "utf8") <= maxBytes)
+        return s;
+    let chars = Math.floor(maxBytes / 4); // every char is at most 4 bytes
+    while (chars > 0 && Buffer.byteLength(s.slice(0, chars), "utf8") > maxBytes)
+        chars--;
+    return `${s.slice(0, chars)}…`;
+}
+//# sourceMappingURL=wecom.js.map

package/dist/push/wecom.js.map

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

package/dist/remote/broadcast.d.ts

@@ -30,6 +30,13 @@ export interface ClientLike {
  * BEFORE `connect()` so the stdio connection is captured too.
  */
 export declare function trackConnections(app: acp.AgentApp, clients: ClientRegistry): void;
+/**
+ * A request fired with zero connected clients. The offline-interaction hold
+ * (server-requests.ts §6) classifies on this type: with push ACTIVE the race
+ * stays pending instead of rejecting into the auto-decline path.
+ */
+export declare class NoClientsError extends Error {
+}
 /**
  * Registry of connected ACP clients (stdio editor + remote WebSocket clients).
  * Membership is managed by the entry point via the SDK's per-connection
@@ -43,6 +50,14 @@ export declare class ClientRegistry {
     add(cx: ClientLike): void;
     remove(cx: ClientLike): void;
     get size(): number;
+    /**
+     * Fired when a request finds ZERO connected clients (just before the
+     * NoClientsError throw): the offline-push hook (§5.1). Wired by the server
+     * at construction — remote-layer code must not import the push module
+     * directly (keeps the layer cycle-free). Fire-and-forget: observer throws
+     * are swallowed, the throw path always proceeds.
+     */
+    noClientsObserver?: (method: string, params?: unknown) => void;
     /**
      * Record a connection's `initialize` clientInfo name, keyed by the SDK's
      * per-connection root (same identity `notifyOthers` filters on) so payloads

package/dist/remote/broadcast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../src/remote/broadcast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAIrD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAKjF;AAQD;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,KAAK,CAAiC;IAC9C,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,GAAG,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI;IAIzB,MAAM,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI;IAI5B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKlD,uEAAuE;IACvE,MAAM,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAOrC;;;;;OAKG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC7D,OAAO,CAAC,IAAI,CAAC;IAUhB,yEAAyE;IACzE,SAAS,IAAI,GAAG,CAAC,YAAY;IAK7B;;;;;;;;;OASG;IACG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9F,QAAQ,IAAI,UAAU,EAAE;CAGzB"}
+{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../src/remote/broadcast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAIrD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAKjF;AAQD;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,KAAK,CAAiC;IAC9C,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,GAAG,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI;IAIzB,MAAM,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI;IAI5B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAE/D;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKlD,uEAAuE;IACvE,MAAM,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAOrC;;;;;OAKG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC7D,OAAO,CAAC,IAAI,CAAC;IAUhB,yEAAyE;IACzE,SAAS,IAAI,GAAG,CAAC,YAAY;IAK7B;;;;;;;;;OASG;IACG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9F,QAAQ,IAAI,UAAU,EAAE;CAGzB"}

package/dist/remote/broadcast.js

@@ -30,6 +30,13 @@ export function trackConnections(app, clients) {
         void conn.closed.then(() => clients.remove(conn.client));
     });
 }
+/**
+ * A request fired with zero connected clients. The offline-interaction hold
+ * (server-requests.ts §6) classifies on this type: with push ACTIVE the race
+ * stays pending instead of rejecting into the auto-decline path.
+ */
+export class NoClientsError extends Error {
+}
 /**
  * Registry of connected ACP clients (stdio editor + remote WebSocket clients).
  * Membership is managed by the entry point via the SDK's per-connection
@@ -49,6 +56,14 @@ export class ClientRegistry {
     get size() {
         return this.clients.size;
     }
+    /**
+     * Fired when a request finds ZERO connected clients (just before the
+     * NoClientsError throw): the offline-push hook (§5.1). Wired by the server
+     * at construction — remote-layer code must not import the push module
+     * directly (keeps the layer cycle-free). Fire-and-forget: observer throws
+     * are swallowed, the throw path always proceeds.
+     */
+    noClientsObserver;
     /**
      * Record a connection's `initialize` clientInfo name, keyed by the SDK's
      * per-connection root (same identity `notifyOthers` filters on) so payloads
@@ -173,7 +188,13 @@ async function notifyAll(registry, method, params) {
 async function requestAny(registry, method, params, options) {
     const clients = registry.snapshot();
     if (clients.length === 0) {
-        throw new Error(`broadcast: no connected clients (${method})`);
+        try {
+            registry.noClientsObserver?.(method, params);
+        }
+        catch {
+            // fire-and-forget hook; never block the throw
+        }
+        throw new NoClientsError(`broadcast: no connected clients (${method})`);
     }
     const controllers = clients.map(() => new AbortController());
     // Link a caller-provided signal: aborting it cancels EVERY inner request.

package/dist/remote/broadcast.js.map

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

package/dist/remote/config.d.ts

@@ -28,7 +28,8 @@
  *                                   tried in order before going headless)
  *     ZCODE_ACP_HUB_TERMINAL_COMMAND=<sh> shell command template ({script})
  *     ZCODE_ACP_WEB_DIR=<abs path>  web-client dist for same-origin hosting
- *                                   (file `remote.webDir` wins; empty = off)
+ *                                   (file `remote.webDir` wins; empty = off;
+ *                                   a leading ~ is expanded to the home dir)
  *   3. Built-in defaults.
  *
  * Process-role plumbing stays env-only by design (never file-configurable):

package/dist/remote/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/remote/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAiC5C,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,IAAI,CAmB3F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,IAAI,CAexF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,aAAa,CAyBvF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/remote/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9F,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAiC5C,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,IAAI,CAmB3F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,GAAG,IAAI,CAexF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,aAAa,CAyBvF"}

package/dist/remote/config.js

@@ -28,7 +28,8 @@
  *                                   tried in order before going headless)
  *     ZCODE_ACP_HUB_TERMINAL_COMMAND=<sh> shell command template ({script})
  *     ZCODE_ACP_WEB_DIR=<abs path>  web-client dist for same-origin hosting
- *                                   (file `remote.webDir` wins; empty = off)
+ *                                   (file `remote.webDir` wins; empty = off;
+ *                                   a leading ~ is expanded to the home dir)
  *   3. Built-in defaults.
  *
  * Process-role plumbing stays env-only by design (never file-configurable):
@@ -36,7 +37,7 @@
  *   ZCODE_ACP_REMOTE_PIN_CWD=1     pin session roots to the process cwd
  *   ZCODE_ACP_RESUME_SESSION=<id>  per-request boot-resume target (ADR-0017)
  */
-import { loadUserConfig } from "../config/user-config.js";
+import { expandHomePath, loadUserConfig } from "../config/user-config.js";
 import { warn } from "../utils.js";
 export const DEFAULT_HUB_PORT = 8377;
 export const DEFAULT_BRIDGE_PORT = 8378;
@@ -60,7 +61,7 @@ function mergeCommon(env) {
         hubHost: file.hubHost ?? ((env.ZCODE_ACP_HUB_HOST ?? "").trim() || DEFAULT_HUB_HOST),
         bridgePort: file.bridgePort ??
             parsePort(env.ZCODE_ACP_REMOTE_PORT, DEFAULT_BRIDGE_PORT, "ZCODE_ACP_REMOTE_PORT"),
-        webDir: file.webDir ?? (env.ZCODE_ACP_WEB_DIR ?? "").trim(),
+        webDir: file.webDir ?? expandHomePath((env.ZCODE_ACP_WEB_DIR ?? "").trim()),
     };
 }
 /** Parse remote config; null = disabled (or misconfigured → warned). */