@iflow-mcp/jkheadley-instar 0.26.2

package/dist/types/pipeline.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Pipeline Types — typed contracts for the Telegram message flow.
+ *
+ * The Meta-Lesson: "Available But Dropped" bugs happen when data flows
+ * through loosely-typed handoffs. Adding a field at layer N doesn't
+ * surface all the places at layers N+1, N+2, N+3 that need to handle it.
+ *
+ * These types make every handoff explicit. If you add a field to
+ * TelegramInbound, TypeScript will force you to carry it through
+ * to PipelineMessage and InjectionPayload — or explicitly acknowledge
+ * the drop with a comment.
+ *
+ * Pipeline stages:
+ *   1. TelegramInbound — raw data from Telegram Bot API (processUpdate)
+ *   2. PipelineMessage — normalized internal message (wireTelegramRouting)
+ *   3. InjectionPayload — what gets injected into a Claude session
+ *   4. LogEntry — what gets persisted to the message log
+ *
+ * Conversion functions:
+ *   toInbound()     → TelegramInbound    (from TelegramUpdate)
+ *   toPipeline()    → PipelineMessage     (from TelegramInbound)
+ *   toInjection()   → InjectionPayload   (from PipelineMessage)
+ *   toLogEntry()    → PipelineLogEntry    (from PipelineMessage)
+ *
+ * Security: Input sanitization (User-Agent Topology Spec, Gap 12)
+ *   toInjection() applies sanitizeSenderName() and sanitizeTopicName() at
+ *   the injection boundary — the point where untrusted user-controlled
+ *   content enters the LLM session context.
+ */
+/**
+ * The sender's identity as provided by Telegram.
+ * Every field here MUST flow through to the session.
+ */
+export interface TelegramSender {
+    /** Telegram numeric user ID */
+    telegramUserId: number;
+    /** Display name (first_name from Telegram) */
+    firstName: string;
+    /** @username (optional — not all users have one) */
+    username?: string;
+}
+/**
+ * Raw inbound message from Telegram, normalized from TelegramUpdate.
+ * This is the "source of truth" — all downstream stages derive from this.
+ */
+export interface TelegramInbound {
+    /** Telegram message ID */
+    messageId: number;
+    /** The sender's identity — NEVER optional, always extracted from Telegram API */
+    sender: TelegramSender;
+    /** Topic thread ID (GENERAL_TOPIC_ID=1 for General) */
+    topicId: number;
+    /** Topic name (from forum_topic_created or registry) */
+    topicName?: string;
+    /** Message content */
+    content: string;
+    /** Message type */
+    type: 'text' | 'voice' | 'photo' | 'document';
+    /** When the message was sent (Telegram date) */
+    timestamp: string;
+    /** Type-specific metadata */
+    media?: {
+        /** Path to downloaded voice/photo file */
+        filePath?: string;
+        /** Voice duration in seconds */
+        voiceDuration?: number;
+        /** Photo caption */
+        caption?: string;
+    };
+}
+/**
+ * Normalized internal message — the common format used by routing,
+ * stall detection, sentinel intercept, and topic callbacks.
+ *
+ * Every field from TelegramInbound is preserved or explicitly
+ * transformed (e.g., voice → "[voice] transcript").
+ */
+export interface PipelineMessage {
+    /** Unique message ID (format: "tg-{telegramMessageId}") */
+    id: string;
+    /** Sender identity — carried from TelegramInbound, never dropped */
+    sender: TelegramSender;
+    /** Topic ID */
+    topicId: number;
+    /** Topic name (if known from registry) */
+    topicName?: string;
+    /** Processed text content (voice → transcript, photo → [image:path]) */
+    content: string;
+    /** Original message type */
+    type: 'text' | 'voice' | 'photo' | 'document';
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** The tmux session this message is routed to (set during routing) */
+    targetSession?: string;
+}
+/**
+ * What gets injected into a Claude tmux session.
+ * The final transformation — all context must be embedded in the text.
+ *
+ * Format: [telegram:42 "Topic Name" from Justin (uid:12345)] message text
+ *
+ * The UID is the authoritative identity — display names are for readability.
+ * Sanitization is applied at this boundary (see toInjection()).
+ */
+export interface InjectionPayload {
+    /** Target tmux session name */
+    tmuxSession: string;
+    /** Topic ID (for tracking/stall detection) */
+    topicId: number;
+    /** Fully tagged text ready for injection.
+     * Includes topic name, sender identity, and UID in the tag. */
+    taggedText: string;
+    /** Sender name (for delivery confirmation, stall tracking) */
+    senderName?: string;
+    /** Telegram user ID (for identity tracking) */
+    telegramUserId?: number;
+}
+/**
+ * What gets persisted to the JSONL message log.
+ * Includes all identity fields for historical search and replay.
+ */
+export interface PipelineLogEntry {
+    messageId: number;
+    topicId: number | null;
+    text: string;
+    fromUser: boolean;
+    timestamp: string;
+    sessionName: string | null;
+    /** Sender identity — NEVER omitted for user messages */
+    senderName?: string;
+    senderUsername?: string;
+    telegramUserId?: number;
+}
+/**
+ * Convert a raw Telegram message to a TelegramInbound.
+ * This is the entry point — where we first capture all identity data.
+ */
+export declare function toInbound(msg: {
+    message_id: number;
+    from: {
+        id: number;
+        first_name: string;
+        username?: string;
+    };
+    message_thread_id?: number;
+    date: number;
+    text?: string;
+    reply_to_message?: {
+        forum_topic_created?: {
+            name: string;
+        };
+    };
+}, opts: {
+    topicName?: string;
+    content: string;
+    type: 'text' | 'voice' | 'photo' | 'document';
+    media?: TelegramInbound['media'];
+}): TelegramInbound;
+/**
+ * Convert a TelegramInbound to a PipelineMessage.
+ * Identity is carried through — this is where the "Available But Dropped" pattern
+ * used to strike. Now the types enforce it.
+ */
+export declare function toPipeline(inbound: TelegramInbound): PipelineMessage;
+/**
+ * Convert a PipelineMessage to an InjectionPayload.
+ * This is where identity becomes embedded in the text tag.
+ *
+ * Format: [telegram:42 "Topic Name" from Justin (uid:12345)] message text
+ *
+ * Security: This is the injection boundary — user-controlled content (display
+ * names, topic names) enters the LLM session context here. Sanitization is
+ * applied per User-Agent Topology Spec, Gap 12.
+ *
+ * The UID is the authoritative identity. Display names are for readability
+ * but MUST NOT be trusted for authorization decisions.
+ */
+export declare function toInjection(pipeline: PipelineMessage, tmuxSession: string): InjectionPayload;
+/**
+ * Build the injection tag string.
+ *
+ * Exported for use by SessionManager.injectTelegramMessage() to avoid
+ * duplicating the tag-building logic.
+ *
+ * Tag format variants:
+ *   [telegram:42 "Topic Name" from Justin (uid:12345)]
+ *   [telegram:42 "Topic Name" from Justin]           — when UID unknown
+ *   [telegram:42 "Topic Name"]                       — when sender unknown
+ *   [telegram:42 from Justin (uid:12345)]             — when no topic name
+ *   [telegram:42]                                     — bare minimum
+ */
+export declare function buildInjectionTag(topicId: number, topicName?: string, senderName?: string, telegramUserId?: number): string;
+/**
+ * Convert a PipelineMessage to a log entry.
+ * All identity fields are preserved for historical search.
+ */
+export declare function toLogEntry(pipeline: PipelineMessage, sessionName: string | null): PipelineLogEntry;
+/**
+ * Build a session history line from a log entry.
+ * Uses the actual sender name instead of generic "User".
+ */
+export declare function formatHistoryLine(entry: PipelineLogEntry): string;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/types/pipeline.d.ts.map

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

