@parall/agent-core 1.13.1

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -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/dist/routing.d.ts

@@ -0,0 +1,25 @@
+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;
+/**
+ * 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 declare const defaultRoutingStrategy: RoutingStrategy;
+/** Route an inbound event based on current dispatch state. */
+export declare function routeTrigger(event: ParallEvent, state: DispatchState, strategy?: RoutingStrategy): TriggerDisposition;
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D,+CAA+C;AAC/C,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,GACzB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAE3B,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,KAAK,kBAAkB,CAAC;AAI/F;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAapC,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,aAAa,EACpB,QAAQ,GAAE,eAAwC,GACjD,kBAAkB,CAKpB"}

package/dist/routing.js

@@ -0,0 +1,29 @@
+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 = (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, state, strategy = defaultRoutingStrategy) {
+    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/dist/session-state.d.ts

@@ -0,0 +1,17 @@
+export declare function setSessionChatId(sessionKey: string, chatId: string): void;
+export declare function getSessionChatId(sessionKey: string): string | undefined;
+export declare function setSessionMessageId(sessionKey: string, messageId: string): void;
+export declare function getSessionMessageId(sessionKey: string): string | undefined;
+export declare function clearSessionMessageId(sessionKey: string): void;
+/** Snapshot the message ID at dispatch time — immune to later session-level overwrites. */
+export declare function setDispatchMessageId(sessionKey: string, messageId: string): void;
+/** Read the dispatch-time snapshot. Prefer this over getSessionMessageId for provenance. */
+export declare function getDispatchMessageId(sessionKey: string): string | undefined;
+export declare function clearDispatchMessageId(sessionKey: string): void;
+export declare function setDispatchGroupKey(sessionKey: string, groupKey: string): void;
+export declare function getDispatchGroupKey(sessionKey: string): string | undefined;
+export declare function clearDispatchGroupKey(sessionKey: string): void;
+export declare function setDispatchNoReply(sessionKey: string, noReply: boolean): void;
+export declare function getDispatchNoReply(sessionKey: string): boolean;
+export declare function clearDispatchNoReply(sessionKey: string): void;
+//# sourceMappingURL=session-state.d.ts.map

package/dist/session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state.d.ts","sourceRoot":"","sources":["../src/session-state.ts"],"names":[],"mappings":"AAYA,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAElE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAExE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,QAEvD;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAEzE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,QAExD;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAEvE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,QAEvD;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,QAEtE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,QAEtD"}

package/dist/session-state.js

@@ -0,0 +1,54 @@
+function normalizeSessionKey(sessionKey) {
+    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();
+const sessionMessageIdMap = new Map();
+const dispatchMessageIdMap = new Map();
+const dispatchGroupKeyMap = new Map();
+const dispatchNoReplyMap = new Map();
+export function setSessionChatId(sessionKey, chatId) {
+    sessionChatIdMap.set(normalizeSessionKey(sessionKey), chatId);
+}
+export function getSessionChatId(sessionKey) {
+    return sessionChatIdMap.get(normalizeSessionKey(sessionKey));
+}
+export function setSessionMessageId(sessionKey, messageId) {
+    sessionMessageIdMap.set(normalizeSessionKey(sessionKey), messageId);
+}
+export function getSessionMessageId(sessionKey) {
+    return sessionMessageIdMap.get(normalizeSessionKey(sessionKey));
+}
+export function clearSessionMessageId(sessionKey) {
+    sessionMessageIdMap.delete(normalizeSessionKey(sessionKey));
+}
+/** Snapshot the message ID at dispatch time — immune to later session-level overwrites. */
+export function setDispatchMessageId(sessionKey, messageId) {
+    dispatchMessageIdMap.set(normalizeSessionKey(sessionKey), messageId);
+}
+/** Read the dispatch-time snapshot. Prefer this over getSessionMessageId for provenance. */
+export function getDispatchMessageId(sessionKey) {
+    return dispatchMessageIdMap.get(normalizeSessionKey(sessionKey));
+}
+export function clearDispatchMessageId(sessionKey) {
+    dispatchMessageIdMap.delete(normalizeSessionKey(sessionKey));
+}
+export function setDispatchGroupKey(sessionKey, groupKey) {
+    dispatchGroupKeyMap.set(normalizeSessionKey(sessionKey), groupKey);
+}
+export function getDispatchGroupKey(sessionKey) {
+    return dispatchGroupKeyMap.get(normalizeSessionKey(sessionKey));
+}
+export function clearDispatchGroupKey(sessionKey) {
+    dispatchGroupKeyMap.delete(normalizeSessionKey(sessionKey));
+}
+export function setDispatchNoReply(sessionKey, noReply) {
+    dispatchNoReplyMap.set(normalizeSessionKey(sessionKey), noReply);
+}
+export function getDispatchNoReply(sessionKey) {
+    return dispatchNoReplyMap.get(normalizeSessionKey(sessionKey)) ?? false;
+}
+export function clearDispatchNoReply(sessionKey) {
+    dispatchNoReplyMap.delete(normalizeSessionKey(sessionKey));
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+/** 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;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,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;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@parall/agent-core",
+  "version": "1.13.1",
+  "description": "Shared agent runtime orchestration helpers for Parall",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parall-hq/parall-mono",
+    "directory": "ts/agent-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@parall/sdk": "1.13.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "pnpm run build && node --test test/*.test.mjs"
+  }
+}

package/src/dispatch-adapter.ts

@@ -0,0 +1,66 @@
+import type { ParallClient } from "@parall/sdk";
+import type { ParallEvent } from "./types.js";
+
+export type GatewayLogger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+export type DispatchContext = {
+  accountId: string;
+  apiUrl: string;
+  apiKey: string;
+  orgId: string;
+  agentUserId: string;
+  runtimeType: string;
+  runtimeKey: string;
+  sessionId?: string;
+  chatId?: string;
+  triggerMessageId?: string;
+  noReply: boolean;
+  stepIdFilePath?: string;
+  client: ParallClient;
+  log?: GatewayLogger;
+};
+
+export type RuntimeEvent =
+  | { 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;
+  earlierEvents?: ParallEvent[];
+  bodyForAgent: string;
+  sessionKey: string;
+  context: DispatchContext;
+};
+
+export type ForkSessionHandle = {
+  sessionKey: string;
+  [key: string]: unknown;
+};
+
+export type ForkOpts = {
+  sessionKey: string;
+  context: DispatchContext;
+};
+
+export type CleanupForkOpts = {
+  fork: ForkSessionHandle;
+  context: DispatchContext;
+};
+
+export interface DispatchAdapter {
+  /** Dispatch a Parall event to the runtime and emit normalized runtime events. */
+  dispatch(opts: DispatchOpts): AsyncIterable<RuntimeEvent>;
+
+  /** Fork the current runtime session for concurrent handling. Return null to buffer on main. */
+  forkSession?(opts: ForkOpts): Promise<ForkSessionHandle | null> | ForkSessionHandle | null;
+
+  /** Clean up a fork session created by forkSession(). */
+  cleanupFork?(opts: CleanupForkOpts): Promise<void> | void;
+}

package/src/event-format.ts

@@ -0,0 +1,40 @@
+import type { ForkResult, ParallEvent } from "./types.js";
+
+export function buildEventBody(event: ParallEvent): string {
+  const lines: string[] = [];
+  if (event.type === "message") {
+    lines.push(`[Event: message.new]`);
+    const chatLabel = event.targetName
+      ? `"${event.targetName}" (${event.targetId})`
+      : event.targetId;
+    lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? "unknown"}]`);
+    lines.push(`[From: ${event.senderName} (${event.senderId})]`);
+    lines.push(`[Message ID: ${event.messageId}]`);
+    if (event.threadRootId) lines.push(`[Thread: ${event.threadRootId}]`);
+    if (event.noReply) lines.push(`[Hint: no_reply]`);
+    if (event.mediaFields?.MediaUrl) {
+      lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
+    }
+    lines.push("", event.body);
+  } else {
+    lines.push(`[Event: task.assigned]`);
+    const taskLabel = event.targetName
+      ? `${event.targetName} (${event.targetId})`
+      : event.targetId;
+    lines.push(`[Task: ${taskLabel} | type: ${event.targetType ?? "task"}]`);
+    lines.push(`[Assigned by: ${event.senderName} (${event.senderId})]`);
+    lines.push("", event.body);
+  }
+  return lines.join("\n");
+}
+
+export function buildForkResultPrefix(results: ForkResult[]): string {
+  if (!results.length) return "";
+  const blocks = results.map((result) => {
+    const lines = [`[Fork result]`];
+    lines.push(`[Handled: ${result.sourceEvent.type} — ${result.sourceEvent.summary}]`);
+    if (result.actions.length) lines.push(`[Actions: ${result.actions.join("; ")}]`);
+    return lines.join("\n");
+  });
+  return blocks.join("\n\n") + "\n\n---\n\n";
+}