pi-onlyne 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dbydd
+
+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/README.md

@@ -0,0 +1,42 @@
+# pi-onlyne
+
+Pi extension for using Onlyne as a workspace-local messaging bridge.
+
+## What it does
+
+- 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.
+
+## Requirements
+
+- `onlyne` available on `PATH`, or set `ONLYNE_BIN`.
+- A workspace with `.onlyne/` already initialized.
+
+## Commands
+
+```text
+/onlyne status
+/onlyne watch on
+/onlyne watch off
+/onlyne config auto-start
+```
+
+## Agent tools
+
+```text
+onlyne_reply({ text })
+onlyne_send({ channelId, conversationId, text, rawText? })
+onlyne_broadcast({ targets, text, rawText? })
+onlyne_mark_no_reply({ reason })
+```
+
+Messages default to Markdown. Set `rawText: true` only when the text must be sent literally.
+
+## Config
+
+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.
+
+See `SPEC.md` for behavior details.

package/SPEC.md

@@ -0,0 +1,46 @@
+# pi-onlyne SPEC
+
+## Scope
+
+Pi extension for Onlyne. Onlyne remains a workspace-local IM broker; this extension owns Pi session lifecycle, watch behavior, message injection, send tools, and a small config surface.
+
+## v1 Decisions
+
+- Watch is configurable; default manual.
+- `watch on` first connects to existing `.onlyne/run/onlyne.sock`; if unavailable, spawns `onlyne --workspace <root> run`.
+- Extension-owned daemon is killed on `watch off`, `session_shutdown`, or process signal.
+- Inbound events come from Onlyne `subscribe_events`; no polling.
+- Inbound mode is rule-based: `auto-handle`, `queue-only`, or `muted`.
+- Outbound defaults to `guarded-explicit`: prefer tool reply, fallback to final text, else send configured error text.
+- Send tools default to Markdown and may pass `raw_text: true` to Onlyne for literal text.
+- Broadcast sends concurrently with per-target retry and per-target results.
+
+## Config
+
+Stored in project `.pi/onlyne.json`:
+
+```json
+{
+  "watch": { "autoStart": false },
+  "inbound": { "defaultMode": "auto-handle", "rules": [] },
+  "outbound": {
+    "defaultReplyMode": "guarded-explicit",
+    "guardedExplicit": { "reminders": 2, "noOutputFallbackText": "Onlyne/Pi error: no valid reply was produced." },
+    "retry": { "attempts": 2, "concurrency": 8 }
+  }
+}
+```
+
+## Tools
+
+- `onlyne_reply({ text })`
+- `onlyne_send({ channelId, conversationId, text, rawText? })`
+- `onlyne_broadcast({ targets, text, rawText? })`
+- `onlyne_mark_no_reply({ reason? })`
+
+## Deferred
+
+- Attachments.
+- Auth QR/secret editing TUI.
+- Schedules.
+- Target groups.

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+export type InboundMode = "auto-handle" | "queue-only" | "muted";
+export type ReplyMode = "guarded-explicit" | "explicit-only" | "implicit-final";
+export interface OnlyneRule {
+    channel: string;
+    conversation?: string;
+    mode: InboundMode;
+}
+export interface OnlyneConfig {
+    watch: {
+        autoStart: boolean;
+    };
+    inbound: {
+        defaultMode: InboundMode;
+        rules: OnlyneRule[];
+    };
+    outbound: {
+        defaultReplyMode: ReplyMode;
+        guardedExplicit: {
+            reminders: number;
+            noOutputFallbackText: string;
+        };
+        retry: {
+            attempts: number;
+            concurrency: number;
+        };
+    };
+}
+export declare const defaultConfig: OnlyneConfig;
+export declare function configPath(cwd: string): string;
+export declare function loadConfig(cwd: string): OnlyneConfig;
+export declare function saveConfig(cwd: string, config: OnlyneConfig): void;
+export declare function inboundModeFor(config: OnlyneConfig, channel: string, conversation?: string): InboundMode;

