@animalabs/agent-framework 0.22.3 → 0.23.0

package/src/gate/event-gate.ts

@@ -45,6 +45,15 @@ const MAX_TRACE_SNIPPET = 80;
 const MAX_INFERENCE_BUFFER = 100;
 /** Minimum interval between filesystem checks for config changes (ms). */
 const RELOAD_THROTTLE_MS = 1000;
+
+/**
+ * Parse a gate file's text as JSON. Some Windows editors save UTF-8 with a
+ * leading U+FEFF (BOM), which `readFileSync(…, 'utf-8')` keeps and
+ * `JSON.parse` rejects; drop exactly one before parsing (#395).
+ */
+function parseGateJson(text: string): unknown {
+  return JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+}
 /** Minimum debounce value (ms). */
 const MIN_DEBOUNCE_MS = 100;
 /** Maximum debounce value (ms). */
@@ -723,7 +732,7 @@ export class EventGate {
       const raw = readFileSync(this.configPath, 'utf-8');
       const stat = statSync(this.configPath);
       this.configMtime = stat.mtimeMs;
-      const config = validateConfig(JSON.parse(raw));
+      const config = validateConfig(parseGateJson(raw));
       this.configSource = 'file';
       this.configErrors = [];
       return config;
@@ -1870,7 +1879,7 @@ export class EventGate {
         return;
       }
       this.privilegedMtime = statSync(this.privilegedUsersPath).mtimeMs;
-      const raw = JSON.parse(readFileSync(this.privilegedUsersPath, 'utf8'));
+      const raw: any = parseGateJson(readFileSync(this.privilegedUsersPath, 'utf8'));
       const ids = Array.isArray(raw) ? raw : Array.isArray(raw?.userIds) ? raw.userIds : [];
       this.privilegedUserIds = new Set(ids.map((x: unknown) => String(x)));
     } catch (err) {
@@ -2003,10 +2012,9 @@ export class EventGate {
     // a turn whose exit didn't end it (a retry stop() cancelled, a successor
     // stop() refused) would make every debounced batch buffer until that
     // agent's next turn ended. A turn that continues after the start() takes
-    // its entry again (onInferenceResumed). A turn that a start() during the
-    // stop() began before this ran loses its entry too, and runs on without
-    // it, so debounced batches are delivered while it runs: nothing refuses
-    // a start() during a stop() yet.
+    // its entry again (onInferenceResumed). A start() made during the stop()
+    // is refused, so no turn of a new lifecycle can have begun before this
+    // runs.
     this.inferring.clear();
   }
 }

package/src/held-writes.ts

@@ -0,0 +1,59 @@
+import type { MessageId, MessageQuery, StoredMessage } from '@animalabs/context-manager';
+
+/**
+ * The id a module holds for a write the framework holds. addMessage holds a
+ * write while its agent's turn is alive or the host is quiesced, and stores
+ * it at a later boundary. Until then, a module's context answers its id as a
+ * handle: `held:` and the write's id in the deferred queue. The context's
+ * getMessage, editMessage and removeMessage take the handle as they take a
+ * stored id, as a process answer's edits and removals do, and once the write
+ * lands, the handle names the stored row, which carries the write's id as
+ * `metadata.deferredWriteId`.
+ */
+const HELD = 'held:';
+
+export function heldHandle(writeId: string): MessageId {
+  return `${HELD}${writeId}`;
+}
+
+/** The deferred write a handle names, or undefined for any other id. A value
+ *  that isn't a string, which only an untyped caller passes, is no handle,
+ *  and goes on to the store as it did before handles. */
+export function heldWriteId(id: MessageId): string | undefined {
+  return typeof id === 'string' && id.startsWith(HELD) ? id.slice(HELD.length) : undefined;
+}
+
+/**
+ * Whether a row matches `filter` as context-manager's queryMessages matches a
+ * stored one. That's its MessageStore's private matchesFilter at 0.14.1, which
+ * the package doesn't export, so the rule is copied here, and a test compares
+ * the two on the same rows. A row matches the external source, one of the
+ * external ids (an empty list filters nothing), the participant, and each
+ * metadata path, dot-separated, by strict equality.
+ */
+export function matchesMessageQuery(row: Pick<StoredMessage, 'participant' | 'metadata'>, filter: MessageQuery): boolean {
+  const external = row.metadata?.external as { source?: unknown; id?: unknown } | undefined;
+  if (filter.source !== undefined && external?.source !== filter.source) return false;
+  if (
+    filter.externalIds !== undefined &&
+    filter.externalIds.length > 0 &&
+    (!external?.id || !filter.externalIds.includes(external.id as string))
+  ) {
+    return false;
+  }
+  if (filter.participant !== undefined && row.participant !== filter.participant) return false;
+  if (filter.metadata !== undefined) {
+    for (const [path, value] of Object.entries(filter.metadata)) {
+      if (valueAt(row.metadata, path) !== value) return false;
+    }
+  }
+  return true;
+}
+
+function valueAt(value: unknown, path: string): unknown {
+  for (const part of path.split('.')) {
+    if (value === undefined || value === null || typeof value !== 'object') return undefined;
+    value = (value as Record<string, unknown>)[part];
+  }
+  return value;
+}

