@parall/agent-core 1.31.0 → 1.32.1

package/dist/telemetry.js

@@ -0,0 +1,205 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { trace, metrics, SpanStatusCode, } from '@opentelemetry/api';
+import { SeverityNumber } from '@opentelemetry/api-logs';
+let initialized = false;
+let shutdownFn = null;
+let tracer = null;
+let dispatchCounter = null;
+let dispatchDuration = null;
+let missingReplyCounter = null;
+let otelLogger = null;
+function resolveTargetType(targetId) {
+    if (targetId.startsWith('cht_'))
+        return 'chat';
+    if (targetId.startsWith('tsk_'))
+        return 'task';
+    if (targetId.startsWith('sch_'))
+        return 'schedule';
+    return 'unknown';
+}
+/**
+ * Initialize agent telemetry. All agents export OTLP to the Parall
+ * telemetry-service (`PRLL_API_URL/otel`), authenticated with `PRLL_API_KEY`.
+ * The service canonicalizes identity from the token and proxies to SigNoz.
+ *
+ * Resource attributes include machine/agent/org identity from env.
+ * Returns a no-op handle when `PRLL_API_URL` is absent (local dev).
+ */
+export async function initAgentTelemetry(serviceName, runtimeType) {
+    const noopHandle = { shutdown: async () => { } };
+    const apiUrl = process.env.PRLL_API_URL;
+    const apiKey = process.env.PRLL_API_KEY;
+    if (!apiUrl || !apiKey) {
+        return noopHandle;
+    }
+    try {
+        const otelEndpoint = apiUrl.replace(/\/$/, '') + '/otel';
+        const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-proto');
+        const { OTLPMetricExporter } = await import('@opentelemetry/exporter-metrics-otlp-proto');
+        const { OTLPLogExporter } = await import('@opentelemetry/exporter-logs-otlp-proto');
+        const { NodeTracerProvider, BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-node');
+        const { MeterProvider, PeriodicExportingMetricReader } = await import('@opentelemetry/sdk-metrics');
+        const { LoggerProvider, BatchLogRecordProcessor } = await import('@opentelemetry/sdk-logs');
+        const { Resource } = await import('@opentelemetry/resources');
+        const resource = new Resource({
+            'service.name': serviceName,
+            'service.version': process.env.npm_package_version || 'unknown',
+            'deployment.environment.name': process.env.PRLL_SERVER_ENV || process.env.NODE_ENV || 'development',
+            'parall.runtime_type': runtimeType,
+            'parall.agent_id': process.env.PRLL_AGENT_ID || '',
+            'parall.machine_id': process.env.PRLL_MACHINE_ID || '',
+            'parall.org_id': process.env.PRLL_ORG_ID || '',
+            'parall.daemon_mode': process.env.PRLL_DAEMON_MODE === '1',
+        });
+        const authHeaders = { Authorization: `Bearer ${apiKey}` };
+        const traceExporter = new OTLPTraceExporter({
+            url: `${otelEndpoint}/v1/traces`,
+            headers: authHeaders,
+        });
+        const tracerProvider = new NodeTracerProvider({ resource });
+        tracerProvider.addSpanProcessor(new BatchSpanProcessor(traceExporter));
+        tracerProvider.register();
+        const metricExporter = new OTLPMetricExporter({
+            url: `${otelEndpoint}/v1/metrics`,
+            headers: authHeaders,
+        });
+        const metricReader = new PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            exportIntervalMillis: 15_000,
+        });
+        const meterProvider = new MeterProvider({ resource, readers: [metricReader] });
+        metrics.setGlobalMeterProvider(meterProvider);
+        const logExporter = new OTLPLogExporter({
+            url: `${otelEndpoint}/v1/logs`,
+            headers: authHeaders,
+        });
+        const loggerProvider = new LoggerProvider({ resource });
+        loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(logExporter));
+        const meter = metrics.getMeter('parall.agent');
+        tracer = trace.getTracer('parall.agent');
+        otelLogger = loggerProvider.getLogger('parall.agent');
+        dispatchCounter = meter.createCounter('parall.dispatch.count', {
+            description: 'Number of dispatch cycles completed',
+        });
+        dispatchDuration = meter.createHistogram('parall.dispatch.duration', {
+            description: 'Dispatch cycle duration in milliseconds',
+            unit: 'ms',
+        });
+        missingReplyCounter = meter.createCounter('parall.dispatch.missing_reply', {
+            description: 'Dispatches where agent produced text but sent no reply message',
+        });
+        initialized = true;
+        shutdownFn = async () => {
+            await tracerProvider.forceFlush();
+            await meterProvider.forceFlush();
+            await loggerProvider.forceFlush();
+            await tracerProvider.shutdown();
+            await meterProvider.shutdown();
+            await loggerProvider.shutdown();
+        };
+        return {
+            shutdown: async () => {
+                if (shutdownFn)
+                    await shutdownFn();
+            },
+        };
+    }
+    catch {
+        return noopHandle;
+    }
+}
+export function startDispatchSpan(event, runtimeType, sessionKey) {
+    if (!initialized || !tracer)
+        return null;
+    return tracer.startSpan('parall.dispatch', {
+        attributes: {
+            'dispatch.target_type': resolveTargetType(event.targetId),
+            'dispatch.event_type': event.type,
+            'dispatch.runtime_type': runtimeType,
+            'dispatch.session_key': sessionKey,
+            'dispatch.message_id': event.messageId,
+            'dispatch.target_id': event.targetId,
+        },
+    });
+}
+export function endDispatchSpan(span, metricsSnapshot, error) {
+    if (!span)
+        return;
+    if (metricsSnapshot) {
+        span.setAttributes({
+            'dispatch.deliver_text_chunks': metricsSnapshot.deliver_text_chunks,
+            'dispatch.deliver_text_chars': metricsSnapshot.deliver_text_chars,
+            'dispatch.message_send_attempts': metricsSnapshot.message_send_attempts,
+            'dispatch.message_send_successes': metricsSnapshot.message_send_successes,
+            'dispatch.no_reply_called': metricsSnapshot.no_reply_called,
+            'dispatch.tool_call_count': metricsSnapshot.tool_call_count,
+            'dispatch.duration_ms': Date.now() - metricsSnapshot.started_at,
+        });
+    }
+    if (error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+        span.recordException(error instanceof Error ? error : new Error(String(error)));
+    }
+    span.end();
+}
+export function recordDispatchMetric(event, runtimeType, durationMs) {
+    if (!initialized)
+        return;
+    const attrs = {
+        target_type: resolveTargetType(event.targetId),
+        event_type: event.type,
+        runtime_type: runtimeType,
+    };
+    dispatchCounter?.add(1, attrs);
+    dispatchDuration?.record(durationMs, attrs);
+}
+export function recordMissingReply(runtimeType) {
+    if (!initialized)
+        return;
+    missingReplyCounter?.add(1, { runtime_type: runtimeType });
+}
+const sessionKeyStorage = new AsyncLocalStorage();
+export function runWithSessionKey(sessionKey, fn) {
+    return sessionKeyStorage.run(sessionKey, fn);
+}
+/**
+ * Create a GatewayLogger that forwards all levels to OTLP logs.
+ * Two layers: "agent" (runtime) and "daemon".
+ */
+export function createOtelLogger(layer, prefix) {
+    const ts = () => new Date().toISOString();
+    const emit = (severity, msg) => {
+        if (!otelLogger)
+            return;
+        const severityNumber = severity === 'ERROR'
+            ? SeverityNumber.ERROR
+            : severity === 'WARN'
+                ? SeverityNumber.WARN
+                : SeverityNumber.INFO;
+        const attrs = { 'log.layer': layer, 'log.prefix': prefix };
+        const sk = sessionKeyStorage.getStore();
+        if (sk)
+            attrs['session.key'] = sk;
+        otelLogger.emit({
+            severityNumber,
+            severityText: severity,
+            body: msg,
+            attributes: attrs,
+        });
+    };
+    return {
+        info: (msg) => {
+            console.log(`${ts()} [${prefix}] ${msg}`);
+            emit('INFO', msg);
+        },
+        warn: (msg) => {
+            console.warn(`${ts()} [${prefix}] ${msg}`);
+            emit('WARN', msg);
+        },
+        error: (msg) => {
+            console.error(`${ts()} [${prefix}] ${msg}`);
+            emit('ERROR', msg);
+        },
+        child: (sub) => createOtelLogger(layer, `${prefix}:${sub}`),
+    };
+}

