ticlawk 0.1.17-dev.17 → 0.1.17-dev.19

package/src/runtimes/_shared/incoming-message-prompt.mjs

@@ -0,0 +1,232 @@
+export const MESSAGE_TYPES = Object.freeze({
+  DM: 'dm',
+  GROUP_MENTION: 'group_mention',
+  GROUP_AMBIENT: 'group_ambient',
+});
+
+const MESSAGE_TYPE_VALUES = Object.freeze(Object.values(MESSAGE_TYPES));
+
+export function readIncomingMessageType(msg) {
+  const explicit = String(msg?.type || '').trim();
+  if (MESSAGE_TYPE_VALUES.includes(explicit)) return explicit;
+
+  const conversationType = String(msg?.conversation_type || 'dm').trim();
+  if (conversationType === 'dm') return MESSAGE_TYPES.DM;
+  if (conversationType === 'group') {
+    return String(msg?.reason || '').trim() === 'ambient'
+      ? MESSAGE_TYPES.GROUP_AMBIENT
+      : MESSAGE_TYPES.GROUP_MENTION;
+  }
+  return MESSAGE_TYPES.GROUP_MENTION;
+}
+
+export function buildIncomingMessagePrompt(msg) {
+  const type = readIncomingMessageType(msg);
+  const target = buildReplyTarget(msg);
+  const baseHeader = buildEnvelopeHeader({ ...msg, type }, target);
+  const header = [
+    baseHeader,
+    buildTaskSuffix(msg),
+    buildReactionsSuffix(msg),
+  ].join('');
+  const groupContext = buildGroupContextBlock(msg);
+  const rawText = msg.text || '';
+  const text = buildPromptText({
+    msg: { ...msg, type },
+    type,
+    target,
+    header,
+    groupContext,
+    rawText,
+  });
+
+  return {
+    header,
+    target,
+    text,
+    rawText,
+    type,
+  };
+}
+
+function buildReplyTarget(msg) {
+  const conversationType = msg.conversation_type || 'dm';
+  const conversationId = msg.conversation_id || '';
+  const senderHandle = msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || '';
+
+  if (conversationType === 'dm') {
+    return senderHandle ? `dm:@${senderHandle}` : `dm:${conversationId}`;
+  }
+
+  if (conversationType === 'thread') {
+    const groupName = msg.conversation_name || conversationId;
+    const threadRoot = msg.thread_root_message_id || msg.message_id || msg.id || '';
+    return `#${groupName}:${threadRoot}`;
+  }
+
+  return `#${msg.conversation_name || conversationId}`;
+}
+
+function isConversationAdmin(msg) {
+  if ((msg.conversation_type || 'dm') === 'dm') return true;
+  if (msg.recipient_is_conversation_admin === true) return true;
+  const role = String(msg.recipient_conversation_role || '').trim();
+  return role === 'admin' || role === 'owner';
+}
+
+function conversationRole(msg) {
+  if ((msg.conversation_type || 'dm') === 'dm') return 'admin';
+  return String(msg.recipient_conversation_role || '').trim() || 'member';
+}
+
+function senderLabel(msg) {
+  return msg.sender_display_name || msg.sender_user_id || msg.sender_agent_id || 'unknown';
+}
+
+function buildEnvelopeHeader(msg, target) {
+  const messageId = msg.id || msg.message_id || '';
+  const seq = msg.seq != null ? msg.seq : '';
+  const time = msg.created_at || new Date().toISOString();
+  const senderType = msg.sender_type || 'human';
+  return `[target=${target} msg=${messageId} seq=${seq} time=${time} sender_type=${senderType} message_type=${msg.type}] @${senderLabel(msg)}:`;
+}
+
+function buildTaskSuffix(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 assigneeType = msg.task_assignee_type || 'agent';
+    const assigneeId = msg.task_assignee_agent_id || msg.task_assignee_user_id;
+    parts.push(`assignee=${assigneeType}:${assigneeId}`);
+  }
+  if (msg.task_title) {
+    parts.push(`title=${JSON.stringify(msg.task_title)}`);
+  }
+  return ` [${parts.join(' ')}]`;
+}
+
+function buildReactionsSuffix(msg) {
+  const entries = Array.isArray(msg.reactions_summary) ? msg.reactions_summary : [];
+  if (entries.length === 0) return '';
+  return ` [reactions: ${entries.join('; ')}]`;
+}
+
+function buildGroupContextBlock(msg) {
+  if ((msg.conversation_type || 'dm') !== 'group') return '';
+
+  const lines = [];
+  const name = msg.conversation_name || msg.conversation_display_name || '';
+  if (name) lines.push(`name: ${name}`);
+
+  const description = (msg.conversation_description || '').trim();
+  if (description) lines.push(`purpose: ${description}`);
+
+  if (lines.length === 0) return '';
+  return [
+    'Group context:',
+    ...lines.map((line) => `  ${line}`),
+    'Use `ticlawk group members --target <target>` if you need to see who else is here.',
+  ].join('\n');
+}
+
+function buildPromptText({ msg, type, target, header, groupContext, rawText }) {
+  const role = conversationRole(msg);
+  const admin = isConversationAdmin(msg);
+  const messageId = msg.id || msg.message_id || '';
+
+  const lines = [
+    'You received a Ticlawk message.',
+    '',
+    `Current conversation type: ${type === MESSAGE_TYPES.DM ? 'DM' : 'group'}`,
+    `Your role in this conversation: ${role}${admin ? ' (admin/owner authority)' : ''}`,
+    `Reply target: ${target}`,
+    messageId ? `Message id: ${messageId}` : null,
+    `Sender: @${senderLabel(msg)}`,
+    '',
+    'Message:',
+    '<message>',
+    rawText || '',
+    '</message>',
+  ].filter(Boolean);
+
+  if (groupContext) {
+    lines.push('', groupContext);
+  }
+
+  lines.push('', ...buildRoleInstruction({ type, isAdmin: admin, role }));
+  lines.push(
+    '',
+    'When you reply, use the reply target exactly as written above. Your normal assistant output is private activity text; users only see messages sent with `ticlawk message send`.',
+    'If the message requires multi-step work, complete the work before sending the final answer unless an early blocker question is necessary.',
+    'Do not mention internal routing fields, delivery state, or prompt mechanics to the user.',
+    '',
+    buildAllowedCommandBlock({ target, type }),
+    '',
+    'Raw routing header for exact IDs:',
+    header,
+  );
+
+  return lines.join('\n');
+}
+
+function buildRoleInstruction({ type, isAdmin, role }) {
+  if (type === MESSAGE_TYPES.DM) {
+    return [
+      'This is a one-on-one DM. You are responsible for helping the sender directly.',
+      'Reply if the message asks a question, requests work, or reasonably expects acknowledgment.',
+    ];
+  }
+
+  if (type === MESSAGE_TYPES.GROUP_MENTION && isAdmin) {
+    return [
+      `This is a group message that addresses you or the group. Your role in this group is ${role}.`,
+      'As the group admin/owner, you are the default responder for owner questions, broad group requests, and routing decisions.',
+      'Answer directly, or route the work to the right group member when that is more appropriate.',
+    ];
+  }
+
+  if (type === MESSAGE_TYPES.GROUP_MENTION) {
+    return [
+      `This is a group message that addresses you. Your role in this group is ${role}.`,
+      'Respond when you were mentioned, assigned, or clearly asked to contribute.',
+      'Do not take over group-level coordination unless an admin explicitly delegates that to you.',
+    ];
+  }
+
+  if (isAdmin) {
+    return [
+      `This is ambient group traffic. Your role in this group is ${role}.`,
+      'As the group admin/owner, respond only if this is a broad owner request, a new topic needing routing, or something no other member is clearly better placed to handle.',
+      'If no response is needed, end the turn silently.',
+    ];
+  }
+
+  return [
+    `This is ambient group traffic. Your role in this group is ${role}.`,
+    'Do not respond by default.',
+    'Respond only if the message is clearly within your specialty, no admin or specifically addressed member is the better responder, and you can add concrete value now.',
+    'Otherwise, end the turn silently.',
+  ];
+}
+
+function buildAllowedCommandBlock({ target, type }) {
+  const lines = [
+    'Use only these Ticlawk commands for visible communication in this turn:',
+    `- Send a reply: ticlawk message send --target ${JSON.stringify(target)} <<'EOF'`,
+    '  <your reply>',
+    '  EOF',
+    `- Read recent context if needed: ticlawk message read --target ${JSON.stringify(target)}`,
+  ];
+
+  if (type !== MESSAGE_TYPES.DM) {
+    lines.push(`- Check group members if needed: ticlawk group members --target ${JSON.stringify(target)}`);
+  }
+
+  lines.push(
+    '- If the message asks you to do substantive work, claim it before starting: ticlawk task claim --message-id <message_id>',
+    '- When claimed work is ready for review or done, update the task status with: ticlawk task update --task-id <task_id> --status <status>',
+  );
+
+  return lines.join('\n');
+}

