@lumenflow/cli 4.24.0 → 5.0.0

package/packs/sidekick/channel-ingress.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * WU-2731 (INIT-060 phase 3, ADR-013 §5 Identity):
+ * Pure inbound-channel ingress sanitizer.
+ *
+ * ADR-013 §5 rules, enforced here:
+ *
+ * - The authoritative `from` value for an inbound phone POST comes from the
+ *   authenticated token subject (`{workspace_id}:phone:{device_id}`). Cloud
+ *   MUST NOT trust a `from` field supplied in the request body.
+ *
+ * - Body-supplied `from` (and any alias under `metadata.from`) is stripped
+ *   before the envelope reaches domain code. The surface that calls this
+ *   module is expected to pass the resolved `from` separately; attempting to
+ *   ingest a body-only envelope (no authoritative from) fails closed.
+ *
+ * The module is HTTP-independent: both the kernel tool-api surface and the
+ * future control-plane adapter (WU-2737) call the same sanitizer so the
+ * ignore-body-from rule is enforced in one place.
+ */
+
+const ENVELOPE_BODY_FIELD_FROM = 'from' as const;
+const ENVELOPE_METADATA_KEY = 'metadata' as const;
+const ENVELOPE_FROM_SOURCE_TOKEN = 'token' as const;
+
+export interface PhoneChannelIngressInput {
+  /**
+   * Raw request body as parsed from JSON. Opaque record; the sanitizer does
+   * not inspect `body`, only the `from` attribution fields.
+   */
+  body: Readonly<Record<string, unknown>>;
+  /**
+   * Authoritative identity claim resolved from the bearer token. Required:
+   * without a token subject, cloud cannot attribute the message, and the
+   * ingress path rejects the request.
+   */
+  authoritativeFrom: string;
+}
+
+export interface PhoneChannelIngressEnvelope {
+  /**
+   * Sanitised request body with any body-level `from` stripped. Everything
+   * else the caller supplied is preserved so downstream code (channel.send,
+   * routing) can consume arbitrary payload fields.
+   */
+  body: Record<string, unknown>;
+  /** Authoritative attribution string (`{workspace_id}:phone:{device_id}`). */
+  from: string;
+  /** Always `'token'` — cloud-safe invariant per ADR-013 §5. */
+  from_source: typeof ENVELOPE_FROM_SOURCE_TOKEN;
+}
+
+export class PhoneChannelIngressError extends Error {
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = 'PhoneChannelIngressError';
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Sanitize an inbound phone-channel request. Returns a cleaned envelope with
+ * the authoritative `from` baked in. Throws `PhoneChannelIngressError` (HTTP
+ * 400) when the authoritative `from` is missing — the surface translates the
+ * error to a 400/403 response.
+ */
+export function sanitizePhoneChannelIngress(
+  input: PhoneChannelIngressInput,
+): PhoneChannelIngressEnvelope {
+  if (typeof input.authoritativeFrom !== 'string' || input.authoritativeFrom.length === 0) {
+    throw new PhoneChannelIngressError(
+      'Inbound phone channel requires authoritative from (token subject); body-only attribution is rejected.',
+      400,
+    );
+  }
+
+  const sanitizedBody = stripKey(input.body, ENVELOPE_BODY_FIELD_FROM);
+  const rawMetadata = sanitizedBody[ENVELOPE_METADATA_KEY];
+  if (
+    rawMetadata !== null &&
+    typeof rawMetadata === 'object' &&
+    !Array.isArray(rawMetadata) &&
+    ENVELOPE_BODY_FIELD_FROM in (rawMetadata as Record<string, unknown>)
+  ) {
+    sanitizedBody[ENVELOPE_METADATA_KEY] = stripKey(
+      rawMetadata as Record<string, unknown>,
+      ENVELOPE_BODY_FIELD_FROM,
+    );
+  }
+
+  return {
+    body: sanitizedBody,
+    from: input.authoritativeFrom,
+    from_source: ENVELOPE_FROM_SOURCE_TOKEN,
+  };
+}
+
+/**
+ * Copy `record` omitting the given key. Implemented with a filtered
+ * `Object.entries` rather than `delete` to satisfy the linter's ban on
+ * dynamic-delete (which would otherwise be a no-op for literal keys but
+ * fails the rule uniformly).
+ */
+function stripKey(record: Readonly<Record<string, unknown>>, key: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [entryKey, entryValue] of Object.entries(record)) {
+    if (entryKey !== key) {
+      result[entryKey] = entryValue;
+    }
+  }
+  return result;
+}
+
+/**
+ * Convenience: reports whether the given `from` subject matches the
+ * phone-device grammar (`{workspace_id}:phone:{device_id}`). Useful to
+ * tell workspace-scoped actors from phone-device actors in the audit log
+ * without reaching for the enrollment parser.
+ */
+export function isPhoneSubject(subject: string): boolean {
+  const parts = subject.split(':');
+  if (parts.length !== 3) {
+    return false;
+  }
+  const [workspace, kind, device] = parts;
+  return (
+    kind === 'phone' &&
+    typeof workspace === 'string' &&
+    workspace.length > 0 &&
+    typeof device === 'string' &&
+    device.length > 0
+  );
+}

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.0",
   "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",