@lumenflow/cli 4.24.0 → 5.0.1

package/packs/sidekick/manifest.ts

@@ -16,6 +16,7 @@ import {
   type PathScope,
   type ToolPermission,
 } from './tools/types.js';
+import { SIDEKICK_EVENT_KIND_VALUES } from './sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Scope constants
@@ -62,6 +63,10 @@ const TOOL_PERMISSIONS_MAP = {
   'routine:update': TOOL_PERMISSIONS.WRITE,
   'routine:delete': TOOL_PERMISSIONS.ADMIN,
   'routine:run': TOOL_PERMISSIONS.READ, // plan-only, no execution
+  // WU-2738 (INIT-060, ADR-013 §6 governance): plan-to-commit flow routed
+  // through agent:execute-turn. Runtime-callable tool, no top-level
+  // surface -- the governed dispatch is the only path to commit a plan.
+  'sidekick:routine:commit_plan': TOOL_PERMISSIONS.WRITE,
   // System tools (3)
   'sidekick:init': TOOL_PERMISSIONS.WRITE,
   'sidekick:status': TOOL_PERMISSIONS.READ,
@@ -74,6 +79,7 @@ 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 ROUTINE_COMMIT_TOOL_ENTRY = 'tool-impl/routine-commit.ts';
 const SYSTEM_TOOLS_ENTRY = 'tool-impl/system-tools.ts';
 const POLICY_FACTORY_ENTRY = 'policy-factory.ts#createSidekickPolicyFactory';
 
@@ -98,6 +104,7 @@ const TOOL_ENTRIES: Record<SidekickToolName, string> = {
   'routine:update': ROUTINE_TOOLS_ENTRY,
   'routine:delete': ROUTINE_TOOLS_ENTRY,
   'routine:run': ROUTINE_TOOLS_ENTRY,
+  'sidekick:routine:commit_plan': ROUTINE_COMMIT_TOOL_ENTRY,
   'sidekick:init': SYSTEM_TOOLS_ENTRY,
   'sidekick:status': SYSTEM_TOOLS_ENTRY,
   'sidekick:export': SYSTEM_TOOLS_ENTRY,
@@ -343,6 +350,23 @@ const TOOL_INPUT_SCHEMAS: Record<SidekickToolName, Record<string, unknown>> = {
     required: ['id'],
     additionalProperties: false,
   },
+  'sidekick:routine:commit_plan': {
+    type: 'object',
+    properties: {
+      plan_id: { type: 'string', minLength: 1 },
+      attestation: {
+        type: 'object',
+        properties: {
+          actor: { type: 'string', minLength: 1 },
+          reason: { type: 'string', minLength: 1 },
+        },
+        required: ['actor', 'reason'],
+        additionalProperties: true,
+      },
+    },
+    required: ['plan_id', 'attestation'],
+    additionalProperties: false,
+  },
   'sidekick:init': {
     type: 'object',
     properties: {},
@@ -387,8 +411,17 @@ function resolveRequiredScopes(permission: ToolPermission): PathScope[] {
   return [SIDEKICK_SCOPE_READ, SIDEKICK_SCOPE_WRITE];
 }
 
+// WU-2738 (INIT-060, ADR-013 §6 governance): tool-level approval surface
+// declarations. Empty array means the default policy permits dispatch; a
+// populated array signals the cloud conductor to render an approval prompt
+// before the governed `agent:execute-turn` dispatch invokes the tool.
+const TOOL_REQUIRED_APPROVALS: Partial<Record<SidekickToolName, string[]>> = {
+  'sidekick:routine:commit_plan': [],
+};
+
 function buildTool(name: SidekickToolName): SidekickManifestTool {
   const permission = TOOL_PERMISSIONS_MAP[name];
+  const requiredApprovals = TOOL_REQUIRED_APPROVALS[name];
   return {
     name,
     entry: TOOL_ENTRIES[name],
@@ -396,6 +429,7 @@ function buildTool(name: SidekickToolName): SidekickManifestTool {
     required_scopes: resolveRequiredScopes(permission),
     input_schema: TOOL_INPUT_SCHEMAS[name],
     output_schema: GENERIC_OUTPUT_SCHEMA,
+    ...(requiredApprovals !== undefined ? { required_approvals: requiredApprovals } : {}),
   };
 }
 
@@ -405,6 +439,41 @@ function buildTool(name: SidekickToolName): SidekickManifestTool {
 
 export const SIDEKICK_TOOL_NAMES = Object.keys(TOOL_PERMISSIONS_MAP) as SidekickToolName[];
 
+/**
+ * WU-2780 (ADR-013 §6 governance): tool names the sidekick pack forbids from
+ * the top-level remote surface (POST /tools/:name). These tools remain
+ * registered as runtime-callable — `agent:execute-turn` dispatches them via
+ * the governed manifest path — but any HTTP allowlist that includes them
+ * MUST be rejected fail-closed. ADR-013 §6 explicitly names `channel.send`:
+ * "The sidekick pack does NOT expose `channel.send` as a top-level surface
+ * the agent can call outside a turn. It is registered only as a
+ * runtime-callable tool."
+ */
+const ADR_013_SECTION_6_RUNTIME_ONLY_TOOLS: readonly SidekickToolName[] = ['channel:send'] as const;
+
+/**
+ * WU-2780 (INIT-060, ADR-013 §6): sidekick pack tools that MAY be exposed on
+ * the HTTP tool-api surface (POST /tools/:name). Mirrors the
+ * `REMOTE_CALLABLE_TOOLS` export pattern in sibling packs (software-delivery,
+ * agent-runtime) so integrators have a single source of truth when wiring
+ * the surface allowlist. ADR-013 §6 runtime-only tools are excluded by
+ * construction; the HTTP tool-api also enforces this fail-closed at router
+ * construction.
+ */
+export const SIDEKICK_REMOTE_CALLABLE_TOOLS: readonly SidekickToolName[] =
+  SIDEKICK_TOOL_NAMES.filter(
+    (name): name is SidekickToolName => !ADR_013_SECTION_6_RUNTIME_ONLY_TOOLS.includes(name),
+  );
+
+/**
+ * WU-2780 (INIT-060, ADR-013 §6): returns a fresh copy of the ordered
+ * remote-callable tool name list. Keeps the export immutable for callers
+ * that prefer arrays over readonly tuples.
+ */
+export function getSidekickRemoteCallableToolNames(): SidekickToolName[] {
+  return [...SIDEKICK_REMOTE_CALLABLE_TOOLS];
+}
+
 const SIDEKICK_MANIFEST_TEMPLATE = {
   id: SIDEKICK_PACK_ID,
   version: SIDEKICK_PACK_VERSION,
@@ -421,8 +490,13 @@ const SIDEKICK_MANIFEST_TEMPLATE = {
     },
   ],
   evidence_types: ['sidekick.audited.tool-call'],
+  emitted_event_kinds: [...SIDEKICK_EVENT_KIND_VALUES],
   state_aliases: {},
   lane_templates: [],
+  // WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge): the sidekick pack
+  // requires the `sidekick-channel` transport surface. The kernel refuses
+  // to activate the pack if the surface isn't registered at startup.
+  surfaces_required: ['sidekick-channel'],
 };
 
 export const SIDEKICK_MANIFEST: SidekickPackManifest = SidekickManifestSchema.parse(

package/packs/sidekick/manifest.yaml

@@ -353,6 +353,13 @@ tools:
     output_schema:
       type: object
       additionalProperties: true
+  # WU-2780 (ADR-013 §6 governance): runtime-callable only. `channel.send`
+  # MUST route through agent:execute-turn so every phone-directed message
+  # becomes an `agent-runtime:tool_called` audit event. The pack manifest
+  # registers it here so the kernel can dispatch it from within a turn, but
+  # the HTTP tool-api surface (POST /tools/:name) rejects it fail-closed —
+  # see SIDEKICK_REMOTE_CALLABLE_TOOLS in manifest.ts and
+  # ADR_013_SECTION_6_FORBIDDEN_REMOTE_TOOLS in surfaces/http/tool-api.ts.
   - name: channel:send
     entry: tool-impl/channel-tools.ts
     permission: write
@@ -558,6 +565,44 @@ tools:
     output_schema:
       type: object
       additionalProperties: true
+  # WU-2738 (INIT-060, ADR-013 §6 governance): plan-to-commit flow routed
+  # through agent:execute-turn. Runtime-callable tool, no top-level
+  # surface -- the governed dispatch is the only path to commit a plan.
+  # required_approvals is declared (empty) so the cloud conductor treats
+  # the tool as approval-aware even when the default policy permits it.
+  - name: sidekick:routine:commit_plan
+    entry: tool-impl/routine-commit.ts
+    permission: write
+    required_scopes:
+      - type: path
+        pattern: .sidekick/**
+        access: read
+      - type: path
+        pattern: .sidekick/**
+        access: write
+    required_approvals: []
+    input_schema:
+      type: object
+      properties:
+        plan_id:
+          type: string
+          minLength: 1
+        attestation:
+          type: object
+          properties:
+            actor:
+              type: string
+              minLength: 1
+            reason:
+              type: string
+              minLength: 1
+          required: [actor, reason]
+          additionalProperties: true
+      required: [plan_id, attestation]
+      additionalProperties: false
+    output_schema:
+      type: object
+      additionalProperties: true
   - name: sidekick:init
     entry: tool-impl/system-tools.ts
     permission: write
@@ -612,5 +657,48 @@ policies:
     reason: Default sidekick policy permits declared tools within scoped access.
 evidence_types:
   - sidekick.audited.tool-call
+# WU-2734 (INIT-060, ADR-013): sidekick emits 16 namespaced event kinds on the
+# pack channel. Command-style task/routine/bootstrap events use queued replay;
+# memory and channel observations are ephemeral and fail silent without
+# control_plane.org_id.
+emitted_event_kinds:
+  - sidekick:task_created
+  - sidekick:task_completed
+  - sidekick:task_scheduled
+  - sidekick:task_snoozed
+  - sidekick:memory_stored
+  - sidekick:memory_recalled
+  - sidekick:memory_forgotten
+  - sidekick:channel_message_sent
+  - sidekick:channel_message_received
+  - sidekick:channel_bridge_connected
+  - sidekick:channel_bridge_disconnected
+  - sidekick:routine_planned
+  - sidekick:routine_committed
+  - sidekick:routine_executed
+  - sidekick:routine_step_failed
+  - sidekick:state_rehydrated
+backpressure_policy:
+  sidekick:task_created: queue-with-replay
+  sidekick:task_completed: queue-with-replay
+  sidekick:task_scheduled: queue-with-replay
+  sidekick:task_snoozed: queue-with-replay
+  sidekick:memory_stored: ephemeral
+  sidekick:memory_recalled: ephemeral
+  sidekick:memory_forgotten: ephemeral
+  sidekick:channel_message_sent: ephemeral
+  sidekick:channel_message_received: ephemeral
+  sidekick:channel_bridge_connected: ephemeral
+  sidekick:channel_bridge_disconnected: ephemeral
+  sidekick:routine_planned: queue-with-replay
+  sidekick:routine_committed: queue-with-replay
+  sidekick:routine_executed: queue-with-replay
+  sidekick:routine_step_failed: queue-with-replay
+  sidekick:state_rehydrated: queue-with-replay
 state_aliases: {}
 lane_templates: []
+# WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge): the sidekick pack requires
+# the `sidekick-channel` transport surface. The kernel refuses to activate the
+# pack if the surface isn't registered at startup.
+surfaces_required:
+  - sidekick-channel

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "4.24.0",
+  "version": "5.0.1",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",
@@ -24,12 +24,14 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
+    "./channel-ingress": "./dist/channel-ingress.js",
     "./storage": "./dist/tool-impl/storage.js",
     "./tools": "./dist/tools/index.js",
     "./tool-impl": "./dist/tool-impl/index.js",
     "./tool-impl/channel-transports": "./dist/tool-impl/channel-transports.js",
     "./tool-impl/channel-tools": "./dist/tool-impl/channel-tools.js",
     "./tool-impl/memory-tools": "./dist/tool-impl/memory-tools.js",
+    "./tool-impl/routine-commit": "./dist/tool-impl/routine-commit.js",
     "./tool-impl/routine-tools": "./dist/tool-impl/routine-tools.js",
     "./tool-impl/shared": "./dist/tool-impl/shared.js",
     "./tool-impl/storage": "./dist/tool-impl/storage.js",