SKILL.md- the skill, written out in plain English

criteria:
  - name: calls_send_imessage
    kind: deterministic
    check: "The skill execution log must contain a call to the sendIMessage() function. (e.g., check 'state/log/pending-eval.ndjson' for relevant entries indicating function calls)."
  - name: calls_read_recent
    kind: deterministic
    check: "The skill execution log must contain a call to the readRecent() function. (e.g., check 'state/log/pending-eval.ndjson' for relevant entries indicating function calls)."
  - name: output_matches_imessage_api
    kind: judge
    check: "The output of the skill, particularly from readRecent(), should reflect a structure consistent with the iMessage API as defined in 'state/lib/imessage.ts', exhibiting correct message formats and recipient/sender information."
  - name: side_effects_honest
    kind: judge
    check: "Any iMessage sent via sendIMessage() should be verifiable on the target device, and readRecent() should accurately reflect recent messages without unexpected side effects."

AGENTS.md- what the AI loads when this skill comes up

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-imessage/api.ts -- iMessage reading from local SQLite + sending via osascript.
 *
 * Reads: local ~/Library/Messages/chat.db via better-sqlite3
 * Sends: osascript to Messages.app
 *
 * Usage:
 *   npx tsx api.ts send +14155551212 "Hey, checking in!"
 *   npx tsx api.ts list 5
 *   npx tsx api.ts list-contact "+14155551212" 5
 *
 * Or import as module:
 *   import { sendIMessage, readRecent } from "./imessage.ts";
 */

import { execSync } from "child_process";
import { env } from "./env.ts";
import { realpathSync, existsSync } from "fs";
import { homedir } from "os";

export interface IMessageData {
  contact: string;
  text: string;
  timestamp: number;
  guid: string;
}

// Load better-sqlite3 dynamically
let Database: any = null;
async function loadDatabase() {
  if (Database) return Database;
  try {
    Database = (await import("better-sqlite3")).default;
    return Database;
  } catch {
    return null;
  }
}

/**
 * Read recent messages from local Messages SQLite database.
 * Gracefully returns error structure if DB unavailable or access denied.
 */
export async function readRecent(contact?: string, limit = 10): Promise<{ messages: IMessageData[]; not_connected?: boolean; hint?: string }> {
  const DB = await loadDatabase();
  if (!DB) {
    return {
      messages: [],
      not_connected: true,
      hint: "better-sqlite3 not available",
    };
  }

  const dbPath = `${homedir()}/Library/Messages/chat.db`;

  if (!existsSync(dbPath)) {
    return {
      messages: [],
      not_connected: true,
      hint: "Messages database not found at ~/Library/Messages/chat.db. Grant Full Disk Access to Terminal in System Settings → Privacy & Security.",
    };
  }

  try {
    const db = new DB(dbPath, { readonly: true });

    // Query: get last N messages, optionally filtered by contact
    // Apple's Messages schema:
    // - message.ROWID, text, attributedBody, date (nanoseconds since 2001-01-01)
    // - handle.ROWID, id (phone/email)
    // - chat_message_join maps messages to chats
    // - chat.ROWID, guid (group UUID), display_name

    let query = `
      SELECT
        m.ROWID as rowid,
        m.text,
        m.date,
        COALESCE(h.id, '') as contact_id,
        COALESCE(c.display_name, '') as chat_name
      FROM message m
      LEFT JOIN handle h ON m.handle_id = h.ROWID
      LEFT JOIN chat_message_join cmj ON m.ROWID = cmj.message_id
      LEFT JOIN chat c ON cmj.chat_id = c.ROWID
      WHERE 1=1
    `;

    const params: any[] = [];

    if (contact) {
      query += ` AND (h.id LIKE ? OR c.display_name LIKE ?)`;
      const pattern = `%${contact}%`;
      params.push(pattern, pattern);
    }

    query += ` ORDER BY m.date DESC LIMIT ?`;
    params.push(limit);

    const stmt = db.prepare(query);
    const rows = stmt.all(...params);

    db.close();

    // Convert to IMessageData format
    const messages: IMessageData[] = rows
      .map((row: any) => {
        // Use text field only; attributedBody is NSAttributedString binary that's hard to decode
        const text = (row.text || "").trim();

        // Skip empty messages
        if (!text) return null;

        // Convert Apple's absolute timestamp (nanoseconds since 2001-01-01) to unix ms
        // row.date is in nanoseconds relative to 2001-01-01 00:00:00 UTC
        // Seconds since 2001-01-01 to 1970-01-01: 978307200 seconds (31 years + 8 leap days)
        const appleEpochSecs = 978307200;
        const unixMs = (row.date / 1000000000) * 1000 + (appleEpochSecs * 1000); // convert nanos to ms

        // Prefer explicit contact ID over group name; both may be empty for system messages
        const sender = row.contact_id || row.chat_name || "Unknown";

        return {
          contact: sender,
          text: text,
          timestamp: Math.round(unixMs),
          guid: `imessage-${row.rowid}`,
        };
      })
      .filter((m: any) => m !== null);

    return { messages };
  } catch (err: any) {
    const msg = err?.message || String(err);
    if (msg.includes("SQLITE_CANTOPEN") || msg.includes("cannot open")) {
      return {
        messages: [],
        not_connected: true,
        hint: "Full Disk Access required for Terminal. Grant it in System Settings → Privacy & Security → Full Disk Access.",
      };
    }
    return {
      messages: [],
      not_connected: true,
      hint: `iMessage read failed: ${msg}`,
    };
  }
}

/** Send an iMessage via osascript (requires Messages.app open). */
export function sendIMessage(to: string, text: string): void {
  if (!/^\+\d{10,15}$/.test(to)) {
    throw new Error(`Invalid E.164 phone number: ${to}`);
  }
  const escapedText = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
  const cmd = `osascript -e 'tell application "Messages" to send "${escapedText}" to buddy "${to}" of (service 1 whose service type is iMessage)'`;
  execSync(cmd, { encoding: "utf-8", timeout: 10_000 });
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "send": {
        const [to, ...textParts] = args;
        if (!to || !textParts.length) { console.error("Usage: api.ts send <phone> <text>"); process.exit(1); }
        try {
          sendIMessage(to, textParts.join(" "));
          console.log("sent");
        } catch (e) {
          console.error("send failed:", e);
          process.exit(1);
        }
        break;
      }
      case "list": {
        const limitStr = args[0];
        const limit = limitStr ? parseInt(limitStr, 10) : 5;
        const result = await readRecent(undefined, limit);
        for (const msg of result.messages) {
          console.log(`${new Date(msg.timestamp).toISOString().slice(0, 16)}\t${msg.contact}\t${msg.text.slice(0, 80)}`);
        }
        if (result.not_connected) {
          console.warn(`⚠ ${result.hint}`);
          process.exit(1);
        }
        break;
      }
      case "list-contact": {
        const [contact, limitStr] = args;
        if (!contact) { console.error("Usage: api.ts list-contact <contact> [limit]"); process.exit(1); }
        const limit = limitStr ? parseInt(limitStr, 10) : 5;
        const result = await readRecent(contact, limit);
        for (const msg of result.messages) {
          console.log(`${new Date(msg.timestamp).toISOString().slice(0, 16)}\t${msg.contact}\t${msg.text.slice(0, 80)}`);
        }
        if (result.not_connected) {
          console.warn(`⚠ ${result.hint}`);
          process.exit(1);
        }
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [send|list|list-contact] ...");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet