@lumenflow/cli 3.17.7 → 3.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "3.17.7",
+  "version": "3.18.1",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -185,13 +185,13 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/agent": "3.17.7",
-    "@lumenflow/kernel": "3.17.7",
-    "@lumenflow/initiatives": "3.17.7",
-    "@lumenflow/metrics": "3.17.7",
-    "@lumenflow/memory": "3.17.7",
-    "@lumenflow/core": "3.17.7",
-    "@lumenflow/control-plane-sdk": "3.17.7"
+    "@lumenflow/agent": "3.18.1",
+    "@lumenflow/memory": "3.18.1",
+    "@lumenflow/control-plane-sdk": "3.18.1",
+    "@lumenflow/core": "3.18.1",
+    "@lumenflow/metrics": "3.18.1",
+    "@lumenflow/initiatives": "3.18.1",
+    "@lumenflow/kernel": "3.18.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

package/packs/agent-runtime/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @lumenflow/packs-agent-runtime@3.18.1 build /home/tom/source/hellmai/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
+> tsc
+

package/packs/agent-runtime/README.md

@@ -0,0 +1,147 @@
+# Agent Runtime Pack
+
+The governed `agent-runtime` pack provides a host-driven agent loop with kernel-enforced tool gating.
+
+Current scope:
+
+- `agent:execute-turn` performs one provider-backed model turn and returns the governed turn contract
+- `policy_factory` converts configured intents into kernel-enforced allow, deny, and `approval_required` rules
+- `runGovernedAgentLoop()` shows how CLI, HTTP, or programmatic hosts can keep orchestration outside the pack while still feeding requested tools back through the kernel
+- `startGovernedAgentSession()` and `resumeGovernedAgentSession()` persist linear session state for long-running governed turns
+- `startGovernedAgentWorkflow()` and `resumeGovernedAgentWorkflow()` add pack-owned branch, join, and scheduled-wakeup orchestration inside the same `agent-session`
+- `createHostContextMessages()` lets a host add task and memory context without depending on any other pack's storage internals
+
+## Config shape
+
+```yaml
+agent_runtime:
+  default_model: default
+  models:
+    default:
+      provider: openai_compatible
+      model: demo-model
+      api_key_env: AGENT_RUNTIME_API_KEY
+      base_url_env: AGENT_RUNTIME_BASE_URL
+  intents:
+    scheduling:
+      description: Schedule or reschedule work
+      allow_tools:
+        - calendar:create-event
+      approval_required_tools:
+        - calendar:create-event
+```
+
+## Orchestration boundary
+
+The kernel remains responsible for:
+
+- tool execution
+- policy evaluation
+- scope enforcement
+- evidence receipts for every governed tool call
+
+The pack owns only `agent-session` orchestration concerns:
+
+- persisted session and workflow state under `.agent-runtime/workflow/`
+- branch and join readiness
+- scheduled wakeups for routine-style follow-up nodes
+- workflow-level continuation records that explain why the next governed turn ran
+
+This keeps scheduled and resumed execution inside the existing `agent-session` task model rather than inventing a new execution class.
+
+## Host loop sketch
+
+```ts
+import {
+  createApprovalResolutionMessage,
+  createHostContextMessages,
+  runGovernedAgentLoop,
+  resumeGovernedAgentWorkflow,
+  startGovernedAgentWorkflow,
+} from '@lumenflow/packs-agent-runtime';
+
+const seedMessages = [
+  ...createHostContextMessages({
+    task_summary: 'Reschedule the weekly review.',
+    memory_summary: 'The reviewer prefers mornings.',
+  }),
+  { role: 'user', content: 'Please sort out the next slot.' },
+];
+
+const result = await runGovernedAgentLoop({
+  runtime,
+  executeTurnInput: {
+    session_id: executionContext.session_id,
+    model_profile: 'default',
+    url: 'https://model-provider.invalid/',
+    messages: seedMessages,
+  },
+  createContext: (metadata) => ({
+    ...executionContext,
+    metadata,
+  }),
+});
+
+if (result.kind === 'approval_required') {
+  await runtime.resolveApproval({
+    request_id: result.pending_request_id,
+    approved: true,
+    approved_by: 'operator@example.com',
+  });
+
+  const approvalMessage = createApprovalResolutionMessage({
+    requestId: result.pending_request_id,
+    approved: true,
+    approvedBy: 'operator@example.com',
+    toolName: result.requested_tool.name,
+  });
+
+  // Append approvalMessage to the next execute-turn call and continue the loop.
+}
+```
+
+The pack keeps tool gating in the kernel. Hosts only decide when to start the loop, when to resolve approvals, and what external context to inject into the conversation.
+
+## Workflow sketch
+
+```ts
+const workflow = await startGovernedAgentWorkflow({
+  runtime,
+  storageRoot: workspaceRoot,
+  workflow: {
+    session_id: executionContext.session_id,
+    nodes: [
+      {
+        id: 'collect',
+        execute_turn_input: {
+          session_id: executionContext.session_id,
+          model_profile: 'default',
+          url: 'https://model-provider.invalid/',
+          messages: [{ role: 'user', content: 'Collect the constraints.' }],
+        },
+      },
+      {
+        id: 'follow-up',
+        depends_on: ['collect'],
+        wake_at: '2026-03-13T09:00:00.000Z',
+        execute_turn_input: {
+          session_id: executionContext.session_id,
+          model_profile: 'default',
+          url: 'https://model-provider.invalid/',
+          messages: [{ role: 'user', content: 'Perform the scheduled follow-up.' }],
+        },
+      },
+    ],
+  },
+  createContext: (metadata) => ({ ...executionContext, metadata }),
+});
+
+if (workflow.kind === 'scheduled') {
+  await resumeGovernedAgentWorkflow({
+    runtime,
+    storageRoot: workspaceRoot,
+    sessionId: executionContext.session_id,
+    createContext: (metadata) => ({ ...executionContext, metadata }),
+  });
+}
+```

