@parall/parel-channel 1.40.0 → 1.41.0

package/dist/typed-dispatch.js

@@ -0,0 +1,345 @@
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { REQUEST_TIMEOUT_MS } from './session.js';
+/** 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',
+];
+export function isTypedEventType(eventType) {
+    return TYPED_EVENT_TYPES.includes(eventType);
+}
+const STALE = { outcome: 'stale' };
+const PENDING = { outcome: 'pending' };
+function sanitizeMeta(value) {
+    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, ctx) {
+    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) {
+    return data.actor_id ? String(data.actor_id) : undefined;
+}
+function deliveryReason(data) {
+    return data.delivery_reason ? String(data.delivery_reason) : undefined;
+}
+function orgGet(ctx, path) {
+    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) {
+    return status === 404 || status === 403;
+}
+async function planTask(ctx, taskId, eventType, actor) {
+    const res = await orgGet(ctx, `/tasks/${taskId}`);
+    if (!res.ok)
+        return goneStatus(res.status) ? STALE : PENDING;
+    const task = (await res.json().catch(() => 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.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) {
+    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) {
+    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>`;
+}
+async function fetchComment(ctx, commentId) {
+    const res = await orgGet(ctx, `/comments/${commentId}`);
+    if (!res.ok)
+        return goneStatus(res.status) ? STALE : PENDING;
+    const comment = (await res.json().catch(() => 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, commentId, taskId, actor, reason) {
+    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 = null;
+    try {
+        const res = await orgGet(ctx, `/tasks/${taskId}`);
+        if (res.ok)
+            task = (await res.json().catch(() => 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, commentId, actor, reason) {
+    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}`,
+    };
+}
+async function planScheduleFire(ctx, runId) {
+    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));
+    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)}`,
+    };
+}
+async function planExternalTrigger(ctx, runId) {
+    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));
+    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}`,
+    };
+}
+async function planApprovalDecided(ctx, approvalId, chatId, actor) {
+    // 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));
+    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,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parel-channel",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Parall channel plugin for the parel runtime — lets a parel agent treat Parall as a managed_ws channel (receive dispatches, reply via the Parall API)",
   "license": "MIT",
   "repository": {

package/src/channel-prompt.ts

@@ -33,6 +33,13 @@ function sanitizeMeta(value: string): string {
     .trim();
 }
 
+export interface PromptAttachment {
+  id: string;
+  fileName: string;
+  fileSize: number;
+  mimeType: string;
+}
+
 export interface ChatPromptArgs {
   chatId: string;
   /** Display name of the chat; undefined when unresolved (best-effort). */
