@burmese/pi 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPets
+
+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/dist/extension.d.ts

@@ -0,0 +1,3 @@
+import { type OpenPetsPiOptions } from "./runtime.js";
+export default function openPetsPiExtension(pi: unknown, options?: OpenPetsPiOptions): void;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extension.js

@@ -0,0 +1,5 @@
+import { createOpenPetsPiExtension } from "./runtime.js";
+export default function openPetsPiExtension(pi, options = {}) {
+    createOpenPetsPiExtension(pi, options);
+}
+//# sourceMappingURL=extension.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from "./extension.js";
+export { allowedPiOpenPetsCommands, classifyPiEvent, classifyPiToolExecutionStart, createOpenPetsPiExtension, createOpenPetsPiRuntime, getPiOpenPetsHelp, normalizePiEvent, parseOpenPetsCommand, shouldIgnoreOpenPetsTool, validateManualSpeech, type OpenPetsPiCommand, type OpenPetsPiExtensionApi, type OpenPetsPiOptions, type OpenPetsPiRuntime, type PiEventEnvelope, type PiEventDecision, } from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default } from "./extension.js";
+export { allowedPiOpenPetsCommands, classifyPiEvent, classifyPiToolExecutionStart, createOpenPetsPiExtension, createOpenPetsPiRuntime, getPiOpenPetsHelp, normalizePiEvent, parseOpenPetsCommand, shouldIgnoreOpenPetsTool, validateManualSpeech, } from "./runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime.d.ts

@@ -0,0 +1,59 @@
+import { type OpenPetsClient, type OpenPetsReaction } from "@burmese/client";
+export interface OpenPetsPiOptions {
+    readonly clientFactory?: () => OpenPetsClient;
+    readonly schedule?: (work: () => Promise<void>) => void;
+    readonly debug?: boolean;
+    readonly debugLog?: (message: string) => void;
+    readonly random?: () => number;
+    readonly now?: () => number;
+}
+export interface OpenPetsPiRuntime {
+    readonly handleEvent: (event: unknown) => void;
+    readonly handleCommand: (args: string, ctx?: OpenPetsPiCommandContext) => Promise<void>;
+}
+export interface OpenPetsPiExtensionApi {
+    readonly on?: (eventName: string, handler: (event: unknown, ctx?: unknown) => unknown) => unknown;
+    readonly registerCommand?: (name: string, command: {
+        readonly description?: string;
+        readonly handler: (args: string, ctx?: unknown) => unknown;
+    }) => unknown;
+}
+export interface OpenPetsPiCommandContext {
+    readonly ui?: {
+        readonly notify?: (message: string, type?: "info" | "warning" | "error") => void;
+    };
+}
+export interface PiEventDecision {
+    readonly reaction?: OpenPetsReaction;
+    readonly speech?: "error";
+    readonly markError?: boolean;
+    readonly clearError?: boolean;
+}
+export interface PiEventEnvelope {
+    readonly type: string;
+    readonly payload?: unknown;
+}
+export type OpenPetsPiCommand = {
+    readonly kind: "help";
+} | {
+    readonly kind: "status";
+} | {
+    readonly kind: "test";
+} | {
+    readonly kind: "react";
+    readonly reaction: OpenPetsReaction;
+} | {
+    readonly kind: "say";
+    readonly message: string;
+};
+export declare const allowedPiOpenPetsCommands: readonly ["help", "status", "test", "react", "say"];
+export declare function createOpenPetsPiExtension(pi: unknown, options?: OpenPetsPiOptions): OpenPetsPiRuntime;
+export declare function createOpenPetsPiRuntime(options?: OpenPetsPiOptions): OpenPetsPiRuntime;
+export declare function classifyPiEvent(event: unknown): PiEventDecision | undefined;
+export declare function normalizePiEvent(event: unknown): PiEventEnvelope;
+export declare function classifyPiToolExecutionStart(toolName: unknown, args?: unknown): OpenPetsReaction | undefined;
+export declare function shouldIgnoreOpenPetsTool(toolName: string): boolean;
+export declare function parseOpenPetsCommand(args: string): OpenPetsPiCommand;
+export declare function validateManualSpeech(message: string): string;
+export declare function getPiOpenPetsHelp(): string;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.js

