@herdctl/chat 0.2.2 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +80 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# @herdctl/chat
|
|
2
|
+
|
|
3
|
+
> Shared chat infrastructure for herdctl connectors
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@herdctl/chat)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
**Documentation**: [herdctl.dev](https://herdctl.dev)
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
`@herdctl/chat` is the shared foundation that powers chat integrations in [herdctl](https://herdctl.dev). It provides session management, streaming message delivery, error handling, and message splitting used by `@herdctl/discord`, `@herdctl/slack`, and `@herdctl/web`.
|
|
13
|
+
|
|
14
|
+
Herdctl is an open-source system for running fleets of autonomous AI agents powered by Claude Code. This package is part of the herdctl monorepo.
|
|
15
|
+
|
|
16
|
+
> **Note**: This is an internal infrastructure package. Most users should use the platform-specific connectors (`@herdctl/discord`, `@herdctl/slack`) or the web dashboard (`@herdctl/web`) rather than this package directly.
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @herdctl/chat
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## What It Provides
|
|
25
|
+
|
|
26
|
+
### Session Management
|
|
27
|
+
|
|
28
|
+
`ChatSessionManager` tracks conversation sessions per channel or DM. Sessions are persisted to disk and automatically expire after a configurable timeout (default: 24 hours). When a user sends a message, the session manager either resumes the existing session or creates a new one, preserving conversation context via Claude SDK session resumption.
|
|
29
|
+
|
|
30
|
+
### Streaming Responses
|
|
31
|
+
|
|
32
|
+
`StreamingResponder` delivers agent responses incrementally as they are generated, rather than waiting for the full response. It buffers content and sends complete chunks at configurable intervals, respecting platform rate limits.
|
|
33
|
+
|
|
34
|
+
### Message Splitting
|
|
35
|
+
|
|
36
|
+
Long agent responses are automatically split at natural breakpoints (paragraph breaks, sentences, clauses) to fit within platform character limits (Discord: 2,000, Slack: 4,000). This ensures messages remain readable without cutting mid-sentence.
|
|
37
|
+
|
|
38
|
+
### Error Handling
|
|
39
|
+
|
|
40
|
+
A shared error handler classifies errors (transient, rate limit, authentication, etc.), provides user-friendly messages, and implements retry logic with exponential backoff. Platform connectors use this to handle failures gracefully without crashing.
|
|
41
|
+
|
|
42
|
+
### DM Filtering
|
|
43
|
+
|
|
44
|
+
The DM filter enforces access control for direct messages: enabled/disabled toggle, allowlist, blocklist, and chat mode (auto vs. mention). Blocklist takes precedence over allowlist.
|
|
45
|
+
|
|
46
|
+
### Message Extraction
|
|
47
|
+
|
|
48
|
+
Utilities for extracting text content from Claude SDK message formats, handling direct strings, nested message objects, and content block arrays.
|
|
49
|
+
|
|
50
|
+
## Architecture
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
@herdctl/chat (shared infrastructure)
|
|
54
|
+
|
|
|
55
|
+
+-- @herdctl/discord (Discord-specific integration)
|
|
56
|
+
+-- @herdctl/slack (Slack-specific integration)
|
|
57
|
+
+-- @herdctl/web (Web dashboard chat)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Each platform connector implements the `IChatConnector` interface and uses the shared infrastructure for everything that isn't platform-specific.
|
|
61
|
+
|
|
62
|
+
## Documentation
|
|
63
|
+
|
|
64
|
+
For more on how chat works in herdctl, visit [herdctl.dev](https://herdctl.dev):
|
|
65
|
+
|
|
66
|
+
- [Chat Configuration](https://herdctl.dev/configuration/agent-config/#chat)
|
|
67
|
+
- [Discord Quick Start](https://herdctl.dev/guides/discord-quick-start/)
|
|
68
|
+
- [Slack Quick Start](https://herdctl.dev/guides/slack-quick-start/)
|
|
69
|
+
|
|
70
|
+
## Related Packages
|
|
71
|
+
|
|
72
|
+
- [`herdctl`](https://www.npmjs.com/package/herdctl) - CLI for running agent fleets
|
|
73
|
+
- [`@herdctl/core`](https://www.npmjs.com/package/@herdctl/core) - Core library for programmatic use
|
|
74
|
+
- [`@herdctl/discord`](https://www.npmjs.com/package/@herdctl/discord) - Discord connector
|
|
75
|
+
- [`@herdctl/slack`](https://www.npmjs.com/package/@herdctl/slack) - Slack connector
|
|
76
|
+
- [`@herdctl/web`](https://www.npmjs.com/package/@herdctl/web) - Web dashboard
|
|
77
|
+
|
|
78
|
+
## License
|
|
79
|
+
|
|
80
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@herdctl/chat",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"description": "Shared chat infrastructure for herdctl connectors",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"dependencies": {
|
|
13
13
|
"yaml": "^2.3.0",
|
|
14
14
|
"zod": "^3.22.0",
|
|
15
|
-
"@herdctl/core": "5.2.
|
|
15
|
+
"@herdctl/core": "5.2.1"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
18
|
"@vitest/coverage-v8": "^4.0.17",
|