@lumenflow/cli 3.6.6 → 3.6.8

package/packs/sidekick/manifest-schema.ts

@@ -0,0 +1,262 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  type PathScope,
+  type ToolPermission,
+} from './tools/types.js';
+
+interface Parser<T> {
+  parse(input: unknown): T;
+}
+
+export const MANIFEST_POLICY_TRIGGERS = {
+  ON_TOOL_REQUEST: 'on_tool_request',
+  ON_CLAIM: 'on_claim',
+  ON_COMPLETION: 'on_completion',
+  ON_EVIDENCE_ADDED: 'on_evidence_added',
+} as const;
+
+export type ManifestPolicyTrigger =
+  (typeof MANIFEST_POLICY_TRIGGERS)[keyof typeof MANIFEST_POLICY_TRIGGERS];
+
+export const MANIFEST_POLICY_DECISIONS = {
+  ALLOW: 'allow',
+  DENY: 'deny',
+} as const;
+
+export type ManifestPolicyDecision =
+  (typeof MANIFEST_POLICY_DECISIONS)[keyof typeof MANIFEST_POLICY_DECISIONS];
+
+export interface SidekickManifestTool {
+  name: string;
+  entry: string;
+  permission: ToolPermission;
+  required_scopes: PathScope[];
+  input_schema?: Record<string, unknown>;
+  output_schema?: Record<string, unknown>;
+  internal_only?: boolean;
+}
+
+export interface SidekickManifestPolicy {
+  id: string;
+  trigger: ManifestPolicyTrigger;
+  decision: ManifestPolicyDecision;
+  reason?: string;
+}
+
+export interface SidekickPackManifest {
+  id: string;
+  version: string;
+  config_key?: string;
+  config_schema?: string;
+  task_types: string[];
+  tools: SidekickManifestTool[];
+  policies: SidekickManifestPolicy[];
+  evidence_types: string[];
+  state_aliases: Record<string, string>;
+  lane_templates: Array<{ id: string }>;
+}
+
+function asRecord(input: unknown, label: string): Record<string, unknown> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error(`${label} must be an object.`);
+  }
+  return input as Record<string, unknown>;
+}
+
+function parseNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function parseStringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array.`);
+  }
+  return value.map((entry, index) => parseNonEmptyString(entry, `${label}[${index}]`));
+}
+
+function parseJsonSchemaObject(value: unknown, label: string): Record<string, unknown> {
+  return asRecord(value, label);
+}
+
+function isSemver(value: string): boolean {
+  let core = value;
+  const prereleaseIndex = core.indexOf('-');
+  if (prereleaseIndex >= 0) {
+    core = core.slice(0, prereleaseIndex);
+  }
+  const metadataIndex = core.indexOf('+');
+  if (metadataIndex >= 0) {
+    core = core.slice(0, metadataIndex);
+  }
+
+  const parts = core.split('.');
+  if (parts.length !== 3) {
+    return false;
+  }
+
+  return parts.every(
+    (part) => part.length > 0 && [...part].every((char) => char >= '0' && char <= '9'),
+  );
+}
+
+const ALLOWED_POLICY_TRIGGERS = new Set<string>(Object.values(MANIFEST_POLICY_TRIGGERS));
+const ALLOWED_POLICY_DECISIONS = new Set<string>(Object.values(MANIFEST_POLICY_DECISIONS));
+const ALLOWED_TOOL_PERMISSIONS = new Set<string>(Object.values(TOOL_PERMISSIONS));
+
+function parsePathScope(input: unknown, label: string): PathScope {
+  const scope = asRecord(input, label);
+  const type = parseNonEmptyString(scope.type, `${label}.type`);
+  const pattern = parseNonEmptyString(scope.pattern, `${label}.pattern`);
+  const access = parseNonEmptyString(scope.access, `${label}.access`);
+
+  if (type !== TOOL_SCOPE_TYPES.PATH) {
+    throw new Error(`${label}.type must be "${TOOL_SCOPE_TYPES.PATH}".`);
+  }
+  if (access !== TOOL_SCOPE_ACCESS.READ && access !== TOOL_SCOPE_ACCESS.WRITE) {
+    throw new Error(
+      `${label}.access must be "${TOOL_SCOPE_ACCESS.READ}" or "${TOOL_SCOPE_ACCESS.WRITE}".`,
+    );
+  }
+
+  return {
+    type: TOOL_SCOPE_TYPES.PATH,
+    pattern,
+    access,
+  };
+}
+
+function parseRequiredScopes(value: unknown, label: string): PathScope[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${label} must be a non-empty array.`);
+  }
+  return value.map((entry, index) => parsePathScope(entry, `${label}[${index}]`));
+}
+
+function parsePolicy(input: unknown, index: number): SidekickManifestPolicy {
+  const policy = asRecord(input, `policies[${index}]`);
+  const trigger = parseNonEmptyString(policy.trigger, `policies[${index}].trigger`);
+  const decision = parseNonEmptyString(policy.decision, `policies[${index}].decision`);
+
+  if (!ALLOWED_POLICY_TRIGGERS.has(trigger)) {
+    throw new Error(`policies[${index}].trigger is invalid.`);
+  }
+  if (!ALLOWED_POLICY_DECISIONS.has(decision)) {
+    throw new Error(`policies[${index}].decision is invalid.`);
+  }
+
+  return {
+    id: parseNonEmptyString(policy.id, `policies[${index}].id`),
+    trigger: trigger as ManifestPolicyTrigger,
+    decision: decision as ManifestPolicyDecision,
+    reason:
+      policy.reason === undefined
+        ? undefined
+        : parseNonEmptyString(policy.reason, `policies[${index}].reason`),
+  };
+}
+
+function parseTool(input: unknown, index: number): SidekickManifestTool {
+  const tool = asRecord(input, `tools[${index}]`);
+  const permission =
+    tool.permission === undefined
+      ? TOOL_PERMISSIONS.READ
+      : parseNonEmptyString(tool.permission, `tools[${index}].permission`);
+
+  if (!ALLOWED_TOOL_PERMISSIONS.has(permission)) {
+    throw new Error(`tools[${index}].permission is invalid.`);
+  }
+
+  return {
+    name: parseNonEmptyString(tool.name, `tools[${index}].name`),
+    entry: parseNonEmptyString(tool.entry, `tools[${index}].entry`),
+    permission: permission as ToolPermission,
+    required_scopes: parseRequiredScopes(tool.required_scopes, `tools[${index}].required_scopes`),
+    input_schema:
+      tool.input_schema === undefined
+        ? undefined
+        : parseJsonSchemaObject(tool.input_schema, `tools[${index}].input_schema`),
+    output_schema:
+      tool.output_schema === undefined
+        ? undefined
+        : parseJsonSchemaObject(tool.output_schema, `tools[${index}].output_schema`),
+    internal_only:
+      tool.internal_only === undefined
+        ? undefined
+        : (() => {
+            if (typeof tool.internal_only !== 'boolean') {
+              throw new Error(`tools[${index}].internal_only must be boolean.`);
+            }
+            return tool.internal_only;
+          })(),
+  };
+}
+
+function parseStateAliases(input: unknown): Record<string, string> {
+  const aliases = asRecord(input ?? {}, 'state_aliases');
+  const parsed: Record<string, string> = {};
+  for (const [key, value] of Object.entries(aliases)) {
+    parsed[parseNonEmptyString(key, 'state_aliases key')] = parseNonEmptyString(
+      value,
+      `state_aliases.${key}`,
+    );
+  }
+  return parsed;
+}
+
+export const SidekickManifestSchema: Parser<SidekickPackManifest> = {
+  parse(input: unknown): SidekickPackManifest {
+    const manifest = asRecord(input, 'manifest');
+    const version = parseNonEmptyString(manifest.version, 'version');
+    if (!isSemver(version)) {
+      throw new Error('version must be semver.');
+    }
+
+    const taskTypes = parseStringArray(manifest.task_types, 'task_types');
+    if (taskTypes.length === 0) {
+      throw new Error('task_types must include at least one item.');
+    }
+
+    const toolsValue = manifest.tools ?? [];
+    if (!Array.isArray(toolsValue)) {
+      throw new Error('tools must be an array.');
+    }
+    const policiesValue = manifest.policies ?? [];
+    if (!Array.isArray(policiesValue)) {
+      throw new Error('policies must be an array.');
+    }
+    const laneTemplatesValue = manifest.lane_templates ?? [];
+    if (!Array.isArray(laneTemplatesValue)) {
+      throw new Error('lane_templates must be an array.');
+    }
+
+    return {
+      id: parseNonEmptyString(manifest.id, 'id'),
+      version,
+      config_key:
+        manifest.config_key === undefined
+          ? undefined
+          : parseNonEmptyString(manifest.config_key, 'config_key'),
+      config_schema:
+        manifest.config_schema === undefined
+          ? undefined
+          : parseNonEmptyString(manifest.config_schema, 'config_schema'),
+      task_types: taskTypes,
+      tools: toolsValue.map((tool, index) => parseTool(tool, index)),
+      policies: policiesValue.map((policy, index) => parsePolicy(policy, index)),
+      evidence_types: parseStringArray(manifest.evidence_types ?? [], 'evidence_types'),
+      state_aliases: parseStateAliases(manifest.state_aliases),
+      lane_templates: laneTemplatesValue.map((laneTemplate, index) => {
+        const entry = asRecord(laneTemplate, `lane_templates[${index}]`);
+        return { id: parseNonEmptyString(entry.id, `lane_templates[${index}].id`) };
+      }),
+    };
+  },
+};