package/dist/types/pipeline.js

@@ -0,0 +1,152 @@
+/**
+ * Pipeline Types — typed contracts for the Telegram message flow.
+ *
+ * The Meta-Lesson: "Available But Dropped" bugs happen when data flows
+ * through loosely-typed handoffs. Adding a field at layer N doesn't
+ * surface all the places at layers N+1, N+2, N+3 that need to handle it.
+ *
+ * These types make every handoff explicit. If you add a field to
+ * TelegramInbound, TypeScript will force you to carry it through
+ * to PipelineMessage and InjectionPayload — or explicitly acknowledge
+ * the drop with a comment.
+ *
+ * Pipeline stages:
+ *   1. TelegramInbound — raw data from Telegram Bot API (processUpdate)
+ *   2. PipelineMessage — normalized internal message (wireTelegramRouting)
+ *   3. InjectionPayload — what gets injected into a Claude session
+ *   4. LogEntry — what gets persisted to the message log
+ *
+ * Conversion functions:
+ *   toInbound()     → TelegramInbound    (from TelegramUpdate)
+ *   toPipeline()    → PipelineMessage     (from TelegramInbound)
+ *   toInjection()   → InjectionPayload   (from PipelineMessage)
+ *   toLogEntry()    → PipelineLogEntry    (from PipelineMessage)
+ *
+ * Security: Input sanitization (User-Agent Topology Spec, Gap 12)
+ *   toInjection() applies sanitizeSenderName() and sanitizeTopicName() at
+ *   the injection boundary — the point where untrusted user-controlled
+ *   content enters the LLM session context.
+ */
+import { sanitizeSenderName, sanitizeTopicName } from '../utils/sanitize.js';
+// ── Conversion Functions ──────────────────────────────────────────
+/**
+ * Convert a raw Telegram message to a TelegramInbound.
+ * This is the entry point — where we first capture all identity data.
+ */
+export function toInbound(msg, opts) {
+    return {
+        messageId: msg.message_id,
+        sender: {
+            telegramUserId: msg.from.id,
+            firstName: msg.from.first_name,
+            username: msg.from.username,
+        },
+        topicId: msg.message_thread_id ?? 1,
+        topicName: opts.topicName || msg.reply_to_message?.forum_topic_created?.name,
+        content: opts.content,
+        type: opts.type,
+        timestamp: new Date(msg.date * 1000).toISOString(),
+        media: opts.media,
+    };
+}
+/**
+ * Convert a TelegramInbound to a PipelineMessage.
+ * Identity is carried through — this is where the "Available But Dropped" pattern
+ * used to strike. Now the types enforce it.
+ */
+export function toPipeline(inbound) {
+    return {
+        id: `tg-${inbound.messageId}`,
+        sender: inbound.sender, // Explicit carry-through
+        topicId: inbound.topicId,
+        topicName: inbound.topicName,
+        content: inbound.content,
+        type: inbound.type,
+        timestamp: inbound.timestamp,
+    };
+}
+/**
+ * Convert a PipelineMessage to an InjectionPayload.
+ * This is where identity becomes embedded in the text tag.
+ *
+ * Format: [telegram:42 "Topic Name" from Justin (uid:12345)] message text
+ *
+ * Security: This is the injection boundary — user-controlled content (display
+ * names, topic names) enters the LLM session context here. Sanitization is
+ * applied per User-Agent Topology Spec, Gap 12.
+ *
+ * The UID is the authoritative identity. Display names are for readability
+ * but MUST NOT be trusted for authorization decisions.
+ */
+export function toInjection(pipeline, tmuxSession) {
+    const { topicId, topicName, sender, content } = pipeline;
+    // Sanitize user-controlled content at the injection boundary
+    const safeName = sanitizeSenderName(sender.firstName);
+    const safeTopic = topicName ? sanitizeTopicName(topicName) : undefined;
+    const uid = sender.telegramUserId;
+    // Build the tag — always includes sender when available, UID when known
+    const topicTag = buildInjectionTag(topicId, safeTopic, safeName, uid);
+    return {
+        tmuxSession,
+        topicId,
+        taggedText: `${topicTag} ${content}`,
+        senderName: safeName !== 'Unknown' ? safeName : sender.firstName,
+        telegramUserId: uid,
+    };
+}
+/**
+ * Build the injection tag string.
+ *
+ * Exported for use by SessionManager.injectTelegramMessage() to avoid
+ * duplicating the tag-building logic.
+ *
+ * Tag format variants:
+ *   [telegram:42 "Topic Name" from Justin (uid:12345)]
+ *   [telegram:42 "Topic Name" from Justin]           — when UID unknown
+ *   [telegram:42 "Topic Name"]                       — when sender unknown
+ *   [telegram:42 from Justin (uid:12345)]             — when no topic name
+ *   [telegram:42]                                     — bare minimum
+ */
+export function buildInjectionTag(topicId, topicName, senderName, telegramUserId) {
+    const uidSuffix = telegramUserId ? ` (uid:${telegramUserId})` : '';
+    if (topicName && senderName) {
+        return `[telegram:${topicId} "${topicName}" from ${senderName}${uidSuffix}]`;
+    }
+    else if (topicName) {
+        return `[telegram:${topicId} "${topicName}"]`;
+    }
+    else if (senderName) {
+        return `[telegram:${topicId} from ${senderName}${uidSuffix}]`;
+    }
+    else {
+        return `[telegram:${topicId}]`;
+    }
+}
+/**
+ * Convert a PipelineMessage to a log entry.
+ * All identity fields are preserved for historical search.
+ */
+export function toLogEntry(pipeline, sessionName) {
+    return {
+        messageId: parseInt(pipeline.id.replace('tg-', ''), 10),
+        topicId: pipeline.topicId,
+        text: pipeline.content,
+        fromUser: true,
+        timestamp: pipeline.timestamp,
+        sessionName,
+        senderName: pipeline.sender.firstName,
+        senderUsername: pipeline.sender.username,
+        telegramUserId: pipeline.sender.telegramUserId,
+    };
+}
+/**
+ * Build a session history line from a log entry.
+ * Uses the actual sender name instead of generic "User".
+ */
+export function formatHistoryLine(entry) {
+    const sender = entry.fromUser
+        ? (entry.senderName || 'User')
+        : 'Agent';
+    return `${sender}: ${entry.text}`;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/types/pipeline.js.map

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

package/dist/users/GdprCommands.d.ts

@@ -0,0 +1,44 @@
+/**
+ * GDPR Data Access Commands — /mydata and /forget
+ *
+ * Implements GDPR Article 15 (Right of Access) and Article 17 (Right to Erasure)
+ * across all memory stores (TopicMemory + SemanticMemory).
+ *
+ * Usage:
+ *   /mydata  — Export all data associated with a user
+ *   /forget  — Delete all data associated with a user
+ *
+ * Design principles:
+ *   - Fail-closed: if a memory store is unavailable, report it rather than silently skip
+ *   - Audit trail: all operations are logged with timestamps
+ *   - Idempotent: running /forget twice is safe
+ *   - User-scoped: only affects data owned by the requesting user
+ */
+import type { UserDataExport, UserErasureResult, UserProfile } from '../core/types.js';
+import type { TopicMemory } from '../memory/TopicMemory.js';
+import type { SemanticMemory } from '../memory/SemanticMemory.js';
+export interface GdprCommandDeps {
+    topicMemory?: TopicMemory;
+    semanticMemory?: SemanticMemory;
+    /** User profile for the export (optional — included when available) */
+    userProfile?: UserProfile;
+}
+/**
+ * Export all data for a user across all memory stores.
+ * Implements GDPR Article 15 (Right of Access).
+ */
+export declare function exportUserData(userId: string, deps: GdprCommandDeps): UserDataExport;
+/**
+ * Delete all data for a user across all memory stores.
+ * Implements GDPR Article 17 (Right to Erasure).
+ */
+export declare function eraseUserData(userId: string, deps: GdprCommandDeps): UserErasureResult;
+/**
+ * Format a user data export for display (e.g., in a Telegram message).
+ */
+export declare function formatExportSummary(data: UserDataExport): string;
+/**
+ * Format an erasure result for display.
+ */
+export declare function formatErasureSummary(result: UserErasureResult): string;
+//# sourceMappingURL=GdprCommands.d.ts.map

package/dist/users/GdprCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GdprCommands.d.ts","sourceRoot":"","sources":["../../src/users/GdprCommands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,GACpB,cAAc,CAoDhB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,GACpB,iBAAiB,CAyBnB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAahE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAqBtE"}

package/dist/users/GdprCommands.js

@@ -0,0 +1,153 @@
+/**
+ * GDPR Data Access Commands — /mydata and /forget
+ *
+ * Implements GDPR Article 15 (Right of Access) and Article 17 (Right to Erasure)
+ * across all memory stores (TopicMemory + SemanticMemory).
+ *
+ * Usage:
+ *   /mydata  — Export all data associated with a user
+ *   /forget  — Delete all data associated with a user
+ *
+ * Design principles:
+ *   - Fail-closed: if a memory store is unavailable, report it rather than silently skip
+ *   - Audit trail: all operations are logged with timestamps
+ *   - Idempotent: running /forget twice is safe
+ *   - User-scoped: only affects data owned by the requesting user
+ */
+/**
+ * Export all data for a user across all memory stores.
+ * Implements GDPR Article 15 (Right of Access).
+ */
+export function exportUserData(userId, deps) {
+    const now = new Date().toISOString();
+    // ── TopicMemory messages ────────────────────────────────────────
+    const messagesByTopic = new Map();
+    if (deps.topicMemory) {
+        const userMessages = deps.topicMemory.getMessagesByUser(userId);
+        for (const msg of userMessages) {
+            const topicId = msg.topicId;
+            if (!messagesByTopic.has(topicId)) {
+                messagesByTopic.set(topicId, []);
+            }
+            messagesByTopic.get(topicId).push({
+                text: msg.text ?? '',
+                fromUser: msg.fromUser,
+                timestamp: msg.timestamp,
+                topicId,
+            });
+        }
+    }
+    const messages = Array.from(messagesByTopic.entries()).map(([topicId, msgs]) => ({
+        topicId,
+        messageCount: msgs.length,
+        messages: msgs,
+    }));
+    // ── SemanticMemory entities ─────────────────────────────────────
+    const knowledgeEntities = [];
+    if (deps.semanticMemory) {
+        const userEntities = deps.semanticMemory.getEntitiesByUser(userId);
+        for (const entity of userEntities) {
+            knowledgeEntities.push({
+                name: entity.name,
+                type: entity.type,
+                content: entity.content,
+                createdAt: entity.createdAt,
+            });
+        }
+    }
+    return {
+        exportedAt: now,
+        exportVersion: '2.0',
+        userId,
+        profile: deps.userProfile ?? createMinimalProfile(userId),
+        messages,
+        knowledgeEntities,
+        activityDigests: [], // Phase 2E scope: TopicMemory + SemanticMemory only
+    };
+}
+/**
+ * Delete all data for a user across all memory stores.
+ * Implements GDPR Article 17 (Right to Erasure).
+ */
+export function eraseUserData(userId, deps) {
+    const now = new Date().toISOString();
+    let messagesDeleted = 0;
+    let entitiesDeleted = 0;
+    const retainedItems = [];
+    // Erase from TopicMemory
+    if (deps.topicMemory) {
+        messagesDeleted = deps.topicMemory.deleteMessagesByUser(userId);
+    }
+    // Erase from SemanticMemory
+    if (deps.semanticMemory) {
+        entitiesDeleted = deps.semanticMemory.deleteEntitiesByUser(userId);
+    }
+    return {
+        userId,
+        erasedAt: now,
+        messagesDeleted,
+        entitiesDeleted,
+        digestsDeleted: 0, // Phase 2E scope: TopicMemory + SemanticMemory only
+        profileRemoved: false, // Profile removal handled separately by UserManager
+        retainedItems,
+    };
+}
+/**
+ * Format a user data export for display (e.g., in a Telegram message).
+ */
+export function formatExportSummary(data) {
+    const totalMessages = data.messages.reduce((sum, t) => sum + t.messageCount, 0);
+    const lines = [
+        `Data Export for ${data.userId}`,
+        `Exported: ${data.exportedAt}`,
+        ``,
+        `Messages: ${totalMessages} across ${data.messages.length} topic(s)`,
+        `Knowledge entities: ${data.knowledgeEntities.length}`,
+        `Activity digests: ${data.activityDigests.length}`,
+    ];
+    return lines.join('\n');
+}
+/**
+ * Format an erasure result for display.
+ */
+export function formatErasureSummary(result) {
+    const total = result.messagesDeleted + result.entitiesDeleted + result.digestsDeleted;
+    const lines = [
+        `Data Erasure for ${result.userId}`,
+        `Erased: ${result.erasedAt}`,
+        ``,
+        `Messages deleted: ${result.messagesDeleted}`,
+        `Entities deleted: ${result.entitiesDeleted}`,
+        `Digests deleted: ${result.digestsDeleted}`,
+        `Total: ${total}`,
+    ];
+    if (result.retainedItems.length > 0) {
+        lines.push('', 'Retained items:');
+        for (const item of result.retainedItems) {
+            lines.push(`  - ${item.count} ${item.type}: ${item.reason}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ── Helpers ──────────────────────────────────────────────────────
+/** Create a minimal profile stub for exports when the full profile is unavailable */
+function createMinimalProfile(userId) {
+    return {
+        id: userId,
+        name: userId,
+        channels: [],
+        permissions: ['user'],
+        preferences: {},
+        dataCollected: {
+            name: true,
+            telegramId: false,
+            communicationPreferences: false,
+            conversationHistory: false,
+            memoryEntries: false,
+            machineIdentities: false,
+        },
+        pendingTelegramTopic: false,
+        createdAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=GdprCommands.js.map

package/dist/users/GdprCommands.js.map

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