ctxttools 0.4.0__tar.gz → 0.4.2__tar.gz

{ctxttools-0.4.0 → ctxttools-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxttools
-Version: 0.4.0
+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
@@ -167,9 +168,10 @@ transform:
   rm        cut sections out of a session      (crm)
   recover   restore from a backup              (crecover)
 
-long-running:
+long-running / hand-off:
   web       run the web dashboard              (ctools-web)
   mcp       run the MCP server                 (ctools-mcp)
+  resume    hand a session back to its tool    (resume)
 
 Run 'ctools <command> --help' for a command's options.
 ```
@@ -177,7 +179,7 @@ Run 'ctools <command> --help' for a command's options.
 Each verb has its own page in [`docs/`](docs/): [dir](docs/cdir.md),
 [grep](docs/cgrep.md), [cat](docs/ccat.md), [du](docs/cdu.md),
 [copy](docs/ccopy.md), [extract](docs/cextract.md),
-[connect](docs/cconnect.md), [rm](docs/crm.md), and
+[connect](docs/cconnect.md), [rm](docs/crm.md), [resume](docs/resume.md), and
 [recover](docs/crecover.md). Sessions are addressed as `agent/session_id`
 throughout.
 
@@ -200,6 +202,7 @@ ctools grep "bug report"                    # every installed agent
 ctools grep -i "deploy" claude-code         # one agent
 ctools grep -C 2 "flaky test" opencode      # with context
 ctools grep -l "parser" pi                  # just the session ids
+ctools grep "parser" .                      # only sessions recorded in this directory
 ctools grep --user "refactor"               # only what you typed
 ctools grep --hosts "mcp config"            # also the hosts in ctools.toml
 ```
@@ -208,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
 ```
 
@@ -229,6 +232,33 @@ The remote side doesn't need ctools installed; plain `ssh` and `tar` will do.
 See [docs/ccopy.md](docs/ccopy.md) for how that works and where the new
 session lands.
 
+### Continue a session in its own tool
+
+`resume` hands a session back to the tool that owns it: it computes the
+agent's resume command, `cd`s into the directory the session was recorded
+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 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
+directory it was recorded in. See [docs/resume.md](docs/resume.md).
+
 ### Token usage
 
 ```bash
@@ -325,14 +355,18 @@ ctools mcp          # run the server on stdio (same as ctools-mcp)
 ### Install and register with Pi
 
 ```bash
-ctools-mcp install
+ctools-mcp install            # global: ~/.pi/agent/mcp.json
+ctools-mcp install --project  # project: .pi/mcp.json in the current directory
 ```
 
 If no working `ctxttools[mcp]` install is found, this installs one with
-`uv tool`. It then registers the server in `~/.pi/agent/mcp.json`. Verify with:
+`uv tool`. It then registers the server in `~/.pi/agent/mcp.json` (or
+`.pi/mcp.json` with `--project`), always with a `python -m ctools.ctools_mcp`
+entry that does not depend on the MCP host's `PATH`. Verify with:
 
 ```bash
 pi mcp list        # "ctools-mcp … connected"
+ctools-mcp check   # also: verifies the command exists and starts, prints the fix
 ```
 
 `ctools-mcp uninstall` removes the entry again (`--all` also removes it from
@@ -352,13 +386,17 @@ Add that to your host's MCP config. The server is started with
 
 ### Tools exposed
 
+Session tools take a single `session` reference: `agent/session_id` (the
+`@` prefix also works), or a bare `session_id` plus the `agent` argument.
+
 | Tool | What it does |
 |---|---|
 | `list_agents` | Agents available and whether they're installed. |
 | `list_sessions` | Recent sessions for one agent. |
 | `search_sessions` | Find sessions by pattern or phrase. |
+| `summarize_session` | Quick orientation: title, date, size, first user and last assistant message. |
 | `export_session` | Get the messages of a session. |
-| `extract_concepts` | Extract concepts from a session. |
+| `extract_concepts` | Extract 'Use the following …' concept blocks from a session. |
 | `get_session_concepts` | Get a session's concepts, optionally of one type. |
 | `copy_concepts` | Copy extracted concepts into a destination session. |
 

{ctxttools-0.4.0 → ctxttools-0.4.2}/README.md

@@ -149,9 +149,10 @@ transform:
   rm        cut sections out of a session      (crm)
   recover   restore from a backup              (crecover)
 
-long-running:
+long-running / hand-off:
   web       run the web dashboard              (ctools-web)
   mcp       run the MCP server                 (ctools-mcp)
+  resume    hand a session back to its tool    (resume)
 
 Run 'ctools <command> --help' for a command's options.
 ```
@@ -159,7 +160,7 @@ Run 'ctools <command> --help' for a command's options.
 Each verb has its own page in [`docs/`](docs/): [dir](docs/cdir.md),
 [grep](docs/cgrep.md), [cat](docs/ccat.md), [du](docs/cdu.md),
 [copy](docs/ccopy.md), [extract](docs/cextract.md),
-[connect](docs/cconnect.md), [rm](docs/crm.md), and
+[connect](docs/cconnect.md), [rm](docs/crm.md), [resume](docs/resume.md), and
 [recover](docs/crecover.md). Sessions are addressed as `agent/session_id`
 throughout.
 
@@ -182,6 +183,7 @@ ctools grep "bug report"                    # every installed agent
 ctools grep -i "deploy" claude-code         # one agent
 ctools grep -C 2 "flaky test" opencode      # with context
 ctools grep -l "parser" pi                  # just the session ids
+ctools grep "parser" .                      # only sessions recorded in this directory
 ctools grep --user "refactor"               # only what you typed
 ctools grep --hosts "mcp config"            # also the hosts in ctools.toml
 ```
@@ -190,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
 ```
 
@@ -211,6 +213,33 @@ The remote side doesn't need ctools installed; plain `ssh` and `tar` will do.
 See [docs/ccopy.md](docs/ccopy.md) for how that works and where the new
 session lands.
 
+### Continue a session in its own tool
+
+`resume` hands a session back to the tool that owns it: it computes the
+agent's resume command, `cd`s into the directory the session was recorded
+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 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
+directory it was recorded in. See [docs/resume.md](docs/resume.md).
+
 ### Token usage
 
 ```bash
@@ -307,14 +336,18 @@ ctools mcp          # run the server on stdio (same as ctools-mcp)
 ### Install and register with Pi
 
 ```bash
-ctools-mcp install
+ctools-mcp install            # global: ~/.pi/agent/mcp.json
+ctools-mcp install --project  # project: .pi/mcp.json in the current directory
 ```
 
 If no working `ctxttools[mcp]` install is found, this installs one with
-`uv tool`. It then registers the server in `~/.pi/agent/mcp.json`. Verify with:
+`uv tool`. It then registers the server in `~/.pi/agent/mcp.json` (or
+`.pi/mcp.json` with `--project`), always with a `python -m ctools.ctools_mcp`
+entry that does not depend on the MCP host's `PATH`. Verify with:
 
 ```bash
 pi mcp list        # "ctools-mcp … connected"
+ctools-mcp check   # also: verifies the command exists and starts, prints the fix
 ```
 
 `ctools-mcp uninstall` removes the entry again (`--all` also removes it from
@@ -334,13 +367,17 @@ Add that to your host's MCP config. The server is started with
 
 ### Tools exposed
 
+Session tools take a single `session` reference: `agent/session_id` (the
+`@` prefix also works), or a bare `session_id` plus the `agent` argument.
+
 | Tool | What it does |
 |---|---|
 | `list_agents` | Agents available and whether they're installed. |
 | `list_sessions` | Recent sessions for one agent. |
 | `search_sessions` | Find sessions by pattern or phrase. |
+| `summarize_session` | Quick orientation: title, date, size, first user and last assistant message. |
 | `export_session` | Get the messages of a session. |
-| `extract_concepts` | Extract concepts from a session. |
+| `extract_concepts` | Extract 'Use the following …' concept blocks from a session. |
 | `get_session_concepts` | Get a session's concepts, optionally of one type. |
 | `copy_concepts` | Copy extracted concepts into a destination session. |
 

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

@@ -450,6 +450,7 @@ class Agent:
     #   { "context": [{role, content}, ...],   # portable spine (llcat/OpenAI)
     #     "source": "agent/session_id",
     #     "model": ..., "created": ..., "modified": ...,   # session facts
+    #     "tool_calls": [{name, summary, msg}, ...],      # optional
     #     "raw": [agent's verbatim records] }              # lossless, optional
     # Every agent that can be seeded gets to_common (export) and from_common
     # (import); agents that can't do either refuse with UnsupportedOperation.
@@ -476,6 +477,9 @@ class Agent:
         raw = self.raw_records(session_id)
         if raw:
             doc['raw'] = raw
+        tool_calls = self.tool_calls(session_id)
+        if tool_calls:
+            doc['tool_calls'] = tool_calls
         return doc
 
     def _session_cwd(self, session_id: str) -> Optional[str]:
@@ -506,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):
@@ -523,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.
@@ -1129,6 +1202,12 @@ class ClaudeCodeAgent(JsonlAgent):
             # No truncation here: the display layer owns column width.
             name = title or (first_user or '').strip().replace('\n', ' ') \
                 or session_id[:8]
+            parent_id = None
+            if 'subagents' in path.parts:
+                # Subagent transcripts live under <parent-session-id>/subagents/;
+                # the first entry's sessionId agrees with the directory name.
+                parent_id = (entries[0].get('sessionId') if entries else None) \
+                    or path.parent.parent.name
             sessions.append(Session(
                 id=session_id,
                 name=name,
@@ -1138,6 +1217,7 @@ class ClaudeCodeAgent(JsonlAgent):
                 path=cwd or str(path),
                 model=model,
                 message_count=message_count,
+                parent_id=parent_id,
             ))
         return sessions
 
@@ -1800,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()