作成日: 2026-03-31
ステータス: Draft
対象: session_log
関連文書:
docs/capabilities/session_log/仕様書.md（経緯参照）本仕様は、butler2 における session_log capability の仕様を定義する。
主目的は次の 2 点である。
Phase 2 では要約や memory 連携を検討できるが、本仕様の初期実装ではそこまでを必須にしない。
ただし butler2 では先行実装として summarize を Goose の Worker Instance に委譲できる最小経路を既に持っている。
旧 ButlerLayer の session_log で扱っていた要件のうち、butler2 では「一次証跡を読む」「補助ログを残す」「必要なら snapshot を作る」に責務を絞っている。
保存場所の探索は LLM / CLI 側に任せ、Butler は申告された path を読む。
session_log_path が与えられた場合はそれを最優先するsession_log を一次証跡として扱うsession_log は、AI セッションの会話・判断・メモを読み取り、必要に応じて repo 内 session_logs/ に補助記録する domain capability である。
初期段階では記録・抽出系を deterministic な non-LLM Maid として実装し、summarize のみ AI Maid を使う。
Phase 1 では、SuperLocalMemory への保存や抽出は行わない。
session_log = 一次証跡、時系列ログ、再開用の正本Phase 1 では次を実装対象とする。
session_log_path 経由の外部ログ読取り次は Phase 2 以降の検討事項とする。
session_log は単一 intent とし、payload.operation で動作を分岐する。
基本 contract:
intent: session_logtarget.service: localdelegation_mode: known_only| operation | 必須項目 | 内容 |
|---|---|---|
start_session |
client |
セッションを開始し、log file と index を確保する |
append_entry |
session_id, role, content |
セッションへ 1 エントリ追記する |
list_sessions |
なし | セッション一覧を返す |
get_session |
なし（session_id か client 推奨。省略時は全体最新） |
セッション全文または一部を返す |
mark |
なし | 前回 mark 以降の差分を返し、新しい mark を保存する |
summarize |
なし（session_id か client 推奨。省略時は全体最新） |
AI Maid で構造化スナップショットを生成する |
start_session必須:
client任意:
session_idtitletagsmetadatasession_id 省略時は Butler が生成する。
append_entry必須:
session_idrolecontent任意:
entry_typemetadataget_session任意:
session_log_pathsession_idclientlog_formatsince_linelimitsession_log_path がある場合は、それを最優先で読む。
session_id を省略した場合は、client に一致する最新 session を返す。
session_id と client を両方省略した場合は、全 session の中で最新のものを返す。
session_log_path 利用時は、client か log_format で parser を決める。
初期対応:
client=codex または log_format=codex_jsonlclient=claude_code または log_format=claude_code_jsonllog_format=role_content_jsonllog_format=plain_textcodex_jsonl の session_meta が複数ある場合は、最初に現れた payload.id を採用する。
通常ログでは先頭 1 件を想定しつつ、異常系や将来のフォーマット揺れでも session_id が途中で上書きされないようにする。
claude_code_jsonl では assistant content の text ブロックに加えて tool_use ブロックも読み取り対象とする。
tool_use はツール名と主要入力（例: file_path, path, pattern, command）を会話抽出へ反映し、
再開時に「どのツールで何を触ろうとしたか」を追えるようにする。
mark任意:
session_log_pathsession_idclientmarkerissue_idmax_charssession_log_path がある場合は、それを最優先で読む。
marker がなければ、issue_id がある場合は issue:<id>、
なければ default:<session_id> を使う。
summarize任意:
session_log_pathsession_idclientlog_formatsummarize は deterministic worker ではなく、Goose の Worker Instance に route する。
session_log_path がある場合はそれを最優先し、なければ session_id / client に基づいて既存 session_logs/*.jsonl から取得する。
出力は session_logs/*_snapshot.md へ保存する。
get_session / mark / summarize の外部ログ読取りは、同じ path 検証と parser 選択ロジックを共有する。
外部ソース対応を追加・変更する場合は、この共有読取層を更新し、operation ごとに別実装を増やさない。
repo-local の補助保存先として session_logs/ を使う。
session_logs/index.jsonsession_logs/marks.jsonsession_logs/<client>_<session_id>.jsonlsession_logs/ はローカル運用物として Git 管理対象外にする。
session_log は要約ではなく、記録内容そのものを evidence として返す。
外部ログを読む場合も、読んだ source path を evidence に残す。
最低限返すべき項目:
session_idlog_filemessage_countconversationmark ではさらに次を返す。
markerprevious_linemarked_linefrom_lineto_linetruncatedsummarize ではさらに次を返す。
source_filesnapshot_fileengine記録・抽出系の session_log は次の Maid として扱う。
kind: scriptprovider: local_scriptmodel: n/arole: session_log_opssession_log_path 優先で外部ログを読めるようにするsession_logs/ は補助ログとして扱うstart_session / append_entry / get_session / mark を成立させるsummarize を Goose の Worker Instance に委譲して構造化スナップショットを生成する