package/src/index.ts

@@ -74,6 +74,7 @@ export type {
   ExecResult,
   PyRunnerOptions,
   ScriptToolCallHandler,
+  ScriptToolResult,
 } from './code-execution/index.js';
 export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './usage/index.js';
 
@@ -97,10 +98,23 @@ export type {
 // connectMcplServer / disconnectMcplServer / restartMcplServer)
 export type { McplServerConfig } from './mcpl/index.js';
 
-// MCPL client connection (exposed so external tooling — server playtests,
-// health probes, protocol harnesses — can dial an MCPL server exactly the
-// way the framework host does, over stdio or WebSocket)
-export { McplServerConnection, McplRequestError } from './mcpl/index.js';
+// Both engines' client connections, and the configuration helpers and
+// protocol revisions they share (exposed so external tooling, such as server
+// playtests, health probes and protocol harnesses, can reach a server
+// exactly the way the framework host does: MCPL over stdio or WebSocket, and
+// modern MCP over stdio or Streamable HTTP)
+export { McplServerConnection, McplRequestError, McplProtocolVersionError, McplUnreapedLaunchError } from './mcpl/index.js';
+export { ModernMcpConnection } from './mcpl/index.js';
+export type { ModernToolCallResult } from './mcpl/index.js';
+export {
+  LEGACY_MCP_PROTOCOL_VERSION,
+  MODERN_MCP_PROTOCOL_VERSION,
+  resolveServerBinding,
+  serverConfigProblems,
+  serverConfigWarnings,
+  checkServerConfig,
+} from './mcpl/index.js';
+export type { McpProtocolFamily, McpTransportKind, ServerBinding } from './mcpl/index.js';
 export type { McplHostCapabilities, McplConnectionCloseInfo } from './mcpl/index.js';
 
 // MCPL tool lifecycle (RFC-007) and tool classes (RFC-008): the types a host
@@ -168,6 +182,7 @@ export * from "./tool-presentation.js";
 export {
   SILENT_HEARTBEAT_SEPARATOR,
   silentHeartbeatOf,
+  type RequestOnlyPrompt,
   type SilentHeartbeatStamp,
   type SilentHeartbeatTick,
 } from './silent-heartbeat.js';

package/src/mcpl/capability-grant.ts

@@ -223,7 +223,7 @@ export function capabilityPatternMatches(pattern: string, path: string): boolean
 /** §13.4: denied unless explicitly enabled by host config. RFC-007 adds both
  *  tool-lifecycle leaves: observing other servers' tool use (and, above all,
  *  their arguments) is an operator decision, never a default. */
-const DENY_BY_DEFAULT: readonly string[] = [
+export const DENY_BY_DEFAULT: readonly string[] = [
   'contextHooks.beforeInference.inject.system',
   'toolLifecycle.observe',
   'toolLifecycle.inputs',