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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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();}