autark-cli 0.1.8 → 0.2.0

package/autark.mjs

@@ -16,6 +16,17 @@ const AGENTMAIL_API = process.env.AGENTMAIL_API_URL || 'https://api.agentmail.to
 const AUTARK_HOME = process.env.AUTARK_HOME || path.join(os.homedir(), '.autark')
 const CREDS_PATH = process.env.AUTARK_CREDENTIALS || path.join(AUTARK_HOME, 'credentials.json')
 
+// Constants used by `autark update` — hoisted before main() runs because
+// async function bodies execute synchronously until their first await; main()
+// dispatches to update() which references these in its first synchronous
+// loop, so they need to be initialized at module-load time before the
+// main().catch() call below.
+const RAW_RUNTIME_BASE = process.env.AUTARK_RUNTIME_RAW_BASE
+  || 'https://autark.kushalsm.com/runtime'
+const SKILL_NAMES = ['autark', 'plumcake', 'chrome-relay', 'email', 'outreach', 'email-finder']
+const ECOSYSTEM_CLIS = ['autark-cli', 'plumcake-cli', 'chrome-relay']
+const PROGRAM_FILES = ['start.md', 'double-down.md', 'check.md', 'followup.md']
+
 const args = process.argv.slice(2)
 main()
   .then(() => maybeNudge())
