docks-kit 0.22.12 → 0.22.20
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 +95 -81
- package/README.md +7 -7
- package/cli/docs/command-guards.md +7 -3
- package/cli/docs/flags.md +59 -9
- package/cli/docs/install.md +2 -2
- package/cli/docs/omp-context.md +14 -8
- package/cli/docs/omp-models.md +1 -1
- 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 +29 -15
- 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 +56 -15
- 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/index.ts +1 -1
- 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/ompPlugins.ts +39 -18
- package/cli/src/engine-native/ompRemovals.ts +51 -23
- package/cli/src/engine-native/ompSync.ts +78 -38
- 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/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
|
@@ -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
|
|
@@ -81,10 +84,13 @@ The command must print `-1`.
|
|
|
81
84
|
|
|
82
85
|
## The clamp hazard a fixed pin carries
|
|
83
86
|
|
|
84
|
-
|
|
85
|
-
model whose window is below the pinned
|
|
86
|
-
token, so omp compacts only once the
|
|
87
|
-
|
|
87
|
+
In omp 18.4.4 through 18.8.7, the fixed-token branch clamps the pinned value
|
|
88
|
+
to `contextWindow - 1`. On any model whose window is at or below the pinned
|
|
89
|
+
value, the reserve collapses to one token, so omp compacts only once the
|
|
90
|
+
context is already full. omp 18.8.8 and later fall back to the reserve-based
|
|
91
|
+
budget for such a pin, so this collapse does not occur there. The kit floor is
|
|
92
|
+
omp 18.4.4, so a supported host can still have the clamp. The reserve-based
|
|
93
|
+
default always leaves at least 15% of the window free.
|
|
88
94
|
|
|
89
95
|
No current role model has a window below 272,000, so the hazard was latent
|
|
90
96
|
rather than live. Not pinning removes it entirely, including for any future
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -346,7 +346,7 @@ has measured both at the other levels.
|
|
|
346
346
|
### GPT-5.6 Sol (OpenAI) - previous generation
|
|
347
347
|
|
|
348
348
|
The role map no longer uses GPT-5.6 Sol. This table stays as the measured
|
|
349
|
-
baseline for the
|
|
349
|
+
baseline for the GPT-6.1 Sol `task` retry fallback.
|
|
350
350
|
|
|
351
351
|
| Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
|
|
352
352
|
|---|---:|---:|---:|---:|---:|---:|---:|
|
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
|
|
@@ -84,13 +84,22 @@ config-root registry lists `docks`, omp copies it forward itself: the sync runs
|
|
|
84
84
|
plugin operation, the sync reads the inventory again and prints one line that
|
|
85
85
|
names each plugin with its version change, for example
|
|
86
86
|
`omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
|
|
87
|
+
|
|
87
88
|
omp deletes the previous plugin folder on `omp plugin upgrade`. A running omp
|
|
88
|
-
session then loses the plugin agents
|
|
89
|
-
|
|
90
|
-
for
|
|
91
|
-
|
|
89
|
+
session then loses the plugin agents of that folder. A test on omp 18.16.0
|
|
90
|
+
showed that `/reload-plugins` brings the agents back, and that `skill://`
|
|
91
|
+
resolves to the new folder (#139). The omp marketplace docs still ask for a
|
|
92
|
+
restart for hooks, extension modules, and non-MCP tools. For each marketplace
|
|
93
|
+
upgrade that changed the version, the sync prints a warning, for example
|
|
94
|
+
`omp plugin docks@docks 0.21.1 -> 0.22.0: running omp sessions lose its plugin agents until they run /reload-plugins and read its skills again through skill:// (restart omp instead when the plugin ships hooks, extension modules, or non-MCP tools).`
|
|
92
95
|
The next step then says
|
|
93
|
-
`
|
|
96
|
+
`Run /reload-plugins in each running omp session, then read each plugin skill again through skill://. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools.`
|
|
97
|
+
A version-changing upgrade does not set the restart trigger. Each other plugin
|
|
98
|
+
operation sets it: an install, a reinstall at the same version, an npm install,
|
|
99
|
+
or a link. A changed kit plugin file or omp config file also sets it. The
|
|
100
|
+
restart next step `Restart omp to load any refreshed plugins, skills, or tools.`
|
|
101
|
+
then prints next to the upgrade rule.
|
|
102
|
+
|
|
94
103
|
The sync also writes one event file for each such upgrade into the upgrade log
|
|
95
104
|
`~/.cache/docks-kit/omp-plugin-upgrades/` (folder 0700, files 0600). The file
|
|
96
105
|
name is `<finishedAt ms>-<random>.json`, and the file holds
|
|
@@ -108,8 +117,8 @@ the warning and an event with the after version `unknown`, for example
|
|
|
108
117
|
|
|
109
118
|
A failed write or prune of the upgrade log does not fail the sync, because it
|
|
110
119
|
is not a harness CLI operation. A failed write warns
|
|
111
|
-
`omp plugin upgrade log not written: <error> — running omp sessions get no reminder for these upgrades
|
|
112
|
-
The summary line, the upgrade warnings, and the next
|
|
120
|
+
`omp plugin upgrade log not written: <error> — running omp sessions get no reminder for these upgrades; give each of them the advice above`.
|
|
121
|
+
The summary line, the upgrade warnings, and the next steps stay. A failed prune
|
|
113
122
|
keeps the new events and warns
|
|
114
123
|
`omp plugin upgrade log not pruned: <error> — it can keep more than 100 event files`.
|
|
115
124
|
|
|
@@ -117,9 +126,12 @@ The kit plugin extension `pluginUpgrades.ts` reads the upgrade log. In each
|
|
|
117
126
|
tool result of a main omp session, it takes the events that finished after
|
|
118
127
|
its omp process started. It adds one reminder for the events that the session
|
|
119
128
|
did not get before. The reminder names each plugin with its version change. It
|
|
120
|
-
says that the
|
|
121
|
-
|
|
122
|
-
|
|
129
|
+
says that the plugin agents of the session may fail. It tells the agent to ask
|
|
130
|
+
the user to run `/reload-plugins`. It then tells the agent to read each plugin
|
|
131
|
+
skill again through `skill://` before it runs a skill script. It asks for a
|
|
132
|
+
restart instead when an upgraded plugin ships hooks, extension modules, or
|
|
133
|
+
non-MCP tools. A folder or file that the extension cannot read gives no
|
|
134
|
+
reminder for that tool result. The next tool result reads it again.
|
|
123
135
|
These limits apply:
|
|
124
136
|
|
|
125
137
|
- omp imports extension modules only at startup. An omp process that started
|
|
@@ -132,7 +144,7 @@ These limits apply:
|
|
|
132
144
|
registry still uses. So a session on a project-scope install keeps its
|
|
133
145
|
folder. For this reason, the reminder says "may".
|
|
134
146
|
- An omp process that started during the upgrade can get a reminder that it
|
|
135
|
-
does not need. A restart is harmless.
|
|
147
|
+
does not need. A reload or a restart is harmless.
|
|
136
148
|
- The log keeps the newest 100 events. A session that stays idle through more
|
|
137
149
|
than 100 later upgrades loses the oldest ones.
|
|
138
150
|
|
|
@@ -147,8 +159,10 @@ directory is `<config root>/agent`, where the config root is
|
|
|
147
159
|
directory never moves under XDG. Only the data root that holds
|
|
148
160
|
`marketplaces.json` does: on Linux and macOS, with no agent-dir override
|
|
149
161
|
active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
|
|
150
|
-
for a named profile) is adopted.
|
|
151
|
-
|
|
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`.
|
|
152
166
|
|
|
153
167
|
## Reconcile flags
|
|
154
168
|
|
package/cli/docs/toolchain.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
| Field | Meaning |
|
|
6
6
|
|-------|---------|
|
|
7
|
-
| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for
|
|
7
|
+
| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool: `npx` for `skills-cli`, `omp install` for `pi-intercom`; the optional `via` field names that tool in the doctor table, and the default is `npx`) |
|
|
8
8
|
| `policy` | Installation policy; `present` installs when missing and never upgrades |
|
|
9
9
|
| `floor` | Minimum acceptable version shown in the doctor table |
|
|
10
10
|
| `verified` | Last kit-tested version and the exact pin for kit-driven installs |
|
|
@@ -37,8 +37,10 @@ server as an npm global for the `typescript-lsp` plugin, so an older Node runs
|
|
|
37
37
|
a server its own manifest rejects. `docks-kit toolchain check` prints
|
|
38
38
|
`below-floor` for a Node older than 22.22.2. The sync pass reads the same
|
|
39
39
|
floor: it skips the `typescript-language-server` install on such a host, warns
|
|
40
|
-
with the host Node version, and installs the other language servers.
|
|
41
|
-
|
|
40
|
+
with the host Node version, and installs the other language servers.
|
|
41
|
+
`docks-kit toolchain upgrade` also reads the floor: it skips the
|
|
42
|
+
`typescript-language-server` upgrade on such a host and warns. Nothing else
|
|
43
|
+
consults the floor, so a host below it still runs every other kit operation.
|
|
42
44
|
|
|
43
45
|
## rust-analyzer: no floor, no pin
|
|
44
46
|
|
|
@@ -62,8 +64,9 @@ the component is not installed. When `rust-analyzer --version` does not answer
|
|
|
62
64
|
within 60 s, sync warns, stops the probe, and does not add the component on that
|
|
63
65
|
run. `rustup update` is the user's remedy for an old component.
|
|
64
66
|
|
|
65
|
-
A
|
|
66
|
-
|
|
67
|
+
A server below its `floor` shows as `below-floor` in `docks-kit toolchain check`.
|
|
68
|
+
A server at or above its floor but below its `verified` pin shows as `ok`.
|
|
69
|
+
To move every npm server that is below its `verified` pin to that pin, run:
|
|
67
70
|
|
|
68
71
|
```bash
|
|
69
72
|
docks-kit toolchain upgrade --dry-run # print the npm command
|
|
@@ -72,8 +75,9 @@ docks-kit toolchain upgrade # run it
|
|
|
72
75
|
|
|
73
76
|
`toolchain upgrade` (`claudeLsp.ts upgradeLspServers`) reads `npm ls -g` to see
|
|
74
77
|
which of `intelephense`, `typescript-language-server`, and `typescript` npm
|
|
75
|
-
owns. It runs one `npm install -g
|
|
76
|
-
below its pin
|
|
78
|
+
owns. It runs one `npm install -g` command that names every npm-owned package
|
|
79
|
+
below its pin as `<pkg>@<verified>`. A package already at or above its pin
|
|
80
|
+
stays as it is. It leaves
|
|
77
81
|
these alone and warns:
|
|
78
82
|
|
|
79
83
|
- A binary on PATH that npm does not own. It came from another installer, so
|
|
@@ -92,13 +96,19 @@ package is not at its pin.
|
|
|
92
96
|
|
|
93
97
|
## Supply-chain stance
|
|
94
98
|
|
|
95
|
-
Every kit-driven install
|
|
96
|
-
`SoT/toolchain.json` `verified` version — never
|
|
97
|
-
npm-worm / Shai-Hulud attack surface). That includes
|
|
98
|
-
`npx skills@<verified>` invocations on agents sync and the release workflow
|
|
99
|
-
(actions pinned to commit SHAs, exact bun/npm versions).
|
|
100
|
-
|
|
101
|
-
|
|
99
|
+
Every kit-driven package install from npm, npx, GitHub releases, or
|
|
100
|
+
`omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
|
|
101
|
+
floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
|
|
102
|
+
the `npx skills@<verified>` invocations on agents sync and the release workflow
|
|
103
|
+
(actions pinned to commit SHAs, exact bun/npm versions). Two installs follow
|
|
104
|
+
the host toolchain and have no pin: `rust-analyzer` (rustup) and `bubblewrap`
|
|
105
|
+
(distro package manager). The existing Claude Code, Codex, and omp marketplace
|
|
106
|
+
plugins have no manifest pin either: sync installs and refreshes them at the
|
|
107
|
+
version that their marketplace publishes (see `plugins`). Any new install
|
|
108
|
+
surface, a new marketplace or plugin source included, needs a manifest pin
|
|
109
|
+
first.
|
|
110
|
+
|
|
111
|
+
The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
|
|
102
112
|
end with `bun add -g docks-kit@latest` because a global installer that pinned
|
|
103
113
|
itself would install a fixed old kit forever. The exemption covers `docks-kit`
|
|
104
114
|
alone; both installers still pin the Bun installer they download to the
|
package/cli/src/argv.ts
CHANGED
|
@@ -19,7 +19,6 @@ import {
|
|
|
19
19
|
spliceOmpBoundary,
|
|
20
20
|
subcommandName as scanSubcommandName,
|
|
21
21
|
type ArgvSurfaces,
|
|
22
|
-
type CommandValue,
|
|
23
22
|
} from "./argvSurface";
|
|
24
23
|
import { validateScannedArgv } from "./argvValidate";
|
|
25
24
|
|
|
@@ -27,13 +26,17 @@ export type ArgvOutcome =
|
|
|
27
26
|
| { readonly kind: "reject"; readonly message: string; readonly exitCode: number }
|
|
28
27
|
| { readonly kind: "accept"; readonly args: ReadonlyArray<string> };
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
/**
|
|
30
|
+
* The one subcommand list. `main.ts` registers it with Effect, and the argv
|
|
31
|
+
* surfaces below accept the same words. The order is the `--help` order.
|
|
32
|
+
*/
|
|
33
|
+
export const COMMANDS = [
|
|
31
34
|
syncCommand,
|
|
32
35
|
harnessesCommand,
|
|
33
36
|
updateCommand,
|
|
34
37
|
modelCommand,
|
|
35
|
-
toolchainCommand,
|
|
36
38
|
modelsCommand,
|
|
39
|
+
toolchainCommand,
|
|
37
40
|
statusCommand,
|
|
38
41
|
pluginsCommand,
|
|
39
42
|
skillsCommand,
|
|
@@ -41,7 +44,7 @@ const COMMANDS: ReadonlyArray<CommandValue> = [
|
|
|
41
44
|
ompCommand,
|
|
42
45
|
scratchCommand,
|
|
43
46
|
tidyCommand,
|
|
44
|
-
];
|
|
47
|
+
] as const;
|
|
45
48
|
|
|
46
49
|
const SURFACES: ArgvSurfaces = buildSurfaces(COMMANDS, GlobalFlag.BuiltIns);
|
|
47
50
|
|
package/cli/src/argvValidate.ts
CHANGED
|
@@ -6,25 +6,12 @@
|
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
8
|
import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseModifiers";
|
|
9
|
+
import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
|
|
9
10
|
import { modelCatalog } from "./engine-native/models";
|
|
10
11
|
import { advisorCatalog, advisorFlagGrammar, effortCatalog, effortFlagGrammar } from "./efforts";
|
|
11
12
|
import type { Tool } from "./manifests";
|
|
12
13
|
import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
|
|
13
14
|
|
|
14
|
-
const LEGACY_HINTS: Readonly<Record<string, string>> = {
|
|
15
|
-
"--force": "--force was renamed to --reconcile",
|
|
16
|
-
"--remove-plugins":
|
|
17
|
-
"--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
|
|
18
|
-
"--680k": "--680k was renamed to --claude-compact-window=680k",
|
|
19
|
-
"--permissive": "--permissive was renamed to --claude-permissive",
|
|
20
|
-
"--supabase": "--supabase was renamed to --claude-plugin=supabase",
|
|
21
|
-
"--n8n": "--n8n was renamed to --claude-plugin=n8n",
|
|
22
|
-
"--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
|
|
23
|
-
"--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
|
|
24
|
-
"--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
|
|
25
|
-
"--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'",
|
|
26
|
-
};
|
|
27
|
-
|
|
28
15
|
const modelCatalogHint = (tool: Tool): string => {
|
|
29
16
|
const catalog = modelCatalog(tool);
|
|
30
17
|
const list = catalog.models
|
|
@@ -76,8 +63,7 @@ export const validateScannedArgv = (
|
|
|
76
63
|
|
|
77
64
|
if (subcommand === "sync") {
|
|
78
65
|
for (const flag of flags) {
|
|
79
|
-
|
|
80
|
-
if (hint !== undefined) return hint;
|
|
66
|
+
if (isLegacyFlag(flag.name)) return LEGACY_FLAG_HINTS[flag.name];
|
|
81
67
|
}
|
|
82
68
|
}
|
|
83
69
|
|
package/cli/src/commands/docs.ts
CHANGED
|
@@ -17,7 +17,7 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
|
|
|
17
17
|
const TOPICS: Record<string, { summary: string; body: string }> = {
|
|
18
18
|
overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
|
|
19
19
|
"sync-layers": {
|
|
20
|
-
summary: "The
|
|
20
|
+
summary: "The four sync targets (claude, codex, agents, omp) and additive-by-default semantics",
|
|
21
21
|
body: syncLayers,
|
|
22
22
|
},
|
|
23
23
|
flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
|
package/cli/src/commands/omp.ts
CHANGED
|
@@ -23,8 +23,15 @@ import {
|
|
|
23
23
|
renderFreeOverlay,
|
|
24
24
|
type CatalogModel,
|
|
25
25
|
} from "../engine-native/ompOverlay";
|
|
26
|
-
import {
|
|
26
|
+
import {
|
|
27
|
+
FAST_ON_TIER,
|
|
28
|
+
requireDeployedConfig,
|
|
29
|
+
toggleDeployedOpenAiFast,
|
|
30
|
+
type FastToggle,
|
|
31
|
+
} from "../engine-native/ompFastMode";
|
|
27
32
|
import { ompPaths } from "../engine-native/ompPaths";
|
|
33
|
+
import { ExitError } from "../engine-native/parseArgs";
|
|
34
|
+
import { withHomeAndFolderLocks } from "../engine-native/syncDispatch";
|
|
28
35
|
|
|
29
36
|
const model = Flag.String("model").pipe(
|
|
30
37
|
Flag.withDescription("Free model selector to use and remember for omp sessions"),
|
|
@@ -251,6 +258,49 @@ const pickLevels = (catalogModel: CatalogModel) =>
|
|
|
251
258
|
return { thinking, advisorThinking };
|
|
252
259
|
});
|
|
253
260
|
|
|
261
|
+
/**
|
|
262
|
+
* Toggle fast mode under the sync lock of `home` and the folder lock of the
|
|
263
|
+
* omp agent folder, with the wait and the held line of a sync. A sync also
|
|
264
|
+
* merges `config.yml` there. Return 0 after the toggle, 1 for a held lock,
|
|
265
|
+
* and 2 for a failed toggle or an invalid wait bound.
|
|
266
|
+
*/
|
|
267
|
+
async function toggleFastUnderLocks(home: string, agentDir: string): Promise<number> {
|
|
268
|
+
const configPath = p(agentDir, "config.yml");
|
|
269
|
+
const err = (line: string) => console.error(line);
|
|
270
|
+
// Check config.yml before any lock. A missing file ends the run before the
|
|
271
|
+
// lock step can create the agent folder, and a folder that a sync creates
|
|
272
|
+
// during the home lock wait is never toggled without its folder lock.
|
|
273
|
+
try {
|
|
274
|
+
requireDeployedConfig(configPath);
|
|
275
|
+
} catch (error) {
|
|
276
|
+
err(error instanceof Error ? error.message : String(error));
|
|
277
|
+
return 2;
|
|
278
|
+
}
|
|
279
|
+
try {
|
|
280
|
+
return await withHomeAndFolderLocks(home, [agentDir], err, async () => {
|
|
281
|
+
let toggle: FastToggle;
|
|
282
|
+
try {
|
|
283
|
+
toggle = toggleDeployedOpenAiFast(configPath);
|
|
284
|
+
} catch (error) {
|
|
285
|
+
err(error instanceof Error ? error.message : String(error));
|
|
286
|
+
return 2;
|
|
287
|
+
}
|
|
288
|
+
const state = toggle.next === FAST_ON_TIER ? "ON" : "OFF";
|
|
289
|
+
console.log(
|
|
290
|
+
`omp fast mode ${state} for OpenAI/Codex models: tier.openai ${toggle.previous} -> ${toggle.next} in ${configPath}`,
|
|
291
|
+
);
|
|
292
|
+
console.log(
|
|
293
|
+
"New omp sessions use it; in a running session, use /fast on|off or restart omp.",
|
|
294
|
+
);
|
|
295
|
+
return 0;
|
|
296
|
+
});
|
|
297
|
+
} catch (error) {
|
|
298
|
+
// An invalid DOCKS_KIT_SYNC_LOCK_WAIT_MS prints its error line, then throws ExitError(2).
|
|
299
|
+
if (error instanceof ExitError) return error.code;
|
|
300
|
+
throw error;
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
|
|
254
304
|
export const ompCommand = Command.make("omp", { model, pick, fast, args }, (config) =>
|
|
255
305
|
Effect.gen(function* () {
|
|
256
306
|
// Check the forwarded arguments before omp, the catalog, or kit.db, so a
|
|
@@ -266,22 +316,13 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
|
|
|
266
316
|
if (Option.isSome(config.model) || config.pick || config.args.length > 0) {
|
|
267
317
|
return yield* bail("--fast toggles fast mode and exits; pass it alone");
|
|
268
318
|
}
|
|
269
|
-
const
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
);
|
|
274
|
-
const toggle = yield* Effect.try({
|
|
275
|
-
try: () => toggleDeployedOpenAiFast(configPath),
|
|
319
|
+
const home = engineHome(process.env);
|
|
320
|
+
const agentDir = ompPaths({ home, env: process.env, platform: process.platform }).agentDir;
|
|
321
|
+
const code = yield* Effect.tryPromise({
|
|
322
|
+
try: () => toggleFastUnderLocks(home, agentDir),
|
|
276
323
|
catch: (error) => (error instanceof Error ? error.message : String(error)),
|
|
277
324
|
}).pipe(Effect.catch((message) => bail(message)));
|
|
278
|
-
|
|
279
|
-
yield* Console.log(
|
|
280
|
-
`omp fast mode ${state} for OpenAI/Codex models: tier.openai ${toggle.previous} -> ${toggle.next} in ${configPath}`,
|
|
281
|
-
);
|
|
282
|
-
yield* Console.log(
|
|
283
|
-
"New omp sessions use it; in a running session, use /fast on|off or restart omp.",
|
|
284
|
-
);
|
|
325
|
+
if (code !== 0) return yield* Effect.sync(() => process.exit(code));
|
|
285
326
|
return;
|
|
286
327
|
}
|
|
287
328
|
|
package/cli/src/commands/sync.ts
CHANGED
|
@@ -1,27 +1,27 @@
|
|
|
1
1
|
import { Argument, Command, Flag } from "effect/cli";
|
|
2
2
|
import { Effect, Option } from "effect";
|
|
3
|
-
import { spawnSync } from "node:child_process";
|
|
4
3
|
import { existsSync } from "node:fs";
|
|
5
4
|
import { join } from "node:path";
|
|
6
5
|
import { bail, engine } from "../engine";
|
|
6
|
+
import { spawnHost } from "../engine-native/exec";
|
|
7
7
|
import type { Logger } from "../engine-native/logger";
|
|
8
8
|
import { kitHome } from "../kitHome";
|
|
9
9
|
import { LoggerService } from "../services";
|
|
10
10
|
|
|
11
11
|
/** Best-effort update autodetection: nudge (never block, never fail) when
|
|
12
12
|
* the kit checkout is behind its upstream. Silent on detached HEADs, no
|
|
13
|
-
* upstream, no network, no git.
|
|
14
|
-
|
|
13
|
+
* upstream, no network, no git. git starts through spawnHost, so a Windows
|
|
14
|
+
* host never runs a `git.exe` from the current directory. */
|
|
15
|
+
export const updateNudge = (logger: Logger): void => {
|
|
15
16
|
try {
|
|
16
17
|
const home = kitHome();
|
|
17
18
|
if (!existsSync(join(home, ".git"))) return;
|
|
18
19
|
if (
|
|
19
|
-
|
|
20
|
+
spawnHost("git", ["-C", home, "fetch", "--quiet"], { stdio: "ignore", timeout: 4000 })
|
|
20
21
|
.status !== 0
|
|
21
22
|
)
|
|
22
23
|
return;
|
|
23
|
-
const res =
|
|
24
|
-
encoding: "utf8",
|
|
24
|
+
const res = spawnHost("git", ["-C", home, "rev-list", "--count", "HEAD..@{u}"], {
|
|
25
25
|
stdio: ["ignore", "pipe", "ignore"],
|
|
26
26
|
});
|
|
27
27
|
const behind = (res.stdout ?? "").trim();
|