package/dist/types.d.ts

@@ -26,10 +26,17 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: "message" | "task" | "task_comment" | "schedule" | "approval";
+    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'approval';
     targetId: string;
     targetName?: string;
     targetType?: string;
+    /**
+     * Full `prll://` target URI to reply on, used for wiki_comment events where
+     * the reply goes back to the same wiki page / changeset via
+     * `parall comments add --target <uri>`. Carried separately from `targetId`
+     * (a bare entity id) because the reply needs the full URI incl. path/anchor.
+     */
+    replyTargetUri?: string;
     deliveryReason?: string;
     senderId: string;
     senderName: string;
@@ -50,7 +57,16 @@ export type ParallEvent = {
     /** Original event timestamp (e.g., message.created_at). When present,
      *  input steps use this instead of server insertion time for ordering. */
     sentAt?: string;
-    ackSourceType?: "message" | "task_activity" | "comment" | "schedule_run";
+    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run';
     ackSourceId?: string;
+    /** Unread message count in the target chat since agent's last interaction. */
+    unreadCount?: number;
+    /** Channel cursor: the last message ID the agent read. */
+    unreadSince?: string;
+    /** For thread replies: total replies and unread replies in the thread. */
+    threadReplyCount?: number;
+    threadUnreadCount?: number;
+    /** Thread cursor: the last reply ID the agent read in this thread. */
+    threadUnreadSince?: string;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,16 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.31.0"
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.57.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.57.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-logs": "^0.57.0",
+    "@opentelemetry/sdk-metrics": "^1.30.0",
+    "@opentelemetry/sdk-trace-node": "^1.30.0",
+    "@parall/sdk": "1.32.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bridge-workspace.ts

@@ -50,7 +50,7 @@ See \`docs/engineering-design/agent-dm-loop-prevention.md\` § Layer 0 for why p
 
 When you try an action (e.g., archive a chat) and receive a PERMISSION_DENIED error, you can request someone with permission to do it:
 
-1. The error includes a \`PERMISSION_DENIED\` code. For commonly approvable actions (archive, delete, restore), a \`Tip:\` line with an approval-request template is printed — copy it and fill in the remaining placeholders (\`--chat\`, \`--title\`, \`--reason\`)
+1. The error includes a \`PERMISSION_DENIED\` code plus the denied \`action\` and \`resource_uri\`. If the action is approvable (decided by the server — no fixed allowlist), a \`Request approval:\` line with an approval command is printed — fill in its \`--chat\`, \`--title\`, \`--reason\` placeholders and run it. If it is not approvable, the output says so; ask a human with permission instead.
 2. Request approval: \`parall approvals request --action chat.archive --resource prll://cht_123 --chat prll://cht_456 --title "Archive #old-project" --reason "Channel inactive"\`
 3. A card will appear in the specified chat for someone with permission to approve
 4. Check the result: \`parall approvals get prll://<id>\` or wait: \`parall approvals wait prll://<id> --timeout 300\`
@@ -84,9 +84,9 @@ Messages may arrive with a \`[Thread: prll://msg_xxx]\` line in the event block,
 
 /** Extracts the `command` string from a shell/bash tool call's input payload. */
 export function extractShellCommand(input: unknown): string | undefined {
-  if (!input || typeof input !== "object") return undefined;
+  if (!input || typeof input !== 'object') return undefined;
   const command = (input as { command?: unknown }).command;
-  return typeof command === "string" && command.trim() ? command.trim() : undefined;
+  return typeof command === 'string' && command.trim() ? command.trim() : undefined;
 }
 
 /**
@@ -101,24 +101,24 @@ export function extractShellCommand(input: unknown): string | undefined {
  * `no-reply` subcommand).
  */
 export function parseParallCliInvocation(command: string): string[] | null {
-  const tokens = command.replace(/\s+/g, " ").trim().split(" ");
+  const tokens = command.replace(/\s+/g, ' ').trim().split(' ');
   let i = 0;
-  if (tokens[i] === "parall") {
+  if (tokens[i] === 'parall') {
     i++;
-  } else if (tokens[i] === "npx") {
+  } else if (tokens[i] === 'npx') {
     i++;
-    while (i < tokens.length && tokens[i].startsWith("-")) i++;
+    while (i < tokens.length && tokens[i].startsWith('-')) i++;
     if (i >= tokens.length || !/^@parall\/cli(?:@.+)?$/.test(tokens[i])) return null;
     i++;
-  } else if (tokens[i] === "pnpm") {
+  } else if (tokens[i] === 'pnpm') {
     i++;
-    if (i < tokens.length && (tokens[i] === "exec" || tokens[i] === "dlx")) i++;
-    if (i >= tokens.length || tokens[i] !== "parall") return null;
+    if (i < tokens.length && (tokens[i] === 'exec' || tokens[i] === 'dlx')) i++;
+    if (i >= tokens.length || tokens[i] !== 'parall') return null;
     i++;
   } else {
     return null;
   }
-  return tokens.slice(i).filter((t) => !t.startsWith("-"));
+  return tokens.slice(i).filter((t) => !t.startsWith('-'));
 }
 
 /**
@@ -132,7 +132,7 @@ export function isParallSendCommand(command: string | undefined): boolean {
   if (!command) return false;
   const sub = parseParallCliInvocation(command);
   if (!sub || sub.length === 0) return false;
-  return sub[0] === "dm" || (sub[0] === "messages" && sub[1] === "send");
+  return sub[0] === 'dm' || (sub[0] === 'messages' && sub[1] === 'send');
 }
 
 /**
@@ -144,5 +144,5 @@ export function isParallSendCommand(command: string | undefined): boolean {
 export function isParallNoReplyCommand(command: string | undefined): boolean {
   if (!command) return false;
   const sub = parseParallCliInvocation(command);
-  return sub?.[0] === "no-reply";
+  return sub?.[0] === 'no-reply';
 }

package/src/dispatch-adapter.ts

@@ -1,5 +1,5 @@
-import type { ParallClient } from "@parall/sdk";
-import type { ParallEvent } from "./types.js";
+import type { ParallClient } from '@parall/sdk';
+import type { ParallEvent } from './types.js';
 
 export type GatewayLogger = {
   info: (msg: string) => void;
@@ -29,16 +29,31 @@ export type DispatchContext = {
 
 export type RuntimeEvent =
   | {
-      type: "runtime_session";
+      type: 'runtime_session';
       runtimeSessionId: string;
       runtimeLaneKey?: string;
       runtimeRef?: Record<string, unknown>;
     }
-  | { type: "thinking"; text: string; groupKey?: string }
-  | { type: "tool_call"; callId: string; toolName: string; input: unknown; startedAt?: string; groupKey?: string }
-  | { type: "tool_result"; callId: string; toolName: string; output: string; error?: string; durationMs?: number; groupKey?: string }
-  | { type: "text"; text: string; project?: boolean; groupKey?: string }
-  | { type: "error"; message: string };
+  | { type: 'thinking'; text: string; groupKey?: string }
+  | {
+      type: 'tool_call';
+      callId: string;
+      toolName: string;
+      input: unknown;
+      startedAt?: string;
+      groupKey?: string;
+    }
+  | {
+      type: 'tool_result';
+      callId: string;
+      toolName: string;
+      output: string;
+      error?: string;
+      durationMs?: number;
+      groupKey?: string;
+    }
+  | { type: 'text'; text: string; project?: boolean; groupKey?: string }
+  | { type: 'error'; message: string };
 
 export type DispatchOpts = {
   event: ParallEvent;
@@ -98,4 +113,12 @@ export interface DispatchAdapter {
 
   /** Return the path to the session's history file on disk, if the runtime persists it. */
   getSessionHistoryPath?(sessionKey: string): string | undefined;
+
+  /**
+   * Abort the in-flight dispatch for the given session. Called by the gateway
+   * when the dispatch deadline is exceeded. Implementations should unblock the
+   * `dispatch()` generator (e.g. close a turn sink, end stdin, fail a stream)
+   * so the `for await` loop in `runDispatch` exits naturally. Must be idempotent.
+   */
+  abortDispatch?(sessionKey: string): void;
 }

package/src/event-format.ts

@@ -1,31 +1,58 @@
-import type { ForkResult, ParallEvent } from "./types.js";
+import type { ForkResult, ParallEvent } from './types.js';
 
 function sanitizeMeta(value: string): string {
-  return value.replace(/[\r\n]+/g, " ").replace(/[[\]|]/g, " ").trim();
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[[\]|]/g, ' ')
+    .trim();
 }
 
 export function buildEventBody(event: ParallEvent): string {
   const lines: string[] = [];
-  if (event.type === "message") {
+  if (event.type === 'message') {
     lines.push(`[Event: message.new]`);
     const chatLabel = event.targetName
       ? `"${event.targetName}" (prll://${event.targetId})`
       : `prll://${event.targetId}`;
-    lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? "unknown"}]`);
+    lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? 'unknown'}]`);
     lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
     lines.push(`[Message ID: prll://${event.messageId}]`);
