ompclaw 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.3.0 (2026-08-30)
+
+### Changed
+
+- Renamed the product, npm package, CLI, repository, service identifiers, default profile, state paths, environment prefix, and OMP host tools from `omp-gateway` to OmpClaw.
+- The new package and command are `ompclaw`; the renamed surfaces intentionally provide no legacy aliases.
+
+### Migration
+
+- Stop and uninstall the old service before installing `com.ompclaw` or `ompclaw.service`.
+- Move the prior state directory to `~/.omp/agent/ompclaw`, rename `gateway.sqlite` and `gateway.lock` to `ompclaw.sqlite` and `ompclaw.lock`, change the old default `gateway` profile to `ompclaw`, and rename `OMP_GATEWAY_*` environment variables to `OMPCLAW_*`. Keep an explicitly configured custom profile unchanged.
+
+## 0.2.0 (2026-08-30)
+
+### Added
+
+- Durable principal-scoped one-shot and cron jobs with timezone validation, bounded retry, restart recovery, Telegram command controls, and OMP host tools.
+- Opt-in gateway-scoped Mnemopi memory and experimental auto-learn skill capture.
+- Read-only inherited harness snapshots that refresh desktop skills, rules, commands, agents, docs, and binaries without sharing runtime state or credentials.
+
+### Changed
+
+- Scheduled and interactive work now share one explicitly serialized OMP runtime and delivery context.
+- Gateway configuration and operator documentation exposed automation, learning, isolation, and at-least-once delivery boundaries.
+
+## 0.1.0 (2026-08-30)
+
+### Alpha
+
+- Initial alpha release of the authenticated Telegram and WebSocket gateway, persistent OMP RPC runtime, SQLite state store, interactive UI bridge, host tools, and user-service installers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omp-telegram contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,10 @@
+OmpClaw
+
+This package includes and adapts work from omp-telegram:
+
+  omp-telegram
+  https://github.com/TerrifiedBug/omp-telegram
+  Copyright (c) omp-telegram contributors
+  Licensed under the MIT License
+
+TerrifiedBug/omp-telegram is the upstream provenance for the adapted Telegram bridge and OMP RPC service work. Its MIT provenance is preserved. The full MIT license for this package is in LICENSE.

package/README.md

