@librechat/agents 3.7.1 → 3.7.3

package/src/eventActor/index.ts

@@ -0,0 +1,32 @@
+export {
+  EventActorExecutor,
+  createEventActorExecutor,
+} from './EventActorExecutor';
+export type {
+  EventActorAdapterPrepareRequest,
+  EventActorAdapterPreparation,
+  EventActorAppliedResult,
+  EventActorCheckpointFork,
+  EventActorCheckpointReference,
+  EventActorCommitRequest,
+  EventActorCommitResult,
+  EventActorDiscardReason,
+  EventActorDiscardRequest,
+  EventActorEvent,
+  EventActorExecutionRequest,
+  EventActorExecutionResult,
+  EventActorExecutorOptions,
+  EventActorHead,
+  EventActorHostAdapter,
+  EventActorInvocation,
+  EventActorInvocationContext,
+  EventActorIndeterminateResult,
+  EventActorInvocationReference,
+  EventActorInvocationResult,
+  EventActorPreparation,
+  EventActorPreparationContext,
+  EventActorPreparedInvocation,
+  EventActorPrepareRequest,
+  EventActorSettlementResult,
+  EventActorTerminalResult,
+} from './types';

package/src/eventActor/types.ts

@@ -0,0 +1,250 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+
+/** Durable event payload accepted by the actor lifecycle. */
+export type EventActorEvent =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly EventActorEvent[]
+  | { readonly [key: string]: EventActorEvent };
+
+/** Stable reference to one persisted LangGraph checkpoint. */
+export interface EventActorCheckpointReference {
+  threadId: string;
+  checkpointId?: string;
+  checkpointNs: string;
+}
+
+/** Committed logical head read before an event invocation is prepared. */
+export interface EventActorHead {
+  actorThreadId: string;
+  generation: number;
+  checkpoint?: EventActorCheckpointReference;
+}
+
+/** Invocation-owned checkpoint fork that cannot become authoritative in place. */
+export interface EventActorCheckpointFork
+  extends EventActorCheckpointReference {
+  invocationId: string;
+}
+
+export interface EventActorInvocationReference {
+  actorThreadId: string;
+  invocationId: string;
+  depth: number;
+  continuation: 'warm' | 'cold';
+  base: EventActorHead;
+  fork: EventActorCheckpointFork;
+}
+
+export interface EventActorInvocation<TEvent extends EventActorEvent>
+  extends EventActorInvocationReference {
+  event: TEvent;
+}
+
+export interface EventActorPreparedInvocation<TEvent extends EventActorEvent>
+  extends EventActorInvocation<TEvent> {
+  /**
+   * Executor-authenticated, time-bounded binding over the complete prepared
+   * invocation. Its wire representation is opaque to callers.
+   */
+  preparationDigest: string;
+}
+
+export type EventActorAdapterPreparation<TEvent extends EventActorEvent> =
+  | { status: 'ready'; invocation: EventActorInvocation<TEvent> }
+  | { status: 'checkpoint_unavailable'; head: EventActorHead };
+
+export type EventActorPreparation<TEvent extends EventActorEvent> =
+  | { status: 'ready'; invocation: EventActorPreparedInvocation<TEvent> }
+  | {
+      status: 'checkpoint_unavailable';
+      request: EventActorPrepareRequest<TEvent>;
+      head: EventActorHead;
+      /** Executor-authenticated binding over this exact request/head pair. */
+      preparationDigest: string;
+    };
+
+export type EventActorTerminalResult<TResult extends EventActorEvent> =
+  | {
+      status: 'applied';
+      result: TResult;
+      checkpoint: EventActorCheckpointFork;
+    }
+  | { status: 'completed_no_action'; result?: TResult };
+
+export type EventActorAppliedResult<TResult extends EventActorEvent> = Extract<
+  EventActorTerminalResult<TResult>,
+  { status: 'applied' }
+> & {
+  /** Executor-issued one-shot settlement for the invocation that produced this action. */
+  invocation: EventActorInvocationReference;
+};
+
+export interface EventActorIndeterminateResult<
+  TResult extends EventActorEvent,
+> {
+  /** Applied handling cannot be proven safe to retry; retain its fork. */
+  status: 'commit_indeterminate';
+  result?: TResult;
+  checkpoint: EventActorCheckpointFork;
+  error: Error;
+}
+
+export type EventActorInvocationResult<TResult extends EventActorEvent> =
+  | EventActorAppliedResult<TResult>
+  | EventActorIndeterminateResult<TResult>
+  | Extract<
+      EventActorTerminalResult<TResult>,
+      { status: 'completed_no_action' }
+    >;
+
+export interface EventActorInvocationContext {
+  signal: AbortSignal;
+  config: RunnableConfig;
+}
+
+export interface EventActorPreparationContext {
+  /** Explicit task-owned cancellation; parent-run ambient signals are excluded. */
+  signal: AbortSignal;
+}
+
+export interface EventActorPrepareRequest<TEvent extends EventActorEvent> {
+  actorThreadId: string;
+  invocationId: string;
+  depth: number;
+  event: TEvent;
+}
+
+export interface EventActorAdapterPrepareRequest<TEvent extends EventActorEvent>
+  extends EventActorPrepareRequest<TEvent> {
+  /** Unique execution-attempt namespace; invocationId remains the logical idempotency key. */
+  checkpointNs: string;
+}
+
+export interface EventActorCommitRequest<TResult extends EventActorEvent> {
+  invocation: EventActorInvocationReference;
+  expectedHead: EventActorHead;
+  checkpoint: EventActorCheckpointFork;
+  result: TResult;
+  retention: {
+    committedCheckpoints: 2;
+    dormantCheckpointTtlMs: number;
+  };
+}
+
+export type EventActorCommitResult =
+  | { status: 'committed'; head: EventActorHead }
+  | { status: 'stale'; head?: EventActorHead };
+
+/** Public settlement outcome after an action has already been applied. */
+export type EventActorSettlementResult<TResult extends EventActorEvent> =
+  | EventActorCommitResult
+  | EventActorIndeterminateResult<TResult>;
+
+export type EventActorDiscardReason =
+  | 'cancelled'
+  | 'completed_no_action'
+  | 'failed';
+
+export interface EventActorDiscardRequest {
+  invocation: EventActorInvocationReference;
+  reason: EventActorDiscardReason;
+}
+
+/**
+ * Host adapter for durable actor state and the concrete agent invocation.
+ * `commit` must compare both the expected generation and checkpoint identity
+ * atomically before advancing the logical actor head. The host mailbox
+ * deduplicates the logical `invocationId` before entering this seam, while each
+ * SDK execution attempt receives a distinct checkpoint namespace. Preparation
+ * methods own rollback until they return a ready invocation and must treat the
+ * request event as immutable. On cancellation they roll back and reject with
+ * `context.signal.reason`; cleanup failures reject with their own error so they
+ * remain observable. `invoke` returns only after its provider, stream, timer,
+ * and executor resources have been released. Once qualifying action evidence
+ * exists, `invoke` must return `applied` even if a later abort or provider
+ * failure occurs; a thrown error is therefore a definite no-action failure
+ * whose fork is safe to discard. `commit` must not reclaim an applied stale
+ * fork: the SDK retains and surfaces it as `commit_conflict` for host
+ * reconciliation. `discard` must be idempotent for the same invocation because
+ * an ambiguous cleanup failure can be retried through the public lifecycle.
+ */
+export interface EventActorHostAdapter<
+  TEvent extends EventActorEvent,
+  TResult extends EventActorEvent,
+> {
+  prepare(
+    request: EventActorAdapterPrepareRequest<TEvent>,
+    context: EventActorPreparationContext
+  ): Promise<EventActorAdapterPreparation<TEvent>>;
+  coldContinue(
+    request: EventActorAdapterPrepareRequest<TEvent>,
+    head: EventActorHead,
+    context: EventActorPreparationContext
+  ): Promise<EventActorInvocation<TEvent>>;
+  invoke(
+    invocation: EventActorInvocation<TEvent>,
+    context: EventActorInvocationContext
+  ): Promise<EventActorTerminalResult<TResult>>;
+  commit(
+    request: EventActorCommitRequest<TResult>
+  ): Promise<EventActorCommitResult>;
+  discard(request: EventActorDiscardRequest): Promise<void>;
+}
+
+export interface EventActorExecutionRequest<TEvent extends EventActorEvent> {
+  actorThreadId: string;
+  invocationId: string;
+  event: TEvent;
+  depth?: number;
+  /** Explicit task-owned signal. Ambient parent-run signals are ignored. */
+  signal?: AbortSignal;
+}
+
+export type EventActorExecutionResult<TResult extends EventActorEvent> =
+  | {
+      status: 'applied';
+      result: TResult;
+      head: EventActorHead;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      status: 'completed_no_action';
+      result?: TResult;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      status: 'cancelled';
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      /** The action happened, but another head won the CAS. Reconcile; do not retry. */
+      status: 'commit_conflict';
+      result: TResult;
+      checkpoint: EventActorCheckpointFork;
+      head?: EventActorHead;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      /** Applied handling cannot be proven safe to retry; retain its fork. */
+      status: 'commit_indeterminate';
+      result?: TResult;
+      checkpoint: EventActorCheckpointFork;
+      error: Error;
+      continuation: 'warm' | 'cold';
+    }
+  | {
+      status: 'failed';
+      error: Error;
+      continuation: 'warm' | 'cold';
+    };
+
+export interface EventActorExecutorOptions {
+  maxDepth?: number;
+  /** Also bounds signed preparation authority and local terminal fences. */
+  dormantCheckpointTtlMs?: number;
+  /** Stable private key of at least 32 bytes for cross-lifetime handoffs. */
+  preparationSigningKey?: string | Uint8Array;
+}

