@parall/agent-core 1.13.1

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./session-state.js";
+export * from "./routing.js";
+export * from "./event-format.js";
+export * from "./dispatch-adapter.js";
+export * from "./gateway-base.js";

package/src/routing.ts

@@ -0,0 +1,47 @@
+import type { DispatchState, ParallEvent } from "./types.js";
+
+/** Where an inbound event should be routed. */
+export type TriggerDisposition =
+  | { action: "main" }
+  | { action: "buffer-main" }
+  | { action: "buffer-fork"; forkKey: string }
+  | { action: "new-fork" };
+
+/** Pluggable strategy for routing triggers when main session is busy. */
+export type RoutingStrategy = (event: ParallEvent, state: DispatchState) => TriggerDisposition;
+
+const MAX_CONCURRENT_FORKS = 20;
+
+/**
+ * Default routing strategy:
+ * - Same target as main → buffer-main (strict per-target serial ordering)
+ * - Active fork for same target → buffer into that fork
+ * - Too many forks → buffer-main (backpressure)
+ * - Otherwise → create a new fork
+ */
+export const defaultRoutingStrategy: RoutingStrategy = (event, state) => {
+  if (state.mainCurrentTargetId === event.targetId) {
+    return { action: "buffer-main" };
+  }
+
+  const existingForkKey = state.activeForks.get(event.targetId);
+  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
+
+  if (state.activeForks.size >= MAX_CONCURRENT_FORKS) {
+    return { action: "buffer-main" };
+  }
+
+  return { action: "new-fork" };
+};
+
+/** Route an inbound event based on current dispatch state. */
+export function routeTrigger(
+  event: ParallEvent,
+  state: DispatchState,
+  strategy: RoutingStrategy = defaultRoutingStrategy,
+): TriggerDisposition {
+  const existingForkKey = state.activeForks.get(event.targetId);
+  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
+  if (!state.mainDispatching) return { action: "main" };
+  return strategy(event, state);
+}

package/src/session-state.ts

@@ -0,0 +1,69 @@
+function normalizeSessionKey(sessionKey: string): string {
+  return sessionKey.toLowerCase();
+}
+
+// Session key → original chat ID mapping.
+// Runtime session keys may be normalized to lowercase, but Parall IDs are case-sensitive.
+const sessionChatIdMap = new Map<string, string>();
+const sessionMessageIdMap = new Map<string, string>();
+const dispatchMessageIdMap = new Map<string, string>();
+const dispatchGroupKeyMap = new Map<string, string>();
+const dispatchNoReplyMap = new Map<string, boolean>();
+
+export function setSessionChatId(sessionKey: string, chatId: string) {
+  sessionChatIdMap.set(normalizeSessionKey(sessionKey), chatId);
+}
+
+export function getSessionChatId(sessionKey: string): string | undefined {
+  return sessionChatIdMap.get(normalizeSessionKey(sessionKey));
+}
+
+export function setSessionMessageId(sessionKey: string, messageId: string) {
+  sessionMessageIdMap.set(normalizeSessionKey(sessionKey), messageId);
+}
+
+export function getSessionMessageId(sessionKey: string): string | undefined {
+  return sessionMessageIdMap.get(normalizeSessionKey(sessionKey));
+}
+
+export function clearSessionMessageId(sessionKey: string) {
+  sessionMessageIdMap.delete(normalizeSessionKey(sessionKey));
+}
+
+/** Snapshot the message ID at dispatch time — immune to later session-level overwrites. */
+export function setDispatchMessageId(sessionKey: string, messageId: string) {
+  dispatchMessageIdMap.set(normalizeSessionKey(sessionKey), messageId);
+}
+
+/** Read the dispatch-time snapshot. Prefer this over getSessionMessageId for provenance. */
+export function getDispatchMessageId(sessionKey: string): string | undefined {
+  return dispatchMessageIdMap.get(normalizeSessionKey(sessionKey));
+}
+
+export function clearDispatchMessageId(sessionKey: string) {
+  dispatchMessageIdMap.delete(normalizeSessionKey(sessionKey));
+}
+
+export function setDispatchGroupKey(sessionKey: string, groupKey: string) {
+  dispatchGroupKeyMap.set(normalizeSessionKey(sessionKey), groupKey);
+}
+
+export function getDispatchGroupKey(sessionKey: string): string | undefined {
+  return dispatchGroupKeyMap.get(normalizeSessionKey(sessionKey));
+}
+
+export function clearDispatchGroupKey(sessionKey: string) {
+  dispatchGroupKeyMap.delete(normalizeSessionKey(sessionKey));
+}
+
+export function setDispatchNoReply(sessionKey: string, noReply: boolean) {
+  dispatchNoReplyMap.set(normalizeSessionKey(sessionKey), noReply);
+}
+
+export function getDispatchNoReply(sessionKey: string): boolean {
+  return dispatchNoReplyMap.get(normalizeSessionKey(sessionKey)) ?? false;
+}
+
+export function clearDispatchNoReply(sessionKey: string) {
+  dispatchNoReplyMap.delete(normalizeSessionKey(sessionKey));
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+/** Result from a completed fork dispatch, to be injected into main session's next turn. */
+export type ForkResult = {
+  forkSessionKey: string;
+  sourceEvent: { type: string; targetId: string; summary: string };
+  actions: string[];
+};
+
+/** Mutable dispatch state for the orchestrator gateway. */
+export type DispatchState = {
+  mainDispatching: boolean;
+  mainCurrentTargetId?: string;
+  activeForks: Map<string, string>;
+  pendingForkResults: ForkResult[];
+  mainBuffer: ParallEvent[];
+};
+
+/** Normalized inbound event from Parall. */
+export type ParallEvent = {
+  type: "message" | "task";
+  targetId: string;
+  targetName?: string;
+  targetType?: string;
+  senderId: string;
+  senderName: string;
+  messageId: string;
+  body: string;
+  threadRootId?: string;
+  noReply?: boolean;
+  mediaFields?: Record<string, string | undefined>;
+  ackSourceType?: "message" | "task_activity";
+  ackSourceId?: string;
+};