@lumenflow/cli 3.17.6 → 3.18.0

package/packs/agent-runtime/tools/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export * from './types.js';

package/packs/agent-runtime/tools/types.ts

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { ToolScope } from '@lumenflow/kernel';
+import {
+  AGENT_RUNTIME_DOMAIN,
+  AGENT_RUNTIME_PACK_ID,
+  AGENT_RUNTIME_PACK_VERSION,
+} from '../constants.js';
+import type { AgentRuntimeToolName } from '../types.js';
+
+export const AGENT_RUNTIME_TOOL_PERMISSIONS = {
+  READ: 'read',
+  WRITE: 'write',
+  ADMIN: 'admin',
+} as const;
+
+export type AgentRuntimeToolPermission =
+  (typeof AGENT_RUNTIME_TOOL_PERMISSIONS)[keyof typeof AGENT_RUNTIME_TOOL_PERMISSIONS];
+
+export interface AgentRuntimeToolDescriptor {
+  name: AgentRuntimeToolName;
+  domain: typeof AGENT_RUNTIME_DOMAIN;
+  pack: typeof AGENT_RUNTIME_PACK_ID;
+  version: typeof AGENT_RUNTIME_PACK_VERSION;
+  permission: AgentRuntimeToolPermission;
+  required_scopes: ToolScope[];
+  entry: string;
+}
+
+export interface AgentRuntimeToolDescriptorInput {
+  name: AgentRuntimeToolDescriptor['name'];
+  permission: AgentRuntimeToolDescriptor['permission'];
+  required_scopes: AgentRuntimeToolDescriptor['required_scopes'];
+  entry: AgentRuntimeToolDescriptor['entry'];
+}
+
+export function createAgentRuntimeToolDescriptor(
+  input: AgentRuntimeToolDescriptorInput,
+): AgentRuntimeToolDescriptor {
+  return {
+    ...input,
+    domain: AGENT_RUNTIME_DOMAIN,
+    pack: AGENT_RUNTIME_PACK_ID,
+    version: AGENT_RUNTIME_PACK_VERSION,
+  };
+}

package/packs/agent-runtime/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__"]
+}