package/src/index.ts

@@ -43,6 +43,9 @@ export * from './hooks';
 /* Programmatic sessions */
 export * from './session';
 
+/* Event actors */
+export * from './eventActor';
+
 /* HITL helpers */
 export * from './hitl';
 

package/src/tools/BashProgrammaticToolCalling.ts

@@ -40,6 +40,7 @@ config();
 
 const DEFAULT_MAX_ROUND_TRIPS = 20;
 const DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();
+const BASH_LAST_BACKGROUND_PID_GUARD = ': &\nwait "$!"';
 
 /** Bash reserved words that get `_tool` suffix when used as function names */
 const BASH_RESERVED = new Set([
@@ -171,6 +172,14 @@ export const BashProgrammaticToolCallingDefinition = {
   schema: BashProgrammaticToolCallingSchema,
 } as const;
 
+function prepareBashProgrammaticCode(code: string): string {
+  /* The Code API's generated Bash wrapper reads `$!` after user code. A user
+   * `set -u` makes that expansion fail when no background process has run.
+   * Seed and reap a no-op job before user code so strict mode remains active
+   * for the payload while the wrapper can safely read its special parameter. */
+  return `${BASH_LAST_BACKGROUND_PID_GUARD}\n${code}`;
+}
+
 function maybeParseJsonResultString(result: unknown): unknown {
   if (typeof result !== 'string') {
     return result;
@@ -320,6 +329,7 @@ export function createBashProgrammaticToolCallingTool(
     async (rawParams, config) => {
       const params = rawParams as ProgrammaticInvocationParams;
       const { code } = params;
+      const preparedCode = prepareBashProgrammaticCode(code);
       const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);
 
       const toolCall = (config.toolCall ?? {}) as ToolCall &
@@ -417,7 +427,7 @@ export function createBashProgrammaticToolCallingTool(
           EXEC_ENDPOINT,
           {
             lang: 'bash',
-            code,
+            code: preparedCode,
             tools: effectiveTools,
             session_id,
             timeout,