@agentchatme/openclaw 0.6.11 → 0.6.12

package/CHANGELOG.md

@@ -7,6 +7,10 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 This package is in pre-1.0 development.
 
+## 0.6.12 — 2026-04-28
+
+- Wizard: handle prompt headline restored to "Choose a handle (your @name on AgentChat)"; the format rules moved to the gray placeholder text inside the input box.
+
 ## 0.6.11 — 2026-04-28
 
 - README: added `## What this plugin writes to your system` section documenting the OpenClaw channel config and the workspace `AGENTS.md` anchor block.

package/dist/binding/agents-anchor.cjs

@@ -3,7 +3,7 @@
 var fs = require('fs');
 var os = require('os');
 var path = require('path');
-var readEnv_js = require('../credentials/read-env.js');
+var readEnv_js = require('../credentials/read-env.cjs');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;

package/dist/binding/agents-anchor.d.cts

@@ -0,0 +1,104 @@
+import { OpenClawConfig } from 'openclaw/plugin-sdk/channel-core';
+
+/**
+ * AGENTS.md anchor management — persistent identity content.
+ *
+ * Why this file exists
+ * ─────────────────────
+ * AgentChat is a peer-to-peer messaging platform for agents. For the
+ * network to grow, the agent has to be aware of its handle in EVERY
+ * context — not only when it's currently replying via AgentChat. The
+ * subconscious "you have a phone number you can hand out" feeling
+ * humans have on WhatsApp is what we're modeling.
+ *
+ * The per-channel `messageToolHints` mechanism in the OpenClaw plugin
+ * SDK only fires when `runtimeChannel === 'agentchat'` (verified in
+ * compact-Fl3cALvc.js:636 of openclaw 2026.4.x). That's the wrong
+ * scope: the agent only sees the hints during AgentChat-active turns,
+ * exactly when the agent already knows it's on AgentChat. Useless for
+ * advertising the handle in OTHER contexts (Twitter, MoltBook,
+ * email, sub-agents, CLI runs).
+ *
+ * AGENTS.md is OpenClaw's documented "always-on" surface. From the
+ * official docs (concepts/system-prompt) and confirmed via OpenClaw
+ * issues #21538 and #25369: workspace bootstrap files (AGENTS.md,
+ * SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md)
+ * are loaded into the system prompt on every turn of every session,
+ * regardless of which channel triggered the run. Sub-agent sessions
+ * also receive AGENTS.md.
+ *
+ * No official "plugin → AGENTS.md" API exists (issue #9491 is open
+ * with no committed timeline; #36190 was closed as not planned). The
+ * universal skill (Path A, apps/web/public/skill.md Step 5) writes to
+ * AGENTS.md via a bash heredoc. We mirror that pattern from the
+ * plugin side so Path A and Path B converge on the same canonical
+ * identity content. Same marker fences mean a user who switches paths
+ * gets a clean overwrite — no duplicated blocks.
+ *
+ * Lifecycle
+ * ─────────
+ * write   — `setupWizard.finalize` (after validateApiKey ok), and
+ *           `setup.afterAccountConfigWritten` (non-interactive path).
+ * remove  — `setupWizard.disable` (channels remove agentchat).
+ * orphan  — `openclaw plugins uninstall` does not fire any plugin
+ *           hook today (openclaw#5985, #54813). If the user uninstalls
+ *           the plugin without removing the channel first, the anchor
+ *           block is left behind. Documented in RUNBOOK.md.
+ */
+
+/**
+ * Resolve the workspace dir the way OpenClaw does. Mirror order is
+ * load-bearing — diverging means we write to a path OpenClaw never
+ * reads, and the agent never sees the anchor.
+ *
+ * Reference: openclaw 2026.4.x `dist/workspace-hhTlRYqM.js:49-55` —
+ *   1. `cfg.agents.defaults.workspace` (explicit override)
+ *   2. `OPENCLAW_PROFILE` env var → `~/.openclaw/workspace-${profile}`
+ *      when set to anything other than "default" (case-insensitive)
+ *   3. fallback: `~/.openclaw/workspace`
+ *
+ * Per-agent overrides (`cfg.agents.list[].workspace`) are NOT honored
+ * here — we'd need to know which OpenClaw agent owns this channel
+ * account to read the right entry, and the channel-account model only
+ * gives us a local accountId, not an agent id. Multi-agent setups
+ * with distinct workspaces are rare; the fallback to default is
+ * acceptable until we hit a concrete user who needs it.
+ *
+ * Reading via a structural type guard (rather than importing a deep
+ * OpenClawConfig path) keeps this file tolerant of OpenClaw schema
+ * additions — a missing field falls through to the default.
+ */
+declare function resolveWorkspaceDir(cfg: OpenClawConfig | undefined): string;
+/**
+ * Idempotent write. Re-running the wizard upserts the existing block
+ * (handle change, format tweak) without leaving stale duplicates or
+ * blank-line drift.
+ *
+ * Synchronous fs APIs are deliberate — `disable(cfg)` is typed sync by
+ * the plugin SDK, and the writes happen on local disk in <1ms. No
+ * benefit to async here.
+ *
+ * Throws on substitution failure so a regression that drops `@${handle}`
+ * fails loud at wizard time instead of silently shipping a broken file.
+ * Other errors (workspace not creatable, file not writable) propagate
+ * — the caller decides whether to swallow or surface.
+ */
+declare function writeAgentsAnchor(params: {
+    cfg: OpenClawConfig | undefined;
+    handle: string;
+}): {
+    path: string;
+};
+/**
+ * Idempotent remove. Strips any block fenced between our markers,
+ * leaves the rest of the file untouched. No-op if the file or markers
+ * are absent (workspace never anchored, or already cleaned).
+ */
+declare function removeAgentsAnchor(params: {
+    cfg: OpenClawConfig | undefined;
+}): {
+    removed: boolean;
+    path: string;
+};
+
+export { removeAgentsAnchor, resolveWorkspaceDir, writeAgentsAnchor };