package/packs/agent-runtime/types.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  AGENT_RUNTIME_API_KEY_ENV,
+  AGENT_RUNTIME_BASE_URL_ENV,
+  AGENT_RUNTIME_PACK_ID,
+} from './constants.js';
+
+export const AGENT_RUNTIME_PROVIDER_KINDS = {
+  OPENAI_COMPATIBLE: 'openai_compatible',
+  MESSAGES_COMPATIBLE: 'messages_compatible',
+} as const;
+
+export const AGENT_RUNTIME_TURN_STATUSES = {
+  REPLY: 'reply',
+  TOOL_REQUEST: 'tool_request',
+  COMPLETE: 'complete',
+  ESCALATE: 'escalate',
+} as const;
+
+export const AGENT_RUNTIME_TOOL_NAMES = {
+  EXECUTE_TURN: 'agent:execute-turn',
+} as const;
+
+export type AgentRuntimePackId = typeof AGENT_RUNTIME_PACK_ID;
+export type AgentRuntimeProviderKind =
+  (typeof AGENT_RUNTIME_PROVIDER_KINDS)[keyof typeof AGENT_RUNTIME_PROVIDER_KINDS];
+export type AgentRuntimeTurnStatus =
+  (typeof AGENT_RUNTIME_TURN_STATUSES)[keyof typeof AGENT_RUNTIME_TURN_STATUSES];
+export type AgentRuntimeToolName =
+  (typeof AGENT_RUNTIME_TOOL_NAMES)[keyof typeof AGENT_RUNTIME_TOOL_NAMES];
+
+export interface AgentRuntimeModelProfileConfig {
+  provider: AgentRuntimeProviderKind;
+  model: string;
+  api_key_env: string;
+  base_url?: string;
+  base_url_env?: string;
+}
+
+export interface AgentRuntimeIntentConfig {
+  description: string;
+  allow_tools: string[];
+  approval_required_tools?: string[];
+}
+
+export interface AgentRuntimeLimitsConfig {
+  max_turns_per_session?: number;
+  max_tool_calls_per_session?: number;
+  max_input_bytes?: number;
+}
+
+export interface AgentRuntimePackConfig {
+  default_model: string;
+  models: Record<string, AgentRuntimeModelProfileConfig>;
+  intents?: Record<string, AgentRuntimeIntentConfig>;
+  limits?: AgentRuntimeLimitsConfig;
+}
+
+export interface AgentRuntimeMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  tool_name?: string;
+  tool_call_id?: string;
+}
+
+export interface AgentRuntimeToolCatalogEntry {
+  name: string;
+  description: string;
+  input_schema?: Record<string, unknown>;
+}
+
+export interface AgentRuntimeIntentCatalogEntry {
+  id: string;
+  description: string;
+}
+
+export interface AgentRuntimeExecuteTurnInput {
+  session_id: string;
+  messages: AgentRuntimeMessage[];
+  model_profile: string;
+  url: string;
+  stream?: boolean;
+  tool_catalog?: AgentRuntimeToolCatalogEntry[];
+  intent_catalog?: AgentRuntimeIntentCatalogEntry[];
+  limits?: AgentRuntimeLimitsConfig;
+}
+
+export interface AgentRuntimeStreamSnapshot {
+  sequence: number;
+  state: 'partial' | 'final';
+  data: Record<string, unknown>;
+}
+
+export interface AgentRuntimeRequestedTool {
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface AgentRuntimeUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+}
+
+export interface AgentRuntimeProviderDescriptor {
+  kind: AgentRuntimeProviderKind;
+  model: string;
+}
+
+export interface AgentRuntimeExecuteTurnOutput {
+  status: AgentRuntimeTurnStatus;
+  intent: string;
+  assistant_message: string;
+  requested_tool?: AgentRuntimeRequestedTool;
+  provider: AgentRuntimeProviderDescriptor;
+  usage?: AgentRuntimeUsage;
+  finish_reason: string;
+}
+
+export const AGENT_RUNTIME_DECLARED_ENVIRONMENT_VARIABLES = [
+  AGENT_RUNTIME_API_KEY_ENV,
+  AGENT_RUNTIME_BASE_URL_ENV,
+] as const;
+
+export type AgentRuntimeDeclaredEnvironmentVariable =
+  (typeof AGENT_RUNTIME_DECLARED_ENVIRONMENT_VARIABLES)[number];

package/packs/agent-runtime/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['__tests__/**/*.test.ts', '**/*.spec.ts'],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    passWithNoTests: false,
+  },
+});

package/packs/sidekick/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-sidekick@3.17.6 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
+> @lumenflow/packs-sidekick@3.18.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
 > tsc
 

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "3.17.6",
+  "version": "3.18.0",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",

package/packs/sidekick/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['__tests__/**/*.test.ts', '**/*.spec.ts'],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    passWithNoTests: false,
+  },
+});

package/packs/software-delivery/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-software-delivery@3.17.6 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
+> @lumenflow/packs-software-delivery@3.18.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
 > tsc
 

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "3.17.6",
+  "version": "3.18.0",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['__tests__/**/*.test.ts', '**/*.spec.ts'],
+    exclude: ['**/node_modules/**', '**/dist/**'],
+    passWithNoTests: false,
+  },
+});

package/templates/core/.lumenflow/rules/wu-workflow.md.template

