# Symbi Shell — インタラクティブエージェントオーケストレーション

> **Status: Beta.** `symbi shell` は日常的に使用可能ですが、コマンドサーフェス、キーバインド、永続化フォーマットはマイナーリリース間で変更される可能性があります。問題は [thirdkeyai/symbiont](https://github.com/thirdkeyai/symbiont/issues) に `shell` ラベルを付けて報告してください。

`symbi shell` は、Symbiont エージェントの構築、オーケストレーション、運用のための [ratatui](https://ratatui.rs) ベースのターミナル UI です。`symbi up` や `symbi run` と同じランタイム上に構築されていますが、会話型のオーサリング、ライブオーケストレーション、リモートアタッチを備えたインタラクティブセッションとして公開されます。

## シェルを使用する場面

| ユースケース | コマンド |
|----------|---------|
| プロジェクトをスキャフォールドし、LLM 支援でエージェント、ツール、ポリシーを反復的に開発 | `symbi shell` |
| インタラクティブループなしで 1 つのエージェントを最後まで実行 | `symbi run <agent> -i <json>` |
| webhook、cron、チャットアダプター用にフルランタイムを起動 | `symbi up` |

シェルはオーサリングのデフォルトエントリーポイントです。非インタラクティブコマンドは CI、cron ジョブ、デプロイパイプライン内での使用に適しています。

## 起動

```bash
symbi shell                    # start a fresh session
symbi shell --list-sessions    # show saved sessions and exit
symbi shell --resume <id>      # reopen a session by UUID
```

`--resume` は UUID または以前に `/snapshot` で保存されたスナップショット名を受け付けます。

## レイアウト

シェルは既存のスクロールバックとターミナルを共有するインラインビューポートを使用します。上から下に以下が表示されます：

- **プロジェクト構造サイドバー**（トグル可能） — 現在のプロジェクトのファイルツリー。エージェント、ポリシー、ツールをハイライト表示。
- **トレースタイムライン** — Observe、Reason、Gate、Act の ORGA フェーズごとに色分けされたカード。LLM 呼び出し中にリアルタイムでストリーミング。
- **エージェントカード** — 現在選択されているエージェントのメタデータ、ポリシー、最近の呼び出し。
- **入力行** — `/command` または自由形式のプロンプトを入力。`@mention` はファジー補完でパスとエージェントを取り込みます。

シンタックスハイライトは tree-sitter 文法経由で Symbiont DSL、Cedar、ToolClad マニフェストをカバーします。

### キーバインド

| バインド | アクション |
|---------|--------|
| `Enter` | 入力を送信（補完ポップアップが表示されていても動作） |
| `/` または `@` | 補完ポップアップを自動で開く |
| `↑` / `↓` | 入力履歴またはポップアップエントリを移動 |
| `Ctrl+R` | 履歴を逆方向に検索 |
| `Tab` | ハイライトされた補完を確定 |
| `Esc` | ポップアップを閉じる／実行中の LLM 呼び出しをキャンセル |
| `Ctrl+L` | 表示されている出力バッファをクリア |
| `Ctrl+D` | シェルを終了 |

Zellij 配下では、シェルはマルチプレクサを検出し、インラインビューポートの互換性警告を出力します。代替スクリーンバッファで実行したい場合は `--full-screen` を使用してください。

## コマンドカタログ

コマンドは目的別にグループ化されています。すべてのコマンドは `help` / `--help` / `-h` を受け付け、オーケストレーターにディスパッチすることなく短い使用法の説明を表示します。

### オーサリング

| コマンド | 機能 |
|---------|-------------|
| `/init [profile\|description]` | Symbiont プロジェクトをスキャフォールド。既知のプロファイル名（`minimal`、`assistant`、`dev-agent`、`multi-agent`）は決定論的スキャフォールドを実行し、その他の文字列はオーケストレーターがプロファイル選択に使用する自由形式の記述として扱われます。 |
| `/spawn <description>` | プロンプトから DSL エージェントを生成。結果は `agents/` に書き込まれる前にプロジェクト制約に対して検証されます。 |
| `/policy <requirement>` | 記述された要件に対する Cedar ポリシーを生成し検証します。 |
| `/tool <description>` | ToolClad `.clad.toml` マニフェストを生成し検証します。 |
| `/behavior <description>` | 再利用可能な DSL ビヘイビアブロックを生成し検証します。 |

オーサリングコマンドは検証が成功した後にのみディスクに書き込みます。制約違反は行単位の正確なエラーとともにトレースタイムラインで説明されます。

### オーケストレーション

| コマンド | パターン |
|---------|---------|
| `/run <agent> [input]` | エージェントを起動または再実行。 |
| `/ask <agent> <message>` | エージェントにメッセージを送信し、応答を待機。 |
| `/send <agent> <message>` | 応答を待たずにメッセージを送信。 |
| `/chain <a,b,c> <input>` | 各エージェントの出力を次のエージェントにパイプ。 |
| `/parallel <a,b,c> <input>` | 同じ入力でエージェントを並列実行し、結果を集約。 |
| `/race <a,b,c> <input>` | 並列実行し、最初に成功した応答が勝ち、残りはキャンセル。 |
| `/debate <a,b,c> <topic>` | トピックに関する構造化されたマルチエージェントディベート。 |
| `/exec <command>` | サンドボックス化された dev エージェント内でシェルコマンドを実行。 |

### 運用

| コマンド | 機能 |
|---------|-------------|
| `/agents` | アクティブなエージェントを一覧表示。 |
| `/monitor [agent]` | 指定したエージェント（またはすべて）のライブステータスをストリーミング。 |
| `/logs [agent]` | 最近のログを表示。 |
| `/audit [filter]` | 最近の監査証跡エントリを表示。エージェント、決定、または時間範囲でフィルター。 |
| `/doctor` | ローカルランタイム環境を診断。 |
| `/memory <agent> [query]` | エージェントのメモリをクエリ。 |
| `/debug <agent>` | エージェントの内部状態を検査。 |
| `/pause`、`/resume-agent`、`/stop`、`/destroy` | エージェントライフサイクル制御。 |

### ツール、スキル、検証

| コマンド | 機能 |
|---------|-------------|
| `/tools [list\|add\|remove]` | エージェントが利用可能な ToolClad ツールを管理。 |
| `/skills [list\|install\|remove]` | エージェントが利用可能なスキルを管理。 |
| `/verify <artifact>` | 署名されたアーティファクト（ツールマニフェスト、スキル）を SchemaPin 署名に対して検証。 |

### スケジューリング

| コマンド | 機能 |
|---------|-------------|
| `/cron list` | スケジュールされたエージェントジョブを一覧表示。 |
| `/cron add` / `/cron remove` | スケジュールされたジョブの作成または削除。 |
| `/cron history` | 最近の実行を表示。 |

`/cron` はローカルでもリモートアタッチ経由でも動作します（後述）。完全な cron エンジンについては [スケジューリングガイド](/scheduling) を参照してください。

### チャネル

| コマンド | 機能 |
|---------|-------------|
| `/channels` | 登録されたチャネルアダプター（Slack、Teams、Mattermost）を一覧表示。 |
| `/connect <channel>` | 新しいチャネルアダプターを登録。 |
| `/disconnect <channel>` | アダプターを削除。 |

デプロイされたランタイムを対象とする場合、チャネル管理にはリモートアタッチが必要です。

### シークレット

| コマンド | 機能 |
|---------|-------------|
| `/secrets list\|set\|get\|remove` | ランタイムの暗号化ローカルストア内のシークレットを管理。 |

シークレットは `SYMBIONT_MASTER_KEY` で保存時に暗号化され、エージェントごとにスコープされます。

### デプロイ (Beta)

> **Status: Beta.** デプロイスタックは OSS エディションではシングルエージェントです。マルチエージェントおよびマネージドデプロイはロードマップにあります。

| コマンド | ターゲット |
|---------|--------|
| `/deploy local` | ローカルの Docker デーモン上の堅牢化されたサンドボックスランナー付き Docker。 |
| `/deploy cloudrun` | Google Cloud Run — イメージをビルド、プッシュし、サービスをデプロイ。 |
| `/deploy aws` | AWS App Runner。 |

`/deploy` はアクティブなエージェントとプロジェクト設定を読み取り、再現可能なデプロイアーティファクトを生成します。マルチエージェントトポロジーでは、コーディネーターと各ワーカーを個別にデプロイし、クロスインスタンスメッセージングで接続します（[ランタイムアーキテクチャ](/runtime-architecture#cross-instance-agent-messaging) を参照）。

### リモートアタッチ

| コマンド | 機能 |
|---------|-------------|
| `/attach <url>` | このシェルを HTTP または HTTPS 経由でリモートランタイムにアタッチ。 |
| `/detach` | 現在アタッチされているランタイムからデタッチ。 |

リモートまたは本番ターゲットには必ず `https://` を使用してください — アタッチチャネルは認証トークンと運用トラフィックを伝送するため、平文 HTTP はローカル開発のみに適しています。`local` ショートカットはデフォルトで `http://localhost:8080` を使用し、明示的なスキームなしで指定された URL はループバック開発のエルゴノミクスを保つために `http://` プレフィックスが付与されます。それ以外のケースでは、完全な `https://...` URL を渡してください。

アタッチされると、`/cron`、`/channels`、`/agents`、`/audit`、およびほとんどの運用コマンドはローカルではなくリモートランタイムに作用します。`/secrets` はローカルのまま — リモートシークレットはリモートランタイムのストアに残ります。

### セッション管理

| コマンド | 機能 |
|---------|-------------|
| `/snapshot [name]` | 現在のセッションを保存。 |
| `/resume <snapshot>` | 保存されたスナップショットを復元。 |
| `/export <path>` | 会話トランスクリプトをディスクにエクスポート。 |
| `/new` | 新しいセッションを開始し、現在のセッションを破棄。 |
| `/compact [limit]` | トークン予算内に収まるように会話履歴を圧縮。 |
| `/context` | 現在のコンテキストウィンドウとトークン使用量を表示。 |

セッションは `.symbi/sessions/<uuid>/` 配下に保存されます。コンテキストが設定された予算を超えると、シェルは自動的に圧縮をトリガーします。

### セッション制御

| コマンド | 機能 |
|---------|-------------|
| `/model [name]` | アクティブな推論モデルを表示または切り替え。 |
| `/cost` | セッションのトークンおよび API コスト合計を表示。 |
| `/status` | ランタイムおよびセッションステータスを表示。 |
| `/dsl` | DSL モードとオーケストレーター入力モードを切り替え — DSL モードはインプロセスで評価。 |
| `/clear` | 表示されている出力バッファをクリア（履歴は保持）。 |
| `/quit` / `/exit` | シェルを終了。 |
| `/help` | コマンドカタログを表示。 |

## DSL モード

`/dsl` を押すと入力行が DSL モードに切り替わります。DSL モードでは、シェルはオーケストレーターを経由せずに、tree-sitter ベースの補完とエラーを備えたインプロセス DSL インタプリタに対して入力を解析・評価します。再度 `/dsl` を押すと元に戻ります。

## 制約と検証

オーサリングコマンドはローカル検証パイプラインを強制します：

1. 生成されたアーティファクトは適切に Symbiont DSL 文法、Cedar、または ToolClad に対して解析されます。
2. 制約ローダーがプロジェクトレベルの制約（例：禁止されたケーパビリティ、必須ポリシー）に対して結果をチェックします。
3. 両方のステップが成功した後にのみアーティファクトがディスクに書き込まれます。

オーケストレーター LLM は検証エラーを通じて制約ファイルの影響を確認できますが、ファイル自体を変更することはできません — これは `symbi tools validate` パイプラインで使用されているのと同じ信頼モデルです。

## Beta の注意事項

シェルの以下の部分はまだ活発に開発中であり、非推奨期間なしに変更される可能性があります：

- `/branch` と `/copy`（セッション分岐）は予約されたコマンドであり、現在は「将来のリリースで予定」のスタブを出力します。
- `/deploy cloudrun` と `/deploy aws` はシングルエージェントのみです。
- スナップショットフォーマットと `.symbi/sessions/` レイアウトはマイナーリリース間で変更される可能性があります。耐久性のあるトランスクリプトが必要な場合は `/export` を使用してください。
- ファジー補完のヒューリスティックとトレースタイムラインのレイアウトはフィードバックに基づいて調整され、変更される可能性があります。

現時点で安定したサーフェスが必要な場合は、`symbi up`、`symbi run`、および [HTTP API](/api-reference) を優先してください — これらは `SECURITY.md` の互換性保証の対象です。

## 関連項目

- [入門ガイド](/getting-started) — インストールと `symbi init`
- [DSL ガイド](/dsl-guide) — エージェント定義言語リファレンス
- [ToolClad](/toolclad) — 宣言的ツール契約
- [スケジューリング](/scheduling) — cron エンジンと配信ルーティング
- [セキュリティモデル](/security-model) — 信頼境界とポリシー実施
