@cotal-ai/connector-core 0.168.0 → 0.169.0
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/agent.d.ts +3 -12
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +36 -207
- package/dist/agent.js.map +1 -1
- package/dist/agui-emitter.d.ts +36 -1
- package/dist/agui-emitter.d.ts.map +1 -1
- package/dist/agui-emitter.js +81 -2
- package/dist/agui-emitter.js.map +1 -1
- package/dist/agui-holder.d.ts +10 -5
- package/dist/agui-holder.d.ts.map +1 -1
- package/dist/agui-holder.js +18 -6
- package/dist/agui-holder.js.map +1 -1
- package/dist/control.d.ts +12 -27
- package/dist/control.d.ts.map +1 -1
- package/dist/control.js +88 -107
- package/dist/control.js.map +1 -1
- package/dist/docs-bundle.bin +0 -0
- package/dist/docs-bundle.generated.d.ts +1 -1
- package/dist/docs-bundle.generated.js +7 -7
- package/dist/docs-bundle.generated.js.map +1 -1
- package/dist/docs-index.bin +0 -0
- package/dist/event-startup.d.ts.map +1 -1
- package/dist/event-startup.js +24 -8
- package/dist/event-startup.js.map +1 -1
- package/dist/event-wal.d.ts +2 -0
- package/dist/event-wal.d.ts.map +1 -1
- package/dist/event-wal.js +51 -1
- package/dist/event-wal.js.map +1 -1
- package/dist/launch.d.ts +5 -3
- package/dist/launch.d.ts.map +1 -1
- package/dist/launch.js +17 -4
- package/dist/launch.js.map +1 -1
- package/dist/manager-call.d.ts +56 -1
- package/dist/manager-call.d.ts.map +1 -1
- package/dist/manager-call.js +241 -1
- package/dist/manager-call.js.map +1 -1
- package/dist/prompt-desk.js +2 -2
- package/dist/prompt-desk.js.map +1 -1
- package/dist/relay.d.ts.map +1 -1
- package/dist/relay.js +64 -33
- package/dist/relay.js.map +1 -1
- package/dist/runtime.d.ts +22 -18
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +48 -27
- package/dist/runtime.js.map +1 -1
- package/dist/session-env.d.ts +12 -9
- package/dist/session-env.d.ts.map +1 -1
- package/dist/session-env.js +46 -13
- package/dist/session-env.js.map +1 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
package/dist/relay.js
CHANGED
|
@@ -3,16 +3,25 @@
|
|
|
3
3
|
*
|
|
4
4
|
* The agent runtime runs a hook on a lifecycle event and pipes the event JSON (which
|
|
5
5
|
* includes `hook_event_name`) on stdin. We forward it to this session's connector over
|
|
6
|
-
* its local control socket and print the reply for the runtime to apply
|
|
6
|
+
* its local control socket and print the reply for the runtime to apply, but only once the
|
|
7
|
+
* connector has proved it holds the endpoint's key and the reply's MAC verifies (the control
|
|
8
|
+
* exchange in `@cotal-ai/core/control-exchange`). The key itself is never sent. It must NEVER
|
|
7
9
|
* block the session: any error → exit 0, no output. The Claude Code hook
|
|
8
10
|
* entry points are one-liners over {@link runHookRelay}.
|
|
9
11
|
*/
|
|
10
12
|
import { connect } from "node:net";
|
|
13
|
+
import { checkControlSocketDir, clientExchange } from "@cotal-ai/core/control-exchange";
|
|
11
14
|
import { controlFromEnv, hasIdentity } from "./session-env.js";
|
|
12
|
-
import { HANDOFF_RECEIPT } from "./control.js";
|
|
13
15
|
/** Re-exported for a plugin process that must stay off the barrel, as a hook does. */
|
|
14
16
|
export { hasIdentity };
|
|
15
17
|
const TIMEOUT_MS = 2000;
|
|
18
|
+
/** The most reply JSON a hook takes, in bytes. A reply is the hook's output for its runtime, and the
|
|
19
|
+
* largest today is the Claude Code hook's, whose injected context is capped at 9,000 characters:
|
|
20
|
+
* under 64 KiB as JSON even if every character were escaped. 1 MiB, the request cap, leaves room for
|
|
21
|
+
* that to grow and still bounds what a proven but runaway server can make a hook hold. */
|
|
22
|
+
const MAX_HOOK_REPLY_BYTES = 1 << 20;
|
|
23
|
+
const MAY_HAVE_BEEN_HANDLED = "this session's control endpoint proved it holds the session's key and was sent the event, " +
|
|
24
|
+
"but no proven reply came back, so the event may have been handled. No reply was used.";
|
|
16
25
|
/** A startup hook may run before the MCP process has bound its socket. Stay inside the existing
|
|
17
26
|
* hook budget, but do not turn one early ENOENT into a permanently lost lifecycle event. */
|
|
18
27
|
const CONNECT_RETRY_INITIAL_MS = 25;
|
|
@@ -126,18 +135,18 @@ export async function runHookRelay(answer, observe) {
|
|
|
126
135
|
catch { /* observation cannot block a native hook */ }
|
|
127
136
|
if (!managed)
|
|
128
137
|
return done(""); // plain session, not a managed one — no connector to relay to
|
|
129
|
-
// The socket path comes from the launch env; the
|
|
130
|
-
// env points at (the same file the in-agent server reads), never recomputed from public
|
|
131
|
-
// A malformed or missing material file
|
|
132
|
-
// hook that blocked the session, so it is caught
|
|
133
|
-
// open is this relay's whole contract.
|
|
138
|
+
// The socket path comes from the launch env; the key and version come from the launch-material
|
|
139
|
+
// file that env points at (the same file the in-agent server reads), never recomputed from public
|
|
140
|
+
// identity. A malformed or missing material file, or a version this build does not speak, THROWS
|
|
141
|
+
// from controlFromEnv, and a hook that throws is a hook that blocked the session, so it is caught
|
|
142
|
+
// here and treated as "no control session": fail open is this relay's whole contract.
|
|
134
143
|
let control;
|
|
135
144
|
try {
|
|
136
145
|
control = controlFromEnv();
|
|
137
146
|
}
|
|
138
147
|
catch {
|
|
139
148
|
warnOnce("this session's control endpoint could not be resolved: the launch material is missing, " +
|
|
140
|
-
"unreadable, readable beyond its owner, malformed, or contradicted by direct COTAL_ variables. " +
|
|
149
|
+
"unreadable, readable beyond its owner, malformed, from another release, or contradicted by direct COTAL_ variables. " +
|
|
141
150
|
"Lifecycle relays are disabled for this session, so presence will not advance and queued peer " +
|
|
142
151
|
"messages will not be injected. Check COTAL_LAUNCH_MATERIAL and COTAL_CONTROL_SOCKET.");
|
|
143
152
|
return done("");
|
|
@@ -147,7 +156,7 @@ export async function runHookRelay(answer, observe) {
|
|
|
147
156
|
// operator to ignore the channel.
|
|
148
157
|
if (!control)
|
|
149
158
|
return done("");
|
|
150
|
-
const
|
|
159
|
+
const endpoint = control;
|
|
151
160
|
const startupCritical = isSessionStart(event);
|
|
152
161
|
let sock;
|
|
153
162
|
let settled = false;
|
|
@@ -173,15 +182,16 @@ export async function runHookRelay(answer, observe) {
|
|
|
173
182
|
drop();
|
|
174
183
|
done(out);
|
|
175
184
|
};
|
|
176
|
-
/** Got a reply: keep the socket until stdout has flushed, then send
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
|
|
185
|
+
/** Got a proven reply: keep the socket until stdout has flushed, then send its receipt (a MAC over
|
|
186
|
+
* this connection's nonces and the reply) down it. Anything that kills us first (the 1s backstop,
|
|
187
|
+
* the runtime SIGKILLing the hook) closes the socket with no receipt, which is exactly the signal
|
|
188
|
+
* the connector needs to NOT commit the batch. */
|
|
189
|
+
const finishWithReceipt = (out, receipt, candidate) => {
|
|
180
190
|
if (!settle())
|
|
181
191
|
return;
|
|
182
192
|
done(out, (then) => {
|
|
183
193
|
try {
|
|
184
|
-
candidate.write(
|
|
194
|
+
candidate.write(receipt, () => {
|
|
185
195
|
drop(candidate);
|
|
186
196
|
then();
|
|
187
197
|
});
|
|
@@ -191,7 +201,18 @@ export async function runHookRelay(answer, observe) {
|
|
|
191
201
|
}
|
|
192
202
|
});
|
|
193
203
|
};
|
|
194
|
-
|
|
204
|
+
// Set once the event has been written to a proven server. Past that point every way of ending
|
|
205
|
+
// without a proven reply (the deadline, a socket error, the exchange refusing) says the event may
|
|
206
|
+
// have been handled, and nothing is retried.
|
|
207
|
+
let requestSent = false;
|
|
208
|
+
const unanswered = () => {
|
|
209
|
+
if (settled)
|
|
210
|
+
return;
|
|
211
|
+
if (requestSent)
|
|
212
|
+
warnOnce(MAY_HAVE_BEEN_HANDLED);
|
|
213
|
+
finish("");
|
|
214
|
+
};
|
|
215
|
+
const timer = setTimeout(unanswered, TIMEOUT_MS);
|
|
195
216
|
const retryLater = () => {
|
|
196
217
|
const wait = retryDelayMs;
|
|
197
218
|
retryDelayMs = Math.min(retryDelayMs * 2, CONNECT_RETRY_MAX_MS);
|
|
@@ -200,11 +221,21 @@ export async function runHookRelay(answer, observe) {
|
|
|
200
221
|
const dial = () => {
|
|
201
222
|
if (settled)
|
|
202
223
|
return;
|
|
203
|
-
|
|
224
|
+
// Off Windows the socket must sit in a directory only this user can enter, checked right before
|
|
225
|
+
// each dial. A directory that is missing reads like a connector that is not up yet; one that
|
|
226
|
+
// exists and is not private counts as no endpoint, so nothing is sent and nothing is printed.
|
|
227
|
+
const dir = checkControlSocketDir(endpoint.path);
|
|
228
|
+
if (!dir.ok) {
|
|
229
|
+
if (dir.absent && startupCritical)
|
|
230
|
+
return retryLater();
|
|
231
|
+
if (!dir.absent)
|
|
232
|
+
warnOnce("this session's control socket is not in a directory private to this user, so the hook " +
|
|
233
|
+
"connected to nothing. Lifecycle relays are disabled until the connector is relaunched.");
|
|
234
|
+
return finish("");
|
|
235
|
+
}
|
|
236
|
+
const candidate = connect(endpoint.path);
|
|
204
237
|
sock = candidate;
|
|
205
238
|
let connected = false;
|
|
206
|
-
let reply = "";
|
|
207
|
-
candidate.setEncoding("utf8");
|
|
208
239
|
// `handoff` opts into the confirmed-delivery protocol: the connector holds the connection open
|
|
209
240
|
// and treats our receipt, not its own socket write, as proof the reply reached the runtime.
|
|
210
241
|
candidate.on("connect", () => {
|
|
@@ -212,20 +243,25 @@ export async function runHookRelay(answer, observe) {
|
|
|
212
243
|
return;
|
|
213
244
|
connected = true;
|
|
214
245
|
try {
|
|
215
|
-
candidate
|
|
246
|
+
clientExchange(candidate, endpoint, { event, handoff: true }, (result) => {
|
|
247
|
+
if (settled || sock !== candidate)
|
|
248
|
+
return;
|
|
249
|
+
if (result.ok)
|
|
250
|
+
return finishWithReceipt(result.reply, result.receipt, candidate);
|
|
251
|
+
// Once the request has been written the server may have handled it, so say so rather
|
|
252
|
+
// than claim nothing happened. Either way nothing is retried and no reply is used.
|
|
253
|
+
if (result.requestSent)
|
|
254
|
+
return unanswered();
|
|
255
|
+
// A stand-in on a dead server's name, or a connector from another release, both end here.
|
|
256
|
+
warnOnce("this session's control endpoint did not prove it holds the session's key, so nothing was " +
|
|
257
|
+
"relayed and no reply was used. A connector from another release looks the same as a stand-in.");
|
|
258
|
+
finish("");
|
|
259
|
+
}, { maxReplyBytes: MAX_HOOK_REPLY_BYTES, onRequestSent: () => (requestSent = true) });
|
|
216
260
|
}
|
|
217
261
|
catch {
|
|
218
262
|
finish("");
|
|
219
263
|
}
|
|
220
264
|
});
|
|
221
|
-
candidate.on("data", (d) => {
|
|
222
|
-
if (settled || sock !== candidate)
|
|
223
|
-
return;
|
|
224
|
-
reply += d;
|
|
225
|
-
const nl = reply.indexOf("\n");
|
|
226
|
-
if (nl >= 0)
|
|
227
|
-
finishWithReceipt(reply.slice(0, nl), candidate);
|
|
228
|
-
});
|
|
229
265
|
candidate.on("error", (error) => {
|
|
230
266
|
if (settled || sock !== candidate)
|
|
231
267
|
return;
|
|
@@ -237,12 +273,7 @@ export async function runHookRelay(answer, observe) {
|
|
|
237
273
|
// Only SessionStart may outpace creation of the connector process. Later hooks must preserve
|
|
238
274
|
// immediate fail-open, and once the frame may have reached a connector any retry could deliver
|
|
239
275
|
// one lifecycle event twice.
|
|
240
|
-
|
|
241
|
-
});
|
|
242
|
-
candidate.on("end", () => {
|
|
243
|
-
if (settled || sock !== candidate)
|
|
244
|
-
return;
|
|
245
|
-
finish(reply);
|
|
276
|
+
unanswered();
|
|
246
277
|
});
|
|
247
278
|
};
|
|
248
279
|
dial();
|
package/dist/relay.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"relay.js","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"relay.js","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"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"}
|
package/dist/runtime.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type ControlEndpoint } from "@cotal-ai/core/control-exchange";
|
|
1
2
|
/**
|
|
2
3
|
* The longest control-socket path the kernel will actually bind, in BYTES.
|
|
3
4
|
*
|
|
@@ -13,25 +14,28 @@
|
|
|
13
14
|
export declare const SUN_PATH_MAX_BYTES: number;
|
|
14
15
|
/**
|
|
15
16
|
* A connector's local control endpoint: the OS path its lifecycle hooks (and the manager's
|
|
16
|
-
* cooperative-shutdown
|
|
17
|
+
* cooperative-shutdown and session calls) connect to, the key both ends prove they hold without
|
|
18
|
+
* sending it, and the exchange version (see `@cotal-ai/core`'s `control-exchange.ts`).
|
|
17
19
|
*
|
|
18
|
-
* The
|
|
19
|
-
* collision-free without leaking identity
|
|
20
|
-
*
|
|
20
|
+
* The id is `sha256(space\0name\0pid\0token)` (base64url, 22 characters): unguessable and
|
|
21
|
+
* collision-free without leaking identity. Off Windows the socket is `ctl.sock` in a directory of
|
|
22
|
+
* its own for this launch, `cotal-ctl-<id>` under `tmpdir()`, which this call makes with mode 0700
|
|
23
|
+
* and refuses to reuse. It has to exist before the path leaves this process: the path rides the
|
|
24
|
+
* child's environment and the argv of the watcher `reclaimWithChild` starts, which any local user can
|
|
25
|
+
* read in `/proc`, so a directory that already exists is not this launch's. The server checks it for
|
|
26
|
+
* owner and mode before it binds, and every client checks it again before it connects, so another
|
|
27
|
+
* user cannot create a name there, even after the server has exited. The directory is appended to
|
|
28
|
+
* `artifacts`, so the launcher removes it with the launch's other artifacts once the child has
|
|
29
|
+
* exited. Call this after every refusal a launch can make, since it is the launch's first write.
|
|
30
|
+
* Windows has no filesystem socket Node can bind, so the path is
|
|
31
|
+
* a named pipe (`\\.\pipe\…`) in the global namespace, where any local process can take a free
|
|
32
|
+
* name. There the exchange is the boundary: a stand-in that cannot prove it holds the key gets no
|
|
33
|
+
* request and its reply is never used.
|
|
21
34
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
* Minted ONCE at launch (in the manager's process, via the connector's `buildLaunch`). Both ends —
|
|
28
|
-
* the in-agent server that LISTENS and the short-lived hooks that CONNECT — then read `path`+`token`
|
|
29
|
-
* from the child env (`COTAL_CONTROL_SOCKET`/`COTAL_CONTROL_TOKEN`), never recompute them from
|
|
30
|
-
* public identity; the manager keeps them in memory for the cooperative shutdown. (`process.pid` is
|
|
31
|
-
* just generation-time entropy — the value flows by env, so it never has to match across processes.)
|
|
35
|
+
* Minted ONCE at launch (in the manager's process, via the connector's `buildLaunch`). The path
|
|
36
|
+
* reaches the child in `COTAL_CONTROL_SOCKET`; the key and version reach it in the launch material,
|
|
37
|
+
* never in argv. (`process.pid` is just generation-time entropy: the value flows by env, so it never
|
|
38
|
+
* has to match across processes.)
|
|
32
39
|
*/
|
|
33
|
-
export declare function controlEndpoint(space: string, name: string, token?: string):
|
|
34
|
-
path: string;
|
|
35
|
-
token: string;
|
|
36
|
-
};
|
|
40
|
+
export declare function controlEndpoint(space: string, name: string, artifacts: string[], token?: string): ControlEndpoint;
|
|
37
41
|
//# sourceMappingURL=runtime.d.ts.map
|
package/dist/runtime.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAA4C,CAAC;AAE5E
|
|
1
|
+
{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEjG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAA4C,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,GAAE,MAA8C,GACpD,eAAe,CA+BjB"}
|
package/dist/runtime.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
+
import { mkdirSync } from "node:fs";
|
|
1
2
|
import { tmpdir } from "node:os";
|
|
2
3
|
import { join } from "node:path";
|
|
3
4
|
import { createHash, randomBytes } from "node:crypto";
|
|
5
|
+
import { CONTROL_PROTOCOL_VERSION } from "@cotal-ai/core/control-exchange";
|
|
4
6
|
/**
|
|
5
7
|
* The longest control-socket path the kernel will actually bind, in BYTES.
|
|
6
8
|
*
|
|
@@ -16,43 +18,62 @@ import { createHash, randomBytes } from "node:crypto";
|
|
|
16
18
|
export const SUN_PATH_MAX_BYTES = process.platform === "darwin" ? 104 : 108;
|
|
17
19
|
/**
|
|
18
20
|
* A connector's local control endpoint: the OS path its lifecycle hooks (and the manager's
|
|
19
|
-
* cooperative-shutdown
|
|
21
|
+
* cooperative-shutdown and session calls) connect to, the key both ends prove they hold without
|
|
22
|
+
* sending it, and the exchange version (see `@cotal-ai/core`'s `control-exchange.ts`).
|
|
20
23
|
*
|
|
21
|
-
* The
|
|
22
|
-
* collision-free without leaking identity
|
|
23
|
-
*
|
|
24
|
+
* The id is `sha256(space\0name\0pid\0token)` (base64url, 22 characters): unguessable and
|
|
25
|
+
* collision-free without leaking identity. Off Windows the socket is `ctl.sock` in a directory of
|
|
26
|
+
* its own for this launch, `cotal-ctl-<id>` under `tmpdir()`, which this call makes with mode 0700
|
|
27
|
+
* and refuses to reuse. It has to exist before the path leaves this process: the path rides the
|
|
28
|
+
* child's environment and the argv of the watcher `reclaimWithChild` starts, which any local user can
|
|
29
|
+
* read in `/proc`, so a directory that already exists is not this launch's. The server checks it for
|
|
30
|
+
* owner and mode before it binds, and every client checks it again before it connects, so another
|
|
31
|
+
* user cannot create a name there, even after the server has exited. The directory is appended to
|
|
32
|
+
* `artifacts`, so the launcher removes it with the launch's other artifacts once the child has
|
|
33
|
+
* exited. Call this after every refusal a launch can make, since it is the launch's first write.
|
|
34
|
+
* Windows has no filesystem socket Node can bind, so the path is
|
|
35
|
+
* a named pipe (`\\.\pipe\…`) in the global namespace, where any local process can take a free
|
|
36
|
+
* name. There the exchange is the boundary: a stand-in that cannot prove it holds the key gets no
|
|
37
|
+
* request and its reply is never used.
|
|
24
38
|
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
* Minted ONCE at launch (in the manager's process, via the connector's `buildLaunch`). Both ends —
|
|
31
|
-
* the in-agent server that LISTENS and the short-lived hooks that CONNECT — then read `path`+`token`
|
|
32
|
-
* from the child env (`COTAL_CONTROL_SOCKET`/`COTAL_CONTROL_TOKEN`), never recompute them from
|
|
33
|
-
* public identity; the manager keeps them in memory for the cooperative shutdown. (`process.pid` is
|
|
34
|
-
* just generation-time entropy — the value flows by env, so it never has to match across processes.)
|
|
39
|
+
* Minted ONCE at launch (in the manager's process, via the connector's `buildLaunch`). The path
|
|
40
|
+
* reaches the child in `COTAL_CONTROL_SOCKET`; the key and version reach it in the launch material,
|
|
41
|
+
* never in argv. (`process.pid` is just generation-time entropy: the value flows by env, so it never
|
|
42
|
+
* has to match across processes.)
|
|
35
43
|
*/
|
|
36
|
-
export function controlEndpoint(space, name, token = randomBytes(32).toString("base64url")) {
|
|
44
|
+
export function controlEndpoint(space, name, artifacts, token = randomBytes(32).toString("base64url")) {
|
|
37
45
|
const id = createHash("sha256")
|
|
38
46
|
.update(`${space}\0${name}\0${process.pid}\0${token}`)
|
|
39
47
|
.digest("base64url")
|
|
40
|
-
.slice(0,
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
//
|
|
46
|
-
//
|
|
48
|
+
.slice(0, 22);
|
|
49
|
+
if (process.platform === "win32")
|
|
50
|
+
return { path: `\\\\.\\pipe\\cotal-${id}`, token, version: CONTROL_PROTOCOL_VERSION };
|
|
51
|
+
const dir = join(tmpdir(), `cotal-ctl-${id}`);
|
|
52
|
+
const path = join(dir, CONTROL_SOCKET_NAME);
|
|
53
|
+
// `id` is a fixed 22 characters, so `tmpdir()` is the only variable part of this path. A TMPDIR
|
|
54
|
+
// pointed inside a deep working copy spends the sun_path budget silently, and the overrun then
|
|
55
|
+
// surfaces as an `EINVAL` from a bind that cannot say why. Refuse HERE, where the path, its length
|
|
56
|
+
// and the limit are all in hand.
|
|
57
|
+
const tail = path.slice(tmpdir().length);
|
|
47
58
|
const bytes = Buffer.byteLength(path);
|
|
48
|
-
if (
|
|
49
|
-
const tail = `/cotal-${id}.sock`.length;
|
|
59
|
+
if (bytes > SUN_PATH_MAX_BYTES) {
|
|
50
60
|
throw new Error(`control socket path is ${bytes} bytes, over the ${SUN_PATH_MAX_BYTES}-byte sun_path limit on ` +
|
|
51
61
|
`${process.platform}, so it cannot be bound and the kernel would report only EINVAL: ${path}. ` +
|
|
52
|
-
`The socket name is a fixed ${tail} bytes, so the temp root must be at most ` +
|
|
53
|
-
`${SUN_PATH_MAX_BYTES - tail} bytes — TMPDIR is ${Buffer.byteLength(tmpdir())} bytes ` +
|
|
62
|
+
`The socket name is a fixed ${tail.length} bytes, so the temp root must be at most ` +
|
|
63
|
+
`${SUN_PATH_MAX_BYTES - tail.length} bytes — TMPDIR is ${Buffer.byteLength(tmpdir())} bytes ` +
|
|
54
64
|
`(${tmpdir()}). Point TMPDIR at a shorter directory.`);
|
|
55
65
|
}
|
|
56
|
-
|
|
66
|
+
try {
|
|
67
|
+
mkdirSync(dir, { mode: 0o700 });
|
|
68
|
+
}
|
|
69
|
+
catch (e) {
|
|
70
|
+
if (e.code !== "EEXIST")
|
|
71
|
+
throw e;
|
|
72
|
+
throw new Error(`control socket directory ${dir} already exists, so another process made it before this launch did; refusing to use it`);
|
|
73
|
+
}
|
|
74
|
+
artifacts.push(dir);
|
|
75
|
+
return { path, token, version: CONTROL_PROTOCOL_VERSION };
|
|
57
76
|
}
|
|
77
|
+
/** The control socket's file name inside its per-launch directory. */
|
|
78
|
+
const CONTROL_SOCKET_NAME = "ctl.sock";
|
|
58
79
|
//# sourceMappingURL=runtime.js.map
|
package/dist/runtime.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAwB,MAAM,iCAAiC,CAAC;AAEjG;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAa,EACb,IAAY,EACZ,SAAmB,EACnB,QAAgB,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAErD,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC;SAC5B,MAAM,CAAC,GAAG,KAAK,KAAK,IAAI,KAAK,OAAO,CAAC,GAAG,KAAK,KAAK,EAAE,CAAC;SACrD,MAAM,CAAC,WAAW,CAAC;SACnB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACxH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAC5C,gGAAgG;IAChG,+FAA+F;IAC/F,mGAAmG;IACnG,iCAAiC;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,KAAK,GAAG,kBAAkB,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,0BAA0B,KAAK,oBAAoB,kBAAkB,0BAA0B;YAC7F,GAAG,OAAO,CAAC,QAAQ,oEAAoE,IAAI,IAAI;YAC/F,8BAA8B,IAAI,CAAC,MAAM,2CAA2C;YACpF,GAAG,kBAAkB,GAAG,IAAI,CAAC,MAAM,sBAAsB,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,SAAS;YAC7F,IAAI,MAAM,EAAE,yCAAyC,CACxD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,SAAS,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,CAAC,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,wFAAwF,CAAC,CAAC;IAC3I,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAC5D,CAAC;AAED,sEAAsE;AACtE,MAAM,mBAAmB,GAAG,UAAU,CAAC"}
|
package/dist/session-env.d.ts
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* client, zod and yaml on every lifecycle event and use none of them.
|
|
5
5
|
*/
|
|
6
6
|
import { type LaunchMaterial } from "@cotal-ai/core/launch-material";
|
|
7
|
+
import { type ControlEndpoint } from "@cotal-ai/core/control-exchange";
|
|
7
8
|
/** Resolve the launch-material file, if this launch uses one. Refuses the two-carrier case: a
|
|
8
9
|
* material file AND direct material vars means two answers to "who is this session", and picking
|
|
9
10
|
* one silently is how a seat ends up connected as something nobody chose. An unreadable or
|
|
@@ -12,19 +13,21 @@ import { type LaunchMaterial } from "@cotal-ai/core/launch-material";
|
|
|
12
13
|
export declare function readMaterial(env: NodeJS.ProcessEnv): LaunchMaterial | undefined;
|
|
13
14
|
/**
|
|
14
15
|
* Resolve this session's local control endpoint. The socket path comes from
|
|
15
|
-
* `COTAL_CONTROL_SOCKET`. The
|
|
16
|
-
* `
|
|
16
|
+
* `COTAL_CONTROL_SOCKET`. The key and its exchange version come from the launch material, or from
|
|
17
|
+
* `COTAL_CONTROL_KEY` and `COTAL_CONTROL_VERSION` when no material file is supplied.
|
|
17
18
|
*
|
|
18
19
|
* {@link readMaterial} refuses a material file together with direct material variables,
|
|
19
|
-
* including `
|
|
20
|
+
* including `COTAL_CONTROL_KEY` and `COTAL_CONTROL_VERSION`.
|
|
20
21
|
*
|
|
21
|
-
* Returns `undefined` when neither socket path nor
|
|
22
|
-
* present
|
|
22
|
+
* Returns `undefined` when neither socket path nor key is present. Throws when only one is
|
|
23
|
+
* present, and when the version is missing or is not the one this build speaks: the version
|
|
24
|
+
* travels with the key, and there is no fallback. A key with whitespace around it and a version set
|
|
25
|
+
* without a key are refused too (see {@link directControlKey}), by the rule the Hermes Python reader
|
|
26
|
+
* applies. Also throws on `COTAL_CONTROL_TOKEN`, the key's
|
|
27
|
+
* name before the control exchange: a hook from that release reads it and sends the key in its first
|
|
28
|
+
* frame, so the key moved to a name such a hook does not read.
|
|
23
29
|
*/
|
|
24
|
-
export declare function controlFromEnv(env?: NodeJS.ProcessEnv):
|
|
25
|
-
path: string;
|
|
26
|
-
token: string;
|
|
27
|
-
} | undefined;
|
|
30
|
+
export declare function controlFromEnv(env?: NodeJS.ProcessEnv): ControlEndpoint | undefined;
|
|
28
31
|
/** True iff the env carries a Cotal identity — i.e. this is a launcher-spawned
|
|
29
32
|
* session, not an operator's plain `claude`. `COTAL_LINK` / `COTAL_AGENT_FILE`
|
|
30
33
|
* count: setting either is itself the explicit opt-in. The connector stays
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"session-env.d.ts","sourceRoot":"","sources":["../src/session-env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAA2C,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;
|
|
1
|
+
{"version":3,"file":"session-env.d.ts","sourceRoot":"","sources":["../src/session-env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAA2C,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAC9G,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAC;AA+B7F;;;;+DAI+D;AAC/D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,cAAc,GAAG,SAAS,CAU/E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,GAAG,SAAS,CAyBhG;AAmBD;;;uBAGuB;AACvB,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEzE"}
|
package/dist/session-env.js
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* client, zod and yaml on every lifecycle event and use none of them.
|
|
5
5
|
*/
|
|
6
6
|
import { LAUNCH_MATERIAL_ENV, readLaunchMaterial } from "@cotal-ai/core/launch-material";
|
|
7
|
+
import { assertControlVersion } from "@cotal-ai/core/control-exchange";
|
|
7
8
|
/** The env vars that carry connection material DIRECTLY, for a hand-driven session. A
|
|
8
9
|
* launcher-spawned seat gets the same material as a file instead, so that a build script, a linter
|
|
9
10
|
* or a test suite the seat shells out to does not inherit a live credential nobody handed it. */
|
|
@@ -16,12 +17,15 @@ const DIRECT_MATERIAL_VARS = [
|
|
|
16
17
|
"COTAL_SENTINEL_CREDS",
|
|
17
18
|
"COTAL_BEARER_CMD",
|
|
18
19
|
"COTAL_EVENTS_REQUIRED",
|
|
19
|
-
// The control
|
|
20
|
+
// The control key belongs here for a reason that is not symmetry. Once a launcher-spawned seat
|
|
20
21
|
// carries a material pointer in its environment, anything that INHERITS that environment and then
|
|
21
|
-
// sets
|
|
22
|
+
// sets COTAL_CONTROL_KEY by hand has two answers for one question, and controlFromEnv would
|
|
22
23
|
// silently prefer the inherited one - handing a process the OUTER seat's control endpoint while
|
|
23
|
-
// its own explicit
|
|
24
|
+
// its own explicit key sat unused. That is not hypothetical: it is what a test harness spreading
|
|
24
25
|
// `...process.env` does, and this whole change exists because that spread used to be invisible.
|
|
26
|
+
"COTAL_CONTROL_KEY",
|
|
27
|
+
"COTAL_CONTROL_VERSION",
|
|
28
|
+
// The key's name before the control exchange. controlFromEnv refuses it on its own too.
|
|
25
29
|
"COTAL_CONTROL_TOKEN",
|
|
26
30
|
// A join link is connection material in one string: it carries the server, the auth and the space.
|
|
27
31
|
// Left off this list, a launch with both a material file and a link resolved the conflict by
|
|
@@ -46,28 +50,57 @@ export function readMaterial(env) {
|
|
|
46
50
|
}
|
|
47
51
|
/**
|
|
48
52
|
* Resolve this session's local control endpoint. The socket path comes from
|
|
49
|
-
* `COTAL_CONTROL_SOCKET`. The
|
|
50
|
-
* `
|
|
53
|
+
* `COTAL_CONTROL_SOCKET`. The key and its exchange version come from the launch material, or from
|
|
54
|
+
* `COTAL_CONTROL_KEY` and `COTAL_CONTROL_VERSION` when no material file is supplied.
|
|
51
55
|
*
|
|
52
56
|
* {@link readMaterial} refuses a material file together with direct material variables,
|
|
53
|
-
* including `
|
|
57
|
+
* including `COTAL_CONTROL_KEY` and `COTAL_CONTROL_VERSION`.
|
|
54
58
|
*
|
|
55
|
-
* Returns `undefined` when neither socket path nor
|
|
56
|
-
* present
|
|
59
|
+
* Returns `undefined` when neither socket path nor key is present. Throws when only one is
|
|
60
|
+
* present, and when the version is missing or is not the one this build speaks: the version
|
|
61
|
+
* travels with the key, and there is no fallback. A key with whitespace around it and a version set
|
|
62
|
+
* without a key are refused too (see {@link directControlKey}), by the rule the Hermes Python reader
|
|
63
|
+
* applies. Also throws on `COTAL_CONTROL_TOKEN`, the key's
|
|
64
|
+
* name before the control exchange: a hook from that release reads it and sends the key in its first
|
|
65
|
+
* frame, so the key moved to a name such a hook does not read.
|
|
57
66
|
*/
|
|
58
67
|
export function controlFromEnv(env = process.env) {
|
|
68
|
+
if (env.COTAL_CONTROL_TOKEN?.trim())
|
|
69
|
+
throw new Error("COTAL config: COTAL_CONTROL_TOKEN is the control key variable of a release before the control exchange. " +
|
|
70
|
+
"Set COTAL_CONTROL_KEY and COTAL_CONTROL_VERSION instead; this build refuses the old name rather than guess which protocol it meant.");
|
|
59
71
|
const path = env.COTAL_CONTROL_SOCKET?.trim();
|
|
60
|
-
const
|
|
61
|
-
|
|
62
|
-
|
|
72
|
+
const material = readMaterial(env);
|
|
73
|
+
const token = material ? material.controlKey : directControlKey(env);
|
|
74
|
+
if (path && token) {
|
|
75
|
+
const direct = env.COTAL_CONTROL_VERSION;
|
|
76
|
+
const version = material ? material.controlVersion : direct?.trim() ? (/^(0|[1-9][0-9]*)$/.test(direct) ? Number(direct) : direct) : undefined;
|
|
77
|
+
assertControlVersion(version, material ? "this launch's material" : "COTAL_CONTROL_VERSION");
|
|
78
|
+
return { path, token, version };
|
|
79
|
+
}
|
|
63
80
|
if (!path && !token)
|
|
64
81
|
return undefined;
|
|
65
82
|
if (path)
|
|
66
|
-
throw new Error("COTAL config: COTAL_CONTROL_SOCKET is set but no control
|
|
83
|
+
throw new Error("COTAL config: COTAL_CONTROL_SOCKET is set but no control key could be resolved - neither the launch material nor COTAL_CONTROL_KEY carries one. " +
|
|
67
84
|
"Half a pair is not a control endpoint, so this launch is refused rather than started without the control plane it was configured to have.");
|
|
68
|
-
throw new Error("COTAL config: a control
|
|
85
|
+
throw new Error("COTAL config: a control key was supplied but COTAL_CONTROL_SOCKET is unset, so there is no socket to authenticate against. " +
|
|
69
86
|
"Half a pair is not a control endpoint, so this launch is refused rather than started without the control plane it was configured to have.");
|
|
70
87
|
}
|
|
88
|
+
/** The key from `COTAL_CONTROL_KEY`, for a launch with no material file. Like every `COTAL_` variable
|
|
89
|
+
* this reader takes, it counts as set when it holds something besides whitespace (what
|
|
90
|
+
* `String.prototype.trim` removes; the Hermes Python reader strips the same set). A set key is used
|
|
91
|
+
* as given: one with whitespace around it is refused rather than trimmed, and so is a version set
|
|
92
|
+
* without a key. `COTAL_CONTROL_VERSION` must then read exactly `1`, checked by the caller. */
|
|
93
|
+
function directControlKey(env) {
|
|
94
|
+
const key = env.COTAL_CONTROL_KEY;
|
|
95
|
+
if (!key?.trim()) {
|
|
96
|
+
if (env.COTAL_CONTROL_VERSION?.trim())
|
|
97
|
+
throw new Error("COTAL config: COTAL_CONTROL_VERSION is set without COTAL_CONTROL_KEY. The version travels with the key; set both or neither.");
|
|
98
|
+
return undefined;
|
|
99
|
+
}
|
|
100
|
+
if (key !== key.trim())
|
|
101
|
+
throw new Error("COTAL config: COTAL_CONTROL_KEY has whitespace around it. A key is used as given, never trimmed; remove the whitespace.");
|
|
102
|
+
return key;
|
|
103
|
+
}
|
|
71
104
|
/** True iff the env carries a Cotal identity — i.e. this is a launcher-spawned
|
|
72
105
|
* session, not an operator's plain `claude`. `COTAL_LINK` / `COTAL_AGENT_FILE`
|
|
73
106
|
* count: setting either is itself the explicit opt-in. The connector stays
|
package/dist/session-env.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"session-env.js","sourceRoot":"","sources":["../src/session-env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAuB,MAAM,gCAAgC,CAAC;
|
|
1
|
+
{"version":3,"file":"session-env.js","sourceRoot":"","sources":["../src/session-env.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const CONNECTOR_VERSION = "0.
|
|
1
|
+
export declare const CONNECTOR_VERSION = "0.169.0";
|
|
2
2
|
//# sourceMappingURL=version.generated.d.ts.map
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cotal-ai/connector-core",
|
|
3
3
|
"description": "Shared MCP-bridge runtime for Cotal connectors: the mesh agent, cotal_* tools, and hook relay.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.169.0",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -41,11 +41,11 @@
|
|
|
41
41
|
"@cotal-ai/core": ">=0.1.0"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
|
-
"@cotal-ai/auth": "0.
|
|
44
|
+
"@cotal-ai/auth": "0.169.0",
|
|
45
45
|
"jose": "^6.2.3",
|
|
46
46
|
"@cotal-ai/smoke-kit": "0.0.0",
|
|
47
47
|
"@ag-ui/core": "0.0.57",
|
|
48
|
-
"@cotal-ai/core": "0.
|
|
48
|
+
"@cotal-ai/core": "0.169.0",
|
|
49
49
|
"@nats-io/jetstream": "3.4.0",
|
|
50
50
|
"@nats-io/transport-node": "3.4.0"
|
|
51
51
|
},
|