Repository navigation
Add a ZCode host - #218
Open
Stanislav Usoltsev (stanislavus) wants to merge 1 commit into
Open
Add a ZCode host#218Stanislav Usoltsev (stanislavus) wants to merge 1 commit into
Stanislav Usoltsev (stanislavus) wants to merge 1 commit into
Conversation
|
Stanislav Usoltsev (@stanislavus) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
Stanislav Usoltsev (stanislavus)
force-pushed
the
zcode-kimi-hosts
branch
from
November 12, 2026 21:16
a133701 to
67bf5dd
Compare
Stanislav Usoltsev (stanislavus)
force-pushed
the
zcode-kimi-hosts
branch
from
November 12, 2026 21:17
67bf5dd to
520ad0b
Compare
Aaron Li (aaron-jx-li)
requested changes
Nov 16, 2026
Aaron Li (aaron-jx-li)
left a comment
Collaborator
There was a problem hiding this comment.
Thanks for the contribution. This PR needs a few changes before it can be merged:
- Kimi Code doesn't belong in this PR.
docs/KIMI.md,tests/test_kimi.py, the Kimi text inREADME.md:193-194andREADME.md:513, anddocs/PLUGIN.md:751-753document a host this PR doesn't add, and #234 already rewritesdocs/KIMI.mdand deletes most oftests/test_kimi.py. Please drop them here so this PR is ZCode only, and let #234 carry the Kimi docs. The Kimi-path negative case intests/test_zcode.py's detection list can stay. Please also remove theTC-980/TASK-980references (tests/test_zcode.py:10-11,298) and the instructions block at the top of the PR description. - A subagent's usage is counted twice.
docs/ZCODE.md:75says a subagent's own hook calls carry its own session id, so the plugin records that session and folds it later.zcode_export(tokeneconomizer/trace/zcode.py:144-149) already adds the subagent'squery_source = 'subagent'rows to the parent, so folding the subagent's own session counts the same rows again, and its task message counts as a prompt. Withmake_dbfromtests/test_zcode.pyand onePostToolUsehook forsess_sub,fold_sessiongivessess_1input 1500 (including the subagent's 200) andsess_subinput 200 / cache 500 / output 50 / prompts 1. Please keep a subagent's hook calls from creating a session of their own (for example aZCode.is_subagentthat reads ZCode's agent field), or haveZCode.completefold a session that has aparent_idand onlysubagentrows as nothing. Add a test where the subagent's hook fires. - Nothing here has run under ZCode.
README.md:73andCLAUDE.md:4list ZCode with the other agents, butdocs/PLUGIN.md:723says the adapter was "read from its code, not run live". That leaves unchecked the hook file, the$HOMEexpansion in its command, the trust step and whetheradditionalContextreaches the model. Every other host indocs/PLUGIN.md§3 has at least one live check. Since you have 0.17.1 installed, please run the "Verify it" steps (docs/ZCODE.md:49-57) and record the results indocs/PLUGIN.mdwith the version and date: the session listed after its first hook, the fold with its prompts and tokens, and a fact the model repeated. Please also add a ZCode row to "Supported versions" (README.md:287) and a ZCode entry under §5 "Known limitations", as the other experimental hosts have. - The hook command points at a path nothing creates.
plugin/hooks/zcode-hooks.json:9and the four entries after it run$HOME/.tokeneconomizer/src/plugin/scripts/te-hook. No step clones the repository there, and the README section (README.md:188-194) has no clone step at all, so following it gives a hook that fails on every event.~/.tokeneconomizeris also the plugin's state directory. Please give the README section agit cloneand say which path goes in the command, as the opencode and Hermes sections do with$PWD/TokenEconomizer/..., and use the same path indocs/ZCODE.md. - Please rebase onto main: #185 and #183 changed
tokeneconomizer/plugin/sidecall.pysince this was opened, and it now conflicts there.
The CLA check also needs a @microsoft-github-policy-service agree reply on this PR.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Upstream pull request text: ZCode host for TokenEconomizer
The person pushes the fork branch
zcode-kimi-hostsand opens the pull request againstmicrosoft/TokenEconomizer. Everything under the rule below is the pull request text. The titleis the first line.
Add ZCode as a host (experimental), and document why Kimi Code is not one
What
tokeneconomizer/trace/zcode.py: a reader for ZCode's SQLite store(
<ZCODE_STORAGE_DIR or ~/.zcode>/cli/db/db.sqlite).zcode_exportopens it read-only, copiesone session's tool calls, exit codes and token usage into a JSON file of the plugin's, and the
other functions read that file:
zcode_session_to_claude,zcode_prompt_count,zcode_session_usage. The copy has no words: a prompt is counted and not kept, and what themodel said or reasoned is not read (the same approach as
trace/hermes.py).plugin/hosts.py: aZCodehost, anddetectsupport. ZCode's hook payload is Claude-shaped(it has
session_id,tool_name,tool_inputand the rest, beside its own camelCase fields),so what tells it apart is its transcript:
transcript_pathandtranscriptPathare onetemporary
zcode-hook-<random>/transcript.jsonl. ZCode also sends the camelCasehookEventNamethat the Grok host takes as its mark, so without this a ZCode payload read asGrok's.
default_hostknowsZCODE_SESSION_ID, after every other agent's variable.plugin/sidecall.py:zcode_call, a side call throughzcode -pin a throwaway directory, inplanmode (its-pdefault isyolo), with the acting tools removed by--disallowed-tools. It is off untilzcode_sidecallis on (orTE_ZCODE_SIDECALL=1), asDroid's is.
plugin/hooks/zcode-hooks.json: the five hook entries, for a repository'szcode.json.docs/ZCODE.md, a section indocs/PLUGIN.md, README rows,docs/KIMI.md.tests/test_zcode.py,tests/test_kimi.py;tests/conftest.pystubszcode_calllike theother side calls.
Why
ZCode (Z.ai's coding agent) runs Claude-shaped hooks and keeps every session in one SQLite file.
The hook's own transcript is a temporary file that holds one line and is deleted when the hook
returns, so no existing reader can see a ZCode session. TokenEconomizer's mechanisms need only
(name, args, result, ok)calls and a prompt count, which the reader gives them.Two facts of the store are not obvious and are tested:
model_usage.input_tokenscounts the cachedreads, where the ledger's input does not, so the reader subtracts them; and a subagent's calls are
rows of its own session with
query_source = 'subagent', which the parent session paid for, while aforked session has a parent too and is not added.
Kimi Code
Kimi Code 2.x has no reader here on purpose. The only
wire.jsonlrecords seen aremetadata,config.updateandtools.set_active_tools, and whether an exit-0 hook's stdout reaches the modelis not tried.
docs/KIMI.mdsays what to collect, andtests/test_kimi.pyhas two skipped teststhat name it, and two tests that pin that no adapter claims a Kimi payload.
Tests
python3 -I -m pytest tests experiments/teststests/test_zcode.py(57 pass and 2 skip, withtests/test_kimi.py): the reader on a synthetic store whoseJSON keys were read off a real one (no conversation copied); words never reach an export; failure
is decided by exit code; typed prompts only (reminders, goal continuations and background-task
notices are not prompts); usage with the cache taken out and the subagent added; the store is
opened read-only and a missing or foreign store is no session and creates nothing; a session id
that is no id is refused.
ZCODE_SESSION_IDinits environment, a camelCase-only payload, a Grok payload, a transcript whose two fields differ,
one with another file name or folder name, no transcript, and a Kimi session path are all not
ZCode. An unknown
--hostvalue is not ZCode.hook.mainwith a payload built as ZCode's own code builds it:session recorded, folded once from the store, a second fold finds nothing.
TE_SIDECALL=1, no stdin),the off-by-default switch from the variable and from the setting, a reply-less call noted and
paused.
How it was verified
The full offline suite passes with the change: 1372 passed, 21 skipped in
testsandexperiments/teststogether, on Python 3.11 with pytest 9.2. The base is the pinned commit 0566b60. The hook code was read from ZCode 0.17.1's bundle, and the storeschema and the JSON keys of its rows from a real 0.17.1 store (keys and aggregate counts only).
Limits
zcode -pwas not called with a realmodel: what it prints, and whether
--disallowed-toolskeeps out every tool, are unchecked. Thatis why the side call is off by default.
docs/ZCODE.mdhas the steps to check both.keeps_start_contextkeeps its default: whether ZCode replays a session start's context on resumewas not traced.
cache_creation_input_tokenswas 0 in every row seen.