@kmmao/happy-agent 0.7.1 → 0.7.2

package/dist/index.cjs

@@ -39,7 +39,7 @@ function _interopNamespaceDefault(e) {
 
 var z__namespace = /*#__PURE__*/_interopNamespaceDefault(z);
 
-var version = "0.7.1";
+var version = "0.7.2";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://s.sangreal.code.xycloud.info:2443").replace(/\/+$/, "");
@@ -157,6 +157,21 @@ function decrypt(key, variant, data) {
     return decryptWithDataKey(data, key);
   }
 }
+function createCipher(key, variant) {
+  return {
+    encrypt(data) {
+      return encodeBase64(encrypt(key, variant, data));
+    },
+    decrypt(data) {
+      try {
+        const value = decrypt(key, variant, decodeBase64(data));
+        return value === null ? { ok: false } : { ok: true, value };
+      } catch {
+        return { ok: false };
+      }
+    }
+  };
+}
 function libsodiumEncryptForPublicKey(data, recipientPublicKey) {
   const ephemeralKeyPair = tweetnacl.box.keyPair();
   const nonce = getRandomBytes(tweetnacl.box.nonceLength);
@@ -639,16 +654,14 @@ async function withBackoff(fn, options) {
 class RpcHandlerManager {
   handlers = /* @__PURE__ */ new Map();
   scopePrefix;
-  encryptionKey;
-  encryptionVariant;
+  cipher;
   logger;
   socket = null;
   reregisterInterval = null;
   fastRetryTimer = null;
   constructor(config) {
     this.scopePrefix = config.scopePrefix;
-    this.encryptionKey = config.encryptionKey;
-    this.encryptionVariant = config.encryptionVariant;
+    this.cipher = config.cipher;
     this.logger = config.logger ?? ((msg, data) => logger.debug(msg, data));
   }
   /**
@@ -662,45 +675,45 @@ class RpcHandlerManager {
     }
   }
   /**
-   * Handle an incoming RPC request
+   * Route a decrypted RPC call to its handler. This is the plaintext core of
+   * the manager: it knows nothing about the wire (no base64, no cipher), so it
+   * is TOTAL — an unknown method or a throwing handler both resolve to an
+   * `{ error }` value rather than rejecting. That makes it the test surface for
+   * routing behaviour, exercised without any crypto setup.
    */
-  async handleRequest(request) {
+  async dispatch(method, params) {
+    const handler = this.handlers.get(method);
+    if (!handler) {
+      this.logger("[RPC] [ERROR] Method not found", { method });
+      return { error: "Method not found" };
+    }
     try {
-      const handler = this.handlers.get(request.method);
-      if (!handler) {
-        this.logger("[RPC] [ERROR] Method not found", {
-          method: request.method
-        });
-        const errorResponse = { error: "Method not found" };
-        return encodeBase64(
-          encrypt(this.encryptionKey, this.encryptionVariant, errorResponse)
-        );
-      }
-      const decryptedParams = decrypt(
-        this.encryptionKey,
-        this.encryptionVariant,
-        decodeBase64(request.params)
-      );
-      this.logger("[RPC] Calling handler", { method: request.method });
-      const result = await handler(decryptedParams);
+      this.logger("[RPC] Calling handler", { method });
+      const result = await handler(params);
       this.logger("[RPC] Handler returned", {
-        method: request.method,
+        method,
         hasResult: result !== void 0
       });
-      const encryptedResponse = encodeBase64(
-        encrypt(this.encryptionKey, this.encryptionVariant, result)
-      );
-      return encryptedResponse;
+      return result;
     } catch (error) {
       this.logger("[RPC] [ERROR] Error handling request", { error });
-      const errorResponse = {
-        error: error instanceof Error ? error.message : "Unknown error"
-      };
-      return encodeBase64(
-        encrypt(this.encryptionKey, this.encryptionVariant, errorResponse)
-      );
+      return { error: error instanceof Error ? error.message : "Unknown error" };
     }
   }
+  /**
+   * Handle an incoming wire RPC request: decrypt params, dispatch in plaintext,
+   * encrypt the result. The Cipher is the only encryption seam; on a decrypt
+   * failure the handler is still dispatched with `null` params (preserving the
+   * previous behaviour where a corrupt payload decrypted to `null`).
+   */
+  async handleRequest(request) {
+    const decrypted = this.cipher.decrypt(request.params);
+    const result = await this.dispatch(
+      request.method,
+      decrypted.ok ? decrypted.value : null
+    );
+    return this.cipher.encrypt(result);
+  }
   onSocketConnect(socket) {
     this.socket = socket;
     this.registerAllHandlers(socket);
@@ -1464,8 +1477,7 @@ class SessionClient extends node_events.EventEmitter {
     });
     this.rpcHandlerManager = createRpcHandlerManager({
       scopePrefix: `session:${opts.sessionId}`,
-      encryptionKey: opts.encryptionKey,
-      encryptionVariant: opts.encryptionVariant,
+      cipher: createCipher(opts.encryptionKey, opts.encryptionVariant),
       logger: (msg, data) => logger.debug(msg, data)
     });
     if (opts.enableRpc !== false) {
@@ -2673,6 +2685,17 @@ const sessionEnvelopeSchema = z__namespace.object({
   subagent: z__namespace.string().refine((value) => cuid2Exports.isCuid(value), {
     message: "subagent must be a cuid2 value"
   }).optional(),
+  /**
+   * Optional Claude-side message UUID for this envelope. Populated by the
+   * CLI when an envelope mirrors a specific JSONL record, so the App can
+   * use it as a precise rewind/fork anchor (the CLI's `forkSession` RPC
+   * accepts this value as `upToMessageId`).
+   *
+   * Backward-compatible: older CLIs / non-Claude agents simply omit it.
+   * App code MUST treat absence as "no fork anchor available" rather than
+   * an error.
+   */
+  claudeUuid: z__namespace.string().min(1).optional(),
   ev: sessionEventSchema
 }).superRefine((envelope, ctx) => {
   if (envelope.ev.t === "service" && envelope.role !== "agent") {
@@ -3850,8 +3873,27 @@ const HAPPY_MCP_TOOL_NAMES = [
   "change_title",
   "query_project_knowledge",
   "update_progress",
-  "update_session_summary"
+  "update_session_summary",
+  "ask_user"
 ];
+const parseIfJsonString = (v) => {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+};
+const looseStringArray = () => z.z.union([z.z.array(z.z.string()), z.z.string()]).transform((v) => {
+  if (Array.isArray(v)) return v;
+  const parsed = parseIfJsonString(v);
+  if (Array.isArray(parsed)) return parsed.map(String);
+  return v.length ? [v] : [];
+});
+const looseObjectArray = (item) => z.z.union([
+  z.z.array(item),
+  z.z.string().transform(parseIfJsonString).pipe(z.z.array(item))
+]);
 const HAPPY_MCP_TOOL_SPECS = {
   change_title: {
     title: "Change Title",
@@ -3886,7 +3928,7 @@ const HAPPY_MCP_TOOL_SPECS = {
     description: 'Optional override for the App\'s Progress tab. In most cases your TodoWrite calls are auto-mirrored, so you do NOT need to call this. Use it only when you want to set extra fields the CLI hook does not capture (currentStage, blockers) or to force a new list boundary with `listId: "new"`.',
     failureLabel: "Failed to update progress",
     inputSchema: {
-      todos: z.z.array(
+      todos: looseObjectArray(
         z.z.object({
           content: z.z.string().describe("Concise description of the task"),
           status: z.z.enum(["pending", "in_progress", "completed"]).describe("Current status of the task"),
@@ -3897,7 +3939,7 @@ const HAPPY_MCP_TOOL_SPECS = {
         })
       ).describe("The full checklist \u2014 always send every item, not a delta"),
       currentStage: z.z.string().optional().describe("Optional overall stage name for the checklist"),
-      blockers: z.z.array(z.z.string()).optional().describe("Optional list of things blocking progress"),
+      blockers: looseStringArray().optional().describe("Optional list of things blocking progress"),
       listId: z.z.string().optional().describe("Target list id. Use 'new' to force a fresh list"),
       label: z.z.string().optional().describe("Short human-readable name for this task list")
     },
@@ -3908,6 +3950,33 @@ const HAPPY_MCP_TOOL_SPECS = {
     fallbackAction: "Update progress",
     reasonPhrases: ["progress update", "progress updates", "update_progress"]
   },
+  ask_user: {
+    title: "Ask User",
+    description: "Ask the user one or more questions via the App's native picker UI. Use this whenever AskUserQuestion is unavailable (the host has disabled it \u2014 common when running under happy-cli's PTY-mode Claude TUI). The input schema is identical to AskUserQuestion's. The tool blocks until the user submits answers in the App, then returns them as a JSON string keyed by question text.",
+    failureLabel: "Failed to get user answer",
+    inputSchema: {
+      questions: looseObjectArray(
+        z.z.object({
+          question: z.z.string().describe("The question to ask the user"),
+          header: z.z.string().describe("Short label/chip for the question (max ~12 chars)"),
+          options: looseObjectArray(
+            z.z.object({
+              label: z.z.string().describe("Option label"),
+              description: z.z.string().describe("Option description"),
+              preview: z.z.string().optional().describe("Optional preview content shown when the option is focused")
+            })
+          ).describe("Available choices for this question (2-4 options)"),
+          multiSelect: z.z.boolean().describe("Allow multiple selections instead of single-select")
+        })
+      ).describe("Questions to ask the user (1-4 questions)")
+    },
+    hideSuccessfulCall: false,
+    autoApproveByDefault: false,
+    permissionAction: "Waiting for user to answer",
+    dynamicAction: "Waiting for user to answer",
+    fallbackAction: "Ask user",
+    reasonPhrases: ["ask user", "user input", "ask_user"]
+  },
   update_session_summary: {
     title: "Update Session Summary",
     description: "Write a narrative session summary the App shows above the progress checklist. Call at milestones, not per task: after first understanding the goal, when scope shifts significantly, when key decisions are made, or when moving to a new phase. Full rewrite each call.",
@@ -3915,9 +3984,9 @@ const HAPPY_MCP_TOOL_SPECS = {
     inputSchema: {
       goal: z.z.string().describe("What the user ultimately wants to accomplish"),
       currentFocus: z.z.string().optional().describe("Brief description of the active task or phase"),
-      keyDecisions: z.z.array(z.z.string()).optional().describe("Important choices already made this session"),
-      openQuestions: z.z.array(z.z.string()).optional().describe("Unresolved questions or pending decisions"),
-      impactScope: z.z.array(z.z.string()).optional().describe("Modules/files/areas affected by this session's work"),
+      keyDecisions: looseStringArray().optional().describe("Important choices already made this session"),
+      openQuestions: looseStringArray().optional().describe("Unresolved questions or pending decisions"),
+      impactScope: looseStringArray().optional().describe("Modules/files/areas affected by this session's work"),
       requestId: z.z.string().optional().describe(
         "Optional request identifier that runtimes may record in sessionSummaryRefresh recent history for request-level confirmation"
       )
@@ -3941,6 +4010,19 @@ HAPPY_MCP_TOOL_NAMES.filter(
 HAPPY_MCP_TOOL_NAMES.filter(
   (toolName) => HAPPY_MCP_TOOL_SPECS[toolName].hideSuccessfulCall
 );
+z.z.object({
+  askId: z.z.string(),
+  answers: z.z.record(z.z.string(), z.z.string()),
+  // When true the user explicitly declined to answer (tapped the "取消选择"
+  // / "Decline" button in the App's picker). The happy-cli handler treats
+  // this as an error so the MCP tool returns isError to Claude TUI — letting
+  // the model know it did not get an answer and should pick a fallback path
+  // (e.g. proceed with assumptions or ask differently).
+  canceled: z.z.boolean().optional()
+}).strict();
+z.z.object({
+  ok: z.z.literal(true)
+}).strict();
 
 const CodexRuntimeConfigSchema = z__namespace.object({
   model: z__namespace.string().nullish(),
@@ -4080,11 +4162,13 @@ z.z.object({
     "invalid_arguments",
     "permission_denied",
     /**
-     * SDK 0.2.119 defines the `mcp_call` control protocol type but does
-     * not expose a public runtime method on the `Query` interface. Until
-     * upstream lands a `callMcpTool()` / equivalent, the CLI handler
-     * returns this code so the App can surface an honest "waiting on
-     * SDK" state instead of masking the gap as a server error.
+     * The agent runtime has no programmatic MCP-tool invocation surface.
+     * In PTY mode the Claude TUI owns the MCP connections itself; the
+     * historical Claude Agent SDK also never exposed a runtime
+     * `callMcpTool()` on `Query`. The CLI handler returns this code so
+     * the App can surface an honest "not supported" state instead of
+     * masking the gap as a server error. Code name preserved for wire
+     * compatibility across older CLI / App builds.
      */
     "sdk_not_implemented",
     "unknown"
@@ -4427,6 +4511,21 @@ z.z.object({
   servers: z.z.record(z.z.string(), McpRegistryEntrySchema)
 });
 
+z__namespace.discriminatedUnion("type", [
+  z__namespace.object({
+    type: z__namespace.literal("success"),
+    sessionId: z__namespace.string()
+  }),
+  z__namespace.object({
+    type: z__namespace.literal("requestToApproveDirectoryCreation"),
+    directory: z__namespace.string()
+  }),
+  z__namespace.object({
+    type: z__namespace.literal("error"),
+    errorMessage: z__namespace.string()
+  })
+]);
+
 const NOT_INSTALLED = Object.freeze({ status: "not-installed" });
 const DISCONNECTED = Object.freeze({ status: "disconnected" });
 const DETECT_TIMEOUT_MS = 3e3;
@@ -4902,8 +5001,7 @@ class MachineClient {
     this.onEphemeral = opts.onEphemeral;
     this.rpcHandlerManager = new RpcHandlerManager({
       scopePrefix: opts.machine.id,
-      encryptionKey: opts.machine.encryptionKey,
-      encryptionVariant: opts.machine.encryptionVariant,
+      cipher: createCipher(opts.machine.encryptionKey, opts.machine.encryptionVariant),
       logger: (msg, data) => logger.debug(msg, data)
     });
     const workDir = opts.workingDirectory ?? process.cwd();

package/dist/index.d.cts

@@ -529,10 +529,46 @@ declare function getOrCreateMachine(config: Config, creds: Credentials, metadata
  */
 declare function listMachines(config: Config, creds: Credentials): Promise<RawMachine[]>;
 
+/**
+ * Outcome of a decrypt attempt.
+ *
+ * The low-level {@link decrypt} returns `unknown | null`, fusing "could not
+ * decrypt" (wrong key, tampered bytes, wrong variant, non-JSON plaintext)
+ * with a value that legitimately decrypted to something falsy.
+ * `DecryptResult` splits those apart: `{ ok: false }` is an authentication or
+ * parse failure, while `{ ok: true, value }` carries the recovered plaintext.
+ * Callers branch on `ok` instead of guessing from a collapsed `null`.
+ */
+type DecryptResult = {
+    ok: true;
+    value: any;
+} | {
+    ok: false;
+};
+/**
+ * A Cipher binds one AccessKey + encryption variant into a small interface.
+ *
+ * It is the single seam every transport client encrypts/decrypts through:
+ * hand it a value and get a wire-ready base64 string, or hand it a base64
+ * wire string and get a {@link DecryptResult}. The variant choice (legacy
+ * NaCl secretbox vs AES-256-GCM dataKey) and the base64 framing live behind
+ * this interface, so call sites never thread `(key, variant)` or call
+ * `encode`/`decodeBase64` themselves — a wrong-variant or wrong-key bug can
+ * only originate at the one `createCipher` call, not at the dozens of places
+ * that used to repeat the pattern.
+ */
+interface Cipher {
+    /** Encrypt a JSON-serializable value, returning a base64 wire string. */
+    encrypt(data: any): string;
+    /** Decode + decrypt a base64 wire string. Never throws. */
+    decrypt(data: string): DecryptResult;
+}
+
 /**
  * Common RPC types and interfaces for both session and machine clients.
  * Mirrors happy-cli/src/api/rpc/types.ts
  */
+
 /**
  * Generic RPC handler function type
  */
@@ -549,8 +585,7 @@ interface RpcRequest {
  */
 interface RpcHandlerConfig {
     scopePrefix: string;
-    encryptionKey: Uint8Array;
-    encryptionVariant: "legacy" | "dataKey";
+    cipher: Cipher;
     logger?: (message: string, data?: unknown) => void;
 }
 
@@ -565,8 +600,7 @@ interface RpcHandlerConfig {
 declare class RpcHandlerManager {
     private handlers;
     private readonly scopePrefix;
-    private readonly encryptionKey;
-    private readonly encryptionVariant;
+    private readonly cipher;
     private readonly logger;
     private socket;
     private reregisterInterval;
@@ -577,7 +611,18 @@ declare class RpcHandlerManager {
      */
     registerHandler<TRequest = any, TResponse = any>(method: string, handler: RpcHandler<TRequest, TResponse>): void;
     /**
-     * Handle an incoming RPC request
+     * Route a decrypted RPC call to its handler. This is the plaintext core of
+     * the manager: it knows nothing about the wire (no base64, no cipher), so it
+     * is TOTAL — an unknown method or a throwing handler both resolve to an
+     * `{ error }` value rather than rejecting. That makes it the test surface for
+     * routing behaviour, exercised without any crypto setup.
+     */
+    dispatch(method: string, params: unknown): Promise<unknown>;
+    /**
+     * Handle an incoming wire RPC request: decrypt params, dispatch in plaintext,
+     * encrypt the result. The Cipher is the only encryption seam; on a decrypt
+     * failure the handler is still dispatched with `null` params (preserving the
+     * previous behaviour where a corrupt payload decrypted to `null`).
      */
     handleRequest(request: RpcRequest): Promise<string>;
     onSocketConnect(socket: Socket): void;

package/dist/index.d.mts

@@ -529,10 +529,46 @@ declare function getOrCreateMachine(config: Config, creds: Credentials, metadata
  */
 declare function listMachines(config: Config, creds: Credentials): Promise<RawMachine[]>;
 
+/**
+ * Outcome of a decrypt attempt.
+ *
+ * The low-level {@link decrypt} returns `unknown | null`, fusing "could not
+ * decrypt" (wrong key, tampered bytes, wrong variant, non-JSON plaintext)
+ * with a value that legitimately decrypted to something falsy.
+ * `DecryptResult` splits those apart: `{ ok: false }` is an authentication or
+ * parse failure, while `{ ok: true, value }` carries the recovered plaintext.
+ * Callers branch on `ok` instead of guessing from a collapsed `null`.
+ */
+type DecryptResult = {
+    ok: true;
+    value: any;
+} | {
+    ok: false;
+};
+/**
+ * A Cipher binds one AccessKey + encryption variant into a small interface.
+ *
+ * It is the single seam every transport client encrypts/decrypts through:
+ * hand it a value and get a wire-ready base64 string, or hand it a base64
+ * wire string and get a {@link DecryptResult}. The variant choice (legacy
+ * NaCl secretbox vs AES-256-GCM dataKey) and the base64 framing live behind
+ * this interface, so call sites never thread `(key, variant)` or call
+ * `encode`/`decodeBase64` themselves — a wrong-variant or wrong-key bug can
+ * only originate at the one `createCipher` call, not at the dozens of places
+ * that used to repeat the pattern.
+ */
+interface Cipher {
+    /** Encrypt a JSON-serializable value, returning a base64 wire string. */
+    encrypt(data: any): string;
+    /** Decode + decrypt a base64 wire string. Never throws. */
+    decrypt(data: string): DecryptResult;
+}
+
 /**
  * Common RPC types and interfaces for both session and machine clients.
  * Mirrors happy-cli/src/api/rpc/types.ts
  */
+
 /**
  * Generic RPC handler function type
  */
@@ -549,8 +585,7 @@ interface RpcRequest {
  */
 interface RpcHandlerConfig {
     scopePrefix: string;
-    encryptionKey: Uint8Array;
-    encryptionVariant: "legacy" | "dataKey";
+    cipher: Cipher;
     logger?: (message: string, data?: unknown) => void;
 }
 
@@ -565,8 +600,7 @@ interface RpcHandlerConfig {
 declare class RpcHandlerManager {
     private handlers;
     private readonly scopePrefix;
-    private readonly encryptionKey;
-    private readonly encryptionVariant;
+    private readonly cipher;
     private readonly logger;
     private socket;
     private reregisterInterval;
@@ -577,7 +611,18 @@ declare class RpcHandlerManager {
      */
     registerHandler<TRequest = any, TResponse = any>(method: string, handler: RpcHandler<TRequest, TResponse>): void;
     /**
-     * Handle an incoming RPC request
+     * Route a decrypted RPC call to its handler. This is the plaintext core of
+     * the manager: it knows nothing about the wire (no base64, no cipher), so it
+     * is TOTAL — an unknown method or a throwing handler both resolve to an
+     * `{ error }` value rather than rejecting. That makes it the test surface for
+     * routing behaviour, exercised without any crypto setup.
+     */
+    dispatch(method: string, params: unknown): Promise<unknown>;
+    /**
+     * Handle an incoming wire RPC request: decrypt params, dispatch in plaintext,
+     * encrypt the result. The Cipher is the only encryption seam; on a decrypt
+     * failure the handler is still dispatched with `null` params (preserving the
+     * previous behaviour where a corrupt payload decrypted to `null`).
      */
     handleRequest(request: RpcRequest): Promise<string>;
     onSocketConnect(socket: Socket): void;

package/dist/index.mjs

@@ -19,7 +19,7 @@ import * as z from 'zod';
 import { z as z$1 } from 'zod';
 import { createServer } from 'http';
 
-var version = "0.7.1";
+var version = "0.7.2";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://s.sangreal.code.xycloud.info:2443").replace(/\/+$/, "");
@@ -137,6 +137,21 @@ function decrypt(key, variant, data) {
     return decryptWithDataKey(data, key);
   }
 }
+function createCipher(key, variant) {
+  return {
+    encrypt(data) {
+      return encodeBase64(encrypt(key, variant, data));
+    },
+    decrypt(data) {
+      try {
+        const value = decrypt(key, variant, decodeBase64(data));
+        return value === null ? { ok: false } : { ok: true, value };
+      } catch {
+        return { ok: false };
+      }
+    }
+  };
+}
 function libsodiumEncryptForPublicKey(data, recipientPublicKey) {
   const ephemeralKeyPair = tweetnacl.box.keyPair();
   const nonce = getRandomBytes(tweetnacl.box.nonceLength);
@@ -619,16 +634,14 @@ async function withBackoff(fn, options) {
 class RpcHandlerManager {
   handlers = /* @__PURE__ */ new Map();
   scopePrefix;
-  encryptionKey;
-  encryptionVariant;
+  cipher;
   logger;
   socket = null;
   reregisterInterval = null;
   fastRetryTimer = null;
   constructor(config) {
     this.scopePrefix = config.scopePrefix;
-    this.encryptionKey = config.encryptionKey;
-    this.encryptionVariant = config.encryptionVariant;
+    this.cipher = config.cipher;
     this.logger = config.logger ?? ((msg, data) => logger.debug(msg, data));
   }
   /**
@@ -642,45 +655,45 @@ class RpcHandlerManager {
     }
   }
   /**
-   * Handle an incoming RPC request
+   * Route a decrypted RPC call to its handler. This is the plaintext core of
+   * the manager: it knows nothing about the wire (no base64, no cipher), so it
+   * is TOTAL — an unknown method or a throwing handler both resolve to an
+   * `{ error }` value rather than rejecting. That makes it the test surface for
+   * routing behaviour, exercised without any crypto setup.
    */
-  async handleRequest(request) {
+  async dispatch(method, params) {
+    const handler = this.handlers.get(method);
+    if (!handler) {
+      this.logger("[RPC] [ERROR] Method not found", { method });
+      return { error: "Method not found" };
+    }
     try {
-      const handler = this.handlers.get(request.method);
-      if (!handler) {
-        this.logger("[RPC] [ERROR] Method not found", {
-          method: request.method
-        });
-        const errorResponse = { error: "Method not found" };
-        return encodeBase64(
-          encrypt(this.encryptionKey, this.encryptionVariant, errorResponse)
-        );
-      }
-      const decryptedParams = decrypt(
-        this.encryptionKey,
-        this.encryptionVariant,
-        decodeBase64(request.params)
-      );
-      this.logger("[RPC] Calling handler", { method: request.method });
-      const result = await handler(decryptedParams);
+      this.logger("[RPC] Calling handler", { method });
+      const result = await handler(params);
       this.logger("[RPC] Handler returned", {
-        method: request.method,
+        method,
         hasResult: result !== void 0
       });
-      const encryptedResponse = encodeBase64(
-        encrypt(this.encryptionKey, this.encryptionVariant, result)
-      );
-      return encryptedResponse;
+      return result;
     } catch (error) {
       this.logger("[RPC] [ERROR] Error handling request", { error });
-      const errorResponse = {
-        error: error instanceof Error ? error.message : "Unknown error"
-      };
-      return encodeBase64(
-        encrypt(this.encryptionKey, this.encryptionVariant, errorResponse)
-      );
+      return { error: error instanceof Error ? error.message : "Unknown error" };
     }
   }
+  /**
+   * Handle an incoming wire RPC request: decrypt params, dispatch in plaintext,
+   * encrypt the result. The Cipher is the only encryption seam; on a decrypt
+   * failure the handler is still dispatched with `null` params (preserving the
+   * previous behaviour where a corrupt payload decrypted to `null`).
+   */
+  async handleRequest(request) {
+    const decrypted = this.cipher.decrypt(request.params);
+    const result = await this.dispatch(
+      request.method,
+      decrypted.ok ? decrypted.value : null
+    );
+    return this.cipher.encrypt(result);
+  }
   onSocketConnect(socket) {
     this.socket = socket;
     this.registerAllHandlers(socket);
@@ -1444,8 +1457,7 @@ class SessionClient extends EventEmitter {
     });
     this.rpcHandlerManager = createRpcHandlerManager({
       scopePrefix: `session:${opts.sessionId}`,
-      encryptionKey: opts.encryptionKey,
-      encryptionVariant: opts.encryptionVariant,
+      cipher: createCipher(opts.encryptionKey, opts.encryptionVariant),
       logger: (msg, data) => logger.debug(msg, data)
     });
     if (opts.enableRpc !== false) {
@@ -2653,6 +2665,17 @@ const sessionEnvelopeSchema = z.object({
   subagent: z.string().refine((value) => cuid2Exports.isCuid(value), {
     message: "subagent must be a cuid2 value"
   }).optional(),
+  /**
+   * Optional Claude-side message UUID for this envelope. Populated by the
+   * CLI when an envelope mirrors a specific JSONL record, so the App can
+   * use it as a precise rewind/fork anchor (the CLI's `forkSession` RPC
+   * accepts this value as `upToMessageId`).
+   *
+   * Backward-compatible: older CLIs / non-Claude agents simply omit it.
+   * App code MUST treat absence as "no fork anchor available" rather than
+   * an error.
+   */
+  claudeUuid: z.string().min(1).optional(),
   ev: sessionEventSchema
 }).superRefine((envelope, ctx) => {
   if (envelope.ev.t === "service" && envelope.role !== "agent") {
@@ -3830,8 +3853,27 @@ const HAPPY_MCP_TOOL_NAMES = [
   "change_title",
   "query_project_knowledge",
   "update_progress",
-  "update_session_summary"
+  "update_session_summary",
+  "ask_user"
 ];
+const parseIfJsonString = (v) => {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+};
+const looseStringArray = () => z$1.union([z$1.array(z$1.string()), z$1.string()]).transform((v) => {
+  if (Array.isArray(v)) return v;
+  const parsed = parseIfJsonString(v);
+  if (Array.isArray(parsed)) return parsed.map(String);
+  return v.length ? [v] : [];
+});
+const looseObjectArray = (item) => z$1.union([
+  z$1.array(item),
+  z$1.string().transform(parseIfJsonString).pipe(z$1.array(item))
+]);
 const HAPPY_MCP_TOOL_SPECS = {
   change_title: {
     title: "Change Title",
@@ -3866,7 +3908,7 @@ const HAPPY_MCP_TOOL_SPECS = {
     description: 'Optional override for the App\'s Progress tab. In most cases your TodoWrite calls are auto-mirrored, so you do NOT need to call this. Use it only when you want to set extra fields the CLI hook does not capture (currentStage, blockers) or to force a new list boundary with `listId: "new"`.',
     failureLabel: "Failed to update progress",
     inputSchema: {
-      todos: z$1.array(
+      todos: looseObjectArray(
         z$1.object({
           content: z$1.string().describe("Concise description of the task"),
           status: z$1.enum(["pending", "in_progress", "completed"]).describe("Current status of the task"),
@@ -3877,7 +3919,7 @@ const HAPPY_MCP_TOOL_SPECS = {
         })
       ).describe("The full checklist \u2014 always send every item, not a delta"),
       currentStage: z$1.string().optional().describe("Optional overall stage name for the checklist"),
-      blockers: z$1.array(z$1.string()).optional().describe("Optional list of things blocking progress"),
+      blockers: looseStringArray().optional().describe("Optional list of things blocking progress"),
       listId: z$1.string().optional().describe("Target list id. Use 'new' to force a fresh list"),
       label: z$1.string().optional().describe("Short human-readable name for this task list")
     },
@@ -3888,6 +3930,33 @@ const HAPPY_MCP_TOOL_SPECS = {
     fallbackAction: "Update progress",
     reasonPhrases: ["progress update", "progress updates", "update_progress"]
   },
+  ask_user: {
+    title: "Ask User",
+    description: "Ask the user one or more questions via the App's native picker UI. Use this whenever AskUserQuestion is unavailable (the host has disabled it \u2014 common when running under happy-cli's PTY-mode Claude TUI). The input schema is identical to AskUserQuestion's. The tool blocks until the user submits answers in the App, then returns them as a JSON string keyed by question text.",
+    failureLabel: "Failed to get user answer",
+    inputSchema: {
+      questions: looseObjectArray(
+        z$1.object({
+          question: z$1.string().describe("The question to ask the user"),
+          header: z$1.string().describe("Short label/chip for the question (max ~12 chars)"),
+          options: looseObjectArray(
+            z$1.object({
+              label: z$1.string().describe("Option label"),
+              description: z$1.string().describe("Option description"),
+              preview: z$1.string().optional().describe("Optional preview content shown when the option is focused")
+            })
+          ).describe("Available choices for this question (2-4 options)"),
+          multiSelect: z$1.boolean().describe("Allow multiple selections instead of single-select")
+        })
+      ).describe("Questions to ask the user (1-4 questions)")
+    },
+    hideSuccessfulCall: false,
+    autoApproveByDefault: false,
+    permissionAction: "Waiting for user to answer",
+    dynamicAction: "Waiting for user to answer",
+    fallbackAction: "Ask user",
+    reasonPhrases: ["ask user", "user input", "ask_user"]
+  },
   update_session_summary: {
     title: "Update Session Summary",
     description: "Write a narrative session summary the App shows above the progress checklist. Call at milestones, not per task: after first understanding the goal, when scope shifts significantly, when key decisions are made, or when moving to a new phase. Full rewrite each call.",
@@ -3895,9 +3964,9 @@ const HAPPY_MCP_TOOL_SPECS = {
     inputSchema: {
       goal: z$1.string().describe("What the user ultimately wants to accomplish"),
       currentFocus: z$1.string().optional().describe("Brief description of the active task or phase"),
-      keyDecisions: z$1.array(z$1.string()).optional().describe("Important choices already made this session"),
-      openQuestions: z$1.array(z$1.string()).optional().describe("Unresolved questions or pending decisions"),
-      impactScope: z$1.array(z$1.string()).optional().describe("Modules/files/areas affected by this session's work"),
+      keyDecisions: looseStringArray().optional().describe("Important choices already made this session"),
+      openQuestions: looseStringArray().optional().describe("Unresolved questions or pending decisions"),
+      impactScope: looseStringArray().optional().describe("Modules/files/areas affected by this session's work"),
       requestId: z$1.string().optional().describe(
         "Optional request identifier that runtimes may record in sessionSummaryRefresh recent history for request-level confirmation"
       )
@@ -3921,6 +3990,19 @@ HAPPY_MCP_TOOL_NAMES.filter(
 HAPPY_MCP_TOOL_NAMES.filter(
   (toolName) => HAPPY_MCP_TOOL_SPECS[toolName].hideSuccessfulCall
 );
+z$1.object({
+  askId: z$1.string(),
+  answers: z$1.record(z$1.string(), z$1.string()),
+  // When true the user explicitly declined to answer (tapped the "取消选择"
+  // / "Decline" button in the App's picker). The happy-cli handler treats
+  // this as an error so the MCP tool returns isError to Claude TUI — letting
+  // the model know it did not get an answer and should pick a fallback path
+  // (e.g. proceed with assumptions or ask differently).
+  canceled: z$1.boolean().optional()
+}).strict();
+z$1.object({
+  ok: z$1.literal(true)
+}).strict();
 
 const CodexRuntimeConfigSchema = z.object({
   model: z.string().nullish(),
@@ -4060,11 +4142,13 @@ z$1.object({
     "invalid_arguments",
     "permission_denied",
     /**
-     * SDK 0.2.119 defines the `mcp_call` control protocol type but does
-     * not expose a public runtime method on the `Query` interface. Until
-     * upstream lands a `callMcpTool()` / equivalent, the CLI handler
-     * returns this code so the App can surface an honest "waiting on
-     * SDK" state instead of masking the gap as a server error.
+     * The agent runtime has no programmatic MCP-tool invocation surface.
+     * In PTY mode the Claude TUI owns the MCP connections itself; the
+     * historical Claude Agent SDK also never exposed a runtime
+     * `callMcpTool()` on `Query`. The CLI handler returns this code so
+     * the App can surface an honest "not supported" state instead of
+     * masking the gap as a server error. Code name preserved for wire
+     * compatibility across older CLI / App builds.
      */
     "sdk_not_implemented",
     "unknown"
@@ -4407,6 +4491,21 @@ z$1.object({
   servers: z$1.record(z$1.string(), McpRegistryEntrySchema)
 });
 
+z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("success"),
+    sessionId: z.string()
+  }),
+  z.object({
+    type: z.literal("requestToApproveDirectoryCreation"),
+    directory: z.string()
+  }),
+  z.object({
+    type: z.literal("error"),
+    errorMessage: z.string()
+  })
+]);
+
 const NOT_INSTALLED = Object.freeze({ status: "not-installed" });
 const DISCONNECTED = Object.freeze({ status: "disconnected" });
 const DETECT_TIMEOUT_MS = 3e3;
@@ -4882,8 +4981,7 @@ class MachineClient {
     this.onEphemeral = opts.onEphemeral;
     this.rpcHandlerManager = new RpcHandlerManager({
       scopePrefix: opts.machine.id,
-      encryptionKey: opts.machine.encryptionKey,
-      encryptionVariant: opts.machine.encryptionVariant,
+      cipher: createCipher(opts.machine.encryptionKey, opts.machine.encryptionVariant),
       logger: (msg, data) => logger.debug(msg, data)
     });
     const workDir = opts.workingDirectory ?? process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmmao/happy-agent",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "CLI client for controlling Happy Coder agents remotely",
   "author": "Kirill Dubovitskiy",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "release": "npx --no-install release-it"
   },
   "dependencies": {
-    "@kmmao/happy-wire": "^0.22.0",
+    "@kmmao/happy-wire": "^0.24.0",
     "axios": "^1.15.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",