@parall/parel-channel 1.41.0 → 1.42.0

package/src/session.ts

@@ -653,7 +653,10 @@ export async function markDispatchReceived(
   sourceType: string,
   sourceId: string,
 ): Promise<void> {
-  if (!reportingEnabled(ctx)) return;
+  // Deliberately NOT gated on reportingEnabled: this is ledger surface, not
+  // session reporting — the URL needs no agent id, and with ack-on-emit gone
+  // the received transition is what keeps the reconnect sweep's TTL window
+  // (and the indicator lifecycle) working even for agent-id-less old configs.
   try {
     const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/received`;
     const res = await fetch(url, {
@@ -667,3 +670,200 @@ export async function markDispatchReceived(
     console.error('[parel-channel] mark received failed', err);
   }
 }
+
+// ── By-source ledger surface ────────────────────────────
+//
+// The connector consumes dispatches without claiming lanes (parel's own
+// queue serializes turns), so its ledger writes address WorkItems by source
+// pointer, and its liveness bookkeeping is a per-source attempt fence in the
+// durable store. Design: parel-reply-contract-alignment.md §5.3.
+
+/**
+ * How long an emitted source may stay unresolved before the reconnect sweep
+ * re-emits it (crash / lost turn_completed self-heal — the successor of the
+ * retired turnwatch timer). Must comfortably exceed any legitimate turn.
+ */
+export const EMIT_TTL_MS = 30 * 60 * 1000;
+
+/** The current emit attempt for a source: its envelope id + emit time. */
+export type ActiveEmit = { id: string; at: number };
+
+function activeEmitKey(sourceType: string, sourceId: string): string {
+  return `active:${sourceType}:${sourceId}`;
+}
+
+/**
+ * Per-source attempt fence. Written before emit, cleared by the matching
+ * turn event's complete: a turn event only closes a source whose stored id
+ * EXACTLY matches one of its envelopeIds — a late turn_completed from a
+ * superseded attempt (the source was re-emitted after the TTL) must not
+ * close the in-flight retry's work (codex P2 attempt fence).
+ */
+export async function readActiveEmit(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+): Promise<ActiveEmit | null> {
+  const raw = await ctx.store?.get(activeEmitKey(sourceType, sourceId)).catch(() => null);
+  if (
+    raw &&
+    typeof raw === 'object' &&
+    typeof (raw as { id?: unknown }).id === 'string' &&
+    typeof (raw as { at?: unknown }).at === 'number'
+  ) {
+    return raw as ActiveEmit;
+  }
+  return null;
+}
+
+export async function writeActiveEmit(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+  envelopeId: string,
+): Promise<void> {
+  await ctx.store
+    ?.set(activeEmitKey(sourceType, sourceId), { id: envelopeId, at: ctx.now() })
+    .catch(() => {});
+}
+
+export async function clearActiveEmit(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+): Promise<void> {
+  await ctx.store?.delete(activeEmitKey(sourceType, sourceId)).catch(() => {});
+}
+
+/**
+ * Deterministic envelope id for a source: `{sourceType}:{sourceId}` on the
+ * first attempt, `…#r{n}` on re-emits. Attempt-suffixed ids are unique per
+ * attempt, so a re-emit is a NEW envelope to parel regardless of any dedupe
+ * behavior — the retry always produces a fresh turn.
+ */
+export function nextEnvelopeId(
+  sourceType: string,
+  sourceId: string,
+  prior: ActiveEmit | null,
+): string {
+  const base = `${sourceType}:${sourceId}`;
+  if (!prior) return base;
+  const m = prior.id.match(/#r(\d+)$/);
+  const attempt = m ? Number(m[1]) + 1 : 1;
+  return `${base}#r${attempt}`;
+}
+
+/** envelope id → source pointer (strips the attempt suffix). */
+export function sourceFromEnvelopeId(
+  envelopeId: string,
+): { sourceType: string; sourceId: string } | null {
+  const bare = envelopeId.replace(/#r\d+$/, '');
+  const i = bare.indexOf(':');
+  if (i <= 0 || i === bare.length - 1) return null;
+  return { sourceType: bare.slice(0, i), sourceId: bare.slice(i + 1) };
+}
+
+/**
+ * Fence-checked turn-end ledger close for a set of envelope ids — the shared
+ * core of BOTH turn-end hooks: onAgentEvent (turn_completed/turn_failed, the
+ * primary) and deliver (the no-observe npm-fallback path, where turn events
+ * never arrive and this is the ONLY terminal ledger hook — without it a
+ * received row would re-emit on every TTL sweep forever). Only sources whose
+ * `active:{source}` store row matches the envelope id EXACTLY are completed
+ * (attempt fence); the fence rows clear on success. Both hooks running is
+ * harmless: whichever completes first consumes the fence, the other skips.
+ */
+export async function completeFencedEnvelopes(
+  ctx: ConnectorContext,
+  envelopeIds: string[],
+): Promise<void> {
+  const fenced: { source_type: string; source_id: string }[] = [];
+  for (const envId of envelopeIds) {
+    const src = sourceFromEnvelopeId(envId);
+    if (!src) continue; // pre-alignment envelope id (dsp_*) — old rows were acked on emit
+    const active = await readActiveEmit(ctx, src.sourceType, src.sourceId);
+    if (active?.id === envId) {
+      fenced.push({ source_type: src.sourceType, source_id: src.sourceId });
+    }
+  }
+  if (fenced.length > 0 && (await completeSources(ctx, fenced))) {
+    for (const src of fenced) {
+      await clearActiveEmit(ctx, src.source_type, src.source_id);
+    }
+  }
+}
+
+/**
+ * Turn-end ledger close: resolves the turn's folded sources on the server —
+ * broad-cover to the turn's reply Effect when one exists, no_action sweep
+ * otherwise (the server decides; POST /dispatch/complete-sources, idempotent).
+ * One immediate retry on failure; a still-failed call leaves the rows
+ * received and the catch-up TTL re-emit self-heals.
+ */
+export async function completeSources(
+  ctx: ConnectorContext,
+  sources: { source_type: string; source_id: string }[],
+): Promise<boolean> {
+  // Ledger surface — not gated on reportingEnabled (see markDispatchReceived).
+  if (sources.length === 0) return true;
+  const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/complete-sources`;
+  const attempt = async (): Promise<boolean> => {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({ sources }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) console.error(`[parel-channel] complete-sources failed (${res.status})`);
+    return res.ok;
+  };
+  try {
+    if (await attempt()) return true;
+  } catch {
+    // fall through to the single immediate retry
+  }
+  try {
+    return await attempt();
+  } catch (err) {
+    console.error('[parel-channel] complete-sources failed', err);
+    return false;
+  }
+}
+
+/**
+ * Turn-end plain text as a suppressed audit step — the runtime-standard
+ * Layer 0 posture (agent-dm-loop-prevention.md): recorded on the session,
+ * never delivered to the chat. No `projection` field, so the server's
+ * projection gate keeps it panel-only; `suppressed: true` is the content
+ * marker the standard bridges write for undelivered text.
+ */
+export async function createSuppressedTextStep(
+  ctx: ConnectorContext,
+  sessionId: string,
+  args: { subject: string; deliveryId: string; text: string },
+): Promise<ReportResult> {
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
+    // Same subject-prefix line the other step writers draw: chv_ turns must
+    // not target 'chat' or the broadcast lands on a channel no client watches.
+    const targetType = args.subject.startsWith('chv_') ? 'channel_conversation' : 'chat';
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({
+        step_type: 'text',
+        target_type: targetType,
+        target_id: args.subject,
+        idempotency_key: `text:${args.deliveryId}`,
+        content: { text: args.text, suppressed: true },
+      }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (res.ok) return 'ok';
+    console.error(`[parel-channel] suppressed text step failed (${res.status})`);
+    return resultForStatus(res.status);
+  } catch (err) {
+    console.error('[parel-channel] suppressed text step failed', err);
+    return 'failed';
+  }
+}

package/src/typed-dispatch.ts

@@ -22,13 +22,15 @@ import { REQUEST_TIMEOUT_MS } from './session.js';
  *   attached_to_uri legitimately revokes access to a delivered run snapshot;
  *   docs/primitives/schedule.md § Snapshot 不变性) — warn + ack + drop.
  *
- * Reply semantics differ from chat messages ON PURPOSE: a typed turn's
- * turn-end text has no chat to deliver to (deliver() only runs the redundant
- * idle), and the agent acts through its sandbox CLI instead — identical to
- * the standard runtimes, where typed events are answered with CLI actions,
- * not auto-delivered text. approval_decided is the one exception: it lives
- * in a chat, so its plan carries the chatId and the reply auto-delivers
- * there like any chat message.
+ * Reply semantics are uniform with the rest of the connector: NOTHING
+ * auto-delivers (the CLI-only reply contract,
+ * parel-reply-contract-alignment.md). A typed turn's turn-end text is never
+ * posted anywhere; the agent acts through its sandbox CLI — identical to
+ * the standard runtimes, where typed events are answered with CLI actions.
+ * approval_decided differs only in ROUTING metadata: it lives in a chat, so
+ * its plan carries the chatId — that anchors the suppressed turn-end audit
+ * step and tells the agent where to `parall messages send`; the reply
+ * itself is still an explicit CLI send.
  */
 
 export interface TypedDispatchData {
@@ -69,7 +71,11 @@ export interface TypedEventPlan {
   /** Input-step content bits. */
   triggerType: string;
   summary: string;
-  /** Set only for approval_decided: the reply auto-delivers to this chat. */
+  /**
+   * Set only for approval_decided: anchors the suppressed turn-end audit
+   * step and tells the agent where to `parall messages send` — replies are
+   * CLI-only, nothing auto-delivers.
+   */
   chatId?: string;
 }
 
@@ -233,8 +239,9 @@ async function planTask(
 }
 
 /**
- * schedule.fire / external_trigger turns have NO delivery target — the
- * managed-agent base behavior ("your reply auto-delivers") does not apply,
+ * schedule.fire / external_trigger turns have NO conversation attached at
+ * all — plain text output is never delivered anywhere (the CLI-only reply
+ * contract), and unlike chat turns there is no obvious chat to send into,
  * so without this line a normal completion silently disappears.
  */
 function cliOnlyOutputHint(kind: 'schedule' | 'trigger'): string {
@@ -510,7 +517,8 @@ async function planApprovalDecided(
   return {
     outcome: 'emit',
     // The decision belongs to the chat conversation it happened in — group
-    // and correlate there, and let the turn-end reply deliver to that chat.
+    // and correlate there; a follow-up reply is the agent's explicit CLI
+    // send into that chat (turn-end text never auto-delivers).
     subject: resolvedChat ?? approval.id,
     body: lines.join('\n'),
     stepTarget: resolvedChat ? { type: 'chat', id: resolvedChat } : null,