@cloop/runner 0.0.0-stage → 0.2.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/README.md +65 -2
- package/dist/box-HBQ4ZM2Y.js +247 -0
- package/dist/chunk-2ZVYM4JU.js +2755 -0
- package/dist/chunk-3DIGCVL4.js +70 -0
- package/dist/chunk-4LFQXBWP.js +26 -0
- package/dist/chunk-AG6SI6I2.js +88 -0
- package/dist/chunk-AQGBNKUG.js +239 -0
- package/dist/chunk-J6AEO3GT.js +97 -0
- package/dist/chunk-JX6VG5FE.js +150 -0
- package/dist/chunk-OJ5AREUC.js +131 -0
- package/dist/chunk-OKF4BDBH.js +8 -0
- package/dist/chunk-ZILLDYL4.js +150 -0
- package/dist/connect-LRQ4C3KK.js +66 -0
- package/dist/disconnect-FQ6ODTTE.js +143 -0
- package/dist/hook-activity-O2NNKTOE.js +91 -0
- package/dist/hook-session-start-MT67MMDM.js +153 -0
- package/dist/index.js +111 -0
- package/dist/install-HTDTCELB.js +100 -0
- package/dist/login-4GUYT5MR.js +14 -0
- package/dist/mcp-server-TV7MHVHZ.js +399 -0
- package/dist/runner-5H7ECAZ6.js +147 -0
- package/dist/statusline-6JMHIL54.js +177 -0
- package/package.json +57 -5
package/README.md
CHANGED
|
@@ -1,3 +1,66 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cloop/runner
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The `cloop` CLI: device login, a stdio MCP server (Cloop Skills), and a Claude Code hook that heartbeat your agents into the Cloop mesh. Harness- and domain-agnostic — Claude Code, Cowork, and Codex all get presence via the MCP server; Claude Code hooks add session-lifecycle detail.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @cloop/runner
|
|
9
|
+
cloop login # approve the device in your browser
|
|
10
|
+
cloop install # register the MCP server with Claude Code / others
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Credentials live in `~/.cloop/credentials.json`. The API origin comes from `CLOOP_ORIGIN`, the stored value, or the staging default.
|
|
14
|
+
|
|
15
|
+
## Commands
|
|
16
|
+
|
|
17
|
+
| Command | What it does |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| `cloop login [--name <device>]` | Device-code flow → long-lived token |
|
|
20
|
+
| `cloop install` | `claude mcp add cloop -- cloop serve` + Cowork/Codex instructions |
|
|
21
|
+
| `cloop serve [--platform <p>]` | Run the stdio MCP server (heartbeats presence) |
|
|
22
|
+
| `cloop hook session-start` | Claude Code SessionStart hook — **not registered in Phase 1** |
|
|
23
|
+
|
|
24
|
+
### Presence model (Phase 1)
|
|
25
|
+
|
|
26
|
+
The MCP server (`cloop serve`) is the sole presence source: one `agent_sessions` row per live server process. Its `session_key` is `CLAUDE_SESSION_ID` when the harness provides it, otherwise a per-process UUID. `name` is the harness label ("Claude Code" / "Codex" / "Cowork"); `machine` is the hostname; login `deviceName` is separate (`cli_devices.name`).
|
|
27
|
+
|
|
28
|
+
`cloop hook session-start` exists in the tree but `cloop install` does **not** wire it up — Claude Code hooks are the Phase 2 coding adapter (richer session lifecycle detail). Leaving it unregistered keeps Phase 1 at one row per MCP process.
|
|
29
|
+
|
|
30
|
+
## MCP tools
|
|
31
|
+
|
|
32
|
+
The server exposes one built-in tool plus every tool advertised by the shared
|
|
33
|
+
app-side registry — it fetches `GET {origin}/api/agent/mesh/tools` at startup and
|
|
34
|
+
registers each dynamically, proxying calls through `POST {origin}/api/agent/mesh/tools`
|
|
35
|
+
`{tool, input}`. New skills land with no CLI release.
|
|
36
|
+
|
|
37
|
+
- `cloop_status {}` — built-in: who's live on your mesh, on what surface (served
|
|
38
|
+
locally from `/api/agent/mesh/status`, not the registry)
|
|
39
|
+
- `cloop_inbox {action?}` — built-in: `drain` (default) returns and clears the
|
|
40
|
+
delegated tasks / DMs pushed to this agent over the mesh; `list` peeks
|
|
41
|
+
- registry tools — e.g. `search`, `list_tasks`, `get_task`, `get_task_context`,
|
|
42
|
+
`get_contact`, `list_cloops`, `get_cloop`
|
|
43
|
+
|
|
44
|
+
If the registry is unreachable at startup, the server runs status-only (warns once
|
|
45
|
+
on stderr). A `401` from any proxied call returns an `isError` result asking the
|
|
46
|
+
user to run `cloop login`.
|
|
47
|
+
|
|
48
|
+
## Live presence mesh (`cloop serve`)
|
|
49
|
+
|
|
50
|
+
On start, `serve` opens a WebSocket to the cloop-mesh Worker's per-user Durable
|
|
51
|
+
Object at `{CLOOP_MESH_URL}/mesh/agent?session_key=…` (default
|
|
52
|
+
`https://mcp-staging.mycloop.com`; override via `CLOOP_MESH_URL` or the stored
|
|
53
|
+
`meshUrl`). The device token rides the first `Sec-WebSocket-Protocol` entry, never
|
|
54
|
+
the URL (query strings leak into edge logs). While it's up, presence
|
|
55
|
+
beats ride the socket (the DO mirrors them into the heartbeat route) and the HTTP
|
|
56
|
+
`HeartbeatClient` is the fallback; it reconnects with 1s→60s backoff + jitter.
|
|
57
|
+
Incoming `delegate` / `dm` frames are appended to `~/.cloop/inbox.jsonl` and the
|
|
58
|
+
statusline shows a `✉ N` pending badge; `cloop_inbox` drains them.
|
|
59
|
+
|
|
60
|
+
## Develop
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npm install
|
|
64
|
+
npm run build
|
|
65
|
+
npm test
|
|
66
|
+
```
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import {
|
|
3
|
+
MeshSocket,
|
|
4
|
+
defaultSocketFactory
|
|
5
|
+
} from "./chunk-ZILLDYL4.js";
|
|
6
|
+
import {
|
|
7
|
+
BoxWatch,
|
|
8
|
+
DEFAULT_FALLBACK_MODEL,
|
|
9
|
+
LocalDriver,
|
|
10
|
+
T3Client,
|
|
11
|
+
T3Driver,
|
|
12
|
+
claudeDialect,
|
|
13
|
+
codexDialect,
|
|
14
|
+
connectCommand,
|
|
15
|
+
isLocal,
|
|
16
|
+
lockThreadsFile,
|
|
17
|
+
mintSession,
|
|
18
|
+
probeClaude,
|
|
19
|
+
probeCodex,
|
|
20
|
+
readRunnerConfig,
|
|
21
|
+
runBoxTool,
|
|
22
|
+
threadsFilePath,
|
|
23
|
+
writeBoxConfig,
|
|
24
|
+
writeRunnerState
|
|
25
|
+
} from "./chunk-2ZVYM4JU.js";
|
|
26
|
+
import "./chunk-AQGBNKUG.js";
|
|
27
|
+
import {
|
|
28
|
+
getMachine
|
|
29
|
+
} from "./chunk-JX6VG5FE.js";
|
|
30
|
+
import "./chunk-AG6SI6I2.js";
|
|
31
|
+
import "./chunk-OKF4BDBH.js";
|
|
32
|
+
import {
|
|
33
|
+
getMeshUrl,
|
|
34
|
+
getToken,
|
|
35
|
+
readCredentials
|
|
36
|
+
} from "./chunk-3DIGCVL4.js";
|
|
37
|
+
|
|
38
|
+
// src/commands/box.ts
|
|
39
|
+
var BEAT_MS = 6e4;
|
|
40
|
+
var RESEND_MS = 5 * 6e4;
|
|
41
|
+
var REPAIR_BEFORE_MS = 2 * 24 * 36e5;
|
|
42
|
+
var out = (line) => console.log(line);
|
|
43
|
+
var red = (s) => `\x1B[31m${s}\x1B[0m`;
|
|
44
|
+
var log = (line) => console.error(`[workstation:daemon] ${line}`);
|
|
45
|
+
var REVOKED_CLOSE = 4001;
|
|
46
|
+
var REFUSED_LINE = "refused: Cloop no longer accepts this runner. It was disconnected, or its login expired. Run `cloop connect` on it to connect it again.";
|
|
47
|
+
async function awaitNewDeviceToken(current, read, { tries = 3, delayMs = 2e3 } = {}) {
|
|
48
|
+
for (let i = 0; i < tries; i++) {
|
|
49
|
+
const next = read();
|
|
50
|
+
if (next && next !== current) return next;
|
|
51
|
+
if (i < tries - 1) await new Promise((r) => setTimeout(r, delayMs));
|
|
52
|
+
}
|
|
53
|
+
return null;
|
|
54
|
+
}
|
|
55
|
+
async function machineHarnesses(cfg) {
|
|
56
|
+
const [claude, codex] = await Promise.all([
|
|
57
|
+
probeClaude(cfg.driver === "claude-code" ? cfg.bin : void 0),
|
|
58
|
+
probeCodex(cfg.driver === "codex" ? cfg.bin : void 0)
|
|
59
|
+
]);
|
|
60
|
+
return [claude, codex].filter((h) => h !== null);
|
|
61
|
+
}
|
|
62
|
+
function localDriver(cfg, name) {
|
|
63
|
+
const bin = cfg.driver === name ? cfg.bin : void 0;
|
|
64
|
+
return new LocalDriver({
|
|
65
|
+
dialect: name === "claude-code" ? claudeDialect(bin, cfg.fallbackModels ?? DEFAULT_FALLBACK_MODEL) : codexDialect(bin),
|
|
66
|
+
repos: cfg.repos,
|
|
67
|
+
label: cfg.label,
|
|
68
|
+
harnesses: () => machineHarnesses(cfg),
|
|
69
|
+
log
|
|
70
|
+
});
|
|
71
|
+
}
|
|
72
|
+
function recordConnected(logLine, write = writeRunnerState) {
|
|
73
|
+
try {
|
|
74
|
+
write({ pid: process.pid, connected_at: (/* @__PURE__ */ new Date()).toISOString() });
|
|
75
|
+
} catch (err) {
|
|
76
|
+
logLine(`state write failed: ${err.code ?? "unknown"}`);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
async function run() {
|
|
80
|
+
let cfg = readRunnerConfig();
|
|
81
|
+
let token = cfg?.deviceToken ?? getToken();
|
|
82
|
+
if (!token || !cfg) {
|
|
83
|
+
out(`${red("\u2717")} Not connected. Run \`cloop connect\` first.`);
|
|
84
|
+
process.exit(1);
|
|
85
|
+
}
|
|
86
|
+
if (!cfg.deviceToken) {
|
|
87
|
+
log("no runner device on this machine; run `cloop connect` so the Agent can reach it");
|
|
88
|
+
}
|
|
89
|
+
const name = process.env.CLOOP_DRIVER ?? cfg.driver ?? "t3";
|
|
90
|
+
const local = isLocal(cfg) ? cfg : null;
|
|
91
|
+
if (name === "t3" === Boolean(local)) {
|
|
92
|
+
out(
|
|
93
|
+
`${red("\u2717")} This machine is not connected for ${name}. Run \`cloop connect --driver ${name}\` first.`
|
|
94
|
+
);
|
|
95
|
+
process.exit(1);
|
|
96
|
+
}
|
|
97
|
+
const t3 = { client: isLocal(cfg) ? null : new T3Client(cfg.t3Url, cfg.token) };
|
|
98
|
+
const machine = getMachine();
|
|
99
|
+
const sessionKey = `box:${machine}`;
|
|
100
|
+
const factory = await defaultSocketFactory();
|
|
101
|
+
const lock = lockThreadsFile(threadsFilePath());
|
|
102
|
+
if (!lock.ok) {
|
|
103
|
+
out(`${red("\u2717")} Another \`cloop box run\` is running (pid ${lock.heldBy}). Stop it first.`);
|
|
104
|
+
process.exit(1);
|
|
105
|
+
}
|
|
106
|
+
const driver = local && name !== "t3" ? localDriver(local, name) : new T3Driver({
|
|
107
|
+
client: () => t3.client,
|
|
108
|
+
t3Bin: isLocal(cfg) ? null : cfg.t3Bin,
|
|
109
|
+
scope: () => cfg && !isLocal(cfg) ? cfg.scope : void 0,
|
|
110
|
+
log,
|
|
111
|
+
watched: ({ work_id, thread_id }) => {
|
|
112
|
+
const e = watch.list().find((x) => work_id ? x.work_id === work_id : x.thread_id === thread_id);
|
|
113
|
+
return e && { thread_id: e.thread_id, settled: Boolean(e.settled_at) };
|
|
114
|
+
}
|
|
115
|
+
});
|
|
116
|
+
const watch = new BoxWatch({
|
|
117
|
+
file: threadsFilePath(),
|
|
118
|
+
watch: (id, onEvent) => driver.watch(id, onEvent),
|
|
119
|
+
send: (frame) => socket.send({ ...frame }),
|
|
120
|
+
log
|
|
121
|
+
});
|
|
122
|
+
const onCall = async (frame) => {
|
|
123
|
+
const started = Date.now();
|
|
124
|
+
const result = await runBoxTool(
|
|
125
|
+
{ driver, onLaunch: (workId, threadId) => watch.add(workId, threadId) },
|
|
126
|
+
frame.tool,
|
|
127
|
+
frame.args
|
|
128
|
+
);
|
|
129
|
+
socket.send({ type: "result", id: frame.id, ...result });
|
|
130
|
+
log(
|
|
131
|
+
`call tool=${frame.tool} ok=${result.ok} ms=${Date.now() - started}${result.ok ? "" : ` error=${result.error} detail=${result.detail.slice(0, 300)}`}`
|
|
132
|
+
);
|
|
133
|
+
};
|
|
134
|
+
const socket = new MeshSocket({
|
|
135
|
+
meshUrl: getMeshUrl(),
|
|
136
|
+
token,
|
|
137
|
+
sessionKey,
|
|
138
|
+
kind: "workstation",
|
|
139
|
+
factory,
|
|
140
|
+
onMessage: () => {
|
|
141
|
+
},
|
|
142
|
+
onCall: (frame) => void onCall(frame),
|
|
143
|
+
onAck: (of, ok) => watch.ack(of, ok),
|
|
144
|
+
onOpen: () => {
|
|
145
|
+
log(`connected to ${getMeshUrl()}`);
|
|
146
|
+
recordConnected(log);
|
|
147
|
+
watch.flush();
|
|
148
|
+
},
|
|
149
|
+
onClose: (code) => log(
|
|
150
|
+
code === REVOKED_CLOSE ? "disconnected by Cloop (revoked), checking" : "disconnected, reconnecting"
|
|
151
|
+
),
|
|
152
|
+
onRefused: () => void (async () => {
|
|
153
|
+
const fresh = await awaitNewDeviceToken(token ?? "", () => readRunnerConfig()?.deviceToken);
|
|
154
|
+
const next = fresh ? readRunnerConfig() : null;
|
|
155
|
+
if (fresh && next) {
|
|
156
|
+
log("reconnecting with the device token `cloop connect` just wrote");
|
|
157
|
+
token = fresh;
|
|
158
|
+
cfg = next;
|
|
159
|
+
if (!isLocal(next)) t3.client = new T3Client(next.t3Url, next.token);
|
|
160
|
+
socket.restart(fresh);
|
|
161
|
+
return;
|
|
162
|
+
}
|
|
163
|
+
log(REFUSED_LINE);
|
|
164
|
+
stop(1);
|
|
165
|
+
})()
|
|
166
|
+
});
|
|
167
|
+
socket.start();
|
|
168
|
+
log(
|
|
169
|
+
`connecting to ${getMeshUrl()} as ${sessionKey} (${readCredentials()?.deviceName ?? machine}) driver=${driver.name}`
|
|
170
|
+
);
|
|
171
|
+
watch.start();
|
|
172
|
+
setInterval(() => watch.flush(), RESEND_MS).unref();
|
|
173
|
+
const renewT3 = async () => {
|
|
174
|
+
if (!cfg || isLocal(cfg) || Date.parse(cfg.expiresAt) - Date.now() >= REPAIR_BEFORE_MS) return;
|
|
175
|
+
try {
|
|
176
|
+
const disk = readRunnerConfig();
|
|
177
|
+
const renewed = {
|
|
178
|
+
...await mintSession(cfg.t3Url, { stored: cfg.t3Bin }),
|
|
179
|
+
// Read from disk: `cloop connect` may have replaced it since.
|
|
180
|
+
deviceToken: disk?.deviceToken ?? cfg.deviceToken,
|
|
181
|
+
...disk?.origin ?? cfg.origin ? { origin: disk?.origin ?? cfg.origin } : {}
|
|
182
|
+
};
|
|
183
|
+
cfg = renewed;
|
|
184
|
+
writeBoxConfig(renewed);
|
|
185
|
+
t3.client = new T3Client(renewed.t3Url, renewed.token);
|
|
186
|
+
log(`T3 session renewed until ${renewed.expiresAt}`);
|
|
187
|
+
} catch (err) {
|
|
188
|
+
log(`T3 session renewal failed: ${err instanceof Error ? err.message : String(err)}`);
|
|
189
|
+
}
|
|
190
|
+
};
|
|
191
|
+
const beat = async () => {
|
|
192
|
+
await renewT3();
|
|
193
|
+
let running = 0;
|
|
194
|
+
try {
|
|
195
|
+
running = (await driver.listThreads({ scope: "unsettled", limit: 1 })).running;
|
|
196
|
+
} catch (err) {
|
|
197
|
+
log(`${driver.name} unreachable: ${err instanceof Error ? err.message : String(err)}`);
|
|
198
|
+
}
|
|
199
|
+
socket.sendPresence({
|
|
200
|
+
session_key: sessionKey,
|
|
201
|
+
name: driver.name === "t3" ? "Cloop box" : "Cloop runner",
|
|
202
|
+
kind: "workstation",
|
|
203
|
+
capabilities: [...driver.capabilities],
|
|
204
|
+
platform: "workstation",
|
|
205
|
+
machine,
|
|
206
|
+
surface: {},
|
|
207
|
+
status: running > 0 ? "active" : "idle",
|
|
208
|
+
event: running > 0 ? `${running} running` : ""
|
|
209
|
+
});
|
|
210
|
+
};
|
|
211
|
+
void beat();
|
|
212
|
+
setInterval(() => void beat(), BEAT_MS);
|
|
213
|
+
const stop = (code = 0) => {
|
|
214
|
+
log("stopping");
|
|
215
|
+
watch.stop();
|
|
216
|
+
if (driver instanceof LocalDriver) driver.stop();
|
|
217
|
+
lock.release();
|
|
218
|
+
socket.close();
|
|
219
|
+
process.exit(code);
|
|
220
|
+
};
|
|
221
|
+
process.on("SIGINT", () => stop());
|
|
222
|
+
process.on("SIGTERM", () => stop());
|
|
223
|
+
await new Promise(() => {
|
|
224
|
+
});
|
|
225
|
+
}
|
|
226
|
+
async function boxCommand(argv) {
|
|
227
|
+
switch (argv[0]) {
|
|
228
|
+
case "connect":
|
|
229
|
+
await connectCommand(["--driver", "t3", ...argv.slice(1)]);
|
|
230
|
+
break;
|
|
231
|
+
case "run":
|
|
232
|
+
await run();
|
|
233
|
+
break;
|
|
234
|
+
default:
|
|
235
|
+
console.error(
|
|
236
|
+
"Usage: cloop box connect [--t3-url <url>] [--t3-bin <path>] [--no-service] | cloop box run"
|
|
237
|
+
);
|
|
238
|
+
process.exit(1);
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
export {
|
|
242
|
+
REFUSED_LINE,
|
|
243
|
+
awaitNewDeviceToken,
|
|
244
|
+
boxCommand,
|
|
245
|
+
recordConnected,
|
|
246
|
+
run
|
|
247
|
+
};
|