package/dist/config.js

@@ -0,0 +1,19 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const defaultConfig = {
+    watch: { autoStart: false },
+    inbound: { defaultMode: "auto-handle", rules: [] },
+    outbound: { defaultReplyMode: "guarded-explicit", guardedExplicit: { reminders: 2, noOutputFallbackText: "Onlyne/Pi error: no valid reply was produced." }, retry: { attempts: 2, concurrency: 8 } },
+};
+export function configPath(cwd) { return join(cwd, ".pi", "onlyne.json"); }
+export function loadConfig(cwd) {
+    const path = configPath(cwd);
+    if (!existsSync(path))
+        return structuredClone(defaultConfig);
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return { ...structuredClone(defaultConfig), ...parsed, watch: { ...defaultConfig.watch, ...parsed.watch }, inbound: { ...defaultConfig.inbound, ...parsed.inbound, rules: parsed.inbound?.rules ?? [] }, outbound: { ...defaultConfig.outbound, ...parsed.outbound, guardedExplicit: { ...defaultConfig.outbound.guardedExplicit, ...parsed.outbound?.guardedExplicit }, retry: { ...defaultConfig.outbound.retry, ...parsed.outbound?.retry } } };
+}
+export function saveConfig(cwd, config) { const path = configPath(cwd); mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`); }
+export function inboundModeFor(config, channel, conversation) {
+    return config.inbound.rules.find((r) => r.channel === channel && r.conversation === conversation)?.mode ?? config.inbound.rules.find((r) => r.channel === channel && !r.conversation)?.mode ?? config.inbound.defaultMode;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function onlyne(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,78 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { broadcast, connectOrSpawn, sendWithRetry, stopProcess, subscribe } from "./onlyne.js";
+import { inboundModeFor, loadConfig, saveConfig } from "./config.js";
+import { findWorkspace } from "./workspace.js";
+const state = { cwd: process.cwd(), workspace: null, watching: false, owner: "stopped" };
+const textResult = (text, details) => ({ content: [{ type: "text", text }], details });
+const currentConfig = () => loadConfig(state.cwd);
+function inboundText(data) { const msg = data?.data?.data ?? data?.data ?? data; const channelId = msg.channel_id ?? msg.channelId; const conversationId = msg.conversation_id ?? msg.conversationId; const text = msg.text ?? msg.content ?? msg.body; return channelId && conversationId && typeof text === "string" ? { channelId, conversationId, text } : null; }
+async function startWatch(pi) { state.workspace = findWorkspace(state.cwd); if (!state.workspace)
+    throw new Error("current workspace has no .onlyne configuration"); const conn = await connectOrSpawn(state.workspace); state.owner = conn.owner; state.child = conn.process; state.socket = subscribe(state.workspace.socketPath, (line) => { if (!line?.event || line.type !== "inbound_message")
+    return; const inbound = inboundText(line); if (!inbound)
+    return; const mode = inboundModeFor(currentConfig(), inbound.channelId, inbound.conversationId); if (mode === "muted")
+    return; state.currentInbound = { ...inbound, replied: false, noReply: false, reminders: 0 }; if (mode === "auto-handle")
+    pi.sendUserMessage(`Onlyne inbound message from ${inbound.channelId}/${inbound.conversationId}:\n\n${inbound.text}\n\nReply with onlyne_reply, or call onlyne_mark_no_reply if no reply is needed.`, { deliverAs: "followUp" }); }); state.watching = true; return `watching ${state.workspace.root} (${state.owner})`; }
+function stopWatch() { state.socket?.destroy(); state.socket = undefined; if (state.owner === "extension")
+    stopProcess(state.child); state.child = undefined; state.watching = false; state.owner = "stopped"; return "watch stopped"; }
+async function reply(text) { if (!state.workspace)
+    throw new Error("onlyne workspace not found"); const inbound = state.currentInbound; if (!inbound)
+    throw new Error("no active inbound message"); const res = await sendWithRetry(state.workspace.socketPath, { channelId: inbound.channelId, conversationId: inbound.conversationId }, text, currentConfig().outbound.retry.attempts); if (res.ok)
+    inbound.replied = true; return res; }
+export default function onlyne(pi) {
+    pi.on("session_start", async (_event, ctx) => { state.cwd = ctx.cwd; state.workspace = findWorkspace(ctx.cwd); ctx.ui.setStatus("onlyne", state.workspace ? "onlyne: ready" : "onlyne: no .onlyne"); if (currentConfig().watch.autoStart && state.workspace) {
+        try {
+            ctx.ui.notify(await startWatch(pi), "info");
+        }
+        catch (e) {
+            ctx.ui.notify(String(e), "warning");
+        }
+    } });
+    pi.on("session_shutdown", async () => { stopWatch(); });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+        process.once(sig, () => stopWatch());
+    pi.on("message_end", async (event) => { const text = typeof event.content === "string" ? event.content.trim() : ""; if (text && !text.startsWith("{") && !text.startsWith("[onlyne-internal]"))
+        state.lastValidOutput = text; });
+    pi.on("turn_end", async () => {
+        const inbound = state.currentInbound;
+        if (!inbound || inbound.replied || inbound.noReply || !state.workspace)
+            return;
+        const cfg = currentConfig();
+        if (cfg.outbound.defaultReplyMode === "explicit-only")
+            return;
+        if (cfg.outbound.defaultReplyMode === "guarded-explicit" && inbound.reminders < cfg.outbound.guardedExplicit.reminders) {
+            if (inbound.reminders === 0)
+                inbound.fallbackText = state.lastValidOutput;
+            inbound.reminders++;
+            pi.sendUserMessage(`Onlyne reminder ${inbound.reminders}/${cfg.outbound.guardedExplicit.reminders}: reply to ${inbound.channelId}/${inbound.conversationId} with onlyne_reply, or call onlyne_mark_no_reply.`, { deliverAs: "followUp" });
+            return;
+        }
+        await reply(inbound.fallbackText || state.lastValidOutput || cfg.outbound.guardedExplicit.noOutputFallbackText);
+    });
+    pi.registerCommand("onlyne", { description: "Onlyne watch/status/config commands", handler: async (argLine, ctx) => { const [cmd, sub] = argLine.trim().split(/\s+/); try {
+            if (cmd === "watch" && sub === "on")
+                ctx.ui.notify(await startWatch(pi), "info");
+            else if (cmd === "watch" && sub === "off")
+                ctx.ui.notify(stopWatch(), "info");
+            else if (cmd === "status")
+                ctx.ui.notify(`onlyne ${state.watching ? "watching" : "stopped"}; owner=${state.owner}; workspace=${state.workspace?.root ?? "none"}`, "info");
+            else if (cmd === "config" && sub === "auto-start") {
+                const cfg = currentConfig();
+                cfg.watch.autoStart = !cfg.watch.autoStart;
+                saveConfig(state.cwd, cfg);
+                ctx.ui.notify(`autoStart=${cfg.watch.autoStart}`, "info");
+            }
+            else
+                ctx.ui.notify("usage: /onlyne status | watch on|off | config auto-start", "info");
+        }
+        catch (e) {
+            ctx.ui.notify(e instanceof Error ? e.message : String(e), "error");
+        } } });
+    pi.registerTool(defineTool({ name: "onlyne_reply", label: "Onlyne reply", description: "Reply with plain text to the current Onlyne inbound message.", parameters: Type.Object({ text: Type.String() }), executionMode: "parallel", async execute(_id, params) { return textResult(JSON.stringify(await reply(params.text))); } }));
+    pi.registerTool(defineTool({ name: "onlyne_send", label: "Onlyne send", description: "Send Markdown to one Onlyne channel conversation. Set rawText=true only for literal plain text.", parameters: Type.Object({ channelId: Type.String(), conversationId: Type.String(), text: Type.String(), rawText: Type.Optional(Type.Boolean()) }), executionMode: "parallel", async execute(_id, params) { if (!state.workspace)
+            throw new Error("onlyne workspace not found"); const res = await sendWithRetry(state.workspace.socketPath, params, params.text, currentConfig().outbound.retry.attempts, params.rawText ?? false); return textResult(JSON.stringify(res), res); } }));
+    pi.registerTool(defineTool({ name: "onlyne_broadcast", label: "Onlyne broadcast", description: "Send Markdown to many Onlyne channel conversations concurrently. Set rawText=true only for literal plain text.", parameters: Type.Object({ targets: Type.Array(Type.Object({ channelId: Type.String(), conversationId: Type.String() })), text: Type.String(), rawText: Type.Optional(Type.Boolean()) }), executionMode: "parallel", async execute(_id, params) { if (!state.workspace)
+            throw new Error("onlyne workspace not found"); const cfg = currentConfig(); const results = await broadcast(state.workspace.socketPath, params.targets, params.text, cfg.outbound.retry.attempts, cfg.outbound.retry.concurrency, params.rawText ?? false); return textResult(JSON.stringify({ ok: results.every((r) => r.ok), results }), results); } }));
+    pi.registerTool(defineTool({ name: "onlyne_mark_no_reply", label: "Onlyne no reply", description: "Mark the current Onlyne inbound message as intentionally not replied.", parameters: Type.Object({ reason: Type.Optional(Type.String()) }), executionMode: "parallel", async execute(_id, params) { if (state.currentInbound)
+            state.currentInbound.noReply = true; return textResult("marked no reply", params); } }));
+}

package/dist/onlyne.d.ts

@@ -0,0 +1,32 @@
+import { type ChildProcess } from "node:child_process";
+import { type Socket } from "node:net";
+import type { Workspace } from "./workspace.js";
+export interface OnlyneRequest {
+    id: string;
+    op: string;
+    channel_id?: string;
+    conversation_id?: string;
+    text?: string;
+    format?: "plain" | "markdown";
+    raw_text?: boolean;
+    limit?: number;
+}
+export interface SendTarget {
+    channelId: string;
+    conversationId: string;
+}
+export interface SendResult extends SendTarget {
+    ok: boolean;
+    error?: string;
+}
+export declare function request(socketPath: string, req: OnlyneRequest): Promise<any>;
+export declare function subscribe(socketPath: string, onLine: (line: any) => void): Socket;
+export declare function spawnDaemon(ws: Workspace, onlyneBin?: string): ChildProcess;
+export declare function waitForSocket(socketPath: string, timeoutMs?: number): Promise<void>;
+export declare function connectOrSpawn(ws: Workspace): Promise<{
+    owner: "external" | "extension";
+    process?: ChildProcess;
+}>;
+export declare function stopProcess(child?: ChildProcess): void;
+export declare function sendWithRetry(socketPath: string, target: SendTarget, text: string, attempts: number, rawText?: boolean): Promise<SendResult>;
+export declare function broadcast(socketPath: string, targets: SendTarget[], text: string, attempts: number, concurrency: number, rawText?: boolean): Promise<SendResult[]>;

package/dist/onlyne.js

@@ -0,0 +1,109 @@
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+export function request(socketPath, req) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath);
+        let data = "";
+        socket.setEncoding("utf8");
+        socket.on("error", reject);
+        socket.on("connect", () => socket.write(`${JSON.stringify(req)}\n`));
+        socket.on("data", (chunk) => { data += chunk; const idx = data.indexOf("\n"); if (idx >= 0) {
+            socket.end();
+            try {
+                resolve(JSON.parse(data.slice(0, idx)));
+            }
+            catch (e) {
+                reject(e);
+            }
+        } });
+    });
+}
+export function subscribe(socketPath, onLine) {
+    const socket = createConnection(socketPath);
+    let buf = "";
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write('{"id":"sub","op":"subscribe_events"}\n'));
+    socket.on("data", (chunk) => { buf += chunk; for (;;) {
+        const idx = buf.indexOf("\n");
+        if (idx < 0)
+            break;
+        const raw = buf.slice(0, idx);
+        buf = buf.slice(idx + 1);
+        if (!raw.trim())
+            continue;
+        try {
+            onLine(JSON.parse(raw));
+        }
+        catch { /* ignore */ }
+    } });
+    return socket;
+}
+export function spawnDaemon(ws, onlyneBin = process.env.ONLYNE_BIN ?? "onlyne") {
+    const script = `
+set -eu
+parent="$1"
+shift
+"$@" &
+child=$!
+cleanup() { kill "$child" 2>/dev/null || true; wait "$child" 2>/dev/null || true; }
+trap cleanup INT TERM HUP EXIT
+while kill -0 "$parent" 2>/dev/null && kill -0 "$child" 2>/dev/null; do sleep 1; done
+cleanup
+`;
+    return spawn("sh", ["-c", script, "onlyne-supervisor", String(process.pid), onlyneBin, "--workspace", ws.root, "run"], { cwd: ws.root, stdio: "ignore" });
+}
+export async function waitForSocket(socketPath, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    let last;
+    while (Date.now() < deadline) {
+        try {
+            await request(socketPath, { id: "ping", op: "ping" });
+            return;
+        }
+        catch (e) {
+            last = e;
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    throw last instanceof Error ? last : new Error("onlyne socket not ready");
+}
+export async function connectOrSpawn(ws) {
+    try {
+        await request(ws.socketPath, { id: "ping", op: "ping" });
+        return { owner: "external" };
+    }
+    catch { /* spawn */ }
+    const process = spawnDaemon(ws);
+    await waitForSocket(ws.socketPath);
+    return { owner: "extension", process };
+}
+export function stopProcess(child) { if (!child || child.killed)
+    return; child.kill("SIGTERM"); setTimeout(() => { if (!child.killed)
+    child.kill("SIGKILL"); }, 1500).unref(); }
+export async function sendWithRetry(socketPath, target, text, attempts, rawText = false) {
+    let error = "unknown error";
+    for (let i = 0; i < Math.max(1, attempts); i++) {
+        try {
+            const res = await request(socketPath, { id: `send-${Date.now()}-${i}`, op: "send_message", channel_id: target.channelId, conversation_id: target.conversationId, text, raw_text: rawText });
+            if (res.ok)
+                return { ...target, ok: true };
+            error = res.error?.message ?? JSON.stringify(res.error ?? res);
+        }
+        catch (e) {
+            error = e instanceof Error ? e.message : String(e);
+        }
+    }
+    return { ...target, ok: false, error };
+}
+export async function broadcast(socketPath, targets, text, attempts, concurrency, rawText = false) {
+    const out = [];
+    let next = 0;
+    async function worker() { for (;;) {
+        const i = next++;
+        if (i >= targets.length)
+            return;
+        out[i] = await sendWithRetry(socketPath, targets[i], text, attempts, rawText);
+    } }
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, targets.length)) }, worker));
+    return out;
+}

package/dist/workspace.d.ts

@@ -0,0 +1,6 @@
+export interface Workspace {
+    root: string;
+    onlyneDir: string;
+    socketPath: string;
+}
+export declare function findWorkspace(start: string): Workspace | null;

package/dist/workspace.js

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export function findWorkspace(start) {
+    let dir = resolve(start);
+    for (;;) {
+        const onlyneDir = join(dir, ".onlyne");
+        if (existsSync(onlyneDir))
+            return { root: dir, onlyneDir, socketPath: join(onlyneDir, "run", "onlyne.sock") };
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pi-onlyne",
+  "version": "0.2.2",
+  "description": "Pi extension tools for sending messages through Onlyne.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dbydd/pi-onlyne.git"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "onlyne",
+    "messaging",
+    "extension"
+  ],
+  "author": "dbydd <1992003927@qq.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.79.10",
+    "@earendil-works/pi-coding-agent": "^0.79.10",
+    "typebox": "^1.2.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.8.3"
+  }
+}