@openparachute/agent 0.1.0

package/container/agent-runner/src/scheduling/task-script.ts

@@ -0,0 +1,121 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { MessageInRow } from '../db/messages-in.js';
+import { touchHeartbeat } from '../db/connection.js';
+
+const SCRIPT_TIMEOUT_MS = 30_000;
+const SCRIPT_MAX_BUFFER = 1024 * 1024;
+
+export interface ScriptResult {
+  wakeAgent: boolean;
+  data?: unknown;
+}
+
+function log(msg: string): void {
+  console.error(`[task-script] ${msg}`);
+}
+
+export async function runScript(script: string, taskId: string): Promise<ScriptResult | null> {
+  const scriptPath = path.join('/tmp', `task-script-${taskId}.sh`);
+  fs.writeFileSync(scriptPath, script, { mode: 0o755 });
+
+  return new Promise((resolve) => {
+    execFile(
+      'bash',
+      [scriptPath],
+      { timeout: SCRIPT_TIMEOUT_MS, maxBuffer: SCRIPT_MAX_BUFFER, env: process.env },
+      (error, stdout, stderr) => {
+        try {
+          fs.unlinkSync(scriptPath);
+        } catch {
+          /* best-effort cleanup */
+        }
+
+        if (stderr) {
+          log(`[${taskId}] stderr: ${stderr.slice(0, 500)}`);
+        }
+
+        if (error) {
+          log(`[${taskId}] error: ${error.message}`);
+          return resolve(null);
+        }
+
+        const lines = stdout.trim().split('\n');
+        const lastLine = lines[lines.length - 1];
+        if (!lastLine) {
+          log(`[${taskId}] no output`);
+          return resolve(null);
+        }
+
+        try {
+          const result = JSON.parse(lastLine);
+          if (typeof result.wakeAgent !== 'boolean') {
+            log(`[${taskId}] output missing wakeAgent boolean: ${lastLine.slice(0, 200)}`);
+            return resolve(null);
+          }
+          resolve(result as ScriptResult);
+        } catch {
+          log(`[${taskId}] output is not valid JSON: ${lastLine.slice(0, 200)}`);
+          resolve(null);
+        }
+      },
+    );
+  });
+}
+
+export interface TaskScriptOutcome {
+  keep: MessageInRow[];
+  skipped: string[];
+}
+
+/**
+ * Run pre-task scripts for any task messages that carry one, serially.
+ * - Errors / missing output / wakeAgent=false → task id added to `skipped`.
+ * - wakeAgent=true → content JSON is mutated to carry `scriptOutput`, so the
+ *   formatter renders it into the prompt.
+ * Non-task messages and tasks without scripts pass through unchanged.
+ */
+export async function applyPreTaskScripts(messages: MessageInRow[]): Promise<TaskScriptOutcome> {
+  const keep: MessageInRow[] = [];
+  const skipped: string[] = [];
+
+  for (const msg of messages) {
+    if (msg.kind !== 'task') {
+      keep.push(msg);
+      continue;
+    }
+
+    let content: Record<string, unknown>;
+    try {
+      content = JSON.parse(msg.content);
+    } catch {
+      keep.push(msg);
+      continue;
+    }
+
+    const script = typeof content.script === 'string' ? (content.script as string) : null;
+    if (!script) {
+      keep.push(msg);
+      continue;
+    }
+
+    log(`running script for task ${msg.id}`);
+    touchHeartbeat();
+    const result = await runScript(script, msg.id);
+    touchHeartbeat();
+
+    if (!result || !result.wakeAgent) {
+      const reason = result ? 'wakeAgent=false' : 'script error/no output';
+      log(`task ${msg.id} skipped: ${reason}`);
+      skipped.push(msg.id);
+      continue;
+    }
+
+    log(`task ${msg.id} wakeAgent=true, enriching prompt`);
+    content.scriptOutput = result.data ?? null;
+    keep.push({ ...msg, content: JSON.stringify(content) });
+  }
+
+  return { keep, skipped };
+}

