@shayne/openclaw-temporal-halo 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Shayne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,152 @@
+# OpenClaw Temporal Halo
+
+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.
+
+This plugin is intentionally tool/skill agnostic. The dream step tells the agent to look at categories like email, calendar, and prior sessions, and lets the agent decide which installed skills/tools to use.
+
+## What You Get
+
+- Always-on context injection via `before_agent_start`
+  - `HALO.md` is prepended verbatim to every agent turn (high convenience, higher privacy risk).
+- Dream mode (cron-triggered)
+  - Run every 30 minutes in an isolated session
+  - Updates `~/.openclaw/temporal-halo/HALO.md`
+- Size guardrails
+  - `HALO.md` budget: 25,000 chars
+  - If a dream draft is >25k on first publish attempt, the agent is instructed to compact to <=20k and retry.
+  - If it’s still >25k on the second attempt, the plugin warns the user (system event) and does not write an oversized file.
+
+## Install (Dev / Local)
+
+Link-install the plugin (no copy) so edits take effect immediately:
+
+```bash
+openclaw plugins install -l .
+openclaw plugins enable openclaw-temporal-halo
+```
+
+Verify it loaded:
+
+```bash
+openclaw plugins info openclaw-temporal-halo
+```
+
+## Install (Remote / Server)
+
+Recommended (after this package is published to npm):
+
+```bash
+openclaw plugins install @shayne/openclaw-temporal-halo
+openclaw plugins enable openclaw-temporal-halo
+```
+
+Alternative (if you want to run from a git clone on the remote machine):
+
+```bash
+git clone https://github.com/shayne/openclaw-temporal-halo.git
+cd openclaw-temporal-halo
+openclaw plugins install -l .
+openclaw plugins enable openclaw-temporal-halo
+```
+
+## Configure
+
+Plugin config lives under `plugins.entries.openclaw-temporal-halo.config` in your OpenClaw config (typically `~/.openclaw/openclaw.json`).
+
+Example:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "openclaw-temporal-halo": {
+        enabled: true,
+        config: {
+          // default: ~/.openclaw/temporal-halo/HALO.md
+          haloPath: "~/.openclaw/temporal-halo/HALO.md",
+          dreamMarker: "[temporal-halo:dream]",
+          maxChars: 25000,
+          compactTargetChars: 20000,
+          debug: false,
+        },
+      },
+    },
+  },
+}
+```
+
+## Set Up Dreaming (OpenClaw Cron)
+
+Temporal Halo uses OpenClaw’s built-in cron scheduler (no OS cron).
+
+Create a repeating isolated job (every 30 minutes) that is silent by default:
+
+```bash
+openclaw cron add \
+  --name "Temporal Halo: Dream" \
+  --every "30m" \
+  --session isolated \
+  --no-deliver \
+  --message "[temporal-halo:dream] Update HALO.md by reviewing email, calendar, recent chats, and prior OpenClaw sessions. Publish via temporal_halo_publish."
+```
+
+Run it once to test:
+
+```bash
+openclaw cron list
+openclaw cron run <job-id>
+```
+
+## Tool Allowlists (If You Use Them)
+
+If you have a strict tool allowlist configured (global `tools.allow` or per-agent `agents.list[].tools.allow`), make sure you allow either:
+
+- `temporal_halo_publish` (tool name), or
+- `openclaw-temporal-halo` (plugin id), or
+- `group:plugins` (all plugin tools)
+
+## HALO.md Structure (Guideline)
+
+The dream step maintains a stable schema with:
+
+- Present (Now to 24h)
+- Near Future (Next 14d)
+- Medium Future (15–60d)
+- Long Horizon (60d+ important)
+- Recent Past (Last 14d)
+- Retrieval Recipes (tool/skill agnostic pointers)
+- Key Identifiers (full values allowed: confirmations, locators, etc.)
+
+## Security Notes
+
+- `HALO.md` may contain sensitive personal identifiers and is injected into every agent turn.
+- Treat this as equivalent to pasting `HALO.md` into every prompt.
+- If you don’t want that, don’t enable this plugin.
+
+## Development
+
+This repo uses `mise` to manage tooling and tasks.
+
+```bash
+mise install
+mise run lint
+mise run check-types
+mise run test
+```
+
+## Publishing (Maintainers)
+
+Preferred: GitHub Actions Trusted Publishing (OIDC) in `.github/workflows/release.yml`.
+
+- Push a tag `vX.Y.Z` to publish `latest` (the workflow verifies the tag matches `package.json`).
+- Push to `main` to publish a `dev` dist-tag (with an auto-generated dev version).
+
+Manual fallback (publishes from your machine; requires `npm login` and publish rights):
+
+```bash
+mise run publish-npm
+```
+
+## License
+
+MIT. See `LICENSE`.

package/config.ts

@@ -0,0 +1,101 @@
+import os from "node:os"
+import path from "node:path"
+
+export type TemporalHaloConfig = {
+	enabled: boolean
+	haloPath: string
+	dreamMarker: string
+	maxChars: number
+	compactTargetChars: number
+	debug: boolean
+}
+
+const ALLOWED_KEYS = [
+	"enabled",
+	"haloPath",
+	"dreamMarker",
+	"maxChars",
+	"compactTargetChars",
+	"debug",
+]
+
+function assertAllowedKeys(
+	value: Record<string, unknown>,
+	allowed: string[],
+	label: string,
+): void {
+	const unknown = Object.keys(value).filter((k) => !allowed.includes(k))
+	if (unknown.length > 0) {
+		throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`)
+	}
+}
+
+function resolveEnvVars(value: string): string {
+	return value.replace(/\$\{([^}]+)\}/g, (_, envVar: string) => {
+		const envValue = process.env[envVar]
+		if (!envValue) {
+			throw new Error(`Environment variable ${envVar} is not set`)
+		}
+		return envValue
+	})
+}
+
+function expandTilde(p: string): string {
+	const trimmed = p.trim()
+	if (trimmed === "~") return os.homedir()
+	if (trimmed.startsWith("~/")) return path.join(os.homedir(), trimmed.slice(2))
+	return trimmed
+}
+
+function defaultHaloPath(): string {
+	return path.join(os.homedir(), ".openclaw", "temporal-halo", "HALO.md")
+}
+
+export function parseConfig(raw: unknown): TemporalHaloConfig {
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {}
+
+	if (Object.keys(cfg).length > 0) {
+		assertAllowedKeys(cfg, ALLOWED_KEYS, "temporal-halo config")
+	}
+
+	const enabled = typeof cfg.enabled === "boolean" ? cfg.enabled : true
+	const haloPathRaw =
+		typeof cfg.haloPath === "string" && cfg.haloPath.trim()
+			? resolveEnvVars(cfg.haloPath)
+			: defaultHaloPath()
+
+	const maxChars =
+		typeof cfg.maxChars === "number" && Number.isFinite(cfg.maxChars)
+			? Math.trunc(cfg.maxChars)
+			: 25_000
+	const compactTargetChars =
+		typeof cfg.compactTargetChars === "number" &&
+		Number.isFinite(cfg.compactTargetChars)
+			? Math.trunc(cfg.compactTargetChars)
+			: 20_000
+
+	if (compactTargetChars > maxChars) {
+		throw new Error(
+			`temporal-halo: compactTargetChars (${compactTargetChars}) must be <= maxChars (${maxChars})`,
+		)
+	}
+
+	return {
+		enabled,
+		haloPath: path.resolve(expandTilde(haloPathRaw)),
+		dreamMarker:
+			typeof cfg.dreamMarker === "string" && cfg.dreamMarker.trim()
+				? cfg.dreamMarker.trim()
+				: "[temporal-halo:dream]",
+		maxChars,
+		compactTargetChars,
+		debug: typeof cfg.debug === "boolean" ? cfg.debug : false,
+	}
+}
+
+export const temporalHaloConfigSchema = {
+	parse: parseConfig,
+}

