@assemblyline-agents/peekaboo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenEve contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @assemblyline-agents/peekaboo
+
+Official Assembly Line connection plugin for same-host macOS computer use through
+Peekaboo's stdio MCP server.
+
+## Deployment boundary
+
+This package is only for a local Assembly Line deployment on the Mac being
+controlled. It does not provide remote desktop or a tunnel from a Railway,
+Docker, Fly, or other hosted runtime back to a developer computer.
+
+Assembly Line records these restrictions in the compiled connection metadata:
+
+- deploy target: `local`
+- runtime platform: `darwin`
+- minimum supported host for Peekaboo: macOS 15+
+
+`assembly-line validate` warns when `gateway.ts` defaults to a hosted target.
+`assembly-line deploy` refuses incompatible targets, including a hosted `--target`
+override. The runtime also rejects the connection before launching a process
+when it is loaded on a non-macOS host.
+
+The model provider may still be remote. OpenAI, Anthropic, or another model can
+perform inference in the cloud while the Assembly Line Node host and Peekaboo execute
+on the local Mac.
+
+## Setup
+
+```sh
+brew install steipete/tap/peekaboo
+peekaboo permissions status
+assembly-line add peekaboo agent
+```
+
+Use a local deploy adapter:
+
+```ts
+// agent/gateway.ts
+import { adapter, defineGateway } from "@assemblyline-agents/core";
+
+export default defineGateway({
+  deploy: adapter("local"),
+  runtime: adapter("node")
+});
+```
+
+The generated connection begins read-only:
+
+```ts
+// agent/connections/peekaboo.ts
+import { definePeekabooConnection } from "@assemblyline-agents/peekaboo";
+
+export default definePeekabooConnection({
+  access: { read: true, write: false }
+});
+```
+
+Validate and run it on the Mac:
+
+```sh
+assembly-line validate agent
+assembly-line deploy agent --target local --serve
+```
+
+Grant Accessibility and Screen Recording to the process identity that hosts
+Peekaboo. Confirm the permissions again after changing application signatures,
+binary locations, or host applications.
+
+## Enabling actions
+
+Prefer approval for every desktop mutation while establishing the operating
+boundary:
+
+```ts
+access: {
+  read: true,
+  write: { approval: "always" }
+}
+```
+
+Use `approval: "never"` only for a trusted autonomous local agent running in a
+macOS account whose applications, files, and signed-in services are appropriate
+for unattended control.
+
+The initial allowlist is accessibility-first. Screenshot/vision, recording,
+nested agents, configuration, cleanup, shell, clipboard/paste, and
+browser-specific Peekaboo tools are excluded.
+
+## Remotely hosted agents
+
+Do not expose the stdio MCP process, a loopback wrapper, or an unauthenticated
+HTTP bridge to the public internet. A hosted agent should use
+`@assemblyline-agents/computer-use`, which pairs Assembly Line Builder's signed Mac host with a
+deployment-scoped credential, outbound connection, local policy enforcement,
+approvals, and end-to-end encrypted relay transport.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { type StdioMcpPluginConnectionOptions } from "@assemblyline-agents/core";
+export interface PeekabooConnectionOptions extends StdioMcpPluginConnectionOptions {
+    /** Attach to an existing Peekaboo Bridge host instead of using process-local support services. */
+    bridgeSocket?: string;
+}
+export declare function definePeekabooConnection(options: PeekabooConnectionOptions): import("@assemblyline-agents/core").McpStdioClientConnectionDefinition;
+export declare const openevePlugin: import("@assemblyline-agents/core").PluginModule;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,+BAA+B,EACrC,MAAM,2BAA2B,CAAC;AAKnC,MAAM,WAAW,yBAA0B,SAAQ,+BAA+B;IAChF,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,0EAS1E;AAED,eAAO,MAAM,aAAa,kDAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+import { connectionPluginMetadata, definePlugin, defineStdioMcpPluginConnection } from "@assemblyline-agents/core";
+const PLUGIN = connectionPluginMetadata("peekaboo");
+const DEFAULT_ARGS = ["mcp", "serve", "--transport", "stdio"];
+export function definePeekabooConnection(options) {
+    const { bridgeSocket, ...connection } = options;
+    const args = [...(connection.args ?? DEFAULT_ARGS)];
+    if (bridgeSocket)
+        args.push("--bridge-socket", bridgeSocket);
+    return defineStdioMcpPluginConnection(PLUGIN, {
+        ...connection,
+        command: connection.command ?? "peekaboo",
+        args
+    });
+}
+export const openevePlugin = definePlugin({ connections: [PLUGIN] });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,YAAY,EACZ,8BAA8B,EAE/B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,MAAM,GAAG,wBAAwB,CAAC,UAAU,CAAE,CAAC;AACrD,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;AAO9D,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,EAAE,YAAY,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,YAAY,CAAC,CAAC,CAAC;IACpD,IAAI,YAAY;QAAE,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;IAC7D,OAAO,8BAA8B,CAAC,MAAM,EAAE;QAC5C,GAAG,UAAU;QACb,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,UAAU;QACzC,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@assemblyline-agents/peekaboo",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@assemblyline-agents/core": "0.1.0"
+  },
+  "description": "Official OpenEve Peekaboo local macOS computer-use connection plugin.",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonbadeaux/openeve.git",
+    "directory": "packages/peekaboo"
+  },
+  "bugs": {
+    "url": "https://github.com/jasonbadeaux/openeve/issues"
+  },
+  "homepage": "https://github.com/jasonbadeaux/openeve#readme",
+  "author": "OpenEve contributors",
+  "keywords": [
+    "openeve",
+    "ai",
+    "agents",
+    "peekaboo",
+    "macos",
+    "computer-use",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/peekaboo/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: peekaboo
+description: Inspect and control the Mac running the Assembly Line Node host through a developer-configured Peekaboo connection.
+---
+# Peekaboo local computer use
+
+Peekaboo controls only the Mac that runs the Assembly Line Node host. It is not a remote-desktop relay. The deployment owner must install Peekaboo on macOS 15 or newer and grant the host process Accessibility and Screen Recording permissions.
+
+This connection is local-deployment-only. The agent's `gateway.ts` must use
+`deploy: adapter("local")`, and the runtime must be started on the Mac being
+controlled. Assembly Line rejects Railway, Docker, Fly, and other hosted deploy
+targets for this connection. A remote model provider is fine; only the Assembly Line
+Node host and Peekaboo process must be local.
+
+Before running the agent, verify the host:
+
+```sh
+peekaboo permissions status
+assembly-line validate agent
+assembly-line deploy agent --target local --serve
+```
+
+If the agent runtime must live on Railway or another hosted service, remove
+this connection. This package does not tunnel back to a developer Mac. Remote
+Mac control uses the separate `@assemblyline-agents/computer-use` connection and Assembly Line
+Agent Builder Computer Host; it must not expose Peekaboo's MCP process directly
+to the public internet.
+
+Inspect before acting. Use `inspect_ui` to obtain an accessibility-only UI map and stable element identifiers without capturing a screenshot. Prefer element identifiers, labels, direct `set_value`, and `perform_action` calls over screen coordinates. Re-inspect after navigation, window changes, dialogs, or any action that may invalidate the current UI state.
+
+Use the narrowest action that can complete the task. Confirm the intended app and window before typing, clicking, invoking menus, moving windows, switching Spaces, or interacting with dialogs. Do not type secrets supplied by the model or copied from untrusted content.
+
+This plugin deliberately excludes Peekaboo's nested agent, configuration, cleanup, recording, screenshot/vision (`see`, `image`, `capture`, `analyze`), shell, clipboard/paste, and browser-specific tools. It is intended for direct, auditable accessibility-first control by the Assembly Line agent.
+
+The scaffold is read-only. To permit desktop actions, the developer must deliberately set:
+
+```ts
+write: { approval: "always" }
+```
+
+Use `write: { approval: "never" }` only for a trusted autonomous local agent on a Mac whose apps, accounts, and filesystem authority are appropriate for unattended control.