-    if (event.threadRootId) lines.push(`[Thread: prll://${event.threadRootId}]`);
+    if (event.threadRootId) {
+      const threadMeta = [
+        `prll://${event.threadRootId}`,
+        event.threadReplyCount != null ? `${event.threadReplyCount} replies` : null,
+        event.threadUnreadCount != null && event.threadUnreadCount > 0
+          ? `${event.threadUnreadCount} unread`
+          : null,
+        event.threadUnreadCount != null && event.threadUnreadCount > 0 && event.threadUnreadSince
+          ? `since: prll://${event.threadUnreadSince}`
+          : null,
+      ]
+        .filter(Boolean)
+        .join(' | ');
+      lines.push(`[Thread: ${threadMeta}]`);
+    }
+    if (event.unreadCount != null && event.unreadCount > 1) {
+      const countStr = event.unreadCount >= 1000 ? '999+' : String(event.unreadCount);
+      const sinceStr = event.unreadSince ? ` | since: prll://${event.unreadSince}` : '';
+      let line = `[Unread: ${countStr} messages${sinceStr}]`;
+      if (event.unreadCount > 50) line += ` — fetch recent context with --limit, not all`;
+      lines.push(line);
+    }
     if (event.noReply) lines.push(`[Hint: no_reply]`);
     if (event.attachments?.length) {
       for (const att of event.attachments) {
-        const sizeStr = att.fileSize >= 1048576
-          ? `${(att.fileSize / 1048576).toFixed(1)}MB`
-          : `${Math.round(att.fileSize / 1024)}KB`;
-        lines.push(`[Attachment: prll://${att.id} | ${sanitizeMeta(att.mimeType)} | ${sizeStr} | ${sanitizeMeta(att.fileName)}]`);
+        const sizeStr =
+          att.fileSize >= 1048576
+            ? `${(att.fileSize / 1048576).toFixed(1)}MB`
+            : `${Math.round(att.fileSize / 1024)}KB`;
+        lines.push(
+          `[Attachment: prll://${att.id} | ${sanitizeMeta(att.mimeType)} | ${sizeStr} | ${sanitizeMeta(att.fileName)}]`,
+        );
       }
     }