package/dream.ts

@@ -0,0 +1,73 @@
+import type { TemporalHaloConfig } from "./config.ts"
+
+export function isDreamPrompt(prompt: string, marker: string): boolean {
+	return prompt.includes(marker)
+}
+
+export function buildHaloUsageInstructions(cfg: TemporalHaloConfig): string {
+	return [
+		"<temporal-halo:usage>",
+		"Use the injected HALO.md below as high-signal temporal context.",
+		"- Prefer HALO.md for disambiguation (recent past / now / upcoming).",
+		"- Use Key Identifiers first for concrete values (confirmations, locators, etc.).",
+		"- If a needed detail is missing, follow Retrieval Recipes to look it up using available tools/skills.",
+		"- Do not hallucinate missing identifiers; retrieve or ask the user.",
+		`- HALO path: ${cfg.haloPath}`,
+		"</temporal-halo:usage>",
+	].join("\n")
+}
+
+export function buildDreamInstructions(cfg: TemporalHaloConfig): string {
+	return [
+		"<temporal-halo:dream>",
+		"You are in Temporal Halo Dream mode.",
+		"Your job: refresh HALO.md by surveying the user’s digital life using whatever tools/skills are available.",
+		"",
+		"Sources to consider (tool/skill agnostic):",
+		"- Email: confirmations, threads needing replies, travel receipts, shipments, key plans.",
+		"- Calendar: today/tomorrow, next 14d, next 60d, and major long-horizon items.",
+		"- Recent chats/messages: commitments, asks, decisions, open loops.",
+		"- Prior OpenClaw sessions: what the user was doing, promised follow-ups, recent context.",
+		"",
+		"HALO horizons:",
+		"- Past: last 14 days",
+		"- Future: next 60 days",
+		"- Keep long-horizon exceptions if they are significant (e.g. big trip).",
+		"",
+		"HALO requirements:",
+		"- Use the stable schema: Present / Near Future / Medium Future / Long Horizon / Recent Past.",
+		"- Include Retrieval Recipes: how to locate original sources when details are missing.",
+		"- Include Key Identifiers with full values when important (sensitive allowed).",
+		"- Keep the document compact and scannable.",
+		`- Hard max size: ${cfg.maxChars} chars. Aim for <=${cfg.compactTargetChars} chars.`,
+		"",
+		"Publishing:",
+		"- When you have the updated markdown for the entire file, call the tool `temporal_halo_publish` with the full markdown.",
+		`- If the tool reports the content is oversize, compact to <=${cfg.compactTargetChars} chars and call the tool again exactly once.`,
+		"- If the second publish attempt is still oversize, stop; a warning will be sent to the user and HALO.md will remain unchanged.",
+		"</temporal-halo:dream>",
+	].join("\n")
+}
+
+export function buildHaloBlock(params: {
+	haloPath: string
+	haloText: string | null
+}): string {
+	if (!params.haloText?.trim()) {
+		return [
+			"<temporal-halo:file>",
+			`HALO.md not found (yet): ${params.haloPath}`,
+			"To create/update it, run the Temporal Halo dream cron job.",
+			"</temporal-halo:file>",
+		].join("\n")
+	}
+
+	return [
+		"<temporal-halo:file>",
+		`Path: ${params.haloPath}`,
+		"----- HALO.md BEGIN -----",
+		params.haloText.trimEnd(),
+		"----- HALO.md END -----",
+		"</temporal-halo:file>",
+	].join("\n")
+}

