@securecoms/agent-runtime 0.1.0

package/PROVENANCE.md

@@ -0,0 +1,28 @@
+# Provenance
+
+This package is a first-party agent runtime for SecureComs. Some brain logic
+(LLM dispatch loop, memory, skill invocation, tool running, config shape) is
+ported from `agentvault-federal`'s `packages/agent-runtime/src/`, which is
+read-only reference material — never a dependency. The `@agentvault/*` cord
+is cut: no runtime import of any `@agentvault/*` package, `apiUrl`, or
+`deviceJwt` concept survives the port (enforced by
+`src/no-agentvault-deps.test.ts`).
+
+Source repo HEAD at the time of cloning: `dda9700cf2e68dfd7f3d341c6794e097c298c6c4`
+(`git -C ~/projects/agentvault-federal rev-parse HEAD`).
+
+| file | source (agentvault-federal path) | source SHA | last reviewed |
+| --- | --- | --- | --- |
+| `src/llm-dispatch.ts` | `packages/agent-runtime/src/llm-dispatch.ts` | dda9700cf2e68dfd7f3d341c6794e097c298c6c4 | 2026-09-08 |
+| `src/memory.ts` | `packages/agent-runtime/src/memory.ts` | dda9700cf2e68dfd7f3d341c6794e097c298c6c4 | 2026-09-08 |
+| `src/skill-invoker.ts` | `packages/agent-runtime/src/skill-invoker.ts` | dda9700cf2e68dfd7f3d341c6794e097c298c6c4 | 2026-09-08 |
+| `src/tool-runner.ts` | `packages/agent-runtime/src/tool-runner.ts` | dda9700cf2e68dfd7f3d341c6794e097c298c6c4 | 2026-09-08 |
+| `src/config.ts` | `packages/agent-runtime/src/config.ts` | dda9700cf2e68dfd7f3d341c6794e097c298c6c4 | 2026-09-08 — shape only — federal fields removed |
+| `src/turn-loop.ts` | `packages/agent-runtime/src/index.ts` (handler, lines ~132–214) | dda9700cf2e68dfd7f3d341c6794e097c298c6c4 | 2026-09-08 — handler loop ported; gate step added |
+
+Note: `tool-gate-hook.ts` in the source repo is **re-implemented**, not
+cloned — a later task rebuilds the tool-gate behavior against this package's
+own transport, so no row is seeded for it here.
+
+This table is complete as of 2026-09-08 and should be re-reviewed if the
+source repo's files move or are re-cut.

package/README.md

