helloagents 3.0.12 → 3.0.15-beta.1

package/cli.mjs

@@ -6,6 +6,8 @@
 'use strict'
 
 import { homedir } from 'node:os'
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -23,11 +25,14 @@ import {
   syncVersion,
 } from './scripts/cli-lifecycle.mjs'
 import { initCliDoctor, runDoctor } from './scripts/cli-doctor.mjs'
+import { runBranchSwitch } from './scripts/cli-branch.mjs'
 import { createMessageHelpers, createInstallMessagePrinter } from './scripts/cli-messages.mjs'
+import { getStableRuntimeRoot, removeRuntimeRoot, syncRuntimeRoot } from './scripts/cli-runtime-root.mjs'
 
 const HOME = homedir()
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)))
 const HELLOAGENTS_HOME = join(HOME, '.helloagents')
+const RUNTIME_ROOT = getStableRuntimeRoot(HOME)
 const CONFIG_FILE = join(HELLOAGENTS_HOME, 'helloagents.json')
 const pkg = loadPackageVersion(PKG_ROOT)
 
@@ -44,7 +49,8 @@ const { printHelp, printInstallMsg } = createInstallMessagePrinter({
 })
 initCliLifecycle({
   home: HOME,
-  pkgRoot: PKG_ROOT,
+  pkgRoot: RUNTIME_ROOT,
+  sourceRoot: PKG_ROOT,
   helloagentsHome: HELLOAGENTS_HOME,
   configFile: CONFIG_FILE,
   pkgVersion: pkg.version,
@@ -54,7 +60,8 @@ initCliLifecycle({
 })
 initCliDoctor({
   home: HOME,
-  pkgRoot: PKG_ROOT,
+  pkgRoot: RUNTIME_ROOT,
+  sourceRoot: PKG_ROOT,
   pkgVersion: pkg.version,
   msg,
   readSettings,
@@ -64,17 +71,29 @@ initCliDoctor({
   getHostLabel,
 })
 
+function ensureRuntimeRoot() {
+  syncRuntimeRoot(PKG_ROOT, RUNTIME_ROOT)
+}
+
 function printPostinstallMessage() {
   console.log(`\n  HelloAGENTS v${pkg.version}\n`)
   ensureConfig(HELLOAGENTS_HOME, CONFIG_FILE, safeJson, ensureDir)
+  ensureRuntimeRoot()
   ok('~/.helloagents/helloagents.json')
+  ok('~/.helloagents/helloagents')
 
   const settings = readSettings()
   const mode = settings.install_mode || DEFAULTS.install_mode
-  console.log(msg(
-    `  HelloAGENTS 包已安装，尚未自动部署到任何 CLI。\n  使用显式命令部署：\n    helloagents install codex --${mode}\n    helloagents install --all --${mode}\n`,
-    `  HelloAGENTS package installed. No CLI targets were configured automatically.\n  Deploy explicitly with:\n    helloagents install codex --${mode}\n    helloagents install --all --${mode}\n`,
-  ))
+  const deployMessage = shouldDeployFromEnv()
+    ? msg(
+      '  HelloAGENTS 包已安装，正在按环境变量部署。\n',
+      '  HelloAGENTS package installed; deploying from environment variables.\n',
+    )
+    : msg(
+      `  HelloAGENTS 包已安装，尚未自动部署到任何 CLI。\n  使用显式命令部署：\n    helloagents install codex --${mode}\n    helloagents install --all --${mode}\n`,
+      `  HelloAGENTS package installed. No CLI targets were configured automatically.\n  Deploy explicitly with:\n    helloagents install codex --${mode}\n    helloagents install --all --${mode}\n`,
+    )
+  console.log(deployMessage)
 }
 
 function runSafely(handler) {
@@ -86,21 +105,110 @@ function runSafely(handler) {
   }
 }
 
+function resolveRuntimeScript(scriptName) {
+  const runtimeScript = join(RUNTIME_ROOT, 'scripts', scriptName)
+  if (existsSync(runtimeScript)) return runtimeScript
+  return join(PKG_ROOT, 'scripts', scriptName)
+}
+
+function runRuntimeScript(scriptName, scriptArgs) {
+  const result = spawnSync(process.execPath, [resolveRuntimeScript(scriptName), ...scriptArgs], {
+    stdio: 'inherit',
+    windowsHide: true,
+  })
+  if (result.error) {
+    console.error(`\n  ✗ ${result.error.message}\n`)
+    process.exitCode = 1
+    return
+  }
+  process.exitCode = typeof result.status === 'number' ? result.status : 1
+}
+
+function envFlag(name) {
+  return ['1', 'true', 'yes', 'on'].includes(String(process.env[name] || '').toLowerCase())
+}
+
+function parseCompactLifecycleSpec() {
+  const raw = String(process.env.HELLOAGENTS || '').trim()
+  if (!raw) return null
+
+  const parts = raw.split(':')
+  if (parts.length > 2 || !parts[0]) {
+    throw new Error(msg('HELLOAGENTS 必须是 target[:mode]，例如 codex:global', 'HELLOAGENTS must be target[:mode], for example codex:global'))
+  }
+
+  const target = normalizeHost(parts[0].trim().toLowerCase())
+  const mode = (parts[1] || '').trim().toLowerCase()
+  if (!target) throw new Error(msg(`不支持的 HELLOAGENTS 目标：${parts[0]}`, `Unsupported HELLOAGENTS target: ${parts[0]}`))
+  if (mode && !['standby', 'global'].includes(mode)) {
+    throw new Error(msg(`不支持的 HELLOAGENTS 模式：${mode}`, `Unsupported HELLOAGENTS mode: ${mode}`))
+  }
+
+  return { target, mode }
+}
+
+function lifecycleArgsFromEnv(defaultTarget = 'all') {
+  const compact = parseCompactLifecycleSpec()
+  const target = (
+    process.env.HELLOAGENTS_TARGET
+    || process.env.HELLOAGENTS_HOST
+    || compact?.target
+    || defaultTarget
+  ).trim()
+  const mode = (process.env.HELLOAGENTS_MODE || compact?.mode || '').trim().toLowerCase()
+  const args = [target === 'all' ? '--all' : target]
+  if (mode) args.push(`--${mode}`)
+  return args
+}
+
+function shouldDeployFromEnv() {
+  return envFlag('HELLOAGENTS_DEPLOY') || Boolean(String(process.env.HELLOAGENTS || '').trim())
+}
+
 const argv = process.argv.slice(2)
 const cmd = argv[0] || ''
 
-if (cmd === 'postinstall') {
+if (cmd === 'codex-notify') {
+  runRuntimeScript('notify.mjs', ['codex-notify', ...argv.slice(1)])
+} else if (cmd === 'notify') {
+  runRuntimeScript('notify.mjs', argv.slice(1))
+} else if (cmd === 'guard') {
+  runRuntimeScript('guard.mjs', argv.slice(1))
+} else if (cmd === 'ralph-loop') {
+  runRuntimeScript('ralph-loop.mjs', argv.slice(1))
+} else if (cmd === 'postinstall') {
   printPostinstallMessage()
+  if (shouldDeployFromEnv()) {
+    runSafely(() => runScopedLifecycle('install', lifecycleArgsFromEnv()))
+  }
 } else if (cmd === 'preuninstall') {
-  runScopedLifecycle('cleanup', [])
+  runSafely(() => {
+    const cleanupArgs = argv.length > 1 ? argv.slice(1) : lifecycleArgsFromEnv('all')
+    runScopedLifecycle('cleanup', cleanupArgs)
+    if (cleanupArgs.includes('--all')) removeRuntimeRoot(RUNTIME_ROOT)
+  })
 } else if (cmd === 'sync-version') {
   syncVersion()
 } else if (cmd === 'doctor') {
   runSafely(() => runDoctor(argv.slice(1)))
 } else if (cmd === '--global' || cmd === '--standby') {
-  switchMode(cmd === '--global' ? 'global' : 'standby')
-} else if (['install', 'update', 'uninstall', 'cleanup', '--cleanup'].includes(cmd)) {
-  runSafely(() => runScopedLifecycle(cmd === '--cleanup' ? 'cleanup' : cmd, argv.slice(1)))
+  runSafely(() => {
+    ensureRuntimeRoot()
+    switchMode(cmd === '--global' ? 'global' : 'standby')
+  })
+} else if (cmd === 'branch' || cmd === 'switch-branch') {
+  runSafely(() => runBranchSwitch(argv.slice(1)))
+} else if (['install', 'update', 'uninstall', 'cleanup'].includes(cmd)) {
+  runSafely(() => {
+    const action = cmd
+    const lifecycleArgs = argv.slice(1)
+    if (cmd === 'install' || cmd === 'update') ensureRuntimeRoot()
+    runScopedLifecycle(action, lifecycleArgs)
+    const positionals = lifecycleArgs.filter((arg) => !arg.startsWith('--'))
+    if (action === 'uninstall' && (lifecycleArgs.includes('--all') || positionals.length === 0)) {
+      removeRuntimeRoot(RUNTIME_ROOT)
+    }
+  })
 } else {
   printHelp()
 }

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.12",
+  "version": "3.0.15-beta.1",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/install.ps1

@@ -0,0 +1,125 @@
+# HelloAGENTS one-shot installer.
+#
+# Environment:
+#   HELLOAGENTS=all|claude|gemini|codex[:standby|global]
+#   HELLOAGENTS_ACTION=install|update|uninstall|switch-branch|branch
+#   HELLOAGENTS_TARGET=all|claude|gemini|codex
+#   HELLOAGENTS_MODE=standby|global
+#   HELLOAGENTS_BRANCH=main|beta|...
+#   HELLOAGENTS_PACKAGE=helloagents|github:owner/repo#ref|...
+
+$ErrorActionPreference = "Stop"
+
+$Action = if ($env:HELLOAGENTS_ACTION) { $env:HELLOAGENTS_ACTION } else { "install" }
+$Target = if ($env:HELLOAGENTS_TARGET) { $env:HELLOAGENTS_TARGET } else { "" }
+$Mode = if ($env:HELLOAGENTS_MODE) { $env:HELLOAGENTS_MODE } else { "" }
+$Branch = if ($env:HELLOAGENTS_BRANCH) { $env:HELLOAGENTS_BRANCH } else { "" }
+$Package = if ($env:HELLOAGENTS_PACKAGE) { $env:HELLOAGENTS_PACKAGE } else { "" }
+
+if ($env:HELLOAGENTS) {
+    $Parts = $env:HELLOAGENTS.Split(":", 2)
+    if (-not $Parts[0]) {
+        throw "HELLOAGENTS must be target[:mode], for example codex:global"
+    }
+    if (-not $Target) { $Target = $Parts[0] }
+    if (-not $Mode -and $Parts.Count -gt 1) { $Mode = $Parts[1] }
+}
+
+if (-not $Target) { $Target = "all" }
+if (-not $Mode) { $Mode = "standby" }
+$Target = $Target.ToLowerInvariant()
+$Mode = $Mode.ToLowerInvariant()
+
+if (@("all", "claude", "gemini", "codex") -notcontains $Target) {
+    throw "Unsupported HELLOAGENTS target: $Target"
+}
+
+if (@("standby", "global") -notcontains $Mode) {
+    throw "Unsupported HELLOAGENTS mode: $Mode"
+}
+
+if (-not $Package) {
+    if ($Branch) {
+        $Package = "github:hellowind777/helloagents#$Branch"
+    } else {
+        $Package = "helloagents"
+    }
+}
+
+function Invoke-Npm {
+    param([string[]]$Args)
+    & npm @Args
+    if ($LASTEXITCODE -ne 0) {
+        throw "npm $($Args -join ' ') failed with exit code $LASTEXITCODE"
+    }
+}
+
+function Enable-PostinstallDeploy {
+    $env:HELLOAGENTS_DEPLOY = "1"
+    $env:HELLOAGENTS_TARGET = $Target
+    $env:HELLOAGENTS_MODE = $Mode
+}
+
+function Invoke-HostScript {
+    param([string]$ScriptName)
+    if ($Target -eq "all") {
+        Invoke-Npm @("explore", "-g", "helloagents", "--", "npm", "run", $ScriptName, "--", "--all", "--$Mode")
+    } else {
+        Invoke-Npm @("explore", "-g", "helloagents", "--", "npm", "run", $ScriptName, "--", $Target, "--$Mode")
+    }
+}
+
+function Sync-Hosts {
+    Invoke-HostScript "sync-hosts"
+}
+
+function Cleanup-Hosts {
+    Invoke-HostScript "cleanup-hosts"
+}
+
+function Uninstall-Hosts {
+    Invoke-HostScript "uninstall"
+}
+
+switch ($Action) {
+    "install" {
+        Enable-PostinstallDeploy
+        Invoke-Npm @("install", "-g", $Package)
+    }
+    "update" {
+        if ($Branch -or $env:HELLOAGENTS_PACKAGE) {
+            Invoke-Npm @("install", "-g", $Package)
+        } else {
+            & npm update -g helloagents
+            if ($LASTEXITCODE -ne 0) {
+                Invoke-Npm @("install", "-g", "helloagents")
+            }
+        }
+        Sync-Hosts
+    }
+    "switch-branch" {
+        if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
+            throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch"
+        }
+        Invoke-Npm @("install", "-g", $Package)
+        Sync-Hosts
+    }
+    "branch" {
+        if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
+            throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for branch"
+        }
+        Invoke-Npm @("install", "-g", $Package)
+        Sync-Hosts
+    }
+    "uninstall" {
+        try {
+            Uninstall-Hosts
+        } catch {
+            Write-Warning "Failed to cleanup HelloAGENTS host integrations before uninstall: $_"
+        }
+        Invoke-Npm @("uninstall", "-g", "helloagents")
+    }
+    default {
+        throw "Unsupported HELLOAGENTS_ACTION: $Action"
+    }
+}

package/install.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env sh
+set -eu
+
+# HelloAGENTS one-shot installer.
+#
+# Environment:
+#   HELLOAGENTS=all|claude|gemini|codex[:standby|global]
+#   HELLOAGENTS_ACTION=install|update|uninstall|switch-branch|branch
+#   HELLOAGENTS_TARGET=all|claude|gemini|codex
+#   HELLOAGENTS_MODE=standby|global
+#   HELLOAGENTS_BRANCH=main|beta|...
+#   HELLOAGENTS_PACKAGE=helloagents|github:owner/repo#ref|...
+
+ACTION="${HELLOAGENTS_ACTION:-install}"
+TARGET="${HELLOAGENTS_TARGET:-}"
+MODE="${HELLOAGENTS_MODE:-}"
+BRANCH="${HELLOAGENTS_BRANCH:-}"
+PACKAGE="${HELLOAGENTS_PACKAGE:-}"
+
+if [ -n "${HELLOAGENTS:-}" ]; then
+  SPEC_TARGET="${HELLOAGENTS%%:*}"
+  SPEC_MODE=""
+  if [ -z "$SPEC_TARGET" ]; then
+    echo "HELLOAGENTS must be target[:mode], for example codex:global" >&2
+    exit 1
+  fi
+  if [ "$SPEC_TARGET" != "$HELLOAGENTS" ]; then
+    SPEC_MODE="${HELLOAGENTS#*:}"
+  fi
+  TARGET="${TARGET:-$SPEC_TARGET}"
+  MODE="${MODE:-$SPEC_MODE}"
+fi
+
+TARGET="${TARGET:-all}"
+MODE="${MODE:-standby}"
+TARGET="$(printf '%s' "$TARGET" | tr '[:upper:]' '[:lower:]')"
+MODE="$(printf '%s' "$MODE" | tr '[:upper:]' '[:lower:]')"
+
+case "$TARGET" in
+  all|claude|gemini|codex) ;;
+  *) echo "Unsupported HELLOAGENTS target: $TARGET" >&2; exit 1 ;;
+esac
+
+case "$MODE" in
+  standby|global) ;;
+  *) echo "Unsupported HELLOAGENTS mode: $MODE" >&2; exit 1 ;;
+esac
+
+if [ -z "$PACKAGE" ]; then
+  if [ -n "$BRANCH" ]; then
+    PACKAGE="github:hellowind777/helloagents#$BRANCH"
+  else
+    PACKAGE="helloagents"
+  fi
+fi
+
+sync_hosts() {
+  if [ "$TARGET" = "all" ]; then
+    npm explore -g helloagents -- npm run sync-hosts -- --all "--$MODE"
+  else
+    npm explore -g helloagents -- npm run sync-hosts -- "$TARGET" "--$MODE"
+  fi
+}
+
+cleanup_hosts() {
+  if [ "$TARGET" = "all" ]; then
+    npm explore -g helloagents -- npm run cleanup-hosts -- --all "--$MODE"
+  else
+    npm explore -g helloagents -- npm run cleanup-hosts -- "$TARGET" "--$MODE"
+  fi
+}
+
+uninstall_hosts() {
+  if [ "$TARGET" = "all" ]; then
+    npm explore -g helloagents -- npm run uninstall -- --all "--$MODE"
+  else
+    npm explore -g helloagents -- npm run uninstall -- "$TARGET" "--$MODE"
+  fi
+}
+
+enable_postinstall_deploy() {
+  export HELLOAGENTS_DEPLOY=1
+  export HELLOAGENTS_TARGET="$TARGET"
+  export HELLOAGENTS_MODE="$MODE"
+}
+
+case "$ACTION" in
+  install)
+    enable_postinstall_deploy
+    npm install -g "$PACKAGE"
+    ;;
+  update)
+    if [ -n "$BRANCH" ] || [ -n "${HELLOAGENTS_PACKAGE:-}" ]; then
+      npm install -g "$PACKAGE"
+    else
+      npm update -g helloagents || npm install -g helloagents
+    fi
+    sync_hosts
+    ;;
+  switch-branch|branch)
+    if [ -z "$BRANCH" ] && [ -z "${HELLOAGENTS_PACKAGE:-}" ]; then
+      echo "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch" >&2
+      exit 1
+    fi
+    npm install -g "$PACKAGE"
+    sync_hosts
+    ;;
+  uninstall)
+    if ! uninstall_hosts; then
+      echo "Warning: failed to cleanup HelloAGENTS host integrations before uninstall" >&2
+    fi
+    npm uninstall -g helloagents
+    ;;
+  *)
+    echo "Unsupported HELLOAGENTS_ACTION: $ACTION" >&2
+    exit 1
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.12",
+  "version": "3.0.15-beta.1",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",
@@ -12,7 +12,8 @@
   },
   "bin": {
     "helloagents": "cli.mjs",
-    "helloagents-js": "cli.mjs"
+    "helloagents-js": "cli.mjs",
+    "helloagents-turn-state": "scripts/turn-state-cli.mjs"
   },
   "scripts": {
     "test": "node --test",
@@ -20,7 +21,13 @@
     "preuninstall": "node cli.mjs preuninstall",
     "uninstall": "node cli.mjs preuninstall",
     "postuninstall": "node cli.mjs preuninstall",
-    "prepublishOnly": "node cli.mjs sync-version"
+    "prepublishOnly": "node cli.mjs sync-version",
+    "deploy": "node cli.mjs install",
+    "deploy:standby": "node cli.mjs install --all --standby",
+    "deploy:global": "node cli.mjs install --all --global",
+    "sync-hosts": "node cli.mjs update",
+    "cleanup-hosts": "node cli.mjs cleanup",
+    "switch-branch": "node cli.mjs switch-branch"
   },
   "files": [
     "cli.mjs",
@@ -32,11 +39,23 @@
     "bootstrap.md",
     "bootstrap-lite.md",
     "README_CN.md",
+    "install.sh",
+    "install.ps1",
     "gemini-extension.json",
     ".claude-plugin/",
     ".codex-plugin/"
   ],
-  "keywords": ["ai", "agent", "claude", "codex", "cli", "orchestration", "subagent", "hooks", "skills"],
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "codex",
+    "cli",
+    "orchestration",
+    "subagent",
+    "hooks",
+    "skills"
+  ],
   "engines": {
     "node": ">=18"
   }