# CMDC — AI Quick Reference (llm.txt)
# Elixir Agent Kernel v0.2.1 | OTP gen_statem | Hex: {:cmdc, "~> 0.2"}
# Full reference: llms-full.txt | HexDocs: https://hexdocs.pm/cmdc
## Facade API — CMDC module
# Create agent session (returns {:ok, pid} | {:error, term})
{:ok, session} = CMDC.create_agent(
model: "anthropic:claude-sonnet-4-5", # required — "provider:model_id"
tools: [CMDC.Tool.ReadFile, CMDC.Tool.Shell], # optional — Tool modules
plugins: [CMDC.Plugin.Builtin.SecurityGuard], # optional — Plugin modules or {Module, opts}
system_prompt: "You are a coding assistant.", # optional — prepended after BasePrompt
working_dir: "/my/project", # optional — default "."
provider_opts: [api_key: "sk-..."], # optional — passed to req_llm
max_turns: 50, # optional — default 100
skills_dirs: ["./skills"], # optional — SKILL.md discovery paths
memory: ["AGENTS.md"], # optional — memory file paths
sandbox: nil, # optional — Sandbox module, nil = local OS
subagents: [], # optional — [SubAgent.t()]
max_tokens: nil, # optional — nil = provider default
user_data: %{tenant_id: "t-1"}, # optional — verbatim into ctx.user_data, SubAgent inherits
messages: [] # optional — [%CMDC.Message{}], inject prior history at boot
)
# Also accepts %CMDC.Options{} struct or blueprint:
{:ok, session} = CMDC.create_agent(blueprint: MyApp.CodingAgent)
CMDC.prompt(session, "Help me refactor this module")
# => %{queued: false} (false = immediate, true = queued while busy)
{:ok, reply} = CMDC.collect_reply(session, timeout: 60_000)
# => {:ok, "Here's the refactored code..."} | {:error, :timeout} | {:error, reason}
CMDC.stop(session) # graceful shutdown
CMDC.abort(session) # abort running task → idle
CMDC.abort(session, reason: :user_cancelled) # v0.2 RFC B6: 事件 {:agent_abort, :user_cancelled}
CMDC.abort(session, kill_tools: :all) # v0.2 RFC B6: brutal_kill 全部工具（含 immune）
CMDC.abort(session, kill_tools: :none) # v0.2 RFC B6: 不杀工具，让其自然完成
CMDC.abort(session, clear_queue: false) # v0.2 RFC B6: 保留 pending prompt 队列
# 事件保证：:agent_abort 100ms 内到达订阅方；
# 默认 clear_queue: true 时，每条被丢弃的 user prompt 发 {:prompt_dropped, text}；
# kill_tools 模式下，每杀一个工具发 {:tool_killed, %{name, call_id, reason}}。
CMDC.status(session)
# => %{
# state: :idle | :running | :streaming | :executing_tools,
# session_id: "...",
# model: "anthropic:claude-sonnet-4-5", # v0.2 RFC C8 — 当前 LLM 模型
# turns: 3, tool_calls: 7, total_tokens: 12_345,
# cost_usd: 0.0123, # v0.2 RFC B5
# token_usage: %CMDC.TokenUsage{ # v0.2 RFC B5 — struct
# prompt_tokens: 8_000, completion_tokens: 4_345, total_tokens: 12_345,
# cost_usd: 0.0123, cached_tokens: 1_200
# },
# uptime_ms: 4_321, timestamp_ms: 1_700_000_000_000,
# pending_tools: [%{name, call_id, args, started_at_ms}, ...], # v0.2 RFC C11 + v0.3 RFC 11G #A15
# pending_approvals: [%{id, tool, args, requested_at, ...}], # v0.2 RFC C11 — 等审批工具
# queues: %{prompt_queue: 0, steering_queue: 0} # v0.2 RFC C11 — 内部队列长度
# }
CMDC.messages(session) # v0.2 — [%CMDC.Message{}] 完整对话历史
# 运行期切换 LLM 模型（v0.2 RFC C8 + v0.3 RFC 11G #A17）— 不重启 Agent，messages/tools/plugin 全保留
CMDC.switch_model(session, "openai:gpt-4o-mini")
# - idle: 立即生效，下次 prompt 用新 model
# - running/streaming/executing_tools: 当前轮跑完再切，下一轮用新 model
# - 同 model + 无 provider_opts: no-op，不发事件
# - 事件: {:model_switched, %{from: old, to: new, provider_opts_changed?: false}}
# - Plugin Action 等价: {:switch_model, "openai:gpt-4o-mini", state}
# 多个 plugin 同时 switch_model，priority 最大者（后执行）的值生效
# 同时切 provider 参数（v0.3 RFC 11G #A17 — 多 provider 容灾）
CMDC.switch_model(session, "openai:gpt-4o-mini",
provider_opts: [base_url: "https://api.fallback.com/v1", api_key: "sk-...", timeout_ms: 90_000]
)
# - 事件: {:model_switched, %{..., provider_opts_changed?: true}}
# - state.config.provider_opts 立即被替换
# - Plugin Action 4 元组形态: {:switch_model, "openai:gpt-4o-mini", state, provider_opts: [...]}
# 运行期挂载/卸载工具（v0.2 RFC C9）— 不重启 Agent，下次 LLM 请求生效
:ok = CMDC.attach_tool(session, MyApp.Tools.GitHubMCP)
# {:error, :already_attached} | {:error, :invalid_tool}
# 事件: {:tool_attached, name}
:ok = CMDC.detach_tool(session, "shell")
# {:error, :not_found}
# 事件: {:tool_detached, name}
# 注意: 已 in-flight 的 tool 调用继续跑完，不被取消;
# 若 LLM 在 detach 后仍调用该 tool，emit {:tool_call_unknown, name, call_id}
# 并自动注入 error tool_result 让 LLM 自我纠正
# EventBus ring buffer 与重连补帧（v0.2 RFC C10）— 默认关闭
{:ok, session} = CMDC.create_agent(model: "...", event_buffer_size: 100)
# 启动时设置 event_buffer_size > 0 开启 per-session 缓存（典型 50-200）
# 默认 0：关闭，无任何内存开销，行为同 v0.1
# 断线重连补帧
{:ok, _} = CMDC.subscribe(session, since: last_seen_index)
# replay last_seen_index < idx <= now 之间的所有事件
# 早于 buffer 起点的部分已被 FIFO 丢弃（无法 replay）
# 工具 API
last_idx = CMDC.EventBus.last_index(session_id) # 获取当前最新 index
size = CMDC.EventBus.buffer_size(session_id) # 当前缓存事件数
# 结构化崩溃监控（v0.2 RFC C12）— 替代 Process.monitor，拿到结构化 reason
ref = CMDC.monitor(session) # 接受 pid | session_id string
# Agent 退出时当前进程收到:
# {:cmdc_down, ref, session_id, structured_reason}
# structured_reason:
# :normal | :shutdown | {:shutdown, _} → 归一为 :normal
# %RuntimeError{} | {%RuntimeError{}, stacktrace} → {:exception, exception}
# :max_turns_exceeded | :provider_timeout | {:plugin_aborted, name, why} (v0.2+ 预留)
# 其他 → 原样透传
CMDC.demonitor(session, ref) # 取消监控
# PromptMode — SubAgent / 长会话 system prompt 降本（v0.2 Phase 10B）
{:ok, session} = CMDC.create_agent(model: "...", prompt_mode: :full)
# 可选：:full（默认，主 Agent）| :task（SubAgent 默认，省 ~50%）
# :minimal（仅工具名列表，省 ~90%）| :none（完全由 system_prompt 接管）
#
# SubAgent 默认 :task，Tool.Task 派发时自动透传
CMDC.SubAgent.new!(name: "router", prompt_mode: :minimal) # 快速分类子代理
# 四模式注入矩阵（true/-）
# mode user_sp | BasePrompt | Identity | tools列表 | Skills | Memory
# :full ✓ | 完整基座 | ✓ | name+desc | ✓ | ✓
# :task ✓ | 精简(~150字节)| ✓ | name+desc | - | -
# :minimal ✓ | - | ✓ | 仅 name (no desc) | - | -
# :none ✓ | - | - | - | - | -
# MemoryFlush — 压缩前提取关键事实，持久化到 MEMORY.md（v0.2 Phase 10C）
{:ok, session} = CMDC.create_agent(
model: "...",
plugins: [
CMDC.Plugin.Builtin.MemoryLoader, # session_start 加载 MEMORY.md / AGENTS.md
CMDC.Plugin.Builtin.MemoryFlush # :before_compact 写入 MEMORY.md
],
working_dir: "/project/path"
)
# 长会话 → 自动 compact → MemoryFlush 写 working_dir/MEMORY.md → 下次会话 MemoryLoader 读回
# 可覆盖 extract_fn 用真实 LLM 提取；默认启发式规则（纯离线，便于单测）
#
# RFC D14 — MemoryFlush emit :plugin_event 统一事件（便于集成方订阅入库）
CMDC.subscribe(session)
# 收到 {:cmdc_event, sid, {:plugin_event, %{kind: :memory_flush, facts, count,
# session_id, occurred_at, file, v: 1}}}
# ModelRouter — 按业务规则在 before_request 切换模型（v0.2 Phase 10D）
{:ok, session} = CMDC.create_agent(
model: "anthropic:claude-sonnet-4-5",
user_data: %{user_tier: :free, task_complexity: :complex, token_budget: 100_000},
plugins: [
{CMDC.Plugin.Builtin.ModelRouter,
default_model: "anthropic:claude-sonnet-4-5",
rules: [
# v0.1 三条（运行时）
%{condition: {:turn_gt, 20}, model: "openai:gpt-4.1-mini"},
%{condition: {:cost_gt, 0.5}, model: "openai:gpt-4.1-mini"},
%{condition: {:tokens_gt, 50_000}, model: "openai:gpt-4.1-mini"},
# v0.2 四条新条件（业务层面）
%{condition: {:token_budget_lt, 5_000}, model: "openai:gpt-4.1-mini"},
%{condition: {:task_complexity, :complex}, model: "anthropic:claude-opus-4"},
%{condition: {:task_complexity_in, [:simple]}, model: "openai:gpt-4.1-mini"},
%{condition: {:time_of_day_in, [22..23, 0..6]}, model: "openai:gpt-4.1-mini"},
%{condition: {:user_tier, :free}, model: "openai:gpt-4.1-mini"},
%{condition: {:user_tier_in, [:enterprise]}, model: "anthropic:claude-opus-4"},
%{condition: {:user_data, :region, "eu-west"}, model: "mistral:mistral-large"},
%{condition: {:user_data, :priority, :gt, 5}, model: "anthropic:claude-opus-4"}
]
}
]
)
# 命中首条规则 → emit {:switch_model, new_model, state} action，下一次 LLM
# 请求用新模型，EventBus 广播 :model_switched（from/to/reason=:model_router）
CMDC.subscribe(session) # receive {:cmdc_event, session_id, event_tuple}
CMDC.unsubscribe(session)
CMDC.approve(session, approval_id) # HITL approve, auto_resume: true (default)
CMDC.approve(session, approval_id, auto_resume: false) # 旧版：只放行不续 turn
CMDC.reject(session, approval_id) # HITL reject, auto_resume: false (default)
CMDC.reject(session, approval_id, auto_resume: true) # 拒绝后立即续 turn 让 LLM 改方案
CMDC.user_respond(session, ref, response) # 应答 AskUser 工具（与 approve/reject 对称）
# session 入参类型 — v0.2 起所有 API 同时接受 pid 与 session_id 字符串
# @type session :: pid() | String.t()
# 字符串通过 CMDC.SessionRegistry（:via 注册）反查 pid；不存在 raise ArgumentError
CMDC.prompt("my-sid", "hello") # ✓ string 入参直接工作
CMDC.status("my-sid") # ✓ 反查 pid 后调用
CMDC.subscribe("not-yet-started") # ✓ 提前订阅合理场景，不 raise
CMDC.user_respond("my-sid", ref, "ans") # ✓ 直接 broadcast，不查注册表
SessionServer.whereis("my-sid") # => pid | nil（不抛异常）
# Steering — mid-execution soft interrupt (do NOT abort + re-prompt; use this)
{:ok, ref} = CMDC.steer(session, "改方向：只看官方文档")
# => {:ok, reference()} # queued; effect signaled by :steering_applied event
# => {:error, :queue_full} # steering_queue 满（默认 max=3）
# => {:error, :rejected} # plugin abort before_steering
# => {:error, :invalid_text} # 入参非合法字符串
# 状态行为：
# idle → 等同 prompt/2，立刻进入新 turn（仅 emit :steering_applied）
# running/streaming → 入 queue，下个 turn 间隙合并注入
# executing_tools → 入 queue，下次 collect_result 时杀掉非 immune 工具，全清空后注入
## Options — CMDC.Options
opts = CMDC.Options.new!(model: "openai:gpt-4o", tools: [CMDC.Tool.Shell])
# @enforce_keys [:model]
# Fields: model, tools, system_prompt, plugins, subagents, skills_dirs,
# memory, sandbox, response_format, provider_opts, max_turns,
# max_tokens, working_dir, max_steering_queue, interrupt_immune_tools,
# user_data, messages
# user_data: arbitrary map() (or keyword, normalized to map) → ctx.user_data
# SubAgent inherits unless its own :user_data is non-nil (then full replace).
# messages: [%CMDC.Message{}] — prior conversation history, injected directly into
# state.messages at Agent boot. Skips one full LLM "re-read" round-trip
# for idle-resume / cross-process restore. Default []. system_prompt is
# still composed by SystemPrompt independently — do NOT put :system in here.
CMDC.Options.new(keyword) # => {:ok, t} | {:error, ValidationError}
CMDC.Options.merge(opts, overrides_keyword) # => new Options
## Events — CMDC.Event (broadcast as {:cmdc_event, session_id, event})
# Lifecycle: :agent_start | {:agent_end, messages, %CMDC.TokenUsage{}} | {:agent_abort, reason} | :agent_abort
# ↑ v0.2 RFC B5: token_usage is now a struct with prompt/completion/total_tokens + cost_usd + cached_tokens
# v0.1.x compat: still a map; pattern-match on Map.get/2 if you need to support both
# Prompt: {:prompt_received, text} | {:prompt_queued, text} | {:prompt_rejected, reason}
# Stream: :message_start | {:message_delta, %{delta: text}} | {:response_complete, %Message{}}
# :thinking_start | {:thinking_delta, %{delta: text}}
# {:status_update, text} | {:title_generated, title}
# Request: {:request_start, %{model: m, messages: n}} | {:stream_error, reason}
# {:stream_stalled, elapsed_s} | {:retry, attempt, delay_ms, reason} | {:context_overflow, r}
# Tool: {:tool_calls, count}
# {:tool_execution_start, name, call_id, args}
# {:tool_execution_end, name, call_id, {:ok, text}|{:error, text}}
# {:tool_execution_metrics, name, call_id, %{started_at_ms[, ended_at_ms, duration_ms]}}
# # v0.3 RFC 11G #A15
# # start 时只含 started_at_ms,
# # end 时含完整 3 字段
# {:tool_blocked, name, call_id, reason} | {:loop_detected, %{type: atom()}}
# HITL: {:approval_required, approval_map} | {:approval_resolved, approval_map}
# approval_map: %{id, tool, args, session_id, hint, requested_at, status(resolved only)}
# {:agent_resumed, %{trigger: :tool_approved|:tool_rejected|:tool_approval_timeout, approval_id}}
# ↑ broadcast when approve/reject auto_resume kicks in (Agent was idle → re-enters running)
# Ask: {:ask_user, sid, question, options, ref} | {:user_responded, sid, ref, response}
# Plan: {:todo_change, sid, todos}
# Compact: {:compact_start, sid} | {:compact_end, sid, removed_count}
# SubAgent: {:subagent_start, sid, child_sid, desc} | {:subagent_end, sid, child_sid, result}
# {:sub_agent_event, call_id, child_sid, event}
# Plugin: {:plugin_event, name, payload}
# Steering: {:steering_received, %{ref, text, queued_at, status: :queued|:rejected_full|:rejected_by_plugin}}
# {:steering_applied, %{refs: [ref], count: pos_integer()}}
# {:tool_skipped_for_steering, %{name, call_id, reason: :killed_by_steering | :pending_dispatch}}
# Other: {:intervention, prompt} | {:stop_blocked, prompt} | {:error, sid, reason}
## EventBus — CMDC.EventBus
EventBus.subscribe(session_id) # => {:ok, pid}
EventBus.subscribe_all() # all sessions
EventBus.broadcast(session_id, event)
EventBus.unsubscribe(session_id)
## TokenUsage — CMDC.TokenUsage (v0.2 RFC B5, @derive Jason.Encoder)
# %CMDC.TokenUsage{
# prompt_tokens: non_neg_integer(), # OpenAI input / Anthropic input_tokens
# completion_tokens: non_neg_integer(), # OpenAI output / Anthropic output_tokens
# total_tokens: non_neg_integer(), # 多数 Provider 自带，缺失时 prompt+completion 补齐
# cost_usd: float() | nil, # Provider 配定价时计算；否则 nil
# cached_tokens: non_neg_integer() | nil # Anthropic cache_read_input_tokens
# }
#
TokenUsage.new(prompt_tokens: 100, completion_tokens: 50)
# %CMDC.TokenUsage{prompt_tokens: 100, completion_tokens: 50, total_tokens: 150, ...}
TokenUsage.from_raw(%{input_tokens: 80, output_tokens: 40}) # Anthropic 风格
TokenUsage.from_raw(%{prompt_token_count: 200, candidates_token_count: 100}) # Google
TokenUsage.add(usage_a, usage_b) # 多 Provider 累加
# 内部 State.token_usage 仍是扩展 map（含 :context_window / :current_context_tokens 等
# 上下文窗口元数据，不进 struct）；事件 / status 边界用 from_state_token_map/3 转 struct。
## Message — CMDC.Message (@derive Jason.Encoder)
Message.system("You are helpful.")
Message.user("Hello")
Message.assistant("Hi!", [%{call_id: "c1", name: "read_file", arguments: %{"path" => "a.ex"}}])
Message.tool_result("c1", "file contents...", false) # call_id, output, is_error
# Fields: id, parent_id, role (:system|:user|:assistant|:tool_result),
# content, thinking, tool_calls, call_id, name, is_error, metadata
## Context — CMDC.Context (passed to Tool.execute/2 and Plugin.handle_event/3)
# @enforce_keys [:session_id, :working_dir, :model]
# Fields: session_id, working_dir, model, sandbox, tools, subagents,
# config, todos, memory_contents, user_data, turn, total_tokens, cost_usd,
# last_assistant_reply # v0.3 — 最后一条 assistant message 的文本，Plugin/Tool 直接读取无需翻 messages
#
# user_data — arbitrary business context map injected from Options.user_data;
# use directly in pattern match: execute(args, %Context{user_data: %{tenant_id: t}})
## Plan — CMDC.Plan (v0.3 ADP Ch6, @derive Jason.Encoder)
# Plan struct 字段：
# goal :: String.t()
# steps :: [%CMDC.Plan.Step{}]
# status :: :draft | :approved | :in_progress | :completed
# created_at, approved_at, metadata :: map()
#
# Step struct 字段：
# id :: String.t() # "step-1", "step-2" ...
# description :: String.t()
# status :: :pending | :in_progress | :completed | :failed | :skipped
# started_at, finished_at, result, notes
#
# 创建/解析
CMDC.Plan.new(goal, step_descriptions) # => %Plan{status: :draft}
CMDC.Plan.from_markdown(markdown, goal) # 解析 "- [ ] ..." checklist
# 状态迁移（railway：{:ok, plan} | {:error, :not_found}）
CMDC.Plan.step_started(plan, step_id)
CMDC.Plan.step_completed(plan, step_id, result)
CMDC.Plan.step_failed(plan, step_id, reason)
CMDC.Plan.step_skipped(plan, step_id, reason)
CMDC.Plan.annotate_step(plan, step_id, notes)
CMDC.Plan.approve(plan) # status → :approved
# Replan（ADP Ch6 动态调整）
CMDC.Plan.replace_steps(plan, ["new1", "new2"]) # 全量重规划，重新编号 step-1…
CMDC.Plan.add_step(plan, "追加的步骤") # 末尾 append，自动 step-N+1
CMDC.Plan.insert_step(plan, "step-2", "新步骤") # 默认在 step-2 之后；opts before: true 在之前
CMDC.Plan.remove_step(plan, "step-3")
# 查询/渲染
CMDC.Plan.get_step(plan, step_id)
CMDC.Plan.current_step(plan) # 第一个 :pending / :in_progress 步骤
CMDC.Plan.progress(plan) # %{total, completed, failed, skipped, pending, in_progress, pct}
CMDC.Plan.all_finished?(plan) / all_completed?(plan)
CMDC.Plan.to_markdown(plan) # "## Goal\n...\n- [x] step-1 ..."
CMDC.Plan.to_prompt_section(plan) # "# Plan\n...\n# Progress\n..." 注入 system prompt
## Built-in Tools (11)
# All tools implement @behaviour CMDC.Tool
# Callbacks: name/0, description/0, parameters/0, execute/2
# Result: {:ok, String.t()} | {:error, String.t()} | {:effect, term()}
CMDC.Tool.ReadFile # read_file — path (req), offset, limit
CMDC.Tool.WriteFile # write_file — path (req), content (req)
CMDC.Tool.EditFile # edit_file — path (req), old_string (req), new_string (req)
CMDC.Tool.Shell # shell — command (req), timeout
CMDC.Tool.Grep # grep — pattern (req), path, include, context_lines, max_results
CMDC.Tool.ListDir # list_dir — path
CMDC.Tool.Glob # glob — pattern (req), path
CMDC.Tool.Task # task — description (req), subagent_type
CMDC.Tool.WriteTodos # write_todos — todos (req) [%{id, content, status}]
CMDC.Tool.AskUser # ask_user — question (req), options
CMDC.Tool.CompactConversation # compact_conversation — reason
## Built-in Plugins (8)
# All plugins implement @behaviour CMDC.Plugin
# Callbacks: init/1, priority/0, handle_event/3
# Actions (8): {:continue, state} | {:intervene, prompt, state} | {:abort, reason, state}
# {:skip, state} | {:block_tool, reason, state}
# {:replace_tool_args, new_args, state} | {:emit, {type, data}, state}
# {:switch_model, model_string, state} # v0.2 RFC C8
# {:switch_model, model_string, state, provider_opts: [...]} # v0.3 RFC 11G #A17
CMDC.Plugin.Builtin.SecurityGuard # priority 10 — blocks dangerous paths/commands
CMDC.Plugin.Builtin.EventLogger # priority 50 — JSON Lines audit log
CMDC.Plugin.Builtin.HumanApproval # priority 15 — HITL before_tool approval
CMDC.Plugin.Builtin.MemoryLoader # priority 100 — loads AGENTS.md into system prompt
CMDC.Plugin.Builtin.PatchToolCalls # priority 120 — patches dangling tool_calls
CMDC.Plugin.Builtin.PromptCache # priority 130 — Anthropic prompt caching
CMDC.Plugin.Builtin.Planning # priority 200 — v0.3 ADP Ch6: plan_first + dynamic plan injection
CMDC.Plugin.Builtin.Reflection # priority 400 — v0.3 ADP Ch4+Ch7: Producer-Reviewer 自评/SubAgent
# --- v0.3 Planning plugin ---
# {CMDC.Plugin.Builtin.Planning,
# plan_first: true, # default true — 在长 prompt 上先出 plan
# min_prompt_length: 20, # 默认 20 字符以下不触发规划
# max_plan_attempts: 2 # 解析失败兜底重试次数
# }
# Emits: {:plugin_event, :plan_generated, %CMDC.Plan{}}
# Side-effect: emit {:update_system_context, :plan, Plan.to_prompt_section(plan)}
# → Agent.state.dynamic_context_sections[:plan] 更新，下一轮 system prompt 自动携带
#
# --- v0.3 Reflection plugin（修 iteration-reset bug + Producer-Reviewer）---
# {CMDC.Plugin.Builtin.Reflection,
# reviewer_prompt: "You are a strict quality reviewer...", # 评审员人设
# reviewer_model: "qwen3-max", # 可选，SubAgent 模式下用不同模型
# reviewer_subagent: true, # true = 启独立 SubAgent (ADP 推荐)
# criteria: ["准确性", "完整性", "可读性"],
# max_reviews: 3, # 最大 review 轮数（max_iterations 别名仍兼容）
# pass_signal: "APPROVED" # 字符串或 %Regex{}，通过信号
# }
# 状态机：:idle ─before_finish→ :reviewing ─after_response(pass)→ :done
# │
# └─max_reviews 达到──→ :done（强制通过）
# Emits: {:plugin_event, :reflection_approved, %{critique, iteration}}
## Plugin Events (13 hooks)
# :session_start | :session_end | {:after_turn, payload} # v0.3 RFC 11G #A16
# {:before_prompt, text} | {:before_request, messages} | {:after_response, message}
# {:before_tool, name, args}
# {:on_tool_error, name, call_id, error, attempt} — tool failed, before retry
# {:after_tool, name, call_id, result} | {:after_tool_batch, results}
# :before_finish | {:before_compact, messages}
# {:before_steering, text} — CMDC.steer/2 触发；continue/intervene/abort/emit
# {:after_turn, payload} payload 字段（v0.3 RFC 11G #A16）：
# outcome :: :finished | :aborted
# abort_reason :: term() | nil
# messages_diff :: [%CMDC.Message{}] — 本轮 prompt cycle 新增的消息（按时间序）
# token_usage_diff :: %CMDC.TokenUsage{} — 本轮增量
# started_at_ms / ended_at_ms / duration_ms
# 与 :session_end 的区别：:session_end 无 payload，保持向后兼容；新 Plugin 建议用 :after_turn
## Dynamic System Prompt Injection (v0.3)
# Plugin 可以通过 emit 事件把文本动态注入下一轮 system prompt：
# {:emit, {:update_system_context, key, text}, state} # 注入 text
# {:emit, {:update_system_context, key, nil}, state} # 删除 key
# 对应 state field：CMDC.Agent.State.dynamic_context_sections :: %{atom() => String.t()}
# SystemPrompt 在 :full / :task / :minimal 三种模式下都会把这些段落拼进去
# （按 key 字典序；排在 BasePrompt + 用户 system_prompt + Blueprint + Skills + Memory 之后）
#
# 典型使用者：CMDC.Plugin.Builtin.Planning 每次生成/更新 plan 都 emit {:update_system_context, :plan, ...}
## Plugin Hook × Action 完整矩阵 + 5 个 Cookbook（v0.2 RFC B7）
# 详见 docs/dev/plugin-cookbook.md
# Hook \ Action | continue | intervene | abort | skip | block_tool | replace_tool_args | emit | switch_model
# :session_start | ✓ | - | ✓ | - | - | - | ✓ | -
# :session_end | ✓ | - | - | - | - | - | ✓ | -
# {:after_turn, p} | ✓ | - | - | - | - | - | ✓ | -
# :before_prompt | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | -
# :before_request | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓
# :after_response | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓
# :before_tool | ✓ | - | ✓ | - | ✓ | ✓ | ✓ | ✓
# :on_tool_error | ✓ | - | ✓ | ✓ | - | - | ✓ | -*
# :after_tool | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓
# :after_tool_batch | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓
# :before_finish | ✓ | ✓ | ✓ | - | - | - | ✓ | -
# :before_compact | ✓ | - | - | ✓ | - | - | ✓ | -
# :before_steering | ✓ | ✓ | ✓ | - | - | - | ✓ | -
# *: :on_tool_error 在 Task 内 retry 循环触发，无 Agent state 上下文，switch_model 被忽略；
# 若需基于工具失败切 model，请在 :after_tool 钩子内基于 result 是 {:error, _} 决定。
#
# 13 hooks × 8 actions 完整矩阵 + emit 形态详解 + 累积/覆盖语义见
# `CMDC.Plugin` 模块 @moduledoc（v0.3 RFC 11G #D27），及 docs/dev/plugin-cookbook.md。
#
# 5 Cookbook 场景：
# 1. DangerousCommandGuard — :before_tool + block_tool 拦截 rm -rf
# 2. PromptAuditLog — :before_prompt + emit 审计所有 user prompt
# 3. BudgetGuard — :after_response + abort 控制成本上限
# 4. ToolFallbackGuard — :on_tool_error + emit 工具降级触发
# 5. SteeringContentGuard — :before_steering + abort 拦截 prompt injection
## Tool Retry (via state.config)
# :tool_max_retries — max retry attempts on tool failure (default 0 = no retry)
# :tool_retry_delay_ms — delay between retries in ms (default 500)
# on_tool_error plugin hook: {:continue, state} = retry, {:abort, _, state} or {:skip, state} = give up
## Blueprint — CMDC.Blueprint
# @callback build(keyword()) :: CMDC.Options.t()
defmodule MyAgent do
use CMDC.Blueprint
@impl true
def build(opts) do
%CMDC.Options{
model: opts[:model] || "anthropic:claude-sonnet-4-5",
tools: [CMDC.Tool.ReadFile, CMDC.Tool.Shell],
system_prompt: "Expert Elixir developer."
}
end
end
{:ok, s} = CMDC.create_agent(blueprint: MyAgent, provider_opts: [api_key: "sk-..."])
## Blueprint.Base — built-in base blueprint (SecurityGuard + EventLogger + PatchToolCalls)
opts = CMDC.Blueprint.Base.build(model: "anthropic:claude-sonnet-4-5", tools: [...])
## SubAgent — CMDC.SubAgent
sa = CMDC.SubAgent.new!(name: "coder", model: "anthropic:claude-opus-4-5",
tools: [CMDC.Tool.ReadFile, CMDC.Tool.EditFile])
# @enforce_keys [:name]
# Fields: name, description, system_prompt, model, tools, plugins, skills_dirs
# nil = inherit from parent agent
## Skill — CMDC.Skill
skills = CMDC.Skill.discover(["./skills"]) # => [%Skill{}]
{:ok, loaded} = CMDC.Skill.load(skill) # reads SKILL.md content
CMDC.Skill.to_prompt_snippet(skills) # => prompt section string
## Sandbox — CMDC.Sandbox (behaviour)
# @callback read_file(path, opts) :: {:ok, String.t()} | {:error, String.t()}
# @callback write_file(path, content, opts) :: :ok | {:error, String.t()}
# @callback edit_file(path, old_str, new_str, opts) :: {:ok, count} | {:error, reason}
# @callback list_dir(path, opts) :: {:ok, [dir_entry]} | {:error, String.t()}
# @callback file_exists?(path, opts) :: boolean()
# @callback grep(pattern, path, opts) :: {:ok, [grep_match]} | {:error, String.t()}
# @callback glob(pattern, path, opts) :: {:ok, [glob_match]} | {:error, String.t()}
# @callback execute(command, opts) :: {:ok, String.t()} | {:error, String.t()}
# Default: CMDC.Sandbox.Local (direct OS execution)
## Provider — CMDC.Provider (req_llm wrapper)
Provider.stream(model, messages, tools, opts) # => {:ok, %{bridge_pid: pid}}
Provider.convert_messages(messages) # => [ReqLLM.Message.t()]
Provider.convert_tools(tool_modules) # => [map()]
## Config — CMDC.Config
config = CMDC.Config.new!(provider_opts: [api_key: "sk-..."])
# Fields: data_dir, default_model, default_tools, provider, provider_opts, providers
## Agent Internals (L2 — usually not called directly)
Agent.prompt(agent_pid, text) # direct gen_statem call
Agent.status(agent_pid) # => %{state: :idle|:running|:streaming|:executing_tools, ...}
Agent.get_state(agent_pid) # => State.t()
# States: :idle → :running → :streaming → :executing_tools → :idle (loop)
## Compactor — CMDC.Agent.Compactor
# Auto-triggers when context exceeds token threshold
# Compactor.maybe_compact(state) => {:compacted, state} | {:skip, state}
# Compactor.force_compact(state) => {:compacted, state} | {:skip, state}
# ArgTruncator: auto-truncates large write_file/edit_file/execute args
## MCP Integration
# Discover MCP servers from mcp.json:
servers = CMDC.MCP.Config.discover(working_dir)
modules = CMDC.MCP.Bridge.discover_tool_modules(servers)
# MCP tools are dynamically wrapped as CMDC.Tool modules
## Session Lifecycle
# CMDC.create_agent → SessionServer.start_link → Supervisor tree:
# SessionServer (Supervisor)
# ├── Agent (gen_statem)
# └── SubAgent.Supervisor (DynamicSupervisor)
# └── child Agent processes (isolated, :temporary)
## Key Patterns
# Streaming events:
CMDC.subscribe(session)
CMDC.prompt(session, "hello")
receive do
{:cmdc_event, sid, {:message_delta, %{delta: chunk}}} -> IO.write(chunk)
{:cmdc_event, _sid, {:agent_end, _msgs, _usage}} -> :done
end
# HITL approval flow (auto-resumes by default — no sleep + re-prompt hack needed):
receive do
{:cmdc_event, _sid, {:approval_required, %{id: ref, tool: tool, args: args}}} ->
:ok = CMDC.approve(session, ref)
end
# 上层若需等待 Agent 重新跑起来再做下一步：
receive do
{:cmdc_event, _sid, {:agent_resumed, %{approval_id: ^ref}}} -> :resumed
end
# 关闭自动续 turn（保留旧 v0.1 行为，需要自己 prompt 续接）：
:ok = CMDC.approve(session, ref, auto_resume: false)
:ok = CMDC.prompt(session, "继续刚才被拦截的操作")
# Steering flow (mid-execution direction change):
CMDC.subscribe(session)
CMDC.prompt(session, "搜索 Elixir gen_statem 教程")
# 一段时间后改变主意，无需 abort，直接追加新指引
{:ok, _ref} = CMDC.steer(session, "改成只看官方 hexdocs，不要第三方教程")
receive do
{:cmdc_event, _sid, {:steering_applied, %{count: n}}} ->
IO.puts("已注入 #{n} 条 steering 指引，agent 重新规划中")
end
# Business context passthrough (multi-tenant / operator id / data scope):
{:ok, session} = CMDC.create_agent(
model: "anthropic:claude-sonnet-4-5",
tools: [MyApp.Tools.FetchOrders],
user_data: %{tenant_id: "acme-1", operator_id: "u-9", data_scope: :restricted}
)
defmodule MyApp.Tools.FetchOrders do
@behaviour CMDC.Tool
def execute(_args, %CMDC.Context{user_data: %{tenant_id: t, data_scope: scope}}) do
rows = Repo.all(from o in Order, where: o.tenant_id == ^t and o.scope == ^scope)
{:ok, Jason.encode!(rows)}
end
end
# SubAgent inherits parent user_data; SubAgent.new!(name: "x", user_data: %{tenant_id: "other"})
# fully replaces (does NOT merge).
# Restore prior conversation history (idle resume / cross-process restore):
history = [
CMDC.Message.user("帮我审核这段代码"),
CMDC.Message.assistant("好的，请贴上来", [], []),
CMDC.Message.user("def hello, do: :world")
]
{:ok, session} = CMDC.create_agent(
model: "anthropic:claude-sonnet-4-5",
system_prompt: "你是一名严谨的 Elixir 审计员。",
messages: history # ← 直接进 state.messages，下次 prompt 自然续接
)
CMDC.prompt(session, "继续：这段代码的复杂度如何？")
# LLM 看到的 messages: [system, user, assistant, user, user] —— 不需要让 LLM 重读 history
# system_prompt 由 SystemPrompt.build/1 拼接，messages 列表里**不要**再放 :system 消息
## Steering Options (CMDC.Options)
# :max_steering_queue — Steering queue 最大长度（默认 3，溢出 → :queue_full）
# :interrupt_immune_tools — Steering 触发时不会被 brutal_kill 的 tool 名白名单
# 默认 ~w(write_file edit_file shell git_commit notebook_edit ask_user)