@parall/parel-channel 1.38.0 → 1.40.0

package/dist/channel-prompt.d.ts

@@ -1,5 +1,15 @@
 /**
- * Prompt framing for external IM channel messages (channel_message
+ * Prompt framing for inbound messages.
+ *
+ * Chat messages (buildChatPrompt): under `main` channel routing every Parall
+ * chat shares the agent's ONE parel session, so consecutive turns can come
+ * from different conversations — each message is framed with its originating
+ * chat so the model registers the context switch instead of answering chat B
+ * with chat A's thread of thought. No reply hint: the turn-end reply is
+ * auto-delivered to the right chat by replyRoute (deliver()), and sandbox CLI
+ * calls get the right PRLL_CHAT_ID via per-turn invocation context.
+ *
+ * External IM channel messages (buildChannelPrompt, channel_message
  * dispatches). Mirrors agent-core's event-format.ts channel branch, adapted
  * to the parel runtime's tool surface:
  *
@@ -15,6 +25,23 @@
  *   form ({"message_id": …}) so threaded conversations aren't nudged toward
  *   new top-level messages.
  */
+export interface ChatPromptArgs {
+    chatId: string;
+    /** Display name of the chat; undefined when unresolved (best-effort). */
+    chatName?: string;
+    /** Sender user id (usr_); display-name enrichment is a follow-up. */
+    senderId?: string;
+    threadRootId?: string;
+    /** The inbound message text (raw, un-framed). */
+    text: string;
+}
+/**
+ * Frame a Parall chat message with its conversation of origin. Kept to a
+ * minimal metadata header: the text itself is the user message, and heavier
+ * context (unread counts, membership) is the standard runtimes' enrichment —
+ * not re-created here.
+ */
+export declare function buildChatPrompt(args: ChatPromptArgs): string;
 export interface ChannelPromptArgs {
     /** Provider name (= clip alias, e.g. "feishu"); undefined when unresolved. */
     provider?: string;

package/dist/channel-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-prompt.d.ts","sourceRoot":"","sources":["../src/channel-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAkBlE"}
+{"version":3,"file":"channel-prompt.d.ts","sourceRoot":"","sources":["../src/channel-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAS5D;AAED,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAkBlE"}

package/dist/channel-prompt.js

@@ -1,5 +1,15 @@
 /**
- * Prompt framing for external IM channel messages (channel_message
+ * Prompt framing for inbound messages.
+ *
+ * Chat messages (buildChatPrompt): under `main` channel routing every Parall
+ * chat shares the agent's ONE parel session, so consecutive turns can come
+ * from different conversations — each message is framed with its originating
+ * chat so the model registers the context switch instead of answering chat B
+ * with chat A's thread of thought. No reply hint: the turn-end reply is
+ * auto-delivered to the right chat by replyRoute (deliver()), and sandbox CLI
+ * calls get the right PRLL_CHAT_ID via per-turn invocation context.
+ *
+ * External IM channel messages (buildChannelPrompt, channel_message
  * dispatches). Mirrors agent-core's event-format.ts channel branch, adapted
  * to the parel runtime's tool surface:
  *
@@ -21,6 +31,24 @@ function sanitizeMeta(value) {
         .replace(/[[\]|]/g, ' ')
         .trim();
 }
+/**
+ * Frame a Parall chat message with its conversation of origin. Kept to a
+ * minimal metadata header: the text itself is the user message, and heavier
+ * context (unread counts, membership) is the standard runtimes' enrichment —
+ * not re-created here.
+ */
+export function buildChatPrompt(args) {
+    const chatLabel = args.chatName
+        ? `${sanitizeMeta(args.chatId)} — ${sanitizeMeta(args.chatName)}`
+        : sanitizeMeta(args.chatId);
+    const lines = [`[Chat: ${chatLabel}]`];
+    if (args.senderId)
+        lines.push(`[From: ${sanitizeMeta(args.senderId)}]`);
+    if (args.threadRootId)
+        lines.push(`[Thread: ${sanitizeMeta(args.threadRootId)}]`);
+    lines.push('', args.text);
+    return lines.join('\n');
+}
 export function buildChannelPrompt(args) {
     const providerLabel = sanitizeMeta(args.provider ?? 'external IM');
     const convLabel = args.externalConversationId

package/dist/delivery.js

@@ -1,5 +1,5 @@
 import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
-import { ensureSession, invalidateSession, patchSession, REQUEST_TIMEOUT_MS, turnEnvelopeKey, } from './session.js';
+import { ensureSession, invalidateSession, patchSession, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, } from './session.js';
 /**
  * Post the agent's reply back to the Parall chat. The chat id rides the
  * replyRoute.data set in inbound.ts.
@@ -34,9 +34,9 @@ export async function buildParallDelivery(delivery, ctx) {
         // not the reply). Only run the redundant idle so a binding without
         // `observe: [turn]` still closes the session.
         if (route.conversationId) {
-            const sessionId = await ensureSession(ctx, route.conversationId, { timeoutMs: 3_000 });
+            const sessionId = await ensureSession(ctx, { timeoutMs: 3_000 });
             if (sessionId) {
-                await idleUnlessSuperseded(ctx, route.conversationId, route.envelopeId, sessionId);
+                await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
             }
         }
         return [];
@@ -46,9 +46,9 @@ export async function buildParallDelivery(delivery, ctx) {
     if (!text)
         return [];
     // Short timeout: this sits in front of the user-visible reply POST. Cache
-    // hit (every message after a chat's first) is a store read; on a slow miss
-    // we degrade to a reply without the session link rather than delay it.
-    const sessionId = await ensureSession(ctx, chatId, { timeoutMs: 3_000 });
+    // hit (every dispatch after the agent's first) is a store read; on a slow
+    // miss we degrade to a reply without the session link rather than delay it.
+    const sessionId = await ensureSession(ctx, { timeoutMs: 3_000 });
     const request = {
         url: `${apiUrl}/api/v1/orgs/${orgId}/chats/${chatId}/messages`,
         method: 'POST',
@@ -101,20 +101,21 @@ export async function buildParallDelivery(delivery, ctx) {
     // run the same turnEnvelope staleness guard and idle is idempotent, so the
     // overlap is harmless.
     if (sessionId) {
-        await idleUnlessSuperseded(ctx, chatId, route.envelopeId, sessionId);
+        await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
     }
     return [];
 }
 /**
- * Idle the subject's session unless a newer envelope owns the turn (the same
- * turnEnvelope staleness guard onAgentEvent runs). Fail-open when the marker
- * is unavailable — a stuck ring is worse than a blink.
+ * Idle the agent's main session unless a newer envelope owns the turn (the
+ * same agent-global turnEnvelope staleness guard onAgentEvent runs — any
+ * chat's later message supersedes this turn's idle). Fail-open when the
+ * marker is unavailable — a stuck ring is worse than a blink.
  */
-async function idleUnlessSuperseded(ctx, subject, envelopeId, sessionId) {
-    const current = await ctx.store?.get(turnEnvelopeKey(subject)).catch(() => null);
+async function idleUnlessSuperseded(ctx, envelopeId, sessionId) {
+    const current = await ctx.store?.get(TURN_ENVELOPE_KEY).catch(() => null);
     if (!(typeof current === 'string' && current) || !envelopeId || current === envelopeId) {
         const result = await patchSession(ctx, sessionId, { status: 'idle' });
         if (result === 'stale')
-            await invalidateSession(ctx, subject);
+            await invalidateSession(ctx);
     }
 }

package/dist/inbound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AA4C3B,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB5B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAiFrF;AA+XD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA2C7B"}
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAiD3B,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB5B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAuDrF;AAkdD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyD7B"}

package/dist/inbound.js

@@ -1,6 +1,6 @@
-import { buildChannelPrompt } from './channel-prompt.js';
+import { buildChannelPrompt, buildChatPrompt } from './channel-prompt.js';
 import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
-import { createChannelInputStep, createInputStep, createTraceStep, ensureSession, invalidateSession, markDispatchReceived, patchSession, REQUEST_TIMEOUT_MS, turnEnvelopeKey, } from './session.js';
+import { createChannelInputStep, createErrorStep, createInputStep, createTraceStep, ensureSession, invalidateSession, markDispatchReceived, patchSession, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, } from './session.js';
 export async function handleParallFrame(frame, ctx) {
     let event;
     try {
@@ -52,48 +52,21 @@ export async function catchUpParall(ctx) {
             if (!res.ok)
                 break;
             const body = (await res.json().catch(() => null));
-            // Same-chat dispatches run SEQUENTIALLY (session reporting PATCHes one
-            // shared session per chat — concurrent replay would let an older
-            // dispatch overwrite trigger_message_id after a newer one and reorder
-            // input steps); different chats still run concurrently. Page order is
-            // FIFO, so per-chat envelope order is preserved. A failed dispatch
-            // resolves to [] and stays pending for the next sweep.
-            //
-            // channel_message dispatches carry no chat_id and their conversation
-            // (the session key) is only known after fetching the message — so they
-            // all share ONE sequential chain: per-conversation order is preserved
-            // at the cost of serializing across conversations, which is fine for
-            // the small external-IM backlogs a reconnect sweep sees.
-            const byChat = new Map();
-            const unkeyed = [];
+            // ALL dispatches replay SEQUENTIALLY, in page order (FIFO): every
+            // envelope feeds the agent's one main session, so cross-chat replay
+            // concurrency would scramble the session's input order AND race the
+            // agent-global turnEnvelope marker (a slower old dispatch could
+            // overwrite a newer one's marker and mis-arm the done-signal guard).
+            // Reconnect backlogs are small; serialization is the correctness
+            // posture, not a throughput concern. A failed dispatch resolves to []
+            // and stays pending for the next sweep.
             for (const d of body?.data ?? []) {
-                const cid = String(d.source_type ?? '') === 'channel_message'
-                    ? CHANNEL_SWEEP_CHAIN
-                    : d.chat_id
-                        ? String(d.chat_id)
-                        : '';
-                if (!cid) {
-                    unkeyed.push(d);
-                    continue;
-                }
-                const group = byChat.get(cid);
-                if (group)
-                    group.push(d);
-                else
-                    byChat.set(cid, [d]);
+                const out = await effectsForDispatch(d, ctx).catch((err) => {
+                    console.error('[parel-channel] catch-up dispatch failed', err);
+                    return [];
+                });
+                effects.push(...out);
             }
-            const runOne = (d) => effectsForDispatch(d, ctx).catch((err) => {
-                console.error('[parel-channel] catch-up dispatch failed', err);
-                return [];
-            });
-            const chains = [...byChat.values()].map(async (group) => {
-                const out = [];
-                for (const d of group)
-                    out.push(...(await runOne(d)));
-                return out;
-            });
-            const pageEffects = await Promise.all([...chains, ...unkeyed.map(runOne)]);
-            effects.push(...pageEffects.flat());
             if (!body?.next_cursor)
                 break;
             cursor = body.next_cursor;
@@ -109,11 +82,6 @@ export async function catchUpParall(ctx) {
     }
     return effects;
 }
-/**
- * Synthetic sweep group key for channel_message dispatches (no chat_id).
- * Chat ids are cht_-prefixed nanoids, so this cannot collide with one.
- */
-const CHANNEL_SWEEP_CHAIN = 'sweep:channel_message';
 async function effectsForDispatch(data, ctx) {
     const sourceType = String(data.source_type ?? '');
     const sourceId = data.source_id ? String(data.source_id) : undefined;
@@ -171,16 +139,18 @@ async function effectsForDispatch(data, ctx) {
     // pending ring (a later successful turn's idle clears agent-level pendings).
     const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
     const envelopeId = dispatchId || `${sourceType}:${sourceId}`;
-    let sessionId = await ensureSession(ctx, chatId);
+    let sessionId = await ensureSession(ctx);
     if (sessionId) {
         // The guard marker goes down BEFORE any session write: a stale
         // turn_completed for the PREVIOUS turn (outbox retry, late event) checks
         // turnEnvelope to decide whether its idle is still safe — if the active
         // patch below could land first, that event would still see the old
-        // envelope id and idle the session out from under this message.
+        // envelope id and idle the session out from under this message. The
+        // marker is agent-global: chats share the one main session, so a chat-A
+        // done signal must not idle it while this (later) message is pending.
         // (Residual read-then-patch overlap is zero when the host runs a
         // connection's hooks serially, per the C3 contract / C3b confirm item.)
-        await ctx.store?.set(turnEnvelopeKey(chatId), envelopeId).catch(() => { });
+        await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => { });
         const report = (sid) => Promise.all([
             patchSession(ctx, sid, { status: 'active', trigger_message_id: sourceId }),
             createInputStep(ctx, sid, {
@@ -195,8 +165,8 @@ async function effectsForDispatch(data, ctx) {
             // The cached session was closed under us (e.g. New Session). The
             // get-or-create falls through terminal rows, so one rebuild + retry
             // repairs reporting for this and every later dispatch.
-            await invalidateSession(ctx, chatId);
-            const fresh = await ensureSession(ctx, chatId);
+            await invalidateSession(ctx);
+            const fresh = await ensureSession(ctx);
             if (fresh && fresh !== sessionId) {
                 await report(fresh);
                 sessionId = fresh;
@@ -212,6 +182,22 @@ async function effectsForDispatch(data, ctx) {
         PRLL_TRIGGER_MESSAGE_ID: sourceId,
         ...(threadRootId ? { PRLL_THREAD_ROOT_ID: threadRootId } : {}),
     };
+    // Frame the message with its chat of origin: all chats share the agent's
+    // one main session, so the model must see WHERE each message comes from or
+    // it answers chat B inside chat A's train of thought. The name is cosmetic
+    // garnish and must never block the emit/ack hot path (the catch-up sweep is
+    // fully serialized — one slow lookup would stall the whole backlog): only
+    // the cached name is used, and a miss kicks off a fire-and-forget prefetch
+    // so the NEXT message from this chat gets the name. The id alone already
+    // marks the context switch.
+    const chatName = await cachedChatName(ctx, chatId);
+    const framedText = buildChatPrompt({
+        chatId,
+        chatName,
+        senderId: msg?.sender_id ? String(msg.sender_id) : undefined,
+        threadRootId,
+        text,
+    });
     const effects = [
         {
             type: 'emitEvent',
@@ -221,10 +207,12 @@ async function effectsForDispatch(data, ctx) {
                 connectionId: ctx.connectionId,
                 source: 'parall',
                 type: 'message',
-                // per_subject routing keys the parel session by subject → one parel
-                // session per Parall chat (mirrors Parall's chat-scoped conversations).
+                // The binding's `main` routing sends every envelope to the agent's
+                // one session; subject still carries the chat so parel's turn input
+                // grouping (F2) never mixes conversations in one turn and agent
+                // events mirror it back for per-chat correlation.
                 subject: chatId,
-                data: { text, chatId, messageId: sourceId, threadRootId },
+                data: { text: framedText, chatId, messageId: sourceId, threadRootId },
                 // chat id + thread anchor ride replyRoute.data so deliver() knows
                 // where to post back (same shape channel-slack-socket uses for its
                 // channel id).
@@ -308,9 +296,9 @@ async function effectsForChannelDispatch(sourceId, dispatchId, ctx) {
     // returned; the turnEnvelope marker goes down before any session write.
     const receivedSettled = markDispatchReceived(ctx, 'channel_message', sourceId);
     const envelopeId = dispatchId || `channel_message:${sourceId}`;
-    let sessionId = await ensureSession(ctx, conversationId);
+    let sessionId = await ensureSession(ctx);
     if (sessionId) {
-        await ctx.store?.set(turnEnvelopeKey(conversationId), envelopeId).catch(() => { });
+        await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => { });
         const report = (sid) => Promise.all([
             patchSession(ctx, sid, { status: 'active', trigger_message_id: sourceId }),
             createChannelInputStep(ctx, sid, {
@@ -326,8 +314,8 @@ async function effectsForChannelDispatch(sourceId, dispatchId, ctx) {
         ]);
         const results = await report(sessionId);
         if (results.includes('stale')) {
-            await invalidateSession(ctx, conversationId);
-            const fresh = await ensureSession(ctx, conversationId);
+            await invalidateSession(ctx);
+            const fresh = await ensureSession(ctx);
             if (fresh && fresh !== sessionId) {
                 await report(fresh);
                 sessionId = fresh;
@@ -354,9 +342,9 @@ async function effectsForChannelDispatch(sourceId, dispatchId, ctx) {
                 // message — the external-audience framing rides inside it (parel has
                 // no separate prompt channel), so 'message' is the right type here.
                 type: 'message',
-                // per_subject routing keys the parel session by subject → one parel
-                // session per external conversation (mirrors chv_ ↔ session 1:1 in
-                // the design).
+                // main routing sends this to the agent's one session too; subject
+                // still carries the external conversation (chv_) for parel's turn
+                // input grouping (F2) and per-conversation event correlation.
                 subject: conversationId,
                 data: {
                     text: buildChannelPrompt({
@@ -399,6 +387,64 @@ async function effectsForChannelDispatch(sourceId, dispatchId, ctx) {
  * degrades to neutral rather than inventing a clip alias.
  */
 const PROVIDER_LOOKUP_TIMEOUT_MS = 3_000;
+/**
+ * How long a cached chat name is served without revalidation. Chat renames
+ * are rare and the frame is the model's cross-chat context anchor, so serve
+ * stale-while-revalidate: past the TTL the cached name is still returned
+ * immediately (never block the hot path) and a background refresh updates
+ * the row for later messages.
+ */
+const CHAT_NAME_TTL_MS = 60 * 60 * 1000;
+/**
+ * chat id → display name for prompt framing, NON-BLOCKING: returns only what
+ * the durable store already holds; a miss fires a background prefetch (tight
+ * timeout, any failure ignored) so later messages get the name. The first
+ * message from a chat is framed id-only — acceptable, the id is the
+ * correctness anchor and the name is garnish; a blocking lookup here would
+ * sit on the emit/ack hot path and stall the fully-serialized catch-up sweep
+ * one dispatch at a time. DMs have no name — the empty name is cached as a
+ * "resolved, nameless" sentinel so they don't re-prefetch on every message.
+ * Rows carry the fetch timestamp; past CHAT_NAME_TTL_MS the stale name is
+ * served AND revalidated in the background, so a renamed chat converges
+ * within one TTL window. (Pre-TTL rows were plain strings — served once and
+ * upgraded by the same background refresh.)
+ */
+async function cachedChatName(ctx, chatId) {
+    const cacheKey = `chatName:${chatId}`;
+    const cached = await ctx.store?.get(cacheKey).catch(() => null);
+    if (cached &&
+        typeof cached === 'object' &&
+        typeof cached.name === 'string') {
+        const { name, at } = cached;
+        if (typeof at !== 'number' || ctx.now() - at > CHAT_NAME_TTL_MS) {
+            void prefetchChatName(ctx, chatId, cacheKey).catch(() => { });
+        }
+        return name || undefined;
+    }
+    if (typeof cached === 'string') {
+        // Legacy plain-string row: serve it, upgrade to the timestamped shape.
+        void prefetchChatName(ctx, chatId, cacheKey).catch(() => { });
+        return cached || undefined;
+    }
+    void prefetchChatName(ctx, chatId, cacheKey).catch(() => { });
+    return undefined;
+}
+async function prefetchChatName(ctx, chatId, cacheKey) {
+    try {
+        const res = await fetch(`${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/chats/${chatId}`, {
+            headers: { Authorization: `Bearer ${requireAgk(ctx)}` },
+            signal: AbortSignal.timeout(PROVIDER_LOOKUP_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json().catch(() => null));
+        const name = typeof body?.name === 'string' ? body.name : '';
+        await ctx.store?.set(cacheKey, { name, at: ctx.now() }).catch(() => { });
+    }
+    catch {
+        // Cosmetic prefetch — the next message from this chat retries.
+    }
+}
 async function resolveChannelProvider(ctx, connectionId, get) {
     const cacheKey = `channelProvider:${connectionId}`;
     const cached = await ctx.store?.get(cacheKey).catch(() => null);
@@ -467,34 +513,48 @@ export async function handleParallAgentEvent(event, ctx) {
         return [];
     try {
         if (event.type === 'turn_completed' || event.type === 'turn_failed') {
-            // Staleness guard: only idle if this event's turn is still the chat's
-            // latest emitted envelope — a late/retried completed event for a
-            // superseded turn must not clear the newer turn's indicator. Fail-open
+            // Staleness guard: only idle if this event's turn covers the AGENT'S
+            // latest emitted envelope (the marker is agent-global — all chats share
+            // the one main session, so a done signal for chat A's turn must not
+            // clear the indicator while a later chat-B message is queued/running).
+            // A late/retried event for a superseded turn is dropped. Fail-open
             // when the marker is unavailable (a stuck ring is worse than a blink).
-            const current = await ctx.store?.get(turnEnvelopeKey(chatId)).catch(() => null);
+            const current = await ctx.store?.get(TURN_ENVELOPE_KEY).catch(() => null);
             if (typeof current === 'string' && current && !event.envelopeIds.includes(current)) {
                 return [];
             }
-            const sessionId = await ensureSession(ctx, chatId);
+            const sessionId = await ensureSession(ctx);
             if (sessionId) {
+                // Error step BEFORE the idle patch so the panel orders failure →
+                // done; the step is what makes a failed turn visible at all (the
+                // reply never arrives — see createErrorStep).
+                let stale = false;
+                if (event.type === 'turn_failed') {
+                    const stepResult = await createErrorStep(ctx, sessionId, {
+                        subject: chatId,
+                        turnId: event.turnId,
+                        error: event.error,
+                    });
+                    stale = stepResult === 'stale';
+                }
                 const result = await patchSession(ctx, sessionId, { status: 'idle' });
                 // A closed session is already terminal (frontend shows done) — just
                 // drop the cache so the next dispatch resolves a fresh one.
-                if (result === 'stale')
-                    await invalidateSession(ctx, chatId);
+                if (stale || result === 'stale')
+                    await invalidateSession(ctx);
             }
             return [];
         }
         if (event.type === 'model_reasoning' ||
             event.type === 'tool_call' ||
             event.type === 'tool_result') {
-            const sessionId = await ensureSession(ctx, chatId);
+            const sessionId = await ensureSession(ctx);
             if (sessionId) {
                 const result = await createTraceStep(ctx, sessionId, chatId, event);
                 // Dropped step is fine (display feed); uncache so the NEXT event
                 // resolves a live session instead of failing forever.
                 if (result === 'stale')
-                    await invalidateSession(ctx, chatId);
+                    await invalidateSession(ctx);
             }
             return [];
         }

package/dist/session.d.ts

@@ -7,23 +7,32 @@ import type { ConnectorContext } from '@parel/plugin-sdk';
  * Every function catches its own failures and returns a degraded value: the
  * message pipeline (emit / reply) must never block on indicator reporting.
  *
- * Session identity is deterministic — (runtime_type='parel',
- * runtime_session_id=subject), where the subject is the envelope routing key:
- * a chat id (cht_) for Parall chats, or a channel conversation id (chv_) for
- * external IM conversations. per_subject routing already keys one parel
- * session per subject, so the parall-side session mirrors it 1:1 without the
- * connector ever knowing parel's internal session id.
+ * Session identity is deterministic and agent-global — (runtime_type='parel',
+ * runtime_session_id='main'). The binding's `main` routing keys EVERY
+ * envelope to one parel session per agent (the single-orchestrator model,
+ * aligned with the standard runtimes; parel-session-alignment-plan.md), so
+ * the parall-side AgentSession mirrors it 1:1: one ase_ per agent, without
+ * the connector ever knowing parel's internal session id. Envelopes still
+ * carry subject=chatId/chv_ — parel groups a turn's inputs by it (F2) and
+ * mirrors it on agent events, so steps and turn signals stay chat-addressed.
  */
 export declare const REQUEST_TIMEOUT_MS = 10000;
+/** The agent-global runtime session identity under `main` channel routing. */
+export declare const MAIN_SESSION_KEY = "main";
 /** Reporting needs the agent id in the endpoint path; old configs lack it. */
 export declare function reportingEnabled(ctx: ConnectorContext): boolean;
 /**
- * The subject's most recently emitted envelope id — the staleness guard for
+ * The agent's most recently emitted envelope id — the staleness guard for
  * turn-level done signals: a turn_completed/failed whose envelopeIds don't
  * include the current value belongs to a superseded turn and must not idle
- * the session out from under the newer one.
+ * the session out from under the newer one. Agent-global (NOT per-subject):
+ * all chats share the one main session, so a completed turn for chat A must
+ * not idle the session while a later-emitted chat-B message is queued or
+ * running — only the turn covering the LAST emitted envelope may idle.
+ * (Pre-main-routing store keys were `turnEnvelope:{subject}`; those rows are
+ * simply never read again.)
  */
-export declare const turnEnvelopeKey: (subject: string) => string;
+export declare const TURN_ENVELOPE_KEY = "turnEnvelope:main";
 /**
  * 'stale' means the session id no longer accepts writes (closed/superseded —
  * e.g. the New Session control ended it): callers invalidate the cache and
@@ -32,15 +41,16 @@ export declare const turnEnvelopeKey: (subject: string) => string;
  */
 export type ReportResult = 'ok' | 'stale' | 'failed';
 /** Drop the cached session id so the next ensureSession re-resolves it. */
-export declare function invalidateSession(ctx: ConnectorContext, subject: string): Promise<void>;
+export declare function invalidateSession(ctx: ConnectorContext): Promise<void>;
 /**
- * Get-or-create the subject's parall AgentSession (ase_), cached in the
+ * Get-or-create the agent's parall AgentSession (ase_), cached in the
  * durable per-connection store. Returns null when reporting is disabled or
  * the call fails — callers skip their report and move on. Callers on a
  * latency-sensitive path (deliver blocks the user-visible reply on this) pass
  * a shorter timeoutMs; the cache-hit fast path is a store read either way.
+ * (Pre-main-routing store keys were `session:{subject}`; never read again.)
  */
-export declare function ensureSession(ctx: ConnectorContext, subject: string, opts?: {
+export declare function ensureSession(ctx: ConnectorContext, opts?: {
     timeoutMs?: number;
 }): Promise<string | null>;
 /** PATCH the session (status / trigger_message_id). Never throws. */
@@ -77,24 +87,62 @@ export declare function createChannelInputStep(ctx: ConnectorContext, sessionId:
     text: string;
     sentAt?: string;
 }): Promise<ReportResult>;
+/**
+ * Credential redaction for runtime error strings that become user-visible
+ * step content. Two layers: every secret VALUE the connector actually holds
+ * (`ctx.secrets`) is replaced exactly — the strongest guarantee for the
+ * secrets in this connector's scope — then credential-shaped patterns are
+ * masked (parall key prefixes, common vendor prefixes, AWS access key ids,
+ * bearer tokens, and any long unbroken token as a fallback: credentials are
+ * long random strings, while prose and paths break on spaces and slashes
+ * first). Pattern matching can't catch every conceivable secret (e.g. a
+ * short password echoed by a foreign exception), which is the accepted
+ * trade-off for keeping the error text diagnosable — the audience is the
+ * org-internal session panel.
+ */
+export declare function redactSecrets(s: string, knownValues?: string[]): string;
+/**
+ * turn_failed → an error step in the session panel, following the
+ * cross-runtime error-step contract (text step + content.status:'error',
+ * same shape agent-core's dispatch-failure step uses — pinned by
+ * ts/protocol-vectors/agent-steps.json). Without this the turn's failure is
+ * invisible on the parall side: the 2026-07-05 parel regression was fully
+ * silent because this connector dropped event.error.
+ *
+ * The error string comes from parel's runtime (exception messages) — length
+ * is unbounded and it can echo credential-shaped values, so it is redacted
+ * (see redactSecrets) and truncated before leaving the connector.
+ */
+export declare function createErrorStep(ctx: ConnectorContext, sessionId: string, args: {
+    subject: string;
+    turnId: string;
+    error: string;
+}): Promise<ReportResult>;
 /**
  * E2 step-trace events → parall AgentSteps, shaped exactly like agent-core's
  * createRuntimeStep so the session panel renders them identically to CC's.
  * tool_call/tool_result carry a session-scoped idempotency key (events are
- * at-most-once today, but a callId key is free insurance); reasoning has no
- * natural key and parel already aggregates it host-side. The E2 tool_result
- * event has no tool name, so tool_call parks it in the store by callId.
+ * at-most-once today, but the key is free insurance). Provider call ids are
+ * only unique WITHIN a turn, and the shared main session makes step
+ * idempotency agent-wide — so the key is turnId-scoped (`tc:{turnId}:{callId}`),
+ * or two turns that both emit `call_1` would swallow the later step as a
+ * duplicate. Reasoning has no natural key and parel already aggregates it
+ * host-side. The E2 tool_result event has no tool name, so tool_call parks
+ * it in the store by callId.
  */
 export declare function createTraceStep(ctx: ConnectorContext, sessionId: string, subject: string, event: {
     type: 'model_reasoning';
+    turnId?: string;
     text: string;
 } | {
     type: 'tool_call';
+    turnId?: string;
     callId: string;
     name: string;
     input: unknown;
 } | {
     type: 'tool_result';
+    turnId?: string;
     callId: string;
     status: 'ok' | 'error';
     durationMs?: number;

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,WAA8B,CAAC;AAG9E;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC;AAMrD,2EAA2E;AAC3E,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AASD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED,qEAAqE;AACrE,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IAAE,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAAC,YAAY,CAAC,CAgBvB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3E,OAAO,CAAC,YAAY,CAAC,CA8BvB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IACJ,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,YAAY,CAAC,CAsCvB;AAOD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnE;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACJ,OAAO,CAAC,YAAY,CAAC,CAyDvB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,gBAAgB,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}