pi-onlyne 0.2.4 → 0.3.0

package/README.md

@@ -19,16 +19,20 @@ Onlyne is deliberately narrow:
 
 `pi-onlyne` connects pi to an existing Onlyne workspace and exposes Onlyne as native pi tools.
 
+Onlyne channels are singleton-routed: each enabled channel has one `bind_conversation_id` set in config or by sending `/handshake` from the desired conversation, so pi tools take `channelId` only.
+
 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
+- send a message to a channel's configured conversation
 - broadcast the same message to multiple conversations
+- inject a local loopback activation so background scripts can wake the session
+- share Onlyne's FIFO consume cursor so `.onlyne/channels/<channel>/out` does not re-read messages already surfaced to pi
 - 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.
+Messages are Markdown by default, matching normal agent output. Use `rawText: true` only when the message must be sent literally. Onlyne can also expose FIFO IO under `.onlyne/channels/<channel>/in|out`; pi-onlyne stays on the socket/event API and advances the shared consume cursor after delivering inbound follow-ups.
 
 ## Install
 
@@ -46,6 +50,8 @@ You also need the `onlyne` CLI installed and an initialized workspace:
 
 ```bash
 onlyne init
+# Optional: refresh the workspace-local agent skill
+onlyne export-skill
 ```
 
 If `onlyne` is not on `PATH`, set:
@@ -79,8 +85,9 @@ When a message arrives through Onlyne, pi receives it as a follow-up message. Th
 
 ```text
 onlyne_reply({ text })
-onlyne_send({ channelId, conversationId, text, rawText? })
+onlyne_send({ channelId, text, rawText? })
 onlyne_broadcast({ targets, text, rawText? })
+onlyne_loopback({ text, rawText? })
 onlyne_mark_no_reply({ reason? })
 ```
 
@@ -89,7 +96,6 @@ onlyne_mark_no_reply({ reason? })
 ```ts
 onlyne_send({
   channelId: "telegram",
-  conversationId: "123456",
   text: "# Build report\n\nAll checks passed."
 })
 ```