package/halo.ts

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto"
+import fs from "node:fs/promises"
+import path from "node:path"
+
+export async function readHaloFile(filePath: string): Promise<string | null> {
+	try {
+		return await fs.readFile(filePath, "utf-8")
+	} catch (err) {
+		const code = (err as { code?: unknown } | null)?.code
+		if (code === "ENOENT" || code === "ENOTDIR") {
+			return null
+		}
+		throw err
+	}
+}
+
+async function renameOverwriting(
+	tmpPath: string,
+	destPath: string,
+): Promise<void> {
+	try {
+		await fs.rename(tmpPath, destPath)
+		return
+	} catch (err) {
+		// On some platforms, rename won't overwrite an existing destination.
+		const code = (err as { code?: unknown } | null)?.code
+		if (code === "EEXIST" || code === "EPERM" || code === "EACCES") {
+			await fs.rm(destPath, { force: true })
+			await fs.rename(tmpPath, destPath)
+			return
+		}
+		throw err
+	}
+}
+
+export async function writeHaloAtomic(
+	filePath: string,
+	contents: string,
+): Promise<void> {
+	const dir = path.dirname(filePath)
+	await fs.mkdir(dir, { recursive: true })
+
+	const tmpPath = `${filePath}.tmp-${process.pid}-${randomUUID()}`
+	await fs.writeFile(tmpPath, contents, "utf-8")
+	await renameOverwriting(tmpPath, filePath)
+}

