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

package/src/adapters/ticlawk/index.mjs

@@ -10,13 +10,16 @@ import { isTerminalRuntimeFailure } from '../../core/runtime-support.mjs';
 import { clearUpdateRequiredState, readUpdateState, setUpdateRequiredState } from '../../core/update-state.mjs';
 import { isManagedInstall, startDetachedSelfUpdate } from '../../core/update.mjs';
 import * as api from './api.mjs';
-import { persistApiCredential } from './credentials.mjs';
+import { persistApiCredential, persistRuntimeCredentials } from './credentials.mjs';
 import { TiclawkWakeClient } from './wake-client.mjs';
+import { buildInboundWakePrompt } from '../../runtimes/_shared/wake-prompt.mjs';
+import { buildGoalStepPrompt } from '../../runtimes/_shared/goal-step-prompt.mjs';
 
 const require = createRequire(import.meta.url);
 const qrcode = require('qrcode-terminal');
 const JOBS_WAKE_DEBOUNCE_MS = 100;
 const BINDINGS_WAKE_DEBOUNCE_MS = 500;
+const CREDENTIALS_WAKE_DEBOUNCE_MS = 500;
 const RECOVERY_AUDIT_INTERVAL_MS = 5 * 60 * 1000;
 const BINDING_AUDIT_INTERVAL_MS = 5 * 60 * 1000;
 const UPDATE_RETRY_COOLDOWN_MS = 15 * 60 * 1000;
@@ -69,98 +72,6 @@ function normalizeInboundMediaAssets(msg) {
     .filter(Boolean);
 }
 
