@vox-ai-app/integrations 1.0.0 → 1.0.2

package/README.md

@@ -1,41 +1,38 @@
-# @vox-ai-app/vox-integrations
+# @vox-ai-app/integrations
 
 macOS system integrations for Vox: Apple Mail, Screen control, and iMessage. Each integration ships with tool implementations and LLM tool definitions.
 
-Requires macOS. Each integration needs specific system permissions granted by the user.
+- Initial release.## [1.0.0] - 2026-03-24- `openDb` / `closeDb` lifecycle.- WAL journal mode, foreign keys, auto-schema creation.- Initial SQLite-based persistence: conversations, messages, tasks, task activity.### Added## [1.0.2] - 2026-04-01- `checkpointId` type consistency.- `getAllSettings` return type (now returns object instead of array).### Fixed- Added migration system (`src/migrations/runner.js` + `001_initial_schema.js`).- Added new exports: `./tools`, `./settings`, `./mcp-servers`, `./schedules`, `./tool-secrets`, `./patterns`, `./vectors`.- Updated exports map: all repo modules now resolve to `./src/repos/*.js`.- Moved 9 repository files from flat `src/` into `src/repos/` subdirectory.### ChangedRequires macOS. Each integration needs specific system permissions granted by the user.
 
 ## Install
 
 ```sh
-npm install @vox-ai-app/vox-integrations
+npm install @vox-ai-app/integrations
 ```
 
 Peer dependency: `electron >= 28`
 
 ## Exports
 
-| Export                                        | Contents                      |
-| --------------------------------------------- | ----------------------------- |
-| `@vox-ai-app/vox-integrations`                | All exports                   |
-| `@vox-ai-app/vox-integrations/defs`           | All tool definitions          |
-| `@vox-ai-app/vox-integrations/mail`           | Mail functions                |
-| `@vox-ai-app/vox-integrations/screen`         | Screen capture + control      |
-| `@vox-ai-app/vox-integrations/screen/capture` | Capture only                  |
-| `@vox-ai-app/vox-integrations/screen/control` | Control only                  |
-| `@vox-ai-app/vox-integrations/screen/queue`   | Session acquire/release       |
-| `@vox-ai-app/vox-integrations/imessage`       | iMessage data, reply, service |
+| Export                                    | Contents                      |
+| ----------------------------------------- | ----------------------------- |
+| `@vox-ai-app/integrations`                | All exports                   |
+| `@vox-ai-app/integrations/defs/mail`      | Mail tool definitions         |
+| `@vox-ai-app/integrations/defs/screen`    | Screen tool definitions       |
+| `@vox-ai-app/integrations/defs/imessage`  | iMessage tool definitions     |
+| `@vox-ai-app/integrations/mail`           | Mail functions                |
+| `@vox-ai-app/integrations/screen`         | Screen capture + control      |
+| `@vox-ai-app/integrations/screen/capture` | Capture only                  |
+| `@vox-ai-app/integrations/screen/control` | Control only                  |
+| `@vox-ai-app/integrations/screen/queue`   | Session acquire/release       |
+| `@vox-ai-app/integrations/imessage`       | iMessage data, reply, service |
 
 ## Mail
 
 Requires **Automation permission** for Mail (System Settings → Privacy & Security → Automation).
 
 ```js
-import {
-  sendEmail,
-  readEmails,
-  searchContacts,
-  replyToEmail
-} from '@vox-ai-app/vox-integrations/mail'
+import { sendEmail, readEmails, searchContacts, replyToEmail } from '@vox-ai-app/integrations/mail'
 
 const emails = await readEmails({ account: 'Work', folder: 'INBOX', limit: 20 })
 await sendEmail({ to: 'user@example.com', subject: 'Hi', body: 'Hello.' })
@@ -45,7 +42,7 @@ await replyToEmail({ messageId: '...', body: 'Thanks!' })
 Tool definitions:
 
 ```js
