@parall/parel-channel 1.42.1 → 1.44.0

package/src/channel-capability.ts

@@ -0,0 +1,121 @@
+/**
+ * Channel-capability credential injection — the parel-native form of the
+ * feishu-cli broker (multi-channel-architecture-design §8.3).
+ *
+ * Bridges deliver the capability as a PATH pointer shim that mints a fresh
+ * short-lived tenant token per lark-cli invocation. In parel we control
+ * neither the sandbox PATH nor a bridge process — but we DO control the
+ * per-turn invocation context, which sandbox-e2b flattens into every exec's
+ * env. So the connector mints at emit time and injects the official
+ * LARKSUITE_CLI_* env set: bare `lark-cli` works ambiently for the whole
+ * turn (turn length ≪ token TTL ~2h), the app secret never leaves the
+ * platform, and revocation bites on the next emit's mint (403 → no env).
+ *
+ * The mint endpoint IS the gate (the platform re-evaluates connection state
+ * + flag on every request — the no-drift invariant), so the connector needs
+ * no declaration-plane fetch: a 403 is the revocation signal and is
+ * negative-cached briefly to keep a revoked grant from adding one 403 per
+ * turn.
+ */
+import type { ConnectorContext } from '@parel/plugin-sdk';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+
+const MINT_TIMEOUT_MS = 5_000;
+// Re-mint this long before the token expires so an env set injected at turn
+// start stays valid through a long turn's tail.
+const EXPIRY_SKEW_MS = 10 * 60 * 1000;
+// After a 403 (no grant / revoked / flag off), skip minting for this long —
+// revocation latency stays bounded while per-turn 403 noise does not.
+const DENIED_TTL_MS = 60 * 1000;
+// A GRANTED result is re-validated on the same cadence: the mint endpoint IS
+// the revocation gate, so a positive cache lasting the token TTL (~2h) would
+// extend revocation latency to hours. Re-minting is cheap (the platform
+// Redis-caches the exchanged token and re-evaluates the gate per request);
+// this cache only absorbs bursty emits within a conversation.
+const GRANTED_TTL_MS = 60 * 1000;
+
+interface MintedToken {
+  app_id: string;
+  brand: string;
+  token: string;
+  expires_at: string;
+}
+
+interface CacheEntry {
+  env: Record<string, string> | null; // null = denied (negative cache)
+  validUntil: number;
+}
+
+// Per-connection cache. The plugin isolate is per-connection, so a plain
+// module map keyed by connectionId is effectively single-entry — the key
+// guards against isolate reuse across connections.
+const cache = new Map<string, CacheEntry>();
+
+/** Test hook: the cache is module-level state, so suites reset it between cases. */
+export function resetChannelCapabilityCache(): void {
+  cache.clear();
+}
+
+function envFromMint(minted: MintedToken): Record<string, string> {
+  return {
+    LARKSUITE_CLI_APP_ID: minted.app_id,
+    LARKSUITE_CLI_BRAND: minted.brand || 'feishu',
+    LARKSUITE_CLI_TENANT_ACCESS_TOKEN: minted.token,
+    // Bot lock: the credential is the app's, not a human's — mirror the
+    // bridge shim's injection exactly (agent-core channel-exec).
+    LARKSUITE_CLI_DEFAULT_AS: 'bot',
+    LARKSUITE_CLI_STRICT_MODE: 'bot',
+  };
+}
+
+/**
+ * Returns the feishu-cli env set to spread into an envelope's invocation
+ * context, or null when the capability is not granted (or the mint degraded
+ * — a transient platform error must never block a dispatch emit).
+ */
+export async function channelCapabilityEnv(
+  ctx: ConnectorContext,
+): Promise<Record<string, string> | null> {
+  const key = ctx.connectionId;
+  const now = Date.now();
+  const hit = cache.get(key);
+  if (hit && hit.validUntil > now) return hit.env;
+
+  try {
+    const res = await fetch(
+      `${parallApiUrl(ctx)}/api/v1/orgs/${encodeURIComponent(parallOrgId(ctx))}/agents/me/channel-token`,
+      {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${requireAgk(ctx)}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ channel_type: 'feishu' }),
+        signal: AbortSignal.timeout(MINT_TIMEOUT_MS),
+      },
+    );
+    if (res.status === 403 || res.status === 404) {
+      // No grant (never had it / revoked / flag off) — or an old server
+      // without the endpoint. Same agent-facing outcome: no capability.
+      cache.set(key, { env: null, validUntil: now + DENIED_TTL_MS });
+      return null;
+    }
+    if (!res.ok) {
+      // Transient (5xx/502-mint-upstream): don't cache, don't block the emit.
+      return null;
+    }
+    const minted = (await res.json()) as MintedToken;
+    if (!minted?.token || !minted.app_id) return null;
+    const env = envFromMint(minted);
+    const expiresAt = Date.parse(minted.expires_at);
+    // Bounded by BOTH the revalidation cadence (revocation latency) and the
+    // token's own remaining life (an injected env must outlive the turn).
+    const tokenBound = Number.isFinite(expiresAt) ? expiresAt - EXPIRY_SKEW_MS : now;
+    const validUntil = Math.max(now + 5_000, Math.min(now + GRANTED_TTL_MS, tokenBound));
+    cache.set(key, { env, validUntil });
+    return env;
+  } catch {
+    // Network failure — degrade to "no env this turn"; the next emit retries.
+    return null;
+  }
+}

