poke-gate 0.1.1 → 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/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.1",
+  "version": "0.1.4",
   "description": "Expose your machine to your Poke AI assistant via MCP tunnel",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -309,7 +309,16 @@ async function promptEnvKeys(keys) {
   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) {
@@ -328,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.");
 }