docks-kit 0.22.13 → 0.22.22
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.
- package/AGENTS.md +97 -83
- package/README.md +7 -7
- package/cli/docs/command-guards.md +12 -7
- package/cli/docs/flags.md +59 -9
- package/cli/docs/install.md +2 -2
- package/cli/docs/omp-context.md +27 -17
- package/cli/docs/omp-models.md +91 -70
- package/cli/docs/overview.md +1 -1
- package/cli/docs/platforms.md +4 -2
- package/cli/docs/plugins.md +8 -5
- package/cli/docs/sync-layers.md +6 -4
- package/cli/docs/toolchain.md +24 -14
- package/cli/src/argv.ts +7 -4
- package/cli/src/argvValidate.ts +2 -16
- package/cli/src/commands/docs.ts +1 -1
- package/cli/src/commands/omp.ts +81 -88
- package/cli/src/commands/sync.ts +6 -6
- package/cli/src/commands/tidy.ts +83 -26
- package/cli/src/engine-native/DESIGN.md +93 -56
- package/cli/src/engine-native/atomicWrite.ts +168 -8
- package/cli/src/engine-native/codexConfig.ts +2 -6
- package/cli/src/engine-native/codexPlugins.ts +1 -1
- package/cli/src/engine-native/codexSync.ts +137 -26
- package/cli/src/engine-native/codexToml.ts +4 -86
- package/cli/src/engine-native/deps.ts +51 -51
- package/cli/src/engine-native/exec.ts +3 -0
- package/cli/src/engine-native/harnesses.ts +5 -11
- package/cli/src/engine-native/index.ts +1 -1
- package/cli/src/engine-native/kitDb.ts +7 -7
- package/cli/src/engine-native/kitLock.ts +121 -0
- package/cli/src/engine-native/modes.ts +49 -31
- package/cli/src/engine-native/ompChild.ts +26 -0
- package/cli/src/engine-native/ompFastMode.ts +14 -7
- package/cli/src/engine-native/ompFileDeploy.ts +12 -6
- package/cli/src/engine-native/ompMarketplace.ts +25 -18
- package/cli/src/engine-native/ompOverlay.ts +23 -69
- package/cli/src/engine-native/ompPlugins.ts +23 -14
- package/cli/src/engine-native/ompRemovals.ts +97 -30
- package/cli/src/engine-native/ompSync.ts +66 -32
- package/cli/src/engine-native/os/targets.ts +16 -4
- package/cli/src/engine-native/os/types.ts +1 -1
- package/cli/src/engine-native/parseArgs.ts +27 -17
- package/cli/src/engine-native/processes.ts +16 -0
- package/cli/src/engine-native/scratch.ts +18 -0
- package/cli/src/engine-native/sharedTypes.d.ts +0 -2
- package/cli/src/engine-native/skillsInstall.ts +27 -2
- package/cli/src/engine-native/skillsPrune.ts +51 -49
- package/cli/src/engine-native/skillsRecords.ts +138 -0
- package/cli/src/engine-native/skillsSync.ts +16 -13
- package/cli/src/engine-native/syncDispatch.ts +186 -4
- package/cli/src/engine-native/tidy.ts +102 -119
- package/cli/src/engine-native/tomlLines.ts +92 -0
- package/cli/src/generated/sotPayload.ts +5 -5
- package/cli/src/main.ts +5 -30
- package/cli/src/manifests.ts +24 -4
- package/package.json +2 -2
- package/cli/src/engine-native/tidyLock.ts +0 -163
package/cli/docs/flags.md
CHANGED
|
@@ -26,11 +26,11 @@ Escape leaves it unchanged.
|
|
|
26
26
|
|
|
27
27
|
| Flag | Effect |
|
|
28
28
|
|------|--------|
|
|
29
|
-
| `--dry-run` | Preview without applying |
|
|
29
|
+
| `--dry-run` | Preview without applying; takes no sync lock and no folder lock |
|
|
30
30
|
| `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
|
|
31
|
-
| `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
|
|
31
|
+
| `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, and the universal skills that `~/.agents/.kit-owned-skills` names |
|
|
32
32
|
| `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
|
|
33
|
-
| `--skip-plugin-refresh` | Install missing Claude
|
|
33
|
+
| `--skip-plugin-refresh` | Install missing Claude, Codex, and omp plugins but skip refresh-only updates |
|
|
34
34
|
| `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
|
|
35
35
|
|
|
36
36
|
## Environment overrides
|
|
@@ -38,6 +38,54 @@ Escape leaves it unchanged.
|
|
|
38
38
|
| Variable | Effect |
|
|
39
39
|
|----------|--------|
|
|
40
40
|
| `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `model` or `toolchain`. |
|
|
41
|
+
| `DOCKS_KIT_SYNC_LOCK_WAIT_MS=<ms>` | Time that `sync`, a `model` write, and `omp --fast` wait for another sync to release a sync lock. A non-negative safe integer in milliseconds (at most `9007199254740991`); unset or empty means `120000` (120 s). Any other value prints `DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer` and exits 2. |
|
|
42
|
+
|
|
43
|
+
## Sync lock
|
|
44
|
+
|
|
45
|
+
`sync` and `model <tool> <value>` hold the lock
|
|
46
|
+
`~/.cache/docks-kit/sync-lock.db` while they run, so two runs never write the
|
|
47
|
+
same files at once.
|
|
48
|
+
|
|
49
|
+
- A run waits up to 120 s for another run to release the lock
|
|
50
|
+
(`DOCKS_KIT_SYNC_LOCK_WAIT_MS` changes the wait). It then prints
|
|
51
|
+
`another docks-kit sync holds <path>; run sync again after it ends` and
|
|
52
|
+
exits 1 with no change.
|
|
53
|
+
- Two homes can share a Codex folder (`CODEX_HOME`), an agents folder
|
|
54
|
+
(`AGENTS_DIR`), or an omp folder (`PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR`,
|
|
55
|
+
`XDG_DATA_HOME`, or a symlink). So a writing sync also holds
|
|
56
|
+
`.docks-kit-sync-lock.db` inside each such folder that it writes. For `codex`
|
|
57
|
+
this is the Codex folder, and for `agents` the agents folder. For `omp` it is
|
|
58
|
+
the omp agent folder, the intercom folder, and the omp data root. A
|
|
59
|
+
`model codex <value>` write holds the Codex folder lock too. The held line
|
|
60
|
+
then names that lock file.
|
|
61
|
+
- A writing sync creates a missing folder of this set just before it takes the
|
|
62
|
+
lock of that folder, after the locks of its ancestors in the set. Each folder
|
|
63
|
+
that it creates gets mode 0700. The lock step does not change the mode of an
|
|
64
|
+
existing folder. The omp pipeline then sets mode 0700 on the omp agent folder
|
|
65
|
+
and the intercom folder.
|
|
66
|
+
- A sync finds the omp folders once, before it takes the locks. The omp
|
|
67
|
+
pipeline and each `omp` command that it starts use these folders. When the
|
|
68
|
+
locked data root is the omp config root, each `omp` command starts without
|
|
69
|
+
`XDG_DATA_HOME`. So a `$XDG_DATA_HOME/omp` folder that appears during the
|
|
70
|
+
sync does not move the plugin data to a folder without a lock. A later
|
|
71
|
+
`omp` uses that new folder, so the sync then prints
|
|
72
|
+
`omp data root moved to <root> during the sync; run docks-kit sync again`
|
|
73
|
+
and exits 1. The next sync locks the new folder and installs the plugins
|
|
74
|
+
there.
|
|
75
|
+
- The locks cover the folder that the kit writes into, not the target of a
|
|
76
|
+
symlinked file. Two homes whose `config.yml` (or another deployed file) links
|
|
77
|
+
to one shared file can still overwrite the merge of each other.
|
|
78
|
+
- `docks-kit omp --fast` checks `config.yml` before it takes a lock. When the
|
|
79
|
+
file is missing, it exits 2 and creates no omp folder. Otherwise it holds the
|
|
80
|
+
sync lock and the omp agent folder lock while it rewrites `config.yml`. The
|
|
81
|
+
wait and the held line are those of a sync.
|
|
82
|
+
- A run with `--dry-run`, `-h`, or `--help` takes no lock. A dry run through
|
|
83
|
+
the `DRY_RUN=1` env global of the private `native-raw` engine channel takes
|
|
84
|
+
no lock either. `model <tool>` without a value only reads, so it takes no
|
|
85
|
+
lock.
|
|
86
|
+
- The lock goes when the run ends, also when the process is killed.
|
|
87
|
+
- A held lock also delays the error of an invalid argument until the wait
|
|
88
|
+
ends.
|
|
41
89
|
|
|
42
90
|
## Per-tool flags
|
|
43
91
|
|
|
@@ -60,7 +108,7 @@ ignored with a warning; Claude modifiers never touch Codex config and vice versa
|
|
|
60
108
|
|
|
61
109
|
| Flag | Effect |
|
|
62
110
|
|------|--------|
|
|
63
|
-
| `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost
|
|
111
|
+
| `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost with `pricingStatus` `free` or `unknown`; recorded in `~/.docks-kit/kit.db` (table `omp_session`) |
|
|
64
112
|
| `--pick` | Interactive picker over free catalog models; records the choice the same way |
|
|
65
113
|
| `--fast` | Toggle `tier.openai` between `priority` and `none` in the deployed `~/.omp/agent/config.yml`, print the change, and exit; the same tier omp's `/fast on` selects for OpenAI and Codex models |
|
|
66
114
|
|
|
@@ -77,10 +125,11 @@ The launcher rejects a forwarded `--config`, `--model`, `--smol`, `--slow`,
|
|
|
77
125
|
in the `--flag value` and the `--flag=value` form and also after a `--`. It
|
|
78
126
|
exits with code 2 before omp starts. The error names the flag and the
|
|
79
127
|
recoveries: `--model <selector>` before the other arguments or `--pick` for a
|
|
80
|
-
free model, `omp` directly for a paid model
|
|
81
|
-
config file. The launcher sets
|
|
82
|
-
`PI_PLAN_MODEL` to the free role values,
|
|
83
|
-
that it replaces, and appends the overlay
|
|
128
|
+
free model, and `omp` directly for a paid model. For a forwarded `--config`, it
|
|
129
|
+
also names `PI_CONFIG_FILES` for another config file. The launcher sets
|
|
130
|
+
`PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and `PI_PLAN_MODEL` to the free role values,
|
|
131
|
+
warns once for each exported value that it replaces, and appends the overlay
|
|
132
|
+
to `PI_CONFIG_FILES`. See
|
|
84
133
|
[omp-models.md](omp-models.md#free-session-launcher-docks-kit-omp) for the
|
|
85
134
|
full policy and the paths that stay outside the launcher.
|
|
86
135
|
|
|
@@ -105,7 +154,7 @@ forwarded `--model` stops the launcher with exit 2, also behind `--`.
|
|
|
105
154
|
| `scratch new <label>` | Create a private directory (mode 0700) `~/.cache/docks-kit/scratch/<label>-XXXXXX` and print its path; the label matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` |
|
|
106
155
|
| `scratch remove <path>...` | Remove each path whose real path is strictly inside the scratch root, the system temporary directory, or `/var/tmp`; print `removed <path>` or `refused <path>: <reason>`; exit 1 when any path is refused |
|
|
107
156
|
| `tidy` | List the safe leftover actions (`remove`, `stop`) and the kept candidates (`keep`) with reasons; change nothing |
|
|
108
|
-
| `tidy --apply` |
|
|
157
|
+
| `tidy --apply` | Take the lock `~/.cache/docks-kit/tidy-lock.db`, then plan, perform those actions, and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails. When another run holds the lock, print only `another docks-kit tidy run holds <path>`, with no plan and no report, and exit 0. A dry run (`tidy` without `--apply`) and the `--report` sections take no lock |
|
|
109
158
|
| `tidy --repo <path>` | Take the worktree candidates only from that repository, at any location |
|
|
110
159
|
| `tidy --report` | After the plan, print read-only sections on memory, temporary directories, processes, Docker, caches, Trash, git, agent histories, scheduled jobs, and global installs |
|
|
111
160
|
|
|
@@ -121,3 +170,4 @@ Old flags exit with a rename hint — there is no compat behavior.
|
|
|
121
170
|
| `--680k` | `--claude-compact-window=680k` |
|
|
122
171
|
| `--permissive` | `--claude-permissive` |
|
|
123
172
|
| `--supabase` / `--n8n` | `--claude-plugin=supabase` / `--claude-plugin=n8n` |
|
|
173
|
+
| `--skip-rtk` | `--skip-bubblewrap` |
|
package/cli/docs/install.md
CHANGED
|
@@ -113,8 +113,8 @@ installed plugins even when the kit is already current. Pass `--no-sync`, then
|
|
|
113
113
|
run `docks-kit sync --skip-plugin-refresh` to skip the refresh-only work.
|
|
114
114
|
A compiled binary inside a checkout updates the checkout; on the next invocation
|
|
115
115
|
the launcher bypasses that now-stale binary and uses updated source until rebuilt.
|
|
116
|
-
Every `docks-kit sync` also does a best-effort behind-upstream
|
|
117
|
-
nudges when the checkout is stale (silent offline / detached / no git).
|
|
116
|
+
Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
|
|
117
|
+
check and nudges when the checkout is stale (silent offline / detached / no git).
|
|
118
118
|
|
|
119
119
|
## Recovering a broken global install
|
|
120
120
|
|
package/cli/docs/omp-context.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# omp context and compaction
|
|
2
2
|
|
|
3
|
-
This topic records why `SoT/.omp/config.yml`
|
|
4
|
-
|
|
3
|
+
This topic records why `SoT/.omp/config.yml` ships no compaction threshold,
|
|
4
|
+
and what omp's reserve-based default computes on each model lane.
|
|
5
5
|
|
|
6
6
|
## How omp resolves the trigger
|
|
7
7
|
|
|
@@ -9,8 +9,10 @@ threshold, and what omp's reserve-based default computes on each model lane.
|
|
|
9
9
|
`packages/agent/src/compaction/compaction.ts` selects the trigger from three
|
|
10
10
|
branches, in priority order.
|
|
11
11
|
|
|
12
|
-
1. A positive `compaction.thresholdTokens` wins.
|
|
13
|
-
|
|
12
|
+
1. A positive `compaction.thresholdTokens` wins. A value below the window is
|
|
13
|
+
exact. For a value at or above the window, the behavior depends on the omp
|
|
14
|
+
release. omp 18.4.4 through 18.8.7 clamps the value to `contextWindow - 1`.
|
|
15
|
+
omp 18.8.8 and later fall back to the reserve-based budget of branch 3.
|
|
14
16
|
2. Otherwise a positive `compaction.thresholdPercent` applies. omp clamps the
|
|
15
17
|
percent to the range 1 through 99 and computes
|
|
16
18
|
`floor(contextWindow * percent / 100)`.
|
|
@@ -31,10 +33,11 @@ constant.
|
|
|
31
33
|
|
|
32
34
|
| Lane | Window | Reserve | Threshold | Percent of window |
|
|
33
35
|
|---|---:|---:|---:|---:|
|
|
34
|
-
| `openai-codex
|
|
36
|
+
| `openai-codex/gpt-6-astra`, `openai-codex/gpt-6-luna` | 272,000 | 40,800 | 231,200 | 85.0% |
|
|
37
|
+
| `openai-codex/gpt-6.1-sol`, `openai-codex/gpt-6.1-terra` | 500,000 | 75,000 | 425,000 | 85.0% |
|
|
35
38
|
| `anthropic/*` | 1,000,000 | 150,000 | 850,000 | 85.0% |
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
Every lane compacts at the same fraction of its own window. The absolute
|
|
38
41
|
trigger differs only because the windows differ.
|
|
39
42
|
|
|
40
43
|
## Why the kit no longer pins 231200
|
|
@@ -59,17 +62,20 @@ No session ran past its window, and omp raised no warning on either lane.
|
|
|
59
62
|
Under the reserve-based default none of the 75 Anthropic compactions would
|
|
60
63
|
have fired, because no session reached 850,000.
|
|
61
64
|
|
|
62
|
-
##
|
|
65
|
+
## How sync removes the deployed pin
|
|
66
|
+
|
|
67
|
+
The kit no longer ships `compaction.thresholdTokens`. omp's schema default
|
|
68
|
+
`-1` applies, and that sentinel selects the reserve-based branch.
|
|
63
69
|
|
|
64
70
|
`ompYaml.ts` `mergeOmpConfig` is additive. Its `mergeMappings, deployed-key
|
|
65
71
|
retention loop` returns every deployed key that the SoT omits to the merged
|
|
66
72
|
output, and the only drop predicate is `dropFallbackWildcard`, which is scoped
|
|
67
|
-
to `retry.fallbackChains`.
|
|
73
|
+
to `retry.fallbackChains`. A key deleted from the SoT therefore stays in every
|
|
74
|
+
already-deployed `~/.omp/agent/config.yml`.
|
|
68
75
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
next sync.
|
|
76
|
+
`ompRemovals.ts OMP_RETIRED_VALUES` therefore records both values that the kit
|
|
77
|
+
shipped: the former `231200` pin and the later `-1`. Sync prunes the deployed
|
|
78
|
+
key only while it holds one of these values, so a user value survives.
|
|
73
79
|
|
|
74
80
|
Verify the deployed value after a sync:
|
|
75
81
|
|
|
@@ -77,14 +83,18 @@ Verify the deployed value after a sync:
|
|
|
77
83
|
omp config get compaction.thresholdTokens
|
|
78
84
|
```
|
|
79
85
|
|
|
80
|
-
The command must print `-1
|
|
86
|
+
The command must print `-1`, the omp default, unless the user set another
|
|
87
|
+
value.
|
|
81
88
|
|
|
82
89
|
## The clamp hazard a fixed pin carries
|
|
83
90
|
|
|
84
|
-
|
|
85
|
-
model whose window is below the pinned
|
|
86
|
-
token, so omp compacts only once the
|
|
87
|
-
|
|
91
|
+
In omp 18.4.4 through 18.8.7, the fixed-token branch clamps the pinned value
|
|
92
|
+
to `contextWindow - 1`. On any model whose window is at or below the pinned
|
|
93
|
+
value, the reserve collapses to one token, so omp compacts only once the
|
|
94
|
+
context is already full. omp 18.8.8 and later fall back to the reserve-based
|
|
95
|
+
budget for such a pin, so this collapse does not occur there. The kit floor is
|
|
96
|
+
omp 18.4.4, so a supported host can still have the clamp. The reserve-based
|
|
97
|
+
default always leaves at least 15% of the window free.
|
|
88
98
|
|
|
89
99
|
No current role model has a window below 272,000, so the hazard was latent
|
|
90
100
|
rather than live. Not pinning removes it entirely, including for any future
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -12,13 +12,12 @@ against.
|
|
|
12
12
|
| `slow` | `anthropic/claude-opus-5-5` | xhigh | 56 | $3.46 | 136.30 s |
|
|
13
13
|
| `plan` | `anthropic/claude-opus-5-5` | xhigh | 56 | $3.46 | 136.30 s |
|
|
14
14
|
| `task` | `anthropic/claude-opus-5-5` | high | 54 | $1.82 | 52.85 s |
|
|
15
|
-
| `advisor` | `anthropic/claude-opus-5-5` | medium | 51 | $1.34 | 21.87 s |
|
|
16
15
|
| `designer` | `anthropic/claude-opus-5-5` | high | 54 | $1.82 | 52.85 s |
|
|
17
16
|
| `vision` | `anthropic/claude-opus-5-5` | medium | 51 | $1.34 | 21.87 s |
|
|
18
17
|
| `smol` / `commit` | `openai-codex/gpt-6-luna` | medium | 29 | $0.02 | n/a |
|
|
19
18
|
| `tiny` | `openai-codex/gpt-6-luna` | low | 21 | $0.0045 | 2.18 s |
|
|
20
|
-
| `fable` | `anthropic/claude-fable-5-
|
|
21
|
-
| `switch_fable` | `anthropic/claude-fable-5-
|
|
19
|
+
| `fable` | `anthropic/claude-fable-5-2` | medium | 56 (v5.0.1) | $3.80 (v5.0.1) | 11.23 s (v5.0.1) |
|
|
20
|
+
| `switch_fable` | `anthropic/claude-fable-5-2` | medium | 56 (v5.0.1) | $3.80 (v5.0.1) | 11.23 s (v5.0.1) |
|
|
22
21
|
| `astra` | `openai-codex/gpt-6-astra` | xhigh | 52 | $2.31 | 126.90 s |
|
|
23
22
|
| `reviewer` | `openai-codex/gpt-6.1-terra` | high | 42 (v5.0.1) | $0.26 (v5.0.1) | 10.91 s (v5.0.1) |
|
|
24
23
|
| `web` | `web/firecrawl` | n/a | n/a | n/a | n/a |
|
|
@@ -27,10 +26,11 @@ The table reports the measured Artificial Analysis figures for each assigned
|
|
|
27
26
|
model and level. It states no motive that the config or omp's own
|
|
28
27
|
documentation does not establish. AA has not measured output speed or latency
|
|
29
28
|
for GPT-6 Luna medium, so that row carries `n/a` for TTFT. AA measures no web
|
|
30
|
-
search provider, so the `web` row carries no figures. The `reviewer`
|
|
31
|
-
from
|
|
32
|
-
predates GPT-6.1 Terra
|
|
33
|
-
GPT-6.1 Terra
|
|
29
|
+
search provider, so the `web` row carries no figures. The `reviewer`, `fable`,
|
|
30
|
+
and `switch_fable` rows come from later captures at Intelligence Index v5.0.1.
|
|
31
|
+
The 2026-09-29 capture predates GPT-6.1 Terra and Fable 5.2. Compare those
|
|
32
|
+
rows only with other v5.0.1 figures (see GPT-6.1 Terra and Claude Fable 5.2
|
|
33
|
+
below). A review benchmark chose the model of the `reviewer` role
|
|
34
34
|
(DocksDocks/public#130), not these figures. The tier of that role follows the
|
|
35
35
|
main session (DocksDocks/public#134).
|
|
36
36
|
|
|
@@ -116,7 +116,7 @@ missed two pre-registered bounds: escaped difference up to 3.26 (bound 2) and
|
|
|
116
116
|
recall difference down to -0.07 (bound -0.05). Both intervals include 0, and
|
|
117
117
|
the user judged the difference as noise.
|
|
118
118
|
|
|
119
|
-
`retry.fallbackChains.astra` holds `anthropic/claude-fable-5-
|
|
119
|
+
`retry.fallbackChains.astra` holds `anthropic/claude-fable-5-2:medium`.
|
|
120
120
|
`retry.fallbackChains.fable` holds `openai-codex/gpt-6-astra:xhigh`.
|
|
121
121
|
Each deliberate cycle stop falls to the other vendor. Without these explicit
|
|
122
122
|
chains, `retry.fallbackChains.default` would send either stop to
|
|
@@ -124,22 +124,21 @@ chains, `retry.fallbackChains.default` would send either stop to
|
|
|
124
124
|
Chain entries are concrete selectors, not role aliases, so this pair cannot
|
|
125
125
|
recurse. The hidden `switch_fable` chain stays empty.
|
|
126
126
|
|
|
127
|
-
###
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
`retry.fallbackChains.advisor`.
|
|
127
|
+
### Advisor removed
|
|
128
|
+
|
|
129
|
+
By owner decision (2026-11-12, 0.22.22), the kit sets no omp advisor.
|
|
130
|
+
`SoT/.omp/config.yml` has no `advisor` block, no `modelRoles.advisor`, and no
|
|
131
|
+
`retry.fallbackChains.advisor`. omp keeps the advisor off by default. The
|
|
132
|
+
plan-lifecycle verification loop takes its place: acceptance checks, a fresh
|
|
133
|
+
code review of the diff, and a round limit. Since 2026-11-01, 33 main
|
|
134
|
+
sessions had an advisor log, and no subagent session had one. A session that
|
|
135
|
+
runs `/advisor on` takes its advisor model from the `slow` role, because no
|
|
136
|
+
`advisor` role is set.
|
|
137
|
+
|
|
138
|
+
History: on 2026-09-24, with omp 18.3.0, an advisor on
|
|
139
|
+
`openai-codex/gpt-6-sol:medium` looped and made 1,313 requests for 140
|
|
140
|
+
main-agent requests. The kit then ran the advisor on Opus 5.5 `medium` and
|
|
141
|
+
excluded every GPT model from that role until this removal.
|
|
143
142
|
|
|
144
143
|
`modelRoles.web` is `web/firecrawl`, and `retry.fallbackChains.web` lists the
|
|
145
144
|
explicit 20-entry provider order that follows it. The two keys replace the
|
|
@@ -254,6 +253,34 @@ selector, so no kit role depends on that default. Runs on
|
|
|
254
253
|
`anthropic/claude-opus-5-5:high` and `:max` after the prune answered with
|
|
255
254
|
exit 0.
|
|
256
255
|
|
|
256
|
+
### Claude Fable 5.2 (Anthropic) - `anthropic/claude-fable-5-2`
|
|
257
|
+
|
|
258
|
+
Source: `https://artificialanalysis.ai`, read on 2026-11-12 at Intelligence
|
|
259
|
+
Index v5.0.1, from the metric table of
|
|
260
|
+
`/models/comparisons/<level-slug>-vs-gpt-5-6-sol-high`. AA serves `max` under
|
|
261
|
+
the bare model slug. These figures use another index version than the rest of
|
|
262
|
+
this snapshot, so they do not compare with the v4.3.2 rows above. Compare them
|
|
263
|
+
with GPT-6.1 Terra below.
|
|
264
|
+
|
|
265
|
+
| Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
|
|
266
|
+
|---|---:|---:|---:|---:|---:|---:|---:|
|
|
267
|
+
| max | 65 | $26.54 | 274k | 275M | 98 | 262.29 | 60% |
|
|
268
|
+
| xhigh | 62 | $14.83 | 162k | 144M | 102 | 85.87 | 62% |
|
|
269
|
+
| high | 62 | $9.08 | 98k | 85M | 97 | 27.98 | 60% |
|
|
270
|
+
| medium | 56 | $3.80 | 43k | 41M | 93 | 11.23 | 55% |
|
|
271
|
+
| low | 54 | $3.10 | 36k | 35M | 97 | 8.42 | 55% |
|
|
272
|
+
|
|
273
|
+
Price: $8.00 in, $40.00 out, $0.20 cache hit per 1M. The omp catalog lists
|
|
274
|
+
the same prices, a $10.00 cache write, a 1M context, and 128K maximum output.
|
|
275
|
+
All AA levels run with default fallback. On 2026-11-12, omp 18.19.0 listed
|
|
276
|
+
`claude-fable-5-2` at low, medium, high, xhigh, and max, and an
|
|
277
|
+
`omp -p --mode json --model anthropic/claude-fable-5-2:medium` run recorded
|
|
278
|
+
`claude-fable-5-2` as the serving model.
|
|
279
|
+
|
|
280
|
+
`fable` and `switch_fable` moved from Fable 5.1 to Fable 5.2 at the same
|
|
281
|
+
level, `medium`. The Fable 5.1 table below stays as the previous-generation
|
|
282
|
+
baseline at v4.3.2.
|
|
283
|
+
|
|
257
284
|
### Claude Fable 5.1 (Anthropic) - `anthropic/claude-fable-5-1`
|
|
258
285
|
|
|
259
286
|
| Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
|
|
@@ -346,7 +373,7 @@ has measured both at the other levels.
|
|
|
346
373
|
### GPT-5.6 Sol (OpenAI) - previous generation
|
|
347
374
|
|
|
348
375
|
The role map no longer uses GPT-5.6 Sol. This table stays as the measured
|
|
349
|
-
baseline for the
|
|
376
|
+
baseline for the GPT-6.1 Sol `task` retry fallback.
|
|
350
377
|
|
|
351
378
|
| Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
|
|
352
379
|
|---|---:|---:|---:|---:|---:|---:|---:|
|
|
@@ -442,18 +469,18 @@ quick answer.
|
|
|
442
469
|
`thinking-level: auto`. It resolves Opus 5.5 high. The `:high` suffix on
|
|
443
470
|
`modelRoles.task` is an explicit level, so it outranks the agent's `auto`,
|
|
444
471
|
and the auto classifier does not run for a `task` spawn.
|
|
445
|
-
- `task.enableEffort`
|
|
446
|
-
every spawn runs the level of its agent's role. When the
|
|
447
|
-
caller can pass `effort: lo`, `med`, or `hi`, and caller
|
|
448
|
-
role suffix. omp maps it onto the model's own ladder,
|
|
449
|
-
`lo` selects the lowest level, `med` the lower middle,
|
|
450
|
-
(`resolveTaskEffortLevel` in omp's
|
|
451
|
-
omp 18.8.5). Then omp caps the result at
|
|
452
|
-
`low, medium, high, xhigh, max` ladder, `hi` gave
|
|
453
|
-
`xhigh` cap, so many `task` spawns ran Opus 5.5 xhigh
|
|
454
|
-
role suffix. On 2026-11-05, a fresh `omp -p` run on omp
|
|
455
|
-
field off had no `effort` field, and its `task` child
|
|
456
|
-
`resolvedModel: anthropic/claude-opus-5-5:high`.
|
|
472
|
+
- `task.enableEffort` stays at omp's default `false`, so the task tool has no
|
|
473
|
+
`effort` field and every spawn runs the level of its agent's role. When the
|
|
474
|
+
field is on, a caller can pass `effort: lo`, `med`, or `hi`, and caller
|
|
475
|
+
effort outranks the role suffix. omp maps it onto the model's own ladder,
|
|
476
|
+
not onto level names: `lo` selects the lowest level, `med` the lower middle,
|
|
477
|
+
and `hi` the highest (`resolveTaskEffortLevel` in omp's
|
|
478
|
+
`packages/tui/src/thinking.ts`, omp 18.8.5). Then omp caps the result at
|
|
479
|
+
`task.maxEffort`. On the `low, medium, high, xhigh, max` ladder, `hi` gave
|
|
480
|
+
`xhigh` under the `xhigh` cap, so many `task` spawns ran Opus 5.5 xhigh
|
|
481
|
+
despite the `:high` role suffix. On 2026-11-05, a fresh `omp -p` run on omp
|
|
482
|
+
18.16.0 with the field off had no `effort` field, and its `task` child
|
|
483
|
+
recorded `resolvedModel: anthropic/claude-opus-5-5:high`.
|
|
457
484
|
- `task.maxEffort` is `xhigh`. With `task.enableEffort` off, the cap applies
|
|
458
485
|
only to a per-call `model` with a `:level` suffix.
|
|
459
486
|
- In the deployed config, `scout` and `sonic` run GPT-6 Luna `medium`. The
|
|
@@ -475,10 +502,13 @@ AA's 1M.
|
|
|
475
502
|
`docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive
|
|
476
503
|
omp session with a configuration overlay that selects a free model. The
|
|
477
504
|
overlay sets the 16 chat-model roles in `ompOverlay.ts ROLE_ORDER` to that
|
|
478
|
-
model and empties the
|
|
479
|
-
FALLBACK_ORDER`. These roles include `memory` and `
|
|
480
|
-
not set them, but omp otherwise uses its built-in priority chain for
|
|
481
|
-
and that chain can name a paid model.
|
|
505
|
+
model and empties the 12 retry fallback chains in `ompOverlay.ts
|
|
506
|
+
FALLBACK_ORDER`. These roles include `memory`, `judge`, and `advisor`. The SoT
|
|
507
|
+
does not set them, but omp otherwise uses its built-in priority chain for
|
|
508
|
+
`memory` and `judge`, and that chain can name a paid model. omp resolves the
|
|
509
|
+
`/advisor on` model from `modelRoles.advisor` before the `slow` role. A
|
|
510
|
+
deployed, user, or project `advisor` role could otherwise send it to a paid
|
|
511
|
+
model. The overlay also empties the retry
|
|
482
512
|
chains keyed by the free model: the bare selector, `<selector>:off`, and
|
|
483
513
|
`<selector>:<level>` for every level in `ompOverlay.ts THINKING_LADDER`. omp
|
|
484
514
|
uses a chain keyed by the model before a role chain, so a project or
|
|
@@ -491,16 +521,16 @@ stays in the merged config. A retry of the free model does not reach such a
|
|
|
491
521
|
chain, because omp uses the empty chain keyed by the free model first.
|
|
492
522
|
The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
|
|
493
523
|
a model that publishes no thinking ladder, where both keys are omitted and the
|
|
494
|
-
deployed values apply.
|
|
524
|
+
deployed or omp default values apply.
|
|
495
525
|
|
|
496
526
|
The launcher renders a run overlay to
|
|
497
527
|
`~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
|
|
498
528
|
through omp's repeatable `--config` flag. Each distinct model-and-level
|
|
499
529
|
combination gets its own file, because omp re-reads a changed overlay during
|
|
500
|
-
a live session, and a second launcher must not change the
|
|
530
|
+
a live session, and a second launcher must not change the level of that
|
|
501
531
|
session. The name sanitizes the selector for the file system and appends a
|
|
502
|
-
digest of the rendered overlay. The digest covers the selector and
|
|
503
|
-
|
|
532
|
+
digest of the rendered overlay. The digest covers the selector and the
|
|
533
|
+
level, so two selectors that differ only in separator characters stay
|
|
504
534
|
apart. A session launch never reads or writes `~/.omp/agent/config.yml` or
|
|
505
535
|
`models.yml`; only `--fast`, below, edits `config.yml`. It
|
|
506
536
|
never touches the SoT. The next plain `omp` run uses the paid configuration
|
|
@@ -576,11 +606,9 @@ Spark 1.3 Free", 1,048,576-token context) at `xhigh`. `xhigh` is the ceiling
|
|
|
576
606
|
of that model ladder: `minimal, low, medium, high, xhigh`. The paid
|
|
577
607
|
`muse-spark-1.3` sibling also offers `max`. The free variant does not.
|
|
578
608
|
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
review passes. When every level of a ladder is above `medium`, the advisor
|
|
583
|
-
takes the lowest level, so it never becomes the most expensive role.
|
|
609
|
+
The level comes from the ladder of the chosen model, never from a fixed list.
|
|
610
|
+
Every role, `advisor` included, runs the same level. Under `--model`, that
|
|
611
|
+
level is the ceiling of the ladder.
|
|
584
612
|
|
|
585
613
|
Free ladders are not uniform. On 2026-09-11 the 26 free models published six
|
|
586
614
|
distinct ladders: 21 include `medium`, 3 stop at `low, high, max` or
|
|
@@ -590,7 +618,7 @@ fail when the session starts.
|
|
|
590
618
|
|
|
591
619
|
The choice persists per machine in `~/.docks-kit/kit.db` (table
|
|
592
620
|
`omp_session`), next to the harness selection. It survives across sessions. It is never
|
|
593
|
-
committed. `--model <selector>` records one selector and derives
|
|
621
|
+
committed. `--model <selector>` records one selector and derives the level
|
|
594
622
|
from the catalog row. `--pick` opens an interactive wizard.
|
|
595
623
|
|
|
596
624
|
The picker lists only models the live `omp models --json` catalog reports at
|
|
@@ -598,31 +626,24 @@ zero input and output cost with `pricingStatus` `free` or `unknown` (26
|
|
|
598
626
|
entries on 2026-09-11). A zero-cost row with another status, such as
|
|
599
627
|
`variable` or `included`, is billed outside the token price, so the picker
|
|
600
628
|
leaves it out. The resulting overlay sets the 16 `ROLE_ORDER` roles to the
|
|
601
|
-
chosen free model and empties the
|
|
629
|
+
chosen free model and empties the 12 `FALLBACK_ORDER` chains and the chains
|
|
602
630
|
keyed by that model. The `web` role, its chain, and each other deployed chain
|
|
603
631
|
keep the deployed values. The
|
|
604
632
|
catalog can advertise a free model that the account cannot call; omp reports
|
|
605
633
|
that provider error unchanged.
|
|
606
634
|
|
|
607
|
-
After the model, the wizard asks about thinking
|
|
608
|
-
planEffortChoice` decides
|
|
635
|
+
After the model, the wizard asks about the thinking level. `ompOverlay.ts
|
|
636
|
+
planEffortChoice` decides whether the question applies, because omp accepts a
|
|
609
637
|
`:level` suffix only for a level the chosen model publishes:
|
|
610
638
|
|
|
611
639
|
- No ladder: the wizard asks nothing and the overlay omits every level.
|
|
612
640
|
- One level: the wizard states that level and asks nothing.
|
|
613
|
-
- Two or more levels: the wizard asks
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
The advisor question leads with a recommendation from `ompOverlay.ts
|
|
618
|
-
advisorRecommendation`: two steps down the model own ladder, clamped to the
|
|
619
|
-
lowest level that model publishes. The recommendation is the first row
|
|
620
|
-
because `Prompt.Select` starts on the first entry and accepts no initial
|
|
621
|
-
index, so `Enter` takes it. The full ladder follows in ladder order. A
|
|
622
|
-
recommendation equal to the chosen level is omitted rather than duplicated.
|
|
641
|
+
- Two or more levels: the wizard asks one question, the thinking level for
|
|
642
|
+
every role. It lists the levels of the model from the highest down, so
|
|
643
|
+
`Enter` keeps the highest level.
|
|
623
644
|
|
|
624
|
-
|
|
625
|
-
|
|
645
|
+
The launch line names the selector and the level, or the model default level
|
|
646
|
+
for a model without a ladder. It reports no separate advisor level.
|
|
626
647
|
|
|
627
648
|
An omp login is required. The kit owns no login flow. Every launch reads the
|
|
628
649
|
live free catalog of each candidate profile. A plain launch checks the
|
|
@@ -647,9 +668,9 @@ stops the launcher before omp starts.
|
|
|
647
668
|
|
|
648
669
|
When the catalog renames the free variant, change only the default selector
|
|
649
670
|
constant. Until then, a plain launch on that default stops with an error. A
|
|
650
|
-
ladder change needs no code change. Under `--model`
|
|
671
|
+
ladder change needs no code change. Under `--model` the level is derived
|
|
651
672
|
from the catalog row of the chosen model, and under `--pick` the user chooses
|
|
652
|
-
|
|
673
|
+
it from the ladder that same row publishes. Refresh the recorded default
|
|
653
674
|
and the ladder counts in these docs in the same commit.
|
|
654
675
|
|
|
655
676
|
## OpenAI fast mode (`docks-kit omp --fast`)
|
|
@@ -670,8 +691,8 @@ The four review agents inherit the live tier of the main session
|
|
|
670
691
|
and on standard processing when it is `none`. A running session keeps the tier
|
|
671
692
|
it started with, so its reviewers do not follow a later toggle.
|
|
672
693
|
|
|
673
|
-
`--fast` never changes the Anthropic tier
|
|
674
|
-
|
|
694
|
+
`--fast` never changes the Anthropic tier. The SoT leaves `tier.anthropic` at
|
|
695
|
+
omp's default `none`, so each session starts with it. In omp
|
|
675
696
|
18.16.0, `/fast on` in a session whose current
|
|
676
697
|
model is Anthropic sets `anthropic: priority` for that session. The reviewers
|
|
677
698
|
then inherit it, so their Opus 5.5 fallback also runs fast. omp has no
|
package/cli/docs/overview.md
CHANGED
|
@@ -12,7 +12,7 @@ AI-assisted dev environment on every machine.
|
|
|
12
12
|
| `SoT/.claude/` | Claude Code config (settings template, Bun runtime programs, CLAUDE.md) |
|
|
13
13
|
| `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
|
|
14
14
|
| `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
|
|
15
|
-
| `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom |
|
|
15
|
+
| `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom, plus the `plugin/` tree, deployed to `~/.docks-kit/omp-plugin` and linked as the `docks-kit-omp` omp plugin |
|
|
16
16
|
| `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (see `docks-kit docs models`) |
|
|
17
17
|
| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
|
|
18
18
|
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
|
package/cli/docs/platforms.md
CHANGED
|
@@ -18,5 +18,7 @@ Rosetta reports `x86_64` and gets the unsupported-host message, so run
|
|
|
18
18
|
docks-kit from a native arm64 shell.
|
|
19
19
|
|
|
20
20
|
EngineNative is the only supported engine on supported hosts.
|
|
21
|
-
`DOCKS_KIT_ENGINE=bash`
|
|
22
|
-
`
|
|
21
|
+
When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync`,
|
|
22
|
+
`model`, `toolchain`, `status`) exit 2 with the removed-engine message. The
|
|
23
|
+
message points at the `bash-engine-final` tag for historical recovery. Other
|
|
24
|
+
commands ignore the variable.
|
package/cli/docs/plugins.md
CHANGED
|
@@ -38,11 +38,14 @@ A marketplace or plugin command that exits non-zero is warned in place AND
|
|
|
38
38
|
recorded, then listed under a `--- Failures ---` block after the summary; the
|
|
39
39
|
sync exits 1. A stale plugin therefore no longer looks like a clean sync.
|
|
40
40
|
|
|
41
|
-
Not a failure: a missing harness CLI, missing git, and a missing
|
|
42
|
-
`SoT/toolchain.json
|
|
43
|
-
without Claude, Codex, or omp installed still syncs its deployed
|
|
44
|
-
cleanly.
|
|
45
|
-
|
|
41
|
+
Not a failure: a missing harness CLI, missing git, and a missing LSP, Bun, or
|
|
42
|
+
`pi-intercom` pin in `SoT/toolchain.json`. Those stay warn-and-skip with exit
|
|
43
|
+
0, so a host without Claude, Codex, or omp installed still syncs its deployed
|
|
44
|
+
config cleanly. A missing `skills-cli` pin is different: when `npx` is
|
|
45
|
+
available and `SoT/.agents/skills.txt` names a skill that is not installed yet,
|
|
46
|
+
the agents sync stops with exit 1, in a dry run too. An unavailable plugin
|
|
47
|
+
inventory warns without a ledger row and falls back to the full refresh, whose
|
|
48
|
+
failed commands are recorded.
|
|
46
49
|
|
|
47
50
|
## Optional opt-ins
|
|
48
51
|
|
package/cli/docs/sync-layers.md
CHANGED
|
@@ -70,8 +70,8 @@ the retired kit `bash.patterns` rules in `OMP_RETIRED_BASH_RULES` (exact
|
|
|
70
70
|
`match` and `approval` pairs, including the 492 former kit prompt rules
|
|
71
71
|
retired in 0.22.8), config.yml keys whose deployed value still equals the value the kit used to
|
|
72
72
|
ship, `providers.webSearchOrder` at any value, and the retired
|
|
73
|
-
`anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
|
|
74
|
-
matches the shipped block.
|
|
73
|
+
`providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
|
|
74
|
+
it still matches the shipped block.
|
|
75
75
|
Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
|
|
76
76
|
registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
|
|
77
77
|
through `omp plugin`, and `pi-intercom` is installed at its
|
|
@@ -159,8 +159,10 @@ directory is `<config root>/agent`, where the config root is
|
|
|
159
159
|
directory never moves under XDG. Only the data root that holds
|
|
160
160
|
`marketplaces.json` does: on Linux and macOS, with no agent-dir override
|
|
161
161
|
active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
|
|
162
|
-
for a named profile) is adopted.
|
|
163
|
-
|
|
162
|
+
for a named profile) is adopted. Under a named profile, the intercom file goes
|
|
163
|
+
into `<agent directory>/intercom`. Otherwise it goes into
|
|
164
|
+
`$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
|
|
165
|
+
`~/.pi/agent/intercom`.
|
|
164
166
|
|
|
165
167
|
## Reconcile flags
|
|
166
168
|
|