offhands 0.1.5 → 0.1.9

package/approval-mcp.mjs

@@ -1,15 +1,37 @@
-// offhand approval MCP server (plain JS, zero deps — spawned BY claude).
-// Newline-delimited JSON-RPC 2.0 over stdio. Exposes one tool,
-// `approval_prompt`, named via --permission-prompt-tool
-// mcp__offhand__approval_prompt. Each call is forwarded to the daemon's
-// local HTTP endpoint (OFFHAND_APPROVAL_URL) which long-polls the phone's
-// verdict, then this returns allow/deny to claude.
+// offhand MCP toolkit (plain JS, zero deps — spawned BY the agent CLI).
+// Newline-delimited JSON-RPC 2.0 over stdio. Started life as a single tool
+// (`approval_prompt`, still the one named via --permission-prompt-tool
+// mcp__offhand__approval_prompt) — Execution Plan 5 added `offhand_status_update`
+// alongside it, and a later pass added `offhand_send_file`, since a CLI wired
+// in via --mcp-config sees every tool this server exposes, not just the one
+// used as the permission hook. Each call is forwarded to a daemon-local HTTP
+// endpoint (localhost-only by construction) or, for send_file, done directly
+// against the local filesystem once (if wired) that endpoint approves it;
+// the daemon does the real work, this file is just the wire adapter between
+// JSON-RPC-over-stdio and plain HTTP.
 
 import { createInterface } from 'node:readline';
+import { copyFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, parse, resolve } from 'node:path';
 
 const APPROVAL_URL = process.env.OFFHAND_APPROVAL_URL ?? 'http://127.0.0.1:4317/approval';
+const STATUS_URL = process.env.OFFHAND_STATUS_URL ?? 'http://127.0.0.1:4317/status';
+const SESSION_ID = process.env.OFFHAND_SESSION_ID ?? '';
+// Derived from STATUS_URL rather than a fourth env var every runner would
+// need to remember to set — same daemon, same port, whatever STATUS_URL
+// already points at (set for both Claude Code and OpenCode today).
+const CONTEXT_URL = process.env.OFFHAND_CONTEXT_URL ?? STATUS_URL.replace(/\/status$/, '/context');
+// Whether a runner actually wired offhand's own approval broker in for this
+// run (only Claude Code does today — see claude-code.ts). Where it isn't,
+// the CLI's own permission model is already the only gate on every other
+// tool call too (OpenCode routes its own tool approvals separately — see
+// opencode-cli.ts's statusOnlyMcpConfigContent doc comment), so send_file
+// stays consistent with that rather than inventing a broker call nothing
+// is listening on.
+const HAS_APPROVAL_CHANNEL = process.env.OFFHAND_APPROVAL_URL !== undefined;
 
