@dotsetlabs/dotclaw 1.1.0

package/container/agent-runner/src/ipc.ts

@@ -0,0 +1,321 @@
+/**
+ * IPC utilities for DotClaw (container-side).
+ * Writes messages and task operations to /workspace/ipc for the host to consume.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { CronExpressionParser } from 'cron-parser';
+
+const IPC_DIR = '/workspace/ipc';
+const MESSAGES_DIR = path.join(IPC_DIR, 'messages');
+const TASKS_DIR = path.join(IPC_DIR, 'tasks');
+const REQUESTS_DIR = path.join(IPC_DIR, 'requests');
+const RESPONSES_DIR = path.join(IPC_DIR, 'responses');
+
+export interface IpcContext {
+  chatJid: string;
+  groupFolder: string;
+  isMain: boolean;
+}
+
+export interface IpcConfig {
+  requestTimeoutMs: number;
+  requestPollMs: number;
+}
+
+function writeIpcFile(dir: string, data: object): string {
+  fs.mkdirSync(dir, { recursive: true });
+
+  const filename = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`;
+  const filepath = path.join(dir, filename);
+
+  const tempPath = `${filepath}.tmp`;
+  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tempPath, filepath);
+
+  return filename;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function requestResponse(
+  type: string,
+  payload: Record<string, unknown>,
+  config: IpcConfig,
+  timeoutMs = config.requestTimeoutMs
+) {
+  fs.mkdirSync(REQUESTS_DIR, { recursive: true });
+  fs.mkdirSync(RESPONSES_DIR, { recursive: true });
+
+  const id = `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  writeIpcFile(REQUESTS_DIR, {
+    id,
+    type,
+    payload,
+    timestamp: new Date().toISOString()
+  });
+
+  const deadline = Date.now() + timeoutMs;
+  const responsePath = path.join(RESPONSES_DIR, `${id}.json`);
+
+  while (Date.now() < deadline) {
+    if (fs.existsSync(responsePath)) {
+      const responseRaw = fs.readFileSync(responsePath, 'utf-8');
+      fs.unlinkSync(responsePath);
+      try {
+        return JSON.parse(responseRaw);
+      } catch {
+        return { ok: false, error: 'Failed to parse IPC response' };
+      }
+    }
+    await sleep(config.requestPollMs);
+  }
+
+  return { ok: false, error: `IPC request timeout (${timeoutMs}ms)` };
+}
+
+export function createIpcHandlers(ctx: IpcContext, config: IpcConfig) {
+  const { chatJid, groupFolder, isMain } = ctx;
+
+  return {
+    async sendMessage(text: string) {
+      const data = {
+        type: 'message',
+        chatJid,
+        text,
+        groupFolder,
+        timestamp: new Date().toISOString()
+      };
+      const filename = writeIpcFile(MESSAGES_DIR, data);
+      return { ok: true, id: filename };
+    },
+    async sendDraft(text: string, draftId: number) {
+      const data = {
+        type: 'message_draft',
+        chatJid,
+        text,
+        draftId,
+        groupFolder,
+        timestamp: new Date().toISOString()
+      };
+      const filename = writeIpcFile(MESSAGES_DIR, data);
+      return { ok: true, id: filename };
+    },
+
+    async scheduleTask(args: {
+      prompt: string;
+      schedule_type: 'cron' | 'interval' | 'once';
+      schedule_value: string;
+      context_mode?: 'group' | 'isolated';
+      target_group?: string;
+    }) {
+      if (args.schedule_type === 'cron') {
+        try {
+          CronExpressionParser.parse(args.schedule_value);
+        } catch {
+          return {
+            ok: false,
+            error: `Invalid cron: "${args.schedule_value}". Use format like "0 9 * * *" (daily 9am) or "*/5 * * * *" (every 5 min).`
+          };
+        }
+      } else if (args.schedule_type === 'interval') {
+        const ms = parseInt(args.schedule_value, 10);
+        if (isNaN(ms) || ms <= 0) {
+          return {
+            ok: false,
+            error: `Invalid interval: "${args.schedule_value}". Must be positive milliseconds (e.g., "300000" for 5 min).`
+          };
+        }
+      } else if (args.schedule_type === 'once') {
+        const date = new Date(args.schedule_value);
+        if (isNaN(date.getTime())) {
+          return {
+            ok: false,
+            error: `Invalid timestamp: "${args.schedule_value}". Use local ISO 8601 format like "2026-02-01T15:30:00" (no Z/UTC suffix).`
+          };
+        }
+      }
+
+      const targetGroup = isMain && args.target_group ? args.target_group : groupFolder;
+
+      const data = {
+        type: 'schedule_task',
+        prompt: args.prompt,
+        schedule_type: args.schedule_type,
+        schedule_value: args.schedule_value,
+        context_mode: args.context_mode || 'group',
+        groupFolder: targetGroup,
+        chatJid,
+        createdBy: groupFolder,
+        timestamp: new Date().toISOString()
+      };
+
+      const filename = writeIpcFile(TASKS_DIR, data);
+      return { ok: true, id: filename };
+    },
+
+    async listTasks() {
+      const tasksFile = path.join(IPC_DIR, 'current_tasks.json');
+      if (!fs.existsSync(tasksFile)) {
+        return { ok: true, tasks: [] as string[] };
+      }
+      const allTasks = JSON.parse(fs.readFileSync(tasksFile, 'utf-8'));
+      const tasks = isMain
+        ? allTasks
+        : allTasks.filter((t: { groupFolder: string }) => t.groupFolder === groupFolder);
+      return { ok: true, tasks };
+    },
+
+    async pauseTask(taskId: string) {
+      writeIpcFile(TASKS_DIR, {
+        type: 'pause_task',
+        taskId,
+        groupFolder,
+        isMain,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async resumeTask(taskId: string) {
+      writeIpcFile(TASKS_DIR, {
+        type: 'resume_task',
+        taskId,
+        groupFolder,
+        isMain,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async cancelTask(taskId: string) {
+      writeIpcFile(TASKS_DIR, {
+        type: 'cancel_task',
+        taskId,
+        groupFolder,
+        isMain,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async updateTask(args: { task_id: string; state_json?: string; prompt?: string; schedule_type?: string; schedule_value?: string; context_mode?: string; status?: string }) {
+      writeIpcFile(TASKS_DIR, {
+        type: 'update_task',
+        taskId: args.task_id,
+        state_json: args.state_json,
+        prompt: args.prompt,
+        schedule_type: args.schedule_type,
+        schedule_value: args.schedule_value,
+        context_mode: args.context_mode,
+        status: args.status,
+        groupFolder,
+        isMain,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async registerGroup(args: { jid: string; name: string; folder: string; trigger?: string }) {
+      if (!isMain) {
+        return { ok: false, error: 'Only the main group can register new groups.' };
+      }
+      writeIpcFile(TASKS_DIR, {
+        type: 'register_group',
+        jid: args.jid,
+        name: args.name,
+        folder: args.folder,
+        trigger: args.trigger,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async removeGroup(args: { identifier: string }) {
+      if (!isMain) {
+        return { ok: false, error: 'Only the main group can remove groups.' };
+      }
+      if (!args.identifier || typeof args.identifier !== 'string') {
+        return { ok: false, error: 'identifier is required (chat id, name, or folder).' };
+      }
+      writeIpcFile(TASKS_DIR, {
+        type: 'remove_group',
+        identifier: args.identifier,
+        groupFolder,
+        isMain,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async listGroups() {
+      if (!isMain) {
+        return { ok: false, error: 'Only the main group can list groups.' };
+      }
+      return requestResponse('list_groups', {}, config);
+    },
+
+    async setModel(args: { model: string; scope?: 'global' | 'group' | 'user'; target_id?: string }) {
+      if (!isMain) {
+        return { ok: false, error: 'Only the main group can change the model.' };
+      }
+      writeIpcFile(TASKS_DIR, {
+        type: 'set_model',
+        model: args.model,
+        scope: args.scope,
+        target_id: args.target_id,
+        groupFolder,
+        chatJid,
+        timestamp: new Date().toISOString()
+      });
+      return { ok: true };
+    },
+
+    async memoryUpsert(args: { items: unknown[]; source?: string; target_group?: string }) {
+      return requestResponse('memory_upsert', {
+        items: args.items,
+        source: args.source,
+        target_group: args.target_group
+      }, config);
+    },
+
+    async memoryForget(args: { ids?: string[]; content?: string; scope?: string; userId?: string; target_group?: string }) {
+      return requestResponse('memory_forget', {
+        ids: args.ids,
+        content: args.content,
+        scope: args.scope,
+        userId: args.userId,
+        target_group: args.target_group
+      }, config);
+    },
+
+    async memoryList(args: { scope?: string; type?: string; userId?: string; limit?: number; target_group?: string }) {
+      return requestResponse('memory_list', {
+        scope: args.scope,
+        type: args.type,
+        userId: args.userId,
+        limit: args.limit,
+        target_group: args.target_group
+      }, config);
+    },
+
+    async memorySearch(args: { query: string; userId?: string; limit?: number; target_group?: string }) {
+      return requestResponse('memory_search', {
+        query: args.query,
+        userId: args.userId,
+        limit: args.limit,
+        target_group: args.target_group
+      }, config);
+    },
+
+    async memoryStats(args: { userId?: string; target_group?: string }) {
+      return requestResponse('memory_stats', {
+        userId: args.userId,
+        target_group: args.target_group
+      }, config);
+    }
+  };
+}

package/container/agent-runner/src/memory.ts

@@ -0,0 +1,336 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+export interface Message {
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: string;
+  seq: number;
+}
+
+export interface SessionMeta {
+  sessionId: string;
+  createdAt: string;
+  updatedAt: string;
+  nextSeq: number;
+}
+
+export interface MemoryState {
+  summary: string;
+  facts: string[];
+  lastSummarySeq: number;
+  updatedAt: string;
+  schemaVersion: number;
+}
+
+export interface SessionContext {
+  sessionId: string;
+  sessionDir: string;
+  historyPath: string;
+  metaPath: string;
+  statePath: string;
+  meta: SessionMeta;
+  state: MemoryState;
+}
+
+export interface MemoryConfig {
+  maxContextTokens: number;
+  compactionTriggerTokens: number;
+  recentContextTokens: number;
+  summaryUpdateEveryMessages: number;
+  memoryMaxResults: number;
+  memoryMaxTokens: number;
+}
+
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(Buffer.byteLength(text, 'utf-8') / 4);
+}
+
+export function createSessionContext(sessionRoot: string, sessionId?: string): { ctx: SessionContext; isNew: boolean } {
+  fs.mkdirSync(sessionRoot, { recursive: true });
+  let isNew = false;
+  let resolvedSessionId = sessionId?.trim();
+  if (!resolvedSessionId) {
+    resolvedSessionId = `session-${crypto.randomUUID()}`;
+    isNew = true;
+  }
+
+  const sessionDir = path.join(sessionRoot, resolvedSessionId);
+  fs.mkdirSync(sessionDir, { recursive: true });
+
+  const metaPath = path.join(sessionDir, 'session.json');
+  const statePath = path.join(sessionDir, 'memory.json');
+  const historyPath = path.join(sessionDir, 'history.jsonl');
+
+  let meta: SessionMeta;
+  if (fs.existsSync(metaPath)) {
+    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } else {
+    meta = {
+      sessionId: resolvedSessionId,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      nextSeq: 1
+    };
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+    isNew = true;
+  }
+
+  let state: MemoryState;
+  if (fs.existsSync(statePath)) {
+    state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+  } else {
+    state = {
+      summary: '',
+      facts: [],
+      lastSummarySeq: 0,
+      updatedAt: new Date().toISOString(),
+      schemaVersion: 1
+    };
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+  }
+
+  return {
+    ctx: {
+      sessionId: resolvedSessionId,
+      sessionDir,
+      historyPath,
+      metaPath,
+      statePath,
+      meta,
+      state
+    },
+    isNew
+  };
+}
+
+export function saveSessionMeta(ctx: SessionContext): void {
+  ctx.meta.updatedAt = new Date().toISOString();
+  fs.writeFileSync(ctx.metaPath, JSON.stringify(ctx.meta, null, 2));
+}
+
+export function saveMemoryState(ctx: SessionContext): void {
+  ctx.state.updatedAt = new Date().toISOString();
+  fs.writeFileSync(ctx.statePath, JSON.stringify(ctx.state, null, 2));
+}
+
+export function appendHistory(ctx: SessionContext, role: 'user' | 'assistant', content: string): Message {
+  const message: Message = {
+    role,
+    content,
+    timestamp: new Date().toISOString(),
+    seq: ctx.meta.nextSeq
+  };
+  ctx.meta.nextSeq += 1;
+  fs.appendFileSync(ctx.historyPath, `${JSON.stringify(message)}\n`);
+  saveSessionMeta(ctx);
+  return message;
+}
+
+export function loadHistory(ctx: SessionContext): Message[] {
+  if (!fs.existsSync(ctx.historyPath)) return [];
+  const lines = fs.readFileSync(ctx.historyPath, 'utf-8').trim().split('\n');
+  const messages: Message[] = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed?.role && parsed?.content) {
+        messages.push(parsed);
+      }
+    } catch {
+      // ignore malformed lines
+    }
+  }
+  return messages;
+}
+
+export function writeHistory(ctx: SessionContext, messages: Message[]): void {
+  if (messages.length === 0) {
+    if (fs.existsSync(ctx.historyPath)) fs.unlinkSync(ctx.historyPath);
+    return;
+  }
+  const content = messages.map(m => JSON.stringify(m)).join('\n') + '\n';
+  fs.writeFileSync(ctx.historyPath, content);
+}
+
+export function splitRecentHistory(messages: Message[], tokenBudget: number, minMessages = 4) {
+  const recent: Message[] = [];
+  let tokens = 0;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    const msgTokens = estimateTokens(message.content);
+    if (tokens + msgTokens > tokenBudget && recent.length >= minMessages) {
+      break;
+    }
+    recent.push(message);
+    tokens += msgTokens;
+  }
+  const recentMessages = recent.reverse();
+  const recentSet = new Set(recentMessages.map(m => m.seq));
+  const olderMessages = messages.filter(m => !recentSet.has(m.seq));
+  return { recentMessages, olderMessages };
+}
+
+export function shouldCompact(totalTokens: number, config: MemoryConfig): boolean {
+  return totalTokens >= config.compactionTriggerTokens;
+}
+
+export function formatTranscriptMarkdown(messages: Message[], title?: string | null): string {
+  const now = new Date();
+  const formatDateTime = (d: Date) => d.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true
+  });
+
+  const lines: string[] = [];
+  lines.push(`# ${title || 'Conversation'}`);
+  lines.push('');
+  lines.push(`Archived: ${formatDateTime(now)}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  for (const msg of messages) {
+    const sender = msg.role === 'user' ? 'User' : 'Assistant';
+    const content = msg.content.length > 4000
+      ? `${msg.content.slice(0, 4000)}...`
+      : msg.content;
+    lines.push(`**${sender}**: ${content}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+export function sanitizeFilename(summary: string): string {
+  return summary
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50);
+}
+
+export function archiveConversation(messages: Message[], summary: string | null, groupDir: string): string | null {
+  if (messages.length === 0) return null;
+  const conversationsDir = path.join(groupDir, 'conversations');
+  fs.mkdirSync(conversationsDir, { recursive: true });
+
+  const date = new Date().toISOString().split('T')[0];
+  let name = summary ? sanitizeFilename(summary) : '';
+  if (!name) {
+    const time = new Date();
+    name = `conversation-${time.getHours().toString().padStart(2, '0')}${time.getMinutes().toString().padStart(2, '0')}`;
+  }
+  const filename = `${date}-${name}.md`;
+  const filePath = path.join(conversationsDir, filename);
+  fs.writeFileSync(filePath, formatTranscriptMarkdown(messages, summary));
+  return filePath;
+}
+
+export function buildSummaryPrompt(existingSummary: string, existingFacts: string[], newMessages: Message[]) {
+  const summaryText = existingSummary ? existingSummary : 'None.';
+  const factsText = existingFacts.length > 0 ? existingFacts.map(f => `- ${f}`).join('\n') : 'None.';
+  const messagesText = newMessages.map(m => `${m.role.toUpperCase()}: ${m.content}`).join('\n\n');
+
+  const instructions = [
+    'You maintain long-term memory for a personal assistant.',
+    'Update the summary and facts using the NEW messages.',
+    'Keep the summary concise, chronological, and focused on durable information.',
+    'Facts should be short, specific, and stable. Avoid transient or speculative details.',
+    'Return JSON only with keys: summary (string), facts (array of strings).'
+  ].join('\n');
+
+  const input = [
+    `Existing summary:\n${summaryText}`,
+    `Existing facts:\n${factsText}`,
+    `New messages:\n${messagesText}`
+  ].join('\n\n');
+
+  return { instructions, input };
+}
+
+export function parseSummaryResponse(text: string): { summary: string; facts: string[] } | null {
+  const trimmed = text.trim();
+  let jsonText = trimmed;
+  const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenceMatch) {
+    jsonText = fenceMatch[1].trim();
+  }
+  try {
+    const parsed = JSON.parse(jsonText);
+    if (typeof parsed.summary !== 'string' || !Array.isArray(parsed.facts)) {
+      return null;
+    }
+    const facts = parsed.facts.filter((f: unknown) => typeof f === 'string');
+    return { summary: parsed.summary, facts };
+  } catch {
+    return null;
+  }
+}
+
+function tokenize(text: string): string[] {
+  return (text.toLowerCase().match(/[a-z0-9]+/g) || []).filter(token => token.length > 1);
+}
+
+function scoreCandidate(candidate: string, queryTokens: string[], weight: number): number {
+  const candidateTokens = tokenize(candidate);
+  if (candidateTokens.length === 0 || queryTokens.length === 0) return 0;
+  const tokenSet = new Set(candidateTokens);
+  let overlap = 0;
+  for (const token of queryTokens) {
+    if (tokenSet.has(token)) overlap += 1;
+  }
+  if (overlap === 0) return 0;
+  return (overlap / Math.sqrt(candidateTokens.length)) * weight;
+}
+
+export function retrieveRelevantMemories(params: {
+  query: string;
+  summary: string;
+  facts: string[];
+  olderMessages: Message[];
+  config: MemoryConfig;
+}): string[] {
+  const queryTokens = tokenize(params.query);
+  if (queryTokens.length === 0) return [];
+
+  const candidates: Array<{ text: string; score: number }> = [];
+
+  if (params.summary) {
+    const summaryLines = params.summary.split('\n').map(line => line.trim()).filter(Boolean);
+    for (const line of summaryLines) {
+      const score = scoreCandidate(line, queryTokens, 1.4);
+      if (score > 0) candidates.push({ text: line, score });
+    }
+  }
+
+  for (const fact of params.facts) {
+    const score = scoreCandidate(fact, queryTokens, 2.0);
+    if (score > 0) candidates.push({ text: fact, score });
+  }
+
+  for (const msg of params.olderMessages.slice(-200)) {
+    const snippet = msg.content.length > 300 ? `${msg.content.slice(0, 300)}...` : msg.content;
+    const score = scoreCandidate(snippet, queryTokens, 1.0);
+    if (score > 0) candidates.push({ text: snippet, score });
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+
+  const results: string[] = [];
+  let tokens = 0;
+  for (const candidate of candidates) {
+    if (results.length >= params.config.memoryMaxResults) break;
+    const nextTokens = estimateTokens(candidate.text);
+    if (tokens + nextTokens > params.config.memoryMaxTokens) break;
+    results.push(candidate.text);
+    tokens += nextTokens;
+  }
+  return results;
+}