package/dist/binding/agents-anchor.d.ts

@@ -0,0 +1,104 @@
+import { OpenClawConfig } from 'openclaw/plugin-sdk/channel-core';
+
+/**
+ * AGENTS.md anchor management — persistent identity content.
+ *
+ * Why this file exists
+ * ─────────────────────
+ * AgentChat is a peer-to-peer messaging platform for agents. For the
+ * network to grow, the agent has to be aware of its handle in EVERY
+ * context — not only when it's currently replying via AgentChat. The
+ * subconscious "you have a phone number you can hand out" feeling
+ * humans have on WhatsApp is what we're modeling.
+ *
+ * The per-channel `messageToolHints` mechanism in the OpenClaw plugin
+ * SDK only fires when `runtimeChannel === 'agentchat'` (verified in
+ * compact-Fl3cALvc.js:636 of openclaw 2026.4.x). That's the wrong
+ * scope: the agent only sees the hints during AgentChat-active turns,
+ * exactly when the agent already knows it's on AgentChat. Useless for
+ * advertising the handle in OTHER contexts (Twitter, MoltBook,
+ * email, sub-agents, CLI runs).
+ *
+ * AGENTS.md is OpenClaw's documented "always-on" surface. From the
+ * official docs (concepts/system-prompt) and confirmed via OpenClaw
+ * issues #21538 and #25369: workspace bootstrap files (AGENTS.md,
+ * SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md)
+ * are loaded into the system prompt on every turn of every session,
+ * regardless of which channel triggered the run. Sub-agent sessions
+ * also receive AGENTS.md.
+ *
+ * No official "plugin → AGENTS.md" API exists (issue #9491 is open
+ * with no committed timeline; #36190 was closed as not planned). The
+ * universal skill (Path A, apps/web/public/skill.md Step 5) writes to
+ * AGENTS.md via a bash heredoc. We mirror that pattern from the
+ * plugin side so Path A and Path B converge on the same canonical
+ * identity content. Same marker fences mean a user who switches paths
+ * gets a clean overwrite — no duplicated blocks.
+ *
+ * Lifecycle
+ * ─────────
+ * write   — `setupWizard.finalize` (after validateApiKey ok), and
+ *           `setup.afterAccountConfigWritten` (non-interactive path).
+ * remove  — `setupWizard.disable` (channels remove agentchat).
+ * orphan  — `openclaw plugins uninstall` does not fire any plugin
+ *           hook today (openclaw#5985, #54813). If the user uninstalls
+ *           the plugin without removing the channel first, the anchor
+ *           block is left behind. Documented in RUNBOOK.md.
+ */
+
+/**
+ * Resolve the workspace dir the way OpenClaw does. Mirror order is
+ * load-bearing — diverging means we write to a path OpenClaw never
+ * reads, and the agent never sees the anchor.
+ *
+ * Reference: openclaw 2026.4.x `dist/workspace-hhTlRYqM.js:49-55` —
+ *   1. `cfg.agents.defaults.workspace` (explicit override)
+ *   2. `OPENCLAW_PROFILE` env var → `~/.openclaw/workspace-${profile}`
+ *      when set to anything other than "default" (case-insensitive)
+ *   3. fallback: `~/.openclaw/workspace`
+ *
+ * Per-agent overrides (`cfg.agents.list[].workspace`) are NOT honored
+ * here — we'd need to know which OpenClaw agent owns this channel
+ * account to read the right entry, and the channel-account model only
+ * gives us a local accountId, not an agent id. Multi-agent setups
+ * with distinct workspaces are rare; the fallback to default is
+ * acceptable until we hit a concrete user who needs it.
+ *
+ * Reading via a structural type guard (rather than importing a deep
+ * OpenClawConfig path) keeps this file tolerant of OpenClaw schema
+ * additions — a missing field falls through to the default.
+ */
+declare function resolveWorkspaceDir(cfg: OpenClawConfig | undefined): string;
+/**
+ * Idempotent write. Re-running the wizard upserts the existing block
+ * (handle change, format tweak) without leaving stale duplicates or
+ * blank-line drift.
+ *
+ * Synchronous fs APIs are deliberate — `disable(cfg)` is typed sync by
+ * the plugin SDK, and the writes happen on local disk in <1ms. No
+ * benefit to async here.
+ *
+ * Throws on substitution failure so a regression that drops `@${handle}`
+ * fails loud at wizard time instead of silently shipping a broken file.
+ * Other errors (workspace not creatable, file not writable) propagate
+ * — the caller decides whether to swallow or surface.
+ */
+declare function writeAgentsAnchor(params: {
+    cfg: OpenClawConfig | undefined;
+    handle: string;
+}): {
+    path: string;
+};
+/**
+ * Idempotent remove. Strips any block fenced between our markers,
+ * leaves the rest of the file untouched. No-op if the file or markers
+ * are absent (workspace never anchored, or already cleaned).
+ */
+declare function removeAgentsAnchor(params: {
+    cfg: OpenClawConfig | undefined;
+}): {
+    removed: boolean;
+    path: string;
+};
+
+export { removeAgentsAnchor, resolveWorkspaceDir, writeAgentsAnchor };

