@raidiant/notifai 9.3.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/orca-session-title.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { readOrcaSessionTitle, type OrcaCommand } from './orca-session-title.js'
+
+const worktreeId = 'repo-123::/worktrees/agent-session-labels'
+
+function response(overrides: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    ok: true,
+    result: {
+      worktree: {
+        id: worktreeId,
+        path: '/worktrees/agent-session-labels',
+        displayName: 'Agent Session context labels',
+        ...overrides,
+      },
+    },
+  })
+}
+
+describe('Orca Agent Session title context', () => {
+  it('accepts only the User-facing title returned for the exact managed worktree', () => {
+    const calls: { executable: string; args: readonly string[] }[] = []
+    const command: OrcaCommand = (executable, args) => {
+      calls.push({ executable, args })
+      return response()
+    }
+
+    expect(
+      readOrcaSessionTitle({ TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: worktreeId }, command),
+    ).toBe('Agent Session context labels')
+    expect(calls).toEqual([
+      {
+        executable: 'orca',
+        args: ['worktree', 'show', '--worktree', `id:${worktreeId}`, '--json'],
+      },
+    ])
+  })
+
+  it.each([
+    ['command failure', () => null],
+    ['malformed JSON', () => '{not json}'],
+    ['failed response', () => JSON.stringify({ ok: false })],
+    ['different worktree id', () => response({ id: 'repo-123::/worktrees/other' })],
+    ['different worktree path', () => response({ path: '/private/untrusted' })],
+    ['blank display name', () => response({ displayName: '   ' })],
+  ])('leaves the generated fallback exceptional when context is unavailable: %s', (_name, command) => {
+    expect(
+      readOrcaSessionTitle(
+        { TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: worktreeId },
+        command,
+      ),
+    ).toBeUndefined()
+  })
+})

package/src/orca-session-title.ts

@@ -0,0 +1,103 @@
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+
+export type OrcaSessionTitleLookup = (env: NodeJS.ProcessEnv) => string | undefined
+export type OrcaCommand = (executable: string, args: readonly string[]) => string | null
+
+const runOrcaCommand: OrcaCommand = (executable, args) => {
+  try {
+    return execFileSync(executable, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2_000,
+      maxBuffer: 512 * 1024,
+      windowsHide: true,
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+function containsControlCharacter(value: string): boolean {
+  return Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0
+    return codePoint < 32 || codePoint === 127
+  })
+}
+
+function worktreePathFromId(value: string): string | null {
+  if (value.length === 0 || value.length > 4_096 || containsControlCharacter(value)) return null
+  const separator = value.indexOf('::')
+  if (separator <= 0) return null
+  const repoId = value.slice(0, separator)
+  const worktreePath = value.slice(separator + 2)
+  if (!/^[A-Za-z0-9._-]+$/u.test(repoId) || worktreePath.length === 0) return null
+  return path.posix.isAbsolute(worktreePath) || path.win32.isAbsolute(worktreePath)
+    ? worktreePath
+    : null
+}
+
+function orcaExecutable(env: NodeJS.ProcessEnv): string | null {
+  const configured = env['ORCA_CLI_COMMAND']?.trim()
+  if (configured !== undefined && configured.length > 0) {
+    return containsControlCharacter(configured) ? null : configured
+  }
+  return env['ORCA_DEV_REPO_ROOT'] === undefined ? 'orca' : 'orca-dev'
+}
+
+/**
+ * Read the User-facing task name assigned to this exact Orca worktree.
+ *
+ * The environment contributes only an opaque selector. Orca must return that
+ * exact id and its matching path before its display name becomes trusted; no
+ * path component or identifier is ever promoted into an Agent Session label.
+ */
+export function readOrcaSessionTitle(
+  env: NodeJS.ProcessEnv,
+  command: OrcaCommand = runOrcaCommand,
+): string | undefined {
+  if (env['TERM_PROGRAM'] !== 'Orca') return undefined
+  const worktreeId = env['ORCA_WORKTREE_ID']
+  if (worktreeId === undefined) return undefined
+  const expectedPath = worktreePathFromId(worktreeId)
+  if (expectedPath === null) return undefined
+  const executable = orcaExecutable(env)
+  if (executable === null) return undefined
+
+  let output: string | null
+  try {
+    output = command(executable, [
+      'worktree',
+      'show',
+      '--worktree',
+      `id:${worktreeId}`,
+      '--json',
+    ])
+  } catch {
+    return undefined
+  }
+  if (output === null || output === '') return undefined
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(output)
+  } catch {
+    return undefined
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined
+  const response = parsed as {
+    ok?: unknown
+    result?: { worktree?: { id?: unknown; path?: unknown; displayName?: unknown } }
+  }
+  const worktree = response.result?.worktree
+  if (
+    response.ok !== true ||
+    worktree?.id !== worktreeId ||
+    worktree.path !== expectedPath ||
+    typeof worktree.displayName !== 'string' ||
+    worktree.displayName.trim().length === 0
+  ) {
+    return undefined
+  }
+  return worktree.displayName
+}

package/src/program.test.ts

@@ -116,6 +116,33 @@ describe('program argv parsing', () => {
     expect(enabled).toBe(1)
   })
 
+  it('dispatches the current Agent Session rename without exposing an id override', async () => {
+    let label: string | undefined
+    const result = await parse(['session', 'rename', 'Hermes Support'], {
+      agentSessionRename: (async (_deps, value) => ((label = value), 0)) as ProgramRunners['agentSessionRename'],
+    })
+    expect(result.exitCode).toBe(0)
+    expect(label).toBe('Hermes Support')
+  })
+
+  it('dispatches sounds --json onto soundsCommand', async () => {
+    let seen: Record<string, unknown> | undefined
+    const result = await parse(['sounds', '--json'], {
+      sounds: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['sounds'],
+    })
+    expect(result.exitCode).toBe(0)
+    expect(seen).toMatchObject({ json: true })
+  })
+
+  it('passes a custom sound name through --sound', async () => {
+    let seen: Record<string, unknown> | undefined
+    await parse(
+      ['send', '--kind', 'done', '--title', 'T', '--body', 'B', '--sound', 'Kitchen timer'],
+      { send: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['send'] },
+    )
+    expect(seen).toMatchObject({ sound: 'Kitchen timer' })
+  })
+
   it('drops empty collector defaults so "not passed" stays absent', async () => {
     let seen: Record<string, unknown> | undefined
     await parse(