@pinet/pinet-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+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,20 @@
+# @pinet/pinet-core
+
+Runtime-core helpers for Pinet that are independent of any Slack adapter.
+
+Current seam:
+
+- Pinet output option normalization (`cli` default, explicit `json`/`full` opt-ins)
+- durable Pinet read result text/detail formatting
+- scheduled wake-up time parsing and thread ID helpers
+
+`@pinet/slack-bridge` still composes the extension and preserves compatibility wrappers, but these helpers now live behind package exports so future extraction can move one boundary at a time.
+
+Design proposal: `plans/slack-split-proposal.md`
+
+## Publishing
+
+This package is included in the full npm publish set tracked in
+[`../plans/npm-publish.md`](../plans/npm-publish.md). Use the GitHub Actions
+workflow's default dry-run/readiness path for validation; do not publish, tag, or
+bump versions without explicit maintainer release approval.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./output-options.js";
+export * from "./pinet-read-formatting.js";
+export * from "./scheduled-wakeups.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./output-options.js";
+export * from "./pinet-read-formatting.js";
+export * from "./scheduled-wakeups.js";

package/dist/output-options.d.ts

@@ -0,0 +1,6 @@
+export type PinetOutputFormat = "cli" | "json";
+export interface PinetOutputOptions {
+    format: PinetOutputFormat;
+    full: boolean;
+}
+export declare function normalizePinetOutputOptions(args: Record<string, unknown>): PinetOutputOptions;

package/dist/output-options.js

@@ -0,0 +1,12 @@
+export function normalizePinetOutputOptions(args) {
+    const rawFormat = args.format ?? args.f ?? args["-f"];
+    const format = rawFormat == null ? "cli" : String(rawFormat).trim().toLowerCase();
+    if (format !== "cli" && format !== "json") {
+        throw new Error('format must be "cli" or "json".');
+    }
+    const rawFull = args.full ?? args["--full"];
+    if (rawFull != null && typeof rawFull !== "boolean") {
+        throw new Error("full must be a boolean when provided.");
+    }
+    return { format, full: rawFull === true };
+}

package/dist/pinet-read-formatting.d.ts

@@ -0,0 +1,49 @@
+import { type PinetMailClass } from "@pinet/broker-core/mail-classification";
+export interface PinetInboxItem {
+    inboxId: number;
+    delivered: boolean;
+    readAt: string | null;
+    message: {
+        id: number;
+        threadId: string;
+        source: string;
+        direction: string;
+        sender: string;
+        body: string;
+        metadata: Record<string, unknown> | null;
+        createdAt: string;
+    };
+}
+export interface PinetReadMessage {
+    inboxId: number;
+    delivered: boolean;
+    readAt: string | null;
+    message: PinetInboxItem["message"];
+}
+export interface PinetUnreadThreadSummary {
+    threadId: string;
+    source: string;
+    channel: string;
+    unreadCount: number;
+    latestMessageId: number;
+    latestAt: string;
+    highestMailClass: PinetMailClass;
+    mailClassCounts: Record<PinetMailClass, number>;
+}
+export interface PinetReadResult {
+    messages: PinetReadMessage[];
+    unreadCountBefore: number;
+    unreadCountAfter: number;
+    unreadThreads: PinetUnreadThreadSummary[];
+    markedReadIds: number[];
+}
+export interface PinetReadOptions {
+    threadId?: string;
+    limit?: number;
+    unreadOnly?: boolean;
+    markRead?: boolean;
+}
+export declare function formatPinetReadResultFull(result: PinetReadResult, options: PinetReadOptions): string;
+export declare function summarizeUnreadThreadCounts(thread: PinetUnreadThreadSummary): string;
+export declare function buildCompactPinetReadDetails(result: PinetReadResult): Record<string, unknown>;
+export declare function formatPinetReadResultCompact(result: PinetReadResult, options: PinetReadOptions): string;

package/dist/pinet-read-formatting.js

