poke-gate 0.0.9 → 0.1.1

package/README.md

@@ -44,11 +44,11 @@ npx poke-gate
 
 ## Setup
 
-1. Open Poke Gate from your menu bar
-2. Click **Start** (or let auto-start run)
-3. If needed, complete the Poke OAuth sign-in flow in your browser
+1. Get an API key from [poke.com/kitchen/api-keys](https://poke.com/kitchen/api-keys)
+2. Open Poke Gate from your menu bar and go to **Settings**
+3. Paste your API key and save
 
-The app connects automatically after sign-in and shows a green dot when ready.
+The app connects automatically and shows a green dot when ready.
 
 ## How it works
 
@@ -94,10 +94,10 @@ From iMessage or Telegram, ask Poke:
 The menu bar app manages everything:
 
 - **Status** — green dot when connected, yellow when connecting, red on error
-- **Personalized** — shows "Connected to your Poke, <name>"
+- **Personalized** — shows "Connected to your Poke, [name]"
 - **Auto-start** — connects on launch if API key is saved
 - **Auto-restart** — reconnects automatically if the connection drops
-- **Settings** — auth status and reconnect controls
+- **Settings** — paste your API key
 - **Logs** — view real-time tool calls and connection events
 - **Screen Recording** — prompts for permission on first launch
 
@@ -127,19 +127,108 @@ If you prefer the command line over the macOS app:
 npx poke-gate
 ```
 
-On first run, if you're not signed in, Poke Gate opens OAuth login automatically. Add `--verbose` to see tool calls in real time:
+On first run, paste your API key when prompted. Add `--verbose` to see tool calls in real time:
 
 ```bash
 npx poke-gate --verbose
 ```
 
+Config is stored at `~/.config/poke-gate/config.json`.
+
+## Agents
+
+Agents are scheduled scripts that run automatically in the background. They live in `~/.config/poke-gate/agents/` and follow a simple naming convention:
+
+```
+<name>.<interval>.js
+```
+
+| File | Runs |
+|------|------|
+| `beeper.1h.js` | Every hour |
+| `backup.2h.js` | Every 2 hours |
+| `health.10m.js` | Every 10 minutes |
+| `cleanup.30m.js` | Every 30 minutes |
+
+Intervals: `Nm` (minutes) or `Nh` (hours). Minimum is 10 minutes.
+
+### Install an agent
+
+Download a community agent from the repository:
+
+```bash
+npx poke-gate agent get beeper
+```
+
+This downloads `beeper.1h.js` and `.env.beeper` to `~/.config/poke-gate/agents/`. Edit the env file with your credentials and test it:
+
+```bash
+nano ~/.config/poke-gate/agents/.env.beeper
+npx poke-gate run-agent beeper
+```
+
+### Per-agent env files
+
+Each agent can have a `.env.<name>` file for secrets:
+
+```
+~/.config/poke-gate/agents/.env.beeper
+```
+
+```env
+BEEPER_TOKEN=your_token_here
+```
+
+Variables are injected into the agent process automatically.
+
+### Agent frontmatter
+
+Each agent file starts with a JSDoc-style frontmatter block:
+
+```javascript
+/**
+ * @agent beeper
+ * @name Beeper Message Digest
+ * @description Fetches messages from the last hour and sends a summary to Poke.
+ * @interval 1h
+ * @env BEEPER_TOKEN - Beeper Desktop local API token
+ * @author f
+ */
+```
+
+### Creating your own agent
+
+An agent is just a JS file that runs with Node.js. It has access to:
+
+- `process.env` — variables from `.env.<name>`
+- `poke` package — `import { Poke, getToken } from "poke"`
+- Any npm package installed globally or via npx
+
+```javascript
+/**
+ * @agent my-agent
+ * @name My Custom Agent
+ * @description Does something useful every 30 minutes.
+ * @interval 30m
+ */
+
+import { Poke, getToken } from "poke";
+
+const poke = new Poke({ apiKey: getToken() });
+await poke.sendMessage("Hello from my agent!");
+```
+
+Save as `~/.config/poke-gate/agents/my-agent.30m.js` and it runs automatically when poke-gate is connected.
+
+Agents start running when poke-gate connects and run once immediately on startup.
+
 ## Security
 
 **Poke Gate grants full shell access to your Poke agent.** This means:
 
 - Any command can be run with your user's permissions
 - Files can be read and written anywhere your user has access
-- Only your authenticated Poke agent can reach the tunnel
+- Only your Poke agent (authenticated by your API key) can reach the tunnel
 
 Only run Poke Gate on machines and networks you trust.
 
@@ -149,11 +238,16 @@ Only run Poke Gate on machines and networks you trust.
 clients/
   Poke macOS Gate/       macOS menu bar app (SwiftUI)
 bin/
-  poke-gate.js           CLI entry point + onboarding
+  poke-gate.js           CLI entry point, run-agent subcommand
 src/
-  app.js                 Startup: MCP server + tunnel
+  app.js                 Startup: MCP server + tunnel + agent scheduler
+  agents.js              Agent discovery, scheduling, and runner
   mcp-server.js          JSON-RPC MCP handler with OS tools
   tunnel.js              PokeTunnel wrapper
+examples/
+  agents/
+    beeper.1h.js         Example: Beeper message digest
+    .env.beeper          Example env file
 ```
 
 ## Credits

package/bin/poke-gate.js

@@ -1,7 +1,29 @@
 #!/usr/bin/env node
 
+const args = process.argv.slice(2);
+
 async function main() {
-  await import("../src/app.js");
+  if (args[0] === "run-agent") {
+    const name = args[1];
+    if (!name) {
+      console.error("Usage: poke-gate run-agent <name>");
+      console.error("Example: poke-gate run-agent beeper");
+      process.exit(1);
+    }
+    const { runAgent } = await import("../src/agents.js");
+    await runAgent(name);
+  } else if (args[0] === "agent" && args[1] === "get") {
+    const name = args[2];
+    if (!name) {
+      console.error("Usage: poke-gate agent get <name>");
+      console.error("Example: poke-gate agent get beeper");
+      process.exit(1);
+    }
+    const { downloadAgent } = await import("../src/agents.js");
+    await downloadAgent(name);
+  } else {
+    await import("../src/app.js");
+  }
 }
 
 main();

package/clients/Poke macOS Gate/Poke macOS Gate.xcodeproj/project.pbxproj

@@ -264,7 +264,7 @@
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MARKETING_VERSION = 0.0.8;
+				MARKETING_VERSION = 0.1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = "dev.fka.Poke-macOS-Gate";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -296,7 +296,7 @@
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MARKETING_VERSION = 0.0.8;
+				MARKETING_VERSION = 0.1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = "dev.fka.Poke-macOS-Gate";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;

package/examples/agents/.env.beeper

@@ -0,0 +1,6 @@
+# Beeper Desktop local API token
+# Find it in Beeper Desktop > Settings > API
+BEEPER_TOKEN=your_beeper_access_token_here
+
+# Optional: override the default Beeper API URL
+# BEEPER_BASE_URL=http://localhost:23373

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

@@ -0,0 +1,117 @@
+/**
+ * @agent beeper
+ * @name Beeper Message Digest
+ * @description Fetches messages from the last hour via Beeper Desktop and sends a summary to Poke.
+ * @interval 1h
+ * @env BEEPER_TOKEN - Beeper Desktop local API token (Settings > API)
+ * @env BEEPER_BASE_URL - (optional) Override default http://localhost:23373
+ * @author f
+ */
+
+import { Poke, getToken } from "poke";
+
+const BEEPER_BASE = process.env.BEEPER_BASE_URL || "http://localhost:23373";
+const BEEPER_TOKEN = process.env.BEEPER_TOKEN;
+
+if (!BEEPER_TOKEN) {
+  console.error("BEEPER_TOKEN not set. Create ~/.config/poke-gate/agents/.env.beeper");
+  process.exit(1);
+}
+
+async function beeperRequest(path, params = {}) {
+  const url = new URL(BEEPER_BASE + path);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) url.searchParams.set(key, String(value));
+  }
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${BEEPER_TOKEN}`,
+      Accept: "application/json",
+    },
+  });
+  if (!res.ok) throw new Error(`Beeper API ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
+async function getRecentMessages() {
+  const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+
+  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 allMessages;
+}
+
+function groupBySender(messages) {
+  const groups = {};
+  for (const msg of messages) {
+    if (msg.isSender) continue;
+    const name = msg.senderName || msg.senderID || "Unknown";
+    if (!groups[name]) groups[name] = [];
+    if (msg.text) groups[name].push(msg.text);
+  }
+  return groups;
+}
+
+function buildSummary(groups) {
+  const senders = Object.keys(groups);
+  if (senders.length === 0) return null;
+
+  let summary = `Messages from the last hour (${senders.length} people):\n\n`;
+
+  for (const [sender, messages] of Object.entries(groups)) {
+    summary += `${sender} (${messages.length} messages):\n`;
+    for (const text of messages.slice(-3)) {
+      const preview = text.length > 100 ? text.slice(0, 100) + "…" : text;
+      summary += `  - ${preview}\n`;
+    }
+    summary += "\n";
+  }
+
+  return summary.trim();
+}
+
+async function main() {
+  console.log("Fetching messages from the last hour...");
+
+  const messages = await getRecentMessages();
+  console.log(`Found ${messages.length} messages`);
+
+  const groups = groupBySender(messages);
+  const summary = buildSummary(groups);
+
+  if (!summary) {
+    console.log("No new messages from others in the last hour.");
+    return;
+  }
+
+  console.log("Sending summary to Poke...");
+
+  const token = getToken();
+  if (!token) {
+    console.error("Not logged in to Poke. Run: npx poke login");
+    process.exit(1);
+  }
+
+  const poke = new Poke({ apiKey: token });
+  await poke.sendMessage(
+    `Here's a summary of my Beeper messages from the last hour:\n\n${summary}`
+  );
+
+  console.log("Summary sent to Poke.");
+}
+
+main().catch((err) => {
+  console.error("Agent error:", err.message);
+  process.exit(1);
+});

