@raidiant/notifai 10.0.0 → 10.1.0

package/src/openclaw-plugin.ts

@@ -0,0 +1,409 @@
+import path from 'node:path'
+import { hookHostPlatform, type HookHostPlatform } from './hook-adapter.js'
+import { harnessAccountHome } from './install-hooks.js'
+import {
+  MISSING_LIFECYCLE_GUIDANCE_CONTEXT,
+  WORKER_ACTIVATION_CONTEXT,
+} from './session-activation.js'
+
+/**
+ * The OpenClaw adapter.
+ *
+ * OpenClaw's extension point is an in-process Gateway plugin, not a command
+ * hook. The generated module shells out to the same `notifai hook <event>`
+ * commands every other harness invokes, so presence, activation, and
+ * retirement stay in the CLI.
+ *
+ *   before_prompt_build -> session-start / subagent-start  (first owner/worker)
+ *   message_received    -> user-prompt-submit              (User is present)
+ *   agent_end           -> stop                            (the turn ended)
+ *   session_end         -> session-end                     (retire local state)
+ *   resolve_exec_env    -> NOTIFAI_ACTIVE_* markers        (exact Source Context)
+ *
+ * `command:stop` is a User abort and is deliberately not wired. Asynchronous
+ * ask is unsupported until a live continuation probe.
+ */
+
+export const OPENCLAW_PLUGIN_MARKER = '// notifai managed openclaw plugin'
+export const OPENCLAW_PLUGIN_ID = 'notifai'
+export const OPENCLAW_PLUGIN_FILENAME = 'index.js'
+export const OPENCLAW_PLUGIN_MANIFEST = 'openclaw.plugin.json'
+export const OPENCLAW_PLUGIN_PACKAGE = 'package.json'
+
+const OPENCLAW_ADAPTER_VERSION = 1
+
+export const OPENCLAW_EVENTS = [
+  ['SessionStart', 'session-start'],
+  ['SubagentStart', 'subagent-start'],
+  ['UserPromptSubmit', 'user-prompt-submit'],
+  ['Stop', 'stop'],
+  ['SessionEnd', 'session-end'],
+] as const
+
+export function openclawStateDir(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  const override = env['OPENCLAW_STATE_DIR']
+  if (override !== undefined && override !== '') return override
+  const homeOverride = env['OPENCLAW_HOME']
+  if (homeOverride !== undefined && homeOverride !== '') {
+    return path.join(homeOverride, '.openclaw')
+  }
+  return path.join(harnessAccountHome(env, platform), '.openclaw')
+}
+
+export function openclawConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  const override = env['OPENCLAW_CONFIG_PATH']
+  if (override !== undefined && override !== '') return override
+  return path.join(openclawStateDir(env, platform), 'openclaw.json')
+}
+
+export function openclawPluginDir(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  return global
+    ? path.join(openclawStateDir(env, platform), 'extensions', OPENCLAW_PLUGIN_ID)
+    : path.join(cwd, '.openclaw', 'extensions', OPENCLAW_PLUGIN_ID)
+}
+
+export function openclawPluginPath(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): string {
+  return path.join(openclawPluginDir(global, cwd, env, platform), OPENCLAW_PLUGIN_FILENAME)
+}
+
+export interface OpenclawPluginOptions {
+  adapterPath: string
+  timeoutSeconds: number
+  platform?: NodeJS.Platform | HookHostPlatform
+  nodePath?: string
+}
+
+export function openclawPluginManifest(): string {
+  return `${JSON.stringify(
+    {
+      id: OPENCLAW_PLUGIN_ID,
+      name: 'Notifai',
+      description: 'Notifai lifecycle activation, Source Context, and session observation.',
+      activation: { onStartup: true },
+      configSchema: { type: 'object', additionalProperties: false },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+export function openclawPluginPackage(): string {
+  return `${JSON.stringify(
+    {
+      name: 'notifai-openclaw',
+      version: '1.0.0',
+      type: 'module',
+      openclaw: { extensions: [`./${OPENCLAW_PLUGIN_FILENAME}`] },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+export function openclawPluginSource(options: OpenclawPluginOptions): string {
+  const { adapterPath, timeoutSeconds } = options
+  const win32 = hookHostPlatform(options.platform) === 'win32'
+  const nodeConstant = win32
+    ? `const NODE = ${JSON.stringify(options.nodePath ?? process.execPath)}\n`
+    : ''
+  const spawnArguments = win32
+    ? 'NODE, [ADAPTER, "hook", event, "--owner", "notifai", "--harness", "openclaw"]'
+    : 'ADAPTER, ["hook", event, "--owner", "notifai", "--harness", "openclaw"]'
+  const windowsHide = win32 ? '\n        windowsHide: true,' : ''
+  return `${OPENCLAW_PLUGIN_MARKER}
+// Generated by \`notifai hooks install --harness openclaw\`. Edits are lost on
+// the next install; change the CLI instead, which is where the logic lives.
+import { spawn } from "node:child_process"
+
+${nodeConstant}const ADAPTER = ${JSON.stringify(adapterPath)}
+const TIMEOUT_MS = ${timeoutSeconds * 1000}
+const ADAPTER_VERSION = ${OPENCLAW_ADAPTER_VERSION}
+const MISSING_LIFECYCLE_GUIDANCE_CONTEXT = ${JSON.stringify(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)}
+const WORKER_ACTIVATION_CONTEXT = ${JSON.stringify(WORKER_ACTIVATION_CONTEXT)}
+
+function runHook(event, envelope) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(${spawnArguments}, {
+        env: process.env,
+        shell: false,${windowsHide}
+        stdio: ["pipe", "pipe", "pipe"],
+      })
+    } catch {
+      resolve(null)
+      return
+    }
+
+    let stdout = ""
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM")
+      finish(null)
+    }, TIMEOUT_MS)
+
+    child.stdout?.setEncoding("utf-8")
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk
+    })
+    child.stderr?.resume()
+    child.on("error", () => finish(null))
+    child.on("close", () => finish(stdout))
+
+    try {
+      child.stdin?.end(JSON.stringify(envelope))
+    } catch {
+      finish(null)
+    }
+  })
+}
+
+function sessionKeyOf(event, ctx) {
+  const key = ctx?.sessionKey ?? event?.sessionKey ?? event?.context?.sessionKey
+  return typeof key === "string" ? key.trim() : ""
+}
+
+function workspaceDirOf(event, ctx) {
+  const dir = ctx?.workspaceDir ?? event?.workspaceDir ?? event?.context?.workspaceDir
+  return typeof dir === "string" && dir.length > 0 ? dir : process.cwd()
+}
+
+function isWorkerSession(sessionKey, ctx) {
+  if (sessionKey === "") return true
+  if (sessionKey.includes(":subagent:")) return true
+  if (sessionKey.includes(":acp:")) return true
+  if (ctx?.targetKind === "acp" || ctx?.dispatchKind === "acp") return true
+  if (typeof ctx?.parentSessionKey === "string" && ctx.parentSessionKey.length > 0) return true
+  return false
+}
+
+function isUserMessage(event, ctx) {
+  const from = event?.from ?? event?.context?.from ?? ctx?.senderId
+  if (typeof from !== "string" || from.trim().length === 0) return false
+  const trigger = ctx?.trigger ?? event?.trigger
+  if (trigger === "cron" || trigger === "heartbeat") return false
+  return true
+}
+
+function register(api) {
+  const activated = new Set()
+  api.on("before_prompt_build", async (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return { prependContext: WORKER_ACTIVATION_CONTEXT }
+    if (activated.has(sessionKey)) return
+    const worker = isWorkerSession(sessionKey, ctx)
+    const resolved = await runHook(worker ? "subagent-start" : "session-start", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: worker ? "SubagentStart" : "SessionStart",
+    })
+    const context = typeof resolved === "string" && resolved.trim().length > 0
+      ? resolved.trim()
+      : worker ? WORKER_ACTIVATION_CONTEXT : MISSING_LIFECYCLE_GUIDANCE_CONTEXT
+    activated.add(sessionKey)
+    return { prependContext: context }
+  })
+
+  api.on("message_received", async (event, ctx) => {
+    if (!isUserMessage(event, ctx)) return
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    await runHook("user-prompt-submit", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: "UserPromptSubmit",
+    })
+  })
+
+  api.on("agent_end", async (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    await runHook("stop", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: "Stop",
+    })
+  })
+
+  api.on("session_end", async (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    activated.delete(sessionKey)
+    await runHook("session-end", {
+      session_id: sessionKey,
+      cwd: workspaceDirOf(event, ctx),
+      hook_event_name: "SessionEnd",
+    })
+  })
+
+  api.on("resolve_exec_env", (event, ctx) => {
+    const sessionKey = sessionKeyOf(event, ctx)
+    if (sessionKey === "") return
+    return {
+      NOTIFAI_ACTIVE_HARNESS: "openclaw",
+      NOTIFAI_ACTIVE_SESSION_ID: sessionKey,
+    }
+  })
+}
+
+export default {
+  id: ${JSON.stringify(OPENCLAW_PLUGIN_ID)},
+  name: "Notifai",
+  register,
+}
+`
+}
+
+export function isOurOpenclawPlugin(contents: string): boolean {
+  return contents.includes(OPENCLAW_PLUGIN_MARKER)
+}
+
+export function openclawPluginTarget(
+  contents: string,
+): { adapter: string; current: boolean; timeoutSeconds?: number; nodePath?: string } | null {
+  if (!isOurOpenclawPlugin(contents)) return null
+  const adapter = /^const ADAPTER = (".*")$/m.exec(contents)?.[1]
+  const node = /^const NODE = (".*")$/m.exec(contents)?.[1]
+  const version = Number(/^const ADAPTER_VERSION = (\d+)$/m.exec(contents)?.[1] ?? 0)
+  const timeoutMs = Number(/^const TIMEOUT_MS = (\d+)$/m.exec(contents)?.[1] ?? Number.NaN)
+  if (adapter === undefined) return null
+  try {
+    return {
+      adapter: JSON.parse(adapter) as string,
+      current: version === OPENCLAW_ADAPTER_VERSION,
+      ...(Number.isFinite(timeoutMs) ? { timeoutSeconds: timeoutMs / 1000 } : {}),
+      ...(node === undefined ? {} : { nodePath: JSON.parse(node) as string }),
+    }
+  } catch {
+    return null
+  }
+}
+
+export function parseOpenclawConfig(source: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(source)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    const stripped = source
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/^\s*\/\/.*$/gm, '')
+      .replace(/,(\s*[}\]])/g, '$1')
+    const parsed: unknown = JSON.parse(stripped)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  }
+  throw new Error('OpenClaw config is not a JSON object')
+}
+
+export function mergeOpenclawNotifaiEntry(
+  config: Record<string, unknown>,
+  pluginDir: string,
+  global: boolean,
+): Record<string, unknown> {
+  const plugins =
+    config.plugins !== null && typeof config.plugins === 'object' && !Array.isArray(config.plugins)
+      ? { ...(config.plugins as Record<string, unknown>) }
+      : {}
+  const entries =
+    plugins.entries !== null && typeof plugins.entries === 'object' && !Array.isArray(plugins.entries)
+      ? { ...(plugins.entries as Record<string, unknown>) }
+      : {}
+  const existing =
+    entries[OPENCLAW_PLUGIN_ID] !== null &&
+    typeof entries[OPENCLAW_PLUGIN_ID] === 'object' &&
+    !Array.isArray(entries[OPENCLAW_PLUGIN_ID])
+      ? { ...(entries[OPENCLAW_PLUGIN_ID] as Record<string, unknown>) }
+      : {}
+  const hooks =
+    existing.hooks !== null && typeof existing.hooks === 'object' && !Array.isArray(existing.hooks)
+      ? { ...(existing.hooks as Record<string, unknown>) }
+      : {}
+  entries[OPENCLAW_PLUGIN_ID] = {
+    ...existing,
+    enabled: true,
+    hooks: { ...hooks, allowConversationAccess: true },
+  }
+  plugins.entries = entries
+  if (!global) {
+    const load =
+      plugins.load !== null && typeof plugins.load === 'object' && !Array.isArray(plugins.load)
+        ? { ...(plugins.load as Record<string, unknown>) }
+        : {}
+    const paths = Array.isArray(load.paths) ? [...load.paths] : []
+    if (!paths.includes(pluginDir)) paths.push(pluginDir)
+    load.paths = paths
+    plugins.load = load
+  }
+  return { ...config, plugins }
+}
+
+export function removeOpenclawNotifaiEntry(
+  config: Record<string, unknown>,
+  pluginDir: string,
+): Record<string, unknown> {
+  const plugins =
+    config.plugins !== null && typeof config.plugins === 'object' && !Array.isArray(config.plugins)
+      ? { ...(config.plugins as Record<string, unknown>) }
+      : {}
+  const entries =
+    plugins.entries !== null && typeof plugins.entries === 'object' && !Array.isArray(plugins.entries)
+      ? { ...(plugins.entries as Record<string, unknown>) }
+      : {}
+  delete entries[OPENCLAW_PLUGIN_ID]
+  if (Object.keys(entries).length > 0) plugins.entries = entries
+  else delete plugins.entries
+  const load =
+    plugins.load !== null && typeof plugins.load === 'object' && !Array.isArray(plugins.load)
+      ? { ...(plugins.load as Record<string, unknown>) }
+      : {}
+  if (Array.isArray(load.paths)) {
+    const paths = load.paths.filter((value) => value !== pluginDir)
+    if (paths.length > 0) load.paths = paths
+    else delete load.paths
+  }
+  if (Object.keys(load).length > 0) plugins.load = load
+  else delete plugins.load
+  if (Object.keys(plugins).length > 0) return { ...config, plugins }
+  const next = { ...config }
+  delete next.plugins
+  return next
+}
+
+/** Config-directory presence is not ownership. These files mean OpenClaw is actually configured. */
+export function openclawHasGlobalEvidence(
+  exists: (file: string) => boolean,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform | HookHostPlatform = process.platform,
+): boolean {
+  const state = openclawStateDir(env, platform)
+  return (
+    exists(openclawConfigPath(env, platform)) ||
+    exists(path.join(state, 'agents')) ||
+    exists(path.join(state, 'workspace'))
+  )
+}

