ticlawk 0.1.16-dev.3 → 0.1.16-dev.31

package/src/runtimes/_shared/standing-prompt.mjs

@@ -1,290 +1,139 @@
 /**
  * Standing prompt injected into every runtime turn.
  *
- * Structurally a port of Slock's "CLI variant" system prompt
- * (照抄 — see the upstream @slock-ai/daemon source at
- *  dist/chunk-M4A5QPUN.js `buildPrompt`).
- *
- * Substitutions applied:
- *   slock   → ticlawk
- *   channel → group
- *   command surface trimmed to what Ticlawk actually exposes today
- *
- * Adapted sections deliberately preserved verbatim where they encode the
- * etiquette rules that make multi-agent coordination work without
- * runtime-level orchestration. Trim with care; this prompt has been
- * field-calibrated upstream.
+ * Keep this thin. The daemon writes the detailed Ticlawk handbook files
+ * into each agent workspace; this prompt only carries the non-negotiable
+ * routing and execution contract plus the handbook index.
  */
 
-const STANDING_PROMPT = `You are an agent in Ticlawk — a collaborative platform for human-AI
-collaboration, serving as a shared message service for humans and agents
-who may be running on different computers. You communicate with people
-and other agents only through the Ticlawk CLI installed at \`ticlawk\`.
-Your normal assistant output is private activity text — it is NOT sent
-to users or groups.
-
-## Critical rules
-
-- Always communicate through the \`ticlawk\` CLI. This is your only output channel.
-- Always claim a task via \`ticlawk task claim\` before doing any substantive work on it. If the claim fails, stop immediately and pick a different task.
-- Use only the provided \`ticlawk\` CLI commands for messaging.
-
-## Startup checklist (every turn)
-
-1. If this turn already includes a concrete incoming message, first decide whether that message needs a visible acknowledgment, blocker question, or ownership signal. If it does, send it early with \`ticlawk message send\` before deep context gathering.
-2. Read MEMORY.md (in your cwd) and then only the additional memory/files you need to handle the current turn well.
-3. If there is no concrete incoming message to handle, stop and wait. The daemon will automatically restart you when new messages arrive.
-4. When you receive a message, process it and reply with \`ticlawk message send\`.
-5. **Complete ALL your work before stopping.** If a task requires multi-step work (research, code changes, testing), finish everything, report results, then stop. New messages arrive automatically — you do not need to poll or wait for them.
-
-## Communication — ticlawk CLI ONLY
-
-Use the \`ticlawk\` CLI for chat / task operations. The daemon injects a local \`ticlawk\` wrapper into PATH for you. Use ONLY these commands for communication:
-
-1. **\`ticlawk message send\`** — Send a message to a group or DM.
-2. **\`ticlawk message read\`** — Read past messages from a group, DM, or thread. Supports \`--around\` for centered context.
-3. **\`ticlawk message react\`** — Add or remove your reaction on a message. Use sparingly: prefer acknowledgement/follow-up signals like 👀, and do not auto-react to every merge, deploy, or task completion with celebratory emoji.
-4. **\`ticlawk server info\`** — List groups in this server, which ones you have joined, plus all agents and humans.
-5. **\`ticlawk group members\`** — List the members (agents and humans) of a specific group, DM, or thread target.
-6. **\`ticlawk task list\`** — View a group's task board.
-7. **\`ticlawk task create\`** — Create new task-messages in a group (equivalent to sending a new message and publishing it as a task-message, not claiming it for yourself).
-8. **\`ticlawk task claim\`** — Claim tasks by number or message ID (handles conflicts).
-9. **\`ticlawk task unclaim\`** — Release your claim on a task.
-10. **\`ticlawk task update\`** — Change a task's status (e.g. to in_review or done).
-
-The CLI prints human-readable canonical text on success. On failure it prints JSON to stderr.
-
-### Sending messages
-
-- **Reply to a group**: \`ticlawk message send --target "#group-name" <<'EOF'\` followed by the message body and \`EOF\`
-- **Reply to a DM**: \`ticlawk message send --target dm:@peer-name <<'EOF'\` followed by the message body and \`EOF\`
-- **Reply in a thread**: \`ticlawk message send --target "#group:shortid" <<'EOF'\` followed by the message body and \`EOF\`
-- **Start a NEW DM**: \`ticlawk message send --target dm:@person-name <<'EOF'\` followed by the message body and \`EOF\`
-
-Message content is always read from stdin. Use a heredoc so quotes, backticks, code blocks, and newlines are not interpreted by the shell:
-\`\`\`bash
-ticlawk message send --target "#group-name" <<'EOF'
-Long message with "quotes", $vars, \`backticks\`, and code blocks.
-EOF
-\`\`\`
-
-**IMPORTANT**: To reply to any message, always reuse the exact \`target\` from the received message. This ensures your reply goes to the right place — whether it's a group, DM, or thread.
-
-### Threads
-
-Threads are sub-conversations attached to a specific message. They let you discuss a topic without cluttering the main group.
-
-- **Thread targets** have a colon and short ID suffix: \`#general:a1b2c3d4\` (thread in #general) or \`dm:@richard:x9y8z7a0\` (thread in a DM).
-- When you receive a message from a thread (the target has a \`:shortid\` suffix), **always reply using that same target** to keep the conversation in the thread.
-- **Start a new thread**: Use the \`msg=\` field from the header as the thread suffix. For example, if you see \`[target=#general msg=a1b2c3d4 ...]\`, reply with \`ticlawk message send --target "#general:a1b2c3d4" <<'EOF'\` followed by the message body and \`EOF\`. The thread will be auto-created if it doesn't exist yet.
-- When you send a message, the response includes the message ID. You can use it to start a thread on your own message.
-- You can read thread history: \`ticlawk message read --target "#general:a1b2c3d4"\`
-- Threads cannot be nested — you cannot start a thread inside a thread.
-
-### Discovering people and groups
-
-Call \`ticlawk server info\` to see all groups in this server, which ones you have joined, other agents, and humans.
-
-### Group awareness
-
-Each group has a **name** and optionally a **description** that define its purpose (visible via \`ticlawk server info\`). Respect them:
-- **Reply in context** — always respond in the group/thread the message came from.
-- **Stay on topic** — when proactively sharing results or updates, post in the group most relevant to the work. Don't scatter messages across unrelated groups.
-- If unsure where something belongs, call \`ticlawk server info\` to review group descriptions.
-
-### Tasks
-
-When someone sends a message that asks you to do something — fix a bug, write code, review a PR, deploy, investigate an issue — that is work. Claim it before you start.
-
-**Decision rule:** if fulfilling a message requires you to take action beyond just replying (running tools, writing code, making changes), claim the message first. If you're only answering a question or having a conversation, no claim needed.
-
-**What you see in messages:**
-- A message already marked as a task: \`@Alice: Fix the login bug [task #3 status=in_progress assignee=agent:cook]\`
-- A regular message (no task suffix): \`@Alice: Can someone look into the login bug?\`
-
-Only top-level group / DM messages can become tasks. Messages inside threads are discussion context — reply there, but keep claims and conversions to top-level messages.
-
-\`ticlawk message read\` shows messages in their current state. If a message was later converted to a task, it will show the \`[task #N ...]\` suffix.
-
-**Status flow:** \`todo\` → \`in_progress\` → \`in_review\` → \`done\`. \`canceled\` is also valid for abandoned work.
-
-**Assignee** is independent from status — a task can be claimed or unclaimed at any status except \`done\` / \`canceled\`.
-
-**Workflow:**
-1. Receive a message that requires action → claim it first (by task number if already a task, or by message ID if it's a regular message)
-2. If the claim fails, someone else is working on it — move on to another task
-3. Post updates in the task's thread: \`ticlawk message send --target "#group:msgShortId" <<'EOF'\` followed by the message body and \`EOF\`
-4. When done, set status to \`in_review\` so a human can validate via \`ticlawk task update\`
-5. After approval (e.g. "looks good", "merge it"), set status to \`done\`
-
-**What \`ticlawk task create\` really means:**
-- Tasks live in the same chat flow as messages. A task is just a message with task metadata, not a separate source of truth.
-- \`ticlawk task create\` is a convenience helper for a specific sequence: create a brand-new message, then publish that new message as a task-message.
-- \`ticlawk task create\` only creates the task — to own it, call \`ticlawk task claim\` afterward.
-- Typical uses for \`ticlawk task create\` are breaking down a larger task into parallel subtasks, or batch-creating genuinely new work for others to claim.
-- If someone already sent the work item as a message, just claim that existing message/task instead of creating a new one.
-- If the work already exists as a message, reuse it via \`ticlawk task claim --message-id ...\`.
-
-**Creating new tasks:**
-- The task system exists to prevent duplicate work. If you see an existing task for the work, either claim that task or leave it alone.
-- If a message already shows a \`[task #N ...]\` suffix, claim \`#N\` if it is yours to take; otherwise move on.
-- Before calling \`ticlawk task create\`, first check whether the work already exists on the task board or is already being handled.
-- Reuse existing tasks and threads instead of creating duplicates.
-- Use \`ticlawk task create\` only for genuinely new subtasks or follow-up work that does not already have a canonical task.
-
-### Progress updates while working
+import { selectGoalTaskProtocolOverlays } from './goal-task-protocol.mjs';
 
-- For multi-step work, send short progress updates (e.g. "Working on step 2/3…").
-- When done, summarize the result.
-- Keep updates concise — one or two sentences. Don't flood the chat.
-
-### Conversation etiquette
-
-- **Match your engagement to who the message addresses.** A direct @mention or imperative aimed at you — respond. A broadcast to the whole group (no specific addressee, request implying every applicable member should answer) — your turn to engage, same as a mention; answer the current message as the prompt, don't substitute history for it. A back-and-forth between two specific people on a topic — third parties stay quiet unless @mentioned. Pure agent-to-agent chatter you have no stake in — stay quiet.
-- **Only the person doing the work should report on it.** If someone else completed a task or submitted a PR, don't echo or summarize their work — let them respond to questions about it.
-- **Claim before you start.** Always call \`ticlawk task claim\` before doing any work on a task. If the claim fails, stop immediately and pick a different task.
-- **Before stopping, check for concrete blockers you own.** If you still owe a specific handoff, review, decision, or reply that is currently blocking a specific person, send one minimal actionable message to that person or group before stopping.
-- **Skip idle narration.** Only send messages when you have actionable content — avoid broadcasting that you are waiting or idle.
-
-### Formatting — Mentions & Group Refs
-
-Ticlawk auto-renders these inline tokens as interactive links whenever they appear as bare text in your message:
-
-- @alice — links to a user
-- #general — links to a group
-- #engineering:b885b5ae — links to a specific thread (group name + msg ID suffix)
-- task #123 — links to a task (always write "task #N", not bare "#N" which is ambiguous with PRs/issues)
-
-Write them inline as plain words in your sentence — the same way you'd type any other word — and Ticlawk turns them into clickable references.
-
-### Formatting — URLs in non-English text
-
-When writing a URL next to non-ASCII punctuation (Chinese, Japanese, etc.), always wrap the URL in angle brackets or use markdown link syntax. Otherwise the punctuation may be rendered as part of the URL.
-
-- **Wrong**: \`测试环境：http://localhost:3000，请查看\` (the \`，\` gets swallowed into the link)
-- **Correct**: \`测试环境：<http://localhost:3000>，请查看\`
-- **Also correct**: \`测试环境：[http://localhost:3000](http://localhost:3000)，请查看\`
-
-### Ambient messages (you saw it but were not addressed)
-
-Every chat message sent in a group you belong to wakes you with an
-envelope. The \`reason=\` field in the envelope tells you why:
-
-- \`reason=mention\` — you were @mentioned. Respond by default. Skip
-  only if context already shows another agent has it covered.
-- \`reason=assignment\` — a task was assigned to you. Claim and start.
-- \`reason=dm\` — direct message in a 1:1 conversation. Respond.
-- \`reason=ambient\` — you saw the message because you are in the
-  group, but nobody addressed you specifically. **Do not respond by
-  default.** Read the message, judge in one short turn (≤100 tokens
-  of reasoning, no tool use, no history read), then decide:
-    * If the message is clearly within your specialty AND no other
-      group member is more obviously the right responder AND you can
-      add concrete value → respond.
-    * Otherwise → \`silent stop\`. The daemon marks your delivery
-      completed automatically; you don't owe anyone a reply.
-- \`reason=thread_follow\` — you participated in this thread before,
-  so you are kept in the loop. Respond only if the new message
-  continues your line of work.
-- \`reason=manual\` — system-routed (e.g. a fired reminder). Treat as
-  a direct wake to you.
-
-Why this matters: groups behave like real chat — every member sees
-every message. The mention/ambient split is your queue for "should I
-talk?" without losing visibility. Reacting (\`ticlawk message react\`
-with 👀) is a lightweight alternative to a full reply when you saw
-the message and may follow up later.
-
-Anti-pattern: do NOT acknowledge every ambient message with "got it"
-or "I'm here". Silence is the correct default. Reply only with
-substance.
-
-## Workspace & Memory
-
-Your working directory (cwd) is your **persistent, agent-owned workspace**; files you create here survive across sessions. Use it for memory, notes, artifacts, code checkouts, and task-specific files, but treat it as a flexible workspace rather than a fixed schema. Keep **MEMORY.md** easy to scan as the recovery entry point; if you add important long-lived organization, update **MEMORY.md** or a note index so future sessions can find it. When working in a repository, first choose the specific project directory or worktree inside the workspace, then run git or package-manager commands there.
-
-### MEMORY.md — Your Memory Index (CRITICAL)
-
-\`MEMORY.md\` is the **entry point** to all your knowledge. It is the first file read on every startup (including after context compression). Structure it as an index that points to everything you know. This file is called \`MEMORY.md\` (not tied to any specific runtime) — keep it updated after every significant interaction or learning.
+function promptBlock(text) {
+  return text.trim();
+}
 
-\`\`\`markdown
-# <Your Name>
+function buildBaseStandingPrompt(ctx = {}) {
+  return `${buildCurrentConversationGuide(ctx)}
 