package/packs/agent-runtime/capability-factory.ts

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import type { PackCapabilityFactory } from '@lumenflow/kernel';
+import { AGENT_RUNTIME_TOOL_NAMES } from './types.js';
+import type { AgentRuntimeModelProfileConfig, AgentRuntimePackConfig } from './types.js';
+
+export const createAgentRuntimeCapabilityFactory: PackCapabilityFactory = async (input) => {
+  if (input.tool.name !== AGENT_RUNTIME_TOOL_NAMES.EXECUTE_TURN) {
+    return {};
+  }
+
+  const packConfig = normalizePackConfig(input.packConfig);
+  if (!packConfig) {
+    return {};
+  }
+
+  const requiredEnv = new Set<string>();
+  const providerHosts = new Set<string>();
+
+  for (const [profileName, profile] of Object.entries(packConfig.models)) {
+    requiredEnv.add(profile.api_key_env);
+    if (profile.base_url_env) {
+      requiredEnv.add(profile.base_url_env);
+    }
+
+    const resolvedBaseUrl = resolveProfileBaseUrl(profileName, profile);
+    if (!resolvedBaseUrl) {
+      continue;
+    }
+    providerHosts.add(toNetworkAllowlistEntry(profileName, resolvedBaseUrl));
+  }
+
+  return {
+    ...(requiredEnv.size > 0 ? { required_env: [...requiredEnv].sort() } : {}),
+    ...(providerHosts.size > 0
+      ? {
+          required_scopes: [
+            {
+              type: 'network' as const,
+              posture: 'allowlist' as const,
+              allowlist_entries: [...providerHosts].sort(),
+            },
+          ],
+        }
+      : {}),
+  };
+};
+
+function normalizePackConfig(value: unknown): AgentRuntimePackConfig | null {
+  if (!isRecord(value) || !isRecord(value.models)) {
+    return null;
+  }
+
+  return value as unknown as AgentRuntimePackConfig;
+}
+
+function resolveProfileBaseUrl(
+  profileName: string,
+  profile: AgentRuntimeModelProfileConfig,
+): string | null {
+  if (typeof profile.base_url === 'string' && profile.base_url.trim().length > 0) {
+    return profile.base_url.trim();
+  }
+
+  if (!profile.base_url_env) {
+    return null;
+  }
+
+  const environmentValue = process.env[profile.base_url_env];
+  if (typeof environmentValue !== 'string' || environmentValue.trim().length === 0) {
+    throw new Error(
+      `agent_runtime.models.${profileName}.base_url_env references "${profile.base_url_env}" but it is not set.`,
+    );
+  }
+
+  return environmentValue.trim();
+}
+
+function toNetworkAllowlistEntry(profileName: string, baseUrl: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl);
+  } catch (error) {
+    throw new Error(
+      `agent_runtime.models.${profileName} must resolve to a valid absolute base URL, got "${baseUrl}".`,
+      { cause: error },
+    );
+  }
+
+  const port =
+    parsed.port || (parsed.protocol === 'https:' ? '443' : parsed.protocol === 'http:' ? '80' : '');
+  if (!port) {
+    throw new Error(
+      `agent_runtime.models.${profileName} uses protocol "${parsed.protocol}" without an explicit port.`,
+    );
+  }
+
+  return `${parsed.hostname}:${port}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/packs/agent-runtime/config.schema.json

@@ -0,0 +1,87 @@
+{
+  "type": "object",
+  "properties": {
+    "default_model": {
+      "type": "string",
+      "minLength": 1
+    },
+    "models": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": ["openai_compatible", "messages_compatible"]
+          },
+          "model": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api_key_env": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          },
+          "base_url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "base_url_env": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          }
+        },
+        "required": ["provider", "model", "api_key_env"],
+        "additionalProperties": false
+      }
+    },
+    "intents": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "minLength": 1
+          },
+          "allow_tools": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "approval_required_tools": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "required": ["description", "allow_tools"],
+        "additionalProperties": false
+      }
+    },
+    "limits": {
+      "type": "object",
+      "properties": {
+        "max_turns_per_session": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_tool_calls_per_session": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_input_bytes": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["default_model", "models"],
+  "additionalProperties": false
+}

package/packs/agent-runtime/constants.ts

@@ -0,0 +1,21 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export const AGENT_RUNTIME_PACK_ID = 'agent-runtime' as const;
+export const AGENT_RUNTIME_PACK_VERSION = '0.1.0' as const;
+export const AGENT_RUNTIME_DOMAIN = AGENT_RUNTIME_PACK_ID;
+export const AGENT_RUNTIME_CONFIG_KEY = 'agent_runtime' as const;
+export const AGENT_RUNTIME_POLICY_ID_PREFIX = `${AGENT_RUNTIME_PACK_ID}.policy` as const;
+export const AGENT_RUNTIME_MANIFEST_FILE_NAME = 'manifest.yaml' as const;
+export const AGENT_RUNTIME_CONFIG_SCHEMA_FILE = 'config.schema.json' as const;
+export const SHA256_ALGORITHM = 'sha256' as const;
+export const UTF8_ENCODING = 'utf8' as const;
+export const AGENT_RUNTIME_STORAGE_PATTERN = '.agent-runtime/**' as const;
+export const AGENT_RUNTIME_API_KEY_ENV = 'AGENT_RUNTIME_API_KEY' as const;
+export const AGENT_RUNTIME_BASE_URL_ENV = 'AGENT_RUNTIME_BASE_URL' as const;
+export const AGENT_RUNTIME_STATIC_PROVIDER_ALLOWLIST = ['model-provider.invalid:443'] as const;
+export const AGENT_RUNTIME_STATIC_PROVIDER_URLS = ['https://model-provider.invalid/'] as const;
+export const AGENT_RUNTIME_AGENT_INTENT_METADATA_KEY = 'agent_intent' as const;
+export const AGENT_RUNTIME_AGENT_TURN_INDEX_METADATA_KEY = 'agent_turn_index' as const;
+export const AGENT_RUNTIME_AGENT_TOOL_CALL_COUNT_METADATA_KEY = 'agent_tool_call_count' as const;
+export const AGENT_RUNTIME_AGENT_WORKFLOW_NODE_ID_METADATA_KEY = 'agent_workflow_node_id' as const;

package/packs/agent-runtime/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+export * from './constants.js';
+export * from './capability-factory.js';
+export * from './manifest.js';
+export * from './orchestration.js';
+export * from './pack-registration.js';
+export * from './policy-factory.js';
+export * from './types.js';
+export * from './tools/index.js';

package/packs/agent-runtime/manifest.ts

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  DomainPackManifestSchema,
+  POLICY_TRIGGERS,
+  type DomainPackManifest,
+} from '@lumenflow/kernel';
+import {
+  AGENT_RUNTIME_API_KEY_ENV,
+  AGENT_RUNTIME_BASE_URL_ENV,
+  AGENT_RUNTIME_CONFIG_KEY,
+  AGENT_RUNTIME_CONFIG_SCHEMA_FILE,
+  AGENT_RUNTIME_PACK_ID,
+  AGENT_RUNTIME_PACK_VERSION,
+  AGENT_RUNTIME_POLICY_ID_PREFIX,
+  AGENT_RUNTIME_STATIC_PROVIDER_ALLOWLIST,
+  AGENT_RUNTIME_STATIC_PROVIDER_URLS,
+  AGENT_RUNTIME_STORAGE_PATTERN,
+} from './constants.js';
+import {
+  AGENT_RUNTIME_PROVIDER_KINDS,
+  AGENT_RUNTIME_TOOL_NAMES,
+  AGENT_RUNTIME_TURN_STATUSES,
+  type AgentRuntimeToolName,
+} from './types.js';
+
+const EXECUTE_TURN_TOOL_ENTRY = 'tool-impl/agent-turn-tools.ts#agentExecuteTurnTool';
+const CAPABILITY_FACTORY_ENTRY = 'capability-factory.ts#createAgentRuntimeCapabilityFactory';
+const POLICY_FACTORY_ENTRY = 'policy-factory.ts#createAgentRuntimePolicyFactory';
+
+const EXECUTE_TURN_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    session_id: { type: 'string', minLength: 1 },
+    model_profile: { type: 'string', minLength: 1 },
+    url: {
+      type: 'string',
+      enum: [...AGENT_RUNTIME_STATIC_PROVIDER_URLS],
+    },
+    stream: {
+      type: 'boolean',
+    },
+    messages: {
+      type: 'array',
+      minItems: 1,
+      items: {
+        type: 'object',
+        properties: {
+          role: {
+            type: 'string',
+            enum: ['system', 'user', 'assistant', 'tool'],
+          },
+          content: { type: 'string' },
+          tool_name: { type: 'string' },
+          tool_call_id: { type: 'string' },
+        },
+        required: ['role', 'content'],
+        additionalProperties: false,
+      },
+    },
+    tool_catalog: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', minLength: 1 },
+          description: { type: 'string', minLength: 1 },
+          input_schema: {
+            type: 'object',
+            additionalProperties: true,
+          },
+        },
+        required: ['name', 'description'],
+        additionalProperties: false,
+      },
+    },
+    intent_catalog: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', minLength: 1 },
+          description: { type: 'string', minLength: 1 },
+        },
+        required: ['id', 'description'],
+        additionalProperties: false,
+      },
+    },
+    limits: {
+      type: 'object',
+      properties: {
+        max_turns_per_session: { type: 'integer', minimum: 1 },
+        max_tool_calls_per_session: { type: 'integer', minimum: 1 },
+        max_input_bytes: { type: 'integer', minimum: 1 },
+      },
+      additionalProperties: false,
+    },
+  },
+  required: ['session_id', 'model_profile', 'url', 'messages'],
+  additionalProperties: false,
+};
+
+const EXECUTE_TURN_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    status: {
+      type: 'string',
+      enum: Object.values(AGENT_RUNTIME_TURN_STATUSES),
+    },
+    intent: { type: 'string', minLength: 1 },
+    assistant_message: { type: 'string' },
+    requested_tool: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', minLength: 1 },
+        input: {
+          type: 'object',
+          additionalProperties: true,
+        },
+      },
+      required: ['name', 'input'],
+      additionalProperties: false,
+    },
+    provider: {
+      type: 'object',
+      properties: {
+        kind: {
+          type: 'string',
+          enum: Object.values(AGENT_RUNTIME_PROVIDER_KINDS),
+        },
+        model: { type: 'string', minLength: 1 },
+      },
+      required: ['kind', 'model'],
+      additionalProperties: false,
+    },
+    usage: {
+      type: 'object',
+      properties: {
+        input_tokens: { type: 'integer', minimum: 0 },
+        output_tokens: { type: 'integer', minimum: 0 },
+        total_tokens: { type: 'integer', minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+    finish_reason: { type: 'string', minLength: 1 },
+  },
+  required: ['status', 'intent', 'assistant_message', 'provider', 'finish_reason'],
+  additionalProperties: false,
+};
+
+const MANIFEST_TOOL_DEFINITIONS = [
+  {
+    name: AGENT_RUNTIME_TOOL_NAMES.EXECUTE_TURN,
+    entry: EXECUTE_TURN_TOOL_ENTRY,
+    permission: 'write',
+    required_scopes: [
+      { type: 'path', pattern: AGENT_RUNTIME_STORAGE_PATTERN, access: 'read' },
+      { type: 'path', pattern: AGENT_RUNTIME_STORAGE_PATTERN, access: 'write' },
+      {
+        type: 'network',
+        posture: 'allowlist',
+        allowlist_entries: [...AGENT_RUNTIME_STATIC_PROVIDER_ALLOWLIST],
+      },
+    ],
+    required_env: [AGENT_RUNTIME_API_KEY_ENV, AGENT_RUNTIME_BASE_URL_ENV],
+    input_schema: EXECUTE_TURN_INPUT_SCHEMA,
+    output_schema: EXECUTE_TURN_OUTPUT_SCHEMA,
+  },
+] as const;
+
+export const AGENT_RUNTIME_MANIFEST = DomainPackManifestSchema.parse({
+  id: AGENT_RUNTIME_PACK_ID,
+  version: AGENT_RUNTIME_PACK_VERSION,
+  config_key: AGENT_RUNTIME_CONFIG_KEY,
+  config_schema: AGENT_RUNTIME_CONFIG_SCHEMA_FILE,
+  capability_factory: CAPABILITY_FACTORY_ENTRY,
+  policy_factory: POLICY_FACTORY_ENTRY,
+  task_types: ['agent-session'],
+  tools: MANIFEST_TOOL_DEFINITIONS,
+  policies: [
+    {
+      id: `${AGENT_RUNTIME_POLICY_ID_PREFIX}.default`,
+      trigger: POLICY_TRIGGERS.ON_TOOL_REQUEST,
+      decision: 'allow',
+      reason: 'Pack baseline allow; dynamic intent gating is applied by the pack policy factory.',
+    },
+  ],
+  evidence_types: ['agent-runtime.turn', 'agent-runtime.provider-call'],
+  state_aliases: {
+    paused: 'waiting',
+  },
+  lane_templates: [],
+}) satisfies DomainPackManifest;
+
+export type AgentRuntimePackManifest = typeof AGENT_RUNTIME_MANIFEST;
+export type AgentRuntimeManifestTool = AgentRuntimePackManifest['tools'][number];
+
+export const AGENT_RUNTIME_MANIFEST_TOOL_NAMES = AGENT_RUNTIME_MANIFEST.tools.map(
+  (tool) => tool.name,
+) as readonly AgentRuntimeToolName[];
+
+export function getAgentRuntimeManifestToolByName(
+  name: string,
+): AgentRuntimeManifestTool | undefined {
+  return AGENT_RUNTIME_MANIFEST.tools.find((tool) => tool.name === name);
+}