@holmes-lab/holmes-kit 0.35.0 → 0.35.2
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/CHANGELOG.md +108 -0
- package/README.md +7 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve.js +9 -2
- package/dist/holmes/cli/codex-oracle.js +36 -2
- package/dist/holmes/cli/doctor.d.ts +14 -1
- package/dist/holmes/cli/doctor.js +355 -72
- package/dist/holmes/cli/index.d.ts +1 -1
- package/dist/holmes/cli/index.js +38 -5
- package/dist/holmes/cli/init.d.ts +2 -0
- package/dist/holmes/cli/init.js +37 -1
- package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
- package/dist/holmes/cli/runtime-binding-approval.js +102 -0
- package/dist/holmes/cli/runtime-binding.d.ts +45 -0
- package/dist/holmes/cli/runtime-binding.js +630 -0
- package/dist/holmes/governance/approval-grants.d.ts +7 -0
- package/dist/holmes/governance/approval-grants.js +8 -2
- package/dist/holmes/governance/approval-queue.d.ts +2 -0
- package/dist/holmes/governance/approval-queue.js +11 -4
- package/dist/holmes/governance/autonomy.d.ts +9 -0
- package/dist/holmes/governance/autonomy.js +65 -13
- package/dist/holmes/guardrail/risk-classifier.js +76 -26
- package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
- package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
- package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
- package/dist/holmes/guardrail/shell-syntax.js +489 -0
- package/dist/holmes/guardrail/shell-words.d.ts +2 -18
- package/dist/holmes/guardrail/shell-words.js +15 -441
- package/dist/holmes/guardrail/write-target.d.ts +54 -0
- package/dist/holmes/guardrail/write-target.js +327 -1
- package/dist/holmes/guardrail/write-verb-word.d.ts +13 -0
- package/dist/holmes/guardrail/write-verb-word.js +55 -0
- package/dist/holmes/hooks/pre-tool-use.d.ts +14 -0
- package/dist/holmes/hooks/pre-tool-use.js +391 -66
- package/dist/holmes/mcp/handlers/spec-approval.js +14 -2
- package/dist/holmes/mcp/handlers.d.ts +9 -1
- package/dist/holmes/mcp/handlers.js +6 -4
- package/dist/holmes/mcp/harness-attestation.d.ts +10 -1
- package/dist/holmes/mcp/harness-attestation.js +70 -3
- package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
- package/dist/holmes/mcp/operator-recovery.js +66 -0
- package/dist/holmes/mcp/server.js +6 -3
- package/dist/holmes/runtime/binding.d.ts +30 -0
- package/dist/holmes/runtime/binding.js +164 -0
- package/dist/holmes/runtime/dispatch.d.ts +9 -0
- package/dist/holmes/runtime/dispatch.js +169 -0
- package/dist/holmes/runtime/hook-process.d.ts +11 -0
- package/dist/holmes/runtime/hook-process.js +130 -0
- package/docs/install-guide.md +65 -0
- package/package.json +1 -1
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type ChildProcess } from 'node:child_process';
|
|
2
|
+
export declare const HOOK_BUDGET_MS = 18000;
|
|
3
|
+
export declare const HOOK_CLEANUP_MS = 8000;
|
|
4
|
+
export declare function boundedHookBudget(value: number | undefined, maximum: number): number;
|
|
5
|
+
export interface HookChildResult {
|
|
6
|
+
bytes: Buffer;
|
|
7
|
+
code: number | null;
|
|
8
|
+
signal: NodeJS.Signals | null;
|
|
9
|
+
}
|
|
10
|
+
/** Bounded hook transport only. Persistent MCP transports do not call this function. */
|
|
11
|
+
export declare function runHookChild(child: ChildProcess, input: Buffer, remainingMs: number, cleanupMs: number): Promise<HookChildResult>;
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.HOOK_CLEANUP_MS = exports.HOOK_BUDGET_MS = void 0;
|
|
4
|
+
exports.boundedHookBudget = boundedHookBudget;
|
|
5
|
+
exports.runHookChild = runHookChild;
|
|
6
|
+
// @implements A-SPEC-751.1
|
|
7
|
+
const node_child_process_1 = require("node:child_process");
|
|
8
|
+
exports.HOOK_BUDGET_MS = 18_000;
|
|
9
|
+
exports.HOOK_CLEANUP_MS = 8_000;
|
|
10
|
+
function boundedHookBudget(value, maximum) {
|
|
11
|
+
if (value === undefined)
|
|
12
|
+
return maximum;
|
|
13
|
+
if (!Number.isInteger(value) || value <= 0 || value > maximum)
|
|
14
|
+
throw new Error('Invalid hook deadline budget');
|
|
15
|
+
return value;
|
|
16
|
+
}
|
|
17
|
+
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
|
|
18
|
+
/** Only a child spawned by this dispatcher may be supplied. Never enumerate unrelated PIDs. */
|
|
19
|
+
async function stopOwnedChild(child, closed, budget) {
|
|
20
|
+
const until = performance.now() + budget;
|
|
21
|
+
let failure;
|
|
22
|
+
try {
|
|
23
|
+
if (child.pid && process.platform === 'win32' && !closed()) {
|
|
24
|
+
failure = await new Promise(resolve => {
|
|
25
|
+
const killer = (0, node_child_process_1.spawn)('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
|
|
26
|
+
let settled = false;
|
|
27
|
+
const finish = (reason) => {
|
|
28
|
+
if (settled)
|
|
29
|
+
return;
|
|
30
|
+
settled = true;
|
|
31
|
+
clearTimeout(timer);
|
|
32
|
+
resolve(reason);
|
|
33
|
+
};
|
|
34
|
+
const timer = setTimeout(() => { killer.kill('SIGKILL'); killer.unref(); finish('process tree cleanup timed out'); }, Math.max(1, until - performance.now()));
|
|
35
|
+
killer.once('error', () => finish('process tree cleanup could not start'));
|
|
36
|
+
killer.once('close', code => finish(code === 0 ? undefined : `process tree cleanup exited ${code}`));
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
else if (child.pid && process.platform !== 'win32') {
|
|
40
|
+
const kill = (signal) => {
|
|
41
|
+
try {
|
|
42
|
+
process.kill(-child.pid, signal);
|
|
43
|
+
}
|
|
44
|
+
catch (error) {
|
|
45
|
+
if (error.code !== 'ESRCH')
|
|
46
|
+
throw error;
|
|
47
|
+
}
|
|
48
|
+
};
|
|
49
|
+
kill('SIGTERM');
|
|
50
|
+
await delay(Math.min(100, budget / 4));
|
|
51
|
+
// A wrapper can exit first while its descendant keeps a pipe open or ignores SIGTERM.
|
|
52
|
+
kill('SIGKILL');
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
failure = 'owned process tree cleanup failed';
|
|
57
|
+
}
|
|
58
|
+
child.stdin?.destroy();
|
|
59
|
+
child.stdout?.destroy();
|
|
60
|
+
child.stderr?.destroy();
|
|
61
|
+
while (!closed() && performance.now() < until)
|
|
62
|
+
await delay(Math.min(20, Math.max(1, until - performance.now())));
|
|
63
|
+
if (!closed()) {
|
|
64
|
+
child.unref();
|
|
65
|
+
return failure ?? 'child closure could not be confirmed before cleanup deadline';
|
|
66
|
+
}
|
|
67
|
+
return failure;
|
|
68
|
+
}
|
|
69
|
+
/** Bounded hook transport only. Persistent MCP transports do not call this function. */
|
|
70
|
+
function runHookChild(child, input, remainingMs, cleanupMs) {
|
|
71
|
+
return new Promise((resolve, reject) => {
|
|
72
|
+
const output = [];
|
|
73
|
+
let bytes = 0;
|
|
74
|
+
let closed = false;
|
|
75
|
+
let finishing = false;
|
|
76
|
+
let externalSignal;
|
|
77
|
+
const signals = ['SIGTERM', 'SIGINT', 'SIGHUP'];
|
|
78
|
+
const handlers = signals.map(signal => () => {
|
|
79
|
+
externalSignal ??= signal;
|
|
80
|
+
void finish(undefined, { bytes: Buffer.alloc(0), code: null, signal: externalSignal }, true);
|
|
81
|
+
});
|
|
82
|
+
const timer = setTimeout(() => { void finish(new Error('Selected hook runtime deadline exceeded'), undefined, true); }, Math.max(1, remainingMs));
|
|
83
|
+
const finish = async (error, result, stop = false) => {
|
|
84
|
+
if (finishing)
|
|
85
|
+
return;
|
|
86
|
+
finishing = true;
|
|
87
|
+
clearTimeout(timer);
|
|
88
|
+
let cleanupFailure;
|
|
89
|
+
if (stop)
|
|
90
|
+
cleanupFailure = await stopOwnedChild(child, () => closed, cleanupMs);
|
|
91
|
+
if (externalSignal) {
|
|
92
|
+
error = undefined;
|
|
93
|
+
result = { bytes: Buffer.alloc(0), code: null, signal: externalSignal };
|
|
94
|
+
}
|
|
95
|
+
signals.forEach((signal, i) => process.removeListener(signal, handlers[i]));
|
|
96
|
+
child.stdout?.removeListener('data', onData);
|
|
97
|
+
child.stdin?.removeListener('error', onInputError);
|
|
98
|
+
if (cleanupFailure) {
|
|
99
|
+
if (result?.signal)
|
|
100
|
+
process.stderr.write(`[Holmes-Kit] ${cleanupFailure}\n`);
|
|
101
|
+
else
|
|
102
|
+
error = new Error(`${error?.message ?? 'Hook transport failed'}; cleanup unconfirmed: ${cleanupFailure}`);
|
|
103
|
+
}
|
|
104
|
+
if (error)
|
|
105
|
+
reject(error);
|
|
106
|
+
else
|
|
107
|
+
resolve(result);
|
|
108
|
+
};
|
|
109
|
+
const onData = (chunk) => {
|
|
110
|
+
if (finishing)
|
|
111
|
+
return;
|
|
112
|
+
bytes += chunk.length;
|
|
113
|
+
if (bytes > 2 * 1024 * 1024)
|
|
114
|
+
void finish(new Error('Hook output exceeds 2 MiB'), undefined, true);
|
|
115
|
+
else
|
|
116
|
+
output.push(chunk);
|
|
117
|
+
};
|
|
118
|
+
const onInputError = (error) => { if (error.code !== 'EPIPE')
|
|
119
|
+
void finish(new Error('Hook input delivery failed'), undefined, true); };
|
|
120
|
+
child.stdout.on('data', onData);
|
|
121
|
+
child.stdin.on('error', onInputError);
|
|
122
|
+
child.once('error', error => { void finish(error, undefined, true); });
|
|
123
|
+
child.once('close', (code, signal) => {
|
|
124
|
+
closed = true;
|
|
125
|
+
void finish(undefined, { bytes: Buffer.concat(output), code, signal }, signal !== null);
|
|
126
|
+
});
|
|
127
|
+
signals.forEach((signal, i) => process.on(signal, handlers[i]));
|
|
128
|
+
child.stdin.end(input);
|
|
129
|
+
});
|
|
130
|
+
}
|
package/docs/install-guide.md
CHANGED
|
@@ -17,6 +17,71 @@ worked on the first try. Find your row, run its one command.
|
|
|
17
17
|
The local install is the path verified end to end, on macOS and Windows, against the public
|
|
18
18
|
registry. The wiring `init` writes uses absolute paths, so nothing needs to be on `PATH`.
|
|
19
19
|
|
|
20
|
+
## Development and consumer runtime binding
|
|
21
|
+
|
|
22
|
+
Maintainers can register a built development package without replacing the release used by consumer
|
|
23
|
+
projects. This explicit installation is separate from ordinary `init`. It applies to Claude Code, Codex
|
|
24
|
+
and Antigravity through a shared resolver; successful setup is not proof that a native session loaded or
|
|
25
|
+
trusted its hooks.
|
|
26
|
+
|
|
27
|
+
Choose three absolute paths: the development workspace, its complete built Holmes-Kit package, and the
|
|
28
|
+
installed release package. The built package must contain its CLI, MCP entry, compiled hooks and build ID.
|
|
29
|
+
Use the built package's CLI to preview the installation (replace the example paths):
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
node "/absolute/development-package/bin/holmes-kit.js" runtime-binding setup --workspace "/absolute/workspace" --package "/absolute/development-package" --release-package "/absolute/release-package" --dry-run
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The default registry is `~/.holmes/runtime/bindings.json`. An explicit `--registry` selects another
|
|
36
|
+
operator-controlled destination; keep that same path on setup, status and doctor calls. A repository marker
|
|
37
|
+
cannot register executable code. Linked worktrees and independent nested workspaces require their own
|
|
38
|
+
binding; missing development builds never silently fall back to the release.
|
|
39
|
+
|
|
40
|
+
Review the exact changed files and resolve every conflict. Then run the same setup without `--dry-run`
|
|
41
|
+
from the operator terminal. If it prints an approval request, that invocation has not applied the plan.
|
|
42
|
+
Review and grant only that current request through the same built CLI:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
node "/absolute/development-package/bin/holmes-kit.js" approve --target "/absolute/workspace" --grant "<request-id>"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Retry the unchanged setup after successful approval. If the plan changed, review its new request instead
|
|
49
|
+
of reusing an old grant. A fully validated zero-change setup needs no additional approval; replacing a build
|
|
50
|
+
at the same path or migrating an old installation receipt is still a real change.
|
|
51
|
+
|
|
52
|
+
Ordinary setup preserves disabled lifecycle entries and native trust. To restore selected Holmes hook
|
|
53
|
+
entries, include `--activate-hooks claude,codex,antigravity` (or a subset) in the preview and apply commands.
|
|
54
|
+
Native trust and global disable switches remain native review steps. Do not manufacture trust records or
|
|
55
|
+
assume a new project hook suppresses another user/plugin hook.
|
|
56
|
+
|
|
57
|
+
After installation, inspect selection and diagnosis:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
node "/absolute/development-package/bin/holmes-kit.js" runtime-binding status --workspace "/absolute/workspace"
|
|
61
|
+
node "/absolute/development-package/bin/holmes-kit.js" doctor --target "/absolute/workspace"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
For a custom registry, add its `--registry` argument to both commands. Reconnect the MCP server if it still
|
|
65
|
+
reports the old build. In a fresh native session, compare MCP and hook package/build/workspace/spec store,
|
|
66
|
+
then observe permission, refusal, official recovery, original task resumption and normal Stop. Repeat in
|
|
67
|
+
each harness and in an unregistered consumer workspace. `binding: matched`, doctor output and generated
|
|
68
|
+
configuration alone do not establish live enforcement.
|
|
69
|
+
|
|
70
|
+
**Approval recovery:** the dedicated MCP dispatcher loads the validated package entry in the same process,
|
|
71
|
+
preserving its genuine native parent. The entry retains its opt-in autoreload supervisor; that chain or
|
|
72
|
+
another host may still be unable to attest. Such routes use the official operator queue without relaxing
|
|
73
|
+
native identity checks. Follow the displayed command: it names the running package's CLI, bound workspace
|
|
74
|
+
and recorded request ID. Do not keep retrying the same refused action without a new decision. Retry the
|
|
75
|
+
original MCP operation after the grant is recognized. Held questions and denial reasons must first be
|
|
76
|
+
addressed; expired, wrong-scope or consumed authority needs an official decision. A chat acknowledgement
|
|
77
|
+
is not a grant. Validate the actual newly installed session before claiming that recovery works there.
|
|
78
|
+
|
|
79
|
+
Routed hooks bound input/selection/execution to 18 seconds and owned-process cleanup to another 8 seconds.
|
|
80
|
+
On timeout or malformed output they return native refusal guidance with status/doctor commands. Repair the
|
|
81
|
+
selected package through a reviewed installation, then retry the original operation. Cleanup uncertainty
|
|
82
|
+
and pending findings remain visible. These bounds do not guarantee that every native host or operating-system
|
|
83
|
+
failure is recoverable without operator action. MCP itself has no hook lifetime deadline.
|
|
84
|
+
|
|
20
85
|
## Before `npm install -g`: check your prefix
|
|
21
86
|
|
|
22
87
|
```
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"//": "@implements A-SPEC-209",
|
|
3
3
|
"name": "@holmes-lab/holmes-kit",
|
|
4
|
-
"version": "0.35.
|
|
4
|
+
"version": "0.35.2",
|
|
5
5
|
"description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
|
|
6
6
|
"main": "dist/holmes/mcp/server.js",
|
|
7
7
|
"types": "dist/holmes/mcp/server.d.ts",
|