@shayne/openclaw-temporal-halo 0.1.0 → 0.1.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 +34 -26
- package/dream.ts +25 -9
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,51 +2,42 @@
|
|
|
2
2
|
|
|
3
3
|
Temporal Halo is an OpenClaw plugin that maintains a living markdown document (`HALO.md`) describing the user’s recent past, present, and future. The plugin injects `HALO.md` into every agent turn and provides a scheduled “dream” flow to keep it up to date.
|
|
4
4
|
|
|
5
|
-
This plugin is intentionally tool/skill agnostic.
|
|
5
|
+
This plugin is intentionally tool/skill agnostic: it does not hardcode email/calendar/chat APIs. Instead, the dream step tells the agent what to look for (calendar, email, messages, etc.) and the agent chooses from whatever skills/tools you have installed and authorized.
|
|
6
6
|
|
|
7
7
|
## What You Get
|
|
8
8
|
|
|
9
|
-
- Always-on context injection
|
|
10
|
-
- `HALO.md` is prepended
|
|
11
|
-
- Dream mode (cron-triggered)
|
|
12
|
-
-
|
|
13
|
-
-
|
|
9
|
+
- Always-on context injection
|
|
10
|
+
- `HALO.md` is prepended to every agent turn (high convenience, higher privacy risk).
|
|
11
|
+
- Dream mode (cron-triggered, agent-driven)
|
|
12
|
+
- Runs periodically (recommended: every 30 minutes)
|
|
13
|
+
- Refreshes `HALO.md` by pulling from your connected digital life sources (calendar/email/messages/etc.)
|
|
14
14
|
- Size guardrails
|
|
15
15
|
- `HALO.md` budget: 25,000 chars
|
|
16
16
|
- If a dream draft is >25k on first publish attempt, the agent is instructed to compact to <=20k and retry.
|
|
17
17
|
- If it’s still >25k on the second attempt, the plugin warns the user (system event) and does not write an oversized file.
|
|
18
18
|
|
|
19
|
-
## Install
|
|
19
|
+
## Install
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
From npm (recommended):
|
|
22
22
|
|
|
23
23
|
```bash
|
|
24
|
-
openclaw plugins install -
|
|
24
|
+
openclaw plugins install @shayne/openclaw-temporal-halo
|
|
25
25
|
openclaw plugins enable openclaw-temporal-halo
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
From a local checkout (development):
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
openclaw plugins info openclaw-temporal-halo
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
## Install (Remote / Server)
|
|
35
|
-
|
|
36
|
-
Recommended (after this package is published to npm):
|
|
30
|
+
Link-install the plugin (no copy) so edits take effect immediately:
|
|
37
31
|
|
|
38
32
|
```bash
|
|
39
|
-
openclaw plugins install
|
|
33
|
+
openclaw plugins install -l .
|
|
40
34
|
openclaw plugins enable openclaw-temporal-halo
|
|
41
35
|
```
|
|
42
36
|
|
|
43
|
-
|
|
37
|
+
Verify it loaded:
|
|
44
38
|
|
|
45
39
|
```bash
|
|
46
|
-
|
|
47
|
-
cd openclaw-temporal-halo
|
|
48
|
-
openclaw plugins install -l .
|
|
49
|
-
openclaw plugins enable openclaw-temporal-halo
|
|
40
|
+
openclaw plugins info openclaw-temporal-halo
|
|
50
41
|
```
|
|
51
42
|
|
|
52
43
|
## Configure
|
|
@@ -79,7 +70,7 @@ Example:
|
|
|
79
70
|
|
|
80
71
|
Temporal Halo uses OpenClaw’s built-in cron scheduler (no OS cron).
|
|
81
72
|
|
|
82
|
-
Create a repeating isolated job (every 30 minutes)
|
|
73
|
+
Create a repeating isolated job (every 30 minutes). Keep the cron message short: the plugin injects the detailed dream instructions automatically.
|
|
83
74
|
|
|
84
75
|
```bash
|
|
85
76
|
openclaw cron add \
|
|
@@ -87,16 +78,25 @@ openclaw cron add \
|
|
|
87
78
|
--every "30m" \
|
|
88
79
|
--session isolated \
|
|
89
80
|
--no-deliver \
|
|
90
|
-
--message "[temporal-halo:dream]
|
|
81
|
+
--message "[temporal-halo:dream] Refresh HALO.md and publish via temporal_halo_publish."
|
|
91
82
|
```
|
|
92
83
|
|
|
93
84
|
Run it once to test:
|
|
94
85
|
|
|
95
86
|
```bash
|
|
96
87
|
openclaw cron list
|
|
97
|
-
openclaw cron run <job-id>
|
|
88
|
+
openclaw cron run <job-id> --timeout 300000
|
|
98
89
|
```
|
|
99
90
|
|
|
91
|
+
## Connect Your Sources (Calendar/Email/Messages)
|
|
92
|
+
|
|
93
|
+
If your `HALO.md` contains mostly meta and not real-world context, the dream run probably could not access calendar/email/messages.
|
|
94
|
+
|
|
95
|
+
- See what skills are available and eligible:
|
|
96
|
+
- `openclaw skills list --eligible --verbose`
|
|
97
|
+
- Make sure the relevant skills are installed in the agent workspace and are authorized.
|
|
98
|
+
- If a skill requires interactive auth, run a one-off dream in an interactive session first, then rely on cron.
|
|
99
|
+
|
|
100
100
|
## Tool Allowlists (If You Use Them)
|
|
101
101
|
|
|
102
102
|
If you have a strict tool allowlist configured (global `tools.allow` or per-agent `agents.list[].tools.allow`), make sure you allow either:
|
|
@@ -123,6 +123,14 @@ The dream step maintains a stable schema with:
|
|
|
123
123
|
- Treat this as equivalent to pasting `HALO.md` into every prompt.
|
|
124
124
|
- If you don’t want that, don’t enable this plugin.
|
|
125
125
|
|
|
126
|
+
## Troubleshooting
|
|
127
|
+
|
|
128
|
+
- `openclaw cron run` times out:
|
|
129
|
+
- The CLI default timeout is 30s. Use `--timeout 300000` (or higher).
|
|
130
|
+
- `HALO.md` doesn’t include calendar/email:
|
|
131
|
+
- Check `openclaw skills list --eligible --verbose`.
|
|
132
|
+
- Ensure those skills are installed and authenticated for the agent running the cron job.
|
|
133
|
+
|
|
126
134
|
## Development
|
|
127
135
|
|
|
128
136
|
This repo uses `mise` to manage tooling and tasks.
|
package/dream.ts
CHANGED
|
@@ -4,15 +4,15 @@ export function isDreamPrompt(prompt: string, marker: string): boolean {
|
|
|
4
4
|
return prompt.includes(marker)
|
|
5
5
|
}
|
|
6
6
|
|
|
7
|
-
export function buildHaloUsageInstructions(
|
|
7
|
+
export function buildHaloUsageInstructions(_cfg: TemporalHaloConfig): string {
|
|
8
8
|
return [
|
|
9
9
|
"<temporal-halo:usage>",
|
|
10
10
|
"Use the injected HALO.md below as high-signal temporal context.",
|
|
11
|
+
"HALO.md should primarily contain the user's real-world context (schedule, travel, commitments, key identifiers), not assistant/system meta.",
|
|
11
12
|
"- Prefer HALO.md for disambiguation (recent past / now / upcoming).",
|
|
12
13
|
"- Use Key Identifiers first for concrete values (confirmations, locators, etc.).",
|
|
13
14
|
"- If a needed detail is missing, follow Retrieval Recipes to look it up using available tools/skills.",
|
|
14
15
|
"- Do not hallucinate missing identifiers; retrieve or ask the user.",
|
|
15
|
-
`- HALO path: ${cfg.haloPath}`,
|
|
16
16
|
"</temporal-halo:usage>",
|
|
17
17
|
].join("\n")
|
|
18
18
|
}
|
|
@@ -21,13 +21,27 @@ export function buildDreamInstructions(cfg: TemporalHaloConfig): string {
|
|
|
21
21
|
return [
|
|
22
22
|
"<temporal-halo:dream>",
|
|
23
23
|
"You are in Temporal Halo Dream mode.",
|
|
24
|
-
"Your job: refresh HALO.md by surveying the user’s digital life using whatever tools/skills are available.",
|
|
24
|
+
"Your job: refresh HALO.md with high-signal, real-world context by surveying the user’s digital life using whatever tools/skills are available.",
|
|
25
|
+
"Do NOT fill HALO.md with assistant/system/plugin meta.",
|
|
25
26
|
"",
|
|
26
|
-
"
|
|
27
|
-
"
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
27
|
+
"Priority order (most important first):",
|
|
28
|
+
"1) Calendar/schedule (today, next 14d, next 60d, plus important long-horizon items)",
|
|
29
|
+
"2) Email/receipts (travel, reservations, shipments, invoices, confirmations, time-sensitive threads)",
|
|
30
|
+
"3) Messages/chats (commitments, decisions, open loops)",
|
|
31
|
+
"4) Tasks/docs/notes (if tools exist)",
|
|
32
|
+
"5) Prior OpenClaw sessions (only for user commitments and open loops; do not copy meta logs)",
|
|
33
|
+
"",
|
|
34
|
+
"First step (capability scan):",
|
|
35
|
+
"- Quickly identify which installed tools/skills can read calendar, email, and messages for THIS user.",
|
|
36
|
+
"- If you have multiple choices, prefer the most direct/authoritative sources (calendar API > summaries).",
|
|
37
|
+
"",
|
|
38
|
+
"Hard exclusions (do not write these into HALO.md):",
|
|
39
|
+
"- Cron job ids, session ids/keys, internal file paths/directories, tool allowlist/policy details.",
|
|
40
|
+
"- Self-referential notes about being a bot/agent, or notes about plugin development/runtime debugging.",
|
|
41
|
+
"",
|
|
42
|
+
"If a source is unavailable (missing tool/auth/permissions):",
|
|
43
|
+
"- Add a very small 'Access Gaps' section with 1-3 bullets: what is missing and how the user can connect/authorize it.",
|
|
44
|
+
"- Still write Retrieval Recipes so a future agent (or the user) can fetch the missing details.",
|
|
31
45
|
"",
|
|
32
46
|
"HALO horizons:",
|
|
33
47
|
"- Past: last 14 days",
|
|
@@ -35,10 +49,12 @@ export function buildDreamInstructions(cfg: TemporalHaloConfig): string {
|
|
|
35
49
|
"- Keep long-horizon exceptions if they are significant (e.g. big trip).",
|
|
36
50
|
"",
|
|
37
51
|
"HALO requirements:",
|
|
52
|
+
"- HALO.md should be scannable and packed with real-world facts: dates, times, locations, people, join links, confirmations, tracking ids.",
|
|
38
53
|
"- Use the stable schema: Present / Near Future / Medium Future / Long Horizon / Recent Past.",
|
|
39
54
|
"- Include Retrieval Recipes: how to locate original sources when details are missing.",
|
|
40
55
|
"- Include Key Identifiers with full values when important (sensitive allowed).",
|
|
41
|
-
"-
|
|
56
|
+
"- Prune any assistant/system meta from prior versions of HALO.md; keep only user-relevant content.",
|
|
57
|
+
"- Keep the document compact and scannable (short bullets; no long transcripts).",
|
|
42
58
|
`- Hard max size: ${cfg.maxChars} chars. Aim for <=${cfg.compactTargetChars} chars.`,
|
|
43
59
|
"",
|
|
44
60
|
"Publishing:",
|
package/openclaw.plugin.json
CHANGED