package/src/channel-prompt.ts

@@ -16,15 +16,15 @@
  *
  * - The audience is OUTSIDE Parall — no prll:// refs, no internal cards or
  *   attachment links in the reply (dead links there).
- * - The reply goes out through the provider clip's `send_message` command.
- *   A parel agent invokes clips from its sandbox via the parall CLI, so the
- *   hint spells out the concrete `parall clip invoke …` command (agent-core
- *   leaves the invocation mechanism to the bridge's own clip tooling).
- * - Provider metadata is best-effort (the connection lookup can fail) —
- *   never instruct the agent to invoke a made-up clip alias.
+ * - Single-path reply (multi-channel-architecture-design §6): with the
+ *   feishu-cli capability granted, the reply goes out through the official
+ *   lark-cli — auth rides the turn's invocation context env
+ *   (channel-capability.ts), so bare `lark-cli` works in the sandbox.
+ *   Without the grant there is no outbound path and the hint says so (the
+ *   provider clip path is retired).
  * - When the inbound external message id is known, offer the in-thread reply
- *   form ({"message_id": …}) so threaded conversations aren't nudged toward
- *   new top-level messages.
+ *   form so threaded conversations aren't nudged toward new top-level
+ *   messages.
  */
 
 function sanitizeMeta(value: string): string {
@@ -90,7 +90,7 @@ export function buildChatPrompt(args: ChatPromptArgs): string {
 }
 
 export interface ChannelPromptArgs {
-  /** Provider name (= clip alias, e.g. "feishu"); undefined when unresolved. */
+  /** Provider name (e.g. "feishu"); undefined when unresolved. */
   provider?: string;
   /** Conversation shape as recorded on the ChannelConversation (dm/group). */
   conversationType?: string;
@@ -99,6 +99,13 @@ export interface ChannelPromptArgs {
   senderName: string;
   /** The inbound message text (raw, un-framed). */
   text: string;
+  /**
+   * Live capability grant: the turn's invocation context carries the minted
+   * LARKSUITE_CLI_* env, so bare `lark-cli` works in the sandbox and is THE
+   * reply path. False → outbound is disabled for this org (no grant); the
+   * hint says so instead of pointing at the retired provider clip.
+   */
+  cliCapable?: boolean;
 }
 
 export function buildChannelPrompt(args: ChannelPromptArgs): string {
@@ -122,16 +129,22 @@ export function buildChannelPrompt(args: ChannelPromptArgs): string {
 }
 
 function buildChannelReplyHint(args: ChannelPromptArgs): string {
-  const target = JSON.stringify({
-    chat_id: args.externalConversationId || '<conversation id>',
-    text: '...',
-  });
-  const threadAlt = args.externalMessageId
-    ? ` To reply in-thread to this specific message, use '${JSON.stringify({ message_id: args.externalMessageId, text: '...' })}' instead.`
-    : '';
-  if (args.provider) {
-    const alias = args.provider;
-    return `\n<system-reminder>To reply, invoke the \`${alias}\` clip's \`send_message\` command from your sandbox: \`parall clip invoke ${alias} send_message '${target}'\` — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider ${alias} API when needed.</system-reminder>`;
+  // Single-path routing (multi-channel-architecture-design §6/§8.3): with
+  // the feishu-cli grant, the minted LARKSUITE_CLI_* env rides this turn's
+  // invocation context, so the official lark-cli works ambiently in the
+  // sandbox and is THE reply path. Without the grant there is no outbound
+  // path — say so instead of pointing at the retired provider clip.
+  // cliCapable alone decides: the mint is feishu-specific, so a successful
+  // grant implies Feishu even when the cosmetic provider-label lookup failed.
+  if (args.cliCapable) {
+    const convRef = args.externalConversationId
+      ? `chat_id "${args.externalConversationId}"`
+      : 'the conversation id named in this event';
+    const threadAlt = args.externalMessageId
+      ? ` To reply threaded to this specific message, reference message_id "${args.externalMessageId}".`
+      : '';
+    return `\n<system-reminder>To reply, use the official Feishu CLI in your sandbox: send a message to ${convRef} with \`lark-cli im\` (see \`lark-cli im --help\` for send syntax; auth is provisioned in your environment — if lark-cli is missing, install it once with \`npm i -g @larksuite/cli\`).${threadAlt} lark-cli is the ONLY outbound path — your plain text output is NOT delivered to the external conversation.</system-reminder>`;
   }
-  return `\n<system-reminder>To reply, invoke your channel provider clip's \`send_message\` command from your sandbox: \`parall clip invoke <alias> send_message '${target}'\` (find the alias with \`parall clip list\`) — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider external platform API when needed.</system-reminder>`;
+  const platform = args.provider ?? 'the external platform';
+  return `\n<system-reminder>This message arrived from ${platform}, but outbound replies are currently disabled for this org (no channel capability granted). Do NOT attempt to reply on the external platform. If action is needed, surface it inside Parall (\`parall messages send\` / \`parall dm\`). Your plain text output is not delivered anywhere.</system-reminder>`;
 }

package/src/delivery.ts

@@ -99,7 +99,7 @@ export async function buildParallDelivery(
   // ON and observe OFF — the platform template always sets both together,
   // so it exists only on a hand-crafted binding.
   if (route.envelopeId) {
-    await completeFencedEnvelopes(ctx, [route.envelopeId]);
+    await completeFencedEnvelopes(ctx, [route.envelopeId], 'ok');
   }
 
   const subject = route.chatId ?? route.conversationId;

package/src/fork.ts

@@ -1,5 +1,7 @@
-import type { ConnectorContext } from '@parel/plugin-sdk';
-import type { AgentEventWithChild, ChildSpawnFailedEvent } from './parel-sdk-compat.js';
+import type { AgentEvent, ConnectorContext } from '@parel/plugin-sdk';
+
+/** The child-spawn failure variant of the sdk's AgentEvent union. */
+type ChildSpawnFailedEvent = Extract<AgentEvent, { type: 'child_spawn_failed' }>;
 
 /**
  * Fork-on-busy scheduling (the parall-side half of parel F4, parel-mono #140;
@@ -298,10 +300,7 @@ export async function clearForkState(ctx: ConnectorContext): Promise<string[]> {
  * Track main-session busyness from the E1 turn stream. Child events (they
  * carry childRef) must NOT feed this — only the main session's turns do.
  */
-export async function noteMainTurnEvent(
-  ctx: ConnectorContext,
-  event: AgentEventWithChild,
-): Promise<void> {
+export async function noteMainTurnEvent(ctx: ConnectorContext, event: AgentEvent): Promise<void> {
   if (event.type === 'turn_started') {
     const row: MainTurnRow = { turnId: event.turnId, subject: event.subject, at: ctx.now() };
     await ctx.store?.set(MAIN_TURN_KEY, row).catch(() => {});
@@ -323,7 +322,7 @@ export async function noteMainTurnEvent(
  */
 export async function settleChildEvent(
   ctx: ConnectorContext,
-  event: AgentEventWithChild,
+  event: AgentEvent,
 ): Promise<{ subject: string; pendingAcks: PendingAck[] } | null> {
   const childRef = event.childRef;
   if (!childRef) return null;

package/src/inbound-channel.ts

@@ -1,12 +1,13 @@
 import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+import { channelCapabilityEnv } from './channel-capability.js';
 import { buildChannelPrompt } from './channel-prompt.js';
 import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
 import {
-  ackEffect,
+  claimDispatchSource,
+  completeSourceEffect,
   createChannelInputStep,
   ensureSession,
   invalidateSession,
-  markDispatchReceived,
   nextEnvelopeId,
   patchSession,
   readActiveEmit,
@@ -61,7 +62,7 @@ export async function effectsForChannelDispatch(
     if (m.status === 404 || m.status === 403) {
       // Deleted / inaccessible (also the shape a disabled org feature flag
       // takes) — permanently unusable, drop it.
-      return [ackEffect(ctx, 'channel_message', sourceId)];
+      return [completeSourceEffect(ctx, 'channel_message', sourceId)];
     }
     return []; // transient: keep pending, the catch-up sweep retries
   }
@@ -77,19 +78,19 @@ export async function effectsForChannelDispatch(
   const text = msg?.text ?? '';
   if (!conversationId) {
     // No conversation → no session key and no reply target: unusable.
-    return [ackEffect(ctx, 'channel_message', sourceId)];
+    return [completeSourceEffect(ctx, 'channel_message', sourceId)];
   }
   if (!text) {
     // The ingress adapter only persists mechanically parsed text; a row with
     // none will never grow any (same reasoning as attachment-only chat
     // messages) — drop rather than let it pile up in the pending queue.
-    return [ackEffect(ctx, 'channel_message', sourceId)];
+    return [completeSourceEffect(ctx, 'channel_message', sourceId)];
   }
 
   const c = await get(`/channel-conversations/${conversationId}`);
   if (!c.ok) {
     if (c.status === 404 || c.status === 403) {
-      return [ackEffect(ctx, 'channel_message', sourceId)];
+      return [completeSourceEffect(ctx, 'channel_message', sourceId)];
     }
     return [];
   }
@@ -114,7 +115,7 @@ export async function effectsForChannelDispatch(
   // (see the comments there): received settles before this function returns;
   // the turnEnvelope marker goes down before any session write; the row
   // stays 'received' until the turn event's complete-sources.
-  const receivedSettled = markDispatchReceived(ctx, 'channel_message', sourceId);
+  const receivedSettled = claimDispatchSource(ctx, 'channel_message', sourceId);
   const priorEmit = await readActiveEmit(ctx, 'channel_message', sourceId);
   const envelopeId = nextEnvelopeId('channel_message', sourceId, priorEmit);
   let sessionId = await ensureSession(ctx);
@@ -154,6 +155,10 @@ export async function effectsForChannelDispatch(
   await receivedSettled;
   await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId);
 
+  // Live capability grant → this turn's lark-cli auth env (mint gate = the
+  // no-drift revocation point) + the hint teaching the single reply path.
+  const capabilityEnv = await channelCapabilityEnv(ctx);
+
   return [
     {
       type: 'emitEvent',
@@ -178,6 +183,7 @@ export async function effectsForChannelDispatch(
             externalMessageId,
             senderName,
             text,
+            cliCapable: capabilityEnv !== null,
           }),
           conversationId,
           channelMessageId: sourceId,
@@ -185,19 +191,19 @@ export async function effectsForChannelDispatch(
           externalConversationId,
           externalMessageId,
         },
-        // No chatId on purpose: the reply goes out through the provider clip
-        // (agent-invoked), NOT deliver() — deliver only runs the redundant
-        // session idle for channel routes (see delivery.ts).
+        // No chatId on purpose: the reply is the agent's own lark-cli send,
+        // NOT deliver() — deliver only runs the redundant session idle for
+        // channel routes (see delivery.ts).
         replyRoute: {
           kind: 'provider_http',
           connectionId: ctx.connectionId,
           data: { conversationId, envelopeId },
         },
-        // No invocation context: PRLL_CHAT_ID must not point CLI defaults at
-        // a chat that doesn't exist, and the reply targets (external ids)
-        // already ride the prompt verbatim. (So no PRLL_DISPATCH_SOURCE_*
-        // either — the external reply goes out through the provider clip,
-        // and this row's ledger close is the turn event's complete-sources.)
+        // Invocation context carries ONLY the capability env: no PRLL_CHAT_ID
+        // (it must not point CLI defaults at a chat that doesn't exist) and
+        // no PRLL_DISPATCH_SOURCE_* (the external reply is a vendor-CLI send,
+        // and this row's ledger close is the turn event's complete-sources).
+        ...(capabilityEnv ? { context: capabilityEnv } : {}),
       },
     },
     // No ack effect — see the message path (inbound.ts): the row stays

package/src/inbound.ts

@@ -5,6 +5,7 @@ import type {
   ConnectorEffect,
   WebSocketFrame,
 } from '@parel/plugin-sdk';
+import { channelCapabilityEnv } from './channel-capability.js';
 import { buildChatPrompt, type PromptAttachment } from './channel-prompt.js';
 import { parallApiUrl, parallOrgId, requireAgk, sandboxEnabled } from './connect.js';
 import { effectsForChannelDispatch, PROVIDER_LOOKUP_TIMEOUT_MS } from './inbound-channel.js';
@@ -25,16 +26,11 @@ import {
   settleChildEvent,
   trackFollowUpAck,
 } from './fork.js';
-import {
-  type AgentEventWithChild,
-  asChildSpawnFailed,
-  asConnectorEffects,
-  type ExtendedConnectorEffect,
-} from './parel-sdk-compat.js';
 import {
   ackByIdEffect,
-  ackEffect,
+  claimDispatchSource,
   completeFencedEnvelopes,
+  completeSourceEffect,
   conversationKey,
   createErrorStep,
   fetchMainSessionFresh,
@@ -46,7 +42,6 @@ import {
   ensureSession,
   invalidateChildSession,
   invalidateSession,
-  markDispatchReceived,
   nextEnvelopeId,
   patchSession,
   readActiveEmit,
@@ -400,7 +395,7 @@ async function effectsForDispatch(
   if (sourceType !== 'message' || !sourceId) return [];
   if (!chatId) {
     // A message dispatch with no chat can never be routed or replied to.
-    return [ackEffect(ctx, sourceType, sourceId)];
+    return [completeSourceEffect(ctx, sourceType, sourceId)];
   }
   if (await shouldSkipLiveRow(ctx, sourceType, sourceId)) return [];
 
@@ -416,7 +411,7 @@ async function effectsForDispatch(
   if (!m.ok) {
     if (m.status === 404 || m.status === 403) {
       // Deleted message / lost chat access — permanently unusable, drop it.
-      return [ackEffect(ctx, sourceType, sourceId)];
+      return [completeSourceEffect(ctx, sourceType, sourceId)];
     }
     // Transient failure: keep pending, the catch-up sweep retries.
     return [];
@@ -449,7 +444,7 @@ async function effectsForDispatch(
     // Truly empty messages never grow content — ack-and-drop rather than let
     // them pile up in the pending queue forever. (Attachment-only messages
     // used to take this path; they now ride the attachment lines instead.)
-    return [ackEffect(ctx, sourceType, sourceId)];
+    return [completeSourceEffect(ctx, sourceType, sourceId)];
   }
 
   // Frame the message with its chat of origin: all chats share the agent's
@@ -496,12 +491,18 @@ async function effectsForDispatch(
   // so the server resolves this WorkItem in the reply's own transaction.
   // (Fork turns get it too — their rows are legacy-acked so the resolve is a
   // no-op today, and it wires up for free when fork ledger parity lands.)
+  // Channel-capability env (lark-cli auth) rides EVERY turn's invocation
+  // context while granted — Feishu workspace ops (docs/calendar/…) are asked
+  // for from ordinary Parall chats, not only from channel turns. Null when
+  // ungranted or the mint degrades; never blocks the emit.
+  const capabilityEnv = await channelCapabilityEnv(ctx);
   const invocationContext: Record<string, string> = {
     PRLL_CHAT_ID: chatId,
     PRLL_TRIGGER_MESSAGE_ID: sourceId,
     PRLL_DISPATCH_SOURCE_TYPE: sourceType,
     PRLL_DISPATCH_SOURCE_ID: sourceId,
     ...(threadRootId ? { PRLL_THREAD_ROOT_ID: threadRootId } : {}),
+    ...(capabilityEnv ?? {}),
   };
 
   const envelope = {
@@ -536,7 +537,7 @@ async function effectsForDispatch(
     // Progress reporting lands on the CHILD's ase_ — its turn does the work,
     // and the replyRoute carries childRef so deliver() links the reply to the
     // child session (and idles IT, not main).
-    const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
+    const receivedSettled = claimDispatchSource(ctx, sourceType, sourceId);
     const childAse = await ensureChildSession(ctx, decision.childRef);
     if (childAse) {
       const results = await Promise.all([
@@ -586,18 +587,18 @@ async function effectsForDispatch(
           source_id: sourceId,
           chat_id: chatId,
         });
-        return asConnectorEffects([
-          { type: 'setTimer', key: retryKey, at: ctx.now() + FORK_RETRY_DELAY_MS },
-        ]);
+        return [{ type: 'setTimer', key: retryKey, at: ctx.now() + FORK_RETRY_DELAY_MS }];
       }
-      return asConnectorEffects([
+      return [
         { type: 'emitEvent', event: childEnvelope, deliverTo: { childRef: decision.childRef } },
-      ]);
+      ];
     }
-    return asConnectorEffects([
+    return [
       { type: 'emitEvent', event: childEnvelope, deliverTo: { childRef: decision.childRef } },
-      ackEffect(ctx, sourceType, sourceId),
-    ]);
+      // Fork-handled rows keep the legacy ack machinery (ledger parity is a
+      // declared follow-up); by id — the precise form.
+      dispatchId ? ackByIdEffect(ctx, dispatchId) : completeSourceEffect(ctx, sourceType, sourceId),
+    ];
   }
 
   if (decision.mode === 'spawn') {
@@ -625,7 +626,7 @@ async function effectsForDispatch(
     // would leave the message stranded with no timer and no bookkeeping
     // until a reconnect).
     let spawnBlackHoled = false;
-    const timerEffects: ExtendedConnectorEffect[] = [];
+    const timerEffects: ConnectorEffect[] = [];
     if (dispatchId) {
       const retryKey = `${FORK_RETRY_PREFIX}${dispatchId}`;
       const attempts = await bumpForkRetryAttempts(ctx, retryKey, {
@@ -643,7 +644,7 @@ async function effectsForDispatch(
       }
     }
     if (!spawnBlackHoled) {
-      const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
+      const receivedSettled = claimDispatchSource(ctx, sourceType, sourceId);
       const childAse = await ensureChildSession(ctx, decision.childRef);
       if (childAse) {
         const results = await Promise.all([
@@ -659,7 +660,14 @@ async function effectsForDispatch(
       }
       await recordSpawn(ctx, subject, decision.childRef, { dispatchId, sourceId });
       await receivedSettled;
-      return asConnectorEffects([
+      // Known gap: SpawnChildSessionEffect (#140) carries no invocation
+      // context, so the fork's OPENING turn runs without the capability env
+      // (lark-cli workspace ops would need a follow-up turn — those arrive
+      // as deliverTo envelopes, which inherit the full context). Channel
+      // replies are unaffected: channel_message dispatches always ride main.
+      // Fix belongs parel-side (context on spawnChildSession) — tracked as a
+      // parel ask.
+      return [
         {
           type: 'spawnChildSession',
           childRef: decision.childRef,
@@ -667,7 +675,7 @@ async function effectsForDispatch(
           subject,
         },
         ...timerEffects,
-      ]);
+      ];
     }
     // fall through: black-holed spawn rides main below.
   }
@@ -682,7 +690,7 @@ async function effectsForDispatch(
   // pending→received transition. It is deliberately NOT gated on the
   // session resolving: a transient session failure must not also cost the
   // indicator.
-  const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
+  const receivedSettled = claimDispatchSource(ctx, sourceType, sourceId);
   let sessionId = await ensureSession(ctx);
   if (sessionId) {
     // The guard marker goes down BEFORE any session write: a stale
@@ -751,7 +759,7 @@ async function effectsForTypedDispatch(
   data: DispatchData,
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
-  // No markDispatchReceived here ON PURPOSE: typed dispatches have no
+  // No claimDispatchSource here ON PURPOSE: typed dispatches have no
   // message-level activity indicator (DispatchResolvedData: "typed
   // dispatches have no indicator"), so there is no pending ring to light —
   // the typed input step below is the session panel's timeline entry.
@@ -761,11 +769,21 @@ async function effectsForTypedDispatch(
   // Typed WorkItems ack by id, never by source: sibling rows (a task
   // mutation's task_assign + task_update) share (source_type, source_id),
   // and the source ack would terminally resolve work that was never emitted.
-  const ack = () =>
-    dispatchId ? ackByIdEffect(ctx, dispatchId) : ackEffect(ctx, sourceType, sourceId);
+  const ack = (): ConnectorEffect[] => {
+    if (!dispatchId) {
+      // No WorkItem id (malformed payload): the by-source form would
+      // terminally resolve SIBLING typed rows sharing this source — leave
+      // the row pending for the sweep instead.
+      console.error(
+        `[parel-channel] typed dispatch without id (${sourceType}:${sourceId}) left pending`,
+      );
+      return [];
+    }
+    return [ackByIdEffect(ctx, dispatchId)];
+  };
   const plan = await planTypedDispatch(data, ctx);
   if (plan.outcome === 'pending') return [];
-  if (plan.outcome === 'stale') return [ack()];
+  if (plan.outcome === 'stale') return ack();
 
   const envelopeId = dispatchId || `${sourceType}:${sourceId}`;
   let sessionId = await ensureSession(ctx);
@@ -796,6 +814,16 @@ async function effectsForTypedDispatch(
     }
   }
 
+  // Typed turns carry the capability env too: a task or schedule is exactly
+  // where "create the Feishu doc / check the calendar" work is assigned, so
+  // the every-turn capability contract covers them (null when ungranted or
+  // the mint degrades; never blocks the emit).
+  const capabilityEnv = await channelCapabilityEnv(ctx);
+  const typedContext: Record<string, string> = {
+    ...(plan.chatId ? { PRLL_CHAT_ID: plan.chatId, PRLL_TRIGGER_MESSAGE_ID: sourceId } : {}),
+    ...(capabilityEnv ?? {}),
+  };
+
   return [
     {
       type: 'emitEvent',
@@ -822,17 +850,10 @@ async function effectsForTypedDispatch(
             ? { chatId: plan.chatId, messageId: sourceId, envelopeId }
             : { envelopeId },
         },
-        ...(plan.chatId
-          ? {
-              context: {
-                PRLL_CHAT_ID: plan.chatId,
-                PRLL_TRIGGER_MESSAGE_ID: sourceId,
-              },
-            }
-          : {}),
+        ...(Object.keys(typedContext).length > 0 ? { context: typedContext } : {}),
       },
     },
-    ack(),
+    ...ack(),
   ];
 }
 
@@ -932,21 +953,20 @@ async function handleParallAgentEventInner(
   event: AgentEvent,
   ctx: ConnectorContext,
 ): Promise<AgentEventEffect[]> {
-  // spawnChildSession's asynchronous error channel — not turn-scoped, pushed
-  // regardless of observe scopes, and shaped outside the published AgentEvent
-  // union (see parel-sdk-compat). Handle it before anything subject-gated.
-  const spawnFailed = asChildSpawnFailed(event);
-  if (spawnFailed) {
+  // spawnChildSession's asynchronous error channel — not turn-scoped and
+  // pushed regardless of observe scopes. Handle it before anything
+  // subject-gated.
+  if (event.type === 'child_spawn_failed') {
     const effects: AgentEventEffect[] = [];
     try {
-      const outcome = await handleChildSpawnFailed(ctx, spawnFailed);
+      const outcome = await handleChildSpawnFailed(ctx, event);
       if (outcome.cleared) {
         // The spawn's ase_ was already created active with an input step; no
         // child turn will ever emit a terminal event for it — settle it here
         // or the session (and its processing indicator) stays active forever.
-        const orphanAse = await ensureChildSession(ctx, spawnFailed.childRef);
+        const orphanAse = await ensureChildSession(ctx, event.childRef);
         if (orphanAse) await patchSession(ctx, orphanAse, { status: 'idle' });
-        await invalidateChildSession(ctx, spawnFailed.childRef);
+        await invalidateChildSession(ctx, event.childRef);
       }
       // Re-drive the stranded messages WITHOUT waiting for a reconnect sweep
       // (a healthy long-lived socket never re-runs onOpen): park their
@@ -971,15 +991,14 @@ async function handleParallAgentEventInner(
     }
     return effects;
   }
-  const withChild = event as AgentEventWithChild;
-  if (withChild.childRef) {
-    return handleChildAgentEvent(withChild, ctx);
+  if (event.childRef) {
+    return handleChildAgentEvent(event, ctx);
   }
   const chatId = event.subject;
   try {
     // Best-effort busy classifier for fork-on-busy: only MAIN turns feed it
     // (child events took the branch above).
-    await noteMainTurnEvent(ctx, withChild).catch(() => {});
+    await noteMainTurnEvent(ctx, event).catch(() => {});
     if (!chatId) return [];
     if (event.type === 'turn_completed' || event.type === 'turn_failed') {
       // Ledger close FIRST, fenced per source — deliberately NOT behind the
@@ -995,7 +1014,11 @@ async function handleParallAgentEventInner(
       // the absorbing turn's envelopeIds and settle here naturally. The
       // server decides reply broad-cover vs no_action per batch; turn_failed
       // sweeps the same way with the error step below as the visible record.
-      await completeFencedEnvelopes(ctx, event.envelopeIds);
+      await completeFencedEnvelopes(
+        ctx,
+        event.envelopeIds,
+        event.type === 'turn_failed' ? 'error' : 'ok',
+      );
 
       // Staleness guard: only idle if this event's turn covers the AGENT'S
       // latest emitted envelope (the marker is agent-global — all chats share
@@ -1065,7 +1088,7 @@ async function handleParallAgentEventInner(
  * turnEnvelope marker or the busy classifier.
  */
 async function handleChildAgentEvent(
-  event: AgentEventWithChild,
+  event: AgentEvent,
   ctx: ConnectorContext,
 ): Promise<AgentEventEffect[]> {
   const childRef = event.childRef ?? '';