@@ -0,0 +1,152 @@
+# OmpClaw
+
+[![CI](https://github.com/wolfiesch/ompclaw/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/wolfiesch/ompclaw/actions/workflows/ci.yml?query=branch%3Amain)
+[![npm package](https://img.shields.io/badge/npm-ompclaw-CB3837?logo=npm)](https://www.npmjs.com/package/ompclaw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Status: Alpha.** OmpClaw is a Bun package for operators who need one persistent [Oh My Pi](https://github.com/can1357/oh-my-pi) 17+ session reachable through Telegram and authenticated WebSocket clients. It deliberately has one session owner and one state writer, rather than creating separate agent processes for each chat or client.
+
+Use it when a single trusted operator needs remote access to an OMP workspace without placing transport credentials in OMP configuration or handing clients an OMP process directly. Telegram and WebSocket are adapters around the same authenticated session. HTTP is health-only.
+
+- **Package:** [`ompclaw`](https://www.npmjs.com/package/ompclaw) `0.3.0`
+- **Repository:** [`wolfiesch/ompclaw`](https://github.com/wolfiesch/ompclaw)
+- **License:** [MIT](LICENSE)
+- **Upstream provenance:** [TerrifiedBug/omp-telegram](https://github.com/TerrifiedBug/omp-telegram), preserved in [NOTICE](NOTICE)
+
+## User quickstart
+
+### Prerequisites
+
+- [Bun](https://bun.sh/)
+- `omp` 17.0.0 or newer, authenticated for the provider you intend to use
+- A Telegram bot token if Telegram is enabled
+
+Install the package:
+
+```bash
+bun add --global ompclaw
+ompclaw --help
+```
+
+Create a token-free JSON configuration. Run the command from the OMP workspace you want the gateway to use, or replace the example workspace path with an absolute path.
+
+```bash
+mkdir -p ~/.config/ompclaw
+cat > ~/.config/ompclaw/config.json <<'JSON'
+{
+  "workspace": "~/path/to/workspace",
+  "stateDir": "~/.omp/agent/ompclaw",
+  "profile": "ompclaw",
+  "omp": {
+    "command": "omp",
+    "autoRestart": true
+  },
+  "transports": {
+    "telegram": {
+      "enabled": true,
+      "account": "default",
+      "tokenEnv": "TELEGRAM_BOT_TOKEN"
+    },
+    "websocket": {
+      "enabled": true,
+      "hostname": "127.0.0.1",
+      "port": 8787,
+      "account": "local",
+      "credentials": [
+        {
+          "tokenEnv": "OMPCLAW_WS_TOKEN",
+          "subject": "local-operator",
+          "channel": "local"
+        }
+      ]
+    }
+  },
+  "automation": {
+    "enabled": true
+  },
+  "learning": {
+    "enabled": true,
+    "autoCapture": true,
+    "memoryModel": "online"
+  }
+}
+JSON
+```
+
+Put token values only in a private environment file. The values below are placeholders, not usable credentials.
+
+```bash
+cat > ~/.config/ompclaw/ompclaw.env <<'ENV'
+TELEGRAM_BOT_TOKEN=replace-with-telegram-bot-token
+OMPCLAW_WS_TOKEN=replace-with-a-long-random-websocket-token
+ENV
+chmod 600 ~/.config/ompclaw/ompclaw.env
+```
+
+Authorize the Telegram operator and the example local WebSocket identity. Set `TELEGRAM_USER_ID` to the numeric ID of the person you intend to authorize.
+
+```bash
+TELEGRAM_USER_ID=123456789
+ompclaw telegram-allow "$TELEGRAM_USER_ID" \
+  --config ~/.config/ompclaw/config.json
+ompclaw principal-add local-operator \
+  --config ~/.config/ompclaw/config.json
+ompclaw identity-bind websocket local local-operator local-operator \
+  --config ~/.config/ompclaw/config.json
+```
+
+The first command prints `Telegram user allowed as telegram:default:<numeric-user-id>`. The identity commands print the updated principal and binding.
+
+Validate credentials, the SQLite store, Telegram reachability, and a short OMP RPC session before starting the gateway:
+
+```bash
+ompclaw doctor \
+  --config ~/.config/ompclaw/config.json \
+  --env-file ~/.config/ompclaw/ompclaw.env
+```
+
+When Telegram is enabled, successful output includes the bot identity, `Webhook: none (...)`, the OMP RPC protocol and session, and ends with:
+
+```text
+Doctor: ready
+```
+
+Start the foreground gateway:
+
+```bash
+ompclaw run \
+  --config ~/.config/ompclaw/config.json \
+  --env-file ~/.config/ompclaw/ompclaw.env
+```
+
+The process owns the OMP session until it receives `SIGINT` or `SIGTERM`. Telegram starts long polling. The WebSocket endpoint accepts authenticated connections at `ws://127.0.0.1:8787/`; `GET /healthz` returns `{"status":"ok"}`.
+
+To install it as a user service instead, use the same validated files:
+
+```bash
+ompclaw service-install \
+  --config ~/.config/ompclaw/config.json \
+  --env-file ~/.config/ompclaw/ompclaw.env
+```
+
+The command reports `Installed and started <manager> service: <path>`. It installs launchd label `com.ompclaw` on macOS or user systemd unit `ompclaw.service` on Linux.
+
+## What the gateway provides
+
+- One authenticated OMP RPC session with streamed assistant updates and a final response routed only to the active authenticated conversation.
+- OMP commands for steering, follow-up, abort, models, thinking, session controls, queue policy, compaction, retries, subagents, history, branching, exports, and login.
+- Telegram long polling with durable update checkpoints, message editing, buttons, file intake, reactions, topics, and interactive OMP UI.
+- An authenticated versioned WebSocket protocol with client identity and conversation address derived from configured credential metadata, not client-supplied fields.
+- SQLite-backed principals, transport identities, conversation bindings, OMP session checkpointing, inbound deduplication, UI state, durable scheduled jobs, and legacy Telegram migration markers.
+- Optional unattended automation with one-shot and cron schedules, explicit timezone support, bounded retries, restart recovery, per-principal ownership, and natural-language job control through OMP host tools.
+- Optional experimental Mnemopi memory and auto-learn capture in OmpClaw-owned state. Inherited desktop skills are refreshed into a read-only snapshot, while gateway-created managed skills and memory remain isolated in the named OMP profile.
+
+Read the [operator guide](docs/guide.md) for configuration, migration, operations, and security boundaries. Read the [RPC and transport reference](docs/rpc-service.md) for the command and protocol matrix.
+
+## Contributors
+
+Package installation above is for operators. Source checkout, development conventions, and verification commands are intentionally separate in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License and notice
+
+`ompclaw` is MIT licensed. It includes and adapts work from TerrifiedBug's MIT-licensed `omp-telegram`; see [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/SECURITY.md

@@ -0,0 +1,61 @@
+# Security policy
+
+## Supported versions
+
+OmpClaw is Alpha. Security fixes are considered for the newest published release only. There is no guaranteed response or remediation timeline during Alpha. If a security fix requires an upgrade, use the newest release rather than expecting backports.
+
+## Report a vulnerability privately
+
+Do not open a public issue, discussion, pull request, or chat message for a suspected vulnerability. Use GitHub's private vulnerability reporting flow for this repository:
+
+<https://github.com/wolfiesch/ompclaw/security/advisories/new>
+
+A useful report includes:
+
+- affected package version and operating system;
+- a minimal reproduction or proof of concept;
+- the impact and attack preconditions;
+- whether an attacker needs local host access, a Telegram account, a WebSocket token, or network access;
+- relevant logs and configuration with every token, user ID, hostname, workspace path, and session path removed.
+
+Please allow maintainers to investigate and prepare a fix before public disclosure. Do not publish exploit details, working credentials, session files, or a bypass while the report is being handled.
+
+## Threat model
+
+The gateway is designed for one trusted operator environment:
+
+- It runs one OMP RPC child process for one configured workspace and profile.
+- A transport identity must resolve to a principal recorded in the local SQLite store before its inbound message reaches OMP.
+- Telegram sender identity is obtained from the Telegram update. WebSocket identity and conversation address are derived from the configured credential, never from client message fields.
+- A live WebSocket connection is limited to one configured conversation origin. Gateway delivery is constrained to the active principal and origin.
+- The JSON configuration contains paths and environment-variable names, not token values. Transport-secret environment variables are removed before the OMP child starts.
+- The gateway locks its state directory so a second gateway process cannot become another state writer. The Telegram adapter separately locks one polling account. Durable automation remains scoped to the principal and conversation derived when the job was created.
+
+The gateway does **not** make an OMP workspace safe for untrusted operators. An authorized principal can cause prompts to be processed by OMP with the authority of the configured OMP profile, workspace, tools, and provider credentials. Treat granting a Telegram allowance or binding a WebSocket identity as granting access to that environment.
+
+The gateway does not defend against a compromised host, another process running as the same operating-system user, stolen provider credentials, a stolen Telegram account, a stolen WebSocket token, a malicious OMP plugin or MCP server, or a compromised client device. It also does not provide end-to-end encryption beyond the transport guarantees supplied by Telegram or your own network deployment.
+
+## Deployment hardening
+
+1. Run the gateway under a dedicated, non-administrator user when practical. Limit that user's workspace, SSH, network, and provider access to what the session requires.
+2. Keep the default WebSocket bind address on loopback, such as `127.0.0.1`. Do not expose the WebSocket port directly to an untrusted network.
+3. If remote WebSocket access is required, put it behind a TLS-terminating, access-controlled network boundary. Restrict firewall rules and protect the client token in transit. Do not rely on the health endpoint as authentication.
+4. Use distinct high-entropy WebSocket tokens for each configured credential. Bind each credential subject explicitly to the intended principal with `identity-bind`.
+5. Allow only the specific Telegram user IDs that should operate the session. Keep Telegram in long-polling mode and resolve any configured webhook before starting the gateway. `doctor` checks for this conflict.
+6. Keep one gateway process and one Telegram poller per bot token. Do not share the state directory, token, or SQLite file among instances.
+7. Leave `omp.allowRpcBash` disabled unless the operator has deliberately accepted the authority granted to OMP RPC bash commands.
+8. Treat unattended scheduled prompts as standing authorization to use the configured OMP environment. Make prompts with external side effects idempotent, pause jobs that no longer need to run, and remove obsolete jobs.
+9. Leave experimental learning disabled unless the operator accepts automatic provider use and gateway-profile managed-skill mutation. Review learned skills before using them in consequential automation.
+10. Keep Bun, OMP, the gateway, operating system, and any reverse proxy current with their security updates.
+
+## Secret handling
+
+- Put Telegram and WebSocket token values in a separate environment file passed with `--env-file`; use only variable names in the JSON configuration.
+- The environment file must be a regular file, owned by the current user, with mode `0600` or stricter on supported Unix systems. Do not commit it, upload it, or paste it into issue reports.
+- The SQLite database stores principals, bindings, checkpoints, deduplication records, pending UI metadata, and durable job prompts and outcomes. Experimental learning also writes gateway-private memory data and managed skills. Treat the state directory and every backup as sensitive.
+- Do not put provider tokens, bot tokens, WebSocket tokens, session exports, or private attachment files in source control, service definitions, shell history, screenshots, or telemetry.
+- Rotate a token and restart the gateway if you suspect disclosure. Review and remove its principal binding if the associated operator should no longer have access.
+
+## Safe disclosure and remediation
+
+Maintainers may ask for a sanitized reproducer or a private follow-up through the GitHub advisory. Before sharing anything, replace token values, numeric user IDs, hostnames, workspace paths, session paths, attachment contents, and message text with safe placeholders. After a fix is available, coordinate a public advisory that describes affected versions, impact, mitigations, and upgrade guidance without publishing secrets or operational data.

package/config.example.json

@@ -0,0 +1,45 @@
+{
+  "workspace": ".",
+  "stateDir": "~/.omp/agent/ompclaw",
+  "profile": "ompclaw",
+  "omp": {
+    "command": "omp",
+    "configFiles": [],
+    "args": [],
+    "allowRpcBash": false,
+    "inheritHarness": false,
+    "autoRestart": true
+  },
+  "transports": {
+    "telegram": {
+      "enabled": true,
+      "account": "default",
+      "tokenEnv": "TELEGRAM_BOT_TOKEN"
+    },
+    "websocket": {
+      "enabled": true,
+      "hostname": "127.0.0.1",
+      "port": 7788,
+      "account": "local",
+      "credentials": [
+        {
+          "tokenEnv": "OMPCLAW_WEBSOCKET_TOKEN",
+          "subject": "local-client",
+          "channel": "ompclaw"
+        }
+      ]
+    }
+  },
+  "automation": {
+    "enabled": false,
+    "pollIntervalMs": 1000,
+    "retryDelayMs": 15000,
+    "maxAttempts": 3
+  },
+  "learning": {
+    "enabled": false,
+    "autoCapture": false,
+    "minToolCalls": 5,
+    "memoryModel": "online"
+  }
+}