@lumenflow/cli 3.6.6 → 3.6.7

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

@@ -0,0 +1,278 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { getStoragePort, type TaskPriority, type TaskRecord } from './storage.js';
+import {
+  asInteger,
+  asNonEmptyString,
+  asStringArray,
+  buildAuditEvent,
+  createId,
+  failure,
+  isDryRun,
+  matchesTags,
+  nowIso,
+  success,
+  toRecord,
+  type ToolContextLike,
+  type ToolOutput,
+} from './shared.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TOOL_NAMES = {
+  CREATE: 'task:create',
+  LIST: 'task:list',
+  COMPLETE: 'task:complete',
+  SCHEDULE: 'task:schedule',
+} as const;
+
+const VALID_PRIORITIES: TaskPriority[] = ['P0', 'P1', 'P2', 'P3'];
+const DEFAULT_PRIORITY: TaskPriority = 'P2';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function asPriority(value: unknown): TaskPriority {
+  return VALID_PRIORITIES.includes(value as TaskPriority)
+    ? (value as TaskPriority)
+    : DEFAULT_PRIORITY;
+}
+
+// ---------------------------------------------------------------------------
+// task:create
+// ---------------------------------------------------------------------------
+
+async function taskCreateTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const title = asNonEmptyString(parsed.title);
+
+  if (!title) {
+    return failure('INVALID_INPUT', 'title is required.');
+  }
+
+  const task: TaskRecord = {
+    id: createId('task'),
+    title,
+    description: asNonEmptyString(parsed.description) ?? undefined,
+    priority: asPriority(parsed.priority),
+    status: 'pending',
+    tags: asStringArray(parsed.tags),
+    due_at: asNonEmptyString(parsed.due_at) ?? undefined,
+    created_at: nowIso(),
+    updated_at: nowIso(),
+  };
+
+  if (isDryRun(parsed)) {
+    return success({ dry_run: true, task: task as unknown as Record<string, unknown> });
+  }
+
+  const storage = getStoragePort();
+  await storage.withLock(async () => {
+    const tasks = await storage.readStore('tasks');
+    tasks.push(task);
+    await storage.writeStore('tasks', tasks);
+    await storage.appendAudit(
+      buildAuditEvent({
+        tool: TOOL_NAMES.CREATE,
+        op: 'create',
+        context,
+        ids: [task.id],
+      }),
+    );
+  });
+
+  return success({ task: task as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// task:list
+// ---------------------------------------------------------------------------
+
+async function taskListTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+  const statusFilter = asNonEmptyString(parsed.status);
+  const priorityFilter = asNonEmptyString(parsed.priority);
+  const tags = asStringArray(parsed.tags);
+  const dueBefore = asNonEmptyString(parsed.due_before);
+  const limit = asInteger(parsed.limit);
+
+  const storage = getStoragePort();
+  const tasks = await storage.readStore('tasks');
+
+  const filtered = tasks.filter((task) => {
+    if (statusFilter && task.status !== statusFilter) {
+      return false;
+    }
+    if (priorityFilter && task.priority !== priorityFilter) {
+      return false;
+    }
+    if (!matchesTags(tags, task.tags)) {
+      return false;
+    }
+    if (dueBefore && task.due_at) {
+      if (Date.parse(task.due_at) >= Date.parse(dueBefore)) {
+        return false;
+      }
+    }
+    if (dueBefore && !task.due_at) {
+      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,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// task:complete
+// ---------------------------------------------------------------------------
+
+async function taskCompleteTool(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 tasks = await storage.readStore('tasks');
+  const task = tasks.find((t) => t.id === id);
+
+  if (!task) {
+    return failure('NOT_FOUND', `task ${id} was not found.`);
+  }
+
+  if (isDryRun(parsed)) {
+    const preview = { ...task, status: 'done' as const, completed_at: nowIso() };
+    return success({
+      dry_run: true,
+      task: preview as unknown as Record<string, unknown>,
+    });
+  }
+
+  await storage.withLock(async () => {
+    const latest = await storage.readStore('tasks');
+    const target = latest.find((t) => t.id === id);
+    if (target) {
+      target.status = 'done';
+      target.completed_at = nowIso();
+      target.updated_at = nowIso();
+      if (parsed.note) {
+        target.note = asNonEmptyString(parsed.note) ?? undefined;
+      }
+      await storage.writeStore('tasks', latest);
+      await storage.appendAudit(
+        buildAuditEvent({
+          tool: TOOL_NAMES.COMPLETE,
+          op: 'update',
+          context,
+          ids: [id],
+        }),
+      );
+    }
+  });
+
+  const updated = await storage.readStore('tasks');
+  const completedTask = updated.find((t) => t.id === id);
+
+  return success({ task: completedTask as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// task:schedule
+// ---------------------------------------------------------------------------
+
+async function taskScheduleTool(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 tasks = await storage.readStore('tasks');
+  const task = tasks.find((t) => t.id === id);
+
+  if (!task) {
+    return failure('NOT_FOUND', `task ${id} was not found.`);
+  }
+
+  const dueAt = asNonEmptyString(parsed.due_at);
+  const cron = asNonEmptyString(parsed.cron);
+
+  if (isDryRun(parsed)) {
+    const preview = {
+      ...task,
+      ...(dueAt ? { due_at: dueAt } : {}),
+      ...(cron ? { cron } : {}),
+    };
+    return success({
+      dry_run: true,
+      task: preview as unknown as Record<string, unknown>,
+    });
+  }
+
+  await storage.withLock(async () => {
+    const latest = await storage.readStore('tasks');
+    const target = latest.find((t) => t.id === id);
+    if (target) {
+      if (dueAt) {
+        target.due_at = dueAt;
+      }
+      // cron is stored but TaskRecord doesn't have it yet -- extend inline
+      if (cron) {
+        (target as unknown as Record<string, unknown>).cron = cron;
+      }
+      target.updated_at = nowIso();
+      await storage.writeStore('tasks', latest);
+      await storage.appendAudit(
+        buildAuditEvent({
+          tool: TOOL_NAMES.SCHEDULE,
+          op: 'update',
+          context,
+          ids: [id],
+        }),
+      );
+    }
+  });
+
+  const updated = await storage.readStore('tasks');
+  const scheduledTask = updated.find((t) => t.id === id);
+
+  return success({ task: scheduledTask as unknown as Record<string, unknown> });
+}
+
+// ---------------------------------------------------------------------------
+// Router (default export)
+// ---------------------------------------------------------------------------
+
+export default async function taskTools(
+  input: unknown,
+  context?: ToolContextLike,
+): Promise<ToolOutput> {
+  switch (context?.tool_name) {
+    case TOOL_NAMES.CREATE:
+      return taskCreateTool(input, context);
+    case TOOL_NAMES.LIST:
+      return taskListTool(input, context);
+    case TOOL_NAMES.COMPLETE:
+      return taskCompleteTool(input, context);
+    case TOOL_NAMES.SCHEDULE:
+      return taskScheduleTool(input, context);
+    default:
+      return failure('UNKNOWN_TOOL', `Unknown task tool: ${context?.tool_name ?? 'unknown'}`);
+  }
+}

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

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  createToolDescriptor,
+} from './types.js';
+
+const CHANNEL_READ_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/channels/**',
+  access: TOOL_SCOPE_ACCESS.READ,
+} as const;
+
+const CHANNEL_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/channels/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const AUDIT_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/audit/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const CHANNEL_TOOLS_ENTRY = 'tool-impl/channel-tools.ts';
+
+export const channelConfigureDescriptor = createToolDescriptor({
+  name: 'channel:configure',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [CHANNEL_READ_SCOPE, CHANNEL_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: CHANNEL_TOOLS_ENTRY,
+  description: 'Configure a messaging channel (terminal-only in v0.1).',
+});
+
+export const channelSendDescriptor = createToolDescriptor({
+  name: 'channel:send',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [CHANNEL_READ_SCOPE, CHANNEL_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: CHANNEL_TOOLS_ENTRY,
+  description: 'Send a message to a channel. Supports dry_run.',
+});
+
+export const channelReceiveDescriptor = createToolDescriptor({
+  name: 'channel:receive',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [CHANNEL_READ_SCOPE],
+  entry: CHANNEL_TOOLS_ENTRY,
+  description: 'Receive messages from a channel with optional limit and since filter.',
+});

package/packs/sidekick/tools/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export * from './types.js';
+export * from './task-tools.js';
+export * from './memory-tools.js';
+export * from './channel-tools.js';
+export * from './routine-tools.js';
+export * from './system-tools.js';

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

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  createToolDescriptor,
+} from './types.js';
+
+const MEMORY_READ_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/memory/**',
+  access: TOOL_SCOPE_ACCESS.READ,
+} as const;
+
+const MEMORY_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/memory/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const AUDIT_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/audit/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const MEMORY_TOOLS_ENTRY = 'tool-impl/memory-tools.ts';
+
+export const memoryStoreDescriptor = createToolDescriptor({
+  name: 'memory:store',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: MEMORY_TOOLS_ENTRY,
+  description: 'Store a typed memory entry (fact, preference, note, snippet) with optional tags.',
+});
+
+export const memoryRecallDescriptor = createToolDescriptor({
+  name: 'memory:recall',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [MEMORY_READ_SCOPE],
+  entry: MEMORY_TOOLS_ENTRY,
+  description: 'Recall memory entries by substring search and/or tag filter.',
+});
+
+export const memoryForgetDescriptor = createToolDescriptor({
+  name: 'memory:forget',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [MEMORY_READ_SCOPE, MEMORY_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: MEMORY_TOOLS_ENTRY,
+  description: 'Remove a memory entry by ID. Supports dry_run.',
+});

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

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  createToolDescriptor,
+} from './types.js';
+
+const ROUTINE_READ_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/routines/**',
+  access: TOOL_SCOPE_ACCESS.READ,
+} as const;
+
+const ROUTINE_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/routines/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const AUDIT_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/audit/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const ROUTINE_TOOLS_ENTRY = 'tool-impl/routine-tools.ts';
+
+export const routineCreateDescriptor = createToolDescriptor({
+  name: 'routine:create',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [ROUTINE_READ_SCOPE, ROUTINE_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: ROUTINE_TOOLS_ENTRY,
+  description: 'Create a named routine with ordered tool+input steps and optional cron.',
+});
+
+export const routineListDescriptor = createToolDescriptor({
+  name: 'routine:list',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [ROUTINE_READ_SCOPE],
+  entry: ROUTINE_TOOLS_ENTRY,
+  description: 'List routines with optional enabled_only filter.',
+});
+
+export const routineRunDescriptor = createToolDescriptor({
+  name: 'routine:run',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [ROUTINE_READ_SCOPE],
+  entry: ROUTINE_TOOLS_ENTRY,
+  description: 'Generate an execution plan for a routine (plan-only, does not execute).',
+});

package/packs/sidekick/tools/system-tools.ts

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  createToolDescriptor,
+} from './types.js';
+
+const SIDEKICK_READ_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/**',
+  access: TOOL_SCOPE_ACCESS.READ,
+} as const;
+
+const SIDEKICK_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const SYSTEM_TOOLS_ENTRY = 'tool-impl/system-tools.ts';
+
+export const sidekickInitDescriptor = createToolDescriptor({
+  name: 'sidekick:init',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [SIDEKICK_READ_SCOPE, SIDEKICK_WRITE_SCOPE],
+  entry: SYSTEM_TOOLS_ENTRY,
+  description: 'Initialize .sidekick/ directory structure. Idempotent.',
+});
+
+export const sidekickStatusDescriptor = createToolDescriptor({
+  name: 'sidekick:status',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [SIDEKICK_READ_SCOPE],
+  entry: SYSTEM_TOOLS_ENTRY,
+  description: 'Show sidekick status: store counts, initialized state, version.',
+});
+
+export const sidekickExportDescriptor = createToolDescriptor({
+  name: 'sidekick:export',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [SIDEKICK_READ_SCOPE],
+  entry: SYSTEM_TOOLS_ENTRY,
+  description: 'Export all sidekick data as a JSON bundle (read-only, no file write).',
+});

package/packs/sidekick/tools/task-tools.ts

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  createToolDescriptor,
+} from './types.js';
+
+const SIDEKICK_READ_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/tasks/**',
+  access: TOOL_SCOPE_ACCESS.READ,
+} as const;
+
+const SIDEKICK_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/tasks/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const AUDIT_WRITE_SCOPE = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/audit/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+} as const;
+
+const TASK_TOOLS_ENTRY = 'tool-impl/task-tools.ts';
+
+export const taskCreateDescriptor = createToolDescriptor({
+  name: 'task:create',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [SIDEKICK_READ_SCOPE, SIDEKICK_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: TASK_TOOLS_ENTRY,
+  description: 'Create a new task with title, priority, due date, and tags.',
+});
+
+export const taskListDescriptor = createToolDescriptor({
+  name: 'task:list',
+  permission: TOOL_PERMISSIONS.READ,
+  required_scopes: [SIDEKICK_READ_SCOPE],
+  entry: TASK_TOOLS_ENTRY,
+  description: 'List tasks with optional filters: status, priority, tag, due_before.',
+});
+
+export const taskCompleteDescriptor = createToolDescriptor({
+  name: 'task:complete',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [SIDEKICK_READ_SCOPE, SIDEKICK_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: TASK_TOOLS_ENTRY,
+  description: 'Mark a task as complete. Supports dry_run.',
+});
+
+export const taskScheduleDescriptor = createToolDescriptor({
+  name: 'task:schedule',
+  permission: TOOL_PERMISSIONS.WRITE,
+  required_scopes: [SIDEKICK_READ_SCOPE, SIDEKICK_WRITE_SCOPE, AUDIT_WRITE_SCOPE],
+  entry: TASK_TOOLS_ENTRY,
+  description: 'Set or update a task due date or cron schedule.',
+});

package/packs/sidekick/tools/types.ts

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { SIDEKICK_DOMAIN, SIDEKICK_PACK_ID, SIDEKICK_PACK_VERSION } from '../constants.js';
+
+export const TOOL_SCOPE_TYPES = {
+  PATH: 'path',
+} as const;
+
+export const TOOL_SCOPE_ACCESS = {
+  READ: 'read',
+  WRITE: 'write',
+} as const;
+
+export const TOOL_PERMISSIONS = {
+  READ: 'read',
+  WRITE: 'write',
+  ADMIN: 'admin',
+} as const;
+
+export type ToolScopeType = (typeof TOOL_SCOPE_TYPES)[keyof typeof TOOL_SCOPE_TYPES];
+export type ToolScopeAccess = (typeof TOOL_SCOPE_ACCESS)[keyof typeof TOOL_SCOPE_ACCESS];
+export type ToolPermission = (typeof TOOL_PERMISSIONS)[keyof typeof TOOL_PERMISSIONS];
+
+export interface PathScope {
+  type: ToolScopeType;
+  pattern: string;
+  access: ToolScopeAccess;
+}
+
+export interface ToolDescriptor {
+  name: string;
+  domain: typeof SIDEKICK_DOMAIN;
+  version: typeof SIDEKICK_PACK_VERSION;
+  permission: ToolPermission;
+  required_scopes: PathScope[];
+  entry: string;
+  description: string;
+  pack: typeof SIDEKICK_PACK_ID;
+}
+
+export interface ToolDescriptorInput {
+  name: ToolDescriptor['name'];
+  permission: ToolDescriptor['permission'];
+  required_scopes: ToolDescriptor['required_scopes'];
+  entry: ToolDescriptor['entry'];
+  description: ToolDescriptor['description'];
+}
+
+export function createToolDescriptor(input: ToolDescriptorInput): ToolDescriptor {
+  return {
+    ...input,
+    domain: SIDEKICK_DOMAIN,
+    version: SIDEKICK_PACK_VERSION,
+    pack: SIDEKICK_PACK_ID,
+  };
+}

package/packs/sidekick/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "noEmit": false,
+    "declaration": true,
+    "strict": true,
+    "useUnknownInCatchVariables": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "allowJs": false,
+    "checkJs": false,
+    "noEmitOnError": true
+  },
+  "include": ["*.ts", "tools/**/*.ts", "tool-impl/**/*.ts"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}