@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/agent-target.d.ts

@@ -0,0 +1,45 @@
+import type { DeviceRecord } from './types.js';
+/** A resolved agent session: the listener's device id and its tmux name. */
+export interface AgentTarget {
+    deviceId: string;
+    name: string;
+    /** `<deviceId>:<name>` — the stable key the app groups the session's chat by. */
+    key: string;
+}
+/**
+ * The target named nothing, named more than one session, or is on a machine
+ * that is offline. The message lists the keys to retry with.
+ */
+export declare class AgentTargetError extends Error {
+    readonly code: 'UNKNOWN_TARGET' | 'AMBIGUOUS_TARGET' | 'TARGET_OFFLINE';
+    constructor(code: 'UNKNOWN_TARGET' | 'AMBIGUOUS_TARGET' | 'TARGET_OFFLINE', message: string);
+}
+/**
+ * Whether an agent may type into this session. Subagents are view-only (no
+ * input). A `hwip sh` session is a real shell: an agent typing into it would
+ * run commands on that machine, on another PC as easily as on its own.
+ */
+export declare const isAgentTarget: (s: {
+    parentName?: string;
+    agentKind?: string;
+}) => boolean;
+/**
+ * Resolve `target` to one live agent session.
+ *
+ * The key `<deviceId>:<tmuxName>` is exact. Anything else is matched against
+ * the tmux name, the user's alias, the agent's own session name and the
+ * listener's label, and must match exactly one session: the same tmux name on
+ * two PCs is the routing bug a guess would reintroduce, so two matches are an
+ * error that lists both keys. The sender's own session (`selfKey`) is left out
+ * of name matching, so the same project on two PCs resolves to the other one;
+ * named alone, it resolves to itself for the caller to refuse.
+ *
+ * A session on an offline machine is refused rather than sent to: the listener
+ * takes commands over its socket only and fetches none it missed, so the
+ * message would be stored and never typed.
+ *
+ * The CLI keeps its own copy (cli/src/agent-target.ts): it depends on this
+ * package, but this package's entry point starts the server when imported.
+ */
+export declare const resolveAgentTarget: (devices: DeviceRecord[], target: string, selfKey?: string) => AgentTarget;
+//# sourceMappingURL=agent-target.d.ts.map

package/dist/agent-target.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgentTarget = exports.isAgentTarget = exports.AgentTargetError = void 0;
+/**
+ * The target named nothing, named more than one session, or is on a machine
+ * that is offline. The message lists the keys to retry with.
+ */
+class AgentTargetError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentTargetError';
+    }
+}
+exports.AgentTargetError = AgentTargetError;
+/**
+ * Whether an agent may type into this session. Subagents are view-only (no
+ * input). A `hwip sh` session is a real shell: an agent typing into it would
+ * run commands on that machine, on another PC as easily as on its own.
+ */
+const isAgentTarget = (s) => !s.parentName && s.agentKind !== 'shell';
+exports.isAgentTarget = isAgentTarget;
+const candidatesOf = (devices) => devices.flatMap((d) => (d.agentSessions ?? [])
+    .filter(exports.isAgentTarget)
+    .map((s) => ({
+    deviceId: d.deviceId,
+    name: s.name,
+    key: `${d.deviceId}:${s.name}`,
+    alias: d.agentSessionAliases?.[s.name],
+    label: s.label,
+    providerSessionName: s.providerSessionName,
+    host: d.nickname ?? d.deviceId,
+    offline: d.isOnline === false,
+})));
+const listCandidates = (list) => list.map((c) => `${c.key} (${c.alias ?? c.providerSessionName ?? c.label ?? c.name} on ${c.host})`).join(', ') || 'none';
+/**
+ * Resolve `target` to one live agent session.
+ *
+ * The key `<deviceId>:<tmuxName>` is exact. Anything else is matched against
+ * the tmux name, the user's alias, the agent's own session name and the
+ * listener's label, and must match exactly one session: the same tmux name on
+ * two PCs is the routing bug a guess would reintroduce, so two matches are an
+ * error that lists both keys. The sender's own session (`selfKey`) is left out
+ * of name matching, so the same project on two PCs resolves to the other one;
+ * named alone, it resolves to itself for the caller to refuse.
+ *
+ * A session on an offline machine is refused rather than sent to: the listener
+ * takes commands over its socket only and fetches none it missed, so the
+ * message would be stored and never typed.
+ *
+ * The CLI keeps its own copy (cli/src/agent-target.ts): it depends on this
+ * package, but this package's entry point starts the server when imported.
+ */
+const resolveAgentTarget = (devices, target, selfKey) => {
+    const all = candidatesOf(devices);
+    const toTarget = ({ deviceId, name, key, host, offline }) => {
+        if (offline) {
+            throw new AgentTargetError('TARGET_OFFLINE', `${key} is on ${host}, which is offline — the message would never be typed`);
+        }
+        return { deviceId, name, key };
+    };
+    const exact = all.find((c) => c.key === target);
+    if (exact)
+        return toTarget(exact);
+    const named = (c) => [c.name, c.alias, c.providerSessionName, c.label].some((n) => n === target);
+    const others = all.filter((c) => c.key !== selfKey);
+    const matches = others.filter(named);
+    if (matches.length === 1)
+        return toTarget(matches[0]);
+    if (matches.length === 0) {
+        const self = all.find((c) => c.key === selfKey && named(c));
+        if (self)
+            return toTarget(self);
+    }
+    if (matches.length > 1) {
+        throw new AgentTargetError('AMBIGUOUS_TARGET', `ambiguous target "${target}" — use one of these keys: ${listCandidates(matches)}`);
+    }
+    throw new AgentTargetError('UNKNOWN_TARGET', `unknown target "${target}" — other agent sessions: ${listCandidates(others)}`);
+};
+exports.resolveAgentTarget = resolveAgentTarget;