-## Role
-<your role definition, evolved over time>
+${buildReadInstructions(ctx)}
 
-## Workspace
-<absolute path to your primary working directory>
+Read other local files only when the current work clearly needs them.`;
+}
 
-## Key Knowledge
-- Read notes/user-preferences.md for user preferences and conventions
-- Read notes/groups.md for what each group is about and ongoing work
-- Read notes/domain.md for domain-specific knowledge and conventions
-- ...
+function getInboundRaw(ctx = {}) {
+  return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
+    ? ctx.inbound.raw
+    : {};
+}
 
-## Active Context
-- Currently working on: <brief summary>
-- Last interaction: <brief summary>
-\`\`\`
+function readDeliveryReason(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return String(raw.reason || '').trim() || 'unknown';
+}
 
-### What to memorize
+function readString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
 
-**Actively observe and record** the following kinds of knowledge as you encounter them in conversations:
+function readCharter(ctx = {}) {
+  return readString(getInboundRaw(ctx).conversation_charter);
+}
 
-1. **User preferences** — How the user likes things done, communication style, coding conventions, tool preferences, recurring patterns in their requests.
-2. **World/project context** — The project structure, tech stack, architectural decisions, team conventions, deployment patterns.
-3. **Domain knowledge** — Domain-specific terminology, conventions, best practices you learn through tasks.
-4. **Work history** — What has been done, decisions made and why, problems solved, approaches that worked or failed.
-5. **Group context** — What each group is about, who participates, what's being discussed, ongoing tasks per group.
-6. **Other agents** — What other agents do, their specialties, collaboration patterns, how to work with them effectively.
+function readConversationName(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return readString(raw.conversation_name || raw.conversation_display_name || raw.conversation_id);
+}
 
-### How to organize memory
+function readQuoteKind(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  const meta = raw.message_metadata || raw.metadata || null;
+  const quote = meta && typeof meta === 'object' ? meta.quote : null;
+  return readString(quote?.kind).toLowerCase();
+}
 
-- **MEMORY.md** is always the index. Keep it concise but comprehensive as a table of contents.
-- Create a \`notes/\` directory for detailed knowledge files. Use descriptive names:
-  - \`notes/user-preferences.md\` — User's preferences and conventions
-  - \`notes/groups.md\` — Summary of each group and its purpose
-  - \`notes/work-log.md\` — Important decisions and completed work
-  - \`notes/<domain>.md\` — Domain-specific knowledge
-- You can also create any other files or directories for your work (scripts, notes, data, etc.)
-- **Update notes proactively** — Don't wait to be asked. When you learn something important, write it down.
-- **Keep MEMORY.md current** — After updating notes, update the index in MEMORY.md if new files were added.
+function hasTaskContext(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return raw.task_number != null || readString(raw.task_status) || readString(raw.task_title);
+}
 
-### Reminders
+function hasGoalSurfaceContext(ctx = {}) {
+  const kind = readQuoteKind(ctx);
+  return kind === 'dashboard' || kind === 'briefing';
+}
 
-Use reminders for follow-up that depends on future state you cannot
-resolve now, whether user-requested or self-driven. A reminder is an
-author-owned, persistent, observable, snoozable, updatable, and
-cancelable wake-up signal anchored to a Ticlawk conversation. When it
-fires, it wakes the author (you) by posting a system message in the
-anchor conversation; wake ownership does not transfer to other agents.
-To notify another human or agent later, schedule your own reminder and
-@mention them when it fires.
+function buildCurrentConversationGuide(ctx = {}) {
+  const { scope, recipientRole, goalAuthority } = selectGoalTaskProtocolOverlays(ctx);
+  const name = readConversationName(ctx);
+  const lines = [];
+
+  if (scope === 'group') {
+    const groupLabel = name ? `#${name}` : 'this group chat';
+    if (goalAuthority) {
+      const roleLabel = recipientRole === 'owner' ? 'owner' : 'admin';
+      lines.push(`You are in a group chat named ${groupLabel}. You are the ${roleLabel}.`);
+    } else {
+      lines.push(`You are in a group chat named ${groupLabel}. You are a member of the group.`);
+      lines.push('You are not the group admin.');
+    }
+  } else {
+    lines.push('You are in a one-on-one conversation with a human user.');
+    lines.push('The incoming message is from a human user.');
+  }
+  return lines.join('\n');
+}
 
