@animalabs/agent-framework 0.22.2 → 0.23.0

package/src/gate/event-gate.ts

@@ -14,6 +14,7 @@
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { GateScript } from './gate-script.js';
+import { safeSlice } from '../safe-slice.js';
 
 import type { ToolDefinition } from '../types/events.js';
 import type {
@@ -44,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). */
@@ -722,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;
@@ -1484,7 +1494,7 @@ export class EventGate {
     const event: PendingEvent = {
       policyName: policy.name,
       content: info.content.length > MAX_CONTENT_SNIPPET
-        ? info.content.slice(0, MAX_CONTENT_SNIPPET) + '...'
+        ? safeSlice(info.content, 0, MAX_CONTENT_SNIPPET) + '...'
         : info.content,
       eventType: info.eventType,
       timestamp: Date.now(),
@@ -1573,8 +1583,10 @@ export class EventGate {
       }
       for (const [channelId, { count, oldest, label }] of byChannel) {
         // Prefer the human-readable name; keep the id parenthesized so the
-        // agent can still address tools that want the composite id.
-        const channel = label ? `#${label} (${channelId})` : channelId;
+        // agent can still address tools that want the composite id. A name
+        // may carry its own `#`, so one is added only where the name lacks
+        // it, as at the other places that add a `#`.
+        const channel = label ? `${label.startsWith('#') ? label : `#${label}`} (${channelId})` : channelId;
         const age = Math.round((Date.now() - oldest) / 1000);
         lines.push(
           `- ${count} message${count > 1 ? 's' : ''} in ${channel} ` +
@@ -1620,6 +1632,17 @@ export class EventGate {
     }
   }
 
+  /** A turn that continues another (a budget restart, a tool-result-guard
+   *  retry) holds the entry its predecessor kept for it, and takes it again
+   *  where that entry ended in between: at a stop(), whose dispose() clears
+   *  every entry, or at a provider hold that kept the turn from starting,
+   *  whose end queues it again. Unlike onInferenceStarted it leaves a
+   *  pending self-wake alone: the logical turn that armed it is the one
+   *  still running. */
+  onInferenceResumed(agentName: string): void {
+    this.inferring.add(agentName);
+  }
+
   onInferenceEnded(agentName: string): void {
     this.inferring.delete(agentName);
     this.flushInferenceBufferIfClear();
@@ -1856,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) {
@@ -1983,5 +2006,15 @@ export class EventGate {
     this.rateLimitDenied.clear();
     this.passiveSampleFires.clear();
     this.inferenceBuffer = [];
+    // stop() disposes the gate once its streams and event loop have ended (a
+    // turn still compiling then is dropped at its next check, before it sends
+    // anything), and a start() goes on with this gate. An agent left here by
+    // 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 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

@@ -2,7 +2,7 @@
 export * from './types/index.js';
 
 // Core classes
-export { AgentFramework, BudgetPreflightError, ProviderWaitNotSleptError, ResumeBlockedError } from './framework.js';
+export { AgentFramework, BudgetPreflightError, ProviderWaitNotSleptError, QuiesceBlockedError, ResumeBlockedError } from './framework.js';
 export type { RuntimeSettingsPreview, HostModeStatus } from './framework.js';
 export { Agent } from './agent.js';
 export type { StartStreamResult } from './agent.js';
@@ -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';
 
@@ -84,14 +85,36 @@ export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';
 
+// Where each accepted inbound item came from (`metadata.inboundSource`)
+export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey } from './mcpl/index.js';
+export type {
+  InboundSource,
+  InboundChannelSource,
+  InboundUnscopedSource,
+  InboundSurfaceSource,
+} from './mcpl/index.js';
+
 // MCPL server config (exposed for hosts that manage servers at runtime via
 // 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 } 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
@@ -159,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',