package/dist/api-client.d.ts

@@ -0,0 +1,162 @@
+import type { McpServerConfig } from './config.js';
+import type { PushResponse, HookTriggerResponse, HookEventResponse, DevicesResponse, DeviceKeyResponse, AgentSessionRenameResponse, PushListResponse, DismissResponse, ChannelsResponse, UploadRequestResponse, AttachedFile, LanDeliveredFile } from './types.js';
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    /** The request cannot have been sent: no connection was ever made. */
+    readonly unsent: boolean;
+    /** The transport's own code for a call that got no reply (`ECONNRESET`), when it gave one. */
+    readonly causeCode?: string;
+    /** A reply this client would not read to the end: the server answered, whatever it said. */
+    readonly unreadReply: boolean;
+    constructor(message: string, code: string, status: number, transport?: {
+        unsent?: boolean;
+        causeCode?: string;
+        unreadReply?: boolean;
+    });
+}
+/**
+ * A failed call that a later one may well get past: the network (NETWORK_ERROR,
+ * status 0), a reply that could not be read (BAD_RESPONSE, status 0), the
+ * request's own timeout, a rate limit, a server error. A 4xx
+ * other than 408 and 429 is an answer about the request itself (bad key, hook
+ * gone) and will say the same thing every time — and so does a refused redirect
+ * (REDIRECT_REFUSED, also status 0): the base URL sends the request elsewhere
+ * on every call. Nor does a base URL that is not an address get to be one.
+ */
+export declare const isTransient: (err: unknown) => boolean;
+/** The time a client waits by. Injected so a test does not sit out the pauses. */
+export interface Clock {
+    now: () => number;
+    /** Rejects with the signal's reason when it aborts first. */
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * The largest file any tier can send — Pro's 1 GiB (`fileMaxBytes` in hwip's
+ * shared tier-limits). The account's own tier still decides below this; the cap
+ * only stops a transfer no tier could accept from being read into memory.
+ */
+export declare const MAX_FILE_BYTES = 1073741824;
+/**
+ * The most a JSON reply (or an error body) may weigh. The API's own replies are
+ * a few KiB, a push list tens; 8 MiB is far past any real one and still small
+ * enough that a wrong or hostile host cannot make this process hold gigabytes.
+ */
+export declare const MAX_RESPONSE_BYTES: number;
+/**
+ * What a one-line message cannot carry: control characters (Cc), the invisible
+ * format characters (Cf — bidi marks and overrides, zero-width space, the BOM,
+ * and the Unicode tag block that can hide text from a reader but not from a
+ * model), the grapheme-join blocker U+034F, and the Hangul fillers (U+115F,
+ * U+1160, U+3164, U+FFA0 — blank letters an attacker would use as an invisible
+ * base character), and line and paragraph separators. U+200C ZWNJ and U+200D ZWJ
+ * are writing, not hiding (Persian, Hindi, emoji sequences), so a lone one
+ * stays — but a run of them is a bit channel, so a run collapses to its first
+ * character (C153). Selectors go by allowlist, not by run: U+FE0E/U+FE0F stay
+ * only after an emoji base (text/emoji presentation), U+E0100–E01EF only after a
+ * unified ideograph (IVS); every other selector — including the Mongolian FVS
+ * (U+180B–U+180D, U+180F) — goes, so spacing a run out with an invisible
+ * character no longer smuggles it past the rule. The same rule as cli's
+ * `UNPRINTABLE` block (src/http-failure.ts): the lines below from
+ * `const UNPRINTABLE` through `sanitizeSmuggled` are character-identical there.
+ */
+export declare const UNPRINTABLE: RegExp;
+/**
+ * The server's own wording, made safe to hand to the model: one line, control
+ * characters gone, cut to a fixed length. A reply from a hijacked or mistaken
+ * host could otherwise put a paragraph of instructions into the tool result.
+ */
+export declare const serverMessage: (value: unknown, fallback: string) => string;
+export declare const readCappedText: (response: Response, max: number) => Promise<string>;
+/** A file transfer's timeout: the usual request budget plus time for its bytes. */
+export declare const transferTimeoutMs: (bytes: number) => number;
+/**
+ * The per-request timeout, ended early by `outer` (the tool call's own abort)
+ * when one is given. Hand-rolled because `AbortSignal.any` needs Node 20.3 and
+ * the package supports 18.17. Each signal aborts with its own reason, so a
+ * timeout still reads as `TimeoutError` and a cancel as `AbortError`.
+ * `release` drops the listener on `outer` once the request has settled.
+ * Exported for tests.
+ */
+export declare const requestSignal: (timeoutMs: number, outer?: AbortSignal) => {
+    signal: AbortSignal;
+    release: () => void;
+};
+export declare class HwipApiClient {
+    private readonly clock;
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: McpServerConfig, clock?: Clock);
+    sendPush(params: {
+        title?: string;
+        body?: string;
+        url?: string;
+        type?: string;
+        priority?: string;
+        targetDeviceId?: string;
+        /** With `type: 'agent.command'`: the tmux session on `targetDeviceId` to type the body into. */
+        agentSessionName?: string;
+        channelId?: string;
+        sessionId?: string;
+        files?: (AttachedFile | LanDeliveredFile)[];
+        isEncrypted?: boolean;
+        senderPublicKey?: string;
+        deviceKeyMap?: Record<string, string>;
+    }): Promise<PushResponse>;
+    triggerHook(hookId: string, params: {
+        title?: string;
+        body?: string;
+        actions?: {
+            id: string;
+            label?: string;
+            style?: string;
+        }[];
+        /** A sealed question: `body`, `senderPublicKey` and `deviceKeyMap` hold the envelope (ask-seal.ts). */
+        isEncrypted?: true;
+        senderPublicKey?: string;
+        deviceKeyMap?: Record<string, string>;
+        timeout?: number;
+        fallback?: string;
+        metadata?: Record<string, unknown>;
+        hookType?: 'combo';
+        /** This ask settles an `exitRemote` answer (tools/ask.ts). */
+        acceptsExit?: boolean;
+        files?: AttachedFile[];
+        sessionId?: string;
+        /** Stable session grouping so the hook joins the agent chat. */
+        agentDeviceId?: string;
+        agentSessionName?: string;
+    }, signal?: AbortSignal, 
+    /**
+     * Sending again: for how long from now the question is still worth it, and who to tell before
+     * each wait (with how many there have been). Without it, one try.
+     */
+    retry?: {
+        withinMs: number;
+        onRetry?: (tries: number) => Promise<void>;
+    }): Promise<HookTriggerResponse>;
+    getHookEvent(hookId: string, eventId: string): Promise<HookEventResponse>;
+    listDevices(): Promise<DevicesResponse>;
+    /** Put this machine's key on the account's device list; `nickname` names it only when the server creates the entry. */
+    registerDeviceKey(deviceId: string, publicKey: string, nickname: string): Promise<DeviceKeyResponse>;
+    /** Set (or clear, when `alias` is empty) the display name for an agent
+     *  session, keyed by its tmux `name` on `deviceId`. */
+    renameAgentSession(deviceId: string, name: string, alias: string): Promise<AgentSessionRenameResponse>;
+    listPushes(params?: {
+        limit?: number;
+        type?: string;
+    }): Promise<PushListResponse>;
+    dismissPush(pushId: string): Promise<DismissResponse>;
+    dismissAllPushes(): Promise<DismissResponse>;
+    listChannels(): Promise<ChannelsResponse>;
+    requestUpload(params: {
+        fileName: string;
+        fileType: string;
+        fileSize: number;
+    }, signal?: AbortSignal): Promise<UploadRequestResponse>;
+    uploadToS3(url: string, content: string | Buffer, contentType: string, signal?: AbortSignal): Promise<void>;
+    private request;
+    /** One request, its JSON body already the bytes to send. */
+    private send;
+}
+//# sourceMappingURL=api-client.d.ts.map