@raidiant/notifai 8.0.0 → 9.0.0

package/src/main.ts

@@ -2,7 +2,7 @@
 import { realIo, type CommandDeps } from './commands.js'
 import { defaultCredentialStore } from './credentials.js'
 import { nativeSkills } from './native-skills.js'
-import { bootstrapLogger } from './logging.js'
+import { argvFlagNames, bootstrapLogger } from './logging.js'
 import { buildProgram } from './program.js'
 
 /**
@@ -24,24 +24,12 @@ const deps: CommandDeps = {
   logger,
 }
 
-/**
- * Which flags were passed, without their values.
- *
- * The flag names answer nearly every question worth asking of an invocation —
- * was `--reply` set, was `--all` — while the values are notification content
- * and user text that has no business being recorded merely because a command
- * ran. Values are available under `log_level = debug`, which is a deliberate act.
- */
-function flagNames(argv: readonly string[]): string[] {
-  return argv.filter((token) => token.startsWith('--'))
-}
-
 const startedAt = Date.now()
 process.on('exit', (code) => {
   logger.info('cli.end', {
     exit: code,
     duration_ms: Date.now() - startedAt,
-    flags: flagNames(process.argv.slice(2)),
+    flags: argvFlagNames(process.argv.slice(2)),
   })
 })
 

package/src/native-skills.test.ts

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { describe, expect, it } from 'vitest'
-import { nativeSkills } from './native-skills.js'
+import { SKILLS_INSTALLER_SPEC, nativeSkills, skillsAddArgv, skillsRemoveArgv } from './native-skills.js'
 
 function writeLock(file: string, ref: string): void {
   mkdirSync(path.dirname(file), { recursive: true })
@@ -22,6 +22,46 @@ function writeLock(file: string, ref: string): void {
   )
 }
 
+describe('skillsAddArgv', () => {
+  it('pins the installer package to an exact reviewed version', () => {
+    const argv = skillsAddArgv({
+      source: 'Raidiant-io/notifai#v8.0.0',
+      skill: 'notifai',
+      cwd: '/tmp',
+      env: {},
+    })
+    expect(SKILLS_INSTALLER_SPEC).toMatch(/^skills@\d+\.\d+\.\d+$/)
+    expect(argv).toEqual([
+      '-y',
+      SKILLS_INSTALLER_SPEC,
+      'add',
+      'Raidiant-io/notifai#v8.0.0',
+      '--skill',
+      'notifai',
+    ])
+    expect(argv).not.toContain('skills')
+  })
+
+  it('uninstalls one skill in the named scope without a prompt', () => {
+    expect(
+      skillsRemoveArgv({
+        skill: 'notifai',
+        scope: 'project',
+        cwd: '/tmp',
+        env: {},
+      }),
+    ).toEqual(['-y', SKILLS_INSTALLER_SPEC, 'remove', 'notifai', '--yes'])
+    expect(
+      skillsRemoveArgv({
+        skill: 'notifai',
+        scope: 'global',
+        cwd: '/tmp',
+        env: {},
+      }),
+    ).toEqual(['-y', SKILLS_INSTALLER_SPEC, 'remove', 'notifai', '--global', '--yes'])
+  })
+})
+
 describe('nativeSkills.list', () => {
   it('reads the project lock file instead of spawning npx', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-skills-project-'))

package/src/native-skills.ts

@@ -3,6 +3,14 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { accountHome, npxLaunch } from './platform.js'
 
+/**
+ * Exact reviewed version of the external `skills` installer.
+ *
+ * The GitHub skill source stays the immutable CLI version tag. The installer
+ * program that fetches it must not float on `latest`.
+ */
+export const SKILLS_INSTALLER_SPEC = 'skills@1.5.23'
+
 /** The two scopes offered by the skills installer. */
 export type SkillScope = 'project' | 'global'
 
@@ -30,9 +38,18 @@ export interface SkillsAddOptions {
   env: NodeJS.ProcessEnv
 }
 
+export interface SkillsRemoveOptions {
+  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>
+  /** Uninstall one installer-managed skill in one scope. */
+  remove(options: SkillsRemoveOptions): Promise<number>
   /** Read installer-managed inventory from lock files. Does not spawn npx. */
   list(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): Promise<SkillsListResult>
 }
@@ -108,15 +125,32 @@ function run(args: string[], options: { cwd: string; env: NodeJS.ProcessEnv }):
   })
 }
 
