@lumenflow/cli 3.19.0 → 3.20.0

package/packs/sidekick/README.md

@@ -1,194 +1,199 @@
 # Sidekick Pack
 
-Personal productivity pack for the LumenFlow kernel. Provides task management,
-workspace memory, communication channels, routines, and system administration
-tools -- all scoped to a local `.sidekick/` directory.
+Workspace-local productivity pack for the LumenFlow kernel. Sidekick manages tasks, memory,
+channels, routines, and status under `.sidekick/`, while keeping every tool call inside the normal
+kernel scope, policy, and evidence pipeline.
 
 ## Status
 
-**Version**: 0.1.0 (pre-release)
-**License**: AGPL-3.0-only
+**Version**: `0.1.0` (pre-release)  
+**License**: `AGPL-3.0-only`
 
 ## Tool Groups
 
-| Group   | Tools                                                        | Description                                 |
-| ------- | ------------------------------------------------------------ | ------------------------------------------- |
-| Task    | `task:create`, `task:list`, `task:complete`, `task:schedule` | Create, query, complete, and schedule tasks |
-| Memory  | `memory:store`, `memory:recall`, `memory:forget`             | Persist and retrieve workspace knowledge    |
-| Channel | `channel:configure`, `channel:send`, `channel:receive`       | Named message channels                      |
-| Routine | `routine:create`, `routine:list`, `routine:run`              | Multi-step tool sequences (plan-only)       |
-| System  | `sidekick:init`, `sidekick:status`, `sidekick:export`        | Bootstrap, health check, data export        |
-
-**Total**: 16 tools
-
-## Key Design Decisions
-
-- **`.sidekick/` is workspace-local storage.** All data lives under the project
-  root in a `.sidekick/` directory managed by the `StoragePort` abstraction.
-- **`routine:run` returns a plan only.** It resolves the routine definition and
-  returns the ordered list of steps with their inputs. It does not execute them.
-- **`sidekick:export` is read-only.** It returns all stored data as a JSON
-  structure. It does not write files to disk.
-- **Every write tool supports `dry_run`.** When `dry_run: true`, the tool
-  validates input and returns what it would do, without persisting changes.
-- **Pack manifest is the contract.** There is no separate contract package. The
-  `manifest.yaml` file defines tool names, schemas, scopes, and policies.
+| Group   | Tools                                                                                      | Description                                                |
+| ------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| Task    | `task:create`, `task:list`, `task:update`, `task:cancel`, `task:complete`, `task:schedule` | Create, manage, cancel, complete, and schedule local tasks |
+| Memory  | `memory:store`, `memory:recall`, `memory:update`, `memory:forget`                          | Persist and edit reusable workspace knowledge              |
+| Channel | `channel:configure`, `channel:list`, `channel:delete`, `channel:send`, `channel:receive`   | Discover and manage named local message channels           |
+| Routine | `routine:create`, `routine:list`, `routine:update`, `routine:delete`, `routine:run`        | Define, stop, inspect, and remove plan-only routines       |
+| System  | `sidekick:init`, `sidekick:status`, `sidekick:export`                                      | Bootstrap, health check, and export Sidekick-managed state |
 
-## Manual Smoke Flow
+**Total**: 23 tools
 
-Use this sequence to verify the pack end-to-end after installation or upgrade.
+## Behavior Notes
 
-### Prerequisites
+- `.sidekick/` is the pack-owned storage root.
+- `routine:run` is plan-only. It returns the resolved steps and never executes them.
+- `routine:update` with `enabled: false` is the stop primitive for routines.
+- `task:cancel` is the destructive task terminal state; it is separate from `task:complete`.
+- `sidekick:export` is read-only. It returns data and does not write export artifacts.
+- All write-capable and destructive tools support `dry_run`.
+- Destructive Sidekick tools are approval-gated through the pack policy factory.
 
-- LumenFlow kernel runtime with the sidekick pack registered
-- HTTP surface running (for HTTP dispatch tests)
+### Approval-Gated Destructive Tools
 
-### Step 1: Initialize
+These tools require policy evaluation to return `approval_required` before execution:
 
