@lumenflow/cli 3.17.7 → 3.18.0

package/packs/agent-runtime/pack-registration.ts

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_RUNTIME_MANIFEST } from './manifest.js';
+import { AGENT_RUNTIME_MANIFEST_FILE_NAME, SHA256_ALGORITHM, UTF8_ENCODING } from './constants.js';
+import type { AgentRuntimePackManifest } from './manifest.js';
+
+const NULL_BYTE_BUFFER = Buffer.from([0]);
+const DEFAULT_EXCLUSIONS = ['node_modules/', '.git/', 'dist/', '.DS_Store'] as const;
+
+function getDefaultPackRoot(): string {
+  return path.dirname(fileURLToPath(import.meta.url));
+}
+
+function normalizeRelativePath(root: string, absolutePath: string): string {
+  return path.relative(root, absolutePath).split(path.sep).join('/');
+}
+
+function shouldExclude(relativePath: string, exclusions: readonly string[]): boolean {
+  return exclusions.some((excluded) => {
+    if (excluded.endsWith('/')) {
+      return relativePath.startsWith(excluded);
+    }
+    return relativePath === excluded || relativePath.endsWith(`/${excluded}`);
+  });
+}
+
+async function collectFilesRecursive(root: string, directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const sortedEntries = [...entries].sort((left, right) => left.name.localeCompare(right.name));
+  const files: string[] = [];
+
+  for (const entry of sortedEntries) {
+    const absolutePath = path.join(directory, entry.name);
+    const relativePath = normalizeRelativePath(root, absolutePath);
+    if (entry.isDirectory()) {
+      files.push(...(await collectFilesRecursive(root, absolutePath)));
+      continue;
+    }
+    files.push(relativePath);
+  }
+
+  return files;
+}
+
+async function listPackFiles(packRoot: string, exclusions: readonly string[]): Promise<string[]> {
+  const absoluteRoot = path.resolve(packRoot);
+  const allFiles = await collectFilesRecursive(absoluteRoot, absoluteRoot);
+  return allFiles.filter((relativePath) => !shouldExclude(relativePath, exclusions)).sort();
+}
+
+export async function computeAgentRuntimePackIntegrity(
+  packRoot = getDefaultPackRoot(),
+  exclusions: readonly string[] = DEFAULT_EXCLUSIONS,
+): Promise<`sha256:${string}`> {
+  const absoluteRoot = path.resolve(packRoot);
+  const files = await listPackFiles(absoluteRoot, exclusions);
+  const digestChunks: Buffer[] = [];
+
+  for (const relativePath of files) {
+    const fileContents = await readFile(path.join(absoluteRoot, relativePath));
+    const fileHash = createHash(SHA256_ALGORITHM).update(fileContents).digest('hex');
+    digestChunks.push(Buffer.from(relativePath, UTF8_ENCODING));
+    digestChunks.push(NULL_BYTE_BUFFER);
+    digestChunks.push(Buffer.from(fileHash, UTF8_ENCODING));
+    digestChunks.push(NULL_BYTE_BUFFER);
+  }
+
+  const combinedDigest = createHash(SHA256_ALGORITHM)
+    .update(digestChunks.length === 0 ? Buffer.alloc(0) : Buffer.concat(digestChunks))
+    .digest('hex');
+
+  return `sha256:${combinedDigest}`;
+}
+
+export async function loadAgentRuntimeManifest(
+  packRoot = getDefaultPackRoot(),
+): Promise<AgentRuntimePackManifest> {
+  const manifestPath = path.join(path.resolve(packRoot), AGENT_RUNTIME_MANIFEST_FILE_NAME);
+  await readFile(manifestPath, UTF8_ENCODING);
+  return structuredClone(AGENT_RUNTIME_MANIFEST);
+}
+
+export interface RegisteredAgentRuntimePack {
+  manifest: AgentRuntimePackManifest;
+  packRoot: string;
+  manifestPath: string;
+  integrity: `sha256:${string}`;
+}
+
+export async function registerAgentRuntimePack(options?: {
+  packRoot?: string;
+  exclusions?: readonly string[];
+}): Promise<RegisteredAgentRuntimePack> {
+  const packRoot = path.resolve(options?.packRoot ?? getDefaultPackRoot());
+  const exclusions = options?.exclusions ?? DEFAULT_EXCLUSIONS;
+  const manifest = await loadAgentRuntimeManifest(packRoot);
+  const integrity = await computeAgentRuntimePackIntegrity(packRoot, exclusions);
+
+  return {
+    manifest,
+    packRoot,
+    manifestPath: path.join(packRoot, AGENT_RUNTIME_MANIFEST_FILE_NAME),
+    integrity,
+  };
+}