package/container/agent-runner/src/timezone.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'bun:test';
+
+import { formatLocalTime, isValidTimezone, parseZonedToUtc, resolveTimezone } from './timezone.js';
+
+// --- formatLocalTime ---
+
+describe('formatLocalTime', () => {
+  it('converts UTC to local time display', () => {
+    // 2026-02-04T18:30:00Z in America/New_York (EST, UTC-5) = 1:30 PM
+    const result = formatLocalTime('2026-02-04T18:30:00.000Z', 'America/New_York');
+    expect(result).toContain('1:30');
+    expect(result).toContain('PM');
+    expect(result).toContain('Feb');
+    expect(result).toContain('2026');
+  });
+
+  it('handles different timezones', () => {
+    // Same UTC time should produce different local times
+    const utc = '2026-06-15T12:00:00.000Z';
+    const ny = formatLocalTime(utc, 'America/New_York');
+    const tokyo = formatLocalTime(utc, 'Asia/Tokyo');
+    // NY is UTC-4 in summer (EDT), Tokyo is UTC+9
+    expect(ny).toContain('8:00');
+    expect(tokyo).toContain('9:00');
+  });
+
+  it('does not throw on invalid timezone, falls back to UTC', () => {
+    expect(() => formatLocalTime('2026-01-01T00:00:00.000Z', 'IST-2')).not.toThrow();
+    const result = formatLocalTime('2026-01-01T12:00:00.000Z', 'IST-2');
+    // Should format as UTC (noon UTC = 12:00 PM)
+    expect(result).toContain('12:00');
+    expect(result).toContain('PM');
+  });
+});
+
+describe('isValidTimezone', () => {
+  it('accepts valid IANA identifiers', () => {
+    expect(isValidTimezone('America/New_York')).toBe(true);
+    expect(isValidTimezone('UTC')).toBe(true);
+    expect(isValidTimezone('Asia/Tokyo')).toBe(true);
+    expect(isValidTimezone('Asia/Jerusalem')).toBe(true);
+  });
+
+  it('rejects invalid timezone strings', () => {
+    expect(isValidTimezone('IST-2')).toBe(false);
+    expect(isValidTimezone('XYZ+3')).toBe(false);
+  });
+
+  it('rejects empty and garbage strings', () => {
+    expect(isValidTimezone('')).toBe(false);
+    expect(isValidTimezone('NotATimezone')).toBe(false);
+  });
+});
+
+describe('resolveTimezone', () => {
+  it('returns the timezone if valid', () => {
+    expect(resolveTimezone('America/New_York')).toBe('America/New_York');
+  });
+
+  it('falls back to UTC for invalid timezone', () => {
+    expect(resolveTimezone('IST-2')).toBe('UTC');
+    expect(resolveTimezone('')).toBe('UTC');
+  });
+});
+
+describe('parseZonedToUtc', () => {
+  it('passes strings with Z suffix through unchanged', () => {
+    const d = parseZonedToUtc('2026-01-15T09:00:00Z', 'America/New_York');
+    expect(d.toISOString()).toBe('2026-01-15T09:00:00.000Z');
+  });
+
+  it('passes strings with numeric offset through unchanged', () => {
+    const d = parseZonedToUtc('2026-01-15T09:00:00+02:00', 'America/New_York');
+    expect(d.toISOString()).toBe('2026-01-15T07:00:00.000Z');
+  });
+
+  it('interprets naive ISO as wall-clock in the given timezone', () => {
+    // 09:00 naive in NY in January = 09:00 EST = 14:00 UTC
+    const d = parseZonedToUtc('2026-01-15T09:00:00', 'America/New_York');
+    expect(d.toISOString()).toBe('2026-01-15T14:00:00.000Z');
+  });
+
+  it('handles a different positive-offset zone', () => {
+    // 09:00 naive in Tokyo (UTC+9) = 00:00 UTC
+    const d = parseZonedToUtc('2026-06-15T09:00:00', 'Asia/Tokyo');
+    expect(d.toISOString()).toBe('2026-06-15T00:00:00.000Z');
+  });
+
+  it('treats invalid timezone as UTC', () => {
+    const d = parseZonedToUtc('2026-01-15T09:00:00', 'NotATimezone');
+    expect(d.toISOString()).toBe('2026-01-15T09:00:00.000Z');
+  });
+});

package/container/agent-runner/src/timezone.ts

@@ -0,0 +1,107 @@
+/**
+ * Timezone utilities — mirror of src/timezone.ts (host).
+ *
+ * The container can't import from src/ (separate tsconfig, different runtime).
+ * Kept deliberately byte-aligned with the host module so behaviour is the
+ * same on both sides of the session-DB boundary.
+ *
+ * TIMEZONE is resolved once at module load from process.env.TZ (which the host
+ * sets from its own TIMEZONE constant when spawning the container; see
+ * src/container-runner.ts). Invalid values fall back to UTC.
+ */
+
+/**
+ * Check whether a timezone string is a valid IANA identifier
+ * that Intl.DateTimeFormat can use.
+ */
+export function isValidTimezone(tz: string): boolean {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the given timezone if valid IANA, otherwise fall back to UTC.
+ */
+export function resolveTimezone(tz: string): string {
+  return isValidTimezone(tz) ? tz : 'UTC';
+}
+
+/**
+ * Convert a UTC ISO timestamp to a localized display string.
+ * Uses the Intl API (no external dependencies).
+ * Falls back to UTC if the timezone is invalid.
+ */
+export function formatLocalTime(utcIso: string, timezone: string): string {
+  const date = new Date(utcIso);
+  return date.toLocaleString('en-US', {
+    timeZone: resolveTimezone(timezone),
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  });
+}
+
+function resolveContainerTimezone(): string {
+  const candidates = [process.env.TZ, Intl.DateTimeFormat().resolvedOptions().timeZone];
+  for (const tz of candidates) {
+    if (tz && isValidTimezone(tz)) return tz;
+  }
+  return 'UTC';
+}
+
+export const TIMEZONE = resolveContainerTimezone();
+
+/**
+ * Interpret a naive ISO-like timestamp (no trailing `Z`, no offset) as wall-clock
+ * time in `tz` and return the corresponding UTC Date. Strings that already carry
+ * offset info (`Z` or `±HH:MM`) are passed through to the Date constructor
+ * unchanged.
+ *
+ * Algorithm: treat the naive string as UTC, ask Intl.DateTimeFormat what that
+ * UTC instant is called in `tz`, then invert the offset. Near DST boundaries
+ * this can be off by an hour for ~1h of wall-clock time per year; acceptable
+ * for scheduling where the agent normally picks round-hour targets.
+ */
+export function parseZonedToUtc(input: string, tz: string): Date {
+  const hasOffset = /Z$|[+-]\d{2}:?\d{2}$/.test(input.trim());
+  if (hasOffset) return new Date(input);
+
+  const zone = resolveTimezone(tz);
+  const asIfUtc = new Date(input + 'Z');
+  if (Number.isNaN(asIfUtc.getTime())) return asIfUtc;
+
+  const fmt = new Intl.DateTimeFormat('en-US', {
+    timeZone: zone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+  const parts = Object.fromEntries(
+    fmt
+      .formatToParts(asIfUtc)
+      .filter((p) => p.type !== 'literal')
+      .map((p) => [p.type, p.value]),
+  );
+  const hour = parts.hour === '24' ? '00' : parts.hour;
+  const zonedAsUtcMs = Date.UTC(
+    Number(parts.year),
+    Number(parts.month) - 1,
+    Number(parts.day),
+    Number(hour),
+    Number(parts.minute),
+    Number(parts.second),
+  );
+  const offsetMs = zonedAsUtcMs - asIfUtc.getTime();
+  return new Date(asIfUtc.getTime() - offsetMs);
+}

package/container/agent-runner/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+}

package/container/build.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Build the parachute-agent container image.
+#
+# Reads one optional build flag from ../.env:
+#   INSTALL_CJK_FONTS=true   — add Chinese/Japanese/Korean fonts (~200MB)
+# Callers can also override by exporting INSTALL_CJK_FONTS directly.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$SCRIPT_DIR"
+
+# Derive the image name from the project root so two parachute-agent installs
+# on the same host don't overwrite each other's `parachute-agent-image:latest`
+# tag. Mirrors src/install-slug.ts (sha1(projectRoot)[:8]) — kept inline here
+# so this script has no source-time dependency on the JS/TS toolchain.
+if command -v shasum >/dev/null 2>&1; then
+    INSTALL_SLUG="$(printf '%s' "$PROJECT_ROOT" | shasum -a 1 | cut -c1-8)"
+else
+    INSTALL_SLUG="$(printf '%s' "$PROJECT_ROOT" | sha1sum | cut -c1-8)"
+fi
+IMAGE_NAME="parachute-agent-image-${INSTALL_SLUG}"
+TAG="${1:-latest}"
+CONTAINER_RUNTIME="${CONTAINER_RUNTIME:-docker}"
+
+# Caller's env takes precedence; fall back to .env.
+if [ -z "${INSTALL_CJK_FONTS:-}" ] && [ -f "../.env" ]; then
+    INSTALL_CJK_FONTS="$(grep '^INSTALL_CJK_FONTS=' ../.env | tail -n1 | cut -d= -f2- | tr -d '"' | tr -d "'" | tr -d '[:space:]')"
+fi
+
+BUILD_ARGS=()
+if [ "${INSTALL_CJK_FONTS:-false}" = "true" ]; then
+    echo "CJK fonts: enabled (adds ~200MB)"
+    BUILD_ARGS+=(--build-arg INSTALL_CJK_FONTS=true)
+fi
+
+echo "Building parachute-agent container image..."
+echo "Image: ${IMAGE_NAME}:${TAG}"
+
+${CONTAINER_RUNTIME} build "${BUILD_ARGS[@]}" -t "${IMAGE_NAME}:${TAG}" .
+
+echo ""
+echo "Build complete!"
+echo "Image: ${IMAGE_NAME}:${TAG}"
+echo ""
+echo "Test with:"
+echo "  echo '{\"prompt\":\"What is 2+2?\",\"groupFolder\":\"test\",\"chatJid\":\"test@g.us\",\"isMain\":false}' | ${CONTAINER_RUNTIME} run -i ${IMAGE_NAME}:${TAG}"

package/container/entrypoint.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Paraclaw agent container entrypoint.
+#
+# The host passes initial session parameters via stdin as a single JSON blob,
+# then the agent-runner opens the session DBs at /workspace/{inbound,outbound}.db
+# and enters its poll loop. All further IO flows through those DBs.
+#
+# We capture stdin to a file first so /tmp/input.json is available for
+# post-mortem inspection if the container exits unexpectedly, then exec bun
+# so that bun becomes PID 1's direct child (under tini) and receives signals.
+
+set -e
+
+cat > /tmp/input.json
+
+exec bun run /app/src/index.ts < /tmp/input.json

package/container/skills/agent-browser/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: agent-browser
+description: Browse the web for any task — research topics, read articles, interact with web apps, fill forms, take screenshots, extract data, and test web pages. Use whenever a browser would be useful, not just when the user explicitly asks.
+allowed-tools: Bash(agent-browser:*)
+---
+
+# Browser Automation with agent-browser
+
+## Quick start
+
+```bash
+agent-browser open <url>        # Navigate to page
+agent-browser snapshot -i       # Get interactive elements with refs
+agent-browser click @e1         # Click element by ref
+agent-browser fill @e2 "text"   # Fill input by ref
+agent-browser close             # Close browser
+```
+
+## Core workflow
+
+1. Navigate: `agent-browser open <url>`
+2. Snapshot: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`)
+3. Interact using refs from the snapshot
+4. Re-snapshot after navigation or significant DOM changes
+
+## Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>      # Navigate to URL
+agent-browser back            # Go back
+agent-browser forward         # Go forward
+agent-browser reload          # Reload page
+agent-browser close           # Close browser
+```
+
+### Snapshot (page analysis)
+
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (recommended)
+agent-browser snapshot -c         # Compact output
+agent-browser snapshot -d 3       # Limit depth to 3
+agent-browser snapshot -s "#main" # Scope to CSS selector
+```
+
+### Interactions (use @refs from snapshot)
+
+```bash
+agent-browser click @e1           # Click
+agent-browser dblclick @e1        # Double-click
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown option
+agent-browser scroll down 500     # Scroll page
+agent-browser upload @e1 file.pdf # Upload files
+```
+
+### Get information
+
+```bash
+agent-browser get text @e1        # Get element text
+agent-browser get html @e1        # Get innerHTML
+agent-browser get value @e1       # Get input value
+agent-browser get attr @e1 href   # Get attribute
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+agent-browser get count ".item"   # Count matching elements
+```
+
+### Screenshots & PDF
+
+```bash
+agent-browser screenshot          # Save to temp directory
+agent-browser screenshot path.png # Save to specific path
+agent-browser screenshot --full   # Full page
+agent-browser pdf output.pdf      # Save as PDF
+```
+
+### Wait
+
+```bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern
+agent-browser wait --load networkidle      # Wait for network idle
+```
+
+### Semantic locators (alternative to refs)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find placeholder "Search" type "query"
+```
+
+### Authentication with saved state
+
+```bash
+# Login once
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "username"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Later: load saved state
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+### Cookies & Storage
+
+```bash
+agent-browser cookies                     # Get all cookies
+agent-browser cookies set name value      # Set cookie
+agent-browser cookies clear               # Clear cookies
+agent-browser storage local               # Get localStorage
+agent-browser storage local set k v       # Set value
+```
+
+### JavaScript
+
+```bash
+agent-browser eval "document.title"   # Run JavaScript
+```
+
+## Example: Form submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Example: Data extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e1  # Get product title
+agent-browser get attr @e2 href  # Get link URL
+agent-browser screenshot products.png
+```