superset-orchestrate

Superset のオーケストレーション

Superset のワークスペース、エージェント、ターミナルの各コマンドを使って、ターミナルエージェントを調整します。これはコーディネーター主導のプロトコルとして扱います。Superset はセッションのトランスポートを提供し、タスクの依存関係と完了状態はコーディネーターが管理します。

制御サーフェスを確立する

1. superset auth whoami --json を実行します。
2. superset terminals --help を実行し、list、read、send、close があることを確認します。
3. これらのコマンドがない場合は、superset update を実行して再確認します。サポートされていないオーケストレーションコマンドを作り出したり、代用したりしないでください。
4. Superset モノレポ内で開発する場合は、superset の代わりに bun run --cwd packages/cli dev -- を使い、ルートの .env で設定された API に対してソース CLI を実行します。リリース前のソースコマンドをテストしながら、本番の CLI 認証を再利用するには、packages/cli から SUPERSET_API_URL=https://api.superset.sh bunx cli-framework dev を実行します。
5. タスクを割り当てる前に、ワークスペース、ホスト、ターミナルを利用できるエージェントを特定します。

superset hosts list --json
superset agents list --local --json
superset workspaces list --local --json

対象のワークスペース内から調整する場合は、エージェントとターミナルのコマンドに --workspace "$SUPERSET_WORKSPACE_ID" を明示的に指定します。ワークスペース ID が環境変数から設定されるのは、workspaces get のみです。リモートホストには、常に --host <id> を指定します。対象ホストがオフラインの場合は、hosts wake <id> を使い、割り当て前にオンラインになったことを確認します。--agent superset は使用しないでください。これはチャットセッションを作成するため、ターミナルの read／send では操作できません。

作業を計画する

次のフィールドを含む、簡潔なコーディネーター用の表を作成します。

フィールド	用途
タスク	固定の短い識別子
依存関係	先に完了する必要のあるタスク
ワークスペース	Superset のワークスペース ID
ホスト	ホスト ID、またはローカル
ターミナル	agents create が返す sessionId
状態	pending、ready、running、completed、blocked、failed のいずれか
結果	概要、ファイル、チェック、後続作業

この状態はコーディネーターの作業コンテキスト内に保持します。Superset の組織タスクは課題トラッカーのレコードであり、オーケストレーション DAG のノードではありません。ユーザーから依頼されない限り、作成も変更もしないでください。

独立したタスクを優先し、依存関係の連鎖は浅くします。並行して編集する場合は、作業者ごとに別々のワークスペース／ブランチを割り当てます。読み取り専用の分析や、ファイルが重複しない意図的に補完し合う作業には、同じワークスペースを使ってもかまいません。

作業者のプロトコルを定義する

各作業者には、次の内容を含む範囲を限定したプロンプトを与えます。

• タスク ID と目的
• ワークスペースの範囲と変更可能なファイル
• 受け入れ条件と検証コマンド
• 必要な依存関係や先行調査の結果
• 作業範囲を広げたり、無関係な変更を上書きしたりしないよう警告すること
• 以下の完了エンベロープ

作業者の最終回答は、次のいずれかのエンベロープで終わるよう求めます。

SUPERSET_WORKER_DONE
task: <task-id>
summary: <one-line outcome>
files: <comma-separated paths or none>
checks: <commands and outcomes>
handoff: <next-step context or none>

SUPERSET_WORKER_BLOCKED
task: <task-id>
reason: <specific blocker>
needs: <decision, access, or dependency required>

これらのマーカーはターミナルのスナップショット上で確認できるプロンプト上の規約であり、永続的な Superset イベントではありません。不正なエンベロープやエンベロープがない場合は、構造化されていない出力として扱い、スナップショット全体を確認してください。

作業者を割り当てる

ターミナルエージェントを一度起動し、そのセッション ID を保持します。

superset agents create \
  --workspace <workspace-id> \
  --host <host-id> \
  --agent <preset-or-config-id> \
  --effort <supported-level> \
  --attachment <optional-path> \
  --prompt "<worker prompt>" \
  --json

不要な場合は --effort または --attachment を省略します。結果は { "kind", "sessionId", "label" } です。kind が terminal であることを確認し、sessionId をターミナル ID として保存します。監視を始める前に、準備ができている独立したタスクをすべて起動します。

作業者に分離されたブランチが必要な場合は、まず superset workspaces create を使います。ファイルの担当範囲が明確に分離されていない限り、同じワークツリーで並行して編集する作業者を起動しないでください。

監視と連絡

コーディネーターのコンテキストを失った場合や、ホストサービスを再起動した場合は、ライブターミナル ID を再取得します。

superset terminals list \
  --workspace <workspace-id> \
  --host <host-id> \
  --json

ターミナルの検出では、意味上の宛先やエージェントの完了状態は特定できません。可能な限り、コーディネーターのテーブルにあるタスクとターミナルの対応関係を維持してください。

セッションを変更せずに、最近の出力を読み取ります。

superset terminals read \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --max-lines 240 \
  --json

JSON の結果には text が含まれます。完了またはブロックを示すエンベロープがあるかを確認し、周囲の出力が申告された結果を裏付けていることを確かめてください。terminals list が報告するのはライブセッションであり、エージェントが作業中かアイドル状態かではありません。セッションの有無、attached、ターミナルのタイトルだけから完了を推測しないでください。

確認事項、依存関係の結果、レビューのフィードバック、または引き継ぎ内容を既存のセッションに送信します。

superset terminals send \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --text "<follow-up>" \
  --json

適切な間隔でポーリングし、各パスで実行中のワーカーすべての出力を読み取ります。進捗とユーザーへの更新を確認できる状態に保つため、長時間ブロックするシェルループを 1 回実行するより、短い監視パスを複数回行うことを優先してください。

ワークフローを進める

1. SUPERSET_WORKER_DONE エンベロープを読み、その証拠を確認した後にのみ、タスクを completed にします。
2. ワーカーが SUPERSET_WORKER_BLOCKED を出力した場合は、タスクを blocked にします。再ディスパッチする前に必要事項を解決するか、ユーザーに確認してください。
3. すべての依存タスクが完了した場合にのみ、保留中のタスクを ready にします。
4. 次のワーカープロンプトに依存関係の結果を含めるか、すでに実行中の依存ワーカーに送信します。
5. プロンプト、入力、またはワーカーの選択を変更してから、失敗したタスクを再ディスパッチします。失敗が繰り返される場合は停止し、阻害要因を報告してください。
6. 結果をまとめて提示する前に、リスクの高い変更や重複する変更を独立して検証します。

ブランチが分離されている場合、コミットするか正確な引き継ぎを提供するよう各実装ワーカーに依頼するのは、その作業がユーザーの依頼したワークフローの範囲内である場合に限ります。Superset はワーカーのブランチを自動的にマージしません。

完了とクリーンアップ

各タスクの結果、ワークスペース／ブランチ、変更したファイル、チェック項目、阻害要因、統合順序をまとめます。ワーカーの申告と、コーディネーターが独立して実施したチェックを区別してください。

ユーザーが確認や続行を希望する可能性がある場合は、完了したターミナルを利用できる状態に保ちます。クリーンアップが依頼されている場合、または明らかにワークフローに含まれる場合にのみ、ターミナルを閉じてください。

superset terminals close \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --json

ターミナルを閉じると、そのセッションは終了します。ワークスペースの削除は別の破壊的操作であり、明示的に範囲を指定する必要があります。