machine-bridge-mcp 0.8.2 → 0.9.0
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 +14 -0
- package/README.md +37 -1
- package/SECURITY.md +10 -0
- package/docs/AGENT_CONTEXT.md +206 -0
- package/docs/ARCHITECTURE.md +9 -0
- package/docs/TESTING.md +1 -0
- package/package.json +5 -4
- package/src/local/agent-context.mjs +708 -0
- package/src/local/runtime.mjs +32 -0
- package/src/shared/server-metadata.json +1 -0
- package/src/shared/tool-catalog.json +172 -0
- package/src/worker/index.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.0 - 2026-07-12
|
|
4
|
+
|
|
5
|
+
### Agent context and local workflows
|
|
6
|
+
|
|
7
|
+
- Add `agent_context`, a bounded bootstrap tool with Codex-compatible instruction precedence: unrestricted `CODEX_HOME`/`~/.codex` guidance, then project root-to-target scopes, selecting the first non-empty `AGENTS.override.md` or `AGENTS.md` candidate per directory under a default 32 KiB combined budget. Add hierarchical `.machine-bridge/agent.json` manifests plus an optional unrestricted user manifest at `~/.config/machine-bridge-mcp/agent.json` for custom candidate priority and bounds.
|
|
8
|
+
- Add `list_local_skills` and `load_local_skill` with Codex-style progressive disclosure. Default discovery scans target-to-root `.agents/skills`, unrestricted user/admin roots, and canonicalized symlinked skill directories; invalid metadata is skipped with bounded warnings. Skill loading returns instructions and a relative file inventory without implicitly executing scripts.
|
|
9
|
+
- Add `list_local_commands` and direct-argv `run_local_command`. Nearest manifests can override or remove inherited commands, caller arguments require manifest opt-in, and callers cannot increase the manifest timeout ceiling.
|
|
10
|
+
|
|
11
|
+
### Architecture, security, and tests
|
|
12
|
+
|
|
13
|
+
- Extract agent discovery into `AgentContextManager` rather than expanding transport or runtime dispatch responsibilities. Keep a static MCP catalog across Worker and stdio transports so host-side caching and filtering do not require dynamic per-skill tools.
|
|
14
|
+
- Reject escaping instruction/config paths, unknown manifest fields, out-of-policy skill symlink targets, symbolic-link skill entrypoints, ambiguous skill names, oversized content/argv, and execution attempts under non-execution profiles. Document that repository instructions and skills are untrusted content and that registered commands are convenience aliases, not a sandbox or approval boundary.
|
|
15
|
+
- Add regression coverage for global/project override selection, empty-candidate fallback, custom priority, instruction-byte ceilings, target-to-root skill discovery, symlinked skill folders, invalid metadata warnings, command override/removal, literal argument handling without shell parsing, timeout ceilings, path escape denial, and execution-profile denial. Update server instructions, architecture, security, testing, and operator documentation for the new bootstrap workflow.
|
|
16
|
+
|
|
3
17
|
## 0.8.2 - 2026-07-11
|
|
4
18
|
|
|
5
19
|
### Relay reliability and protocol correctness
|
package/README.md
CHANGED
|
@@ -108,6 +108,37 @@ machine-mcp stdio --workspace /path/to/project
|
|
|
108
108
|
|
|
109
109
|
The stdio server writes only JSON-RPC messages to stdout and operational logs to stderr. See [docs/CLIENTS.md](docs/CLIENTS.md) for the host/model distinction and transport trade-offs.
|
|
110
110
|
|
|
111
|
+
## Agent instructions, local skills, and command registry
|
|
112
|
+
|
|
113
|
+
For substantive workspace tasks, clients can call `agent_context` for the relevant file or directory. Its default instruction discovery mirrors Codex: under unrestricted policy it first checks `CODEX_HOME` or `~/.codex`, then walks from the project root to the target directory, selecting the first non-empty `AGENTS.override.md` or `AGENTS.md` in each scope. Deeper guidance has higher precedence, and the default combined budget is 32 KiB.
|
|
114
|
+
|
|
115
|
+
Skill discovery also follows Codex-style progressive disclosure. By default, Machine Bridge scans `.agents/skills` from the target directory through the project root; unrestricted policy additionally enables `~/.agents/skills` and, on Unix-like systems, `/etc/codex/skills`. `agent_context` initially returns bounded metadata, while `load_local_skill` returns the selected `SKILL.md` and file inventory without executing anything implicitly.
|
|
116
|
+
|
|
117
|
+
A project can add custom instruction candidates, explicit skill roots, and registered commands with `.machine-bridge/agent.json`:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"version": 1,
|
|
122
|
+
"instruction_files": [
|
|
123
|
+
"PROJECT.override.md",
|
|
124
|
+
"AGENTS.override.md",
|
|
125
|
+
"AGENTS.md"
|
|
126
|
+
],
|
|
127
|
+
"instruction_max_bytes": 65536,
|
|
128
|
+
"commands": {
|
|
129
|
+
"check": {
|
|
130
|
+
"description": "Run repository validation.",
|
|
131
|
+
"argv": ["npm", "run", "check"],
|
|
132
|
+
"cwd": ".",
|
|
133
|
+
"timeout_seconds": 600,
|
|
134
|
+
"allow_extra_args": false
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`instruction_files` is a priority list: each directory contributes only its first non-empty candidate. Deeper manifests override earlier settings and can remove an inherited command with `null`. `run_local_command` executes registered commands as direct argv processes without shell parsing and is available only when direct execution is enabled. See [Agent context, local skills, and registered commands](docs/AGENT_CONTEXT.md) for the complete contract.
|
|
141
|
+
|
|
111
142
|
## Policy controls
|
|
112
143
|
|
|
113
144
|
The default is `full`. Narrow or customize it with explicit flags:
|
|
@@ -233,6 +264,10 @@ The exact `tools/list` response reflects the active local policy. Definitions co
|
|
|
233
264
|
|
|
234
265
|
- `server_info`
|
|
235
266
|
- `project_overview`
|
|
267
|
+
- `agent_context` — effective instructions, skill summaries, and registered commands for a target path
|
|
268
|
+
- `list_local_skills`
|
|
269
|
+
- `load_local_skill` — load instructions and file inventory without implicit execution
|
|
270
|
+
- `list_local_commands`
|
|
236
271
|
- `list_roots`
|
|
237
272
|
- `list_dir`
|
|
238
273
|
- `list_files`
|
|
@@ -270,6 +305,7 @@ Managed jobs are non-interactive and persist independently of the MCP connection
|
|
|
270
305
|
|
|
271
306
|
### Processes
|
|
272
307
|
|
|
308
|
+
- `run_local_command` — direct argv execution of a manifest-registered command
|
|
273
309
|
- `run_process` — one-shot argv execution without a shell
|
|
274
310
|
- `start_process`
|
|
275
311
|
- `read_process`
|
|
@@ -350,7 +386,7 @@ npm pack --dry-run
|
|
|
350
386
|
|
|
351
387
|
`npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, local path/write/process/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
|
|
352
388
|
|
|
353
|
-
See [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
|
|
389
|
+
See [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
|
|
354
390
|
|
|
355
391
|
## Uninstall
|
|
356
392
|
|
package/SECURITY.md
CHANGED
|
@@ -51,6 +51,16 @@ The default for newly selected workspaces is `full`, which prioritizes ease of u
|
|
|
51
51
|
|
|
52
52
|
For untrusted repositories or instructions, run the bridge inside a disposable VM/container or under a dedicated low-privilege OS account. On macOS and Windows, this external isolation is especially important. The project does not claim an in-process OS sandbox.
|
|
53
53
|
|
|
54
|
+
## Agent instructions, skills, and command manifests
|
|
55
|
+
|
|
56
|
+
Repository and user instruction files are untrusted content from the model's perspective. `agent_context` returns their text in deterministic precedence order but does not certify correctness or safety. A malicious `AGENTS.md`, custom instruction file, or `SKILL.md` can attempt prompt injection or recommend destructive operations. Use only trusted repositories and skill roots, or isolate the bridge externally.
|
|
57
|
+
|
|
58
|
+
Skill loading is non-executing. `load_local_skill` returns an entrypoint and bounded file inventory; scripts remain inert until a separate process or command tool is called. Symlinked skill directories are followed only after canonical path-policy validation, while symbolic-link `SKILL.md` entrypoints are rejected. Traversal, cycles, content, summaries, and inventory are bounded.
|
|
59
|
+
|
|
60
|
+
Registered commands are available only under direct-execution-capable policy. They use argv spawning rather than shell parsing, reject undeclared caller arguments, and enforce the manifest timeout as a ceiling. They are not an approval or sandbox boundary: a repository-controlled package script, interpreter, compiler, or executable can still run arbitrary code with local-user authority. Deeper manifests can override or remove inherited commands, so callers must obtain context for the actual target path rather than assuming the repository-root registry applies everywhere.
|
|
61
|
+
|
|
62
|
+
The remote MCP host remains an independent boundary. Machine Bridge can advertise these tools and instruct the model to bootstrap with `agent_context`, but it cannot force a host to expose or invoke them, and it cannot bypass host confirmation or refusal.
|
|
63
|
+
|
|
54
64
|
## Filesystem exposure
|
|
55
65
|
|
|
56
66
|
Direct filesystem scope is profile-dependent. The default `full` profile is unrestricted. The `agent`, `edit`, and `review` profiles confine direct filesystem tools to the canonical selected workspace, including symbolic-link resolution.
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# Agent context, local skills, and registered commands
|
|
2
|
+
|
|
3
|
+
The default compatibility target is the current OpenAI Codex guidance for repository instructions and filesystem skills.
|
|
4
|
+
|
|
5
|
+
Machine Bridge exposes a stable agent bootstrap layer so an MCP client can use repository instructions and local workflows without requiring one dynamically named MCP tool per skill or command.
|
|
6
|
+
|
|
7
|
+
The default discovery rules intentionally track current Codex conventions where practical. Machine Bridge also adds a JSON manifest for custom instruction priority, additional skill roots, and named local commands.
|
|
8
|
+
|
|
9
|
+
This does not make a remote MCP session identical to a locally installed coding agent. The MCP host can independently filter tools, require confirmation, truncate results, or decline calls before they reach Machine Bridge. The bridge cannot alter or bypass those host decisions.
|
|
10
|
+
|
|
11
|
+
## Tool model
|
|
12
|
+
|
|
13
|
+
Five tools form the agent-context surface:
|
|
14
|
+
|
|
15
|
+
- `agent_context` discovers effective instructions, skill summaries, and registered commands for a target path;
|
|
16
|
+
- `list_local_skills` searches discovered `SKILL.md` or `skill.md` bundles;
|
|
17
|
+
- `load_local_skill` returns one skill entrypoint plus a bounded relative file inventory;
|
|
18
|
+
- `list_local_commands` returns the effective command registry;
|
|
19
|
+
- `run_local_command` executes one registered command as a direct argv process.
|
|
20
|
+
|
|
21
|
+
The server instructions tell MCP clients to call `agent_context` before substantive workspace work. This is behavioral guidance, not a protocol-enforced precondition. Every file, Git, mutation, and process tool therefore retains its own policy enforcement.
|
|
22
|
+
|
|
23
|
+
## Instruction scope and precedence
|
|
24
|
+
|
|
25
|
+
For a target path, Machine Bridge chooses the nearest ancestor containing `.git` as the project scope root. If no Git marker is found, a target inside the configured workspace uses the workspace root; an unrestricted target outside the workspace uses the target directory.
|
|
26
|
+
|
|
27
|
+
The default instruction candidates, in priority order, are:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
[
|
|
31
|
+
"AGENTS.override.md",
|
|
32
|
+
"AGENTS.md"
|
|
33
|
+
]
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Discovery then works as follows:
|
|
37
|
+
|
|
38
|
+
1. under unrestricted policy, read the first non-empty candidate in `CODEX_HOME` or `~/.codex`;
|
|
39
|
+
2. walk from the project scope root to the target directory;
|
|
40
|
+
3. in each directory, apply its optional `.machine-bridge/agent.json` first;
|
|
41
|
+
4. select only the first non-empty instruction candidate in that directory;
|
|
42
|
+
5. concatenate selected files from global to root to leaf, so later directories have higher precedence.
|
|
43
|
+
|
|
44
|
+
Empty candidates are skipped. Only one instruction file is selected per directory. This matches the important Codex override behavior: `AGENTS.override.md` suppresses `AGENTS.md` in the same directory, while deeper directories override broader guidance.
|
|
45
|
+
|
|
46
|
+
The combined instruction budget defaults to 32 KiB. Once the budget would be exceeded, discovery stops and returns `instructions_truncated: true`. A manifest can raise or lower the budget within the hard 2 MiB ceiling.
|
|
47
|
+
|
|
48
|
+
Global instruction discovery is disabled under workspace-confined profiles because reading `~/.codex` would otherwise bypass the profile's direct-filesystem boundary. Project instructions still work in every profile.
|
|
49
|
+
|
|
50
|
+
## Custom instruction priority
|
|
51
|
+
|
|
52
|
+
A manifest may replace the candidate list. The list is priority order, not a list of files to concatenate from the same directory:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"version": 1,
|
|
57
|
+
"instruction_files": [
|
|
58
|
+
"LOCAL.override.md",
|
|
59
|
+
"AGENTS.override.md",
|
|
60
|
+
"AGENTS.md",
|
|
61
|
+
".github/agent-guidance.md"
|
|
62
|
+
],
|
|
63
|
+
"instruction_max_bytes": 65536
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
For each directory, Machine Bridge selects the first non-empty file in that list. Candidate paths must be relative and their canonical targets must remain inside the directory being inspected.
|
|
68
|
+
|
|
69
|
+
## Configuration format
|
|
70
|
+
|
|
71
|
+
A project configuration lives at `.machine-bridge/agent.json`. Relative skill roots and command working directories are resolved against the directory containing `.machine-bridge`, not against the hidden configuration directory itself.
|
|
72
|
+
|
|
73
|
+
```json
|
|
74
|
+
{
|
|
75
|
+
"version": 1,
|
|
76
|
+
"instruction_files": [
|
|
77
|
+
"PROJECT.override.md",
|
|
78
|
+
"AGENTS.override.md",
|
|
79
|
+
"AGENTS.md"
|
|
80
|
+
],
|
|
81
|
+
"instruction_max_bytes": 65536,
|
|
82
|
+
"skill_roots": [
|
|
83
|
+
".agents/skills",
|
|
84
|
+
".codex/skills"
|
|
85
|
+
],
|
|
86
|
+
"commands": {
|
|
87
|
+
"check": {
|
|
88
|
+
"description": "Run the repository validation suite.",
|
|
89
|
+
"argv": ["npm", "run", "check"],
|
|
90
|
+
"cwd": ".",
|
|
91
|
+
"timeout_seconds": 600,
|
|
92
|
+
"allow_extra_args": false
|
|
93
|
+
},
|
|
94
|
+
"test-file": {
|
|
95
|
+
"description": "Run one test file selected by the caller.",
|
|
96
|
+
"argv": ["node", "--test"],
|
|
97
|
+
"cwd": ".",
|
|
98
|
+
"timeout_seconds": 120,
|
|
99
|
+
"allow_extra_args": true
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Supported top-level fields are:
|
|
106
|
+
|
|
107
|
+
- `version`: required and currently fixed at `1`;
|
|
108
|
+
- `instruction_files`: non-empty priority-ordered relative candidates;
|
|
109
|
+
- `instruction_max_bytes`: combined instruction budget from 1 KiB through 2 MiB;
|
|
110
|
+
- `skill_roots`: explicit skill directories; when present, this replaces inherited/default roots;
|
|
111
|
+
- `commands`: named command definitions merged with inherited commands.
|
|
112
|
+
|
|
113
|
+
Configuration is evaluated from global to project root to target directory. A deeper definition replaces the inherited value. A deeper command value of `null` removes that command:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"version": 1,
|
|
118
|
+
"commands": {
|
|
119
|
+
"deploy": null
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Unknown fields are rejected so misspellings do not silently weaken the intended workflow.
|
|
125
|
+
|
|
126
|
+
Under unrestricted policy only, `~/.config/machine-bridge-mcp/agent.json` acts as the initial user-level manifest. Relative paths in that file are resolved from the user's home directory.
|
|
127
|
+
|
|
128
|
+
## Skill discovery
|
|
129
|
+
|
|
130
|
+
Without an explicit `skill_roots` setting, Machine Bridge uses Codex-compatible filesystem locations:
|
|
131
|
+
|
|
132
|
+
- `<target>/.agents/skills`;
|
|
133
|
+
- every ancestor's `.agents/skills` through the project root;
|
|
134
|
+
- under unrestricted policy, `~/.agents/skills`;
|
|
135
|
+
- under unrestricted policy on Unix-like systems, `/etc/codex/skills`.
|
|
136
|
+
|
|
137
|
+
An explicit `skill_roots` list can add compatibility with other layouts, such as `.codex/skills`, or narrow discovery to selected directories.
|
|
138
|
+
|
|
139
|
+
Machine Bridge recursively finds directories containing `SKILL.md` or `skill.md`. The entrypoint must contain simple YAML front matter with non-empty `name` and `description` fields:
|
|
140
|
+
|
|
141
|
+
```markdown
|
|
142
|
+
---
|
|
143
|
+
name: release-review
|
|
144
|
+
description: Review a release without publishing it.
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
# Workflow
|
|
148
|
+
|
|
149
|
+
...
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Invalid skills are skipped and reported in `skill_warnings` or `warnings`; one malformed bundle does not prevent valid skills from loading.
|
|
153
|
+
|
|
154
|
+
Symlinked skill folders are followed, matching Codex behavior. Under workspace-confined profiles, the canonical symlink target must remain inside the workspace. Skill entrypoint files themselves may not be symbolic links. Directory traversal, cycles, entry count, depth, content, and returned file inventory are bounded.
|
|
155
|
+
|
|
156
|
+
## Progressive disclosure
|
|
157
|
+
|
|
158
|
+
`agent_context` initially returns only skill metadata: name, description, path, ID, size, and hash. Its skill summary list has an 8,000-character budget and a caller-selected count limit. Descriptions are shortened first and excess skills are omitted with `skills_truncated: true`.
|
|
159
|
+
|
|
160
|
+
`load_local_skill` accepts a stable opaque ID, an unambiguous exact name, or a displayed entrypoint path. It returns:
|
|
161
|
+
|
|
162
|
+
- the full bounded UTF-8 `SKILL.md` content;
|
|
163
|
+
- metadata and a content hash;
|
|
164
|
+
- a bounded relative inventory of files in the skill directory.
|
|
165
|
+
|
|
166
|
+
Loading a skill never executes its scripts. The model must inspect the instructions and then invoke an ordinary bridge tool, a registered command, or a managed job. This keeps documentation loading separate from executable authority.
|
|
167
|
+
|
|
168
|
+
## Registered command execution
|
|
169
|
+
|
|
170
|
+
`run_local_command` is available only when direct process execution is enabled (`agent` or `full`, including equivalent custom policies). It does not invoke a shell. Manifest `argv` elements and caller-supplied arguments remain distinct process arguments, so characters such as `;`, `$()`, pipes, and redirections are not interpreted by a shell.
|
|
171
|
+
|
|
172
|
+
The manifest remains authoritative:
|
|
173
|
+
|
|
174
|
+
- caller arguments are rejected unless `allow_extra_args` is true;
|
|
175
|
+
- a caller can reduce the timeout but cannot increase it beyond `timeout_seconds`;
|
|
176
|
+
- the working directory is canonicalized and remains subject to active path policy;
|
|
177
|
+
- the command receives the isolated or full environment selected by the Machine Bridge profile.
|
|
178
|
+
|
|
179
|
+
Registered commands are workflow aliases, not a sandbox or approval boundary. Repository-controlled package scripts, interpreters, compilers, and executables can run arbitrary code with the local user's authority. Use `edit` or `review`, or external VM/container isolation, for untrusted repositories.
|
|
180
|
+
|
|
181
|
+
For arbitrary one-off execution, existing tools remain available according to policy:
|
|
182
|
+
|
|
183
|
+
- `run_process` for direct argv execution;
|
|
184
|
+
- `exec_command` for shell syntax under shell-enabled policy;
|
|
185
|
+
- `start_job` for durable multi-step work;
|
|
186
|
+
- `stage_job` for local operator review and later approval.
|
|
187
|
+
|
|
188
|
+
## Recommended remote workflow
|
|
189
|
+
|
|
190
|
+
A remote coding task should normally follow this sequence:
|
|
191
|
+
|
|
192
|
+
1. call `agent_context` with the file or directory being changed;
|
|
193
|
+
2. apply returned instructions in precedence order;
|
|
194
|
+
3. load only skills relevant to the task;
|
|
195
|
+
4. inspect files before editing;
|
|
196
|
+
5. prefer a registered command for validation or a standard workflow;
|
|
197
|
+
6. use direct or shell execution only when the registry does not cover the operation;
|
|
198
|
+
7. report files changed and commands run.
|
|
199
|
+
|
|
200
|
+
This approximates local coding-agent context loading while keeping MCP transport, local policy, and host policy as explicit independent boundaries.
|
|
201
|
+
|
|
202
|
+
## Security and failure behavior
|
|
203
|
+
|
|
204
|
+
Agent configuration, instruction content, skill traversal, skill summaries, skill inventory, command count, argv size, timeouts, and process output are bounded. Invalid JSON, unknown fields, escaping paths, ambiguous skill names, invalid skill metadata, and missing commands fail explicitly or produce bounded warnings.
|
|
205
|
+
|
|
206
|
+
Instruction and skill contents are untrusted operational text. They may contain prompt injection or unsafe command guidance. Machine Bridge exposes the content; it does not certify or approve it.
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -32,12 +32,21 @@ A canonical workspace receives an independent profile, Worker name, secret set,
|
|
|
32
32
|
- process-session buffers and stdin lifecycle;
|
|
33
33
|
- layered fixed runtime diagnostics;
|
|
34
34
|
- local resource aliases and detached managed-job coordination;
|
|
35
|
+
- agent-context discovery and registered-command execution coordination;
|
|
35
36
|
- mutation serialization;
|
|
36
37
|
- child-process tracking and cancellation;
|
|
37
38
|
- output, traversal, concurrency, and time limits.
|
|
38
39
|
|
|
39
40
|
`RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
|
|
40
41
|
|
|
42
|
+
### Agent context manager
|
|
43
|
+
|
|
44
|
+
`AgentContextManager` is a local domain module beneath `LocalRuntime`. It discovers the nearest Git/workspace scope, applies optional user configuration and hierarchical `.machine-bridge/agent.json` files, selects the first non-empty instruction candidate in each global/root-to-target scope, discovers bounded Codex-style `.agents/skills` metadata, and resolves registered commands. The runtime remains responsible for canonical path policy and process execution.
|
|
45
|
+
|
|
46
|
+
The MCP surface is deliberately static: `agent_context`, `list_local_skills`, `load_local_skill`, `list_local_commands`, and `run_local_command`. Skills and commands do not become dynamically named MCP tools. This avoids host-side catalog caching/filtering problems and keeps one schema contract across Worker and stdio transports. Initial skill delivery is metadata-only and budgeted; loading a skill is read-only and execution requires a separate ordinary tool call. Registered commands use direct argv spawning and inherit the active runtime environment policy.
|
|
47
|
+
|
|
48
|
+
See [Agent context, local skills, and registered commands](AGENT_CONTEXT.md) for precedence and configuration semantics.
|
|
49
|
+
|
|
41
50
|
### Managed job runner
|
|
42
51
|
|
|
43
52
|
`ManagedJobManager` persists bounded per-workspace job envelopes below the owner-only profile directory. `start_job` validates the complete plan, snapshots referenced resource metadata/hashes, writes an owner-only plan/status, and launches `job-runner.mjs` as a detached process with runner-level logs redirected to owner-only files. `stage_job` performs the same acceptance validation but writes a non-running `staged` envelope; only local `job approve` transitions it to queued and launches the runner.
|
package/docs/TESTING.md
CHANGED
|
@@ -17,6 +17,7 @@ The suite includes:
|
|
|
17
17
|
- generated Cloudflare Worker types and strict TypeScript checking, including unused-local and unused-parameter rejection;
|
|
18
18
|
- syntax validation for every shipped JavaScript entry point;
|
|
19
19
|
- shared tool-catalog schema, annotation, and profile-inventory checks;
|
|
20
|
+
- hierarchical agent-context precedence, custom instruction ordering, local skill discovery/loading, command override/removal, direct argv argument handling, timeout ceilings, and execution-profile denial;
|
|
20
21
|
- canonical path and symbolic-link escape tests;
|
|
21
22
|
- relative-path privacy and error-path redaction tests;
|
|
22
23
|
- atomic create/update, optimistic hash, exact edit, and patch transaction tests;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "machine-bridge-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Cross-client MCP bridge for canonical local automation, files, Git, SSH resources, managed jobs, and processes over stdio or an OAuth-protected remote relay.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -43,8 +43,8 @@
|
|
|
43
43
|
"prepublishOnly": "npm run check && npm run version:check && npm run release:check",
|
|
44
44
|
"worker:types": "wrangler types src/worker/worker-configuration.d.ts",
|
|
45
45
|
"typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
|
|
46
|
-
"syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs",
|
|
47
|
-
"check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
|
|
46
|
+
"syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs",
|
|
47
|
+
"check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run agent-context:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
|
|
48
48
|
"worker:dry-run": "wrangler deploy --dry-run",
|
|
49
49
|
"worker:integration-test": "node tests/worker-integration-test.mjs",
|
|
50
50
|
"release:check": "node scripts/github-release.mjs --check",
|
|
@@ -66,7 +66,8 @@
|
|
|
66
66
|
"install:test": "node tests/install-smoke-test.mjs",
|
|
67
67
|
"secure-file:test": "node tests/secure-file-test.mjs",
|
|
68
68
|
"architecture:test": "node tests/architecture-test.mjs",
|
|
69
|
-
"release-state:test": "node tests/release-state-test.mjs"
|
|
69
|
+
"release-state:test": "node tests/release-state-test.mjs",
|
|
70
|
+
"agent-context:test": "node tests/agent-context-test.mjs"
|
|
70
71
|
},
|
|
71
72
|
"dependencies": {
|
|
72
73
|
"wrangler": "4.110.0",
|