@@ -40,8 +47,27 @@ export interface ChatPromptArgs {
   /** Sender user id (usr_); display-name enrichment is a follow-up. */
   senderId?: string;
   threadRootId?: string;
-  /** The inbound message text (raw, un-framed). */
+  /** The inbound message text (raw, un-framed); may be empty (attachment-only). */
   text: string;
+  /** Message attachments — rendered as reference lines (agent fetches via CLI). */
+  attachments?: PromptAttachment[];
+}
+
+/**
+ * One reference line per attachment, byte-identical to agent-core's
+ * event-format rendering: the agent learns the attachment EXISTS and pulls
+ * the bytes itself through its sandbox CLI (`parall files download prll://…`)
+ * — same discover-then-fetch contract the standard runtimes use.
+ */
+function attachmentLines(attachments: PromptAttachment[] | undefined): string[] {
+  if (!attachments?.length) return [];
+  return attachments.map((att) => {
+    const sizeStr =
+      att.fileSize >= 1048576
+        ? `${(att.fileSize / 1048576).toFixed(1)}MB`
+        : `${Math.round(att.fileSize / 1024)}KB`;
+    return `[Attachment: prll://${att.id} | ${sanitizeMeta(att.mimeType)} | ${sizeStr} | ${sanitizeMeta(att.fileName)}]`;
+  });
 }
 
 /**
@@ -57,6 +83,7 @@ export function buildChatPrompt(args: ChatPromptArgs): string {
   const lines = [`[Chat: ${chatLabel}]`];
   if (args.senderId) lines.push(`[From: ${sanitizeMeta(args.senderId)}]`);
   if (args.threadRootId) lines.push(`[Thread: ${sanitizeMeta(args.threadRootId)}]`);
+  lines.push(...attachmentLines(args.attachments));
   lines.push('', args.text);
   return lines.join('\n');
 }

package/src/connect.ts

@@ -54,6 +54,16 @@ export function parallAgentId(ctx: ConnectorContext): string {
   return String(ctx.config.parallAgentId ?? '');
 }
 
+/**
+ * Whether this deployment provisions a sandbox (shell + `parall` CLI) for the
+ * agent. Server writes `parallSandbox: "off"` into the connection config only
+ * for conversational-only deployments (no platform E2B key) — an absent field
+ * means sandbox-enabled (every config generated before the field existed was).
+ */
+export function sandboxEnabled(ctx: ConnectorContext): boolean {
+  return String(ctx.config.parallSandbox ?? '') !== 'off';
+}
+
 export function requireAgk(ctx: ConnectorContext): string {
   const agk = ctx.secrets.parallApiKey;
   if (!agk) {

package/src/delivery.ts

@@ -1,7 +1,10 @@
 import type { ChannelDelivery, ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
 import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { childRefKnown } from './fork.js';
 import {
+  ensureChildSession,
   ensureSession,
+  invalidateChildSession,
   invalidateSession,
   patchSession,
   REQUEST_TIMEOUT_MS,
@@ -42,15 +45,18 @@ export async function buildParallDelivery(
     threadRootId?: string;
     envelopeId?: string;
     conversationId?: string;
+    childRef?: string;
   };
   const chatId = route.chatId;
   if (!chatId) {
-    // External IM turn (channel_message): the reply already went out through
-    // the provider clip, agent-invoked — the turn-end text is deliberately
-    // NOT delivered anywhere (same contract as agent-core: plain output is
-    // not the reply). Only run the redundant idle so a binding without
-    // `observe: [turn]` still closes the session.
-    if (route.conversationId) {
+    // No delivery target: external IM turns (channel_message — the reply
+    // already went out through the provider clip, agent-invoked) and typed
+    // dispatch turns (task/schedule/trigger/wiki — the agent acts via its
+    // sandbox CLI). The turn-end text is deliberately NOT delivered anywhere
+    // (same contract as agent-core: plain output is not the reply). Only run
+    // the redundant idle so a binding without `observe: [turn]` still closes
+    // the session.
+    if (route.envelopeId) {
       const sessionId = await ensureSession(ctx, { timeoutMs: 3_000 });
       if (sessionId) {
         await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
@@ -66,7 +72,24 @@ export async function buildParallDelivery(
   // Short timeout: this sits in front of the user-visible reply POST. Cache
   // hit (every dispatch after the agent's first) is a store read; on a slow
   // miss we degrade to a reply without the session link rather than delay it.
-  const sessionId = await ensureSession(ctx, { timeoutMs: 3_000 });
+  // A fork-owned envelope (replyRoute carries childRef) links to the CHILD's
+  // ase_ — its session panel owns this turn, not main's. Same short timeout
+  // as the main path: this sits in front of the user-visible reply POST, so
+  // a slow resolve degrades to a reply without the session link, never a
+  // 10s-delayed message.
+  const childLive = route.childRef ? await childRefKnown(ctx, route.childRef) : false;
+  if (route.childRef && !childLive) {
+    // Terminal stale-child delivery: the fork was purged (New Session) or
+    // given up on (black hole → the opening already re-planned onto main).
+    // Posting would land pre-reset output in the fresh conversation line, or
+    // duplicate a reply main already produced — drop it entirely (no POST,
+    // no retry effect).
+    console.warn('[parel-channel] dropping reply from stale fork', route.childRef);
+    return [];
+  }
+  const sessionId = route.childRef
+    ? await ensureChildSession(ctx, route.childRef, { timeoutMs: 3_000 })
+    : await ensureSession(ctx, { timeoutMs: 3_000 });
 
   const request = {
     url: `${apiUrl}/api/v1/orgs/${orgId}/chats/${chatId}/messages`,
@@ -118,9 +141,15 @@ export async function buildParallDelivery(
   // resolves this connector (npm ^1 fallback path; the artifact path freezes
   // connector+config atomically) would otherwise never idle. Both signals
   // run the same turnEnvelope staleness guard and idle is idempotent, so the
-  // overlap is harmless.
+  // overlap is harmless. Child turns skip the guard entirely — the marker is
+  // main's; a child's own turn ending always idles the child ase_.
   if (sessionId) {
-    await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
+    if (route.childRef) {
+      const result = await patchSession(ctx, sessionId, { status: 'idle' });
+      if (result === 'stale') await invalidateChildSession(ctx, route.childRef);
+    } else {
+      await idleUnlessSuperseded(ctx, route.envelopeId, sessionId);
+    }
   }
   return [];
 }