@@ -99,7 +105,6 @@ onlyne_send({
 ```ts
 onlyne_send({
   channelId: "telegram",
-  conversationId: "123456",
   text: "# not a heading",
   rawText: true
 })
@@ -110,13 +115,25 @@ onlyne_send({
 ```ts
 onlyne_broadcast({
   targets: [
-    { channelId: "telegram", conversationId: "123456" },
-    { channelId: "feishu", conversationId: "oc_xxx" }
+    { channelId: "telegram" },
+    { channelId: "feishu" }
   ],
-  text: "# Release shipped\n\nVersion 0.2.3 is live."
+  text: "# Release shipped\n\nVersion 0.3.0 is live."
 })
 ```
 
+### Loopback wake-up
+
+From any local script, inject an inbound message into the current Onlyne daemon:
+
+```bash
+onlyne client '{"id":"wake","op":"loopback","text":"background job finished","raw_text":true}'
+# or, with FIFO IO enabled by the daemon:
+printf 'background job finished\n' > .onlyne/channels/loopback/in
+```
+
+Pi treats channel `loopback` as wake-up-only: it sends a follow-up to the session, but does not expect `onlyne_reply`.
+
 ## Local state
 
 This extension stores its own pi-side config at:

package/SPEC.md

@@ -14,6 +14,9 @@ Pi extension for Onlyne. Onlyne remains a workspace-local IM broker; this extens
 - 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.
+- Loopback inbound messages wake Pi without creating a reply obligation.
+- After pi surfaces an inbound follow-up, it calls `mark_io_consumed` so Onlyne FIFO `out_cursor = "consume"` stays synchronized with pi notifications.
+- FIFO IO itself remains owned by the Onlyne daemon; pi-onlyne does not open `.onlyne/channels/*/in|out` directly.
 
 ## Config
 
@@ -34,8 +37,9 @@ Stored in project `.pi/onlyne.json`:
 ## Tools
 
 - `onlyne_reply({ text })`
-- `onlyne_send({ channelId, conversationId, text, rawText? })`
+- `onlyne_send({ channelId, text, rawText? })`
 - `onlyne_broadcast({ targets, text, rawText? })`
+- `onlyne_loopback({ text, rawText? })`
 - `onlyne_mark_no_reply({ reason? })`
 
 ## Deferred

package/dist/index.js

@@ -1,23 +1,32 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { broadcast, connectOrSpawn, sendWithRetry, stopProcess, subscribe } from "./onlyne.js";
+import { broadcast, connectOrSpawn, loopback, markConsumed, 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; }
+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 messageId = msg.message_id ?? msg.messageId; const text = msg.text ?? msg.content ?? msg.body; return channelId && conversationId && typeof text === "string" ? { channelId, conversationId, messageId, text } : null; }
+function consumeIfNotified(inbound) { if (state.workspace && inbound.messageId)
+    void markConsumed(state.workspace.socketPath, inbound.messageId).catch(() => { }); }
 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})`; }
+    return; if (inbound.channelId === "loopback") {
+    if (mode === "auto-handle")
+        pi.sendUserMessage(`Onlyne loopback activation${inbound.conversationId ? ` (${inbound.conversationId})` : ""}:\n\n${inbound.text}`, { deliverAs: "followUp" });
+    consumeIfNotified(inbound);
+    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" });
+    consumeIfNotified(inbound);
+} }); 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)
+    throw new Error("no active inbound message"); const res = await sendWithRetry(state.workspace.socketPath, { channelId: inbound.channelId }, 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) {
@@ -69,10 +78,12 @@ export default function onlyne(pi) {
             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)
+    pi.registerTool(defineTool({ name: "onlyne_send", label: "Onlyne send", description: "Send Markdown to the channel's configured Onlyne conversation. Set rawText=true only for literal plain text.", parameters: Type.Object({ channelId: 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)
+    pi.registerTool(defineTool({ name: "onlyne_broadcast", label: "Onlyne broadcast", description: "Send Markdown to many configured Onlyne channels concurrently. Set rawText=true only for literal plain text.", parameters: Type.Object({ targets: Type.Array(Type.Object({ channelId: 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_loopback", label: "Onlyne loopback", description: "Inject a local loopback activation message so scripts can wake the current Pi session. Set rawText=false for Markdown. FIFO alternative: write to .onlyne/channels/loopback/in.", parameters: Type.Object({ 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 loopback(state.workspace.socketPath, params.text, params.rawText ?? true); return textResult(JSON.stringify(res), res); } }));
     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

@@ -5,7 +5,7 @@ export interface OnlyneRequest {
     id: string;
     op: string;
     channel_id?: string;
-    conversation_id?: string;
+    message_id?: string;
     text?: string;
     format?: "plain" | "markdown";
     raw_text?: boolean;
@@ -13,7 +13,6 @@ export interface OnlyneRequest {
 }
 export interface SendTarget {
     channelId: string;
-    conversationId: string;
 }
 export interface SendResult extends SendTarget {
     ok: boolean;
@@ -28,5 +27,7 @@ export declare function connectOrSpawn(ws: Workspace): Promise<{
     process?: ChildProcess;
 }>;
 export declare function stopProcess(child?: ChildProcess): void;
+export declare function loopback(socketPath: string, text: string, rawText?: boolean): Promise<any>;
+export declare function markConsumed(socketPath: string, messageId: string): Promise<any>;
 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

@@ -80,11 +80,17 @@ export async function connectOrSpawn(ws) {
 export function stopProcess(child) { if (!child || child.killed)
     return; child.kill("SIGTERM"); setTimeout(() => { if (!child.killed)
     child.kill("SIGKILL"); }, 1500).unref(); }
+export async function loopback(socketPath, text, rawText = true) {
+    return request(socketPath, { id: `loopback-${Date.now()}`, op: "loopback", text, raw_text: rawText });
+}
+export async function markConsumed(socketPath, messageId) {
+    return request(socketPath, { id: `consume-${Date.now()}`, op: "mark_io_consumed", message_id: messageId });
+}
 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 });
+            const res = await request(socketPath, { id: `send-${Date.now()}-${i}`, op: "send_message", channel_id: target.channelId, text, raw_text: rawText });
             if (res.ok)
                 return { ...target, ok: true };
             error = res.error?.message ?? JSON.stringify(res.error ?? res);

package/package.json

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