@securecoms/agent-bridge 0.6.0 → 0.8.0

package/dist/service/hermes-config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Strict, line-based editor for `~/.hermes/config.yaml`'s `plugins.enabled`
+ * block sequence. Hermes only loads user plugins listed there (plugins.py's
+ * loader — see spec §4), so `wire --harness hermes` must add our plugin's
+ * entry or the copied connector never runs.
+ *
+ * This module is PURE: it takes the file's text and returns either a noop
+ * (already correct / refused) or the edited text. File I/O and the
+ * `config.yaml.bak-wire-<ts>-<pid>` backup live with the caller (wire.ts /
+ * harness-wire.ts, Task 6).
+ *
+ * Hardened rules (spec §4, audited against the real production file at
+ * `config.yaml:569-573`):
+ *   1. The inserted item copies the EXISTING first item's exact column —
+ *      never `key-indent + 2`. Production shape has items at the SAME
+ *      indent as the `enabled:` key itself (a legal, if unusual, YAML block
+ *      sequence style); some configs indent items by +2. Both must work,
+ *      which is why the column is READ from the first item, never computed.
+ *   2. Insertion lands after the LAST consecutive same-column `- ` item —
+ *      stop scanning at the first line that isn't one (the boundary before
+ *      a sibling key such as `disabled: []`).
+ *   2b. Stopping the scan is not enough on its own: the line the scan
+ *      stopped at must be a LEGITIMATE list terminator before the insertion
+ *      is allowed to happen there. Legitimate means one of: (a) a sibling
+ *      key at the same column as `enabled:` itself (e.g. `disabled:`), (b)
+ *      end-of-block via blank-line(s) then a genuine dedent below the
+ *      items' column, or (c) end of file. Anything else that stops the
+ *      scan — a bare `-`, a mapping-style item (`- ` followed by an
+ *      indented `key: value` on the next line), a blank line followed by
+ *      MORE same-column items (ambiguous: did the writer mean to end the
+ *      list or just add a spacer?), or any other unrecognized content —
+ *      refuses rather than insert at a spot that was never verified to be
+ *      the list's actual end.
+ *   3. `plugins.disabled` is checked too: an entry listed there wins over
+ *      `plugins.enabled` in the loader, so refuse rather than add a second,
+ *      shadowed entry.
+ *   4. Any structural surprise — no `plugins:` block, an inline
+ *      `enabled: [...]` form, an empty enabled list, mixed-indent items, a
+ *      comment line interleaved with items (ambiguous: it could be a
+ *      trailing comment on the item above or a leading comment on the item
+ *      below), or a non-boundary list terminator (see 2b) — refuses with no
+ *      write and an actionable message. Never reformats, never touches any
+ *      other key.
+ */
+export declare const HERMES_PLUGIN_NAME = "securecoms-platform";
+export interface EnsureHermesPluginEnabledResult {
+    action: "noop" | "edited";
+    text?: string;
+    reason?: string;
+}
+export declare function ensureHermesPluginEnabled(configText: string): EnsureHermesPluginEnabledResult;

package/dist/service/install-prep.d.ts

@@ -1,4 +1,5 @@
 import { type ServiceInput } from "./config.js";
