@raidiant/notifai 8.0.0 → 9.0.0

package/src/commands-send.ts

@@ -14,9 +14,11 @@ import {
   buildDraft,
   formatReceipt,
   receiptExitCode,
+  rejectAccidentalEscapedNewlines,
   validateMediaInputs,
   type SendFlags,
 } from './send.js'
+import { recordObservedDeliveryProof } from './commands-setup-proof.js'
 import {
   EXIT,
   authedClient,
@@ -63,7 +65,7 @@ export async function sendCommand(
   if (!flags.reply && flags.kind === undefined) {
     deps.io.err(
       '--kind is required: say what this notification is. ' +
-        'update (news) · done (finished) · failed (terminal failure) · blocked (cannot proceed). ' +
+        'update (news) · done (finished) · failed (terminal failure) · blocked (cannot proceed; no User reply would resume it). ' +
         '--reply makes it a question without --kind.',
     )
     return EXIT.usage
@@ -111,6 +113,11 @@ export async function sendCommand(
     )
     return EXIT.usage
   }
+  const escapedBody = rejectAccidentalEscapedNewlines(flags.body, flags.literalBackslashN)
+  if (escapedBody !== null) {
+    deps.io.err(escapedBody)
+    return EXIT.usage
+  }
   const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt)
   if (mediaInputError !== null) {
     deps.io.err(mediaInputError)
@@ -138,7 +145,7 @@ export async function sendCommand(
       mediaIds.push(image)
       continue
     }
-    const uploaded = await uploadImage(deps, authed.client, image)
+    const uploaded = await uploadImage(deps, authed.client, image, config.media_origins.value)
     if (!uploaded.ok) {
       if (uploaded.error !== null) deps.io.err(uploaded.error)
       return uploaded.exit
@@ -175,6 +182,15 @@ export async function sendCommand(
   }
   const waitSeconds = flags.noWait ? 0 : config.wait_seconds.value
   const idempotencyKey = flags.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`
+  // Persist the retry identity before entering the ambiguous network boundary.
+  // If the process is killed after the server accepts but before a response,
+  // this is the only durable way to reconstruct the same Agent Event key.
+  log(deps).info('send.attempt', {
+    idempotency_key: idempotencyKey,
+    kind: flags.reply ? 'question' : (flags.kind ?? 'update'),
+    title: flags.title,
+    session_id: source.invocation.source?.session_id ?? null,
+  })
   let receipt: SubmissionReceipt
   try {
     receipt = await authed.client.submit(
@@ -182,7 +198,20 @@ export async function sendCommand(
       waitSeconds,
     )
   } catch (err) {
-    return reportError(deps, err)
+    const exit = reportError(deps, err)
+    if (exit === EXIT.network) {
+      deps.io.err(
+        'The server may have accepted this Notification Request before the connection failed. ' +
+          `Retry the same send with \`--idempotency-key ${idempotencyKey}\` so this Agent Event cannot create a duplicate.`,
+      )
+    }
+    if (err instanceof ApiCallError && err.code === 'no_active_devices') {
+      deps.io.err(
+        'After setup succeeds, repeat this original Notification Request with ' +
+          `\`--idempotency-key ${idempotencyKey}\`; the setup verification request does not replace this Agent Event.`,
+      )
+    }
+    return exit
   }
   const receiptExit = receiptExitCode(receipt)
   // The single most useful line in the log: it ties the local invocation to
