fuli-context 0.7.4-beta.3 → 0.7.6

package/src/adaptive-runtime/lease-client.js

@@ -0,0 +1,335 @@
+import { dirname } from 'node:path';
+
+import { resolveSetupPaths } from '../setup/paths.js';
+import { readJsonFile } from '../storage/json-file.js';
+import { readAdaptiveRuntimeSettings } from './settings.js';
+
+export function createRuntimeLeaseClient({
+  runtimeConfigPath,
+  paths = resolveSetupPaths({ dataDir: dirname(runtimeConfigPath) }),
+  readJson = readJsonFile,
+  readSettings = readAdaptiveRuntimeSettings,
+  fetchImpl = globalThis.fetch,
+  setHeartbeat = setInterval,
+  clearHeartbeat = clearInterval
+}) {
+  const leases = new Map();
+
+  async function withGraphLease(owner, operation) {
+    return withLease({ kind: 'graph', owner }, operation);
+  }
+
+  async function withExecutorLease(executorId, owner, operation) {
+    return withLease({ kind: 'executor', executorId, owner }, operation);
+  }
+
+  async function acquireGraphLease(owner) {
+    return acquireLease({ kind: 'graph', owner });
+  }
+
+  async function acquireExecutorLease(executorId, owner) {
+    return acquireLease({ kind: 'executor', executorId, owner });
+  }
+
+  async function acquireLease(input) {
+    const settings = readSettings(paths.adaptiveRuntimeSettingsPath);
+    if (!settings.enabled) return disabledLease();
+
+    const consoleUrl = runtimeConsoleUrl(readJson(paths.graphRuntimeStatePath, null));
+    const lease = await requestJson(`${consoleUrl}/api/system/runtime/leases`, {
+      method: 'POST',
+      body: input,
+      timeoutMs: 180_000,
+      fetchImpl
+    });
+    const handle = publicLease(lease);
+    if (!handle.enabled) return handle;
+
+    const entry = {
+      handle,
+      consoleUrl,
+      heartbeat: null,
+      heartbeatActive: false,
+      refreshPromise: null,
+      released: false
+    };
+    leases.set(handle.leaseId, entry);
+    try {
+      startHeartbeat(entry, settings);
+      return { ...entry.handle };
+    } catch (error) {
+      removeLease(entry);
+      await releaseRemote(entry).catch(() => {});
+      throw error;
+    }
+  }
+
+  async function refreshLease(reference) {
+    const entry = findLease(reference);
+    if (!entry) return { ...leaseReference(reference), refreshed: false };
+    return refreshEntry(entry);
+  }
+
+  async function releaseLease(reference) {
+    const entry = findLease(reference);
+    if (!entry) return { ...leaseReference(reference), released: false };
+
+    const pendingRefresh = entry.refreshPromise;
+    removeLease(entry);
+    if (pendingRefresh) await pendingRefresh.catch(() => {});
+
+    try {
+      const result = await releaseRemote(entry);
+      return {
+        ...entry.handle,
+        released: result?.released !== false
+      };
+    } catch {
+      return { ...entry.handle, released: false };
+    }
+  }
+
+  async function withLease(input, operation) {
+    if (typeof operation !== 'function') throw new TypeError('Runtime operation is required');
+    const handle = await acquireLease(input);
+    try {
+      return await operation();
+    } finally {
+      await releaseLease(handle);
+    }
+  }
+
+  async function close() {
+    const handles = [...leases.values()].map(({ handle }) => ({ ...handle }));
+    await Promise.allSettled(handles.map((handle) => releaseLease(handle)));
+  }
+
+  function startHeartbeat(entry, settings) {
+    if (entry.heartbeatActive || entry.released) return;
+    const ttlSeconds = Number(settings.leaseTtlSeconds);
+    const heartbeatMs = Number.isFinite(ttlSeconds) && ttlSeconds > 0
+      ? Math.max(1000, Math.floor(ttlSeconds * 1000 / 3))
+      : 1000;
+    let heartbeat;
+    try {
+      heartbeat = setHeartbeat(() => {
+        if (!entry.heartbeatActive || entry.released) return;
+        void refreshEntry(entry).catch(() => {});
+      }, heartbeatMs);
+      entry.heartbeat = heartbeat;
+      entry.heartbeatActive = true;
+      heartbeat?.unref?.();
+    } catch (error) {
+      entry.heartbeat = null;
+      entry.heartbeatActive = false;
+      if (heartbeat !== undefined) {
+        try {
+          clearHeartbeat(heartbeat);
+        } catch {
+          // A failed cleanup must not hide the heartbeat setup error.
+        }
+      }
+      throw error;
+    }
+  }
+
+  function stopHeartbeat(entry) {
+    if (!entry.heartbeatActive && entry.heartbeat === null) return;
+    const heartbeat = entry.heartbeat;
+    entry.heartbeat = null;
+    entry.heartbeatActive = false;
+    if (heartbeat !== undefined && heartbeat !== null) {
+      try {
+        clearHeartbeat(heartbeat);
+      } catch {
+        // Releasing a lease remains best effort even if timer cleanup fails.
+      }
+    }
+  }
+
+  function removeLease(entry) {
+    if (entry.released) return;
+    entry.released = true;
+    stopHeartbeat(entry);
+    if (leases.get(entry.handle.leaseId) === entry) leases.delete(entry.handle.leaseId);
+  }
+
+  async function refreshEntry(entry) {
+    if (entry.released || leases.get(entry.handle.leaseId) !== entry) {
+      return { ...entry.handle, refreshed: false };
+    }
+    if (entry.refreshPromise) return entry.refreshPromise;
+
+    const promise = (async () => {
+      try {
+        const result = await requestJson(
+          `${entry.consoleUrl}/api/system/runtime/leases/${encodeURIComponent(entry.handle.leaseId)}`,
+          { method: 'PATCH', body: {}, timeoutMs: 10_000, fetchImpl }
+        );
+        if (entry.released || leases.get(entry.handle.leaseId) !== entry) {
+          return { ...entry.handle, refreshed: false };
+        }
+        const refreshed = result?.refreshed !== false;
+        const nextHandle = publicLease({ ...entry.handle, ...result });
+        if (nextHandle.enabled) entry.handle = nextHandle;
+        if (!refreshed) {
+          removeLease(entry);
+        } else if (!entry.heartbeatActive) {
+          try {
+            startHeartbeat(entry, readSettings(paths.adaptiveRuntimeSettingsPath));
+          } catch {
+            // The successful manual refresh still extends the remote lease.
+            // The next explicit refresh can retry heartbeat setup.
+          }
+        }
+        return { ...entry.handle, refreshed };
+      } catch (error) {
+        stopHeartbeat(entry);
+        throw error;
+      }
+    })();
+    entry.refreshPromise = promise;
+    try {
+      return await promise;
+    } finally {
+      if (entry.refreshPromise === promise) entry.refreshPromise = null;
+    }
+  }
+
+  function findLease(reference) {
+    const leaseId = leaseReference(reference).leaseId;
+    return leaseId ? leases.get(leaseId) ?? null : null;
+  }
+
+  async function releaseRemote(entry) {
+    return requestJson(
+      `${entry.consoleUrl}/api/system/runtime/leases/${encodeURIComponent(entry.handle.leaseId)}`,
+      { method: 'DELETE', timeoutMs: 10_000, fetchImpl }
+    );
+  }
+
+  return {
+    acquireGraphLease,
+    acquireExecutorLease,
+    refreshLease,
+    releaseLease,
+    withGraphLease,
+    withExecutorLease,
+    close
+  };
+}
+
+export function bindRuntimeLeaseAgentTools(application, leaseClient) {
+  if (!application || typeof application !== 'object') {
+    throw new TypeError('Runtime lease application is required');
+  }
+  for (const method of [
+    'acquireGraphLease',
+    'acquireExecutorLease',
+    'refreshLease',
+    'releaseLease'
+  ]) {
+    if (typeof leaseClient?.[method] !== 'function') {
+      throw new TypeError(`Runtime lease client is missing ${method}`);
+    }
+  }
+  application.acquireRuntimeLease = ({ kind, executorId = null, owner }) => {
+    if (kind === 'graph') {
+      if (executorId !== null && executorId !== undefined) {
+        throw new TypeError('Graph runtime lease cannot select an executor');
+      }
+      return leaseClient.acquireGraphLease(owner);
+    }
+    if (kind === 'executor') {
+      if (typeof executorId !== 'string' || !executorId.trim()) {
+        throw new TypeError('Executor runtime lease requires executorId');
+      }
+      return leaseClient.acquireExecutorLease(executorId, owner);
+    }
+    throw new TypeError('Runtime lease kind must be graph or executor');
+  };
+  application.refreshRuntimeLease = ({ leaseId }) =>
+    leaseClient.refreshLease(leaseId);
+  application.releaseRuntimeLease = ({ leaseId }) =>
+    leaseClient.releaseLease(leaseId);
+  return application;
+}
+
+function disabledLease() {
+  return { enabled: false, leaseId: null };
+}
+
+function leaseReference(value) {
+  if (typeof value === 'string' && value) return { enabled: true, leaseId: value };
+  return publicLease(value);
+}
+
+function publicLease(value, fallback = null) {
+  const source = {
+    ...(fallback && typeof fallback === 'object' ? fallback : {}),
+    ...(value && typeof value === 'object' ? value : {})
+  };
+  if (source.enabled !== true || typeof source.leaseId !== 'string' || !source.leaseId) {
+    return disabledLease();
+  }
+  const handle = {
+    enabled: true,
+    leaseId: source.leaseId
+  };
+  if (typeof source.kind === 'string') handle.kind = source.kind;
+  if (source.executorId === null || typeof source.executorId === 'string') {
+    handle.executorId = source.executorId;
+  }
+  for (const key of ['acquiredAt', 'expiresAt']) {
+    if (source[key] === null || typeof source[key] === 'string') handle[key] = source[key];
+  }
+  return handle;
+}
+
+function runtimeConsoleUrl(state) {
+  if (!state || typeof state.url !== 'string') {
+    throw new Error('Adaptive memory needs the Fuli management UI; run `fuli start` first');
+  }
+  let url;
+  try {
+    url = new URL(state.url);
+  } catch {
+    throw new Error('The recorded Fuli management UI address is invalid');
+  }
+  if (
+    url.protocol !== 'http:' ||
+    !['127.0.0.1', 'localhost', '::1', '[::1]'].includes(url.hostname) ||
+    url.username || url.password ||
+    (url.pathname !== '/' && url.pathname !== '') || url.search || url.hash
+  ) {
+    throw new Error('Adaptive memory only accepts the recorded loopback Fuli management UI');
+  }
+  return url.origin;
+}
+
+async function requestJson(url, {
+  method,
+  body,
+  timeoutMs,
+  fetchImpl
+}) {
+  const response = await fetchImpl(url, {
+    method,
+    headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  if (!response.ok) {
+    let detail = null;
+    try {
+      const value = await response.json();
+      detail = typeof value?.message === 'string'
+        ? value.message
+        : typeof value?.error === 'string' ? value.error : null;
+    } catch {
+      // The status is enough when the local coordinator did not return JSON.
+    }
+    throw new Error(detail ?? `Adaptive runtime request failed (${response.status})`);
+  }
+  return response.json();
+}

package/src/adaptive-runtime/runtime-broker.js

@@ -0,0 +1,318 @@
+import { randomUUID } from 'node:crypto';
+
+import { createExecutorPool } from './executor-pool.js';
+import { createGraphServices } from './graph-services.js';
+import { normalizeAdaptiveRuntimeSettings } from './settings.js';
+import {
+  initialAdaptiveRuntimeState,
+  readAdaptiveRuntimeState,
+  writeAdaptiveRuntimeState
+} from './state.js';
+
+export function createAdaptiveRuntimeBroker({
+  paths,
+  settings,
+  services = createGraphServices({ paths }),
+  executorAdapters = new Map(),
+  readState = readAdaptiveRuntimeState,
+  writeState = writeAdaptiveRuntimeState,
+  now = () => Date.now(),
+  setTimer = setTimeout,
+  clearTimer = clearTimeout
+}) {
+  const configured = normalizeAdaptiveRuntimeSettings(settings);
+  const leases = new Map();
+  const executorPool = createExecutorPool({
+    adapters: executorAdapters,
+    idleMs: configured.executorIdleSeconds * 1000,
+    setTimer,
+    clearTimer
+  });
+  let state = initializeState();
+  let providerTimer = null;
+  let databaseTimer = null;
+  let transition = Promise.resolve();
+  let closed = false;
+
+  scheduleIdle();
+
+  async function acquire(input = {}) {
+    if (!configured.enabled) return disabledLease();
+    if (closed) throw new Error('Adaptive runtime coordinator is closed');
+    const kind = input.kind ?? 'graph';
+    if (!['graph', 'executor'].includes(kind)) {
+      throw new TypeError('Runtime lease kind must be graph or executor');
+    }
+    const executorId = kind === 'executor' ? requiredExecutorId(input.executorId) : null;
+    const leaseId = randomUUID();
+    const lease = {
+      leaseId,
+      kind,
+      executorId,
+      owner: ownerText(input.owner),
+      acquiredAt: isoNow(),
+      expiresAt: null,
+      timer: null
+    };
+    leases.set(leaseId, lease);
+    clearIdleTimers();
+    armExpiry(lease);
+    try {
+      await exclusive(async () => {
+        await ensureAwake();
+        if (executorId) await executorPool.acquire(executorId, leaseId);
+      });
+      return publicLease(lease);
+    } catch (error) {
+      leases.delete(leaseId);
+      if (lease.timer) clearTimer(lease.timer);
+      if (executorId) executorPool.release(executorId, leaseId);
+      touch();
+      scheduleIdle();
+      throw error;
+    }
+  }
+
+  function refresh(leaseId) {
+    const lease = leases.get(validLeaseId(leaseId));
+    if (!lease) return { refreshed: false };
+    armExpiry(lease);
+    return { refreshed: true, ...publicLease(lease) };
+  }
+
+  function release(leaseId) {
+    const normalized = validLeaseId(leaseId);
+    const lease = leases.get(normalized);
+    if (!lease) return { released: false };
+    leases.delete(normalized);
+    if (lease.timer) clearTimer(lease.timer);
+    if (lease.executorId) executorPool.release(lease.executorId, normalized);
+    touch();
+    scheduleIdle();
+    return { released: true };
+  }
+
+  async function withLease(input, operation) {
+    if (typeof operation !== 'function') throw new TypeError('Runtime operation is required');
+    if (!configured.enabled) return operation();
+    const lease = await acquire(input);
+    const stopHeartbeat = scheduleHeartbeat(lease.leaseId);
+    try {
+      return await operation();
+    } finally {
+      stopHeartbeat();
+      release(lease.leaseId);
+    }
+  }
+
+  function status() {
+    const lastActivityMs = Date.parse(state.lastActivityAt);
+    return {
+      enabled: configured.enabled,
+      stage: state.stage,
+      activeLeaseCount: leases.size,
+      lastActivityAt: state.lastActivityAt,
+      updatedAt: state.updatedAt,
+      nextProviderSleepAt: nextSleepAt(lastActivityMs, configured.providerIdleSeconds, [
+        'awake', 'degraded'
+      ]),
+      nextDatabaseSleepAt: nextSleepAt(lastActivityMs, configured.databaseIdleSeconds, [
+        'awake', 'provider-sleeping', 'degraded'
+      ]),
+      lastError: state.lastError,
+      settings: configured,
+      executors: executorPool.status()
+    };
+  }
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    clearIdleTimers();
+    for (const lease of leases.values()) {
+      if (lease.timer) clearTimer(lease.timer);
+    }
+    leases.clear();
+    executorPool.close();
+  }
+
+  async function ensureAwake() {
+    const alreadyReady = state.stage === 'awake' &&
+      (typeof services.ready !== 'function' || await services.ready());
+    if (alreadyReady) return;
+    persist('waking');
+    try {
+      await services.start();
+      persist('awake');
+    } catch (error) {
+      persist('degraded', errorMessage(error));
+      throw error;
+    }
+  }
+
+  function scheduleIdle() {
+    clearIdleTimers();
+    if (!configured.enabled || closed || leases.size > 0) return;
+    const lastActivityMs = Date.parse(state.lastActivityAt);
+    if (['awake', 'degraded'].includes(state.stage)) {
+      providerTimer = scheduleAt(
+        lastActivityMs + configured.providerIdleSeconds * 1000,
+        sleepProvider
+      );
+    }
+    if (['awake', 'provider-sleeping', 'degraded'].includes(state.stage)) {
+      databaseTimer = scheduleAt(
+        lastActivityMs + configured.databaseIdleSeconds * 1000,
+        sleepDatabase
+      );
+    }
+  }
+
+  function scheduleAt(timestamp, operation) {
+    const timer = setTimer(() => {
+      void exclusive(async () => {
+        if (closed || leases.size > 0) return;
+        await operation();
+      }).catch((error) => {
+        persist('degraded', errorMessage(error));
+        scheduleIdle();
+      });
+    }, Math.max(0, timestamp - now()));
+    timer?.unref?.();
+    return timer;
+  }
+
+  async function sleepProvider() {
+    if (!['awake', 'degraded'].includes(state.stage)) return;
+    await services.stopProviders();
+    persist('provider-sleeping');
+    scheduleIdle();
+  }
+
+  async function sleepDatabase() {
+    if (state.stage === 'sleeping') return;
+    await services.stopDatabases();
+    persist('sleeping');
+    clearIdleTimers();
+  }
+
+  function exclusive(operation) {
+    const result = transition.then(operation, operation);
+    transition = result.catch(() => {});
+    return result;
+  }
+
+  function scheduleHeartbeat(leaseId) {
+    const delayMs = Math.max(1000, Math.floor(configured.leaseTtlSeconds * 1000 / 3));
+    const token = { cancelled: false, timer: null };
+    const beat = () => {
+      if (token.cancelled) return;
+      if (!refresh(leaseId).refreshed) return;
+      token.timer = setTimer(beat, delayMs);
+      token.timer?.unref?.();
+    };
+    token.timer = setTimer(beat, delayMs);
+    token.timer?.unref?.();
+    return () => {
+      token.cancelled = true;
+      if (token.timer) clearTimer(token.timer);
+      token.timer = null;
+    };
+  }
+
+  function armExpiry(lease) {
+    if (lease.timer) clearTimer(lease.timer);
+    const expiresAtMs = now() + configured.leaseTtlSeconds * 1000;
+    lease.expiresAt = new Date(expiresAtMs).toISOString();
+    lease.timer = setTimer(() => release(lease.leaseId), configured.leaseTtlSeconds * 1000);
+    lease.timer?.unref?.();
+  }
+
+  function initializeState() {
+    const saved = readState(paths.adaptiveRuntimeStatePath);
+    const initial = saved ?? initialAdaptiveRuntimeState({
+      enabled: configured.enabled,
+      now: new Date(now())
+    });
+    if (!configured.enabled) return persistValue({ ...initial, stage: 'always-on' });
+    if (initial.stage === 'always-on' || initial.stage === 'waking') {
+      return persistValue({ ...initial, stage: 'awake' });
+    }
+    return initial;
+  }
+
+  function touch() {
+    state = persistValue({ ...state, lastActivityAt: isoNow(), lastError: null });
+  }
+
+  function persist(stage, lastError = null) {
+    state = persistValue({ ...state, stage, lastError });
+  }
+
+  function persistValue(value) {
+    const next = {
+      ...value,
+      version: 1,
+      updatedAt: isoNow()
+    };
+    return writeState(paths.adaptiveRuntimeStatePath, next) ?? next;
+  }
+
+  function nextSleepAt(lastActivityMs, idleSeconds, stages) {
+    if (!configured.enabled || leases.size > 0 || !stages.includes(state.stage)) return null;
+    return new Date(lastActivityMs + idleSeconds * 1000).toISOString();
+  }
+
+  function clearIdleTimers() {
+    if (providerTimer) clearTimer(providerTimer);
+    if (databaseTimer) clearTimer(databaseTimer);
+    providerTimer = null;
+    databaseTimer = null;
+  }
+
+  function isoNow() {
+    return new Date(now()).toISOString();
+  }
+
+  return { acquire, refresh, release, withLease, status, close };
+}
+
+function publicLease(lease) {
+  return {
+    enabled: true,
+    leaseId: lease.leaseId,
+    kind: lease.kind,
+    executorId: lease.executorId,
+    acquiredAt: lease.acquiredAt,
+    expiresAt: lease.expiresAt
+  };
+}
+
+function disabledLease() {
+  return { enabled: false, leaseId: null };
+}
+
+function validLeaseId(value) {
+  if (typeof value !== 'string' || !/^[0-9a-f-]{36}$/i.test(value)) {
+    throw new TypeError('Runtime lease ID is invalid');
+  }
+  return value;
+}
+
+function requiredExecutorId(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 200) {
+    throw new TypeError('executorId must be non-empty text with at most 200 characters');
+  }
+  return value.trim();
+}
+
+function ownerText(value) {
+  const owner = String(value ?? 'unknown').replace(/[\r\n\t]+/g, ' ').trim();
+  return owner.slice(0, 200) || 'unknown';
+}
+
+function errorMessage(error) {
+  return String(error instanceof Error ? error.message : error)
+    .replace(/[\r\n\t]+/g, ' ')
+    .slice(0, 500);
+}