+import { type AutoWireDeps } from "./harness-wire.js";
 export interface PrepDeps {
     readFile: (p: string) => string;
     writeFileMode: (p: string, data: string, mode: number) => void;
@@ -37,13 +38,6 @@ export declare function verifyDaemonUp(args: {
     attempts?: number;
     delayMs?: number;
 }, deps: PrepDeps): Promise<boolean>;
-export declare function harnessSnippet(args: {
-    slug: string;
-    port: number;
-    tokenFilePath: string;
-    harness: string;
-    identityId: string;
-}): string;
 export interface OrchestrateInstallCtx {
     credentialAbsPath: string;
     label?: string;
@@ -52,7 +46,9 @@ export interface OrchestrateInstallCtx {
     home: string;
     launchAgentsDir?: string;
     systemdDir?: string;
+    connectorsSrcDir: string;
     prepDeps: PrepDeps;
+    autoWireDeps: AutoWireDeps;
     installService: (input: ServiceInput) => {
         label: string;
         filePath: string;
@@ -65,5 +61,6 @@ export interface OrchestrateInstallCtx {
 }
 export declare function orchestrateInstall(ctx: OrchestrateInstallCtx): Promise<{
     echo: string;
-    harnessSnippetShown: boolean;
+    harnessWired: boolean;
+    harnessError: boolean;
 }>;

package/dist/service/wire.d.ts

@@ -1,10 +1,43 @@
 import type { AgentFleetEntry } from "./fleet.js";
 export type Harness = "openclaw" | "hermes";
-export interface WireDeps {
+/**
+ * Per-harness allow-list of file extensions the copier includes when it
+ * installs a connector — openclaw ships a JS runtime, hermes ships Python
+ * (F8: a single `.js|.json` filter silently produced an EMPTY hermes install,
+ * since none of adapter.py/securecoms_transport.py/securecoms_gate.py/
+ * plugin.yaml/__init__.py matched it).
+ */
+export declare const CONNECTOR_FILE_EXTENSIONS: Record<Harness, readonly string[]>;
+/**
+ * Directory names the copier never descends into, checked AT THE DIRECTORY
+ * BRANCH before recursion (F8) — a filename-only extension filter still
+ * walks into `tests/` and would copy every `*.py` it finds there, since `.py`
+ * is itself an allow-listed hermes extension. `__pycache__` is compiled
+ * bytecode, never source, for either harness.
+ */
+export declare const CONNECTOR_SKIP_DIRS: ReadonlySet<string>;
+/** The config read/backup/write seams the Hermes `plugins.enabled` auto-edit
+ *  needs (spec §4, F4). Shared between `WireDeps` (the `wire` verb) and
+ *  `AutoWireDeps` (the `install` auto-wire path) so `enableHermesConfig`
+ *  below is the ONE implementation both paths call — never duplicated,
+ *  never skippable on just one of the two. Unused for the openclaw harness,
+ *  which has no config file to edit. */
+export interface HermesConfigIoDeps {
+    /** Returns null when the file (or its parent ~/.hermes) doesn't exist or
+     *  isn't readable — treated as a config-edit refusal, same posture as any
+     *  other structural surprise `ensureHermesPluginEnabled` reports. */
+    readHermesConfig: (path: string) => string | null;
+    /** Persists the ORIGINAL text under a `hermesConfigBackupPath` name,
+     *  called BEFORE `writeHermesConfig` — only invoked when an edit is about
+     *  to happen, never on a noop/refusal. */
+    backupHermesConfig: (path: string, originalText: string) => void;
+    writeHermesConfig: (path: string, newText: string) => void;
+}
+export interface WireDeps extends HermesConfigIoDeps {
     home: string;
     argv: string[];
     readFleet: () => AgentFleetEntry[];
-    copyConnector: (srcDir: string, dstDir: string) => void;
+    copyConnector: (srcDir: string, dstDir: string, harness: Harness) => void;
     writeBinding: (dstDir: string, identityId: string) => void;
     removeBinding: (dstDir: string) => void;
     getHealth: (port: number) => {
@@ -12,20 +45,17 @@ export interface WireDeps {
     } | null;
     log: (s: string) => void;
     /**
-     * Precomputed absolute path to the reference connector's source dir
-     * (`<pkgRoot>/connectors/openclaw`). REQUIRED: the only real caller
-     * (bin.ts's realWireDeps) always computes this via
-     * `connectorsSrcDir(import.meta.url)` using bin.ts's OWN import.meta.url —
-     * see that function's doc comment for why it has to be bin.ts's URL, not
-     * wire.ts's. A fallback that read wire.ts's own import.meta.url used to
-     * live here, but wire.ts sits one directory deeper than bin.ts
-     * (`src/service/wire.ts` vs `src/bin.ts`), so that fallback resolved to
-     * the wrong path — removed rather than fixed, since every real caller
-     * already supplies this field. Unit tests must pass a value too (any
-     * string is fine — `copyConnector` is mocked in tests and never inspects
-     * it for the non-hermes paths that reach it).
+     * Resolves a harness's connector SOURCE dir on demand, keyed by harness —
+     * Task 6 makes BOTH openclaw and hermes real installs, so a single
+     * WireDeps instance must be able to wire either one. Real callers
+     * (bin.ts's realWireDeps) supply `(h) => connectorsSrcDir(import.meta.url,
+     * h)` using bin.ts's OWN import.meta.url — see the standalone
+     * `connectorsSrcDir` function's doc comment below for why it has to be the
+     * entry point's URL, not wire.ts's own. Unit tests must pass a function
+     * too (any string-returning stub is fine — `copyConnector` is mocked in
+     * tests and never inspects the path for its own sake).
      */
-    connectorsSrcDir: string;
+    connectorsSrcDir: (harness: Harness) => string;
 }
 /**
  * Detects an installed harness by probing well-known home-relative dirs.
@@ -35,42 +65,69 @@ export interface WireDeps {
  */
 export declare function detectHarness(home: string, statDir: (p: string) => boolean): Harness | null;
 /**
- * Where the connector gets installed for a given harness. Openclaw is the
- * REFERENCE CONNECTOR (Task 6, connectors/openclaw/) and is fully wired.
- * Hermes gets a defined target path so `detectHarness`/`wire --harness hermes`
- * don't crash, but the Hermes CONNECTOR ITSELF is a fast-follow — only
- * detection + this target dir ship in this task. Do not claim a working
- * Hermes connector exists.
+ * Where the connector gets installed for a given harness. Both harnesses are
+ * real installs as of Task 6: openclaw at its `local-plugins` dir; hermes at
+ * `~/.hermes/plugins/securecoms` — the loader's actual user-plugins dir
+ * (verified against the production config; `local-plugins` was a Task 4/5
+ * placeholder value, never the real one).
  */
 export declare function connectorTargetDir(home: string, harness: Harness): string;
 /**
- * Resolves the reference connector's SOURCE dir at runtime. `connectors/` is
- * shipped SOURCE (not compiled — H2), so this must resolve from the running
- * file's location back to the package root, never into dist/. Callers pass
- * their OWN import.meta.url (bin.ts's), not wire.ts's: esbuild bundles
- * wire.ts's code into dist/bin.js, so only the entry point's import.meta.url
- * is guaranteed to sit exactly one directory below the package root in BOTH
- * dev (src/bin.ts) and the built artifact (dist/bin.js) — mirrors
- * resolve-bin.ts's loadPackageMeta (`dist/bin.js -> ../package.json`).
+ * Resolves a connector's SOURCE dir at runtime, keyed by harness (`connectors/
+ * <harness>`) — `connectors/` is shipped SOURCE (not compiled — H2), so this
+ * must resolve from the running file's location back to the package root,
+ * never into dist/. Callers pass their OWN import.meta.url (bin.ts's), not
+ * wire.ts's: esbuild bundles wire.ts's code into dist/bin.js, so only the
+ * entry point's import.meta.url is guaranteed to sit exactly one directory
+ * below the package root in BOTH dev (src/bin.ts) and the built artifact
+ * (dist/bin.js) — mirrors resolve-bin.ts's loadPackageMeta (`dist/bin.js ->
+ * ../package.json`).
+ */
+export declare function connectorsSrcDir(importMetaUrl: string, harness: Harness): string;
+/** Path to the Hermes gateway's `config.yaml`, whose `plugins.enabled` block
+ *  the auto-edit targets (spec §4). v1 targets the default `~/.hermes`
+ *  profile only — `HERMES_HOME`/secondary profiles are documented as
+ *  unsupported by `wire` in this round (spec §4 scope limit). */
+export declare function hermesConfigPath(home: string): string;
+/** Backup filename for a config.yaml auto-edit: `<path>.bak-wire-<ts>-<pid>`
+ *  (spec §4 rule 4) — unique enough per host that two `wire` runs essentially
+ *  never collide (different timestamp, or different pid at the same ms). */
+export declare function hermesConfigBackupPath(configPath: string, ts: number, pid: number): string;
+/**
+ * F4 (load-bearing): the ONE enable helper invoked from BOTH `runWire` (the
+ * `wire` verb, below) and `autoWireHarness` (the `install` auto-wire path,
+ * harness-wire.ts) — a hermes wire that copies the connector and writes the
+ * binding but skips this step is the silent half-wire the spec forbids.
+ * Reads config.yaml, runs Task 5's pure `ensureHermesPluginEnabled`, and on
+ * an actual edit backs up the ORIGINAL text before writing the new text.
+ * Never writes anything on a noop or a refusal.
  */
-export declare function connectorsSrcDir(importMetaUrl: string): string;
+export declare function enableHermesConfig(home: string, deps: HermesConfigIoDeps): {
+    ok: boolean;
+    message: string;
+};
 /**
  * Installs the reference connector into the harness's plugin dir and drops
  * an explicit securecoms.binding.json naming the resolved agent's identity.
  * There is NO auto-discovery (audit C1): the binding is written for EVERY
  * agent, singleton included, every time `wire` runs.
  *
- * Hermes has no real connector yet (this round only ships detection +
- * `connectorTargetDir`, see that function's doc comment) — refuse rather
- * than install the openclaw connector's files into a Hermes plugin dir,
- * which would be a false "installed" success.
+ * Hermes (Task 6) additionally needs its `~/.hermes/config.yaml`
+ * `plugins.enabled` entry (F4's `enableHermesConfig`, shared with
+ * autoWireHarness) — Hermes only loads plugins listed there, so the copy +
+ * binding alone would leave the connector inert. If that edit refuses (no
+ * `plugins:` block, an already-disabled entry, an ambiguous list shape, or a
+ * missing config.yaml entirely), the copy and binding REMAIN on disk — they
+ * are harmless without the enable — but `wire` exits non-zero with the
+ * manual-edit instructions, so callers see harness-NOT-wired rather than a
+ * silent half-wire.
  */
 export declare function runWire(deps: WireDeps): number;
 /** Removes the explicit binding for the resolved agent. Leaves the copied
- *  connector files in place — unwire un-names the agent, it doesn't uninstall
- *  the plugin (that stays a harness-native operation).
- *
- *  Hermes never has anything installed by `runWire` (see its hermes guard),
- *  so there's nothing to remove — no-op cleanly rather than call
- *  `removeBinding` against a dir that was never created. */
+ *  connector files (and, for hermes, the config.yaml plugin entry) in place
+ *  — unwire un-names the agent, it doesn't uninstall the plugin (that stays
+ *  a harness-native operation). For hermes specifically: removing the
+ *  installed files while config.yaml still lists the plugin would make
+ *  Hermes log load errors at boot, so the copy AND the config entry both
+ *  deliberately remain — printed as explicit manual-cleanup instructions. */
 export declare function runUnwire(deps: WireDeps): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",