@parall/parel-channel 1.42.1 → 1.44.0

package/src/session.ts

@@ -590,12 +590,14 @@ export async function createTraceStep(
 }
 
 /**
- * Ack a dispatch by source so it leaves the pending queue (idempotent).
- * Typed as the fetch effect so it can ride BOTH hook channels (onMessage's
- * ConnectorEffect[] and onAgentEvent's AgentEventEffect[] — the fork spawn
- * ack fires from a child agent event).
+ * Terminally drop ONE source's live WorkItem via the unified complete's
+ * source form (no covering reply Effect exists for a dropped row, so the
+ * server sweeps it to no_action — the drop semantics; idempotent). Typed as
+ * the fetch effect so it can ride BOTH hook channels (ConnectorEffect[] and
+ * AgentEventEffect[]). Replaces the legacy by-source ack for drop cases —
+ * that endpoint retires at S3 (dispatch-convergence-design.md §3).
  */
-export function ackEffect(
+export function completeSourceEffect(
   ctx: ConnectorContext,
   sourceType: string,
   sourceId: string,
@@ -603,15 +605,15 @@ export function ackEffect(
   return {
     type: 'fetch',
     request: {
-      url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/ack`,
+      url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/complete`,
       method: 'POST',
       headers: {
         Authorization: `Bearer ${requireAgk(ctx)}`,
         'Content-Type': 'application/json',
       },
-      body: JSON.stringify({ source_type: sourceType, source_id: sourceId }),
+      body: JSON.stringify({ sources: [{ source_type: sourceType, source_id: sourceId }] }),
     },
-    idempotencyKey: `ack:${sourceType}:${sourceId}`,
+    idempotencyKey: `complete:src:${sourceType}:${sourceId}`,
   };
 }
 
@@ -643,31 +645,35 @@ export function ackByIdEffect(
 }
 
 /**
- * Lights the pending ring (server broadcasts dispatch.received). Must COMPLETE
- * before the ack effect is returned: MarkReceived only transitions rows still
- * in status='pending', and ack moves the same row to 'acked' — losing the race
- * means the ring never appears.
+ * Claim the source's WorkItem before the turn (server folds the row into its
+ * message lane, flips it pending→received and broadcasts dispatch.received —
+ * the pending ring rides the claim side effect now; the retired received
+ * endpoint was a bare receipt). Best-effort like the receipt was: a refused
+ * or failed claim never blocks the emit — the row stays pending and the
+ * turn's complete resolves it just the same. Must COMPLETE before any
+ * settling effect is returned so a same-batch complete can't race the
+ * pending→received transition.
  */
-export async function markDispatchReceived(
+export async function claimDispatchSource(
   ctx: ConnectorContext,
   sourceType: string,
   sourceId: string,
 ): Promise<void> {
   // 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.
+  // session reporting — the URL needs no agent id, and the claim transition
+  // is what keeps the indicator lifecycle working even for agent-id-less old
+  // configs.
   try {
-    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/received`;
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/claim`;
     const res = await fetch(url, {
       method: 'POST',
       headers: jsonHeaders(ctx),
       body: JSON.stringify({ source_type: sourceType, source_id: sourceId }),
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     });
-    if (!res.ok) console.error(`[parel-channel] mark received failed (${res.status})`);
+    if (!res.ok) console.error(`[parel-channel] claim source failed (${res.status})`);
   } catch (err) {
-    console.error('[parel-channel] mark received failed', err);
+    console.error('[parel-channel] claim source failed', err);
   }
 }
 
@@ -735,6 +741,25 @@ export async function clearActiveEmit(
   await ctx.store?.delete(activeEmitKey(sourceType, sourceId)).catch(() => {});
 }
 
+/**
+ * Burn the fence after an ERROR close: keep the attempt id (so the re-driven
+ * emit's nextEnvelopeId picks a fresh `#r{n+1}` — a bare repeat of the base
+ * id could be deduped by parel and strand the retry) but zero the timestamp
+ * (so the redelivery-skip window is already over and the server's re-drive
+ * hint re-emits immediately instead of hiding behind a 30-min TTL).
+ */
+export async function burnActiveEmit(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+): Promise<void> {
+  const prior = await readActiveEmit(ctx, sourceType, sourceId);
+  if (!prior) return;
+  await ctx.store
+    ?.set(activeEmitKey(sourceType, sourceId), { id: prior.id, at: 0 })
+    .catch(() => {});
+}
+
 /**
  * Deterministic envelope id for a source: `{sourceType}:{sourceId}` on the
  * first attempt, `…#r{n}` on re-emits. Attempt-suffixed ids are unique per
@@ -763,6 +788,9 @@ export function sourceFromEnvelopeId(
   return { sourceType: bare.slice(0, i), sourceId: bare.slice(i + 1) };
 }
 
+/** Turn outcome for the ledger close — mirrors the server's turn_outcome. */
+export type TurnOutcome = 'ok' | 'error';
+
 /**
  * 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
@@ -770,51 +798,70 @@ export function sourceFromEnvelopeId(
  * 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.
+ * (attempt fence). Both hooks running is harmless: whichever completes first
+ * consumes the fence, the other skips.
+ *
+ * Fence disposal follows the outcome: an "ok" close clears the fences (the
+ * sources are terminal); an "error" close BURNS them instead — the server
+ * released the uncovered members back to pending and its re-drive hint
+ * re-emits them, so the burned fence must neither hide the retry behind the
+ * redelivery-skip TTL nor let it reuse a dedupe-prone envelope id.
  */
 export async function completeFencedEnvelopes(
   ctx: ConnectorContext,
   envelopeIds: string[],
+  outcome: TurnOutcome = 'ok',
 ): 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) {
+    // A BURNED fence (at === 0) still carries the attempt id but the attempt
+    // is already error-closed — its members are back in pending awaiting the
+    // re-drive. The redundant deliver()-side close for the same envelope
+    // must skip here, or its "ok" would no_action-sweep the very rows the
+    // error close just released (the retry hole S3a closes).
+    if (active?.id === envId && active.at > 0) {
       fenced.push({ source_type: src.sourceType, source_id: src.sourceId });
     }
   }
-  if (fenced.length > 0 && (await completeSources(ctx, fenced))) {
+  if (fenced.length > 0 && (await completeSources(ctx, fenced, outcome))) {
     for (const src of fenced) {
-      await clearActiveEmit(ctx, src.source_type, src.source_id);
+      if (outcome === 'error') {
+        await burnActiveEmit(ctx, src.source_type, src.source_id);
+      } else {
+        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.
+ * Turn-end ledger close: resolves the turn's folded sources on the server via
+ * the unified complete's source form (POST /dispatch/complete, idempotent) —
+ * broad-cover to the turn's reply Effect when one exists; otherwise a
+ * no_action sweep on "ok", or a release back to pending on the redrive budget
+ * on "error" (a failed turn must not silently consume work it never handled).
+ * One immediate retry on failure; a still-failed call leaves the rows live
+ * and the catch-up TTL re-emit self-heals.
  */
 export async function completeSources(
   ctx: ConnectorContext,
   sources: { source_type: string; source_id: string }[],
+  outcome: TurnOutcome = 'ok',
 ): Promise<boolean> {
-  // Ledger surface — not gated on reportingEnabled (see markDispatchReceived).
+  // Ledger surface — not gated on reportingEnabled (see claimDispatchSource).
   if (sources.length === 0) return true;
-  const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/complete-sources`;
+  const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/complete`;
   const attempt = async (): Promise<boolean> => {
     const res = await fetch(url, {
       method: 'POST',
       headers: jsonHeaders(ctx),
-      body: JSON.stringify({ sources }),
+      body: JSON.stringify({ sources, turn_outcome: outcome }),
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     });
-    if (!res.ok) console.error(`[parel-channel] complete-sources failed (${res.status})`);
+    if (!res.ok) console.error(`[parel-channel] complete (sources) failed (${res.status})`);
     return res.ok;
   };
   try {
@@ -825,7 +872,7 @@ export async function completeSources(
   try {
     return await attempt();
   } catch (err) {
-    console.error('[parel-channel] complete-sources failed', err);
+    console.error('[parel-channel] complete (sources) failed', err);
     return false;
   }
 }

package/dist/parel-sdk-compat.d.ts

@@ -1,63 +0,0 @@
-import type { AgentEvent, ChannelEnvelope, ConnectorEffect } from '@parel/plugin-sdk';
-/**
- * Local mirrors of parel host types that shipped in parel-mono #140 (F3
- * injectInFlight / F4 child sessions) but are not yet published in
- * @parel/plugin-sdk (the mirror lives on parel-oss branch
- * feat/channel-child-sessions). The host accepts these shapes today — prod
- * runs #140 — so the connector uses them through this compat layer and casts
- * at the hook boundary.
- *
- * TODO(parel-sdk-#140-types): DELETE this file (and the casts) once
- * @parel/plugin-sdk ships the mirror sitting on parel-oss branch
- * `feat/channel-child-sessions` — check the branch/`@parel/plugin-sdk`
- * changelog on every sdk version bump. Until then the shapes below must stay
- * byte-compatible with parel-mono ts/packages/cloudflare/src/channel-types.ts.
- */
-/**
- * Spawn a fork child session off this connection's main conversation session.
- * Idempotent on childRef (opaque, connector-owned). Host gates: binding must
- * opt in (childSessions) + `main` routing; failures come back asynchronously
- * as a `child_spawn_failed` agent event. The child seeds from the parent
- * transcript at the last turn boundary (never sees in-flight output).
- */
-export interface SpawnChildSessionEffect {
-    type: 'spawnChildSession';
-    childRef: string;
-    input: string;
-    subject?: string;
-}
-/** emitEvent with the #140 deliverTo extension: route to a spawned child. */
-export interface EmitToChildEffect {
-    type: 'emitEvent';
-    event: ChannelEnvelope;
-    deliverTo: {
-        childRef: string;
-    };
-}
-/**
- * Asynchronous error channel for a failed spawnChildSession effect (pushed
- * regardless of observe scopes). codes: disabled | unsupported_routing |
- * no_binding | invalid_request | depth_limit | concurrency_limit |
- * spawn_failed.
- */
-export interface ChildSpawnFailedEvent {
-    type: 'child_spawn_failed';
-    childRef: string;
-    code: string;
-    error: string;
-}
-/** Effect union the #140 host actually executes. */
-export type ExtendedConnectorEffect = ConnectorEffect | SpawnChildSessionEffect | EmitToChildEffect;
-/**
- * Every event from a connector-spawned child carries the childRef it was
- * spawned with (#140: AgentEventBase.childRef). Absent on main-session
- * events and on sdk versions that predate the field.
- */
-export type AgentEventWithChild = AgentEvent & {
-    childRef?: string;
-};
-/** Narrow an incoming agent event to the not-yet-published failure shape. */
-export declare function asChildSpawnFailed(event: unknown): ChildSpawnFailedEvent | null;
-/** Cast helper: the host executes the extended union; the sdk type lags it. */
-export declare function asConnectorEffects(effects: ExtendedConnectorEffect[]): ConnectorEffect[];
-//# sourceMappingURL=parel-sdk-compat.d.ts.map

package/dist/parel-sdk-compat.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parel-sdk-compat.d.ts","sourceRoot":"","sources":["../src/parel-sdk-compat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oDAAoD;AACpD,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG,uBAAuB,GAAG,iBAAiB,CAAC;AAEpG;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,GAAG,IAAI,CAS/E;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,eAAe,EAAE,CAExF"}

package/dist/parel-sdk-compat.js

@@ -1,16 +0,0 @@
-/** Narrow an incoming agent event to the not-yet-published failure shape. */
-export function asChildSpawnFailed(event) {
-    const e = event;
-    if (e?.type !== 'child_spawn_failed')
-        return null;
-    return {
-        type: 'child_spawn_failed',
-        childRef: typeof e.childRef === 'string' ? e.childRef : '',
-        code: typeof e.code === 'string' ? e.code : 'unknown',
-        error: typeof e.error === 'string' ? e.error : '',
-    };
-}
-/** Cast helper: the host executes the extended union; the sdk type lags it. */
-export function asConnectorEffects(effects) {
-    return effects;
-}

package/src/parel-sdk-compat.ts

@@ -1,77 +0,0 @@
-import type { AgentEvent, ChannelEnvelope, ConnectorEffect } from '@parel/plugin-sdk';
-
-/**
- * Local mirrors of parel host types that shipped in parel-mono #140 (F3
- * injectInFlight / F4 child sessions) but are not yet published in
- * @parel/plugin-sdk (the mirror lives on parel-oss branch
- * feat/channel-child-sessions). The host accepts these shapes today — prod
- * runs #140 — so the connector uses them through this compat layer and casts
- * at the hook boundary.
- *
- * TODO(parel-sdk-#140-types): DELETE this file (and the casts) once
- * @parel/plugin-sdk ships the mirror sitting on parel-oss branch
- * `feat/channel-child-sessions` — check the branch/`@parel/plugin-sdk`
- * changelog on every sdk version bump. Until then the shapes below must stay
- * byte-compatible with parel-mono ts/packages/cloudflare/src/channel-types.ts.
- */
-
-/**
- * Spawn a fork child session off this connection's main conversation session.
- * Idempotent on childRef (opaque, connector-owned). Host gates: binding must
- * opt in (childSessions) + `main` routing; failures come back asynchronously
- * as a `child_spawn_failed` agent event. The child seeds from the parent
- * transcript at the last turn boundary (never sees in-flight output).
- */
-export interface SpawnChildSessionEffect {
-  type: 'spawnChildSession';
-  childRef: string;
-  input: string;
-  subject?: string;
-}
-
-/** emitEvent with the #140 deliverTo extension: route to a spawned child. */
-export interface EmitToChildEffect {
-  type: 'emitEvent';
-  event: ChannelEnvelope;
-  deliverTo: { childRef: string };
-}
-
-/**
- * Asynchronous error channel for a failed spawnChildSession effect (pushed
- * regardless of observe scopes). codes: disabled | unsupported_routing |
- * no_binding | invalid_request | depth_limit | concurrency_limit |
- * spawn_failed.
- */
-export interface ChildSpawnFailedEvent {
-  type: 'child_spawn_failed';
-  childRef: string;
-  code: string;
-  error: string;
-}
-
-/** Effect union the #140 host actually executes. */
-export type ExtendedConnectorEffect = ConnectorEffect | SpawnChildSessionEffect | EmitToChildEffect;
-
-/**
- * Every event from a connector-spawned child carries the childRef it was
- * spawned with (#140: AgentEventBase.childRef). Absent on main-session
- * events and on sdk versions that predate the field.
- */
-export type AgentEventWithChild = AgentEvent & { childRef?: string };
-
-/** Narrow an incoming agent event to the not-yet-published failure shape. */
-export function asChildSpawnFailed(event: unknown): ChildSpawnFailedEvent | null {
-  const e = event as { type?: unknown; childRef?: unknown; code?: unknown; error?: unknown };
-  if (e?.type !== 'child_spawn_failed') return null;
-  return {
-    type: 'child_spawn_failed',
-    childRef: typeof e.childRef === 'string' ? e.childRef : '',
-    code: typeof e.code === 'string' ? e.code : 'unknown',
-    error: typeof e.error === 'string' ? e.error : '',
-  };
-}
-
-/** Cast helper: the host executes the extended union; the sdk type lags it. */
-export function asConnectorEffects(effects: ExtendedConnectorEffect[]): ConnectorEffect[] {
-  return effects as ConnectorEffect[];
-}