@@ -0,0 +1,94 @@
+import { classifyPinetMail, formatPinetMailClassLabel, } from "@pinet/broker-core/mail-classification";
+function truncateText(value, maxLength = 180) {
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= maxLength)
+        return collapsed;
+    return `${collapsed.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+export function formatPinetReadResultFull(result, options) {
+    const scope = options.threadId ? `thread ${options.threadId}` : "your Pinet inbox";
+    const mode = options.unreadOnly === false ? "latest" : "unread";
+    const lines = [
+        `Pinet read (${mode}) from ${scope}: ${result.messages.length} message${result.messages.length === 1 ? "" : "s"}.`,
+        `Unread before: ${result.unreadCountBefore}; unread after: ${result.unreadCountAfter}.`,
+    ];
+    if (result.messages.length > 0) {
+        lines.push("");
+        for (const item of result.messages) {
+            const classification = classifyPinetMail({
+                source: item.message.source,
+                threadId: item.message.threadId,
+                sender: item.message.sender,
+                body: item.message.body,
+                metadata: item.message.metadata,
+            });
+            const label = formatPinetMailClassLabel(classification.class);
+            lines.push(`- [${label}] [${item.message.source}/${item.message.threadId} #${item.message.id}] ${item.message.sender}: ${item.message.body}`);
+        }
+    }
+    if (result.unreadThreads.length > 0) {
+        lines.push("", "Unread thread pointers:");
+        for (const thread of result.unreadThreads.slice(0, 10)) {
+            const label = formatPinetMailClassLabel(thread.highestMailClass);
+            const counts = summarizeUnreadThreadCounts(thread);
+            lines.push(`- [${label}] ${thread.threadId} (${thread.source}${thread.channel ? `/${thread.channel}` : ""}): ${thread.unreadCount} unread${counts ? ` (${counts})` : ""}; latest #${thread.latestMessageId}; pointer=pinet action=read args.thread_id=${thread.threadId} args.unread_only=true`);
+        }
+    }
+    if (result.markedReadIds.length > 0) {
+        lines.push("", `Marked read: ${result.markedReadIds.join(", ")}.`);
+    }
+    return lines.join("\n");
+}
+export function summarizeUnreadThreadCounts(thread) {
+    return [
+        thread.mailClassCounts.steering > 0 ? `${thread.mailClassCounts.steering} steering` : null,
+        thread.mailClassCounts.fwup > 0 ? `${thread.mailClassCounts.fwup} fwup` : null,
+        thread.mailClassCounts.maintenance_context > 0
+            ? `${thread.mailClassCounts.maintenance_context} maintenance/context`
+            : null,
+    ]
+        .filter((item) => Boolean(item))
+        .join(", ");
+}
+export function buildCompactPinetReadDetails(result) {
+    return {
+        messageCount: result.messages.length,
+        unreadCountBefore: result.unreadCountBefore,
+        unreadCountAfter: result.unreadCountAfter,
+        markedReadIds: result.markedReadIds,
+        messages: result.messages.map((item) => {
+            const classification = classifyPinetMail({
+                source: item.message.source,
+                threadId: item.message.threadId,
+                sender: item.message.sender,
+                body: item.message.body,
+                metadata: item.message.metadata,
+            });
+            return {
+                inboxId: item.inboxId,
+                messageId: item.message.id,
+                threadId: item.message.threadId,
+                source: item.message.source,
+                sender: item.message.sender,
+                class: classification.class,
+                preview: truncateText(item.message.body),
+            };
+        }),
+        unreadThreads: result.unreadThreads.slice(0, 10).map((thread) => ({
+            threadId: thread.threadId,
+            source: thread.source,
+            unreadCount: thread.unreadCount,
+            latestMessageId: thread.latestMessageId,
+            highestMailClass: thread.highestMailClass,
+            mailClassSummary: summarizeUnreadThreadCounts(thread),
+        })),
+    };
+}
+export function formatPinetReadResultCompact(result, options) {
+    const mode = options.unreadOnly === false ? "latest" : "unread";
+    const markedSuffix = result.markedReadIds.length > 0 ? `; marked ${result.markedReadIds.length}` : "";
+    const unreadThreadSuffix = result.unreadThreads.length > 0
+        ? `; ${result.unreadThreads.length} unread thread${result.unreadThreads.length === 1 ? "" : "s"}`
+        : "";
+    return `Pinet read: ${result.messages.length} ${mode} message${result.messages.length === 1 ? "" : "s"}; unread ${result.unreadCountBefore}→${result.unreadCountAfter}${markedSuffix}${unreadThreadSuffix}.`;
+}

package/dist/scheduled-wakeups.d.ts

@@ -0,0 +1,7 @@
+export interface ScheduledWakeupInput {
+    delay?: string;
+    at?: string;
+}
+export declare function parseScheduledWakeupDelay(delay: string): number | null;
+export declare function resolveScheduledWakeupFireAt(input: ScheduledWakeupInput, now?: number): string;
+export declare function buildScheduledWakeupThreadId(agentId: string): string;

package/dist/scheduled-wakeups.js

@@ -0,0 +1,57 @@
+const DELAY_UNITS_MS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 60 * 60_000,
+    d: 24 * 60 * 60_000,
+};
+export function parseScheduledWakeupDelay(delay) {
+    const normalized = delay.trim().toLowerCase().replace(/\s+/g, "");
+    if (!normalized) {
+        return null;
+    }
+    const tokenRegex = /(\d+)(ms|s|m|h|d)/g;
+    let totalMs = 0;
+    let matchedLength = 0;
+    for (const match of normalized.matchAll(tokenRegex)) {
+        const [token, amountText, unit] = match;
+        if (!token || !amountText || !unit || match.index !== matchedLength) {
+            return null;
+        }
+        const amount = Number.parseInt(amountText, 10);
+        if (!Number.isFinite(amount) || amount < 0) {
+            return null;
+        }
+        totalMs += amount * DELAY_UNITS_MS[unit];
+        matchedLength += token.length;
+    }
+    if (matchedLength !== normalized.length || totalMs <= 0) {
+        return null;
+    }
+    return totalMs;
+}
+export function resolveScheduledWakeupFireAt(input, now = Date.now()) {
+    const hasDelay = typeof input.delay === "string" && input.delay.trim().length > 0;
+    const hasAt = typeof input.at === "string" && input.at.trim().length > 0;
+    if (hasDelay === hasAt) {
+        throw new Error("Provide exactly one of delay or at.");
+    }
+    if (hasDelay) {
+        const delayMs = parseScheduledWakeupDelay(input.delay);
+        if (delayMs == null) {
+            throw new Error("Invalid delay. Use values like 5m, 30s, 1h30m, or 1d.");
+        }
+        return new Date(now + delayMs).toISOString();
+    }
+    const fireAtMs = Date.parse(input.at);
+    if (Number.isNaN(fireAtMs)) {
+        throw new Error("Invalid timestamp. Use an ISO-8601 time like 2026-04-02T14:30:00Z.");
+    }
+    if (fireAtMs <= now) {
+        throw new Error("Scheduled wake-up time must be in the future.");
+    }
+    return new Date(fireAtMs).toISOString();
+}
+export function buildScheduledWakeupThreadId(agentId) {
+    return `wakeup:${agentId}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pinet/pinet-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pinet runtime core for pi — broker/follower orchestration and mesh tooling",
+  "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gugu91/extensions.git",
+    "directory": "pinet-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./output-options": "./dist/output-options.js",
+    "./pinet-read-formatting": "./dist/pinet-read-formatting.js",
+    "./scheduled-wakeups": "./dist/scheduled-wakeups.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist/"
+  ],
+  "pi": {},
+  "scripts": {
+    "build": "node ../scripts/build-package.mjs",
+    "prepack": "pnpm run build",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run *.test.ts"
+  },
+  "dependencies": {
+    "@pinet/broker-core": "0.1.0",
+    "@pinet/transport-core": "0.1.0"
+  },
+  "types": "./dist/index.d.ts"
+}