poke-gate 0.1.1 → 0.1.5

package/clients/Poke macOS Gate/Poke macOS Gate/GateService.swift

@@ -32,12 +32,13 @@ class GateService: ObservableObject {
 
     func runPokeLogin() {
         let fullPath = shellPath()
+        let npxBin = findNpx()
         let proc = Process()
         proc.executableURL = URL(fileURLWithPath: "/bin/zsh")
-        proc.arguments = ["-c", "npx -y poke@latest login"]
+        proc.arguments = ["-c", "\(npxBin) -y poke@latest login"]
         proc.environment = ["HOME": NSHomeDirectory(), "PATH": fullPath]
         try? proc.run()
-        appendLog("Launched poke login — check your browser.")
+        appendLog("Launched poke login (npx: \(npxBin)) — check your browser.")
     }
 
     func autoStartIfNeeded() {
@@ -90,19 +91,82 @@ class GateService: ObservableObject {
         }
     }
 
-    private func shellPath() -> String {
-        let loginShell = ProcessInfo.processInfo.environment["SHELL"] ?? "/bin/zsh"
-        let pathProc = Process()
-        let pathPipe = Pipe()
-        pathProc.executableURL = URL(fileURLWithPath: loginShell)
-        pathProc.arguments = ["-ilc", "echo $PATH"]
-        pathProc.standardOutput = pathPipe
-        pathProc.standardError = FileHandle.nullDevice
-        pathProc.environment = ["HOME": NSHomeDirectory()]
-        try? pathProc.run()
-        pathProc.waitUntilExit()
-        let data = pathPipe.fileHandleForReading.readDataToEndOfFile()
-        return String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+    func shellPath() -> String {
+        let home = NSHomeDirectory()
+        let fallback = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin"
+
+        // Try multiple shells/strategies to get PATH
+        let strategies: [(String, [String])] = [
+            ("/bin/zsh", ["-ilc", "echo $PATH"]),
+            ("/bin/zsh", ["-lc", "echo $PATH"]),
+            ("/bin/bash", ["-lc", "echo $PATH"]),
+        ]
+
+        for (shell, args) in strategies {
+            let proc = Process()
+            let pipe = Pipe()
+            proc.executableURL = URL(fileURLWithPath: shell)
+            proc.arguments = args
+            proc.standardOutput = pipe
+            proc.standardError = FileHandle.nullDevice
+            proc.environment = ["HOME": home]
+            do {
+                try proc.run()
+                proc.waitUntilExit()
+                if proc.terminationStatus == 0 {
+                    let data = pipe.fileHandleForReading.readDataToEndOfFile()
+                    if let path = String(data: data, encoding: .utf8)?
+                        .trimmingCharacters(in: .whitespacesAndNewlines),
+                       !path.isEmpty {
+                        return path
+                    }
+                }
+            } catch {
+                continue
+            }
+        }
+
+        // Fallback: build PATH from common locations
+        var paths = fallback.split(separator: ":").map(String.init)
+
+        let commonDirs = [
+            "\(home)/.nvm/versions/node",
+            "\(home)/.volta/bin",
+            "\(home)/.fnm/aliases/default/bin",
+            "\(home)/.local/bin",
+            "\(home)/.cargo/bin",
+            "/opt/homebrew/bin",
+            "/usr/local/bin",
+        ]
+
+        for dir in commonDirs {
+            if FileManager.default.fileExists(atPath: dir) {
+                if dir.contains(".nvm") {
+                    // Find the latest node version in nvm
+                    if let versions = try? FileManager.default.contentsOfDirectory(atPath: dir) {
+                        if let latest = versions.sorted().last {
+                            let binPath = "\(dir)/\(latest)/bin"
+                            if !paths.contains(binPath) { paths.insert(binPath, at: 0) }
+                        }
+                    }
+                } else if !paths.contains(dir) {
+                    paths.insert(dir, at: 0)
+                }
+            }
+        }
+
+        return paths.joined(separator: ":")
+    }
+
+    private func findNpx() -> String {
+        let path = shellPath()
+        for dir in path.split(separator: ":") {
+            let npxPath = "\(dir)/npx"
+            if FileManager.default.isExecutableFile(atPath: npxPath) {
+                return npxPath
+            }
+        }
+        return "npx"
     }
 
     private func launchProcess() {
@@ -112,15 +176,17 @@ class GateService: ObservableObject {
         appendLog("Starting poke-gate…")
 
         let fullPath = shellPath()
+        let npxBin = findNpx()
+
+        appendLog("Using npx at: \(npxBin)")
 
         let proc = Process()
         let pipe = Pipe()
 
         proc.executableURL = URL(fileURLWithPath: "/bin/zsh")
-        proc.arguments = ["-c", "npx -y poke-gate --verbose"]
+        proc.arguments = ["-c", "\(npxBin) -y poke-gate --verbose"]
         proc.environment = ProcessInfo.processInfo.environment.merging(
             [
-                "POKE_API_KEY": resolveToken() ?? "",
                 "PATH": fullPath,
             ],
             uniquingKeysWith: { _, new in new }

package/clients/Poke macOS Gate/Poke macOS Gate/Poke_macOS_GateApp.swift

@@ -23,6 +23,11 @@ struct Poke_macOS_GateApp: App {
         }
         .windowResizability(.contentSize)
 
+        Window("Agents", id: "agents") {
+            AgentsView()
+        }
+        .defaultSize(width: 700, height: 480)
+
         Window("About", id: "about") {
             AboutView()
         }
@@ -110,6 +115,11 @@ struct PopoverContent: View {
                     openWindow(id: "logs")
                 }
 
+                ActionButton(icon: "bolt.fill", label: "Agents") {
+                    NSApp.activate(ignoringOtherApps: true)
+                    openWindow(id: "agents")
+                }
+
                 ActionButton(icon: "gearshape", label: "Settings") {
                     NSApp.activate(ignoringOtherApps: true)
                     openWindow(id: "settings")

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

@@ -259,12 +259,15 @@
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = "Poke macOS Gate/Info.plist";
+				INFOPLIST_KEY_CFBundleDisplayName = "Poke macOS Gate";
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.productivity";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MARKETING_VERSION = 0.1.0;
+				MACOSX_DEPLOYMENT_TARGET = 26.0;
+				MARKETING_VERSION = 0.1.5;
 				PRODUCT_BUNDLE_IDENTIFIER = "dev.fka.Poke-macOS-Gate";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -291,12 +294,15 @@
 				ENABLE_PREVIEWS = YES;
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = "Poke macOS Gate/Info.plist";
+				INFOPLIST_KEY_CFBundleDisplayName = "Poke macOS Gate";
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.productivity";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MARKETING_VERSION = 0.1.0;
+				MACOSX_DEPLOYMENT_TARGET = 26.0;
+				MARKETING_VERSION = 0.1.5;
 				PRODUCT_BUNDLE_IDENTIFIER = "dev.fka.Poke-macOS-Gate";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;

package/docs/.vitepress/config.mts

@@ -0,0 +1,75 @@
+import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+
+export default withMermaid(
+  defineConfig({
+    title: 'Poke Gate',
+    description: 'Let your Poke AI assistant access your machine',
+    head: [
+      ['link', { rel: 'icon', href: '/logo.png' }],
+    ],
+    themeConfig: {
+      logo: '/logo.png',
+      nav: [
+        { text: 'Guide', link: '/getting-started' },
+        { text: 'Agents', link: '/agents/' },
+        { text: 'CLI', link: '/cli' },
+        {
+          text: 'Download',
+          items: [
+            { text: 'macOS App', link: 'https://github.com/f/poke-gate/releases/latest' },
+            { text: 'Homebrew', link: '/getting-started#homebrew' },
+            { text: 'npm', link: 'https://www.npmjs.com/package/poke-gate' },
+          ]
+        }
+      ],
+      sidebar: [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Getting Started', link: '/getting-started' },
+            { text: 'How It Works', link: '/how-it-works' },
+            { text: 'Tools', link: '/tools' },
+          ]
+        },
+        {
+          text: 'Agents',
+          items: [
+            { text: 'Overview', link: '/agents/' },
+            { text: 'Creating Agents', link: '/agents/creating' },
+            { text: 'Installing Agents', link: '/agents/installing' },
+            { text: 'Community Agents', link: '/agents/community' },
+          { text: 'Beeper Example', link: '/agents/beeper' },
+          { text: 'Sharing Agents', link: '/agents/sharing' },
+          ]
+        },
+        {
+          text: 'Reference',
+          items: [
+            { text: 'macOS App', link: '/macos-app' },
+            { text: 'CLI Reference', link: '/cli' },
+            { text: 'Security', link: '/security' },
+          ]
+        }
+      ],
+      socialLinks: [
+        { icon: 'github', link: 'https://github.com/f/poke-gate' },
+        { icon: 'npm', link: 'https://www.npmjs.com/package/poke-gate' },
+      ],
+      footer: {
+        message: 'Community project — not affiliated with Poke or The Interaction Company.',
+        copyright: 'Released under the MIT License.',
+      },
+      editLink: {
+        pattern: 'https://github.com/f/poke-gate/edit/main/docs/:path',
+        text: 'Edit this page on GitHub',
+      },
+    },
+    mermaid: {
+      theme: 'neutral',
+      themeVariables: {
+        fontSize: '13px',
+      },
+    },
+  })
+)

package/docs/agents/beeper.md

@@ -0,0 +1,107 @@
+# Beeper Agent
+
+The Beeper agent fetches messages from the last hour via [Beeper Desktop](https://beeper.com)'s local API, groups them by sender, and sends a summary to your Poke agent.
+
+## What it does
+
+Every hour:
+
+1. Calls Beeper's local API at `http://localhost:23373`
+2. Searches for messages from the last 60 minutes
+3. Filters out messages you sent (only shows incoming)
+4. Groups messages by sender name
+5. Formats a summary with sender name, message count, and last 3 messages
+6. Sends the summary to Poke via `sendMessage`
+
+## Prerequisites
+
+- [Beeper Desktop](https://beeper.com) running on your machine
+- Beeper API token (find it in Beeper Desktop > Settings > API)
+- Signed in to Poke (`npx poke login`)
+
+## Install
+
+```bash
+npx poke-gate agent get beeper
+```
+
+When prompted, paste your Beeper token:
+
+```
+BEEPER_TOKEN (Find it in Beeper Desktop > Settings > API): <paste>
+```
+
+## Test
+
+```bash
+npx poke-gate run-agent beeper
+```
+
+Expected output:
+
+```
+[agents] Running agent: beeper (beeper.1h.js)
+[agents] [beeper] Fetching messages from the last hour...
+[agents] [beeper] Found 42 messages
+[agents] [beeper] Sending summary to Poke...
+[agents] [beeper] Summary sent to Poke.
+[agents] [beeper] completed
+```
+
+## What Poke receives
+
+Your Poke agent gets a message like:
+
+> Messages from the last hour (3 people):
+>
+> Alice (5 messages):
+>   - Hey, are you free for lunch?
+>   - The meeting got moved to 3pm
+>   - Can you review my PR?
+>
+> Bob (2 messages):
+>   - Deployed the fix
+>   - All tests passing now
+>
+> Mom (1 messages):
+>   - Don't forget dinner tonight!
+
+## Configuration
+
+### Env variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BEEPER_TOKEN` | yes | Beeper Desktop API token |
+| `BEEPER_BASE_URL` | no | Override default `http://localhost:23373` |
+
+Edit: `~/.config/poke-gate/agents/.env.beeper`
+
+### Change the interval
+
+Rename the file to change how often it runs:
+
+```bash
+# Every 30 minutes
+mv ~/.config/poke-gate/agents/beeper.1h.js ~/.config/poke-gate/agents/beeper.30m.js
+```
+
+Or use the macOS Agents editor.
+
+## Frontmatter
+
+```javascript
+/**
+ * @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
+ */
+```
+
+## Source
+
+[View on GitHub](https://github.com/f/poke-gate/blob/main/examples/agents/beeper.1h.js)

package/docs/agents/community.md

@@ -0,0 +1,77 @@
+# Community Agents
+
+Ready-to-use agents you can install with a single command. All agents are open source and included in the [Poke Gate repository](https://github.com/f/poke-gate/tree/main/examples/agents).
+
+## Beeper Message Digest
+
+Fetches messages from the last hour via [Beeper Desktop](https://beeper.com)'s local API, groups them by sender, and sends a summary to Poke. Great for staying on top of conversations across all your messaging platforms without checking each one.
+
+| | |
+|---|---|
+| **File** | `beeper.1h.js` |
+| **Interval** | Every hour |
+| **Requires** | Beeper Desktop running, API token |
+
+```bash
+npx poke-gate agent get beeper
+```
+
+[Full documentation →](/agents/beeper)
+
+---
+
+## Screen Time Report
+
+Sends a daily summary of your Mac usage — currently running apps, uptime, and top processes. Poke learns your work patterns and can answer questions like "what was I doing yesterday?" or "how long have I been working today?".
+
+| | |
+|---|---|
+| **File** | `screentime.24h.js` |
+| **Interval** | Every 24 hours |
+| **Requires** | Nothing — works out of the box |
+
+```bash
+npx poke-gate agent get screentime
+```
+
+---
+
+## Battery Guardian
+
+Monitors your battery and alerts you via Poke when it drops below 20% on battery power. Only alerts once per discharge cycle — won't spam you. Resets when you plug in.
+
+| | |
+|---|---|
+| **File** | `battery.30m.js` |
+| **Interval** | Every 30 minutes |
+| **Requires** | Nothing — works out of the box |
+
+```bash
+npx poke-gate agent get battery
+```
+
+::: tip Custom threshold
+Set `BATTERY_THRESHOLD` in `.env.battery` to change the alert level (default: 20%).
+:::
+
+---
+
+## WiFi Logger
+
+Tracks which WiFi network you're on and notifies Poke when you switch networks or disconnect. This gives Poke passive context about your location — it knows if you're at home, at the office, or at a cafe without you telling it.
+
+| | |
+|---|---|
+| **File** | `wifi.30m.js` |
+| **Interval** | Every 30 minutes |
+| **Requires** | Nothing — works out of the box |
+
+```bash
+npx poke-gate agent get wifi
+```
+
+---
+
+## Want more?
+
+Check the [Sharing Agents](/agents/sharing) page for ideas and instructions on contributing your own agent to the community.

package/docs/agents/creating.md

@@ -0,0 +1,132 @@
+# Creating Agents
+
+This guide walks you through creating an agent from scratch.
+
+## Step 1: Create the file
+
+Agents live in `~/.config/poke-gate/agents/`. Create a file with the naming convention `name.interval.js`:
+
+```bash
+touch ~/.config/poke-gate/agents/hello.1h.js
+```
+
+This creates an agent called "hello" that runs every hour.
+
+## Step 2: Add frontmatter
+
+Start with the frontmatter block. This is optional but recommended — it's displayed in the macOS Agents editor.
+
+```javascript
+/**
+ * @agent hello
+ * @name Hello World
+ * @description Sends a greeting to Poke every hour.
+ * @interval 1h
+ * @author you
+ */
+```
+
+## Step 3: Write your logic
+
+Agents are standard Node.js ESM scripts. They can import the Poke SDK and any globally installed packages.
+
+```javascript
+/**
+ * @agent hello
+ * @name Hello World
+ * @description Sends a greeting to Poke every hour.
+ * @interval 1h
+ */
+
+import { Poke, getToken } from "poke";
+
+const token = getToken();
+if (!token) {
+  console.error("Not signed in. Run: npx poke login");
+  process.exit(1);
+}
+
+const poke = new Poke({ apiKey: token });
+await poke.sendMessage("Hello! This is an automated message from my Hello agent.");
+
+console.log("Sent greeting to Poke.");
+```
+
+## Step 4: Add env variables (optional)
+
+If your agent needs secrets (API tokens, URLs, etc.), create a `.env.<name>` file:
+
+```bash
+nano ~/.config/poke-gate/agents/.env.hello
+```
+
+```env
+# My custom config
+MY_API_KEY=secret_123
+```
+
+Then read them in your script:
+
+```javascript
+const apiKey = process.env.MY_API_KEY;
+```
+
+## Step 5: Test it
+
+Run your agent manually:
+
+```bash
+npx poke-gate run-agent hello
+```
+
+You should see:
+
+```
+[agents] Running agent: hello (hello.1h.js)
+[agents] [hello] Sent greeting to Poke.
+[agents] [hello] completed
+```
+
+## Step 6: Let it run
+
+Start Poke Gate normally. Your agent will be discovered and scheduled:
+
+```bash
+npx poke-gate
+```
+
+```
+[agents] Found 1 agent(s):
+  Hello World (every 1h)
+[agents] Running agent: hello (hello.1h.js)
+```
+
+## Tips
+
+- **Keep agents fast.** They have a 5-minute timeout. If your agent takes longer, it'll be killed.
+- **Use `console.log`** for debugging. Output appears in the Poke Gate logs.
+- **Handle errors gracefully.** If your agent throws, it logs the error and continues to the next scheduled run.
+- **Change the interval** by renaming the file (e.g. `hello.1h.js` → `hello.30m.js`) or using the macOS Agents editor.
+
+## Template
+
+Here's a minimal template to copy:
+
+```javascript
+/**
+ * @agent my-agent
+ * @name My Agent
+ * @description What this agent does.
+ * @interval 1h
+ */
+
+import { Poke, getToken } from "poke";
+
+const poke = new Poke({ apiKey: getToken() });
+
+// Your logic here
+const result = "Something useful";
+
+await poke.sendMessage(result);
+console.log("Done.");
+```

package/docs/agents/index.md

@@ -0,0 +1,85 @@
+# Agents
+
+Agents are scheduled scripts that **push information from your computer to Poke**. They run in the background, gather data from local sources (APIs, files, services), and send it to your Poke agent — so Poke learns about what's happening on your machine without you asking.
+
+Think of it this way: **Tools** let Poke pull from your machine (you ask, Poke acts). **Agents** let your machine push to Poke (your computer tells Poke, Poke learns and replies).
+
+::: tip Secure and deterministic
+Agents are **push-only** — they send data to Poke, but Poke cannot reach back into the agent or your computer through them. Each agent is a plain JavaScript file that you write and control. It runs the same way every time, with no AI decision-making involved. The agent doesn't "try" to access your machine — it only does exactly what the script says. This makes agents predictable, auditable, and safe.
+:::
+
+```mermaid
+flowchart LR
+    subgraph YourMac ["Your Mac"]
+        Agent["Agent script"]
+        Local["Local data source"]
+        Local -->|reads| Agent
+    end
+
+    Agent -->|sendMessage| Poke["Poke Agent"]
+    Poke -->|replies| You["You"]
+```
+
+**Example:** A Beeper agent runs every hour, fetches your unread messages, and sends a digest to Poke. Now Poke knows who messaged you — and can answer "did anyone text me?" without needing your machine in real time.
+
+## How agents work
+
+1. You place a `.js` file in `~/.config/poke-gate/agents/`
+2. The filename defines the schedule: `name.interval.js`
+3. When Poke Gate connects, it discovers all agents and starts their timers
+4. Each agent runs once immediately, then repeats on schedule
+5. Agents use the Poke SDK to send messages — pushing data to your agent
+
+## 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 |
+| `digest.24h.js` | Every 24 hours |
+
+**Intervals:** `Nm` (minutes) or `Nh` (hours). Minimum is **10 minutes**.
+
+## Frontmatter
+
+Each agent 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.
+ * @interval 1h
+ * @env BEEPER_TOKEN - Beeper Desktop local API token
+ * @author f
+ */
+```
+
+The `@name` and `@description` are shown in the macOS app's Agents editor and in the scheduler logs.
+
+## Per-agent env files
+
+Each agent can have a `.env.<name>` file in the same directory:
+
+```
+~/.config/poke-gate/agents/.env.beeper
+```
+
+```env
+BEEPER_TOKEN=your_token_here
+BEEPER_BASE_URL=http://localhost:23373
+```
+
+Variables are injected into the agent's environment automatically. The agent reads them via `process.env.BEEPER_TOKEN`.
+
+## What's next?
+
+- [Creating Agents](/agents/creating) — write your first agent from scratch
+- [Installing Agents](/agents/installing) — download community agents
+- [Beeper Example](/agents/beeper) — full walkthrough of a real agent