@parall/parel-channel 1.40.0 → 1.41.0

package/src/index.ts

@@ -1,7 +1,12 @@
 import type { ChannelConnector } from '@parel/plugin-sdk';
 import { connectParall } from './connect.js';
 import { buildParallDelivery } from './delivery.js';
-import { catchUpParall, handleParallAgentEvent, handleParallFrame } from './inbound.js';
+import {
+  catchUpParall,
+  handleParallAgentEvent,
+  handleParallFrame,
+  handleParallTimer,
+} from './inbound.js';
 
 /**
  * Parall channel plugin for the parel runtime.
@@ -21,6 +26,7 @@ const connector: ChannelConnector = {
   connect: connectParall,
   onOpen: catchUpParall,
   onMessage: handleParallFrame,
+  onTimer: handleParallTimer,
   onAgentEvent: handleParallAgentEvent,
   deliver: buildParallDelivery,
 };

package/src/parel-sdk-compat.ts

@@ -0,0 +1,77 @@
+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[];
+}

package/src/session.ts

@@ -1,4 +1,4 @@
-import type { ConnectorContext } from '@parel/plugin-sdk';
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
 import { parallAgentId, parallApiUrl, parallOrgId, requireAgk } from './connect.js';
 
 /**
@@ -41,7 +41,51 @@ export function reportingEnabled(ctx: ConnectorContext): boolean {
  * simply never read again.)
  */
 export const TURN_ENVELOPE_KEY = `turnEnvelope:${MAIN_SESSION_KEY}`;
-const SESSION_CACHE_KEY = `session:${MAIN_SESSION_KEY}`;
+export const SESSION_CACHE_KEY = `session:${MAIN_SESSION_KEY}`;
+const childSessionCacheKey = (childRef: string) => `sessionChild:${childRef}`;
+
+/**
+ * Conversation key for envelope subjects and fork routing. Thread-aware:
+ * parel's turn grouping (F2) and mid-turn injection (F3) key on the envelope
+ * subject, and a turn carries ONE reply route — grouping two threads of the
+ * same chat under one subject would absorb thread B into thread A's turn and
+ * deliver its reply to the wrong thread (agent-core's lane keys draw the
+ * same thread/channel line). `~` is outside both nanoid and ULID alphabets,
+ * so the composite never collides with a plain id.
+ */
+export function conversationKey(chatId: string, threadRootId?: string): string {
+  return threadRootId ? `${chatId}~${threadRootId}` : chatId;
+}
+
+/**
+ * The addressable entity id inside a (possibly thread-composite) subject.
+ * Splits ONLY the `cht_…~msg_…` composite conversationKey produces — typed
+ * wiki subjects are scheme-stripped paths where `~` is a legal character
+ * (e.g. `wik_1/docs/~draft.md`) and must pass through untouched.
+ */
+export function subjectEntityId(subject: string): string {
+  const sep = subject.indexOf('~');
+  if (sep === -1) return subject;
+  const head = subject.slice(0, sep);
+  const tail = subject.slice(sep + 1);
+  return head.startsWith('cht_') && tail.startsWith('msg_') ? head : subject;
+}
+
+/**
+ * Step broadcast routing by subject shape: chat ids and channel conversations
+ * have live subscribers; task/schedule/trigger/wiki subjects are stored-only
+ * targets (the server publishes step WS events for chat/task targets and
+ * simply persists the rest). Mirrors agent-core's resolveStepTarget so both
+ * runtimes' session panels read identically.
+ */
+export function stepTargetTypeFor(subject: string): string {
+  if (subject.startsWith('chv_')) return 'channel_conversation';
+  if (subject.startsWith('tsk_')) return 'task';
+  if (subject.startsWith('sch_')) return 'schedule';
+  if (subject.startsWith('xtr_')) return 'external_trigger';
+  if (subject.startsWith('wcs_') || subject.startsWith('wik_')) return 'wiki';
+  return 'chat';
+}
 
 /**
  * 'stale' means the session id no longer accepts writes (closed/superseded —
@@ -105,6 +149,89 @@ export async function ensureSession(
   }
 }
 
+/**
+ * Resolve the CURRENT main ase_ from the server, bypassing the cache — the
+ * onOpen generation check needs the authoritative id to compare against the
+ * cached one (New Session rotates it). Updates the cache on success; returns
+ * null on failure WITHOUT touching the cache (the caller must not lose its
+ * only generation token to a transient error).
+ */
+export async function fetchMainSessionFresh(ctx: ConnectorContext): Promise<string | null> {
+  if (!reportingEnabled(ctx)) return null;
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({ runtime_type: 'parel', runtime_session_id: MAIN_SESSION_KEY }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json().catch(() => null)) as { id?: string } | null;
+    const id = body?.id;
+    if (!id) return null;
+    await ctx.store?.set(SESSION_CACHE_KEY, id).catch(() => {});
+    return id;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get-or-create the parall AgentSession mirroring one fork child session
+ * (ase_ with parent_session_id → the main ase_, runtime_session_id = the
+ * opaque childRef — the connector never sees parel's internal session id).
+ * Same caching/degradation posture as ensureSession; the parent resolve
+ * reuses the main-session cache so the extra cost is one store read.
+ */
+export async function ensureChildSession(
+  ctx: ConnectorContext,
+  childRef: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<string | null> {
+  if (!reportingEnabled(ctx)) return null;
+  const cacheKey = childSessionCacheKey(childRef);
+  const cached = await ctx.store?.get(cacheKey).catch(() => null);
+  if (typeof cached === 'string' && cached) return cached;
+  const parentId = await ensureSession(ctx, opts);
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({
+        runtime_type: 'parel',
+        runtime_session_id: childRef,
+        // Forks sit outside the main-lane uniqueness (parent set), mirroring
+        // the standard runtimes' fork ase_ semantics.
+        runtime_lane_key: `agent:fork:parel:${childRef}`,
+        ...(parentId ? { parent_session_id: parentId } : {}),
+      }),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      console.error(`[parel-channel] child session get-or-create failed (${res.status})`);
+      return null;
+    }
+    const body = (await res.json().catch(() => null)) as { id?: string } | null;
+    const id = body?.id;
+    if (!id) return null;
+    await ctx.store?.set(cacheKey, id).catch(() => {});
+    return id;
+  } catch (err) {
+    console.error('[parel-channel] child session get-or-create failed', err);
+    return null;
+  }
+}
+
+/** Drop one child session's cache row (its ase_ was closed under us). */
+export async function invalidateChildSession(
+  ctx: ConnectorContext,
+  childRef: string,
+): Promise<void> {
+  await ctx.store?.delete(childSessionCacheKey(childRef)).catch(() => {});
+}
+
 /** PATCH the session (status / trigger_message_id). Never throws. */
 export async function patchSession(
   ctx: ConnectorContext,
@@ -230,6 +357,57 @@ export async function createChannelInputStep(
   }
 }
 
+/**
+ * Input step for a typed (non-message) dispatch — task/schedule/trigger/
+ * wiki-comment/approval events. Same processing-ring/panel role as the chat
+ * input step; the target routes the record to the source entity instead of a
+ * chat (typed dispatches have no message-level indicator, so the step is the
+ * panel timeline entry, not an indicator driver).
+ */
+export async function createTypedInputStep(
+  ctx: ConnectorContext,
+  sessionId: string,
+  args: {
+    target: { type: string; id: string } | null;
+    triggerType: string;
+    /** WorkItem id — the replay identity. source_id is NOT unique per event
+     * for task WorkItems (it can be the task id), so keying the step on it
+     * would suppress every later event's input step for the same task. */
+    dispatchId: string;
+    sourceId: string;
+    summary: string;
+    senderId?: string;
+  },
+): Promise<ReportResult> {
+  try {
+    const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: jsonHeaders(ctx),
+      body: JSON.stringify({
+        step_type: 'input',
+        ...(args.target ? { target_type: args.target.type, target_id: args.target.id } : {}),
+        // Session-scoped dedup — a failed ack leaves the dispatch replayable
+        // by the catch-up sweep, same rationale as the chat input step.
+        idempotency_key: `input:${args.dispatchId || args.sourceId}`,
+        content: {
+          trigger_type: args.triggerType,
+          trigger_ref: { source_id: args.sourceId },
+          ...(args.senderId ? { sender_id: args.senderId } : {}),
+          summary: args.summary.slice(0, 200),
+        },
+      }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (res.ok) return 'ok';
+    console.error(`[parel-channel] typed input step failed (${res.status})`);
+    return resultForStatus(res.status);
+  } catch (err) {
+    console.error('[parel-channel] typed input step failed', err);
+    return 'failed';
+  }
+}
+
 const ERROR_TEXT_MAX = 500;
 
 /**
@@ -282,16 +460,18 @@ export async function createErrorStep(
   const text = `Turn failed: ${redactSecrets(args.error, knownSecrets)}`.slice(0, ERROR_TEXT_MAX);
   try {
     const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
-    // Same subject-prefix line createTraceStep draws: 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';
+    // Same subject-shape line createTraceStep draws: non-chat subjects must
+    // not target 'chat' or the broadcast lands on a channel no client
+    // watches. Thread-composite subjects address the chat itself.
+    const targetId = subjectEntityId(args.subject);
+    const targetType = stepTargetTypeFor(targetId);
     const res = await fetch(url, {
       method: 'POST',
       headers: jsonHeaders(ctx),
       body: JSON.stringify({
         step_type: 'text',
         target_type: targetType,
-        target_id: args.subject,
+        target_id: targetId,
         // At-most-once today (agent-event pushes are not replayed), but the
         // turnId key makes a future retry path free of duplicate error rows.
         idempotency_key: `error:${args.turnId}`,
@@ -387,15 +567,17 @@ export async function createTraceStep(
   }
   try {
     const url = `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/agents/${parallAgentId(ctx)}/sessions/${sessionId}/steps`;
-    // The subject prefix tells chat turns from external IM turns — channel
-    // steps must not target 'chat' or the server would broadcast them onto
-    // a messages:{chv_} channel no client subscribes to (agent-core's
-    // resolveStepTarget draws the same line).
-    const targetType = subject.startsWith('chv_') ? 'channel_conversation' : 'chat';
+    // The subject shape tells chat turns from external IM / typed-entity
+    // turns — non-chat steps must not target 'chat' or the server would
+    // broadcast them onto a messages:{…} channel no client subscribes to
+    // (agent-core's resolveStepTarget draws the same line). Thread-composite
+    // subjects address the chat itself.
+    const targetId = subjectEntityId(subject);
+    const targetType = stepTargetTypeFor(targetId);
     const res = await fetch(url, {
       method: 'POST',
       headers: jsonHeaders(ctx),
-      body: JSON.stringify({ ...body, target_type: targetType, target_id: subject }),
+      body: JSON.stringify({ ...body, target_type: targetType, target_id: targetId }),
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     });
     if (res.ok) return 'ok';
@@ -407,6 +589,59 @@ 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).
+ */
+export function ackEffect(
+  ctx: ConnectorContext,
+  sourceType: string,
+  sourceId: string,
+): Extract<ConnectorEffect, { type: 'fetch' }> {
+  return {
+    type: 'fetch',
+    request: {
+      url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/ack`,
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${requireAgk(ctx)}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ source_type: sourceType, source_id: sourceId }),
+    },
+    idempotencyKey: `ack:${sourceType}:${sourceId}`,
+  };
+}
+
+/**
+ * Ack ONE dispatch WorkItem by its id. Typed dispatches must use this form:
+ * sibling WorkItems (e.g. a task mutation's task_assign + task_update rows)
+ * share (source_type, source_id), so the by-source ack would terminally
+ * resolve work that was never emitted. Message dispatches keep the by-source
+ * form (one WorkItem per message; the source ack is the established legacy
+ * contract).
+ */
+export function ackByIdEffect(
+  ctx: ConnectorContext,
+  dispatchId: string,
+): Extract<ConnectorEffect, { type: 'fetch' }> {
+  return {
+    type: 'fetch',
+    request: {
+      url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/${dispatchId}/ack`,
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${requireAgk(ctx)}`,
+        'Content-Type': 'application/json',
+      },
+      body: '{}',
+    },
+    idempotencyKey: `ackid:${dispatchId}`,
+  };
+}
+
 /**
  * Lights the pending ring (server broadcasts dispatch.received). Must COMPLETE
  * before the ack effect is returned: MarkReceived only transitions rows still