poke-gate 0.1.0 → 0.1.4

package/docs/package.json

@@ -0,0 +1,15 @@
+{
+  "private": true,
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "vitepress build",
+    "preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.3"
+  },
+  "dependencies": {
+    "mermaid": "^11.13.0",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}

package/docs/public/CNAME

@@ -0,0 +1 @@
+poke-gate.fka.dev

package/docs/security.md

@@ -0,0 +1,35 @@
+# Security
+
+::: danger Full shell access
+Poke Gate grants **full shell access** to your Poke agent. Understand the implications before running it.
+:::
+
+## What the agent can do
+
+When Poke Gate is running, your Poke agent can:
+
+- **Run any command** with your user's permissions (`run_command`)
+- **Read any file** your user can access (`read_file`, `read_image`)
+- **Write any file** your user can access (`write_file`)
+- **List any directory** (`list_directory`)
+- **Take screenshots** of your screen (`take_screenshot`)
+- **See system info** — hostname, memory, uptime (`system_info`)
+
+## What protects you
+
+- **Authentication** — only your Poke agent (authenticated via your Poke OAuth session) can reach the tunnel. No one else can send tool calls.
+- **Tunnel isolation** — the MCP server only listens on `127.0.0.1` (localhost). It's not exposed to the network. The tunnel is the only way to reach it.
+- **No persistent access** — when you quit Poke Gate (Ctrl-C or Quit from menu bar), the tunnel closes and the connection is deleted. Your machine is no longer reachable.
+- **Connection cleanup** — old connections are deleted before new ones are created, preventing stale tunnels.
+
+## Best practices
+
+1. **Only run on trusted machines** — don't run Poke Gate on shared or public computers.
+2. **Quit when not needed** — close the app when you don't need remote access.
+3. **Review agent scripts** — before installing a community agent, read the code. Agents run with your full user permissions.
+4. **Keep env files secure** — `.env` files in `~/.config/poke-gate/agents/` may contain API tokens. Don't commit them to git.
+5. **Use verbose mode** — run with `--verbose` to see what tools are being called in real time.
+
+## Reporting issues
+
+If you discover a security vulnerability, please email [security@fka.dev](mailto:security@fka.dev) instead of opening a public issue.

package/docs/tools.md

@@ -0,0 +1,101 @@
+# Tools
+
+Poke Gate exposes 7 tools to your Poke agent via MCP.
+
+## run_command
+
+Execute any shell command on your machine.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `command` | string | yes | The shell command to execute |
+| `cwd` | string | no | Working directory (defaults to home) |
+
+**Returns:** `{ stdout, stderr, exitCode }`
+
+**Examples from Poke:**
+- "Run `ls -la` in my home directory"
+- "What's running on port 3000?"
+- "Show me the git log for my project"
+- "Install lodash in my project"
+
+::: info
+Commands have a 30-second timeout and 1MB output buffer.
+:::
+
+## read_file
+
+Read the contents of a text file.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | yes | Absolute or relative path (supports `~`) |
+
+**Examples:**
+- "Read my ~/.zshrc"
+- "Show me the package.json in my project"
+
+## read_image
+
+Read an image or binary file and return it as base64.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | yes | Path to the image file |
+
+Supports: png, jpg, gif, webp, svg, pdf, bmp, ico.
+
+For image files, returns MCP `image` content type with base64 data so the agent can "see" the image.
+
+## write_file
+
+Write content to a file. Creates the file if it doesn't exist, overwrites if it does.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | yes | Absolute or relative path (supports `~`) |
+| `content` | string | yes | Content to write |
+
+**Examples:**
+- "Create a file called notes.txt on my Desktop"
+- "Write a Python script that..."
+
+## list_directory
+
+List files and directories at a given path.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | no | Directory path (defaults to home, supports `~`) |
+
+Returns entries with `d` for directories and `-` for files.
+
+## system_info
+
+Get system information. No parameters needed.
+
+**Returns:**
+```json
+{
+  "hostname": "MacBook-Pro.local",
+  "platform": "darwin",
+  "arch": "arm64",
+  "uptime": "5h 23m",
+  "totalMemory": "16GB",
+  "freeMemory": "4GB",
+  "homeDir": "/Users/you",
+  "nodeVersion": "v22.21.1"
+}
+```
+
+## take_screenshot
+
+Capture the screen and save it to a file.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | no | Save path (defaults to `~/Desktop/screenshot-<timestamp>.png`) |
+
+::: warning
+Requires **Screen Recording** permission on macOS. The system will prompt you the first time.
+:::

package/examples/agents/battery.30m.js

@@ -0,0 +1,78 @@
+/**
+ * @agent battery
+ * @name Battery Guardian
+ * @description Alerts you via Poke when your battery drops below 20%.
+ * @interval 30m
+ * @author f
+ */
+
+import { Poke, getToken } from "poke";
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const token = getToken();
+if (!token) {
+  console.error("Not signed in. Run: npx poke login");
+  process.exit(1);
+}
+
+const THRESHOLD = parseInt(process.env.BATTERY_THRESHOLD || "20", 10);
+const STATE_FILE = join(homedir(), ".config", "poke-gate", "agents", ".battery-state.json");
+
+function getBattery() {
+  try {
+    const output = execSync("pmset -g batt", { encoding: "utf-8", timeout: 5000 });
+    const match = output.match(/(\d+)%/);
+    const charging = output.includes("AC Power") || output.includes("charging");
+    return {
+      level: match ? parseInt(match[1], 10) : null,
+      charging,
+    };
+  } catch {
+    return { level: null, charging: false };
+  }
+}
+
+function loadState() {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return { alerted: false };
+  }
+}
+
+function saveState(state) {
+  writeFileSync(STATE_FILE, JSON.stringify(state));
+}
+
+const { level, charging } = getBattery();
+
+if (level === null) {
+  console.log("Could not read battery level.");
+  process.exit(0);
+}
+
+console.log(`Battery: ${level}% ${charging ? "(charging)" : "(on battery)"}`);
+
+const state = loadState();
+
+if (level <= THRESHOLD && !charging && !state.alerted) {
+  console.log(`Battery low (${level}%). Alerting Poke...`);
+
+  const poke = new Poke({ apiKey: token });
+  await poke.sendMessage(
+    `⚠️ Battery alert: your Mac is at ${level}%. You're not plugged in. Consider charging soon.`
+  );
+
+  saveState({ alerted: true });
+  console.log("Alert sent.");
+} else if (level > THRESHOLD || charging) {
+  if (state.alerted) {
+    saveState({ alerted: false });
+    console.log("Battery recovered, reset alert state.");
+  } else {
+    console.log("Battery OK, no alert needed.");
+  }
+}

package/examples/agents/beeper.1h.js

