very-happy-cli 0.2.177 → 0.2.179

package/dist/{deterministicJson-ChGfQEF6.cjs → deterministicJson-B8z2GPi9.cjs}

@@ -1,28 +1,126 @@
 'use strict';
 
-var index = require('./index-De8L5lFK.cjs');
+var logger = require('./logger-C1GWx3gi.cjs');
+var prompt = require('./prompt-lgF9IE82.cjs');
+var client = require('./client-ZjOsn6nZ.cjs');
+var reportProgressTool = require('./reportProgressTool-CM1JFAHg.cjs');
+var index = require('./index-C6O2vVjm.cjs');
 var promises = require('node:fs/promises');
 var node_crypto = require('node:crypto');
 var node_fs = require('node:fs');
 var path = require('node:path');
 var z = require('zod');
-var client = require('./client-DyvBTYee.cjs');
-var context = require('./context-BKbrZ55r.cjs');
-var sessionOps = require('./sessionOps-Dmt7WUUs.cjs');
-var resources = require('./resources-JDPugcDq.cjs');
-var tools = require('./tools-DDKTB5aQ.cjs');
-var reportProgressTool = require('./reportProgressTool-Du_zAK4h.cjs');
-var peerTools = require('./peerTools-DtGKWli5.cjs');
+var client$1 = require('./client-BKcK1Bi-.cjs');
+var context = require('./context-DXzU5bFM.cjs');
+var sessionOps = require('./sessionOps-S-qPBLFf.cjs');
+var resources = require('./resources-CvIlkzpP.cjs');
+var tools = require('./tools-_w52DZG6.cjs');
+var peerTools = require('./peerTools-DRQETXaz.cjs');
 var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
 var node_http = require('node:http');
 var streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
-var logger = require('./logger-LvwVeATU.cjs');
 var limits = require('./limits-C-a7gr04.cjs');
-var downloadTarget = require('./downloadTarget-Dj3WoVJa.cjs');
+var downloadTarget = require('./downloadTarget-BQJK_6oH.cjs');
 var agentGuidance = require('./agentGuidance-BtBx2xxE.cjs');
+var webPanels = require('./webPanels-FCgFKvVe.cjs');
+var persistence = require('./persistence-BegE7NPa.cjs');
+var pushNotifications = require('./pushNotifications-DaLQUyi0.cjs');
 var previewPath = require('./previewPath-B0rBdhy1.cjs');
 var crypto = require('crypto');
 
