@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.
@@ -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. Required, and not defaulted to a swallow: the holder runs behind a hook
31
- * that must not throw, so the only way a failure reaches a human is if the caller is made to say
32
- * where it goes. */
33
- onError: (e: Error) => void;
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 answer every connector gives when its event plane stops for good, used as a holder's
65
- * `onError`.
77
+ * The one line every connector logs when its event plane stops, used as a holder's `onError`.
66
78
  *
67
- * Whether a seat may outlive its event plane is the space's policy, so it is decided here and not
68
- * by each harness: on a space that requires events the seat stops, because a seat that kept taking
69
- * turns would be on the roster while breaking the policy that admitted it. Any other space keeps
70
- * the seat running with the reason in its log.
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
- stopSeat: () => void;
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 it starts AT MOST ONCE, that everything touching it is serialized,
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
- * Terminal. Once set, this holder never starts, pumps, or reports success again.
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
- * It does not retry, and that is a decision rather than an omission. A retry on the next hook
96
- * would re-run that preflight and a WAL recovery against a stream this holder has already
97
- * failed to establish itself on, on a timer set by how often the user happens to type. The
98
- * emitter's own answer to an uncertain publish is to halt rather than to limp, and a holder that
99
- * quietly reconnected underneath it would reintroduce, one layer up, exactly the silence the
100
- * emitter refuses.
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
- * Same contract as {@link adopt} and {@link flush}: synchronous, non-throwing, work on the chain,
173
- * because a lifecycle hook calls it and a hook must not be made to wait or to fail.
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,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;yBAEqB;IACrB,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB,GAAG,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CASrB;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAiB,CAAC,CAAC,EAAE,YAAY,GAAG,SAAS;IAsCtD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAtCxB,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC;oDACgD;IAChD,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,CAAC,CAAQ;IACrB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,CAAS;IACrB;2EACuE;IACvE,OAAO,CAAC,KAAK,CAAoC;IACjD;qFACiF;IACjF,OAAO,CAAC,QAAQ,CAAC,CAAgB;IAEjC;;;;;;OAMG;gBAEgB,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAC1F,KAAK,EAAE,sBAAsB;IAGhD;;mFAE+E;IAC/E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,uDAAuD;IACvD,IAAI,OAAO,IAAI,KAAK,GAAG,SAAS,CAE/B;IAED,4FAA4F;IAC5F,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,uEAAuE;IACvE,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAOlD;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAS1B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAc7E;;;;;OAKG;YACW,aAAa;IAqE3B,OAAO,CAAC,GAAG;IAQX;;;;;wFAKoF;IACpF,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,OAAO;IAOf,4FAA4F;IACtF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}
1
+ {"version":3,"file":"agui-holder.d.ts","sourceRoot":"","sources":["../src/agui-holder.ts"],"names":[],"mappings":"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"}