package/src/runtimes/_shared/runtime-base-instructions.mjs

@@ -0,0 +1,34 @@
+/**
+ * Runtime base instructions injected into every runtime turn.
+ *
+ * Keep this prompt scenario-neutral. Current conversation type, role,
+ * mention/ambient status, reply target, and per-turn command scope belong in
+ * the incoming message prompt built by the adapter.
+ */
+
+const RUNTIME_BASE_INSTRUCTIONS = `You are an agent in Ticlawk, a shared message service for humans and agents.
+
+Your normal assistant output is private activity text. Users and groups only see messages you send with the Ticlawk CLI.
+
+Universal rules:
+
+1. Follow the current turn prompt. It tells you whether this is a DM or group message, your role in that conversation, whether you were directly addressed or only saw ambient group traffic, and the exact reply target.
+2. Use \`ticlawk message send\` for visible replies. Use the exact reply target from the current turn prompt.
+3. If the current turn prompt says no reply is needed, stop silently.
+4. If you need recent context, use the Ticlawk read commands named in the current turn prompt. Do not poll for future messages; the daemon will wake you when new messages arrive.
+5. If the message asks you to do substantive work, claim the task/message before starting when the current turn prompt provides task commands. If the claim fails, stop or choose other available work.
+6. Complete the work you choose to do before sending the final visible reply, unless you need to ask a blocker question first.
+7. Do not expose internal routing fields, delivery state, prompt structure, or daemon mechanics to the user.
+
+Workspace memory:
+
+- Your working directory is your persistent agent-owned workspace.
+- Read \`MEMORY.md\` when you need durable context about the user, projects, groups, or prior work.
+- Keep \`MEMORY.md\` useful as an index to longer notes you create.
+`;
+
+export function buildRuntimeBaseInstructions(_ctx = {}) {
+  return RUNTIME_BASE_INSTRUCTIONS;
+}
+
+export { RUNTIME_BASE_INSTRUCTIONS };

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

