dingo-pack 0.4.2__tar.gz
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.
- dingo_pack-0.4.2/.github/workflows/publish.yml +41 -0
- dingo_pack-0.4.2/.github/workflows/test.yml +40 -0
- dingo_pack-0.4.2/.gitignore +9 -0
- dingo_pack-0.4.2/ADAPTERS.md +96 -0
- dingo_pack-0.4.2/CHANGELOG.md +34 -0
- dingo_pack-0.4.2/LICENSE +21 -0
- dingo_pack-0.4.2/PKG-INFO +284 -0
- dingo_pack-0.4.2/README.md +267 -0
- dingo_pack-0.4.2/README.zh-CN.md +219 -0
- dingo_pack-0.4.2/REFERENCE.md +223 -0
- dingo_pack-0.4.2/RELEASING.md +54 -0
- dingo_pack-0.4.2/bin/dingo-pack +4355 -0
- dingo_pack-0.4.2/hooks/hint.py +217 -0
- dingo_pack-0.4.2/hooks/hooks.json +38 -0
- dingo_pack-0.4.2/pyproject.toml +41 -0
- dingo_pack-0.4.2/selftest_dingo_pack.py +2105 -0
- dingo_pack-0.4.2/selftest_release.py +90 -0
- dingo_pack-0.4.2/skills/dingo-pack/SKILL.md +38 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Build and validate before the protected, token-free publishing job.
|
|
2
|
+
name: publish
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
permissions:
|
|
7
|
+
contents: read
|
|
8
|
+
jobs:
|
|
9
|
+
build:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- uses: astral-sh/setup-uv@v6
|
|
14
|
+
- name: Self-test
|
|
15
|
+
run: uv run --no-project python selftest_dingo_pack.py
|
|
16
|
+
- name: Build and validate distributions
|
|
17
|
+
run: |
|
|
18
|
+
uv build
|
|
19
|
+
uvx twine check dist/*
|
|
20
|
+
uv run --no-project python selftest_release.py --artifacts dist
|
|
21
|
+
- name: Check the version matches the release tag
|
|
22
|
+
run: |
|
|
23
|
+
v=$(uv run --no-project python bin/dingo-pack --version | awk '{print $2}')
|
|
24
|
+
test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != package version $v"; exit 1; }
|
|
25
|
+
- uses: actions/upload-artifact@v4
|
|
26
|
+
with:
|
|
27
|
+
name: distributions
|
|
28
|
+
path: dist/*
|
|
29
|
+
if-no-files-found: error
|
|
30
|
+
pypi:
|
|
31
|
+
needs: build
|
|
32
|
+
runs-on: ubuntu-latest
|
|
33
|
+
environment: pypi
|
|
34
|
+
permissions:
|
|
35
|
+
id-token: write
|
|
36
|
+
steps:
|
|
37
|
+
- uses: actions/download-artifact@v4
|
|
38
|
+
with:
|
|
39
|
+
name: distributions
|
|
40
|
+
path: dist/
|
|
41
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
name: test
|
|
2
|
+
on: [push, pull_request]
|
|
3
|
+
permissions:
|
|
4
|
+
contents: read
|
|
5
|
+
jobs:
|
|
6
|
+
posix:
|
|
7
|
+
strategy:
|
|
8
|
+
# One broken cell must not cancel the others (the 3.8 cell hid 3.12 / macOS results).
|
|
9
|
+
fail-fast: false
|
|
10
|
+
matrix:
|
|
11
|
+
include:
|
|
12
|
+
# ubuntu-latest is 26.04 now and setup-python has no 3.8 build for it;
|
|
13
|
+
# 3.8 is still built for 22.04.
|
|
14
|
+
- {os: ubuntu-22.04, python: '3.8'}
|
|
15
|
+
- {os: ubuntu-latest, python: '3.12'}
|
|
16
|
+
- {os: macos-latest, python: '3.12'}
|
|
17
|
+
runs-on: ${{ matrix.os }}
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v4
|
|
20
|
+
- uses: actions/setup-python@v5
|
|
21
|
+
with:
|
|
22
|
+
python-version: ${{ matrix.python }}
|
|
23
|
+
- name: Portable smoke and failure diagnostics
|
|
24
|
+
run: python selftest_release.py --portable
|
|
25
|
+
- name: Full Linux regression
|
|
26
|
+
if: runner.os == 'Linux'
|
|
27
|
+
run: python selftest_dingo_pack.py
|
|
28
|
+
windows-boundary:
|
|
29
|
+
runs-on: windows-latest
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
- uses: actions/setup-python@v5
|
|
33
|
+
with:
|
|
34
|
+
python-version: '3.12'
|
|
35
|
+
- name: Native Windows gives an actionable unsupported-platform message
|
|
36
|
+
shell: pwsh
|
|
37
|
+
run: |
|
|
38
|
+
$output = python bin/dingo-pack --version 2>&1 | Out-String
|
|
39
|
+
if ($LASTEXITCODE -ne 2 -or $output -notmatch 'inside WSL2') { throw $output }
|
|
40
|
+
exit 0
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Adapters: teaching dingo-pack about another coding agent
|
|
2
|
+
|
|
3
|
+
dingo-pack's core (process trees, memory, slots, the git queue via wombat-gate, boxes, the board) does not care which agent you run. Three things do, and they live in an **adapter**:
|
|
4
|
+
|
|
5
|
+
1. **Find the sessions.** Which agent sessions are alive on this machine: id, name, pid, working directory, state.
|
|
6
|
+
2. **Read a session's record.** Where its transcript is, and how many tokens each turn used.
|
|
7
|
+
3. **Hook into it.** How to make the agent run `dingo-pack save --hook` every turn and `hooks/hint.py` before heavy tool calls (optional: everything else works without hooks).
|
|
8
|
+
|
|
9
|
+
dingo-pack ships one adapter, for Claude Code. If you are an agent (Codex, pi, …) reading this to set dingo-pack up for yourself: write the ~100 lines below for your own agent, run the adapter test, and point dingo-pack at the file. We maintain the interface, the Claude Code adapter and the test, not other agents' adapters.
|
|
10
|
+
|
|
11
|
+
## 1 · The interface
|
|
12
|
+
|
|
13
|
+
One Python file that defines `ADAPTER`, an object with these attributes and methods (duck-typed; no base class to import):
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
class MyAgentAdapter:
|
|
17
|
+
name = "my-agent" # shown in `dingo-pack top` next to each session
|
|
18
|
+
owner_env = "MY_AGENT_PID" # env var your agent sets in every process it starts, holding the agent's pid;
|
|
19
|
+
# None if there is none (then only the agent's process tree counts as its children)
|
|
20
|
+
|
|
21
|
+
def sessions(self):
|
|
22
|
+
"""Live sessions on this machine. A list of dicts:
|
|
23
|
+
{"id": str, "pid": int, "name": str or None, "cwd": str or None,
|
|
24
|
+
"proc_start": str or None, # /proc/<pid>/stat field 22, to tell a reused pid apart (None if unknown)
|
|
25
|
+
"status": "busy" | "idle" | "waiting" | None,
|
|
26
|
+
"started_at": float or None} # epoch seconds"""
|
|
27
|
+
|
|
28
|
+
def transcript(self, session_id):
|
|
29
|
+
"""Path of the session's transcript file, or None."""
|
|
30
|
+
|
|
31
|
+
def subtranscripts(self, session_id, path):
|
|
32
|
+
"""Paths of its sub-agents' transcripts (may be [])."""
|
|
33
|
+
|
|
34
|
+
def usage(self, path, cache):
|
|
35
|
+
"""Tokens in one transcript, read incrementally. `cache` is a dict you may keep state in
|
|
36
|
+
(dingo-pack saves it between runs, keyed however you like). Return
|
|
37
|
+
{"days": {"YYYY-MM-DD": [input, cache_write, cache_read, output, turns]},
|
|
38
|
+
"last_input": int or None} # input tokens of the latest turn (input + cache write + cache read)
|
|
39
|
+
or None if the file cannot be read. Count each model call once."""
|
|
40
|
+
|
|
41
|
+
def hooks(self):
|
|
42
|
+
"""A short text for the human: how to make the agent run the two hooks."""
|
|
43
|
+
|
|
44
|
+
ADAPTER = MyAgentAdapter()
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Rules:
|
|
48
|
+
|
|
49
|
+
- **Read only.** An adapter must not write to the agent's files or send signals. dingo-pack's own test checks that `sessions()` and `usage()` leave the files they read unchanged.
|
|
50
|
+
- **Say "unknown", never guess.** If a field is not available, return `None`; the board then shows "读不到" / "?" instead of a made-up number.
|
|
51
|
+
- Standard library only, Python ≥ 3.8.
|
|
52
|
+
|
|
53
|
+
## 2 · Test it
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
DINGO_AGENTS=/path/to/my_agent_adapter.py dingo-pack adapter test
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
It loads the file, calls each method on the live machine, and checks: types and required keys, that each `pid` is alive, that transcripts exist and `usage()` returns non-negative integers, and that nothing it read changed. Exit code 0 = usable; otherwise it lists what is wrong.
|
|
60
|
+
|
|
61
|
+
## 3 · Use it
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
export DINGO_AGENTS=claude-code,/path/to/my_agent_adapter.py # several agents on one machine
|
|
65
|
+
dingo-pack top # each session: children, what it waits for, spin flags, tokens
|
|
66
|
+
dingo-pack tokens # tokens per session today
|
|
67
|
+
dingo-pack board
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`DINGO_AGENTS` takes built-in names (`claude-code`) and paths to adapter files, comma-separated. The default is `claude-code`.
|
|
71
|
+
|
|
72
|
+
## 4 · What uses the interface (0.4)
|
|
73
|
+
|
|
74
|
+
`top`, `tokens` and the task columns of `board` go through adapters. The roster (`save` / `list` / `resume` / `close-all` / `restore`) and `ghosts` still talk to Claude Code directly; they move behind the interface in a later version.
|
|
75
|
+
|
|
76
|
+
## 5 · The Claude Code adapter, for reference
|
|
77
|
+
|
|
78
|
+
- sessions: `~/.claude/sessions/<pid>.json` (`sessionId`, `pid`, `procStart`, `name`, `nameSource`, `status`, `cwd`, `startedAt`).
|
|
79
|
+
- transcript: `~/.claude/projects/<dir>/<sessionId>.jsonl`; sub-agents in `<sessionId>/subagents/*.jsonl`.
|
|
80
|
+
- usage: assistant lines carry `message.usage` (`input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `output_tokens`); one message is often written several times with the same `message.id`, so it is counted once.
|
|
81
|
+
- owner_env: `CLAUDE_PID`.
|
|
82
|
+
- hooks: the plugin in this repo (`/plugin install dingo-pack@dingo-pack`), or the snippet in REFERENCE.md.
|
|
83
|
+
|
|
84
|
+
## 6 · Claude Code、Codex、OpenCode Go 的接入边界
|
|
85
|
+
|
|
86
|
+
三者可在同一 POSIX 主机上调用 `dingo-pack run --heavy --mem <预估> -- <命令>`,
|
|
87
|
+
共享本地 DINGO_HOME。README 中英版给出项目 AGENTS.md、Codex skill、OpenCode
|
|
88
|
+
instructions 的配置例子。这些规则要求 agent 主动包命令,不构成外部命令拦截。
|
|
89
|
+
|
|
90
|
+
内置适配器只有 `claude-code`;Codex 与 OpenCode Go 没有内置发现/token/恢复适配。
|
|
91
|
+
不要在 DINGO_AGENTS 中填写不存在的内置名称。自定义实现通过文件路径加载,按上文
|
|
92
|
+
`adapter test` 校验;名册与 ghosts 仍仅针对 Claude。
|
|
93
|
+
|
|
94
|
+
All three agents can share command admission. Only Claude Code has a built-in session
|
|
95
|
+
adapter. Use external adapter file paths for other agents; do not invent built-in names.
|
|
96
|
+
The instruction/skill examples in both READMEs are guidance, not enforcement hooks.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# 更新记录 / Changelog
|
|
2
|
+
|
|
3
|
+
## 0.4.2 · 候选 / candidate
|
|
4
|
+
|
|
5
|
+
- Re-release of the 0.4.1 candidate with the public repo brought in sync: `hooks/hint.py` and `skills/dingo-pack/SKILL.md` now match the source tree.
|
|
6
|
+
- Positional arguments after options are accepted on Python < 3.12 (argparse `parse_known_args` fallback), so `mark done --sid X note` and similar forms work from 3.8 through 3.14; command lines are unchanged.
|
|
7
|
+
- Self-test falls back to the tool's fixed-zone implementation when `zoneinfo` is missing (Python 3.8), removing the four zone-related failures there.
|
|
8
|
+
- CI: the 3.8 job runs on `ubuntu-22.04` (setup-python has no 3.8 build for 26.04) and `fail-fast` is off, so one red job no longer cancels the others; the test matrix is an explicit `include`.
|
|
9
|
+
|
|
10
|
+
## 0.4.1 · 候选 / candidate
|
|
11
|
+
|
|
12
|
+
- 基于 0.4.0,保留 boxes、tokens、任务列及只读适配接口;未部署、未发布。
|
|
13
|
+
Based on 0.4.0; retains boxes, tokens, task columns and read-only adapters; not deployed or published.
|
|
14
|
+
- 失败时输出配置上限、退出信号和审慎的可能撞限提示;保留子命令输出、退出码与整树停止行为。
|
|
15
|
+
Report configured limits, exit signals and cautious memory hints; preserve child output and exit codes.
|
|
16
|
+
- sdist 补 ADAPTERS、发布说明与回归;补中英平台表、三种 agent 接法和安装演示。
|
|
17
|
+
Include adapter/release docs and regressions in sdist; document platforms, agent setup and local install.
|
|
18
|
+
- 发布前独立构建检查,审批后的上传任务只消费产物;增加 Linux/macOS CI 与 Windows 边界检查。
|
|
19
|
+
Validate artifacts before environment approval; publishing consumes artifacts; add platform CI.
|
|
20
|
+
|
|
21
|
+
## 0.4.0 · work 源码基线 / source baseline
|
|
22
|
+
|
|
23
|
+
boxes、tokens、adapter test、任务等待列及 claim 扩展;历史测试通过但未部署。
|
|
24
|
+
Adds boxes, tokens, adapter test, task/wait columns and claim extensions; historically tested, not deployed.
|
|
25
|
+
|
|
26
|
+
## 0.3.1 · 未公开发布 / unpublished build
|
|
27
|
+
|
|
28
|
+
慢盘队列、CPU 名额、doctor、ghosts、会话恢复、看板与占用登记。
|
|
29
|
+
I/O lane, CPU slots, doctor, ghosts, session restore, board and claims.
|
|
30
|
+
|
|
31
|
+
## 0.1.1 · 公开 release / public release
|
|
32
|
+
|
|
33
|
+
名额、内存准入与上限、lease、Claude 名册与恢复。
|
|
34
|
+
Slots, memory admission/limits, leases and Claude roster/resume.
|
dingo_pack-0.4.2/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 liyifreddy
|
|
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,284 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: dingo-pack
|
|
3
|
+
Version: 0.4.2
|
|
4
|
+
Summary: The pack eats in order: heavy-job slots, memory admission and a crash-recovery session roster for many AI agents on one machine.
|
|
5
|
+
Project-URL: Homepage, https://github.com/liyifreddy/dingo-pack
|
|
6
|
+
Project-URL: Issues, https://github.com/liyifreddy/dingo-pack/issues
|
|
7
|
+
Author: liyifreddy
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: claude-code,memory,multi-agent,oom,queue,sessions,wsl
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Operating System :: POSIX
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: System :: Monitoring
|
|
15
|
+
Requires-Python: >=3.8
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# 🐕 dingo-pack
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<img src="https://raw.githubusercontent.com/liyifreddy/dingo-pack/main/docs/img/dingo-pack-banner.jpg" width="100%"
|
|
22
|
+
alt="Dingoes eating side by side at a trough with four compartments while three more wait their turn">
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
**Like a tab saver, for your Claude Code sessions.**
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
dingo-pack save # remember the open sessions (the hooks also do it)
|
|
29
|
+
dingo-pack close-all # remember them, close the idle ones that are waiting / done
|
|
30
|
+
dingo-pack restore # bring the last batch back, one terminal tab each
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
🌐 **English** · [中文](https://github.com/liyifreddy/dingo-pack/blob/main/README.zh-CN.md)
|
|
34
|
+
|
|
35
|
+
The pack eats in order: dingoes share a kill without a scramble. dingo-pack is the pack
|
|
36
|
+
leader for a dozen coding agents on one machine — it also hands out slots for heavy work
|
|
37
|
+
and checks what is wrong when the machine struggles.
|
|
38
|
+
|
|
39
|
+
`restore` opens a new Windows Terminal tab per session when it runs in WSL, a tmux window
|
|
40
|
+
inside tmux, and otherwise prints the commands for you to paste. `close-all` only closes
|
|
41
|
+
sessions that are idle and said they are waiting or done, and it is for humans: inside an
|
|
42
|
+
agent it refuses.
|
|
43
|
+
|
|
44
|
+
## 🚀 Quick start
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
pipx install git+https://github.com/liyifreddy/dingo-pack
|
|
48
|
+
|
|
49
|
+
dingo-pack # one screen: memory, slots, sessions
|
|
50
|
+
dingo-pack run --heavy --mem 4G -- pytest # heavy work waits for a slot and free memory
|
|
51
|
+
dingo-pack doctor # what's wrong with this machine right now?
|
|
52
|
+
dingo-pack list # after a crash: which sessions were lost
|
|
53
|
+
dingo-pack resume --midway # reopen the ones that were mid-task
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
In Claude Code, install the plugin and the roster saves itself:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
/plugin marketplace add liyifreddy/dingo-pack
|
|
60
|
+
/plugin install dingo-pack@dingo-pack
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
One file, Python ≥ 3.8, standard library only. Linux, macOS and WSL.
|
|
64
|
+
|
|
65
|
+
## Release and installation demo
|
|
66
|
+
|
|
67
|
+
Current release: **0.4.2**. Install it from PyPI with pip or pipx:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
python3 -m pip install dingo-pack # or: pipx install dingo-pack
|
|
71
|
+
dingo-pack --version
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
To install from this source tree instead, use a separate environment:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
python3 -m venv .venv-demo && .venv-demo/bin/python -m pip install .
|
|
78
|
+
.venv-demo/bin/dingo-pack --version
|
|
79
|
+
.venv-demo/bin/dingo-pack run --heavy --threads 1 --mem 64M -- python3 -c 'print("hello")'
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Expected from either: `dingo-pack 0.4.2`; the source demo also prints `hello`
|
|
83
|
+
(admission may wait). State and locks must live on a local disk; leave `DINGO_HOME`
|
|
84
|
+
at its default, outside a WSL mounted drive. `boxes`, `tokens`, adapter validation
|
|
85
|
+
and task/wait columns are included; `watch`, `dispatch` and full three-table
|
|
86
|
+
crosscheck remain design proposals. See [CHANGELOG](CHANGELOG.md) and
|
|
87
|
+
[release procedure](RELEASING.md).
|
|
88
|
+
|
|
89
|
+
## Platforms and agents
|
|
90
|
+
|
|
91
|
+
| Platform | Support boundary | Tested for this candidate (2026-11-04) |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| Linux | POSIX CLI and `/proc` monitoring | WSL Linux kernel tested; separate native Linux host not tested |
|
|
94
|
+
| WSL2 | Run Python and the CLI inside WSL; state on the Linux disk | Tested: full suite, bounded CSV and install smoke |
|
|
95
|
+
| macOS | POSIX CLI, `ps`/`vm_stat` fallbacks; Linux-only probes may be unknown | Not tested; portable CI job added, not yet run |
|
|
96
|
+
| Native Windows | Unsupported: requires `fcntl`, POSIX signals and resource limits; use WSL2 | Tested with native Windows Python 3.14: actionable unsupported-platform message, exit 2 |
|
|
97
|
+
|
|
98
|
+
All three agents can use the same `run` queue on a supported host. No tool-specific
|
|
99
|
+
hook is required to wrap a shell command. Configuration examples below are manual
|
|
100
|
+
instructions, not enforcement hooks.
|
|
101
|
+
|
|
102
|
+
- **Claude Code:** plugin installation above supplies hooks; see [REFERENCE](REFERENCE.md)
|
|
103
|
+
for manual hook configuration. The bundled `skills/dingo-pack/SKILL.md` supplies guidance.
|
|
104
|
+
- **Codex:** add the following rule to the project's `AGENTS.md`. Optionally copy
|
|
105
|
+
`skills/dingo-pack/SKILL.md` into `.agents/skills/dingo-pack/SKILL.md` in that project.
|
|
106
|
+
- **OpenCode Go:** when using OpenCode with Go, put the same rule in the project's
|
|
107
|
+
`AGENTS.md`. Alternatively reference a rule file in `opencode.json`:
|
|
108
|
+
`{"$schema":"https://opencode.ai/config.json","instructions":["docs/heavy-work.md"]}`.
|
|
109
|
+
No provider credentials are needed by dingo-pack.
|
|
110
|
+
|
|
111
|
+
```markdown
|
|
112
|
+
Before heavy shell work, run `dingo-pack who`, then wrap the command:
|
|
113
|
+
`dingo-pack run --heavy --mem <estimated peak> -- <command>`.
|
|
114
|
+
Use the same local DINGO_HOME for all agents sharing the machine.
|
|
115
|
+
Keep the queue and memory limits in force; report failures with the diagnostic line.
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Claude Code has a built-in session/token adapter. Codex and OpenCode can share the
|
|
119
|
+
queue, but automatic session discovery, token counts, resume and close are not
|
|
120
|
+
provided for them. External read-only adapters can extend `top`/`tokens`/task columns;
|
|
121
|
+
[ADAPTERS](ADAPTERS.md) defines that interface. Roster and ghosts are still Claude-specific.
|
|
122
|
+
Agent UI sessions were not launched for this candidate's tests.
|
|
123
|
+
|
|
124
|
+
Sources: [Codex instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md),
|
|
125
|
+
[skills](https://learn.chatgpt.com/docs/build-skills),
|
|
126
|
+
[OpenCode rules](https://docs.opencode.ai/docs/rules/).
|
|
127
|
+
|
|
128
|
+
## Reading memory failures
|
|
129
|
+
|
|
130
|
+
On a failed job, the CLI preserves its exit status and prints configured per-process
|
|
131
|
+
and tree limits, sampled RSS, and the exit signal. `SIGSEGV`/139 and `SIGKILL`/137 with
|
|
132
|
+
a configured cap mean **possible memory limit hit**, not proof of OOM. A tree-limit
|
|
133
|
+
stop is confirmed by the supervisor. An ordinary nonzero exit keeps its cause unknown;
|
|
134
|
+
read the child's `MemoryError`, parser error or application error too.
|
|
135
|
+
|
|
136
|
+
Without configuration, defaults are `--mem 1G`, per-process `--limit 1.5G`, and matching tree limit.
|
|
137
|
+
`default_mem` / `DINGO_DEFAULT_MEM` overrides the estimate. RLIMIT_DATA
|
|
138
|
+
and RLIMIT_AS are not RSS: failed allocations and brief peaks can be missed by RSS
|
|
139
|
+
sampling. For large CSVs, prefer chunked reading; if more memory is needed, check
|
|
140
|
+
available memory and raise the estimate/caps together. Input file size alone does not
|
|
141
|
+
predict peak memory. `python3 selftest_release.py --large-csv` exercises a 670 MiB
|
|
142
|
+
synthetic CSV under bounded memory without loading gigabytes into RAM.
|
|
143
|
+
|
|
144
|
+
## 😩 The problem
|
|
145
|
+
|
|
146
|
+
- 💥 **Heavy jobs pile up.** Test runs, model loads, builds and reviews from several
|
|
147
|
+
sessions start at once. In our 16 GB WSL VM, 13 sessions already used 4.4 GB; then the
|
|
148
|
+
kernel killed a 7.5–11 GB Python job, and work in flight died with it.
|
|
149
|
+
- 🪟 **WSL drops its Windows drives.** When memory runs out, `/mnt/c`, `/mnt/g`, … start
|
|
150
|
+
returning I/O errors until remounted — for every session at once.
|
|
151
|
+
- 👻 **Closed sessions leave things running.** Their python, node and MCP servers keep
|
|
152
|
+
eating memory until the next big job tips the machine over.
|
|
153
|
+
- 🧠 **After a crash, who was running?** Our laptop went down with 8 sessions open. We
|
|
154
|
+
pieced the list together from memory.
|
|
155
|
+
|
|
156
|
+
## ✨ Five things
|
|
157
|
+
|
|
158
|
+
- ✅ 🎟️ **Slots and memory.** `run --heavy` waits for a free slot (6 by default) *and*
|
|
159
|
+
enough free memory, then runs the job under a memory limit for the whole process tree.
|
|
160
|
+
On a simulated 350 MB machine, four 150 MB jobs started together hit the OOM killer;
|
|
161
|
+
through dingo-pack, all four finish.
|
|
162
|
+
- ✅ 🚚 **A lane for slow disks.** `run --io` gives big copies, archives and scans on a
|
|
163
|
+
network or 9p drive their own queue (1 at a time), apart from CPU work.
|
|
164
|
+
- ✅ 📋 **Roster: close-all, restore, recall.** Before you shut down, `close-all` notes every
|
|
165
|
+
session and closes the ones that are idle and waiting or done; `restore` brings them
|
|
166
|
+
back. After a crash `restore` works too: it brings back what the crash lost.
|
|
167
|
+
- ✅ 👻 **Ghosts and sub-agent hints.** `ghosts` finds processes whose session is gone.
|
|
168
|
+
The hint hook tells an agent, before it starts sub-agents or heavy commands, how many
|
|
169
|
+
slots are free, how much memory is left, and how many jobs it should run in parallel.
|
|
170
|
+
- ✅ 🩺 **One-stop checkup.** `doctor` reads memory, recent OOM kills, whether each
|
|
171
|
+
network drive still answers, your WSL settings, stuck slots, lost sessions, ghosts and
|
|
172
|
+
git lock files (through [wombat-gate](https://github.com/liyifreddy/wombat-gate)). It
|
|
173
|
+
only reports; it never fixes anything for you.
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
heavy 0 [###### pytest (est 2G) ######]
|
|
177
|
+
heavy 1 [######### lease: code review #########]
|
|
178
|
+
io 0 [## tar of the dataset ##]
|
|
179
|
+
queue C ──> D ──> E next in line waits for a free slot AND enough memory
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## 🎟️ Heavy work and slow disks
|
|
183
|
+
|
|
184
|
+
```sh
|
|
185
|
+
dingo-pack run --heavy --mem 6G -- python train.py # wait for a slot + 6 GB, then run
|
|
186
|
+
dingo-pack run --heavy --mem 2G --timeout 30m -- pytest # give up after 30 min (exit 75)
|
|
187
|
+
dingo-pack run --io -- tar -cf /mnt/g/backup.tar data/ # big copy on a slow disk: its own lane
|
|
188
|
+
dingo-pack who # who holds the slots, who is waiting
|
|
189
|
+
dingo-pack top # memory by session
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
- `--threads N` (default 8) sets `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`
|
|
193
|
+
and friends for the job and takes N of the machine's CPU slots (one per core). `doctor`
|
|
194
|
+
and the hint warn when the load is above 1.5 per core.
|
|
195
|
+
- `--mem` is your best guess at the peak. The limit defaults to 1.5 × that; go over it
|
|
196
|
+
and only your job stops (a single process gets a MemoryError; a whole tree over the
|
|
197
|
+
limit is stopped with exit 137), not the machine.
|
|
198
|
+
- Work that isn't a shell command — an agent's own review, a batch of sub-agents — takes
|
|
199
|
+
a lease: `dingo-pack lease --mem 3G --for 45m`, then `dingo-pack release`. The lease
|
|
200
|
+
also ends when its agent exits.
|
|
201
|
+
|
|
202
|
+
## 📋 The roster
|
|
203
|
+
|
|
204
|
+
<p align="center">
|
|
205
|
+
<img src="https://raw.githubusercontent.com/liyifreddy/dingo-pack/main/docs/img/dingo-pack-roster-captioned.jpg" width="100%"
|
|
206
|
+
alt="Three panels: at night the pack leader keeps a roster by the campfires; a storm scatters the pack while the leader shelters with the roster; at dawn the leader whistles and the pack comes back to the fires">
|
|
207
|
+
</p>
|
|
208
|
+
|
|
209
|
+
1. **Save** — sessions are snapshotted as they work.
|
|
210
|
+
2. **The machine goes down** — the roster is already on disk.
|
|
211
|
+
3. **Resume** — `list` shows who was lost; `resume` calls them back.
|
|
212
|
+
|
|
213
|
+
<p align="center"><sub>Illustrations generated with Google Gemini and edited by the author.</sub></p>
|
|
214
|
+
|
|
215
|
+
```sh
|
|
216
|
+
dingo-pack mark running "step 3" # say what you're doing: running | waiting | blocked | done
|
|
217
|
+
dingo-pack mark waiting --until 18:30 "nightly job"
|
|
218
|
+
dingo-pack close-all # before shutting down: note everyone, close the idle waiting / done ones
|
|
219
|
+
dingo-pack restore # bring back what close-all closed
|
|
220
|
+
dingo-pack resume NAME... --via tmux # by name; tabs via Windows Terminal, tmux, or just print
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
`close-all` never touches a session that is busy, running, blocked, or the one you
|
|
224
|
+
type it in, and it checks each session again right before closing it. It is for humans:
|
|
225
|
+
inside an agent it refuses.
|
|
226
|
+
|
|
227
|
+
## 👻 Ghosts
|
|
228
|
+
|
|
229
|
+
```sh
|
|
230
|
+
dingo-pack ghosts # process trees whose Claude Code session is gone
|
|
231
|
+
dingo-pack ghosts --reap # stop them, after asking (humans only)
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
A process belongs to the session whose `CLAUDE_PID` it carries. Jobs left on purpose
|
|
235
|
+
(nohup, setsid, tmux, or a session that said it is waiting) are listed but kept.
|
|
236
|
+
|
|
237
|
+
## 📊 Board
|
|
238
|
+
|
|
239
|
+
```sh
|
|
240
|
+
dingo-pack board # one line per session: state, box, expected finish, flags
|
|
241
|
+
dingo-pack board --html board.html --watch 30 # a page that refreshes itself
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
It reads each session's last status line. "ask now" means the expected finish it wrote
|
|
245
|
+
has passed; "may have stopped" means the status line has not changed for 3 hours
|
|
246
|
+
(`--stale-h`). It only understands an expected time after a word like 预计 / 约 … 完 / ETA;
|
|
247
|
+
anything else is left blank rather than guessed.
|
|
248
|
+
|
|
249
|
+
## 🧰 Team routines (optional)
|
|
250
|
+
|
|
251
|
+
`name` (next session name for a letter), `card new` (next free card number + skeleton),
|
|
252
|
+
`lint` (naming, one session per letter, stale or overdue status lines), `queue` (prompts
|
|
253
|
+
waiting for a condition) and `claim` (the per-box occupancy file). All are deterministic
|
|
254
|
+
and off unless you call them — see the [reference](REFERENCE.md).
|
|
255
|
+
|
|
256
|
+
## ⚙️ More
|
|
257
|
+
|
|
258
|
+
The plugin brings the CLI, the roster hooks, the hint hook and a skill that teaches the
|
|
259
|
+
agent when to use a slot. Hook setup without the plugin, project settings, every option
|
|
260
|
+
and WSL memory tips are in the [reference](REFERENCE.md).
|
|
261
|
+
|
|
262
|
+
## ⚠️ Limits
|
|
263
|
+
|
|
264
|
+
- The agent process itself can't be limited, only counted with a lease.
|
|
265
|
+
- Only jobs started through dingo-pack are managed.
|
|
266
|
+
- Slots are handed out roughly first come, first served (the kernel decides who wakes first).
|
|
267
|
+
- macOS: the per-process limit isn't enforced (the tree limit is), and free memory is an
|
|
268
|
+
estimate. `ghosts`, `top` and the WSL checks need Linux.
|
|
269
|
+
- The roster reads Claude Code's session files, which aren't a documented interface. If
|
|
270
|
+
they change, it falls back to transcripts and says so.
|
|
271
|
+
|
|
272
|
+
## ✅ Self-test
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
python3 selftest_dingo_pack.py --base /some/local/dir # 1–3 min, depending on load
|
|
276
|
+
python3 selftest_dingo_pack.py --mutants # each planted bug must turn a check red
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Memory tests run on a simulated machine, never on your real memory.
|
|
280
|
+
|
|
281
|
+
## 📄 License
|
|
282
|
+
|
|
283
|
+
MIT. Sister tool: [wombat-gate](https://github.com/liyifreddy/wombat-gate), a git commit
|
|
284
|
+
queue for agents sharing one repo.
|