idZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddl mZddlmZmZddlmZddlmZmZd d lmZmZmZd d lmZd d lmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z% d$ d%dZ& d$ d&dZ' d$ d'dZ(eGddZ) d( d)dZ* d*dZ+ d+dZ, d,dZ-e.hdZ/d-dZ0 d.dZ1 d/dZ2d0dZ3ejhdZ5e.hdZ6d1dZ7d2dZ8 d$ d3d Z9 d$ d4d!Z: d$ d5d"Z; d( d6d#Z,sessionId:}`` JSONL entry. ``list_sessions`` reads the LAST tag from the file tail — most recent wins. Passing ``None`` appends an empty-string tag entry which ``list_sessions`` treats as ``None`` (cleared). Tags are Unicode-sanitized before storing (removes zero-width chars, directional marks, private-use characters, etc.) for CLI filter compatibility. Args: session_id: UUID of the session to tag. tag: Tag string, or ``None`` to clear. Leading/trailing whitespace is stripped. Must be non-empty after sanitization and stripping (unless ``None``). directory: Project directory path (same semantics as ``list_sessions(directory=...)``). When omitted, all project directories are searched for the session file. Raises: ValueError: If ``session_id`` is not a valid UUID, or if ``tag`` is empty/whitespace-only after sanitization. FileNotFoundError: If the session file cannot be found. See Also: :func:`tag_session_via_store` for the :class:`SessionStore`-backed async variant. Example: Tag a session:: tag_session( "550e8400-e29b-41d4-a716-446655440000", "experiment", directory="/path/to/project", ) Clear a tag:: tag_session(session_id, None) rN)tag must be non-empty (use None to clear)tag)rr6r r!r$r&)rr'_sanitize_unicoder(r)r*r+)r,r6r. sanitizedr0s r1 tag_sessionr:ps^ * %/ |<== %c*002 HI I !os2'  "     z43r3cxt|std|t||}|td|d|r d|zdz |j tj|j|z dy#t $r3}|j t jk(rtd|d|d}~wwxYw) uDelete a session by removing its JSONL file and subagent transcripts. This is a hard delete — the ``{session_id}.jsonl`` file is removed permanently, along with the sibling ``{session_id}/`` subdirectory that holds subagent transcripts (if it exists). SDK users who need soft-delete semantics can use ``tag_session(id, '__hidden')`` and filter on listing instead. Args: session_id: UUID of the session to delete. directory: Project directory path (same semantics as ``list_sessions(directory=...)``). When omitted, all project directories are searched for the session file. Raises: ValueError: If ``session_id`` is not a valid UUID. FileNotFoundError: If the session file cannot be found. See Also: :func:`delete_session_via_store` for the :class:`SessionStore`-backed async variant. Example: Delete a session:: delete_session("550e8400-e29b-41d4-a716-446655440000") rNSession not found in project directory for r7T) ignore_errors) rr'_find_session_fileFileNotFoundErrorunlinkOSErrorerrnoENOENTshutilrmtreeparent)r,r.pathes r1delete_sessionrKs> * %/ |<== j) 4D |zl* -;D+I;7 N  JL N    MM$++ *$?  77ell "#hzl*$EFA M sA== B9.B44B9ceZdZUdZded<y)ForkSessionResultzResult of a fork operation.strr,N)__name__ __module__ __qualname____doc____annotations__r3r1rMrMs %O)r3rMct|std||rt|std|t||}|td|d|r d|zdz|\}}|j std|dt |\}}dfd } t |||||| \} } || d z } tj| tjtjztjzd } tj| d j| d zjd tj| t!| S#tj| wxYw)aFork a session into a new branch with fresh UUIDs. Copies transcript messages from the source session into a new session file, remapping every message UUID and preserving the ``parentUuid`` chain. Supports ``up_to_message_id`` for branching from a specific point in the conversation. Forked sessions start without undo history (file-history snapshots are not copied). Args: session_id: UUID of the source session to fork. directory: Project directory path (same semantics as ``list_sessions(directory=...)``). When omitted, all project directories are searched for the session file. up_to_message_id: Slice transcript up to this message UUID (inclusive). If omitted, copies the full transcript. title: Custom title for the fork. If omitted, derives from the original title + " (fork)". Returns: ``ForkSessionResult`` with the new session's UUID. Raises: ValueError: If ``session_id`` or ``up_to_message_id`` is not a valid UUID. FileNotFoundError: If the source session file cannot be found. ValueError: If the session has no messages to fork, or if ``up_to_message_id`` is not found in the transcript. See Also: :func:`fork_session_via_store` for the :class:`SessionStore`-backed async variant. Example: Fork a session:: result = fork_session("550e8400-e29b-41d4-a716-446655440000") print(result.session_id) Fork from a specific point:: result = fork_session( "550e8400-e29b-41d4-a716-446655440000", up_to_message_id="660e8400-e29b-41d4-a716-446655440001", ) rInvalid up_to_message_id: r<r=r>r7 has no messages to forkc>t}dt|tjdd}t d|tz djdd}t |dxs9t |dxs+t |dxst |dxst |xsdS)Nutf-8replaceerrorsrraiTitle)lenminrdecodemaxrr)buf_lenheadtailcontents r1 _derive_titlez#fork_session.._derive_title8sg,9W&89:AA IB s1g(::;=>EE IF  ,D- @ .t]C .tY? /tY? /t4     r3.jsonlir&rYr,)return str | None)rr'_find_session_file_with_dirrA read_bytes_parse_fork_transcript_build_fork_linesosopenO_WRONLYO_CREATO_EXCLwritejoinencodecloserM)r,r.up_to_message_idr-source file_path project_dir transcriptcontent_replacementsrfforked_session_idlines fork_pathfdres @r1 fork_sessionrsj * %/ |<==/? @56F5GHII (Y ?F ~zl* -;D+I;7 N  JL N  $I{""$G 8J?  (9 ::  s 7EE0c d|Dcgc]}|jdr|}}|std|d|rKd}t|D]\}} | jd|k(s|}n|dk(rtd|d||d|d z}i} |D]%} tt j | | d<'|Dcgc]}|jd d k7s|} }| std|di} |D] } | | | d< tt j } t jtjjjd d }g}t| D]\}}| |d}d}|jd}|rN| j|}|sn:|jd d k7r| j|}n|jd}|rN|t| d z k(r|n|jd|}|jd}|r| j|n|}i||||| |d||ddd}dD]}|j|d|jtj |d|rG|jtj d| |tt j |dd|r|j#nd}|s|xsdd}|jtj d| |tt j |dd| |fScc}wcc}w)uCore fork transform — remap UUIDs and produce serialized JSONL lines. Shared by the filesystem and SessionStore-backed paths. Returns ``(forked_session_id, lines)`` where each line is a compact JSON string without a trailing newline. ``derive_title`` is invoked only when no explicit ``title`` is given, so the disk path's head/tail byte scan and the store path's entry scan only run when needed. isSidechainr<rWuuidzMessage z not found in session Nrrprogress+00:00Z parentUuid timestamplogicalParentUuidF)r messageUuid)rrrr rr forkedFrom)teamName agentNameslugsourceToolAssistantUUIDr!r$content-replacement)rr replacementsrrzForked sessionz (fork)r)rr rrr)getr' enumeraterNuuid_moduuid4rnowrutc isoformatrZr^popappendr)r*r()r|r}r,rxr- derive_titlerJcutoffientry uuid_mappingwritableby_uuidr~rroriginalnew_uuidnew_parent_uuid parent_idrHrlogical_parentnew_logical_parentforkedkey fork_titles r1rnrn\sr((DZquu]/C!ZJD 8JL  ^ ,N     )!3*" ''/  PC JJsD !P  TZZ:>?U+Z JJ1!2$8 01!$ &  #(TJ $:*:;7C  LL &.)HNN,-  "   e ##iE0FsL(L(0L- L-c,t||}|r|dSdS)z]Find the path to a session's JSONL file. Returns the path if found, None otherwise. rN)rk)r,r.results r1r@r@s!)Y ?F6!9(D(r3c |d d fd }|rZt|}t|}| ||}|r|S t|}|D]$}||k(r t|}|||}|s"|cSyt } t | j } | D]} || }|s|cSy#t$rg}YqwxYw#t$rYywxYw)zFind a session file and its containing project directory. Returns ``(file_path, project_dir)`` or None. The fork operation needs the project dir to write the new file adjacent to the source. rgcx|z } |j}|jdkDr||fS y#t$rYywxYw)Nr)statst_sizerC)r{rIst file_names r1_try_dirz-_find_session_file_with_dir.._try_dirsTY& BzzA~k**   s "- 99N)r{rrituple[Path, Path] | None)rrr ExceptionrlistiterdirrC) r,r.r canonicalr{rworktree_pathswtwt_project_dir projects_dirdirentsrrs @r1rkrks,f%I&y1 ' 2  "k*F  0;N!BY.r2N)!.1!M!$&L|++-.% M + N  s# B#4B4# B10B14 C?C>usersystemr assistant attachmentc6d}d}|D]_}t|ts|jd}t|tr|r|}|jd}t|ts[|s^|}a|r|S|r|Sdj d|Ddz}t |xsdS)a%Mirror the disk path's head/tail title scan over parsed entry objects. Precedence matches ``_extract_last_json_string_field`` semantics: last occurrence wins for both ``customTitle`` and ``aiTitle``; ``customTitle`` beats ``aiTitle``; first user prompt is the final fallback. Nrr]r&c3JK|]}tj|dyw)r!r$N)r)r*).0rJs r1 z-_derive_title_from_entries..JsHCqdjjz::Cs!#) isinstancedictrrNrur)rawcustomairJctatjsonls r1_derive_title_from_entriesr2sFB !T"  UU= ! b# 2F UU9  b# 2B    IIHCH H4 OE *5 1 9T9r3cBg}g}|jddjD]}|j}|s tj|}t|ts=|jd}|tvr1t|jdtr|j||dk(s|jd|k(st|jdts|j|d||fS#tj t f$rYwxYw) zParse JSONL content into transcript entries + content-replacement records. Only keeps entries that have a uuid and are transcript message types. Content-replacement entries are collected for re-emission in the fork. rYrZr[rrrr r)r` splitlinesr(r)loadsJSONDecodeErrorr'rrr_TRANSCRIPT_TYPESrNrrextend)rer,r|r}liner entry_types r1rmrmNs(*J&(wy9DDFzz|  JJt$E%& YYv& * *z%))F:KS/Q   e $ / / +&*4599^4d; ' 'n(= >%G( + ++$$j1   sDDDc|d}|rqt|}t|}|t||z |ry t|}|D]'}||k(r t|}|t||z |s'yt d|d|t } t| j} | D]} t| |z |syt d|d#t$rg}YwxYw#t$r} t d|d| d} ~ wwxYw)uAppend data to an existing session file. Searches candidate paths and tries the append directly — no existence check. Uses O_WRONLY | O_APPEND (without O_CREAT) so the open fails with ENOENT for missing files, avoiding TOCTOU. rgNr<z$ not found in project directory for z" not found (no projects directory)z# not found in any project directory) rr _try_appendrrrArrrrC) r,r0r.rrr{rrrrrrJrs r1r+r+psF,f%I&y1 ( 2  "{;3JD'Q  0;N!BY.r2N)k*D/! zl"Fyk R  %&L|++-.  uy($ /  hzl2UV WW5 N & zl"D E  s) CC CC C3C..C3c tj|tjtjz} tj|}|jdk(r tj|ytj||jd tj|y#t$r7}|j t j t jfvrYd}~yd}~wwxYw#tj|wxYw)uTry appending to a path. Opens with O_WRONLY | O_APPEND (no O_CREAT), so the open fails with ENOENT if the file does not exist — no separate existence check. Returns ``True`` on successful write, ``False`` if the file does not exist (ENOENT/ENOTDIR) or is 0-byte. A 0-byte ``.jsonl`` is a "session not here, keep searching" signal that readers (``_read_session_lite``) already honor; without this guard the search would stop at an empty stub in one project dir while the real file lives in a worktree. Re-raises all other errors (ENOSPC, EACCES, EIO, etc.) so real write failures surface. O_APPEND semantics: Python's ``os.open`` with ``os.O_APPEND`` maps to the kernel's append mode on all platforms. On POSIX, O_APPEND makes the kernel atomically seek-to-EOF on every write (race-free). On Windows, CPython's ``os.open`` translates O_APPEND to ``FILE_APPEND_DATA`` (also atomic). CPython handles this correctly on all platforms, so no explicit-position fallback is needed. NFrrYT) rorprqO_APPENDrCrDrEENOTDIRfstatrrwrtrv)rIr0rrJrs r1rrs( WWT2;;4 5 xx| <<1    T[[)*    77u||U]]3 3   s.5B/$C23%C2/ C/8,C*)C**C/2D u![​-‏‪-‮⁦-⁩-]>CfCnCoc|}tdD]P}|}tjd|}djd|D}tj d|}||k(sO|S|S)zSanitize a string by removing dangerous Unicode characters. Iteratively applies NFKC normalization and strips format/private-use/unassigned characters until no more changes occur (max 10 iterations). NFKCr7c3XK|]"}tj|tvs|$ywN) unicodedatacategory_FORMAT_CATEGORIES)rcs r1rz$_sanitize_unicode..s' !+"6"6q"9AS"SAws **)ranger normalizeru_UNICODE_STRIP_REsub)valuecurrent_previouss r1r8r8stG 2Y''8''   $''G4 h   N Nr3ctjtjj j ddS)Nrr)rrrrrrZrTr3r1_iso_nowrs+ << % / / 1 9 9(C HHr3cDKt|std||j}|s tdt|}||d}d||t t j td}|j|tt|gd{y7w)axRename a session by appending a custom-title entry to a :class:`SessionStore`. Async, store-backed counterpart to :func:`rename_session`. Args: session_store: The store to write to. session_id: UUID of the session to rename. title: New session title. Leading/trailing whitespace is stripped. Must be non-empty after stripping. directory: Project directory used to compute the ``project_key``. Defaults to the current working directory. Raises: ValueError: If ``session_id`` is not a valid UUID, or if ``title`` is empty/whitespace-only. rr project_keyr,r)rrr rrN) rr'r(rrNrrrrr r) session_storer,r-r.r/rrrs r1rename_session_via_storers, * %/ |<=={{}H 233+I6K&1LCHNN$%Z E   sT*;U%C$D EEEsBB BB cfKt|std||(t|j}|s td|}t |}||d}d||nd|t t jtd}|j|tt|gd{y7w)a{Tag a session by appending a tag entry to a :class:`SessionStore`. Async, store-backed counterpart to :func:`tag_session`. Pass ``None`` to clear the tag. Tags are Unicode-sanitized before storing. Args: session_store: The store to write to. session_id: UUID of the session to tag. tag: Tag string, or ``None`` to clear. directory: Project directory used to compute the ``project_key``. Defaults to the current working directory. Raises: ValueError: If ``session_id`` is not a valid UUID, or if ``tag`` is empty/whitespace-only after sanitization. rNr5rr6r7)rr6r rr) rr'r8r(rrNrrrrr r)rr,r6r.r9rrrs r1tag_session_via_storer*s, * %/ |<== %c*002 HI I+I6K&1LCos2HNN$%Z E   sT*;U%C$D EEEsB'B1)B/*B1cKt|std|t|dsyt|}||d}|j |d{y7w)u.Delete a session from a :class:`SessionStore`. Async, store-backed counterpart to :func:`delete_session`. If the store does not implement :meth:`SessionStore.delete`, deletion is a no-op (appropriate for WORM/append-only backends — matches the :class:`SessionStore` contract). Whether subagent transcripts under the session are also removed depends on the store's ``delete({session_id})`` semantics — :class:`InMemorySessionStore` cascades; custom stores may not. Args: session_store: The store to delete from. session_id: UUID of the session to delete. directory: Project directory used to compute the ``project_key``. Defaults to the current working directory. Raises: ValueError: If ``session_id`` is not a valid UUID. rdeleteNr)rr'rrr)rr,r.rrs r1delete_session_via_storerSsX2 * %/ |<== ]H 5+I6K&1LC   s ###sA A AAc  Kt|std||rt|std|t|}||d}|j|d{}|st d|dt d|g}g} D]} | j d} | tvr1t| j d tr|j| M| d k(sS| j d |k(sht| j d ts| j| d t|| |||fd \} } || d}|j|| Dcgc]}tj|c}d{t!| S7(cc}w7w)u$Fork a session into a new branch with fresh UUIDs via a :class:`SessionStore`. Async, store-backed counterpart to :func:`fork_session`. Runs the fork transform directly over the objects returned by ``session_store.load()`` — no JSONL round-trip. A storage-layer copy (e.g. S3 CopyObject) is NOT sufficient: the transform remaps every UUID, rewrites ``sessionId`` on each entry, and stamps ``forkedFrom``, so the data must pass through this process once. Args: session_store: The store to read the source from and write the fork to. session_id: UUID of the source session to fork. directory: Project directory used to compute the ``project_key``. Defaults to the current working directory. up_to_message_id: Slice transcript up to this message UUID (inclusive). If omitted, copies the full transcript. title: Custom title for the fork. If omitted, derives from the original title + " (fork)". Returns: ``ForkSessionResult`` with the new session's UUID. Raises: ValueError: If ``session_id`` or ``up_to_message_id`` is not a valid UUID, or if the session has no messages to fork. FileNotFoundError: If the source session is not found in the store. rrVrNr<r=list[dict[str, Any]]rrrr rctSr)r)rsr1z(fork_session_via_store..s *3/r3rh)rr'rloadrAr rrrrNrrrrnr)rrM)rr,r.rxr-rsrc_keyloadedr|r}rrr~rdst_keyrrs @r1fork_session_via_storerusF * %/ |<==/? @56F5GHII+I6K*5ZPG %%g. .F (:,j ABB !%%;V DC')J&(YYv& * *z%))F:KS/Q   e $ / / +&*4599^4d; ' 'n(= > 1 /  u+6EVWG   we(LedD)9e(L MMM (9 ::I/F)MMsDAFFA9FF,F AF F ) F3F 4FFr)r,rNr-rNr.rjriNone)r,rNr6rjr.rjrir )r,rNr.rjrir )NNN) r,rNr.rjrxrjr-rjrirM)r|rr} list[Any]r,rNrxrjr-rjrzCallable[[], str | None]riztuple[str, list[str]])r,rNr.rjriz Path | None)r,rNr.rjrir)rr rirj)rebytesr,rNriz&tuple[list[dict[str, Any]], list[Any]])r,rNr0rNr.rjrir )rIrr0rNribool)rrNrirN)rirN) rr r,rNr-rNr.rjrir ) rr r,rNr6rjr.rjrir )rr r,rNr.rjrir ) rr r,rNr.rjrxrjr-rjrirM)=rR __future__rrDr)rorerFrrrcollections.abcr dataclassesrrrpathlibrtypingr r typesr r rsession_store_validationrsessionsrrrrrrrrrr2r:rKrMrrnr@rk frozensetrrrmr+rcompilerrr8rrrrrrTr3r1rsW$# $!'??7   (!8484 8484 84|!C4C4 C4C4 C4P!/@/@/@ /@d ** *!#' i;i;i;!i;  i;  i;XH$$H$#H$H$! H$  H$ + H$H$` ) ) ) )4444nWX:8, , #,+,D3X3X 3X3X 3Xl!VBJJ128I! &F&F&F &F &F  &FZ! &F&F&F &F &F  &FX!$$$$ $J!#' M;M;M;M;! M;  M;  M;r3