+jUdZddlZddlZddlZddlZddlZddlZddlmZm Z m Z ddl m Z m Z ddlmZddlmZmZmZmZmZmZmZmZddlmZejeZejd ejZ ejd ej!Z"ejd Z#d Z$e%e&d fe'd<de&de&fdZ(GddZ)dS)u LightClaw outbound message sender — builds and sends messages to the server. Mirrors: src/outbound.ts Streaming mode: GatewayStreamConsumer is active (SUPPORTS_MESSAGE_EDITING=True). Gateway calls send() with the first chunk, then edit_message() with accumulated full text for subsequent chunks, and finally edit_message(finalize=True). Round lifecycle: The round msgId spans the WHOLE agent turn (one user input → one round), so the front-end can aggregate streamed text, tool progress, post-stream follow-up text and attachment links into a single bubble. Closing the round (typing_stop + state cleanup) is the sole responsibility of stop_typing(), which the framework guarantees to invoke at turn end (see STREAMING_DESIGN.md §3.1 — at least four call sites). - Streaming: inbound typing_start → send(first_chunk) → edit_message() × N → edit_message(finalize=True) # only flushes residual delta → [optional tool_start / follow-up stream_chunk / attachment link]* → stop_typing() → typing_stop # framework-driven close - Commands: inbound typing_start → [tool_start]* → send(response) → stop_typing() → typing_stop # framework-driven close - Standalone: typing_start → stream_chunk → typing_stop (self-managed) N)AnyDictOptional)unquoteurlparse) SendResult) CHANNEL_KEYDEFAULT_AGENT_IDEVENT_MESSAGE_PRIVATE KIND_USAGELOCALFILE_SCHEMEMEDIA_MAX_BYTESgenerate_msg_id guess_mime)format_file_sizez+^.{1,2}\s+\w[\w_]*(?:\.\w+)*(?:\.\.\.|:|\()z)\bwrite_file\b.*?["\'/](/[^"\'<>\s,;}{]+)z"path"\s*:\s*"(/[^"]+)")u ▉u ▊u▉u▊._STREAM_CURSORStextreturnc|s|StD]1}||r|dt| cS2|S)zRemove a trailing streaming-cursor glyph if present. Idempotent and safe to call multiple times. Returns *text* unchanged when no cursor is found. N)rendswithlen)rcursors .usage.jsonl``. ``usage`` may be ``None`` — in that case we still write a line with ``"usage": null`` to preserve **ordinal alignment** with transcript turns: history-side join pairs the i-th sidecar entry with the i-th turn-end assistant, so a missing line would shift every subsequent turn by one and never self-heal. Best-effort: any error is logged at WARNING level and swallowed. The realtime usage frame has already been emitted (or skipped) by the caller, so a write failure only affects historical re-render — never the live UI. zK[lightclaw] usage persist skipped (session not yet indexed): to=%s msgId=%sNr:) roundMsgIdr<riF),rR) ensure_ascii separatorsT)exist_okazutf-8)encoding zD[lightclaw] usage placeholder persisted (no delta): path=%s msgId=%sz@[lightclaw] usage persisted: path=%s msgId=%s input=%s output=%s inputTokens outputTokensz9[lightclaw] usage persist failed: chat=%s msgId=%s err=%s)rgr+r,r@rAjsondumpsrdmakedirsredirnameopenwriter*OSErrorwarning) r.rFr7rhrilog_pathr_linefexcs r_persist_turn_usagez!OutboundMixin._persist_turn_usage s(# 33GXFFH  /\ *!$)++"455#%%E :e%JOOOD K11D A A A Ahg666 %!t $$$ % % % % % % % % % % % % % % %} 'l  )lIIm,,eii.G.G      NNKs          sH4EBE;C  E C$$E'C$(!E AE FE>>Fmetadatakwargsc K|jstdddSt|}|j|pt }|j|}|r t|o,t|dkot |}|rdnd} |} | dkr)|j |rd|z} d|j |<t d | ||t||t||| | || |r|||| dkr ||j|<td| S|j|} | rt|o,t|dkot |}|rdnd} | dkr|nd|z} t d | || t||t||| | | | td| S||}t|o,t|dkot |}|rt d ||t||t|||d|| ||td| St d||t||t||dd|| |t|||d|| |t||dd|| ||td| S)uSend a message to the user. Streaming mode behavior: - Round open (inbound already sent typing_start): - Tool progress → send as tool_start, keep round open - Stream first chunk → send as stream_chunk, record snapshot for subsequent edit_message() delta computation, keep round open - No round (standalone message, e.g. cron delivery): - typing_start → stream_chunk → typing_stop (full lifecycle) Fz Not connectedT)successerror retryablei tool_start stream_chunk zB[lightclaw] send (%s, round open): to=%s msgId=%s content=%d charsr#r/r7r message_idzH[lightclaw] send (%s, reuse last round): to=%s msgId=%s content=%d charszH[lightclaw] send (tool_start, no round): to=%s msgId=%s content=%d charsz>[lightclaw] send (standalone): to=%s msgId=%s content=%d charsr' typing_start typing_stop)r)rr_incoming_agent_idsr*r rIboolr_TOOL_PROGRESS_REmatchrNr+r,r1r rE_track_write_file_path_edit_snapshot_last_round_idrKrO) r.rFr&r5rrr7rhis_tool_progressmsg_kindactual_content last_round_ids rsendzOutboundMixin.sendJs$~ Te?dSSS S 'w//+//88L))*..w776%+g%5N37'0 KKT'<W     ! !%##^('($     >++GW===>))/6#G,d|DDD D+//88  F#SCLL3.S3D3J3J73S3S   (8K||^H $|33'9I  KKZ'=#g,,     ! !%##^((8$   d}EEE E33G<<   OG s* O/@/F/Fw/O/O    E KKZs7||     ! !%##W<'($      ) ) )d|DDD D  L \3w<<     !   .'3h  H H    !   ~#h        !   -'3h  H H   W%%%$<@@@@rc KdS)uSend typing indicator — no-op. Inbound already sends typing_start when a message arrives. LightClaw's typing_start persists until typing_stop — no refresh needed. N)r.rFrrs r send_typingzOutboundMixin.send_typings  rcK|j|}|sdS|j|pt}||d{V|jg|j||krH|j|\}}|t d|||d|d|d| t| |dt|||j|d|d||||| nX|d kr6t d ||||||d nt d ||||j|<t d ||| t| |dd||||j|<|j|d||dS)uStop typing indicator — sends typing_stop and closes the round. Called by the framework (gateway/run.py and base adapter) when: 1. Agent finishes processing (success or error) 2. Session processing completes in _process_message_background This is where the round gets properly closed with typing_stop. We also remember the closed round msgId in ``_last_round_id`` so that any output the framework routes AFTER this point (e.g. attachment links emitted via ``send_document`` / ``send_image``) can reuse the same msgId. The reservation lives until the next inbound message clears it. NzB[lightclaw] emit usage: to=%s msgId=%s input=%s output=%s total=%srsrt totalTokensr')chatIdri)r#r/r7r5r8)rFr7rhriunknownzA[lightclaw] usage placeholder (unmeasurable turn): to=%s msgId=%szI[lightclaw] usage skipped (no LLM turn, no sidecar entry): to=%s msgId=%sz'[lightclaw] stop_typing: to=%s msgId=%srr)rIr*rr _deliver_pending_files_usage_tracker_round_usage_emitted classify_turnr+r,r1r rEr _round_reply_torrrrMrO)r.rFrrhr7ri usage_reasons r stop_typingzOutboundMixin.stop_typings**733   F+//88LD %g . =w UUU  !   -#h      (4G$ ... W%%%%%rF)finalizerrrc 8Kt|}|j|}|r||krtd|S|j|d}||r|t |d} n:|} td||t |t ||j |pt} | r=| t| || d|| ||j|<|r+td||t | n7td ||t | |r |d dndtd|S) uEdit message — streaming delta computation and delivery. Called by GatewayStreamConsumer with accumulated full text (possibly with a cursor suffix like " ▉"). We strip the cursor, compute the delta against the previous snapshot, and emit a stream_chunk frame. ``finalize=True`` only marks the end of *one streaming segment*, NOT the end of the whole agent turn. After a streamed answer the agent may still emit tool progress, follow-up text, attachment links, etc., and they should all reuse the same round msgId so the front-end can aggregate them into a single bubble. Therefore round closure (typing_stop + ``_clear_round_id``) is delegated entirely to ``stop_typing()``, which the framework guarantees to invoke at the end of the turn (see STREAMING_DESIGN.md §3.1 — at least four guaranteed call sites). Here we only flush the residual delta and keep the snapshot in sync so any subsequent ``edit_message`` calls within the same round still compute correct deltas. Tool progress edits (message_id != round_msg_id) are ignored. Trr'Nz[[lightclaw] edit_message delta fallback: to=%s msgId=%s previous=%d chars, content=%d charsrrzi[lightclaw] edit_message finalize (round kept open for post-stream output): to=%s msgId=%s delta=%d charszJ[lightclaw] edit_message: to=%s msgId=%s delta=%d chars, content_tail='%s'i)rrIr*rr startswithrr+r|rr r1r rEr,) r.rFrr&rrrrhpreviousdeltar7s r edit_messagezOutboundMixin.edit_message\sB'w//**733  C|z99dzBBB B&**7B77   h ' ' CMMNN+EEE NN6s8}}c'll   +//88L>>>r image_urlcaptioncK|stddS|drX|pd}d|d}|r|d|n|}||||| d {VS|d r|t d d }||} | r ||| ||| d {VStdd |S)uSend an image reference without proactive upload. Three input shapes are handled in-order: * ``http(s)://...`` → embed as Markdown image tag (no IO) * ``file://...`` → strip scheme, treat as local path * absolute local path → delegate to :meth:`_send_attachment` which emits a ``localfile://`` link Fzimage_url is requiredrr)zhttp://zhttps://r'z ![image]()rr5rNfile://)rr5rzImage not found: )rrrstriprYrr_resolve_attachment_path_send_attachment) r.rFrrr5rrmdpayloadresolveds r send_imagezOutboundMixin.send_imagesf  Le3JKKK K    7 8 8 [Mr))++D)Y)))B37?''2''--///RG7GhQYZZZZZZZZ Z    * * 3!#i..//2I00;;  ..7!H/  %/N9/N/NOOOOr file_pathc||rtj|sdStj|}t |}t |d5}t j| }dddn #1swxYwY||d|d|dS)uNRead *file_path* and wrap it as a base64 ``FileAttachment`` dict. Currently unused — we deliver files via ``localfile://`` Markdown links instead of base64 WS payloads. Kept for potential future use (e.g. a small-file fast-path) and for API compatibility with the TS ``sendFiles`` emitter. Nrbzdata:z;base64,)namemimeTypebytes) rdreisfilebasenamerrybase64 b64encodereaddecode)r.r file_namemimerr s r_file_to_attachmentz!OutboundMixin._file_to_attachments y 9 9 4G$$Y// )$$ )T " " 7a#AFFHH--4466D 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7!t>Zd>Z>ZTX>Z>Z[[[s"9B''B+.B+rcZKtd|||pddd||}|s6|||}|rtd|||}|sxtd||||rt j|nd} | |d| d |d || d{VS||krtd |||} t j |} nG#t$r:} td || tdd| cYd} ~ Sd} ~ wwxYw| tkr"td|t| t j|} |pt j| } |j|t#| d| dt&| d} |dt)| d}n#t*$rYnwxYw|pd}|r|d|n|}| |||| d{VS)aDeliver a local file by emitting a ``localfile://`` Markdown link. Never uploads. Never embeds base64 binary. The caller usually provides a local path; we normalize that exact path deterministically (``file://`` decode, ``~`` / env expansion, relative-path anchoring) without probing sibling directories, then emit an inline Markdown link through the standard text send path. z@[lightclaw] _send_attachment invoked: chat=%s file=%r caption=%rr'N<uG[lightclaw] attachment path corrected via tracked write_file: %r → %rue[lightclaw] attachment file not found: original=%r tried=%s — notifying user instead of silent dropz (unknown)u)⚠️ 文件已生成但读取失败：`u `（路径 `u` 不可访问）ru/[lightclaw] attachment path resolved: %r → %rz+[lightclaw] attachment stat failed: %r (%s)Fz Stat failed: rz`[lightclaw] file %s exceeds %d bytes (got %d); advertising link anyway, download may be rejectedu📎 [z](rz (r)r+r,r_correct_attachment_pathr|_attachment_candidatesrdrerrgetsizer{rrabspath_delivered_paths setdefaultsetaddrr ExceptionrrY)r.rFrrrr5r resolved_path correcteddisplaysizerabs_path display_namelinkrrs rrzOutboundMixin._send_attachments\"  N YB 4   55i@@  * 55gyIII * ,y !*   NNE466yAA   6?Obg&&y111KGmGmmQZmmm!H#  I % % KKA=   "  J7??9--DD J J J NNH)UX Y Y Ye3H33H3HIII I I I I I I J / ! ! NND?D    7??9-- >BG$4$4X$>$>  ((#%%88<z:OutboundMixin._correct_attachment_path..s0BBB!!Bq0A0ABABBBrNr'r.r r) _pending_file_pathsr*rdrerrYrsplitr)r.rFrpendingexistingreq_baserreq_stems rrz&OutboundMixin._correct_attachment_pathsC *..w77=2BBwBBB 47## _" # # % % , ,] ; ;     Aw""h../ >>#q))!,    7##A&&,,S!44Q78CCHHHD x==A  A; trc d|vrdSd}t|}|r(|dd}|s5d|vr1t|}|r|d}|r*|dr|drdS|j|g}||vr3| |t d||dSdS) zEExtract and stash the file path from a write_file tool_start message. write_fileNr z "',;:.)}]z"path"/z...z4[lightclaw] tracked write_file path: chat=%s path=%r) _WRITE_FILE_PATH_REsearchgroupr _JSON_PATH_RErrrrrr+r,)r.rFr&remm2rs rrz$OutboundMixin._track_write_file_paths) w & & F" & &w / /  3771::$$\22D #G++%%g..B #xx{{ 4??3// 4==3G3G  F*55grBB w   NN4 KKF       rcK|j|g}|sdS|j|t}|D]}tj|}||vrtd||Btj |std||~td||| ||d{VdS)alAuto-deliver write_file results that weren't tagged with MEDIA:. Called by stop_typing() BEFORE emitting typing_stop so the attachment links land inside the same message bubble as the rest of the response. Paths already delivered this turn (via the framework's send_document() path) are skipped using ``_delivered_paths``. NzB[lightclaw] skip auto-deliver (already delivered): chat=%s path=%rz?[lightclaw] skip auto-deliver (file not found): chat=%s path=%rzT[lightclaw] auto-delivering write_file result (model missed MEDIA:): chat=%s path=%r) rrMrrrdrerr+r,rr)r.rFr deliveredrers rrz$OutboundMixin._deliver_pending_filess+*..w;;  F)--gsuu==  7 7Dwt,,H9$$ &T 7>>$''  UT KK"    ''66 6 6 6 6 6 6 6 6) 7 7rc $K|rYtj|}|j|t ||||||||dd{VS)Nr)r) rdrerrrrrrr*)r.rFrrrr5rrs r send_documentzOutboundMixin.send_document"s  Kwy11H  ! , ,Wcee < < @ @ J J J**7Iw S[4:JJz4J4J+LLLLLLLL Lr audio_pathc lK||||||dd{VSNrrrr*)r.rFrrr5rs r send_voicezOutboundMixin.send_voice0d**7JRZ4:JJz4J4J+LLLLLLLL Lr video_pathc lK||||||dd{VSrr)r.rFrrr5rs r send_videozOutboundMixin.send_video7rr image_pathc lK||||||dd{VSrr)r.rFrrr5rs rsend_image_filezOutboundMixin.send_image_file>rr)NNrH)NNN)NNNN)&__name__ __module__ __qualname____doc__rdictr1rr4r rlistrErKrOrbrgrrrrrrrrrrr staticmethodrrrrrrrrrrrrrrasM  &9c99$9999 G#GTGdGGGG$"& $ $( $$$ $$ $ 3- $ ~ $ $$~$ $$$$L(s(s(((( 3s3t33338"I"I&)"I #"I"I"I"IH G G&) G # G G G G777 7 S#X' 7  7777B#'-1 VAVAVAVA3- VA 4S>* VA  VA VAVAVAVAv.2     4S>*         k&k&k&k&k&k&k&f-1M?M?M?M?M? M?  M?4S>*M?M? M?M?M?M?T"&"&-1 %P%P%P%P# %P 3- %P 4S>* %P %P%P%P%PV\S\Xd^\\\\("&#'"&-1]W]W]W]W# ]W C= ]W 3- ]W4S>*]W ]W]W]W]WF3#3$333\3jCHSM\<++'*+ #++++ZcCD< 7C 7D 7 7 7 7FFJCG L L L'* L5=c] LC= L3;C= L  L L L LGK"&LLL(+L6>smL3-L LLLLGK"&LLL(+L6>smL3-L LLLLGK"&LLL(+L6>smL3-L LLLLLLrr)*r#rruloggingrdrerAtypingrrr urllib.parserrgateway.platforms.baserconfigr r r r rrrrmediar getLoggerr r+compileUNICODErDOTALLr r rtupler__annotations__rrrrrr4s<  &&&&&&&&&&********------                    $#####  8 $ $BJ2BJ!bj0I 566 $NsCxMMM s s    bLbLbLbLbLbLbLbLbLbLr