-const TOOL = {
+const APPROVAL_TOOL = {
   name: 'approval_prompt',
   description: 'Forwards a permission request to the offhand phone client and waits for the verdict.',
   inputSchema: {
@@ -23,6 +45,92 @@ const TOOL = {
   },
 };
 
+const STATUS_TOOL = {
+  name: 'offhand_status_update',
+  description:
+    "Sends a short plain-English progress note to the person's phone, outside the normal response — use it at meaningful checkpoints (starting a long step, hitting a snag, finishing a phase) so they see progress without waiting for the whole run to finish.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'A short, human-readable status note.' },
+    },
+    required: ['text'],
+  },
+};
+
+const SEND_FILE_TOOL = {
+  name: 'offhand_send_file',
+  description:
+    "Sends a file already on this machine's disk (a screenshot, a generated video, a log, a diff export) to the person's phone. Give an absolute path to a file that exists right now.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Absolute path to the file to send.' },
+    },
+    required: ['path'],
+  },
+};
+
+const CONTEXT_TOOL = {
+  name: 'offhand_context',
+  description:
+    "Looks up locally-relevant repository context (dirty files, recently-changed files, files matching your search terms) before you spend turns rediscovering the same things. This is a best-effort local search, not authoritative — it may be incomplete or wrong. Use it as a starting point, and keep exploring the repository yourself wherever it looks warranted.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'What you are looking for or working on right now (e.g. "authentication middleware", "the task at hand").' },
+    },
+    required: ['query'],
+  },
+};
+
+const TOOLS = [APPROVAL_TOOL, STATUS_TOOL, SEND_FILE_TOOL, CONTEXT_TOOL];
+
+/** Duplicated from drop.ts on purpose — this file ships standalone (see the
+ * HAS_APPROVAL_CHANNEL comment above), so it can't import the bundled
+ * daemon's TS modules. Keep in sync by hand if drop.ts's naming rules change. */
+function safeDropName(input) {
+  const base = basename(input).replace(/[<>:"/\\|?*\x00-\x1F]/g, '_').replace(/[. ]+$/g, '').trim();
+  if (!base || base === '.' || base === '..') return 'drop';
+  return base;
+}
+
+function dedupeDropName(desiredName, existingNames) {
+  const safe = safeDropName(desiredName);
+  const existing = new Set(existingNames.map((n) => n.toLowerCase()));
+  if (!existing.has(safe.toLowerCase())) return safe;
+  const parsed = parse(safe);
+  const stem = parsed.name || 'drop';
+  const ext = parsed.ext;
+  for (let i = 1; ; i++) {
+    const candidate = `${stem}-${i}${ext}`;
+    if (!existing.has(candidate.toLowerCase())) return candidate;
+  }
+}
+
+function dropOutboxDir() {
+  const home = process.env.OFFHAND_HOME ?? join(homedir(), '.offhand');
+  return join(home, 'drop-outbox');
+}
+
+/** Copies sourcePath into the daemon's drop outbox — the same directory the
+ * daemon's own file watcher polls for `offhand drop <file>` — so the actual
+ * relay send is handled by code that already exists and is already tested. */
+function queueFileForPhone(sourcePath) {
+  const source = resolve(sourcePath);
+  const st = statSync(source); // throws ENOENT if missing — surfaces as a normal tool error below
+  if (!st.isFile()) throw new Error(`not a file: ${sourcePath}`);
+  const outbox = dropOutboxDir();
+  mkdirSync(outbox, { recursive: true });
+  let existing = [];
+  try {
+    existing = readdirSync(outbox);
+  } catch {}
+  const dest = join(outbox, dedupeDropName(basename(source), existing));
+  copyFileSync(source, dest);
+  return dest;
+}
+
 function send(msg) {
   process.stdout.write(JSON.stringify(msg) + '\n');
 }
@@ -45,6 +153,24 @@ async function callDaemon(args) {
   return res.json();
 }
 
+async function sendStatus(text) {
+  await fetch(STATUS_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ sessionId: SESSION_ID, text }),
+  });
+}
+
+async function fetchContext(query) {
+  const res = await fetch(CONTEXT_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ sessionId: SESSION_ID, query }),
+  });
+  if (!res.ok) return { block: null, filesSelected: 0 };
+  return res.json();
+}
+
 const rl = createInterface({ input: process.stdin });
 rl.on('line', (line) => {
   if (!line.trim()) return;
@@ -66,14 +192,67 @@ async function handle(msg) {
       reply(id, {
         protocolVersion: params?.protocolVersion ?? '2024-11-05',
         capabilities: { tools: {} },
-        serverInfo: { name: 'offhand-approvals', version: '0.0.1' },
+        serverInfo: { name: 'offhand', version: '0.1.0' },
       });
       return;
     case 'tools/list':
-      reply(id, { tools: [TOOL] });
+      reply(id, { tools: TOOLS });
       return;
     case 'tools/call': {
-      if (params?.name !== TOOL.name) {
+      if (params?.name === SEND_FILE_TOOL.name) {
+        const path = String(params.arguments?.path ?? '').trim();
+        try {
+          if (!path) throw new Error('no path given');
+          if (HAS_APPROVAL_CHANNEL) {
+            const verdict = await callDaemon({ tool_name: SEND_FILE_TOOL.name, input: { path } });
+            if (!verdict.approve) {
+              reply(id, { content: [{ type: 'text', text: verdict.message ?? 'denied from phone' }] });
+              return;
+            }
+          }
+          const dest = queueFileForPhone(path);
+          reply(id, { content: [{ type: 'text', text: `queued ${basename(dest)} for the phone` }] });
+        } catch (e) {
+          reply(id, { content: [{ type: 'text', text: `could not send file: ${e?.message ?? e}` }] });
+        }
+        return;
+      }
+      if (params?.name === STATUS_TOOL.name) {
+        const text = String(params.arguments?.text ?? '').trim();
+        try {
+          if (text) await sendStatus(text);
+          reply(id, { content: [{ type: 'text', text: text ? 'sent' : 'nothing to send (empty text)' }] });
+        } catch (e) {
+          // A dropped status note is never fatal to the run — it's a nice-
+          // to-have channel, not a control one like approvals.
+          reply(id, { content: [{ type: 'text', text: `status channel error: ${e?.message ?? e}` }] });
+        }
+        return;
+      }
+      if (params?.name === CONTEXT_TOOL.name) {
+        const query = String(params.arguments?.query ?? '').trim();
+        try {
+          if (!query) throw new Error('no query given');
+          const { block, filesSelected } = await fetchContext(query);
+          reply(id, {
+            content: [
+              {
+                type: 'text',
+                text:
+                  block && filesSelected > 0
+                    ? block
+                    : 'No local repository signal found for this query — proceed with your own discovery as usual.',
+              },
+            ],
+          });
+        } catch (e) {
+          // Same posture as offhand_status_update: a dropped lookup is
+          // never fatal — the agent just falls back to its own discovery.
+          reply(id, { content: [{ type: 'text', text: `context lookup unavailable: ${e?.message ?? e}` }] });
+        }
+        return;
+      }
+      if (params?.name !== APPROVAL_TOOL.name) {
         replyError(id, -32602, `unknown tool: ${params?.name}`);
         return;
       }