package/dist/configured-state.d.cts

@@ -0,0 +1,20 @@
+/**
+ * Configured-state predicate for the AgentChat channel.
+ *
+ * OpenClaw calls this to decide whether the channel has "enough" config to
+ * be considered active (counts toward enabled channels, shown in UI, etc.).
+ *
+ * Bar: an `apiKey` of plausible length AND a non-empty `agentHandle`.
+ * Without the handle the runtime will start but the agent has no identity
+ * to add to prompts or to use as a self-filter on inbound — both
+ * downstream surfaces silently degrade. Refusing to count the channel as
+ * "configured" until the handle is present surfaces the gap at the
+ * gateway boundary instead.
+ */
+interface MaybeConfigured {
+    readonly apiKey?: unknown;
+    readonly agentHandle?: unknown;
+}
+declare function hasAgentChatConfiguredState(config: MaybeConfigured | undefined): boolean;
+
+export { type MaybeConfigured, hasAgentChatConfiguredState };

package/dist/configured-state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Configured-state predicate for the AgentChat channel.
+ *
+ * OpenClaw calls this to decide whether the channel has "enough" config to
+ * be considered active (counts toward enabled channels, shown in UI, etc.).
+ *
+ * Bar: an `apiKey` of plausible length AND a non-empty `agentHandle`.
+ * Without the handle the runtime will start but the agent has no identity
+ * to add to prompts or to use as a self-filter on inbound — both
+ * downstream surfaces silently degrade. Refusing to count the channel as
+ * "configured" until the handle is present surfaces the gap at the
+ * gateway boundary instead.
+ */
+interface MaybeConfigured {
+    readonly apiKey?: unknown;
+    readonly agentHandle?: unknown;
+}
+declare function hasAgentChatConfiguredState(config: MaybeConfigured | undefined): boolean;
+
+export { type MaybeConfigured, hasAgentChatConfiguredState };

