Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

perf(chat): trim ~10KB OpenClaw boilerplate + add granular perf marks

Yuting Zhonge3aa0b5733a2
diff --git a/src/app/api/chat/route.ts b/src/app/api/chat/route.ts
index b8e8ded3..1883ae36 100644
--- a/src/app/api/chat/route.ts
+++ b/src/app/api/chat/route.ts
@@ -200,11 +200,17 @@ export async function POST(request: Request) {
let assistantBuffer = "";
try {
perf.mark("stream_start");
+ // Surface input sizes so each perf trace tells us *why* this turn
+ // was fast/slow — a 24KB system prompt with a 1.8KB kickoff brief
+ // behaves very differently from a 200B reply. Browser console
+ // table includes these alongside the timing marks.
send("meta", {
project_slug: project.slug,
agent: agentName,
session_id: sessionId,
session_key: sessionKey,
+ message_chars: body.message.length,
+ is_kickoff: Boolean(taskId),
});
for await (const evt of streamChatViaGateway({
sessionKey,
diff --git a/src/components/live-transcript.tsx b/src/components/live-transcript.tsx
index 58a80e4c..b8e08708 100644
--- a/src/components/live-transcript.tsx
+++ b/src/components/live-transcript.tsx
@@ -163,6 +163,13 @@ export function LiveTranscript({
const [pendingAssistant, setPendingAssistant] = useState("");
const [pendingTools, setPendingTools] = useState<ToolEntry[]>([]);
const [pendingError, setPendingError] = useState<string | null>(null);
+ /**
+ * Most recent OpenClaw lifecycle phase for the in-flight turn (run.start,
+ * run.warming, etc.). Surfaced in the "thinking…" indicator so a long
+ * wait before the first model token at least shows forward motion.
+ * Cleared when the turn ends.
+ */
+ const [pendingLifecycle, setPendingLifecycle] = useState<string | null>(null);
const scrollRef = useRef<HTMLDivElement>(null);
const stickyBottomRef = useRef(true);
@@ -225,6 +232,7 @@ export function LiveTranscript({
setPendingAssistant("");
setPendingTools([]);
setPendingError(null);
+ setPendingLifecycle(null);
}
if (data.byteOffset !== byteOffset) setByteOffset(data.byteOffset);
const shouldStop = onPolled?.({
@@ -360,6 +368,33 @@ export function LiveTranscript({
);
},
onError: (msg) => setPendingError(msg),
+ onLifecycle: (phase) => setPendingLifecycle(phase),
+ onMeta: (meta) => {
+ if (process.env.NODE_ENV !== "production") {
+ // eslint-disable-next-line no-console
+ console.log(
+ `[chat-perf] turn start agent=${meta.agent} session=${meta.session_id} message_chars=${meta.message_chars}${meta.is_kickoff ? " (kickoff)" : ""}`,
+ );
+ }
+ },
+ onPerf: (marks) => {
+ if (process.env.NODE_ENV !== "production") {
+ // eslint-disable-next-line no-console
+ console.groupCollapsed(
+ `[chat-perf] turn complete (${marks.length} marks)`,
+ );
+ // eslint-disable-next-line no-console
+ console.table(
+ marks.map((m) => ({
+ name: m.name,
+ "at (ms)": Math.round(m.at),
+ "Δ (ms)": Math.round(m.delta),
+ })),
+ );
+ // eslint-disable-next-line no-console
+ console.groupEnd();
+ }
+ },
});
}
}
@@ -387,6 +422,7 @@ export function LiveTranscript({
} finally {
setSendingChat(false);
setTurnStartedAt(null);
+ setPendingLifecycle(null);
abortRef.current = null;
}
},
@@ -467,6 +503,7 @@ export function LiveTranscript({
agentDisplayName={agentDisplayName}
events={events}
turnStartedAt={turnStartedAt}
+ lifecyclePhase={pendingLifecycle}
/>
)}
</li>
@@ -591,12 +628,23 @@ type SseToolEvent = {
label?: string;
};
+type SsePerfMark = { name: string; at: number; delta: number };
+type SseMeta = {
+ message_chars?: number;
+ is_kickoff?: boolean;
+ agent?: string;
+ session_id?: string;
+};
+
function handleSseEvent(
raw: string,
handlers: {
onText: (chunk: string) => void;
onTool: (evt: SseToolEvent) => void;
onError: (msg: string) => void;
+ onLifecycle?: (phase: string) => void;
+ onMeta?: (meta: SseMeta) => void;
+ onPerf?: (marks: SsePerfMark[]) => void;
},
) {
const lines = raw.split("\n");
@@ -619,6 +667,22 @@ function handleSseEvent(
handlers.onTool(data as SseToolEvent);
return;
}
+ if (evt === "lifecycle") {
+ const phase = (data as { phase?: string }).phase;
+ if (typeof phase === "string" && handlers.onLifecycle) {
+ handlers.onLifecycle(phase);
+ }
+ return;
+ }
+ if (evt === "meta") {
+ if (handlers.onMeta) handlers.onMeta(data as SseMeta);
+ return;
+ }
+ if (evt === "perf") {
+ const marks = (data as { marks?: SsePerfMark[] }).marks;
+ if (Array.isArray(marks) && handlers.onPerf) handlers.onPerf(marks);
+ return;
+ }
if (evt === "error") {
const msg = (data as { message?: string }).message ?? "unknown error";
handlers.onError(msg);
@@ -984,6 +1048,7 @@ function WorkingStatus({
agentDisplayName,
events,
turnStartedAt,
+ lifecyclePhase,
}: {
agentDisplayName: string;
events: TranscriptEvent[];
@@ -994,6 +1059,14 @@ function WorkingStatus({
* turn's first event hasn't been written to JSONL yet.
*/
turnStartedAt: number | null;
+ /**
+ * Most recent OpenClaw lifecycle phase (e.g. "run.start", "warming",
+ * "compacting") for the in-flight turn. Used to give the user a more
+ * specific status than "thinking…" during the pre-first-token wait,
+ * which is the dominant chunk of latency for kickoffs against codex/
+ * gpt-5.5 with a multi-KB system prompt.
+ */
+ lifecyclePhase?: string | null;
}) {
const [now, setNow] = useState<number>(() => Date.now());
useEffect(() => {
@@ -1025,8 +1098,19 @@ function WorkingStatus({
let headline = `${agentDisplayName} is thinking…`;
let subtitle: string | null = null;
if (!lastEvent || lastEvent.kind === "user_message" || lastEvent.kind === "unknown") {
- headline = `Starting ${agentDisplayName}…`;
- subtitle = "Delivering the brief to OpenClaw.";
+ // Pre-first-event window. For a kickoff this can be 10-20s while
+ // Codex chews through the system prompt. Use the gateway lifecycle
+ // hint if we got one — it tells us OpenClaw is alive and which phase
+ // it's in — otherwise fall back to a generic "starting" message.
+ const lifecycleSummary = lifecyclePhase
+ ? humanLifecyclePhase(lifecyclePhase)
+ : null;
+ headline = lifecycleSummary
+ ? `${agentDisplayName} · ${lifecycleSummary}`
+ : `Starting ${agentDisplayName}…`;
+ subtitle = lifecycleSummary
+ ? "Waiting on the model's first token."
+ : "Delivering the brief to OpenClaw.";
} else if (inFlightToolCall) {
headline = `Calling ${formatToolName(inFlightToolCall.name)}…`;
subtitle = inFlightToolCall.label ?? null;
@@ -1095,6 +1179,24 @@ function formatElapsed(ms: number): string {
return `${h}h ${m % 60}m`;
}
+/**
+ * Translate an OpenClaw `agent` stream lifecycle phase into a short
+ * user-facing label. We don't try to enumerate every possible phase —
+ * unknown values fall through to a generic "starting up…" so a future
+ * gateway protocol bump doesn't render a blank status. Used by the
+ * pre-first-event branch of WorkingStatus (the ~15s pause where the
+ * model is parsing the system prompt and brief).
+ */
+function humanLifecyclePhase(phase: string): string {
+ const p = phase.toLowerCase();
+ if (p.includes("warming") || p.includes("warmup")) return "warming up…";
+ if (p.includes("compact")) return "compacting context…";
+ if (p === "start" || p.endsWith(".start") || p.includes("run.start"))
+ return "calling the model…";
+ if (p.includes("end") || p.includes("complete")) return "finishing up…";
+ return "starting up…";
+}
+
/**
* Strip the project-slug prefix and the namespace path so the user sees
* the bare action name. Tools come in two conventions:
diff --git a/src/server/agent-templates.test.ts b/src/server/agent-templates.test.ts
index dad8fdb6..4ee30767 100644
--- a/src/server/agent-templates.test.ts
+++ b/src/server/agent-templates.test.ts
@@ -81,6 +81,30 @@ describe("ensureProjectAgents — IDENTITY.md per-agent + SKILL.md shared", () =
}
});
+ // System-prompt-size regression guard: OpenClaw seeds each workspace with
+ // ~11 KB of generic boilerplate (camera tools, memory rituals, etc.) that
+ // gets injected into every model call but doesn't apply to a marketing
+ // CMO. We overwrite the five OpenClaw-default files with sub-300-char
+ // stubs so the system prompt stays lean. If someone resurrects the
+ // boilerplate, this test catches it.
+ it("overwrites OpenClaw default workspace files with minimal stubs", async () => {
+ await ensureProjectAgents("demo");
+ for (const fname of [
+ "AGENTS.md",
+ "SOUL.md",
+ "TOOLS.md",
+ "USER.md",
+ "HEARTBEAT.md",
+ ]) {
+ const path = join(tmpDataDir, "agents", "demo-cmo", fname);
+ expect(existsSync(path)).toBe(true);
+ const body = readFileSync(path, "utf8");
+ // Generous bound; the stubs are ~150–300 chars. Anything beyond 1 KB
+ // means the OpenClaw boilerplate snuck back in.
+ expect(body.length).toBeLessThan(1024);
+ }
+ });
+
it("SKILL.md is byte-identical across all three agents (shared source of truth)", async () => {
await ensureProjectAgents("demo");
const cmo = read("demo-cmo", "SKILL.md");
diff --git a/src/server/agent-templates.ts b/src/server/agent-templates.ts
index e2df3b2c..a0d66efa 100644
--- a/src/server/agent-templates.ts
+++ b/src/server/agent-templates.ts
@@ -357,11 +357,81 @@ ${template.system_prompt}
${skill}`;
await writeFile(join(workspaceAbs, "IDENTITY.md"), body, "utf8");
+
+ // OpenClaw seeds every agent workspace with generic AGENTS.md / SOUL.md
+ // / TOOLS.md / USER.md / HEARTBEAT.md boilerplate (~11 KB total) aimed
+ // at general-purpose assistants — workspace memory rituals, camera/SSH
+ // tool notes, user-profile templates. None of it applies to a marketing
+ // CMO/specialist whose identity already lives in IDENTITY.md, and all
+ // of it inflates every model call's system prompt. Overwrite with thin
+ // pointer stubs after `openclaw agents add` runs so the runtime still
+ // finds the files but the injected bytes drop to ~1 KB.
+ await writeMinimalWorkspaceStubs(workspaceAbs);
} catch (err) {
console.error(`Could not write IDENTITY.md for ${template.key}:`, err);
}
}
+const STUB_AGENTS_MD = `# Workspace
+
+This agent's role and operating rules live in IDENTITY.md (loaded
+automatically). The other files in this directory exist only so the
+OpenClaw runtime finds the names it expects — they're intentionally
+empty for prompt-efficiency.
+`;
+
+const STUB_SOUL_MD = `# Personality
+
+Be terse, opinionated, and useful. Skip filler ("Great question!",
+"I'd be happy to help"). Lead with the point — a dollar figure, a
+specific gap, a recommendation. Have a point of view; the user can
+push back if they disagree.
+`;
+
+const STUB_TOOLS_MD = `# Local Notes
+
+Empty by design. Domain tool usage lives in IDENTITY.md; runtime
+infrastructure (cameras, SSH, TTS) does not apply to this agent.
+`;
+
+const STUB_USER_MD = `# About the user
+
+A solo marketer running their own business on the notfair-cmo
+platform. They pay attention to dollar figures and concrete next
+steps. Build context here as you learn it across sessions.
+`;
+
+const STUB_HEARTBEAT_MD = `# Heartbeat
+
+Empty by design — heartbeats are disabled. Cron-driven check-ins
+arrive as normal "(task assignment)" turns instead.
+`;
+
+/**
+ * Overwrite the OpenClaw-default workspace files with minimal stubs.
+ *
+ * Why: `openclaw agents add` seeds each workspace with five generic
+ * files aimed at general-purpose assistants (camera/SSH tool notes,
+ * memory-discipline lectures, user-profile templates). That's ~11 KB
+ * of irrelevant boilerplate injected into every model call. Replacing
+ * them with sub-300-char stubs that still satisfy whatever runtime
+ * filesystem expectations OpenClaw has cuts the system prompt by
+ * roughly that amount.
+ *
+ * Idempotent: re-running on an existing workspace just rewrites the
+ * stubs. We don't delete the files because OpenClaw may probe for them
+ * by name during session startup.
+ */
+async function writeMinimalWorkspaceStubs(workspaceAbs: string): Promise<void> {
+ await Promise.all([
+ writeFile(join(workspaceAbs, "AGENTS.md"), STUB_AGENTS_MD, "utf8"),
+ writeFile(join(workspaceAbs, "SOUL.md"), STUB_SOUL_MD, "utf8"),
+ writeFile(join(workspaceAbs, "TOOLS.md"), STUB_TOOLS_MD, "utf8"),
+ writeFile(join(workspaceAbs, "USER.md"), STUB_USER_MD, "utf8"),
+ writeFile(join(workspaceAbs, "HEARTBEAT.md"), STUB_HEARTBEAT_MD, "utf8"),
+ ]);
+}
+
export async function agentExists(name: string): Promise<boolean> {
try {
// `agents list` doesn't currently take a name filter, so list-all and grep.
diff --git a/src/server/openclaw/gateway-client.ts b/src/server/openclaw/gateway-client.ts
index 1cdf576c..ae948207 100644
--- a/src/server/openclaw/gateway-client.ts
+++ b/src/server/openclaw/gateway-client.ts
@@ -406,6 +406,11 @@ export async function* streamChatViaGateway(
let resolveWait: (() => void) | null = null;
let firstEventSeen = false;
let firstDeltaEmitted = false;
+ // Per-channel "first event" marks so the perf trace shows which OpenClaw
+ // stream type unblocked the user. Helps attribute latency to the model
+ // (first tool start / text) vs. plumbing (first lifecycle event).
+ let firstLifecycleSeen = false;
+ let firstToolStartSeen = false;
const wake = () => {
if (resolveWait) {
@@ -481,6 +486,10 @@ export async function* streamChatViaGateway(
if (!phase) return;
const name = typeof d.name === "string" ? d.name : "tool";
const label = phase === "start" ? labelForTool(name, d.args) : undefined;
+ if (phase === "start" && !firstToolStartSeen) {
+ firstToolStartSeen = true;
+ perf?.mark("gw_first_tool_start");
+ }
events.push({ kind: "tool", phase, toolCallId, name, label });
wake();
return;
@@ -490,6 +499,10 @@ export async function* streamChatViaGateway(
const d = payload.data ?? {};
const phase = typeof d.phase === "string" ? d.phase : payload.state;
if (phase) {
+ if (!firstLifecycleSeen) {
+ firstLifecycleSeen = true;
+ perf?.mark("gw_first_lifecycle");
+ }
events.push({ kind: "lifecycle", phase });
wake();
}