blun-king-cli 9.1.474 → 9.1.476

package/bin/agent-api-http-adapter.mjs

@@ -228,6 +228,9 @@ function createAgentApiHttpAdapter(options = {}) {
   if (typeof options.closeSession !== 'function') {
     throw new TypeError('closeSession must be a function');
   }
+  if (options.touchSession !== undefined && typeof options.touchSession !== 'function') {
+    throw new TypeError('touchSession must be a function');
+  }
   const owners = new Map();
 
   function hasActiveOwner(principalId, sessionId) {
@@ -238,6 +241,20 @@ function createAgentApiHttpAdapter(options = {}) {
     return false;
   }
 
+  function isSessionActive(input) {
+    return input !== null
+      && typeof input === 'object'
+      && hasActiveOwner(input.principalId, input.sessionId);
+  }
+
+  function touchSession(principalId, sessionId) {
+    try {
+      options.touchSession?.({ principalId, sessionId });
+    } catch {
+      // Activity bookkeeping must not replace the customer response.
+    }
+  }
+
   function requireOwner(principalId, sessionId, requestId) {
     const key = scopeKey(sessionId, requestId);
     const scopeOwners = owners.get(key);
@@ -313,9 +330,11 @@ function createAgentApiHttpAdapter(options = {}) {
         prompt,
         tools,
       }));
+      touchSession(principalId, sessionId);
       trackScope(key, principalId, internalSessionId, response);
       return jsonResponse(200, response);
     } catch (error) {
+      touchSession(principalId, sessionId);
       trackScope(key, principalId, internalSessionId, null);
       throw error;
     }
@@ -331,9 +350,11 @@ function createAgentApiHttpAdapter(options = {}) {
         requestId,
         toolResults: body.tool_results,
       }));
+      touchSession(principalId, sessionId);
       trackScope(owner.key, principalId, owner.internalSessionId, response);
       return jsonResponse(200, response);
     } catch (error) {
+      touchSession(principalId, sessionId);
       trackScope(owner.key, principalId, owner.internalSessionId, null);
       throw error;
     }
@@ -348,6 +369,7 @@ function createAgentApiHttpAdapter(options = {}) {
       requestId,
       reason: typeof body.reason === 'string' ? body.reason : undefined,
     });