@@ -191,7 +220,7 @@ export async function sendCommand(
   log(deps).info('send.submitted', {
     request_id: receipt.request_id,
     kind: flags.reply ? 'question' : (flags.kind ?? 'update'),
-    title: flags.title,
+    title_chars: flags.title.length,
     overall: receipt.overall,
     replayed: receipt.replayed,
     agent_acknowledgement_required: receipt.agent_acknowledgement_required,
@@ -363,19 +392,52 @@ export async function repliesCommand(
     // Every delivered question in the session's queue, in registration order —
     // an agent may have several outstanding at once.
     const state = readSessionState(sessionId, deps.env)
-    requestIds = (Array.isArray(state.pending) ? state.pending : [])
+    const pending = Array.isArray(state.pending) ? state.pending : []
+    requestIds = pending
       .map((entry) => entry.request_id)
       .filter((id): id is string => id !== undefined)
+    const unsent = pending.filter((entry) => entry.request_id === undefined)
     if (requestIds.length === 0) {
       // `--json` is a promise about stdout, and an empty result is still a
       // result: a caller that asked for machine-readable output must not have
       // to parse an English sentence to learn there was nothing pending.
       if (flags.json === true) {
-        deps.io.out(JSON.stringify({ session_id: sessionId, pending: [], replies: [] }, null, 2))
+        deps.io.out(
+          JSON.stringify(
+            {
+              session_id: sessionId,
+              pending: unsent.map((entry) => ({
+                question: entry.question,
+                ...(entry.question_id === undefined ? {} : { question_id: entry.question_id }),
+              })),
+              replies: [],
+            },
+            null,
+            2,
+          ),
+        )
+      } else if (unsent.length > 0) {
+        for (const entry of unsent) {
+          deps.io.out(
+            entry.question_id === undefined
+              ? `unpushed question: ${entry.question}`
+              : `unpushed question ${entry.question_id}: ${entry.question}`,
+          )
+        }
+        deps.io.out('Retire one with `notifai close <question_id>` so a later Stop will not send it.')
       } else {
         deps.io.err(`Session ${sessionId} has no pushed question pending.`)
       }
-      return EXIT.noReply
+      return unsent.length > 0 ? EXIT.ok : EXIT.noReply
+    }
+    if (unsent.length > 0 && flags.json !== true) {
+      for (const entry of unsent) {
+        deps.io.out(
+          entry.question_id === undefined
+            ? `unpushed question: ${entry.question}`
+            : `unpushed question ${entry.question_id}: ${entry.question}`,
+        )
+      }
     }
   }
   if (requestIds.length === 0) {
@@ -527,8 +589,8 @@ function recordReplies(deps: CommandDeps, requestId: string, replies: readonly R
       request_id: requestId,
       sequence: reply.seq,
       device: reply.device_name,
-      text: reply.text,
-      answers: reply.answers,
+      text_chars: reply.text.length,
+      answers_count: reply.answers?.length ?? 0,
       source: reply.source,
     })
   }
@@ -587,11 +649,12 @@ export async function statusCommand(
   if (!authed) return EXIT.auth
   try {
     const snapshot = await authed.client.evidence(requestId)
+    recordObservedDeliveryProof(deps, snapshot, config.project.value)
     if (flags.json) {
       deps.io.out(JSON.stringify(snapshot, null, 2))
       return EXIT.ok
     }
-    deps.io.out(`request ${snapshot.request_id} (${snapshot.event ?? 'no event'}) — ${snapshot.overall}`)
+    deps.io.out(`request ${snapshot.request_id} — ${snapshot.overall}`)
     let anyReplyReceived = false
     for (const d of snapshot.deliveries) {
       deps.io.out(`  ${d.device_name}:`)

package/src/commands-setup-proof.ts

@@ -66,6 +66,40 @@ export function observedCompanionReceipt(
   deviceId: string,
 ): { delivery: EvidenceSnapshot['deliveries'][number]; observedAt: string } | null {
   const delivery = snapshot.deliveries.find((candidate) => candidate.device_id === deviceId)
-  const receipt = delivery?.events.find((event) => event.stage === 'companion_received')
-  return delivery && receipt ? { delivery, observedAt: receipt.occurred_at } : null
+  if (!delivery) return null
+  if (delivery.companion_receipt.state === 'observed' && delivery.companion_receipt.observed_at) {
+    return { delivery, observedAt: delivery.companion_receipt.observed_at }
+  }
+  const receipt = delivery.events.find((event) => event.stage === 'companion_received')
+  return receipt ? { delivery, observedAt: receipt.occurred_at } : null
+}
+
+/** Replace an unknown setup proof after this age; recent in-flight proofs stay. */
+export const SETUP_PROOF_STALE_MS = 24 * 60 * 60 * 1000
+
+export function setupProofIsStale(proof: SetupProofRecord, now: number): boolean {
+  const started = Date.parse(proof.started_at)
+  return Number.isFinite(started) && now - started > SETUP_PROOF_STALE_MS
+}
+
+/**
+ * Persist ordinary send/status Companion Receipts as the project's delivery
+ * proof so doctor does not demand a second verification request.
+ */
+export function recordObservedDeliveryProof(
+  deps: CommandDeps,
+  snapshot: EvidenceSnapshot,
+  project: string | null,
+): boolean {
+  for (const delivery of snapshot.deliveries) {
+    const observed = observedCompanionReceipt(snapshot, delivery.device_id)
+    if (observed === null) continue
+    return writeSetupProof(deps, {
+      request_id: snapshot.request_id,
+      device_id: delivery.device_id,
+      project,
+      started_at: observed.observedAt,
+    })
+  }
+  return false
 }

package/src/commands-skill.ts

@@ -1,4 +1,4 @@
-import type { NativeSkill, SkillScope } from './native-skills.js'
+import { SKILLS_INSTALLER_SPEC, type NativeSkill, type SkillScope } from './native-skills.js'
 import { type ReadinessState } from './readiness.js'
 import { skillsSource } from './release.js'
 import type { CommandDeps } from './commands-core.js'
@@ -18,6 +18,8 @@ export const SKILLS_SOURCE: string | null = skillsSource()
  */
 const SKILLS_SOURCE_LABEL = SKILLS_SOURCE ?? 'the public release tag matching this CLI'
 
+const SKILL_SCOPES: readonly SkillScope[] = ['project', 'global']
+
 function skillSourceParts(): { source: string; ref: string } | null {
   if (SKILLS_SOURCE === null) return null
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -35,13 +37,23 @@ function expectedSkill(skill: NativeSkill): boolean {
   )
 }
 
-export async function skillReadiness(
-  deps: CommandDeps,
-  selectedScope?: SkillScope,
-): Promise<ReadinessState> {
-  const scopes: SkillScope[] = selectedScope === undefined ? ['project', 'global'] : [selectedScope]
+function skillPin(skill: NativeSkill): string {
+  return skill.ref ?? 'unknown pin'
+}
+
+export interface ScopedNotifaiSkills {
+  installed: NativeSkill[]
+  errors: string[]
+}
+
+/**
+ * Installer-managed notifai skills in both scopes. Duplicate detection has to
+ * see the pair; a selected-scope filter would hide the copy the harness still
+ * lists.
+ */
+export async function listScopedNotifaiSkills(deps: CommandDeps): Promise<ScopedNotifaiSkills> {
   const results = await Promise.all(
-    scopes.map(async (scope) => {
+    SKILL_SCOPES.map(async (scope) => {
       if (deps.nativeSkills === undefined) return { scope, skills: [] as NativeSkill[] }
       try {
         return { scope, ...(await deps.nativeSkills.list(scope, deps.cwd, deps.env)) }
@@ -50,19 +62,70 @@ export async function skillReadiness(
       }
     }),
   )
-  const installed = results.flatMap(({ skills }) => skills).find(expectedSkill)
-  if (installed !== undefined) {
+  return {
+    installed: results.flatMap(({ skills }) => skills.filter((skill) => skill.name === 'notifai')),
+    errors: results
+      .filter((result) => result.error !== undefined)
+      .map((result) => `${result.scope}: ${result.error}`),
+  }
+}
+
+function duplicateSkillState(installed: NativeSkill[], selectedScope?: SkillScope): ReadinessState {
+  const project = installed.find((skill) => skill.scope === 'project')
+  const global = installed.find((skill) => skill.scope === 'global')
+  const projectPin = project === undefined ? 'not installed' : skillPin(project)
+  const globalPin = global === undefined ? 'not installed' : skillPin(global)
+  return {
+    id: 'skill',
+    title: 'Agent guidance skill',
+    status: 'gap',
+    detail:
+      `project (${projectPin}) and global (${globalPin}) are both installed, so the harness lists both. ` +
+      'Keep either project or global and uninstall the other.',
+    technical: {
+      project:
+        project === undefined
+          ? null
+          : { ref: project.ref, path: project.path, current: expectedSkill(project) },
+      global:
+        global === undefined
+          ? null
+          : { ref: global.ref, path: global.path, current: expectedSkill(global) },
+      resolution: 'both-listed',
+    },
+    remedy:
+      selectedScope === undefined
+        ? {
+            by: 'user-here',
+            summary:
+              'keep either the project or the machine-global skill and uninstall the other; add --global to remove the machine-global copy',
+            command: `npx -y ${SKILLS_INSTALLER_SPEC} remove notifai`,
+          }
+        : {
+            by: 'cli',
+            summary: `keep the ${selectedScope} skill and uninstall the other`,
+            command: `notifai init --skills --setup-scope ${selectedScope}`,
+          },
+  }
+}
+
+export async function skillReadiness(
+  deps: CommandDeps,
+  selectedScope?: SkillScope,
+): Promise<ReadinessState> {
+  const { installed, errors } = await listScopedNotifaiSkills(deps)
+  if (installed.length > 1) return duplicateSkillState(installed, selectedScope)
+
+  const current = installed.find(expectedSkill)
+  if (current !== undefined) {
     return {
       id: 'skill',
       title: 'Agent guidance skill',
       status: 'ready',
-      detail: `installed from ${SKILLS_SOURCE_LABEL} in the ${installed.scope} scope`,
+      detail: `installed from ${SKILLS_SOURCE_LABEL} in the ${current.scope} scope`,
     }
   }
 
-  const errors = results
-    .filter((result) => result.error !== undefined)
-    .map((result) => `${result.scope}: ${result.error}`)
   const scopeText = selectedScope === undefined ? 'project or machine-global scope' : `${selectedScope} scope`
   return {
     id: 'skill',
@@ -77,8 +140,8 @@ export async function skillReadiness(
       summary: 'install the skill agents follow when deciding to notify',
       command:
         selectedScope === undefined
-          ? 'notifai init --skills'
-          : `notifai init --skills --skills-scope ${selectedScope}`,
+          ? 'notifai init --skills --setup-scope project'
+          : `notifai init --skills --setup-scope ${selectedScope}`,
     },
   }
 }