@cotal-ai/connector-core 0.79.0 → 0.81.1
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/dist/agui-emitter.d.ts +139 -5
- package/dist/agui-emitter.d.ts.map +1 -1
- package/dist/agui-emitter.js +310 -28
- package/dist/agui-emitter.js.map +1 -1
- package/dist/agui-holder.d.ts +113 -25
- package/dist/agui-holder.d.ts.map +1 -1
- package/dist/agui-holder.js +288 -84
- package/dist/agui-holder.js.map +1 -1
- package/dist/docs-bundle.generated.d.ts +1 -1
- package/dist/docs-bundle.generated.js +17 -17
- package/dist/docs-bundle.generated.js.map +1 -1
- package/dist/durable-source.d.ts +55 -2
- package/dist/durable-source.d.ts.map +1 -1
- package/dist/durable-source.js +98 -27
- package/dist/durable-source.js.map +1 -1
- package/package.json +2 -2
package/dist/agui-holder.d.ts
CHANGED
|
@@ -27,10 +27,23 @@ import type { AguiEmitter } from "./agui-emitter.js";
|
|
|
27
27
|
* metadata with nothing reporting why.
|
|
28
28
|
*/
|
|
29
29
|
export interface AguiEmitterHolderHooks {
|
|
30
|
-
/** Where a failure goes
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
|
|
30
|
+
/** Where a failure goes, with the delay before the holder re-establishes the plane (`0` when it
|
|
31
|
+
* does so at once), or `null` when it will not because the holder is closed. Required, and not
|
|
32
|
+
* defaulted to a swallow: the holder runs behind a hook that must not throw, so the only way a
|
|
33
|
+
* failure reaches a human is if the caller is made to say where it goes. */
|
|
34
|
+
onError: (e: Error, retryInMs: number | null) => void;
|
|
35
|
+
/**
|
|
36
|
+
* The position the adopted source has reached now: its `DurableSource.end`, for the path the
|
|
37
|
+
* holder is bound to. Taken when {@link AguiEmitterHolder.closeRun} is called, so a terminal the
|
|
38
|
+
* plane cannot take at once is placed on the turn the source had begun by then, whatever is
|
|
39
|
+
* written after it. Required: a terminal held with no position would have to be paired with a
|
|
40
|
+
* turn by count, and a connector that repeats a terminal, or loses one, then shifts every later
|
|
41
|
+
* terminal onto the wrong turn (Sol, round 11 of 2026-10-13).
|
|
42
|
+
*/
|
|
43
|
+
sourceEnd: (path: string) => Promise<string>;
|
|
44
|
+
/** The wait between re-establish attempts while the plane stays down. The first attempt after
|
|
45
|
+
* a failure is at once; this paces the ones after it. Default one second. */
|
|
46
|
+
retryMs?: number;
|
|
34
47
|
/**
|
|
35
48
|
* Told which run {@link AguiEmitterHolder.closeRun} closed, so the connector's own mapper can
|
|
36
49
|
* forget the run it will no longer attribute records to. Optional, and it is NOT the holder
|
|
@@ -61,24 +74,22 @@ export interface AguiEmitterHolderHooks {
|
|
|
61
74
|
runMeta?: (runId: string) => CotalMeta | undefined;
|
|
62
75
|
}
|
|
63
76
|
/**
|
|
64
|
-
* The one
|
|
65
|
-
* `onError`.
|
|
77
|
+
* The one line every connector logs when its event plane stops, used as a holder's `onError`.
|
|
66
78
|
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
* the seat
|
|
79
|
+
* The seat never stops for it, on any space. It used to, on a space that requires events, and the
|
|
80
|
+
* harness then restarted the connector on the next tool call: the plane was re-established anyway,
|
|
81
|
+
* once per keystroke, with a dropped mesh connection each time. The holder re-establishes it in
|
|
82
|
+
* process instead, at once, and the seat keeps its connection; the line says when.
|
|
71
83
|
*/
|
|
72
84
|
export declare function eventPlaneStopped(opts: {
|
|
73
|
-
required: boolean;
|
|
74
85
|
log: (line: string) => void;
|
|
75
|
-
|
|
76
|
-
}): (e: Error) => void;
|
|
86
|
+
}): (e: Error, retryInMs: number | null) => void;
|
|
77
87
|
/**
|
|
78
|
-
* Holds at most one {@link AguiEmitter}, started on first adopt
|
|
88
|
+
* Holds at most one {@link AguiEmitter} at a time, started on first adopt and re-established at
|
|
89
|
+
* once after a failure.
|
|
79
90
|
*
|
|
80
91
|
* `T` is the connector's source record type; the holder never inspects one. It owns four things —
|
|
81
|
-
* WHEN the emitter starts, that
|
|
92
|
+
* WHEN the emitter starts, that ONE runs at a time, that everything touching it is serialized,
|
|
82
93
|
* and carrying the first adopt's opaque context to the connector-owned factory — and deliberately
|
|
83
94
|
* owns no policy about what that context, an event, or a frame means.
|
|
84
95
|
*/
|
|
@@ -90,16 +101,44 @@ export declare class AguiEmitterHolder<T, StartContext = undefined> {
|
|
|
90
101
|
* while the first start is still in flight. */
|
|
91
102
|
private boundPath?;
|
|
92
103
|
/**
|
|
93
|
-
*
|
|
104
|
+
* The failure the plane is down for. While set, this holder starts and pumps nothing; it clears
|
|
105
|
+
* when {@link revive} re-establishes the plane.
|
|
94
106
|
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
* emitter
|
|
107
|
+
* The re-establish runs AT ONCE, off the failing step: a seat whose plane is down is a seat
|
|
108
|
+
* whose turns are missing from the wire, and nothing is gained by waiting to find out whether
|
|
109
|
+
* the fault has cleared. While it stays down the attempts follow every `retryMs`, a fixed wait
|
|
110
|
+
* that neither grows nor is capped: a standing fault costs one start a second, and the plane is
|
|
111
|
+
* back within that second of the fault clearing, whether or not the agent is doing anything. It
|
|
112
|
+
* is the same recovery a connector restart runs, so it adds no path the emitter did not already
|
|
113
|
+
* take, and a pending frame is settled by `start()` before anything new is read. The failure is
|
|
114
|
+
* still reported, every time, with the delay; a plane that came back on its own is not a plane
|
|
115
|
+
* that failed silently.
|
|
101
116
|
*/
|
|
102
117
|
private dead?;
|
|
118
|
+
/** The first adopt's context, kept so a re-establish starts the emitter as the first start did. */
|
|
119
|
+
private startContext?;
|
|
120
|
+
/** True from a failure until a re-establish has gone through in full. A failure under it is the
|
|
121
|
+
* plane still down, and the next attempt is paced by `retryMs`; without it, at once. */
|
|
122
|
+
private retried;
|
|
123
|
+
private reviveTimer?;
|
|
124
|
+
/**
|
|
125
|
+
* The turn terminals held while no emitter can take them: ones that arrived while the plane was
|
|
126
|
+
* down or while a fresh start was in flight, one whose own close failed, and the ones a dying
|
|
127
|
+
* emitter still held. Each with the position the source had reached when it was reported, which
|
|
128
|
+
* is what names its turn; {@link revive} hands them to the fresh emitter, whose pump places each
|
|
129
|
+
* on the turn the source had begun by that position (Sol, rounds 10 and 11 of 2026-10-13,
|
|
130
|
+
* through the built MCP entry point: held by count, the second turn to end during an outage lost
|
|
131
|
+
* its terminal as a repeat of the first, and a repeated terminal shifted every later one onto the
|
|
132
|
+
* wrong turn).
|
|
133
|
+
*/
|
|
134
|
+
private held;
|
|
135
|
+
/** The last turn the dying emitter had begun on the wire, for the fresh emitter to place a
|
|
136
|
+
* terminal reported before any record it reads. Absent until an emitter has been dropped. */
|
|
137
|
+
private lastTurn?;
|
|
138
|
+
/** True from the moment {@link revive} drops the failed emitter until its fresh start, pump and
|
|
139
|
+
* held close have all gone through. A terminal that arrives in that window is held, never
|
|
140
|
+
* queued: a queued close would run after the recovery pump and close whatever run is open then. */
|
|
141
|
+
private reviving;
|
|
103
142
|
/**
|
|
104
143
|
* Terminal, and NOT a failure. Set by {@link close} when the owner releases this holder: it never
|
|
105
144
|
* starts, pumps or closes a run again, `failure` stays empty, and `onError` is not called. Kept
|
|
@@ -160,17 +199,36 @@ export declare class AguiEmitterHolder<T, StartContext = undefined> {
|
|
|
160
199
|
* Synchronous and non-throwing by contract, because a hook calls it. The work lands on the chain.
|
|
161
200
|
*/
|
|
162
201
|
adopt(path: unknown, context?: StartContext): void;
|
|
202
|
+
/**
|
|
203
|
+
* Bind to the first usable path, with the first adopt's context, AT THE CALL: a terminal reported
|
|
204
|
+
* after this call, and before the start it queues has run, takes its source position from the
|
|
205
|
+
* bound path. The binding is checked by every later start, see {@link ensureStarted}, and it is
|
|
206
|
+
* set once: a later hook cannot overwrite the first session's startup fact while the
|
|
207
|
+
* connector-owned factory is still waiting on its own async preconditions.
|
|
208
|
+
*/
|
|
209
|
+
private bind;
|
|
163
210
|
/**
|
|
164
211
|
* Adopt if necessary, then drain the source into frames.
|
|
165
212
|
*
|
|
166
213
|
* Same contract as {@link adopt}: synchronous, non-throwing, work on the chain.
|
|
167
214
|
*/
|
|
168
215
|
flush(path: unknown): void;
|
|
216
|
+
/**
|
|
217
|
+
* Place every terminal the emitter still has waiting, then close the open run with the terminal
|
|
218
|
+
* owed to it, if one is. A terminal that arrived while a pump was reading was reported past that
|
|
219
|
+
* read, so another pump reads up to it and places it; one placed on the run the pump leaves open
|
|
220
|
+
* is the close the source has not synthesized, because the next prompt is not written yet. A
|
|
221
|
+
* close that fails here holds the terminal again on its way out, so the next re-establish still
|
|
222
|
+
* owes it. Every terminal goes this way, live or after an outage: a close of whatever run is open
|
|
223
|
+
* when the step runs would end the NEXT run when the flush before it read the next prompt.
|
|
224
|
+
*/
|
|
225
|
+
private settle;
|
|
169
226
|
/**
|
|
170
227
|
* Close the open run at a turn boundary the record stream cannot see.
|
|
171
228
|
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
229
|
+
* Non-throwing, work on the chain, as {@link adopt} and {@link flush}: a lifecycle hook calls it
|
|
230
|
+
* and a hook must not be made to fail. The promise handed back never rejects; it resolves once the
|
|
231
|
+
* source position the terminal is reported at has been read, for a hook that replies after that.
|
|
174
232
|
*
|
|
175
233
|
* It deliberately does NOT start an emitter. A session that never adopted a transcript has nothing
|
|
176
234
|
* open and nothing to close, and starting one here would reach the broker on the way OUT of a
|
|
@@ -186,7 +244,20 @@ export declare class AguiEmitterHolder<T, StartContext = undefined> {
|
|
|
186
244
|
closeRun(timestamp: number, error?: {
|
|
187
245
|
message: string;
|
|
188
246
|
code?: string;
|
|
189
|
-
}): void
|
|
247
|
+
}): Promise<void>;
|
|
248
|
+
/**
|
|
249
|
+
* Close the run `emitter` has open with this terminal, reporting the close. A close that FAILS
|
|
250
|
+
* holds the terminal before the failure goes on to kill the plane: the terminal is owed to its
|
|
251
|
+
* turn whether the log took it or not, and a close that failed before its frame froze leaves
|
|
252
|
+
* the run open for the re-establish to find (Sol, review of 2026-10-13: a terminal whose own
|
|
253
|
+
* log write failed was lost, and the next prompt closed the failed run as a finish). A close
|
|
254
|
+
* that failed after the freeze is the frozen frame itself; the start that settles it closes the
|
|
255
|
+
* run, and the held terminal is then dropped for naming a run the wire has closed.
|
|
256
|
+
*/
|
|
257
|
+
private closeOpenRun;
|
|
258
|
+
/** Hand a held terminal to a live emitter, which places it on its turn when its pump reads up
|
|
259
|
+
* to the position it was reported at. */
|
|
260
|
+
private handOver;
|
|
190
261
|
/**
|
|
191
262
|
* Start at most once, bind the path once.
|
|
192
263
|
*
|
|
@@ -195,6 +266,23 @@ export declare class AguiEmitterHolder<T, StartContext = undefined> {
|
|
|
195
266
|
*/
|
|
196
267
|
private ensureStarted;
|
|
197
268
|
private die;
|
|
269
|
+
/**
|
|
270
|
+
* Re-establish the plane after a failure: clear the failure, drop the emitter, and queue a start
|
|
271
|
+
* and a pump on the chain. The start is a fresh `startEmitter`, which reopens the
|
|
272
|
+
* write-ahead log, settles any frame it left pending, and builds the connector's mapper from the
|
|
273
|
+
* bracket state the log holds, before reading on from the stored cursor. A failure here is
|
|
274
|
+
* reported like the first, and the next attempt follows after `retryMs`.
|
|
275
|
+
*
|
|
276
|
+
* THE EMITTER IS DROPPED WHETHER OR NOT IT HALTED. A failure that leaves it running leaves it
|
|
277
|
+
* running with state the log never accepted: a publish that failed on the wire leaves the frame
|
|
278
|
+
* frozen as pending, which every later pump refuses to read past; a write that failed before the
|
|
279
|
+
* freeze leaves the mapper holding a run the log never opened, so the re-read of the same record
|
|
280
|
+
* closes a run the brackets never saw and the pump refuses that too. Measured on 2026-10-12 with
|
|
281
|
+
* the real reader, mapper, log and frontier: with the running emitter kept, both outages wedged
|
|
282
|
+
* the plane for good behind a retry every minute. Only a start settles the pending frame, and
|
|
283
|
+
* only a start rebuilds the mapper from the log, so the re-establish is a start.
|
|
284
|
+
*/
|
|
285
|
+
private revive;
|
|
198
286
|
/** Wait for the endpoint to be live, if the caller supplied a wait. SHARED: while one step
|
|
199
287
|
* waits, every later step joins the same promise, so a burst of flushes during one outage
|
|
200
288
|
* produces one listener and one release, and the steps still run one at a time on the chain
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agui-holder.d.ts","sourceRoot":"","sources":["../src/agui-holder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,
|
|
1
|
+
{"version":3,"file":"agui-holder.d.ts","sourceRoot":"","sources":["../src/agui-holder.ts"],"names":[],"mappings":"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"}
|