autark-cli 0.1.4 → 0.1.5

package/README.md

@@ -18,47 +18,53 @@ autark login send your@email.com
 autark login verify your@email.com --code 123456
 ```
 
-## Use
+## Runbook use
 
 Autark is ID-first. Use `product list` / `context` to discover IDs, then pass IDs for writes. `slug/H01` remains a convenience alias.
 
 ```sh
-# products
 autark product upsert --slug chrome-relay --name "Chrome Relay" --tagline "..."
 autark product list   # prints slug, visibility, id, name
 autark context chrome-relay
 
-autark context --product-id <product_id>
-
-# hypotheses
 autark hypothesis create --product-id <product_id> --md @./H01.md --code H01 --title "..."
-autark context --hypothesis-id <hypothesis_id>
-autark hypothesis status --hypothesis-id <hypothesis_id> --status active   # active|inactive|dead
-
-# aliases still work
-autark hypothesis create --product chrome-relay --md @./H01.md --code H01
-autark context chrome-relay/H01
-autark hypothesis status chrome-relay/H01 --status inactive
-
-# runs
 autark run start --hypothesis-id <hypothesis_id>
+autark log action --run-id <run_id> --channel github --title "..." --url https://github.com/...
 autark run finish --run-id <run_id> --narrative @./narrative.md
+```
 
-# actions (anything the agent did during a run)
-autark log action --run-id <run_id> --channel email --title "..." \
-  --recipient person@example.com --agentmail-thread-id <thread_id>
-autark log action --run-id <run_id> --channel github --title "..." --url https://github.com/...
+## Mail use
 
-autark me
-autark logout
+`autark mail` covers the AgentMail surface Autark needs. It does not require a separate AgentMail CLI login.
+
+```sh
+autark mail setup --prefix laksh
+
+autark mail send --run-id <run_id> \
+  --to person@example.com \
+  --subject "Subject" \
+  --text @./body.txt
+
+autark mail reply --run-id <run_id> --message-id <message_id> --text @./reply.txt
+
+autark mail threads --limit 20
+autark mail thread <thread_id>
+autark mail messages --limit 20
+autark mail message <message_id>
+autark mail raw <message_id>
+autark mail attachment --message-id <message_id> --attachment-id <attachment_id> --out file.bin
 ```
 
+Mail sends/replies call AgentMail directly with the user's inbox-scoped key from `~/.autark/credentials.json`, then log an Autark `email` action containing `agentmail_thread_id` and `agentmail_inbox_id`.
+
 ## ENV
 
 - `AUTARK_API_URL` — override the default Worker URL (`https://autark-api.kushalsokke.workers.dev`)
+- `AGENTMAIL_API_URL` — override AgentMail API base
+- `AGENTMAIL_API_KEY`, `AGENTMAIL_EMAIL`, `AGENTMAIL_INBOX_ID` — override local mail credentials for debugging
 
 ## Architecture
 
 The CLI is a thin HTTP client over a Cloudflare Worker that holds the InstantDB admin token. Magic-link auth via InstantDB. Token saved to `~/.autark/credentials.json` after login.
 
-The web at autark.kushalsm.com reads from InstantDB. Writes should go through the Worker/CLI path; dashboard direct writes are being phased out.
+The Worker uses the AgentMail org key only for provisioning and dashboard thread reads. Local mail send/reply uses the user's inbox-scoped key.

package/autark.mjs

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 // autark CLI — thin HTTP client over the autark-api Worker.
 //
-// Auth: magic-link flow saves a refresh_token to ~/.autark/credentials.json.
-// Every subsequent command sends it as `Authorization: Bearer <token>`.
-//
-// The CLI is ID-first: once a product/hypothesis/run exists, use its id.
-// slug/Hxx remains as a convenience alias for humans.
+// The runbook API is ID-first. slug/Hxx remains as a convenience alias.
+// Mail commands call AgentMail directly with the user's inbox-scoped key;
+// autark-api uses the org key only for provisioning and dashboard thread reads.
 
 import fs from 'node:fs'
 import os from 'node:os'
@@ -13,6 +11,7 @@ import path from 'node:path'
 import process from 'node:process'
 
 const API = process.env.AUTARK_API_URL || 'https://autark-api.kushalsokke.workers.dev'
+const AGENTMAIL_API = process.env.AGENTMAIL_API_URL || 'https://api.agentmail.to/v0'
 const CREDS_PATH = path.join(os.homedir(), '.autark', 'credentials.json')
 
 const args = process.argv.slice(2)
@@ -47,6 +46,7 @@ async function main() {
   }
   if (group === 'log' && command === 'action') return logAction(rest)
   if (group === 'context') return context([command, ...rest].filter(Boolean))
