@raidiant/notifai 0.1.7 → 0.2.0

package/src/native-skills.ts

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/** The two scopes offered by the skills installer. */
+export type SkillScope = 'project' | 'global'
+
+/** The installer-managed evidence needed by Notifai readiness. */
+export interface NativeSkill {
+  name: string
+  scope: SkillScope
+  path: string
+  source: string | null
+  sourceType: string | null
+  sourceUrl: string | null
+  ref: string | null
+}
+
+export interface SkillsListResult {
+  skills: NativeSkill[]
+  error?: string
+}
+
+export interface SkillsAddOptions {
+  source: string
+  skill: string
+  scope?: SkillScope
+  cwd: string
+  env: NodeJS.ProcessEnv
+}
+
+export interface NativeSkills {
+  /** Launch the native interactive `npx skills add` flow. */
+  add(options: SkillsAddOptions): Promise<number>
+  /** Ask the native installer for its managed install inventory. */
+  list(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): Promise<SkillsListResult>
+}
+
+interface JsonSkill {
+  name?: unknown
+  path?: unknown
+  scope?: unknown
+  source?: unknown
+  sourceType?: unknown
+  sourceUrl?: unknown
+}
+
+interface LockEntry {
+  source?: unknown
+  sourceType?: unknown
+  sourceUrl?: unknown
+  ref?: unknown
+}
+
+interface LockFile {
+  skills?: Record<string, LockEntry>
+}
+
+function skillLockPath(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): string {
+  if (scope === 'project') return path.join(cwd, 'skills-lock.json')
+  const stateHome = env['XDG_STATE_HOME']
+  const home = env['HOME'] ?? env['USERPROFILE'] ?? os.homedir()
+  return stateHome !== undefined && stateHome !== ''
+    ? path.join(stateHome, 'skills', '.skill-lock.json')
+    : path.join(home, '.agents', '.skill-lock.json')
+}
+
+function readLock(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): LockFile {
+  const file = skillLockPath(scope, cwd, env)
+  if (!existsSync(file)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as LockFile
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function lockEntryFor(lock: LockFile, name: string): LockEntry | undefined {
+  const direct = lock.skills?.[name]
+  if (direct) return direct
+  const normalized = name.toLowerCase().replace(/[\s_]+/g, '-')
+  const key = Object.keys(lock.skills ?? {}).find(
+    (candidate) => candidate.toLowerCase().replace(/[\s_]+/g, '-') === normalized,
+  )
+  return key === undefined ? undefined : lock.skills?.[key]
+}
+
+function jsonArray(stdout: string): unknown[] | null {
+  const start = stdout.indexOf('[')
+  const end = stdout.lastIndexOf(']')
+  if (start < 0 || end < start) return null
+  try {
+    const parsed: unknown = JSON.parse(stdout.slice(start, end + 1))
+    return Array.isArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function managedSkills(stdout: string, scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): NativeSkill[] | null {
+  const entries = jsonArray(stdout)
+  if (entries === null) return null
+  const lock = readLock(scope, cwd, env)
+  return entries.flatMap((entry): NativeSkill[] => {
+    if (entry === null || typeof entry !== 'object') return []
+    const value = entry as JsonSkill
+    if (
+      typeof value.name !== 'string' ||
+      typeof value.path !== 'string' ||
+      value.scope !== scope
+    ) {
+      return []
+    }
+    const lockEntry = lockEntryFor(lock, value.name)
+    return [
+      {
+        name: value.name,
+        scope,
+        path: value.path,
+        source: typeof value.source === 'string' ? value.source : null,
+        sourceType: typeof value.sourceType === 'string' ? value.sourceType : null,
+        sourceUrl: typeof value.sourceUrl === 'string' ? value.sourceUrl : null,
+        ref: typeof lockEntry?.ref === 'string' ? lockEntry.ref : null,
+      },
+    ]
+  })
+}
+
+function run(
+  args: string[],
+  options: { cwd: string; env: NodeJS.ProcessEnv; stdio: 'inherit' | 'capture' },
+): Promise<{ code: number; stdout: string }> {
+  return new Promise((resolve) => {
+    const child = spawn('npx', args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: options.stdio === 'inherit' ? 'inherit' : ['ignore', 'pipe', 'ignore'],
+    })
+    if (options.stdio === 'capture') {
+      let stdout = ''
+      child.stdout?.on('data', (chunk: Buffer | string) => {
+        stdout += chunk.toString()
+      })
+      child.on('error', () => resolve({ code: 1, stdout }))
+      child.on('exit', (code) => resolve({ code: code ?? 1, stdout }))
+      return
+    }
+    child.on('error', () => resolve({ code: 1, stdout: '' }))
+    child.on('exit', (code) => resolve({ code: code ?? 1, stdout: '' }))
+  })
+}
+
+/** The only process/filesystem adapter Notifai needs for the external installer. */
+export const nativeSkills: NativeSkills = {
+  async add(options) {
+    const args = ['-y', 'skills', 'add', options.source, '--skill', options.skill]
+    if (options.scope === 'global') args.push('--global')
+    // An explicit scope is the unattended contract. Native `--yes` keeps all
+    // remaining installer prompts non-interactive after the scope is chosen.
+    if (options.scope !== undefined) args.push('--yes')
+    return (await run(args, { cwd: options.cwd, env: options.env, stdio: 'inherit' })).code
+  },
+
+  async list(scope, cwd, env) {
+    const result = await run(
+      ['-y', 'skills', 'list', '--json', ...(scope === 'global' ? ['--global'] : [])],
+      { cwd, env, stdio: 'capture' },
+    )
+    if (result.code !== 0) return { skills: [], error: `npx skills list exited with code ${result.code}` }
+    const skills = managedSkills(result.stdout, scope, cwd, env)
+    return skills === null
+      ? { skills: [], error: 'npx skills list returned invalid JSON' }
+      : { skills }
+  },
+}

package/src/opencode-plugin.ts

@@ -30,7 +30,7 @@ export const OPENCODE_PLUGIN_MARKER = '// notifai managed opencode plugin'
 export const OPENCODE_PLUGIN_FILENAME = 'notifai.js'
 
 /** Bump when an installed generated file must be rewritten to remain functional. */
-const OPENCODE_ADAPTER_VERSION = 2
+const OPENCODE_ADAPTER_VERSION = 4
 
 export function opencodePluginDir(
   global: boolean,
@@ -88,7 +88,7 @@ function runHook(event, envelope) {
   return new Promise((resolve) => {
     let child
     try {
-      child = spawn(EXEC, [SCRIPT, "hook", event, "--owner", "notifai"], {
+      child = spawn(EXEC, [SCRIPT, "hook", event, "--owner", "notifai", "--harness", "opencode"], {
         env: process.env,
         shell: false,
         stdio: ["pipe", "pipe", "pipe"],
@@ -128,20 +128,51 @@ function runHook(event, envelope) {
   })
 }
 
+function additionalContext(stdout) {
+  if (typeof stdout !== "string" || stdout.trim() === "") return null
+  try {
+    const parsed = JSON.parse(stdout)
+    const context = parsed?.hookSpecificOutput?.additionalContext
+    return typeof context === "string" && context.length > 0 ? context : null
+  } catch {
+    return null
+  }
+}
+
 export const NotifAIPlugin = async ({ directory }) => {
   const cwd = typeof directory === "string" && directory.length > 0 ? directory : process.cwd()
 
   return {
+    /** Exact active-harness identity for shell commands such as \`notifai ask\`. */
+    "shell.env": async (input, output) => {
+      output.env.NOTIFAI_ACTIVE_HARNESS = "opencode"
+      const sessionID = input?.sessionID
+      if (typeof sessionID === "string" && sessionID.length > 0) {
+        output.env.NOTIFAI_ACTIVE_SESSION_ID = sessionID
+      }
+    },
+
     /**
      * Presence. The user typing is the signal every harness shares, and it is
      * also what publishes the project -> session pointer \`notifai ask\` reads.
      */
-    "chat.message": async (input) => {
-      await runHook("user-prompt-submit", {
+    "chat.message": async (input, output) => {
+      const stdout = await runHook("user-prompt-submit", {
         session_id: input?.sessionID ?? input?.info?.sessionID,
         cwd,
         hook_event_name: "UserPromptSubmit",
       })
+      const context = additionalContext(stdout)
+      if (context !== null) {
+        output.parts.push({
+          id: "prt_notifai_" + Date.now(),
+          sessionID: input.sessionID,
+          messageID: output.message.id,
+          type: "text",
+          text: context,
+          synthetic: true,
+        })
+      }
     },
 
     /** Session lifecycle events are delivered through OpenCode's event bus. */
@@ -185,17 +216,19 @@ export function isOurOpencodePlugin(contents: string): boolean {
  */
 export function opencodePluginTarget(
   contents: string,
-): { exec: string; script: string; current: boolean } | null {
+): { exec: string; script: string; current: boolean; timeoutSeconds?: number } | null {
   if (!isOurOpencodePlugin(contents)) return null
   const exec = /^const EXEC = (".*")$/m.exec(contents)?.[1]
   const script = /^const SCRIPT = (".*")$/m.exec(contents)?.[1]
   const version = Number(/^const ADAPTER_VERSION = (\d+)$/m.exec(contents)?.[1] ?? 1)
+  const timeoutMs = Number(/^const TIMEOUT_MS = (\d+)$/m.exec(contents)?.[1] ?? Number.NaN)
   if (exec === undefined || script === undefined) return null
   try {
     return {
       exec: JSON.parse(exec) as string,
       script: JSON.parse(script) as string,
       current: version === OPENCODE_ADAPTER_VERSION,
+      ...(Number.isFinite(timeoutMs) ? { timeoutSeconds: timeoutMs / 1000 } : {}),
     }
   } catch {
     return null

package/src/send.ts

@@ -1,7 +1,9 @@
 import {
   CLI_SOUNDS,
+  COLLAPSE_KEY_MAX_BYTES,
   INTERRUPTION_LEVELS,
   NOTIFICATION_SCHEMA_VERSION,
+  QUESTION_TEXT_MAX_LENGTH,
   type IosOptionsT,
   type LifecycleT,
   type MacosOptionsT,
@@ -9,6 +11,7 @@ import {
   NOTIFICATION_KINDS,
   PLATFORMS,
   type Platform,
+  type QuestionT,
   type SubmissionReceipt,
 } from '@raidiant/notifai-protocol'
 import type { CliConfig } from './config.js'
@@ -31,11 +34,8 @@ export interface SendFlags {
   ttl?: number
   collapseKey?: string
   sound?: string
-  badge?: number
   threadId?: string
   level?: string
-  relevance?: number
-  targetContentId?: string
   data?: string[]
   image?: string
   /** Enable the inline reply action for this Notification Request. */
@@ -43,10 +43,17 @@ export interface SendFlags {
   /** How long the server accepts a reply after submission. */
   replyWindow?: number
   /**
-   * Answer labels; turns the reply into a closed question. One value splits on
-   * commas; repeating the flag passes each label through verbatim.
+   * Answer labels; turns the reply into a closed question. One flag occurrence
+   * per label, always — a label is a label, whatever characters it contains.
    */
-  replyChoice?: string | string[]
+  replyChoice?: string[]
+  /** The user may select several of the offered answers. */
+  replyMulti?: boolean
+  /**
+   * A full question set, overriding the single question the flags describe.
+   * Not a user-facing flag: `ask --form` and the hooks build it.
+   */
+  questions?: QuestionT[]
   /** Platform whose optional notification fields these flags configure. */
   platform?: string
   /**
@@ -72,14 +79,21 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
   const targets: NotificationDraftT['targets'] =
     deviceIds && deviceIds.length > 0 ? { mode: 'selected', device_ids: deviceIds } : { mode: 'all' }
 
-  const sound = flags.sound ?? config.sound.value
+  const effectiveKind = flags.reply ? 'question' : (flags.kind ?? 'update')
+  const profile = KIND_PROFILES[effectiveKind as keyof typeof KIND_PROFILES]
+  const configuredSound = config.sound.source === 'default' ? undefined : config.sound.value
+  const sound = flags.sound ?? configuredSound ?? profile?.sound
   if (sound !== null && sound !== undefined && !CLI_SOUNDS.includes(sound as CliSound)) {
     return {
       ok: false,
       error: `Unknown sound "${sound}" — supported: ${CLI_SOUNDS.map((value) => `"${value}"`).join(', ')}.`,
     }
   }
-  const level = flags.level ?? config.interruption_level.value
+  const configuredLevel =
+    config.interruption_level.source === 'default'
+      ? undefined
+      : config.interruption_level.value
+  const level = flags.level ?? configuredLevel ?? profile?.level
   if (
     level !== null &&
     level !== undefined &&
@@ -93,13 +107,10 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
   else if (sound !== null && sound !== undefined) {
     options.sound = sound as Exclude<(typeof CLI_SOUNDS)[number], 'none'>
   }
-  if (flags.badge !== undefined) options.badge = flags.badge
   if (flags.threadId !== undefined) options.thread_id = flags.threadId
   if (level !== null && level !== undefined) {
     options.interruption_level = level as (typeof INTERRUPTION_LEVELS)[number]
   }
-  if (flags.relevance !== undefined) options.relevance_score = flags.relevance
-  if (flags.targetContentId !== undefined) options.target_content_id = flags.targetContentId
   if (flags.data?.length) {
     const data: Record<string, string> = {}
     for (const pair of flags.data) {
@@ -122,6 +133,16 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
 
   const ttl = flags.ttl ?? config.ttl_seconds.value
   const collapse = flags.collapseKey ?? config.collapse_key.value
+  if (
+    collapse !== null &&
+    collapse !== undefined &&
+    Buffer.byteLength(collapse, 'utf8') > COLLAPSE_KEY_MAX_BYTES
+  ) {
+    return {
+      ok: false,
+      error: `--collapse-key must be at most ${COLLAPSE_KEY_MAX_BYTES} UTF-8 bytes.`,
+    }
+  }
 
   const project = flags.project ?? config.project.value
   // Harnesses can export NOTIFAI_SESSION once instead of passing the flag
@@ -137,6 +158,24 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
       error: CHOICE_USAGE,
     }
   }
+  if (flags.replyMulti && choices === null && flags.questions === undefined) {
+    return { ok: false, error: '--reply-multi needs answers to select between; add --reply-choice.' }
+  }
+  // The banner body doubles as the question text on a single-question send, so
+  // it inherits the question's readable-in-full bound; context beyond that
+  // belongs in --detail, which never rides the banner.
+  if (
+    flags.reply &&
+    flags.questions === undefined &&
+    flags.body.length > QUESTION_TEXT_MAX_LENGTH
+  ) {
+    return {
+      ok: false,
+      error:
+        `A question must be readable where it is answered: keep it within ${QUESTION_TEXT_MAX_LENGTH} ` +
+        'characters and put the longer context in --detail.',
+    }
+  }
 
   const draft: NotificationDraftT = {
     schema_version: NOTIFICATION_SCHEMA_VERSION,
@@ -161,20 +200,35 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
     ...(flags.reply
       ? {
           reply: {
-            expires_in_seconds: flags.replyWindow ?? 86400,
-            ...(choices !== null ? { kind: 'choice' as const, choices } : {}),
+            expires_in_seconds: flags.replyWindow ?? 3600,
+            questions: flags.questions ?? [
+              {
+                id: 'q1',
+                text: flags.body,
+                ...(choices !== null ? { choices } : {}),
+                ...(flags.replyMulti ? { multi: true } : {}),
+              },
+            ],
           },
         }
       : {}),
     ...(Object.keys(options).length > 0
-      ? platform === 'ios'
-        ? { platform: { ios: options } }
-        : { platform: { macos: options } }
+      ? flags.platform === undefined
+        ? { platform: { ios: options, macos: options } }
+        : platform === 'ios'
+          ? { platform: { ios: options } }
+          : { platform: { macos: options } }
       : {}),
   }
   return { ok: true, draft, platform }
 }
 
+const KIND_PROFILES = {
+  update: { sound: 'none', level: 'passive' },
+  done: { sound: 'done', level: 'passive' },
+  question: { sound: 'attention', level: 'active' },
+} as const
+
 function resolvePlatform(value: string | undefined): Platform | null {
   if (value === undefined) return 'ios'
   return (PLATFORMS as readonly string[]).includes(value) ? (value as Platform) : null
@@ -209,23 +263,19 @@ export function receiptExitCode(receipt: SubmissionReceipt): number {
 }
 
 /**
- * `"Staging,Production"` -> `[{id:'staging',label:'Staging'}, ...]`.
+ * One flag occurrence, one answer: `--choice Staging --choice Production` ->
+ * `[{id:'staging',label:'Staging'}, ...]`.
  *
- * A single occurrence splits on commas, which keeps the common one-liner
- * short. Repeating the flag is the escape hatch, and the only way to write a
- * label that itself contains a comma: passing `"Yes, ship it,No"` as one value
- * silently yields three choices, and nothing downstream can detect that the
- * agent meant two.
+ * Commas are ordinary characters. The old single-value comma split produced
+ * buttons the agent never intended ("Nothing, I'll review" became two answers)
+ * and nothing downstream could detect it, so the delimiter form is gone
+ * rather than guarded: a label is a label.
  */
 export function parseChoices(
-  value: string | string[] | undefined,
+  value: string[] | undefined,
 ): { id: string; label: string }[] | null | 'invalid' {
-  if (value === undefined) return null
-  const raw = Array.isArray(value) ? value : [value]
-  if (raw.length === 0) return null
-  const labels = (raw.length === 1 ? (raw[0] ?? '').split(',') : raw)
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0)
+  if (value === undefined || value.length === 0) return null
+  const labels = value.map((part) => part.trim()).filter((part) => part.length > 0)
   if (labels.length < 2 || labels.length > 6) return 'invalid'
   const choices = labels.map((label) => ({ id: slugify(label), label }))
   if (choices.some((choice) => choice.id === '')) return 'invalid'
@@ -235,38 +285,10 @@ export function parseChoices(
 
 /** Message shared by every surface that accepts choice labels. */
 export const CHOICE_USAGE =
-  'Choices must be 2-6 non-empty labels, unique once slugified. One value splits on ' +
-  'commas ("Staging,Production"); repeat the flag when a label contains a comma.'
-
-/**
- * Catches the split that looked like it worked.
- *
- * `--choice "macOS parity,Long-form detail,Nothing, I'll review"` produced four
- * buttons rather than three, because the third label contained a comma. Nothing
- * downstream can detect it — the labels are all well-formed — and the CLI
- * cheerfully echoed the wrong list back, so the user saw buttons the agent
- * never intended.
- *
- * The tell is a comma followed by a space. A delimiter list is written
- * "Yes,No"; prose is written "Nothing, I'll review". That is a heuristic and it
- * will occasionally be wrong, which is exactly why this warns and names the
- * escape hatch rather than rejecting: the split may well have been intended.
- */
-export function ambiguousChoiceSplit(value: string | string[] | undefined): string | null {
-  if (value === undefined || Array.isArray(value)) return null
-  if (!/,\s/.test(value)) return null
-  const parts = value
-    .split(',')
-    .map((part) => part.trim())
-    .filter((part) => part.length > 0)
-  return (
-    `Heads up: "${value}" was split on commas into ${parts.length} answers ` +
-    `(${parts.join(' / ')}). If one of those labels was meant to contain a comma, ` +
-    'pass --choice once per answer instead.'
-  )
-}
+  'Offer 2-6 answers, one --choice flag per answer, unique once slugified — ' +
+  'e.g. --choice "Yes, ship it" --choice "Not yet".'
 
-function slugify(label: string): string {
+export function slugify(label: string): string {
   return label
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')

package/src/skill.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+const skill = readFileSync(new URL('../../../skills/notifai/SKILL.md', import.meta.url), 'utf8')
+const harnessReference = readFileSync(
+  new URL('../../../skills/notifai/references/harness-setup.md', import.meta.url),
+  'utf8',
+)
+
+describe('Notifai agent skill', () => {
+  it('leads with the notification decision before message composition', () => {
+    expect(skill.indexOf('## When to notify')).toBeGreaterThan(0)
+    expect(skill.indexOf('## When to notify')).toBeLessThan(skill.indexOf('## Compose and send'))
+  })
+
+  it('teaches kind profiles and a correctly classified completion', () => {
+    expect(skill).toContain('--kind done')
+    expect(skill).toContain('| `update` (default) | `none` | `passive` |')
+    expect(skill).toContain('| `done` | `done` | `passive` |')
+    expect(skill).toContain('| question (`--reply`) | `attention` | `active` |')
+  })
+
+  it('documents reply lifecycle, routing, session minting, and doctor exits', () => {
+    for (const required of [
+      '--reply-choice',
+      'notifai close <request_id>',
+      'notifai devices',
+      '--device',
+      '--all',
+      "require('node:crypto').randomUUID()",
+      'exit status is nonzero',
+    ]) {
+      expect(skill).toContain(required)
+    }
+  })
+
+  it('moves per-harness mechanics into progressive disclosure', () => {
+    expect(skill).toContain('[Harness setup and recovery](references/harness-setup.md)')
+    for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode']) {
+      expect(harnessReference).toContain(`**${harness}:**`)
+    }
+  })
+})