+    touchSession(principalId, sessionId);
     trackScope(owner.key, principalId, owner.internalSessionId, null);
     return jsonResponse(200, {
       id: `agent-${requestId}`,
@@ -412,7 +434,7 @@ function createAgentApiHttpAdapter(options = {}) {
     }
   }
 
-  return Object.freeze({ handleRequest });
+  return Object.freeze({ handleRequest, isSessionActive });
 }
 
 export {

package/bin/agent-api-service-environment.mjs

@@ -0,0 +1,236 @@
+import path from 'node:path';
+
+import { createAgentApiServiceHost } from './agent-api-service-host.mjs';
+
+const LOOPBACK_HOST = '127.0.0.1';
+const PROVIDER_NAME = 'privateAgentProvider';
+const PUBLIC_MODEL = 'king';
+
+function requireEnvironment(env) {
+  if (env === null || typeof env !== 'object' || Array.isArray(env)) {
+    throw new TypeError('env must be an object');
+  }
+  return env;
+}
+
+function requiredValue(env, name, options = {}) {
+  const value = env[name];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${name} is required`);
+  }
+  const normalized = options.preserve === true ? value : value.trim();
+  return normalized;
+}
+
+function optionalValue(env, name) {
+  if (!Object.hasOwn(env, name)) return undefined;
+  const value = env[name];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function integerValue(value, name, options = {}) {
+  if (!/^\d+$/u.test(value)) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  const parsed = Number(value);
+  const minimum = options.minimum ?? 1;
+  const maximum = options.maximum ?? Number.MAX_SAFE_INTEGER;
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    if (options.rangeMessage !== undefined) {
+      throw new TypeError(`${name} ${options.rangeMessage}`);
+    }
+    if (minimum === 1024) {
+      throw new TypeError(`${name} must be an integer of at least 1024`);
+    }
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return parsed;
+}
+
+function requireSecret(env, name) {
+  const value = requiredValue(env, name, { preserve: true });
+  if (Buffer.byteLength(value, 'utf8') < 32) {
+    throw new TypeError(`${name} must contain at least 32 bytes`);
+  }
+  return value;
+}
+
+function requireAbsoluteRoot(env) {
+  const value = requiredValue(env, 'BLUN_AGENT_API_ROOT_DIR');
+  if (!path.isAbsolute(value)) {
+    throw new TypeError('BLUN_AGENT_API_ROOT_DIR must be an absolute path');
+  }
+  return path.resolve(value);
+}
+
+function requireProviderBaseUrl(env) {
+  const value = requiredValue(env, 'BLUN_AGENT_API_PROVIDER_BASE_URL');
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new TypeError('BLUN_AGENT_API_PROVIDER_BASE_URL must be a valid URL');
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new TypeError('BLUN_AGENT_API_PROVIDER_BASE_URL must use http or https');
+  }
+  if (parsed.username.length > 0 || parsed.password.length > 0) {
+    throw new TypeError('BLUN_AGENT_API_PROVIDER_BASE_URL must not contain credentials');
+  }
+  if (parsed.search.length > 0 || parsed.hash.length > 0) {
+    throw new TypeError('BLUN_AGENT_API_PROVIDER_BASE_URL must not contain a query or fragment');
+  }
+  return value;
+}
+
+function loadAgentApiServiceEnvironment(input = process.env) {
+  const env = requireEnvironment(input);
+  const rootDir = requireAbsoluteRoot(env);
+  const internalSecret = requireSecret(env, 'BLUN_AGENT_API_INTERNAL_SECRET');
+  const isolationSecret = requireSecret(env, 'BLUN_AGENT_API_ISOLATION_SECRET');
+  if (internalSecret === isolationSecret) {
+    throw new TypeError('Agent API internal and isolation secrets must be different');
+  }
+
+  const port = integerValue(
+    requiredValue(env, 'BLUN_AGENT_API_PORT'),
+    'BLUN_AGENT_API_PORT',
+    { maximum: 65_535, rangeMessage: 'must be an integer from 1 through 65535' },
+  );
+  const providerBaseUrl = requireProviderBaseUrl(env);
+  const providerApiKey = requiredValue(
+    env,
+    'BLUN_AGENT_API_PROVIDER_API_KEY',
+    { preserve: true },
+  );
+  const providerModel = requiredValue(env, 'BLUN_AGENT_API_PROVIDER_MODEL');
+  const maxContextSize = integerValue(
+    requiredValue(env, 'BLUN_AGENT_API_MAX_CONTEXT_TOKENS'),
+    'BLUN_AGENT_API_MAX_CONTEXT_TOKENS',
+  );
+  const maxOutputSize = integerValue(
+    requiredValue(env, 'BLUN_AGENT_API_MAX_OUTPUT_TOKENS'),
+    'BLUN_AGENT_API_MAX_OUTPUT_TOKENS',
+  );
+  if (maxOutputSize > maxContextSize) {
+    throw new TypeError(
+      'BLUN_AGENT_API_MAX_OUTPUT_TOKENS must not exceed BLUN_AGENT_API_MAX_CONTEXT_TOKENS',
+    );
+  }
+  const maxBodyBytes = integerValue(
+    requiredValue(env, 'BLUN_AGENT_API_MAX_BODY_BYTES'),
+    'BLUN_AGENT_API_MAX_BODY_BYTES',
+    { minimum: 1024 },
+  );
+  const maxPrincipals = integerValue(
+    requiredValue(env, 'BLUN_AGENT_API_MAX_PRINCIPALS'),
+    'BLUN_AGENT_API_MAX_PRINCIPALS',
+  );
+  const maxSessionsPerPrincipal = integerValue(
+    requiredValue(env, 'BLUN_AGENT_API_MAX_SESSIONS_PER_PRINCIPAL'),
+    'BLUN_AGENT_API_MAX_SESSIONS_PER_PRINCIPAL',
+  );
+
+  const idleTimeoutRaw = optionalValue(env, 'BLUN_AGENT_API_SESSION_IDLE_TIMEOUT_MS');
+  const idleSweepRaw = optionalValue(env, 'BLUN_AGENT_API_IDLE_SWEEP_INTERVAL_MS');
+  const sessionIdleTimeoutMs = idleTimeoutRaw === undefined
+    ? 0
+    : integerValue(idleTimeoutRaw, 'BLUN_AGENT_API_SESSION_IDLE_TIMEOUT_MS');
+  if (idleSweepRaw !== undefined && sessionIdleTimeoutMs === 0) {
+    throw new TypeError(
+      'BLUN_AGENT_API_IDLE_SWEEP_INTERVAL_MS requires BLUN_AGENT_API_SESSION_IDLE_TIMEOUT_MS',
+    );
+  }
+  const idleSweepIntervalMs = idleSweepRaw === undefined
+    ? undefined
+    : integerValue(idleSweepRaw, 'BLUN_AGENT_API_IDLE_SWEEP_INTERVAL_MS');
+
+  const providerConfig = Object.freeze({
+    type: 'blun',
+    apiKey: providerApiKey,
+    baseUrl: providerBaseUrl,
+    defaultModel: providerModel,
+  });
+  const modelConfig = Object.freeze({
+    provider: PROVIDER_NAME,
+    model: providerModel,
+    maxContextSize,
+    maxOutputSize,
+    capabilities: Object.freeze(['tool_use']),
+  });
+  const harnessConfig = Object.freeze({
+    providers: Object.freeze({ [PROVIDER_NAME]: providerConfig }),
+    models: Object.freeze({ [PUBLIC_MODEL]: modelConfig }),
+    defaultModel: PUBLIC_MODEL,
+  });
+  const hostOptions = Object.freeze({
+    rootDir,
+    internalSecret,
+    isolationSecret,
+    harnessConfig,
+    maxBodyBytes,
+    maxPrincipals,
+    maxSessionsPerPrincipal,
+    sessionIdleTimeoutMs,
+    idleSweepIntervalMs,
+  });
+
+  return Object.freeze({
+    listen: Object.freeze({ host: LOOPBACK_HOST, port }),
+    hostOptions,
+  });
+}
+
+async function startAgentApiServiceFromEnvironment(options = {}) {
+  const createServiceHost = options.createServiceHost === undefined
+    ? createAgentApiServiceHost
+    : options.createServiceHost;
+  if (typeof createServiceHost !== 'function') {
+    throw new TypeError('createServiceHost must be a function');
+  }
+  const config = loadAgentApiServiceEnvironment(
+    options.env === undefined ? process.env : options.env,
+  );
+  const service = createServiceHost(config.hostOptions);
+  if (service === null || typeof service !== 'object'
+    || typeof service.listen !== 'function'
+    || typeof service.close !== 'function') {
+    throw new TypeError('Agent API service host must provide listen and close');
+  }
+
+  let address;
+  try {
+    address = await service.listen(config.listen);
+  } catch (error) {
+    try {
+      await service.close();
+    } catch {
+      // The listen failure is the actionable error; cleanup remains best-effort.
+    }
+    throw error;
+  }
+
+  let closePromise;
+  return Object.freeze({
+    address: Object.freeze({
+      address: address.address,
+      family: address.family,
+      port: address.port,
+    }),
+    close() {
+      closePromise ??= Promise.resolve().then(() => service.close());
+      return closePromise;
+    },
+  });
+}
+
+export {
+  LOOPBACK_HOST,
+  PROVIDER_NAME,
+  PUBLIC_MODEL,
+  loadAgentApiServiceEnvironment,
+  startAgentApiServiceFromEnvironment,
+};

package/bin/agent-api-service-host.mjs

@@ -113,6 +113,7 @@ function createAgentApiServiceHost(options = {}) {
     runtime,
     publicModel: 'king',
   });
+  let adapter;
   const sessionRegistry = createAgentApiSessionRegistry({
     rootDir,
     isolationSecret,
@@ -121,11 +122,20 @@ function createAgentApiServiceHost(options = {}) {
     sessionOptions: options.sessionOptions,
     maxPrincipals: options.maxPrincipals,
     maxSessionsPerPrincipal: options.maxSessionsPerPrincipal,
+    sessionIdleTimeoutMs: options.sessionIdleTimeoutMs,
+    idleSweepIntervalMs: options.idleSweepIntervalMs,
+    now: options.now,
+    scheduleInterval: options.scheduleInterval,
+    cancelInterval: options.cancelInterval,
+    isSessionActive(input) {
+      return adapter?.isSessionActive(input) === true;
+    },
   });
-  const adapter = createAgentApiHttpAdapter({
+  adapter = createAgentApiHttpAdapter({
     controller,
     resolveSession: sessionRegistry.resolveSession,
     closeSession: sessionRegistry.closeSession,
+    touchSession: sessionRegistry.touchSession,
   });
   const privateServer = createAgentApiPrivateHttpServer({
     adapter,

package/bin/agent-api-session-registry.mjs

@@ -40,6 +40,13 @@ function requireLimit(value) {
   return value;
 }
 
+function requireIdleDuration(value, label, { allowZero = true } = {}) {
+  if (!Number.isSafeInteger(value) || value < (allowZero ? 0 : 1)) {
+    throw new TypeError(`${label} must be ${allowZero ? 'a non-negative' : 'a positive'} integer`);
+  }
+  return value;
+}
+
 function validateIsolationSecret(value) {
   if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') < 32) {
     throw new TypeError('isolationSecret must contain at least 32 bytes');
@@ -98,8 +105,37 @@ function createAgentApiSessionRegistry(options = {}) {
     options.maxSessionsPerPrincipal ?? DEFAULT_MAX_SESSIONS_PER_PRINCIPAL,
   );
   const maxPrincipals = requireLimit(options.maxPrincipals ?? DEFAULT_MAX_PRINCIPALS);
+  const sessionIdleTimeoutMs = requireIdleDuration(
+    options.sessionIdleTimeoutMs ?? 0,
+    'sessionIdleTimeoutMs',
+  );
+  if (sessionIdleTimeoutMs === 0 && options.idleSweepIntervalMs !== undefined) {
+    throw new TypeError('idleSweepIntervalMs requires sessionIdleTimeoutMs');
+  }
+  const idleSweepIntervalMs = sessionIdleTimeoutMs === 0
+    ? 0
+    : requireIdleDuration(
+      options.idleSweepIntervalMs ?? Math.min(sessionIdleTimeoutMs, 60_000),
+      'idleSweepIntervalMs',
+      { allowZero: false },
+    );
+  const now = options.now ?? Date.now;
+  const scheduleInterval = options.scheduleInterval ?? setInterval;
+  const cancelInterval = options.cancelInterval ?? clearInterval;
+  if (typeof now !== 'function') throw new TypeError('now must be a function');
+  if (typeof scheduleInterval !== 'function') {
+    throw new TypeError('scheduleInterval must be a function');
+  }
+  if (typeof cancelInterval !== 'function') {
+    throw new TypeError('cancelInterval must be a function');
+  }
+  if (options.isSessionActive !== undefined && typeof options.isSessionActive !== 'function') {
+    throw new TypeError('isSessionActive must be a function');
+  }
   const principals = new Map();
   let closed = false;
+  let sweepHandle;
+  let sweepPromise = Promise.resolve(0);
 
   function ensureOpen() {
     if (closed) {
@@ -210,11 +246,22 @@ function createAgentApiSessionRegistry(options = {}) {
     );
     let record = principals.get(principalId);
     const existing = record?.sessions.get(publicSessionId);
-    if (existing !== undefined) return existing;
+    if (existing !== undefined) {
+      if (existing.closingPromise !== undefined) {
+        await existing.closingPromise;
+        return resolveSession(input);
+      }
+      existing.lastActiveAt = now();
+      return existing.pending;
+    }
     if (input.create !== true) {
       throw registryError('AGENT_API_SESSION_NOT_FOUND', 'Agent API session was not found');
     }
     record = getOrCreatePrincipal(principalId);
+    if (record.sessions.size >= maxSessionsPerPrincipal) {
+      await pruneIdleSessions({ principalId });
+      record = principals.get(principalId) ?? getOrCreatePrincipal(principalId);
+    }
     if (record.sessions.size >= maxSessionsPerPrincipal) {
       throw registryError(
         'AGENT_API_SESSION_LIMIT',
@@ -222,12 +269,22 @@ function createAgentApiSessionRegistry(options = {}) {
       );
     }
 
-    const pending = createSession(record, principalId, publicSessionId);
-    record.sessions.set(publicSessionId, pending);
+    const entry = {
+      closingPromise: undefined,
+      lastActiveAt: now(),
+      pending: undefined,
+      ready: false,
+    };
+    entry.pending = createSession(record, principalId, publicSessionId).then((session) => {
+      entry.ready = true;
+      entry.lastActiveAt = now();
+      return session;
+    });
+    record.sessions.set(publicSessionId, entry);
     try {
-      return await pending;
+      return await entry.pending;
     } catch (error) {
-      if (record.sessions.get(publicSessionId) === pending) {
+      if (record.sessions.get(publicSessionId) === entry) {
         record.sessions.delete(publicSessionId);
       }
       if (!record.harnessReady
@@ -239,6 +296,74 @@ function createAgentApiSessionRegistry(options = {}) {
     }
   }
 
+  function touchSession(input) {
+    if (closed || input === null || typeof input !== 'object') return false;
+    const record = principals.get(input.principalId);
+    const entry = record?.sessions.get(input.sessionId);
+    if (entry === undefined || entry.closingPromise !== undefined) return false;
+    entry.lastActiveAt = now();
+    return true;
+  }
+
+  function sessionIsActive(principalId, publicSessionId) {
+    if (options.isSessionActive === undefined) return false;
+    try {
+      const result = options.isSessionActive({ principalId, sessionId: publicSessionId });
+      return result === true || result?.then !== undefined;
+    } catch {
+      return true;
+    }
+  }
+
+  async function closeEntry(record, principalId, publicSessionId, entry) {
+    if (entry.closingPromise !== undefined) return entry.closingPromise;
+    entry.closingPromise = (async () => {
+      let failure;
+      try {
+        const session = await entry.pending;
+        await session.close?.();
+      } catch (error) {
+        failure = error;
+      }
+      if (record.sessions.get(publicSessionId) === entry) {
+        record.sessions.delete(publicSessionId);
+      }
+      if (record.sessions.size === 0 && principals.get(principalId) === record) {
+        principals.delete(principalId);
+        const harness = await record.harnessPromise.catch(() => null);
+        try {
+          await harness?.close?.();
+        } catch (error) {
+          failure ??= error;
+        }
+      }
+      if (failure !== undefined) throw failure;
+      return true;
+    })();
+    return entry.closingPromise;
+  }
+
+  async function pruneIdleSessions(input = {}) {
+    if (closed || sessionIdleTimeoutMs === 0) return 0;
+    const principalFilter = input.principalId;
+    const cutoff = now() - sessionIdleTimeoutMs;
+    const closing = [];
+    for (const [principalId, record] of principals) {
+      if (principalFilter !== undefined && principalId !== principalFilter) continue;
+      for (const [publicSessionId, entry] of record.sessions) {
+        if (!entry.ready
+          || entry.closingPromise !== undefined
+          || entry.lastActiveAt > cutoff
+          || sessionIsActive(principalId, publicSessionId)) {
+          continue;
+        }
+        closing.push(closeEntry(record, principalId, publicSessionId, entry));
+      }
+    }
+    const outcomes = await Promise.allSettled(closing);
+    return outcomes.filter((outcome) => outcome.status === 'fulfilled').length;
+  }
+
   async function closeSession(input) {
     ensureOpen();
     if (input === null || typeof input !== 'object') {
@@ -251,36 +376,48 @@ function createAgentApiSessionRegistry(options = {}) {
       'sessionId',
     );
     const record = principals.get(principalId);
-    const pending = record?.sessions.get(publicSessionId);
-    if (pending === undefined) return false;
-    record.sessions.delete(publicSessionId);
-    const session = await pending;
-    await session.close?.();
-    if (record.sessions.size === 0 && principals.get(principalId) === record) {
-      principals.delete(principalId);
-      const harness = await record.harnessPromise.catch(() => null);
-      await harness?.close?.();
-    }
-    return true;
+    const entry = record?.sessions.get(publicSessionId);
+    if (entry === undefined) return false;
+    return closeEntry(record, principalId, publicSessionId, entry);
   }
 
   async function close() {
     if (closed) return;
     closed = true;
+    if (sweepHandle !== undefined) cancelInterval(sweepHandle);
+    await sweepPromise;
     const records = [...principals.values()];
     principals.clear();
     for (const record of records) {
-      const sessions = await Promise.allSettled([...record.sessions.values()]);
+      const sessions = await Promise.allSettled(
+        [...record.sessions.values()].map(async (entry) => {
+          if (entry.closingPromise !== undefined) {
+            await entry.closingPromise;
+            return null;
+          }
+          return entry.pending;
+        }),
+      );
       record.sessions.clear();
       for (const outcome of sessions) {
-        if (outcome.status === 'fulfilled') await outcome.value.close?.();
+        if (outcome.status === 'fulfilled' && outcome.value !== null) {
+          await outcome.value.close?.();
+        }
       }
       const harness = await record.harnessPromise.catch(() => null);
       await harness?.close?.();
     }
   }
 
-  return Object.freeze({ close, closeSession, resolveSession });
+  if (sessionIdleTimeoutMs > 0) {
+    sweepHandle = scheduleInterval(() => {
+      sweepPromise = sweepPromise.then(() => pruneIdleSessions()).catch(() => 0);
+      return sweepPromise;
+    }, idleSweepIntervalMs);
+    sweepHandle?.unref?.();
+  }
+
+  return Object.freeze({ close, closeSession, pruneIdleSessions, resolveSession, touchSession });
 }
 
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blun-king-cli",
-  "version": "9.1.474",
+  "version": "9.1.476",
   "description": "BLUN CLI - your own AI agent with a Telegram channel. Get it done. With BLUN.",
   "license": "MIT",
   "bin": {