Skip to content

v0.1.4

Latest

Choose a tag to compare

@x0c x0c released this 20 Nov 08:06

0.1.4

Add best-effort session creation with cross-runtime fallback, harden cold-reader and late-binding supervision, fix superseded-turn settlement liveness, and add atomic pre-dispatch cancellation and queued message withdrawal.

Changes

  • Best-effort session start (agent_session_control.besteffort & session create): Omitting --runtime tries candidates in registry order (availability-gated, per-runtime backoff retries, cross-runtime fallback) and supports an optional --prompt first turn inside a bounded confirmation window, returning full attempts evidence or create_exhausted.
  • Superseded-turn settlement (SupervisorRunner.observation_changes): When observation["current_turn"] is False (a later user message has started a new turn) and no own follow-up message remains unrecorded, the superseded turn settles immediately without waiting on the later turn's live phase, screen hash, or trailing assistant-message shape. Mixed-attribution superseded turns settle as unknown (mixed_attribution) and outcome-less superseded turns settle as unknown (turn_superseded) instead of deadlocking downstream target queues.
  • Target-lock wait & admission hardening (admit, _wait_for_target, RunStore):
    • Late-bound sessions without an initial history_path accept newly learned native history paths while keeping cwd checks strict.
    • on_busy="reject" settles immediately with target_busy without transitioning through queued or queue_reason.
    • Pre-dispatch runs waiting behind a contended target: lock evaluate process_messages(None) so queued cancellations settle promptly.
    • Cold-opened HistoryObserver readers treat their initial materialization reset properly without false history_reset failures.
  • Atomic pre-dispatch cancellation (RunStore.cancel_queued & LocalController.interrupt): Cancelling a delivery="accepted", execution="queued" run atomically settles the run locally (delivery="rejected", execution="interrupted", error.code="cancelled") and prevents SupervisorRunner.dispatch() from starting it concurrently; active runs fall back to enqueuing interrupt with version-conflict retry.
  • Control message withdrawal (RunStore.withdraw_message): Allows withdrawing a still-queued follow-up/control message (state="withdrawn"), which no longer blocks run settlement.
  • CLI & Supervisor hardening: Enforced non-TTY JSON output contracts (including usage_error envelopes), actionable recovery hints on not_found/wait_timeout, canonical __main__ execution in supervisor, and updated codex/opencode runtime handling.

Install

uv venv
source .venv/bin/activate
VERSION=0.1.4
BASE=https://github.com/x0c/agent-session-control/releases/download/v${VERSION}
SESSKIT=https://github.com/x0c/sesskit/releases/download/v0.3.2/sesskit-0.3.2-py3-none-any.whl

python -m pip install "${BASE}/agent_session_control-${VERSION}-py3-none-any.whl"
# With native-history observation:
python -m pip install "${SESSKIT}" "${BASE}/agent_session_control-${VERSION}-py3-none-any.whl"

简体中文

新增带运行时回退的尽最大努力会话创建,加固冷启动历史读取与延迟绑定监管,修复被新回合接替运行的结清活性问题,并新增未派发运行的原子取消与排队控制消息撤回原语。

变更内容

  • 尽最大努力会话启动(agent_session_control.besteffort 与 session create):省略 --runtime 时按注册表顺序尝试候选运行时(可用性门控、单运行时退避重试、跨运行时回退),支持可选 --prompt 首回合与有限确认窗口,返回完整 attempts 尝试日志或 create_exhausted。
  • 已被后续回合接替的运行结清(SupervisorRunner.observation_changes):当 observation["current_turn"] 为 False(会话历史中已有后续用户消息开启新回合)且本运行没有尚未落盘的自身追问/回答消息时,不再受后续新回合的活跃相位、屏幕刷新或尾部消息类型阻塞,立即按该回合自身结果结清;混合归因的超期回合结清为 unknown(mixed_attribution),无明确结果的被接替回合结清为 unknown(turn_superseded),防止整条目标队列永久饿死。
  • 目标锁等待与准入加固(admit、_wait_for_target、RunStore):
    • 提交时尚未绑定 history_path 的会话在首回合学到真实路径时正常准入(cwd 校验仍严格)。
    • on_busy="reject" 在目标锁被占时直接拒收为 target_busy,不经过 queued 或写入 queue_reason。
    • 在等待被占用 target: 锁期间,未派发运行会在休眠前执行 process_messages(None),使排队的取消请求能及时生效。
    • 冷打开 HistoryObserver 的首次物化 reset 不再误判为 history_reset。
  • 未派发运行原子同步取消(RunStore.cancel_queued 与 LocalController.interrupt):对处于 delivery="accepted" 且 execution="queued" 的未派发运行,在存储事务内原子完成取消(delivery="rejected"、execution="interrupted"、error.code="cancelled"),同时防止 SupervisorRunner.dispatch() 并发下发;已开始派发或执行中的运行仍回退为带版本冲突重试的排队 interrupt。
  • 控制消息撤回(RunStore.withdraw_message):支持将尚未派发的 state="queued" 控制/追问消息撤回为 state="withdrawn",且 withdrawn 状态不再阻塞运行结清。
  • CLI 与监管进程加固:完善非 TTY JSON 输出契约(含 usage_error 信封)、not_found/wait_timeout 恢复提示、supervisor 模块规范化入口以及 codex/opencode 运行时适配。

安装方式

uv venv
source .venv/bin/activate
VERSION=0.1.4
BASE=https://github.com/x0c/agent-session-control/releases/download/v${VERSION}
SESSKIT=https://github.com/x0c/sesskit/releases/download/v0.3.2/sesskit-0.3.2-py3-none-any.whl

python -m pip install "${BASE}/agent_session_control-${VERSION}-py3-none-any.whl"
# 如需原生历史观测:
python -m pip install "${SESSKIT}" "${BASE}/agent_session_control-${VERSION}-py3-none-any.whl"