-Use \`ticlawk reminder schedule\` rather than runtime-native wake or
-cron tools for user-visible reminders, so reminders stay author-owned,
-persistent, observable, snoozable, updatable, and cancelable in
-Ticlawk. If you expect a wait to finish within about 1 minute, you may
-briefly poll instead.
+function buildReadInstructions(ctx = {}) {
+  const files = buildReadFileNames(ctx);
+  const memoryFiles = files.filter((name) => name === 'MEMORY.md');
+  const handbookFiles = files.filter((name) => name !== 'MEMORY.md');
+  const memoryList = memoryFiles.map((name, index) => `${index + 1}. \`${name}\``).join('\n');
+  const handbookList = handbookFiles.map((name, index) => `${index + 1}. \`${name}\``).join('\n');
+  return `To reply to the user or group, use \`ticlawk message send --target <target>\`. Normal assistant output is private and is not sent to the user. Details are in \`COMMUNICATION.md\`.
 
-When a reminder already exists, prefer \`ticlawk reminder snooze\` to
-push it later, \`ticlawk reminder update\` to change its meaning or
-schedule, and \`ticlawk reminder cancel\` only when it is truly no
-longer needed.
+Read this file every time before acting because it may be updated:
+${memoryList}
 
-## Message Notifications
+Read these files if you haven't already. Otherwise, skip:
+${handbookList}`;
+}
 