+  if (group === 'mail') return mail(command, rest)
 
   usage()
   process.exit(1)
@@ -69,6 +69,7 @@ async function loginVerify(rest) {
   const result = await api('POST', '/v1/auth/login/verify', { email, code }, { auth: false })
   if (!result.token) throw new Error('verify succeeded but no token returned')
   saveCredentials({
+    ...loadCredentials(),
     user_id: result.user.id,
     email:   result.user.email,
     token:   result.token,
@@ -194,15 +195,235 @@ async function logAction(rest) {
   const result = await api('POST', `/v1/runs/${encodeURIComponent(run)}/actions`, {
     channel,
     title,
-    url:                 opts.url || undefined,
-    agentmail_thread_id: opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
-    recipient:           opts.recipient || undefined,
-    metadata:            opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
-    occurred_at:         opts['occurred-at'] || opts.occurred_at || undefined,
+    url:                  opts.url || undefined,
+    agentmail_thread_id:  opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
+    agentmail_inbox_id:   opts['agentmail-inbox-id'] || opts.inbox_id || opts.agentmail_inbox_id || undefined,
+    recipient:            opts.recipient || undefined,
+    metadata:             opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
+    occurred_at:          opts['occurred-at'] || opts.occurred_at || undefined,
   })
   console.log(result.id)
 }
 
+// ============================================================ mail
+
+async function mail(command, rest) {
+  if (!command || command === '--help' || command === 'help') return mailUsage()
+  if (command === 'setup')     return mailSetup(rest)
+  if (command === 'send')      return mailSend(rest)
+  if (command === 'reply')     return mailReply(rest, 'reply')
+  if (command === 'reply-all') return mailReply(rest, 'reply-all')
+  if (command === 'forward')   return mailForward(rest)
+  if (command === 'threads')   return mailThreads(rest)
+  if (command === 'thread')    return mailThread(rest)
+  if (command === 'messages')  return mailMessages(rest)
+  if (command === 'message')   return mailMessage(rest)
+  if (command === 'raw')       return mailRaw(rest)
+  if (command === 'attachment') return mailAttachment(rest)
+  if (command === 'request')   return mailRequest(rest)
+  mailUsage()
+  process.exit(1)
+}
+
+async function mailSetup(rest) {
+  const opts = parseArgs(rest)
+  const existing = loadCredentials() || {}
+  if (existing.agentmail_token && existing.agentmail_email && !opts.force) {
+    console.log(existing.agentmail_email)
+    return
+  }
+  const prefix = required(opts.prefix || defaultInboxPrefix(existing.email), '--prefix')
+  const result = await api('POST', '/v1/onboard/agentmail', {
+    prefix,
+    display_name: opts['display-name'] || opts.display_name || existing.email || prefix,
+    purpose: opts.purpose || 'runner',
+  })
+  saveCredentials({
+    ...existing,
+    agentmail_email:      result.agentmail_email || result.email,
+    agentmail_inbox_id:   result.agentmail_inbox_id || result.inbox_id || result.email,
+    agentmail_api_key_id: result.agentmail_api_key_id || result.api_key_id,
+    agentmail_token:      result.agentmail_token,
+    agentmail_saved_at:   new Date().toISOString(),
+  })
+  console.log(result.agentmail_email || result.email)
+}
+
+async function mailSend(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const to = listOpt(opts.to, '--to')
+  const subject = opts.subject || ''
+  const body = mailBody(opts, { to, subject })
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/send`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: 'send',
+    defaultTitle: opts.title || `Email: ${subject || to.join(', ')}`,
+    recipient: to.join(','),
+    subject,
+    response: result,
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailReply(rest, mode) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], '--message-id')
+  const body = mailBody(opts)
+  const endpoint = mode === 'reply-all' ? 'reply-all' : 'reply'
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/${endpoint}`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: mode,
+    defaultTitle: opts.title || `${mode === 'reply-all' ? 'Reply-all' : 'Reply'}: ${messageId}`,
+    recipient: listOpt(opts.to).join(','),
+    response: result,
+    metadata: { message_id: messageId },
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailForward(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], '--message-id')
+  const to = listOpt(opts.to, '--to')
+  const body = mailBody(opts, { to, subject: opts.subject || '' })
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/forward`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: 'forward',
+    defaultTitle: opts.title || `Forward: ${opts.subject || messageId}`,
+    recipient: to.join(','),
+    response: result,
+    metadata: { message_id: messageId },
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailThreads(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const qs = queryString({ limit: opts.limit, page_token: opts['page-token'] || opts.page_token })
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/threads${qs}`))
+}
+
+async function mailThread(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const threadId = required(opts['thread-id'] || opts.thread_id || opts._[0], 'thread_id')
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/threads/${encodeURIComponent(threadId)}`))
+}
+
+async function mailMessages(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const qs = queryString({ limit: opts.limit, page_token: opts['page-token'] || opts.page_token })
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages${qs}`))
+}
+
+async function mailMessage(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], 'message_id')
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}`))
+}
+
+async function mailRaw(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], 'message_id')
+  const raw = await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/raw`, undefined, { parseJson: false })
+  process.stdout.write(raw)
+}
+
+async function mailAttachment(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id, '--message-id')
+  const attachmentId = required(opts['attachment-id'] || opts.attachment_id, '--attachment-id')
+  const body = await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`, undefined, { parseJson: false })
+  if (opts.out) fs.writeFileSync(opts.out, body)
+  else process.stdout.write(body)
+}
+
+async function mailRequest(rest) {
+  const opts = parseArgs(rest)
+  const method = (opts.method || opts._[0] || 'GET').toUpperCase()
+  const requestPath = required(opts.path || opts._[1], '--path')
+  const body = opts.body ? JSON.parse(readValue(opts.body)) : undefined
+  const parseJson = opts.raw ? false : true
+  const result = await agentmailRequest(method, requestPath.startsWith('/') ? requestPath : `/${requestPath}`, body, { parseJson })
+  if (parseJson) printJson(result)
+  else process.stdout.write(result)
+}
+
+function mailBody(opts, base = {}) {
+  const body = { ...base }
+  if (opts.text !== undefined) body.text = readValue(opts.text)
+  if (opts.html !== undefined) body.html = readValue(opts.html)
+  if (opts.subject !== undefined) body.subject = opts.subject
+  for (const key of ['cc', 'bcc', 'reply-to', 'label', 'attachment']) {
+    const snake = key.replaceAll('-', '_')
+    const value = opts[key] ?? opts[snake]
+    if (value !== undefined) body[snake] = listOpt(value)
+  }
+  if (opts.headers !== undefined) body.headers = JSON.parse(readValue(opts.headers))
+  return body
+}
+
+async function maybeLogMailAction(opts, { kind, defaultTitle, recipient, subject, response, metadata = {} }) {
+  const runId = opts['run-id'] || opts.run_id || opts.run
+  if (!runId) return null
+  const creds = requireAgentmailCredentials()
+  const threadId = response?.thread_id
+  if (!threadId) throw new Error('AgentMail response missing thread_id; refusing to log email action')
+  return api('POST', `/v1/runs/${encodeURIComponent(runId)}/actions`, {
+    channel: 'email',
+    title: opts.title || defaultTitle,
+    recipient: recipient || undefined,
+    agentmail_thread_id: threadId,
+    agentmail_inbox_id: creds.inboxId,
+    metadata: compact({
+      kind,
+      subject,
+      message_id: response?.message_id,
+      ...metadata,
+    }),
+  })
+}
+
+async function agentmailRequest(method, pathStr, body, { parseJson = true } = {}) {
+  const creds = requireAgentmailCredentials()
+  const res = await fetch(AGENTMAIL_API + pathStr, {
+    method,
+    headers: {
+      authorization: `Bearer ${creds.token}`,
+      'content-type': 'application/json',
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  const text = await res.text()
+  let data = text
+  if (parseJson) {
+    try { data = text ? JSON.parse(text) : null } catch { data = { raw: text } }
+  }
+  if (!res.ok) {
+    const msg = parseJson ? (data?.error || data?.message || JSON.stringify(data)) : text
+    throw new Error(`AgentMail ${res.status}: ${msg}`)
+  }
+  return data
+}
+
+function requireAgentmailCredentials() {
+  const creds = loadCredentials()
+  const token = process.env.AGENTMAIL_API_KEY || creds?.agentmail_token
+  const email = process.env.AGENTMAIL_EMAIL || creds?.agentmail_email
+  const inboxId = process.env.AGENTMAIL_INBOX_ID || creds?.agentmail_inbox_id || email
+  if (!token) throw new Error('missing agentmail_token. run: autark mail setup --prefix <name>')
+  if (!inboxId) throw new Error('missing agentmail_inbox_id. run: autark mail setup --prefix <name>')
+  return { token, email, inboxId }
+}
+
 // ============================================================ context
 
 async function context(rest) {
@@ -223,12 +444,8 @@ async function context(rest) {
   const productSlug = parts[0]
   const code = parts[1]
 
-  if (!code) {
-    return printProductContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}`))
-  }
-
-  const result = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
-  return printHypothesisContext(result)
+  if (!code) return printProductContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}`))
+  return printHypothesisContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`))
 }
 
 function printProductContext(r) {
@@ -264,9 +481,7 @@ function printHypothesisContext(result) {
         console.log(`  [${a.channel}] ${a.title}${pointer ? `  →  ${pointer}` : ''}`)
       }
     }