+/** argv for `npx`, including the pinned installer spec. */
+export function skillsAddArgv(options: SkillsAddOptions): string[] {
+  const args = ['-y', SKILLS_INSTALLER_SPEC, '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 args
+}
+
+/** argv for uninstalling one skill in one installer scope. */
+export function skillsRemoveArgv(options: SkillsRemoveOptions): string[] {
+  const args = ['-y', SKILLS_INSTALLER_SPEC, 'remove', options.skill]
+  if (options.scope === 'global') args.push('--global')
+  args.push('--yes')
+  return args
+}
+
 /** 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 run(args, { cwd: options.cwd, env: options.env })
+    return run(skillsAddArgv(options), { cwd: options.cwd, env: options.env })
+  },
+
+  async remove(options) {
+    return run(skillsRemoveArgv(options), { cwd: options.cwd, env: options.env })
   },
 
   async list(scope, cwd, env) {

package/src/opencode-plugin.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import { hookHostPlatform, type HookHostPlatform } from './hook-adapter.js'
 import { configHome } from './install-hooks.js'
+import { SESSION_ACTIVATION_CONTEXT } from './session-activation.js'
 
 /**
  * The OpenCode adapter.
@@ -31,7 +32,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 = 8
+const OPENCODE_ADAPTER_VERSION = 10
 
 export function opencodePluginDir(
   global: boolean,
@@ -103,6 +104,7 @@ import { spawn } from "node:child_process"
 ${nodeConstant}const ADAPTER = ${JSON.stringify(adapterPath)}
 const TIMEOUT_MS = ${timeoutSeconds * 1000}
 const ADAPTER_VERSION = ${OPENCODE_ADAPTER_VERSION}
+const SESSION_ACTIVATION_CONTEXT = ${JSON.stringify(SESSION_ACTIVATION_CONTEXT)}
 const PENDING_SESSION_TITLE =
   /^New session(?: *- *[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]+)?Z)?$/i
 
@@ -158,6 +160,17 @@ export const NotifAIPlugin = async ({ directory, client }) => {
   const cwd = typeof directory === "string" && directory.length > 0 ? directory : process.cwd()
 
   return {
+    /** Model-visible activation, independent of CLI setup and delivery state. */
+    "experimental.chat.system.transform": async (input, output) => {
+      const sessionID = input?.sessionID
+      if (typeof sessionID !== "string" || sessionID.length === 0) return
+      if (output.system.length === 0) {
+        output.system.push(SESSION_ACTIVATION_CONTEXT)
+      } else {
+        output.system[0] = output.system[0] + "\\n\\n" + SESSION_ACTIVATION_CONTEXT
+      }
+    },
+
     /** Exact active-harness identity and first-party title for agent shell commands. */
     "shell.env": async (input, output) => {
       output.env.NOTIFAI_ACTIVE_HARNESS = "opencode"

package/src/program.test.ts

@@ -82,7 +82,6 @@ describe('program argv parsing', () => {
         '--multi',
         '--reply',
         '--reply-timeout', '30',
-        '--event', 'tests_passed',
       ],
       { send: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['send'] },
     )
@@ -95,7 +94,6 @@ describe('program argv parsing', () => {
       multi: true,
       reply: true,
       replyTimeout: 30,
-      event: 'tests_passed',
       noWait: false,
     })
   })
@@ -113,6 +111,16 @@ describe('program argv parsing', () => {
     expect(seen).not.toHaveProperty('wait')
   })
 
