@zeph-to/mcp-server 2.0.0 → 2.2.0

package/README.md

@@ -4,6 +4,7 @@
 [![downloads](https://img.shields.io/npm/dm/@zeph-to/mcp-server.svg)](https://www.npmjs.com/package/@zeph-to/mcp-server)
 [![node](https://img.shields.io/node/v/@zeph-to/mcp-server.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/@zeph-to/mcp-server.svg)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-docs.zeph.to-1f6feb)](https://docs.zeph.to)
 
 **Your agent calls `zeph_ask`; the question lands on your phone as buttons + a text field; your reply comes back into the same tool call and the agent keeps going.**
 
@@ -16,6 +17,8 @@ Zeph's MCP server is the agent side of that round trip — plus one-way notifica
 
 Part of the Zeph toolchain: [`@zeph-to/cli`](https://github.com/zeph-to/cli) (installer, push CLI, tmux remote control) · [`zeph-to/plugin`](https://github.com/zeph-to/plugin) (Claude Code plugin bundling this server) · the [Zeph app](https://zeph.to) on your phone.
 
+> **New here?** [docs.zeph.to](https://docs.zeph.to) walks the whole setup — one command on your machine, the app on your phone, and a restart. The reference below assumes that is already done.
+
 ## Setup
 
 The easiest way to set up for all agents at once:
@@ -70,7 +73,7 @@ e.g. a second account:
 | `ZEPH_WS_URL` | No | WebSocket endpoint for the hook-response fast path — `zeph_ask`/`zeph_prompt`/`zeph_input` answers arrive the moment the user submits them instead of on the next poll. Falls back to pure polling when unset. Also read from `wsUrl` in `~/.zeph/config.json` |
 | `ZEPH_DISABLE_SESSION_CACHE` | No | Set to `1`/`true` to skip writing the session-id handoff file under `~/.cache/zeph/`. Useful for read-only filesystems, ephemeral CI runners, or sandboxed envs that audit filesystem writes. The plugin's stop hook still works without it (transcript-path UUID extraction is the primary path; the cache is a fallback for older Claude Code versions). |
 | `ZEPH_SESSION_ID` | No | Override the session id attached to pushes (grouping in the app). Auto-detected from the newest Claude Code transcript when unset |
-| `ZEPH_DISABLE_ENCRYPTION` | No | Set to `1`/`true` to force E2E-style push encryption off, even when the account has keys. Useful while cleaning up legacy key state |
+| `ZEPH_DISABLE_ENCRYPTION` | No | Set to `1`/`true` to force push encryption off even when the account has it enabled. A local override for debugging what the server actually received — encryption is already off unless the account opted in (see [Encryption](#encryption)) |
 
 \* If env vars are not set, the server reads from `~/.zeph/config.json` (created by `zeph install`). Unresolved `${...}` interpolations are also treated as unset.
 
@@ -205,6 +208,16 @@ fallback:    "skip" (auto-select on timeout, optional)
 
 Returns: `{ actionId: "fix", timedOut: false }` or `{ value: "custom text", timedOut: false }`
 
+The user can also attach screenshots or files to their answer. Those are downloaded to `~/.zeph/attachments/hook-<eventId>/` and the result gains an `attachments` array of absolute local paths, alongside the button or the text:
+
+```
+{ value: "look at this", attachments: ["/Users/you/.zeph/attachments/hook-hevt_1/screen.png"],
+  attachmentsNote: "The user attached 1 file(s) to this answer. Read each path above to see them.",
+  timedOut: false }
+```
+
+Reading those paths is part of reading the answer. Note that hook attachments are never end-to-end encrypted — the same limitation as the question itself, since the hook route carries no sender key.
+
 ### zeph_input
 
 Request free-form text input from the user. Blocks until response or timeout.
@@ -219,7 +232,7 @@ inputType:   "text" | "password" | "multiline"
 timeout:     120    (seconds, default: 120, max: 600)
 ```
 
-Returns: `{ value: "feat: add clipboard sync", timedOut: false }`
+Returns: `{ value: "feat: add clipboard sync", timedOut: false }` — plus `attachments` when the user attached files, exactly as in `zeph_ask` above.
 
 ### Client timeouts
 
@@ -329,12 +342,12 @@ Create an API key with the **MCP** preset in Settings > API Keys for the correct
 
 ## Encryption
 
-Push bodies and file attachments are encrypted with AES-256-GCM. This server holds its own ECDH P-256 keypair, generated on first use and stored in `~/.config/zeph/device-keys.json` — the private half never leaves the machine. Each push is encrypted once, and its AES key is wrapped separately for every device on your account using ECDH against that device's public key.
+End-to-end encryption is **off by default** and turning it on needs Zeph Pro. The switch is in the app under Settings → E2E Encryption; until you flip it, every push leaves this server in plaintext. If the account later loses Pro the server answers `PRO_REQUIRED` and this one drops back to plaintext for the rest of the process. No configuration either way — but the opt-in is read **once at startup**, so turning it on while this server is running takes effect only after a restart.
 
-Toggle encryption in the Zeph app (Settings → Encryption); when it is off, pushes go out as plaintext. No configuration needed. The opt-in is read once at startup, so **turning it on while this server is running takes effect only after a restart.**
+With it on, push bodies and file attachments are encrypted with AES-256-GCM. This server holds its own ECDH P-256 keypair, generated on first use and stored in `~/.config/zeph/device-keys.json` — the private half never leaves the machine, and the backend stores public keys only and rejects a private-key upload. Each push is encrypted once, and its AES key is wrapped separately for every device on your account using ECDH against that device's public key.
 
 **Threat model:** against a passive backend — a leaked snapshot, an operator reading the table — the stored ciphertext and wrapped keys are useless, so push contents stay private. Three limits worth knowing:
-- **No protection from an active malicious operator.** Recipient public keys come from `GET /devices` on that same server, unsigned and unpinned. A backend that injects a device record carrying its own key gets the message key wrapped for it, and reads everything. Closing this needs out-of-band device verification (ADR-0007 Phase 4, not built).
+- **No protection from an active malicious operator.** Recipient public keys come from `GET /devices` on that same server, unsigned and unpinned. A backend that injects a device record carrying its own key gets the message key wrapped for it, and reads everything. The Zeph app ships the counter-measure — compare device fingerprints, mark a device verified, and strict mode then wraps only for verified devices — but it defaults off, its verified list is per browser profile, and this server does not consult it: `selectRecipients` asks only whether a device has a public key, and whether that key is the legacy account-wide one (ADR-0007 Phase 4).
 - **No forward secrecy.** The ECDH secret for a given sender/device pair is static, so compromising either private key opens every past push wrapped for that pair.
 - **`senderPublicKey` is unsigned**, so a swapped one makes a push undecryptable — that direction fails closed rather than leaking.
 

package/dist/api-client.d.ts

@@ -57,6 +57,12 @@ export declare class ZephApiClient {
         fileType: string;
         fileSize: number;
     }): Promise<UploadRequestResponse>;
+    /**
+     * Resolve a fileKey to its bytes. Two hops by design: the API hands back a
+     * presigned URL (files never travel through Lambda), and that URL is
+     * self-authenticating, so the second fetch carries no API key.
+     */
+    downloadFile(fileKey: string): Promise<Uint8Array>;
     uploadToS3(url: string, content: string | Buffer, contentType: string): Promise<void>;
     private request;
 }

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAEV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAC1B,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAKjC;AAKD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,eAAe;IAK7B,QAAQ,CAAC,MAAM,EAAE;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACvC,GAAG,OAAO,CAAC,YAAY,CAAC;IAInB,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,QAAQ,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gEAAgE;QAChE,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GACA,OAAO,CAAC,mBAAmB,CAAC;IAIzB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzE,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAI7C;2DACuD;IACjD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAQtG,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQjF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrD,gBAAgB,IAAI,OAAO,CAAC,eAAe,CAAC;IAI5C,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIzC,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAc7E,OAAO;CA0CtB"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-client.js

@@ -59,6 +59,22 @@ class ZephApiClient {
     async requestUpload(params) {
         return this.request('POST', '/files/upload-request', params);
     }
+    /**
+     * Resolve a fileKey to its bytes. Two hops by design: the API hands back a
+     * presigned URL (files never travel through Lambda), and that URL is
+     * self-authenticating, so the second fetch carries no API key.
+     */
+    async downloadFile(fileKey) {
+        const meta = await this.request('GET', `/files/${encodeURIComponent(fileKey)}`);
+        const downloadUrl = meta.data?.downloadUrl;
+        if (!downloadUrl)
+            throw new ApiError('Download URL missing', 'DOWNLOAD_FAILED', 502);
+        const response = await fetch(downloadUrl, { signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS) });
+        if (!response.ok) {
+            throw new ApiError(`File download failed with status ${response.status}`, 'DOWNLOAD_FAILED', response.status);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
     async uploadToS3(url, content, contentType) {
         const isText = typeof content === 'string';
         const body = isText ? content : new Uint8Array(content);

package/dist/config.d.ts

@@ -16,6 +16,15 @@ export interface McpServerConfig {
     /** Last path segment of the project directory — prefixed onto push titles. */
     projectName: string;
 }
+/** The project directory the agent runs in, across supported agents. */
+/**
+ * The key every per-project zeph file is named by. Shelling out to `cksum`
+ * (rather than a pure-JS CRC) is what guarantees it matches the files the bash
+ * hooks have already written — they key off `printf '%s' "$dir" | cksum`. Null
+ * when `cksum` is unavailable, which means no per-project file can be resolved.
+ */
+export declare const projectHash: (dir: string) => string | null;
+export declare const detectProjectDir: () => string;
 /**
  * Prefix a push title with the project name so the device feed stays
  * scannable — "zeph · Build finished" instead of a bare "Build finished".

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uCAGmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAiBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAuGF,eAAO,MAAM,UAAU,QAAO,eAiC7B,CAAC;AA4BF;;;;;sEAKsE;AACtE,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uCAGmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,wEAAwE;AACxE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAMlD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,MAMnC,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAwGF,eAAO,MAAM,UAAU,QAAO,eAiC7B,CAAC;AA4BF;;;;;sEAKsE;AACtE,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC"}

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listenerDeviceId = exports.loadConfig = exports.formatPushTitle = void 0;
+exports.listenerDeviceId = exports.loadConfig = exports.formatPushTitle = exports.detectProjectDir = exports.projectHash = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const crypto_1 = require("crypto");
@@ -9,6 +9,21 @@ const path_1 = require("path");
 const DEFAULT_BASE_URL = 'https://api.zeph.to/v1';
 const PROJECT_DIR_ENV_KEYS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
 /** The project directory the agent runs in, across supported agents. */
+/**
+ * The key every per-project zeph file is named by. Shelling out to `cksum`
+ * (rather than a pure-JS CRC) is what guarantees it matches the files the bash
+ * hooks have already written — they key off `printf '%s' "$dir" | cksum`. Null
+ * when `cksum` is unavailable, which means no per-project file can be resolved.
+ */
+const projectHash = (dir) => {
+    try {
+        return (0, child_process_1.execFileSync)('cksum', { input: dir, encoding: 'utf-8' }).split(' ')[0] || null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.projectHash = projectHash;
 const detectProjectDir = () => {
     for (const key of PROJECT_DIR_ENV_KEYS) {
         const val = process.env[key];
@@ -17,6 +32,7 @@ const detectProjectDir = () => {
     }
     return process.cwd();
 };
+exports.detectProjectDir = detectProjectDir;
 /** Last path segment of a directory: "/Users/me/code/zeph" -> "zeph". */
 const projectNameFromDir = (dir) => dir.split('/').filter(Boolean).pop() ?? 'project';
 /**
@@ -106,7 +122,9 @@ const writeSessionCache = (sessionId, projectDir) => {
     if (envIsTrue('ZEPH_DISABLE_SESSION_CACHE'))
         return;
     try {
-        const hash = (0, child_process_1.execFileSync)('cksum', { input: projectDir, encoding: 'utf-8' }).split(' ')[0];
+        const hash = (0, exports.projectHash)(projectDir);
+        if (!hash)
+            return;
         const cacheDir = (0, path_1.join)(process.env.XDG_CACHE_HOME ?? (0, path_1.join)((0, os_1.homedir)(), '.cache'), 'zeph');
         (0, fs_1.mkdirSync)(cacheDir, { recursive: true, mode: 0o700 });
         const cachePath = (0, path_1.join)(cacheDir, `session-${hash}`);
@@ -130,7 +148,7 @@ const loadConfig = () => {
     if (!apiKey) {
         throw new Error('ZEPH_API_KEY not found. Run "npx @zeph-to/cli install" or set ZEPH_API_KEY env var.');
     }
-    const projectDir = detectProjectDir();
+    const projectDir = (0, exports.detectProjectDir)();
     // Claude Code names the running session outright; take it over the
     // transcript scan, which picks the newest file in the project directory and
     // so returns a sibling agent's id whenever two run in one project — the

package/dist/remote-state.d.ts

@@ -0,0 +1,34 @@
+/**
+ * True when this button ends the session. Case-insensitive by contract — the
+ * rules have always said so, but until now nothing enforced it, so a skill
+ * emitting `Done` would have read as a non-exit answer and left the user in
+ * REMOTE for the whole TTL.
+ */
+export declare const isSessionExitId: (actionId: string) => boolean;
+/**
+ * What a `zeph_ask` outcome does to the mode.
+ *
+ * - **exit** — a Done-like id, whether the user tapped it or a timeout
+ *   resolved to it. This is the one case a fallback ends the session.
+ * - **enter** — the user answered with anything else: another button, or free
+ *   text (no id at all). Free text the server cannot judge — "thanks, that's
+ *   it" is a meaning call that stays with the model — so it counts as staying.
+ * - **keep** — the ask timed out onto a non-exit fallback. Rule 5 recommends
+ *   `wait`/`review` there, and ask.ts returns the fallback id verbatim, so
+ *   reading it as an exit would drop a user out of REMOTE over an ask they
+ *   simply had not answered yet. Nor is it an entry: a timeout is not a user
+ *   action, and a NORMAL session must not become remote because nobody
+ *   replied. The mode is left exactly as it was.
+ */
+export type RemoteTransition = 'enter' | 'exit' | 'keep';
+export declare const remoteTransitionFor: (answer: {
+    actionId?: string;
+    timedOut: boolean;
+}) => RemoteTransition;
+/** `<stateDir>/remote-active-<projectHash>`, or null when the key can't be built. */
+export declare const remoteStatePath: () => string | null;
+/** Enter REMOTE, or push its expiry back. Best-effort: never throws. */
+export declare const enterRemote: () => void;
+/** Leave REMOTE. Best-effort: never throws, and a missing file is success. */
+export declare const exitRemote: () => void;
+//# sourceMappingURL=remote-state.d.ts.map

package/dist/remote-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-state.d.ts","sourceRoot":"","sources":["../src/remote-state.ts"],"names":[],"mappings":"AA8BA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,OAC8B,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,eAAO,MAAM,mBAAmB,GAC9B,QAAQ;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,KAC/C,gBAGF,CAAC;AAKF,qFAAqF;AACrF,eAAO,MAAM,eAAe,QAAO,MAAM,GAAG,IAG3C,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,WAAW,QAAO,IAS9B,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,UAAU,QAAO,IAQ7B,CAAC"}

package/dist/remote-state.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitRemote = exports.enterRemote = exports.remoteStatePath = exports.remoteTransitionFor = exports.isSessionExitId = void 0;
+/**
+ * Sticky REMOTE state — the server's half.
+ *
+ * REMOTE used to have nowhere to live: the model re-derived it every turn by
+ * rescanning the conversation. It now lives in a file, and this module is one
+ * of the two places that owns a transition. The other is the plugin's
+ * UserPromptSubmit hook, which enters REMOTE when a prompt matches a
+ * phone-injection marker; this module handles the transitions the server
+ * already knows about — a `zeph_ask` that came back answered.
+ *
+ * **Three implementations share the file format** — plugin/hooks/gate.sh
+ * (`zeph_remote_active` / `zeph_remote_touch`), cli/src/gate.ts
+ * (`isRemoteActive` / `touchRemoteActive`), and this file. Nothing checks them
+ * against each other at build time, so the format is pinned by literal
+ * assertions in remote-state.test.ts. The bash reader sweeps any non-numeric
+ * body on sight (`case "$ts" in *[!0-9]*)`), which means a JSON or ISO-8601
+ * body written here would enter REMOTE and be deleted by the very next prompt
+ * hook — silently, and invisibly from either repo's tests.
+ *
+ * There is no TTL logic here on purpose: expiry is the readers' job, and
+ * duplicating the window would give it two definitions.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const config_js_1 = require("./config.js");
+/** Action ids that end a remote session (CORE_RULES: case-insensitive). */
+const SESSION_EXIT_IDS = ['done', 'stop', 'exit'];
+/**
+ * True when this button ends the session. Case-insensitive by contract — the
+ * rules have always said so, but until now nothing enforced it, so a skill
+ * emitting `Done` would have read as a non-exit answer and left the user in
+ * REMOTE for the whole TTL.
+ */
+const isSessionExitId = (actionId) => SESSION_EXIT_IDS.includes(actionId.trim().toLowerCase());
+exports.isSessionExitId = isSessionExitId;
+const remoteTransitionFor = (answer) => {
+    if (answer.actionId !== undefined && (0, exports.isSessionExitId)(answer.actionId))
+        return 'exit';
+    return answer.timedOut ? 'keep' : 'enter';
+};
+exports.remoteTransitionFor = remoteTransitionFor;
+const stateDir = () => (0, path_1.join)(process.env.XDG_STATE_HOME || (0, path_1.join)((0, os_1.homedir)(), '.local', 'state'), 'zeph');
+/** `<stateDir>/remote-active-<projectHash>`, or null when the key can't be built. */
+const remoteStatePath = () => {
+    const hash = (0, config_js_1.projectHash)((0, config_js_1.detectProjectDir)());
+    return hash ? (0, path_1.join)(stateDir(), `remote-active-${hash}`) : null;
+};
+exports.remoteStatePath = remoteStatePath;
+/** Enter REMOTE, or push its expiry back. Best-effort: never throws. */
+const enterRemote = () => {
+    const file = (0, exports.remoteStatePath)();
+    if (!file)
+        return;
+    try {
+        (0, fs_1.mkdirSync)(stateDir(), { recursive: true });
+        (0, fs_1.writeFileSync)(file, `${Math.floor(Date.now() / 1000)}\n`);
+    }
+    catch {
+        /* an answered ask is still an answer — state IO must not reach the caller */
+    }
+};
+exports.enterRemote = enterRemote;
+/** Leave REMOTE. Best-effort: never throws, and a missing file is success. */
+const exitRemote = () => {
+    const file = (0, exports.remoteStatePath)();
+    if (!file)
+        return;
+    try {
+        (0, fs_1.unlinkSync)(file);
+    }
+    catch {
+        /* already gone, or unwritable — either way the caller has an answer */
+    }
+};
+exports.exitRemote = exitRemote;

package/dist/response-files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Saving the files a user attached to a hook answer.
+ *
+ * `zeph_ask` and `zeph_input` hand the agent a JSON result, and an agent
+ * cannot look at an S3 key — so an answered screenshot only becomes useful
+ * once it is a path on this machine. This module downloads each attachment
+ * to `~/.zeph/attachments/hook-<eventId>/` and returns the absolute paths,
+ * which the tool then names in its result for the agent to read.
+ *
+ * The files are plaintext by contract: the hook route carries no sender key,
+ * so the server rejects an encrypted attachment on a response rather than
+ * let one arrive here as bytes nothing can open.
+ *
+ * Failure is per file, never fatal. A question that was answered has been
+ * answered; losing one image must not turn that into a tool error and make
+ * the user answer again.
+ */
+import type { ZephApiClient } from './api-client.js';
+import type { AttachedFile } from './types.js';
+/**
+ * The part of a tool result that tells the agent about saved attachments.
+ * Spread into the result object; empty when nothing was attached, so a plain
+ * answer keeps the shape it has always had.
+ *
+ * The instruction is explicit because a bare list of paths in a JSON result
+ * reads as metadata — the agent has to be told these are the user's answer
+ * and that opening them is part of reading it.
+ */
+export declare const attachmentNote: (paths: string[]) => Record<string, unknown>;
+export interface SaveResponseFilesDeps {
+    /** Test seam for the two-step fetch (metadata → presigned URL → bytes). */
+    fetchBytes?: (fileKey: string) => Promise<Uint8Array>;
+    dir?: string;
+}
+export declare const saveResponseFiles: (client: ZephApiClient, eventId: string, files: AttachedFile[] | undefined, deps?: SaveResponseFilesDeps) => Promise<string[]>;
+//# sourceMappingURL=response-files.d.ts.map

package/dist/response-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-files.d.ts","sourceRoot":"","sources":["../src/response-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAmB/C;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAM/D,CAAC;AAET,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,aAAa,EACrB,SAAS,MAAM,EACf,OAAO,YAAY,EAAE,GAAG,SAAS,EACjC,OAAM,qBAA0B,KAC/B,OAAO,CAAC,MAAM,EAAE,CAiBlB,CAAC"}

package/dist/response-files.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Saving the files a user attached to a hook answer.
+ *
+ * `zeph_ask` and `zeph_input` hand the agent a JSON result, and an agent
+ * cannot look at an S3 key — so an answered screenshot only becomes useful
+ * once it is a path on this machine. This module downloads each attachment
+ * to `~/.zeph/attachments/hook-<eventId>/` and returns the absolute paths,
+ * which the tool then names in its result for the agent to read.
+ *
+ * The files are plaintext by contract: the hook route carries no sender key,
+ * so the server rejects an encrypted attachment on a response rather than
+ * let one arrive here as bytes nothing can open.
+ *
+ * Failure is per file, never fatal. A question that was answered has been
+ * answered; losing one image must not turn that into a tool error and make
+ * the user answer again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveResponseFiles = exports.attachmentNote = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** Shared with the `zeph listener` daemon, which writes push attachments here. */
+const ATTACHMENTS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.zeph', 'attachments');
+/**
+ * Make a filesystem-safe single path segment: take the basename (drops any
+ * `../` prefix), strip control characters and embedded separators, remove
+ * leading dots, and cap the length. Empty or dot-only names use the fallback.
+ */
+const safeSegment = (raw, fallback) => {
+    const cleaned = (0, node_path_1.basename)(raw)
+        .replace(/[\x00-\x1f\x7f]/g, '')
+        .replace(/[/\\]/g, '_')
+        .replace(/^\.+/, '')
+        .trim();
+    return (cleaned || fallback).slice(0, 200);
+};
+/**
+ * The part of a tool result that tells the agent about saved attachments.
+ * Spread into the result object; empty when nothing was attached, so a plain
+ * answer keeps the shape it has always had.
+ *
+ * The instruction is explicit because a bare list of paths in a JSON result
+ * reads as metadata — the agent has to be told these are the user's answer
+ * and that opening them is part of reading it.
+ */
+const attachmentNote = (paths) => paths.length
+    ? {
+        attachments: paths,
+        attachmentsNote: `The user attached ${paths.length} file(s) to this answer. Read each path above to see them.`,
+    }
+    : {};
+exports.attachmentNote = attachmentNote;
+const saveResponseFiles = async (client, eventId, files, deps = {}) => {
+    if (!files?.length)
+        return [];
+    const fetchBytes = deps.fetchBytes ?? ((key) => client.downloadFile(key));
+    const dir = (0, node_path_1.join)(deps.dir ?? ATTACHMENTS_DIR, safeSegment(`hook-${eventId}`, 'hook'));
+    const paths = [];
+    for (const [i, file] of files.entries()) {
+        try {
+            const bytes = await fetchBytes(file.fileKey);
+            (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+            const abs = (0, node_path_1.join)(dir, safeSegment(file.fileName || `file-${i}`, `file-${i}`));
+            (0, node_fs_1.writeFileSync)(abs, bytes);
+            paths.push(abs);
+        }
+        catch (err) {
+            console.error(`[zeph] attachment "${file.fileName}" failed to save: ${err.message}`);
+        }
+    }
+    return paths;
+};
+exports.saveResponseFiles = saveResponseFiles;

package/dist/tools/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/tools/ask.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAuBxD,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SAyH7H,CAAC"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/tools/ask.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAkDxD,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SA+I7H,CAAC"}

package/dist/tools/ask.js

@@ -7,6 +7,8 @@ const poll_js_1 = require("../poll.js");
 const config_js_1 = require("../config.js");
 const mime_js_1 = require("../mime.js");
 const sanitize_js_1 = require("../sanitize.js");
+const response_files_js_1 = require("../response-files.js");
+const remote_state_js_1 = require("../remote-state.js");
 // The device feed shows a short preview of the body. Anything longer than
 // this gets truncated there, so we attach the full text as a file — the
 // user can always open the complete content instead of squinting at a
@@ -20,9 +22,31 @@ const buildAskMarkdown = (title, body, actions) => {
     }
     return parts.join('\n');
 };
+/**
+ * Apply the mode transition this answer implies, and tell the model where it
+ * landed. The state itself lives in a file the prompt hooks also read, so the
+ * two carriers agree without either re-deriving REMOTE from the transcript.
+ *
+ * `zephState` is reported only when the server actually decided something. A
+ * timeout onto a safe fallback changes nothing, and naming a state there would
+ * mean re-reading the file — a fourth parser of a format three already share,
+ * to answer a question the server was not asked.
+ */
+const settleRemoteState = (answer) => {
+    switch ((0, remote_state_js_1.remoteTransitionFor)(answer)) {
+        case 'exit':
+            (0, remote_state_js_1.exitRemote)();
+            return { zephState: 'NORMAL' };
+        case 'enter':
+            (0, remote_state_js_1.enterRemote)();
+            return { zephState: 'REMOTE' };
+        case 'keep':
+            return {};
+    }
+};
 const registerAskTool = (server, client, config, waiter) => {
     server.registerTool('zeph_ask', {
-        description: 'Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.',
+        description: 'Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files to the answer: those arrive as local absolute paths in the `attachments` field of the result, and reading them is part of reading the answer. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.',
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -107,14 +131,34 @@ const registerAskTool = (server, client, config, waiter) => {
             });
             const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx, waiter);
             if (!event) {
-                if (fallback)
-                    return (0, error_format_js_1.textResult)({ actionId: fallback, timedOut: true });
+                if (fallback) {
+                    return (0, error_format_js_1.textResult)({
+                        actionId: fallback,
+                        timedOut: true,
+                        ...settleRemoteState({ actionId: fallback, timedOut: true }),
+                    });
+                }
                 return (0, error_format_js_1.timeoutError)(timeout, 'Try again or use zeph_notify for one-way communication');
             }
             const response = event.data.response;
-            if (response?.actionId)
-                return (0, error_format_js_1.textResult)({ actionId: response.actionId, timedOut: false });
-            return (0, error_format_js_1.textResult)({ value: response?.value ?? '', timedOut: false });
+            // Saved before the button branch returns: a user can tap a quick reply
+            // AND attach a screenshot, and dropping the files there would lose them
+            // silently for the one caller that never looks at `value`.
+            const attachments = await (0, response_files_js_1.saveResponseFiles)(client, trigger.data.eventId, response?.files);
+            if (response?.actionId) {
+                return (0, error_format_js_1.textResult)({
+                    actionId: response.actionId,
+                    timedOut: false,
+                    ...settleRemoteState({ actionId: response.actionId, timedOut: false }),
+                    ...(0, response_files_js_1.attachmentNote)(attachments),
+                });
+            }
+            return (0, error_format_js_1.textResult)({
+                value: response?.value ?? '',
+                timedOut: false,
+                ...settleRemoteState({ timedOut: false }),
+                ...(0, response_files_js_1.attachmentNote)(attachments),
+            });
         }
         catch (err) {
             return (0, error_format_js_1.formatToolError)(err);

package/dist/tools/input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/tools/input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAErE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,eAAO,MAAM,iBAAiB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SA2D/H,CAAC"}
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/tools/input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAGrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,eAAO,MAAM,iBAAiB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SAgE/H,CAAC"}

package/dist/tools/input.js

@@ -6,9 +6,10 @@ const error_format_js_1 = require("../error-format.js");
 const poll_js_1 = require("../poll.js");
 const config_js_1 = require("../config.js");
 const sanitize_js_1 = require("../sanitize.js");
+const response_files_js_1 = require("../response-files.js");
 const registerInputTool = (server, client, config, waiter) => {
     server.registerTool('zeph_input', {
-        description: 'Request text input from the user via push notification. The tool blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable.',
+        description: 'Request text input from the user via push notification. The tool blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files: those arrive as local absolute paths in the `attachments` field of the result, and reading them is part of reading the answer.',
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -46,7 +47,12 @@ const registerInputTool = (server, client, config, waiter) => {
             const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx, waiter);
             if (!event)
                 return (0, error_format_js_1.timeoutError)(timeout, 'Try again with a longer timeout');
-            return (0, error_format_js_1.textResult)({ value: event.data.response?.value ?? '', timedOut: false });
+            const attachments = await (0, response_files_js_1.saveResponseFiles)(client, trigger.data.eventId, event.data.response?.files);
+            return (0, error_format_js_1.textResult)({
+                value: event.data.response?.value ?? '',
+                timedOut: false,
+                ...(0, response_files_js_1.attachmentNote)(attachments),
+            });
         }
         catch (err) {
             return (0, error_format_js_1.formatToolError)(err);

package/dist/types.d.ts

@@ -23,6 +23,9 @@ export interface HookEventResponse {
         response?: {
             actionId?: string;
             value?: string;
+            /** Screenshots and files the user attached to the answer — plaintext,
+             *  since the hook route carries no key this end could decrypt with. */
+            files?: AttachedFile[];
             respondedDeviceId?: string;
         };
     };
@@ -89,6 +92,11 @@ export interface UploadRequestResponse {
         uploadUrl: string;
     };
 }
+export interface DownloadUrlResponse {
+    data: {
+        downloadUrl: string;
+    };
+}
 export interface AttachedFile {
     fileKey: string;
     fileName: string;

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/mcp-server",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Zeph MCP server — AI agent notifications, prompts, and input via MCP protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",