@lobechat/agent-signal

@lobechat/agent-signal is the shared Agent Signal domain package. It defines the language of Agent Signal nodes and source events, but it does not run policies, call model runtimes, read databases, trigger workflows, or import app server modules.

Use this package when code needs browser-safe or server-safe source event types, source event constants, scope-key helpers, and the core Agent Signal node shapes.

Do not add app integration here. Side effects belong in src/server/services/agentSignal or the browser service facade.

Public APIs

Core node APIs

Import from the package root when building or inspecting source, signal, action, and executor nodes:

import type { AgentSignalSource, BaseAction, BaseSignal } from '@lobechat/agent-signal';
import { createAction, createSignal, createSource } from '@lobechat/agent-signal';

Use these APIs inside runtime, scheduler, policy, and observability code that needs normalized semantic nodes.

Source event APIs

Import from @lobechat/agent-signal/source when producing, typing, validating, or routing source events:

import {
  AGENT_SIGNAL_SOURCE_TYPES,
  createSourceEvent,
  type AgentSignalSourceEvent,
  type AgentSignalSourceEventInput,
} from '@lobechat/agent-signal/source';

const event = createSourceEvent({
  payload: {
    message: 'Please remember that I prefer concise answers.',
    messageId: 'msg_1',
    topicId: 'topic_1',
  },
  sourceId: 'source_1',
  sourceType: AGENT_SIGNAL_SOURCE_TYPES.agentUserMessage,
});

createSourceEvent fills in:

• scopeKey, from topicId first, then bot thread metadata, then fallback:global
• timestamp, from Date.now() when the caller does not provide one

Use AgentSignalSourceEventInput<TSourceType> for producer inputs and AgentSignalSourceEvent<TSourceType> once scopeKey and timestamp are required.

Scope-key APIs

Use getSourceEventScopeKey for source-event payloads and AgentSignalScopeKey when code already has structured scope metadata:

import { AgentSignalScopeKey, getSourceEventScopeKey } from '@lobechat/agent-signal/source';

const topicScopeKey = getSourceEventScopeKey({ topicId: 'topic_1' });
const botScopeKey = AgentSignalScopeKey.forBotThread({
  applicationId: 'discord-app',
  platform: 'discord',
  platformThreadId: 'thread_1',
});

Which Layer To Use

Use this package for:

• Shared browser/server source event types
• Source type constants and payload maps
• Scope-key derivation
• Pure Agent Signal source, signal, action, result, and trigger types
• Pure node builders

Use the browser service facade for:

• Emitting source events from browser runtime code
• Sending events through tRPC
• Keeping UI paths non-blocking

See src/services/agentSignal.ts and src/store/chat/slices/aiChat/actions/agentSignalBridge.ts.

Use server services for:

• Feature gating
• DB access
• Workflow handoff
• Policy/runtime execution
• Redis or in-memory dedupe
• Observability persistence

See src/server/services/agentSignal/emitter.ts, src/server/services/agentSignal/orchestrator.ts, and src/server/services/agentSignal/sources/index.ts.

Supported Source Events

AGENT_SIGNAL_CLIENT_SOURCE_TYPES is the allow-list for browser-originated events accepted by src/server/routers/lambda/agentSignal.ts. It currently includes only the client.* source events.

Source Event Modules

• Source event API: input and normalized event types plus createSourceEvent.
• Source type catalog: constants, payload map, source variants, and the client allow-list.
• Scope-key helpers: topic, bot thread, task, agent/user, and user scope-key builders.
• Browser service facade: tRPC client wrapper for browser code.
• Browser bridge: feature-gated non-blocking browser emission helper.
• Lambda router: authenticated browser ingress and client source type validation.
• Server emitter: feature-gated immediate execution or workflow handoff.
• Server orchestrator: source event execution through policies, runtime, and observability.
• Source dedupe store: source event dedupe, scope locking, and source node rendering.
• Workflow trigger: async Upstash Workflow handoff.
• Workflow runner: workflow execution and client runtime bridge.
• Agent Runtime: server runtime source event producers.
• Chat: browser chat runtime source event producer.
• Gateway event handler: browser gateway source event producer.
• Bot router: bot-platform source event producer.

Adding A Source Event

1. Add the constant and payload shape in src/source/sourceTypes.ts.
2. Add a renderer in src/server/services/agentSignal/sources/renderers if the generic payload needs normalization before becoming an AgentSignalSource.
3. Register the renderer in src/server/services/agentSignal/sources/buildSource.ts.
4. Add the source to AGENT_SIGNAL_CLIENT_SOURCE_TYPES only when browser code should be allowed to emit it through the lambda router.
5. Add focused tests for source event creation, router validation, renderer normalization, or workflow bridging depending on the new producer path.

Keep source events stable. Source type strings are persisted in traces, dedupe keys, and workflow payloads.