@@ -15,7 +15,7 @@ ready -> in_progress -> done
 
 ```bash
 # 1. Check lane is free
-cat docs/04-operations/tasks/status.md
+cat docs/operations/tasks/status.md
 
 # 2. Claim the WU (creates worktree)
 pnpm wu:claim --id WU-XXX --lane <Lane>

package/templates/core/LUMENFLOW.md.template

@@ -8,7 +8,7 @@
 
 LumenFlow is a vendor-agnostic workflow framework for AI-native software development.
 
-> **Context Safety**: When approaching context limits (80% usage, 50+ tool calls), spawn a fresh agent instead of continuing after compaction. See [wu-sizing-guide.md]({{DOCS_ONBOARDING_PATH}}/wu-sizing-guide.md).
+> **Context Safety**: When approaching context limits (80% usage, 50+ tool calls), spawn a fresh agent instead of continuing after compaction. See [wu-sizing-guide.md]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md).
 
 ---
 
@@ -358,6 +358,6 @@ Supported clients: `claude-code`, `codex-cli`, `cursor`, `gemini-cli`, `windsurf
 - [Quick Reference: Commands]({{QUICK_REF_LINK}}) -- Complete CLI reference (100+ commands)
 - [Troubleshooting wu:done]({{DOCS_ONBOARDING_PATH}}/troubleshooting-wu-done.md) -- Most common completion mistakes
 - [.lumenflow/constraints.md](.lumenflow/constraints.md) -- Non-negotiable rules and forbidden commands
-- [WU Sizing Guide]({{DOCS_ONBOARDING_PATH}}/wu-sizing-guide.md) -- Scoping work without needless fragmentation
+- [WU Sizing Guide]({{DOCS_OPERATIONS_PATH}}/_frameworks/lumenflow/wu-sizing-guide.md) -- Scoping work without needless fragmentation
 - [Skills Index](.claude/skills/INDEX.md)
 - [Agents README](.claude/agents/README.md)

package/templates/core/ai/onboarding/first-wu-mistakes.md.template

@@ -330,7 +330,7 @@ sizing_estimate:
   strategy: checkpoint-resume
 ```
 
-3. **Split the WU** only if the work is no longer atomic or should land independently (see [wu-sizing-guide.md](./wu-sizing-guide.md) section 3 for splitting patterns).
+3. **Split the WU** only if the work is no longer atomic or should land independently (see [wu-sizing-guide.md](../../wu-sizing-guide.md) section 3 for splitting patterns).
 
 **Strict mode:** Teams can enforce sizing compliance for delegated work with `--strict-sizing` on `wu:brief`. In strict mode, missing or non-compliant sizing metadata blocks the operation.
 
@@ -339,7 +339,7 @@ sizing_estimate:
 pnpm wu:brief --id WU-XXX --client claude-code --strict-sizing
 ```
 
-See the [WU Sizing Guide](./wu-sizing-guide.md) section 1.4 for the full contract specification.
+See the [WU Sizing Guide](../../wu-sizing-guide.md) section 1.5 for the full contract specification.
 
 ---
 

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -835,4 +835,4 @@ For a complete picture of how all WU commands, memory tools, and orchestration t
 - **[Failure-Mode Runbook](../../lumenflow-agent-capsule.md)** -- Concrete remediation for main-behind-origin, partial-claim state, spawn-provenance enforcement, and wu:recover usage
 - **[Troubleshooting wu:done](./troubleshooting-wu-done.md)** -- Most common agent mistake (two-step wu:prep + wu:done workflow)
 - **[First WU Mistakes](./first-wu-mistakes.md)** -- Common first-time pitfalls and how to avoid them
-- **[WU Sizing Guide](./wu-sizing-guide.md)** -- Context safety triggers, complexity assessment, and session strategies
+- **[WU Sizing Guide](../../wu-sizing-guide.md)** -- Context safety triggers, complexity assessment, and session strategies

package/templates/core/ai/onboarding/starting-prompt.md.template

@@ -733,5 +733,5 @@ rm -rf /tmp/nextjs-scaffold
 - [troubleshooting-wu-done.md](troubleshooting-wu-done.md) - Why agents forget wu:done
 - [first-wu-mistakes.md](first-wu-mistakes.md) - Common mistakes to avoid
 - [quick-ref-commands.md](quick-ref-commands.md) - Command reference
