@parall/parel-channel 1.40.0 → 1.41.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAK1D;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,SAAS,EAAE,gBAMhB,CAAC;AAEF,eAAe,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAU1D;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,SAAS,EAAE,gBAOhB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 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.
  *
@@ -19,6 +19,7 @@ const connector = {
     connect: connectParall,
     onOpen: catchUpParall,
     onMessage: handleParallFrame,
+    onTimer: handleParallTimer,
     onAgentEvent: handleParallAgentEvent,
     deliver: buildParallDelivery,
 };

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

@@ -0,0 +1,63 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,16 @@
+/** 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/dist/session.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectorContext } from '@parel/plugin-sdk';
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
 /**
  * Best-effort progress reporting: dispatch received, AgentSession lifecycle,
  * and input steps — the signals parall's message-level activity indicator and
@@ -33,6 +33,32 @@ export declare function reportingEnabled(ctx: ConnectorContext): boolean;
  * simply never read again.)
  */
 export declare const TURN_ENVELOPE_KEY = "turnEnvelope:main";
+export declare const SESSION_CACHE_KEY = "session:main";
+/**
+ * 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 declare function conversationKey(chatId: string, threadRootId?: string): string;
+/**
+ * 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 declare function subjectEntityId(subject: string): string;
+/**
+ * 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 declare function stepTargetTypeFor(subject: string): string;
 /**
  * 'stale' means the session id no longer accepts writes (closed/superseded —
  * e.g. the New Session control ended it): callers invalidate the cache and
@@ -53,6 +79,26 @@ export declare function invalidateSession(ctx: ConnectorContext): Promise<void>;
 export declare function ensureSession(ctx: ConnectorContext, opts?: {
     timeoutMs?: number;
 }): Promise<string | null>;
+/**
+ * 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 declare function fetchMainSessionFresh(ctx: ConnectorContext): Promise<string | 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 declare function ensureChildSession(ctx: ConnectorContext, childRef: string, opts?: {
+    timeoutMs?: number;
+}): Promise<string | null>;
+/** Drop one child session's cache row (its ase_ was closed under us). */
+export declare function invalidateChildSession(ctx: ConnectorContext, childRef: string): Promise<void>;
 /** PATCH the session (status / trigger_message_id). Never throws. */
 export declare function patchSession(ctx: ConnectorContext, sessionId: string, body: {
     status: 'active' | 'idle';
@@ -87,6 +133,27 @@ export declare function createChannelInputStep(ctx: ConnectorContext, sessionId:
     text: string;
     sentAt?: string;
 }): Promise<ReportResult>;
+/**
+ * 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 declare 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>;
 /**
  * Credential redaction for runtime error strings that become user-visible
  * step content. Two layers: every secret VALUE the connector actually holds
@@ -148,6 +215,26 @@ export declare function createTraceStep(ctx: ConnectorContext, sessionId: string
     durationMs?: number;
     outputPreview?: string;
 }): Promise<ReportResult>;
+/**
+ * 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 declare function ackEffect(ctx: ConnectorContext, sourceType: string, sourceId: string): Extract<ConnectorEffect, {
+    type: 'fetch';
+}>;
+/**
+ * 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 declare function ackByIdEffect(ctx: ConnectorContext, dispatchId: string): Extract<ConnectorEffect, {
+    type: 'fetch';
+}>;
 /**
  * Lights the pending ring (server broadcasts dispatch.received). Must COMPLETE
  * before the ack effect is returned: MarkReceived only transitions rows still

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -35,7 +35,54 @@ export function reportingEnabled(ctx) {
  * 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) => `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, threadRootId) {
+    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) {
+    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) {
+    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';
+}
 function resultForStatus(status) {
     return status === 404 || status === 409 || status === 410 ? 'stale' : 'failed';
 }
@@ -87,6 +134,87 @@ export async function ensureSession(ctx, opts = {}) {
         return null;
     }
 }
+/**
+ * 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) {
+    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));
+        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, childRef, opts = {}) {
+    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));
+        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, childRef) {
+    await ctx.store?.delete(childSessionCacheKey(childRef)).catch(() => { });
+}
 /** PATCH the session (status / trigger_message_id). Never throws. */
 export async function patchSession(ctx, sessionId, body) {
     try {
@@ -194,6 +322,44 @@ export async function createChannelInputStep(ctx, sessionId, args) {
         return 'failed';
     }
 }
+/**
+ * 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, sessionId, args) {
+    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;
 /**
  * Credential redaction for runtime error strings that become user-visible
@@ -239,16 +405,18 @@ export async function createErrorStep(ctx, sessionId, args) {
     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}`,
@@ -331,15 +499,17 @@ export async function createTraceStep(ctx, sessionId, subject, event) {
     }
     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)
@@ -352,6 +522,50 @@ export async function createTraceStep(ctx, sessionId, subject, event) {
         return 'failed';
     }
 }
+/**
+ * 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, sourceType, sourceId) {
+    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, dispatchId) {
+    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

package/dist/typed-dispatch.d.ts

@@ -0,0 +1,76 @@
+import type { ConnectorContext } from '@parel/plugin-sdk';
+/**
+ * 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 declare const TYPED_EVENT_TYPES: readonly ["task_assign", "task_update", "task_comment", "wiki_comment", "schedule.fire", "external_trigger", "approval_decided"];
+export declare function isTypedEventType(eventType: string): boolean;
+/** 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';
+};
+/**
+ * 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 declare function planTypedDispatch(data: TypedDispatchData, ctx: ConnectorContext): Promise<TypedDispatchResult>;
+//# sourceMappingURL=typed-dispatch.d.ts.map

package/dist/typed-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-dispatch.d.ts","sourceRoot":"","sources":["../src/typed-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,kIAQpB,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAC3B,cAAc;AAChB,2CAA2C;GACzC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE;AACtB,gEAAgE;GAC9D;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAY3B;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,iBAAiB,EACvB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAwC9B"}