+  it('maps init --setup-scope onto the command flags', async () => {
+    let seen: Record<string, unknown> | undefined
+    const { exitCode } = await parse(
+      ['init', '--skills', '--setup-scope', 'global', '--no-hooks'],
+      { init: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['init'] },
+    )
+    expect(exitCode).toBe(0)
+    expect(seen).toMatchObject({ skills: true, setupScope: 'global', hooks: false })
+  })
+
   it('disentangles --no-wait and --wait from their shared commander flag', async () => {
     const capture = (sink: Record<string, unknown>[]): ProgramRunners['send'] =>
       (async (_deps, flags) => (sink.push(flags as Record<string, unknown>), 0)) as ProgramRunners['send']
@@ -191,6 +199,15 @@ describe('program argv parsing', () => {
     expect(deps.errLines.join('\n')).toContain('send')
   })
 
+  it('rejects send --event now that the public event field is gone', async () => {
+    const { exitCode, deps } = await parse(
+      ['send', '--kind', 'done', '--title', 'T', '--body', 'B', '--event', 'tests_passed'],
+      { send: (async () => 0) as ProgramRunners['send'] },
+    )
+    expect(exitCode).toBe(2)
+    expect(deps.errLines).toHaveLength(0)
+  })
+
   it('drops the empty --event collector for logs', async () => {
     let seen: Record<string, unknown> | undefined
     const logs = ((_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['logs']
@@ -199,4 +216,22 @@ describe('program argv parsing', () => {
     await parse(['logs', '--event', 'send.submitted'], { logs })
     expect(seen).toMatchObject({ event: ['send.submitted'] })
   })
+
+  it('passes close --pending without inventing a request id', async () => {
+    let seenId: string | undefined
+    let seenFlags: Record<string, unknown> | undefined
+    const close = (async (_deps, requestId, flags) => {
+      seenId = requestId
+      seenFlags = flags as Record<string, unknown>
+      return 0
+    }) as ProgramRunners['close']
+
+    await parse(['close', '--pending', '--json'], { close })
+    expect(seenId).toBeUndefined()
+    expect(seenFlags).toEqual({ pending: true, json: true })
+
+    await parse(['close', 'req_abc'], { close })
+    expect(seenId).toBe('req_abc')
+    expect(seenFlags).toEqual({})
+  })
 })

package/src/program.ts

@@ -35,6 +35,7 @@ import type { Platform } from '@raidiant/notifai-protocol'
 import type { SkillScope } from './native-skills.js'
 import { GROUP, SEND_GROUP, helpConfiguration, rootHelpFooter } from './ui/help.js'
 import { readStdinWithTimeout } from './hook-input.js'
+import { argvFlagNames } from './logging.js'
 
 /**
  * One source of truth for the version: the manifest npm actually published.
@@ -149,7 +150,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       if (!deferDiagnostics) {
         logger?.debug('cli.start', {
           version: version(),
-          argv: process.argv.slice(2),
+          flags: argvFlagNames(process.argv.slice(2)),
           cwd: process.cwd(),
         })
       }
@@ -217,12 +218,24 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--project-id <id>', 'project identifier slug (default: derived from the directory name)')
     .option('--skills', 'install/update the agent skill from its pinned public release')
     .option('--no-skills', 'suppress the optional agent-skill status line')
-    .option('--skills-scope <scope>', 'unattended skill scope: project or global')
+    .option(
+      '--setup-scope <scope>',
+      'unattended setup scope: project or global (skill, hooks, and config). The CLI binary is always a global install',
+    )
+    .option('--skills-scope <scope>', 'unattended skill scope; same values as --setup-scope')
     .option('--hooks', 'install harness hooks for registered-question routing')
     .option('--no-hooks', 'skip the hooks without being asked')
-    .action(async (opts: { projectId?: string; skills?: boolean; skillsScope?: SkillScope; hooks?: boolean }) => {
-      exit(await runners.init(deps, opts))
-    })
+    .action(
+      async (opts: {
+        projectId?: string
+        skills?: boolean
+        setupScope?: SkillScope
+        skillsScope?: SkillScope
+        hooks?: boolean
+      }) => {
+        exit(await runners.init(deps, opts))
+      },
+    )
 
   program
     .command('doctor')
@@ -240,7 +253,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .summary('Sign in and pair this machine')
     .description('Pair this machine with your Notifai account via browser approval')
     .option('--name <name>', 'machine name shown in the dashboard (default: hostname)')
-    .option('--base-url <url>', 'developer override for the service origin (also NOTIFAI_BASE_URL)')
+    .option('--base-url <url>', 'pairing override for the service origin (also NOTIFAI_BASE_URL)')
     .option('--no-open', 'do not open the approval page in a browser')
     .action(async (opts: { name?: string; baseUrl?: string; open?: boolean }) => {
       exit(await runners.login(deps, opts))
@@ -306,6 +319,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .requiredOption('--title <title>', 'brief title whose substance is immediately understandable')
     .option('--body <markdown>', 'canonical Markdown body')
     .option('--body-file <path>', 'read the canonical Markdown body from a file (use - for stdin)')
+    .option(
+      '--literal-backslash-n',
+      'allow the two-character sequence \\n in --body instead of treating it as a mistaken escaped newline',
+    )
     .option('--subtitle <subtitle>', 'a plain-text line between the title and body')
     .option(
       '--image <path|url|media_id>',
@@ -318,7 +335,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       (v: string, all: string[] = []) => [...all, v],
     )
     .optionsGroup(SEND_GROUP.routing)
-    .option('--kind <kind>', 'what this is (required): update | done | failed | blocked — question is set by --reply')
+    .option('--kind <kind>', 'what this is (required): update | done | failed | blocked (no User reply would resume it) — question is set by --reply')
     .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
     .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[] = []) => [...all, v])
     .option('--all', 'target all routable devices (overrides configured devices)')
@@ -327,7 +344,6 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       '--session-label <text>',
       'first human session name, frozen locally (env: NOTIFAI_SESSION_LABEL)',
     )
-    .option('--event <event>', 'agent event name, e.g. tests_passed')
     .optionsGroup(SEND_GROUP.presentation)
     .option('--collapse-key <key>', 'replace earlier notifications with the same key')
     .option('--thread-id <id>', 'group related notifications')
@@ -357,7 +373,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--no-wait', 'return immediately after acceptance')
     .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[] = []) => [...all, v])
     .option('--idempotency-key <key>', 'safe-retry key (default: random)')
-    .option('--base-url <url>', 'developer override for the service origin (also NOTIFAI_BASE_URL)')
+    .option(
+      '--base-url <url>',
+      'pairing override for the service origin; ignored when this machine is already paired (also NOTIFAI_BASE_URL)',
+    )
     .option('--json', 'print the full submission receipt as JSON')
     .action(async (opts: Record<string, unknown>) => {
       // commander maps --no-wait onto the same "wait" flag; disentangle.
@@ -443,6 +462,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--json', 'machine-readable output')
     .option('--body <markdown>', 'optional Markdown context appended after the question block')
     .option('--body-file <path>', 'read optional Markdown context from a file (use - for stdin)')
+    .option(
+      '--literal-backslash-n',
+      'allow the two-character sequence \\n in --body instead of treating it as a mistaken escaped newline',
+    )
     .option('--form <path>', 'ask several questions as one form; JSON file (use - for stdin)')
     .option(
       '--image <path|url|media_id>',
@@ -466,6 +489,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       json?: boolean
       body?: string
       bodyFile?: string
+      literalBackslashN?: boolean
       form?: string
       image?: string[]
       imageAlt?: string[]
@@ -507,17 +531,21 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
         ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
         ...(opts.sessionLabel !== undefined ? { sessionLabel: opts.sessionLabel } : {}),
         ...(opts.json === true ? { json: true } : {}),
+        ...(opts.literalBackslashN === true ? { literalBackslashN: true } : {}),
       }
       exit(await runners.ask(deps, question, flags))
     })
 
   program
-    .command('close <request_id>')
+    .command('close [request_id]')
     .helpGroup(GROUP.agent)
     .summary('Retire a question so late answers are rejected')
-    .description('Retire a question so late answers are rejected rather than lost')
+    .description(
+      'Retire a question so late answers are rejected rather than lost. Pass --pending to withdraw this session\'s outstanding registrations, including ones the turn-end hook has not pushed yet.',
+    )
+    .option('--pending', 'retire this session\'s outstanding questions, including ones not yet pushed')
     .option('--json', 'machine-readable output')
-    .action(async (requestId: string, opts: { json?: boolean }) => {
+    .action(async (requestId: string | undefined, opts: { json?: boolean; pending?: boolean }) => {
       exit(await runners.close(deps, requestId, opts))
     })
 

package/src/send.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import {
+  accidentalEscapedNewlineMessage,
+  hasAccidentalEscapedNewlines,
+  rejectAccidentalEscapedNewlines,
+} from './send.js'
+
+describe('accidental escaped newlines', () => {
+  it('catches a shell-quoted backslash-n body', () => {
+    expect(hasAccidentalEscapedNewlines('line1\\nline2')).toBe(true)
+    expect(rejectAccidentalEscapedNewlines('line1\\nline2', false)).toBe(
+      accidentalEscapedNewlineMessage(),
+    )
+  })
+
+  it('preserves real multiline Markdown', () => {
+    expect(hasAccidentalEscapedNewlines('line1\nline2')).toBe(false)
+    expect(rejectAccidentalEscapedNewlines('line1\nline2', false)).toBeNull()
+  })
+
+  it('lets an explicit flag keep visible backslash-n text', () => {
+    expect(rejectAccidentalEscapedNewlines('use \\n in the sample', true)).toBeNull()
+  })
+
+  it('does not treat an escaped backslash plus n as accidental', () => {
+    expect(hasAccidentalEscapedNewlines('escape as \\\\n')).toBe(false)
+  })
+})

package/src/send.ts

@@ -31,7 +31,6 @@ export interface SendFlags {
   /** The one canonical Markdown body. */
   body: string
   subtitle?: string
-  event?: string
   /** What this notification is; absent means update. */
   kind?: string
   project?: string
@@ -80,6 +79,34 @@ export interface SendFlags {
    * questions and their retirements ride the wire as what they are.
    */
   lifecycle?: LifecycleT
+  /**
+   * Allow the two-character sequence backslash-n to be sent as visible text.
+   * Without this, a likely accidental escaped newline is refused.
+   */
+  literalBackslashN?: boolean
+}
+
+/** A backslash-n pair that was not itself escaped as a literal backslash. */
+const ACCIDENTAL_ESCAPED_NEWLINE = /(?:^|[^\\])\\n/
+
+export function hasAccidentalEscapedNewlines(body: string): boolean {
+  return ACCIDENTAL_ESCAPED_NEWLINE.test(body)
+}
+
+export function accidentalEscapedNewlineMessage(): string {
+  return [
+    'This body contains the two-character sequence \\n, which is sent literally and shows as \\n on the device.',
+    'To send a real line break, pass a multiline --body or --body-file -.',
+    'If you meant the visible characters \\n, pass --literal-backslash-n.',
+  ].join('\n')
+}
+
+export function rejectAccidentalEscapedNewlines(
+  body: string | undefined,
+  allowLiteral: boolean | undefined,
+): string | null {
+  if (allowLiteral === true || body === undefined) return null
+  return hasAccidentalEscapedNewlines(body) ? accidentalEscapedNewlineMessage() : null
 }
 
 export type DraftBuild =
@@ -309,7 +336,6 @@ export function buildDraft(
 
   const draft: NotificationDraftT = {
     schema_version: NOTIFICATION_SCHEMA_VERSION,
-    ...(flags.event !== undefined ? { event: flags.event } : {}),
     ...(flags.kind !== undefined
       ? { kind: flags.kind as (typeof NOTIFICATION_KINDS)[number] }
       : {}),

package/src/session-activation.ts

@@ -0,0 +1,45 @@
+import type { HookHarness } from './hooks.js'
+
+/**
+ * Model-visible session bootstrap. It names the installed capability and its
+ * authoritative sources without restating any notification policy that the
+ * user may have overridden.
+ */
+export const SESSION_ACTIVATION_CONTEXT =
+  'Notifai is active for this session, even when the user did not mention it. ' +
+  'Before beginning task work, use the Notifai skill and run `notifai guidance`; its resolved guidance governs notification decisions for Agent Events. ' +
+  'Missing skill or CLI readiness is handled through `notifai init` and its diagnosis. ' +
+  'For delegated work, the parent owns User-visible Notification Requests unless it explicitly delegates that ownership; workers report Agent Events to the parent and do not send independently.'
+
+/** One lifecycle meaning, encoded for each harness output contract. */
+export function sessionActivationOutput(
+  harness: HookHarness | undefined,
+  hookEventName: 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit',
+): string | undefined {
+  if (harness === 'cursor') {
+    return JSON.stringify({ additional_context: SESSION_ACTIVATION_CONTEXT })
+  }
+  if (harness === 'claude-code' || harness === 'codex') {
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext: SESSION_ACTIVATION_CONTEXT,
+      },
+    })
+  }
+  return undefined
+}
+
+/**
+ * Cursor currently accepts sessionStart context without reliably delivering it
+ * to the model. Its native post-Stop follow-up is the narrow fallback and is
+ * claimed once per conversation by the hook-state layer.
+ */
+export function cursorStopActivationOutput(): string {
+  return JSON.stringify({
+    followup_message: SESSION_ACTIVATION_CONTEXT.replace(
+      'Before beginning task work,',
+      'Before finalizing the Agent Event from the turn that just ended,',
+    ),
+  })
+}