@animalabs/agent-framework 0.9.0 → 0.10.0

package/dist/src/framework.js

@@ -13,7 +13,7 @@ import { computeGrant, CapabilityGrant, expandAdvertisementShorthand } from './m
 import { maskNegotiatedCapabilities } from './mcpl/capability-mask.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } from './mcpl/push-handler.js';
-import { parseProsePrefix } from './mcpl/prose-grammar.js';
+import { parseProsePrefix, parseHybridProsePrefix } from './mcpl/prose-grammar.js';
 import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
@@ -64,6 +64,8 @@ function sniffImageMediaType(data) {
 const SILENCING_TOOLS = new Set([
     'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
 ]);
+/** World-surface publication names that outrank hybrid prose envelopes. */
+const HYBRID_PUBLICATION_TOOLS = new Set(['say', 'whisper']);
 /**
  * True when an injected message is real conversational input — something the
  * agent might actually be replying to — rather than ambient machinery.
@@ -159,6 +161,13 @@ function proseModePrimer(mode) {
         return '[prose-routing] Mode change: your plain text auto-routes to the ' +
             'conversational locus again. `>>` destination prefixes are no longer needed.';
     }
+    if (mode === 'hybrid') {
+        return '[prose-routing] Hybrid routing enabled: unprefixed text still lands in the ' +
+            'current conversational locus. A leading `>>>destination` envelope instead routes ' +
+            'that prose to one uniquely resolved authorized Discord or Eidoverse channel. The ' +
+            'envelope remains in your memory but recipients see only its body; delivery or failure ' +
+            'is reported back to you.';
+    }
     // Deliberately terse: a short event-style notice is classifier-safe from
     // the user role (ablation D, 2026-07-24), while the full grammar as a user
     // message drew a deterministic reasoning_extraction refusal (ablation A/B).
@@ -249,7 +258,7 @@ function validateUtilityArgs(input, schema) {
 }
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
-import { EventGate } from './gate/event-gate.js';
+import { EventGate, formatShadowWarning } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
 import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, } from './recovery/discord-awareness-outbox.js';
@@ -459,6 +468,8 @@ export class AgentFramework {
     /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
      *  Cleared at every non-restart turn start; survives context restarts. */
     proseTargetPins = new Map();
+    /** Hybrid router is fail-closed after a malformed/unresolved envelope until a new valid target. */
+    proseHybridSuppressed = new Set();
     /** Agents whose current turn requested `!` continuation — re-woken when the
      *  turn completes instead of pausing until the next external event. */
     proseContinuations = new Set();
@@ -1570,8 +1581,10 @@ export class AgentFramework {
     /**
      * Add or replace (upsert) a gate policy at runtime. Validated and persisted
      * to gate.json; hot-applied in memory. Throws if no gate is configured or the
-     * policy is invalid. `position: 'prepend'` puts a wake rule ahead of broad
-     * defer/debounce rules (first match wins).
+     * policy is invalid. Placement: `'prepend'` puts a rule ahead of EVERYTHING
+     * (including addressed-message wake rules — see EventGate.lintShadows);
+     * `{before: name}` / `{after: name}` anchor it against a specific rule,
+     * which is usually what a sampler or debounce actually wants.
      */
     addGatePolicy(rawPolicy, options) {
         if (!this.eventGate) {
@@ -1904,9 +1917,17 @@ export class AgentFramework {
             name: 'wake_add_rule',
             description: 'Add or replace a wake rule (a gate.json policy) at runtime — no need to ' +
                 'hand-edit the file. The rule is validated and hot-applied immediately. ' +
-                'A rule with the same `name` replaces the existing one in place. Use ' +
-                '`position: "prepend"` to put a wake rule ahead of broad defer/debounce ' +
-                'rules (first match wins). Two common shapes:\n' +
+                'A rule with the same `name` replaces the existing one in place (add a ' +
+                'position to move it). ⚠️ ORDERING IS SEMANTICS: first match wins, and a ' +
+                'matched rule CONSUMES the event — a broad rule placed early makes every ' +
+                'later rule unreachable for its scope, including your addressed-message ' +
+                '(DM/mention) wake rules. Prefer `insertBefore`/`insertAfter` to place a ' +
+                'rule relative to a specific existing rule; use `position: "prepend"` only ' +
+                'when the rule really must beat EVERYTHING. For "additionally wake me ' +
+                'every Nth event / at most N per hour" governors, set `passthrough: true` ' +
+                'so non-firing matches fall through to your normal rules instead of ' +
+                'swallowing them. The result includes a before/after probe table and any ' +
+                'shadow warnings — READ THEM before ending the turn. Two common shapes:\n' +
                 '• Watch a FILE/workspace path: match on `mount` + `pathGlob`, e.g. ' +
                 '`{ name: "watch-notes", match: { scope: ["workspace:modified"], mount: "project", pathGlob: "notes/*.md" }, behavior: "always" }`.\n' +
                 '• Watch a CHANNEL: match on `source` + `channel` (and/or `tagsAny: ["chat:ambient"]`), ' +
@@ -1973,7 +1994,27 @@ export class AgentFramework {
                     position: {
                         type: 'string',
                         enum: ['append', 'prepend'],
-                        description: 'Where to insert a NEW rule (ignored when replacing by name). Default "append".',
+                        description: 'Coarse placement. "append" (default) adds at the end; "prepend" puts the rule ' +
+                            'ahead of EVERYTHING — including addressed-message wake rules — so prefer ' +
+                            'insertBefore/insertAfter unless the rule really must beat every other rule. ' +
+                            'When replacing an existing name, giving any placement MOVES the rule there; ' +
+                            'omit all placement fields to update it in place.',
+                    },
+                    insertBefore: {
+                        type: 'string',
+                        description: 'Insert the rule immediately BEFORE the named existing rule (error if absent). ' +
+                            'The safe way to order against a specific catch-all, e.g. insertBefore: "discord-ambient".',
+                    },
+                    insertAfter: {
+                        type: 'string',
+                        description: 'Insert the rule immediately AFTER the named existing rule (error if absent).',
+                    },
+                    passthrough: {
+                        type: 'boolean',
+                        description: 'Observer semantics for rateLimit/passiveSample rules: when the rule matches but ' +
+                            'does not fire (below N, bucket empty), the event FALLS THROUGH to later rules ' +
+                            'instead of being consumed. Use for "additionally wake me every Nth event" ' +
+                            'governors so they never swallow DM/mention wakes.',
                     },
                     resets: {
                         type: 'array',
@@ -4307,6 +4348,98 @@ export class AgentFramework {
             await this.deliverProseEnvelope(agent, envelope.replace(/^\s+(?=>>)/, ''));
         }
     }
+    /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
+    async deliverHybridProse(agent, rawText, locus, allowLocus) {
+        const lines = rawText.split('\n');
+        const envelopes = [];
+        let current = [];
+        for (const line of lines) {
+            if (line.trimStart().startsWith('>>>') && current.length > 0) {
+                envelopes.push(current.join('\n'));
+                current = [];
+            }
+            current.push(line);
+        }
+        if (current.length > 0)
+            envelopes.push(current.join('\n'));
+        for (const envelope of envelopes) {
+            if (!envelope.trim())
+                continue;
+            const normalized = envelope.replace(/^\s+(?=>>>)/, '');
+            const attempted = normalized.startsWith('>>>');
+            const parsed = parseHybridProsePrefix(normalized);
+            if (parsed.continueTurn)
+                this.proseContinuations.add(agent.name);
+            if (parsed.kind === 'private') {
+                this.proseTargetPins.delete(agent.name);
+                this.proseHybridSuppressed.add(agent.name);
+                console.error(`[prose] ${agent.name}: >>>skip_reply — ${parsed.body.length} chars kept in context (not sent)`);
+                continue;
+            }
+            if (parsed.kind === 'target') {
+                const resolved = this.channelRegistry.resolveProseTarget(parsed.target);
+                if ('error' in resolved) {
+                    this.proseTargetPins.delete(agent.name);
+                    this.proseHybridSuppressed.add(agent.name);
+                    this.bounceProse(agent, parsed.body, resolved.error, resolved.candidates, '>>>');
+                    continue;
+                }
+                let body = parsed.body;
+                const usedClipboard = body.includes('{{unsent}}');
+                if (usedClipboard)
+                    body = body.replaceAll('{{unsent}}', this.proseClipboards.get(agent.name) ?? '');
+                this.proseTargetPins.set(agent.name, resolved.channelId);
+                this.proseHybridSuppressed.delete(agent.name);
+                if (!body.trim()) {
+                    console.error(`[prose] ${agent.name}: >>>${parsed.target} established target; empty body — nothing sent yet`);
+                    continue;
+                }
+                try {
+                    const outcome = await this.channelRegistry.routeSpeech(agent.name, body, resolved.channelId);
+                    this.recordProseDelivery(agent.name, outcome);
+                    if (outcome?.delivered) {
+                        this.proseBounceStreaks.delete(agent.name);
+                        if (usedClipboard)
+                            this.proseClipboards.delete(agent.name);
+                    }
+                    else {
+                        this.proseTargetPins.delete(agent.name);
+                        this.proseHybridSuppressed.add(agent.name);
+                        this.bounceProse(agent, parsed.body, `delivery to ${resolved.channelId} was not confirmed`, undefined, '>>>');
+                    }
+                }
+                catch (err) {
+                    this.proseTargetPins.delete(agent.name);
+                    this.proseHybridSuppressed.add(agent.name);
+                    this.bounceProse(agent, parsed.body, `delivery to ${resolved.channelId} failed: ${err instanceof Error ? err.message : String(err)}`, undefined, '>>>');
+                }
+                continue;
+            }
+            if (attempted) {
+                this.proseTargetPins.delete(agent.name);
+                this.proseHybridSuppressed.add(agent.name);
+                this.bounceProse(agent, normalized, 'malformed >>> routing envelope: destination is missing', undefined, '>>>');
+                continue;
+            }
+            if (this.proseHybridSuppressed.has(agent.name)) {
+                this.recordProseSuppression(agent.name, 1);
+                continue;
+            }
+            const sticky = this.proseTargetPins.get(agent.name);
+            if (!allowLocus && !sticky) {
+                this.recordProseSuppression(agent.name, 1);
+                continue;
+            }
+            const target = sticky ?? locus;
+            try {
+                const outcome = await this.channelRegistry.routeSpeech(agent.name, envelope, target);
+                this.recordProseDelivery(agent.name, outcome);
+            }
+            catch (err) {
+                console.error('hybrid locus delivery failed:', err);
+            }
+        }
+    }
     async deliverProseEnvelope(agent, rawText) {
         const name = agent.name;
         const parsed = parseProsePrefix(rawText);
@@ -4365,7 +4498,7 @@ export class AgentFramework {
     }
     /** Cap on consecutive bounce-triggered wakes (notices still append after). */
     static PROSE_BOUNCE_WAKE_CAP = 2;
-    bounceProse(agent, text, reason, candidates) {
+    bounceProse(agent, text, reason, candidates, prefix = '>>') {
         const name = agent.name;
         this.proseClipboards.set(name, text);
         const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
@@ -4373,8 +4506,9 @@ export class AgentFramework {
         const cand = candidates?.length ? ` Known channels it could mean: ${candidates.join(', ')}.` : '';
         const notice = `[prose-routing] Your text (${text.length} chars) was not delivered — ${reason}.${cand} ` +
             'The text is retained; nothing is lost. To deliver it unchanged, reply with a ' +
-            'destination plus the token {{unsent}}, e.g. ">>#channel {{unsent}}" or ">>@person {{unsent}}". ' +
-            '">>skip_reply {{unsent}}" keeps it in context only. The prose_help tool shows the full syntax.';
+            `destination plus the token {{unsent}}, e.g. "${prefix}#channel {{unsent}}" or "${prefix}@person {{unsent}}". ` +
+            `"${prefix}skip_reply {{unsent}}" keeps it in context only.` +
+            (prefix === '>>' ? ' The prose_help tool shows the full syntax.' : '');
         try {
             // Through framework.addMessage, NOT the context manager directly: while
             // the turn is still streaming this defers the notice to the next tool
@@ -4563,6 +4697,9 @@ export class AgentFramework {
             this.turnEngagedChannels.delete(agent.name);
             this.turnProseDeliveries.delete(agent.name);
             this.turnProseSuppressed.delete(agent.name);
+            this.proseHybridSuppressed.delete(agent.name);
+            if (agent.proseRouting === 'hybrid')
+                this.proseTargetPins.delete(agent.name);
             if (agent.proseRouting === 'explicit') {
                 // Explicit prose routing: there is no locus. The model names every
                 // destination in-band (`>>` prefixes); the only turn state is the
@@ -4801,7 +4938,7 @@ export class AgentFramework {
         });
         const proseStream = this.channelRegistry
             ? new ProseStreamRouter({
-                mode: agent.proseRouting === 'explicit' ? 'explicit' : 'locus',
+                mode: agent.proseRouting === 'explicit' ? 'explicit' : agent.proseRouting === 'hybrid' ? 'hybrid' : 'locus',
                 initialTarget: typingChannel,
                 resolve: (spec) => {
                     const r = this.channelRegistry.resolveProseTarget(spec);
@@ -4917,9 +5054,17 @@ export class AgentFramework {
                             const rawXml = rawText && /^<(antml:)?function_calls>/.test(rawText)
                                 ? rawText
                                 : undefined;
+                            // Persist THIS round's text only. `roundPreamble` (membrane
+                            // ≥0.5.79) is the per-round delta; the legacy `preamble` is
+                            // CUMULATIVE in XML mode — persisting it per round stored each
+                            // round's text N times and re-persisted injected
+                            // <function_results> as the agent's own words (the Evander
+                            // 2026-08-08 scaffold-leak pyramid: r1 ×3, r2 ×2).
+                            const roundText = event.context.roundPreamble ??
+                                event.context.preamble;
                             assistantBlocks = [];
-                            if (event.context.preamble) {
-                                assistantBlocks.push({ type: 'text', text: event.context.preamble });
+                            if (roundText) {
+                                assistantBlocks.push({ type: 'text', text: roundText });
                             }
                             for (const c of event.calls) {
                                 assistantBlocks.push({
@@ -4956,14 +5101,28 @@ export class AgentFramework {
                             const roundToolNames = event.calls.map((c) => c.name);
                             const hasSameRoundPrivateThink = roundToolNames.includes('think') &&
                                 requestSnapshot.sameRoundThinkTextPolicy === 'private';
-                            if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)))) {
+                            if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)) ||
+                                (agent.proseRouting === 'hybrid' && HYBRID_PUBLICATION_TOOLS.has(bareToolName(n))))) {
                                 turnSilenced = true;
                             }
                             if (roundContent && roundContent.length > 0) {
                                 liveProseRouting = true;
                                 const roundSegments = splitProseSegments(assistantBlocks);
                                 if (roundSegments.length > 0) {
-                                    if (agent.proseRouting === 'explicit') {
+                                    if (agent.proseRouting === 'hybrid') {
+                                        if (turnSilenced) {
+                                            this.recordProseSuppression(agent.name, roundSegments.length);
+                                        }
+                                        else if (!hasSameRoundPrivateThink) {
+                                            const locus = resolveTurnLocus();
+                                            for (const seg of roundSegments) {
+                                                turnSpeechChain = turnSpeechChain
+                                                    .then(() => this.deliverHybridProse(agent, seg, locus, true))
+                                                    .catch((err) => console.error('mid-turn hybrid prose delivery failed:', err));
+                                            }
+                                        }
+                                    }
+                                    else if (agent.proseRouting === 'explicit') {
                                         // Explicit mode: every segment through the prose gateway.
                                         // Silencing does not apply — unprefixed prose bounces and
                                         // prefixed prose is deliberate; think-privacy still holds.
@@ -5243,7 +5402,17 @@ export class AgentFramework {
                                 .join('\n')
                                 .trim();
                             if (speechText) {
-                                if (agent.proseRouting === 'explicit') {
+                                if (agent.proseRouting === 'hybrid') {
+                                    const locus = resolveTurnLocus();
+                                    console.error(`[prose] ${agent.name}: text-only turn -> hybrid prose gateway`);
+                                    try {
+                                        await this.deliverHybridProse(agent, speechText, locus, true);
+                                    }
+                                    catch (err) {
+                                        console.error('text-only hybrid prose delivery failed:', err);
+                                    }
+                                }
+                                else if (agent.proseRouting === 'explicit') {
                                     console.error(`[prose] ${agent.name}: text-only turn -> prose gateway`);
                                     try {
                                         await this.deliverProse(agent, speechText);
@@ -5292,13 +5461,30 @@ export class AgentFramework {
                                 .filter((n) => typeof n === 'string');
                             const silenced = liveProseRouting
                                 ? turnSilenced
-                                : turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
+                                : turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)) ||
+                                    (agent.proseRouting === 'hybrid' && HYBRID_PUBLICATION_TOOLS.has(bareToolName(n))));
                             const segments = splitProseSegments(liveProseRouting ? terminalContent : response.content);
                             // Preserve in-channel ordering: everything enqueued live must
                             // land before the trailing prose. Awaited even when silenced —
                             // the chain may still be flushing earlier rounds' posts.
                             await turnSpeechChain;
-                            if (agent.proseRouting === 'explicit') {
+                            if (agent.proseRouting === 'hybrid') {
+                                if (silenced && segments.length > 0) {
+                                    this.recordProseSuppression(agent.name, segments.length);
+                                }
+                                else if (segments.length > 0) {
+                                    const locus = resolveTurnLocus();
+                                    for (const seg of segments) {
+                                        try {
+                                            await this.deliverHybridProse(agent, seg, locus, true);
+                                        }
+                                        catch (err) {
+                                            console.error('trailing hybrid prose delivery failed:', err);
+                                        }
+                                    }
+                                }
+                            }
+                            else if (agent.proseRouting === 'explicit') {
                                 if (segments.length > 0) {
                                     console.error(`[prose] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> ${segments.length} trailing segment(s) via prose gateway`);
                                     for (const seg of segments) {
@@ -6082,6 +6268,9 @@ export class AgentFramework {
         const blocks = toolResults.map(tc => ({
             type: 'tool_result',
             toolUseId: tc.id,
+            // Persisted so XML replay can reconstruct the legacy <tool_name>
+            // element byte-identically to the live injection.
+            toolName: tc.name,
             content: spilled.get(tc.id).text,
             isError: tc.result.isError,
         }));
@@ -6316,7 +6505,7 @@ export class AgentFramework {
     /**
      * Effective tool-result inline cap for an agent, with provenance. Desired
      * value: resident's durable agent_settings value → residence
-     * FrameworkConfig.toolResultInlineMaxChars → house default (5000).
+     * FrameworkConfig.toolResultInlineMaxChars → house default (24000).
      * Effective value: min(desired, strategy bound) for EVERY source — the
      * strategy's per-message safety limit is a ceiling, not a suggestion
      * (Sol's #94 ruling: a durable preference must not be a durable path for
@@ -8520,17 +8709,70 @@ export class AgentFramework {
                 : input.rateLimit !== undefined ? { rate_limit: input.rateLimit }
                     : input.passiveSample !== undefined ? { passive_sample: input.passiveSample }
                         : input.behavior;
-            const position = input.position === 'prepend' ? 'prepend' : 'append';
+            // Placement: at most one of position / insertBefore / insertAfter.
+            // With none given, a replaced rule stays where it was and a new rule
+            // appends (addPolicy's contract).
+            const placementSources = [
+                input.position !== undefined ? 'position' : null,
+                input.insertBefore !== undefined ? 'insertBefore' : null,
+                input.insertAfter !== undefined ? 'insertAfter' : null,
+            ].filter((s) => s !== null);
+            if (placementSources.length > 1) {
+                finish({
+                    success: false,
+                    error: `wake_add_rule: give at most one placement, got [${placementSources.join(', ')}].`,
+                    isError: true,
+                });
+                return;
+            }
+            let position;
+            if (typeof input.insertBefore === 'string' && input.insertBefore) {
+                position = { before: input.insertBefore };
+            }
+            else if (typeof input.insertAfter === 'string' && input.insertAfter) {
+                position = { after: input.insertAfter };
+            }
+            else if (input.position === 'prepend' || input.position === 'append') {
+                position = input.position;
+            }
             const rawPolicy = {
                 name: input.name,
                 match: input.match ?? {},
                 behavior,
+                ...(input.passthrough !== undefined ? { passthrough: input.passthrough } : {}),
                 ...(input.resets !== undefined ? { resets: input.resets } : {}),
             };
-            const policy = this.addGatePolicy(rawPolicy, { position });
+            // Before/after probe table + shadow lint: the moment a rule changes the
+            // evaluation order is the moment its real semantics must be legible
+            // (af#105 — a prepended catch-all sampler silently disabled the
+            // addressed-message wakes for 12h before anyone could see why).
+            const before = new Map(this.eventGate.probeTable().map((r) => [r.probe, r]));
+            const policy = this.addGatePolicy(rawPolicy, position ? { position } : undefined);
+            const after = this.eventGate.probeTable();
+            const probes = after.map((r) => {
+                const prev = before.get(r.probe);
+                const changed = !!prev && (prev.policy !== r.policy || prev.wouldWake !== r.wouldWake);
+                return {
+                    probe: r.probe,
+                    rule: r.policy ?? '(default)',
+                    behavior: r.behavior,
+                    wouldWake: r.wouldWake,
+                    ...(changed ? { changed: true, was: `${prev.policy ?? '(default)'} (wouldWake=${prev.wouldWake})` } : {}),
+                };
+            });
+            const shadowWarnings = this.eventGate.lintShadows()
+                .map((w) => formatShadowWarning(w));
             finish({
                 success: true,
-                data: { added: policy.name, policies: this.getGatePolicyNames() },
+                data: {
+                    added: policy.name,
+                    policies: this.getGatePolicyNames(),
+                    ...(shadowWarnings.length > 0 ? { shadowWarnings } : {}),
+                    probes,
+                    ...(probes.some((p) => 'changed' in p)
+                        ? {}
+                        : { note: 'No canonical probe changed its winning rule — the new rule affects none of the common chat/heartbeat shapes, or only channel/path-specific events the probes do not model.' }),
+                },
             });
         }
         catch (err) {