pi-onlyne 0.2.3 → 0.2.4

package/README.md

@@ -1,14 +1,34 @@
 # pi-onlyne
 
-Pi extension for using Onlyne as a workspace-local messaging bridge.
+**Give pi agents a real IM inbox/outbox through [Onlyne](https://github.com/dbydd/onlyne).**
 
-## What it does
+`pi-onlyne` is the Pi extension for Onlyne. It adds tools and commands to pi so an agent can receive messages from IM channels and send replies without pretending that a chat platform is a terminal, a browser tab, or a custom workflow engine.
 
-- Watches an existing Onlyne workspace.
-- Starts Onlyne for the current workspace when requested.
-- Subscribes to inbound channel events without polling.
-- Lets the agent reply, send, or broadcast messages through tools.
-- Keeps config in the project, not in global home state.
+## What is Onlyne?
+
+[Onlyne](https://github.com/dbydd/onlyne) is a small workspace-local IM channel daemon. It runs in your project directory, keeps its config/state under `.onlyne/`, and brokers local agent calls to real messaging adapters such as Telegram, Feishu/Lark, QQ Bot, and WeChat.
+
+Onlyne is deliberately narrow:
+
+- local workspace daemon, not a global cloud service
+- channel broker, not an agent runtime
+- Unix socket / stdio friendly, not a web dashboard
+- local history and event stream, not a heavy message platform
+
+## What does this extension do?
+
+`pi-onlyne` connects pi to an existing Onlyne workspace and exposes Onlyne as native pi tools.
+
+With this extension, a pi agent can:
+
+- watch an Onlyne workspace for inbound IM messages
+- surface inbound messages into the current pi session
+- reply to the current inbound message
+- send a message to a specific channel conversation
+- broadcast the same message to multiple conversations
+- mark an inbound message as intentionally not replied
+
+Messages are Markdown by default, matching normal agent output. Use `rawText: true` only when the message must be sent literally.
 
 ## Install
 
@@ -16,16 +36,35 @@ Pi extension for using Onlyne as a workspace-local messaging bridge.
 pi install npm:pi-onlyne
 ```
 
-For a one-off run:
+For a one-off run without installing:
 
 ```bash
 pi -e npm:pi-onlyne
 ```
 
-## Requirements
+You also need the `onlyne` CLI installed and an initialized workspace:
+
+```bash
+onlyne init
+```
+
+If `onlyne` is not on `PATH`, set:
+
+```bash
+export ONLYNE_BIN=/path/to/onlyne
+```
+
+## Typical workflow
+
+1. Initialize/configure Onlyne in your project.
+2. Install this Pi extension.
+3. Start watching from pi:
+
+```text
+/onlyne watch on
+```
 
-- `onlyne` available on `PATH`, or set `ONLYNE_BIN`.
-- A workspace with `.onlyne/` already initialized.
+When a message arrives through Onlyne, pi receives it as a follow-up message. The agent can then call `onlyne_reply`, or deliberately call `onlyne_mark_no_reply`.
 
 ## Commands
 
@@ -42,13 +81,59 @@ pi -e npm:pi-onlyne
 onlyne_reply({ text })
 onlyne_send({ channelId, conversationId, text, rawText? })
 onlyne_broadcast({ targets, text, rawText? })
-onlyne_mark_no_reply({ reason })
+onlyne_mark_no_reply({ reason? })
+```
+
+### Send one message
+
+```ts
+onlyne_send({
+  channelId: "telegram",
+  conversationId: "123456",
+  text: "# Build report\n\nAll checks passed."
+})
 ```
 
-Messages default to Markdown. Set `rawText: true` only when the text must be sent literally.
+### Send literal text
+
+```ts
+onlyne_send({
+  channelId: "telegram",
+  conversationId: "123456",
+  text: "# not a heading",
+  rawText: true
+})
+```
+
+### Broadcast
+
+```ts
+onlyne_broadcast({
+  targets: [
+    { channelId: "telegram", conversationId: "123456" },
+    { channelId: "feishu", conversationId: "oc_xxx" }
+  ],
+  text: "# Release shipped\n\nVersion 0.2.3 is live."
+})
+```
+
+## Local state
+
+This extension stores its own pi-side config at:
+
+```text
+.pi/onlyne.json
+```
+
+Onlyne itself stores workspace state under:
+
+```text
+.onlyne/
+```
 
-## Config
+That keeps each project isolated: different workspaces can run different Onlyne daemons, channels, histories, and policies.
 
-Project-local config lives at `.pi/onlyne.json`. Defaults are safe: watch is manual, inbound messages auto-handle once watch is on, and outbound reply fallback is guarded.
+## Links
 
-See `SPEC.md` for behavior details.
+- Onlyne main repository: https://github.com/dbydd/onlyne
+- pi-onlyne package: https://www.npmjs.com/package/pi-onlyne

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Pi extension tools for sending messages through Onlyne.",
   "type": "module",
   "main": "./dist/index.js",