tokenjuice-integrations 0.10.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,29 @@
1
+ # tokenjuice Hermes plugin
2
+
3
+ This directory is a self-contained Hermes plugin. It registers the public
4
+ `transform_terminal_output` hook and needs Hermes 0.22.5 or newer. Optional
5
+ LangChain and FastMCP modules are not loaded by Hermes.
6
+
7
+ Install the [tokenjuice CLI](https://github.com/vincentkoc/tokenjuice) separately
8
+ with `npm install --global tokenjuice` (Node.js 22 or newer), then install this
9
+ plugin through Hermes using the repository's `src/python/tokenjuice_integrations`
10
+ subdirectory. Use an exact commit when installing from Git. Enable it with
11
+ `hermes plugins enable tokenjuice` and check `hermes plugins doctor tokenjuice`.
12
+ See the [setup guide](https://github.com/vincentkoc/tokenjuice/blob/main/docs/framework-integrations.md#hermes)
13
+ for the bundled release alternative.
14
+
15
+ The plugin passes captured terminal output to the local `tokenjuice
16
+ compact-shell-result` subprocess. It never executes the command supplied in the
17
+ hook payload. Only successful foreground output is eligible; failures, background
18
+ polls, exact file reads, and explicit raw requests retain their original output.
19
+ Missing executables, invalid responses, inputs over 2 MB, and five-second timeouts
20
+ also preserve the original output.
21
+
22
+ The CLI reads tokenjuice's local configuration and rules. Bridge calls disable
23
+ statistics and require no credentials or network service. Keep `tokenjuice` on
24
+ PATH, or set `TOKENJUICE_BIN` to its executable path. No Hermes permissions are
25
+ changed. Disable with `hermes plugins disable tokenjuice`; remove with
26
+ `hermes plugins remove tokenjuice`.
27
+
28
+ Maintained by [vincentkoc](https://github.com/vincentkoc). MIT-licensed; see the
29
+ [repository license](https://github.com/vincentkoc/tokenjuice/blob/main/LICENSE).
@@ -0,0 +1,3 @@
1
+ """Optional native adapters and the dependency-free Hermes plugin entrypoint."""
2
+
3
+ from .hermes import register
@@ -0,0 +1,39 @@
1
+ """Pass captured output to tokenjuice; never execute the command in the payload."""
2
+ import asyncio
3
+ import json
4
+ import os
5
+ import subprocess
6
+
7
+ MAX_INPUT_BYTES = 2_000_000
8
+
9
+
10
+ def compact_result(source, result, *, launcher=None, timeout=5):
11
+ if not isinstance(result, dict) or type(result.get("exitCode")) is not int or result["exitCode"] != 0:
12
+ return None
13
+ if not isinstance(result.get("output"), str) or not isinstance(result.get("command"), str):
14
+ return None
15
+ try:
16
+ payload = json.dumps({"source": source, "result": result}).encode("utf-8")
17
+ if len(payload) > MAX_INPUT_BYTES:
18
+ return None
19
+ command = list(launcher) if launcher is not None else [os.environ.get("TOKENJUICE_BIN", "tokenjuice")]
20
+ completed = subprocess.run(
21
+ [*command, "compact-shell-result"], input=payload,
22
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=timeout,
23
+ check=False, env={**os.environ, "TOKENJUICE_STATS": "off"},
24
+ )
25
+ if completed.returncode != 0 or len(completed.stdout) > MAX_INPUT_BYTES:
26
+ return None
27
+ response = json.loads(completed.stdout)
28
+ if not isinstance(response, dict):
29
+ return None
30
+ text = response.get("text")
31
+ if response.get("action") == "rewrite" and isinstance(text, str) and 0 < len(text) < len(result["output"]):
32
+ return text
33
+ except (OSError, ValueError, TypeError, subprocess.TimeoutExpired):
34
+ pass
35
+ return None
36
+
37
+
38
+ async def acompact_result(source, result, **options):
39
+ return await asyncio.to_thread(compact_result, source, result, **options)
@@ -0,0 +1,24 @@
1
+ """FastMCP response middleware, including servers backed by a proxy provider."""
2
+ from fastmcp.server.middleware import Middleware
3
+
4
+ from .bridge import acompact_result
5
+
6
+
7
+ class TokenjuiceMiddleware(Middleware):
8
+ def __init__(self, decode, replace, *, launcher=None):
9
+ self.decode = decode
10
+ self.replace = replace
11
+ self.launcher = launcher
12
+
13
+ async def on_call_tool(self, context, call_next):
14
+ result = await call_next(context)
15
+ if getattr(result, "isError", False) or getattr(result, "is_error", False):
16
+ return result
17
+ try:
18
+ execution = self.decode(context, result)
19
+ if execution is None:
20
+ return result
21
+ text = await acompact_result("fastmcp", execution, launcher=self.launcher)
22
+ return self.replace(result, text) if text is not None else result
23
+ except Exception:
24
+ return result
@@ -0,0 +1,13 @@
1
+ """Hermes native terminal transform. The host retains its own status envelope."""
2
+ from .bridge import compact_result
3
+
4
+
5
+ def transform_terminal_output(command, output, returncode=None, env_type="", **kwargs):
6
+ # Background poll output has no environment provenance; do not rewrite it.
7
+ if not isinstance(env_type, str) or not env_type:
8
+ return None
9
+ return compact_result("hermes", {"command": command, "output": output, "exitCode": returncode})
10
+
11
+
12
+ def register(ctx):
13
+ ctx.register_hook("transform_terminal_output", transform_terminal_output)
@@ -0,0 +1,38 @@
1
+ """LangChain sync/async middleware for explicitly mapped shell tools."""
2
+ from langchain.agents.middleware import AgentMiddleware
3
+ from langchain_core.messages import ToolMessage
4
+
5
+ from .bridge import acompact_result, compact_result
6
+
7
+
8
+ class TokenjuiceMiddleware(AgentMiddleware):
9
+ def __init__(self, decode, *, launcher=None):
10
+ self.decode = decode
11
+ self.launcher = launcher
12
+
13
+ def _execution(self, request, result):
14
+ if not isinstance(result, ToolMessage) or result.status == "error" or not isinstance(result.content, str):
15
+ return None
16
+ try:
17
+ execution = self.decode(request, result)
18
+ if isinstance(execution, dict) and execution.get("output") == result.content:
19
+ return execution
20
+ except Exception:
21
+ pass
22
+ return None
23
+
24
+ def wrap_tool_call(self, request, handler):
25
+ result = handler(request)
26
+ execution = self._execution(request, result)
27
+ if execution is None:
28
+ return result
29
+ text = compact_result("langchain", execution, launcher=self.launcher)
30
+ return result.model_copy(update={"content": text}) if text is not None else result
31
+
32
+ async def awrap_tool_call(self, request, handler):
33
+ result = await handler(request)
34
+ execution = self._execution(request, result)
35
+ if execution is None:
36
+ return result
37
+ text = await acompact_result("langchain", execution, launcher=self.launcher)
38
+ return result.model_copy(update={"content": text}) if text is not None else result
@@ -0,0 +1,7 @@
1
+ name: tokenjuice
2
+ version: 0.10.0
3
+ description: Compact successful terminal output before model consumption
4
+ author: vincentkoc
5
+ requires_hermes: ">=0.22.5"
6
+ provides_hooks:
7
+ - transform_terminal_output
@@ -0,0 +1,57 @@
1
+ Metadata-Version: 2.4
2
+ Name: tokenjuice-integrations
3
+ Version: 0.10.0
4
+ Summary: Local tool-result compaction for LangChain and FastMCP
5
+ Author: Vincent Koc
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/vincentkoc/tokenjuice
8
+ Project-URL: Documentation, https://github.com/vincentkoc/tokenjuice/blob/main/docs/framework-integrations.md
9
+ Project-URL: Source, https://github.com/vincentkoc/tokenjuice
10
+ Project-URL: Issues, https://github.com/vincentkoc/tokenjuice/issues
11
+ Requires-Python: >=3.11
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Provides-Extra: langchain
15
+ Requires-Dist: langchain<2,>=1.4; extra == "langchain"
16
+ Provides-Extra: fastmcp
17
+ Requires-Dist: fastmcp<5,>=4.1; extra == "fastmcp"
18
+ Dynamic: license-file
19
+
20
+ # tokenjuice-integrations
21
+
22
+ Python adapters for [tokenjuice](https://github.com/vincentkoc/tokenjuice), a local
23
+ tool-output compactor. LangChain tool middleware and FastMCP server/proxy
24
+ middleware replace eligible successful shell output before model consumption.
25
+ Failures, unknown exit status, exact file reads, and explicit raw requests pass
26
+ through. Applications map their own trusted execution records; tool success
27
+ alone does not establish a shell exit code.
28
+
29
+ ## Install
30
+
31
+ Python 3.11 or newer and tokenjuice CLI 0.10.0 or newer are required. Install the CLI separately
32
+ with Node.js 22 or newer, and install only the Python extras your application uses:
33
+
34
+ ```sh
35
+ npm install --global tokenjuice
36
+ python -m pip install "tokenjuice-integrations[langchain]"
37
+ # Or: python -m pip install "tokenjuice-integrations[fastmcp]"
38
+ ```
39
+
40
+ Keep the CLI on your application's PATH or set `TOKENJUICE_BIN` to its executable
41
+ path. For an npm/release bundle, install its `dist/python` directory with the same
42
+ extras instead of a registry name.
43
+
44
+ ## Configure
45
+
46
+ - [LangChain middleware and execution-record mapping](https://github.com/vincentkoc/tokenjuice/blob/main/docs/framework-integrations.md#langchain)
47
+ - [FastMCP middleware and coherent result replacement](https://github.com/vincentkoc/tokenjuice/blob/main/docs/framework-integrations.md#fastmcp)
48
+ - [Hermes native plugin installation](https://github.com/vincentkoc/tokenjuice/blob/main/docs/framework-integrations.md#hermes)
49
+
50
+ The adapters send captured output to the local `tokenjuice compact-shell-result`
51
+ subprocess. They never execute the command string in that payload. Bridge calls
52
+ disable statistics and preserve the original result on missing executables,
53
+ invalid responses, inputs over 2 MB, or five-second timeouts. No model service or
54
+ API key is required. Remove middleware from the application to disable it.
55
+
56
+ MIT-licensed. Source, issue tracking, and native contract tests are in the
57
+ [tokenjuice repository](https://github.com/vincentkoc/tokenjuice).
@@ -0,0 +1,12 @@
1
+ tokenjuice_integrations/README.md,sha256=b0QFvL8XSgccAiOiD6x5APx9mc4VbQFP2dwistyKqDo,1724
2
+ tokenjuice_integrations/__init__.py,sha256=xvl6AiX5_zGFdF-r3L27paS8YVWf4rEXkJGrbO2Zffg,111
3
+ tokenjuice_integrations/bridge.py,sha256=U-iTq3m6fmus_i5NSv3_7bqXyzo1UhoahCl3NxlmVac,1640
4
+ tokenjuice_integrations/fastmcp.py,sha256=mL6DAe-ZK9CfjUyKS_Y1U63OEIdOxgXSn-jplmIr9Vo,915
5
+ tokenjuice_integrations/hermes.py,sha256=6IobCWqDqaAMZ6cdzpy1w0wlOICs7Uh6151qbgFhYm4,559
6
+ tokenjuice_integrations/langchain.py,sha256=9xB7wi_1nZZrQZ7qVHwe_zianYyOiqmE13lWhmki4TM,1566
7
+ tokenjuice_integrations/plugin.yaml,sha256=ZJO0ybbMxfmCJy1hoo22OycGaw7_xkBbHWJjK5a8rj4,199
8
+ tokenjuice_integrations-0.10.0.dist-info/licenses/LICENSE,sha256=Ahq_HKyykcKwvpKrB41sM2-Fnxvsmjo6-8A5Nilx4x4,1068
9
+ tokenjuice_integrations-0.10.0.dist-info/METADATA,sha256=43ulwjDPoqQmV1n912VAa23-l8ZDhHLtHE_ffPsAZU0,2743
10
+ tokenjuice_integrations-0.10.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
11
+ tokenjuice_integrations-0.10.0.dist-info/top_level.txt,sha256=M8JHqekqsqEKm_pOULJnGhLZfdvWhxYokrFOcISE7Po,24
12
+ tokenjuice_integrations-0.10.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vincent Koc
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ tokenjuice_integrations