package/index.ts

@@ -0,0 +1,62 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { parseConfig, temporalHaloConfigSchema } from "./config.ts"
+import {
+	buildDreamInstructions,
+	buildHaloBlock,
+	buildHaloUsageInstructions,
+	isDreamPrompt,
+} from "./dream.ts"
+import { readHaloFile } from "./halo.ts"
+import { registerTemporalHaloPublishTool } from "./tools/publish.ts"
+
+export default {
+	id: "openclaw-temporal-halo",
+	name: "Temporal Halo",
+	description: "Always-on temporal HALO.md context + cron-driven dreaming",
+	configSchema: temporalHaloConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		const cfg = parseConfig(api.pluginConfig)
+
+		if (!cfg.enabled) {
+			api.logger.info("temporal-halo: disabled via plugin config")
+			return
+		}
+
+		registerTemporalHaloPublishTool(api, cfg)
+
+		api.on(
+			"before_agent_start",
+			async (event: Record<string, unknown>, ctx: Record<string, unknown>) => {
+				const prompt = typeof event.prompt === "string" ? event.prompt : ""
+				const isDream = isDreamPrompt(prompt, cfg.dreamMarker)
+
+				let haloText: string | null = null
+				try {
+					haloText = await readHaloFile(cfg.haloPath)
+				} catch (err) {
+					api.logger.warn(
+						`temporal-halo: failed reading HALO.md: ${String(err)}`,
+					)
+				}
+
+				const parts: string[] = []
+				parts.push(buildHaloUsageInstructions(cfg))
+				if (isDream) {
+					parts.push(buildDreamInstructions(cfg))
+				}
+				parts.push(buildHaloBlock({ haloPath: cfg.haloPath, haloText }))
+
+				if (cfg.debug) {
+					const sessionKey =
+						typeof ctx.sessionKey === "string" ? ctx.sessionKey : ""
+					api.logger.info(
+						`temporal-halo: injecting HALO context (${haloText?.length ?? 0} chars) sessionKey=${sessionKey}`,
+					)
+				}
+
+				return { prependContext: parts.join("\n\n") }
+			},
+		)
+	},
+}

package/openclaw.plugin.json

