@parall/parel-channel 1.40.0 → 1.41.0

package/src/typed-dispatch.ts

@@ -0,0 +1,521 @@
+import type { ConnectorContext } from '@parel/plugin-sdk';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { REQUEST_TIMEOUT_MS } from './session.js';
+
+/**
+ * Typed (non-message) dispatches → agent events.
+ *
+ * Mirrors the standard runtimes' coverage (agent-core gateway dispatch.new
+ * switch; hermes adapter's inline port): task_assign / task_update /
+ * task_comment / wiki_comment / schedule.fire / external_trigger /
+ * approval_decided. Each handler pulls the source entity, renders the same
+ * event-body line format agent-core's buildEventBody produces (so an agent
+ * moved between runtimes reads identical events), and returns a plan the
+ * inbound pipeline turns into envelope + progress reporting + ack.
+ *
+ * Semantics carried over from the standard runtimes:
+ * - Permanently-unusable sources (404/403, deleted comments, no_reply hints,
+ *   stale task assignment) resolve to `stale` — the caller acks and drops.
+ * - Transient fetch failures resolve to `pending` — the dispatch stays
+ *   pending and the reconnect catch-up sweep retries it.
+ * - schedule.fire tolerates 404 by contract (post-fire PATCH on target_ids /
+ *   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.
+ */
+
+export interface TypedDispatchData {
+  id?: unknown;
+  event_type?: unknown;
+  source_type?: unknown;
+  source_id?: unknown;
+  chat_id?: unknown;
+  task_id?: unknown;
+  actor_id?: unknown;
+  delivery_reason?: unknown;
+}
+
+/** Dispatch event types this module consumes (everything but the message pair). */
+export const TYPED_EVENT_TYPES = [
+  'task_assign',
+  'task_update',
+  'task_comment',
+  'wiki_comment',
+  'schedule.fire',
+  'external_trigger',
+  'approval_decided',
+] as const;
+
+export function isTypedEventType(eventType: string): boolean {
+  return (TYPED_EVENT_TYPES as readonly string[]).includes(eventType);
+}
+
+/** What the inbound pipeline needs to emit + report one typed event. */
+export interface TypedEventPlan {
+  outcome: 'emit';
+  /** F2 grouping key + agent-event correlation anchor (task/schedule/… id). */
+  subject: string;
+  /** Framed event body (the envelope's data.text). */
+  body: string;
+  /** Input-step routing; null skips the step (no meaningful target). */
+  stepTarget: { type: string; id: string } | null;
+  /** Input-step content bits. */
+  triggerType: string;
+  summary: string;
+  /** Set only for approval_decided: the reply auto-delivers to this chat. */
+  chatId?: string;
+}
+
+export type TypedDispatchResult =
+  | TypedEventPlan
+  /** Permanently unusable — ack and drop. */
+  | { outcome: 'stale' }
+  /** Transient failure — leave pending for the catch-up sweep. */
+  | { outcome: 'pending' };
+
+const STALE: TypedDispatchResult = { outcome: 'stale' };
+const PENDING: TypedDispatchResult = { outcome: 'pending' };
+
+function sanitizeMeta(value: string): string {
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[[\]|]/g, ' ')
+    .trim();
+}
+
+/**
+ * Build the plan for one typed dispatch. Never throws: any unexpected error
+ * degrades to `pending` (same posture as the message path — the sweep
+ * retries, and a poisoned row eventually surfaces as a stuck pending count).
+ */
+export async function planTypedDispatch(
+  data: TypedDispatchData,
+  ctx: ConnectorContext,
+): Promise<TypedDispatchResult> {
+  const eventType = String(data.event_type ?? '');
+  const sourceId = data.source_id ? String(data.source_id) : '';
+  try {
+    switch (eventType) {
+      case 'task_assign':
+      case 'task_update': {
+        const taskId = data.task_id ? String(data.task_id) : sourceId;
+        if (!taskId) return STALE;
+        return await planTask(ctx, taskId, eventType, actorId(data));
+      }
+      case 'task_comment': {
+        const taskId = data.task_id ? String(data.task_id) : '';
+        if (!sourceId || !taskId) return STALE;
+        return await planTaskComment(ctx, sourceId, taskId, actorId(data), deliveryReason(data));
+      }
+      case 'wiki_comment': {
+        if (!sourceId) return STALE;
+        return await planWikiComment(ctx, sourceId, actorId(data), deliveryReason(data));
+      }
+      case 'schedule.fire': {
+        if (!sourceId) return STALE;
+        return await planScheduleFire(ctx, sourceId);
+      }
+      case 'external_trigger': {
+        if (!sourceId) return STALE;
+        return await planExternalTrigger(ctx, sourceId);
+      }
+      case 'approval_decided': {
+        if (!sourceId) return STALE;
+        const chatId = data.chat_id ? String(data.chat_id) : undefined;
+        return await planApprovalDecided(ctx, sourceId, chatId, actorId(data));
+      }
+      default:
+        return PENDING; // unknown typed event — future work, never ack-drop
+    }
+  } catch (err) {
+    console.error(`[parel-channel] typed dispatch ${eventType} failed`, err);
+    return PENDING;
+  }
+}
+
+function actorId(data: TypedDispatchData): string | undefined {
+  return data.actor_id ? String(data.actor_id) : undefined;
+}
+
+function deliveryReason(data: TypedDispatchData): string | undefined {
+  return data.delivery_reason ? String(data.delivery_reason) : undefined;
+}
+
+function orgGet(ctx: ConnectorContext, path: string): Promise<Response> {
+  return fetch(`${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}${path}`, {
+    headers: { Authorization: `Bearer ${requireAgk(ctx)}` },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+}
+
+/** 404/403 are permanent for a dispatch pointer; anything else is transient. */
+function goneStatus(status: number): boolean {
+  return status === 404 || status === 403;
+}
+
+// ---------------------------------------------------------------------------
+// task_assign / task_update
+
+interface TaskRow {
+  id?: string;
+  identifier?: string;
+  title?: string;
+  status?: string;
+  priority?: string;
+  description?: string;
+  project_id?: string;
+  parent_id?: string;
+  assignee_id?: string;
+  creator_id?: string;
+  updated_at?: string;
+}
+
+async function planTask(
+  ctx: ConnectorContext,
+  taskId: string,
+  eventType: 'task_assign' | 'task_update',
+  actor?: string,
+): Promise<TypedDispatchResult> {
+  const res = await orgGet(ctx, `/tasks/${taskId}`);
+  if (!res.ok) return goneStatus(res.status) ? STALE : PENDING;
+  const task = (await res.json().catch(() => null)) as TaskRow | null;
+  if (!task?.id) return STALE;
+
+  // Same staleness rule as the standard runtimes (gateway handleTaskDispatch):
+  // an update only concerns this agent while it is the assignee, or — for
+  // updates — the creator watching its own delegation. Anything else is a
+  // stale row (reassigned before delivery) — ack it away.
+  const me = String((ctx.config as Record<string, unknown>).parallAgentId ?? '');
+  const isAssignee = task.assignee_id === me;
+  const isCreatorUpdate = eventType === 'task_update' && task.creator_id === me;
+  if (me && !isAssignee && !isCreatorUpdate) return STALE;
+
+  // Metadata lines pass through sanitizeMeta — a task title with newlines or
+  // brackets must not be able to forge [Event: …] header lines (the body
+  // below is user content by definition and stays verbatim).
+  const label = task.identifier
+    ? `${sanitizeMeta(task.identifier)} (prll://${task.id})`
+    : `prll://${task.id}`;
+  // Standard runtimes collapse task_update onto the SAME task.assigned event
+  // body (agent-core handleTaskDispatch → handleTaskAssignment) — managed
+  // agents must read the identical contract, and the shared task skill only
+  // teaches [Event: task.assigned].
+  const lines = [`[Event: task.assigned]`, `[Task: ${label}]`];
+  const by = actor ?? task.creator_id;
+  if (by) {
+    lines.push(`[Assigned by: prll://${by}]`);
+  }
+  lines.push(`Title: ${sanitizeMeta(task.title ?? '')}`);
+  lines.push(
+    `Status: ${sanitizeMeta(task.status ?? '')}`,
+    `Priority: ${sanitizeMeta(task.priority ?? '')}`,
+  );
+  if (task.project_id) lines.push(`Project: prll://${task.project_id}`);
+  if (task.parent_id) lines.push(`Parent: prll://${task.parent_id}`);
+  if (task.description) lines.push('', task.description);
+  lines.push('', taskActionHint(task.id));
+
+  return {
+    outcome: 'emit',
+    subject: task.id,
+    body: lines.join('\n'),
+    stepTarget: { type: 'task', id: task.id },
+    triggerType: eventType,
+    summary: `${eventType === 'task_assign' ? 'Task assigned' : 'Task updated'}: ${task.title ?? task.id}`,
+  };
+}
+
+/**
+ * schedule.fire / external_trigger turns have NO delivery target — the
+ * managed-agent base behavior ("your reply auto-delivers") does not apply,
+ * so without this line a normal completion silently disappears.
+ */
+function cliOnlyOutputHint(kind: 'schedule' | 'trigger'): string {
+  return `<system-reminder>This ${kind} event has NO conversation attached — your plain text output is NOT delivered anywhere. To surface results, act through your sandbox CLI (e.g. \`parall messages send <chatId> --text "…"\` to a relevant chat, \`parall tasks update …\`, or the target referenced above).</system-reminder>`;
+}
+
+function taskActionHint(taskId: string): string {
+  return `<system-reminder>Act on this task with your sandbox CLI: \`parall tasks get ${taskId}\`, \`parall tasks update ${taskId} --status …\`, \`parall tasks comments add ${taskId} --body "…"\`. Your plain text output is NOT delivered anywhere for task events.</system-reminder>`;
+}
+
+// ---------------------------------------------------------------------------
+// task_comment / wiki_comment
+
+interface CommentRow {
+  id?: string;
+  body?: string;
+  author_id?: string;
+  author?: { display_name?: string };
+  target_uri?: string;
+  hints?: { no_reply?: boolean };
+}
+
+async function fetchComment(
+  ctx: ConnectorContext,
+  commentId: string,
+): Promise<{ comment: CommentRow } | TypedDispatchResult> {
+  const res = await orgGet(ctx, `/comments/${commentId}`);
+  if (!res.ok) return goneStatus(res.status) ? STALE : PENDING;
+  const comment = (await res.json().catch(() => null)) as CommentRow | null;
+  if (!comment?.id) return STALE;
+  // no_reply-hinted comments are informational — same drop the gateway does.
+  if (comment.hints?.no_reply) return STALE;
+  return { comment };
+}
+
+async function planTaskComment(
+  ctx: ConnectorContext,
+  commentId: string,
+  taskId: string,
+  actor: string | undefined,
+  reason: string | undefined,
+): Promise<TypedDispatchResult> {
+  const fetched = await fetchComment(ctx, commentId);
+  if (!('comment' in fetched)) return fetched;
+  const comment = fetched.comment;
+
+  // Task context is optional garnish (the gateway treats it the same way).
+  let task: TaskRow | null = null;
+  try {
+    const res = await orgGet(ctx, `/tasks/${taskId}`);
+    if (res.ok) task = (await res.json().catch(() => null)) as TaskRow | null;
+  } catch {
+    /* optional */
+  }
+
+  const lines = [`[Event: task.comment.created]`];
+  const label = task?.identifier
+    ? `${sanitizeMeta(task.identifier)} (prll://${taskId})`
+    : `prll://${taskId}`;
+  lines.push(`[Task: ${label}]`);
+  if (task?.title) lines.push(`Title: ${sanitizeMeta(task.title)}`);
+  if (task?.status || task?.priority) {
+    // Task context parity with agent-core's task_comment body.
+    lines.push(
+      `Status: ${sanitizeMeta(task.status ?? '')}`,
+      `Priority: ${sanitizeMeta(task.priority ?? '')}`,
+    );
+  }
+  if (reason) lines.push(`[Delivery: ${sanitizeMeta(reason)}]`);
+  const author = comment.author?.display_name ?? actor ?? 'unknown';
+  lines.push(`[From: ${sanitizeMeta(author)} (prll://${comment.author_id ?? ''})]`);
+  lines.push(`[Comment ID: prll://${comment.id}]`);
+  lines.push('', comment.body ?? '');
+  lines.push('', taskActionHint(taskId));
+
+  return {
+    outcome: 'emit',
+    subject: taskId,
+    body: lines.join('\n'),
+    stepTarget: { type: 'task', id: taskId },
+    triggerType: 'task_comment',
+    summary: `Task comment by ${author}`,
+  };
+}
+
+async function planWikiComment(
+  ctx: ConnectorContext,
+  commentId: string,
+  actor: string | undefined,
+  reason: string | undefined,
+): Promise<TypedDispatchResult> {
+  const fetched = await fetchComment(ctx, commentId);
+  if (!('comment' in fetched)) return fetched;
+  const comment = fetched.comment;
+
+  // Routing key = scheme-stripped target_uri (same as agent-core's
+  // parseWikiCommentTarget): distinct pages / anchors / changesets group
+  // into distinct subjects instead of colliding on one wiki id.
+  const targetUri = comment.target_uri ?? '';
+  const routingKey = targetUri.replace(/^prll:\/\//, '') || `comment:${comment.id}`;
+  const isChangeset = routingKey.startsWith('wcs_');
+
+  const lines = [`[Event: wiki.comment.created]`];
+  lines.push(`[${isChangeset ? 'Wiki Changeset' : 'Wiki'}: prll://${routingKey}]`);
+  if (reason) lines.push(`[Delivery: ${sanitizeMeta(reason)}]`);
+  const author = comment.author?.display_name ?? actor ?? 'unknown';
+  lines.push(`[From: ${sanitizeMeta(author)} (prll://${comment.author_id ?? ''})]`);
+  lines.push(`[Comment ID: prll://${comment.id}]`);
+  lines.push('', comment.body ?? '');
+  lines.push(
+    '',
+    `<system-reminder>Reply with your sandbox CLI: \`parall comments add --target prll://${routingKey} --body "…"\` (read context first with \`parall comments get ${comment.id}\`). Your plain text output is NOT delivered anywhere for wiki events.</system-reminder>`,
+  );
+
+  return {
+    outcome: 'emit',
+    subject: routingKey,
+    body: lines.join('\n'),
+    stepTarget: { type: 'wiki', id: routingKey },
+    triggerType: 'wiki_comment',
+    summary: `Wiki comment by ${author}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// schedule.fire
+
+interface ScheduleRunRow {
+  id?: string;
+  schedule_id?: string;
+  fired_description?: string;
+  scheduled_fire_at?: string;
+  fired_attached_uri?: string;
+}
+
+async function planScheduleFire(
+  ctx: ConnectorContext,
+  runId: string,
+): Promise<TypedDispatchResult> {
+  const res = await orgGet(ctx, `/schedule_runs/${runId}`);
+  if (!res.ok) {
+    if (res.status === 404) {
+      // Contract: warn + ack + drop (a post-fire PATCH can revoke access to
+      // a delivered snapshot — expected, but keep it findable in triage).
+      console.warn(`[parel-channel] schedule run ${runId} not accessible (404), dropping`);
+      return STALE;
+    }
+    return goneStatus(res.status) ? STALE : PENDING;
+  }
+  const run = (await res.json().catch(() => null)) as ScheduleRunRow | null;
+  if (!run?.id || !run.schedule_id) return STALE;
+
+  const lines = [`[Event: schedule.fired]`];
+  lines.push(`[Schedule: prll://${run.schedule_id}]`);
+  lines.push(`[Run: prll://${run.id}]`);
+  if (run.scheduled_fire_at) lines.push(`[Scheduled at: ${sanitizeMeta(run.scheduled_fire_at)}]`);
+  if (run.fired_attached_uri) lines.push(`[Attached: ${sanitizeMeta(run.fired_attached_uri)}]`);
+  lines.push('', run.fired_description ?? '');
+  lines.push('', cliOnlyOutputHint('schedule'));
+
+  return {
+    outcome: 'emit',
+    subject: run.schedule_id,
+    body: lines.join('\n'),
+    stepTarget: { type: 'schedule', id: run.schedule_id },
+    triggerType: 'schedule_fire',
+    summary: `Schedule fired: ${(run.fired_description ?? run.id).slice(0, 120)}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// external_trigger
+
+interface ExternalTriggerRunRow {
+  id?: string;
+  trigger_id?: string;
+  trigger_name?: string;
+  agent_input_body?: string;
+  connection_id?: string;
+  connection_display_name?: string;
+  connection_source_type?: string;
+  ingress_event_id?: string;
+  ingress_event_type?: string;
+  trigger_snapshot?: { attached_to_uri?: unknown };
+}
+
+async function planExternalTrigger(
+  ctx: ConnectorContext,
+  runId: string,
+): Promise<TypedDispatchResult> {
+  const res = await orgGet(ctx, `/external-trigger-runs/${runId}`);
+  if (!res.ok) {
+    if (res.status === 404) {
+      console.warn(`[parel-channel] external trigger run ${runId} not accessible (404), dropping`);
+      return STALE;
+    }
+    return goneStatus(res.status) ? STALE : PENDING;
+  }
+  const run = (await res.json().catch(() => null)) as ExternalTriggerRunRow | null;
+  if (!run?.id || !run.trigger_id) return STALE;
+
+  const lines = [`[Event: external.trigger]`];
+  const triggerLabel = run.trigger_name
+    ? `${sanitizeMeta(run.trigger_name)} (prll://${run.trigger_id})`
+    : `prll://${run.trigger_id}`;
+  lines.push(`[Trigger: ${triggerLabel}]`);
+  lines.push(`[Run: prll://${run.id}]`);
+  if (run.connection_id) {
+    const label = run.connection_display_name
+      ? `${sanitizeMeta(run.connection_display_name)} (prll://${run.connection_id})`
+      : `prll://${run.connection_id}`;
+    lines.push(`[Connection: ${label}]`);
+  }
+  if (run.ingress_event_id) lines.push(`[Ingress: prll://${run.ingress_event_id}]`);
+  const attached = run.trigger_snapshot?.attached_to_uri;
+  if (typeof attached === 'string' && attached) lines.push(`[Attached: ${sanitizeMeta(attached)}]`);
+  if (run.connection_source_type) {
+    lines.push(`[Source: ${sanitizeMeta(run.connection_source_type)}]`);
+  }
+  if (run.ingress_event_type) {
+    lines.push(`[External event: ${sanitizeMeta(run.ingress_event_type)}]`);
+  }
+  lines.push('', run.agent_input_body ?? '');
+  lines.push('', cliOnlyOutputHint('trigger'));
+
+  return {
+    outcome: 'emit',
+    subject: run.trigger_id,
+    body: lines.join('\n'),
+    stepTarget: { type: 'external_trigger', id: run.trigger_id },
+    triggerType: 'external_trigger',
+    summary: `External trigger: ${run.trigger_name ?? run.trigger_id}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// approval_decided
+
+interface ApprovalRow {
+  id?: string;
+  title?: string;
+  status?: string;
+  execution_status?: string;
+  chat_id?: string;
+  decided_by?: string;
+}
+
+async function planApprovalDecided(
+  ctx: ConnectorContext,
+  approvalId: string,
+  chatId: string | undefined,
+  actor: string | undefined,
+): Promise<TypedDispatchResult> {
+  // Approvals are NOT org-scoped in the API surface (ENDPOINTS.APPROVAL).
+  const res = await fetch(`${parallApiUrl(ctx)}/api/v1/approvals/${approvalId}`, {
+    headers: { Authorization: `Bearer ${requireAgk(ctx)}` },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) return goneStatus(res.status) ? STALE : PENDING;
+  const approval = (await res.json().catch(() => null)) as ApprovalRow | null;
+  if (!approval?.id) return STALE;
+
+  const statusLabel = approval.status === 'approved' ? 'Approved' : 'Rejected';
+  const execInfo = approval.execution_status ? ` | execution: ${approval.execution_status}` : '';
+  const resolvedChat = chatId ?? approval.chat_id;
+
+  const lines = [`[Event: approval.decided]`];
+  lines.push(`[Approval: prll://${approval.id}]`);
+  if (resolvedChat) lines.push(`[Chat: prll://${resolvedChat}]`);
+  lines.push(`[Decided by: ${sanitizeMeta(actor ?? approval.decided_by ?? 'system')}]`);
+  lines.push('', `${statusLabel}: ${approval.title ?? ''}${execInfo}`);
+
+  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.
+    subject: resolvedChat ?? approval.id,
+    body: lines.join('\n'),
+    stepTarget: resolvedChat ? { type: 'chat', id: resolvedChat } : null,
+    triggerType: 'approval_decided',
+    summary: `${statusLabel}: ${approval.title ?? approval.id}`,
+    chatId: resolvedChat,
+  };
+}