@@ -152,13 +163,18 @@ async function main() {
   if (group === 'me')     return me()
 
   if (group === 'product') {
-    if (command === 'upsert') return productUpsert(rest)
-    if (command === 'list')   return productList()
+    if (command === 'upsert')        return productUpsert(rest)
+    if (command === 'list')          return productList()
+    if (command === 'pause')         return productPause(rest, 'paused')
+    if (command === 'unpause')       return productPause(rest, 'active')
+    if (command === 'run-status')    return productPause(rest)
     if (!command || command === '--help' || command === '-h') return productUsage()
   }
   if (group === 'hypothesis') {
     if (command === 'create') return hypothesisCreate(rest)
     if (command === 'status') return hypothesisStatus(rest)
+    if (command === 'pause')   return hypothesisPause(rest, 'inactive')
+    if (command === 'unpause') return hypothesisPause(rest, 'active')
     if (!command || command === '--help' || command === '-h') return hypothesisUsage()
   }
   if (group === 'run') {
@@ -170,6 +186,20 @@ async function main() {
     if (command === 'action') return logAction(rest)
     if (!command || command === '--help' || command === '-h') return logUsage()
   }
+  if (group === 'action') {
+    if (command === 'escalate')   return actionEscalate(rest)
+    if (command === 'unescalate') return actionEscalate(rest, { clear: true })
+    if (!command || command === '--help' || command === '-h') return actionUsage()
+  }
+  if (group === 'feedback') {
+    if (command === 'record') return feedbackRecord(rest)
+    if (command === 'delete') return feedbackDelete(rest)
+    if (!command || command === '--help' || command === '-h') return feedbackUsage()
+  }
+  if (group === 'deliverability') {
+    if (command === 'check') return deliverabilityCheck(rest)
+    if (!command || command === '--help' || command === '-h') return deliverabilityUsage()
+  }
   if (group === 'context') {
     if (!command || command === '--help' || command === '-h') return contextUsage()
     return context([command, ...rest].filter(Boolean))
@@ -245,6 +275,9 @@ async function settingsShow(rest) {
   console.log(`agentmail_email   ${fmt(s.agentmail_email)}`)
   console.log(`custom_domain     ${fmt(s.custom_domain)}`)
   console.log(`domain_status     ${fmt(s.custom_domain_status)}`)
+  if (Array.isArray(s.custom_domains) && s.custom_domains.length) {
+    console.log(`custom_domains    ${s.custom_domains.map((d) => `${d.domain}:${d.status}`).join(', ')}`)
+  }
 }
 
 function settingsUsage() {
@@ -272,14 +305,6 @@ function settingsUsage() {
 // AUTARK_UPDATE_OFFLINE=1 skips the self-update step (for tests).
 // AUTARK_HOME overrides the install root (for sandbox tests).
 
-// The autark repo is private. Pages serves the canonical files at
-// autark.kushalsm.com/runtime/* (synced from runtime/ at build time).
-const RAW_RUNTIME_BASE = process.env.AUTARK_RUNTIME_RAW_BASE
-  || 'https://autark.kushalsm.com/runtime'
-const SKILL_NAMES = ['autark', 'plumcake', 'chrome-relay', 'email', 'outreach', 'email-finder']
-const ECOSYSTEM_CLIS = ['autark-cli', 'plumcake-cli', 'chrome-relay']
-const PROGRAM_FILES = ['start.md', 'double-down.md', 'check.md', 'followup.md']
-
 async function update(rest) {
   const opts = parseArgs(rest)
   const dryRun = !!process.env.AUTARK_UPDATE_DRY_RUN || !!opts['dry-run']
@@ -609,6 +634,20 @@ async function logAction(rest) {
   const run = required(opts['run-id'] || opts.run_id || opts.run, '--run-id')
   const channel = required(opts.channel, '--channel')
   const title   = required(opts.title, '--title')
+  const needsHuman = Boolean(opts['needs-human'] || opts.needs_human || opts.escalate)
+  const escalationReason = opts['escalation-reason'] || opts.escalation_reason || opts.reason || undefined
+
+  // Merge `our_comment_id` into metadata if passed as a sugar flag. This is
+  // the per-channel anchor the reply-state cron uses to detect engagement on
+  // OUR specific comment (vs the parent we were replying to). Always pass
+  // it when you posted a comment somewhere we can re-fetch — github issue/PR
+  // comments, gists, HN replies, Substack comments, Reddit comments.
+  const meta = opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined
+  const ourCommentId = opts['our-comment-id'] || opts.our_comment_id
+  const metadata = ourCommentId
+    ? { ...(meta || {}), our_comment_id: String(ourCommentId) }
+    : meta
+
   const result = await api('POST', `/v1/runs/${encodeURIComponent(run)}/actions`, {
     channel,
     title,
@@ -616,12 +655,156 @@ async function logAction(rest) {
     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,
+    metadata,
+    needs_human:          needsHuman || undefined,
+    escalation_reason:    needsHuman ? escalationReason : undefined,
     occurred_at:          opts['occurred-at'] || opts.occurred_at || undefined,
   })
   console.log(result.id)
 }
 
+// ============================================================ action escalate
+
+async function actionEscalate(rest, { clear = false } = {}) {
+  const opts = parseArgs(rest)
+  const id = required(opts['action-id'] || opts.action_id || opts._[0], 'action id')
+  const reason = opts.reason || opts._.slice(1).join(' ') || undefined
+  const body = { needs_human: !clear }
+  if (!clear) body.reason = reason || ''
+  const result = await api('PATCH', `/v1/actions/${encodeURIComponent(id)}/escalate`, body)
+  console.log(`${result.id}  needs_human=${result.needs_human}${result.escalation_reason ? `  reason="${result.escalation_reason}"` : ''}`)
+}
+
+function actionUsage() {
+  console.log(`autark action escalate <action-id> [--reason "<one-line why>"]
+autark action unescalate <action-id>`)
+}
+
+// ============================================================ product pause
+
+async function productPause(rest, fixedStatus) {
+  const opts = parseArgs(rest)
+  const slug = opts.slug || opts._[0]
+  let productId = opts['product-id'] || opts.product_id
+  if (!productId && slug) {
+    const list = await api('GET', '/v1/products')
+    const found = (list.products || []).find((p) => p.slug === slug)
+    if (!found) throw new Error(`product not found: ${slug}`)
+    productId = found.id
+  }
+  if (!productId) throw new Error('pass product slug or --product-id')
+  const status = fixedStatus || required(opts.status, '--status (active|paused)')
+  const result = await api('PATCH', `/v1/products/${encodeURIComponent(productId)}/run-status`, { run_status: status })
+  console.log(`${slug || productId} → run_status=${result.run_status}`)
+}
+
+// ============================================================ hypothesis pause
+// Hypothesis-level pause is just a status flip. Convenience wrappers around the
+// existing /hypotheses/:id/status endpoint so the CLI surface matches "pause".
+
+async function hypothesisPause(rest, status) {
+  const opts = parseArgs(rest)
+  const ref = opts._[0] || opts.hypothesis
+  let hypId = opts['hypothesis-id'] || opts.hypothesis_id || opts.id
+  let label = hypId || ref
+  if (!hypId) {
+    if (!ref) throw new Error('pass product/Hxx or --hypothesis-id')
+    const [productSlug, code] = splitHypothesisRef(ref)
+    const ctx = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
+    hypId = ctx.hypothesis?.id
+    label = ref
+  }
+  if (!hypId) throw new Error('hypothesis not found')
+  const result = await api('PATCH', `/v1/hypotheses/${encodeURIComponent(hypId)}/status`, { status })
+  console.log(`${label} → ${result.status}`)
+}
+
+// ============================================================ feedback
+
+async function feedbackRecord(rest) {
+  const opts = parseArgs(rest)
+  const ref = opts.hypothesis || opts._[0]
+  let hypId = opts['hypothesis-id'] || opts.hypothesis_id
+  if (!hypId) {
+    if (!ref) throw new Error('pass product/Hxx or --hypothesis-id')
+    const [productSlug, code] = splitHypothesisRef(ref)
+    const ctx = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
+    hypId = ctx.hypothesis?.id
+  }
+  if (!hypId) throw new Error('hypothesis not found')
+  const text = readValue(required(opts.text || opts.message || opts.body, '--text "<feedback>"'))
+  const body = { text }
+  if (opts['action-id'] || opts.action_id) body.action_id = opts['action-id'] || opts.action_id
+  const result = await api('POST', `/v1/hypotheses/${encodeURIComponent(hypId)}/feedback`, body)
+  console.log(result.id)
+}
+
+async function feedbackDelete(rest) {
+  const opts = parseArgs(rest)
+  const id = required(opts['feedback-id'] || opts.id || opts._[0], 'feedback id')
+  const result = await api('DELETE', `/v1/feedback/${encodeURIComponent(id)}`)
+  console.log(`${result.id} deleted`)
+}
+
+function feedbackUsage() {
+  console.log(`autark feedback record <product/Hxx> --text "<nudge>" [--action-id <id>]
+autark feedback delete <feedback-id>`)
+}
+
+// ====================================================== deliverability
+
+// Pre-send email validator. Calls AgentMail's recipient-check endpoint so the
+// agent can avoid blasting a guessed/permutated address and inflating the
+// bounce rate. Falls back to a syntactic check if the endpoint is unreachable.
+async function deliverabilityCheck(rest) {
+  const opts = parseArgs(rest)
+  const email = required(opts.email || opts._[0], 'email')
+  const creds = loadCredentials() || {}
+  const token = creds.agentmail_token
+  let verdict = { email, deliverable: null, source: 'syntactic', reason: '' }
+
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    verdict = { ...verdict, deliverable: false, reason: 'malformed address' }
+    console.log(JSON.stringify(verdict, null, 2))
+    process.exitCode = 1
+    return
+  }
+  if (!token) {
+    verdict.reason = 'no agentmail token; syntactic check only'
+    console.log(JSON.stringify(verdict, null, 2))
+    return
+  }
+
+  try {
+    const res = await fetch('https://api.agentmail.to/v0/deliverability/check', {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ email }),
+    })
+    if (!res.ok) {
+      verdict.reason = `agentmail check ${res.status}; fell back to syntactic`
+      verdict.deliverable = null
+    } else {
+      const body = await res.json().catch(() => ({}))
+      verdict.source = 'agentmail'
+      verdict.deliverable = body.deliverable !== false
+      verdict.reason = body.reason || ''
+      if (body.risk) verdict.risk = body.risk
+    }
+  } catch (err) {
+    verdict.reason = `network error: ${err.message}`
+  }
+  console.log(JSON.stringify(verdict, null, 2))
+  if (verdict.deliverable === false) process.exitCode = 1
+}
+
+function deliverabilityUsage() {
+  console.log(`autark deliverability check <email>
+  Returns JSON {email, deliverable, source, reason}. Exits non-zero when the
+  address is known-undeliverable. Call this before logging an email action so
+  bounces don't tank your domain rep.`)
+}
+
 // ============================================================ mail
 
 async function mail(command, rest) {
@@ -1103,9 +1286,14 @@ function usage() {
   me                         show signed-in user
 
   product upsert|list        create/edit/list products
+  product pause|unpause      stop / resume cron on a product
   hypothesis create|status   create or update hypotheses
+  hypothesis pause|unpause   stop / resume work on a hypothesis
   run start|finish           start / finish a run
   log action                 record one outreach touch
+  action escalate            flag an action for human attention
+  feedback record|delete     leave a free-text nudge on a hypothesis
+  deliverability check       pre-send check for an email address
   context [<slug>|...]       pull product or hypothesis context
 
   mail setup|send|reply|...  send/read mail via your AgentMail inbox
@@ -1123,6 +1311,9 @@ function productUsage() {
 
   list                       prints slug, visibility, id, name
 
+  pause   <slug>             cron will skip this product on start ticks
+  unpause <slug>             resume cron
+
 The brief is the markdown the agent reads at the top of every run
 to understand what the product is and who it might serve.`)
 }
@@ -1136,6 +1327,9 @@ function hypothesisUsage() {
   status --hypothesis-id <id>      --status active|inactive|dead
   status <slug>/<H01>              --status active|inactive|dead          # slug/code alias
 
+  pause   <slug>/<H01>             flip to inactive (cron skips it)
+  unpause <slug>/<H01>             flip back to active
+
 Hypotheses are frozen on create. Only --status changes after.
 If --code is omitted, autark picks the next H## for the product.`)
 }
@@ -1159,10 +1353,40 @@ function logUsage() {
          [--agentmail-thread-id <uuid>]       # email
          [--agentmail-inbox-id <email>]       # email — defaults to your inbox
          [--recipient <email>]                # email
-         [--metadata @./meta.json]            # any channel-specific extras
+         [--our-comment-id <id>]              # see "Always capture our_comment_id" below
+         [--metadata @./meta.json]            # any other channel-specific extras
+         [--escalate --reason "<why>"]        # flag this action as needs_human
 
 One row per external touch. Body content stays in AgentMail/GitHub/etc;
-this just records the pointer + the title agents see on the dashboard.`)
+this just records the pointer + the title agents see on the dashboard.
+
+  Log the URL of YOUR comment, not the parent
+
+  The reply-state cron parses the comment id out of the --url you log to
+  detect "did anyone reply to you?". Most channels' URLs already contain
+  the id; you just have to log the permalink of your OWN comment, not the
+  issue/post URL you replied to.
+
+    github (issue or PR comment):
+      use the response's html_url, ends in #issuecomment-<id>
+        NEW_URL=$(gh api repos/<o>/<r>/issues/<n>/comments \\
+          -X POST -f body=@body.md --jq .html_url)
+
+    gist:
+      ends in #gistcomment-<id>
+
+    hn:
+      .../item?id=<your_new_item_id> (your id, not the parent's)
+
+    reddit:
+      .../r/<sub>/comments/<thread>/<title>/<your_comment_id>/
+
+    substack:
+      Substack permalinks don't always include the comment id, so for
+      this channel use --our-comment-id <id> from the response body.
+
+  Escape hatch: --our-comment-id <id> tucks the id into metadata. Use it
+  when the URL pattern can't encode the comment (Substack, edge HN cases).`)
 }
 
 function contextUsage() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autark-cli",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "CLI for autark — hypothesis-driven product runbooks. Track products, hypotheses, runs, and actions from the terminal.",
   "type": "module",
   "license": "MIT",
@@ -19,4 +19,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}