instar 1.3.165 → 1.3.166

package/dist/messaging/installAgentMessageHook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installAgentMessageHook.d.ts","sourceRoot":"","sources":["../../src/messaging/installAgentMessageHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;oFACoF;AACpF,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7G,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,gBAAgB,CAAC;IAC/B;;sDAEkD;IAClD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,2BAA2B,GAAG,gBAAgB,CAuFzF"}
+{"version":3,"file":"installAgentMessageHook.d.ts","sourceRoot":"","sources":["../../src/messaging/installAgentMessageHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;oFACoF;AACpF,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7G,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,gBAAgB,CAAC;IAC/B;;sDAEkD;IAClD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,2BAA2B,GAAG,gBAAgB,CAkGzF"}

package/dist/messaging/installAgentMessageHook.js

@@ -83,16 +83,26 @@ export function buildAgentMessageHook(deps) {
             telegramSenderChatId: input.senderChatId,
             topicId: input.topicId,
         });
-        try {
-            await handler(msg, { topicId: input.topicId, senderBotId: input.senderBotId });
-        }
-        catch (err) {
-            // A role-handler failure is recorded but doesn't un-mark the id (we still treat
-            // the message as processed; retrying would just re-fail). Stage-B forensics can see
-            // the routed row + the absence of a downstream effect.
+        // Accept-boundary (the #581 / #3 class — this is the THIRD a2a path): a role
+        // handler (e.g. the mentee mentor-message handler) SPAWNS a session and
+        // bounded-waits for the reply — that can take MINUTES — and delivers its
+        // reply OUT via a separate a2a message, not this HTTP response. AWAITING it
+        // here meant the caller's /a2a/inbox POST waited the full handler, so the
+        // sender's ~10s `AbortSignal.timeout` fired and logged a FALSE "local-inbox
+        // delivery attempt failed" (the message was in fact accepted — its id is
+        // marked processed above — and the reply will arrive on its own channel).
+        // Respond ACCEPTED immediately and run the handler in the background. The
+        // idempotency mark above still dedups any retry; a handler failure is caught
+        // + logged async (it can't reject a response that already returned).
+        void Promise.resolve()
+            .then(() => handler(msg, { topicId: input.topicId, senderBotId: input.senderBotId }))
+            .catch((err) => {
+            // A role-handler failure is recorded but doesn't un-mark the id (we still
+            // treat the message as processed; retrying would just re-fail). Stage-B
+            // forensics can see the routed row + the absence of a downstream effect.
             // eslint-disable-next-line no-console
             console.error(`[a2a] role-handler "${msg.role}" failed:`, err instanceof Error ? err.message : String(err));
-        }
+        });
         return { handled: true };
     };
 }

package/dist/messaging/installAgentMessageHook.js.map

@@ -1 +1 @@
-{"version":3,"file":"installAgentMessageHook.js","sourceRoot":"","sources":["../../src/messaging/installAgentMessageHook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"installAgentMessageHook.js","sourceRoot":"","sources":["../../src/messaging/installAgentMessageHook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.165",
+  "version": "1.3.166",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-31T11:39:31.391Z",
-  "instarVersion": "1.3.165",
+  "generatedAt": "2026-05-31T12:02:03.497Z",
+  "instarVersion": "1.3.166",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.166.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What to Tell Your User
+
+If you run multiple agents that talk to each other, you'll stop seeing spurious "delivery failed" timeouts in the logs for messages that actually went through fine. The receiving agent now confirms it got the message right away and does the work in the background, and the reply still comes back as normal.
+
+## Summary of New Capabilities
+
+- The agent-to-agent inbox hook (the third and last of the agent-to-agent transports) now responds at the accept boundary: it acknowledges immediately after validating the message and runs the (potentially minutes-long) handler in the background, instead of making the sender wait through it. Completes the same fix already shipped for the co-located relay and the cross-machine threadline paths.
+
+## Evidence
+
+- Found in the agent's own server log: recurring "[a2a] local-inbox delivery attempt failed (to=instar-codey): aborted due to timeout".
+- Root traced through the call chain: the /a2a/inbox response awaited the role handler, which spawns a session and waits minutes; the sender's ~10s timeout fired first. The reply flows back on a separate channel, so awaiting was unnecessary.
+- Unit tests: a held (slow) handler no longer blocks the response (it would have hung if still awaited); a background handler error still yields a clean acknowledgement. Idempotency, validation, and spoof-defense cases unchanged. Independent adversarial review.
+
+## What Changed — Agent-to-agent task delivery no longer logs false "delivery failed" timeouts
+
+When one of your agents hands a task to another agent on the same machine (for example a mentor agent assigning work to a mentee), the receiver was only acknowledging the message AFTER it had finished the whole task — which means spinning up a work session and waiting minutes for it to think and reply. But the sender only waits about 10 seconds for an acknowledgement, so it gave up and logged a "delivery failed" every time — even though the message was actually received fine and the reply was on its way back on a separate channel.
+
+Now the receiver acknowledges the moment it accepts the message and does the work in the background. The sender gets its acknowledgement right away, stops logging false failures, and stops holding a connection open for ten seconds each time. The actual reply still comes back exactly as before.

package/upgrades/side-effects/a2a-inbox-accept-boundary.md

@@ -0,0 +1,40 @@
+# Side-effects — /a2a/inbox accept-boundary
+
+## 1. What files/state does this touch at runtime?
+`installAgentMessageHook.ts` — the role-handler invocation in the agent-message hook. No new files,
+config, schema, or state. The role handler still runs (now in the background); the idempotency mark
+and ledger row are unchanged.
+
+## 2. Does it change any functional behavior?
+The `/a2a/inbox` HTTP response now returns `{handled:true}` immediately after the message is validated
++ marked processed, instead of after the (minutes-long) role handler completes. The handler runs in
+the background and delivers its reply on its own a2a channel exactly as before. Net: the sender no
+longer times out (its ~10s `AbortSignal.timeout`) and no longer logs a false "delivery failed".
+
+## 3. What happens on failure / weird config?
+A background handler rejection is caught and logged (`console.error`), exactly as the old `try/catch`
+did — just on a later microtask. The id stays marked processed (unchanged). Validation failures
+(unknown role, spoof, already-processed) still short-circuit BEFORE the handler, unchanged.
+
+## 4. Migration parity — do existing agents get it?
+Yes, via the normal release — code-only, compiled into `dist`. No agent-installed file / config /
+template change → no `PostUpdateMigrator` pass.
+
+## 5. Could it spam / flood / burn resources?
+No — it REDUCES resource use (no 10s held connection per mentor a2a message). Same single handler
+run, no new timers/IO/network. The idempotency mark still bounds duplicate processing.
+
+## 6. Rollback / off-switch?
+Revert the one block (re-`await` the handler). No data, no migration, no flag. Mirrors #581/#3
+rollback.
+
+## 7. Concurrency / ordering?
+The handler now runs after the response returns instead of before. The idempotency `markProcessed`
+still happens BEFORE the response (so retries dedup). The reply-out is unchanged (a separate a2a
+send). A background handler error cannot affect the already-sent response.
+
+## Blast radius
+Small + additive: one block in `installAgentMessageHook.ts` swapped from await-then-respond to
+respond-then-background. Exactly mirrors the proven #581 (`/messages/relay-agent`) and #3
+(`/threadline/messages/receive`) accept-boundaries. Only the a2a role-handler dispatch timing
+changes; validation, idempotency, ledger, and the reply path are untouched.