-```bash
-# Via kernel tool dispatch (or HTTP POST /tools/sidekick:init)
+- `task:cancel`
+- `memory:forget`
+- `channel:delete`
+- `routine:delete`
+
+The permission label helps classify them as destructive, but the actual pause comes from the pack
+policy path and kernel approval flow.
+
+## Manual Smoke Flow
+
+Use this sequence after installation or whenever you want to smoke test the current contract.
+
+### 1. Initialize storage
+
+```text
 tool: sidekick:init
 input: {}
 ```
 
-Expected: `{ "success": true, "data": { "initialized": true, "root_dir": ".sidekick" } }`
+Expected: `initialized: true` and a `.sidekick/` root path.
 
-### Step 2: Create a Task
+### 2. Create and update a task
 
-```bash
+```text
 tool: task:create
 input: { "title": "Review docs", "priority": "P1", "tags": ["docs"] }
 ```
 
-Expected: `{ "success": true, "data": { "id": "<uuid>", "title": "Review docs", ... } }`
-
-### Step 3: List Tasks
-
-```bash
-tool: task:list
-input: { "status": "pending" }
+```text
+tool: task:update
+input: {
+  "id": "<task-id>",
+  "description": "Check final Sidekick contract",
+  "due_at": "2026-03-31T00:00:00Z"
+}
 ```
 
-Expected: Array containing the task from Step 2.
+Expected: `task:list` returns the updated task metadata.
 
-### Step 4: Store a Memory
+### 3. Store and update memory
 
-```bash
+```text
 tool: memory:store
-input: { "type": "note", "content": "Sidekick pack validated", "tags": ["smoke-test"] }
+input: { "type": "note", "content": "Sidekick docs updated", "tags": ["docs"] }
 ```
 
-Expected: `{ "success": true, "data": { "id": "<uuid>", ... } }`
-
-### Step 5: Recall Memory
-
-```bash
-tool: memory:recall
-input: { "query": "validated", "type": "note" }
+```text
+tool: memory:update
+input: { "id": "<memory-id>", "type": "snippet", "content": "task:cancel is approval-gated" }
 ```
 
-Expected: Array containing the memory from Step 4.
+Expected: `memory:recall` returns the edited record.
 
-### Step 6: Create a Routine
+### 4. Create and stop a routine
 
-```bash
+```text
 tool: routine:create
 input: {
   "name": "daily-review",
   "steps": [
     { "tool": "task:list", "input": { "status": "pending" } },
     { "tool": "sidekick:status", "input": {} }
-  ]
+  ],
+  "enabled": true
 }
 ```
 
-Expected: `{ "success": true, "data": { "id": "<uuid>", "name": "daily-review", ... } }`
+```text
+tool: routine:update
+input: { "id": "<routine-id>", "enabled": false }
+```
 
-### Step 7: Run Routine (plan-only)
+Expected: `routine:list` still shows the routine, while `routine:list { "enabled_only": true }`
+excludes it.
 
-```bash
+### 5. Inspect a routine plan
+
+```text
 tool: routine:run
-input: { "id": "<routine-id-from-step-6>" }
+input: { "id": "<routine-id>" }
 ```
 
-Expected: A plan object listing the two steps with their resolved inputs. No
-side-effects -- the steps are NOT executed.
+Expected: A plan object listing the ordered steps. No side effects occur.
 
-### Step 8: Check Status
+### 6. Check channel discovery
 
-```bash
-tool: sidekick:status
+```text
+tool: channel:send
+input: { "channel": "alerts", "content": "Docs smoke flow" }
+```
+
+```text
+tool: channel:list
 input: {}
 ```
 
-Expected: Summary showing `task_count >= 1`, `memory_entries >= 1`,
-`routines >= 1`.
+Expected: A local channel entry with stable metadata such as `message_count` and
+`last_message_at`.
 
-### Step 9: Export
+### 7. Verify a destructive dry run
 
-```bash
-tool: sidekick:export
-input: { "include_audit": true }
+```text
+tool: task:cancel
+input: { "id": "<task-id>", "dry_run": true }
 ```
 
-Expected: Full JSON dump of all stores including audit trail from prior steps.
+Expected: The response previews the canceled task and includes `dry_run: true`, while
+`task:list { "status": "pending" }` still shows the task as pending.
 
-### Step 10: Complete the Task
+### 8. Verify approval-gated destructive behavior
 
-```bash
-tool: task:complete
-input: { "id": "<task-id-from-step-2>", "note": "Smoke test passed" }
-```
+Run `task:cancel`, `memory:forget`, `channel:delete`, or `routine:delete` through the kernel
+runtime or host surface that evaluates policies.
 
-Expected: `{ "success": true, "data": { "status": "done", ... } }`
+Expected: The first attempt returns `APPROVAL_REQUIRED`. After approval resolution, the tool runs
+and the audit trail reflects the final delete or cancel transition.
 
-### Step 11: Verify via HTTP Surface
+### 9. Export
 
-```bash
-curl -X POST http://localhost:<port>/tools/sidekick:status \
-  -H "Content-Type: application/json" \
-  -d '{ "context": { "task_id": "smoke-test", "workspace_id": "test" } }'
+```text
+tool: sidekick:export
+input: { "include_audit": true }
 ```
 
