@lumenflow/cli 3.6.6 → 3.6.7

package/packs/sidekick/tool-impl/channel-tools.ts

@@ -0,0 +1,226 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { getStoragePort, type ChannelMessageRecord, type ChannelRecord } from './storage.js';
+import {
+  asInteger,
+  asNonEmptyString,
+  buildAuditEvent,
+  createId,
+  failure,
+  isDryRun,
+  nowIso,
+  success,
+  toRecord,
+  type ToolContextLike,
+  type ToolOutput,
+} from './shared.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TOOL_NAMES = {
+  CONFIGURE: 'channel:configure',
+  SEND: 'channel:send',
+  RECEIVE: 'channel:receive',
+} as const;
+
+const OUTBOX_CAP = 100;
+const DEFAULT_CHANNEL_NAME = 'default';
+
+// ---------------------------------------------------------------------------
+// channel:configure
+// ---------------------------------------------------------------------------
+
+async function channelConfigureTool(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const name = asNonEmptyString(parsed.name);
+
+  if (!name) {
+    return failure('INVALID_INPUT', 'name is required.');
+  }
+
+  const now = nowIso();
+  const channel: ChannelRecord = {
+    id: createId('chan'),
+    name,
+    created_at: now,
+    updated_at: now,
+  };
+
+  if (isDryRun(parsed)) {
+    return success({
+      dry_run: true,
+      channel: channel as unknown as Record<string, unknown>,
+    });
+  }
+
+  const storage = getStoragePort();
+  let resolvedChannel = channel;
+
+  await storage.withLock(async () => {
+    const channels = await storage.readStore('channels');
+    const existing = channels.find((c) => c.name === name);
+
+    if (existing) {
+      resolvedChannel = { ...existing, updated_at: now };
+      const updated = channels.map((c) => (c.id === existing.id ? resolvedChannel : c));
+      await storage.writeStore('channels', updated);
+      await storage.appendAudit(
+        buildAuditEvent({
+          tool: TOOL_NAMES.CONFIGURE,
+          op: 'update',
+          context,
+          ids: [existing.id],
+        }),
+      );
+    } else {
+      channels.push(channel);
+      await storage.writeStore('channels', channels);
+      await storage.appendAudit(
+        buildAuditEvent({
+          tool: TOOL_NAMES.CONFIGURE,
+          op: 'create',
+          context,
+          ids: [channel.id],
+        }),
+      );
+    }
+  });
+
+  return success({ channel: resolvedChannel as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// channel:send
+// ---------------------------------------------------------------------------
+
+async function channelSendTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const content = asNonEmptyString(parsed.content);
+
+  if (!content) {
+    return failure('INVALID_INPUT', 'content is required.');
+  }
+
+  const channelName = asNonEmptyString(parsed.channel) ?? DEFAULT_CHANNEL_NAME;
+  const sender = asNonEmptyString(parsed.sender) ?? 'assistant';
+  const now = nowIso();
+
+  const message: ChannelMessageRecord = {
+    id: createId('msg'),
+    channel_id: '', // resolved below
+    sender,
+    content,
+    created_at: now,
+  };
+
+  if (isDryRun(parsed)) {
+    return success({
+      dry_run: true,
+      message: { ...message, channel_id: 'dry-run' } as unknown as Record<string, unknown>,
+    });
+  }
+
+  const storage = getStoragePort();
+  let resolvedMessage = message;
+
+  await storage.withLock(async () => {
+    const channels = await storage.readStore('channels');
+    const found = channels.find((c) => c.name === channelName);
+    let channelId: string;
+
+    if (!found) {
+      channelId = createId('chan');
+      channels.push({
+        id: channelId,
+        name: channelName,
+        created_at: now,
+        updated_at: now,
+      });
+      await storage.writeStore('channels', channels);
+    } else {
+      channelId = found.id;
+      const updated = channels.map((c) => (c.id === channelId ? { ...c, updated_at: now } : c));
+      await storage.writeStore('channels', updated);
+    }
+
+    resolvedMessage = { ...message, channel_id: channelId };
+
+    const messages = await storage.readStore('messages');
+    messages.push(resolvedMessage);
+
+    // Cap outbox at OUTBOX_CAP
+    const capped = messages.length > OUTBOX_CAP ? messages.slice(-OUTBOX_CAP) : messages;
+    await storage.writeStore('messages', capped);
+
+    await storage.appendAudit(
+      buildAuditEvent({
+        tool: TOOL_NAMES.SEND,
+        op: 'create',
+        context,
+        ids: [channelId, resolvedMessage.id],
+      }),
+    );
+  });
+
+  return success({ message: resolvedMessage as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// channel:receive
+// ---------------------------------------------------------------------------
+
+async function channelReceiveTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const channelName = asNonEmptyString(parsed.channel);
+  const limit = asInteger(parsed.limit);
+
+  const storage = getStoragePort();
+  const messages = await storage.readStore('messages');
+  const channels = await storage.readStore('channels');
+
+  let filtered = messages;
+
+  if (channelName) {
+    const channel = channels.find((c) => c.name === channelName);
+    if (channel) {
+      filtered = messages.filter((m) => m.channel_id === channel.id);
+    } else {
+      filtered = [];
+    }
+  }
+
+  const sorted = filtered.toSorted((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+
+  const items = limit && limit > 0 ? sorted.slice(-limit) : sorted;
+
+  return success({
+    items: items as unknown as Record<string, unknown>,
+    count: items.length,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Router (default export)
+// ---------------------------------------------------------------------------
+
+export default async function channelTools(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  switch (context?.tool_name) {
+    case TOOL_NAMES.CONFIGURE:
+      return channelConfigureTool(input, context);
+    case TOOL_NAMES.SEND:
+      return channelSendTool(input, context);
+    case TOOL_NAMES.RECEIVE:
+      return channelReceiveTool(input, context);
+    default:
+      return failure('UNKNOWN_TOOL', `Unknown channel tool: ${context?.tool_name ?? 'unknown'}`);
+  }
+}

package/packs/sidekick/tool-impl/index.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export {
+  type AuditEvent,
+  type ChannelMessageRecord,
+  type ChannelRecord,
+  type MemoryRecord,
+  type MemoryType,
+  type RoutineRecord,
+  type RoutineStepRecord,
+  type SidekickStores,
+  type StoragePort,
+  type StoreName,
+  type TaskPriority,
+  type TaskRecord,
+  type TaskStatus,
+  FsStoragePort,
+  getStoragePort,
+  runWithStoragePort,
+  setDefaultStoragePort,
+} from './storage.js';

package/packs/sidekick/tool-impl/memory-tools.ts

@@ -0,0 +1,188 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { getStoragePort, type MemoryRecord, type MemoryType } from './storage.js';
+import {
+  asInteger,
+  asNonEmptyString,
+  asStringArray,
+  buildAuditEvent,
+  createId,
+  failure,
+  includesText,
+  isDryRun,
+  matchesTags,
+  nowIso,
+  success,
+  toRecord,
+  type ToolContextLike,
+  type ToolOutput,
+} from './shared.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TOOL_NAMES = {
+  STORE: 'memory:store',
+  RECALL: 'memory:recall',
+  FORGET: 'memory:forget',
+} as const;
+
+const VALID_MEMORY_TYPES: MemoryType[] = ['fact', 'preference', 'note'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function asMemoryType(value: unknown): MemoryType | null {
+  return VALID_MEMORY_TYPES.includes(value as MemoryType) ? (value as MemoryType) : null;
+}
+
+// ---------------------------------------------------------------------------
+// memory:store
+// ---------------------------------------------------------------------------
+
+async function memoryStoreTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const type = asMemoryType(parsed.type);
+  const content = asNonEmptyString(parsed.content);
+
+  if (!type) {
+    return failure('INVALID_INPUT', 'type must be one of fact, preference, note.');
+  }
+  if (!content) {
+    return failure('INVALID_INPUT', 'content is required.');
+  }
+
+  const memory: MemoryRecord = {
+    id: createId('mem'),
+    type,
+    content,
+    tags: asStringArray(parsed.tags),
+    created_at: nowIso(),
+    updated_at: nowIso(),
+  };
+
+  if (isDryRun(parsed)) {
+    return success({
+      dry_run: true,
+      memory: memory as unknown as Record<string, unknown>,
+    });
+  }
+
+  const storage = getStoragePort();
+  await storage.withLock(async () => {
+    const memories = await storage.readStore('memories');
+    memories.push(memory);
+    await storage.writeStore('memories', memories);
+    await storage.appendAudit(
+      buildAuditEvent({
+        tool: TOOL_NAMES.STORE,
+        op: 'create',
+        context,
+        ids: [memory.id],
+      }),
+    );
+  });
+
+  return success({ memory: memory as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// memory:recall
+// ---------------------------------------------------------------------------
+
+async function memoryRecallTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const query = asNonEmptyString(parsed.query);
+  const type = asMemoryType(parsed.type);
+  const tags = asStringArray(parsed.tags);
+  const limit = asInteger(parsed.limit);
+
+  const storage = getStoragePort();
+  const memories = await storage.readStore('memories');
+
+  const filtered = memories.filter((memory) => {
+    if (type && memory.type !== type) {
+      return false;
+    }
+    if (!matchesTags(tags, memory.tags)) {
+      return false;
+    }
+    if (!includesText(memory.content, query)) {
+      return false;
+    }
+    return true;
+  });
+
+  const sorted = filtered.toSorted((a, b) => Date.parse(b.updated_at) - Date.parse(a.updated_at));
+
+  const items = limit && limit > 0 ? sorted.slice(0, limit) : sorted;
+
+  return success({
+    items: items as unknown as Record<string, unknown>,
+    count: items.length,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// memory:forget
+// ---------------------------------------------------------------------------
+
+async function memoryForgetTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const id = asNonEmptyString(parsed.id);
+
+  if (!id) {
+    return failure('INVALID_INPUT', 'id is required.');
+  }
+
+  const storage = getStoragePort();
+  const memories = await storage.readStore('memories');
+  const exists = memories.some((memory) => memory.id === id);
+
+  if (!exists) {
+    return failure('NOT_FOUND', `memory ${id} was not found.`);
+  }
+
+  if (isDryRun(parsed)) {
+    return success({ dry_run: true, deleted_id: id });
+  }
+
+  await storage.withLock(async () => {
+    const latest = await storage.readStore('memories');
+    const remaining = latest.filter((memory) => memory.id !== id);
+    await storage.writeStore('memories', remaining);
+    await storage.appendAudit(
+      buildAuditEvent({
+        tool: TOOL_NAMES.FORGET,
+        op: 'delete',
+        context,
+        ids: [id],
+      }),
+    );
+  });
+
+  return success({ deleted_id: id });
+}
+
+// ---------------------------------------------------------------------------
+// Router (default export)
+// ---------------------------------------------------------------------------
+
+export default async function memoryTools(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  switch (context?.tool_name) {
+    case TOOL_NAMES.STORE:
+      return memoryStoreTool(input, context);
+    case TOOL_NAMES.RECALL:
+      return memoryRecallTool(input, context);
+    case TOOL_NAMES.FORGET:
+      return memoryForgetTool(input, context);
+    default:
+      return failure('UNKNOWN_TOOL', `Unknown memory tool: ${context?.tool_name ?? 'unknown'}`);
+  }
+}

package/packs/sidekick/tool-impl/routine-tools.ts

@@ -0,0 +1,194 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { getStoragePort, type RoutineRecord, type RoutineStepRecord } from './storage.js';
+import {
+  asInteger,
+  asNonEmptyString,
+  buildAuditEvent,
+  createId,
+  failure,
+  isDryRun,
+  nowIso,
+  success,
+  toRecord,
+  type ToolContextLike,
+  type ToolOutput,
+} from './shared.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TOOL_NAMES = {
+  CREATE: 'routine:create',
+  LIST: 'routine:list',
+  RUN: 'routine:run',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function normalizeSteps(value: unknown): RoutineStepRecord[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const steps: RoutineStepRecord[] = [];
+  for (const candidate of value) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+      continue;
+    }
+    const record = candidate as Record<string, unknown>;
+    const tool = asNonEmptyString(record.tool);
+    if (!tool) {
+      continue;
+    }
+    const input =
+      record.input && typeof record.input === 'object' && !Array.isArray(record.input)
+        ? (record.input as Record<string, unknown>)
+        : {};
+
+    steps.push({ tool, input });
+  }
+
+  return steps;
+}
+
+// ---------------------------------------------------------------------------
+// routine:create
+// ---------------------------------------------------------------------------
+
+async function routineCreateTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const name = asNonEmptyString(parsed.name);
+  const steps = normalizeSteps(parsed.steps);
+
+  if (!name) {
+    return failure('INVALID_INPUT', 'name is required.');
+  }
+  if (steps.length === 0) {
+    return failure('INVALID_INPUT', 'steps must include at least one tool step.');
+  }
+
+  const now = nowIso();
+  const routine: RoutineRecord = {
+    id: createId('routine'),
+    name,
+    steps,
+    created_at: now,
+    updated_at: now,
+  };
+
+  if (isDryRun(parsed)) {
+    return success({
+      dry_run: true,
+      routine: routine as unknown as Record<string, unknown>,
+    });
+  }
+
+  const storage = getStoragePort();
+  await storage.withLock(async () => {
+    const routines = await storage.readStore('routines');
+    routines.push(routine);
+    await storage.writeStore('routines', routines);
+    await storage.appendAudit(
+      buildAuditEvent({
+        tool: TOOL_NAMES.CREATE,
+        op: 'create',
+        context,
+        ids: [routine.id],
+      }),
+    );
+  });
+
+  return success({ routine: routine as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// routine:list
+// ---------------------------------------------------------------------------
+
+async function routineListTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const limit = asInteger(parsed.limit);
+
+  const storage = getStoragePort();
+  const routines = await storage.readStore('routines');
+
+  const sorted = routines.toSorted((a, b) => Date.parse(b.updated_at) - Date.parse(a.updated_at));
+
+  const items = limit && limit > 0 ? sorted.slice(0, limit) : sorted;
+
+  return success({
+    items: items as unknown as Record<string, unknown>,
+    count: items.length,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// routine:run (PLAN-ONLY -- does NOT execute tool steps)
+// ---------------------------------------------------------------------------
+
+async function routineRunTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const id = asNonEmptyString(parsed.id);
+
+  if (!id) {
+    return failure('INVALID_INPUT', 'id is required.');
+  }
+
+  const storage = getStoragePort();
+  const routines = await storage.readStore('routines');
+  const routine = routines.find((r) => r.id === id);
+
+  if (!routine) {
+    return failure('NOT_FOUND', `routine ${id} was not found.`);
+  }
+
+  await storage.appendAudit(
+    buildAuditEvent({
+      tool: TOOL_NAMES.RUN,
+      op: 'execute',
+      context,
+      ids: [id],
+      details: { plan_only: true },
+    }),
+  );
+
+  return success({
+    routine_id: routine.id,
+    name: routine.name,
+    plan_only: true,
+    plan: routine.steps.map((step, index) => ({
+      index,
+      tool: step.tool,
+      input: step.input,
+    })),
+    governance: {
+      dispatch_required: true,
+      execution: 'No tool steps were executed by routine:run. This endpoint only returns a plan.',
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Router (default export)
+// ---------------------------------------------------------------------------
+
+export default async function routineTools(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  switch (context?.tool_name) {
+    case TOOL_NAMES.CREATE:
+      return routineCreateTool(input, context);
+    case TOOL_NAMES.LIST:
+      return routineListTool(input, context);
+    case TOOL_NAMES.RUN:
+      return routineRunTool(input, context);
+    default:
+      return failure('UNKNOWN_TOOL', `Unknown routine tool: ${context?.tool_name ?? 'unknown'}`);
+  }
+}