+function createProjectInjector(deps) {
+  const timeoutMs = deps.timeoutMs ?? 1500;
+  const now = deps.now ?? Date.now;
+  const presenceEvery = deps.presenceMinIntervalMs ?? 3e4;
+  const state = { projectId: null, prefixSent: false, cursor: 0, injectedVersion: null };
+  const titles = /* @__PURE__ */ new Map();
+  let lastPresenceAt = 0;
+  let lastPresenceVersion = null;
+  const label = (id) => titles.get(id) ?? id.slice(0, 8);
+  function withTimeout(p) {
+    return Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(new Error("project injection timeout")), timeoutMs).unref?.())]);
+  }
+  function reportPresence(force) {
+    const sid = deps.sessionId();
+    const meta = deps.metadata?.() ?? null;
+    const machineId = typeof meta?.machineId === "string" ? meta.machineId : null;
+    if (!sid || !machineId || !state.projectId) return;
+    const t = now();
+    if (!force && state.injectedVersion === lastPresenceVersion && t - lastPresenceAt < presenceEvery) return;
+    lastPresenceAt = t;
+    lastPresenceVersion = state.injectedVersion;
+    const entry = {
+      sessionId: sid,
+      agent: deps.agent,
+      state: "running",
+      injectedInstructionsVersion: state.injectedVersion,
+      ...typeof meta?.summary?.text === "string" ? { title: String(meta.summary.text).slice(0, 200) } : {},
+      ...typeof meta?.board?.progress === "string" ? { doing: String(meta.board.progress).slice(0, 200) } : {},
+      ...typeof meta?.worktree?.branch === "string" ? { branch: String(meta.worktree.branch).slice(0, 200) } : {},
+      ...typeof meta?.host === "string" ? { machine: String(meta.host).slice(0, 200) } : {},
+      ...Array.isArray(meta?.capabilities) ? { capabilities: meta.capabilities.filter((c) => typeof c === "string").slice(0, 32) } : {}
+    };
+    void deps.client.presence(machineId, [entry]).catch((error) => logger.logger.debug(`[projects] presence write skipped: ${String(error)}`));
+  }
+  function markDelivered(sid, ids) {
+    if (ids.length) void deps.client.delivered(sid, ids).catch((error) => logger.logger.debug(`[projects] delivered ack skipped: ${String(error)}`));
+  }
+  async function firstTurn(sid, message) {
+    const ctx = await withTimeout(deps.client.context(sid, {}, timeoutMs));
+    for (const s of ctx.sessions) if (s.title) titles.set(s.sessionId, s.title);
+    const built = prompt.buildFirstTurnPrefix(ctx, { label });
+    if (!built || !ctx.project) {
+      state.projectId = null;
+      return message;
+    }
+    state.projectId = ctx.project.id;
+    state.prefixSent = true;
+    state.cursor = ctx.asOf;
+    state.injectedVersion = built.instructionsVersion;
+    markDelivered(sid, ctx.unread.map((u) => u.id));
+    reportPresence(true);
+    return prompt.prependToMessage(message, built.prefix);
+  }
+  async function laterTurn(sid, message) {
+    const d = await withTimeout(deps.client.digest(sid, state.cursor, timeoutMs));
+    if (!d.projectId) {
+      state.projectId = null;
+      state.prefixSent = false;
+      state.injectedVersion = null;
+      return message;
+    }
+    if (d.projectId !== state.projectId) {
+      state.prefixSent = false;
+      return firstTurn(sid, message);
+    }
+    state.cursor = d.asOf;
+    if (d.instructions) state.injectedVersion = d.instructions.version;
+    markDelivered(sid, d.messages.map((m) => m.id));
+    reportPresence(!!d.instructions);
+    return prompt.prependToMessage(message, prompt.buildDigestLine(d, { label }));
+  }
+  return {
+    state: () => ({ ...state }),
+    /** A fresh agent with no memory of earlier turns (ACP backend restart, new Claude conversation) needs P again. */
+    reset() {
+      state.prefixSent = false;
+      state.cursor = 0;
+    },
+    async decorate(message) {
+      if (typeof message !== "string") return message;
+      const sid = deps.sessionId();
+      if (!sid || deps.client.isDisabled()) return message;
+      try {
+        const out = state.prefixSent ? await laterTurn(sid, message) : await firstTurn(sid, message);
+        return out;
+      } catch (error) {
+        if (!(error instanceof client.ProjectsUnsupportedError)) logger.logger.debug(`[projects] injection skipped: ${String(error)}`);
+        return message;
+      }
+    }
+  };
+}
+
 const TEAMS_ADOPT_CAPABILITY = "teams-adopt-v1";
 const TeamAdoptSchema = z.z.object({
   requestId: z.z.string().min(1).max(128),
@@ -78,7 +176,7 @@ async function retainTeam(path, input, resolvedTeamId, guidanceDelivered = false
   }
 }
 function createTeamAdoption(sessionId) {
-  const client$1 = client.createTeamsClient(sessionId);
+  const client = client$1.createTeamsClient(sessionId);
   let current;
   return (raw) => {
     const parsed = TeamAdoptSchema.safeParse(raw);
@@ -107,7 +205,7 @@ function createTeamAdoption(sessionId) {
       let intent;
       try {
         intent = await retainIntent(path, input);
-        const connected = await client$1.initialize(input, { resumeAdoption: true, expectedTeamId: intent.resolvedTeamId, onTeamResolved: (teamId) => retainTeam(path, input, teamId, intent?.guidanceDelivered) });
+        const connected = await client.initialize(input, { resumeAdoption: true, expectedTeamId: intent.resolvedTeamId, onTeamResolved: (teamId) => retainTeam(path, input, teamId, intent?.guidanceDelivered) });
         const instructions = `${resources.TEAM_SKILL}
 
 This session is now connected as the team lead. Call team_inspect to read the authoritative state before continuing the user's goal. Do not call team_create or team_join again.`;
@@ -118,7 +216,7 @@ This session is now connected as the team lead. Call team_inspect to read the au
         }
         operation.result = { status: "connected", teamId: connected.team.id, botId: connected.botId, instructions };
       } catch (error) {
-        if (error instanceof client.TeamConnectionPreflightError && intent?.fresh && !intent.resolvedTeamId) {
+        if (error instanceof client$1.TeamConnectionPreflightError && intent?.fresh && !intent.resolvedTeamId) {
           await promises.unlink(path).catch(() => {
           });
           operation.safeToChange = true;
@@ -130,6 +228,41 @@ This session is now connected as the team lead. Call team_inspect to read the au
   };
 }
 
+const REQUEST_HUMAN_TOOL_NAME = "request_human";
+const REQUEST_HUMAN_REASON_MAX = 200;
+const REQUEST_HUMAN_DEDUPE_MS = 6e4;
+const REQUEST_HUMAN_TOOL_DESCRIPTION = "Ask the user to step in when you cannot continue on your own: a captcha, 2FA code, QR scan, OAuth consent page, or a decision only they can make. Sends a push notification and marks the task board as blocked. Give a short reason (no secrets; the server can read it). If this machine declares a web panel showing what you are working in (e.g. a remote desktop or browser dashboard), pass its id as `panel` so the notification opens it. Afterwards, poll for your own completion condition (the page changed, the element disappeared) instead of waiting for a reply.";
+function createRequestHuman(deps) {
+  const now = deps.now ?? Date.now;
+  let last = null;
+  return async (rawReason, panel) => {
+    const reason = rawReason.replace(/\s+/g, " ").trim().slice(0, REQUEST_HUMAN_REASON_MAX);
+    if (!reason) return { notified: false, error: "reason must be a non-empty string" };
+    await deps.reportBlocked(reason);
+    const at = now();
+    if (last && last.reason === reason && at - last.at < REQUEST_HUMAN_DEDUPE_MS) {
+      return { notified: true, deduped: true };
+    }
+    let url = `/session/${encodeURIComponent(deps.sessionId)}`;
+    let unknownPanel;
+    if (panel) {
+      const machineId = deps.machineId();
+      const { panels } = webPanels.normalizeWebPanels(await deps.readPanels().catch(() => void 0));
+      if (machineId && panels.some((p) => p.id === panel)) url = webPanels.webPanelPath(machineId, panel);
+      else unknownPanel = panel;
+    }
+    const sent = await deps.sendAttention({ sessionId: deps.sessionId, reason, url });
+    if (sent.sent) last = { reason, at };
+    return { notified: sent.sent, url, ...unknownPanel ? { unknownPanel } : {}, ...sent.error ? { error: sent.error } : {} };
+  };
+}
+function requestHumanResultText(r) {
+  if (r.deduped) return "Already asked for this in the last minute; the board still shows it. Keep polling your completion condition.";
+  if (!r.notified) return `Could not notify the user: ${r.error ?? "unknown error"}. The task board is marked blocked.`;
+  const panelNote = r.unknownPanel ? ` (panel "${r.unknownPanel}" is not declared on this machine, so the notification opens the session instead)` : "";
+  return `Notified the user${panelNote}. This does not mean they have seen it. Poll your own completion condition (URL changed, element gone) instead of waiting for a reply.`;
+}
+
 function createMcpServer(handlers, options, sessionId, client) {
   const mcp = new mcp_js.McpServer({
     name: "Very Happy Tools",
@@ -138,6 +271,7 @@ function createMcpServer(handlers, options, sessionId, client) {
   tools.registerTeamsTools(mcp, sessionId);
   reportProgressTool.registerAutomationTools(mcp);
   if (client) peerTools.registerSessionPeerTools(mcp, peerTools.createSessionPeerToolExecutor(client));
+  if (client) reportProgressTool.registerProjectTools(mcp, reportProgressTool.createProjectToolExecutor(() => client.sessionId));
   mcp.registerTool("change_title", {
     description: "Change the title of the current chat session",
     title: "Change Chat Title",
@@ -224,6 +358,18 @@ function createMcpServer(handlers, options, sessionId, client) {
       isError: true
     };
   });
+  mcp.registerTool(REQUEST_HUMAN_TOOL_NAME, {
+    description: REQUEST_HUMAN_TOOL_DESCRIPTION,
+    title: "Ask the user to step in",
+    inputSchema: {
+      reason: z.z.string().describe("What you need from the user, one short line (no secrets)"),
+      panel: z.z.string().optional().describe("Id of this machine's web panel that shows what you are working in (from ~/.happy/settings.json webPanels)")
+    }
+  }, async (args) => {
+    const response = await handlers.requestHuman(String(args.reason ?? ""), args.panel);
+    logger.logger.debug("[happyMCP] request_human response:", response);
+    return { content: [{ type: "text", text: requestHumanResultText(response) }], isError: response.error === "reason must be a non-empty string" };
+  });
   reportProgressTool.registerReportProgressTool(mcp, async (args) => {
     const response = await handlers.reportProgress(String(args.progress ?? ""), reportProgressTool.normalizeAttention(args.attention), reportProgressTool.normalizePhase(args.phase));
     logger.logger.debug("[happyMCP] report_progress response:", response);
@@ -321,10 +467,66 @@ async function startHappyServer(client, options) {
       } catch (error) {
         return { delivered: false, truncated: false, totalBytes: 0, error: String(error) };
       }
-    }
+    },
+    requestHuman: createRequestHuman({
+      sessionId: client.sessionId,
+      machineId: () => client.getMetadata()?.machineId,
+      readPanels: async () => (await persistence.readSettings()).webPanels,
+      // Same board write (and attention-change throttle bypass) as report_progress.
+      reportBlocked: (reason) => handlers.reportProgress(reason, "blocked"),
+      sendAttention: (input) => options?.push ? options.push.sendAttention({ ...input, sessionTitle: pushNotifications.getSessionNotificationBody(client.getMetadata()) }) : Promise.resolve({ sent: false, error: "push is not available in this runner" })
+    })
   };
   const contextPath = "/runtime-context/" + node_crypto.randomUUID();
+  const steerPath = "/runtime-steer/" + node_crypto.randomUUID();
   const server = node_http.createServer(async (req, res) => {
+    if (req.url?.startsWith("/runtime-steer/")) {
+      const steer = options?.piSteer;
+      if (!steer || req.headers.origin) {
+        res.writeHead(403).end();
+        return;
+      }
+      if (req.method === "GET" && req.url === steerPath) {
+        const gone = new AbortController();
+        res.on("close", () => gone.abort());
+        const item = await steer.take(25e3, gone.signal);
+        if (res.writableEnded || gone.signal.aborted) {
+          return;
+        }
+        if (!item) {
+          res.writeHead(204).end();
+          return;
+        }
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(item));
+        return;
+      }
+      if (req.method === "POST" && (req.url === steerPath + "/hello" || req.url === steerPath + "/ack")) {
+        let body = "";
+        for await (const chunk of req) {
+          body += chunk.toString();
+          if (Buffer.byteLength(body) > 1024) {
+            res.writeHead(413).end();
+            return;
+          }
+        }
+        if (req.url.endsWith("/hello")) {
+          steer.hello();
+          res.writeHead(204).end();
+          return;
+        }
+        try {
+          const ack = JSON.parse(body);
+          if (typeof ack.id !== "number") throw new Error("id");
+          steer.ack(ack.id, ack.delivered === true);
+          res.writeHead(204).end();
+        } catch {
+          res.writeHead(400).end();
+        }
+        return;
+      }
+      res.writeHead(403).end();
+      return;
+    }
     if (req.url?.startsWith("/runtime-context/")) {
       if (!options?.onContextUsage || req.url !== contextPath || req.method !== "POST" || req.headers.origin) {
         res.writeHead(403).end();
@@ -381,14 +583,17 @@ async function startHappyServer(client, options) {
   return {
     url: baseUrl.toString(),
     contextUsageUrl: options?.onContextUsage ? new URL(contextPath, baseUrl).toString() : void 0,
+    steerUrl: options?.piSteer ? new URL(steerPath, baseUrl).toString() : void 0,
     toolNames: [
       "change_title",
       limits.CLIPBOARD_TOOL_NAME,
       agentGuidance.PREVIEW_TOOL_NAME,
       agentGuidance.REPORT_PROGRESS_TOOL_NAME,
+      REQUEST_HUMAN_TOOL_NAME,
       ...tools.TEAM_TOOL_NAMES,
       ...reportProgressTool.AUTOMATION_TOOL_NAMES,
       ...peerTools.SESSION_PEER_TOOL_NAMES,
+      ...reportProgressTool.PROJECT_TOOL_NAMES,
       ...options?.assistant && !process.env.VH_TEAM_SCOPE_FILE ? downloadTarget.ASSISTANT_TOOL_NAMES : []
     ],
     stop: () => {
@@ -485,5 +690,6 @@ function hashObject(obj, options, encoding = "hex") {
   return crypto.createHash("sha256").update(jsonString).digest(encoding);
 }
 
+exports.createProjectInjector = createProjectInjector;
 exports.hashObject = hashObject;
 exports.startHappyServer = startHappyServer;

package/dist/{deterministicJson-BkQETt8_.mjs → deterministicJson-D_whDMFd.mjs}

@@ -1,26 +1,124 @@
-import { C as ContextUsageSchema } from './index-DMy3OCBe.mjs';
+import { l as logger } from './logger-BtVhHnD8.mjs';
+import { p as prependToMessage, b as buildDigestLine, a as buildFirstTurnPrefix } from './prompt-BOouDaTM.mjs';
+import { P as ProjectsUnsupportedError } from './client-BhoEBnuN.mjs';
+import { c as createSelfReportState, A as AUTOMATION_TOOL_NAMES, P as PROJECT_TOOL_NAMES, r as registerAutomationTools, a as registerProjectTools, d as createProjectToolExecutor, b as registerReportProgressTool, n as normalizeAttention, e as normalizePhase, f as normalizeProgress, s as shouldAcceptSelfReport } from './reportProgressTool-gHItlSzz.mjs';
+import { C as ContextUsageSchema } from './index-DPOa4NhL.mjs';
 import { unlink, mkdir, open, rename } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { dirname } from 'node:path';
 import { z } from 'zod';
-import { T as TeamConnectionPreflightError, c as createTeamsClient } from './client-BPMWutfs.mjs';
-import { t as teamScopePath } from './context-CCRpVXFo.mjs';
-import { g as waitForSessionKey, e as sendUserMessage } from './sessionOps-CdgbEJgf.mjs';
-import { T as TEAM_SKILL } from './resources-BdFBQi8r.mjs';
-import { T as TEAM_TOOL_NAMES, r as registerTeamsTools } from './tools-BrM3bZW5.mjs';
-import { c as createSelfReportState, A as AUTOMATION_TOOL_NAMES, r as registerAutomationTools, a as registerReportProgressTool, n as normalizeAttention, b as normalizePhase, d as normalizeProgress, s as shouldAcceptSelfReport } from './reportProgressTool-B203EZCR.mjs';
-import { S as SESSION_PEER_TOOL_NAMES, r as registerSessionPeerTools, a as createSessionPeerToolExecutor } from './peerTools-CxmrKnfV.mjs';
+import { T as TeamConnectionPreflightError, c as createTeamsClient } from './client-DuTDwWSQ.mjs';
+import { t as teamScopePath } from './context-DploEcoN.mjs';
+import { g as waitForSessionKey, e as sendUserMessage } from './sessionOps-BIGgRube.mjs';
+import { T as TEAM_SKILL } from './resources-y9jfyO-_.mjs';
+import { T as TEAM_TOOL_NAMES, r as registerTeamsTools } from './tools-D8-PnZEG.mjs';
+import { S as SESSION_PEER_TOOL_NAMES, r as registerSessionPeerTools, a as createSessionPeerToolExecutor } from './peerTools-CWKzcQ7u.mjs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { l as logger } from './logger-13cBr_ew.mjs';
 import { C as CLIPBOARD_TOOL_NAME, a as CLIPBOARD_TOOL_TITLE, b as CLIPBOARD_TOOL_DESCRIPTION, c as CLIPBOARD_MAX_BYTES } from './limits-DIo7rEBR.mjs';
-import { A as ASSISTANT_TOOL_NAMES, a as registerAssistantTools, c as checkDownloadTarget } from './downloadTarget-ByXzbDK4.mjs';
+import { A as ASSISTANT_TOOL_NAMES, a as registerAssistantTools, c as checkDownloadTarget } from './downloadTarget-BoNwTIH_.mjs';
 import { P as PREVIEW_TOOL_NAME, R as REPORT_PROGRESS_TOOL_NAME, a as PREVIEW_TOOL_TITLE, b as PREVIEW_TOOL_DESCRIPTION, c as PREVIEW_DOWNLOAD_PARAM_DESCRIPTION } from './agentGuidance-BDYt2Qy2.mjs';
+import { n as normalizeWebPanels, w as webPanelPath } from './webPanels-B2_C2-3g.mjs';
+import { r as readSettings } from './persistence-Cr-wutZ4.mjs';
+import { g as getSessionNotificationBody } from './pushNotifications-BdFjDjQe.mjs';
 import { c as checkPreviewPath } from './previewPath-CXN4Vag0.mjs';
 import { createHash } from 'crypto';
 
+function createProjectInjector(deps) {
+  const timeoutMs = deps.timeoutMs ?? 1500;
+  const now = deps.now ?? Date.now;
+  const presenceEvery = deps.presenceMinIntervalMs ?? 3e4;
+  const state = { projectId: null, prefixSent: false, cursor: 0, injectedVersion: null };
+  const titles = /* @__PURE__ */ new Map();
+  let lastPresenceAt = 0;
+  let lastPresenceVersion = null;
+  const label = (id) => titles.get(id) ?? id.slice(0, 8);
+  function withTimeout(p) {
+    return Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(new Error("project injection timeout")), timeoutMs).unref?.())]);
+  }
+  function reportPresence(force) {
+    const sid = deps.sessionId();
+    const meta = deps.metadata?.() ?? null;
+    const machineId = typeof meta?.machineId === "string" ? meta.machineId : null;
+    if (!sid || !machineId || !state.projectId) return;
+    const t = now();
+    if (!force && state.injectedVersion === lastPresenceVersion && t - lastPresenceAt < presenceEvery) return;
+    lastPresenceAt = t;
+    lastPresenceVersion = state.injectedVersion;
+    const entry = {
+      sessionId: sid,
+      agent: deps.agent,
+      state: "running",
+      injectedInstructionsVersion: state.injectedVersion,
+      ...typeof meta?.summary?.text === "string" ? { title: String(meta.summary.text).slice(0, 200) } : {},
+      ...typeof meta?.board?.progress === "string" ? { doing: String(meta.board.progress).slice(0, 200) } : {},
+      ...typeof meta?.worktree?.branch === "string" ? { branch: String(meta.worktree.branch).slice(0, 200) } : {},
+      ...typeof meta?.host === "string" ? { machine: String(meta.host).slice(0, 200) } : {},
+      ...Array.isArray(meta?.capabilities) ? { capabilities: meta.capabilities.filter((c) => typeof c === "string").slice(0, 32) } : {}
+    };
+    void deps.client.presence(machineId, [entry]).catch((error) => logger.debug(`[projects] presence write skipped: ${String(error)}`));
+  }
+  function markDelivered(sid, ids) {
+    if (ids.length) void deps.client.delivered(sid, ids).catch((error) => logger.debug(`[projects] delivered ack skipped: ${String(error)}`));
+  }
+  async function firstTurn(sid, message) {
+    const ctx = await withTimeout(deps.client.context(sid, {}, timeoutMs));
+    for (const s of ctx.sessions) if (s.title) titles.set(s.sessionId, s.title);
+    const built = buildFirstTurnPrefix(ctx, { label });
+    if (!built || !ctx.project) {
+      state.projectId = null;
+      return message;
+    }
+    state.projectId = ctx.project.id;
+    state.prefixSent = true;
+    state.cursor = ctx.asOf;
+    state.injectedVersion = built.instructionsVersion;
+    markDelivered(sid, ctx.unread.map((u) => u.id));
+    reportPresence(true);
+    return prependToMessage(message, built.prefix);
+  }
+  async function laterTurn(sid, message) {
+    const d = await withTimeout(deps.client.digest(sid, state.cursor, timeoutMs));
+    if (!d.projectId) {
+      state.projectId = null;
+      state.prefixSent = false;
+      state.injectedVersion = null;
+      return message;
+    }
+    if (d.projectId !== state.projectId) {
+      state.prefixSent = false;
+      return firstTurn(sid, message);
+    }
+    state.cursor = d.asOf;
+    if (d.instructions) state.injectedVersion = d.instructions.version;
+    markDelivered(sid, d.messages.map((m) => m.id));
+    reportPresence(!!d.instructions);
+    return prependToMessage(message, buildDigestLine(d, { label }));
+  }
+  return {
+    state: () => ({ ...state }),
+    /** A fresh agent with no memory of earlier turns (ACP backend restart, new Claude conversation) needs P again. */
+    reset() {
+      state.prefixSent = false;
+      state.cursor = 0;
+    },
+    async decorate(message) {
+      if (typeof message !== "string") return message;
+      const sid = deps.sessionId();
+      if (!sid || deps.client.isDisabled()) return message;
+      try {
+        const out = state.prefixSent ? await laterTurn(sid, message) : await firstTurn(sid, message);
+        return out;
+      } catch (error) {
+        if (!(error instanceof ProjectsUnsupportedError)) logger.debug(`[projects] injection skipped: ${String(error)}`);
+        return message;
+      }
+    }
+  };
+}
+
 const TEAMS_ADOPT_CAPABILITY = "teams-adopt-v1";
 const TeamAdoptSchema = z.object({
   requestId: z.string().min(1).max(128),
@@ -128,6 +226,41 @@ This session is now connected as the team lead. Call team_inspect to read the au
   };
 }
 
+const REQUEST_HUMAN_TOOL_NAME = "request_human";
+const REQUEST_HUMAN_REASON_MAX = 200;
+const REQUEST_HUMAN_DEDUPE_MS = 6e4;
+const REQUEST_HUMAN_TOOL_DESCRIPTION = "Ask the user to step in when you cannot continue on your own: a captcha, 2FA code, QR scan, OAuth consent page, or a decision only they can make. Sends a push notification and marks the task board as blocked. Give a short reason (no secrets; the server can read it). If this machine declares a web panel showing what you are working in (e.g. a remote desktop or browser dashboard), pass its id as `panel` so the notification opens it. Afterwards, poll for your own completion condition (the page changed, the element disappeared) instead of waiting for a reply.";
+function createRequestHuman(deps) {
+  const now = deps.now ?? Date.now;
+  let last = null;
+  return async (rawReason, panel) => {
+    const reason = rawReason.replace(/\s+/g, " ").trim().slice(0, REQUEST_HUMAN_REASON_MAX);
+    if (!reason) return { notified: false, error: "reason must be a non-empty string" };
+    await deps.reportBlocked(reason);
+    const at = now();
+    if (last && last.reason === reason && at - last.at < REQUEST_HUMAN_DEDUPE_MS) {
+      return { notified: true, deduped: true };
+    }
+    let url = `/session/${encodeURIComponent(deps.sessionId)}`;
+    let unknownPanel;
+    if (panel) {
+      const machineId = deps.machineId();
+      const { panels } = normalizeWebPanels(await deps.readPanels().catch(() => void 0));
+      if (machineId && panels.some((p) => p.id === panel)) url = webPanelPath(machineId, panel);
+      else unknownPanel = panel;
+    }
+    const sent = await deps.sendAttention({ sessionId: deps.sessionId, reason, url });
+    if (sent.sent) last = { reason, at };
+    return { notified: sent.sent, url, ...unknownPanel ? { unknownPanel } : {}, ...sent.error ? { error: sent.error } : {} };
+  };
+}
+function requestHumanResultText(r) {
+  if (r.deduped) return "Already asked for this in the last minute; the board still shows it. Keep polling your completion condition.";
+  if (!r.notified) return `Could not notify the user: ${r.error ?? "unknown error"}. The task board is marked blocked.`;
+  const panelNote = r.unknownPanel ? ` (panel "${r.unknownPanel}" is not declared on this machine, so the notification opens the session instead)` : "";
+  return `Notified the user${panelNote}. This does not mean they have seen it. Poll your own completion condition (URL changed, element gone) instead of waiting for a reply.`;
+}
+
 function createMcpServer(handlers, options, sessionId, client) {
   const mcp = new McpServer({
     name: "Very Happy Tools",
@@ -136,6 +269,7 @@ function createMcpServer(handlers, options, sessionId, client) {
   registerTeamsTools(mcp, sessionId);
   registerAutomationTools(mcp);
   if (client) registerSessionPeerTools(mcp, createSessionPeerToolExecutor(client));
+  if (client) registerProjectTools(mcp, createProjectToolExecutor(() => client.sessionId));
   mcp.registerTool("change_title", {
     description: "Change the title of the current chat session",
     title: "Change Chat Title",
@@ -222,6 +356,18 @@ function createMcpServer(handlers, options, sessionId, client) {
       isError: true
     };
   });
+  mcp.registerTool(REQUEST_HUMAN_TOOL_NAME, {
+    description: REQUEST_HUMAN_TOOL_DESCRIPTION,
+    title: "Ask the user to step in",
+    inputSchema: {
+      reason: z.string().describe("What you need from the user, one short line (no secrets)"),
+      panel: z.string().optional().describe("Id of this machine's web panel that shows what you are working in (from ~/.happy/settings.json webPanels)")
+    }
+  }, async (args) => {
+    const response = await handlers.requestHuman(String(args.reason ?? ""), args.panel);
+    logger.debug("[happyMCP] request_human response:", response);
+    return { content: [{ type: "text", text: requestHumanResultText(response) }], isError: response.error === "reason must be a non-empty string" };
+  });
   registerReportProgressTool(mcp, async (args) => {
     const response = await handlers.reportProgress(String(args.progress ?? ""), normalizeAttention(args.attention), normalizePhase(args.phase));
     logger.debug("[happyMCP] report_progress response:", response);
@@ -319,10 +465,66 @@ async function startHappyServer(client, options) {
       } catch (error) {
         return { delivered: false, truncated: false, totalBytes: 0, error: String(error) };
       }
-    }
+    },
+    requestHuman: createRequestHuman({
+      sessionId: client.sessionId,
+      machineId: () => client.getMetadata()?.machineId,
+      readPanels: async () => (await readSettings()).webPanels,
+      // Same board write (and attention-change throttle bypass) as report_progress.
+      reportBlocked: (reason) => handlers.reportProgress(reason, "blocked"),
+      sendAttention: (input) => options?.push ? options.push.sendAttention({ ...input, sessionTitle: getSessionNotificationBody(client.getMetadata()) }) : Promise.resolve({ sent: false, error: "push is not available in this runner" })
+    })
   };
   const contextPath = "/runtime-context/" + randomUUID();
+  const steerPath = "/runtime-steer/" + randomUUID();
   const server = createServer(async (req, res) => {
+    if (req.url?.startsWith("/runtime-steer/")) {
+      const steer = options?.piSteer;
+      if (!steer || req.headers.origin) {
+        res.writeHead(403).end();
+        return;
+      }
+      if (req.method === "GET" && req.url === steerPath) {
+        const gone = new AbortController();
+        res.on("close", () => gone.abort());
+        const item = await steer.take(25e3, gone.signal);
+        if (res.writableEnded || gone.signal.aborted) {
+          return;
+        }
+        if (!item) {
+          res.writeHead(204).end();
+          return;
+        }
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(item));
+        return;
+      }
+      if (req.method === "POST" && (req.url === steerPath + "/hello" || req.url === steerPath + "/ack")) {
+        let body = "";
+        for await (const chunk of req) {
+          body += chunk.toString();
+          if (Buffer.byteLength(body) > 1024) {
+            res.writeHead(413).end();
+            return;
+          }
+        }
+        if (req.url.endsWith("/hello")) {
+          steer.hello();
+          res.writeHead(204).end();
+          return;
+        }
+        try {
+          const ack = JSON.parse(body);
+          if (typeof ack.id !== "number") throw new Error("id");
+          steer.ack(ack.id, ack.delivered === true);
+          res.writeHead(204).end();
+        } catch {
+          res.writeHead(400).end();
+        }
+        return;
+      }
+      res.writeHead(403).end();
+      return;
+    }
     if (req.url?.startsWith("/runtime-context/")) {
       if (!options?.onContextUsage || req.url !== contextPath || req.method !== "POST" || req.headers.origin) {
         res.writeHead(403).end();
@@ -379,14 +581,17 @@ async function startHappyServer(client, options) {
   return {
     url: baseUrl.toString(),
     contextUsageUrl: options?.onContextUsage ? new URL(contextPath, baseUrl).toString() : void 0,
+    steerUrl: options?.piSteer ? new URL(steerPath, baseUrl).toString() : void 0,
     toolNames: [
       "change_title",
       CLIPBOARD_TOOL_NAME,
       PREVIEW_TOOL_NAME,
       REPORT_PROGRESS_TOOL_NAME,
+      REQUEST_HUMAN_TOOL_NAME,
       ...TEAM_TOOL_NAMES,
       ...AUTOMATION_TOOL_NAMES,
       ...SESSION_PEER_TOOL_NAMES,
+      ...PROJECT_TOOL_NAMES,
       ...options?.assistant && !process.env.VH_TEAM_SCOPE_FILE ? ASSISTANT_TOOL_NAMES : []
     ],
     stop: () => {
@@ -483,4 +688,4 @@ function hashObject(obj, options, encoding = "hex") {
   return createHash("sha256").update(jsonString).digest(encoding);
 }
 
-export { hashObject as h, startHappyServer as s };
+export { createProjectInjector as c, hashObject as h, startHappyServer as s };

package/dist/{doctor-BsN3JZJn.cjs → doctor-Br1Kcy2J.cjs}

@@ -1,19 +1,19 @@
 'use strict';
 
 var chalk = require('chalk');
-var configuration = require('./configuration-DZPy0T9Z.cjs');
-var persistence = require('./persistence-DXbKOHxl.cjs');
-var controlClient = require('./controlClient-SX8gSza2.cjs');
+var configuration = require('./configuration-CMHZnp6G.cjs');
+var persistence = require('./persistence-BegE7NPa.cjs');
+var controlClient = require('./controlClient-C-5qCt8W.cjs');
 var doctor$1 = require('./doctor-u46qYYKX.cjs');
 var node_fs = require('node:fs');
 var path = require('node:path');
 var projectPath = require('./projectPath-ChLhdOyt.cjs');
-var _package = require('./package-Ch9WGDV_.cjs');
+var _package = require('./package-SgqTYsjn.cjs');
 var doctorReadiness = require('./doctorReadiness-BCZGcN0a.cjs');
-var authRelay = require('./authRelay-BdYkC1Po.cjs');
+var authRelay = require('./authRelay-Dy1qU9td.cjs');
 var cliUpdate = require('./cliUpdate-DsKXPFYp.cjs');
 var node_child_process = require('node:child_process');
-var piRunnerArgs = require('./piRunnerArgs-BVRZe2AR.cjs');
+var piRunnerArgs = require('./piRunnerArgs-Cs-378Vz.cjs');
 
 function shareSafeProcessLine(process2) {
   return `PID ${process2.pid}: command arguments hidden for privacy`;
@@ -313,8 +313,8 @@ ${typeLabels[type] || type}:`));
   }
   console.log(chalk.gray("  An external claude command is only needed for native terminal/mirror use."));
   try {
-    const { resolveAgentHomesForCli } = await Promise.resolve().then(function () { return require('./agentHome-BdTXEUPe.cjs'); });
-    const { describeAgentHome } = await Promise.resolve().then(function () { return require('./index-CrR4JISa.cjs'); });
+    const { resolveAgentHomesForCli } = await Promise.resolve().then(function () { return require('./agentHome-BWcz8mz0.cjs'); });
+    const { describeAgentHome } = await Promise.resolve().then(function () { return require('./index-B0UjHlAe.cjs'); });
     const homes = await resolveAgentHomesForCli();
     console.log(chalk.green(`\u2713 Claude config dir: ${describeAgentHome(homes.claudeConfigDir)}`));
     console.log(chalk.green(`\u2713 Codex home: ${describeAgentHome(homes.codexHome)}`));