ticlawk 0.1.16-dev.9 → 0.1.17-dev.1

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

@@ -0,0 +1,268 @@
+/**
+ * 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 conversationId = msg.conversation_id || '';
+  // The goal lane (transition deliveries) executes against the charter; its
+  // per-step instructions come from the goal-step prompt, so here the charter
+  // is just the goal/success spec. The chat lane must NOT run the loop — it
+  // only signals goal changes to wake the goal lane.
+  const authorityLine = msg.reason === 'transition'
+    ? 'This is the goal and success spec for this conversation. Run the current step against it.'
+    : hasGoalAuthority(msg)
+      ? `This is the goal the backend goal lane is already driving. Handle the incoming message and reply; do not run a goal loop or start gap/execution work yourself. If this message sets, clarifies, or changes the goal, update the charter and then run \`ticlawk goal changed --conversation ${conversationId}\` to wake the goal lane. See GOAL_AUTHORITY.md.`
+      : '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,
+  };
+}

package/src/runtimes/claude-code/index.mjs

@@ -23,12 +23,14 @@ import {
 } from './session.mjs';
 import { discoverSessions } from './transcripts.mjs';
 import { buildImageMessageFromInbound } from '../../core/media/inbound.mjs';
-import { emitWorkerEvent } from '../../core/events/worker-events.mjs';
+import { emitWorkerEventBestEffort } from '../../core/events/worker-events.mjs';
 import {
   shouldStreamRuntime,
   reportSubprocessFailure,
   terminalRuntimeFailure,
   updateBindingRuntimeMeta,
+  resolveRuntimeSessionScope,
+  buildRuntimeSessionMetaPatch,
 } from '../../core/runtime-support.mjs';
 
 export const claudeCodeRuntime = {
@@ -130,31 +132,35 @@ export const claudeCodeRuntime = {
       ? await buildImageMessageFromInbound(inbound, 'claude-code')
       : inbound.text;
 
-    // shouldRotate=true means meta.sessionId is missing or invalidated.
+    // shouldRotate=true means this conversation has no runtime session
+    // yet, or the agent was reset and all scoped sessions are invalid.
     // We pass sessionId=null so `claude` creates a fresh session; the new
     // session_id is captured from stream events and persisted below.
     // Unifying rotate + non-rotate into one path means the standing prompt
     // is always attached, so the agent uses the CLI to reply on every
     // turn — including the first.
-    const shouldRotate = !meta.sessionId || meta.rotatePending;
-    const targetSessionId = shouldRotate ? null : meta.sessionId;
-    const errEventSessionId = meta.sessionId || binding.id;
+    const sessionScope = resolveRuntimeSessionScope(meta, inbound);
+    const targetSessionId = sessionScope.shouldRotate ? null : sessionScope.sessionId;
+    const errEventSessionId = targetSessionId || binding.id;
 
     try {
       const claudePath = requireClaudePath(runtimeClaudePath);
       const claudeVersion = getClaudeCodeRuntimeHealth(claudePath).version || meta.claudeVersion || null;
       const agentEnv = buildAgentRuntimeEnv({
         agentId: binding.id,
-        sessionId: meta.sessionId,
+        sessionId: targetSessionId,
         hostId: binding.runtime_host_id,
+        conversationId: inbound.conversationId,
+        messageId: inbound.messageId,
+        target: inbound.envelopeTarget,
       });
-      const appendSystemPrompt = buildStandingPrompt({ agentId: binding.id });
+      const appendSystemPrompt = buildStandingPrompt({ agentId: binding.id, inbound });
       const result = shouldStreamRuntime(this.name, this)
         ? await this.runTurnStream({ sessionId: targetSessionId, projectDir, claudePath, agentEnv }, message, {
             appendSystemPrompt,
             onEvent: async (event) => {
               if (event?.type === 'turn.started') {
-                await emitWorkerEvent({
+                emitWorkerEventBestEffort({
                   adapter,
                   binding,
                   agent: this.name,
@@ -167,34 +173,19 @@ export const claudeCodeRuntime = {
                   },
                   logger: ctx.logger,
                 });
-              } else if (event?.type === 'message.delta' && event.text) {
-                await emitWorkerEvent({
-                  adapter,
-                  binding,
-                  agent: this.name,
-                  sessionId: event.sessionId || targetSessionId || binding.id,
-                  cwd: projectDir,
-                  replyToMessageId: inbound.messageId || null,
-                  event: {
-                    hook_event_name: 'worker.message.delta',
-                    worker_event_name: 'worker.message.delta',
-                    delta: event.text,
-                  },
-                  logger: ctx.logger,
-                });
               }
             },
           })
         : await this.runTurn({ sessionId: targetSessionId, projectDir, claudePath, agentEnv }, message, { appendSystemPrompt });
       const nextBinding = await updateBindingRuntimeMeta(ctx, binding, {
-        sessionId: result?.sessionId || meta.sessionId,
+        ...buildRuntimeSessionMetaPatch(meta, sessionScope, {
+          sessionId: result?.sessionId,
+        }),
         runtimePath: claudePath,
         claudePath,
         claudeVersion,
-        rotatePending: false,
-        lastRotatedAt: shouldRotate ? new Date().toISOString() : meta.lastRotatedAt,
       }, { status: 'connected' });
-      await emitWorkerEvent({
+      emitWorkerEventBestEffort({
         adapter,
         binding: nextBinding,
         agent: this.name,
@@ -209,7 +200,7 @@ export const claudeCodeRuntime = {
       });
       return true;
     } catch (err) {
-      await emitWorkerEvent({
+      emitWorkerEventBestEffort({
         adapter,
         binding,
         agent: this.name,
@@ -239,24 +230,6 @@ export const claudeCodeRuntime = {
     }
   },
 
-  async reconcileAfterRestart(binding, ctx) {
-    const meta = binding.runtimeMeta || {};
-    await emitWorkerEvent({
-      adapter: ctx.adapter,
-      binding,
-      agent: this.name,
-      sessionId: meta.sessionId || binding.id,
-      cwd: ensureAgentHome(binding.id) || '',
-      event: {
-        hook_event_name: 'Stop',
-        worker_event_name: 'worker.turn.complete',
-        reason: 'connector.restart.reconcile',
-      },
-      logger: ctx.logger,
-    });
-    return 1;
-  },
-
   // Friendly display name for a CC session (encoded project path →
   // last meaningful segment). Used when materializing a binding.
   formatDisplayName(session) {

package/src/runtimes/claude-code/session.mjs

@@ -231,23 +231,19 @@ export function streamCCPrompt({
     let seenTurnStart = false;
     let activeSessionId = sessionId || null;
     let finalText = '';
-    let eventChain = Promise.resolve();
 
     const emit = (event) => {
       if (typeof onEvent !== 'function') return;
-      eventChain = eventChain
+      void Promise.resolve()
         .then(() => onEvent(event))
         .catch(() => {});
-      return eventChain;
     };
 
     const settle = (fn, value) => {
       if (settled) return;
       settled = true;
       if (timeout) clearTimeout(timeout);
-      eventChain
-        .catch(() => {})
-        .finally(() => fn(value));
+      fn(value);
     };
 
     const parseLine = (line) => {
@@ -267,7 +263,6 @@ export function streamCCPrompt({
         const deltaText = parsed.event?.delta?.text;
         if (typeof deltaText === 'string' && deltaText) {
           finalText += deltaText;
-          emit({ type: 'message.delta', sessionId: activeSessionId, text: deltaText });
         }
         return;
       }