diff options
16 files changed, 413 insertions, 105 deletions
diff --git a/docs/next/website/src/content/docs/add-herdr-support.mdx b/docs/next/website/src/content/docs/add-herdr-support.mdx new file mode 100644 index 00000000..0ed689a3 --- /dev/null +++ b/docs/next/website/src/content/docs/add-herdr-support.mdx @@ -0,0 +1,117 @@ +--- +title: Add Herdr support to your agent +description: Report your coding agent's state and resume command to Herdr from your own code, without adding native support to Herdr. +--- + +If you build a coding agent, you can make it a first-class citizen in Herdr from your own code. You don't need a pull request to Herdr, and you don't need to wait for a Herdr release. + +Once your agent reports to Herdr, users get: + +- your agent's name and `idle`, `working`, or `blocked` state in the sidebar and in `herdr agent list` +- notifications when it finishes or needs a decision +- `herdr agent wait` and other automation that waits on agent state +- the same session back in the same pane after a Herdr server restart + +Herdr owns the integrations for agents whose vendors don't ship one. If you maintain your agent, owning the integration yourself means you can fix it on your own release schedule. + +## How it works + +Every process in a Herdr pane inherits these environment variables: + +| Variable | Meaning | +| --- | --- | +| `HERDR_ENV` | `1` inside Herdr | +| `HERDR_PANE_ID` | The pane your agent runs in | +| `HERDR_BIN_PATH` | The Herdr binary that owns this pane | +| `HERDR_SOCKET_PATH` | Herdr's API socket | + +Your agent makes three kinds of reports through `"$HERDR_BIN_PATH"`: + +1. **State.** Report `idle`, `working`, or `blocked` whenever it changes. +2. **Resume command.** Report the command that reopens the current session. +3. **Release.** Release the pane when your agent exits. + +Only report when `HERDR_ENV=1` and the other variables are set. Outside Herdr, your integration should do nothing. + +## Report state + +```bash +"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --state working \ + --seq 1 +``` + +- Report `working` when a turn starts, `idle` when your agent is ready for input, and `blocked` when it needs the user to decide something. Add `--message` to explain a block. +- `--agent` is the name users see. Use your own agent's name, not the name of an agent Herdr already supports. +- `--source` identifies your integration. Keep it stable and unique. Don't start it with `herdr:`, because Herdr's own integrations use that prefix. +- `--seq` is optional but recommended. It must increase with every report from your source, including across sessions and restarts of your agent. A timestamp works well. Herdr ignores reports whose number is not higher than the last one it accepted, so late or out-of-order reports can't overwrite newer state. + +## Report the resume command + +Put the command that resumes the current session after `--`. Include the options that session needs, such as the model or permission mode, so the resumed session behaves the same: + +```bash +"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --state idle \ + --seq 2 \ + --agent-session-id "$SESSION_ID" \ + -- my-agent --resume "$SESSION_ID" --model my-model +``` + +You can attach the command to any state report, or send it with `pane report-agent-session` when only the session changes. Report it again whenever your agent switches sessions. + +After a Herdr server restart, Herdr opens the pane in the same directory and runs that command there. The command must follow these rules: + +- The first word is a plain command name on the user's `PATH`, such as `my-agent`, not a path. +- No argument contains an apostrophe. +- Your source must hold the pane first, so send a state report with `report-agent` before or along with the command. Otherwise Herdr answers with `resume_not_accepted`. + +Herdr rejects a command that breaks the first two rules with `invalid_resume_argv` and does not apply that report. Users can turn off resume with `[session] resume_agents_on_restore = false`. + +## Release on exit + +```bash +"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --seq 3 +``` + +Releasing clears your agent's name, state, and resume command from the pane right away. Only release when the user actually quits. If your agent replaces one session with another in the same process, report the new session instead of releasing. + +If your agent exits without releasing, Herdr notices once the pane is back at its idle shell prompt and clears the agent and its resume command. This usually takes a second or two. It is a safety net, not a replacement for releasing. + +## Keep it out of the way + +- Don't let Herdr slow your agent down. Send reports in the background or with a short timeout, and ignore failures. +- Send only the latest state. If several changes queue up while a report is in flight, drop the older ones. +- Older Herdr versions ignore the resume command, so everything else keeps working there. + +## Use the socket directly + +`HERDR_BIN_PATH` and the CLI are the portable choice, including on Windows. If your agent needs direct IPC, send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting). The resume command goes in the `resume_argv` array. + +## Check your integration + +Start your agent in a Herdr pane, then check what Herdr sees: + +```bash +herdr pane get "$HERDR_PANE_ID" +herdr agent list +``` + +To test restore without touching your normal session, use a separate named session: + +1. Start `herdr --session my-agent-test`, then run your agent in a pane. +2. Stop that session with `herdr session stop my-agent-test`. +3. Start `herdr --session my-agent-test` again. The pane should run your resume command and your agent should report again. + +## Example + +[Prime Agent's built-in Herdr reporter](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts) is a real-world integration. It activates only inside Herdr, maps agent events to `working`, `idle`, and `blocked`, keeps its report order across sessions, and releases the pane on exit. + +To change how your agent appears without changing its state, such as a title or custom status text, see [Custom status labels](/docs/integrations/#custom-status-labels). diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx index 78274850..5c4351a5 100644 --- a/docs/next/website/src/content/docs/agents.mdx +++ b/docs/next/website/src/content/docs/agents.mdx @@ -116,7 +116,7 @@ herdr integration install claude herdr integration status ``` -Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list. If you are building an agent, the [custom integration guide](/docs/integrations/#integrate-your-own-agent) shows how to report lifecycle state without adding native support to Herdr. +Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list. If you are building an agent, [Add Herdr support to your agent](/docs/add-herdr-support/) shows how to report lifecycle state and a resume command without adding native support to Herdr. ## Custom agent labels diff --git a/docs/next/website/src/content/docs/integrations.mdx b/docs/next/website/src/content/docs/integrations.mdx index e36dfdf2..3aff5ae1 100644 --- a/docs/next/website/src/content/docs/integrations.mdx +++ b/docs/next/website/src/content/docs/integrations.mdx @@ -66,51 +66,14 @@ Herdr uses integrations in two ways: Custom integrations can also report state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable. -## Integrate your own agent - -An agent running in a Herdr pane inherits `HERDR_ENV`, `HERDR_PANE_ID`, `HERDR_BIN_PATH`, and `HERDR_SOCKET_PATH`. If the agent exposes lifecycle hooks, use those hooks to report semantic state through Herdr's CLI: - -```bash -"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent \ - --state working -``` - -Report `idle` when the agent is ready for input and `blocked` when it needs a user decision. Use `--message` to describe a block. When the agent exits, release the same source's lifecycle authority: - -```bash -"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent -``` - -Report only when `HERDR_ENV=1` and the required variables are present. This keeps the integration a no-op outside Herdr. Keep `--source` stable and unique to the integration. If reports can arrive out of order, include a strictly increasing `--seq`; Herdr ignores stale sequence numbers from the same source. - -You can include `--agent-session-id` or `--agent-session-path` with `report-agent`, or use `pane report-agent-session` when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. - -To have Herdr resume your agent after a Herdr server restart, report the command that resumes the current session after `--`. Include any options the session needs, such as the model or permission mode: - -```bash -"$HERDR_BIN_PATH" pane report-agent-session "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent \ - --agent-session-id "$SESSION_ID" \ - -- my-agent --resume "$SESSION_ID" --model my-model -``` - -Herdr runs that command in the restored pane's directory. The first word must be a plain command name on `PATH`, not a path, and no argument may contain an apostrophe. Report the agent's state with `report-agent` first so your source holds the pane, and report the command again whenever the session changes. Herdr keeps it only while your source holds the pane and drops it on release. `[session] resume_agents_on_restore = false` disables it. - -Herdr cannot identify a custom agent's process, so it treats the pane returning to its idle shell prompt as the agent exiting and clears the agent and its resume command. Still release authority on exit so the pane updates immediately. - -Use `HERDR_BIN_PATH` and the CLI wrappers for portable integrations. Code that needs direct IPC can send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting). - -[Prime Agent's built-in Herdr reporter](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts) is a real-world example. It activates only inside Herdr, maps agent events to `working`, `idle`, and `blocked`, preserves report ordering across sessions, and releases authority on exit. - Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, MastraCode, and Antigravity CLI panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it. Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Qwen Code version `1`, Letta Code version `1`, Cursor Agent CLI version `1`, Grok CLI version `2`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `5`, MastraCode version `1`, or Antigravity CLI version `1`. Check installed versions with `herdr integration status`. +## Integrate your own agent + +If you build a coding agent, you can report its state and resume command to Herdr from your own code, without adding native support to Herdr. See [Add Herdr support to your agent](/docs/add-herdr-support/). + ## Pi Install the Pi integration: diff --git a/docs/next/website/src/content/docs/ja/add-herdr-support.mdx b/docs/next/website/src/content/docs/ja/add-herdr-support.mdx new file mode 100644 index 00000000..d095bc2d --- /dev/null +++ b/docs/next/website/src/content/docs/ja/add-herdr-support.mdx @@ -0,0 +1,117 @@ +--- +title: エージェントに Herdr 対応を追加する +description: Herdr にネイティブサポートを追加せずに、自分のコードからコーディングエージェントの状態と resume コマンドを Herdr に報告します。 +--- + +コーディングエージェントを開発しているなら、自分のコードだけでそのエージェントを Herdr の第一級の存在にできます。Herdr へのプルリクエストも、Herdr のリリースを待つ必要もありません。 + +エージェントが Herdr に報告すると、ユーザーは次のものを得られます: + +- サイドバーと `herdr agent list` に表示されるエージェント名と `idle`、`working`、`blocked` の状態 +- 完了したときや判断が必要になったときの通知 +- `herdr agent wait` など、エージェントの状態を待つ自動化 +- Herdr サーバーの再起動後、同じペインで同じセッションが戻ること + +ベンダーがインテグレーションを提供していないエージェントについては、Herdr がインテグレーションを管理します。エージェントのメンテナーが自分でインテグレーションを持てば、自分のリリーススケジュールで修正できます。 + +## 仕組み + +Herdr ペイン内のすべてのプロセスは、次の環境変数を継承します: + +| 変数 | 意味 | +| --- | --- | +| `HERDR_ENV` | Herdr 内では `1` | +| `HERDR_PANE_ID` | エージェントが動いているペイン | +| `HERDR_BIN_PATH` | このペインを管理する Herdr バイナリ | +| `HERDR_SOCKET_PATH` | Herdr の API ソケット | + +エージェントは `"$HERDR_BIN_PATH"` を通じて 3 種類の報告をします: + +1. **状態。** `idle`、`working`、`blocked` が変わるたびに報告します。 +2. **resume コマンド。** 現在のセッションを開き直すコマンドを報告します。 +3. **解放。** エージェントの終了時にペインを解放します。 + +`HERDR_ENV=1` で他の変数も設定されているときだけ報告してください。Herdr の外では、インテグレーションは何もしないようにします。 + +## 状態を報告する + +```bash +"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --state working \ + --seq 1 +``` + +- ターンの開始時に `working`、入力を受け付けられるときに `idle`、ユーザーの判断が必要なときに `blocked` を報告します。ブロックの理由は `--message` で説明できます。 +- `--agent` はユーザーに表示される名前です。Herdr がすでに対応しているエージェントの名前ではなく、自分のエージェントの名前を使ってください。 +- `--source` はインテグレーションを識別します。固定かつ一意にしてください。`herdr:` で始めないでください。この接頭辞は Herdr 自身のインテグレーションが使います。 +- `--seq` は省略できますが、付けることを推奨します。source からの報告ごとに増加する必要があり、エージェントのセッションや再起動をまたいでも増加し続ける必要があります。タイムスタンプが適しています。Herdr は最後に受け付けた番号より大きくない報告を無視するので、遅れて届いた報告や順不同の報告が新しい状態を上書きすることはありません。 + +## resume コマンドを報告する + +現在のセッションを再開するコマンドを `--` の後に置きます。モデルや権限モードなど、そのセッションに必要なオプションも含めると、再開したセッションが同じように動きます: + +```bash +"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --state idle \ + --seq 2 \ + --agent-session-id "$SESSION_ID" \ + -- my-agent --resume "$SESSION_ID" --model my-model +``` + +コマンドはどの状態報告に付けてもかまいません。セッションだけが変わったときは `pane report-agent-session` で送れます。エージェントがセッションを切り替えるたびに、もう一度報告してください。 + +Herdr サーバーの再起動後、Herdr は同じディレクトリでペインを開き、そこでそのコマンドを実行します。コマンドは次のルールに従う必要があります: + +- 最初の語は、`my-agent` のようにユーザーの `PATH` 上にある単純なコマンド名にします。パスは使えません。 +- どの引数にもアポストロフィを含めません。 +- 先に source がペインを保持している必要があります。コマンドより前か同時に、`report-agent` で状態を報告してください。そうしないと Herdr は `resume_not_accepted` を返します。 + +最初の 2 つのルールに違反するコマンドは、Herdr が `invalid_resume_argv` で拒否し、その報告は適用されません。ユーザーは `[session] resume_agents_on_restore = false` で resume を無効にできます。 + +## 終了時に解放する + +```bash +"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --seq 3 +``` + +解放すると、エージェントの名前、状態、resume コマンドがすぐにペインから消えます。解放するのはユーザーが実際に終了したときだけにしてください。同じプロセス内でセッションを別のセッションに置き換える場合は、解放せずに新しいセッションを報告します。 + +エージェントが解放せずに終了した場合、Herdr はペインがアイドルなシェルプロンプトに戻ったことに気づき、エージェントと resume コマンドを消去します。通常は 1〜2 秒かかります。これは安全網であり、解放の代わりにはなりません。 + +## エージェントの邪魔をしない + +- Herdr のせいでエージェントを遅くしないでください。報告はバックグラウンドか短いタイムアウトで送り、失敗は無視します。 +- 最新の状態だけを送ります。報告の送信中に複数の変化がたまったら、古いものは捨てます。 +- 古い Herdr は resume コマンドを無視するので、それ以外の機能はそのまま動きます。 + +## ソケットを直接使う + +`HERDR_BIN_PATH` と CLI は Windows を含めて移植性のある選択肢です。エージェントに直接の IPC が必要な場合は、[Socket API](/ja/docs/socket-api/) に記載された同等の `pane.report_agent`、`pane.report_agent_session`、`pane.release_agent` リクエストを送信します。resume コマンドは `resume_argv` 配列に入れます。 + +## インテグレーションを確認する + +Herdr のペインでエージェントを起動し、Herdr から見える内容を確認します: + +```bash +herdr pane get "$HERDR_PANE_ID" +herdr agent list +``` + +普段のセッションに影響を与えずに復元をテストするには、別の名前付きセッションを使います: + +1. `herdr --session my-agent-test` を起動し、ペインでエージェントを実行します。 +2. `herdr session stop my-agent-test` でそのセッションを停止します。 +3. `herdr --session my-agent-test` をもう一度起動します。ペインで resume コマンドが実行され、エージェントが再び報告するはずです。 + +## 例 + +[Prime Agent の組み込み Herdr レポーター](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)は実際のインテグレーションです。Herdr 内でのみ有効になり、エージェントイベントを `working`、`idle`、`blocked` に対応付け、セッションをまたいで報告順序を維持し、終了時にペインを解放します。 + +タイトルやカスタムのステータス文言など、状態を変えずにエージェントの見た目を変えるには、[カスタムステータスラベル](/ja/docs/integrations/#カスタムステータスラベル)を参照してください。 diff --git a/docs/next/website/src/content/docs/ja/agents.mdx b/docs/next/website/src/content/docs/ja/agents.mdx index 528ab0e4..cb71a678 100644 --- a/docs/next/website/src/content/docs/ja/agents.mdx +++ b/docs/next/website/src/content/docs/ja/agents.mdx @@ -114,7 +114,7 @@ herdr integration install claude herdr integration status ``` -対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧は[インテグレーション](/ja/docs/integrations/)を参照してください。エージェントを開発している場合は、[カスタムインテグレーションガイド](/ja/docs/integrations/#独自エージェントを統合する)で、Herdr にネイティブサポートを追加せずにライフサイクル状態を報告する方法を確認できます。 +対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧は[インテグレーション](/ja/docs/integrations/)を参照してください。エージェントを開発している場合は、[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)で、Herdr にネイティブサポートを追加せずにライフサイクル状態と resume コマンドを報告する方法を確認できます。 ## カスタムエージェントラベル diff --git a/docs/next/website/src/content/docs/ja/cli-reference.mdx b/docs/next/website/src/content/docs/ja/cli-reference.mdx index b622c245..2904b069 100644 --- a/docs/next/website/src/content/docs/ja/cli-reference.mdx +++ b/docs/next/website/src/content/docs/ja/cli-reference.mdx @@ -258,7 +258,8 @@ herdr pane report-agent <pane_id> \ [--message TEXT] \ [--seq N] \ [--agent-session-id ID] \ - [--agent-session-path PATH] + [--agent-session-path PATH] \ + [-- RESUME_COMMAND...] herdr pane report-agent-session <pane_id> \ --source ID \ @@ -266,7 +267,8 @@ herdr pane report-agent-session <pane_id> \ [--seq N] \ [--agent-session-id ID] \ [--agent-session-path PATH] \ - [--session-start-source SOURCE] + [--session-start-source SOURCE] \ + [-- RESUME_COMMAND...] herdr pane release-agent <pane_id> \ --source ID \ @@ -276,6 +278,8 @@ herdr pane release-agent <pane_id> \ `report-agent-session` はライフサイクル状態を報告せずにネイティブセッション識別子を更新します。`release-agent` は、そのエージェントプロセスが終了したときに、そのソースのライフサイクル権限を終了します。 +`--` の後の引数は、サーバー再起動後にこのセッションを再開するために Herdr が実行するコマンドです。最初の引数は `PATH` 上の単純なコマンド名でなければならず、どの引数にもアポストロフィを含めることはできません。 + 公式インテグレーションがネイティブセッション参照を報告している場合、`pane get`、`pane list`、`agent get`、`agent list` は読み取り専用の `agent_session` オブジェクトを含みます。ネイティブセッション参照が保存されていない場合、このフィールドは省略されます。 これらのコマンドは、ペインを制御しているフォアグラウンドプロセスの cwd を解決できる場合に `foreground_cwd` を含みます。既存の `cwd` フィールドは、ラベルと follow-cwd 挙動に使われるペイン/ワークスペースの cwd のままです。 diff --git a/docs/next/website/src/content/docs/ja/integrations.mdx b/docs/next/website/src/content/docs/ja/integrations.mdx index d54eaa88..126ba824 100644 --- a/docs/next/website/src/content/docs/ja/integrations.mdx +++ b/docs/next/website/src/content/docs/ja/integrations.mdx @@ -68,37 +68,14 @@ Herdr はインテグレーションを 2 つの異なる方法で使います: カスタムインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。Herdr への組み込みや、認識済みのエージェント実行ファイルは必要ありません。 -## 独自エージェントを統合する - -Herdr ペイン内で動くエージェントは、`HERDR_ENV`、`HERDR_PANE_ID`、`HERDR_BIN_PATH`、`HERDR_SOCKET_PATH` を継承します。エージェントがライフサイクルフックを提供している場合は、そのフックから Herdr の CLI を使ってセマンティックな状態を報告します: - -```bash -"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent \ - --state working -``` - -エージェントが入力待ちになったら `idle`、ユーザーの判断が必要になったら `blocked` を報告します。ブロックの説明には `--message` を使います。エージェントの終了時には、同じ source のライフサイクル権威を解放します: - -```bash -"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent -``` - -Herdr の外では何もしないように、`HERDR_ENV=1` で必要な変数が存在するときだけ報告してください。`--source` はインテグレーションごとに一意かつ固定にします。報告が順不同で届く可能性がある場合は、単調増加する `--seq` を含めてください。Herdr は同じ source から届いた古いシーケンス番号を無視します。 - -`report-agent` に `--agent-session-id` または `--agent-session-path` を含めることも、セッション識別が状態とは独立して変わる場合に `pane report-agent-session` を使うこともできます。Herdr はその参照をペイン API とエージェント API で公開します。セッションの自動復元には、それに加えて、そのエージェントの起動方法と参照先セッションの再開方法を Herdr が把握している必要があります。 - -移植可能なインテグレーションには `HERDR_BIN_PATH` と CLI ラッパーを使ってください。直接 IPC が必要なコードでは、[Socket API](/ja/docs/socket-api/) に記載された同等の `pane.report_agent`、`pane.report_agent_session`、`pane.release_agent` リクエストを送信できます。 - -[Prime Agent の組み込み Herdr レポーター](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)は実際の実装例です。Herdr 内でのみ有効になり、エージェントイベントを `working`、`idle`、`blocked` に対応付け、セッションをまたいで報告順序を維持し、終了時に権威を解放します。 - 一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode、Antigravity CLI のペインを resume します。 エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Qwen Code は `1`、Letta Code は `1`、Cursor Agent CLI は `1`、Grok CLI は `2`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `5`、MastraCode は `1`、Antigravity CLI は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。 +## 独自エージェントを統合する + +コーディングエージェントを開発している場合は、Herdr にネイティブサポートを追加せずに、自分のコードからエージェントの状態と resume コマンドを Herdr に報告できます。[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)を参照してください。 + ## Pi Pi インテグレーションをインストールします: diff --git a/docs/next/website/src/content/docs/ja/session-state.mdx b/docs/next/website/src/content/docs/ja/session-state.mdx index 4f16bda6..a66d6a92 100644 --- a/docs/next/website/src/content/docs/ja/session-state.mdx +++ b/docs/next/website/src/content/docs/ja/session-state.mdx @@ -83,7 +83,7 @@ pane_history = true resume_agents_on_restore = false ``` -Herdr が resume するのは、現行の公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインだけです。 +Herdr が resume するのは、現行の公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインと、エージェント自身が resume コマンドを報告したペインです。[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)を参照してください。 クライアントがアタッチしてターミナルサイズとテーマのコンテキストを提供すると、Herdr は各ペインがフォーカスされるのを待たずに、ワークスペースとタブをまたいで復元対象のエージェントペインを resume します。 diff --git a/docs/next/website/src/content/docs/ja/socket-api.mdx b/docs/next/website/src/content/docs/ja/socket-api.mdx index 35a03625..361f5222 100644 --- a/docs/next/website/src/content/docs/ja/socket-api.mdx +++ b/docs/next/website/src/content/docs/ja/socket-api.mdx @@ -545,6 +545,22 @@ Herdr はローカルソケット上の改行区切り JSON を使います。Un } ``` +どちらのメソッドも、Herdr サーバーの再起動後に報告元の現在のセッションを再開するコマンドを、省略可能な `resume_argv` 配列で受け付けます。最初の要素はパスではなく単純なコマンド名でなければならず、どの要素にもアポストロフィを含めることはできません。無効な値は `invalid_resume_argv` で失敗し、その報告は適用されません。カスタムエージェントは、コマンドを付ける前に `pane.report_agent` でペインを保持している必要があり、そうでない場合は `resume_not_accepted` で失敗します。Herdr は同じ `source` と `agent` がペインを保持している間だけコマンドを保持し、そのエージェントに対する Herdr 組み込みの resume コマンドより優先します。古い Herdr はこのフィールドを無視します。 + +```json +{ + "id": "req_3", + "method": "pane.report_agent_session", + "params": { + "pane_id": "w1:p1", + "source": "custom:my-agent", + "agent": "my-agent", + "agent_session_id": "...", + "resume_argv": ["my-agent", "--resume", "..."] + } +} +``` + Herdr に保存されたネイティブセッション参照があるとき、`pane.get`、`pane.list`、`agent.get`、`agent.list` は読み取り専用の `agent_session` オブジェクトを公開します: ```json diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx index d333dab7..69bff955 100644 --- a/docs/next/website/src/content/docs/session-state.mdx +++ b/docs/next/website/src/content/docs/session-state.mdx @@ -81,7 +81,7 @@ Native agent session restore is enabled by default. Disable it with: resume_agents_on_restore = false ``` -Herdr resumes panes that reported a native session reference through a current official Herdr integration, and panes whose agent reported its own resume command. See [Integrate your own agent](/docs/integrations/#integrate-your-own-agent). +Herdr resumes panes that reported a native session reference through a current official Herdr integration, and panes whose agent reported its own resume command. See [Add Herdr support to your agent](/docs/add-herdr-support/). After a client attaches and provides terminal size and theme context, Herdr resumes eligible restored agent panes across workspaces and tabs without waiting for each pane to be focused. diff --git a/docs/next/website/src/content/docs/zh-cn/add-herdr-support.mdx b/docs/next/website/src/content/docs/zh-cn/add-herdr-support.mdx new file mode 100644 index 00000000..827fd233 --- /dev/null +++ b/docs/next/website/src/content/docs/zh-cn/add-herdr-support.mdx @@ -0,0 +1,117 @@ +--- +title: 为你的智能体添加 Herdr 支持 +description: 在不为 Herdr 添加原生支持的情况下,从你自己的代码向 Herdr 上报编码智能体的状态和恢复命令。 +--- + +如果你在开发编码智能体,只靠你自己的代码就能让它在 Herdr 中获得一等支持。不需要向 Herdr 提交拉取请求,也不需要等待 Herdr 发布新版本。 + +智能体向 Herdr 上报后,用户会得到: + +- 在侧边栏和 `herdr agent list` 中显示的智能体名称以及 `idle`、`working` 或 `blocked` 状态 +- 智能体完成或需要用户决策时的通知 +- `herdr agent wait` 以及其他等待智能体状态的自动化 +- Herdr 服务器重启后,同一个窗格中恢复同一个会话 + +对于厂商没有提供集成的智能体,由 Herdr 维护集成。如果你维护自己的智能体,自己掌握集成就可以按自己的发布节奏修复问题。 + +## 工作方式 + +Herdr 窗格中的每个进程都会继承这些环境变量: + +| 变量 | 含义 | +| --- | --- | +| `HERDR_ENV` | 在 Herdr 中为 `1` | +| `HERDR_PANE_ID` | 智能体所在的窗格 | +| `HERDR_BIN_PATH` | 管理这个窗格的 Herdr 可执行文件 | +| `HERDR_SOCKET_PATH` | Herdr 的 API 套接字 | + +你的智能体通过 `"$HERDR_BIN_PATH"` 发送三类上报: + +1. **状态。** 每当 `idle`、`working` 或 `blocked` 发生变化时上报。 +2. **恢复命令。** 上报重新打开当前会话的命令。 +3. **释放。** 智能体退出时释放窗格。 + +仅在 `HERDR_ENV=1` 且其他变量都存在时上报。在 Herdr 之外,集成不应执行任何操作。 + +## 上报状态 + +```bash +"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --state working \ + --seq 1 +``` + +- 一轮开始时上报 `working`,可以接收输入时上报 `idle`,需要用户做决定时上报 `blocked`。可以用 `--message` 说明阻塞原因。 +- `--agent` 是用户看到的名称。请使用你自己智能体的名称,不要使用 Herdr 已经支持的智能体的名称。 +- `--source` 用于标识你的集成。保持稳定且唯一。不要以 `herdr:` 开头,这个前缀由 Herdr 自己的集成使用。 +- `--seq` 可以省略,但建议加上。它必须随来自你的来源的每次上报递增,跨会话和智能体重启也要继续递增。时间戳就很合适。Herdr 会忽略编号不大于上次已接受编号的上报,所以迟到或乱序的上报不会覆盖更新的状态。 + +## 上报恢复命令 + +把恢复当前会话的命令放在 `--` 之后。带上该会话需要的选项,例如模型或权限模式,这样恢复后的会话行为一致: + +```bash +"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --state idle \ + --seq 2 \ + --agent-session-id "$SESSION_ID" \ + -- my-agent --resume "$SESSION_ID" --model my-model +``` + +命令可以附在任何一次状态上报中,只有会话变化时也可以用 `pane report-agent-session` 发送。每当智能体切换会话时,请重新上报。 + +Herdr 服务器重启后,Herdr 会在同一目录中打开该窗格并在其中运行这条命令。命令必须遵守以下规则: + +- 第一个词是用户 `PATH` 上的普通命令名,例如 `my-agent`,不能是路径。 +- 任何参数都不能包含撇号。 +- 你的来源必须先持有该窗格,所以请在发送命令之前或同时用 `report-agent` 上报状态。否则 Herdr 会返回 `resume_not_accepted`。 + +违反前两条规则的命令会被 Herdr 以 `invalid_resume_argv` 拒绝,该次上报也不会生效。用户可以用 `[session] resume_agents_on_restore = false` 关闭恢复。 + +## 退出时释放 + +```bash +"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ + --source my-agent \ + --agent my-agent \ + --seq 3 +``` + +释放会立即从窗格中清除智能体的名称、状态和恢复命令。只在用户真正退出时释放。如果智能体在同一个进程中用一个会话替换另一个会话,请上报新会话,而不是释放。 + +如果智能体退出时没有释放,Herdr 会在窗格回到空闲的 shell 提示符后察觉,并清除该智能体及其恢复命令。通常需要一两秒。这只是兜底机制,不能代替释放。 + +## 不要拖慢智能体 + +- 不要让 Herdr 拖慢你的智能体。在后台或用较短的超时发送上报,并忽略失败。 +- 只发送最新状态。如果一次上报正在发送时积累了多个变化,丢弃较旧的那些。 +- 旧版 Herdr 会忽略恢复命令,其他功能照常工作。 + +## 直接使用套接字 + +`HERDR_BIN_PATH` 和 CLI 是可移植的选择,包括在 Windows 上。如果你的智能体需要直接 IPC,可以发送 [Socket API](/zh-cn/docs/socket-api/) 中说明的等效 `pane.report_agent`、`pane.report_agent_session` 和 `pane.release_agent` 请求。恢复命令放在 `resume_argv` 数组中。 + +## 检查你的集成 + +在 Herdr 窗格中启动你的智能体,然后查看 Herdr 看到了什么: + +```bash +herdr pane get "$HERDR_PANE_ID" +herdr agent list +``` + +要在不影响日常会话的情况下测试恢复,请使用单独的命名会话: + +1. 启动 `herdr --session my-agent-test`,然后在一个窗格中运行你的智能体。 +2. 用 `herdr session stop my-agent-test` 停止该会话。 +3. 再次启动 `herdr --session my-agent-test`。窗格应当运行你的恢复命令,智能体应当再次上报。 + +## 示例 + +[Prime Agent 内置的 Herdr 上报器](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)是一个真实的集成。它只在 Herdr 中启用,将智能体事件映射为 `working`、`idle` 和 `blocked`,跨会话保持上报顺序,并在退出时释放窗格。 + +如果想在不改变状态的情况下改变智能体的显示方式,例如标题或自定义状态文字,请参阅[自定义状态标签](/zh-cn/docs/integrations/#自定义状态标签)。 diff --git a/docs/next/website/src/content/docs/zh-cn/agents.mdx b/docs/next/website/src/content/docs/zh-cn/agents.mdx index 80d572c6..13ec4998 100644 --- a/docs/next/website/src/content/docs/zh-cn/agents.mdx +++ b/docs/next/website/src/content/docs/zh-cn/agents.mdx @@ -114,7 +114,7 @@ herdr integration install claude herdr integration status ``` -每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。如果你正在构建智能体,[自定义集成指南](/zh-cn/docs/integrations/#集成你自己的智能体)介绍了如何在不为 Herdr 添加原生支持的情况下上报生命周期状态。 +每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。如果你正在构建智能体,[为你的智能体添加 Herdr 支持](/zh-cn/docs/add-herdr-support/)介绍了如何在不为 Herdr 添加原生支持的情况下上报生命周期状态和恢复命令。 ## 自定义智能体标签 diff --git a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx index 987e0c4a..ae5c3ab4 100644 --- a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx +++ b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx @@ -258,7 +258,8 @@ herdr pane report-agent <pane_id> \ [--message TEXT] \ [--seq N] \ [--agent-session-id ID] \ - [--agent-session-path PATH] + [--agent-session-path PATH] \ + [-- RESUME_COMMAND...] herdr pane report-agent-session <pane_id> \ --source ID \ @@ -266,7 +267,8 @@ herdr pane report-agent-session <pane_id> \ [--seq N] \ [--agent-session-id ID] \ [--agent-session-path PATH] \ - [--session-start-source SOURCE] + [--session-start-source SOURCE] \ + [-- RESUME_COMMAND...] herdr pane release-agent <pane_id> \ --source ID \ @@ -276,6 +278,8 @@ herdr pane release-agent <pane_id> \ `report-agent-session` 只更新原生会话身份,不上报生命周期状态。`release-agent` 在智能体进程退出时结束该来源的生命周期权威。 +`--` 之后的参数是服务器重启后 Herdr 为恢复此会话而运行的命令。第一个参数必须是 `PATH` 上的普通命令名,并且任何参数都不能包含撇号。 + 当官方集成上报了原生会话引用时,`pane get`、`pane list`、`agent get` 和 `agent list` 会包含一个只读的 `agent_session` 对象。没有存储原生会话引用时,该字段被省略。 当 Herdr 能解析控制窗格的前台进程的 cwd 时,这些命令会包含 `foreground_cwd`。已有的 `cwd` 字段仍然是用于标签和 follow-cwd 行为的窗格/工作区 cwd。 diff --git a/docs/next/website/src/content/docs/zh-cn/integrations.mdx b/docs/next/website/src/content/docs/zh-cn/integrations.mdx index 32d97e08..0fc3d2c0 100644 --- a/docs/next/website/src/content/docs/zh-cn/integrations.mdx +++ b/docs/next/website/src/content/docs/zh-cn/integrations.mdx @@ -68,37 +68,14 @@ Herdr 以两种不同方式使用集成: 自定义集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。它们不需要内置到 Herdr 中,也不要求 Herdr 识别智能体的可执行文件。 -## 集成你自己的智能体 - -在 Herdr 窗格中运行的智能体会继承 `HERDR_ENV`、`HERDR_PANE_ID`、`HERDR_BIN_PATH` 和 `HERDR_SOCKET_PATH`。如果智能体提供生命周期钩子,可从这些钩子通过 Herdr CLI 上报语义状态: - -```bash -"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent \ - --state working -``` - -当智能体等待输入时上报 `idle`,需要用户决策时上报 `blocked`。用 `--message` 描述阻塞原因。智能体退出时,释放同一来源的生命周期权威: - -```bash -"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ - --source custom:my-agent \ - --agent my-agent -``` - -仅在 `HERDR_ENV=1` 且必要变量存在时上报,这样集成在 Herdr 外不会执行任何操作。保持 `--source` 稳定且对该集成唯一。如果上报可能乱序到达,请加入严格递增的 `--seq`;Herdr 会忽略同一来源的旧序列号。 - -你可以在 `report-agent` 中加入 `--agent-session-id` 或 `--agent-session-path`,也可以在会话身份独立于状态变化时使用 `pane report-agent-session`。Herdr 会通过窗格和智能体 API 暴露该引用。自动恢复会话还要求 Herdr 知道如何启动该智能体并恢复所引用的会话。 - -要实现可移植的集成,请使用 `HERDR_BIN_PATH` 和 CLI 包装命令。需要直接 IPC 的代码可以发送 [Socket API](/zh-cn/docs/socket-api/) 中说明的等效 `pane.report_agent`、`pane.report_agent_session` 和 `pane.release_agent` 请求。 - -[Prime Agent 内置的 Herdr 上报器](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)是一个真实实现示例。它只在 Herdr 中启用,将智能体事件映射为 `working`、`idle` 和 `blocked`,跨会话保持上报顺序,并在退出时释放权威。 - 一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode 和 Antigravity CLI 的窗格。 原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Qwen Code 版本 `1`、Letta Code 版本 `1`、Cursor Agent CLI 版本 `1`、Grok CLI 版本 `2`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `5`、MastraCode 版本 `1`、Antigravity CLI 版本 `1`。用 `herdr integration status` 查看已安装版本。 +## 集成你自己的智能体 + +如果你在开发编码智能体,可以在不为 Herdr 添加原生支持的情况下,从你自己的代码向 Herdr 上报它的状态和恢复命令。参阅[为你的智能体添加 Herdr 支持](/zh-cn/docs/add-herdr-support/)。 + ## Pi 安装 Pi 集成: diff --git a/docs/next/website/src/content/docs/zh-cn/session-state.mdx b/docs/next/website/src/content/docs/zh-cn/session-state.mdx index 9be84060..6cb83f7d 100644 --- a/docs/next/website/src/content/docs/zh-cn/session-state.mdx +++ b/docs/next/website/src/content/docs/zh-cn/session-state.mdx @@ -83,7 +83,7 @@ pane_history = true resume_agents_on_restore = false ``` -Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引用的窗格。 +Herdr 会恢复通过当前官方 Herdr 集成上报了原生会话引用的窗格,以及智能体自己上报了恢复命令的窗格。参阅[为你的智能体添加 Herdr 支持](/zh-cn/docs/add-herdr-support/)。 当客户端连接并提供终端尺寸和主题上下文后,Herdr 会跨工作区和标签页恢复符合条件的智能体窗格,不需要等每个窗格被聚焦。 diff --git a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx index f947fc43..e26c259e 100644 --- a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx +++ b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx @@ -541,6 +541,22 @@ Herdr 在本地 socket 上使用换行分隔的 JSON。在 Unix 上,那个 socke } ``` +两个方法都接受可选的 `resume_argv` 数组,内容是 Herdr 服务器重启后恢复上报者当前会话的命令。第一个元素必须是普通命令名而不是路径,并且任何元素都不能包含撇号;无效值会以 `invalid_resume_argv` 失败,该次上报不会生效。自定义智能体必须先通过 `pane.report_agent` 持有窗格才能附加命令,否则请求会以 `resume_not_accepted` 失败。Herdr 只在同一 `source` 和 `agent` 持有窗格时保留该命令,并且它优先于 Herdr 为该智能体内置的恢复命令。旧版 Herdr 会忽略这个字段。 + +```json +{ + "id": "req_3", + "method": "pane.report_agent_session", + "params": { + "pane_id": "w1:p1", + "source": "custom:my-agent", + "agent": "my-agent", + "agent_session_id": "...", + "resume_argv": ["my-agent", "--resume", "..."] + } +} +``` + Herdr 存有原生会话引用时,`pane.get`、`pane.list`、`agent.get` 和 `agent.list` 暴露一个只读的 `agent_session` 对象: ```json |