package/packs/agent-runtime/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@lumenflow/packs-agent-runtime",
+  "version": "3.18.0",
+  "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
+  "keywords": [
+    "lumenflow",
+    "pack",
+    "agent-runtime",
+    "orchestration",
+    "policy"
+  ],
+  "homepage": "https://github.com/hellmai/lumenflow-dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hellmai/lumenflow-dev.git",
+    "directory": "packages/@lumenflow/packs/agent-runtime"
+  },
+  "license": "AGPL-3.0-only",
+  "author": {
+    "name": "HellmAI",
+    "url": "https://hellm.ai"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./tools": "./dist/tools/index.js",
+    "./tool-impl": "./dist/tool-impl/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "manifest.yaml",
+    "config.schema.json",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tgz",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lumenflow/kernel": "workspace:^"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,165 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { POLICY_TRIGGERS, type PackPolicyFactory, type PolicyRule } from '@lumenflow/kernel';
+import {
+  AGENT_RUNTIME_AGENT_INTENT_METADATA_KEY,
+  AGENT_RUNTIME_POLICY_ID_PREFIX,
+} from './constants.js';
+import type { AgentRuntimeIntentConfig, AgentRuntimePackConfig } from './types.js';
+
+interface NormalizedIntentRule {
+  allowTools: Set<string>;
+  approvalRequiredTools: Set<string>;
+}
+
+type NormalizedIntentRuleMap = Map<string, NormalizedIntentRule>;
+
+export const createAgentRuntimePolicyFactory: PackPolicyFactory = async (input) => {
+  const intentRules = normalizeIntentRules(input.packConfig);
+  if (intentRules.size === 0) {
+    return [];
+  }
+
+  const rules: PolicyRule[] = [
+    {
+      id: `${AGENT_RUNTIME_POLICY_ID_PREFIX}.intent-approval`,
+      trigger: POLICY_TRIGGERS.ON_TOOL_REQUEST,
+      decision: 'approval_required',
+      reason: 'The classified agent intent requires approval before this tool may run.',
+      when: (context) => matchesApprovalRequiredIntent(context, intentRules),
+    },
+    {
+      id: `${AGENT_RUNTIME_POLICY_ID_PREFIX}.intent-deny`,
+      trigger: POLICY_TRIGGERS.ON_TOOL_REQUEST,
+      decision: 'deny',
+      reason: 'The classified agent intent does not permit this tool.',
+      when: (context) => matchesDeniedIntent(context, intentRules),
+    },
+  ];
+
+  return rules;
+};
+
+function normalizeIntentRules(packConfig: unknown): NormalizedIntentRuleMap {
+  const config = asRecord(packConfig);
+  const intents = asRecord(config?.intents);
+  if (!intents) {
+    return new Map();
+  }
+
+  const normalized = new Map<string, NormalizedIntentRule>();
+  for (const [intentId, candidate] of Object.entries(intents)) {
+    const parsed = normalizeIntentConfig(intentId, candidate);
+    normalized.set(intentId, parsed);
+  }
+  return normalized;
+}
+
+function normalizeIntentConfig(intentId: string, value: unknown): NormalizedIntentRule {
+  const config = asRecord(value);
+  if (!config) {
+    throw new Error(`agent_runtime.intents.${intentId} must be an object.`);
+  }
+
+  const allowTools = normalizeToolList(
+    config.allow_tools,
+    `agent_runtime.intents.${intentId}.allow_tools`,
+  );
+  const approvalRequiredTools = normalizeToolList(
+    config.approval_required_tools,
+    `agent_runtime.intents.${intentId}.approval_required_tools`,
+    true,
+  );
+
+  return {
+    allowTools: new Set([...allowTools, ...approvalRequiredTools]),
+    approvalRequiredTools: new Set(approvalRequiredTools),
+  };
+}
+
+function normalizeToolList(value: unknown, fieldName: string, optional = false): string[] {
+  if (value === undefined && optional) {
+    return [];
+  }
+  if (
+    !Array.isArray(value) ||
+    value.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)
+  ) {
+    throw new Error(`${fieldName} must be an array of non-empty strings.`);
+  }
+
+  return value.map((entry) => entry.trim());
+}
+
+function matchesApprovalRequiredIntent(
+  context: Parameters<NonNullable<PolicyRule['when']>>[0],
+  intentRules: NormalizedIntentRuleMap,
+): boolean {
+  const toolName = readCandidateToolName(context);
+  if (!toolName) {
+    return false;
+  }
+
+  const intentRule = resolveIntentRule(context, intentRules);
+  return intentRule?.approvalRequiredTools.has(toolName) ?? false;
+}
+
+function matchesDeniedIntent(
+  context: Parameters<NonNullable<PolicyRule['when']>>[0],
+  intentRules: NormalizedIntentRuleMap,
+): boolean {
+  const toolName = readCandidateToolName(context);
+  if (!toolName) {
+    return false;
+  }
+
+  const intentRule = resolveIntentRule(context, intentRules);
+  if (!intentRule) {
+    return false;
+  }
+
+  return !intentRule.allowTools.has(toolName);
+}
+
+function resolveIntentRule(
+  context: Parameters<NonNullable<PolicyRule['when']>>[0],
+  intentRules: NormalizedIntentRuleMap,
+): NormalizedIntentRule | null {
+  const intent = readAgentIntent(context);
+  if (!intent) {
+    return null;
+  }
+
+  return (
+    intentRules.get(intent) ?? {
+      allowTools: new Set<string>(),
+      approvalRequiredTools: new Set<string>(),
+    }
+  );
+}
+
+function readAgentIntent(context: Parameters<NonNullable<PolicyRule['when']>>[0]): string | null {
+  const executionMetadata = asRecord(context.execution_metadata);
+  const candidate = executionMetadata?.[AGENT_RUNTIME_AGENT_INTENT_METADATA_KEY];
+  return typeof candidate === 'string' && candidate.trim().length > 0 ? candidate.trim() : null;
+}
+
+function readCandidateToolName(
+  context: Parameters<NonNullable<PolicyRule['when']>>[0],
+): string | null {
+  if (typeof context.tool_name !== 'string' || context.tool_name.trim().length === 0) {
+    return null;
+  }
+
+  const toolName = context.tool_name.trim();
+  return toolName === 'agent:execute-turn' ? null : toolName;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export type { AgentRuntimeIntentConfig, AgentRuntimePackConfig };