package/package.json

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

package/src/agents.js

@@ -0,0 +1,335 @@
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+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");
+
+const MIN_INTERVAL_MS = 10 * 60 * 1000;
+
+function log(msg) {
+  const ts = new Date().toISOString().slice(11, 19);
+  console.log(`[${ts}] [agents] ${msg}`);
+}
+
+function parseInterval(token) {
+  const match = token.match(/^(\d+)(m|h)$/);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  const ms = unit === "h" ? value * 60 * 60 * 1000 : value * 60 * 1000;
+  if (ms < MIN_INTERVAL_MS) return null;
+  return ms;
+}
+
+function parseFrontmatter(filePath) {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const match = content.match(/\/\*\*[\s\S]*?\*\//);
+    if (!match) return {};
+    const block = match[0];
+    const meta = {};
+    const lines = block.split("\n");
+    for (const line of lines) {
+      const m = line.match(/@(\w+)\s+(.*)/);
+      if (m) {
+        const key = m[1].trim();
+        const value = m[2].replace(/\*\/$/, "").trim();
+        if (key === "env") {
+          if (!meta.env) meta.env = [];
+          meta.env.push(value);
+        } else {
+          meta[key] = value;
+        }
+      }
+    }
+    return meta;
+  } catch {
+    return {};
+  }
+}
+
+function parseEnvFile(filePath) {
+  const env = {};
+  if (!existsSync(filePath)) return env;
+  const lines = readFileSync(filePath, "utf-8").split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    let value = trimmed.slice(eqIdx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    env[key] = value;
+  }
+  return env;
+}
+
+export function discoverAgents() {
+  if (!existsSync(AGENTS_DIR)) {
+    mkdirSync(AGENTS_DIR, { recursive: true });
+    return [];
+  }
+
+  const files = readdirSync(AGENTS_DIR).filter((f) => f.endsWith(".js"));
+  const agents = [];
+
+  for (const file of files) {
+    const parts = file.replace(/\.js$/, "").split(".");
+    if (parts.length < 2) continue;
+
+    const intervalToken = parts[parts.length - 1];
+    const name = parts.slice(0, -1).join(".");
+    const intervalMs = parseInterval(intervalToken);
+
+    if (!intervalMs) {
+      log(`Skipping ${file}: invalid or too short interval (min 10m)`);
+      continue;
+    }
+
+    const agentPath = join(AGENTS_DIR, file);
+    const meta = parseFrontmatter(agentPath);
+
+    agents.push({
+      name,
+      file,
+      path: agentPath,
+      intervalToken,
+      intervalMs,
+      envFile: join(AGENTS_DIR, `.env.${name}`),
+      meta,
+    });
+  }
+
+  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) => {
+    exec(`node "${agent.path}"`, {
+      env,
+      timeout: 5 * 60 * 1000,
+      maxBuffer: 1024 * 1024,
+      cwd: AGENTS_DIR,
+    }, (error, stdout, stderr) => {
+      if (stdout.trim()) log(`[${agent.name}] ${stdout.trim()}`);
+      if (stderr.trim()) log(`[${agent.name}] stderr: ${stderr.trim()}`);
+      if (error) log(`[${agent.name}] exited with code ${error.code ?? 1}`);
+      else log(`[${agent.name}] completed`);
+      resolve();
+    });
+  });
+}
+
+export async function runAgent(name) {
+  const agents = discoverAgents();
+  const agent = agents.find((a) => a.name === name);
+  if (!agent) {
+    const allFiles = readdirSync(AGENTS_DIR).filter((f) => f.endsWith(".js"));
+    const match = allFiles.find((f) => f.startsWith(name + "."));
+    if (match) {
+      const parts = match.replace(/\.js$/, "").split(".");
+      const intervalToken = parts[parts.length - 1];
+      const intervalMs = parseInterval(intervalToken);
+      await runAgentProcess({
+        name,
+        file: match,
+        path: join(AGENTS_DIR, match),
+        intervalToken,
+        intervalMs: intervalMs || 0,
+        envFile: join(AGENTS_DIR, `.env.${name}`),
+      });
+      return;
+    }
+    console.error(`Agent "${name}" not found in ${AGENTS_DIR}`);
+    console.error("Available agents:", agents.map((a) => a.name).join(", ") || "none");
+    process.exit(1);
+  }
+  await runAgentProcess(agent);
+}
+
+const REPO_BASE = "https://raw.githubusercontent.com/f/poke-gate/main/examples/agents";
+
+export async function downloadAgent(name) {
+  mkdirSync(AGENTS_DIR, { recursive: true });
+
+  console.log(`Fetching agent "${name}" from GitHub...`);
+
+  const indexRes = await fetch(`${REPO_BASE}/`).catch(() => null);
+
+  const jsUrl = `${REPO_BASE}/${name}`;
+  const envUrl = `${REPO_BASE}/.env.${name}`;
+
+  // Try to find the exact file first, or search for name.*.js pattern
+  let jsFileName = null;
+  let jsContent = null;
+
+  // Try direct match (user might pass "beeper.1h.js")
+  let res = await fetch(`${REPO_BASE}/${name}`).catch(() => null);
+  if (res?.ok) {
+    jsFileName = name;
+    jsContent = await res.text();
+  }
+
+  // Try with .js extension
+  if (!jsContent) {
+    res = await fetch(`${REPO_BASE}/${name}.js`).catch(() => null);
+    if (res?.ok) {
+      jsFileName = `${name}.js`;
+      jsContent = await res.text();
+    }
+  }
+
+  // Try common intervals
+  if (!jsContent) {
+    for (const interval of ["10m", "30m", "1h", "2h", "6h", "12h", "24h"]) {
+      res = await fetch(`${REPO_BASE}/${name}.${interval}.js`).catch(() => null);
+      if (res?.ok) {
+        jsFileName = `${name}.${interval}.js`;
+        jsContent = await res.text();
+        break;
+      }
+    }
+  }
+
+  if (!jsContent) {
+    console.error(`Agent "${name}" not found in the repository.`);
+    console.error(`Browse available agents: https://github.com/f/poke-gate/tree/main/examples/agents`);
+    process.exit(1);
+  }
+
+  const dest = join(AGENTS_DIR, jsFileName);
+  writeFileSync(dest, jsContent);
+  console.log(`  Saved: ${dest}`);
+
+  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 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 {
+      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;
+}
+
+export function startAgentScheduler() {
+  const agents = discoverAgents();
+
+  if (agents.length === 0) {
+    log("No agents found. Add scripts to ~/.config/poke-gate/agents/");
+    return;
+  }
+
+  log(`Found ${agents.length} agent(s):`);
+  for (const agent of agents) {
+    const interval = agent.intervalToken;
+    const hasEnv = existsSync(agent.envFile);
+    const desc = agent.meta.name || agent.name;
+    log(`  ${desc} (every ${interval}${hasEnv ? ", has .env" : ""})`);
+  }
+
+  for (const agent of agents) {
+    runAgentProcess(agent);
+
+    setInterval(() => {
+      runAgentProcess(agent);
+    }, agent.intervalMs);
+  }
+}

package/src/app.js

@@ -1,5 +1,6 @@
 import { startMcpServer, enableLogging } from "./mcp-server.js";
 import { startTunnel } from "./tunnel.js";
+import { startAgentScheduler } from "./agents.js";
 import { Poke, isLoggedIn, login, getToken } from "poke";
 
 const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
@@ -44,6 +45,7 @@ async function main() {
             log(`Tunnel connected (${data.connectionId})`);
             log("Ready — your Poke agent can now access this machine.");
             notifyPoke(data.connectionId, token);
+            startAgentScheduler();
             break;
           case "disconnected":
             log("Tunnel disconnected. Reconnecting...");