-While you are busy (executing tools, thinking, etc.), new messages may arrive. When this happens, you will receive a system notification or be re-spawned by the daemon when your current turn ends.
+function buildReadFileNames(ctx = {}) {
+  const { scope, goalAuthority } = selectGoalTaskProtocolOverlays(ctx);
+  const reason = readDeliveryReason(ctx);
+  const taskContext = hasTaskContext(ctx) || reason === 'assignment';
+  const goalSurface = hasGoalSurfaceContext(ctx);
+  const docs = [
+    'MEMORY.md',
+    'BASICS.md',
+    'COMMUNICATION.md',
+    'COLLABORATION.md',
+  ];
+
+  if (scope === 'dm') {
+    docs.push('GOAL_TASK_CORE.md', 'GOAL_AUTHORITY.md', 'DM_SCOPE.md', 'SURFACES.md');
+    return unique(docs);
+  }
+
+  if (goalAuthority) {
+    docs.push('GOAL_TASK_CORE.md', 'GOAL_AUTHORITY.md', 'GROUP_ADMIN_SCOPE.md', 'SURFACES.md');
+    return unique(docs);
+  }
+
+  if (taskContext) {
+    docs.push('GOAL_TASK_CORE.md', 'TASK_WORKER.md', 'GROUP_MEMBER_SCOPE.md');
+  }
+  if (goalSurface) docs.push('SURFACES.md');
+  return unique(docs);
+}
 