package/src/program.ts

@@ -180,11 +180,12 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
   /**
    * Bare `notifai`.
    *
-   * At a human terminal this opens the interactive app; anywhere else it prints
-   * help exactly as before. The check is the same one every other prompt in this
-   * CLI is gated on — stdin and stdout both TTYs, not CI, `NOTIFAI_NO_INPUT`
-   * unset — because an agent that reaches a prompt does not fail, it hangs
-   * for ever waiting on a stdin nobody is typing into.
+   * At a human terminal this opens the interactive app, which enters `init`
+   * when the machine is not yet paired and otherwise offers daily actions.
+   * Anywhere else it prints help exactly as before. The check is the same one
+   * every other prompt in this CLI is gated on — stdin and stdout both TTYs,
+   * not CI, `NOTIFAI_NO_INPUT` unset — because an agent that reaches a prompt
+   * does not fail, it hangs for ever waiting on a stdin nobody is typing into.
    */
   /**
    * An unrecognised subcommand reaches the root as an excess argument, and
@@ -292,7 +293,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
 
   program
     .command('login')
-    .helpGroup(GROUP.start)
+    .helpGroup(GROUP.advanced)
     .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)')
@@ -641,7 +642,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .description('Wire this harness to route registered questions to your devices')
     .option(
       '--harness <name>',
-      'claude-code | codex | cursor | opencode (default: every detected harness)',
+      'claude-code | codex | cursor | opencode | openclaw (default: every detected harness)',
     )
     .option('--global', 'install for every project instead of just this one')
     .action((opts: { harness?: string; global?: boolean }) => {
@@ -650,7 +651,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
   hooks
     .command('uninstall')
     .description('Remove the hooks this CLI installed')
-    .option('--harness <name>', 'claude-code | codex | cursor | opencode (default: detected)')
+    .option('--harness <name>', 'claude-code | codex | cursor | opencode | openclaw (default: detected)')
     .option('--global', 'remove the machine-wide install')
     .action((opts: { harness?: string; global?: boolean }) => {
       exit(runners.hooksUninstall(deps, opts))

package/src/session-activation.ts

@@ -31,7 +31,7 @@ export function sessionActivationOutput(
   const context = hookEventName === 'SubagentStart'
     ? WORKER_ACTIVATION_CONTEXT
     : rootActivationContext(cwd, env)
-  if (harness === 'opencode') return context
+  if (harness === 'opencode' || harness === 'openclaw') return context
   if (harness === 'cursor') {
     return JSON.stringify({ additional_context: context })
   }

package/src/skill.test.ts

@@ -252,7 +252,7 @@ describe('Notifai agent skill', () => {
     // Harness names may appear only in setup/routing material, where the
     // harness IS the subject.
     for (const heading of ['## Decide whether to notify', '## Send', '## Ask a question', '## When the answer arrives']) {
-      expect(section(heading), heading).not.toMatch(/OpenCode|Orca|Cursor|Codex|Hermes/)
+      expect(section(heading), heading).not.toMatch(/OpenCode|OpenClaw|Orca|Cursor|Codex|Hermes/)
     }
   })
 
@@ -397,7 +397,7 @@ describe('Notifai agent skill', () => {
   it('moves per-harness mechanics into progressive disclosure', () => {
     expect(skill).toContain('[Harness setup and recovery](references/harness-setup.md)')
     expect(skill).toMatch(/read it when you are\s+installing hooks or diagnosing routing/i)
-    for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode', 'Hermes']) {
+    for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode', 'OpenClaw', 'Hermes']) {
       expect(harnessReference).toContain(`**${harness}:**`)
     }
     expect(harnessReference).toMatch(/exact `HERMES_SESSION_ID`/i)

package/src/ui/help.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { rootHelpFooter } from './help.js'
+
+function stripAnsi(text: string): string {
+  return text.replace(/\u001B\[[0-9;]*m/g, '')
+}
+
+describe('rootHelpFooter', () => {
+  it('leads first-run with init, not the interactive app', () => {
+    const footer = stripAnsi(rootHelpFooter())
+    const start = footer.slice(footer.indexOf('Start here'))
+    const firstCommand = start.match(/notifai(?: init)?/)?.[0]
+    expect(firstCommand).toBe('notifai init')
+    expect(start.indexOf('notifai init')).toBeLessThan(start.search(/notifai\s{2,}/))
+  })
+})

package/src/ui/help.ts

@@ -1,8 +1,8 @@
 /**
  * Help that answers "what can I do here", not "what strings does argv accept".
  *
- * The old help listed seventeen commands in one flat column, with the two a new
- * user needs (`init`, `login`) sitting between a platform capability dump and
+ * The old help listed seventeen commands in one flat column, with the one a new
+ * user needs (`init`) sitting between a platform capability dump and
  * an entry point marked "Internal:". Everything was equally prominent, which is
  * the same as nothing being prominent.
  *
@@ -102,18 +102,17 @@ export const helpConfiguration: HelpConfiguration = {
 /**
  * Footer for the root help.
  *
- * Its whole job is to make the interactive app discoverable, because someone
- * reading a wall of flags has already demonstrated they did not know it was
- * there.
+ * First-run is `notifai init`. The interactive app is what a human opens
+ * later, once setup is no longer the thing in the way.
  */
 export function rootHelpFooter(): string {
   const lines = [
     '',
     style.heading('Start here'),
+    `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
     `  ${style.code('notifai')}              ${style.dim(
-      `${glyph.arrow} the interactive app: status, settings, devices, test sends`,
+      `${glyph.arrow} after setup: status, settings, devices, test sends`,
     )}`,
-    `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
     '',
     style.heading('First call, for an agent'),
     `  ${style.code('notifai send --kind done --title "All 42 tests passed" --body "Finished in 3m 10s. Next: review the release candidate."')}`,