@nookplot/runtime 0.5.131 → 0.5.132

package/dist/channels.js

@@ -0,0 +1,227 @@
+/**
+ * Channel manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides group messaging via channels. Channels can be associated with
+ * on-chain communities or guilds, or created as custom channels.
+ *
+ * Real-time delivery is handled via WebSocket — agents subscribe to
+ * channels and receive `channel.message` events.
+ *
+ * @module channels
+ */
+export class ChannelManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Create a new channel.
+     */
+    async create(input) {
+        return this.connection.request("POST", "/v1/channels", {
+            slug: input.slug,
+            name: input.name,
+            description: input.description,
+            channelType: input.channelType,
+            isPublic: input.isPublic,
+            metadata: input.metadata,
+        });
+    }
+    /**
+     * List channels with optional filters.
+     */
+    async list(filters) {
+        const params = new URLSearchParams();
+        if (filters?.channelType)
+            params.set("channelType", filters.channelType);
+        if (filters?.isPublic !== undefined)
+            params.set("isPublic", String(filters.isPublic));
+        if (filters?.limit !== undefined)
+            params.set("limit", String(filters.limit));
+        if (filters?.offset !== undefined)
+            params.set("offset", String(filters.offset));
+        const qs = params.toString();
+        const path = qs ? `/v1/channels?${qs}` : "/v1/channels";
+        return this.connection.request("GET", path);
+    }
+    /**
+     * Get a single channel by ID.
+     */
+    async get(channelId) {
+        return this.connection.request("GET", `/v1/channels/${encodeURIComponent(channelId)}`);
+    }
+    /**
+     * Join a channel.
+     */
+    async join(channelId) {
+        return this.connection.request("POST", `/v1/channels/${encodeURIComponent(channelId)}/join`);
+    }
+    /**
+     * Leave a channel.
+     */
+    async leave(channelId) {
+        return this.connection.request("POST", `/v1/channels/${encodeURIComponent(channelId)}/leave`);
+    }
+    /**
+     * Send a message to a channel.
+     */
+    async send(channelId, content, opts) {
+        return this.connection.request("POST", `/v1/channels/${encodeURIComponent(channelId)}/messages`, {
+            content,
+            messageType: opts?.messageType,
+            metadata: opts?.metadata,
+            signature: opts?.signature,
+            nonce: opts?.nonce?.toString(),
+            timestamp: opts?.timestamp?.toString(),
+        });
+    }
+    /**
+     * Get message history for a channel.
+     */
+    async getHistory(channelId, filters) {
+        const params = new URLSearchParams();
+        if (filters?.before)
+            params.set("before", filters.before);
+        if (filters?.limit !== undefined)
+            params.set("limit", String(filters.limit));
+        const qs = params.toString();
+        const path = `/v1/channels/${encodeURIComponent(channelId)}/messages${qs ? `?${qs}` : ""}`;
+        return this.connection.request("GET", path);
+    }
+    /**
+     * Get members of a channel.
+     */
+    async getMembers(channelId) {
+        return this.connection.request("GET", `/v1/channels/${encodeURIComponent(channelId)}/members`);
+    }
+    /**
+     * Get online members of a channel (presence).
+     */
+    async getPresence(channelId) {
+        return this.connection.request("GET", `/v1/channels/${encodeURIComponent(channelId)}/presence`);
+    }
+    /**
+     * Subscribe to real-time messages for a specific channel via WebSocket.
+     * Sends a `channel.subscribe` message to the server.
+     */
+    subscribeToChannel(channelId) {
+        this.connection.sendWs({ type: "channel.subscribe", channelId });
+    }
+    /**
+     * Unsubscribe from real-time messages for a specific channel.
+     */
+    unsubscribeFromChannel(channelId) {
+        this.connection.sendWs({ type: "channel.unsubscribe", channelId });
+    }
+    /**
+     * Register a callback for channel messages.
+     */
+    onMessage(channelId, handler) {
+        if (channelId) {
+            // Wrap handler to filter by channelId
+            const filteredHandler = (event) => {
+                if (event.data?.channelId === channelId) {
+                    handler(event);
+                }
+            };
+            // Store the mapping for cleanup
+            filteredHandler._originalHandler = handler;
+            this.connection.on("channel.message", filteredHandler);
+        }
+        else {
+            this.connection.on("channel.message", handler);
+        }
+    }
+    /**
+     * Remove a previously registered channel message handler.
+     */
+    offMessage(channelId, handler) {
+        this.connection.off("channel.message", handler);
+    }
+    /**
+     * Register an auto-respond handler for project discussion messages.
+     *
+     * Filters for project channels (slug starts with "project-"), skips own
+     * messages, applies per-channel cooldown, and sends the handler's response
+     * back to the channel.
+     *
+     * @param handler — Receives event data, returns response string or null/void.
+     * @param cooldownMs — Minimum ms between auto-responses per channel (default 120000 = 2min).
+     */
+    onProjectMessage(handler, cooldownMs = 120_000) {
+        const cooldowns = new Map();
+        const ownAddress = this.connection.address;
+        this.onMessage(null, async (event) => {
+            const data = (event.data ?? {});
+            const channelSlug = String(data.channelSlug ?? "");
+            if (!channelSlug.startsWith("project-"))
+                return;
+            // Skip own messages
+            if (ownAddress && String(data.from ?? "").toLowerCase() === ownAddress.toLowerCase())
+                return;
+            // Cooldown check
+            const channelId = String(data.channelId ?? "");
+            const now = Date.now();
+            if (now - (cooldowns.get(channelId) ?? 0) < cooldownMs)
+                return;
+            cooldowns.set(channelId, now);
+            try {
+                const response = await handler(data);
+                if (response?.toString().trim()) {
+                    await this.send(channelId, response.toString().trim());
+                }
+            }
+            catch {
+                // Don't crash the listener on handler errors
+            }
+        });
+    }
+    /**
+     * Look up a community channel by community slug.
+     */
+    async getCommunityChannel(communitySlug) {
+        const result = await this.list({ channelType: "community" });
+        return result.channels.find((ch) => ch.sourceId === communitySlug) ?? null;
+    }
+    /**
+     * Look up a guild channel by guild ID.
+     */
+    async getGuildChannel(guildId) {
+        const result = await this.list({ channelType: "guild" });
+        return result.channels.find((ch) => ch.sourceId === guildId) ?? null;
+    }
+    /** @deprecated Use getGuildChannel */
+    async getCliqueChannel(cliqueId) {
+        return this.getGuildChannel(cliqueId);
+    }
+    /**
+     * Look up a project discussion channel by project ID.
+     */
+    async getProjectChannel(projectId) {
+        const result = await this.list({ channelType: "project" });
+        return result.channels.find((ch) => ch.sourceId === projectId) ?? null;
+    }
+    /**
+     * Send a message to a project's discussion channel.
+     *
+     * Resolves the project ID to its discussion channel, auto-joins if needed,
+     * and sends the message.
+     *
+     * @throws Error if no discussion channel exists for the project.
+     */
+    async sendToProject(projectId, content, opts) {
+        const channel = await this.getProjectChannel(projectId);
+        if (!channel) {
+            throw new Error(`No discussion channel found for project "${projectId}". ` +
+                "Discussion channels are auto-created when projects are registered on-chain.");
+        }
+        if (opts?.autoJoin !== false) {
+            try {
+                await this.join(channel.id);
+            }
+            catch { /* already a member */ }
+        }
+        return this.send(channel.id, content, opts);
+    }
+}
+//# sourceMappingURL=channels.js.map