@@ -0,0 +1,53 @@
+{
+	"id": "openclaw-temporal-halo",
+	"name": "Temporal Halo",
+	"description": "Always-on temporal HALO.md context + cron-driven dreaming",
+	"version": "0.1.0",
+	"uiHints": {
+		"enabled": {
+			"label": "Enabled",
+			"help": "If false, the plugin will not inject HALO or enable dream helpers."
+		},
+		"haloPath": {
+			"label": "HALO.md Path",
+			"placeholder": "~/.openclaw/temporal-halo/HALO.md",
+			"help": "Global HALO document path. Default: ~/.openclaw/temporal-halo/HALO.md"
+		},
+		"dreamMarker": {
+			"label": "Dream Marker",
+			"placeholder": "[temporal-halo:dream]",
+			"help": "If the agent prompt contains this marker, the plugin injects dream instructions."
+		},
+		"maxChars": {
+			"label": "Max HALO chars",
+			"placeholder": "25000",
+			"help": "Hard cap for HALO.md on disk. Publish attempts above this are rejected."
+		},
+		"compactTargetChars": {
+			"label": "Compaction target chars",
+			"placeholder": "20000",
+			"help": "If a publish attempt is oversize, the agent is instructed to compact to this target."
+		},
+		"debug": {
+			"label": "Debug Logging",
+			"help": "Enable verbose logging"
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"enabled": { "type": "boolean" },
+			"haloPath": { "type": "string" },
+			"dreamMarker": { "type": "string" },
+			"maxChars": { "type": "number", "minimum": 1000, "maximum": 200000 },
+			"compactTargetChars": {
+				"type": "number",
+				"minimum": 1000,
+				"maximum": 200000
+			},
+			"debug": { "type": "boolean" }
+		},
+		"required": []
+	}
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@shayne/openclaw-temporal-halo",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "OpenClaw temporal HALO.md plugin (always-on context + scheduled dreaming)",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/shayne/openclaw-temporal-halo.git"
+	},
+	"bugs": {
+		"url": "https://github.com/shayne/openclaw-temporal-halo/issues"
+	},
+	"homepage": "https://github.com/shayne/openclaw-temporal-halo#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"*.ts",
+		"tools/**/*.ts",
+		"openclaw.plugin.json",
+		"README.md",
+		"LICENSE"
+	],
+	"dependencies": {
+		"@sinclair/typebox": "0.34.47"
+	},
+	"scripts": {
+		"check-types": "bunx tsc --noEmit",
+		"lint": "bunx @biomejs/biome ci .",
+		"lint:fix": "bunx @biomejs/biome check --write .",
+		"test": "bunx vitest run"
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.2.14"
+	},
+	"openclaw": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.8",
+		"@types/node": "^22.13.4",
+		"openclaw": "2026.2.14",
+		"typescript": "^5.9.3",
+		"vitest": "^3.0.6"
+	}
+}

package/tools/publish.ts

