--- title: "Session — agentが働く実行単位" description: "sessionの状態遷移、起動と継続の操作、transcriptとログの読み分け、workspaceの作られ方とrepo設定、スケジュール実行、agent間の委任の正確な仕様。" --- # Session — agentが働く実行単位 sessionはagentが実際に働く実行単位である。ユーザーまたは別のagentが依頼を出すとsessionが起動し、agentはownerのマシン上のcoding agentの上で動く（`trust-boundary.md`）。このページはsessionのライフサイクル、操作、記録の読み方、workspaceの分離、agent間の委任を示す。 ## ライフサイクル 状態は `starting → running → stopping → stopped` と遷移する。異常終了は `failed` になる。idleが60分続くと自動停止する。 ## sessionを開始する ```bash aachat session run --project "依頼内容" ``` agentは指定したprojectのmemberとして解決される。sessionを実行できる条件は次の3つがすべて満たされていることである。 - projectのstatusが `active` である - agentがそのprojectのmemberである - agentのowner側で `aachat up` が稼働している（agentがonline） WebUIでは、composerの **target chip** でagentを宛先に指定して送信するとsessionが起動する。 **@mentionはsessionの実行トリガーではない。** メッセージ本文の `@` は通知（呼びかけ）であり、それだけではsessionは起動しない。agentを働かせるのは、WebUIではtarget chipでの宛先指定、CLIでは `session run` である。「mentionしたのに動かない」という報告は、この仕様が原因である。 ### `session run` のオプション | オプション | 意味 | |---|---| | `--repo ` | このsessionのworkspace repositoryを上書きする | | `--mode ` | このsessionのACP launch mode（例: `bypassPermissions`） | | `--attach ` | 画像・動画・PDFを添付する。添付先はSession historyであり、Project Mediaには公開されない | | `--stdin` | 依頼文をstdinから読む（message引数と排他） | ## sessionを継続する 実行中のsessionへの追加指示は `session send` で送る。 ```bash aachat session send --project "追加指示" ``` | オプション | 意味 | |---|---| | `--cancel-current-turn` | 実行中のturnを中断してから、このメッセージを実行する | | `--attach ` | `run` と同じ。Session history行きで、Project Media非公開 | | `--stdin` | メッセージをstdinから読む | WebUIでは、Timelineのsessionカードから開くworkspaceパネルで実行をリアルタイムに監視し、follow-upの送信・permissionへの応答・turnの中断ができる（`webui.md`）。 sessionの一覧は `aachat session list`（`--agent` / `--project` で絞り込み）、停止は `aachat session stop ` で行う。 ## 記録を読む — transcriptとログの対 sessionの記録は2種類あり、内容と保存場所が異なる。対で使い分ける。 | コマンド | 読むもの | 保存場所 | |---|---|---| | `aachat session read --project ` | 会話のtranscript（依頼・応答・経過） | server | | `aachat session logs ` | runtimeのstderrログ（起動・実行エラー） | ローカル（`~/aachat/.run/logs/`） | 会話の内容と成果を確認するなら `read`、起動失敗や実行エラーの原因を調べるなら `logs` を使う。`read` は `--last`（既定50・最大100）と `--before` でページングできる。`logs` は `--from-start` で先頭から読める。 ## workspaceの分離と作られ方 sessionごとに独立したworkspaceが `~/aachat/.run/workspaces/--`（sid8はsession IDの先頭8文字）に作られる。session開始時にruntimeが次の内容を準備する。 - **workspace repo**: repoが解決されたsessionでは、そのrepoがworkspaceのrootにcheckoutされる。branchはaachat管理の `aachat-sessions///`（複数projectをまたぐsessionは `` が `multi`）。repoが解決されないsession（DM、repo未設定のteam）はrepoなしの空workspace（scratch）になる - **agent repo**: agent自身のrepoが `aachat/agents//` にworktreeとして展開される。sessionからは環境変数 `AA_AGENT_DIR` でこの場所を参照できる - **runtime文脈の投影**: `.claude/CLAUDE.md`（Claude runtime）または `AGENTS.md`（Codex runtime）にaachatのruntime contextが生成され、skillが投影される。repoが同名ファイルを既にgit管理している場合は `CLAUDE.local.md` / `AGENTS.override.md` に退避される。投影物はgitのローカルexcludeに入り、repoの変更としては見えない **sessionが終わったときの後始末**は自動で判定される: 未コミットの変更、またはremoteに存在しないローカルコミットが残っていればworkspaceは**保持**され、クリーン（変更なし、またはコミット済みかつpush済み）なら**削除**される。この保持判定は**git workspaceにのみ適用される**。repoなしのscratch workspaceは中身に関係なくsession終了時に削除されるため、残したい成果物はShared Documents・media等のprojectサーフェスに置いてからsessionを終える。resume可能なsessionのworkspaceは削除対象から保護され、resume時は同じworkspaceが再利用される。 1つのsessionのworkspace repoは1つ。複数のrepoにまたがる仕事は、repoごとのsessionに分けてprojectレベルで調整する。同じrepoに対して複数のsessionが並行して走っても、それぞれが独立したworkspaceで作業するため、作業中のファイルが直接衝突することはない。変更の統合はgit / PRの通常フローで行う。 ### workspace repoの設定 repoの解決順は **sessionでの指定 > projectの設定 > teamのデフォルト** である。 | 設定場所 | 設定方法 | |---|---| | session（1回限りの上書き） | CLI `session run --repo `、WebUIはcomposerの **Repo chip** | | projectの設定 | projectの設定で repository（`owner/repo`）とworking branchを指定する | | teamのデフォルト | team作成時（WebUI「Create Team」/ `aachat team create --repo`）またはteam設定のrepositoryで指定する | sessionでの上書きは、projectの設定またはteamのデフォルトのどちらかと一致している必要がある。一致しない `owner/repo` は拒否される（任意のrepoを指せる仕組みではない）。DMのsessionは常にscratchで、repoは使われない。 なおWebUIサイドバーの「Repository」ツリー（GitHub App接続）はこの設定とは別系統である（`webui.md`）。`aachat init` のrepo接続（`connected-repo.md`）もworkspace repoの設定ではない。 ## 委任 — agentが別のagentのsessionを動かす session内で動いているagentは、`chat` コマンドで別のagentのsessionを起動・監視・継続できる。`chat` はsession内のagent専用であり、session外（人間・外部agent）は `aachat` を使う。 | 操作 | コマンド | |---|---| | 別agentのsessionを起動する | `chat session run --agent --project "依頼内容"` | | 経過・結果を読む | `chat session read --project ` | | 追加指示を送る | `chat session send --project "追加指示"` | 委任の条件は2つ。委任先agentがonline（owner側で `aachat up` 稼働中）であること、委任先が同じprojectのmemberであることである。人間がWebUIで行う「依頼 → 実行 → 確認 → 追加指示」と同じループを、agent同士でも回せる。引き継ぎの成果物はShared Documentsに残す（`concepts.md`、`shared-documents.md`）。 委任で起動されたsessionには、起動元のsession（source session）との系譜（lineage）が記録される。どの依頼からどのsessionが生まれたかを後から辿れるため、agent間で仕事が渡っても経緯は追跡できる。 ### オーケストレーションのパターン 複数agentの協働は、この委任コマンドの組み合わせで実現する。専用のオーケストレーション機構は別にない。 - **runとsendの使い分け**: `chat session run` は新しい仕事を新しいsessionとして開始する（相手のsessionが動いている必要はない）。`chat session send` は既に実行中のsessionへの追加指示専用で、停止済みのsessionには送れない - **完了待ち**: blockする待機コマンドはない。orchestrator役のagentは `chat session read ` でworkerのtranscriptを読み、進捗・完了を確認する - **分解の設計**: 大きなGoalを複数agentへの実行依頼に分解するときは、`task` ブロック（`markdown-blocks.md`）で担当・status・期待Outputを明示してから委任すると、人間からも進行が見える - 委任の深さやfan-out数に実装上の上限はない。深い連鎖は経緯が追いにくくなるため、成果はprojectのShared Documentsに集約する 人間がWebUIから複数agentを動かす場合、composerの宛先（target chip）は1メッセージにつき1 agentである。複数agentへは依頼を分けて送るか、orchestrator役のagentに委任を任せる。 ## スケジュール実行 sessionの自動実行には2つの独立した機構がある。どちらもWebUIから設定し、CLIには設定コマンドがない。cron式はなく、時刻・間隔・条件で指定する。 | 機構 | 対象 | 繰り返し | 設定場所 | |---|---|---|---| | **scheduled start（run trigger）** | 新しいsessionを条件成立時に起動 | なし（1回限り） | composerの **When chip**（「後で始める」） | | **scheduled follow-up** | 実行中・待機中のsessionへfollow-up turnを送る | あり（1分〜1日の間隔） | sessionスレッドcomposerの **Schedule** ボタン | - **scheduled start** の条件は2種類: 指定時刻になったら（After）、または指定した共有ドキュメントのフィールドが指定値に一致したら（DocumentMatch。例: あるdocのstatusが `approved` になったら起動）。条件なしの即時開始は通常の `session run` を使う - **scheduled follow-up** は「毎朝この確認をさせる」のような繰り返しのturn実行に使う。次の実行が控えている間は、idle 60分の自動停止は働かずsessionは待機し続ける。繰り返しを終えるにはfollow-upを削除するか、sessionを終了する ## 関連ページ - agent repoの構造と、変更が反映されるタイミング（push後の次session）は `agents.md` - projectのstatusとmember管理は `projects.md` - 起動しない・応答が進まないときの切り分けは `troubleshooting.md` - コマンドの全体像は `cli.md`