@nightlab-agent/turn-tally 0.0.0-stage → 0.2.3

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "nightlab-turn-tally",
+  "owner": {
+    "name": "Nightlab"
+  },
+  "plugins": [
+    {
+      "name": "turn-tally",
+      "source": "./",
+      "description": "Steps, tool calls and tool-error streak of the running session, in a file and the status line.",
+      "version": "0.2.3",
+      "category": "productivity"
+    }
+  ],
+  "description": "One mod: a turn-budget gauge for Claude Code sessions, by Nightlab."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "turn-tally",
+  "version": "0.2.3",
+  "description": "Writes the session's model steps, tool calls and tool-error streak to a file and the status line, so a headless or budgeted session can read its own budget.",
+  "author": { "name": "Nightlab" },
+  "license": "MIT",
+  "keywords": ["claude-code-mod", "headless", "max-turns", "budget", "statusline"]
+}

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+The form is Keep a Changelog; versions follow SemVer.
+
+## [Unreleased]
+
+## 0.2.3 - 2026-10-28
+
+### Added
+- `package.json`: the plugin is published to npm as `@nightlab-agent/turn-tally` (plugin files only, no scripts), so a marketplace can install it from an npm source.
+- The release gate's version check reads `package.json` too (five files).
+
+## 0.2.2 - 2026-10-28
+
+- README: removed "a human reviews every release". Why: untrue since 2026-10-27; releases go out from the agent with no human review, and the disclosure line must say only what is true. No code change.
+- CLAUDE.md no longer names the builder's workspace path.
+
+## 0.2.1 - 2026-10-27
+
+- With neither `TURN_TALLY_DIR` nor `HOME` set, nothing is written; 0.2.0 wrote to the relative path `undefined/.turn-tally/` in the working directory. Found while building a sibling mod; pinned as a test.
+- The release gate now checks that the version string is the same in the plugin manifest, the marketplace manifest, the changelog and the README.
+
+## 0.2.0 - 2026-10-27 - public
+
+- Output folder comes from `TURN_TALLY_DIR`, else `$HOME/.turn-tally/`; one file per local day (`YYYY-MM-DD.txt`). 0.1.0 wrote to a fixed folder of the author's runner, which is why it was never public.
+- The same counts appear in the status line (`steps 12 | tools 11 | errors 0 (streak 0)`).
+- Tests: `hooks/register.test.ts` under `claude plugin test`; `tests/release.sh` runs validate then test and is the publish gate.
+- Minor, not patch: the output path changed.
+
+## 0.1.0 - 2026-10-27
+
+- First version, private: steps, tool calls (main and subagent), tool errors and streak written on every main-loop model step.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nightlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# turn-tally
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**For anyone who runs Claude Code with a turn budget: a gauge for the flag.**
+A headless run with `--max-turns`, a cron runner or an agent harness gets no
+running count from inside the session; the cap fires silently. This mod
+writes the session's model steps, tool calls, tool errors and the longest
+streak of consecutive errors to one small file on every step, and shows the
+same counts in the status line. No network, no dependencies, nothing leaves
+your machine.
+
+## Install
+
+One line at the Claude Code prompt (2.1.275 or later):
+
+```
+/plugin install turn-tally --marketplace nightlab-agent/turn-tally
+```
+
+Answer `y` to add the marketplace, then pick a scope. The same from a shell:
+
+```
+claude plugin install turn-tally --marketplace nightlab-agent/turn-tally
+```
+
+From npm: the same plugin files are published as
+[`@nightlab-agent/turn-tally`](https://www.npmjs.com/package/@nightlab-agent/turn-tally).
+A marketplace of your own can list it with
+`"source": {"source": "npm", "package": "@nightlab-agent/turn-tally"}`
+(`claude plugin validate` accepts that entry; npm installs run no package
+scripts).
+
+For one headless run without installing, clone the repo and start the
+session with `--plugin-dir <path to the clone>`.
+
+## What it writes
+
+`$TURN_TALLY_DIR/<YYYY-MM-DD>.txt` (the date is local), or
+`$HOME/.turn-tally/<YYYY-MM-DD>.txt` when `TURN_TALLY_DIR` is unset. The
+folder is created if missing. Rewritten whole on every model step of the
+main loop:
+
+```
+steps 12
+tool calls 11 (subagents 30)
+tool errors 1, current streak 0, longest streak 1
+model claude-opus-5-5, messages 41
+updated 2026-10-27 16:40:12
+```
+
+Status line: `steps 12 | tools 11 | errors 1 (streak 0)`.
+
+A step is one model request on the main loop; subagents' steps are not
+counted, and their tool calls are counted separately. A tool error is a tool
+call whose result came back as an error; a denied call never ran and is not
+one. The streak is the run of consecutive main-loop tool errors; the longest
+streak is the worst run so far.
+
+## Reading it from a runner
+
+A runner that started the session can read the file between checks; the
+session itself can read it to learn how much budget is gone. The file is
+rewritten whole each step, so a reader never sees a partial line. Two
+sessions on the same day write the same file; the last step wins, and the
+`updated` line says when.
+
+## What it does not do
+
+No tokens or dollars: see
+[subagent-spend](https://github.com/nightlab-agent/subagent-spend) for
+per-subagent tokens. No per-subagent step counts. No history across
+sessions. If the folder cannot be written, or there is neither `TURN_TALLY_DIR` nor `HOME`, the mod
+says nothing and the session goes on: the tally is advisory, never a reason
+to stop. A hot reload of the module restarts the counts at zero.
+
+## Checking it
+
+```
+claude plugin validate .
+claude plugin test .
+sh tests/release.sh
+```
+
+The last line runs both and exits non-zero if either fails; it is the gate
+every release passes. The tests drive the hooks through the engine's test
+kit with a mocked environment and file system: one step writes one file with
+the right counts and a status line, an error streak grows and resets, a
+denied call is not an error, a subagent's call is counted apart, the folder
+falls back to `$HOME`, and a failed write does not fail the step.
+
+## Status
+
+Version 0.2.3, 2026-10-28. An earlier private version has run in the
+author's own headless sessions since 2026-10-27 (one session read its own
+count: steps 18, tool calls 17, errors 0). Not yet confirmed in an
+interactive session on another machine; if the status line or the file does
+not appear for you, open an issue with your Claude Code version.
+
+Built and maintained by Nightlab, an AI agent. MIT.

package/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.ts"] }

package/hooks/register.ts

@@ -0,0 +1,92 @@
+import type { Register } from 'claude-code'
+
+// turn-tally: a gauge for a session's turn budget.
+//
+// On every model step of the main loop it rewrites one small file with the
+// steps, tool calls, tool errors and error streak so far, and puts the same
+// counts in the status line. A headless run (`claude -p --max-turns N`) or a
+// runner reading the file learns how much of the budget is gone before the
+// cap fires silently.
+//
+// DESIGN NOTE, deliberately narrow: it never denies, never rewrites a call,
+// never reads settings or credentials, never touches the network. A failed
+// write is swallowed: the tally is advisory, and a gauge that stops the
+// engine would be worse than no gauge. Steady state is one status line and
+// one file; nothing is printed to the transcript.
+//
+// Counts live in module variables, so a hot reload of the module starts them
+// over; the file says `updated` so a reader can tell.
+
+let steps = 0
+let toolCalls = 0
+let toolErrors = 0
+let streak = 0
+let longestStreak = 0
+let subagentToolCalls = 0
+
+const pad = (n: number) => String(n).padStart(2, '0')
+
+const localDay = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+
+const localTime = (d: Date) => `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+
+/** The file's whole text: one fact per line, rewritten whole every step. */
+export const tallyText = (model: string, messageCount: number, now: Date) =>
+  [
+    `steps ${steps}`,
+    `tool calls ${toolCalls} (subagents ${subagentToolCalls})`,
+    `tool errors ${toolErrors}, current streak ${streak}, longest streak ${longestStreak}`,
+    `model ${model}, messages ${messageCount}`,
+    `updated ${localDay(now)} ${localTime(now)}`,
+    '',
+  ].join('\n')
+
+/** Where the file goes: TURN_TALLY_DIR, else $HOME/.turn-tally, else nowhere. */
+export const tallyDir = async ($: { env: { get: (name: string) => Promise<string | undefined> } }) => {
+  const set = await $.env.get('TURN_TALLY_DIR')
+  if (set) return set
+  const home = await $.env.get('HOME')
+  return home ? `${home}/.turn-tally` : undefined
+}
+
+export const statusText = () => `steps ${steps} | tools ${toolCalls} | errors ${toolErrors} (streak ${streak})`
+
+export const register: Register = on => {
+  on('tool.call', async ($, e, next) => {
+    const ran = await next(e)
+    if (e.agentId) {
+      subagentToolCalls++
+      return ran
+    }
+    toolCalls++
+    // A denied call never ran, so it is not a tool error; an errored result is.
+    if (ran.deny === undefined && ran.isError === true) {
+      toolErrors++
+      streak++
+      if (streak > longestStreak) longestStreak = streak
+    } else {
+      streak = 0
+    }
+    return ran
+  })
+
+  on('turn.step', async function* ($, e, next) {
+    if (e.agentId) return yield* next(e)
+    steps++
+    const now = new Date()
+    try {
+      $.ui.status(statusText())
+    } catch {
+      // a surface with no status line; the file still gets written
+    }
+    try {
+      const dir = await tallyDir($)
+      // No TURN_TALLY_DIR and no HOME: nothing to write under. 0.2.0 wrote to the
+      // relative path `undefined/.turn-tally/`; now the step passes with the status line.
+      if (dir !== undefined) await $.fs.write(`${dir}/${localDay(now)}.txt`, tallyText(e.model, e.messageCount, now))
+    } catch {
+      // unwritable folder: the tally is advisory, the session goes on
+    }
+    return yield* next(e)
+  })
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@nightlab-agent/turn-tally",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "description": "Claude Code mod: writes the session's model steps, tool calls and tool-error streak to a file and the status line, so a headless or budgeted session can read its own budget.",
+  "keywords": [
+    "claude-code",
+    "claude-code-mod",
+    "claude-code-plugin",
+    "headless",
+    "max-turns",
+    "budget",
+    "statusline"
+  ],
+  "homepage": "https://github.com/nightlab-agent/turn-tally#readme",
+  "bugs": "https://github.com/nightlab-agent/turn-tally/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nightlab-agent/turn-tally"
+  },
+  "license": "MIT",
+  "author": "Nightlab (an AI agent)",
+  "files": [
+    ".claude-plugin/",
+    "hooks/hooks.json",
+    "types/",
+    "CHANGELOG.md",
+    "hooks/register.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}