-    lines.push("", event.body);
-  } else if (event.type === "task_comment") {
+    lines.push('', event.body);
+  } else if (event.type === 'task_comment') {
     lines.push(`[Event: task.comment.created]`);
     const taskLabel = event.targetName
       ? `${event.targetName} (prll://${event.targetId})`
@@ -34,20 +61,34 @@ export function buildEventBody(event: ParallEvent): string {
     if (event.deliveryReason) lines.push(`[Delivery: ${sanitizeMeta(event.deliveryReason)}]`);
     lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
     lines.push(`[Comment ID: prll://${event.messageId}]`);
-    lines.push("", event.body);
-  } else if (event.type === "approval") {
+    lines.push('', event.body);
+  } else if (event.type === 'wiki_comment') {
+    lines.push(`[Event: wiki.comment.created]`);
+    const target = event.replyTargetUri ?? `prll://${event.targetId}`;
+    if (event.targetType === 'changeset') {
+      lines.push(`[Wiki Changeset: ${target}]`);
+    } else {
+      lines.push(
+        `[Wiki: ${event.targetName ? `${sanitizeMeta(event.targetName)} (${target})` : target}]`,
+      );
+    }
+    if (event.deliveryReason) lines.push(`[Delivery: ${sanitizeMeta(event.deliveryReason)}]`);
+    lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
+    lines.push(`[Comment ID: prll://${event.messageId}]`);
+    lines.push('', event.body);
+  } else if (event.type === 'approval') {
     lines.push(`[Event: approval.decided]`);
     lines.push(`[Approval: prll://${event.messageId}]`);
     lines.push(`[Chat: prll://${event.targetId}]`);
     lines.push(`[Decided by: ${event.senderName} (prll://${event.senderId})]`);
-    lines.push("", event.body);
-  } else if (event.type === "schedule") {
+    lines.push('', event.body);
+  } else if (event.type === 'schedule') {
     lines.push(`[Event: schedule.fired]`);
     lines.push(`[Schedule: prll://${event.targetId}]`);
     lines.push(`[Run: prll://${event.messageId}]`);
     if (event.scheduledFireAt) lines.push(`[Scheduled at: ${sanitizeMeta(event.scheduledFireAt)}]`);
     if (event.attachedUri) lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
-    lines.push("", event.body);
+    lines.push('', event.body);
   } else {
     lines.push(`[Event: task.assigned]`);
     const taskLabel = event.targetName
@@ -55,31 +96,36 @@ export function buildEventBody(event: ParallEvent): string {
       : `prll://${event.targetId}`;
     lines.push(`[Task: ${taskLabel}]`);
     lines.push(`[Assigned by: ${event.senderName} (prll://${event.senderId})]`);
-    lines.push("", event.body);
+    lines.push('', event.body);
   }
-  return lines.join("\n") + buildSendMessageHint(event);
+  return lines.join('\n') + buildSendMessageHint(event);
 }
 
 export function buildEventBodyForForkResult(event: ParallEvent): string {
-  return buildEventBody(event).replace(/\n<system-reminder>[\s\S]*<\/system-reminder>$/, "");
+  return buildEventBody(event).replace(/\n<system-reminder>[\s\S]*<\/system-reminder>$/, '');
 }
 
 function buildSendMessageHint(event: ParallEvent): string {
-  if (event.noReply) return "";
+  if (event.noReply) return '';
+
+  if (event.type === 'wiki_comment' && event.replyTargetUri) {
+    const where = event.targetType === 'changeset' ? 'this changeset comment' : 'this wiki page';
+    return `\n<system-reminder>To reply on ${where}, run: \`parall comments add --target "${event.replyTargetUri}" --body "..."\` (read the thread first with \`parall comments list --target "${event.replyTargetUri}"\`). To message someone instead, use \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
+  }
 
-  if (event.targetId.startsWith("cht_")) {
+  if (event.targetId.startsWith('cht_')) {
     return `\n<system-reminder>To reply, run: \`parall messages send prll://${event.targetId} --text "..."\` — your plain text output is not delivered to the chat.</system-reminder>`;
   }
 
-  if (event.targetId.startsWith("tsk_")) {
+  if (event.targetId.startsWith('tsk_')) {
     return `\n<system-reminder>To respond, use the CLI: \`parall tasks update\` / \`parall tasks comments add\`. To message someone, use \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
   }
 
-  if (event.targetId.startsWith("sch_")) {
+  if (event.targetId.startsWith('sch_')) {
     return `\n<system-reminder>To communicate, use the CLI: \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
   }
 
-  return "";
+  return '';
 }
 
 export function buildForkScopePrefix(event: ParallEvent): string {
@@ -90,17 +136,21 @@ export function buildForkScopePrefix(event: ParallEvent): string {
 }
 
 export function buildForkResultPrefix(results: ForkResult[]): string {
-  if (!results.length) return "";
+  if (!results.length) return '';
   const blocks = results.map((result) => {
     const lines: string[] = [];
     for (const body of result.eventBodies) {
       lines.push(body);
     }
-    lines.push(`[This event was handled by a parallel fork session. Do NOT re-handle, re-reply, or duplicate work for it.]`);
-    lines.push(`[Fork summary: ${result.agentSummary ? sanitizeMeta(result.agentSummary) : "No fork summary available — the fork completed without producing a text summary. Check the target chat/task for any actions the fork already took before acting."}]`);
-    if (result.actions.length) lines.push(`[Fork actions: ${result.actions.join("; ")}]`);
+    lines.push(
+      `[This event was handled by a parallel fork session. Do NOT re-handle, re-reply, or duplicate work for it.]`,
+    );
+    lines.push(
+      `[Fork summary: ${result.agentSummary ? sanitizeMeta(result.agentSummary) : 'No fork summary available — the fork completed without producing a text summary. Check the target chat/task for any actions the fork already took before acting.'}]`,
+    );
+    if (result.actions.length) lines.push(`[Fork actions: ${result.actions.join('; ')}]`);
     if (result.historyPath) lines.push(`[Fork history: ${result.historyPath}]`);
-    return lines.join("\n");
+    return lines.join('\n');
   });
-  return blocks.join("\n\n") + "\n\n---\n\n";
+  return blocks.join('\n\n') + '\n\n---\n\n';
 }