Agent Signal
Use this skill to implement event-driven background work for agents without coupling the work to the foreground chat request.
Agent Signal has one consistent runtime shape:
source event -> signal interpretation -> action execution -> built-in result signals
Durable self-iteration work has one extra completion branch:
memory/skill action -> execAgent enqueue -> agent.execution.completed -> selfIteration receipt projection
Start Here
- Read
references/architecture.md to map the package boundary, runtime queue, scope model, and async workflow handoff.
- Read
references/handlers.md before writing any new policy, source handler, signal handler, or action handler.
- Read
references/observability.md when you need tracing, metrics, debugging, or workflow snapshot visibility.
Use The Right Entry Point
- Use
emitAgentSignalSourceEvent(...) when a server-owned producer should execute the pipeline immediately.
- Use
executeAgentSignalSourceEvent(...) when a worker or controlled backend path already owns execution timing and may inject a runtime guard backend.
- Use
enqueueAgentSignalSourceEvent(...) when the caller should return quickly and let Upstash Workflow process the event out-of-band.
- Use
emitAgentSignalSourceEventWithStore(...) for isolated tests or evals that should avoid ambient Redis state.
Read:
apps/server/src/services/agentSignal/index.ts
apps/server/src/workflows/agentSignal/index.ts
apps/server/src/workflows/agentSignal/run.ts
Core Model
source: A normalized fact that happened. Sources come from producers such as runtime lifecycle events, user messages, or bot ingress.
signal: A semantic interpretation derived from one source or from another signal. Signals express meaning, routing, or policy state.
action: A concrete side effect planned from one signal. Actions do the work.
policy: An installable middleware bundle that registers source, signal, and action handlers.
procedure: Not a distinct runtime node. Treat "procedure" as the end-to-end flow for one use case: ingress source, matching handlers, planned actions, execution result, and observability.
Keep the boundaries strict:
- Add a new
source when the outside world produced a new event.
- Add a new
signal when the system needs a reusable semantic interpretation.
- Add a new
action when the runtime needs a concrete side effect.
- Add or update a
policy when you are wiring those pieces together.
Implementation Workflow
- Decide whether the use case is synchronous or quiet background work.
- Define or reuse a source type in
packages/agent-signal/src/source/sourceTypes.ts.
- Define or reuse signal and action types in
apps/server/src/services/agentSignal/policies/types.ts.
- Implement handlers with
defineSourceHandler, defineSignalHandler, or defineActionHandler.
- Add source normalization or hydration under
apps/server/src/services/agentSignal/sources/** when the producer payload needs shaping.
- Bundle handlers with
defineAgentSignalHandlers(...).
- Register the policy in
apps/server/src/services/agentSignal/policies/index.ts and pass it into the runtime factory if needed.
- Add or update ingress code that emits or enqueues the source event.
- For async self-iteration writes, stamp an Agent Signal operation marker and project user-visible receipts from the completion path.
- Add observability and tests before considering the flow complete.
Default Reading Set
- Shared semantic core:
packages/agent-signal/src/index.ts
packages/agent-signal/src/base/builders.ts
packages/agent-signal/src/base/types.ts
packages/agent-signal/src/source/sourceTypes.ts
packages/agent-signal/src/source/sourceEvent.ts
- Server-owned runtime and middleware:
apps/server/src/services/agentSignal/runtime/AgentSignalRuntime.ts
apps/server/src/services/agentSignal/runtime/AgentSignalScheduler.ts
apps/server/src/services/agentSignal/runtime/middleware.ts
apps/server/src/services/agentSignal/runtime/context.ts
- Existing policy example:
apps/server/src/services/agentSignal/policies/analyzeIntent/index.ts
apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts
apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts
apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackAction.ts
apps/server/src/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts
apps/server/src/services/agentSignal/policies/analyzeIntent/actions/skillManagement.ts
apps/server/src/services/agentSignal/policies/analyzeIntent/completionSkillSynthesis.ts
apps/server/src/services/agentSignal/policies/completionPolicy.ts
apps/server/src/services/agentSignal/services/selfIteration/completion/buildSelfIterationReceipts.ts
apps/server/src/services/agentSignal/services/selfIteration/completion/selfIterationCompletionHandler.ts
- Observability:
apps/server/src/services/agentSignal/observability/projector.ts
apps/server/src/services/agentSignal/observability/traceEvents.ts
packages/observability-otel/src/modules/agent-signal/index.ts
Implementation Rules
- Reuse existing source, signal, and action types before adding new ones.
- Keep source handlers focused on interpretation and fan-out, not heavy side effects.
- Keep action handlers responsible for side effects, idempotency, and executor-style result reporting. For memory/skill self-iteration actions, the side effect is enqueueing
execAgent; the durable write and receipt projection happen after completion.
- Use stable ids and idempotency keys when the same source can arrive more than once.
- Preserve scope discipline. The runtime uses
scopeKey to serialize related background work.
- Prefer the dedicated shared package types and builders from
@lobechat/agent-signal for normalized nodes and result contracts.
- Do not project memory or skill receipts from the enqueue action. Use
agent.execution.completed + selfIteration finalState via createSelfIterationCompletionHandler(...).
- Add focused tests near the touched runtime, policy, or store module. Existing tests under
apps/server/src/services/agentSignal/**/__test__ and **/__tests__ are the reference pattern.
References
- Architecture and boundaries:
references/architecture.md
- Writing handlers and policies:
references/handlers.md
- Observability, metrics, and debugging:
references/observability.md
1---
2name: agent-signal
3description: 'Use for Agent Signal sources, actions, policies, middleware, workflow handoff and deduplication.'
4metadata:
5 source: https://skillmd.com/skills/lobehub/agent-signal
6---
7
8# Agent Signal
9
10Use this skill to implement event-driven background work for agents without coupling the work to the foreground chat request.
11
12Agent Signal has one consistent runtime shape:
13
14`source event` -> `signal interpretation` -> `action execution` -> built-in result signals
15
16Durable self-iteration work has one extra completion branch:
17
18`memory/skill action` -> `execAgent` enqueue -> `agent.execution.completed` -> `selfIteration` receipt projection
19
20## Start Here
21
221. Read `references/architecture.md` to map the package boundary, runtime queue, scope model, and async workflow handoff.
232. Read `references/handlers.md` before writing any new policy, source handler, signal handler, or action handler.
243. Read `references/observability.md` when you need tracing, metrics, debugging, or workflow snapshot visibility.
25
26## Use The Right Entry Point
27
28- Use `emitAgentSignalSourceEvent(...)` when a server-owned producer should execute the pipeline immediately.
29- Use `executeAgentSignalSourceEvent(...)` when a worker or controlled backend path already owns execution timing and may inject a runtime guard backend.
30- Use `enqueueAgentSignalSourceEvent(...)` when the caller should return quickly and let Upstash Workflow process the event out-of-band.
31- Use `emitAgentSignalSourceEventWithStore(...)` for isolated tests or evals that should avoid ambient Redis state.
32
33Read:
34
35- `apps/server/src/services/agentSignal/index.ts`
36- `apps/server/src/workflows/agentSignal/index.ts`
37- `apps/server/src/workflows/agentSignal/run.ts`
38
39## Core Model
40
41- `source`: A normalized fact that happened. Sources come from producers such as runtime lifecycle events, user messages, or bot ingress.
42- `signal`: A semantic interpretation derived from one source or from another signal. Signals express meaning, routing, or policy state.
43- `action`: A concrete side effect planned from one signal. Actions do the work.
44- `policy`: An installable middleware bundle that registers source, signal, and action handlers.
45- `procedure`: Not a distinct runtime node. Treat "procedure" as the end-to-end flow for one use case: ingress source, matching handlers, planned actions, execution result, and observability.
46
47Keep the boundaries strict:
48
49- Add a new `source` when the outside world produced a new event.
50- Add a new `signal` when the system needs a reusable semantic interpretation.
51- Add a new `action` when the runtime needs a concrete side effect.
52- Add or update a `policy` when you are wiring those pieces together.
53
54## Implementation Workflow
55
561. Decide whether the use case is synchronous or quiet background work.
572. Define or reuse a source type in `packages/agent-signal/src/source/sourceTypes.ts`.
583. Define or reuse signal and action types in `apps/server/src/services/agentSignal/policies/types.ts`.
594. Implement handlers with `defineSourceHandler`, `defineSignalHandler`, or `defineActionHandler`.
605. Add source normalization or hydration under `apps/server/src/services/agentSignal/sources/**` when the producer payload needs shaping.
616. Bundle handlers with `defineAgentSignalHandlers(...)`.
627. Register the policy in `apps/server/src/services/agentSignal/policies/index.ts` and pass it into the runtime factory if needed.
638. Add or update ingress code that emits or enqueues the source event.
649. For async self-iteration writes, stamp an Agent Signal operation marker and project user-visible receipts from the completion path.
6510. Add observability and tests before considering the flow complete.
66
67## Default Reading Set
68
69- Shared semantic core:
70 `packages/agent-signal/src/index.ts`
71 `packages/agent-signal/src/base/builders.ts`
72 `packages/agent-signal/src/base/types.ts`
73 `packages/agent-signal/src/source/sourceTypes.ts`
74 `packages/agent-signal/src/source/sourceEvent.ts`
75- Server-owned runtime and middleware:
76 `apps/server/src/services/agentSignal/runtime/AgentSignalRuntime.ts`
77 `apps/server/src/services/agentSignal/runtime/AgentSignalScheduler.ts`
78 `apps/server/src/services/agentSignal/runtime/middleware.ts`
79 `apps/server/src/services/agentSignal/runtime/context.ts`
80- Existing policy example:
81 `apps/server/src/services/agentSignal/policies/analyzeIntent/index.ts`
82 `apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts`
83 `apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts`
84 `apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackAction.ts`
85 `apps/server/src/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts`
86 `apps/server/src/services/agentSignal/policies/analyzeIntent/actions/skillManagement.ts`
87 `apps/server/src/services/agentSignal/policies/analyzeIntent/completionSkillSynthesis.ts`
88 `apps/server/src/services/agentSignal/policies/completionPolicy.ts`
89 `apps/server/src/services/agentSignal/services/selfIteration/completion/buildSelfIterationReceipts.ts`
90 `apps/server/src/services/agentSignal/services/selfIteration/completion/selfIterationCompletionHandler.ts`
91- Observability:
92 `apps/server/src/services/agentSignal/observability/projector.ts`
93 `apps/server/src/services/agentSignal/observability/traceEvents.ts`
94 `packages/observability-otel/src/modules/agent-signal/index.ts`
95
96## Implementation Rules
97
98- Reuse existing source, signal, and action types before adding new ones.
99- Keep source handlers focused on interpretation and fan-out, not heavy side effects.
100- Keep action handlers responsible for side effects, idempotency, and executor-style result reporting. For memory/skill self-iteration actions, the side effect is enqueueing `execAgent`; the durable write and receipt projection happen after completion.
101- Use stable ids and idempotency keys when the same source can arrive more than once.
102- Preserve scope discipline. The runtime uses `scopeKey` to serialize related background work.
103- Prefer the dedicated shared package types and builders from `@lobechat/agent-signal` for normalized nodes and result contracts.
104- Do not project memory or skill receipts from the enqueue action. Use `agent.execution.completed` + `selfIteration` finalState via `createSelfIterationCompletionHandler(...)`.
105- Add focused tests near the touched runtime, policy, or store module. Existing tests under `apps/server/src/services/agentSignal/**/__test__` and `**/__tests__` are the reference pattern.
106
107## References
108
109- Architecture and boundaries: `references/architecture.md`
110- Writing handlers and policies: `references/handlers.md`
111- Observability, metrics, and debugging: `references/observability.md`