-Expected: HTTP 200 with the same status payload as Step 8.
-
-### Dry Run Verification
-
-Repeat Step 2 with `"dry_run": true` added to the input. Verify that the
-response includes `"dry_run": true` and that `task:list` does not return the
-dry-run task.
+Expected: A full JSON snapshot of stores plus audit events.
 
 ## Validation
 
 ```bash
-# Schema and integrity validation
+# Pack contract and integrity
 pnpm pack:validate --id sidekick
 
-# Unit tests (119 tests across 3 suites)
-npx vitest run packages/@lumenflow/packs/sidekick/__tests__/
+# Sidekick tool and manifest tests
+pnpm vitest run packages/@lumenflow/packs/sidekick/__tests__/
 
-# HTTP surface tests (13 tests)
-npx vitest run packages/@lumenflow/surfaces/http/__tests__/tool-api.test.ts
+# Kernel approval coverage for Sidekick destructive tools
+pnpm vitest run packages/@lumenflow/kernel/src/__tests__/runtime.test.ts
 ```
 
-## Storage Architecture
+## Storage Layout
 
-The pack uses a `StoragePort` abstraction with a filesystem adapter
-(`FsStoragePort`). Each store (tasks, memories, channels, messages, routines)
-is a JSON array file under `.sidekick/`. An append-only `audit.jsonl` file
-records every tool invocation.
+Sidekick uses a `StoragePort` abstraction with a filesystem adapter. The persisted layout is:
 
-```
+```text
 .sidekick/
-  tasks.json
-  memories.json
-  channels.json
-  messages.json
-  routines.json
-  audit.jsonl
+  audit/
+    events.jsonl
+  channels/
+    channels.json
+    messages.json
+  memory/
+    memories.json
+  routines/
+    routines.json
+  tasks/
+    tasks.json
 ```
 
 ## Contributing
 
-This pack follows the LumenFlow development workflow. See the root `CLAUDE.md`
-and `LUMENFLOW.md` for contribution guidelines.
+This pack follows the LumenFlow workflow. See the repository `LUMENFLOW.md` and workspace rules for
+delivery expectations.

package/packs/sidekick/manifest-schema.ts

@@ -2,23 +2,18 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 import {
-  TOOL_PERMISSIONS,
-  TOOL_SCOPE_ACCESS,
-  TOOL_SCOPE_TYPES,
-  type PathScope,
-  type ToolPermission,
-} from './tools/types.js';
+  DomainPackManifestSchema,
+  POLICY_TRIGGERS,
+  type DomainPackManifest,
+  type DomainPackTool,
+} from '@lumenflow/kernel';
+import type { PathScope, 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 const MANIFEST_POLICY_TRIGGERS = POLICY_TRIGGERS;
 
 export type ManifestPolicyTrigger =
   (typeof MANIFEST_POLICY_TRIGGERS)[keyof typeof MANIFEST_POLICY_TRIGGERS];
@@ -26,237 +21,29 @@ export type ManifestPolicyTrigger =
 export const MANIFEST_POLICY_DECISIONS = {
   ALLOW: 'allow',
   DENY: 'deny',
+  APPROVAL_REQUIRED: 'approval_required',
 } as const;
 
 export type ManifestPolicyDecision =
   (typeof MANIFEST_POLICY_DECISIONS)[keyof typeof MANIFEST_POLICY_DECISIONS];
 
-export interface SidekickManifestTool {
-  name: string;
-  entry: string;
+export interface SidekickManifestTool extends Omit<
+  DomainPackTool,
+  'permission' | 'required_scopes'
+> {
   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 type SidekickManifestPolicy = DomainPackManifest['policies'][number];
 
-export interface SidekickPackManifest {
-  id: string;
-  version: string;
-  config_key?: string;
-  config_schema?: string;
-  task_types: string[];
+export interface SidekickPackManifest extends Omit<DomainPackManifest, 'tools' | 'policies'> {
   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`) };
-      }),
-    };
+    return DomainPackManifestSchema.parse(input) as SidekickPackManifest;
   },
 };