Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
import asyncio
import logging
import os
import uuid
from copy import copy
from dataclasses import dataclass, field, replace
from typing import Any, Callable, Literal, Optional
from core.agent_auth_service import classify_auth_error
from core.agent_tool_policy import runs_in_background as tool_runs_in_background
from core.backend_failure import backend_failure_notification_output, emit_backend_failure
from core.handlers.session_handler import (
ClaudeBackendDisabledError,
ClaudeInputNotSentError,
ClaudeSessionNotFoundError,
)
from core.agent_output import (
DeliveryReceipt,
Narration,
Notice,
Reply,
ToolActivity,
TurnEnd,
TurnOutcome,
emit_output,
)
from core.message_dispatcher import ActivityOutputDeliveryError
from core.message_output import (
HARNESS_RUN_ID_TRIGGER_KINDS,
MessageOutput,
terminal_output_for,
terminal_turn_output,
)
from core.native_dispatch_phase import mark_backend_dispatch_attempted, mark_prewrite_recovery_required
from core.processing_indicator import STOPPED_REACTION_EMOJI
from core.reply_enhancer import strip_silent_blocks
from core.resource_governance import pids_failure_labels
from core.run_settlement import SETTLED_BY_TURN_ONLY_RESULT
from core.runtime_activation import RuntimeActivationIdentity, RuntimeActivationRegistry
from core.runtime_work import RuntimeWorkLane
from core.services.agent_steering import (
ActiveSteerTarget,
SteerOutcome,
SteerRequest,
SteerResult,
result as steer_result,
)
from core.session_activities import SessionActivity, activity_completion_output
from modules.claude_sdk_compat import TextBlock, ToolUseBlock, is_claude_sdk_buffer_error
from modules.agents.claude_process_reaper import (
AVIBE_CLAUDE_SESSION_OWNER,
claude_diagnostic_without_stderr,
claude_process_exit_reason_i18n,
claude_process_exit_signal,
get_claude_client_returncode,
register_claude_owned_process,
)
from modules.agents.catalog import display_name_for_backend
from vibe.i18n import t as i18n_t
from modules.agents.base import (
AGENT_RUNTIME_TURN_KEY,
AGENT_RUNTIME_TURN_TOKEN,
AGENT_TURN_TOKEN,
AgentRequest,
BaseAgent,
message_with_files,
)
# NOTE: AskUserQuestion support is disabled because Claude Code SDK cannot
# respond to it programmatically. See: https://github.com/anthropics/claude-code/issues/10168
# Keeping the import for future use when SDK adds support.
# from modules.agents.claude_question_handler import ClaudeQuestionHandler
from modules.im import MessageContext
logger = logging.getLogger(__name__)
# Position of a native steer receipt inside buffered Assistant frames. The
# frames on both sides share one terminal Result, which decides whether the
# boundary closes a human primary phase or is ignored with detached output.
_STEER_BOUNDARY = object()
@dataclass
class _ClaudeInputReceipt:
text: str
kind: Literal["primary", "steer"]
state: Literal["writing", "accepted", "unknown"] = "writing"
@dataclass(frozen=True)
class _BufferedClaudeFailureReplay:
diagnostic: str
auth_handled: bool = False
replay_failed: bool = False
@dataclass
class _ClaudeOutputRecoveryRecord:
"""One immutable phase/output owner retained across receiver generations."""
phase_id: str
composite_key: str
generation: object | None
owner: Literal["activity", "detached"]
lifecycle: Literal["provisional", "delivery_pending", "delivered"] = "provisional"
text: str = ""
activities: list[SessionActivity] = field(default_factory=list)
output: MessageOutput | None = None
request: AgentRequest | None = None
context: MessageContext | None = None
subtype: str = "success"
is_error: bool = False
duration_ms: int = 0
delivering: bool = False
provenance: str | None = None
local_settlement_only: bool = False
claim_pending: bool = False
claim_metadata: dict[str, object] | None = None
# Read live on every use, so changing them needs no new client.
_CLAUDE_LIVE_CONFIG_FIELDS = frozenset({"idle_timeout_seconds"})
def _claude_launch_inputs(claude_config: Any) -> dict[str, Any]:
return {
key: value
for key, value in vars(claude_config).items()
if key not in _CLAUDE_LIVE_CONFIG_FIELDS
}
def _result_uuid(message: object) -> Optional[str]:
"""A ``ResultMessage``'s stream identity, None when it carries none."""
value = getattr(message, "uuid", None)
return value if isinstance(value, str) and value else None
class ClaudeAgent(BaseAgent):
"""Existing Claude Code integration extracted into an agent backend."""
name = "claude"
# Preserve the usual task-notification -> assistant/result association while
# bounding terminal-only notifications on the otherwise long-lived stream.
ACTIVITY_OUTPUT_FLUSH_GRACE_SECONDS = 30.0
# AskUserQuestion support is disabled - SDK cannot respond programmatically
# Set to True when SDK adds support (see issue #10168)
ENABLE_ASK_USER_QUESTION = False
def __init__(self, controller):
super().__init__(controller)
self.session_handler = controller.session_handler
self.session_manager = controller.session_manager
self.receiver_tasks = controller.receiver_tasks
self.claude_sessions = controller.claude_sessions
self.claude_client = controller.claude_client
self._last_assistant_text: dict[str, str] = {}
self._pending_assistant_message: dict[str, str] = {}
self._native_session_ids: dict[str, str] = {}
self._suppressed_synthetic_results: set[str] = set()
self._suppressed_synthetic_error_text: dict[str, str] = {}
self._suppress_receiver_runtime_release: set[str] = set()
# Store reaction info per runtime session for cleanup after terminal
# result. Under the runtime turn gate there is normally one active entry;
# the list shape remains for defensive cleanup of older queued state.
self._pending_reactions: dict[str, list[tuple[str, str]]] = {}
self._pending_requests: dict[str, list[AgentRequest]] = {}
self._steering_locks: dict[str, asyncio.Lock] = {}
self._steering_generations: dict[str, int] = {}
# Monotonic admission epochs let a writer that was queued before Stop
# distinguish Stop-owned prewrite rejection from an unrelated runtime
# replacement after the lock has been released.
self._steering_stop_epochs: dict[str, int] = {}
self._native_input_receipts: dict[str, list[_ClaudeInputReceipt]] = {}
self._ambiguous_primary_results: dict[str, object] = {}
self._steering_input_shutdowns: set[str] = set()
self._ambiguous_interrupts: set[str] = set()
self._steering_closing: set[str] = set()
self._stop_owned_terminal_keys: set[str] = set()
self._stop_owned_terminal_epochs: dict[str, int] = {}
self._steering_writers: set[str] = set()
# Recovery state is keyed by immutable phase/output identity. The
# composite runtime key is only an index used to find records; it is
# never the owner of retained text, receipts, or idempotency.
self._output_recovery_ledger: dict[str, _ClaudeOutputRecoveryRecord] = {}
self._activity_flush_tasks: dict[str, asyncio.Task] = {}
self._activity_settle_events: dict[str, asyncio.Event] = {}
self._buffered_assistant_messages: dict[str, list[tuple[object, int | None]]] = {}
self._activity_provenance_barriers: set[str] = set()
self._activity_provenance_barrier_owners: dict[str, int] = {}
self._foreground_tool_use_ids: dict[str, set[str]] = {}
self._turns_with_foreground_tools: set[str] = set()
self._provisional_tool_use_ids: dict[str, set[str]] = {}
self._provisional_unbound_tool_use_ids: dict[str, set[str]] = {}
self._provisional_foreground_tool_use_ids: dict[str, set[str]] = {}
self._provisional_activity_ids: dict[str, set[str]] = {}
self._provisional_unbound_activity_ids: dict[str, set[str]] = {}
self._provisional_foreground_task_ids: dict[str, set[str]] = {}
self._provisional_phase_ids: dict[str, str] = {}
self._resolved_provisional_phase_ids: dict[str, str] = {}
self._detached_foreground_tool_use_ids: dict[str, set[str]] = {}
self._detached_foreground_task_ids: dict[str, set[str]] = {}
self._synthetic_pending_owners: dict[str, AgentRequest] = {}
self._synthetic_owner_settlements: dict[str, asyncio.Event] = {}
self._provenance_recovery_evidence: dict[str, dict[str, object]] = {}
# Question handler for AskUserQuestion support (disabled)
# NOTE: Uncomment when SDK adds AskUserQuestion support
# self._question_handler = ClaudeQuestionHandler(
# agent=self,
# controller=controller,
# im_client=controller.im_client,
# settings_manager=controller.settings_manager,
# )
self._question_handler = None
def _output_recovery_generation(self, composite_key: str) -> object | None:
client = self.claude_sessions.get(composite_key)
# Identity is opaque, not the reusable numeric generation counter. The
# client itself is the identity for adapters without an activation registry.
return self._client_activation_identity(client) or client
def _output_records_for_runtime(
self,
composite_key: str,
) -> list[_ClaudeOutputRecoveryRecord]:
return [
record
for record in self._output_recovery_ledger.values()
if record.composite_key == composite_key
and record.lifecycle != "delivered"
]
def _output_record(
self,
composite_key: str,
phase_id: str | None,
*,
owner: Literal["activity", "detached"],
) -> _ClaudeOutputRecoveryRecord | None:
normalized = str(phase_id or "").strip()
if normalized:
record = self._output_recovery_ledger.get(normalized)
if (
record is not None and record.composite_key == composite_key
and record.owner == owner
):
return record
return None
for record in self._output_records_for_runtime(composite_key):
if record.owner == owner:
return record
return None
def _upsert_output_record(
self,
composite_key: str,
*,
phase_id: str,
owner: Literal["activity", "detached"],
text: str = "",
activities: list[SessionActivity] | None = None,
output: MessageOutput | None = None,
lifecycle: Literal["provisional", "delivery_pending"] = "provisional",
) -> _ClaudeOutputRecoveryRecord:
normalized_phase_id = str(phase_id or "").strip() or (
f"{composite_key}:output:{uuid.uuid4().hex}"
)
existing = self._output_recovery_ledger.get(normalized_phase_id)
if existing is not None:
if existing.composite_key != composite_key:
raise RuntimeError("Claude output phase identity collision")
# A DELIVERY_PENDING record is immutable. Later frames may create a
# different record, but they can never replace its selected payload,
# receipt batch, or idempotency identity.
if existing.lifecycle == "delivery_pending":
return existing
if text:
existing.text = str(text).strip()
if activities:
existing.activities = list(activities)
if output is not None:
existing.output = output
existing.lifecycle = lifecycle
return existing
record = _ClaudeOutputRecoveryRecord(
phase_id=normalized_phase_id,
composite_key=composite_key,
generation=self._output_recovery_generation(composite_key),
owner=owner,
lifecycle=lifecycle,
text=str(text or "").strip(),
activities=list(activities or ()),
output=output,
request=self._synthetic_pending_owners.get(composite_key),
)
self._output_recovery_ledger[normalized_phase_id] = record
return record
def _remove_output_record(
self,
record: _ClaudeOutputRecoveryRecord,
) -> None:
record.lifecycle = "delivered"
self._output_recovery_ledger.pop(record.phase_id, None)
def _provisional_output_record(
self, composite_key: str, owner: Literal["activity", "detached"],
) -> _ClaudeOutputRecoveryRecord | None:
return next((
record for record in self._output_records_for_runtime(composite_key)
if record.owner == owner and record.lifecycle == "provisional"
and record.generation is self._output_recovery_generation(composite_key)
), None)
def _detached_phase(
self, composite_key: str, *, claim_activity: bool = False,
) -> _ClaudeOutputRecoveryRecord:
"""Find only the unclassified phase, never a retained terminal payload."""
record = self._provisional_output_record(composite_key, "detached")
if record is None:
record = self._upsert_output_record(
composite_key,
phase_id=f"{composite_key}:detached:{uuid.uuid4().hex}",
owner="detached",
)
if claim_activity:
registry = self._activity_registry()
record.claim_pending = bool(
registry is not None and registry.has_completed_output(self.name, composite_key)
)
phase_id = self._resolved_provisional_phase_ids.get(composite_key)
if phase_id is not None:
record.claim_metadata = {
"provenance_phase_id": phase_id,
"provenance_detached": True,
}
return record
@staticmethod
def _snapshot_output_context(context: MessageContext) -> MessageContext:
captured = copy(context)
captured.platform_specific = dict(
getattr(context, "platform_specific", None) or {}
)
return captured
def _classify_output_record(
self, record: _ClaudeOutputRecoveryRecord, context: MessageContext,
*, text: str | None, message=None,
) -> None:
"""Freeze payload and terminal owner synchronously before delivery awaits."""
if record.lifecycle != "provisional":
return
record.text = str(text or "").strip()
record.context = self._snapshot_output_context(context)
record.provenance = self._result_origin_kind(message)
record.subtype = str(getattr(message, "subtype", "success") or "")
record.is_error = (
self._terminal_backend_failure(message, getattr(message, "result", None))
is not None
)
record.duration_ms = getattr(message, "duration_ms", 0)
if record.output is None:
record.output = self._unsolicited_message_output(message, phase_id=record.phase_id)
record.lifecycle = "delivery_pending"
if record.request is not None and record.activities:
owned = self._request_activities(record.request)
if owned and [a.id for a in owned] == [a.id for a in record.activities]:
# Transfer the existing claim, rather than giving Request and
# recovery two independent copies of receipt ownership.
self._clear_request_activities(record.request)
def _retire_output_generation(self, composite_key: str, client, context=None) -> None:
"""Retire native inference, never a frozen output receipt's recovery owner."""
generation = self._client_activation_identity(client) or client
for record in self._output_records_for_runtime(composite_key):
if record.generation is not generation or record.lifecycle != "provisional":
continue
captured = record.context or getattr(record.request, "context", None) or context
if captured is None:
continue
# A detached/claimed provisional payload has no future Result after
# retirement. Keep it detached and freeze its existing content;
# never let a replacement generation finish or overwrite this phase.
self._classify_output_record(
record, captured,
text=record.text or (
record.activities[-1].metadata.get("summary", "")
if record.activities else ""
),
)
record.provenance = "unresolved_generation_end"
if any(record.lifecycle == "delivery_pending" for record in self._output_records_for_runtime(composite_key)):
recovery_context = next(
(record.context for record in self._output_records_for_runtime(composite_key) if record.context is not None),
context,
)
if recovery_context is not None:
self._schedule_completed_activity_flush(composite_key, recovery_context)
def _retain_activity_output_record(
self,
composite_key: str,
activities: list[SessionActivity],
*,
text: str = "",
) -> _ClaudeOutputRecoveryRecord:
activity = activities[-1]
output = self._activity_message_output(
activity,
activities=activities,
detached=True,
completes_turn=False,
)
phase_id = str(
output.idempotency_key
or f"{composite_key}:activity:{activity.id}"
)
record = self._upsert_output_record(
composite_key,
phase_id=phase_id,
owner="activity",
text=text,
activities=activities,
output=output,
lifecycle="provisional",
)
return record
def _claude_error_diagnostic(
self,
composite_key: str,
error: Exception,
*,
client=None,
) -> str:
diagnostic = getattr(self.session_handler, "claude_error_diagnostic", None)
if callable(diagnostic):
try:
if client is not None:
try:
return diagnostic(composite_key, error, client=client)
except TypeError:
# Keep compatibility with lightweight test doubles and
# older session handlers that still expose the two-arg
# diagnostic hook.
pass
return diagnostic(composite_key, error)
except Exception:
logger.debug("claude: failed to build error diagnostic", exc_info=True)
return str(error)
def _translate_error(self, key: str, **kwargs) -> str:
translator = getattr(self.session_handler, "_t", None) or getattr(self.controller, "_t", None)
if callable(translator):
try:
return str(translator(key, **kwargs))
except Exception:
logger.debug("claude: failed to translate error notify", exc_info=True)
lang = getattr(getattr(self.controller, "config", None), "language", "en")
return str(i18n_t(key, lang, **kwargs))
def _format_error_notify(
self,
error: Exception,
*,
composite_key: str | None = None,
client=None,
) -> str:
"""Return the durable notify text for Claude terminal errors."""
from modules.agents.model_hub import launch_refusal_copy
refusal = launch_refusal_copy(self.controller, error)
if refusal is not None:
return f"❌ {refusal}"
if isinstance(error, ClaudeInputNotSentError):
return f"❌ {self._translate_error(error.message_key)}"
if isinstance(error, ClaudeSessionNotFoundError):
detail = self._translate_error(
"error.claudeSessionNotFound",
sessionId=error.session_id,
path=error.working_path,
)
return f"❌ {detail}"
if is_claude_sdk_buffer_error(error):
return f"❌ {self._translate_error('error.sessionConnectionLost')}"
if client is None:
client = self.claude_sessions.get(composite_key) if composite_key else None
returncode = get_claude_client_returncode(client)
if returncode is not None:
reason_key, reason_values = claude_process_exit_reason_i18n(returncode)
reason = self._translate_error(reason_key, **reason_values)
message = self._translate_error("error.claudeProcessTerminated", reason=reason)
resource_failure = getattr(client, "_vibe_resource_failure", None)
if resource_failure is not None:
if getattr(resource_failure, "kind", None) == "pids":
language = str(
getattr(getattr(self.controller, "config", None), "language", "en")
or "en"
)
message = (
f"{message} "
f"{self._translate_error('error.agentPidsLimit', **pids_failure_labels(resource_failure, language))}"
)
elif getattr(resource_failure, "kind", None) == "memory":
message = f"{message} {self._translate_error('error.agentMemoryLimit')}"
return f"❌ {message}"
return f"❌ Claude error: {error}"
@staticmethod
async def _human_query_messages(message: str, session_id: str):
"""Yield an SDK streaming user message with explicit human provenance."""
yield {
"type": "user",
"message": {"role": "user", "content": message},
"parent_tool_use_id": None,
"session_id": session_id,
"origin": {"kind": "human"},
}
def _assert_current_client_for_write(self, composite_key: str, client) -> None:
"""Reject a retired Claude generation before marking a native write."""
registered = self.claude_sessions.get(composite_key)
if registered is not None and registered is not client:
raise ClaudeInputNotSentError(
"claude_runtime_changed_before_write",
"error.claudeInputRuntimeChanged",
)
if getattr(client, "_vibe_runtime_activation_retired", False) is True:
raise ClaudeInputNotSentError(
"claude_runtime_changed_before_write",
"error.claudeInputRuntimeChanged",
)
if composite_key in self._steering_closing_keys():
raise ClaudeInputNotSentError(
"claude_runtime_changed_before_write",
"error.claudeInputRuntimeChanged",
)
identity = self._client_activation_identity(client)
registry = getattr(getattr(self.controller, "agent_service", None), "activation_registry", None)
if identity is not None and registry is not None and not registry.is_current(identity):
raise ClaudeInputNotSentError(
"claude_runtime_changed_before_write",
"error.claudeInputRuntimeChanged",
)
async def _write_human_query(
self,
client,
composite_key: str,
message: str,
context: MessageContext,
) -> None:
"""Write one human query after the caller acquires the native-write fence.
``_steering_lock`` is the sole admission fence for native writes and
Stop. Runtime-generation retirement may hold its own lock while it
marks a client retired, but it never waits for that lock from here:
eviction can then mark-and-wait without creating a reverse lock order.
"""
self._assert_current_client_for_write(composite_key, client)
# The write is now admitted against the exact client generation. If
# transport.write fails after this point, delivery is attempted or
# ambiguous and must follow the normal recovery path.
mark_backend_dispatch_attempted(context)
await client.query(
self._human_query_messages(message, composite_key),
session_id=composite_key,
)
async def _refuse_disabled_turn(self, context, request) -> None:
language = str(getattr(getattr(self.controller, "config", None), "language", "en") or "en")
await emit_backend_failure(
self.controller,
context,
self.name,
"claude backend disabled",
display_text=(
f"❌ {i18n_t('error.agentRuntimeRetired', language, agent=display_name_for_backend(self.name))}"
),
request=request,
)
await self._remove_ack_reaction(request)
async def handle_message(self, request: AgentRequest) -> None:
context = request.context
runtime_base_session_id = request.base_session_id
runtime_session_key = request.composite_session_id
turn_registered = False
client = None
input_receipt = None
stop_owned = False
# Question callback handling (disabled - SDK doesn't support AskUserQuestion response)
# if self.ENABLE_ASK_USER_QUESTION and request.message.startswith("claude_question:"):
# await self._handle_question_callback(request)
# return
if getattr(getattr(self.config, "claude", None), "enabled", True) is False:
# Claude stays registered while disabled, so a turn queued behind
# the one the disable interrupted still reaches it. It must start
# nothing and say why, as Codex and OpenCode do.
await self._refuse_disabled_turn(context, request)
return
try:
try:
client = await self.session_handler.get_or_create_claude_session(
context,
subagent_name=request.subagent_name,
subagent_model=request.subagent_model or getattr(request, "vibe_agent_model", None),
subagent_reasoning_effort=(
request.subagent_reasoning_effort
or getattr(request, "vibe_agent_reasoning_effort", None)
),
agent_system_prompt=getattr(request, "vibe_agent_system_prompt", None),
)
except ClaudeBackendDisabledError:
# Claude was turned off while this turn's client was being
# created; the client is already gone.
await self._refuse_disabled_turn(context, request)
return
runtime_base_session_id = getattr(client, "_vibe_runtime_base_session_id", runtime_base_session_id)
runtime_session_key = getattr(client, "_vibe_runtime_session_key", runtime_session_key)
mark_session_active = getattr(self.session_handler, "mark_session_active", None)
if callable(mark_session_active):
mark_session_active(runtime_session_key)
# Prepare message with file attachment info if present
message = self._prepare_message_with_files(request)
message = self.render_input(message, getattr(request, "input_metadata", None))
admission_stop_epoch = self._steering_stop_epoch(runtime_session_key)
try:
async with self._steering_lock(runtime_session_key):
if (
self._steering_stop_epoch(runtime_session_key)
!= admission_stop_epoch
):
# Stop already won the only admission fence. The
# request was never registered and must retain its
# definitely-unsent recovery evidence without entering
# the generic runtime-error settlement path.
setattr(request, "_claude_stop_owned", True)
raise ClaudeInputNotSentError(
"claude_runtime_changed_before_write",
"error.claudeInputRuntimeChanged",
)
# Queue reaction and register the request while holding the
# same fence as Stop/native write. This makes registration
# itself part of the terminal ownership decision.
if request.ack_reaction_message_id and request.ack_reaction_emoji:
if runtime_session_key not in self._pending_reactions:
self._pending_reactions[runtime_session_key] = []
self._pending_reactions[runtime_session_key].append(
(request.ack_reaction_message_id, request.ack_reaction_emoji)
)
self._pending_requests.setdefault(runtime_session_key, []).append(request)
self._refresh_activity_provenance_barrier(runtime_session_key)
input_receipt = self._register_native_input(
runtime_session_key,
message,
kind="primary",
)
writers = self._steering_writer_keys()
writers.add(runtime_session_key)
try:
await self._write_human_query(
client,
runtime_session_key,
message,
request.context,
)
finally:
writers.discard(runtime_session_key)
except (Exception, asyncio.CancelledError):
if input_receipt is not None:
self._remove_native_input_receipt(runtime_session_key, input_receipt)
raise
input_receipt.state = "accepted"
from core.skill_observability import accept_catalog
accept_catalog(self.controller, context, getattr(client, "_vibe_pending_skill_catalog", None), backend="claude")
setattr(client, "_vibe_pending_skill_catalog", None)
if (
runtime_session_key not in self.receiver_tasks
or self.receiver_tasks[runtime_session_key].done()
):
receiver_kwargs: dict[str, object] = {
"composite_key": runtime_session_key,
}
receiver_identity = self._client_activation_identity(client)
if receiver_identity is not None:
receiver_kwargs["receiver_activation_identity"] = receiver_identity
self.receiver_tasks[runtime_session_key] = asyncio.create_task(
self._receive_messages(
client,
runtime_base_session_id,
request.working_path,
context,
**receiver_kwargs,
)
)
self.mark_runtime_turn_started(
context,
activation_identity=self._client_activation_identity(client),
)
turn_registered = True
logger.info(f"Sent message to Claude for session {runtime_session_key}")
await self._delete_ack(context, request)
except asyncio.CancelledError:
if not turn_registered:
await self._remove_specific_pending_reaction(runtime_session_key, context, request)
self._remove_pending_request(runtime_session_key, request)
self._mark_session_idle_if_no_pending_requests(runtime_session_key)
await self._delete_ack(context, request)
if not bool(getattr(request, "_claude_stop_owned", False)):
self._release_service_runtime_turn(context)
raise
except Exception as e:
logger.error(f"Error processing Claude message: {e}", exc_info=True)
from modules.agents.model_hub import launch_refusal_copy
missing_session = isinstance(e, ClaudeSessionNotFoundError)
input_not_sent = isinstance(e, ClaudeInputNotSentError)
hub_refusal = launch_refusal_copy(self.controller, e) is not None
stop_owned = bool(getattr(request, "_claude_stop_owned", False))
if missing_session:
mark_prewrite_recovery_required(context, "native_session_not_found")
elif input_not_sent:
mark_prewrite_recovery_required(context, e.reason)
diagnostic = self._claude_error_diagnostic(
runtime_session_key,
e,
client=client,
)
# Classify BEFORE recording: ``record_model_hub_native_failure``
# turns the pending native/hub attempt into a failed one, so a
# process the service killed on purpose would settle that source's
# provenance as exhausted with no backend fault behind it.
intentional_teardown = self._teardown_is_intentional(
runtime_session_key, e, client=client
)
if not intentional_teardown and not input_not_sent:
await self.record_model_hub_native_failure(context, diagnostic)
# Clean up the specific reaction for this request (not FIFO)
await self._remove_specific_pending_reaction(runtime_session_key, context, request)
self._remove_pending_request(runtime_session_key, request)
self._mark_session_idle_if_no_pending_requests(runtime_session_key)
await self._remove_ack_reaction(request)
error_notify = self._format_error_notify(
e,
composite_key=runtime_session_key,
client=client,
)
try:
if stop_owned:
# Stop owns the only terminal settlement. The prewrite
# failure above is durable recovery evidence only; emitting
# a runtime-changed error or another silent result here
# would settle the same user request twice.
self._requeue_request_activity(request)
logger.info(
"Claude request was rejected after Stop won admission for %s",
runtime_session_key,
)
return
# A typed local resume failure or Hub refusal takes precedence
# over incidental auth words in a path, model id, or diagnostic.
handled = False
if not missing_session and not input_not_sent and not hub_refusal:
handled = await self._offer_auth_recovery(
context,
error_notify,
client=client,
output=terminal_output_for(request),
terminal_error=diagnostic,
)
if handled and client is not None and get_claude_client_returncode(client) is not None:
# Auth recovery owns the visible settlement, but a query can
# fail after the cached CLI has already exited. Retire that
# runtime here so its client and Model Hub credential cannot
# survive until a later retry; preserve newer queued turns.
self._requeue_request_activity(request)
await self._cleanup_runtime_session(
runtime_session_key,
preserve_pending_request_state=True,
reason="query_auth_failure",
)
if not handled:
# Third and last emit site that can be holding a claimed
# Activity batch. The request is in the FIFO from the moment
# it is queued, so a background Activity that completes while
# ``client.query`` is in flight attaches its batch here; the
# auth branch above already requeues for exactly that reason.
# Both receiver paths hand the batch back before their
# terminal emit, unconditionally -- do the same rather than
# only for a contained teardown, because the non-contained
# release is no better: it terminalizes those Runs from this
# empty error body. Requeueing resets the request output to
# the plain terminal shape, so the emit below carries no
# provenance it can no longer honour.
self._requeue_request_activity(request)
contained = await self.session_handler.handle_session_error(
runtime_session_key, context, e, client=client
)
# ``handle_session_error`` sends through the IM client, which doesn't
# write to ``messages``, and the web Chat renders only durable
# ``message.new`` rows. The auth branch persists its recovery text.
# A contained failure (a teardown the service performed itself)
# must stay silent on every surface, so skip the durable row too.
# Only an explicit ``True`` suppresses: the session handler is
# duck-typed here, and a handler that returns anything else must
# keep the failure visible.
if contained is not True:
try:
from core.message_mirror import persist_agent_message
notification = backend_failure_notification_output(
context,
"claude",
request=request,
output=terminal_output_for(request),
)
persist_agent_message(
context,
"notify",
error_notify,
metadata=notification.provenance(context),
native_message_id=notification.idempotency_key,
)
except Exception:
logger.debug(
"claude: failed to persist terminal error row", exc_info=True
)
# No async receiver result is coming. Auth recovery settles its
# own failure; otherwise do that here without another bubble.
await self._emit_no_result_settlement(
context,
request,
diagnostic,
contained=contained is True,
)
finally:
# Stop owns a prewrite rejection's terminal settlement. Keep the
# service gate held until handle_stop finishes cleanup and emits
# its single silent terminal result.
if not stop_owned:
self._release_service_runtime_turn(context)
finally:
await self._delete_ack(context, request)
async def _offer_auth_recovery(
self,
context: MessageContext,
error_notify: str,
*,
client,
output,
terminal_error: str,
) -> bool:
"""Offer re-login for a failed Claude call that can be an auth failure.
A CLI that a signal ended (the OOM killer, a service stop) was
terminated, and that is the failure's cause whatever its diagnostic
says.
The CLI's stderr is never auth evidence. The CLI reports an auth
failure as frames: an Assistant message whose ``error`` is
``authentication_failed``, then an ``is_error`` Result, and those
reach recovery on their own path. Stderr carries its notices, such as
one naming the claude.ai login at every start when an API key
outranks it, so reading it for auth words sent ordinary crashes to
OAuth. The diagnostic keeps stderr for the user; only this check
leaves it out.
"""
if claude_process_exit_signal(get_claude_client_returncode(client)) is not None:
return False
evidence = claude_diagnostic_without_stderr(str(terminal_error or ""))
if not classify_auth_error("claude", f"{error_notify}\n{evidence}"):
return False
return await self.controller.agent_auth_service.maybe_emit_auth_recovery_message(
context,
"claude",
error_notify,
output=output,
terminal_error=terminal_error,
)
def _teardown_is_intentional(self, composite_key: str, error: Exception, *, client=None) -> bool:
"""Did the service kill this Claude process itself?
The session handler owns the classification; this only reaches it.
Duck-typed like the other handler calls here, and failure-closed: an
unknown answer must record the failure rather than silently drop
backend-health evidence.
"""
probe = getattr(self.session_handler, "claude_teardown_is_intentional", None)
if not callable(probe):
return False
try:
return probe(composite_key, error, client=client) is True
except Exception:
logger.debug("claude: teardown classification failed", exc_info=True)
return False
async def _emit_no_result_settlement(
self,
context: MessageContext,
request: Any,
diagnostic: Optional[str],
*,
contained: bool,
) -> None:
"""Settle a turn whose backend produced no terminal result.
Three call sites reach this state -- a failed direct query, a receiver that
hit EOF, and a receiver exception -- and all three must settle the turn
through the one outbound chokepoint, because nothing else will.
``contained`` is #1202's classification: the service killed this Claude
process itself. That branch is the whole point of the split. Emitting the
ordinary shape for it recorded a FAILED Turn and an ``agent_runs`` row
terminalized from an empty body -- provenance that contradicts the
classification the caller already made, and which #1202 only hid the bubble
for. ``contained_teardown_output_for`` routes the release through the
settlement lane instead, where the run lands ``failed`` with
``interrupt_reason=backend_refresh``: still terminal, still visible to
anything reading the reason, but no longer indistinguishable from a backend
that actually broke.
What does NOT change is ``is_error``. Inside the dispatcher's silent branch
it feeds four things -- the collapsed status bubble's footer word, the
durable Turn outcome, the IM silent-terminal trace, and (when no durable
Turn owns the session) the sidebar status projection -- and for all four
"no terminal result was produced" remains true no matter who killed the
process. Clearing it would collapse the bubble to a green ``done`` for a
turn that answered nothing.
The three that must NOT read that as a backend fault are told so by the
settlement, which outranks the flag: ``NON_COMPLETING_TURN_SETTLEMENTS``
for the two Turn-outcome surfaces, and the same map's membership for the
sidebar, which has no dot between ``idle`` and ``failed`` to spend on it.
The one thing suppressed is ``terminal_error``: with the flag set and no
diagnostic, the bubble reads ``stopped`` (an intentional silent end) rather
than ``failed``, which is exactly what this is. The settlement supplies the
machine-readable cause; the footer only has to stop claiming success.
"""
await emit_output(
self.controller,
context,
TurnEnd(
outcome=TurnOutcome.TEARDOWN if contained else TurnOutcome.FAILED,
silent=True,
terminal_error=None if contained else diagnostic,
output=terminal_output_for(request),
),
)
def _release_service_runtime_turn(self, context: MessageContext) -> None:
service = getattr(self.controller, "agent_service", None)
release = getattr(service, "release_runtime_turn", None)
if callable(release):
release(context)
def backend_alive(self, context) -> Optional[bool]:
"""Liveness via the receiver task for this turn's runtime session.
``receiver_tasks`` is keyed by the Claude runtime session key. When that
key matches the turn's ``AGENT_RUNTIME_TURN_KEY`` we know the answer; if
it doesn't (e.g. a client-overridden runtime key) we return ``None`` so
the caller never false-alarms."""
payload = getattr(context, "platform_specific", None) or {}
key = str(payload.get(AGENT_RUNTIME_TURN_KEY) or "").strip()
if not key:
return None
task = self.receiver_tasks.get(key)
if task is None:
return None
return not task.done()
def capture_backend_liveness(self, context) -> Callable[[], Optional[bool]]:
"""Bind liveness to the receiver task generation accepting this turn."""
payload = getattr(context, "platform_specific", None) or {}
key = str(payload.get(AGENT_RUNTIME_TURN_KEY) or "").strip()
task = self.receiver_tasks.get(key) if key else None
if task is None:
return lambda: None
return lambda: not task.done()
async def _handle_question_callback(self, request: AgentRequest) -> None:
"""Handle question-related callbacks (button clicks, modal submissions).
NOTE: This method is disabled because Claude Code SDK cannot respond to
AskUserQuestion programmatically. See: https://github.com/anthropics/claude-code/issues/10168
"""
# AskUserQuestion support disabled
await emit_output(
self.controller,
request.context,
Notice(
"AskUserQuestion support is currently disabled. Claude Code SDK does not support programmatic"
" responses to this tool."
),
)
return
async def clear_sessions(self, session_key: str) -> int:
"""Clear Claude sessions scoped to the provided session key."""
agent_map = self.sessions.list_agent_sessions(session_key, self.name)
session_bases_to_clear = set(agent_map.keys())
self.sessions.clear_agent_sessions(session_key, self.name)
sessions_to_clear = []
for composite_id in list(self.claude_sessions.keys()):
if self._runtime_key_matches_session_base(composite_id, session_bases_to_clear):
sessions_to_clear.append(composite_id)
for composite_id in sessions_to_clear:
await self._cleanup_runtime_session(
composite_id,
reason="session_clear",
)
# Legacy session manager cleanup (best-effort)
await self.session_manager.clear_session(session_key)
return len(sessions_to_clear) or len(session_bases_to_clear)
def runtime_turn_keys_for_session_key(self, session_key: str) -> set[str]:
agent_map = self.sessions.list_agent_sessions(session_key, self.name)
session_bases_to_clear = set(agent_map.keys())
runtime_keys = set()
for composite_id in self.runtime_turn_keys():
if self._runtime_key_matches_session_base(composite_id, session_bases_to_clear):
runtime_keys.add(composite_id)
return runtime_keys
def runtime_turn_keys(self) -> set[str]:
return set(self.claude_sessions.keys()) | set(self.receiver_tasks.keys())
def runtime_ownership_snapshots(self):
return self.session_handler.runtime_ownership_snapshots()
@staticmethod
def _client_activation_identity(client) -> RuntimeActivationIdentity | None:
identity = getattr(client, "_vibe_runtime_activation_identity", None)
return identity if isinstance(identity, RuntimeActivationIdentity) else None
def runtime_activation_identity_for_request(
self,
request,
) -> RuntimeActivationIdentity | None:
runtime_key = str(getattr(request, "composite_session_id", "") or "").strip()
if runtime_key:
return self._client_activation_identity(self.claude_sessions.get(runtime_key))
session_key = str(getattr(request, "session_key", "") or "").strip()
candidates = [
self._client_activation_identity(client)
for client in self.claude_sessions.values()
if session_key
and str(
getattr(client, "_vibe_runtime_fallback_session_key", "") or ""
).strip()
== session_key
]
identities = tuple(
dict.fromkeys(identity for identity in candidates if identity is not None)
)
if len(identities) > 1:
raise ValueError("ambiguous Claude Session route maps to live runtimes")
return identities[0] if identities else None
def runtime_activation_identity_for_session_binding(
self,
*,
session_anchor: str,
workdir: str | None,
) -> RuntimeActivationIdentity | None:
normalized_anchor = str(session_anchor or "").strip()
normalized_workdir = str(workdir or "").strip()
if not normalized_anchor:
return None
anchor_clients = [
client
for client in self.claude_sessions.values()
if str(
getattr(client, "_vibe_runtime_base_session_id", "") or ""
).strip()
== normalized_anchor
]
if not anchor_clients:
return None
exact_clients = [
client
for client in anchor_clients
if str(getattr(client, "_vibe_runtime_workdir", "") or "").strip()
== normalized_workdir
]
if len(exact_clients) != 1:
raise ValueError("Claude Session binding is ambiguous or changed workdir")
identity = self._client_activation_identity(exact_clients[0])
if identity is None:
raise ValueError("Claude runtime generation is not attached")
return identity
def record_runtime_turn_start(
self,
*,
runtime_key: str,
request: AgentRequest | None,
) -> None:
del request
mark_started = getattr(self.session_handler, "mark_session_turn_started", None)
if callable(mark_started):
mark_started(runtime_key)
else:
self.session_handler.touch_session_activity(runtime_key)
@staticmethod
def _runtime_key_matches_session_base(runtime_key: str, session_bases: set[str]) -> bool:
for session_base in session_bases:
if runtime_key == session_base or runtime_key.startswith(f"{session_base}:"):
return True
return False
async def refresh_auth_state(self) -> None:
"""Reconnect Claude runtime so future requests load fresh auth."""
session_ids = self.runtime_turn_keys()
for composite_id in session_ids:
await self._cleanup_runtime_session(
composite_id,
reason="auth_refresh",
)
logger.info("Refreshed Claude auth state across %d runtime session(s)", len(session_ids))
async def adopt_model_hub_catalog(self) -> None:
"""Nothing to apply: each turn resolves its model, limits, and efforts.
A session whose resolved launch changed moves to a new client at that
turn, by the same rule as any other launch-input change.
"""
async def renew_runtime(self, claude_config, *, config_save: bool = False) -> None:
"""Adopt persisted runtime config; each session moves to it at its next turn.
Every session owns its own process, so nothing drains or reconnects
here: a session's next turn starts a new client, unless background work
it started is still running. A config save that changes only fields read
live, such as the idle timeout, renews nothing.
"""
previous = self.config.claude
self.config.claude = claude_config
self.controller.config.claude = claude_config
session_handler = getattr(self, "session_handler", None)
if session_handler is None:
return
session_handler.config = self.controller.config
if config_save and _claude_launch_inputs(previous) == _claude_launch_inputs(claude_config):
return
session_handler.renew_runtime()
async def refresh_runtime_config(self, claude_config) -> None:
"""Reload persisted runtime config before reconnecting Claude sessions."""
self.config.claude = claude_config
self.controller.config.claude = claude_config
session_handler = getattr(self, "session_handler", None)
if session_handler is not None:
session_handler.config = self.controller.config
await self.refresh_auth_state()
async def prepare_resume_binding(
self,
*,
base_session_id: str,
session_key: str,
working_path: str,
) -> None:
"""Drop only the target Claude runtime session before rebinding it."""
composite_key = f"{base_session_id}:{working_path}"
if composite_key not in self.claude_sessions and composite_key not in self.receiver_tasks:
return
await self._cleanup_runtime_session(
composite_key,
reason="resume_rebind",
)
logger.info("Prepared Claude runtime for resumed session %s", composite_key)
async def _disconnect_client(self, client, composite_key: str) -> None:
try:
if hasattr(client, "disconnect"):
await client.disconnect()
elif hasattr(client, "close"):
await client.close()
except Exception as exc: # noqa: BLE001
logger.warning("Error disconnecting Claude session %s: %s", composite_key, exc)
def _disconnect_client_after_receiver(
self,
client,
composite_key: str,
receiver_task: asyncio.Task | None,
) -> None:
async def _run() -> None:
if receiver_task is not None:
try:
await receiver_task
except asyncio.CancelledError:
pass
except Exception as exc: # noqa: BLE001
logger.warning("Claude receiver ended with error before deferred disconnect: %s", exc)
await self._disconnect_client(client, composite_key)
asyncio.create_task(_run())
@staticmethod
def _drain_receiver_task_exception(receiver_task: asyncio.Task) -> None:
try:
exc = receiver_task.exception()
except asyncio.CancelledError:
return
except Exception as exc: # noqa: BLE001
logger.warning("Error reading Claude receiver cleanup result: %s", exc)
return
if exc is not None:
logger.warning("Claude receiver ended with error during cleanup: %s", exc)
async def _stop_receiver_task(self, receiver_task: asyncio.Task | None) -> None:
if receiver_task is None:
return
if receiver_task.done():
self._drain_receiver_task_exception(receiver_task)
return
receiver_result_retrieved = False
try:
await asyncio.wait_for(asyncio.shield(receiver_task), timeout=0.1)
except asyncio.TimeoutError:
pass
except asyncio.CancelledError:
pass
except Exception as exc: # noqa: BLE001
receiver_result_retrieved = True
logger.warning("Claude receiver ended with error during cleanup: %s", exc)
if receiver_task.done():
if not receiver_result_retrieved:
self._drain_receiver_task_exception(receiver_task)
return
receiver_task.cancel()
try:
await receiver_task
except asyncio.CancelledError:
pass
except Exception as exc: # noqa: BLE001
logger.warning("Error stopping Claude receiver during cleanup: %s", exc)
async def retire_for_native_migration(self) -> None:
"""Strict retirement without the broad duplicate-process reaper."""
handler = self.session_handler
for key, client in list(self.claude_sessions.items()):
async with handler._claude_runtime_generation_lock(key):
if self.claude_sessions.get(key) is not client:
raise RuntimeError("Claude runtime generation changed")
if key in handler.active_sessions or not handler._retire_claude_runtime_activation(
key, client, lambda: self.claude_sessions.get(key) is client
):
raise RuntimeError("Claude runtime retirement was refused")
process = getattr(getattr(client, "_transport", None), "_process", None)
if process is None:
raise RuntimeError("Claude runtime process ownership is unavailable")
await client.disconnect()
if process.returncode is None:
await asyncio.wait_for(process.wait(), timeout=5)
if process.returncode is None:
raise RuntimeError("Claude runtime process did not exit")
await self._stop_receiver_task(self.receiver_tasks.get(key))
self.receiver_tasks.pop(key, None)
self.claude_sessions.pop(key, None)
handler.clear_session_tracking(key)
handler._retire_model_hub_process_scope(key)
self._native_session_ids.pop(key, None)
self._last_assistant_text.pop(key, None)
self._pending_assistant_message.pop(key, None)
self._retire_steering_state(key)
async def _cleanup_runtime_session(
self,
composite_key: str,
*,
current_receiver_task: asyncio.Task | None = None,
expected_client=None,
preserve_pending_request_state: bool = False,
runtime_lock_held: bool = False,
activation_retired: bool = False,
reason: str = "claude_agent_cleanup",
) -> None:
"""Drop Claude runtime state without canceling the current receiver task."""
current_client = self.claude_sessions.get(composite_key)
if expected_client is not None and current_client is not None and current_client is not expected_client:
return
cleanup_client = expected_client or current_client
cleanup_lock = self._steering_lock(composite_key)
await self._prepare_steering_cleanup(composite_key)
try:
await self._cleanup_runtime_session_state(
composite_key,
current_receiver_task=current_receiver_task,
expected_client=expected_client,
preserve_pending_request_state=preserve_pending_request_state,
runtime_lock_held=runtime_lock_held,
activation_retired=activation_retired,
reason=reason,
)
finally:
current_client = self.claude_sessions.get(composite_key)
if current_client is None or current_client is cleanup_client:
self._retire_steering_state(composite_key, expected_lock=cleanup_lock)
async def _cleanup_runtime_session_state(
self,
composite_key: str,
*,
current_receiver_task: asyncio.Task | None = None,
expected_client=None,
preserve_pending_request_state: bool = False,
runtime_lock_held: bool = False,
activation_retired: bool = False,
reason: str = "claude_agent_cleanup",
) -> None:
current_client = self.claude_sessions.get(composite_key)
if expected_client is not None and current_client is not None and current_client is not expected_client:
return
self._retire_output_generation(composite_key, expected_client or current_client)
preserve_synthetic_delivery = self._has_synthetic_delivery_pending(composite_key)
preserve_pending_request_state = (
preserve_pending_request_state or preserve_synthetic_delivery
)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._buffered_assistant_messages.pop(composite_key, None)
self._activity_provenance_barriers.discard(composite_key)
self._activity_provenance_barrier_owners.pop(composite_key, None)
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
self._provisional_tool_use_ids.pop(composite_key, None)
self._provisional_unbound_tool_use_ids.pop(composite_key, None)
self._provisional_foreground_tool_use_ids.pop(composite_key, None)
self._provisional_activity_ids.pop(composite_key, None)
self._provisional_unbound_activity_ids.pop(composite_key, None)
self._provisional_foreground_task_ids.pop(composite_key, None)
self._provisional_phase_ids.pop(composite_key, None)
self._resolved_provisional_phase_ids.pop(composite_key, None)
self._clear_detached_foreground_tool_state(composite_key)
self._native_session_ids.pop(composite_key, None)
self._suppressed_synthetic_results.discard(composite_key)
self._suppressed_synthetic_error_text.pop(composite_key, None)
if not preserve_synthetic_delivery:
self._synthetic_pending_owners.pop(composite_key, None)
if not preserve_pending_request_state:
self._pending_reactions.pop(composite_key, None)
pending_requests = self._pending_requests.pop(composite_key, None) or []
for pending_request in pending_requests:
self._requeue_request_activity(pending_request)
cleanup_name = "_cleanup_session_locked" if runtime_lock_held else "cleanup_session"
cleanup = getattr(self.session_handler, cleanup_name, None)
if callable(cleanup):
cleanup_kwargs = {
"current_receiver_task": current_receiver_task,
"activation_retired": activation_retired,
"reason": reason,
}
if expected_client is not None:
cleanup_kwargs["expected_client"] = expected_client
try:
await cleanup(composite_key, **cleanup_kwargs)
except TypeError as error:
# A few lightweight session-handler test doubles still expose
# the pre-generation-aware cleanup signature. Preserve the
# exact-client guard for the real handler while remaining
# compatible with those narrow adapters.
if "expected_client" not in str(error):
raise
cleanup_kwargs.pop("expected_client", None)
await cleanup(composite_key, **cleanup_kwargs)
return
if (
expected_client is not None
and self.claude_sessions.get(composite_key) is not expected_client
):
return
receiver_task = self.receiver_tasks.pop(composite_key, None)
client = self.claude_sessions.pop(composite_key, None)
cleanup_from_receiver = receiver_task is not None and receiver_task is current_receiver_task
clear_tracking = getattr(self.session_handler, "clear_session_tracking", None)
if callable(clear_tracking):
clear_tracking(composite_key)
try:
if client is not None:
if cleanup_from_receiver:
self._disconnect_client_after_receiver(client, composite_key, receiver_task)
else:
await self._disconnect_client(client, composite_key)
finally:
if not cleanup_from_receiver:
await self._stop_receiver_task(receiver_task)
async def force_cleanup_stuck_active_session(
self,
composite_key: str,
*,
runtime_lock_held: bool = False,
activation_retired: bool = False,
) -> None:
"""Settle and drop a Claude session whose active flag is stale.
SessionHandler owns the idle timer, but ClaudeAgent owns the pending
request FIFO and Workbench turn tokens. Force cleanup must retire the
failed turn here before removing the SDK client, otherwise a later
result can adopt the stale request/token.
"""
self._steering_closing_keys().add(composite_key)
async with self._steering_lock(composite_key):
pending_request = self._pop_pending_request(composite_key)
self._requeue_request_activity(pending_request)
context = getattr(pending_request, "context", None)
if context is not None:
self._adopt_pending_turn_token(context, pending_request)
await self._remove_result_pending_reaction(composite_key, context, pending_request)
else:
self._pending_reactions.pop(composite_key, None)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._suppress_receiver_runtime_release.add(composite_key)
try:
try:
await self._cleanup_runtime_session(
composite_key,
preserve_pending_request_state=True,
runtime_lock_held=runtime_lock_held,
activation_retired=activation_retired,
reason="stuck_active_eviction",
)
except Exception:
if context is not None:
self._release_service_runtime_turn(context)
raise
finally:
self._suppress_receiver_runtime_release.discard(composite_key)
if context is not None:
try:
await emit_output(
self.controller,
context,
TurnEnd(outcome=TurnOutcome.FAILED, silent=True, output=terminal_output_for(pending_request)),
)
except Exception:
logger.debug(
"Failed to emit terminal result while force-cleaning Claude session %s",
composite_key,
exc_info=True,
)
self._release_service_runtime_turn(context)
def steering_native_turn_id(self, target: ActiveSteerTarget) -> Optional[str]:
composite_key = target.runtime_key
client = self.claude_sessions.get(composite_key)
receiver_task = self.receiver_tasks.get(composite_key)
active_sessions = getattr(self.session_handler, "active_sessions", set())
if (
client is None
or receiver_task is None
or receiver_task.done()
or composite_key not in active_sessions
or composite_key in self._steering_closing_keys()
or composite_key in self._steering_input_shutdown_keys()
or composite_key in self._ambiguous_interrupt_keys()
):
return None
return f"claude:{composite_key}:{id(client)}:{id(receiver_task)}"
def _steering_lock(self, composite_key: str) -> asyncio.Lock:
locks = getattr(self, "_steering_locks", None)
if locks is None:
locks = {}
self._steering_locks = locks
return locks.setdefault(composite_key, asyncio.Lock())
def _steering_generation(self, composite_key: str) -> int:
generations = getattr(self, "_steering_generations", None)
if generations is None:
generations = {}
self._steering_generations = generations
return generations.get(composite_key, 0)
def _steering_stop_epoch(self, composite_key: str) -> int:
epochs = getattr(self, "_steering_stop_epochs", None)
if epochs is None:
epochs = {}
self._steering_stop_epochs = epochs
return epochs.get(composite_key, 0)
def _advance_steering_stop_epoch(self, composite_key: str) -> int:
epoch = self._steering_stop_epoch(composite_key) + 1
self._steering_stop_epochs[composite_key] = epoch
return epoch
def _steering_closing_keys(self) -> set[str]:
closing = getattr(self, "_steering_closing", None)
if closing is None:
closing = set()
self._steering_closing = closing
return closing
def _steering_writer_keys(self) -> set[str]:
writers = getattr(self, "_steering_writers", None)
if writers is None:
writers = set()
self._steering_writers = writers
return writers
async def _prepare_steering_cleanup(self, composite_key: str) -> None:
await self._close_steering_admission(composite_key)
def _mark_steering_closing(self, composite_key: str) -> None:
"""Reject new native writes before an async receiver-end replay."""
self._steering_closing_keys().add(composite_key)
async def _close_steering_admission(self, composite_key: str) -> None:
"""Close native write admission and drain the current writer.
The closing marker prevents a waiter from entering the fence, while
acquiring the same lock makes an already-admitted write finish before
receiver replay or cleanup can settle the old generation.
"""
self._mark_steering_closing(composite_key)
async with self._steering_lock(composite_key):
pass
def _retire_steering_state(
self,
composite_key: str,
*,
expected_lock: asyncio.Lock | None = None,
) -> None:
locks = getattr(self, "_steering_locks", None)
lock = locks.get(composite_key) if locks is not None else None
if expected_lock is not None and lock is not expected_lock:
return
if lock is not None and lock.locked():
return
if locks is not None:
locks.pop(composite_key, None)
generations = getattr(self, "_steering_generations", None)
if generations is not None:
generations.pop(composite_key, None)
receipts = getattr(self, "_native_input_receipts", None)
if receipts is not None:
receipts.pop(composite_key, None)
ambiguous_results = getattr(self, "_ambiguous_primary_results", None)
if ambiguous_results is not None:
ambiguous_results.pop(composite_key, None)
input_shutdowns = getattr(self, "_steering_input_shutdowns", None)
if input_shutdowns is not None:
input_shutdowns.discard(composite_key)
ambiguous_interrupts = getattr(self, "_ambiguous_interrupts", None)
if ambiguous_interrupts is not None:
ambiguous_interrupts.discard(composite_key)
self._stop_owned_terminal_keys.discard(composite_key)
if not self._has_synthetic_delivery_pending(composite_key):
self._synthetic_pending_owners.pop(composite_key, None)
self._activity_provenance_barriers.discard(composite_key)
self._activity_provenance_barrier_owners.pop(composite_key, None)
self._steering_closing_keys().discard(composite_key)
self._steering_writer_keys().discard(composite_key)
def _advance_steering_generation(
self,
composite_key: str,
) -> None:
current_generation = self._steering_generation(composite_key)
self._steering_generations[composite_key] = current_generation + 1
def _register_native_input(
self,
composite_key: str,
text: str,
*,
kind: Literal["primary", "steer"],
) -> _ClaudeInputReceipt:
receipt = _ClaudeInputReceipt(text=text, kind=kind)
self._native_input_receipt_map().setdefault(composite_key, []).append(receipt)
return receipt
def _native_input_receipt_map(self) -> dict[str, list[_ClaudeInputReceipt]]:
receipts = getattr(self, "_native_input_receipts", None)
if receipts is None:
receipts = {}
self._native_input_receipts = receipts
return receipts
def _remove_native_input_receipt(
self,
composite_key: str,
receipt: _ClaudeInputReceipt,
) -> None:
receipt_map = self._native_input_receipt_map()
receipts = receipt_map.get(composite_key) or []
for index, candidate in enumerate(receipts):
if candidate is receipt:
receipts.pop(index)
break
if not receipts:
receipt_map.pop(composite_key, None)
@staticmethod
def _native_user_input_text(message) -> str | None:
if getattr(message, "parent_tool_use_id", None) is not None:
return None
content = getattr(message, "content", None)
if isinstance(content, str):
return content
if isinstance(content, list):
texts = [
block.text
for block in content
if isinstance(block, TextBlock) and isinstance(block.text, str)
]
if len(texts) == len(content):
return "\n".join(texts)
return None
@staticmethod
def _echoed_receipt_run(
receipts: list[_ClaudeInputReceipt],
text: str,
) -> tuple[int, int] | None:
"""Return the earliest contiguous receipt run one native echo replays.
Claude dequeues every input queued behind a running response together
and replays them as one top-level user message joined by newlines.
"""
for start in range(len(receipts)):
joined = receipts[start].text
end = start + 1
while True:
if joined == text:
return start, end
if end == len(receipts) or not text.startswith(f"{joined}\n"):
break
joined = f"{joined}\n{receipts[end].text}"
end += 1
return None
def _observe_native_user_input(
self,
composite_key: str,
message,
) -> list[_ClaudeInputReceipt]:
text = self._native_user_input_text(message)
if text is None:
return []
receipt_map = self._native_input_receipt_map()
receipts = receipt_map.get(composite_key) or []
if not receipts:
return []
origin = self._result_origin_kind(message)
if origin not in {None, "human"}:
# Injected turns (task notifications, peers, ...) are never Avibe
# input, even when their text happens to equal a receipt.
return []
run = self._echoed_receipt_run(receipts, text)
if run is None:
# A human or origin-less replay is Avibe input in a shape the receipts
# do not model. The stream gives no sound boundary for which receipts
# it covers, so they stay pending; make the drift loud instead of
# guessing.
logger.warning(
"Claude replayed input that matches no pending receipt for %s; "
"%d input receipt(s) remain pending",
composite_key,
len(receipts),
)
return []
start, end = run
consumed = receipts[start:end]
del receipts[start:end]
if not receipts:
receipt_map.pop(composite_key, None)
for receipt in consumed:
logger.debug(
"Observed Claude %s input receipt for %s",
receipt.kind,
composite_key,
)
return consumed
def _pending_steering_input_state(self, composite_key: str) -> str | None:
for receipt in self._native_input_receipt_map().get(composite_key) or []:
if receipt.kind == "steer":
return receipt.state
return None
def _discard_completed_primary_input_receipts(self, composite_key: str) -> None:
receipt_map = self._native_input_receipt_map()
receipts = receipt_map.get(composite_key) or []
receipts[:] = [receipt for receipt in receipts if receipt.kind != "primary"]
if not receipts:
receipt_map.pop(composite_key, None)
def _clear_native_input_receipts(self, composite_key: str) -> None:
self._native_input_receipt_map().pop(composite_key, None)
def _terminal_claim_superseded(
self,
composite_key: str,
expected_steering_generation: int,
) -> bool:
"""Whether a terminal frame arrived before Claude echoed the steer input."""
generation_changed = expected_steering_generation != self._steering_generation(
composite_key
)
return generation_changed or self._pending_steering_input_state(composite_key) is not None
@staticmethod
def _steering_input_closer(client):
end_input = getattr(client, "end_input", None)
if callable(end_input):
return end_input
end_input = getattr(getattr(client, "_transport", None), "end_input", None)
return end_input if callable(end_input) else None
def _steering_input_shutdown_keys(self) -> set[str]:
shutdowns = getattr(self, "_steering_input_shutdowns", None)
if shutdowns is None:
shutdowns = set()
self._steering_input_shutdowns = shutdowns
return shutdowns
def _ambiguous_interrupt_keys(self) -> set[str]:
interrupts = getattr(self, "_ambiguous_interrupts", None)
if interrupts is None:
interrupts = set()
self._ambiguous_interrupts = interrupts
return interrupts
async def _close_steering_input(
self,
composite_key: str,
end_input,
) -> str | None:
"""Half-close input after a write whose acceptance is ambiguous."""
# An ambiguous writer cannot accept another steer safely. EOF bounds the
# reconciliation while preserving any prompt that reached Claude.
self._steering_input_shutdown_keys().add(composite_key)
try:
await end_input()
return None
except Exception as exc: # noqa: BLE001 - the existing receiver keeps ownership
logger.warning(
"Failed to half-close Claude steering input for %s; preserving the live receiver",
composite_key,
exc_info=True,
)
return str(exc)
async def steer_active_turn(
self,
request: SteerRequest,
target: ActiveSteerTarget,
) -> SteerResult:
composite_key = target.runtime_key
async with self._steering_lock(composite_key):
client = self.claude_sessions.get(composite_key)
receiver_task = self.receiver_tasks.get(composite_key)
active_sessions = getattr(self.session_handler, "active_sessions", set())
if (
client is None
or receiver_task is None
or receiver_task.done()
or composite_key not in active_sessions
or composite_key in self._steering_closing_keys()
or composite_key in self._steering_input_shutdown_keys()
or composite_key in self._ambiguous_interrupt_keys()
):
return steer_result(
SteerOutcome.REFUSED,
reason="runtime_unavailable",
backend=self.name,
)
native_turn_id = f"claude:{composite_key}:{id(client)}:{id(receiver_task)}"
if native_turn_id != request.expected_native_turn_id:
return steer_result(
SteerOutcome.NOT_ACTIVE,
reason="stale_native_turn",
backend=self.name,
)
primary_requests = self._pending_requests.get(composite_key)
if not primary_requests or primary_requests[0] is not target.agent_request:
return steer_result(
SteerOutcome.NOT_ACTIVE,
reason="primary_turn_changed",
backend=self.name,
)
primary_request_count = len(primary_requests)
end_input = self._steering_input_closer(client)
if end_input is None:
return steer_result(
SteerOutcome.REFUSED,
reason="native_input_reconciliation_unsupported",
backend=self.name,
)
writers = self._steering_writer_keys()
writers.add(composite_key)
message = self.render_input(message_with_files(request.text, request.files), request.input_metadata)
input_receipt = self._register_native_input(
composite_key,
message,
kind="steer",
)
try:
try:
await self._write_human_query(
client,
composite_key,
message,
target.agent_request.context,
)
except ClaudeInputNotSentError as exc:
self._remove_native_input_receipt(composite_key, input_receipt)
return steer_result(
SteerOutcome.REFUSED,
reason="runtime_generation_changed",
backend=self.name,
diagnostic=exc.reason,
)
except (asyncio.TimeoutError, TimeoutError) as exc:
input_receipt.state = "unknown"
self._advance_steering_generation(composite_key)
await self._close_steering_input(
composite_key,
end_input,
)
return steer_result(
SteerOutcome.UNKNOWN,
reason="acknowledgement_ambiguous",
backend=self.name,
diagnostic=str(exc),
)
except Exception as exc: # noqa: BLE001 - SDK transports expose several concrete types
diagnostic = str(exc)
lowered = diagnostic.lower()
if any(
marker in lowered
for marker in (
"failed to write",
"broken pipe",
"connection reset",
"timed out",
"timeout",
"disconnected",
"connection lost",
"unexpected eof",
)
):
input_receipt.state = "unknown"
self._advance_steering_generation(composite_key)
await self._close_steering_input(
composite_key,
end_input,
)
return steer_result(
SteerOutcome.UNKNOWN,
reason="acknowledgement_ambiguous",
backend=self.name,
diagnostic=diagnostic,
)
if any(
marker in lowered
for marker in (
"not connected",
"not ready for writing",
"terminated process",
"process that exited with error",
)
):
self._remove_native_input_receipt(composite_key, input_receipt)
return steer_result(
SteerOutcome.REFUSED,
reason="runtime_unavailable",
backend=self.name,
diagnostic=diagnostic,
)
input_receipt.state = "unknown"
self._advance_steering_generation(composite_key)
await self._close_steering_input(
composite_key,
end_input,
)
return steer_result(
SteerOutcome.UNKNOWN,
reason="unclassified_transport_failure",
backend=self.name,
diagnostic=diagnostic,
)
finally:
writers.discard(composite_key)
runtime_stable = not (
self.claude_sessions.get(composite_key) is not client
or self.receiver_tasks.get(composite_key) is not receiver_task
or receiver_task.done()
or composite_key in self._steering_closing_keys()
or self._pending_requests.get(composite_key) is not primary_requests
or len(primary_requests) != primary_request_count
or primary_requests[0] is not target.agent_request
)
if not runtime_stable:
input_receipt.state = "unknown"
self._advance_steering_generation(composite_key)
close_diagnostic = await self._close_steering_input(
composite_key,
end_input,
)
if close_diagnostic is not None:
return steer_result(
SteerOutcome.UNKNOWN,
reason="native_input_close_failed",
backend=self.name,
diagnostic=close_diagnostic,
)
return steer_result(
SteerOutcome.UNKNOWN,
reason="receiver_generation_changed",
backend=self.name,
)
input_receipt.state = "accepted"
self._advance_steering_generation(composite_key)
return steer_result(
SteerOutcome.ACCEPTED,
backend=self.name,
receiver_generation=native_turn_id,
)
async def handle_stop(self, request: AgentRequest) -> bool:
composite_key = request.composite_session_id
if composite_key not in self.claude_sessions:
if self._has_synthetic_delivery_pending(composite_key):
# Terminal delivery already owns this turn. There is no native
# work left to interrupt and Stop must not steal its receipt.
self._schedule_completed_activity_flush(composite_key, request.context)
return True
request.stop_failure_reason = "not_active"
return False
client = self.claude_sessions[composite_key]
if not hasattr(client, "interrupt"):
request.stop_failure_reason = "unsupported"
await emit_output(
self.controller, request.context, Notice("⚠️ This Claude session cannot be interrupted; consider /new.")
)
return False
try:
stopped_request = None
retained_terminal_owner = False
async with self._steering_lock(composite_key):
if (
self.claude_sessions.get(composite_key) is not client
or composite_key in self._steering_closing_keys()
or composite_key in self._ambiguous_interrupt_keys()
):
request.stop_failure_reason = "not_active"
return False
self._steering_closing_keys().add(composite_key)
try:
await client.interrupt()
except Exception:
self._steering_closing_keys().discard(composite_key)
self._ambiguous_interrupt_keys().add(composite_key)
raise
stop_epoch = self._advance_steering_stop_epoch(composite_key)
# Claim the pending Result owner before releasing the lock. A
# terminal frame queued behind interrupt must not settle this
# stopped Turn as a successful result.
retained_terminal_owner = self._has_synthetic_delivery_pending(composite_key)
if not retained_terminal_owner:
stopped_request = self._pop_pending_request(composite_key)
if stopped_request is not None:
self._stop_owned_terminal_keys.add(composite_key)
self._stop_owned_terminal_epochs[composite_key] = stop_epoch
except Exception as err:
request.stop_failure_reason = "interrupt_failed"
logger.error(f"Failed to interrupt Claude session {composite_key}: {err}")
await emit_output(
self.controller, request.context, Notice("⚠️ Failed to interrupt Claude session. Please try /new.")
)
return False
self._requeue_request_activity(stopped_request)
self._adopt_pending_turn_token(request.context, stopped_request)
if stopped_request is not None:
try:
# Registry only: ``finish()`` below owns removing the 👀 and
# putting ⏹️ in its place, and it can only do that if the
# reaction is still on the message when it runs.
await self._remove_specific_pending_reaction(
composite_key,
request.context,
stopped_request,
clear_on_platform=False,
)
await self._remove_ack_reaction(
stopped_request,
terminal_emoji=STOPPED_REACTION_EMOJI,
)
except Exception:
logger.debug("Failed to clear Claude stop processing indicator", exc_info=True)
self._suppress_receiver_runtime_release.add(composite_key)
try:
self._mark_session_idle_if_no_pending_requests(composite_key)
await self._cleanup_runtime_session(
composite_key,
reason="user_stop",
)
except Exception as err:
logger.error("Failed to clean up stopped Claude session %s: %s", composite_key, err, exc_info=True)
self._release_service_runtime_turn(request.context)
raise
finally:
self._suppress_receiver_runtime_release.discard(composite_key)
if retained_terminal_owner:
self._schedule_completed_activity_flush(composite_key, request.context)
return True
try:
# A user-initiated stop is terminal but intentional, so it carries
# NO user-facing message: a single SILENT result settles the dot to
# idle + releases the SSE waiter through the outbound chokepoint
# WITHOUT a bubble. IM says it in the reaction instead — the ⏹️
# stamped above is the receipt, at no cost in thread noise. Emit
# only after cleanup so the next turn cannot
# acquire the gate and reuse a client that this stop is still
# disconnecting. ``stop_output_for`` (not the terminal-turn default) keeps
# this empty body out of the run's terminal state so the stop settles it
# ``canceled`` instead of ``succeeded`` — see its docstring.
await emit_output(
self.controller,
request.context,
TurnEnd(outcome=TurnOutcome.STOPPED, silent=True, output=terminal_output_for(request)),
)
except Exception as err:
logger.error("Failed to emit Claude stop result for session %s: %s", composite_key, err, exc_info=True)
self._release_service_runtime_turn(request.context)
return True
async def release_native_runtime(self, request: AgentRequest) -> None:
"""End the SDK client an earlier Claude phase of this Session left cached.
A cached client is reused before the row is consulted, and it still holds
the conversation the backend switch replaced.
"""
composite_key = self.runtime_turn_key(request)
if composite_key and composite_key in self.claude_sessions:
await self.end_runtime_session(composite_key)
async def end_runtime_session(self, composite_key: str) -> bool:
"""Interrupt and clean up one runtime without racing native steering."""
async with self._steering_lock(composite_key):
client = self.claude_sessions.get(composite_key)
if client is None:
return False
self._steering_closing_keys().add(composite_key)
try:
if hasattr(client, "interrupt"):
await client.interrupt()
except Exception: # noqa: BLE001 - operational End remains best-effort
logger.debug(
"Failed to interrupt Claude runtime before ending %s",
composite_key,
exc_info=True,
)
await self._cleanup_runtime_session(
composite_key,
reason="running_agent_end",
)
return True
def _receiver_generation_current(
self, composite_key: str, client,
identity: RuntimeActivationIdentity | None,
) -> bool:
current = self.claude_sessions.get(composite_key)
if current is not None and current is not client:
return False
service = getattr(self.controller, "agent_service", None)
registry = getattr(service, "activation_registry", None)
if identity is not None and isinstance(registry, RuntimeActivationRegistry):
return registry.current(identity.backend, identity.resource_key) is identity
return True
async def _receive_messages(
self,
client,
base_session_id: str,
working_path: str,
context: MessageContext,
*,
composite_key: str | None = None,
receiver_activation_identity: RuntimeActivationIdentity | None = None,
):
"""Receive messages from Claude SDK client."""
receiver_steering_lock = None
try:
session_key = self.controller._get_session_key(context)
composite_key = composite_key or f"{base_session_id}:{working_path}"
if receiver_activation_identity is None:
receiver_activation_identity = self._client_activation_identity(client)
receiver_steering_lock = self._steering_lock(composite_key)
receiver_stop_epoch = self._steering_stop_epoch(composite_key)
self._set_activity_connection(
composite_key,
context,
"connected",
activation_identity=receiver_activation_identity,
)
# Build a request object for question handler
request = AgentRequest(
context=context,
message="",
user_message="",
working_path=working_path,
base_session_id=base_session_id,
composite_session_id=composite_key,
session_key=session_key,
)
message_stream = client.receive_messages().__aiter__()
# Claude runs one turn at a time and replays the input that starts
# a human turn before any Assistant frame of it. The first content
# frame after a Result therefore names what started the turn: an
# input origin kind, or "" when anything else comes first, such as
# Assistant output from a task notification. ``None`` means unseen.
# A client's first receiver starts before its first turn. A later
# receiver may start inside a turn it cannot see the start of, so
# no frame before its first Result proves an owner.
joined_running_client = getattr(client, "_vibe_receiver_attached", False)
setattr(client, "_vibe_receiver_attached", True)
turn_origin: str | None = "" if joined_running_client else None
# Each Result ends one native response phase. The pending human-path
# Assistant text belongs to a phase only if this receiver set it there.
response_phase = object()
ending_phase = None
pending_assistant_phase = None
while True:
settling_ambiguous_primary = False
settling_ambiguous_assistant_text = None
settling_ambiguous_had_foreground_tools = False
# Capture the steering generation before waiting for the next
# native frame. A frame already buffered in the SDK must retain
# the ownership state at the time its receive was started.
terminal_steering_generation = self._steering_generation(composite_key)
try:
message = await anext(message_stream)
except StopAsyncIteration:
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
buffered = self._ambiguous_primary_results.pop(composite_key, None)
if buffered is None:
break
(
message,
settling_ambiguous_assistant_text,
settling_ambiguous_had_foreground_tools,
) = self._unpack_buffered_terminal(buffered)
settling_ambiguous_primary = True
except Exception:
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
buffered = self._ambiguous_primary_results.pop(composite_key, None)
if buffered is None:
raise
(
message,
settling_ambiguous_assistant_text,
settling_ambiguous_had_foreground_tools,
) = self._unpack_buffered_terminal(buffered)
settling_ambiguous_primary = True
logger.warning(
"Settling buffered Claude primary result after receiver failure for %s",
composite_key,
exc_info=True,
)
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
if settling_ambiguous_primary:
await self._cleanup_runtime_session_state(
composite_key,
current_receiver_task=asyncio.current_task(),
preserve_pending_request_state=True,
reason="ambiguous_primary_receiver_failure",
)
if settling_ambiguous_assistant_text:
self._last_assistant_text[composite_key] = (
settling_ambiguous_assistant_text
)
if settling_ambiguous_had_foreground_tools:
self._turns_with_foreground_tools.add(composite_key)
try:
claude_session_id = self._maybe_capture_session_id(
message,
base_session_id,
session_key,
context,
working_path=working_path,
)
if claude_session_id:
self._native_session_ids[composite_key] = claude_session_id
runtime_client = self.claude_sessions.get(composite_key)
if runtime_client is client:
setattr(runtime_client, "_vibe_native_session_id", claude_session_id)
register_claude_owned_process(
runtime_client,
native_session_id=claude_session_id,
owner=AVIBE_CLAUDE_SESSION_OWNER,
)
logger.info(f"Captured Claude session id {claude_session_id} for {base_session_id}")
if self._handle_activity_message(
message,
composite_key,
context,
activation_identity=receiver_activation_identity,
):
registry = self._activity_registry()
if registry is not None and registry.has_completed_output(
self.name,
composite_key,
):
self._schedule_completed_activity_flush(composite_key, context)
continue
if self.claude_client._is_skip_message(message):
continue
message_type = self._detect_message_type(message)
if message_type not in {"assistant", "result", "system"}:
terminal_steering_generation = None
if message_type == "result":
turn_origin = None
ending_phase, response_phase = response_phase, object()
elif message_type == "assistant" and turn_origin is None:
turn_origin = ""
if message_type == "user":
if turn_origin is None:
# A frame without origin, such as a tool result,
# means this receiver joined the turn after it
# started, so its owner is unproven.
turn_origin = self._result_origin_kind(message) or ""
async with self._steering_lock(composite_key):
receipts = self._observe_native_user_input(
composite_key,
message,
)
if any(receipt.kind == "steer" for receipt in receipts):
await self._retire_primary_phase_on_steer_receipt(
context,
composite_key,
)
continue
formatter = self._get_formatter(context)
is_model_refusal_fallback = self._is_model_refusal_fallback_message(message)
model_refusal_fallback_notice = (
self._parse_model_refusal_fallback_notice(message)
if is_model_refusal_fallback
else None
)
# Unsolicited backend output (a background-task completion or
# a ScheduleWakeup re-invoked the agent inside this SDK
# process) reaches this long-lived receiver with no Avibe turn
# open. Open an agent-initiated turn so the reply is persisted
# + delivered + notified instead of dropped by the outbound
# active-turn guard. An actionable refusal-fallback frame is
# the one user-facing system exception: it belongs to the
# replacement run and must use that run's turn.
output_mode = None
result_owner = "agent"
if message_type == "result":
# Stop's interrupt may await before claiming its epoch.
# Observe its decision under the existing admission
# fence before classification, replay, or detached routing.
async with self._steering_lock(composite_key):
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
if self._stop_owned_result_for_receiver(
composite_key,
receiver_stop_epoch,
):
self._clear_result_phase_state(composite_key)
self._stop_owned_terminal_keys.discard(composite_key)
logger.info(
"Suppressing Claude terminal result owned by Stop for %s",
composite_key,
)
continue
result_owner = self._result_owner(composite_key, message)
self._resolve_provisional_phase(
composite_key,
context,
owner=result_owner,
terminal_message=message,
)
buffer_assistant = (
message_type == "assistant"
and self._should_buffer_assistant_message(composite_key)
)
# A proven human turn takes the path its human Result would
# replay it on, only earlier: attributed to the pending
# request and never claiming Activity output.
proven_human_frame = (
buffer_assistant
and self._turn_answers_pending_human(composite_key, turn_origin)
)
if buffer_assistant and not proven_human_frame:
# TaskStarted can legally arrive before the terminal
# Result. Record foreground tool ownership now, while
# the visible assistant/toolcall output remains buffered
# until Result.origin classifies the phase.
for block in getattr(message, "content", []) or []:
if isinstance(block, ToolUseBlock):
self._track_tool_activity_mode(
composite_key,
block,
detached=False,
provisional=True,
)
self._buffered_assistant_messages.setdefault(
composite_key,
[],
).append((message, terminal_steering_generation))
logger.debug(
"Buffered Claude Assistant frame until terminal provenance "
"is known for %s",
composite_key,
)
continue
if (
message_type in ("assistant", "result")
or model_refusal_fallback_notice is not None
) and not proven_human_frame:
output_mode = await self._maybe_begin_agent_initiated_turn(
context,
composite_key,
base_session_id,
working_path,
session_key,
message_type=message_type,
result_owner=result_owner,
receiver_activation_identity=receiver_activation_identity,
)
if output_mode in {"activity", "detached"}:
record = self._provisional_output_record(composite_key, output_mode)
if record is not None and record.context is None:
record.context = self._snapshot_output_context(context)
if message_type == "assistant":
self.session_handler.touch_session_activity(composite_key)
toolcalls = []
text_parts = []
# AskUserQuestion detection disabled - SDK cannot respond
# ask_user_question_block = None
for block in getattr(message, "content", []) or []:
if isinstance(block, ToolUseBlock):
self._track_tool_activity_mode(
composite_key,
block,
detached=(
output_mode == "detached"
or output_mode == "activity"
),
provisional=bool(
self._pending_requests.get(composite_key)
and output_mode
not in {"detached", "activity"}
),
)
# AskUserQuestion handling disabled - tool is disallowed via ClaudeAgentOptions
# if self.ENABLE_ASK_USER_QUESTION and self._question_handler:
# if self._question_handler.is_ask_user_question(block):
# ask_user_question_block = block
# continue
toolcalls.append(
(
formatter.format_toolcall(
block.name,
block.input,
get_relative_path=lambda path: self.get_relative_path(path, context),
),
formatter.format_toolcall_label(
block.name,
block.input,
get_relative_path=lambda path: self.get_relative_path(path, context),
),
)
)
elif isinstance(block, TextBlock):
text = block.text.strip() if block.text else ""
if text:
text_parts.append(text)
# Update the status footer's session token figure to this
# request's context-window occupancy. SET (not add): the
# latest assistant message reflects current context size,
# so the figure tracks it live and drops after a /compact.
context_tokens = self._extract_context_tokens(message)
if context_tokens:
self.controller.note_session_tokens(context, total=context_tokens)
assistant_text = self._extract_text_blocks(message, context)
if output_mode == "detached":
if assistant_text:
self._retain_detached_unsolicited_assistant_text(
composite_key,
assistant_text,
)
continue
if output_mode == "activity":
record = self._provisional_output_record(composite_key, "activity")
if assistant_text and record is not None:
record.text = assistant_text
continue
failure_disposition = await self._process_assistant_terminal_frame(
context,
composite_key,
message,
assistant_text,
terminal_steering_generation=terminal_steering_generation,
)
if failure_disposition in {"teardown", "superseded"}:
continue
if failure_disposition == "auth":
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
preserve_pending_request_state=True,
reason="assistant_auth_failure",
)
return
if failure_disposition:
continue
if assistant_text:
self._last_assistant_text[composite_key] = assistant_text
pending_assistant_phase = response_phase
pending_requests = self._pending_requests.get(composite_key) or []
pending_request = pending_requests[0] if pending_requests else None
self._adopt_pending_turn_token(context, pending_request)
pending = self._pending_assistant_message.pop(composite_key, None)
if pending:
await emit_output(self.controller, context, Narration(pending))
for toolcall_text, toolcall_label in toolcalls:
# Persisted/verbose text stays the original
# ``format_toolcall`` output; ``status_label`` carries
# the clean claude-pipe label for the concise bubble only.
await emit_output(
self.controller,
context,
ToolActivity(toolcall_text, status_label=toolcall_label),
)
if text_parts:
# Claude writes Markdown; keep it as written, like the
# Result and every other backend's narration.
self._pending_assistant_message[composite_key] = "\n\n".join(
text_parts
)
pending_assistant_phase = response_phase
# AskUserQuestion handling disabled - SDK cannot respond programmatically
# See: https://github.com/anthropics/claude-code/issues/10168
# if self.ENABLE_ASK_USER_QUESTION and ask_user_question_block:
# logger.info(
# "Detected AskUserQuestion for session %s",
# base_session_id,
# )
# answered = await self._question_handler.handle_ask_user_question(
# request=request,
# tool_use_block=ask_user_question_block,
# client=client,
# composite_session_id=composite_key,
# )
# if not answered:
# logger.warning(
# "AskUserQuestion timed out for session %s",
# base_session_id,
# )
# return
# logger.info(
# "AskUserQuestion answered for session %s, continuing",
# base_session_id,
# )
continue
# Match the structured subtype instead of relying only on the
# current SDK's generic SystemMessage class. A future SDK may
# promote this event to a dedicated typed message.
if is_model_refusal_fallback:
if model_refusal_fallback_notice is None:
logger.debug("Ignoring non-actionable Claude refusal fallback for %s", composite_key)
continue
if not self._has_pending_requests(composite_key):
logger.info(
"Dropping Claude refusal fallback for %s without an active turn",
composite_key,
)
continue
await self._handle_model_refusal_fallback(
context,
composite_key,
model_refusal_fallback_notice,
)
continue
if message_type == "system":
formatted_message = self.claude_client.format_message(
message,
get_relative_path=lambda path: self.get_relative_path(path, context),
formatter=formatter,
)
system_is_auth_failure = self._is_auth_failure_result(
getattr(message, "subtype", "") or "",
formatted_message,
)
auth_failure_handled = False
async with self._steering_lock(composite_key):
if (
composite_key in self._steering_closing_keys()
or (
system_is_auth_failure
and self._terminal_claim_superseded(
composite_key,
terminal_steering_generation,
)
)
):
logger.info(
"Ignoring Claude system terminal superseded by steering or teardown for %s",
composite_key,
)
continue
if await self._handle_auth_failure_result(
context,
composite_key,
getattr(message, "subtype", "") or "",
formatted_message,
):
# Retire the failed request from the FIFO (else the next
# successful turn adopts its stale token). Codex P2.
self._retire_failed_auth_turn(composite_key, context)
mark_session_idle = getattr(self.session_handler, "mark_session_idle", None)
if callable(mark_session_idle):
mark_session_idle(composite_key)
await self._clear_pending_reactions(composite_key, context)
auth_failure_handled = True
if auth_failure_handled:
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
preserve_pending_request_state=True,
reason="result_auth_failure",
)
return
continue
if message_type == "result":
replay_baseline = (
self._pending_assistant_message.get(composite_key),
self._last_assistant_text.get(composite_key),
)
if await self._flush_buffered_assistant_messages(
composite_key,
context,
owner=result_owner,
terminal_steering_generation=terminal_steering_generation,
):
self._clear_result_phase_state(composite_key)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
preserve_pending_request_state=True,
reason="assistant_auth_failure",
)
return
# Replayed frames belong to the phase this Result ends.
# Each write stores a fresh object, so identity shows one.
if any(
current is not None and current is not before
for current, before in zip(
(
self._pending_assistant_message.get(composite_key),
self._last_assistant_text.get(composite_key),
),
replay_baseline,
)
):
pending_assistant_phase = ending_phase
raw_result_text = getattr(message, "result", None)
result_text = raw_result_text
if output_mode in {"activity", "detached"}:
record = (
self._provisional_output_record(composite_key, "activity")
if output_mode == "activity"
else self._detached_phase(composite_key)
)
if record is None:
raise RuntimeError("Claude terminal phase has no output owner")
phase_text = None
if pending_assistant_phase is ending_phase:
# This phase streamed Assistant text on the human
# path before its Result proved another owner. The
# record takes it over, so it never replays as the
# next turn's narration or terminal text.
self._pending_assistant_message.pop(composite_key, None)
phase_text = self._last_assistant_text.pop(composite_key, None)
self._classify_output_record(
record, context,
text=self._select_detached_result_text(
composite_key,
message,
raw_result_text,
# The phase text stands in only for an empty body.
record.text
or (None if str(raw_result_text or "").strip() else phase_text),
),
message=message,
)
# Freeze this phase before awaiting any earlier retry.
# Every later Result gets its own record, including a
# failure Result with no preceding Assistant frame.
await self._flush_output_recovery(composite_key, context)
self._clear_detached_foreground_tool_state(composite_key)
self._resolved_provisional_phase_ids.pop(
composite_key,
None,
)
continue
terminal_superseded = False
superseded_result_text = ""
superseded_request = None
failure_disposition = None
async with self._steering_lock(composite_key):
self._pending_assistant_message.pop(composite_key, None)
if self._consume_suppressed_synthetic_result(
composite_key,
message,
raw_result_text,
):
self._last_assistant_text.pop(composite_key, None)
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
continue
if not settling_ambiguous_primary:
await self._emit_buffered_primary_phase(
context,
composite_key,
)
if (
not settling_ambiguous_primary
and self._pending_steering_input_state(composite_key)
== "unknown"
):
self._discard_completed_primary_input_receipts(
composite_key
)
self._ambiguous_primary_results[composite_key] = (
message,
self._last_assistant_text.get(composite_key),
composite_key in self._turns_with_foreground_tools,
)
self._clear_result_phase_state(composite_key)
logger.info(
"Deferring Claude primary result until ambiguous steering reaches native EOF or a later result for %s",
composite_key,
)
continue
if composite_key in self._steering_closing_keys():
logger.info(
"Ignoring Claude terminal result during teardown for %s",
composite_key,
)
continue
terminal_superseded = bool(
not settling_ambiguous_primary
and self._terminal_claim_superseded(
composite_key,
terminal_steering_generation,
)
)
if terminal_superseded:
self._discard_completed_primary_input_receipts(
composite_key
)
pending = self._pending_requests.get(composite_key) or []
superseded_request = pending[0] if pending else None
superseded_result_text = self._select_terminal_text(
composite_key,
raw_result_text,
)
else:
self._clear_native_input_receipts(composite_key)
failure_disposition = await self._handle_terminal_failure_result(
context,
composite_key,
message,
raw_result_text
or self._last_assistant_text.get(composite_key),
)
if failure_disposition == "auth":
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
if failure_disposition == "auth":
pass
elif failure_disposition:
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
continue
if failure_disposition is None:
# ResultMessage.result already contains the last
# AssistantMessage, so only the terminal owner emits it.
pending_request = self._pop_pending_request(composite_key)
if (
self._synthetic_pending_owners.get(composite_key)
is pending_request
):
self._synthetic_pending_owners.pop(
composite_key,
None,
)
self._refresh_activity_provenance_barrier(composite_key)
output_activities = self._request_activities(pending_request)
output_activity = output_activities[-1] if output_activities else None
result_text = self._select_terminal_text(
composite_key,
raw_result_text,
)
if terminal_superseded:
self._adopt_pending_turn_token(context, superseded_request)
if superseded_result_text or self._request_activities(
superseded_request
):
await self._emit_primary_phase_output(
context,
superseded_request,
superseded_result_text,
reply_id=_result_uuid(message),
)
self._clear_result_phase_state(composite_key)
logger.info(
"Kept Claude Turn open across a pre-steer terminal result for %s",
composite_key,
)
continue
if failure_disposition == "auth":
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
preserve_pending_request_state=True,
reason="result_auth_failure",
)
return
# The receiver is long-lived and reused across a session's
# turns, so ``context`` still carries the FIRST turn's
# ``turn_token``. Adopt the token of the turn THIS result
# belongs to (the FIFO-matched pending request) so the
# streaming completion guard in ``_stream_chunk`` correlates
# the result to the live sink instead of rejecting it as a
# stale straggler. No-op for fresh sessions / absent tokens.
self._adopt_pending_turn_token(context, pending_request)
close_after_payload = getattr(context, "platform_specific", None) or {}
backend_cleanup = (
asyncio.Event()
if close_after_payload.get("close_after")
else None
)
if backend_cleanup is not None:
close_after_payload["_close_after_backend_cleanup"] = backend_cleanup
# A terminal result consumes this Turn even when IM delivery
# fails. A failed Activity delivery is requeued below, but its
# retry is detached and cannot reuse this Turn's token.
emit_failed = False
try:
if output_activity is not None:
await self._emit_activity_result(
context,
output_activity,
result_text,
detached=False,
completes_turn=True,
subtype=getattr(message, "subtype", "") or "",
duration_ms=getattr(message, "duration_ms", 0),
request=pending_request,
)
self._clear_request_activities(pending_request)
else:
await self.emit_result_message(
context,
result_text,
subtype=getattr(message, "subtype", "") or "",
duration_ms=getattr(message, "duration_ms", 0),
parse_mode="markdown",
request=pending_request,
)
except ActivityOutputDeliveryError as err:
if not err.delivered or err.durable:
emit_failed = True
self._requeue_request_activity(pending_request)
if not err.delivered:
await self._settle_activity_turn_after_delivery_failure(
context
)
else:
self._schedule_completed_activity_flush(
composite_key,
context,
)
raise
logger.error(
"Delivered Claude Activity batch remains fail-closed "
"after incomplete local settlement (runtime=%s error=%s)",
composite_key,
err,
)
if self._requeue_request_activity_for_local_settlement(
pending_request
):
self._schedule_completed_activity_flush(
composite_key,
context,
)
else:
self._clear_request_activities(pending_request)
except Exception:
emit_failed = True
if output_activity is not None:
self._requeue_request_activity(pending_request)
await self._settle_activity_turn_after_delivery_failure(
context
)
raise
else:
native_session_id = self._native_session_ids.get(composite_key) or self._reserved_native_session_id(
context,
self.name,
) or self._reserved_native_session_id(
getattr(pending_request, "context", None),
self.name,
)
if pending_request is not None and native_session_id:
try:
self._maybe_backfill_session_title(
pending_request,
native_session_id,
)
except Exception:
logger.warning(
"Claude result delivered but session title backfill failed",
exc_info=True,
)
finally:
try:
await self._remove_result_pending_reaction(
composite_key,
context,
pending_request,
)
self._last_assistant_text.pop(composite_key, None)
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
is_idle = self._mark_session_idle_if_no_pending_requests(composite_key)
try:
session = await self.session_manager.get_or_create_session(
context.user_id, context.channel_id
)
if session and is_idle:
session.session_active[composite_key] = False
except Exception:
logger.debug(
"claude: failed to update session_active after result for %s",
composite_key,
exc_info=True,
)
if emit_failed:
self._release_service_runtime_turn(context)
finally:
if backend_cleanup is not None:
backend_cleanup.set()
if close_after_payload.get("_close_after_backend_cleanup") is backend_cleanup:
close_after_payload.pop("_close_after_backend_cleanup", None)
if (
result_owner == "human"
and not settling_ambiguous_primary
):
self._refresh_activity_provenance_barrier(composite_key)
registry = self._activity_registry()
if (
registry is not None
and registry.has_completed_output(
self.name,
composite_key,
)
):
self._schedule_completed_activity_flush(
composite_key,
context,
expected_steering_generation=(
self._steering_generation(composite_key)
),
)
if settling_ambiguous_primary:
return
continue
# Ignore UserMessage/tool results; toolcalls are emitted from ToolUseBlock.
continue
except Exception as e:
logger.error(f"Error processing message from Claude: {e}", exc_info=True)
continue
# EOF owns terminal settlement. Announce it before awaiting any lock
# so an overlapping write cannot report ACCEPTED with no receiver.
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
self._mark_steering_closing(composite_key)
buffered_failure = await self._replay_buffered_terminal_failures(
composite_key,
context,
terminal_steering_generation=self._steering_generation(composite_key),
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
eof_steering_generation = self._steering_generation(composite_key)
pending_requests = self._pending_requests.get(composite_key) or []
synthetic_delivery_pending = self._has_synthetic_delivery_pending(
composite_key
)
# A failed detached emit still has a live synthetic owner. It is not
# an EOF-without-result turn: settle the retained output first so
# _handle_receiver_eof cannot replace it with a generic error or
# release the gate before durable delivery.
had_pending_requests = bool(pending_requests) and not synthetic_delivery_pending
if had_pending_requests:
if buffered_failure is None:
await self._handle_receiver_eof(
composite_key, context,
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
else:
await self._handle_receiver_eof(
composite_key,
context,
buffered_failure=buffered_failure,
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
await self._flush_completed_activity_outputs(
composite_key,
context,
expected_steering_generation=eof_steering_generation,
allow_closing=True,
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
await self._flush_detached_activity_output(composite_key, context)
if synthetic_delivery_pending:
# The receiver generation is dead even when its detached
# recovery owner remains alive. Retire only this exact client;
# the retained owner and gate are generation-independent.
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=client,
preserve_pending_request_state=True,
reason="receiver_eof_with_retained_detached_output",
)
return
if not had_pending_requests and not self._has_pending_requests(composite_key):
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=client,
preserve_pending_request_state=True,
reason="receiver_eof",
)
return
except asyncio.CancelledError:
# Receiver task was explicitly cancelled (e.g. /stop, /clear,
# or a new message replacing the session). Clean up reactions
# because this receiver will never process another result.
composite_key = composite_key or f"{base_session_id}:{working_path}"
logger.info("Claude receiver cancelled for session %s", composite_key)
if self._receiver_generation_current(composite_key, client, receiver_activation_identity):
retained_owner = self._has_synthetic_delivery_pending(composite_key)
if not retained_owner:
self._mark_session_idle_if_no_pending_requests(composite_key)
await self._clear_pending_reactions(
composite_key, context, preserve_pending_requests=retained_owner,
)
if composite_key not in self._suppress_receiver_runtime_release and not retained_owner:
self._release_service_runtime_turn(context)
raise
except Exception as e:
composite_key = composite_key or f"{base_session_id}:{working_path}"
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
# Close admission before replaying the prior turn's failure. The
# replay is explicitly allowed to settle that already-buffered
# failure, while every new native write sees the closing fence.
self._mark_steering_closing(composite_key)
buffered_failure = await self._replay_buffered_terminal_failures(
composite_key,
context,
terminal_steering_generation=self._steering_generation(composite_key),
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
logger.error(
f"Error in Claude receiver for session {composite_key}: {e}",
exc_info=True,
)
await self._handle_receiver_exception(
composite_key,
context,
e,
buffered_failure=buffered_failure,
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
if not self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
):
return
await self._flush_completed_activity_outputs(
composite_key,
context,
expected_steering_generation=self._steering_generation(composite_key),
allow_closing=True,
expected_client=client,
expected_activation_identity=receiver_activation_identity,
)
await self._flush_detached_activity_output(composite_key, context)
# NOTE: no `finally` cleanup of pending reactions here.
# When the receiver ends normally (stream exhausted after a result),
# new messages may have already queued their reactions via
# handle_message(). Blindly clearing them here would remove the
# 👀 for an in-flight request that hasn't produced a result yet.
# The except blocks above handle the cancel/error cases; the
# normal-result case is handled by _remove_pending_reaction()
# inside the loop.
finally:
owns_generation = self._receiver_generation_current(
composite_key, client, receiver_activation_identity,
)
if owns_generation:
self._suppressed_synthetic_results.discard(composite_key)
self._suppressed_synthetic_error_text.pop(composite_key, None)
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
self._clear_detached_foreground_tool_state(composite_key)
self._retire_output_generation(composite_key, client, context)
if any(
record.lifecycle == "delivery_pending"
for record in self._output_records_for_runtime(composite_key)
):
self._schedule_completed_activity_flush(composite_key, context)
self._end_activity_runtime(
composite_key,
activation_identity=receiver_activation_identity,
)
if composite_key is not None and owns_generation:
self._retire_steering_state(
composite_key,
expected_lock=receiver_steering_lock,
)
async def _replay_buffered_terminal_failures(
self,
composite_key: str,
context: MessageContext,
*,
terminal_steering_generation: int,
expected_client,
expected_activation_identity: RuntimeActivationIdentity | None,
) -> _BufferedClaudeFailureReplay | None:
"""Replay buffered structured failures before receiver-end settlement.
Origin-less Assistant text is intentionally not replayed here: without a
terminal Result it has no safe owner. Structured failure frames are
different because ``_process_assistant_terminal_frame`` already owns the
shared teardown, steering, receipt, and synthetic-result policy.
"""
if not self._buffered_assistant_messages.get(composite_key):
return None
async with self._steering_lock(composite_key):
if not self._receiver_generation_current(
composite_key, expected_client, expected_activation_identity,
):
return None
messages = self._buffered_assistant_messages.pop(composite_key, None)
if not messages:
return None
for message, frame_steering_generation in messages:
if message is _STEER_BOUNDARY:
continue
try:
text = self._extract_text_blocks(message, context)
except Exception:
text = str(getattr(message, "result", "") or "")
logger.warning(
"Failed to extract buffered Claude Assistant failure text for %s",
composite_key,
exc_info=True,
)
diagnostic = self._terminal_backend_failure(message, text)
if diagnostic is None:
continue
try:
disposition = await self._process_assistant_terminal_frame(
context,
composite_key,
message,
text,
terminal_steering_generation=(
frame_steering_generation
if frame_steering_generation is not None
else terminal_steering_generation
),
allow_closing=True,
expected_client=expected_client,
expected_activation_identity=expected_activation_identity,
)
except asyncio.CancelledError:
raise
except Exception:
# The receiver-end path must still run even if recording or
# emitting the replayed failure fails. The pending request is
# deliberately left for that path to settle conservatively.
logger.warning(
"Failed to replay buffered Claude terminal failure for %s",
composite_key,
exc_info=True,
)
return _BufferedClaudeFailureReplay(
diagnostic=diagnostic,
replay_failed=True,
)
if disposition == "auth":
return _BufferedClaudeFailureReplay(
diagnostic=diagnostic,
auth_handled=True,
)
if disposition == "failure":
return _BufferedClaudeFailureReplay(diagnostic=diagnostic)
return None
async def _handle_receiver_eof(
self,
composite_key: str,
context: MessageContext,
*,
buffered_failure: _BufferedClaudeFailureReplay | None = None,
expected_client=None,
expected_activation_identity: RuntimeActivationIdentity | None = None,
) -> None:
"""Settle a Claude receiver that ended without a ResultMessage."""
async with self._steering_lock(composite_key):
if expected_client is not None and not self._receiver_generation_current(
composite_key, expected_client, expected_activation_identity,
):
return
pending_request = self._pop_pending_request(composite_key)
if pending_request is None:
return
pending_token = str(
(
getattr(
getattr(pending_request, "context", None),
"platform_specific",
None,
)
or {}
).get(AGENT_RUNTIME_TURN_TOKEN)
or ""
)
if not pending_token:
self._pending_requests.setdefault(composite_key, []).insert(0, pending_request)
return
# The receiver context may belong to an earlier turn. Adopt the FIFO
# owner's identity before any visible or durable failure output.
self._adopt_pending_turn_token(context, pending_request)
terminal_error = (
buffered_failure.diagnostic
if buffered_failure is not None and buffered_failure.replay_failed
else "Claude receiver ended without a terminal result"
)
client = expected_client or self.claude_sessions.get(composite_key)
returncode = get_claude_client_returncode(client)
auth_handled = False
# Only the ``handle_session_error`` branch below can classify this EOF as a
# teardown the service performed itself. Every other way out of the branch
# tree -- no returncode, no handler, auth recovery -- has no classification
# to offer, and the settlement at the bottom is shared by all of them, so
# the default has to be "not contained": an unclassified EOF is a real
# failure and must keep saying so.
contained = False
# A failed replay is only a diagnostic. The still-owned request needs
# the ordinary no-result settlement below, before releasing its gate.
if buffered_failure is not None and not buffered_failure.replay_failed:
if buffered_failure.auth_handled:
self._retire_failed_auth_turn(
composite_key,
context,
failed_request=pending_request,
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=client,
preserve_pending_request_state=True,
reason="receiver_auth_failure",
)
await self._remove_ack_reaction(pending_request)
self._discard_pending_reaction(composite_key)
await self._clear_pending_reactions(composite_key, context)
self._mark_session_idle_if_no_pending_requests(composite_key)
self._release_service_runtime_turn(context)
return
diagnostic = buffered_failure.diagnostic
self._requeue_request_activity(pending_request)
handle_session_error = getattr(self.session_handler, "handle_session_error", None)
if callable(handle_session_error):
contained = (
await handle_session_error(
composite_key,
context,
RuntimeError(diagnostic),
client=client,
)
is True
)
logger.warning(
"Claude receiver ended after buffered terminal failure for session %s",
composite_key,
)
await self._remove_specific_pending_reaction(composite_key, context, pending_request)
await self._remove_ack_reaction(pending_request)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._refresh_activity_provenance_barrier(composite_key)
self._mark_session_idle_if_no_pending_requests(composite_key)
if returncode is None or not callable(handle_session_error):
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=client,
preserve_pending_request_state=True,
reason="receiver_eof_after_buffered_failure",
)
self._release_service_runtime_turn(context)
return
if returncode is not None:
eof_error = RuntimeError(terminal_error)
diagnostic = self._claude_error_diagnostic(
composite_key,
eof_error,
client=client,
)
error_notify = self._format_error_notify(
eof_error,
composite_key=composite_key,
client=client,
)
failure_context = getattr(pending_request, "context", context)
intentional_teardown = self._teardown_is_intentional(
composite_key, eof_error, client=client
)
if not intentional_teardown:
await self.record_model_hub_native_failure(failure_context, diagnostic)
auth_handled = await self._offer_auth_recovery(
context,
error_notify,
client=client,
output=terminal_output_for(pending_request),
terminal_error=diagnostic,
)
if auth_handled:
self._retire_failed_auth_turn(
composite_key,
context,
failed_request=pending_request,
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=client,
preserve_pending_request_state=True,
reason="receiver_auth_failure",
)
if pending_request is not None:
await self._remove_ack_reaction(pending_request)
self._discard_pending_reaction(composite_key)
await self._clear_pending_reactions(composite_key, context)
self._mark_session_idle_if_no_pending_requests(composite_key)
else:
self._requeue_request_activity(pending_request)
handle_session_error = getattr(self.session_handler, "handle_session_error", None)
if callable(handle_session_error):
contained = (
await handle_session_error(
composite_key, context, eof_error, client=client
)
is True
)
# A teardown the service performed itself is already
# explained in the log; do not leave a durable failure row
# for the web Chat to render.
if not contained:
try:
from core.message_mirror import persist_agent_message
notification = backend_failure_notification_output(
context,
"claude",
request=pending_request,
output=terminal_output_for(pending_request),
)
persist_agent_message(
context,
"notify",
error_notify,
metadata=notification.metadata,
native_message_id=notification.idempotency_key,
)
except Exception:
logger.debug(
"claude: failed to persist terminated EOF notification",
exc_info=True,
)
else:
diagnostic = terminal_error
else:
self._requeue_request_activity(pending_request)
diagnostic = terminal_error
if auth_handled:
self._release_service_runtime_turn(context)
return
logger.warning("Claude receiver ended without a result for session %s", composite_key)
await self._remove_specific_pending_reaction(composite_key, context, pending_request)
await self._remove_ack_reaction(pending_request)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._mark_session_idle_if_no_pending_requests(composite_key)
if returncode is None or not callable(getattr(self.session_handler, "handle_session_error", None)):
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=client,
preserve_pending_request_state=True,
reason="receiver_eof_without_result",
)
try:
await self._emit_no_result_settlement(
context,
pending_request,
diagnostic,
contained=contained,
)
finally:
self._release_service_runtime_turn(context)
async def _handle_receiver_exception(
self,
composite_key: str,
context: MessageContext,
error: Exception,
*,
buffered_failure: _BufferedClaudeFailureReplay | None = None,
expected_client=None,
expected_activation_identity: RuntimeActivationIdentity | None = None,
) -> None:
retain_runtime_turn = False
# A receiver exception retires this client generation. Close native
# write admission before any replay or cleanup awaits so a concurrent
# primary/steer cannot enter the dying receiver. Keep the steering
# lock limited to the state snapshot; session cleanup may acquire the
# generation lock and must never do so while this lock is held.
if expected_client is not None and not self._receiver_generation_current(
composite_key, expected_client, expected_activation_identity,
):
return
self._mark_steering_closing(composite_key)
async with self._steering_lock(composite_key):
if expected_client is not None and not self._receiver_generation_current(
composite_key, expected_client, expected_activation_identity,
):
return
mark_session_idle = getattr(self.session_handler, "mark_session_idle", None)
if callable(mark_session_idle):
mark_session_idle(composite_key)
# A reused receiver context can carry an older Turn token. Bind failure
# delivery to the current FIFO head before clearing terminal state.
pending = self._pending_requests.get(composite_key) or []
pending_request = pending[0] if pending else None
self._adopt_pending_turn_token(context, pending_request)
# Clearing reactions can touch the IM adapter, so keep that await out of
# the admission fence as well. The fence is already closed and the
# state snapshot above identifies the failed turn.
synthetic_delivery_pending = self._has_synthetic_delivery_pending(composite_key)
try:
if synthetic_delivery_pending:
await self._clear_pending_reactions(
composite_key,
context,
preserve_pending_requests=True,
)
else:
await self._clear_pending_reactions(composite_key, context)
if (
buffered_failure is None
and synthetic_delivery_pending
):
# The receiver is gone, but the detached output still has a
# durable recovery owner. Do not replace it with a generic
# receiver error or retire the gate before its retry settles.
retain_runtime_turn = True
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=expected_client,
preserve_pending_request_state=True,
reason="receiver_error_with_retained_detached_output",
)
return
if buffered_failure is not None:
if buffered_failure.auth_handled:
if pending_request is not None:
current_pending = self._pending_requests.get(composite_key) or []
self._retire_failed_auth_turn(
composite_key,
context,
failed_request=(
None
if current_pending
and current_pending[0] is pending_request
else pending_request
),
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=expected_client,
preserve_pending_request_state=True,
reason="receiver_error_auth_failure",
)
if pending_request is not None:
await self._remove_ack_reaction(pending_request)
self._discard_pending_reaction(composite_key)
self._refresh_activity_provenance_barrier(composite_key)
self._mark_session_idle_if_no_pending_requests(composite_key)
return
if buffered_failure.replay_failed:
# A replay exception needs the ordinary receiver-error
# fallback, but if the shared terminal path already removed
# the request there is no remaining turn to settle again.
if pending_request is None:
logger.warning(
"Buffered Claude failure replay failed after terminal "
"ownership was already consumed for %s",
composite_key,
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=expected_client,
preserve_pending_request_state=True,
reason="receiver_error_after_buffered_failure",
)
self._refresh_activity_provenance_barrier(composite_key)
return
buffered_failure = None
else:
# The structured failure already emitted the authoritative
# terminal failure. Receiver transport failure is cleanup
# context, not a second user-visible error.
logger.warning(
"Claude receiver error followed buffered terminal failure for %s: %s",
composite_key,
buffered_failure.diagnostic,
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=expected_client,
preserve_pending_request_state=True,
reason="receiver_error_after_buffered_failure",
)
self._refresh_activity_provenance_barrier(composite_key)
self._mark_session_idle_if_no_pending_requests(composite_key)
return
# Read the client once and reuse it for both the health gate and the
# handler, so a replacement registering in between cannot make the
# two disagree about which generation actually failed.
errored_client = expected_client or self.claude_sessions.get(composite_key)
diagnostic = self._claude_error_diagnostic(
composite_key,
error,
client=errored_client,
)
if pending_request is None:
# No Turn is in flight: the last one already settled, and an
# agent-initiated Turn would hold a FIFO entry. Nobody waits on
# this runtime, so its end is no news for the conversation and
# no evidence about a Model Hub source. Retire it quietly, as an
# idle EOF does; the next Turn starts a fresh process.
logger.warning(
"Claude runtime %s ended with no Turn in flight: %s",
composite_key,
diagnostic,
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=errored_client,
preserve_pending_request_state=True,
reason="receiver_error_without_turn",
)
self._refresh_activity_provenance_barrier(composite_key)
return
error_notify = self._format_error_notify(
error,
composite_key=composite_key,
client=errored_client,
)
failure_context = getattr(pending_request, "context", context)
intentional_teardown = self._teardown_is_intentional(
composite_key, error, client=errored_client
)
if not intentional_teardown:
await self.record_model_hub_native_failure(failure_context, diagnostic)
handled = await self._offer_auth_recovery(
context,
error_notify,
client=errored_client,
output=terminal_output_for(pending_request),
terminal_error=diagnostic,
)
if handled:
if pending_request is not None:
current_pending = self._pending_requests.get(composite_key) or []
self._retire_failed_auth_turn(
composite_key,
context,
failed_request=(
None
if current_pending and current_pending[0] is pending_request
else pending_request
),
)
await self._cleanup_runtime_session(
composite_key,
current_receiver_task=asyncio.current_task(),
expected_client=errored_client,
preserve_pending_request_state=True,
reason="receiver_error_auth_failure",
)
if pending_request is not None:
await self._remove_ack_reaction(pending_request)
self._discard_pending_reaction(composite_key)
self._mark_session_idle_if_no_pending_requests(composite_key)
else:
# Give a claimed Activity batch back to the Registry BEFORE the
# terminal emit, exactly as ``_handle_receiver_eof`` does. This
# path only ever peeked at the FIFO head, so a request carrying
# an ``activity_completion_output`` still owned that batch and
# its ``run_ids`` when the receiver died. Emitting on it either
# terminalizes those Runs from an empty body or -- once the
# settlement stops completing the Run -- skips them entirely and
# discards the claim with them. Requeueing resets the request's
# output to the plain terminal shape, so the release below
# carries no provenance it can no longer honour and the batch
# stays deliverable by whoever claims it next.
self._requeue_request_activity(pending_request)
contained = await self.session_handler.handle_session_error(
composite_key,
context,
error,
client=errored_client,
)
# A teardown the service performed itself is contained: no IM
# message and no durable failure row on any surface.
if contained is not True:
try:
from core.message_mirror import persist_agent_message
notification = backend_failure_notification_output(
context,
"claude",
request=pending_request,
output=terminal_output_for(pending_request),
)
persist_agent_message(
context,
"notify",
error_notify,
metadata=notification.metadata,
native_message_id=notification.idempotency_key,
)
except Exception:
logger.debug(
"claude: failed to persist terminal receiver-error row",
exc_info=True,
)
await self._emit_no_result_settlement(
context,
pending_request,
diagnostic,
contained=contained is True,
)
finally:
if not retain_runtime_turn:
self._release_service_runtime_turn(context)
async def _handle_assistant_terminal_failure(
self,
context: MessageContext,
composite_key: str,
message,
text: str,
) -> str | None:
"""Handle a structured AssistantMessage failure and its paired result."""
diagnostic = self._terminal_backend_failure(message, text)
if diagnostic is None:
return None
handled_auth = await self._settle_terminal_backend_failure(
context,
composite_key,
diagnostic,
)
if handled_auth:
return "auth"
self._suppressed_synthetic_results.add(composite_key)
self._suppressed_synthetic_error_text[composite_key] = diagnostic
return "failure"
async def _process_assistant_terminal_frame(
self,
context: MessageContext,
composite_key: str,
message,
text: str,
*,
terminal_steering_generation: int,
allow_closing: bool = False,
expected_client=None,
expected_activation_identity: RuntimeActivationIdentity | None = None,
) -> str | None:
"""Apply one Assistant failure through the shared steering decision path."""
async with self._steering_lock(composite_key):
if expected_client is not None and not self._receiver_generation_current(
composite_key, expected_client, expected_activation_identity,
):
return "superseded"
if composite_key in self._steering_closing_keys() and not allow_closing:
logger.info(
"Ignoring Claude assistant output during teardown for %s",
composite_key,
)
return "teardown"
diagnostic = self._terminal_backend_failure(message, text)
if (
diagnostic is not None
and self._terminal_claim_superseded(
composite_key,
terminal_steering_generation,
)
):
self._discard_completed_primary_input_receipts(composite_key)
self._suppressed_synthetic_results.add(composite_key)
self._suppressed_synthetic_error_text[composite_key] = diagnostic
logger.info(
"Ignoring Claude terminal assistant failure superseded by steering for %s",
composite_key,
)
return "superseded"
if diagnostic is not None:
self._clear_native_input_receipts(composite_key)
return await self._handle_assistant_terminal_failure(
context,
composite_key,
message,
text,
)
async def _handle_terminal_failure_result(
self,
context: MessageContext,
composite_key: str,
message,
text: str | None,
) -> str | None:
diagnostic = self._terminal_backend_failure(message, text)
if diagnostic is None:
return None
handled_auth = await self._settle_terminal_backend_failure(
context,
composite_key,
diagnostic,
)
return "auth" if handled_auth else "failure"
async def _settle_terminal_backend_failure(
self,
context: MessageContext,
composite_key: str,
diagnostic: str,
) -> bool:
pending_requests = self._pending_requests.get(composite_key) or []
pending_request = pending_requests[0] if pending_requests else None
self._adopt_pending_turn_token(context, pending_request)
logger.warning(
"Claude terminal backend failure for session %s: %s",
composite_key,
diagnostic,
)
failure_context = getattr(pending_request, "context", context)
await self.record_model_hub_native_failure(failure_context, diagnostic)
handled_auth = await emit_backend_failure(
self.controller,
context,
self.name,
diagnostic,
display_text=f"❌ Claude error: {diagnostic}",
request=pending_request,
)
if handled_auth:
self._retire_failed_auth_turn(composite_key, context)
if pending_request is not None:
await self._remove_ack_reaction(pending_request)
self._discard_pending_reaction(composite_key)
await self._clear_pending_reactions(composite_key, context)
self._mark_session_idle_if_no_pending_requests(composite_key)
return True
popped_request = self._pop_pending_request(composite_key)
self._requeue_request_activity(popped_request)
if popped_request is not None:
await self._remove_ack_reaction(popped_request)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._discard_pending_reaction(composite_key)
self._mark_session_idle_if_no_pending_requests(composite_key)
return False
def _consume_suppressed_synthetic_result(self, composite_key: str, message, text: Optional[str]) -> bool:
if composite_key not in self._suppressed_synthetic_results:
return False
expected = " ".join(
self._suppressed_synthetic_error_text.get(composite_key, "").lower().split()
)
actual = " ".join((text or "").lower().split())
same_failure_text = bool(
expected
and actual
and (expected in actual or actual in expected)
)
if (
self._terminal_backend_failure(message, text) is None
and not same_failure_text
and not self._is_malformed_tool_call_retry_failure_result(message, text)
):
self._suppressed_synthetic_results.discard(composite_key)
self._suppressed_synthetic_error_text.pop(composite_key, None)
return False
self._suppressed_synthetic_results.discard(composite_key)
self._suppressed_synthetic_error_text.pop(composite_key, None)
logger.warning(
"Claude paired terminal ResultMessage for session %s suppressed: %s",
composite_key,
text or "<empty>",
)
return True
async def _delete_ack(self, context: MessageContext, request: AgentRequest):
service = getattr(self.controller, "processing_indicator", None)
if service is not None:
await service.delete_ack_message(request, channel_id=context.channel_id)
return
ack_id = request.ack_message_id
if ack_id and hasattr(self.im_client, "delete_message"):
try:
await self.im_client.delete_message(context.channel_id, ack_id)
except Exception as err:
logger.debug("Could not delete ack message: %s", err)
finally:
request.ack_message_id = None
async def _remove_pending_reaction(self, composite_key: str, context: MessageContext) -> None:
"""Remove the oldest stored reaction for a session after result is sent.
The backend turn gate normally leaves at most one pending reaction, but
keep FIFO cleanup for defensive compatibility with older queued state.
"""
reactions = self._pending_reactions.get(composite_key)
if reactions:
# Pop the oldest reaction (FIFO)
message_id, emoji = reactions.pop(0)
# Clean up empty list
if not reactions:
self._pending_reactions.pop(composite_key, None)
try:
await self.im_client.remove_reaction(context, message_id, emoji)
except Exception as err:
logger.debug(f"Failed to remove reaction ack: {err}")
def _discard_pending_reaction(self, composite_key: str) -> None:
reactions = self._pending_reactions.get(composite_key)
if not reactions:
return
reactions.pop(0)
if not reactions:
self._pending_reactions.pop(composite_key, None)
async def _remove_result_pending_reaction(
self,
composite_key: str,
context: MessageContext,
request: Optional[AgentRequest],
) -> None:
reactions_before = len(self._pending_reactions.get(composite_key) or [])
if request is not None:
await self._remove_specific_pending_reaction(composite_key, context, request)
await self._remove_ack_reaction(request)
reactions_after = len(self._pending_reactions.get(composite_key) or [])
if reactions_before and reactions_after == reactions_before:
self._discard_pending_reaction(composite_key)
def _pop_pending_request(self, composite_key: str) -> Optional[AgentRequest]:
requests = self._pending_requests.get(composite_key)
if not requests:
return None
request = requests.pop(0)
self._ambiguous_interrupt_keys().discard(composite_key)
if not requests:
self._pending_requests.pop(composite_key, None)
return request
@staticmethod
def _adopt_pending_turn_token(context: MessageContext, pending_request: Optional[AgentRequest]) -> None:
"""Copy pending Turn identity onto the reused receiver context.
Claude runs one long-lived receiver per runtime session, so the context
captured when it started can carry an older turn's tokens. The web stream
guard uses ``turn_token`` and the shared backend runtime gate uses
``agent_runtime_turn_token``; both must follow the FIFO-matched pending
request before any assistant/tool/result emit. Harness Run attribution is
Turn-scoped too, so replace it rather than leaking a prior receiver turn.
"""
if pending_request is None:
return
src = getattr(pending_request, "context", None)
src_payload = (getattr(src, "platform_specific", None) or {}) if src is not None else {}
token = src_payload.get(AGENT_TURN_TOKEN)
runtime_key = src_payload.get(AGENT_RUNTIME_TURN_KEY)
runtime_token = src_payload.get(AGENT_RUNTIME_TURN_TOKEN)
attribution_keys = (
"task_trigger_kind",
"task_execution_id",
"accepted_agent_run_ids",
"close_after",
)
current_payload = getattr(context, "platform_specific", None) or {}
updates_attribution = any(
key in src_payload or key in current_payload for key in attribution_keys
)
if not (token or runtime_key or runtime_token or updates_attribution):
return
if context.platform_specific is None:
context.platform_specific = {}
if token:
context.platform_specific[AGENT_TURN_TOKEN] = token
if runtime_key:
context.platform_specific[AGENT_RUNTIME_TURN_KEY] = runtime_key
if runtime_token:
context.platform_specific[AGENT_RUNTIME_TURN_TOKEN] = runtime_token
for key in attribution_keys:
if key not in src_payload:
context.platform_specific.pop(key, None)
continue
value = src_payload[key]
if isinstance(value, list):
value = list(value)
if isinstance(value, dict):
value = dict(value)
execution_ids = value.get("execution_ids")
if isinstance(execution_ids, list):
value["execution_ids"] = list(execution_ids)
context.platform_specific[key] = value
def _retire_failed_auth_turn(
self,
composite_key: str,
context: MessageContext,
*,
failed_request: AgentRequest | None = None,
) -> None:
"""Retire a terminal auth-failure turn from the pending FIFO.
The auth error IS this turn's (failed) result, so pop its pending request:
leaving the failed entry would make the next result adopt the old
``turn_token`` — then ``_stream_chunk`` rejects the live turn's completion
and Stop sticks until the safety timeout. Adopt the failed turn's own token
and release its Chat stream now. Called from auth-failure terminal paths
after the recovery notify has been persisted."""
if failed_request is None:
failed_request = self._pop_pending_request(composite_key)
self._requeue_request_activity(failed_request)
self._adopt_pending_turn_token(context, failed_request)
_mark = getattr(self.controller, "mark_turn_complete", None)
if callable(_mark):
_mark(context)
def _has_pending_requests(self, composite_key: str) -> bool:
return bool(self._pending_requests.get(composite_key))
def _activity_registry(self):
service = getattr(self.controller, "agent_service", None)
return getattr(service, "activities", None)
@staticmethod
def _request_activities(request: AgentRequest | None) -> list[SessionActivity]:
if request is None:
return []
return list(getattr(request, "output_activities", None) or [])
async def _retire_synthetic_pending_owner(
self,
composite_key: str,
context: MessageContext,
*,
owner: AgentRequest | None,
is_error: bool = False,
) -> bool:
"""Release this output's captured owner, never the current runtime owner.
Detached output never completes a Turn, so retirement is the synthetic
owner's terminal boundary: it ends the agent-initiated Turn through the
canonical silent result before the gate opens for the next Turn. The
Run, if any, stays with the detached output that already settled it.
"""
synthetic = owner
if (
synthetic is not None
and (
self._request_activities(synthetic)
or any(
record.request is synthetic
for record in self._output_records_for_runtime(composite_key)
)
)
):
# Delivery has not crossed the durable boundary. Keep the same
# owner responsible for the retained payload and its gate.
return False
if synthetic is None:
return False
if self._synthetic_pending_owners.get(composite_key) is synthetic:
self._synthetic_pending_owners.pop(composite_key, None)
pending = self._pending_requests.get(composite_key) or []
if pending and pending[0] is synthetic:
self._pop_pending_request(composite_key)
self._clear_request_activities(synthetic)
self._mark_session_idle_if_no_pending_requests(composite_key)
owner_context = getattr(synthetic, "context", None) or context
# Output arriving while this Turn settles belongs to the next Turn. The
# receiver waits here rather than classifying it against a gate that
# this settling Turn still holds.
settled = asyncio.Event()
self._synthetic_owner_settlements[composite_key] = settled
try:
# Releases the Turn only: another owner settles its Runs.
await emit_output(
self.controller,
owner_context,
TurnEnd(
outcome=TurnOutcome.FAILED if is_error else TurnOutcome.DONE,
output=MessageOutput(completes_turn=True, completes_run=False),
),
)
except BaseException as exc:
# No backend result will ever arrive for this Turn again and its
# record is already gone, so a failed or cancelled settle must still
# latch its outcome and release its waiter rather than wedge the
# Session.
if isinstance(exc, Exception):
logger.warning(
"Agent-initiated turn settle failed for %s", composite_key, exc_info=True,
)
latch = getattr(
getattr(self.controller, "session_turns", None), "on_terminal_result", None,
)
if is_error and callable(latch):
latch(owner_context, is_error=True, settled_by=SETTLED_BY_TURN_ONLY_RESULT)
mark = getattr(self.controller, "mark_turn_complete", None)
if callable(mark):
mark(owner_context, settled_by=SETTLED_BY_TURN_ONLY_RESULT)
if not isinstance(exc, Exception):
raise
finally:
self._release_service_runtime_turn(owner_context)
if self._synthetic_owner_settlements.get(composite_key) is settled:
self._synthetic_owner_settlements.pop(composite_key, None)
settled.set()
return True
def _has_synthetic_delivery_pending(self, composite_key: str) -> bool:
"""Whether a synthetic turn still owns retained detached output."""
synthetic = self._synthetic_pending_owners.get(composite_key)
pending = self._pending_requests.get(composite_key) or []
if synthetic is None and pending:
candidate = pending[0]
if getattr(candidate, "_claude_synthetic_owner", False):
synthetic = candidate
self._synthetic_pending_owners[composite_key] = candidate
if synthetic is None:
# Detached output can coexist with a real pending human request.
# That output needs retry, but it does not own the human turn or
# its runtime gate. Only an explicit synthetic owner may hold the
# gate across receiver cleanup.
return False
return bool(
self._request_activities(synthetic)
or any(
record.request is synthetic
and record.lifecycle == "delivery_pending"
for record in self._output_records_for_runtime(composite_key)
)
)
def _notify_classified_terminal_activities(
self,
activities: list[SessionActivity],
) -> None:
"""Hand deferred terminal Activities to their existing Run owner."""
service = getattr(self.controller, "agent_service", None)
notify = getattr(service, "on_activity_terminal", None)
ack_terminal = getattr(
self._activity_registry(),
"ack_recovered_terminal",
None,
)
for activity in activities:
status = str(getattr(activity, "status", "") or "").strip().lower()
if status not in {
"completed",
"failed",
"stopped",
"killed",
"disconnected",
}:
continue
if getattr(activity, "completed_at", None) is None:
continue
if getattr(activity, "foreground", False):
# A foreground task is one step of its Turn, and the agent can
# recover from a failed step. As on the live path, the Turn's
# Result owns the Run outcome; only the provenance snapshot the
# task kept until that Result arrived is retired here.
if callable(ack_terminal):
try:
ack_terminal(activity)
except Exception:
logger.warning(
"Failed to retire classified foreground Activity %s",
getattr(activity, "id", ""),
exc_info=True,
)
continue
if callable(notify):
notify(activity)
def _attach_request_activities(
self,
request: AgentRequest,
activities: list[SessionActivity],
) -> None:
retained = list(getattr(request, "output_activities", None) or [])
retained_ids = {item.id for item in retained}
for activity in activities:
if activity.id not in retained_ids:
retained.append(activity)
retained_ids.add(activity.id)
registry = self._activity_registry()
bind_batch = getattr(registry, "bind_completed_output_batch", None)
if callable(bind_batch):
retained = list(bind_batch(retained))
request.output_activities = retained
if retained:
request.output = self._activity_message_output(
retained[-1],
activities=retained,
detached=False,
completes_turn=True,
)
@staticmethod
def _requeue_activities(
registry,
activities: list[SessionActivity],
) -> None:
"""Restore a claimed batch to its Registry-owned queue positions."""
registry.requeue_completed_outputs(activities)
@staticmethod
def _requeue_activities_for_local_settlement(
registry,
activities: list[SessionActivity],
) -> bool:
requeue = getattr(
registry,
"requeue_completed_outputs_for_local_settlement",
None,
)
return bool(
callable(requeue)
and requeue(activities) == len(activities)
)
def _claim_activity_batch_for_turns(
self,
registry,
composite_key: str,
turn_ids: set[str],
) -> list[SessionActivity]:
"""Claim one causal batch through the shared Registry transaction."""
return registry.claim_completed_output_batch(
self.name,
composite_key,
turn_ids=turn_ids,
)
@staticmethod
def _request_activity_turn_ids(request: AgentRequest | None) -> set[str]:
activities = ClaudeAgent._request_activities(request)
turn_ids = {
str(activity.turn_id or "").strip()
for activity in activities
}
context = getattr(request, "context", None) if request is not None else None
request_turn_id = str(
((getattr(context, "platform_specific", None) or {}).get(AGENT_TURN_TOKEN))
or ""
).strip()
if request_turn_id:
turn_ids.add(request_turn_id)
turn_ids.discard("")
return turn_ids
def _clear_request_activities(self, request: AgentRequest | None) -> None:
if request is None:
return
request.output_activities = []
def _requeue_request_activity(self, request: AgentRequest | None) -> None:
activities = self._request_activities(request)
if not activities or request is None:
return
registry = self._activity_registry()
if registry is not None:
self._requeue_activities(registry, activities)
self._clear_request_activities(request)
request.output = terminal_turn_output()
def _requeue_request_activity_for_local_settlement(
self,
request: AgentRequest | None,
) -> bool:
activities = self._request_activities(request)
registry = self._activity_registry()
if (
request is None
or not activities
or registry is None
or not self._requeue_activities_for_local_settlement(
registry,
activities,
)
):
return False
self._clear_request_activities(request)
request.output = terminal_turn_output()
return True
def _activity_output_pending(self, composite_key: str) -> bool:
registry = self._activity_registry()
return bool(
self._output_record(composite_key, None, owner="activity") is not None
or (
registry is not None
and (
registry.has_active(self.name, composite_key)
or registry.has_completed_output(self.name, composite_key)
)
)
)
async def _wait_for_activity_output(self, composite_key: str) -> None:
"""Serialize Claude inference until native background output is consumed."""
while self._activity_output_pending(composite_key):
event = self._activity_settle_events.setdefault(composite_key, asyncio.Event())
if not self._activity_output_pending(composite_key):
self._signal_activity_output_settled(composite_key)
return
await event.wait()
def _signal_activity_output_settled(self, composite_key: str) -> None:
if self._activity_output_pending(composite_key):
return
event = self._activity_settle_events.pop(composite_key, None)
if event is not None:
event.set()
def on_activity_output_settled(self, runtime_key: str) -> None:
self._signal_activity_output_settled(runtime_key)
@staticmethod
def _activity_session_id(context: MessageContext) -> str | None:
value = (getattr(context, "platform_specific", None) or {}).get("agent_session_id")
return str(value or "").strip() or None
def _set_activity_connection(
self,
composite_key: str,
context: MessageContext,
state: str,
*,
activation_identity: RuntimeActivationIdentity | None = None,
) -> None:
registry = self._activity_registry()
if registry is None:
return
registry.set_connection(
backend=self.name,
runtime_key=composite_key,
session_id=self._activity_session_id(context),
state=state,
activation_identity=activation_identity,
)
def _end_activity_runtime(
self,
composite_key: str,
*,
activation_identity: RuntimeActivationIdentity | None = None,
) -> None:
service = getattr(self.controller, "agent_service", None)
end_runtime = getattr(service, "end_activity_runtime", None)
completed = []
if callable(end_runtime) and composite_key:
completed = (
end_runtime(
self.name,
composite_key,
activation_identity=activation_identity,
)
or []
)
if completed:
self._mark_session_idle_if_runtime_free(composite_key)
self._signal_activity_output_settled(composite_key)
@staticmethod
def _task_field(message, name: str, default=None):
value = getattr(message, name, None)
if value is not None:
return value
data = getattr(message, "data", None)
return data.get(name, default) if isinstance(data, dict) else default
def _track_tool_activity_mode(
self,
composite_key: str,
block: ToolUseBlock,
*,
detached: bool = False,
provisional: bool = False,
) -> None:
"""Remember which Claude task frames belong to foreground tool steps."""
tool_use_id = str(getattr(block, "id", "") or "").strip()
if not tool_use_id:
return
# Foreground evidence decides live Activity ownership, so it follows
# each tool's real default: an ``Agent`` call with no flag runs in the
# background even though a ``Bash`` call with no flag does not.
runs_in_background = tool_runs_in_background(
str(getattr(block, "name", "") or ""),
getattr(block, "input", None),
)
if provisional:
self._provisional_tool_use_ids.setdefault(
composite_key,
set(),
).add(tool_use_id)
if runs_in_background:
return
self._provisional_foreground_tool_use_ids.setdefault(
composite_key,
set(),
).add(tool_use_id)
return
if runs_in_background:
return
if detached:
self._detached_foreground_tool_use_ids.setdefault(
composite_key,
set(),
).add(tool_use_id)
return
self._foreground_tool_use_ids.setdefault(composite_key, set()).add(
tool_use_id
)
self._turns_with_foreground_tools.add(composite_key)
def _clear_detached_foreground_tool_state(self, composite_key: str) -> None:
self._detached_foreground_tool_use_ids.pop(composite_key, None)
self._detached_foreground_task_ids.pop(composite_key, None)
def _ensure_provisional_phase(self, composite_key: str) -> str:
phase_id = self._provisional_phase_ids.get(composite_key)
if phase_id is None:
phase_id = f"{composite_key}:provisional:{uuid.uuid4().hex}"
self._provisional_phase_ids[composite_key] = phase_id
return phase_id
def _provisional_phase_tool_ids(self, composite_key: str) -> set[str]:
tool_ids = set(
self._provisional_tool_use_ids.get(composite_key) or ()
)
for message, _generation in self._buffered_assistant_messages.get(
composite_key,
(),
):
for block in getattr(message, "content", []) or []:
if not isinstance(block, ToolUseBlock):
continue
tool_id = str(getattr(block, "id", "") or "").strip()
if tool_id:
tool_ids.add(tool_id)
return tool_ids
def _resolve_provisional_phase(
self,
composite_key: str,
context: MessageContext,
*,
owner: str,
terminal_message=None,
) -> None:
"""Classify buffered tool/task facts before terminal output can await."""
provisional_activity_ids = set(
self._provisional_activity_ids.get(composite_key) or ()
)
unbound_activity_ids = set(
self._provisional_unbound_activity_ids.get(composite_key) or ()
)
provisional_tool_ids = self._provisional_phase_tool_ids(composite_key)
unbound_tool_ids = set(
self._provisional_unbound_tool_use_ids.get(composite_key) or ()
)
provisional_foreground_tool_ids = set(
self._provisional_foreground_tool_use_ids.get(composite_key) or ()
)
phase_id = self._provisional_phase_ids.get(composite_key)
if owner not in {"human", "detached"}:
return
if phase_id:
self._resolved_provisional_phase_ids[composite_key] = phase_id
registry = self._activity_registry()
pending = self._pending_requests.get(composite_key) or []
pending_request = pending[0] if pending else None
turn_id = self._current_turn_id(composite_key, context) if pending else None
run_ids = self._activity_run_ids(composite_key, context) if pending else []
source = (
getattr(pending_request, "context", None)
if pending_request is not None
else context
)
delivery_key = str(
(getattr(source, "platform_specific", None) or {}).get(
"delivery_key_external"
)
or ""
).strip()
if owner == "human":
if provisional_foreground_tool_ids:
self._foreground_tool_use_ids.setdefault(
composite_key,
set(),
).update(provisional_foreground_tool_ids)
self._turns_with_foreground_tools.add(composite_key)
activity_ids = provisional_activity_ids - unbound_activity_ids
detached = False
else:
detached_tool_ids = self._detached_foreground_tool_use_ids.setdefault(
composite_key,
set(),
)
detached_tool_ids.update(provisional_foreground_tool_ids)
activity_ids = provisional_activity_ids
detached = True
if registry is None or not activity_ids and not provisional_tool_ids:
return
classification_failed = False
try:
classified = registry.classify_provisional_provenance(
self.name,
composite_key,
activity_ids=activity_ids,
parent_activity_ids=(
provisional_tool_ids
if owner == "detached"
else provisional_tool_ids - unbound_tool_ids
),
turn_id=turn_id,
run_ids=run_ids,
delivery_key_external=delivery_key,
phase_id=phase_id,
detached=detached,
)
except Exception as error:
# Terminal Result provenance is authoritative even when the
# registry's durable classification write is temporarily
# unavailable. Keep a bounded recovery record and let the shared
# Result path settle the request exactly once; the receiver must
# not skip this already-consumed terminal frame.
self._provenance_recovery_evidence[composite_key] = {
"owner": owner,
"phase_id": phase_id,
"activity_ids": tuple(sorted(activity_ids)),
"tool_use_ids": tuple(sorted(provisional_tool_ids)),
"error": f"{type(error).__name__}: {error}",
}
logger.warning(
"Claude provisional provenance classification needs recovery "
"for %s; continuing with terminal owner %s",
composite_key,
owner,
exc_info=True,
)
classification_failed = True
if not classification_failed and classified:
self._notify_classified_terminal_activities(classified)
if owner == "human":
# Keep uncorrelated task facts provisional for a later detached
# Result. Only a TaskStarted tied to a tool phase proves that the
# human terminal owns that Activity.
self._provisional_foreground_tool_use_ids.pop(composite_key, None)
self._provisional_foreground_task_ids.pop(composite_key, None)
if not unbound_activity_ids:
self._provisional_activity_ids.pop(composite_key, None)
self._provisional_unbound_activity_ids.pop(composite_key, None)
self._provisional_tool_use_ids.pop(composite_key, None)
self._provisional_unbound_tool_use_ids.pop(composite_key, None)
self._provisional_phase_ids.pop(composite_key, None)
self._resolved_provisional_phase_ids.pop(composite_key, None)
elif owner == "detached":
self._provisional_activity_ids.pop(composite_key, None)
self._provisional_unbound_activity_ids.pop(composite_key, None)
self._provisional_tool_use_ids.pop(composite_key, None)
self._provisional_unbound_tool_use_ids.pop(composite_key, None)
self._provisional_foreground_tool_use_ids.pop(composite_key, None)
self._provisional_foreground_task_ids.pop(composite_key, None)
self._provisional_phase_ids.pop(composite_key, None)
if classification_failed:
return
if classified and phase_id and owner == "human":
try:
claimed = registry.claim_completed_output_batch(
self.name,
composite_key,
metadata_match={
"provenance_phase_id": phase_id,
"provenance_human": True,
},
)
except Exception as error:
# The Result is already consumed and its origin is authoritative.
# Receipt binding is preparatory work: retain exact terminal
# evidence, leave the Activity claim retryable, and let the
# normal terminal path settle this Result exactly once.
self._provenance_recovery_evidence[composite_key] = {
"owner": owner,
"phase_id": phase_id,
"activity_ids": tuple(sorted(activity_ids)),
"tool_use_ids": tuple(sorted(provisional_tool_ids)),
"terminal": {
"subtype": str(
getattr(terminal_message, "subtype", "") or ""
),
"result": str(
getattr(terminal_message, "result", "") or ""
),
},
"error": f"{type(error).__name__}: {error}",
}
logger.warning(
"Claude provisional receipt binding needs recovery for %s; "
"continuing with terminal owner %s",
composite_key,
owner,
exc_info=True,
)
return
if pending_request is not None and claimed:
self._attach_request_activities(pending_request, claimed)
self._refresh_activity_provenance_barrier(composite_key)
def _select_terminal_text(
self,
composite_key: str,
sdk_result: str | None,
) -> str:
"""Select terminal content from assistant TextBlocks, never tool labels."""
assistant_text = str(
self._last_assistant_text.get(composite_key) or ""
).strip()
if assistant_text:
return assistant_text
if composite_key in self._turns_with_foreground_tools:
return "<silent>Claude turn completed without assistant text.</silent>"
return str(sdk_result or "")
@staticmethod
def _result_origin_kind(message) -> str | None:
origin = getattr(message, "origin", None)
if isinstance(origin, dict):
kind = origin.get("kind")
else:
kind = getattr(origin, "kind", None)
normalized = str(kind or "").strip().lower()
return normalized or None
def _has_competing_activity(self, composite_key: str) -> bool:
if (
self._output_records_for_runtime(composite_key)
or composite_key in self._activity_provenance_barriers
):
return True
registry = self._activity_registry()
pending = self._pending_requests.get(composite_key) or []
pending_context = getattr(pending[0], "context", None) if pending else None
current_turn_id = (
self._current_turn_id(composite_key, pending_context)
if pending
else None
)
has_competing_output = (
getattr(registry, "has_competing_output", None)
if registry is not None
else None
)
return bool(
callable(has_competing_output)
and has_competing_output(
self.name,
composite_key,
current_turn_id=current_turn_id,
)
)
def _refresh_activity_provenance_barrier(self, composite_key: str) -> None:
"""Track a pending human turn whose terminal owner is not classified."""
pending = self._pending_requests.get(composite_key) or []
if not pending:
self._activity_provenance_barriers.discard(composite_key)
self._activity_provenance_barrier_owners.pop(composite_key, None)
return
owner = id(pending[0])
previous_owner = self._activity_provenance_barrier_owners.get(composite_key)
if previous_owner != owner:
self._activity_provenance_barriers.discard(composite_key)
self._activity_provenance_barrier_owners.pop(composite_key, None)
if composite_key in self._activity_provenance_barriers:
return
if (
self._output_records_for_runtime(composite_key)
or self._has_competing_activity(composite_key)
):
self._activity_provenance_barriers.add(composite_key)
self._activity_provenance_barrier_owners[composite_key] = owner
def _should_buffer_assistant_message(self, composite_key: str) -> bool:
"""Hold an origin-less Assistant frame while Activity ownership is open."""
if self._buffered_assistant_messages.get(composite_key):
# Replay is ordered: once a phase's frames are held, the rest of
# that phase is held with them, even if competing output has since
# finished. A later frame must not overtake the earlier ones.
return True
records = self._output_records_for_runtime(composite_key)
if records:
pending = self._pending_requests.get(composite_key) or []
human_pending = bool(pending and not getattr(pending[0], "_claude_synthetic_owner", False))
return human_pending or any(record.lifecycle == "delivery_pending" for record in records)
return (
composite_key in self._activity_provenance_barriers
or self._has_competing_activity(composite_key)
)
def _turn_answers_pending_human(
self,
composite_key: str,
turn_origin: str | None,
) -> bool:
"""Whether Claude's replay proved this turn answers the pending human.
A turn that starts with a replayed human input ends with a human
Result, so its frames need not wait for that Result. Held frames and
detached or claimed Activity output that is not yet delivered are
earlier, so they are never overtaken. Queued completed Activity output
follows the human Result either way: the Activity flush defers while a
human request is pending.
"""
if turn_origin != "human":
return False
if self._buffered_assistant_messages.get(composite_key):
return False
if self._output_records_for_runtime(composite_key):
return False
pending = self._pending_requests.get(composite_key) or []
return bool(
pending and not getattr(pending[0], "_claude_synthetic_owner", False)
)
def _result_owner(self, composite_key: str, message) -> str:
"""Classify a terminal frame before it can claim shared state."""
origin_kind = self._result_origin_kind(message)
if origin_kind == "human":
return "human"
if origin_kind:
return "detached"
if self._pending_requests.get(composite_key):
return "detached" if self._has_competing_activity(composite_key) else "human"
return "agent"
def _stop_owned_result_for_receiver(
self,
composite_key: str,
receiver_stop_epoch: int,
) -> bool:
"""Whether this receiver predates a Stop that already settled its turn."""
stop_epoch = self._stop_owned_terminal_epochs.get(composite_key)
return (
(
stop_epoch is not None
and stop_epoch > receiver_stop_epoch
)
or (
composite_key in self._stop_owned_terminal_keys
and composite_key in self._steering_closing_keys()
)
)
async def _flush_buffered_assistant_messages(
self,
composite_key: str,
context: MessageContext,
*,
owner: str,
terminal_steering_generation: int,
) -> bool:
"""Replay ambiguous Assistant frames after terminal provenance is known."""
messages = self._buffered_assistant_messages.pop(composite_key, None)
if not messages:
return False
detached = owner == "detached"
try:
formatter = self._get_formatter(context)
except Exception: # noqa: BLE001 - terminal settlement must survive replay formatting
formatter = None
logger.warning(
"Failed to create Claude formatter while replaying buffered "
"Assistant frames for %s",
composite_key,
exc_info=True,
)
for message, frame_steering_generation in messages:
try:
if message is _STEER_BOUNDARY:
if not detached:
# Mirror the live steer boundary: the text before it
# closes the primary phase without closing the Turn.
await self._emit_steered_primary_output(
context,
composite_key,
str(
self._last_assistant_text.get(composite_key) or ""
).strip(),
)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
# Foreground-tool evidence is phase-local, as on the
# live steer path. Every later frame of this phase is
# buffered, so replaying them re-derives exactly the
# evidence that belongs after the boundary.
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
continue
assistant_text = self._extract_text_blocks(message, context)
context_tokens = self._extract_context_tokens(message)
if context_tokens:
self.controller.note_session_tokens(context, total=context_tokens)
toolcalls = []
for block in getattr(message, "content", []) or []:
if not isinstance(block, ToolUseBlock):
continue
self._track_tool_activity_mode(
composite_key,
block,
detached=detached,
)
if formatter is not None:
toolcalls.append(
(
formatter.format_toolcall(
block.name,
block.input,
get_relative_path=lambda path: self.get_relative_path(path, context),
),
formatter.format_toolcall_label(
block.name,
block.input,
get_relative_path=lambda path: self.get_relative_path(path, context),
),
)
)
if detached:
if assistant_text:
record = self._provisional_output_record(composite_key, "activity")
if record is None:
record = self._detached_phase(composite_key)
record.text = assistant_text
continue
failure_disposition = await self._process_assistant_terminal_frame(
context,
composite_key,
message,
assistant_text,
terminal_steering_generation=(
frame_steering_generation
if frame_steering_generation is not None
else terminal_steering_generation
),
)
if failure_disposition in {"teardown", "superseded", "auth", "failure"}:
if failure_disposition == "auth":
return True
continue
if assistant_text:
self._last_assistant_text[composite_key] = assistant_text
pending = self._pending_requests.get(composite_key) or []
self._adopt_pending_turn_token(
context,
pending[0] if pending else None,
)
previous = self._pending_assistant_message.pop(composite_key, None)
if previous:
await emit_output(self.controller, context, Narration(previous))
for toolcall_text, toolcall_label in toolcalls:
await emit_output(
self.controller,
context,
ToolActivity(toolcall_text, status_label=toolcall_label),
)
if assistant_text:
self._pending_assistant_message[composite_key] = assistant_text
except asyncio.CancelledError:
raise
except Exception:
# Assistant replay is ancillary to the terminal Result. Keep
# the Result on the receiver so its provenance can still settle
# the owning human/Activity phase.
logger.warning(
"Failed to replay buffered Claude Assistant frame for %s; "
"continuing to terminal Result",
composite_key,
exc_info=True,
)
return False
def _clear_result_phase_state(self, composite_key: str) -> None:
"""Retire response-local evidence before Claude consumes another input."""
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._buffered_assistant_messages.pop(composite_key, None)
self._provisional_tool_use_ids.pop(composite_key, None)
self._provisional_unbound_tool_use_ids.pop(composite_key, None)
self._provisional_foreground_tool_use_ids.pop(composite_key, None)
self._provisional_activity_ids.pop(composite_key, None)
self._provisional_unbound_activity_ids.pop(composite_key, None)
self._provisional_foreground_task_ids.pop(composite_key, None)
self._provisional_phase_ids.pop(composite_key, None)
self._resolved_provisional_phase_ids.pop(composite_key, None)
self._foreground_tool_use_ids.pop(composite_key, None)
self._turns_with_foreground_tools.discard(composite_key)
self._refresh_activity_provenance_barrier(composite_key)
async def _emit_primary_phase_output(
self,
context: MessageContext,
request: AgentRequest | None,
text: str,
*,
reply_id: str | None = None,
) -> None:
"""Emit a completed pre-steer phase without closing the shared Turn.
``reply_id`` is the phase's ``ResultMessage.uuid`` when the stream gave one:
the reply's identity, so two phases with the same text stay two deliveries
and a replay of one stays one. A phase rebuilt from assistant frames at a
steer receipt has no Result, and so no identity.
"""
activities = self._request_activities(request)
activity = activities[-1] if activities else None
output = (
self._activity_message_output(
activity,
activities=activities,
detached=False,
completes_turn=False,
)
if activity is not None
# A reply: recorded on the Turn's Runs when it is delivered, like any other.
else MessageOutput(completes_turn=False, completes_run=False, idempotency_key=reply_id or None)
)
emitted_text = text or (
str(activity.metadata.get("summary") or "") if activity else ""
)
# A completed phase is a reply like any other: a ``result`` that does not end
# the Turn (docs/plans/reply-and-turn-end.md).
receipt = await emit_output(self.controller, context, Reply(emitted_text, output=output))
if activity is None:
return
if strip_silent_blocks(emitted_text).strip():
self._require_activity_delivery(activity, receipt)
self._clear_request_activities(request)
if request is not None:
request.output = terminal_turn_output()
async def _emit_buffered_primary_phase(
self,
context: MessageContext,
composite_key: str,
) -> bool:
"""Emit and retire a buffered Result once later input/output proves it primary."""
buffered = self._ambiguous_primary_results.pop(composite_key, None)
if buffered is None:
return False
buffered_text = self._select_buffered_terminal_text(
composite_key,
buffered,
)
pending = self._pending_requests.get(composite_key) or []
buffered_request = pending[0] if pending else None
if buffered_text or self._request_activities(buffered_request):
self._adopt_pending_turn_token(context, buffered_request)
buffered_message, _, _ = self._unpack_buffered_terminal(buffered)
await self._emit_primary_phase_output(
context,
buffered_request,
buffered_text,
reply_id=_result_uuid(buffered_message),
)
return True
async def _retire_primary_phase_on_steer_receipt(
self,
context: MessageContext,
composite_key: str,
) -> None:
"""Close all response-local primary state at the native input boundary."""
emitted_primary = await self._emit_buffered_primary_phase(
context,
composite_key,
)
buffered = self._buffered_assistant_messages.get(composite_key)
if buffered:
# No Result separates these origin-less frames from the steer, so
# Claude consumed it inside the same turn: one terminal Result
# classifies both sides. Keep the frames and their provisional
# facts for it; human replay closes the primary phase here.
buffered.append((_STEER_BOUNDARY, None))
return
if not emitted_primary:
await self._emit_steered_primary_output(
context,
composite_key,
self._select_terminal_text(composite_key, None),
)
self._clear_result_phase_state(composite_key)
async def _emit_steered_primary_output(
self,
context: MessageContext,
composite_key: str,
primary_text: str,
) -> None:
pending = self._pending_requests.get(composite_key) or []
primary_request = pending[0] if pending else None
if primary_text or self._request_activities(primary_request):
self._adopt_pending_turn_token(context, primary_request)
await self._emit_primary_phase_output(
context,
primary_request,
primary_text,
)
def _select_buffered_terminal_text(self, composite_key: str, buffered) -> str:
"""Render a buffered pre-steer result without using newer assistant text."""
message, assistant_text, had_foreground_tools = self._unpack_buffered_terminal(
buffered
)
if assistant_text:
return str(assistant_text).strip()
if had_foreground_tools:
return "<silent>Claude turn completed without assistant text.</silent>"
return str(getattr(message, "result", "") or "")
@staticmethod
def _unpack_buffered_terminal(
buffered,
) -> tuple[object, str | None, bool]:
if isinstance(buffered, tuple) and len(buffered) == 3:
message, assistant_text, had_foreground_tools = buffered
return message, assistant_text, bool(had_foreground_tools)
return buffered, None, False
def _select_detached_result_text(
self,
composite_key: str,
message,
sdk_result: str | None,
assistant_text: str | None,
) -> str | None:
"""Prefer assistant text unless a detached Result carries a real failure."""
failure = self._terminal_backend_failure(message, sdk_result)
if failure is not None:
return sdk_result or assistant_text
if assistant_text:
return assistant_text
if self._detached_foreground_tool_use_ids.get(composite_key):
return "<silent>Claude turn completed without assistant text.</silent>"
return sdk_result
def _retain_detached_unsolicited_assistant_text(
self,
composite_key: str,
text: str,
) -> None:
"""Keep later detached phases separate from a retained payload."""
normalized = str(text or "").strip()
if not normalized:
return
self._detached_phase(composite_key).text = normalized
def _current_turn_id(
self,
composite_key: str,
context: MessageContext,
) -> str | None:
pending = self._pending_requests.get(composite_key) or []
source = getattr(pending[0], "context", None) if pending else context
value = (getattr(source, "platform_specific", None) or {}).get(AGENT_TURN_TOKEN)
return str(value or "").strip() or None
def _activity_run_ids(
self,
composite_key: str,
context: MessageContext,
) -> list[str]:
pending = self._pending_requests.get(composite_key) or []
source = getattr(pending[0], "context", None) if pending else context
spec = getattr(source, "platform_specific", None) or {}
if spec.get("task_trigger_kind") not in HARNESS_RUN_ID_TRIGGER_KINDS:
return []
run_ids: list[str] = []
primary = str(spec.get("task_execution_id") or "").strip()
if primary:
run_ids.append(primary)
values = spec.get("accepted_agent_run_ids")
if isinstance(values, list):
for value in values:
run_id = str(value or "").strip()
if run_id and run_id not in run_ids:
run_ids.append(run_id)
return run_ids
def _handle_activity_message(
self,
message,
composite_key: str,
context: MessageContext,
*,
activation_identity: RuntimeActivationIdentity | None = None,
) -> bool:
"""Project Claude task events into the backend-neutral Activity registry."""
subtype = str(getattr(message, "subtype", "") or "").strip().lower()
class_name = getattr(getattr(message, "__class__", None), "__name__", "")
event = {
"TaskStartedMessage": "task_started",
"TaskProgressMessage": "task_progress",
"TaskNotificationMessage": "task_notification",
"TaskUpdatedMessage": "task_updated",
}.get(class_name, subtype)
if event not in {"task_started", "task_progress", "task_notification", "task_updated"}:
return False
task_id = str(self._task_field(message, "task_id", "") or "").strip()
if not task_id:
logger.warning("Ignoring Claude %s without task_id for %s", event, composite_key)
return True
registry = self._activity_registry()
if registry is None:
return True
existing_activity = next(
(
activity
for activity in registry.active_for_runtime(self.name, composite_key)
if activity.id == task_id
),
None,
)
session_id = self._activity_session_id(context)
description = str(self._task_field(message, "description", "") or "").strip() or None
task_type = str(self._task_field(message, "task_type", "") or "").strip()
tool_use_id = str(self._task_field(message, "tool_use_id", "") or "").strip()
detached_tool_ids = self._detached_foreground_tool_use_ids.get(composite_key) or set()
detached_task_ids = self._detached_foreground_task_ids.get(composite_key) or set()
if task_id in detached_task_ids or (tool_use_id and tool_use_id in detached_tool_ids):
self._detached_foreground_task_ids.setdefault(composite_key, set()).add(
task_id
)
return True
foreground_tool_ids = self._foreground_tool_use_ids.get(composite_key) or set()
provisional_foreground_tool_ids = (
getattr(self, "_provisional_foreground_tool_use_ids", {}).get(composite_key)
or set()
)
foreground = bool(
(existing_activity is not None and existing_activity.foreground)
or (tool_use_id and tool_use_id in foreground_tool_ids)
or (tool_use_id and tool_use_id in provisional_foreground_tool_ids)
)
pending = self._pending_requests.get(composite_key) or []
# A pending human request is not enough to prove that this Activity
# belongs to it: an interleaved detached phase may have started it.
# Keep newly-created Activities provisional until Result.origin
# classifies the phase, even when a buffered foreground ToolUseBlock
# already supplied an operational foreground hint. The exception is a
# foreground task whose parent tool frame was emitted live for that
# human request: that frame was attributed because nothing competed,
# and it still does not, so the task inherits the frame's owner. A
# foreground completion carries no Activity output for a terminal
# Result to claim; background tools stay provisional.
live_human_activity = bool(
pending
and existing_activity is None
and tool_use_id
and tool_use_id in provisional_foreground_tool_ids
and not getattr(pending[0], "_claude_synthetic_owner", False)
and not self._buffered_assistant_messages.get(composite_key)
and not self._has_competing_activity(composite_key)
)
provenance_pending = bool(
(pending and existing_activity is None and not live_human_activity)
or (
existing_activity is not None
and existing_activity.metadata.get("provenance_pending")
)
)
phase_id = None
if provenance_pending:
self._activity_provenance_barriers.add(composite_key)
if pending:
self._activity_provenance_barrier_owners[composite_key] = id(pending[0])
prior_phase = (
str(existing_activity.metadata.get("provenance_phase_id") or "").strip()
if existing_activity is not None else ""
)
phase_id = prior_phase or self._ensure_provisional_phase(composite_key)
current_phase = self._provisional_phase_ids.get(composite_key) == phase_id
# A task may outlive the human request whose phase first observed
# it. Its terminal event keeps that immutable phase and must not
# become positive correlation for the current/newer human request.
if current_phase:
self._provisional_activity_ids.setdefault(
composite_key,
set(),
).add(task_id)
# A background tool is still positive phase evidence. The
# ``run_in_background`` flag describes execution mode, not whether
# the resulting Activity belongs to the human Result or a detached
# task-notification Result. Keep foreground-only tracking separate
# for output selection, but use every provisionally observed tool
# ID when correlating TaskStarted to its Assistant phase.
known_tool_ids = (
foreground_tool_ids
| provisional_foreground_tool_ids
| (self._provisional_tool_use_ids.get(composite_key) or set())
)
if current_phase and (not tool_use_id or tool_use_id not in known_tool_ids):
self._provisional_unbound_activity_ids.setdefault(
composite_key,
set(),
).add(task_id)
if tool_use_id:
self._provisional_unbound_tool_use_ids.setdefault(
composite_key,
set(),
).add(tool_use_id)
if current_phase and foreground:
self._provisional_foreground_task_ids.setdefault(
composite_key,
set(),
).add(task_id)
elif existing_activity is not None:
phase_id = str(
existing_activity.metadata.get("provenance_phase_id") or ""
).strip() or None
# The SDK task ``summary`` is a CLI-generated receipt such as
# 'Background command "..." completed (exit code 0)'. It is not
# assistant output, so it never becomes the Activity's visible
# fallback text; a completion without assistant text settles silently.
metadata = {
key: value
for key, value in {
"task_type": task_type or None,
"last_tool_name": self._task_field(message, "last_tool_name"),
"output_file": self._task_field(message, "output_file"),
}.items()
if value not in (None, "")
}
if provenance_pending:
metadata["provenance_pending"] = True
if phase_id:
metadata["provenance_phase_id"] = phase_id
if existing_activity is None:
if provenance_pending:
# Activity ownership is provisional until Result.origin
# classifies this phase. Never inherit a newer human request's
# Harness identity while the task's owner is ambiguous.
run_ids = []
turn_id = None
else:
source = getattr(pending[0], "context", None) if pending else context
delivery_key = str(
(getattr(source, "platform_specific", None) or {}).get(
"delivery_key_external"
)
or ""
).strip()
if delivery_key:
metadata["delivery_key_external"] = delivery_key
if live_human_activity:
metadata["provenance_human"] = True
run_ids = self._activity_run_ids(composite_key, context)
turn_id = self._current_turn_id(composite_key, context)
else:
run_ids = []
if existing_activity.run_id:
run_ids.append(existing_activity.run_id)
existing_run_ids = existing_activity.metadata.get("run_ids")
if isinstance(existing_run_ids, list):
for value in existing_run_ids:
run_id = str(value or "").strip()
if run_id and run_id not in run_ids:
run_ids.append(run_id)
turn_id = existing_activity.turn_id
if run_ids:
metadata["run_ids"] = run_ids
if event == "task_started":
started = registry.start(
backend=self.name,
runtime_key=composite_key,
session_id=session_id,
activity_id=task_id,
kind=task_type or "background_task",
description=description,
foreground=foreground,
parent_activity_id=tool_use_id or None,
turn_id=turn_id,
run_id=run_ids[0] if run_ids else None,
metadata=metadata,
activation_identity=activation_identity,
)
if started is None:
return True
mark_active = getattr(self.session_handler, "mark_session_active", None)
if callable(mark_active):
mark_active(composite_key)
self.session_handler.touch_session_activity(composite_key)
return True
status = str(self._task_field(message, "status", "") or "").strip().lower()
terminal = status in {"completed", "failed", "stopped", "killed"}
if event in {"task_progress", "task_updated"} and not terminal:
progressed = registry.progress(
backend=self.name,
runtime_key=composite_key,
session_id=session_id,
activity_id=task_id,
description=description,
metadata=metadata,
activation_identity=activation_identity,
)
if progressed is None:
return True
mark_active = getattr(self.session_handler, "mark_session_active", None)
if callable(mark_active):
mark_active(composite_key)
self.session_handler.touch_session_activity(composite_key)
return True
if not terminal:
logger.warning("Ignoring Claude %s with non-terminal status %r", event, status)
return True
if existing_activity is None or (
existing_activity is not None
and foreground
and not existing_activity.foreground
and bool(pending)
):
registry.start(
backend=self.name,
runtime_key=composite_key,
session_id=session_id,
activity_id=task_id,
kind=task_type or "background_task",
description=description,
foreground=foreground,
parent_activity_id=tool_use_id or None,
turn_id=turn_id,
run_id=run_ids[0] if run_ids else None,
metadata=metadata,
activation_identity=activation_identity,
)
completed = registry.complete(
backend=self.name,
runtime_key=composite_key,
activity_id=task_id,
status=status,
metadata=metadata,
expects_output=(
status == "completed"
and not foreground
),
retain_terminal_snapshot=(
status != "completed"
and (not foreground or bool(metadata.get("provenance_pending")))
)
or (
status == "completed"
and foreground
and bool(metadata.get("provenance_pending"))
),
activation_identity=activation_identity,
)
if completed is not None and status == "completed" and not foreground:
supervisor = getattr(self.controller, "runtime_work_supervisor", None)
notify = getattr(supervisor, "notify", None)
if callable(notify):
notify(RuntimeWorkLane.ACTIVITY_OUTPUTS)
service = getattr(self.controller, "agent_service", None)
on_terminal = getattr(service, "on_activity_terminal", None)
if (
completed is not None
and not foreground
and callable(on_terminal)
and not bool((completed.metadata or {}).get("provenance_pending"))
):
on_terminal(completed)
if status != "completed" or foreground:
self._mark_session_idle_if_runtime_free(composite_key)
self._signal_activity_output_settled(composite_key)
return True
@staticmethod
def _activity_message_output(
activity: SessionActivity,
*,
activities: list[SessionActivity] | None = None,
detached: bool,
completes_turn: bool,
) -> MessageOutput:
return activity_completion_output(
activity,
activities=activities,
detached=detached,
completes_turn=completes_turn,
)
@staticmethod
def _require_activity_delivery(
activity: SessionActivity,
receipt: DeliveryReceipt,
) -> None:
if not receipt.delivered:
raise ActivityOutputDeliveryError(
f"Claude Activity output {activity.id} was not persisted or delivered",
delivered=False,
)
async def _settle_activity_turn_after_delivery_failure(
self,
context: MessageContext,
) -> None:
"""Close the origin Turn if delivery failed before its terminal chokepoint."""
try:
await emit_output(
self.controller,
context,
TurnEnd(silent=True, output=MessageOutput(completes_turn=True, completes_run=False)),
)
except Exception:
logger.debug(
"Failed to settle Activity Turn after delivery failure",
exc_info=True,
)
async def _emit_activity_result(
self,
context: MessageContext,
activity: SessionActivity,
text: str | None,
*,
detached: bool,
completes_turn: bool,
subtype: str = "success",
duration_ms: int = 0,
request: AgentRequest | None = None,
activities: list[SessionActivity] | None = None,
output: MessageOutput | None = None,
) -> None:
"""Apply the Activity's explicit visible-or-silent output policy."""
request_output = getattr(request, "output", None) if request is not None else None
if output is None:
output = (
request_output
if isinstance(request_output, MessageOutput)
else self._activity_message_output(
activity,
activities=activities,
detached=detached,
completes_turn=completes_turn,
)
)
visible_text = str(text or "")
if not strip_silent_blocks(visible_text).strip():
# The Turn's content-free end, or detached work's content-free answer.
await emit_output(
self.controller,
context,
self._result_event("", parse_mode="markdown", failed=(subtype or "").startswith("error"), output=output),
)
return
receipt = await self.emit_result_message(
context,
visible_text,
subtype=subtype,
duration_ms=duration_ms,
parse_mode="markdown",
request=request,
output=output,
)
self._require_activity_delivery(activity, receipt)
@staticmethod
def _unsolicited_message_output(
message,
*,
phase_id: str | None = None,
) -> MessageOutput:
native_id = str(
getattr(message, "uuid", "")
or getattr(message, "message_id", "")
or ""
).strip()
identity = native_id
if not identity:
session_id = str(getattr(message, "session_id", "") or "").strip()
num_turns = getattr(message, "num_turns", None)
if session_id and num_turns is not None:
frame_identity = ":".join(
[
session_id,
str(num_turns),
str(getattr(message, "duration_ms", "")),
str(getattr(message, "duration_api_ms", "")),
str(getattr(message, "subtype", "")),
]
)
identity = uuid.uuid5(uuid.NAMESPACE_OID, frame_identity).hex
else:
# Older SDK frames expose no stable identity. Allocate one once
# for this MessageOutput instead of deduplicating by visible text.
identity = uuid.uuid4().hex
if phase_id:
identity = f"{identity}:{phase_id}"
metadata = {"backend": "claude", "source": "agent_initiated"}
if phase_id:
metadata["provenance_phase_id"] = phase_id
return MessageOutput(
completes_turn=False,
completes_run=False,
detached=True,
idempotency_key=f"claude-unsolicited:{identity}",
causation_id=native_id or None,
metadata=metadata,
)
async def _flush_detached_unsolicited_output(
self,
composite_key: str,
context: MessageContext,
) -> bool:
return await self._flush_output_recovery(composite_key, context)
async def _flush_detached_activity_output(
self,
composite_key: str,
context: MessageContext,
) -> bool:
# Grace/EOF may terminalize an already claimed Activity without a
# Result. This never consumes the pending human request.
record = self._provisional_output_record(composite_key, "activity")
if record is not None and record.activities:
self._classify_output_record(
record, context,
text=record.text or record.activities[-1].metadata.get("summary", ""),
)
return await self._flush_output_recovery(composite_key, context)
async def _flush_output_recovery(
self, composite_key: str, context: MessageContext,
) -> bool:
"""Deliver frozen ledger records, independent of live client generation."""
records = [
record for record in self._output_records_for_runtime(composite_key)
if record.lifecycle == "delivery_pending"
]
if not records:
return False
for record in records:
if record.delivering:
# The receiver and managed grace worker share this owner. No
# second send may enter while the same receipt is in flight.
return True
record.delivering = True
try:
if record.claim_pending:
registry = self._activity_registry()
if registry is None:
raise RuntimeError("Claude Activity recovery lost its registry")
if not record.activities:
if registry.has_claimed_output(self.name, composite_key):
self._schedule_completed_activity_flush(composite_key, context)
return True
# Select once using the existing FIFO/receipt algorithm.
# Binding is a separate fallible step: this record owns
# the exact members and payload before attempting it.
record.activities = registry.claim_completed_output_batch(
self.name, composite_key,
metadata_match=record.claim_metadata or {"provenance_pending": True},
bind_receipt=False,
)
if not record.activities and record.claim_metadata is None:
record.activities = registry.claim_completed_output_batch(
self.name, composite_key, bind_receipt=False,
)
if record.activities:
if record.output.activity_batch_id is None:
receipt_id = str(
record.activities[0].metadata.get("output_batch_id")
or record.phase_id
)
receipt_members = [
replace(activity, metadata={
**activity.metadata, "output_batch_id": receipt_id,
})
for activity in record.activities
]
record.output = self._activity_message_output(
receipt_members[-1], activities=receipt_members,
detached=True, completes_turn=False,
)
record.activities = registry.bind_completed_output_batch(
record.activities, batch_id=record.output.activity_batch_id,
)
record.output = self._activity_message_output(
record.activities[-1], activities=record.activities,
detached=True, completes_turn=False,
)
record.owner = "activity"
record.claim_pending = False
if record.activities:
output = record.output
if record.local_settlement_only:
output = replace(
output,
metadata={**output.metadata, "activity_local_settlement_only": True},
)
await self._emit_activity_result(
record.context or context,
record.activities[-1], record.text,
detached=True, completes_turn=False,
subtype=record.subtype, duration_ms=record.duration_ms,
activities=record.activities, output=output,
)
elif record.text:
receipt = await self.emit_result_message(
record.context or context, record.text,
subtype=record.subtype, duration_ms=record.duration_ms,
parse_mode="markdown", output=record.output,
)
# A silent-only reply settles without a Message, so it has no
# receipt; retrying it would block every later record.
if not receipt.delivered and strip_silent_blocks(record.text).strip():
raise ActivityOutputDeliveryError(
"Claude detached output was not accepted", delivered=False,
)
except asyncio.CancelledError:
self._schedule_completed_activity_flush(composite_key, context)
raise
except ActivityOutputDeliveryError as error:
if error.delivered and not error.durable:
# Positive transport evidence forbids another external send,
# even when every durable write failed. The existing
# dispatcher/Registry local-settlement path retains this
# exact claim; only the delivery policy changes.
record.local_settlement_only = True
self._schedule_completed_activity_flush(composite_key, context)
logger.warning(
"Claude Activity receipt recovery remains pending (phase=%s delivered=%s)",
record.phase_id, error.delivered, exc_info=True,
)
return True
except Exception:
self._schedule_completed_activity_flush(composite_key, context)
logger.warning(
"Claude output recovery remains pending (phase=%s)",
record.phase_id, exc_info=True,
)
return True
finally:
record.delivering = False
self._remove_output_record(record)
await self._retire_synthetic_pending_owner(
composite_key,
context,
owner=record.request,
is_error=record.is_error,
)
self._mark_session_idle_if_runtime_free(composite_key)
self._signal_activity_output_settled(composite_key)
# Another Result can append a record while this batch is in flight.
# The active managed worker must retain responsibility for that record
# rather than exiting with a stale, already-drained list snapshot.
retry = any(
record.lifecycle == "delivery_pending"
for record in self._output_records_for_runtime(composite_key)
)
if retry:
self._schedule_completed_activity_flush(composite_key, context)
return retry
async def _flush_completed_activity_outputs(
self,
composite_key: str,
context: MessageContext,
*,
expected_steering_generation: int | None = None,
allow_closing: bool = False,
expected_client=None,
expected_activation_identity: RuntimeActivationIdentity | None = None,
) -> bool:
"""Deliver task notifications that ended the receiver without a Result."""
supervisor = getattr(self.controller, "runtime_work_supervisor", None)
run_in_partition = getattr(supervisor, "run_in_partition", None)
if callable(run_in_partition):
return await run_in_partition(
RuntimeWorkLane.ACTIVITY_OUTPUTS,
f"{self.name}\x1f{composite_key}",
lambda: self._flush_completed_activity_outputs_owned(
composite_key,
context,
expected_steering_generation=expected_steering_generation,
allow_closing=allow_closing,
expected_client=expected_client,
expected_activation_identity=expected_activation_identity,
),
)
return await self._flush_completed_activity_outputs_owned(
composite_key,
context,
expected_steering_generation=expected_steering_generation,
allow_closing=allow_closing,
expected_client=expected_client,
expected_activation_identity=expected_activation_identity,
)
async def _flush_completed_activity_outputs_owned(
self,
composite_key: str,
context: MessageContext,
*,
expected_steering_generation: int | None = None,
allow_closing: bool = False,
expected_client=None,
expected_activation_identity: RuntimeActivationIdentity | None = None,
) -> bool:
"""Claim, emit, and settle while the exact runtime partition is held."""
registry = self._activity_registry()
if registry is None:
return False
if (
self._output_record(composite_key, None, owner="activity") is not None
or any(record.claim_pending for record in self._output_records_for_runtime(composite_key))
):
# The detached Result already owns this exact claimed batch. Let
# _flush_detached_activity_output retry its retained payload instead
# of claiming a second batch or mixing receipt identities.
return False
if expected_steering_generation is None:
expected_steering_generation = self._steering_generation(composite_key)
while True:
async with self._steering_lock(composite_key):
if expected_client is not None and not self._receiver_generation_current(
composite_key, expected_client, expected_activation_identity,
):
return False
if composite_key in self._steering_closing_keys() and not allow_closing:
logger.info(
"Ignoring Claude Activity terminal output superseded by steering for %s",
composite_key,
)
return False
if composite_key in self._ambiguous_interrupt_keys():
logger.info(
"Deferring Claude Activity terminal output while interrupt "
"ownership is ambiguous for %s",
composite_key,
)
return True
steering_state = self._pending_steering_input_state(composite_key)
if (
self._terminal_claim_superseded(
composite_key,
expected_steering_generation,
)
and steering_state != "unknown"
):
logger.info(
"Ignoring Claude Activity terminal output superseded by steering for %s",
composite_key,
)
return False
pending = self._pending_requests.get(composite_key) or []
pending_request = pending[0] if pending else None
synthetic_pending_owner = (
pending_request is not None
and self._synthetic_pending_owners.get(composite_key)
is pending_request
and bool(self._request_activities(pending_request))
)
if synthetic_pending_owner:
activities = self._request_activities(pending_request)
if not activities:
activities = registry.claim_completed_output_batch(
self.name,
composite_key,
)
if not activities:
return False
self._retain_activity_output_record(composite_key, activities)
elif pending_request is not None:
self._refresh_activity_provenance_barrier(composite_key)
if (
composite_key in self._activity_provenance_barriers
and not self._request_activities(pending_request)
):
# A completed Activity is not evidence that the pending
# human request owns it. Keep the registry claim queued
# until a terminal Result classifies the phase; this
# barrier also covers the no-Assistant-frame case where
# the old grace timer could otherwise pop the request.
self._activity_provenance_barriers.add(composite_key)
logger.info(
"Deferring Claude Activity flush until terminal "
"provenance is classified for %s",
composite_key,
)
return True
if self._request_activities(pending_request):
# A bound claim set is one concrete outbound batch. Later
# completions, even from the same Turn, wait for the next
# normal flush and receive their own receipt.
return registry.has_completed_output(self.name, composite_key)
pending_turn_ids = self._request_activity_turn_ids(pending_request)
activities = self._claim_activity_batch_for_turns(
registry,
composite_key,
pending_turn_ids,
)
if not activities:
return registry.has_completed_output(self.name, composite_key)
if self._terminal_claim_superseded(
composite_key,
expected_steering_generation,
):
self._requeue_activities(registry, activities)
logger.info(
"Ignoring Claude Activity terminal output superseded by steering for %s",
composite_key,
)
return False
self._attach_request_activities(pending_request, activities)
matched_request = self._pop_pending_request(composite_key)
else:
matched_request = None
if synthetic_pending_owner:
await self._flush_detached_activity_output(composite_key, context)
return bool(
registry.has_completed_output(self.name, composite_key)
)
if matched_request is not None:
self._adopt_pending_turn_token(context, matched_request)
retained = self._request_activities(matched_request)
activity = retained[-1]
result_text = str(activity.metadata.get("summary") or "").strip()
try:
await self._emit_activity_result(
context,
activity,
result_text,
detached=False,
completes_turn=True,
request=matched_request,
)
self._clear_request_activities(matched_request)
except ActivityOutputDeliveryError as err:
if not err.delivered or err.durable:
self._requeue_request_activity(matched_request)
if not err.delivered:
await self._settle_activity_turn_after_delivery_failure(context)
raise
logger.error(
"Delivered Claude Activity batch remains fail-closed after "
"incomplete local settlement (runtime=%s error=%s)",
composite_key,
err,
)
if self._requeue_request_activity_for_local_settlement(
matched_request
):
return True
self._clear_request_activities(matched_request)
except Exception:
self._requeue_request_activity(matched_request)
await self._settle_activity_turn_after_delivery_failure(context)
raise
finally:
await self._remove_result_pending_reaction(
composite_key,
context,
matched_request,
)
self._last_assistant_text.pop(composite_key, None)
self._pending_assistant_message.pop(composite_key, None)
self._buffered_assistant_messages.pop(composite_key, None)
self._mark_session_idle_if_no_pending_requests(composite_key)
self._signal_activity_output_settled(composite_key)
continue
activities = registry.claim_completed_output_batch(
self.name,
composite_key,
metadata_match={"provenance_pending": True},
)
if not activities:
activities = registry.claim_completed_output_batch(
self.name,
composite_key,
)
if not activities:
return False
activity = activities[-1]
result_text = str(activity.metadata.get("summary") or "").strip()
try:
await self._emit_activity_result(
context,
activity,
result_text,
detached=True,
completes_turn=False,
activities=activities,
)
except ActivityOutputDeliveryError as err:
if not err.delivered or err.durable:
self._requeue_activities(registry, activities)
raise
logger.error(
"Delivered Claude Activity batch remains fail-closed after incomplete "
"local settlement (runtime=%s error=%s)",
composite_key,
err,
)
if self._requeue_activities_for_local_settlement(
registry,
activities,
):
return True
except Exception:
self._requeue_activities(registry, activities)
raise
self._mark_session_idle_if_runtime_free(composite_key)
self._signal_activity_output_settled(composite_key)
def _schedule_completed_activity_flush(
self,
composite_key: str,
context: MessageContext,
*,
expected_steering_generation: int | None = None,
) -> None:
existing = self._activity_flush_tasks.get(composite_key)
if existing is not None and not existing.done():
return
if expected_steering_generation is None:
expected_steering_generation = self._steering_generation(composite_key)
async def _flush_after_grace() -> None:
retry = False
try:
await asyncio.sleep(self.ACTIVITY_OUTPUT_FLUSH_GRACE_SECONDS)
retry = await self._flush_detached_activity_output(composite_key, context)
retry = (
await self._flush_completed_activity_outputs(
composite_key,
context,
expected_steering_generation=expected_steering_generation,
)
or retry
)
except asyncio.CancelledError:
raise
except Exception:
retry = True
logger.warning(
"Failed to flush completed Claude Activities for %s",
composite_key,
exc_info=True,
)
finally:
if self._activity_flush_tasks.get(composite_key) is task:
self._activity_flush_tasks.pop(composite_key, None)
if retry:
self._schedule_completed_activity_flush(
composite_key,
context,
expected_steering_generation=expected_steering_generation,
)
task = asyncio.create_task(_flush_after_grace())
self._activity_flush_tasks[composite_key] = task
async def _maybe_begin_agent_initiated_turn(
self,
context: MessageContext,
composite_key: str,
base_session_id: str,
working_path: str,
session_key: str,
*,
message_type: str | None = None,
result_owner: str = "agent",
receiver_activation_identity: RuntimeActivationIdentity | None = None,
) -> str | None:
"""Open a turn for UNSOLICITED backend output (no Avibe query behind it).
Claude Code re-invokes the agent loop inside this same SDK process when a
background task completes or a ScheduleWakeup fires, streaming a fresh
assistant/result run onto this long-lived receiver. The previous turn's
terminal result already released the runtime gate and this receiver's
reused context still carries that turn's (now stale) token, so the
outbound active-turn guard would drop the whole reply — it would never be
persisted, delivered, or pushed.
A completed Activity carries its origin Turn. If that Turn is still
current, attach provenance to its request. If a newer user Turn owns the
runtime, preserve the Activity output as detached Session delivery and do
not pop or settle that request. With no pending request, open an
agent-initiated Turn and synthesize a pending ``AgentRequest`` so the
existing result path retains its normal lifecycle behavior.
"""
settling = self._synthetic_owner_settlements.get(composite_key)
if settling is not None:
await settling.wait()
registry = self._activity_registry()
pending = self._pending_requests.get(composite_key) or []
defer_activity_claim = message_type == "result" and (
result_owner == "detached" or result_owner == "human" and not pending
)
if message_type == "result" and result_owner == "human":
# Result.origin is the terminal owner. Preserve any detached state
# for a later task-notification Result instead of letting it
# intercept this human settlement.
if pending:
return None
if self._provisional_output_record(composite_key, "activity") is not None:
return "activity"
if self._output_records_for_runtime(composite_key):
self._detached_phase(composite_key, claim_activity=defer_activity_claim)
return "detached"
synthetic_owner = self._synthetic_pending_owners.get(composite_key)
if (
message_type == "result"
and result_owner == "detached"
and synthetic_owner is not None
):
owned_activities = self._request_activities(synthetic_owner)
if owned_activities:
# Reuse the receipt batch already claimed by the synthetic
# request. A second registry claim is intentionally prohibited
# and would strand the original Activity receipt.
self._retain_activity_output_record(composite_key, owned_activities)
return "activity"
self._detached_phase(composite_key, claim_activity=True)
return "detached"
# A structured AssistantMessage failure pops the turn's real pending
# request and arms ``_suppressed_synthetic_results`` for its paired
# ResultMessage. Opening an agent-initiated turn for that duplicate frame
# would leak the gate and block the next user message. The marker is cleared
# when the paired result is consumed or the receiver exits.
if composite_key in self._suppressed_synthetic_results:
return None
if message_type == "result" and result_owner == "human":
# No pending human request remains, so this is an unsolicited
# frame despite the SDK's human origin marker. It still needs the
# same synthetic owner as any other unsolicited terminal frame so
# the runtime gate stays held until durable delivery.
result_owner = "detached"
if message_type == "result" and result_owner == "detached" and pending:
self._detached_phase(composite_key, claim_activity=True)
return "detached"
if pending:
pending_request = pending[0]
retained = self._request_activities(pending_request)
if retained:
return None
pending_turn_ids = self._request_activity_turn_ids(pending_request)
activities = (
self._claim_activity_batch_for_turns(
registry,
composite_key,
pending_turn_ids,
)
if registry is not None
else []
)
if activities:
self._attach_request_activities(
pending_request,
activities,
)
return None
activities = (
registry.claim_completed_output_batch(self.name, composite_key)
if registry is not None
else []
)
if not activities:
return None
self._retain_activity_output_record(composite_key, activities)
logger.info(
"Claude Activity batch %s output detached from the current user turn in %s",
",".join(activity.id for activity in activities),
composite_key,
)
return "activity"
completed_activities = (
registry.claim_completed_output_batch(self.name, composite_key)
if registry is not None and not defer_activity_claim
else []
)
service = getattr(self.controller, "agent_service", None)
begin = getattr(service, "begin_agent_initiated_turn", None)
if not callable(begin):
if registry is not None:
self._requeue_activities(registry, completed_activities)
return None
payload = getattr(context, "platform_specific", None) or {}
runtime_key = str(payload.get(AGENT_RUNTIME_TURN_KEY) or "").strip() or composite_key
token = await begin(
self.name,
context,
runtime_key,
activation_identity=receiver_activation_identity,
)
if not token:
# The gate is CONTENDED — a user turn holds it, or one is queued on it
# and we must not block the receiver behind that waiter (deadlock; see
# begin_agent_initiated_turn). Keep Activity provenance until its real
# result branch consumes it. A generic ScheduleWakeup output has no
# Activity, so mark just this assistant/result sequence detached.
logger.info(
"Agent-initiated output for %s not opened: runtime gate contended "
"(a user turn holds or is queued on it)",
composite_key,
)
if completed_activities:
self._retain_activity_output_record(
composite_key,
completed_activities,
)
return "activity"
if message_type in {"assistant", "result"}:
self._detached_phase(composite_key, claim_activity=defer_activity_claim)
return "detached"
return None
# Mark the session ACTIVE so this in-flight agent-initiated turn gets the
# SAME idle-eviction exemption a user turn gets in ``handle_message``.
# Without it the turn is protected only by per-message activity touches and
# could be reclaimed mid-turn if it goes quiet past the idle timeout (e.g.
# it kicks off its own long background work). The terminal result / EOF /
# error / cancel paths all mark the session idle again, so this stays
# balanced; the stuck-active backstop still reclaims a wedged turn. (The
# SILENT wait BEFORE this first output is still bounded by the idle timeout
# — once the session is evicted the receiver is gone and no agent-initiated
# turn can open. See docs/plans/agent-initiated-turn-outbox.md.)
mark_active = getattr(self.session_handler, "mark_session_active", None)
if callable(mark_active):
mark_active(composite_key)
latest_activity = completed_activities[-1] if completed_activities else None
request = AgentRequest(
context=self._snapshot_output_context(context),
message="",
user_message="",
working_path=working_path,
base_session_id=base_session_id,
composite_session_id=composite_key,
session_key=session_key,
output=(
self._activity_message_output(
latest_activity,
detached=False,
completes_turn=True,
)
if latest_activity is not None
else None
),
output_activities=completed_activities,
)
request._claude_synthetic_owner = True
self._pending_requests.setdefault(composite_key, []).append(request)
self._synthetic_pending_owners[composite_key] = request
logger.info(
"Opened agent-initiated turn for session %s (unsolicited backend output)",
composite_key,
)
if message_type == "result" and result_owner == "detached":
if completed_activities:
self._retain_activity_output_record(
composite_key,
completed_activities,
)
return "activity"
self._detached_phase(composite_key, claim_activity=defer_activity_claim)
return "detached"
return None
def _mark_session_idle_if_no_pending_requests(self, composite_key: str) -> bool:
if self._has_pending_requests(composite_key):
return False
registry = self._activity_registry()
if registry is not None and registry.has_active(self.name, composite_key):
return False
mark_session_idle = getattr(self.session_handler, "mark_session_idle", None)
if callable(mark_session_idle):
mark_session_idle(composite_key)
return True
def _mark_session_idle_if_runtime_free(self, composite_key: str) -> bool:
service = getattr(self.controller, "agent_service", None)
runtime_turn_active = getattr(service, "runtime_turn_active", None)
if callable(runtime_turn_active) and runtime_turn_active(composite_key):
return False
return self._mark_session_idle_if_no_pending_requests(composite_key)
def _remove_pending_request(self, composite_key: str, request: AgentRequest) -> None:
requests = self._pending_requests.get(composite_key)
if not requests:
return
for index, pending_request in enumerate(requests):
if pending_request is request:
requests.pop(index)
break
if not requests:
self._pending_requests.pop(composite_key, None)
async def _remove_specific_pending_reaction(
self,
composite_key: str,
context: MessageContext,
request: AgentRequest,
*,
clear_on_platform: bool = True,
) -> None:
"""Remove a specific reaction from the queue by matching message_id.
Used on error paths to remove the current request's reaction instead of FIFO.
``clear_on_platform=False`` forgets the REGISTRY entry only. The registry
and the processing indicator both point at the same platform reaction, so
a caller that then calls ``_remove_ack_reaction`` would otherwise remove
it twice — and the second removal reports failure (the reaction is
already gone), which is exactly what suppresses a terminal receipt. A
stop hands both platform operations to ``finish()`` instead.
"""
target_id = getattr(request, "ack_reaction_message_id", None)
target_emoji = getattr(request, "ack_reaction_emoji", None)
if not target_id:
return
reactions = self._pending_reactions.get(composite_key)
if not reactions:
return
# Find and remove the matching reaction
for i, (msg_id, emoji) in enumerate(reactions):
if msg_id == target_id and emoji == target_emoji:
reactions.pop(i)
if not reactions:
self._pending_reactions.pop(composite_key, None)
if not clear_on_platform:
return
try:
await self.im_client.remove_reaction(context, msg_id, emoji)
except Exception as err:
logger.debug(f"Failed to remove reaction ack: {err}")
return
async def _clear_pending_reactions(
self,
composite_key: str,
context: MessageContext,
*,
preserve_pending_requests: bool = False,
) -> None:
"""Clear all pending reactions for a session (for error cleanup)."""
reactions = self._pending_reactions.pop(composite_key, None)
requests = (
None
if preserve_pending_requests
else self._pending_requests.pop(composite_key, None)
)
if reactions:
for message_id, emoji in reactions:
try:
await self.im_client.remove_reaction(context, message_id, emoji)
except Exception as err:
logger.debug(f"Failed to remove reaction ack: {err}")
if requests:
for request in requests:
self._requeue_request_activity(request)
await self._remove_ack_reaction(request)
def get_relative_path(self, abs_path: str, context: Optional[MessageContext] = None) -> str:
"""Convert absolute path to relative path from working directory."""
try:
cwd = self.session_handler.get_working_path(context)
abs_path = os.path.abspath(os.path.expanduser(abs_path))
rel_path = os.path.relpath(abs_path, cwd)
if rel_path.startswith("../.."):
return abs_path
return rel_path
except Exception:
return abs_path
def _get_target_context(self, context: MessageContext) -> MessageContext:
"""Return context for sending messages (respect Slack thread replies)."""
if self.im_client.should_use_thread_for_reply() and context.thread_id:
return MessageContext(
user_id=context.user_id,
channel_id=context.channel_id,
thread_id=context.thread_id,
message_id=context.message_id,
platform_specific=context.platform_specific,
)
return context
def _maybe_capture_session_id(
self,
message,
base_session_id: str,
session_key: str,
context: MessageContext,
*,
working_path: Optional[str] = None,
) -> Optional[str]:
"""Capture session id from system init messages."""
if (
hasattr(message, "__class__")
and message.__class__.__name__ == "SystemMessage"
and getattr(message, "subtype", None) == "init"
and getattr(message, "data", None)
):
session_id = message.data.get("session_id")
if session_id:
# avibe: bind the native id to the RESERVED workbench session row so
# the reply publishes under the open Chat session, not a freshly
# minted hidden row (Codex P1). Target subagents are the exception:
# their native id is persisted under the namespaced anchor, then the
# publish target is pinned back to the open Chat session.
reserved_id = self._reserved_agent_session_id(context)
uses_backend_anchor = self._uses_namespaced_backend_session(context)
reserved = self._bind_reserved_workbench_session(context, session_id)
if reserved:
return session_id
binder = getattr(self.session_handler, "bind_agent_session_id", None)
if callable(binder):
agent_session_id = binder(
session_key=session_key,
agent_name=self.name,
session_anchor=base_session_id,
native_session_id=session_id,
working_path=working_path,
)
else:
agent_session_id = self.session_handler.capture_session_id(
base_session_id,
session_id,
session_key,
working_path=working_path,
)
if agent_session_id:
payload = dict(context.platform_specific or {})
payload["agent_session_id"] = (
reserved_id if uses_backend_anchor and reserved_id else agent_session_id
)
context.platform_specific = payload
return session_id
return None
def _extract_text_blocks(self, message, _context: MessageContext) -> str:
"""Extract text-only content blocks for result fallbacks."""
parts = []
for block in getattr(message, "content", []) or []:
if isinstance(block, TextBlock):
text = block.text.strip() if block.text else ""
if text:
parts.append(text)
return "\n\n".join(parts).strip()
@staticmethod
def _is_model_refusal_fallback_message(message) -> bool:
return (getattr(message, "subtype", "") or "").strip().lower() == "model_refusal_fallback"
@staticmethod
def _parse_model_refusal_fallback_notice(message) -> Optional[tuple[str, str, str]]:
data = getattr(message, "data", None)
if not isinstance(data, dict):
return None
direction = str(data.get("direction") or "").strip().lower()
if direction and direction != "retry":
return None
original_value = data.get("original_model") or data.get("originalModel") or ""
fallback_value = data.get("fallback_model") or data.get("fallbackModel") or ""
original_model = " ".join(str(original_value).split())[:160]
fallback_model = " ".join(str(fallback_value).split())[:160]
provider_content = str(data.get("content") or "").strip()
if not provider_content and not (original_model and fallback_model):
return None
return original_model, fallback_model, provider_content
async def _handle_model_refusal_fallback(
self,
context: MessageContext,
composite_key: str,
notice: tuple[str, str, str],
) -> None:
"""Surface Claude's structured safety fallback without ending the turn."""
# Claude Code can write this marker after the fallback assistant row. Do
# not infer retraction order from the marker alone: the result path may
# still need that assistant text when ResultMessage.result is empty.
pending_requests = self._pending_requests.get(composite_key) or []
self._adopt_pending_turn_token(context, pending_requests[0] if pending_requests else None)
original_model, fallback_model, provider_content = notice
text = ""
translator = getattr(self.session_handler, "_t", None) or getattr(self.controller, "_t", None)
if callable(translator) and original_model and fallback_model:
text = translator(
"status.claudeRefusalFallback",
originalModel=original_model,
fallbackModel=fallback_model,
)
if not text:
text = provider_content
if not text:
logger.warning("Claude refusal fallback for %s had no displayable content", composite_key)
return
logger.info(
"Claude safety fallback for session %s: %s -> %s",
composite_key,
original_model or "<unknown>",
fallback_model or "<unknown>",
)
await emit_output(self.controller, context, Notice(text))
async def _handle_auth_failure_result(
self,
context: MessageContext,
composite_key: str,
subtype: str,
text: Optional[str],
) -> bool:
if not self._is_auth_failure_result(subtype, text):
return False
# The reused receiver still carries an EARLIER turn's ``turn_token``; adopt
# THIS turn's token (the FIFO head — the request this result belongs to, per
# the success path below) BEFORE the auth-recovery emit. The recovery helper
# now settles the failed dot through the outbound chokepoint, whose
# active-turn guard would otherwise treat the stale token as a superseded
# turn and skip the failed-status write for 2nd-or-later Claude auth failures.
pending = self._pending_requests.get(composite_key) or []
pending_request = pending[0] if pending else None
self._adopt_pending_turn_token(context, pending_request)
handled = await self.controller.agent_auth_service.maybe_emit_auth_recovery_message(
context,
"claude",
f"❌ Claude error: {text}",
output=terminal_output_for(pending_request),
terminal_error=text,
)
return handled
@staticmethod
def _is_auth_failure_result(subtype: str, text: Optional[str]) -> bool:
return bool(
text
and text.strip()
and (subtype or "").strip().lower() in {"error", "failed"}
and classify_auth_error("claude", text)
)
@staticmethod
def _error_value_text(value) -> str:
if isinstance(value, dict):
for key in ("message", "error", "type", "name"):
text = str(value.get(key) or "").strip()
if text:
return text
return str(value).strip()
return str(value or "").strip()
@classmethod
def _terminal_backend_failure(cls, message, text: Optional[str]) -> str | None:
"""Extract only structured terminal failure evidence from Claude frames."""
subtype = str(getattr(message, "subtype", "") or "").strip().lower()
error_value = getattr(message, "error", None)
errors = getattr(message, "errors", None)
api_status = getattr(message, "api_error_status", None)
structured_failure = bool(
getattr(message, "is_error", False)
or error_value
or bool(errors)
or api_status
or subtype == "failed"
or subtype.startswith("error")
or cls._is_synthetic_api_error_message(message, text)
)
if not structured_failure:
return None
candidates = [
str(text or "").strip(),
str(getattr(message, "result", "") or "").strip(),
cls._error_value_text(error_value),
]
error_token = cls._error_value_text(error_value).lower()
if not candidates[0] and error_token in {
"authentication_error",
"authentication_failed",
}:
candidates.insert(0, "OAuth authentication failed.")
if isinstance(errors, (list, tuple)):
candidates.extend(cls._error_value_text(item) for item in errors)
elif errors:
candidates.append(cls._error_value_text(errors))
if api_status:
candidates.append(f"API error status {api_status}")
candidates.append(subtype)
return next((candidate for candidate in candidates if candidate), "Claude backend failed")
@staticmethod
def _is_synthetic_api_error_message(message, text: Optional[str] = None) -> bool:
if not getattr(message, "isApiErrorMessage", False):
model = str(getattr(message, "model", "") or "").strip().lower()
if model != "<synthetic>":
return False
return ClaudeAgent._is_malformed_tool_call_retry_failure_text(text)
@staticmethod
def _is_malformed_tool_call_retry_failure_text(text: Optional[str]) -> bool:
normalized = " ".join((text or "").strip().lower().split())
if not normalized:
return False
return (
"tool call" in normalized
and "could not be parsed" in normalized
and "retry also failed" in normalized
)
@staticmethod
def _is_malformed_tool_call_retry_failure_result(message, text: Optional[str]) -> bool:
subtype = (getattr(message, "subtype", "") or "").strip().lower()
if subtype != "error" and not getattr(message, "is_error", False):
return False
candidates = [text or ""]
errors = getattr(message, "errors", None) or []
candidates.extend(str(error) for error in errors)
normalized = " ".join(" ".join(candidates).strip().lower().split())
if not normalized:
return False
if ClaudeAgent._is_malformed_tool_call_retry_failure_text(normalized):
return True
has_tool = "tool call" in normalized or "tool-call" in normalized or "tool-use" in normalized
has_parse = "parse" in normalized or "parsing" in normalized or "malformed" in normalized
has_retry = "retry" in normalized or "retried" in normalized
return has_tool and has_parse and has_retry
@staticmethod
def _extract_context_tokens(message) -> int:
"""Current context-window occupancy from an AssistantMessage's ``usage``.
Each AssistantMessage carries the RAW per-request Anthropic usage block
(``data["message"]["usage"]``), so its ``input_tokens +
cache_read_input_tokens + cache_creation_input_tokens`` is the full prompt
sent for that request — i.e. the whole context at that moment — and
``output_tokens`` is the response that joins the context for the next
request. The LATEST assistant message therefore reflects the current
occupancy, which the dispatcher SETs (not accumulates) so the figure
tracks the live context size and drops after a /compact.
NB: ``ResultMessage.usage`` is the CLI's CUMULATIVE turn usage (summed
across requests), so it overstates occupancy and must NOT be used here.
Defensive: ``usage`` may be a dict or object, or absent — returns 0 rather
than raising so a missing field never breaks the turn."""
usage = getattr(message, "usage", None)
if usage is None:
return 0
def _field(name: str) -> int:
value = usage.get(name) if isinstance(usage, dict) else getattr(usage, name, None)
try:
return int(value) if value and int(value) > 0 else 0
except (TypeError, ValueError):
return 0
return (
_field("input_tokens")
+ _field("cache_read_input_tokens")
+ _field("cache_creation_input_tokens")
+ _field("output_tokens")
)
def _detect_message_type(self, message) -> Optional[str]:
"""Infer message type name from Claude SDK class."""
if not hasattr(message, "__class__"):
return None
class_name = message.__class__.__name__
mapping = {
"SystemMessage": "system",
"UserMessage": "user",
"AssistantMessage": "assistant",
"ResultMessage": "result",
}
return mapping.get(class_name)
def _prepare_message_with_files(self, request: AgentRequest) -> str:
return message_with_files(request.message, request.files)