agent-common 1.0.1 → 1.0.2
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/CHANGELOG.md +12 -0
- package/dist/transport/ws.d.ts +19 -3
- package/dist/transport/ws.d.ts.map +1 -1
- package/dist/transport/ws.js +27 -9
- package/dist/transport/ws.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.0.2] - 2026-04-07
|
|
4
|
+
|
|
5
|
+
- `setupWebSocket`:
|
|
6
|
+
- `getCategoryData(category)` now returns an object whose keys are **spread** into the delta payload. Lets consumers bundle related fields (e.g. `messages + messageCount`) under one fingerprint.
|
|
7
|
+
- New optional `onMessage(ws, msg)` callback for custom client-to-server message types beyond the built-in `refresh`. Return `true` to signal the message was handled.
|
|
8
|
+
- `WsHandle` now exposes `broadcast(message)` for raw-string broadcasts to all open clients.
|
|
9
|
+
|
|
10
|
+
## [1.0.1] - 2026-04-07
|
|
11
|
+
|
|
12
|
+
- `json()` accepts `options.extraHeaders` to merge custom headers (e.g. SECURITY_HEADERS) into the response.
|
|
13
|
+
- `serveStatic()` accepts `options.spaFallback` (default true) — set to `false` for strict 404-on-miss behavior, and `options.extraHeaders` to merge headers into 200 responses.
|
|
14
|
+
|
|
3
15
|
## [1.0.0] - 2026-04-07
|
|
4
16
|
|
|
5
17
|
Initial release of `agent-common`. Extracted shared scaffolding from `agent-comm`, `agent-tasks`, `agent-knowledge`, and `agent-discover`:
|
package/dist/transport/ws.d.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
import { WebSocketServer } from 'ws';
|
|
1
|
+
import { WebSocketServer, WebSocket } from 'ws';
|
|
2
2
|
import type { Server } from 'http';
|
|
3
3
|
export interface WsHandle {
|
|
4
4
|
wss: WebSocketServer;
|
|
5
|
+
/** Send a raw JSON string to every open client. */
|
|
6
|
+
broadcast(message: string): void;
|
|
5
7
|
close(): void;
|
|
6
8
|
}
|
|
7
9
|
export interface WsOptions<F extends Record<string, string>> {
|
|
@@ -9,10 +11,24 @@ export interface WsOptions<F extends Record<string, string>> {
|
|
|
9
11
|
httpServer: Server;
|
|
10
12
|
/** Compute current fingerprints. Cheap query — runs every poll interval. */
|
|
11
13
|
getFingerprints: () => F;
|
|
12
|
-
/**
|
|
13
|
-
|
|
14
|
+
/**
|
|
15
|
+
* Fetch fresh data for a single changed category. Return an object that
|
|
16
|
+
* will be SPREAD into the delta payload (so the consumer controls keys).
|
|
17
|
+
* For the simple case, return `{ [category]: value }`. For bundled fields,
|
|
18
|
+
* return `{ messages: [...], messageCount: n }`.
|
|
19
|
+
*/
|
|
20
|
+
getCategoryData: (category: keyof F) => Record<string, unknown>;
|
|
14
21
|
/** Fetch full state payload (sent on connect and on client `refresh`). */
|
|
15
22
|
getFullState: () => Record<string, unknown>;
|
|
23
|
+
/**
|
|
24
|
+
* Optional custom message handler. Called after `refresh` has been ruled out.
|
|
25
|
+
* Return true to signal the message was handled; false/undefined falls through
|
|
26
|
+
* to the default "unknown message type" error response.
|
|
27
|
+
*/
|
|
28
|
+
onMessage?: (ws: WebSocket, msg: {
|
|
29
|
+
type?: string;
|
|
30
|
+
[key: string]: unknown;
|
|
31
|
+
}) => boolean | void;
|
|
16
32
|
/** Max concurrent connections (default: 50). */
|
|
17
33
|
maxConnections?: number;
|
|
18
34
|
/** Max single message size in bytes (default: 4096). */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/transport/ws.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/transport/ws.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,eAAe,CAAC;IACrB,mDAAmD;IACnD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IACzD,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChE,0EAA0E;IAC1E,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,KAAK,OAAO,GAAG,IAAI,CAAC;IAC9F,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAOD,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,CAuJ7F"}
|
package/dist/transport/ws.js
CHANGED
|
@@ -5,9 +5,15 @@
|
|
|
5
5
|
// - getFingerprints(): an object whose keys are categories and values are
|
|
6
6
|
// short fingerprint strings derived from the DB. Polled every interval.
|
|
7
7
|
// - getCategoryData(category): returns the current data for a category.
|
|
8
|
-
//
|
|
9
|
-
//
|
|
10
|
-
//
|
|
8
|
+
// The returned object is SPREAD into the delta payload, so the consumer
|
|
9
|
+
// controls the keys — this lets one category push multiple related
|
|
10
|
+
// fields (e.g. messages + messageCount) in a single delta.
|
|
11
|
+
// - getFullState(): returns the full state payload sent on connect and
|
|
12
|
+
// on client `refresh`.
|
|
13
|
+
//
|
|
14
|
+
// Optional:
|
|
15
|
+
// - onMessage(ws, msg): handle custom client-to-server message types
|
|
16
|
+
// beyond the built-in `refresh`. Return true if handled.
|
|
11
17
|
// =============================================================================
|
|
12
18
|
import { WebSocketServer, WebSocket } from 'ws';
|
|
13
19
|
export function setupWebSocket(opts) {
|
|
@@ -39,7 +45,8 @@ export function setupWebSocket(opts) {
|
|
|
39
45
|
let hasChanges = false;
|
|
40
46
|
for (const key of Object.keys(currentFp)) {
|
|
41
47
|
if (prev[key] !== currentFp[key]) {
|
|
42
|
-
|
|
48
|
+
const data = opts.getCategoryData(key);
|
|
49
|
+
Object.assign(changed, data);
|
|
43
50
|
hasChanges = true;
|
|
44
51
|
}
|
|
45
52
|
}
|
|
@@ -84,13 +91,17 @@ export function setupWebSocket(opts) {
|
|
|
84
91
|
if (state)
|
|
85
92
|
state.fingerprints = null;
|
|
86
93
|
sendFull(ws);
|
|
94
|
+
return;
|
|
87
95
|
}
|
|
88
|
-
|
|
89
|
-
const
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
ws.send(JSON.stringify({ type: 'error', message: `Unknown message type: ${safeType}` }));
|
|
96
|
+
if (opts.onMessage) {
|
|
97
|
+
const handled = opts.onMessage(ws, msg);
|
|
98
|
+
if (handled)
|
|
99
|
+
return;
|
|
93
100
|
}
|
|
101
|
+
const safeType = String(msg.type ?? '')
|
|
102
|
+
.slice(0, 64)
|
|
103
|
+
.replace(/[<>&"']/g, '');
|
|
104
|
+
ws.send(JSON.stringify({ type: 'error', message: `Unknown message type: ${safeType}` }));
|
|
94
105
|
});
|
|
95
106
|
ws.on('error', () => clients.delete(ws));
|
|
96
107
|
ws.on('close', () => clients.delete(ws));
|
|
@@ -129,6 +140,13 @@ export function setupWebSocket(opts) {
|
|
|
129
140
|
pollTimer.unref();
|
|
130
141
|
return {
|
|
131
142
|
wss,
|
|
143
|
+
broadcast(message) {
|
|
144
|
+
for (const [ws] of clients) {
|
|
145
|
+
if (ws.readyState === WebSocket.OPEN) {
|
|
146
|
+
ws.send(message);
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
},
|
|
132
150
|
close() {
|
|
133
151
|
clearInterval(pingTimer);
|
|
134
152
|
clearInterval(pollTimer);
|
package/dist/transport/ws.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/transport/ws.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qCAAqC;AACrC,EAAE;AACF,mEAAmE;AACnE,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,
|
|
1
|
+
{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/transport/ws.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qCAAqC;AACrC,EAAE;AACF,mEAAmE;AACnE,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,uEAAuE;AACvE,+DAA+D;AAC/D,yEAAyE;AACzE,2BAA2B;AAC3B,EAAE;AACF,YAAY;AACZ,uEAAuE;AACvE,6DAA6D;AAC7D,gFAAgF;AAEhF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AA+ChD,MAAM,UAAU,cAAc,CAAmC,IAAkB;IACjF,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;IACjD,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC;IACnD,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC;IACrD,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,KAAK,CAAC;IACpD,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ;QACb,CAAC,CAAC,GAAG,EAAE,EAAE;YACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,2BAA2B,GAAG,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CACxF,CAAC;QACJ,CAAC,CAAC,CAAC;IAEL,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC;IACzF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,SAAS,QAAQ,CAAC,EAAa;QAC7B,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,KAAK;gBAAE,KAAK,CAAC,YAAY,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;YAC1C,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC;QACrE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAED,SAAS,SAAS,CAAC,EAAa,EAAE,KAAqB,EAAE,SAAY;QACnE,MAAM,IAAI,GAAG,KAAK,CAAC,YAAa,CAAC;QACjC,MAAM,OAAO,GAA4B,EAAE,CAAC;QAC5C,IAAI,UAAU,GAAG,KAAK,CAAC;QAEvB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAmB,EAAE,CAAC;YAC3D,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;gBACvC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;gBAC7B,UAAU,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,UAAU;YAAE,OAAO;QACxB,KAAK,CAAC,YAAY,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;QAEtC,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,EAAa,EAAE,EAAE;QACrC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,cAAc,EAAE,CAAC;YACtC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;YACvC,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,QAAQ,CAAC,EAAE,CAAC,CAAC;QAEb,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,KAAK;gBAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QAChC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE;YAC/B,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;gBACpE,OAAO;YACT,CAAC;YAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3E,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC,CAAC,CAAC;gBACrF,OAAO;YACT,CAAC;YAED,MAAM,GAAG,GAAG,MAAmD,CAAC;YAChE,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC9B,IAAI,KAAK;oBAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;gBACrC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBACb,OAAO;YACT,CAAC;YAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBACxC,IAAI,OAAO;oBAAE,OAAO;YACtB,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;iBACpC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;iBACZ,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YAC3B,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3F,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QACzC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;gBACjB,EAAE,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACnB,SAAS;YACX,CAAC;YACD,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;YACpB,EAAE,CAAC,IAAI,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,EAAE,cAAc,CAAC,CAAC;IACnB,SAAS,CAAC,KAAK,EAAE,CAAC;IAElB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YACzC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;gBAClC,IAAI,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI;oBAAE,SAAS;gBAC/C,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;oBACxB,QAAQ,CAAC,EAAE,CAAC,CAAC;oBACb,SAAS;gBACX,CAAC;gBACD,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC,EAAE,cAAc,CAAC,CAAC;IACnB,SAAS,CAAC,KAAK,EAAE,CAAC;IAElB,OAAO;QACL,GAAG;QACH,SAAS,CAAC,OAAe;YACvB,KAAK,MAAM,CAAC,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;oBACrC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;QACD,KAAK;YACH,aAAa,CAAC,SAAS,CAAC,CAAC;YACzB,aAAa,CAAC,SAAS,CAAC,CAAC;YACzB,KAAK,MAAM,CAAC,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;gBAC3B,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;YACzC,CAAC;YACD,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,GAAG,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}
|
package/package.json
CHANGED