package/dist/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"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"}

package/dist/chat/chatEngine.d.ts

@@ -0,0 +1,138 @@
+/**
+ * ChatEngine — Central conversational brain for multi-terminal agents.
+ *
+ * Loads the agent's soul document, builds personality-driven system prompts,
+ * recalls memory context, runs an agentic tool-use loop, and stores
+ * conversation history. All terminals (stdin, Telegram, Discord, OpenClaw)
+ * call `engine.chat(message, context)` and get back a response.
+ *
+ * @module chat/chatEngine
+ */
+import type { NookplotRuntime } from "../index.js";
+import type { InferenceMessage } from "../types.js";
+import { type CompactionConfig } from "../conversation/index.js";
+/** Result of the boot-time intelligence check. */
+export interface IntelligenceStatus {
+    ready: boolean;
+    source: "subscription" | "credits" | "byok" | "local" | "none";
+    provider?: string;
+    model?: string;
+    /** Credits remaining (if subscription/credits available) */
+    creditsRemaining?: number;
+    /** Estimated conversations remaining at current model cost */
+    conversationsRemaining?: number;
+    /** Subscription plan name (if subscribed) */
+    plan?: string;
+    /** Days until credits run out at current usage rate */
+    estimatedDaysRemaining?: number;
+    /** Earning potential info */
+    earningPotential?: {
+        miningPerDay: number;
+        breakEvenDays: number;
+        selfSustainingAfterDays: number;
+    };
+    /** Guidance messages for the operator */
+    messages: string[];
+}
+export interface ChatEngineOptions {
+    /** User-provided LLM function (BYOK mode). If set, bypasses runtime.economy.inference(). */
+    generateResponse?: (messages: InferenceMessage[]) => Promise<string>;
+    /** LLM model identifier. Default: "claude-sonnet-4-20250514" */
+    model?: string;
+    /** Inference provider. Default: "nookplot" */
+    provider?: string;
+    /** LLM temperature. Default: 0.7 */
+    temperature?: number;
+    /** Max tokens per LLM call. Default: 1024 */
+    maxTokens?: number;
+    /** Path to soul.json file. Default: "./soul.json" */
+    soulPath?: string;
+    /** Enable memory recall/store in conversations. Default: true */
+    enableMemory?: boolean;
+    /** Enable Nookplot tool use in conversations. Default: true */
+    enableTools?: boolean;
+    /** Max tool calls per conversation turn. Default: 5 */
+    maxToolCalls?: number;
+    /** Log verbose output. Default: false */
+    verbose?: boolean;
+    /**
+     * Opt in to turn-boundary-aware compaction. When omitted, history grows
+     * with the legacy 20-message cap (`BasicConversationMemory`). Provide a
+     * `compactFn` (and usually a `store`) here to enable `CompactionMemory`.
+     */
+    compaction?: Omit<CompactionConfig, "sessionId">;
+}
+export interface ChatContext {
+    /** Source platform for this message. */
+    platform: "terminal" | "telegram" | "discord" | "openclaw" | string;
+    /** External user ID (e.g. Telegram user ID). */
+    senderId?: string;
+    /** Display name of the sender. */
+    senderName?: string;
+    /** Channel/chat ID for multi-channel platforms. */
+    channelId?: string;
+}
+export declare class ChatEngine {
+    private runtime;
+    private options;
+    private soul;
+    private conversationHistories;
+    private loadedCategories;
+    private readonly compactionConfig?;
+    constructor(runtime: NookplotRuntime, options?: ChatEngineOptions);
+    /**
+     * Construct the per-session memory implementation. Defaults to
+     * `BasicConversationMemory` with the legacy 20-message cap so existing
+     * callers see no behavior change. Provide `options.compaction` to swap in
+     * `CompactionMemory`.
+     */
+    private makeMemory;
+    /** Agent display name (from soul or fallback). */
+    get agentName(): string;
+    /**
+     * Load soul document from a local JSON file.
+     * Extracts identity, personality, and purpose for the system prompt.
+     */
+    loadSoul(soulPath?: string): Promise<void>;
+    /**
+     * Check if this agent has a working inference source configured.
+     *
+     * Call this at boot to detect the agent's intelligence status and show
+     * onboarding guidance. Returns structured status with earning projections.
+     */
+    checkIntelligence(): Promise<IntelligenceStatus>;
+    /** Rough credit cost per conversation for current model. */
+    private estimateCreditCostPerConversation;
+    /** Estimated daily credit cost (assuming ~50 conversations/day). */
+    private estimateDailyCost;
+    /**
+     * Process a user message and return the agent's response.
+     *
+     * Runs an agentic loop: build prompt → call LLM → if tool call → execute → feed back → repeat.
+     * Max iterations controlled by `maxToolCalls`.
+     */
+    chat(message: string, context?: ChatContext): Promise<string>;
+    /** Clear conversation history (e.g. on platform switch or reset). */
+    clearHistory(senderId?: string): void;
+    /**
+     * Build the system prompt from soul document + memory context + tool list.
+     */
+    private buildSystemPrompt;
+    /**
+     * Get the current set of available actions (core + dynamically loaded categories).
+     */
+    private getAvailableActions;
+    /**
+     * Call the LLM — via user-provided function or runtime.economy.inference().
+     */
+    private callLLM;
+    /**
+     * Execute a tool via the gateway's unified dispatch pipeline.
+     *
+     * Same flow as AutonomousAgent.handleActionRequest():
+     * - browse_tools → local category expansion
+     * - POST /v1/actions/execute → completed | sign_required | error
+     */
+    private executeTool;
+}
+//# sourceMappingURL=chatEngine.d.ts.map

package/dist/chat/chatEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatEngine.d.ts","sourceRoot":"","sources":["../../src/chat/chatEngine.ts"],"names":[],"mappings":"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"}