-    if (run.narrative_md) {
-      console.log(`\n${run.narrative_md}`)
-    }
+    if (run.narrative_md) console.log(`\n${run.narrative_md}`)
   }
 }
 
@@ -301,14 +516,10 @@ function saveCredentials(creds) {
 
 function loadCredentials() {
   if (!fs.existsSync(CREDS_PATH)) return null
-  try {
-    return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8'))
-  } catch {
-    return null
-  }
+  try { return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8')) } catch { return null }
 }
 
-// ============================================================ arg parsing
+// ============================================================ utilities
 
 function parseArgs(list) {
   const opts = { _: [] }
@@ -320,12 +531,11 @@ function parseArgs(list) {
     }
     const key = arg.slice(2)
     const next = list[i + 1]
-    if (!next || next.startsWith('--')) {
-      opts[key] = true
-    } else {
-      opts[key] = next
-      i++
-    }
+    const value = (!next || next.startsWith('--')) ? true : next
+    if (value !== true) i++
+    if (opts[key] === undefined) opts[key] = value
+    else if (Array.isArray(opts[key])) opts[key].push(value)
+    else opts[key] = [opts[key], value]
   }
   return opts
 }
@@ -338,12 +548,43 @@ function required(value, label) {
 }
 
 function readValue(value) {
-  if (typeof value === 'string' && value.startsWith('@')) {
-    return fs.readFileSync(value.slice(1), 'utf8')
-  }
+  if (typeof value === 'string' && value.startsWith('@')) return fs.readFileSync(value.slice(1), 'utf8')
   return String(value)
 }
 
+function listOpt(value, label) {
+  if (value === undefined || value === null || value === '') {
+    if (label) throw new Error(`${label} is required`)
+    return []
+  }
+  const values = Array.isArray(value) ? value : [value]
+  return values.flatMap(v => String(v).split(',')).map(v => v.trim()).filter(Boolean)
+}
+
+function queryString(params) {
+  const q = new URLSearchParams()
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== '') q.set(k, v)
+  const s = q.toString()
+  return s ? `?${s}` : ''
+}
+
+function defaultInboxPrefix(email) {
+  if (!email) return ''
+  return String(email).split('@')[0].toLowerCase().replace(/[^a-z0-9._-]/g, '').replace(/^[._-]+/, '').slice(0, 30)
+}
+
+function compact(obj) {
+  const out = {}
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v !== undefined && v !== null && v !== '' && !(Array.isArray(v) && !v.length)) out[k] = v
+  }
+  return out
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2))
+}
+
 function splitHypothesisRef(ref) {
   const m = String(ref).match(/^([\w.-]+)\/(H\d{2})$/)
   if (!m) throw new Error(`expected product/Hxx, got ${ref}`)
@@ -353,8 +594,26 @@ function splitHypothesisRef(ref) {
 // ============================================================ usage
 
 function loginUsage() {
-  console.log(`autark login send <email>
-autark login verify <email> --code <6-digit-code>`)
+  console.log(`autark login send <email>\nautark login verify <email> --code <6-digit-code>`)
+}
+
+function mailUsage() {
+  console.log(`autark mail
+
+  setup       --prefix <name> [--force]
+  send        --to <email[,email]> --subject <s> --text @body.txt [--run-id <id>]
+  reply       --message-id <id> --text @reply.txt [--run-id <id>]
+  reply-all   --message-id <id> --text @reply.txt [--run-id <id>]
+  forward     --message-id <id> --to <email> [--text @body.txt] [--run-id <id>]
+  threads     [--limit N]
+  thread      <thread_id>
+  messages    [--limit N]
+  message     <message_id>
+  raw         <message_id>
+  attachment  --message-id <id> --attachment-id <id> [--out file]
+  request     <METHOD> <path> [--body @json] [--raw]
+
+Mail uses the inbox-scoped token in ~/.autark/credentials.json.`)
 }
 
 function usage() {
@@ -378,9 +637,11 @@ function usage() {
   autark run finish --run-id <id> --narrative @./run.md
 
   autark log action --run-id <id> --channel <c> --title <t> [--url <u>]
-                    [--agentmail-thread-id <uuid>] [--recipient <email>]
+                    [--agentmail-thread-id <uuid>] [--agentmail-inbox-id <inbox>] [--recipient <email>]
                     [--metadata @./meta.json]
 
+  autark mail setup/send/reply/thread/messages/...       AgentMail via autark credentials
+
   autark context --product-id <id>
   autark context --hypothesis-id <id>
   autark context <slug>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autark-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "CLI for autark — hypothesis-driven product runbooks. Track products, hypotheses, runs, and actions from the terminal.",
   "type": "module",
   "license": "MIT",