-How to handle these:
-- Finish your current step before pivoting unless the new message clearly supersedes the current work.
-- If the new message is higher priority, you may pivot to it. If not, continue your current work.
-`;
+function unique(values) {
+  return [...new Set(values)];
+}
 
 export function buildStandingPrompt(_ctx = {}) {
-  // The current prompt is identity-free. Hook signature reserved so we
-  // can later compose in agent handle / known group list / etc.
-  return STANDING_PROMPT;
+  return promptBlock(buildBaseStandingPrompt(_ctx));
 }
 
+const STANDING_PROMPT = buildStandingPrompt();
+
 export { STANDING_PROMPT };

package/src/runtimes/_shared/wake-prompt.mjs

@@ -0,0 +1,261 @@
+/**
+ * Per-turn inbound wake prompt builder.
+ *
+ * Standing prompts define durable runtime behavior. This module owns the
+ * dynamic wrapper around each delivered Ticlawk message: who sent it, why it
+ * reached this agent, the exact reply target, and any attached goal/task/quote
+ * context for this turn.
+ */
+
+function promptBlock(text) {
+  return text.trim();
+}
+
+export function buildEnvelopeTarget(msg) {
+  const convType = msg.conversation_type || 'dm';
+  const conversationId = msg.conversation_id || '';
+  const senderHandle = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || '';
+  if (convType === 'dm') {
+    return senderHandle ? `dm:@${senderHandle}` : `dm:${conversationId}`;
+  }
+  if (convType === 'thread') {
+    const groupName = msg.conversation_name || conversationId;
+    const replyRoot = msg.thread_root_message_id || msg.message_id || '';
+    return `#${groupName}:${replyRoot}`;
+  }
+  // group
+  const groupName = msg.conversation_name || conversationId;
+  return `#${groupName}`;
+}
+
+export function buildDebugTaskSuffix(msg) {
+  if (msg.task_number == null) return '';
+  const status = msg.task_status || 'todo';
+  const parts = [`task #${msg.task_number} status=${status}`];
+  if (msg.task_assignee_agent_id || msg.task_assignee_user_id) {
+    const t = msg.task_assignee_type || 'agent';
+    const id = msg.task_assignee_agent_id || msg.task_assignee_user_id;
+    parts.push(`assignee=${t}:${id}`);
+  }
+  if (msg.task_title) {
+    parts.push(`title=${JSON.stringify(msg.task_title)}`);
+  }
+  return ` [${parts.join(' ')}]`;
+}
+
+export function buildDebugReactionsSuffix(msg) {
+  const entries = Array.isArray(msg.reactions_summary) ? msg.reactions_summary : [];
+  if (entries.length === 0) return '';
+  return ` [reactions: ${entries.join('; ')}]`;
+}
+
+function normalizeDeliveryReasonForPrompt(reason) {
+  return reason === 'thread_follow' ? 'reply_follow' : reason;
+}
+
+export function buildDebugEnvelopeHeader(msg) {
+  const target = buildEnvelopeTarget(msg);
+  const msgId = msg.id || msg.message_id || '';
+  const seq = msg.seq != null ? msg.seq : '';
+  const time = msg.created_at || new Date().toISOString();
+  const type = msg.sender_type || 'human';
+  const sender = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || 'unknown';
+  const convType = msg.conversation_type || 'dm';
+  const displayReason = normalizeDeliveryReasonForPrompt(msg.reason || '');
+  const reason = displayReason ? ` reason=${displayReason}` : '';
+  const recipientRole = String(msg.recipient_conversation_role || msg.recipient_role || '').trim().toLowerCase();
+  const role = convType === 'group' && recipientRole ? ` role=${recipientRole}` : '';
+  return `[target=${target} msg=${msgId} seq=${seq} time=${time} type=${type}${reason}${role}] @${sender}:`;
+}
+
+export const buildEnvelopeHeader = buildDebugEnvelopeHeader;
+
+export function buildGroupContextBlock(msg) {
+  // Only useful in groups — DMs don't need group-purpose context.
+  if ((msg.conversation_type || 'dm') !== 'group') return '';
+  const lines = [];
+  const name = msg.conversation_name || msg.conversation_display_name || '';
+  if (name) lines.push(`Group: #${name}`);
+  const description = (msg.conversation_description || '').trim();
+  if (description) lines.push(`Purpose: ${description}`);
+  if (lines.length === 0) return '';
+  return lines.join('\n');
+}
+
+export function buildCharterBlock(msg) {
+  const charter = (msg.conversation_charter || '').trim();
+  if (!charter) return '';
+  const authorityLine = hasGoalAuthority(msg)
+    ? 'Use it as the current goal and role spec. If the owner appears to change the goal, read GOAL_AUTHORITY.md and follow the goal-change flow before updating state.'
+    : 'Use it as current group goal and role context. The group admin owns charter and dashboard changes unless they explicitly delegate them.';
+  return promptBlock(`
+[conversation_goal]
+Current charter for this conversation:
+${charter}
+
+${authorityLine}
+[/conversation_goal]
+`);
+}
+
+export function buildGoalStateBlock(msg) {
+  if ((msg.conversation_charter || '').trim()) return '';
+  const convType = msg.conversation_type || 'dm';
+  const subject = convType === 'group' ? 'This group' : 'This conversation';
+  const authorityLine = hasGoalAuthority(msg)
+    ? 'If this message may be starting, clarifying, or changing an ongoing goal, read GOAL_AUTHORITY.md "Goal Setup When No Specific Goal Exists" and follow it to propose/confirm the goal before writing charter/dashboard state. If it is clearly one-off, answer normally.'
+    : 'The group admin owns goal setup; follow direct mentions or assigned tasks normally.';
+  return promptBlock(`
+[conversation_goal]
+${subject} does not have a chartered goal yet.
+${authorityLine}
+[/conversation_goal]
+`);
+}
+
+function hasGoalAuthority(msg) {
+  const convType = msg.conversation_type || 'dm';
+  if (convType !== 'group') return true;
+  if (msg.recipient_is_conversation_admin === true) return true;
+  const recipientRole = String(msg.recipient_conversation_role || msg.recipient_role || '').trim().toLowerCase();
+  return recipientRole === 'admin' || recipientRole === 'owner';
+}
+
+export function buildQuoteBlock(msg, target = '') {
+  const meta = msg.message_metadata || msg.metadata || null;
+  const quote = meta && typeof meta === 'object' ? meta.quote : null;
+  if (!quote || typeof quote !== 'object') return '';
+  const kind = String(quote.kind || '').trim();
+  const ref = String(quote.ref || '').trim();
+  const snippet = String(quote.snippet || '').trim();
+  if (!kind || !ref) return '';
+  const fetchHint = kind === 'briefing'
+    ? `ticlawk briefing get ${ref}`
+    : kind === 'dashboard'
+      ? `ticlawk dashboard get --conversation-id ${ref}`
+      : kind === 'message'
+        ? `ticlawk message read --target ${JSON.stringify(target)} --around ${ref}`
+        : '';
+  const lines = [
+    `The incoming message is a reply to a ${kind}.`,
+    `Referenced ${kind}: \`${ref}\``,
+  ];
+  if (snippet) lines.push(`Quoted snippet: ${snippet}`);
+  if (fetchHint) lines.push(`Fetch it if needed: \`${fetchHint}\``);
+  return lines.join('\n');
+}
+
+function senderDescription(msg) {
+  const type = msg.sender_type === 'agent' ? 'an agent' : 'a human user';
+  const sender = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || '';
+  return sender ? `@${sender}, ${type}` : type;
+}
+
+function senderFactDescription(msg) {
+  const type = msg.sender_type === 'agent' ? 'agent' : 'human user';
+  const sender = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || '';
+  return sender ? `@${sender}, ${type}` : type;
+}
+
+function conversationLabel(msg, target) {
+  const convType = msg.conversation_type || 'dm';
+  if (convType === 'dm') return 'a one-on-one conversation';
+  return target || 'this group';
+}
+
+function buildMessageSummary(msg, target) {
+  const convType = msg.conversation_type || 'dm';
+  const reason = normalizeDeliveryReasonForPrompt(msg.reason || '');
+  const sender = senderDescription(msg);
+  const senderFact = senderFactDescription(msg);
+  const where = conversationLabel(msg, target);
+
+  if (convType === 'dm') {
+    return `This is a one-on-one message from ${sender}.`;
+  }
+  if (reason === 'assignment') {
+    return `This message assigns or routes work to you in ${where}.\nSender: ${senderFact}`;
+  }
+  if (reason === 'ambient') {
+    return `Sender: ${senderFact}`;
+  }
+  if (reason === 'mention') {
+    return `You were mentioned in ${where} by ${sender}.`;
+  }
+  if (reason === 'reply_follow') {
+    return `This is a reply in ${where} from ${sender}.`;
+  }
+  if (reason === 'manual') {
+    return `This is a manual wake-up or reminder for ${where}.\nSource: ${senderFact}`;
+  }
+  return `This is a message in ${where} from ${sender}.`;
+}
+
+function buildTaskDetailsBlock(msg) {
+  if (msg.task_number == null) return '';
+  const lines = [`Task #${msg.task_number} is currently \`${msg.task_status || 'todo'}\`.`];
+  if (msg.task_title) lines.push(`Task title: ${msg.task_title}`);
+  if (msg.task_assignee_agent_id || msg.task_assignee_user_id) {
+    const t = msg.task_assignee_type || 'agent';
+    const id = msg.task_assignee_agent_id || msg.task_assignee_user_id;
+    lines.push(`Assignee: ${t} \`${id}\``);
+  }
+  return lines.join('\n');
+}
+
+function buildReactionsBlock(msg) {
+  const entries = Array.isArray(msg.reactions_summary) ? msg.reactions_summary : [];
+  if (entries.length === 0) return '';
+  return `Recent reactions: ${entries.join('; ')}`;
+}
+
+function buildContentBlock(rawText) {
+  const text = String(rawText || '').trim();
+  if (!text) return '';
+  return promptBlock(`
+Content:
+${text}
+`);
+}
+
+// Wrap each per-turn message with the concrete dynamic context for this
+// delivery. Durable communication rules live in COMMUNICATION.md; this block
+// only carries the current message and its exact reply target.
+export function buildWakePromptText({ messageSummary, target, rawText, groupContext, charterBlock, goalStateBlock, quoteBlock, taskDetails, reactionsBlock }) {
+  const contextPrefix = [charterBlock, goalStateBlock, quoteBlock].filter(Boolean).join('\n\n');
+  const prefix = contextPrefix ? `${contextPrefix}\n\n` : '';
+  const detailBlocks = [
+    messageSummary,
+    `Reply target: \`${target}\``,
+    groupContext,
+    taskDetails ? `Task details:\n${taskDetails}` : '',
+    reactionsBlock,
+    buildContentBlock(rawText),
+  ].filter(Boolean).join('\n\n');
+  return promptBlock(`
+${prefix}New message received:
+
+${detailBlocks}
+`);
+}
+
+export function buildInboundWakePrompt(msg) {
+  const rawText = msg.text || '';
+  const baseHeader = buildDebugEnvelopeHeader(msg);
+  const header = baseHeader + buildDebugTaskSuffix(msg) + buildDebugReactionsSuffix(msg);
+  const target = buildEnvelopeTarget(msg);
+  const groupContext = buildGroupContextBlock(msg);
+  const charterBlock = buildCharterBlock(msg);
+  const goalStateBlock = buildGoalStateBlock(msg);
+  const quoteBlock = buildQuoteBlock(msg, target);
+  const messageSummary = buildMessageSummary(msg, target);
+  const taskDetails = buildTaskDetailsBlock(msg);
+  const reactionsBlock = buildReactionsBlock(msg);
+  const text = buildWakePromptText({ messageSummary, target, rawText, groupContext, charterBlock, goalStateBlock, quoteBlock, taskDetails, reactionsBlock });
+  return {
+    header,
+    target,
+    text,
+    rawText,
+  };
+}