@@ -36,12 +36,20 @@ async function beeperRequest(path, params = {}) {
 async function getRecentMessages() {
   const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString();
 
-  const data = await beeperRequest("/v1/messages/search", {
-    dateAfter: oneHourAgo,
-    limit: 200,
-  });
+  let allMessages = [];
+  let cursor = null;
+
+  while (true) {
+    const params = { dateAfter: oneHourAgo, limit: 20 };
+    if (cursor) params.cursor = cursor;
+    const data = await beeperRequest("/v1/messages/search", params);
+    const items = data.items || [];
+    allMessages.push(...items);
+    if (!data.hasMore || !data.oldestCursor) break;
+    cursor = data.oldestCursor;
+  }
 
-  return data.items || [];
+  return allMessages;
 }
 
 function groupBySender(messages) {

package/examples/agents/screentime.24h.js

@@ -0,0 +1,86 @@
+/**
+ * @agent screentime
+ * @name Screen Time Report
+ * @description Sends a daily summary of your most-used apps to Poke.
+ * @interval 24h
+ * @author f
+ */
+
+import { Poke, getToken } from "poke";
+import { execSync } from "node:child_process";
+
+const token = getToken();
+if (!token) {
+  console.error("Not signed in. Run: npx poke login");
+  process.exit(1);
+}
+
+function getScreenTime() {
+  try {
+    const result = execSync(
+      `defaults read com.apple.ScreenTimeAgent 2>/dev/null || echo "{}"`,
+      { encoding: "utf-8", timeout: 10000 }
+    ).trim();
+
+    // Fallback: use process list to estimate active apps
+    const ps = execSync(
+      `ps -eo etime,comm | grep -i "/Applications/" | sort -rn | head -20`,
+      { encoding: "utf-8", timeout: 10000 }
+    ).trim();
+
+    return ps;
+  } catch {
+    return null;
+  }
+}
+
+function getActiveApps() {
+  try {
+    const script = `
+      tell application "System Events"
+        set appList to name of every application process whose background only is false
+      end tell
+      return appList as text
+    `;
+    const result = execSync(`osascript -e '${script}'`, {
+      encoding: "utf-8",
+      timeout: 10000,
+    }).trim();
+    return result.split(", ");
+  } catch {
+    return [];
+  }
+}
+
+function getUptime() {
+  try {
+    return execSync("uptime", { encoding: "utf-8", timeout: 5000 }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+const apps = getActiveApps();
+const uptimeStr = getUptime();
+const screenData = getScreenTime();
+
+let report = `Daily screen report:\n\n`;
+report += `Uptime: ${uptimeStr}\n\n`;
+
+if (apps.length > 0) {
+  report += `Currently running apps (${apps.length}):\n`;
+  for (const app of apps) {
+    report += `  - ${app}\n`;
+  }
+}
+
+if (screenData) {
+  report += `\nTop processes by runtime:\n${screenData}\n`;
+}
+
+console.log("Sending screen time report...");
+
+const poke = new Poke({ apiKey: token });
+await poke.sendMessage(report);
+
+console.log("Report sent.");

package/examples/agents/wifi.30m.js

@@ -0,0 +1,85 @@
+/**
+ * @agent wifi
+ * @name WiFi Logger
+ * @description Logs your current WiFi network to Poke so it knows where you are.
+ * @interval 30m
+ * @author f
+ */
+
+import { Poke, getToken } from "poke";
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const token = getToken();
+if (!token) {
+  console.error("Not signed in. Run: npx poke login");
+  process.exit(1);
+}
+
+const STATE_FILE = join(homedir(), ".config", "poke-gate", "agents", ".wifi-state.json");
+
+function getCurrentNetwork() {
+  try {
+    const iface = execSync(
+      "networksetup -listallhardwareports | awk '/Wi-Fi/{getline; print $2}'",
+      { encoding: "utf-8", timeout: 5000 }
+    ).trim();
+
+    const ssid = execSync(
+      `networksetup -getairportnetwork ${iface || "en0"} 2>/dev/null | sed 's/Current Wi-Fi Network: //'`,
+      { encoding: "utf-8", timeout: 5000 }
+    ).trim();
+
+    if (ssid.includes("not associated") || !ssid) return null;
+    return ssid;
+  } catch {
+    return null;
+  }
+}
+
+function loadState() {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return { lastNetwork: null };
+  }
+}
+
+function saveState(state) {
+  writeFileSync(STATE_FILE, JSON.stringify(state));
+}
+
+const network = getCurrentNetwork();
+const state = loadState();
+
+console.log(`Current WiFi: ${network || "not connected"}`);
+
+if (network && network !== state.lastNetwork) {
+  console.log(`Network changed from "${state.lastNetwork}" to "${network}". Notifying Poke...`);
+
+  const poke = new Poke({ apiKey: token });
+  await poke.sendMessage(
+    `I just connected to WiFi network "${network}". ` +
+    (state.lastNetwork
+      ? `Previously I was on "${state.lastNetwork}".`
+      : `This is the first network I've logged.`) +
+    ` Remember this for context about where I am.`
+  );
+
+  saveState({ lastNetwork: network });
+  console.log("Poke notified.");
+} else if (!network && state.lastNetwork) {
+  console.log("Disconnected from WiFi. Notifying Poke...");
+
+  const poke = new Poke({ apiKey: token });
+  await poke.sendMessage(
+    `I've disconnected from WiFi (was on "${state.lastNetwork}"). I might be on the move.`
+  );
+
+  saveState({ lastNetwork: null });
+  console.log("Poke notified.");
+} else {
+  console.log("No network change.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poke-gate",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Expose your machine to your Poke AI assistant via MCP tunnel",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
 import { exec } from "node:child_process";
+import { createInterface } from "node:readline";
 
 const CONFIG_DIR = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
 const AGENTS_DIR = join(CONFIG_DIR, "poke-gate", "agents");
@@ -109,10 +110,31 @@ export function discoverAgents() {
   return agents;
 }
 
+import { symlinkSync, lstatSync } from "node:fs";
+
+function ensureNodeModulesLink() {
+  const pkgRoot = join(new URL(".", import.meta.url).pathname, "..");
+  const source = join(pkgRoot, "node_modules");
+  const target = join(AGENTS_DIR, "node_modules");
+
+  if (!existsSync(source)) return;
+
+  try {
+    const stat = lstatSync(target);
+    if (stat.isSymbolicLink()) return;
+  } catch {}
+
+  try {
+    symlinkSync(source, target, "junction");
+  } catch {}
+}
+
 function runAgentProcess(agent) {
   const agentEnv = parseEnvFile(agent.envFile);
   const env = { ...process.env, ...agentEnv };
 
+  ensureNodeModulesLink();
+
   log(`Running agent: ${agent.name} (${agent.file})`);
 
   return new Promise((resolve) => {
@@ -212,26 +234,91 @@ export async function downloadAgent(name) {
   writeFileSync(dest, jsContent);
   console.log(`  Saved: ${dest}`);
 
-  // Try to download matching .env file
   const envName = name.split(".")[0];
+  const envDest = join(AGENTS_DIR, `.env.${envName}`);
+
+  if (existsSync(envDest)) {
+    console.log(`  .env.${envName} already exists, skipped.`);
+    console.log(`\n  Test it: npx poke-gate run-agent ${envName}`);
+    return;
+  }
+
   const envRes = await fetch(`${REPO_BASE}/.env.${envName}`).catch(() => null);
   if (envRes?.ok) {
-    const envContent = await envRes.text();
-    const envDest = join(AGENTS_DIR, `.env.${envName}`);
-    if (!existsSync(envDest)) {
-      writeFileSync(envDest, envContent);
-      console.log(`  Saved: ${envDest}`);
-      console.log(`\n  Edit the env file with your credentials:`);
-      console.log(`    nano ${envDest}`);
+    const envTemplate = await envRes.text();
+    const keys = parseEnvKeys(envTemplate);
+
+    if (keys.length > 0) {
+      console.log(`\n  This agent needs ${keys.length} env variable(s):\n`);
+      const values = await promptEnvKeys(keys);
+      let content = "";
+      for (const { key, comment } of keys) {
+        if (comment) content += `# ${comment}\n`;
+        content += `${key}=${values[key] || ""}\n`;
+      }
+      writeFileSync(envDest, content);
+      console.log(`\n  Saved: ${envDest}`);
     } else {
-      console.log(`  .env.${envName} already exists, skipped.`);
+      writeFileSync(envDest, envTemplate);
+      console.log(`  Saved: ${envDest}`);
     }
   }
 
   console.log(`\n  Test it: npx poke-gate run-agent ${envName}`);
 }
 
+function parseEnvKeys(template) {
+  const keys = [];
+  const lines = template.split("\n");
+  let lastComment = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) {
+      lastComment = trimmed.slice(1).trim();
+      continue;
+    }
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) { lastComment = null; continue; }
+    const key = trimmed.slice(0, eqIdx).trim();
+    const value = trimmed.slice(eqIdx + 1).trim();
+    const isPlaceholder = !value || value.includes("your_") || value.includes("_here");
+    if (isPlaceholder) {
+      keys.push({ key, comment: lastComment });
+    }
+    lastComment = null;
+  }
+  return keys;
+}
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function promptEnvKeys(keys) {
+  const values = {};
+  for (const { key, comment } of keys) {
+    const hint = comment ? ` (${comment})` : "";
+    values[key] = await ask(`  ${key}${hint}: `);
+  }
+  return values;
+}
+
+let schedulerRunning = false;
+const activeTimers = [];
+
 export function startAgentScheduler() {
+  if (schedulerRunning) {
+    log("Agent scheduler already running, skipping.");
+    return;
+  }
+  schedulerRunning = true;
+
   const agents = discoverAgents();
 
   if (agents.length === 0) {
@@ -250,8 +337,18 @@ export function startAgentScheduler() {
   for (const agent of agents) {
     runAgentProcess(agent);
 
-    setInterval(() => {
+    const timer = setInterval(() => {
       runAgentProcess(agent);
     }, agent.intervalMs);
+    activeTimers.push(timer);
+  }
+}
+
+export function stopAgentScheduler() {
+  for (const timer of activeTimers) {
+    clearInterval(timer);
   }
+  activeTimers.length = 0;
+  schedulerRunning = false;
+  log("Agent scheduler stopped.");
 }