@@ -0,0 +1,190 @@
+import { Type } from "@sinclair/typebox"
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { TemporalHaloConfig } from "../config.ts"
+import { writeHaloAtomic } from "../halo.ts"
+
+type RegisteredTool = Parameters<OpenClawPluginApi["registerTool"]>[0]
+type ExtractFn<T> = T extends (...args: infer Args) => infer Result
+	? (...args: Args) => Result
+	: never
+type OpenClawPluginToolFactory = ExtractFn<RegisteredTool>
+
+export type TemporalHaloToolContext = Parameters<OpenClawPluginToolFactory>[0]
+
+function normalizeToken(value: string | undefined | null): string {
+	return (value ?? "").trim().toLowerCase()
+}
+
+function normalizeMainKey(value: string | undefined | null): string {
+	const trimmed = (value ?? "").trim()
+	return trimmed ? trimmed.toLowerCase() : "main"
+}
+
+function normalizeAgentId(value: string | undefined | null): string {
+	const raw = (value ?? "").trim()
+	if (!raw) return "main"
+	const lowered = raw.toLowerCase()
+	const normalized = lowered
+		.replace(/[^a-z0-9_-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+	return normalized.slice(0, 64) || "main"
+}
+
+function resolveAgentIdFromSessionKey(
+	sessionKey: string | undefined | null,
+): string | null {
+	const raw = (sessionKey ?? "").trim()
+	if (!raw) return null
+	const lowered = raw.toLowerCase()
+	if (!lowered.startsWith("agent:")) return null
+	const parts = lowered.split(":")
+	return parts.length >= 2 ? (parts[1] ?? null) : null
+}
+
+export function resolveWarningSessionKey(
+	toolCtx: TemporalHaloToolContext,
+): string | null {
+	const cfg = toolCtx.config as unknown as {
+		session?: { scope?: unknown; mainKey?: unknown }
+	} | null
+
+	if (cfg?.session?.scope === "global") {
+		return "global"
+	}
+
+	const agentId =
+		normalizeToken(toolCtx.agentId) ||
+		normalizeToken(resolveAgentIdFromSessionKey(toolCtx.sessionKey)) ||
+		"main"
+	const mainKey = normalizeMainKey(
+		typeof cfg?.session?.mainKey === "string" ? cfg.session.mainKey : null,
+	)
+
+	return `agent:${normalizeAgentId(agentId)}:${mainKey}`
+}
+
+export function createTemporalHaloPublishTool(params: {
+	api: OpenClawPluginApi
+	cfg: TemporalHaloConfig
+	toolCtx: TemporalHaloToolContext
+}): AnyAgentTool {
+	let oversizeAttempts = 0
+
+	return {
+		name: "temporal_halo_publish",
+		label: "Temporal Halo Publish",
+		description: "Atomically write HALO.md with strict size enforcement.",
+		parameters: Type.Object({
+			markdown: Type.String({
+				description: "Full markdown content for HALO.md",
+			}),
+		}),
+		async execute(_toolCallId: string, args: { markdown: string }) {
+			const markdown = typeof args.markdown === "string" ? args.markdown : ""
+			const trimmed = markdown.trimEnd()
+			if (!trimmed.trim()) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "temporal_halo_publish: markdown required",
+						},
+					],
+					details: { ok: false, error: "markdown_required" },
+				}
+			}
+
+			const chars = trimmed.length
+			if (chars > params.cfg.maxChars) {
+				oversizeAttempts += 1
+				if (oversizeAttempts === 1) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text:
+									`HALO draft is ${chars} chars (max ${params.cfg.maxChars}). ` +
+									`Compact it to <=${params.cfg.compactTargetChars} chars and call temporal_halo_publish again.`,
+							},
+						],
+						details: {
+							ok: false,
+							published: false,
+							error: "oversize",
+							chars,
+							maxChars: params.cfg.maxChars,
+							next: "compact_and_retry",
+							targetChars: params.cfg.compactTargetChars,
+							attempt: oversizeAttempts,
+						},
+					}
+				}
+
+				const warnKey =
+					resolveWarningSessionKey(params.toolCtx) ??
+					(params.toolCtx.sessionKey ? params.toolCtx.sessionKey : null)
+				if (warnKey) {
+					try {
+						params.api.runtime.system.enqueueSystemEvent(
+							`Temporal Halo warning: HALO publish still oversize (${chars} chars) after compaction attempt. HALO.md was not updated.`,
+							{ sessionKey: warnKey, contextKey: "temporal-halo" },
+						)
+					} catch (err) {
+						params.api.logger.warn(
+							`temporal-halo: failed to enqueue warning system event: ${String(err)}`,
+						)
+					}
+				}
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text:
+								`HALO draft is still ${chars} chars (max ${params.cfg.maxChars}). ` +
+								"Warning sent. HALO.md was not updated.",
+						},
+					],
+					details: {
+						ok: false,
+						published: false,
+						error: "oversize_after_retry",
+						chars,
+						maxChars: params.cfg.maxChars,
+						attempt: oversizeAttempts,
+						warned: Boolean(warnKey),
+					},
+				}
+			}
+
+			await writeHaloAtomic(params.cfg.haloPath, trimmed)
+			oversizeAttempts = 0
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `Published HALO.md (${chars} chars) to ${params.cfg.haloPath}`,
+					},
+				],
+				details: {
+					ok: true,
+					published: true,
+					path: params.cfg.haloPath,
+					chars,
+				},
+			}
+		},
+	}
+}
+
+export function registerTemporalHaloPublishTool(
+	api: OpenClawPluginApi,
+	cfg: TemporalHaloConfig,
+) {
+	api.registerTool(
+		(toolCtx: TemporalHaloToolContext) =>
+			createTemporalHaloPublishTool({ api, cfg, toolCtx }),
+		{ name: "temporal_halo_publish" },
+	)
+}