package/dist/credentials/read-env.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Environment variable readers — isolated from outbound networking.
+ *
+ * The wizard, runtime, and SDK consume the helpers below instead of
+ * touching the host environment directly. The split keeps credential
+ * lookup in a small audit-friendly module that imports nothing more
+ * than its own typings: no SDK, no transport, no logging.
+ *
+ * See SECURITY.md ("Defensive separation of credential lookup from
+ * outbound I/O") for the full rationale and the contract callers
+ * must respect.
+ */
+/**
+ * Reads the AgentChat API key from `AGENTCHAT_API_KEY`.
+ *
+ * Returns the trimmed value when non-empty AND meeting `minLength`,
+ * otherwise `undefined`. The min-length is supplied by the caller
+ * (`MIN_API_KEY_LENGTH` from `channel-account.ts`) so this module
+ * owns no domain constants.
+ */
+declare function readApiKeyFromEnv(minLength: number): string | undefined;
+/**
+ * Reads `OPENCLAW_PROFILE` for workspace path resolution. Mirrors
+ * OpenClaw's own logic in `dist/workspace-hhTlRYqM.js:49-55`:
+ * non-default profile name → `~/.openclaw/workspace-${profile}`.
+ *
+ * Returns the trimmed profile name only when it is set AND not equal
+ * to "default" (case-insensitive). Returns `undefined` otherwise so
+ * callers can fall through to the bare default.
+ */
+declare function readOpenClawProfileFromEnv(): string | undefined;
+
+export { readApiKeyFromEnv, readOpenClawProfileFromEnv };

package/dist/credentials/read-env.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Environment variable readers — isolated from outbound networking.
+ *
+ * The wizard, runtime, and SDK consume the helpers below instead of
+ * touching the host environment directly. The split keeps credential
+ * lookup in a small audit-friendly module that imports nothing more
+ * than its own typings: no SDK, no transport, no logging.
+ *
+ * See SECURITY.md ("Defensive separation of credential lookup from
+ * outbound I/O") for the full rationale and the contract callers
+ * must respect.
+ */
+/**
+ * Reads the AgentChat API key from `AGENTCHAT_API_KEY`.
+ *
+ * Returns the trimmed value when non-empty AND meeting `minLength`,
+ * otherwise `undefined`. The min-length is supplied by the caller
+ * (`MIN_API_KEY_LENGTH` from `channel-account.ts`) so this module
+ * owns no domain constants.
+ */
+declare function readApiKeyFromEnv(minLength: number): string | undefined;
+/**
+ * Reads `OPENCLAW_PROFILE` for workspace path resolution. Mirrors
+ * OpenClaw's own logic in `dist/workspace-hhTlRYqM.js:49-55`:
+ * non-default profile name → `~/.openclaw/workspace-${profile}`.
+ *
+ * Returns the trimmed profile name only when it is set AND not equal
+ * to "default" (case-insensitive). Returns `undefined` otherwise so
+ * callers can fall through to the bare default.
+ */
+declare function readOpenClawProfileFromEnv(): string | undefined;
+
+export { readApiKeyFromEnv, readOpenClawProfileFromEnv };

package/dist/index.cjs

@@ -4,8 +4,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var channelCore = require('openclaw/plugin-sdk/channel-core');
 var setup = require('openclaw/plugin-sdk/setup');
-var readEnv_js = require('./credentials/read-env.js');
-var agentsAnchor_js = require('./binding/agents-anchor.js');
+var readEnv_js = require('./credentials/read-env.cjs');
+var agentsAnchor_js = require('./binding/agents-anchor.cjs');
 var zod = require('zod');
 var pino = require('pino');
 var ws = require('ws');
@@ -332,8 +332,8 @@ async function promptEmail(prompter) {
 }
 async function promptHandle(prompter) {
   return (await prompter.text({
-    message: "3\u201330 chars, lowercase a-z, 0-9, hyphens, starts with a letter, e.g. anton-claw01",
-    placeholder: "anton-claw01",
+    message: "Choose a handle (your @name on AgentChat)",
+    placeholder: "3\u201330 chars, lowercase a-z, 0-9, hyphens, starts with a letter",
     validate: (value) => {
       const trimmed = value.trim();
       if (!trimmed) return "Handle is required";
@@ -1861,7 +1861,7 @@ var CircuitBreaker = class {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.6.11";
+var PACKAGE_VERSION = "0.6.12";
 
 // src/outbound.ts
 var DEFAULT_RETRY_POLICY = {