-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 threadRoot = msg.thread_root_message_id || msg.message_id || '';
-    return `#${groupName}:${threadRoot}`;
-  }
-  // group
-  const groupName = msg.conversation_name || conversationId;
-  return `#${groupName}`;
-}
-
-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 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(' ')}]`;
-}
-
-function buildReactionsSuffix(msg) {
-  const entries = Array.isArray(msg.reactions_summary) ? msg.reactions_summary : [];
-  if (entries.length === 0) return '';
-  return ` [reactions: ${entries.join('; ')}]`;
-}
-
-function buildEnvelopeHeader(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';
-  // `reason` tells the agent how this delivery was routed: 'mention'
-  // / 'assignment' = you were directly addressed → respond by default;
-  // 'ambient' = you are in the room and saw it → respond only if
-  // clearly the right responder; 'dm' / 'thread_follow' / 'manual' =
-  // the legacy direct paths. The agent's behaviour split is in the
-  // standing prompt; we just surface the field.
-  const reason = msg.reason ? ` reason=${msg.reason}` : '';
-  return `[target=${target} msg=${msgId} seq=${seq} time=${time} type=${type}${reason}] @${sender}:`;
-}
-
-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(`name: ${name}`);
-  const description = (msg.conversation_description || '').trim();
-  if (description) lines.push(`purpose: ${description}`);
-  if (lines.length === 0) return '';
-  return [
-    'Group context:',
-    ...lines.map((l) => `  ${l}`),
-    'Use `ticlawk group members --target <target>` if you need to see who else is here.',
-  ].join('\n');
-}
-
-// Wrap each per-turn message with an explicit reply instruction so the
-// runtime LLM never has to remember the standing prompt to figure out
-// HOW to reply. Codex in particular treats the developerInstructions as
-// background and ignores the chat-send pattern without this per-turn
-// nudge.
-function buildWakePromptText({ envelopeHeader, target, rawText, groupContext }) {
-  const body = `${envelopeHeader} ${rawText || ''}`.trim();
-  const lines = ['New message received:', '', body];
-  if (groupContext) {
-    lines.push('', groupContext);
-  }
-  lines.push(
-    '',
-    `Respond as appropriate — reply using \`ticlawk message send --target "${target}"\` (body via stdin / heredoc), or take action as needed. Complete ALL your work before stopping.`,
-    'Reply in the channel or create/reply in a thread as appropriate; use each message\'s `target` and `msg` fields to choose the exact target.',
-    '',
-    'IMPORTANT: If the message requires multi-step work (research, code changes, testing), complete ALL steps before stopping. Sending a progress update does NOT mean your task is done — only stop when you have NO more work to do. The daemon will wake you again automatically when new messages arrive.',
-  );
-  return lines.join('\n');
-}
-
 export function normalizeInboundMessage(msg) {
   // Claimed delivery rows carry the recipient agent id; legacy messages
   // (history sync, manual inserts) may still use plain agent_id. Prefer
@@ -169,33 +80,24 @@ export function normalizeInboundMessage(msg) {
   const messageId = msg.id || msg.message_id || null;
   const deliveryId = msg.delivery_id || null;
   const media = normalizeInboundMediaAssets(msg);
-  const rawText = msg.text || '';
   const enriched = { ...msg, id: messageId };
-  const baseHeader = buildEnvelopeHeader(enriched);
-  // Task + reactions suffixes are appended INSIDE the envelope so an
-  // agent can see at a glance whether a message is already claimed and
-  // who has already acknowledged it: `[task #N status=… assignee=…]` +
-  // `[reactions: …]`.
-  const taskSuffix = buildTaskSuffix(enriched);
-  const reactionsSuffix = buildReactionsSuffix(enriched);
-  const header = baseHeader + taskSuffix + reactionsSuffix;
-  const target = buildEnvelopeTarget(enriched);
-  const groupContext = buildGroupContextBlock(enriched);
-  const text = header
-    ? buildWakePromptText({ envelopeHeader: header, target, rawText, groupContext })
-    : rawText;
+  const isTransition = msg.reason === 'transition';
+  // A transition delivery is a goal-lane FSM step, not a chat message: it has
+  // no backing message, so build a per-step goal prompt from its payload.
+  const wakePrompt = isTransition ? buildGoalStepPrompt(enriched) : buildInboundWakePrompt(enriched);
   return {
     bindingId: recipientAgentId,
     messageId,
     deliveryId,
     conversationId: msg.conversation_id || null,
+    lane: isTransition ? 'goal' : 'chat',
     seq: msg.seq != null ? Number(msg.seq) : null,
     senderType: msg.sender_type || 'human',
-    envelopeHeader: header,
-    envelopeTarget: target,
-    text,
-    rawText,
-    action: msg.action || (media.length > 0 ? 'image' : 'task'),
+    envelopeHeader: wakePrompt.header,
+    envelopeTarget: wakePrompt.target,
+    text: wakePrompt.text,
+    rawText: wakePrompt.rawText,
+    action: isTransition ? 'transition' : (msg.action || (media.length > 0 ? 'image' : 'task')),
     media,
     raw: {
       ...msg,
@@ -233,6 +135,19 @@ function getAgentIdFromPayload(payload) {
   return String(payload?.recipient_agent_id || '').trim();
 }
 
+// Two lanes run concurrently per agent (see the lane-aware claim RPC):
+// the goal lane carries FSM transition deliveries (reason='transition'),
+// everything else is the user-facing chat lane. The claim unit and the
+// daemon's in-flight key are the (agent, lane) channel, so a running chat
+// turn and a running goal transition never block each other.
+function getDeliveryLaneFromPayload(payload) {
+  return payload?.reason === 'transition' ? 'goal' : 'chat';
+}
+
+function channelKeyFor(agentId, lane) {
+  return `${agentId}:${lane}`;
+}
+
 // Whitelist of meta keys runtimes actually consume. Anything else in
 // the source row's meta blob is dropped on the floor so stale fields
 // (like the post-Y2 workdir/cwd/projectDir leftovers) can't sneak
@@ -243,6 +158,11 @@ const RUNTIME_META_KEYS = [
   'runtimePath',
   'rotatePending',
   'lastRotatedAt',
+  // Per-lane scoped session maps (keyed by conversation): the chat lane and
+  // the goal-FSM lane keep separate runtime sessions so a transition turn
+  // never resumes a user-chat session or vice-versa.
+  'chatSessions',
+  'goalSessions',
   // claude_code
   'claudePath',
   'claudeVersion',
@@ -359,6 +279,31 @@ function getRuntimeWorkdir(runtimeMeta = {}) {
   return String(runtimeMeta.workdir || runtimeMeta.cwd || runtimeMeta.projectDir || '').trim();
 }
 
+function compareStrings(a, b) {
+  const av = String(a || '');
+  const bv = String(b || '');
+  if (av < bv) return -1;
+  if (av > bv) return 1;
+  return 0;
+}
+
+function compareNumbers(a, b) {
+  const av = Number(a);
+  const bv = Number(b);
+  const aFinite = Number.isFinite(av);
+  const bFinite = Number.isFinite(bv);
+  if (aFinite && bFinite && av !== bv) return av - bv;
+  if (aFinite !== bFinite) return aFinite ? -1 : 1;
+  return 0;
+}
+
+function compareClaimedDeliveries(a, b) {
+  return compareStrings(a?.created_at, b?.created_at)
+    || compareStrings(a?.conversation_id, b?.conversation_id)
+    || compareNumbers(a?.seq, b?.seq)
+    || compareStrings(a?.delivery_id, b?.delivery_id);
+}
+
 function runtimeLabel(runtime) {
   if (runtime === 'claude_code') return 'Claude Code';
   if (runtime === 'opencode') return 'OpenCode';
@@ -472,8 +417,10 @@ export function createTiclawkAdapter(ctx) {
   let bindingAuditTimer = null;
   let jobsWakeTimer = null;
   let bindingsWakeTimer = null;
+  let credentialsWakeTimer = null;
   let lastJobsWakeAt = 0;
   let lastBindingsWakeAt = 0;
+  let lastCredentialsWakeAt = 0;
   let updateRequired = null;
   let lastUpdateRequiredLogAt = 0;
 
@@ -649,7 +596,7 @@ export function createTiclawkAdapter(ctx) {
 
         const binding = await ctx.persistBinding(buildBindingFromSource(msg));
         if (!binding?.runtime) {
-          throw new Error('claimed message missing runtime binding');
+          throw new Error('claimed delivery missing runtime binding');
         }
         if (!belongsToRuntimeHost(binding, hostId)) {
           await api.releaseDelivery(deliveryId, hostId, 'binding-host-mismatch');
@@ -717,6 +664,91 @@ export function createTiclawkAdapter(ctx) {
     }
   }
 
+  // The goal lane's canonical completion is `ticlawk goal report`, which
+  // completes the transition delivery inside report_goal_transition (before
+  // emitting the next step) so the live-transition slot frees up. By the time
+  // the turn returns the row is usually already 'completed', so this
+  // best-effort complete then 409s — that is the expected healthy path, not an
+  // error. A turn that finished without reporting leaves the row 'claimed' for
+  // stale-claimed recovery.
+  async function completeGoalDelivery(deliveryId) {
+    try {
+      await api.completeDelivery(deliveryId, hostId);
+    } catch (err) {
+      if (err?.status === 409) return;
+      throw err;
+    }
+  }
+
+  async function processGoalTransitionsForAgent(agentId, messages) {
+    for (const msg of messages) {
+      const deliveryId = msg.delivery_id;
+      const step = msg?.payload?.step || null;
+      try {
+        const messageHostId = getRuntimeHostIdFromPayload(msg);
+        if (messageHostId && messageHostId !== hostId) {
+          await api.releaseDelivery(deliveryId, hostId, 'host-mismatch');
+          continue;
+        }
+
+        const binding = await ctx.persistBinding(buildBindingFromSource(msg));
+        if (!binding?.runtime) {
+          throw new Error('claimed transition missing runtime binding');
+        }
+        if (!belongsToRuntimeHost(binding, hostId)) {
+          await api.releaseDelivery(deliveryId, hostId, 'binding-host-mismatch');
+          continue;
+        }
+
+        const completed = await ctx.bus.dispatchToAgent(binding.runtime, binding.id, normalizeInboundMessage(msg));
+        if (completed !== true) {
+          if (isTerminalRuntimeFailure(completed)) {
+            await completeGoalDelivery(deliveryId);
+            void requestDrain('transition.terminal-completed');
+            debugError('ticlawk', 'transition.terminal-failed', {
+              agentId,
+              deliveryId,
+              step,
+              runtime: binding.runtime,
+              reason: completed.reason || 'runtime terminal failure',
+            });
+            continue;
+          }
+          throw new Error('runtime did not complete transition turn');
+        }
+        await completeGoalDelivery(deliveryId);
+        void requestDrain('transition.completed');
+        debugLog('ticlawk', 'transition.completed', {
+          agentId,
+          deliveryId,
+          step,
+          runtime: binding.runtime,
+        });
+      } catch (err) {
+        if (api.isUpdateRequiredError(err)) {
+          recordUpdateRequired(err, 'transition.dispatch');
+        }
+        try {
+          await api.releaseDelivery(deliveryId, hostId, 'transition-dispatch-error');
+        } catch (releaseErr) {
+          debugError('ticlawk', 'transition.release-failed', {
+            agentId,
+            deliveryId,
+            hostId,
+            error: releaseErr?.message || 'unknown error',
+          });
+        }
+        debugError('ticlawk', 'transition.dispatch-failed', {
+          agentId,
+          deliveryId,
+          step,
+          hostId,
+          error: err?.message || 'unknown error',
+        });
+      }
+    }
+  }
+
   async function refreshBindings(reason = 'manual') {
     let channels = [];
     const startedAt = Date.now();
@@ -755,6 +787,27 @@ export function createTiclawkAdapter(ctx) {
           error: err?.message || 'unknown error',
         });
       }
+
+      // Agents created from the App via POST /me/agents land here in
+      // status='unpaired'. Once we've successfully registered the
+      // binding locally, flip them to 'connected' — same end state the
+      // legacy QR pairing flow leaves agents in. spawn itself stays
+      // lazy (happens on first delivery via deliverTurn).
+      if (agent.status === 'unpaired' && agentHostId === hostId) {
+        try {
+          await api.updateAgent(agent.id, {
+            status: 'connected',
+            runtime_host_id: hostId,
+            runtime_host_label: getHostLabel(),
+          });
+          debugLog('ticlawk', 'binding.unpaired-claimed', { agentId: agent.id });
+        } catch (err) {
+          debugError('ticlawk', 'binding.unpaired-claim-failed', {
+            agentId: agent.id,
+            error: err?.message || 'unknown error',
+          });
+        }
+      }
     }
     const pruned = await pruneDeletedBindings(channels, reason);
     debugLog('ticlawk', 'binding.refresh-ok', {
@@ -769,6 +822,33 @@ export function createTiclawkAdapter(ctx) {
     return hydrated;
   }
 
+  const syncCredentials = coalesce(async (reason = 'manual') => {
+    const startedAt = Date.now();
+    try {
+      const payload = await api.fetchCredentials();
+      const credentials = Array.isArray(payload?.credentials) ? payload.credentials : [];
+      const result = persistRuntimeCredentials(credentials);
+      debugLog('ticlawk-credentials', 'sync-ok', {
+        reason,
+        saved: result.saved,
+        removed: result.removed,
+        durationMs: Date.now() - startedAt,
+        wakeToSyncMs: String(reason || '').startsWith('wake') && lastCredentialsWakeAt
+          ? Date.now() - lastCredentialsWakeAt
+          : null,
+      });
+    } catch (err) {
+      if (api.isUpdateRequiredError(err)) {
+        recordUpdateRequired(err, 'credentials.sync');
+      }
+      debugError('ticlawk-credentials', 'sync-failed', {
+        reason,
+        durationMs: Date.now() - startedAt,
+        error: err?.message || 'unknown error',
+      });
+    }
+  });
+
   async function releaseBlockedRows(agentId, messages, reason) {
     for (const msg of messages) {
       if (!msg?.delivery_id) continue;
@@ -817,7 +897,8 @@ export function createTiclawkAdapter(ctx) {
       return { failed: true, claimed: 0, launched: 0 };
     }
 
-    const claimed = Array.isArray(data) ? data.length : 0;
+    const orderedData = Array.isArray(data) ? [...data].sort(compareClaimedDeliveries) : [];
+    const claimed = orderedData.length;
     debugLog('ticlawk', 'claim.result', {
       reason,
       hostId,
@@ -836,12 +917,12 @@ export function createTiclawkAdapter(ctx) {
       });
     }
 
-    if (!Array.isArray(data) || data.length === 0) {
+    if (orderedData.length === 0) {
       return { failed: false, claimed: 0, launched: 0 };
     }
 
     const grouped = new Map();
-    for (const msg of data) {
+    for (const msg of orderedData) {
       const agentId = getAgentIdFromPayload(msg);
       if (!agentId) {
         // Claim rows must carry the recipient agent id; a missing value
@@ -854,33 +935,39 @@ export function createTiclawkAdapter(ctx) {
         });
         continue;
       }
-      const bucket = grouped.get(agentId) || [];
-      bucket.push(msg);
-      grouped.set(agentId, bucket);
+      const lane = getDeliveryLaneFromPayload(msg);
+      const channelKey = channelKeyFor(agentId, lane);
+      const bucket = grouped.get(channelKey) || { agentId, lane, messages: [] };
+      bucket.messages.push(msg);
+      grouped.set(channelKey, bucket);
     }
 
     let launched = 0;
-    for (const [agentId, messages] of grouped.entries()) {
-      if (processingChannels.has(agentId)) {
+    for (const [channelKey, { agentId, lane, messages }] of grouped.entries()) {
+      if (processingChannels.has(channelKey)) {
         debugError('ticlawk', 'claim.blocked-claimed-rows', {
           reason,
+          channelKey,
           agentId,
+          lane,
           blockedRows: messages.length,
         });
         await releaseBlockedRows(agentId, messages, reason);
         continue;
       }
-      const run = processPendingMessagesForAgent(agentId, messages)
+      const run = (lane === 'goal'
+        ? processGoalTransitionsForAgent(agentId, messages)
+        : processPendingMessagesForAgent(agentId, messages))
         .catch(() => {})
         .finally(() => {
-          processingChannels.delete(agentId);
+          processingChannels.delete(channelKey);
           void requestDrain('channel.completed');
         });
-      processingChannels.set(agentId, run);
+      processingChannels.set(channelKey, run);
       launched += messages.length;
     }
 
-    return { failed: false, claimed: data.length, launched };
+    return { failed: false, claimed: orderedData.length, launched };
   }
 
   async function runDrain(reason) {
@@ -919,6 +1006,15 @@ export function createTiclawkAdapter(ctx) {
     bindingsWakeTimer.unref?.();
   }
 
+  function scheduleCredentialSync(reason) {
+    credentialsWakeTimer = clearDebounce(credentialsWakeTimer);
+    credentialsWakeTimer = setTimeout(() => {
+      credentialsWakeTimer = null;
+      void syncCredentials(reason);
+    }, CREDENTIALS_WAKE_DEBOUNCE_MS);
+    credentialsWakeTimer.unref?.();
+  }
+
   async function reportHostCapabilitiesNow() {
     const entries = await Promise.all(Object.entries(ctx.runtimes || {})
       .filter(([, runtime]) => typeof runtime?.health === 'function')
@@ -958,6 +1054,7 @@ export function createTiclawkAdapter(ctx) {
       void refreshBindings('wake.hello')
         .then(() => requestDrain('wake.hello'))
         .catch(() => {});
+      void syncCredentials('wake.hello');
       void reportHostCapabilitiesNow();
       return;
     }
@@ -979,6 +1076,17 @@ export function createTiclawkAdapter(ctx) {
       scheduleRefreshAndDrain('wake.bindings.changed');
       return;
     }
+    if (event?.type === 'credentials.changed') {
+      lastCredentialsWakeAt = Date.now();
+      debugLog('ticlawk-wake', 'credentials.changed', {
+        credentialId: event.credential_id || null,
+        name: event.name || null,
+        status: event.status || null,
+        reason: event.reason || null,
+      });
+      scheduleCredentialSync('wake.credentials.changed');
+      return;
+    }
     if (event?.type === 'auth.revoked') {
       wakeState.lastError = 'auth revoked';
       debugError('ticlawk-wake', 'auth.revoked', {});
@@ -1013,7 +1121,17 @@ export function createTiclawkAdapter(ctx) {
 
   function connectWakeSocket() {
     connectorSocket = new TiclawkWakeClient({
-      getUrl: api.getConnectorWsUrl,
+      // host_id rides on the WS query string so connector-wake can flip
+      // runtime_hosts.online for the right row. Empty host_id is
+      // tolerated by the server (it just skips the state write).
+      getUrl: () => {
+        const base = String(api.getConnectorWsUrl() || '').trim();
+        if (!base) return '';
+        const hostId = String(getHostId() || '').trim();
+        if (!hostId) return base;
+        const sep = base.includes('?') ? '&' : '?';
+        return `${base}${sep}host_id=${encodeURIComponent(hostId)}`;
+      },
       getApiKey: api.getApiKey,
       onEvent: handleWakeEvent,
       onStatus: handleWakeStatus,
@@ -1163,11 +1281,11 @@ export function createTiclawkAdapter(ctx) {
     id: 'ticlawk',
 
     async start() {
-      // No stale-delivery recovery anywhere — if the daemon is killed
-      // mid-claim, the row stays `claimed` forever. lease_expires_at
-      // was dropped in X1; no cron has replaced it. Rare in practice;
-      // when it happens the fix is a one-row UPDATE in supabase.
+      // Stale claimed deliveries are recovered conservatively by the
+      // claim RPC; this startup path only refreshes local bindings and
+      // asks for the next drain.
       await refreshBindings('startup');
+      await syncCredentials('startup');
       await requestDrain('startup');
       connectWakeSocket();
       startAuditTimers();

package/src/adapters/ticlawk/wake-client.mjs

@@ -165,7 +165,7 @@ export class TiclawkWakeClient {
       return;
     }
 
-    if (type === 'jobs.available' || type === 'bindings.changed') {
+    if (type === 'jobs.available' || type === 'bindings.changed' || type === 'credentials.changed') {
       this.onEvent?.(msg);
       return;
     }