@@ -0,0 +1,255 @@
+import { pickHookSpeech, validateHookSpeech } from "@burmese/agent-events";
+import { allowedReactions, createOpenPetsClient } from "@burmese/client";
+const automaticTimeoutMs = 500;
+const errorSuccessSuppressionMs = 5_000;
+const boundedCommandSliceLength = 300;
+const openPetsClientLabel = "Pi";
+export const allowedPiOpenPetsCommands = ["help", "status", "test", "react", "say"];
+export function createOpenPetsPiExtension(pi, options = {}) {
+    const runtime = createOpenPetsPiRuntime(options);
+    const api = isPiApi(pi) ? pi : undefined;
+    if (!api)
+        return runtime;
+    const subscribe = (eventName) => {
+        api.on?.(eventName, (event) => runtime.handleEvent({ type: eventName, payload: event }));
+    };
+    for (const eventName of ["session_start", "session_shutdown", "agent_start", "agent_end", "turn_start", "tool_execution_start", "tool_execution_end"]) {
+        subscribe(eventName);
+    }
+    api.registerCommand?.("openpets", {
+        description: "Control OpenPets desktop pet reactions and check local connection status.",
+        handler: async (args, ctx) => runtime.handleCommand(args, isCommandContext(ctx) ? ctx : undefined),
+    });
+    return runtime;
+}
+export function createOpenPetsPiRuntime(options = {}) {
+    const clientFactory = options.clientFactory ?? (() => createOpenPetsClient({ connectTimeoutMs: automaticTimeoutMs, responseTimeoutMs: automaticTimeoutMs, source: "plugin" }));
+    const schedule = options.schedule ?? defaultSchedule;
+    const debug = options.debug === true || process.env.OPENPETS_PI_DEBUG === "1";
+    const debugLog = options.debugLog ?? ((message) => {
+        if (debug)
+            process.stderr.write(`${message}\n`);
+    });
+    let client;
+    let recentErrorAt = Number.NEGATIVE_INFINITY;
+    let lastErrorSpeechAt = Number.NEGATIVE_INFINITY;
+    const getClient = () => {
+        client ??= clientFactory();
+        return client;
+    };
+    const runAutomatic = (decision) => {
+        if (!decision?.reaction)
+            return;
+        const reaction = decision.reaction;
+        if (decision.markError)
+            recentErrorAt = options.now?.() ?? Date.now();
+        if (decision.clearError && (options.now?.() ?? Date.now()) - recentErrorAt < errorSuccessSuppressionMs)
+            return;
+        try {
+            schedule(async () => {
+                try {
+                    if (decision.speech === "error" && shouldSendErrorSpeech()) {
+                        await getClient().say(validateHookSpeech(pickHookSpeech("error", options.random)), { reaction, clientLabel: openPetsClientLabel });
+                        return;
+                    }
+                    await getClient().react(reaction, { clientLabel: openPetsClientLabel });
+                }
+                catch (error) {
+                    debugLog(`OpenPets Pi extension ignored error: ${sanitizeDebugError(error)}`);
+                }
+            });
+        }
+        catch (error) {
+            debugLog(`OpenPets Pi extension scheduling ignored error: ${sanitizeDebugError(error)}`);
+        }
+    };
+    const shouldSendErrorSpeech = () => {
+        const now = options.now?.() ?? Date.now();
+        if (now - lastErrorSpeechAt < 20_000)
+            return false;
+        lastErrorSpeechAt = now;
+        return true;
+    };
+    return {
+        handleEvent(event) {
+            try {
+                runAutomatic(classifyPiEvent(event));
+            }
+            catch (error) {
+                debugLog(`OpenPets Pi event ignored error: ${sanitizeDebugError(error)}`);
+            }
+        },
+        async handleCommand(args, ctx) {
+            try {
+                const command = parseOpenPetsCommand(args);
+                await executeCommand(command, getClient(), ctx);
+            }
+            catch (error) {
+                notify(ctx, sanitizeUserError(error), "error");
+            }
+        },
+    };
+}
+export function classifyPiEvent(event) {
+    const envelope = normalizePiEvent(event);
+    const type = envelope.type;
+    const record = isRecord(envelope.payload) ? envelope.payload : isRecord(event) ? event : {};
+    switch (type) {
+        case "session_start":
+            return { reaction: "waving" };
+        case "session_shutdown":
+            return { reaction: "idle" };
+        case "agent_start":
+            return { reaction: "thinking" };
+        case "turn_start":
+            return { reaction: "working" };
+        case "agent_end":
+            return { reaction: "success", clearError: true };
+        case "tool_execution_start": {
+            const reaction = classifyPiToolExecutionStart(record.toolName, record.args);
+            return reaction ? { reaction } : undefined;
+        }
+        case "tool_execution_end":
+            return record.isError === true ? { reaction: "error", speech: "error", markError: true } : undefined;
+        default:
+            return undefined;
+    }
+}
+export function normalizePiEvent(event) {
+    if (isRecord(event) && typeof event.type === "string") {
+        return { type: event.type, payload: "payload" in event ? event.payload : event };
+    }
+    return { type: "", payload: event };
+}
+export function classifyPiToolExecutionStart(toolName, args) {
+    const normalized = typeof toolName === "string" ? toolName.toLowerCase() : "";
+    if (!normalized || shouldIgnoreOpenPetsTool(normalized))
+        return undefined;
+    if (/edit|write|patch|apply/.test(normalized))
+        return "editing";
+    if (/bash|shell|terminal|exec|command/.test(normalized))
+        return isTestLikeArgs(args) ? "testing" : "running";
+    return "working";
+}
+export function shouldIgnoreOpenPetsTool(toolName) {
+    const normalized = toolName.toLowerCase().replace(/[^a-z0-9_:/.-]+/g, "_");
+    return /(?:^|[_:/.-])openpets(?:[_:/.-]|$)/.test(normalized) || /^(?:openpets|burmese)_(?:status|say|react)$/.test(normalized);
+}
+export function parseOpenPetsCommand(args) {
+    const trimmed = args.trim();
+    if (!trimmed || trimmed === "help" || trimmed === "--help" || trimmed === "-h")
+        return { kind: "help" };
+    const [head = "", ...rest] = trimmed.split(/\s+/);
+    const tail = trimmed.slice(head.length).trim();
+    switch (head.toLowerCase()) {
+        case "status":
+            if (rest.length > 0)
+                throw new Error("Usage: /openpets status");
+            return { kind: "status" };
+        case "test":
+            if (rest.length > 0)
+                throw new Error("Usage: /openpets test");
+            return { kind: "test" };
+        case "react": {
+            if (rest.length !== 1)
+                throw new Error("Usage: /openpets react <reaction>");
+            return { kind: "react", reaction: validateReaction(rest[0] ?? "") };
+        }
+        case "say":
+            return { kind: "say", message: validateManualSpeech(tail) };
+        default:
+            throw new Error(`Unknown /openpets command: ${head}`);
+    }
+}
+export function validateManualSpeech(message) {
+    const trimmed = message.trim();
+    if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/i.test(trimmed))
+        throw new Error("OpenPets speech must not contain secrets.");
+    return validateHookSpeech(trimmed);
+}
+export function getPiOpenPetsHelp() {
+    return "OpenPets commands: /openpets status, /openpets test, /openpets react <reaction>, /openpets say <message>.";
+}
+async function executeCommand(command, client, ctx) {
+    switch (command.kind) {
+        case "help":
+            notify(ctx, getPiOpenPetsHelp(), "info");
+            return;
+        case "status": {
+            const status = await client.status();
+            notify(ctx, status.ok ? "OpenPets is connected." : `OpenPets unavailable: ${sanitizeStatusReason(status.unavailableReason)}`, status.ok ? "info" : "warning");
+            return;
+        }
+        case "test":
+            await client.say("Pi connected", { reaction: "waving", clientLabel: openPetsClientLabel });
+            notify(ctx, "OpenPets test sent.", "info");
+            return;
+        case "react":
+            await client.react(command.reaction, { clientLabel: openPetsClientLabel });
+            notify(ctx, `OpenPets reaction set: ${command.reaction}`, "info");
+            return;
+        case "say":
+            await client.say(command.message, { clientLabel: openPetsClientLabel });
+            notify(ctx, "OpenPets message sent.", "info");
+            return;
+    }
+}
+function isTestLikeArgs(args) {
+    const command = isRecord(args) && typeof args.command === "string" ? args.command.slice(0, boundedCommandSliceLength) : "";
+    return /\b(test|vitest|jest|pytest|npm\s+test|pnpm\s+test|yarn\s+test|cargo\s+test|go\s+test)\b/i.test(command);
+}
+function validateReaction(value) {
+    if (!allowedReactions.includes(value))
+        throw new Error("Invalid OpenPets reaction.");
+    return value;
+}
+function notify(ctx, message, type) {
+    ctx?.ui?.notify?.(message, type);
+}
+function defaultSchedule(work) {
+    void Promise.resolve().then(work).catch(() => undefined);
+}
+function sanitizeDebugError(error) {
+    if (!error)
+        return "unknown";
+    if (isRecord(error) && typeof error.code === "string")
+        return sanitizeKnownErrorCode(error.code);
+    if (error instanceof Error)
+        return error.name.replace(/[^a-z0-9_-]/gi, "_").slice(0, 80) || "Error";
+    return "unknown";
+}
+function sanitizeKnownErrorCode(code) {
+    const normalized = code.toLowerCase();
+    if (normalized.includes("enoent"))
+        return "ENOENT";
+    if (normalized.includes("econnrefused"))
+        return "ECONNREFUSED";
+    if (normalized.includes("connect_timeout"))
+        return "connect_timeout";
+    if (normalized.includes("response_timeout"))
+        return "response_timeout";
+    if (normalized.includes("connection_closed"))
+        return "connection_closed";
+    if (normalized.includes("unavailable"))
+        return "unavailable";
+    return "OpenPetsClientError";
+}
+function sanitizeUserError(error) {
+    return error instanceof Error ? error.message.replace(/[\r\n]+/g, " ").slice(0, 140) : "OpenPets command failed.";
+}
+function sanitizeStatusReason(reason) {
+    const text = typeof reason === "string" ? reason : "not running";
+    if (/ENOENT|ECONNREFUSED|connect_timeout|response_timeout|unavailable/i.test(text))
+        return "not running";
+    return "unavailable";
+}
+function isPiApi(value) {
+    return isRecord(value) && (typeof value.on === "function" || typeof value.registerCommand === "function");
+}
+function isCommandContext(value) {
+    return isRecord(value) && (value.ui === undefined || isRecord(value.ui));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=runtime.js.map

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@burmese/pi",
+  "version": "3.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wannabeepolymath/pet-assistant.git",
+    "directory": "packages/pi"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "openpets",
+    "coding-agent"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/extension.d.ts",
+    "dist/extension.js",
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/runtime.d.ts",
+    "dist/runtime.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "default": "./dist/extension.js"
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.js"
+    ]
+  },
+  "dependencies": {
+    "@burmese/agent-events": "3.1.0",
+    "@burmese/client": "3.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node dist/check-pi.js && node dist/check-pi-compat.js",
+    "check": "pnpm typecheck && pnpm build && pnpm test",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc"
+  }
+}