package/packs/sidekick/manifest.ts

@@ -0,0 +1,333 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { SIDEKICK_PACK_ID, SIDEKICK_PACK_VERSION, SIDEKICK_POLICY_ID_PREFIX } from './constants.js';
+import {
+  MANIFEST_POLICY_DECISIONS,
+  MANIFEST_POLICY_TRIGGERS,
+  SidekickManifestSchema,
+  type SidekickManifestTool,
+  type SidekickPackManifest,
+} from './manifest-schema.js';
+import {
+  TOOL_PERMISSIONS,
+  TOOL_SCOPE_ACCESS,
+  TOOL_SCOPE_TYPES,
+  type PathScope,
+  type ToolPermission,
+} from './tools/types.js';
+
+// ---------------------------------------------------------------------------
+// Scope constants
+// ---------------------------------------------------------------------------
+
+const SIDEKICK_SCOPE_READ: PathScope = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/**',
+  access: TOOL_SCOPE_ACCESS.READ,
+};
+
+const SIDEKICK_SCOPE_WRITE: PathScope = {
+  type: TOOL_SCOPE_TYPES.PATH,
+  pattern: '.sidekick/**',
+  access: TOOL_SCOPE_ACCESS.WRITE,
+};
+
+// ---------------------------------------------------------------------------
+// 16-tool contract (per strategy: 5 groups)
+// ---------------------------------------------------------------------------
+
+const TOOL_PERMISSIONS_MAP = {
+  // Task tools (4)
+  'task:create': TOOL_PERMISSIONS.WRITE,
+  'task:list': TOOL_PERMISSIONS.READ,
+  'task:complete': TOOL_PERMISSIONS.WRITE,
+  'task:schedule': TOOL_PERMISSIONS.WRITE,
+  // Memory tools (3)
+  'memory:store': TOOL_PERMISSIONS.WRITE,
+  'memory:recall': TOOL_PERMISSIONS.READ,
+  'memory:forget': TOOL_PERMISSIONS.WRITE,
+  // Channel tools (3)
+  'channel:configure': TOOL_PERMISSIONS.WRITE,
+  'channel:send': TOOL_PERMISSIONS.WRITE,
+  'channel:receive': TOOL_PERMISSIONS.READ,
+  // Routine tools (3)
+  'routine:create': TOOL_PERMISSIONS.WRITE,
+  'routine:list': TOOL_PERMISSIONS.READ,
+  'routine:run': TOOL_PERMISSIONS.READ, // plan-only, no execution
+  // System tools (3)
+  'sidekick:init': TOOL_PERMISSIONS.WRITE,
+  'sidekick:status': TOOL_PERMISSIONS.READ,
+  'sidekick:export': TOOL_PERMISSIONS.READ, // returns data, no file write
+} as const satisfies Record<string, ToolPermission>;
+
+type SidekickToolName = keyof typeof TOOL_PERMISSIONS_MAP;
+
+const TASK_TOOLS_ENTRY = 'tool-impl/task-tools.ts';
+const MEMORY_TOOLS_ENTRY = 'tool-impl/memory-tools.ts';
+const CHANNEL_TOOLS_ENTRY = 'tool-impl/channel-tools.ts';
+const ROUTINE_TOOLS_ENTRY = 'tool-impl/routine-tools.ts';
+const SYSTEM_TOOLS_ENTRY = 'tool-impl/system-tools.ts';
+
+const TOOL_ENTRIES: Record<SidekickToolName, string> = {
+  'task:create': TASK_TOOLS_ENTRY,
+  'task:list': TASK_TOOLS_ENTRY,
+  'task:complete': TASK_TOOLS_ENTRY,
+  'task:schedule': TASK_TOOLS_ENTRY,
+  'memory:store': MEMORY_TOOLS_ENTRY,
+  'memory:recall': MEMORY_TOOLS_ENTRY,
+  'memory:forget': MEMORY_TOOLS_ENTRY,
+  'channel:configure': CHANNEL_TOOLS_ENTRY,
+  'channel:send': CHANNEL_TOOLS_ENTRY,
+  'channel:receive': CHANNEL_TOOLS_ENTRY,
+  'routine:create': ROUTINE_TOOLS_ENTRY,
+  'routine:list': ROUTINE_TOOLS_ENTRY,
+  'routine:run': ROUTINE_TOOLS_ENTRY,
+  'sidekick:init': SYSTEM_TOOLS_ENTRY,
+  'sidekick:status': SYSTEM_TOOLS_ENTRY,
+  'sidekick:export': SYSTEM_TOOLS_ENTRY,
+};
+
+// ---------------------------------------------------------------------------
+// Input schemas (JSON Schema objects)
+// ---------------------------------------------------------------------------
+
+const TOOL_INPUT_SCHEMAS: Record<SidekickToolName, Record<string, unknown>> = {
+  'task:create': {
+    type: 'object',
+    properties: {
+      title: { type: 'string', minLength: 1 },
+      description: { type: 'string' },
+      priority: { type: 'string', enum: ['P0', 'P1', 'P2', 'P3'] },
+      due_at: { type: 'string' },
+      tags: { type: 'array', items: { type: 'string' } },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['title'],
+    additionalProperties: false,
+  },
+  'task:list': {
+    type: 'object',
+    properties: {
+      status: { type: 'string', enum: ['pending', 'done'] },
+      priority: { type: 'string', enum: ['P0', 'P1', 'P2', 'P3'] },
+      tags: { type: 'array', items: { type: 'string' } },
+      search: { type: 'string' },
+      due_before: { type: 'string' },
+      limit: { type: 'integer', minimum: 1 },
+    },
+    additionalProperties: false,
+  },
+  'task:complete': {
+    type: 'object',
+    properties: {
+      id: { type: 'string', minLength: 1 },
+      note: { type: 'string' },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['id'],
+    additionalProperties: false,
+  },
+  'task:schedule': {
+    type: 'object',
+    properties: {
+      id: { type: 'string', minLength: 1 },
+      due_at: { type: 'string' },
+      cron: { type: 'string' },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['id'],
+    additionalProperties: false,
+  },
+  'memory:store': {
+    type: 'object',
+    properties: {
+      type: { type: 'string', enum: ['fact', 'preference', 'note', 'snippet'] },
+      content: { type: 'string', minLength: 1 },
+      tags: { type: 'array', items: { type: 'string' } },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['type', 'content'],
+    additionalProperties: false,
+  },
+  'memory:recall': {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      type: { type: 'string', enum: ['fact', 'preference', 'note', 'snippet'] },
+      tags: { type: 'array', items: { type: 'string' } },
+      limit: { type: 'integer', minimum: 1 },
+    },
+    additionalProperties: false,
+  },
+  'memory:forget': {
+    type: 'object',
+    properties: {
+      id: { type: 'string', minLength: 1 },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['id'],
+    additionalProperties: false,
+  },
+  'channel:configure': {
+    type: 'object',
+    properties: {
+      name: { type: 'string', minLength: 1 },
+      type: { type: 'string', enum: ['terminal'] },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['name'],
+    additionalProperties: false,
+  },
+  'channel:send': {
+    type: 'object',
+    properties: {
+      channel: { type: 'string' },
+      content: { type: 'string', minLength: 1 },
+      sender: { type: 'string' },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['content'],
+    additionalProperties: false,
+  },
+  'channel:receive': {
+    type: 'object',
+    properties: {
+      channel: { type: 'string' },
+      limit: { type: 'integer', minimum: 1 },
+      since: { type: 'string' },
+    },
+    additionalProperties: false,
+  },
+  'routine:create': {
+    type: 'object',
+    properties: {
+      name: { type: 'string', minLength: 1 },
+      steps: {
+        type: 'array',
+        minItems: 1,
+        items: {
+          type: 'object',
+          properties: {
+            tool: { type: 'string', minLength: 1 },
+            input: { type: 'object', additionalProperties: true },
+          },
+          required: ['tool'],
+          additionalProperties: false,
+        },
+      },
+      cron: { type: 'string' },
+      enabled: { type: 'boolean' },
+      dry_run: { type: 'boolean' },
+    },
+    required: ['name', 'steps'],
+    additionalProperties: false,
+  },
+  'routine:list': {
+    type: 'object',
+    properties: {
+      enabled_only: { type: 'boolean' },
+      limit: { type: 'integer', minimum: 1 },
+    },
+    additionalProperties: false,
+  },
+  'routine:run': {
+    type: 'object',
+    properties: {
+      id: { type: 'string', minLength: 1 },
+    },
+    required: ['id'],
+    additionalProperties: false,
+  },
+  'sidekick:init': {
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+  },
+  'sidekick:status': {
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+  },
+  'sidekick:export': {
+    type: 'object',
+    properties: {
+      include_audit: { type: 'boolean' },
+    },
+    additionalProperties: false,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Generic output schema
+// ---------------------------------------------------------------------------
+
+const GENERIC_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    success: { type: 'boolean' },
+    data: { type: 'object', additionalProperties: true },
+    error: { type: 'object', additionalProperties: true },
+  },
+  additionalProperties: true,
+};
+
+// ---------------------------------------------------------------------------
+// Builder helpers
+// ---------------------------------------------------------------------------
+
+function resolveRequiredScopes(permission: ToolPermission): PathScope[] {
+  if (permission === TOOL_PERMISSIONS.READ) {
+    return [SIDEKICK_SCOPE_READ];
+  }
+  return [SIDEKICK_SCOPE_READ, SIDEKICK_SCOPE_WRITE];
+}
+
+function buildTool(name: SidekickToolName): SidekickManifestTool {
+  const permission = TOOL_PERMISSIONS_MAP[name];
+  return {
+    name,
+    entry: TOOL_ENTRIES[name],
+    permission,
+    required_scopes: resolveRequiredScopes(permission),
+    input_schema: TOOL_INPUT_SCHEMAS[name],
+    output_schema: GENERIC_OUTPUT_SCHEMA,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exported manifest
+// ---------------------------------------------------------------------------
+
+export const SIDEKICK_TOOL_NAMES = Object.keys(TOOL_PERMISSIONS_MAP) as SidekickToolName[];
+
+const SIDEKICK_MANIFEST_TEMPLATE = {
+  id: SIDEKICK_PACK_ID,
+  version: SIDEKICK_PACK_VERSION,
+  config_key: SIDEKICK_PACK_ID,
+  task_types: ['sidekick'],
+  tools: SIDEKICK_TOOL_NAMES.map((name) => buildTool(name)),
+  policies: [
+    {
+      id: `${SIDEKICK_POLICY_ID_PREFIX}.default`,
+      trigger: MANIFEST_POLICY_TRIGGERS.ON_TOOL_REQUEST,
+      decision: MANIFEST_POLICY_DECISIONS.ALLOW,
+      reason: 'Default sidekick policy permits declared tools within scoped access.',
+    },
+  ],
+  evidence_types: ['sidekick.audited.tool-call'],
+  state_aliases: {},
+  lane_templates: [],
+};
+
+export const SIDEKICK_MANIFEST: SidekickPackManifest = SidekickManifestSchema.parse(
+  SIDEKICK_MANIFEST_TEMPLATE,
+);
+
+export function getSidekickManifestToolByName(name: string): SidekickManifestTool | undefined {
+  return SIDEKICK_MANIFEST.tools.find((tool) => tool.name === name);
+}
+
+export function getSidekickToolCount(): number {
+  return SIDEKICK_MANIFEST.tools.length;
+}