@tinyclaw/types 1.1.0-dev.7c8f470 → 1.1.0-dev.89e6aff

package/dist/index.d.ts

@@ -428,6 +428,18 @@ export interface ChannelPlugin extends PluginMeta {
      * These tools are merged into AgentContext.tools before the agent loop starts.
      */
     getPairingTools?(secrets: SecretsManagerInterface, configManager: ConfigManagerInterface): Tool[];
+    /**
+     * Send an outbound message to a user on this channel.
+     * Optional — channels that support proactive messaging implement this.
+     * The gateway calls this method to deliver nudges, task results, etc.
+     */
+    sendToUser?(userId: string, message: OutboundMessage): Promise<void>;
+    /**
+     * The userId prefix this channel owns (e.g. 'discord', 'friend', 'web').
+     * Used by the gateway to route outbound messages to the correct channel.
+     * If not provided, the gateway cannot route to this channel.
+     */
+    readonly channelPrefix?: string;
 }
 /** A provider plugin registers an additional LLM provider. */
 export interface ProviderPlugin extends PluginMeta {
@@ -458,6 +470,8 @@ export interface PluginRuntimeContext {
     secrets: SecretsManagerInterface;
     /** Config manager for reading/writing channel config. */
     configManager: ConfigManagerInterface;
+    /** Outbound gateway for sending proactive messages across channels. */
+    gateway?: OutboundGateway;
 }
 /** The three enforcement actions defined by the SHIELD.md v0.1 spec. */
 export type ShieldAction = 'block' | 'require_approval' | 'log';
@@ -546,6 +560,133 @@ export interface ShieldEngine {
     /** Get all loaded threat entries (for debugging/audit). */
     getThreats(): ThreatEntry[];
 }
+/** Priority levels for outbound messages. */
+export type OutboundPriority = 'urgent' | 'normal' | 'low';
+/** The source that triggered the outbound message. */
+export type OutboundSource = 'background_task' | 'sub_agent' | 'reminder' | 'pulse' | 'system' | 'agent';
+/**
+ * An outbound message to be delivered to a user.
+ */
+export interface OutboundMessage {
+    /** The message content to deliver. */
+    content: string;
+    /** Priority determines delivery urgency. */
+    priority: OutboundPriority;
+    /** What triggered this message. */
+    source: OutboundSource;
+    /** Optional metadata for channel-specific rendering. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Outbound Gateway — routes proactive messages to users across channels.
+ *
+ * The gateway maintains a registry of channel senders (keyed by userId prefix)
+ * and resolves the correct channel for each outbound message by inspecting the
+ * userId prefix (e.g. 'discord:123' → Discord channel, 'web:owner' → Web SSE).
+ */
+export interface OutboundGateway {
+    /**
+     * Register a channel sender for a given userId prefix.
+     * Called during boot after channel plugins are loaded.
+     */
+    register(prefix: string, sender: ChannelSender): void;
+    /**
+     * Unregister a channel sender (e.g. during shutdown).
+     */
+    unregister(prefix: string): void;
+    /**
+     * Send a message to a specific user.
+     * Resolves the userId prefix → channel sender → delivers.
+     */
+    send(userId: string, message: OutboundMessage): Promise<OutboundDeliveryResult>;
+    /**
+     * Broadcast a message to all registered channels.
+     * Each channel decides how to handle the broadcast (e.g. to all connected users).
+     */
+    broadcast(message: OutboundMessage): Promise<OutboundDeliveryResult[]>;
+    /**
+     * Get all registered channel prefixes.
+     */
+    getRegisteredChannels(): string[];
+}
+/**
+ * A channel sender — the outbound delivery contract that each channel implements.
+ * Registered with the gateway during boot.
+ */
+export interface ChannelSender {
+    /** The channel name (for logging/debugging). */
+    readonly name: string;
+    /** Send a message to a specific user on this channel. */
+    send(userId: string, message: OutboundMessage): Promise<void>;
+    /** Broadcast a message to all users on this channel. */
+    broadcast?(message: OutboundMessage): Promise<void>;
+}
+/**
+ * Result of an outbound delivery attempt.
+ */
+export interface OutboundDeliveryResult {
+    /** Whether delivery succeeded. */
+    success: boolean;
+    /** The channel prefix that handled delivery. */
+    channel: string;
+    /** The target userId. */
+    userId: string;
+    /** Error message if delivery failed. */
+    error?: string;
+}
+/** Categories of nudge notifications the agent can send proactively. */
+export type NudgeCategory = 'task_complete' | 'task_failed' | 'reminder' | 'check_in' | 'insight' | 'system' | 'software_update' | 'agent_initiated';
+/** A nudge queued for delivery. */
+export interface Nudge {
+    /** Unique nudge identifier. */
+    id: string;
+    /** Target userId (e.g. 'web:owner', 'discord:123'). */
+    userId: string;
+    /** Category for filtering and user preferences. */
+    category: NudgeCategory;
+    /** The message content to deliver. */
+    content: string;
+    /** Delivery priority. */
+    priority: OutboundPriority;
+    /** When the nudge was created. */
+    createdAt: number;
+    /** When the nudge should be delivered (0 = immediately). */
+    deliverAfter: number;
+    /** Whether this nudge has been delivered. */
+    delivered: boolean;
+    /** Optional metadata for context. */
+    metadata?: Record<string, unknown>;
+}
+/** User preferences for nudge behavior. */
+export interface NudgePreferences {
+    /** Master switch — disables all nudges when false. */
+    enabled: boolean;
+    /** Quiet hours start (24h format, e.g. '22:00'). Nudges are held until end. */
+    quietHoursStart?: string;
+    /** Quiet hours end (24h format, e.g. '08:00'). */
+    quietHoursEnd?: string;
+    /** Max nudges per hour (rate limiting). */
+    maxPerHour: number;
+    /** Per-category opt-out. Categories listed here are suppressed. */
+    suppressedCategories: NudgeCategory[];
+}
+/** The nudge engine interface. */
+export interface NudgeEngine {
+    /** Queue a nudge for delivery. Respects quiet hours and preferences. */
+    schedule(nudge: Omit<Nudge, 'id' | 'createdAt' | 'delivered'>): string;
+    /** Process pending nudges — deliver those that are due. */
+    flush(): Promise<void>;
+    /** Get all pending (undelivered) nudges. */
+    pending(): Nudge[];
+    /** Cancel a pending nudge by id. */
+    cancel(id: string): boolean;
+    /** Update user preferences. */
+    setPreferences(prefs: Partial<NudgePreferences>): void;
+    /** Get current preferences. */
+    getPreferences(): NudgePreferences;
+    /** Shut down the engine (clear timers). */
+    stop(): void;
+}
 export interface Signal {
     type: 'positive' | 'negative' | 'correction' | 'preference';
     confidence: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinyclaw/types",
-  "version": "1.1.0-dev.7c8f470",
+  "version": "1.1.0-dev.89e6aff",
   "description": "Shared TypeScript type definitions for Tiny Claw",
   "license": "GPL-3.0",
   "author": "Waren Gonzaga",