-import { MAIL_TOOL_DEFINITIONS } from '@vox-ai-app/vox-integrations/defs'
+import { MAIL_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/mail'
 ```
 
 ## Screen
@@ -58,8 +55,8 @@ import {
   clickAt,
   typeText,
   getUiElements
-} from '@vox-ai-app/vox-integrations/screen'
-import { acquireScreen, releaseScreen } from '@vox-ai-app/vox-integrations/screen/queue'
+} from '@vox-ai-app/integrations/screen'
+import { acquireScreen, releaseScreen } from '@vox-ai-app/integrations/screen/queue'
 
 const session = await acquireScreen()
 try {
@@ -74,7 +71,7 @@ try {
 Tool definitions:
 
 ```js
-import { SCREEN_TOOL_DEFINITIONS } from '@vox-ai-app/vox-integrations/defs'
+import { SCREEN_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/screen'
 ```
 
 ## iMessage
@@ -84,7 +81,7 @@ Requires **Full Disk Access** (System Settings → Privacy & Security → Full D
 ### Tool use (read conversations, send messages)
 
 ```js
-import { listConversations, listContacts, sendReply } from '@vox-ai-app/vox-integrations/imessage'
+import { listConversations, listContacts, sendReply } from '@vox-ai-app/integrations/imessage'
 
 const conversations = listConversations()
 const contacts = listContacts()
@@ -94,7 +91,7 @@ await sendReply('+15551234567', 'Hello from Vox!')
 ### Gateway service (AI replies to incoming iMessages)
 
 ```js
-import { createIMessageService } from '@vox-ai-app/vox-integrations/imessage'
+import { createIMessageService } from '@vox-ai-app/integrations/imessage'
 
 const svc = createIMessageService({
   logger,
@@ -117,7 +114,7 @@ svc.start('my-passphrase')
 Tool definitions:
 
 ```js
-import { IMESSAGE_TOOL_DEFINITIONS } from '@vox-ai-app/vox-integrations/defs'
+import { IMESSAGE_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/imessage'
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vox-ai-app/integrations",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "license": "MIT",
   "description": "macOS integrations (Mail, Screen, iMessage) for Vox",
@@ -8,10 +8,9 @@
   "private": false,
   "exports": {
     ".": "./src/index.js",
-    "./defs": "./src/defs/index.js",
-    "./defs/mail": "./src/defs/mail.js",
-    "./defs/screen": "./src/defs/screen.js",
-    "./defs/imessage": "./src/defs/imessage.js",
+    "./defs/mail": "./src/mail/def.js",
+    "./defs/screen": "./src/screen/def.js",
+    "./defs/imessage": "./src/imessage/def.js",
     "./mail": "./src/mail/index.js",
     "./screen": "./src/screen/index.js",
     "./screen/capture": "./src/screen/capture/index.js",
@@ -36,7 +35,7 @@
     "electron": ">=28.0.0"
   },
   "dependencies": {
-    "@vox-ai-app/tools": "^1.0.0",
+    "@vox-ai-app/tools": "^1.0.1",
     "better-sqlite3": "^12.0.0"
   }
 }

package/src/imessage/mac/reply.js

@@ -3,9 +3,24 @@ import os from 'os'
 import path from 'path'
 import { promisify } from 'util'
 import { exec } from 'child_process'
+import { shell } from 'electron'
 
 const execAsync = promisify(exec)
 
+const isAutomationDeniedError = (err) => {
+  const msg = String(err?.message || err?.stderr || '').toLowerCase()
+  return (
+    msg.includes('not allowed to send apple events') ||
+    msg.includes('apple event handler failed') ||
+    msg.includes('-1743') ||
+    msg.includes('access not allowed')
+  )
+}
+
+const openMessagesAutomationSettings = () => {
+  shell.openExternal('x-apple.systempreferences:com.apple.preference.security?Privacy_Automation')
+}
+
 const writeTmp = async (content, ext) => {
   const file = path.join(os.tmpdir(), `vox_ims_${Date.now()}.${ext}`)
   await fs.writeFile(file, content, 'utf8')
@@ -62,6 +77,17 @@ end tell`
   try {
     await execAsync(`osascript "${scriptFile}"`, { timeout: 15_000 })
     console.info('[imessage] Reply sent to', handle, 'files:', filePaths.length)
+  } catch (err) {
+    if (isAutomationDeniedError(err)) {
+      openMessagesAutomationSettings()
+      throw Object.assign(
+        new Error(
+          'Vox needs permission to control Messages. Please grant it in System Settings → Privacy & Security → Automation → Vox → Messages.'
+        ),
+        { code: 'IMESSAGE_AUTOMATION_REQUIRED' }
+      )
+    }
+    throw err
   } finally {
     await fs.unlink(scriptFile).catch(() => {})
   }

package/src/imessage/mac/service.js

@@ -12,22 +12,6 @@ const REPLY_TIMEOUT_MS = 90_000
 const FDA_ERROR_MESSAGE =
   'Vox needs Full Disk Access to read Messages. Opening System Settings → Privacy & Security → Full Disk Access — please enable it for Vox and try again.'
 
-/**
- * Creates a self-contained iMessage watcher service.
- *
- * @param {object} opts
- * @param {(text: string, handle: string) => Promise<string|null>} opts.onMessage
- *   Called when a passphrase-matched message arrives. Must return the AI reply text (or null to skip reply).
- * @param {(text: string, handle: string) => void} [opts.onTranscript]
- *   Optional: called before onMessage, useful for emitting transcript events upstream.
- * @param {() => void} [opts.onOpenSettings]
- *   Optional: called when Full Disk Access is required. Default opens nothing.
- * @param {{ info: Function, warn: Function, error: Function }} [opts.logger]
- *   Optional: defaults to console.
- * @param {number} [opts.pollIntervalMs]
- *   Poll interval in ms. Default 3000.
- * @returns {{ start, stop, getPassphrase, listConversations, listContacts, openSettings }}
- */
 export const createIMessageService = ({
   onMessage,
   onTranscript,

package/src/mail/manage/mac/index.js

@@ -9,7 +9,7 @@ import {
 import { ensureAppleMailConfigured } from '../../shared/index.js'
 
 const runAs = async (script, signal) => {
-  await ensureAppleMailConfigured()
+  await ensureAppleMailConfigured(signal)
   const scriptFile = await writeTempScript(script, 'scpt')
   try {
     const { stdout } = await execAbortable(
@@ -53,7 +53,7 @@ export const replyToEmailMac = async (
   { messageId, body, replyAll = false, account },
   { signal } = {}
 ) => {
-  const bodyEsc = esc(body)
+  const bodyEsc = esc(body).replace(/\n/g, '" & return & "')
   const replyCmd = replyAll ? 'reply theMsg with reply to all' : 'reply theMsg'
   const senderLines = account
     ? [
@@ -83,7 +83,7 @@ export const replyToEmailMac = async (
   }
 }
 export const forwardEmailMac = async ({ messageId, to, body = '', account }, { signal } = {}) => {
-  const bodyEsc = esc(body)
+  const bodyEsc = esc(body).replace(/\n/g, '" & return & "')
   const senderLines = account
     ? [
         `  set acct to first account whose name contains "${esc(account)}"`,
@@ -205,11 +205,11 @@ export const createDraftMac = async (
       `  set acct to first account whose name contains "${esc(account)}"`,
       '  set addressesList to email addresses of acct',
       '  set senderAddr to item 1 of addressesList',
-      `  set msg to make new outgoing message with properties {subject:"${esc(subject)}", content:"${esc(body).replace(/\n/g, '\\n')}", visible:true, sender:senderAddr}`
+      `  set msg to make new outgoing message with properties {subject:"${esc(subject)}", content:"${esc(body).replace(/\n/g, '" & return & "')}", visible:true, sender:senderAddr}`
     )
   } else {
     lines.push(
-      `  set msg to make new outgoing message with properties {subject:"${esc(subject)}", content:"${esc(body).replace(/\n/g, '\\n')}", visible:true}`
+      `  set msg to make new outgoing message with properties {subject:"${esc(subject)}", content:"${esc(body).replace(/\n/g, '" & return & "')}", visible:true}`
     )
   }
   lines.push('  tell msg')

package/src/mail/send/mac/index.js

@@ -9,11 +9,11 @@ import {
 } from '@vox-ai-app/tools/exec'
 import { ensureAppleMailConfigured } from '../../shared/index.js'
 export const sendEmailMac = async (
-  { to, cc, bcc, subject, body, attachments, account },
+  { to, cc = [], bcc = [], subject, body, attachments = [], account },
   { signal } = {}
 ) => {
   await ensureAppleMailConfigured(signal)
-  const bodyEsc = esc(body).replace(/\n/g, '\\n')
+  const bodyEsc = esc(body).replace(/\n/g, '" & return & "')
   const lines = ['tell application "Mail"']
   if (account) {
     lines.push(