@kagura-agent/atlas-openclaw 0.1.3 → 0.1.5
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 +9 -5
- package/index.mjs +15 -4
- package/package.json +1 -1
- package/worker.mjs +29 -15
package/README.md
CHANGED
|
@@ -14,6 +14,8 @@ In Atlas, choose **Connect AI tools → OpenClaw** from the account menu. The st
|
|
|
14
14
|
|
|
15
15
|
Each connection has its own account key, Atlas address, token and agent. Channel-level settings supply shared defaults; an account can override them. A channel-level token represents the default account. `enabled: false` on the channel stops every account; on an account it stops only that connection. Multiple accounts require plugin 0.1.3 or later. To upgrade, run `openclaw plugins install --force --accept-capabilities @kagura-agent/atlas-openclaw`.
|
|
16
16
|
|
|
17
|
+
Add `atlas_board` to `tools.alsoAllow`, preserving existing entries. Atlas includes this permission in the generated configuration. Loading the plugin and connecting the channel do not grant an agent permission to use its tools: a profile such as `coding` with an existing additive allowlist can otherwise reject every Atlas turn before the model runs. The tool is available only with an Atlas task binding; allowing it does not grant arbitrary board access. Explicit deny rules still apply.
|
|
18
|
+
|
|
17
19
|
Restart the OpenClaw gateway after installation. Atlas shows **Connected** when the authenticated socket connects. Select the connection and send a message.
|
|
18
20
|
|
|
19
21
|
Use the public HTTPS Atlas origin when OpenClaw runs on another machine. Forward `/agent-worker` with WebSocket upgrades and `/api/agent-worker/` to the same Atlas server. Loopback HTTP is supported for local development and SSH tunnels.
|
|
@@ -44,13 +46,15 @@ Increase the committed package version before another release. An existing versi
|
|
|
44
46
|
|
|
45
47
|
WebSocket notifications wake the worker; reconnecting and periodic server notifications refresh the durable queue. If no server notification or ping arrives for 45 seconds, the plugin closes the stale socket and reconnects, including when a sleeping computer leaves TCP apparently open. Repeated disconnects use exponential backoff with jitter, resetting after a stable connection. Authentication rejection ends the account lifecycle with a configuration error. Creating credentials alone never marks an Atlas connection online.
|
|
46
48
|
|
|
47
|
-
Each account runs at most four tasks. Finishing a run checks for queued work; a stop notification bypasses capacity and aborts the requested run immediately. Queue fetches, tools and previews share cancellation signals.
|
|
49
|
+
Each account runs at most four tasks. Finishing a run checks for queued work; a stop notification bypasses capacity and aborts the requested run immediately. Queue fetches, tools and previews share cancellation signals. Overlapping periodic heartbeat ticks share one renewal. Short renewable run leases prevent a lost worker from silently reexecuting work. Claiming is deliberately not retried after an ambiguous failure: without a confirmed lease, the model must not start. The lease expires and Atlas records the interruption.
|
|
48
50
|
|
|
49
51
|
Reads, heartbeat renewals and writes protected by server receipts retry transient network/5xx failures. Rate limits respect Retry-After within a bounded deadline. Authentication, validation and conflict errors are not retried. Tool writes reuse the same request ID; canvas changes, run updates and receipts commit in the same SQLite transaction. Final settlement is also idempotent and can finish after model cancellation. Exhausted final delivery retries remain an error, never a successful delivery.
|
|
50
52
|
|
|
51
53
|
Streaming previews coalesce, serialize and stop before final settlement. A preview failure does not prevent later updates or the final response. Final delivery seals the draft; callbacks arriving after cancellation or dispatcher completion cannot alter it.
|
|
52
54
|
|
|
53
|
-
Each turn gets a fresh OpenClaw session with Atlas's completed conversation history. Cancelled and failed prompts are excluded so runtime transcript replay cannot revive them.
|
|
55
|
+
Each turn gets a fresh OpenClaw session with Atlas's completed conversation history. Cancelled and failed prompts are excluded so runtime transcript replay cannot revive them. Atlas preserves OpenClaw's configured tool policy, including terminal and file tools, explicit denials, sandboxing and approval requirements. The additional `atlas_board` tool exists only for its bound task and cannot choose another board or acquire a new scope. Atlas content must be accessed through that scoped tool; unrelated tasks use the agent's other configured tools. Stop aborts the dispatcher; only after it returns does the plugin report settlement. OpenClaw error payloads are failures, not successful replies.
|
|
56
|
+
|
|
57
|
+
Tool discovery can load the plugin separately from its channel worker. Run authority therefore travels through OpenClaw's native tool binding, rather than a process-global session map. The binding is separate from model input; credentials come from the selected account's host configuration. The host checks invocation lifetime, and Atlas validates the lease and canvas scope on every request.
|
|
54
58
|
|
|
55
59
|
Maintainer source (repository access required): [Channel registration](https://github.com/kagura-chen/atlas/blob/main/plugins/openclaw-atlas/index.mjs) · [Worker and scoped tool](https://github.com/kagura-chen/atlas/blob/main/plugins/openclaw-atlas/worker.mjs) · [Manifest](https://github.com/kagura-chen/atlas/blob/main/plugins/openclaw-atlas/openclaw.plugin.json) · [Atlas service](https://github.com/kagura-chen/atlas/blob/main/server/agent-chat.ts) · [Scope validation](https://github.com/kagura-chen/atlas/blob/main/server/agent-scope.ts) · [HTTP and gateway](https://github.com/kagura-chen/atlas/blob/main/server/agent-chat-api.ts).
|
|
56
60
|
|
|
@@ -66,7 +70,7 @@ This comparison uses static source at Cove commit `3de8390882e8b0170b493d4f81001
|
|
|
66
70
|
| HTTP delivery | [REST client](https://github.com/kagura-chen/cove/blob/3de8390882e8b0170b493d4f81001b498a78cdc1/packages/plugin/src/rest-client.ts) distinguishes safe retries and rate limits | Decide retry safety by Atlas receipts, preserve status on non-JSON errors and cancel outstanding I/O |
|
|
67
71
|
| Queue and stop | Cove serializes by conversation and dispatches control messages immediately after authorization | Atlas enforces one active turn per conversation on the server; authenticated stop notifications bypass worker capacity |
|
|
68
72
|
| Draft and final reply | [dispatch](https://github.com/kagura-chen/cove/blob/3de8390882e8b0170b493d4f81001b498a78cdc1/packages/plugin/src/dispatch.ts) seals drafts and guards callbacks; [outbound](https://github.com/kagura-chen/cove/blob/3de8390882e8b0170b493d4f81001b498a78cdc1/packages/plugin/src/outbound.ts) requires delivery confirmation | Separate best-effort previews from the durable finish receipt; await writes before settlement |
|
|
69
|
-
| Authorization and sessions | Cove admits channel messages before enrichment and uses canonical thread sessions | Atlas checks worker and board permissions before claim; fresh sessions use completed Atlas history and
|
|
70
|
-
| Platform features | Cove has group policy, commands, reactions, recurring tasks, media delivery, child-run hooks and usage collection |
|
|
73
|
+
| Authorization and sessions | Cove admits channel messages before enrichment and uses canonical thread sessions | Atlas checks worker and board permissions before claim; fresh sessions use completed Atlas history, the host's tool policy and a scoped board tool |
|
|
74
|
+
| Platform features | Cove has group policy, commands, reactions, recurring tasks, media delivery, child-run hooks and usage collection | Atlas does not mirror Cove's group UI, media rendering, child-run progress or cost accounting. Tool availability remains the OpenClaw operator's policy |
|
|
71
75
|
|
|
72
|
-
The supported OpenClaw SDK requires `contracts.tools` in the manifest. Atlas uses its buffered reply dispatcher; Cove's `runInboundReplyTurn` wrapper is not exported by the minimum supported host. Package verification checks installation and account resolution on both the minimum and latest OpenClaw versions. Failure regressions live in [channel tests](https://github.com/kagura-chen/atlas/blob/main/tests/openclaw-channel.test.ts).
|
|
76
|
+
The supported OpenClaw SDK requires `contracts.tools` in the manifest. Atlas uses its buffered reply dispatcher; Cove's `runInboundReplyTurn` wrapper is not exported by the minimum supported host. Package verification checks installation and account resolution, then starts a real gateway against an isolated Atlas fixture and deterministic model. It must execute a terminal command, preserve an explicit tool denial, read the board and deliver the final reply on both the minimum and latest OpenClaw versions. Failure regressions live in [channel tests](https://github.com/kagura-chen/atlas/blob/main/tests/openclaw-channel.test.ts).
|
package/index.mjs
CHANGED
|
@@ -2,7 +2,7 @@ import {
|
|
|
2
2
|
createChatChannelPlugin,
|
|
3
3
|
defineChannelPluginEntry,
|
|
4
4
|
} from "openclaw/plugin-sdk/channel-core";
|
|
5
|
-
import { boardTool, startAccount } from "./worker.mjs";
|
|
5
|
+
import { boardTool, client, startAccount } from "./worker.mjs";
|
|
6
6
|
import { accountConfig } from "./accounts.mjs";
|
|
7
7
|
|
|
8
8
|
const plugin = createChatChannelPlugin({
|
|
@@ -27,7 +27,18 @@ export default defineChannelPluginEntry({
|
|
|
27
27
|
description: "External agents with scoped canvas tools",
|
|
28
28
|
plugin,
|
|
29
29
|
registerFull: (api) =>
|
|
30
|
-
api.registerTool(
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
api.registerTool(
|
|
31
|
+
(context) => {
|
|
32
|
+
const binding = context.toolBindings?.atlas;
|
|
33
|
+
if (!binding || binding.sessionKey !== context.sessionKey) return null;
|
|
34
|
+
const account = accountConfig.resolveAccount(
|
|
35
|
+
context.runtimeConfig ?? context.config,
|
|
36
|
+
binding.accountId,
|
|
37
|
+
);
|
|
38
|
+
return boardTool(context, client(account));
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
names: ["atlas_board"],
|
|
42
|
+
},
|
|
43
|
+
),
|
|
33
44
|
});
|
package/package.json
CHANGED
package/worker.mjs
CHANGED
|
@@ -4,8 +4,6 @@ import { setTimeout as sleep } from "node:timers/promises";
|
|
|
4
4
|
import WebSocket from "ws";
|
|
5
5
|
import { createClient, requestWithRetry } from "./transport.mjs";
|
|
6
6
|
|
|
7
|
-
const sessionRegistry = Symbol.for("atlas.openclaw.active-runs");
|
|
8
|
-
export const sessions = (globalThis[sessionRegistry] ||= new Map());
|
|
9
7
|
export function connection(account) {
|
|
10
8
|
const base = new URL(account.baseUrl);
|
|
11
9
|
if (
|
|
@@ -37,9 +35,9 @@ export function client(account) {
|
|
|
37
35
|
return createClient(connection(account), account.token);
|
|
38
36
|
}
|
|
39
37
|
|
|
40
|
-
export function boardTool(context) {
|
|
41
|
-
const
|
|
42
|
-
if (!
|
|
38
|
+
export function boardTool(context, request) {
|
|
39
|
+
const binding = context.toolBindings?.atlas;
|
|
40
|
+
if (!binding || binding.sessionKey !== context.sessionKey) return null;
|
|
43
41
|
return {
|
|
44
42
|
name: "atlas_board",
|
|
45
43
|
label: "Atlas board",
|
|
@@ -62,16 +60,25 @@ export function boardTool(context) {
|
|
|
62
60
|
options: { type: "array", items: { type: "string" }, maxItems: 6 },
|
|
63
61
|
},
|
|
64
62
|
},
|
|
65
|
-
async execute(callId, args) {
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
63
|
+
async execute(callId, args, signal) {
|
|
64
|
+
const post = (action, body) =>
|
|
65
|
+
requestWithRetry(
|
|
66
|
+
(path, payload, options) => {
|
|
67
|
+
context.assertInvocationCurrent?.();
|
|
68
|
+
return request(path, payload, options);
|
|
69
|
+
},
|
|
70
|
+
`runs/${encodeURIComponent(binding.runId)}/${action}`,
|
|
71
|
+
{ ...body, lease: binding.lease },
|
|
72
|
+
{ signal, idempotent: true },
|
|
73
|
+
);
|
|
69
74
|
const requestId = `tool:${callId}`;
|
|
70
|
-
const result = await
|
|
75
|
+
const result = await post("tool", { ...args, requestId });
|
|
71
76
|
if (args.action === "ask") {
|
|
72
77
|
for (;;) {
|
|
73
|
-
await sleep(1000, undefined, { signal
|
|
74
|
-
const state = await
|
|
78
|
+
await sleep(1000, undefined, { signal });
|
|
79
|
+
const state = await post("heartbeat", {});
|
|
80
|
+
if (state.status === "cancelling")
|
|
81
|
+
throw new Error("Stopped by the user");
|
|
75
82
|
if (
|
|
76
83
|
state.question?.id === result.questionId &&
|
|
77
84
|
state.question.answer !== undefined
|
|
@@ -142,7 +149,6 @@ export async function executeRun(ctx, request, id) {
|
|
|
142
149
|
throw e;
|
|
143
150
|
}
|
|
144
151
|
};
|
|
145
|
-
sessions.set(sessionKey, { post, controller, heartbeat });
|
|
146
152
|
const timer = setInterval(() => {
|
|
147
153
|
void heartbeat().catch(() => {});
|
|
148
154
|
}, 10000);
|
|
@@ -199,6 +205,16 @@ export async function executeRun(ctx, request, id) {
|
|
|
199
205
|
ChatType: "direct",
|
|
200
206
|
SenderId: job.run.conversationId,
|
|
201
207
|
CommandAuthorized: false,
|
|
208
|
+
// The host carries this binding into tool discovery, including cold-loaded registries.
|
|
209
|
+
// It is not model input; the server still validates the lease and canvas scope.
|
|
210
|
+
GatewayRunToolBindings: {
|
|
211
|
+
atlas: {
|
|
212
|
+
runId: id,
|
|
213
|
+
lease: job.lease,
|
|
214
|
+
sessionKey,
|
|
215
|
+
accountId: ctx.accountId,
|
|
216
|
+
},
|
|
217
|
+
},
|
|
202
218
|
};
|
|
203
219
|
try {
|
|
204
220
|
controller.signal.throwIfAborted();
|
|
@@ -227,7 +243,6 @@ export async function executeRun(ctx, request, id) {
|
|
|
227
243
|
},
|
|
228
244
|
replyOptions: {
|
|
229
245
|
abortSignal: controller.signal,
|
|
230
|
-
toolsAllow: ["atlas_board"],
|
|
231
246
|
suppressDefaultToolProgressMessages: true,
|
|
232
247
|
onAgentRunTerminalOutcome: (outcome) => {
|
|
233
248
|
if (active() && outcome === "failed")
|
|
@@ -253,7 +268,6 @@ export async function executeRun(ctx, request, id) {
|
|
|
253
268
|
} finally {
|
|
254
269
|
closed = true;
|
|
255
270
|
pendingPreview = undefined;
|
|
256
|
-
sessions.delete(sessionKey);
|
|
257
271
|
// Drain in-flight presentation writes before committing the terminal receipt.
|
|
258
272
|
await progress;
|
|
259
273
|
clearInterval(timer);
|