@@ -0,0 +1,126 @@
+# @securecoms/agent-runtime
+
+A first-party SecureComs agent. It attaches to the local SecureComs daemon
+and runs a BYO (bring-your-own) OpenAI-compatible LLM against incoming
+messages, with skills, per-channel memory, and a local tool gate — no
+AgentVault backend involved.
+
+## Install and run
+
+```
+npm i -g @securecoms/agent-runtime
+securecoms-agent --identity <identity_id>
+```
+
+`<identity_id>` (or `SECURECOMS_IDENTITY`) selects which local daemon
+connection this process serves.
+
+## Running it at login (service install)
+
+```
+securecoms-agent install --identity <identity_id> [--llm-endpoint <url>] \
+  [--llm-model <model>] [--llm-key-file <path>] [--skills-dir <dir>] \
+  [--data-dir <dir>] [--exec-path <node>]
+securecoms-agent install --identity <identity_id> --dry-run
+securecoms-agent uninstall --identity <identity_id>
+```
+
+Every install flag also reads its `SECURECOMS_*` variable from the environment
+when the flag is absent (`SECURECOMS_IDENTITY`, `SECURECOMS_LLM_ENDPOINT`,
+`SECURECOMS_LLM_MODEL`, `SECURECOMS_LLM_API_KEY_FILE`, `SECURECOMS_SKILLS_DIR`,
+`SECURECOMS_DATA_DIR`), so an operator who already exports the run-mode
+environment can just run `securecoms-agent install`. The flag always wins.
+`--exec-path` is the one exception: it is never taken from the environment.
+`--dry-run` prints the resolved Node path, the service file path, the log
+path, the key file, and the rendered plist/unit **without writing anything or
+calling `launchctl`/`systemctl`** — use it to inspect an install before making
+it.
+
+`install` writes a per-user service that starts the agent at login and
+restarts it on crash — a launchd LaunchAgent at
+`~/Library/LaunchAgents/com.securecoms.agent.<slug>.plist` on macOS (logs at
+`~/Library/Logs/securecoms-agent-<slug>.log`), a systemd `--user` unit at
+`~/.config/systemd/user/securecoms-agent-<slug>.service` on Linux
+(`journalctl --user -u securecoms-agent-<slug> -f`). `<slug>` is the first
+eight characters of the identity when they are lowercase hex (the usual case:
+identities are UUIDs), otherwise the whole identity slugified to
+`[a-z0-9-]`. Any other platform is refused.
+
+Only the non-secret settings you pass are baked into the service definition,
+under their `SECURECOMS_*` names; anything you omit falls back to the
+runtime's own default. **The installer never accepts or writes an API key
+value — only `--llm-key-file <path>`**, so no secret reaches the plist, the
+unit file, or a process listing. If `--llm-key-file` is given, install checks the file is
+readable and refuses otherwise — a key file the agent cannot read would make
+it exit 2 on every start, and the service manager would restart-loop that
+failure.
+
+The Node interpreter baked into the service must survive a reboot and an
+upgrade, so install does not simply use the Node you ran it with: a path whose
+location encodes a version (a Homebrew Cellar keg, or nvm/asdf/fnm/volta/n) is
+resolved to a stable equivalent — `/usr/local/bin/node`,
+`/opt/homebrew/bin/node`, `/opt/homebrew/opt/node/bin/node`, `/usr/bin/node`,
+or `~/.local/bin/node`, preferring one that is the same real file as the Node
+you ran, and requiring Node >= 22 on the running architecture. If no stable
+Node exists, install refuses and tells you to install one or pass
+`--exec-path <path>`, which overrides the choice outright.
+
+## Connection and identity
+
+The runtime never reads a token from the environment. It reads the
+connection file at `~/.securecoms/connections/<identity_id>.json`, which
+names a token file on disk; the token itself is read from that file, not
+passed on the command line or in an env var. Before any socket opens, the
+runtime checks a two-anchor identity gate: the identity baked into this
+process (from `--identity`/`SECURECOMS_IDENTITY`) must match both the
+identity recorded in the connection file and the identity the local daemon
+reports on its health endpoint. Any mismatch refuses the connection outright.
+
+## Configuration
+
+All configuration is via `SECURECOMS_*` environment variables (see
+`src/config.ts` for the source of truth):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SECURECOMS_IDENTITY` | — (or `--identity <id>`) | Which local daemon connection to serve |
+| `SECURECOMS_LLM_ENDPOINT` | `http://127.0.0.1:11434` | Base URL of an OpenAI-compatible LLM server, with or without a trailing `/v1` |
+| `SECURECOMS_LLM_MODEL` | `llama3` | Model name to request |
+| `SECURECOMS_LLM_API_KEY` | unset | API key for the LLM endpoint, if it requires one |
+| `SECURECOMS_LLM_API_KEY_FILE` | unset (or `--llm-key-file <path>`) | File holding the API key (trimmed on read). Preferred: it wins over `SECURECOMS_LLM_API_KEY`, and it is the only key form the service installer accepts. An unreadable or empty file exits 2 |
+| `SECURECOMS_SKILLS_DIR` | this package's own `skills/` | Directory of skill manifests to load |
+| `SECURECOMS_DATA_DIR` | `~/.securecoms/agent-runtime` | Root directory for per-channel state |
+| `SECURECOMS_LOG_LEVEL` | `info` | One of `debug`, `info`, `warn`, `error` |
+| `SECURECOMS_TOOL_ALLOW` | `echo` | Comma-separated tool allow-list |
+| `SECURECOMS_TOOL_DENY` | unset | Comma-separated tool deny-list (wins over allow) |
+| `SECURECOMS_TOOL_DEFAULT` | `deny` | Fallback policy for a tool matched by neither list |
+
+## Memory
+
+Memory is local only, never sent anywhere but the configured LLM endpoint,
+and scoped per channel under `<dataDir>/channels/<channel>/` — one channel's
+history and captured memories never leak into another channel's turn.
+
+## Adding a skill
+
+Drop a manifest under `SECURECOMS_SKILLS_DIR`, either as a flat
+`<skillsDir>/<name>.json` file or as `<skillsDir>/<dir>/manifest.json`. A
+manifest needs `name`, `description`, a JSON-Schema `parameters` object, and
+a `handler`:
+
+- `builtin:<name>` — one of the runtime's built-in handlers (currently
+  `echo`, `timestamp`).
+- `script:<path>` — an executable file, path relative to `skillsDir` and
+  contained within it (symlinks included — a link that resolves outside
+  `skillsDir` is refused). It runs with its arguments as JSON on stdin, cwd
+  set to `skillsDir`, and a minimal environment (no inherited secrets).
+
+A manifest with any other handler shape is skipped with a warning, and a
+skill invocation that throws is turned into a `tool_failed` tool message
+rather than dropping the turn.
+
+## Provenance
+
+See [PROVENANCE.md](./PROVENANCE.md) for which files were ported from
+`agentvault-federal`'s reference `agent-runtime` package and how the
+AgentVault package-dependency cord was cut.