ctxttools 0.4.1__tar.gz → 0.4.2__tar.gz

{ctxttools-0.4.1/ctxttools.egg-info → ctxttools-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxttools
-Version: 0.4.1
+Version: 0.4.2
 Summary: CLI tools for LLM conversations
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -12,6 +12,7 @@ Requires-Dist: platformdirs>=3.0.0
 Requires-Dist: tomli>=2.0.0; python_version < "3.11"
 Provides-Extra: mcp
 Requires-Dist: mcp<2.0,>=1.2.0; extra == "mcp"
+Requires-Dist: pyyaml>=6.0; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Dynamic: license-file
@@ -210,7 +211,7 @@ ctools grep --hosts "mcp config"            # also the hosts in ctools.toml
 
 ```bash
 ctools cat opencode/ses_abc           # JSON list of {role, content}
-ctools cat --text opencode/ses_abc    # a readable transcript
+ctools cat --text opencode/ses_abc    # a markdown transcript (**role**:/content)
 ctools cat ssh://me@box/pi/<id>       # a session on another machine
 ```
 
@@ -239,11 +240,20 @@ in, and `exec`s the command (replacing ctools). It's the one verb that
 "leaves ctools".
 
 ```bash
+ctools resume claude-code/55b9c8b7-788b-4f9e-a8b7-cfa0461b357b  # a cdir row, pasted
 ctools resume claude-code a293cac2   # cd + exec `claude --resume a293cac2`
 ctools resume pi <id>                # `pi --session <id>`
-ctools dir --resume-command pi <id>  # just print the command, don't exec it
+ctools resume .                      # the most recent session in this directory
+ctools dir --resume-command pi/<id>  # just print the command, don't exec it
 ```
 
+The session is named the way `cdir` prints it — `agent/session`, the
+two-word `agent session`, or a bare id resolved across the installed
+agents. A directory (`.`, `..`, `/path`, `~/proj`) instead names the most
+recently recorded session in it; `resume <agent> .` scopes that to one
+agent. `resume` says which session a directory resolved to before it
+leaves.
+
 The resume command comes from the agent backend and is overridable per
 machine in `~/.config/ctools/resume-commands.json`. The `cd` into the
 recorded directory matters: `claude --resume` only finds a session from the

ctxttools-0.4.1/PKG-INFO → ctxttools-0.4.2/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.4
-Name: ctxttools
-Version: 0.4.1
-Summary: CLI tools for LLM conversations
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE.MIT
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tiktoken>=0.5.0
-Requires-Dist: structlog>=24.0
-Requires-Dist: platformdirs>=3.0.0
-Requires-Dist: tomli>=2.0.0; python_version < "3.11"
-Provides-Extra: mcp
-Requires-Dist: mcp<2.0,>=1.2.0; extra == "mcp"
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Dynamic: license-file
-
 # ctools
 
 <p align="center">
@@ -210,7 +192,7 @@ ctools grep --hosts "mcp config"            # also the hosts in ctools.toml
 
 ```bash
 ctools cat opencode/ses_abc           # JSON list of {role, content}
-ctools cat --text opencode/ses_abc    # a readable transcript
+ctools cat --text opencode/ses_abc    # a markdown transcript (**role**:/content)
 ctools cat ssh://me@box/pi/<id>       # a session on another machine
 ```
 
@@ -239,11 +221,20 @@ in, and `exec`s the command (replacing ctools). It's the one verb that
 "leaves ctools".
 
 ```bash
+ctools resume claude-code/55b9c8b7-788b-4f9e-a8b7-cfa0461b357b  # a cdir row, pasted
 ctools resume claude-code a293cac2   # cd + exec `claude --resume a293cac2`
 ctools resume pi <id>                # `pi --session <id>`
-ctools dir --resume-command pi <id>  # just print the command, don't exec it
+ctools resume .                      # the most recent session in this directory
+ctools dir --resume-command pi/<id>  # just print the command, don't exec it
 ```
 
+The session is named the way `cdir` prints it — `agent/session`, the
+two-word `agent session`, or a bare id resolved across the installed
+agents. A directory (`.`, `..`, `/path`, `~/proj`) instead names the most
+recently recorded session in it; `resume <agent> .` scopes that to one
+agent. `resume` says which session a directory resolved to before it
+leaves.
+
 The resume command comes from the agent backend and is overridable per
 machine in `~/.config/ctools/resume-commands.json`. The `cd` into the
 recorded directory matters: `claude --resume` only finds a session from the

{ctxttools-0.4.1 → ctxttools-0.4.2}/ctools/agents.py

@@ -510,12 +510,15 @@ class Agent:
         """
         return self._session_cwd(session_id)
 
-    def from_common(self, doc: Dict[str, object], cwd: Optional[str] = None) -> str:
+    def from_common(self, doc: Dict[str, object], cwd: Optional[str] = None,
+                    notice: bool = True) -> str:
         """Import a common-format envelope into a NEW session; return its id.
 
         ``cwd`` (or ``doc['cwd']``) seeds the session for that working
         directory when the agent records one, so the copy lands in the
         destination's matching project dir and resumes from there.
+        ``notice`` appends the import notice that tells a resumed model its
+        own tool history was left behind (see :meth:`import_notice`).
         """
         context = doc.get('context') or []
         if not isinstance(context, list):
@@ -527,8 +530,74 @@ class Agent:
         # If the envelope carries verbatim records *for this agent* (a same-
         # agent round trip), replay them; otherwise project the portable spine.
         messages = self._from_common_messages(doc, context)
+        if notice:
+            note = self.import_notice(doc)
+            if note is not None:
+                messages = messages + [note]
         return self.create_session(messages, cwd=cwd)
 
+    # Marker opening the import notice, so a copy of a copy is not annotated
+    # twice and the notice is recognisable to a reader and to tests.
+    IMPORT_NOTICE_TAG = 'ctools-import-notice'
+
+    def import_notice(self, doc: Dict[str, object]) -> Optional[Message]:
+        """A closing message telling a resumed model what its transcript hides.
+
+        The common format carries the conversation's *text*. Tool calls and
+        their results do not survive the projection, so a copied session reads
+        as an assistant that edits files by describing the edit ("let me
+        validate" / "valid, now reload and test") with nothing to show it ever
+        did. Resumed, the model matches that style and keeps narrating work it
+        never performs — the "it thought it made the edits but they all failed"
+        failure, which is really the tools never being called at all.
+
+        The notice is appended rather than prepended: on a long imported
+        transcript the first message is the first thing context truncation
+        drops, and the last message is the one a resuming model is reading from.
+        Returns None when there is nothing the transcript could mislead about,
+        or nothing to mislead (an empty copy stays empty).
+        """
+        context = doc.get('context')
+        if not isinstance(context, list) or not context:
+            return None
+        source = str(doc.get('source') or '')
+        src_agent = source.split('/', 1)[0]
+        tools = doc.get('tool_calls')
+        n_tools = len(tools) if isinstance(tools, list) else 0
+        # Evidence decides. Either the envelope recorded tool activity that the
+        # spine cannot carry, or it names a session in a *different known*
+        # agent, which is a cross-agent copy by definition. A bare '-' or a
+        # file path names no session, so nothing was demonstrably dropped.
+        cross = (src_agent in REGISTRY and src_agent != self.name)
+        if not (n_tools or cross):
+            return None
+        last = context[-1] if isinstance(context[-1], dict) else {}
+        if self.IMPORT_NOTICE_TAG in str(last.get('content') or ''):
+            return None  # already an imported copy; don't stack notices
+
+        named = source if src_agent in REGISTRY else 'another agent'
+        lost = (f"{n_tools} tool call(s) it recorded, and every result they "
+                f"produced, were left behind" if n_tools else
+                "any tool calls it made, and every result they produced, were "
+                "left behind")
+        if src_agent == self.name:
+            provenance = (f"This session was re-seeded from its own transcript in "
+                          f"{source} by `ctools ccopy`.")
+        else:
+            provenance = (f"This session was copied into {self.name} from "
+                          f"{named} by `ctools ccopy`.")
+        text = (
+            f"<{self.IMPORT_NOTICE_TAG}>\n"
+            f"{provenance} It carries the conversation's text only: {lost}.\n\n"
+            f"So nothing above as edited, written, created, deleted, run, printed, or "
+            f"tested has happened in this session. Treat those as unverified history, "
+            f"not as the current state of the files: an assistant turn that says it "
+            f"made a change is evidence that a change was *wanted*, nothing more. "
+            f"Re-read the files you need with your own tools before acting, and make "
+            f"every change with a real tool call.\n"
+            f"</{self.IMPORT_NOTICE_TAG}>")
+        return Message(role='user', content=text)
+
     def _from_common_messages(self, doc: Dict[str, object],
                               context: List[dict]) -> List[Message]:
         """Build the Message list a common import seeds from.
@@ -1811,6 +1880,58 @@ class OpencodeAgent(SqliteAgent):
         return [Message(role=role, content=text)
                 for _, role, text in self._rows(session_id) if text]
 
+    def tool_calls(self, session_id: str) -> List[dict]:
+        """opencode's ``tool`` parts, in conversation order.
+
+        The text projection drops these, so they are exactly what a copy loses;
+        exporting name and count is what lets an imported session state how much
+        of its own history is missing. ``msg`` indexes the conversation the way
+        :meth:`messages` numbers it, matching Claude Code's tool_calls.
+        """
+        conn = self.connect()
+        if conn is None:
+            raise SessionNotFound(self.name, session_id)
+        try:
+            cursor = conn.cursor()
+            cursor.execute('''
+                SELECT id FROM message WHERE session_id = ? ORDER BY time_created
+            ''', (session_id,))
+            msg_ids = [row[0] for row in cursor.fetchall()]
+            out: List[dict] = []
+            conv = -1
+            for msg_id in msg_ids:
+                cursor.execute('''
+                    SELECT data FROM part WHERE message_id = ? ORDER BY time_created
+                ''', (msg_id,))
+                has_text = False
+                tools: List[dict] = []
+                for (part_data,) in cursor.fetchall():
+                    try:
+                        part = json.loads(part_data)
+                    except (json.JSONDecodeError, TypeError):
+                        continue
+                    if not isinstance(part, dict):
+                        continue
+                    if part.get('type') == 'text' and part.get('text'):
+                        has_text = True
+                    elif part.get('type') == 'tool':
+                        tools.append(part)
+                if has_text:
+                    conv += 1
+                for part in tools:
+                    state = part.get('state')
+                    state = state if isinstance(state, dict) else {}
+                    out.append({
+                        'name': str(part.get('tool') or 'tool'),
+                        'summary': _summarize_args(state.get('input') or {}),
+                        'msg': max(conv, 0),
+                    })
+            return out
+        except sqlite3.Error:
+            return []
+        finally:
+            conn.close()
+
     def raw_records(self, session_id: str) -> List[dict]:
         """Each message's verbatim `message.data` plus its `part` rows, in order."""
         conn = self.connect()

{ctxttools-0.4.1 → ctxttools-0.4.2}/ctools/ccat.py

@@ -10,13 +10,13 @@ By default the output is a JSON list of {role, content} objects (one array per
 session) — the llcat/OpenAI spine — so it is importable and pipeable: feed it to
 jq, to another tool, or back into a session. Tool calls are interleaved as
 {role: "tool"} entries after the turn that made them. Use --text for a
-human-readable transcript, or --raw for the lossless envelope (the context plus
+model-readable markdown transcript (each message as '**role**:' then content), or --raw for the lossless envelope (the context plus
 the source agent's verbatim records, its tool calls, and session metadata).
 
 Usage:
     ccat opencode/ses_abc123                 # print one conversation as JSON
     ccat opencode/ses_a opencode/ses_b       # several, each a JSON array
-    ccat --text opencode/ses_abc            # human-readable transcript
+    ccat --text opencode/ses_abc            # markdown transcript (**role**: / content)
     ccat --raw opencode/ses_abc > session.json   # lossless envelope
     ccat ssh://chris@remote/opencode/ses_a  # a conversation on another host
     ccat opencode/ses_abc | jq .            # it is JSON, so pipe it anywhere
@@ -60,24 +60,30 @@ _DEFAULT_ROLE = ('msg', 'bold')
 
 
 def _render_transcript(messages: List[dict], color: bool) -> None:
-    """Print one conversation as a readable transcript on stdout.
-
-    Each message becomes `    <role>  <content>`; the role is a short dimmed
-    label in a fixed column so the content lines up.
+    """Print one conversation as a model-readable markdown transcript.
+
+    Each message becomes ``**<role>**:\n<content>`` — the role in bold
+    markdown (so it is parseable for a model, not just a human) followed by a
+    blank line. When ``color`` is set the role line is styled via a rich
+    console (``force_terminal`` so ``--color always`` works even when piped).
+    Content is printed as-is: markup and syntax highlighting are off so a
+    transcript that itself contains ``**`` or ``[red]`` is not mangled.
     """
-    width = 9  # len("assistant")
+    if not color:
+        for m in messages:
+            role = m.get('role', '')
+            label, _style = _ROLE.get(role, _DEFAULT_ROLE)
+            print(f'**{label}**:')
+            print(m.get('content', ''))
+            print()
+        return
+    console = Console(force_terminal=True, highlight=False, markup=False)
     for m in messages:
         role = m.get('role', '')
         label, style = _ROLE.get(role, _DEFAULT_ROLE)
-        if color:
-            line = Text()
-            line.append('    ')
-            line.append(f'{label:<{width}}', style=style)
-            line.append('  ')
-            line.append(m.get('content', ''))
-            print(line)
-        else:
-            print(f'    {label:<{width}}  {m.get("content", "")}')
+        console.print(Text(f'**{label}**:', style=style))
+        console.print(m.get('content', ''))
+        console.print()
 
 
 def _merge_tool_calls(messages: List[dict],
@@ -228,7 +234,7 @@ def build_parser() -> argparse.ArgumentParser:
                      "(one array per session) — the llcat/OpenAI spine — so it "
                      "can be imported or piped to another tool. Tool calls are "
                      "interleaved as {role: 'tool'} entries after the turn that "
-                     "made them. Pass --text for a readable transcript instead, "
+                     "made them. Pass --text for a markdown transcript instead, "
                      "or --raw for the lossless envelope (the context plus the "
                      "source agent's verbatim records, its tool calls, and "
                      "session metadata). Several sessions print in order, "
@@ -239,7 +245,8 @@ def build_parser() -> argparse.ArgumentParser:
                         help="One or more sessions to print (agent/session_id, "
                              "or ssh://[user@]host[:port]/agent/session_id)")
     parser.add_argument("-t", "--text", action="store_true", dest="text_out",
-                        help="Print a human-readable transcript instead of JSON")
+                        help=("Print a markdown transcript (each message as "
+                              "'**role**:' then the content) instead of JSON"))
     parser.add_argument("-r", "--raw", action="store_true", dest="raw_out",
                         help=("Print the lossless envelope: context plus the "
                               "agent's verbatim records and session metadata "

{ctxttools-0.4.1 → ctxttools-0.4.2}/ctools/ccopy.py

@@ -86,9 +86,13 @@ def export_common(agent: Agent, session_id: str) -> dict:
     return agent.to_common(session_id)
 
 
-def import_common(agent: Agent, doc: dict) -> str:
-    """Import a common-format envelope into a NEW session in `agent`; return id."""
-    return agent.from_common(doc)
+def import_common(agent: Agent, doc: dict, notice: bool = True) -> str:
+    """Import a common-format envelope into a NEW session in `agent`; return id.
+
+    ``notice`` keeps the import notice that tells a resumed model its tool
+    history was not copied (see Agent.import_notice).
+    """
+    return agent.from_common(doc, notice=notice)
 
 
 def common_copy(source: Agent, source_id: str, destination: Agent) -> Tuple[str, int]:
@@ -536,6 +540,10 @@ def build_parser() -> argparse.ArgumentParser:
                         help="Seed the new session for the current directory "
                              "instead of the source session's working "
                              "directory")
+    parser.add_argument("--no-import-notice", action="store_true",
+                        dest="no_import_notice",
+                        help=("Do not append the notice that tells a copied "
+                              "session its tool calls were not carried over"))
     parser.add_argument("-v", "--verbose", action="store_true",
                         help="Verbose output")
     version_option(parser, "ccopy")
@@ -708,7 +716,8 @@ def main(argv=None) -> int:
     if dst_remote is None:
         guard = guard_write(dst_agent, note="ccopy")
         try:
-            new_id = import_common(dst_agent, common_doc)
+            new_id = import_common(dst_agent, common_doc,
+                                   notice=not args.no_import_notice)
         except BaseException:
             guard.rollback()
             raise
@@ -733,11 +742,22 @@ def main(argv=None) -> int:
                       f"write: {backup_path}[/dim]")
         console.print(f"[dim]Restore it with: crecover restore {dst_ref} "
                       f"{backup_path}[/dim]")
+    # Ask the destination whether it actually annotated the copy, so the note
+    # below can never drift from what was written.
+    noted = (dst_remote is None and not args.no_import_notice
+             and dst_agent.import_notice(common_doc) is not None)
     resume = get_resume_command(dst_ref, new_id)
     if resume:
         suffix = f" on {dst_remote.target}" if dst_remote else ""
         console.print(f"[green]Resume it{suffix} with:[/green]")
         console.print(f"  {resume}")
+    if noted:
+        # Advisory, on stderr: stdout keeps the id/resume lines parseable.
+        err_console.print("[dim]Copied text only — the source's tool calls and "
+                          "their results are not in the new session, so it opens "
+                          "with a notice telling the model to re-read files "
+                          "rather than trust that narration (--no-import-notice "
+                          "to suppress).[/dim]")
     return 0
 
 

{ctxttools-0.4.1 → ctxttools-0.4.2}/ctools/cdir.py

@@ -40,7 +40,7 @@ from ctools.lib import format_datetime, format_size, get_formatter, install_clea
 from ctools.pathfilter import (canonical_dir as _canonical_dir,
                                looks_like_path as _looks_like_path,
                                session_matches_dir as _session_path_matches)
-from ctools.resume import _resolve as _resume_resolve
+from ctools.resume import _resolve as _resume_resolve, parse_ref_args
 
 __all__ = ['app']
 
@@ -908,11 +908,11 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("-o", "--output",
                         help=("Select output fields (comma-separated). "
                               "Use 'help' to list available fields."))
-    parser.add_argument("--resume-command", nargs=2,
-                        metavar=("AGENT", "SESSION"),
-                        help=("Print the resume command for AGENT/SESSION "
-                              "(with the cd into the session's recorded cwd) "
-                              "and exit, without exec-ing it"))
+    parser.add_argument("--resume-command", nargs="+", metavar="AGENT/SESSION",
+                        help=("Print the resume command for a session "
+                              "(AGENT/SESSION, as listed; or AGENT SESSION) "
+                              "with the cd into its recorded cwd, and exit "
+                              "without exec-ing it"))
     version_option(parser, "cdir")
     return parser
 
@@ -925,8 +925,10 @@ def main(argv=None) -> int:
         return v
 
     if args.resume_command:
-        agent_name, session_id = args.resume_command
-        cmd, cwd, err = _resume_resolve(agent_name, session_id)
+        # Same accepted shapes as `ctools resume`, so a listed row pastes here too.
+        agent_name, session_id, err = parse_ref_args(args.resume_command)
+        if not err:
+            cmd, cwd, err = _resume_resolve(agent_name, session_id)
         if err:
             console.print(f"[red]{err}[/red]")
             return 1