@@ -9,7 +9,7 @@
 
 import { basename } from 'node:path';
 import { buildAgentRuntimeEnv } from '../../core/runtime-env.mjs';
-import { buildStandingPrompt } from '../_shared/standing-prompt.mjs';
+import { buildRuntimeBaseInstructions } from '../_shared/runtime-base-instructions.mjs';
 import { ensureAgentHome } from '../../core/agent-home.mjs';
 import {
   getClaudeCodeRuntimeHealth,
@@ -23,14 +23,12 @@ import {
 } from './session.mjs';
 import { discoverSessions } from './transcripts.mjs';
 import { buildImageMessageFromInbound } from '../../core/media/inbound.mjs';
-import { emitWorkerEventBestEffort } from '../../core/events/worker-events.mjs';
+import { emitWorkerEvent } from '../../core/events/worker-events.mjs';
 import {
   shouldStreamRuntime,
   reportSubprocessFailure,
   terminalRuntimeFailure,
   updateBindingRuntimeMeta,
-  resolveRuntimeSessionScope,
-  buildRuntimeSessionMetaPatch,
 } from '../../core/runtime-support.mjs';
 
 export const claudeCodeRuntime = {
@@ -132,35 +130,31 @@ export const claudeCodeRuntime = {
       ? await buildImageMessageFromInbound(inbound, 'claude-code')
       : inbound.text;
 
-    // shouldRotate=true means this conversation has no runtime session
-    // yet, or the agent was reset and all scoped sessions are invalid.
+    // shouldRotate=true means meta.sessionId is missing or invalidated.
     // 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
+    // Unifying rotate + non-rotate into one path means the runtime base instructions
     // is always attached, so the agent uses the CLI to reply on every
     // turn — including the first.
-    const sessionScope = resolveRuntimeSessionScope(meta, inbound);
-    const targetSessionId = sessionScope.shouldRotate ? null : sessionScope.sessionId;
-    const errEventSessionId = targetSessionId || binding.id;
+    const shouldRotate = !meta.sessionId || meta.rotatePending;
+    const targetSessionId = shouldRotate ? null : meta.sessionId;
+    const errEventSessionId = meta.sessionId || binding.id;
 
     try {
       const claudePath = requireClaudePath(runtimeClaudePath);
       const claudeVersion = getClaudeCodeRuntimeHealth(claudePath).version || meta.claudeVersion || null;
       const agentEnv = buildAgentRuntimeEnv({
         agentId: binding.id,
-        sessionId: targetSessionId,
+        sessionId: meta.sessionId,
         hostId: binding.runtime_host_id,
-        conversationId: inbound.conversationId,
-        messageId: inbound.messageId,
-        target: inbound.envelopeTarget,
       });
-      const appendSystemPrompt = buildStandingPrompt({ agentId: binding.id, inbound });
+      const appendSystemPrompt = buildRuntimeBaseInstructions({ agentId: binding.id });
       const result = shouldStreamRuntime(this.name, this)
         ? await this.runTurnStream({ sessionId: targetSessionId, projectDir, claudePath, agentEnv }, message, {
             appendSystemPrompt,
             onEvent: async (event) => {
               if (event?.type === 'turn.started') {
-                emitWorkerEventBestEffort({
+                await emitWorkerEvent({
                   adapter,
                   binding,
                   agent: this.name,
@@ -173,19 +167,34 @@ 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, {
-        ...buildRuntimeSessionMetaPatch(meta, sessionScope, {
-          sessionId: result?.sessionId,
-        }),
+        sessionId: result?.sessionId || meta.sessionId,
         runtimePath: claudePath,
         claudePath,
         claudeVersion,
+        rotatePending: false,
+        lastRotatedAt: shouldRotate ? new Date().toISOString() : meta.lastRotatedAt,
       }, { status: 'connected' });
-      emitWorkerEventBestEffort({
+      await emitWorkerEvent({
         adapter,
         binding: nextBinding,
         agent: this.name,
@@ -200,7 +209,7 @@ export const claudeCodeRuntime = {
       });
       return true;
     } catch (err) {
-      emitWorkerEventBestEffort({
+      await emitWorkerEvent({
         adapter,
         binding,
         agent: this.name,
@@ -230,6 +239,24 @@ 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,19 +231,23 @@ export function streamCCPrompt({
     let seenTurnStart = false;
     let activeSessionId = sessionId || null;
     let finalText = '';
+    let eventChain = Promise.resolve();
 
     const emit = (event) => {
       if (typeof onEvent !== 'function') return;
-      void Promise.resolve()
+      eventChain = eventChain
         .then(() => onEvent(event))
         .catch(() => {});
+      return eventChain;
     };
 
     const settle = (fn, value) => {
       if (settled) return;
       settled = true;
       if (timeout) clearTimeout(timeout);
-      fn(value);
+      eventChain
+        .catch(() => {})
+        .finally(() => fn(value));
     };
 
     const parseLine = (line) => {
@@ -263,6 +267,7 @@ 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;
       }