cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): clarify resource event types — add RESOURCE_CREATED, RESOURCE_DELETED, RESOURCE_MOVED #8038

Closed
HAL9000 wants to merge 1 commits from spec/resource-event-types-clarification into master
pull from: spec/resource-event-types-clarification
merge into: cleveragents:master
Conversation 6 Commits 1 Files Changed 1
+34
1 changed files with 34 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specification.md
+34
View File
@@ -46039,7 +46039,10 @@ CleverAgents emits domain events for every significant state change. Events flow
<span style="color: #888;"># Resource events</span>
RESOURCE_ACCESSED = <span style="color: #66cc66;">"resource.accessed"</span>
RESOURCE_CREATED = <span style="color: #66cc66;">"resource.created"</span>
RESOURCE_MODIFIED = <span style="color: #66cc66;">"resource.modified"</span>
RESOURCE_DELETED = <span style="color: #66cc66;">"resource.deleted"</span>
RESOURCE_MOVED = <span style="color: #66cc66;">"resource.moved"</span>
RESOURCE_INDEXED = <span style="color: #66cc66;">"resource.indexed"</span>
<span style="color: #888;"># Correction events</span>
@@ -46136,6 +46139,37 @@ CleverAgents emits domain events for every significant state change. Events flow
<span style="color: magenta; font-weight: 600;">return</span> <span style="color: cyan;">self</span>._subject
</code></pre></div>
#### Resource Event Types and ResourceFileWatcher Behavior
> **Clarification added in response to issue [#8018](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8018).**
> Tracked for implementation in [#8025](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8025).
The full set of resource `EventType` values is:
| `EventType` member | String value | Description |
|---|---|---|
| `RESOURCE_ACCESSED` | `"resource.accessed"` | A resource was read or queried. |
| `RESOURCE_CREATED` | `"resource.created"` | A new resource file was created on disk. |
| `RESOURCE_MODIFIED` | `"resource.modified"` | An existing resource file was modified in place. |
| `RESOURCE_DELETED` | `"resource.deleted"` | A resource file was removed from disk. |
| `RESOURCE_MOVED` | `"resource.moved"` | A resource file was renamed or relocated. |
| `RESOURCE_INDEXED` | `"resource.indexed"` | A resource was (re-)indexed into the context store. |
**`ResourceFileWatcher` mapping (required behavior):**
`ResourceFileWatcher` monitors the filesystem using a `FileChangeType` enumeration produced by the underlying watcher library. It **MUST** map each `FileChangeType` to a distinct `EventType` as follows:
| `FileChangeType` | Required `EventType` emitted |
|---|---|
| `CREATED` | `RESOURCE_CREATED` |
| `MODIFIED` | `RESOURCE_MODIFIED` |
| `DELETED` | `RESOURCE_DELETED` |
| `MOVED` | `RESOURCE_MOVED` |
**Design rationale:** The `EventType` value alone MUST be sufficient for any subscriber to determine the nature of a filesystem change. Subscribers MUST NOT need to inspect `details["change_type"]` or any other payload field to distinguish between created, modified, deleted, or moved events. Encoding the change semantics in the event type (rather than a payload field) keeps subscriber logic simple and enables type-safe subscription via `EventBus.subscribe(EventType.RESOURCE_DELETED, handler)`.
> **Historical note:** Prior to this clarification, `ResourceFileWatcher` emitted `RESOURCE_MODIFIED` for all filesystem change types (created, modified, deleted, moved) and included a `change_type` key in `details` so subscribers could distinguish them. This was a workaround for the missing enum variants and is **no longer the intended design**. New and updated implementations MUST use the distinct event types listed above.
#### LLM Call Tracing
Every LLM invocation is traced with full context for debugging and cost tracking: