toolnexus 0.20.0 → 0.22.0

package/src/agents/compaction.ts

@@ -102,6 +102,26 @@ export interface CompactorOptions {
    * default. Composes with the memory builtin.
    */
   flushToMemory?: boolean
+  /**
+   * Called after each compaction with what changed, so a host can tell its UI or log (SPEC §4C).
+   * Never called on a no-op. Awaited before the next model call.
+   */
+  onCompact?: (info: CompactInfo) => void | Promise<void>
+}
+
+/** One compaction, for {@link CompactorOptions.onCompact}. Token counts come from `countTokens`. */
+export interface CompactInfo {
+  tokensBefore: number
+  tokensAfter: number
+  messagesBefore: number
+  messagesAfter: number
+  /** How many messages were folded into the summary. */
+  summarized: number
+  /** The text `summarize` returned (without the header line). */
+  summary: string
+  /** The summarized messages, verbatim, so a host can persist them (the loop saves only the
+   * compacted transcript). */
+  folded: Message[]
 }
 
 /** The event a `beforeLLM` hook receives (§8). */
@@ -134,7 +154,8 @@ export function compactor(
 
   return async (ev: BeforeLLMEvent): Promise<{ messages: Message[] } | undefined> => {
     const msgs = ev.messages
-    if (count(msgs) <= opts.maxTokens) return undefined // under budget → no-op
+    const before = count(msgs)
+    if (before <= opts.maxTokens) return undefined // under budget → no-op
 
     // Preserve a leading system prompt verbatim (identity / soul / skills — never summarized).
     const headEnd = msgs[0]?.role === "system" ? 1 : 0
@@ -143,9 +164,17 @@ export function compactor(
     const split = findTailStart(msgs, headEnd, keepTail, count)
     if (split <= headEnd) return undefined // nothing safely compactible
 
-    const older = msgs.slice(headEnd, split)
-    if (older.length === 0) return undefined
+    let older = msgs.slice(headEnd, split)
     const tail = msgs.slice(split)
+    // The latest user prompt is never summarized away. When the only clean boundary is the first
+    // message after the system prompt (one prompt followed by a long agentic run), keep that
+    // prompt verbatim and summarize the work after it: [system, prompt, summary].
+    let pinned: Message[] = []
+    if (split === msgs.length && headEnd < msgs.length && isBoundary(msgs[headEnd])) {
+      pinned = msgs.slice(headEnd, headEnd + 1)
+      older = msgs.slice(headEnd + 1)
+    }
+    if (older.length === 0) return undefined
 
     const flushNote: Message[] = opts.flushToMemory
       ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
@@ -154,7 +183,19 @@ export function compactor(
     const summary = await opts.summarize(older)
     const summaryMsg: Message = { role: "system", content: `${SUMMARY_PREFIX}${summary}` }
 
-    return { messages: [...system, summaryMsg, ...flushNote, ...tail] }
+    const out = [...system, ...pinned, summaryMsg, ...flushNote, ...tail]
+    const after = count(out)
+    if (after >= before) return undefined // compaction would not shrink the transcript → no-op
+    await opts.onCompact?.({
+      tokensBefore: before,
+      tokensAfter: after,
+      messagesBefore: msgs.length,
+      messagesAfter: out.length,
+      summarized: older.length,
+      summary,
+      folded: older,
+    })
+    return { messages: out }
   }
 }
 

package/src/agents/runtime.ts

@@ -390,6 +390,11 @@ export interface RuntimeOptions {
   /** §8 observability sink applied to EVERY agent's client, unless that agent's def
    * sets its own `onMetric`. Resolves independently of `hooks`. Forwarded verbatim. */
   onMetric?: (ev: MetricEvent) => void
+  /** The runtime-level §10 interpreter (SPEC §4C): answers a suspension when no agent on the
+   * handle's chain has its own `waitFor`. Absent ⇒ unchanged (the suspension goes durable). A
+   * host running an agent as a tool (`asToolWith`) sets it so the child's asks reach the same
+   * bridge as the parent turn. */
+  waitFor?: (request: Request) => Promise<Answer>
 }
 
 interface GateWaiter {
@@ -855,11 +860,20 @@ export class AgentRuntime {
    * escalation traced (nearest interpreter wins; the Request's `data.path` names
    * the suspended subtree that is asking). */
   private wrapWaitFor(h: Handle): ((req: Request) => Promise<Answer>) | undefined {
-    const waitFor = h.def.waitFor
+    const own = h.def.waitFor
+    let waitFor = own
+    if (!waitFor && this.opts.waitFor) {
+      // The runtime-level bridge answers only when NO agent on the chain has its own waitFor;
+      // otherwise the ask escalates to that nearest interpreter, as before.
+      let a: Handle | null = h.parent
+      while (a && !a.def.waitFor) a = a.parent
+      if (!a) waitFor = this.opts.waitFor
+    }
     if (!waitFor) return undefined
+    const answerer = own ? h.id : this.root.id
     return async (req: Request): Promise<Answer> => {
       const path = Array.isArray(req.data?.path) ? (req.data!.path as string[]).join("/") : h.id
-      this.t(`${path}: escalate → ${h.id} answers ("nearest interpreter")`)
+      this.t(`${path}: escalate → ${answerer} answers ("nearest interpreter")`)
       return waitFor(req)
     }
   }