@engineeros/connector 1.59.40 → 1.59.42

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.
Files changed (3) hide show
  1. package/README.md +95 -72
  2. package/bin/engineeros-connector.mjs +490 -453
  3. package/package.json +2 -1
package/README.md CHANGED
@@ -1,72 +1,95 @@
1
- # EngineerOS Connector
2
-
3
- Connect a local coding agent or Bug Hunter host to EngineerOS.
4
-
5
- ## Requirements
6
-
7
- - Node.js 22 or newer and npm on Windows, macOS or Linux.
8
- - An EngineerOS pairing command and access to your chosen coding agent.
9
- - Git when connecting a code repository.
10
- - Protected credential storage: Windows Credential Manager/Data Protection, macOS Keychain, or Linux Secret Service. On Linux, install `secret-tool` (`libsecret-tools`) and run an unlocked keyring such as GNOME Keyring or KWallet.
11
-
12
- ## Install
13
-
14
- ```sh
15
- npm install --global @engineeros/connector@latest
16
- engineeros-connector version
17
- ```
18
-
19
- To run without a global install, replace `engineeros-connector` in the commands below with `npx --yes @engineeros/connector@latest`.
20
-
21
- ## Connect a workspace
22
-
23
- In EngineerOS, open **Project steering → Connect workspace** and copy the pairing command. Run it inside your project folder. For example, with Codex:
24
-
25
- ```sh
26
- engineeros-connector agent codex-acp install
27
- engineeros-connector pair PAIRING_CODE --url https://your-engineeros.example --workspace . --onboard --agent codex-acp
28
- ```
29
-
30
- Replace the code and server URL with the values from EngineerOS. Sign in to the agent when prompted; for Codex, run `codex login` in another terminal. Keep the connector terminal open.
31
-
32
- Run `engineeros-connector agents` to list supported agents. Use the chosen agent's ID in both commands above; for Claude, use `claude-acp`.
33
-
34
- Restart an already paired workspace with:
35
-
36
- ```sh
37
- engineeros-connector start --workspace .
38
- ```
39
-
40
- ## Connect Bug Hunter without a repository
41
-
42
- Choose **Find bugs in a running app** in EngineerOS, add your target and copy its host command:
43
-
44
- ```sh
45
- engineeros-connector hunt-host PAIRING_CODE --url https://your-engineeros.example --project PROJECT_UUID --agent codex-acp
46
- ```
47
-
48
- The command prepares the agent and browser tools. Complete the requested agent sign-in and keep the terminal open. Configure test accounts, app builds and devices in Bug Hunter Setup as needed.
49
-
50
- Restart the host with:
51
-
52
- ```sh
53
- engineeros-connector hunt-host --project PROJECT_UUID
54
- ```
55
-
56
- ## Troubleshoot and update
57
-
58
- ```sh
59
- engineeros-connector doctor --workspace .
60
- npm install --global @engineeros/connector@latest
61
- ```
62
-
63
- - **Missing pairing:** copy a new pairing command from EngineerOS.
64
- - **Agent sign-in failed:** sign in to the selected agent, then restart the connector.
65
- - **Credential storage unavailable:** unlock or configure the protected store listed above, then restart. Headless Linux hosts also need a running Secret Service.
66
- - **Uploaded input refused:** use public HTTPS storage or the hunt host's local inputs folder. Downloads reject private/metadata addresses and are limited to 25 MB and 60 seconds.
67
-
68
- ## License
69
-
70
- Copyright (c) 2026 [Techmirus Innovations](https://www.techmirus.com).
71
-
72
- The [EngineerOS Connector Binary Use License](LICENSE) permits personal and commercial use of the official executable distribution. The original source remains proprietary. Third-party dependencies retain their own licenses; bundled grammar notices are in [grammars/NOTICE.md](grammars/NOTICE.md).
1
+ # EngineerOS Connector
2
+
3
+ Connect a local coding agent or Bug Hunter host to EngineerOS.
4
+
5
+ ## Requirements
6
+
7
+ - Node.js 22 or newer and npm on Windows, macOS or Linux.
8
+ - An EngineerOS pairing command and access to your chosen coding agent.
9
+ - Git when connecting a code repository.
10
+ - Protected credential storage: Windows Credential Manager/Data Protection, macOS Keychain, or Linux Secret Service. On Linux, install `secret-tool` (`libsecret-tools`) and run an unlocked keyring such as GNOME Keyring or KWallet.
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ npm install --global @engineeros/connector@latest
16
+ engineeros-connector version
17
+ ```
18
+
19
+ To run without a global install, replace `engineeros-connector` in the commands below with `npx --yes @engineeros/connector@latest`.
20
+
21
+ ## Connect a workspace
22
+
23
+ In EngineerOS, open **Project steering → Connect workspace** and copy the pairing command. Run it inside your project folder. For example, with Codex:
24
+
25
+ ```sh
26
+ engineeros-connector agent codex-acp install
27
+ engineeros-connector pair PAIRING_CODE --url https://your-engineeros.example --workspace . --onboard --agent codex-acp
28
+ ```
29
+
30
+ Replace the code and server URL with the values from EngineerOS. Sign in to the agent when prompted; for Codex, run `codex login` in another terminal. Keep the connector terminal open.
31
+
32
+ Run `engineeros-connector agents` to list supported agents. Use the chosen agent's ID in both commands above; for Claude, use `claude-acp`.
33
+
34
+ Restart an already paired workspace with:
35
+
36
+ ```sh
37
+ engineeros-connector start --workspace .
38
+ ```
39
+
40
+ ## Connect Bug Hunter without a repository
41
+
42
+ Choose **Find bugs in a running app** in EngineerOS, add your target and copy its host command:
43
+
44
+ ```sh
45
+ engineeros-connector hunt-host PAIRING_CODE --url https://your-engineeros.example --project PROJECT_UUID --agent codex-acp
46
+ ```
47
+
48
+ The command prepares the agent and checks the installed browser runtime. Complete the requested agent sign-in and keep the terminal open. Browser provisioning is explicit:
49
+
50
+ ```sh
51
+ engineeros-connector tools setup playwright --project PROJECT_UUID
52
+ ```
53
+
54
+ This installs the registry's pinned Playwright runtime and matching managed Chromium. Linux setup names any required system dependencies. Connector startup and hunts only verify the runtime; they do not download browsers or substitute installed Chrome/Edge. Setup verifies a real isolated context, synthetic navigation, HTTP/WebSocket interception, state restoration, screenshot/trace capture and evidence storage. Configure test accounts, app builds and devices in Bug Hunter Setup as needed.
55
+
56
+ Public-only browsing blocks state-changing/unknown HTTP operations and WebSockets before initial navigation. Parsed, unambiguous GraphQL queries on the recognized `/graphql` endpoint may pass with JSON operation documents; mutations, subscriptions, batches, multipart and persisted/unknown documents do not. The same policy applies to explicit request steps and every browser redirect hop through Chromium response interception. Frames/popups that cannot establish this guard before network access are blocked with an unsupported-capability diagnostic. A connector-local proxy validates and pins actual socket destinations and redirects; metadata/reserved addresses remain denied. Private DNS targets need every approved private address in Allowed hosts; localhost names must resolve exclusively to loopback. Local-looking suffixes grant no private-network access. An address change requires a new authorized run. Health/version checks, launch readiness, reset hooks, schema introspection and discovery use the same guarded socket rules; public-only grants refuse launch/seed/reset effects. Cloud web browsers and Electron with protected HTTP(S) targets are blocked when this socket boundary cannot be enforced. Purely local Electron actions and native WebDriver retain their separate execution paths and are not qualified web transport coverage.
57
+
58
+ Restart the host with:
59
+
60
+ ```sh
61
+ engineeros-connector hunt-host --project PROJECT_UUID
62
+ ```
63
+
64
+ ## Connector agent defaults
65
+
66
+ Workspace assignments and Bug Hunter agent turns use the connector's shipped execution policy: concise reports, bounded reads, reuse of supplied context/memory, targeted verification, and explicit capability gaps. Required coverage, evidence, permissions and response contracts still apply. The policy is attached on a new session; continuations reuse it instead of repeating it. It does not copy this repository's development instructions into another project or create instruction/skill files there.
67
+
68
+ | Agent | Connector controls | Remaining inheritance |
69
+ | --- | --- | --- |
70
+ | Codex CLI and `codex-acp` | Disable installed plugins, apps, bundled skills and the automatic skill catalogue. Connector defaults override extension settings; ACP ignores ambient `CODEX_CONFIG`. | Authentication, provider configuration, repository rules and unrelated native settings (including separately configured MCP servers) remain available. |
71
+ | `claude-acp` | Supply empty user/project/local settings sources, plugin and skill lists; accept only session-supplied MCP configuration; disable prompt suggestions. Apply to new and loaded sessions. | Existing login and managed policy remain. Repository instructions are read explicitly when workspace work requires them. Requires an adapter supporting `claudeCode.options` session metadata. |
72
+ | Gemini | Force `--extensions none`. | Other settings and skills may still load; emit a warning. |
73
+ | OpenCode | Supply the connector tool directory; disable project config and external/Claude skill discovery; replace inherited inline config overrides. | User-level plugins and settings may still load; emit a warning. |
74
+ | Forge or custom ACP | Supply the shared execution policy. | Configuration exclusion is unsupported; emit a warning and continue. Forge retains its existing user-scope MCP registration. |
75
+
76
+ These controls apply only to connector launches. They do not edit the coding agent's global settings or copy credentials. Unsupported adapters remain usable with the warning; their extension context cannot be guaranteed. Use a current Codex or Claude ACP adapter for enforced plugin exclusions. Configuration controls reduce avoidable context; actual token savings require comparison of recorded usage for equivalent runs.
77
+
78
+ ## Troubleshoot and update
79
+
80
+ ```sh
81
+ engineeros-connector doctor --workspace .
82
+ npm install --global @engineeros/connector@latest
83
+ ```
84
+
85
+ - **Missing pairing:** copy a new pairing command from EngineerOS.
86
+ - **Agent sign-in failed:** sign in to the selected agent, then restart the connector.
87
+ - **Credential storage unavailable:** unlock or configure the protected store listed above, then restart. Headless Linux hosts also need a running Secret Service.
88
+ - **Result delivery interrupted:** completed prompt answers and failures are saved locally and retried after reconnecting. If EngineerOS permanently rejects an outcome, the terminal names the retained evidence file and reason. Keep that file when investigating; a rejected outcome does not automatically rerun the agent.
89
+ - **Uploaded input refused:** use public HTTPS storage or the hunt host's local inputs folder. Downloads reject private/metadata addresses and are limited to 25 MB and 60 seconds.
90
+
91
+ ## License
92
+
93
+ Copyright (c) 2026 [Techmirus Innovations](https://www.techmirus.com).
94
+
95
+ The [EngineerOS Connector Binary Use License](LICENSE) permits personal and commercial use of the official executable distribution. The original source remains proprietary. Third-party dependencies retain their own licenses; bundled grammar notices are in [grammars/NOTICE.md](grammars/NOTICE.md).