-- [wu-sizing-guide.md](wu-sizing-guide.md) - Context safety and WU sizing
+- [wu-sizing-guide.md](../../wu-sizing-guide.md) - Context safety and WU sizing
 - [initiative-orchestration.md](initiative-orchestration.md) - Initiative orchestration, delegation, recovery

package/templates/vendors/claude/.claude/skills/frontend-design/SKILL.md.template

@@ -2,7 +2,7 @@
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces. Use when building React components, pages, UI features, or when user requests visual/design work.
 version: 1.0.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source: docs/operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
 last_updated: {{DATE}}
 allowed-tools: Read, Write, Edit, Bash
 ---

package/templates/core/ai/onboarding/wu-sizing-guide.md.template

@@ -1,84 +0,0 @@
-# Work Unit Sizing Guide
-
-**Last updated:** {{DATE}}
-
-Use this summary to decide whether work should stay as one WU and what execution strategy it needs.
-
----
-
-## Default Bias
-
-Bias toward **one coherent outcome = one WU**.
-
-Do not split a WU just because it has multiple implementation steps, tests, or docs, or because it may need another session. Split only when the work is no longer one coherent deliverable.
-
-Before splitting, ask: **Can these parts ship, review, and roll back independently?** If no, keep one WU and choose a better execution strategy.
-
-Keep one WU when:
-
-- The acceptance criteria describe one user-visible or operator-visible outcome
-- One agent can still complete it with `single-session`, `checkpoint-resume`, or `orchestrator-worker`
-- The touched files support the same change, even if there are several of them
-- Code, tests, and docs all support the same change
-
-Split when:
-
-- Parts can ship or be reviewed independently
-- Different lanes or owners should deliver different parts
-- Risk isolation matters, such as tracer-bullet, feature-flag, or adapter-first rollout
-- The work keeps widening and no longer has a clean stopping point
-
-Anti-patterns that should usually stay one WU:
-
-- One API endpoint split into backend, tests, and docs WUs
-- One shippable feature split into backend and frontend WUs even though neither stands alone
-- One refactor split into "step 1", "step 2", and "cleanup" WUs with no independent ship point
-
----
-
-## Baseline Heuristics
-
-| Complexity | Files | Tool Calls | Suggested Strategy                                      |
-| ---------- | ----- | ---------- | ------------------------------------------------------- |
-| Simple     | <20   | <50        | Single session                                          |
-| Medium     | 20-50 | 50-100     | Checkpoint and resume                                   |
-| Complex    | 50+   | 100+       | Orchestrate or checkpoint first; split only if the WU is non-atomic |
-| Oversized  | 100+  | 200+       | Re-check cohesion; split only if no exception applies and the work cannot land coherently |
-
-These are guardrails for session strategy, not a license to multiply WUs that still belong together.
-
----
-
-## Context Safety Triggers
-
-Checkpoint and hand off when any of these happen:
-
-- Context usage approaches 50% and is still climbing
-- Tool calls exceed roughly 50 in one session
-- File churn keeps widening without clear closure
-- You have to repeatedly rediscover the same repo rules
-
-If a trigger fires, first ask whether the WU is still atomic. If yes, checkpoint or hand off. If no, split it.
-
----
-
-## Recovery Pattern
-
-```bash
-pnpm mem:checkpoint "state before handoff" --wu WU-XXX
-pnpm wu:brief --id WU-XXX --client codex-cli
-```
-
-Use handoff when the WU is still coherent but the session is getting tired. Split only when the work itself is no longer coherent.
-
----
-
-## Docs-Only Exception
-
-Documentation WUs can tolerate broader file counts when the change pattern is shallow and mechanical, but they still need to stay understandable in one session.
-
-If the docs work starts spilling into CLI, core, or packaging changes, treat it like a normal cross-code WU again.
-
-## Shallow Multi-File Exception
-
-Code WUs may also stay as one WU when the change is mechanical across many files, such as a rename or import rewrite, and each file change stays shallow and uniform.