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

package/src/core/argv.mjs

@@ -29,7 +29,17 @@ export function parseOptionArgs(argv = []) {
       const value = inlineValue !== undefined
         ? inlineValue
         : argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : true;
-      args[rawKey] = value;
+      // Repeated flags collect into an array so `--attach a --attach b`
+      // surfaces as ['a','b'] to callers that expect repeatable input
+      // (--attach on message send, --member on group create, etc).
+      // First occurrence stays scalar so single-value callers don't
+      // have to learn array-or-string.
+      if (Object.prototype.hasOwnProperty.call(args, rawKey)) {
+        const existing = args[rawKey];
+        args[rawKey] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+      } else {
+        args[rawKey] = value;
+      }
       continue;
     }
     args._.push(arg);

package/src/core/events/worker-events.mjs

@@ -1,22 +1,9 @@
-import { createHash } from 'node:crypto';
-
 const workerEventSeq = new Map();
-const DELTA_LOG_PREVIEW_CHARS = 48;
 
 function shortId(value) {
   return value ? String(value).slice(0, 8) : null;
 }
 
-function hashText(text) {
-  return createHash('sha1').update(String(text)).digest('hex').slice(0, 12);
-}
-
-function previewDelta(text) {
-  const normalized = String(text).replace(/\n/g, '\\n');
-  if (normalized.length <= DELTA_LOG_PREVIEW_CHARS) return normalized;
-  return normalized.slice(0, DELTA_LOG_PREVIEW_CHARS) + '…';
-}
-
 function nextWorkerEventMeta({ agent, sessionId, turnId }) {
   const key = `${agent}:${sessionId || ''}:${turnId || 'session'}`;
   const seq = (workerEventSeq.get(key) || 0) + 1;
@@ -37,6 +24,16 @@ export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd
   if (!sessionId || typeof adapter.emitEvent !== 'function') return;
   const eventName = event?.worker_event_name || event?.hook_event_name || 'unknown';
   const logicalTurnId = replyToMessageId || turnId || event?.turn_id || null;
+  if (eventName === 'worker.message.delta') {
+    logger?.debugLog?.('events', 'delta.drop', {
+      bindingId: binding.id,
+      agent,
+      sessionId: shortId(sessionId),
+      turnId: shortId(logicalTurnId),
+      chars: typeof event?.delta === 'string' ? event.delta.length : null,
+    });
+    return;
+  }
   const { key, seq, originTs } = nextWorkerEventMeta({ agent, sessionId, turnId: logicalTurnId });
   const enrichedEvent = {
     ...event,
@@ -45,29 +42,14 @@ export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd
     event_seq: seq,
     origin_ts: originTs,
   };
-  if (typeof event?.delta === 'string' && event.delta) {
-    enrichedEvent.delta_chars = event.delta.length;
-    enrichedEvent.delta_hash = hashText(event.delta);
-    logger?.debugLog?.('events', 'delta.recv', {
-      bindingId: binding.id,
-      agent,
-      sessionId: shortId(sessionId),
-      turnId: shortId(logicalTurnId),
-      seq,
-      chars: event.delta.length,
-      hash: enrichedEvent.delta_hash,
-      preview: previewDelta(event.delta),
-    });
-  } else {
-    logger?.debugLog?.('events', 'event.recv', {
-      bindingId: binding.id,
-      agent,
-      sessionId: shortId(sessionId),
-      turnId: shortId(logicalTurnId),
-      seq,
-      eventName,
-    });
-  }
+  logger?.debugLog?.('events', 'event.recv', {
+    bindingId: binding.id,
+    agent,
+    sessionId: shortId(sessionId),
+    turnId: shortId(logicalTurnId),
+    seq,
+    eventName,
+  });
   await adapter.emitEvent(binding, {
     agent,
     sessionId,
@@ -78,3 +60,17 @@ export async function emitWorkerEvent({ adapter, binding, agent, sessionId, cwd
     clearWorkerEventMeta(key);
   }
 }
+
+export function emitWorkerEventBestEffort(args) {
+  void emitWorkerEvent(args).catch((err) => {
+    const event = args?.event || {};
+    const eventName = event.worker_event_name || event.hook_event_name || 'unknown';
+    args?.logger?.debugError?.('events', 'event.best-effort-failed', {
+      bindingId: args?.binding?.id || null,
+      agent: args?.agent || null,
+      sessionId: shortId(args?.sessionId),
+      eventName,
+      error: err?.message || 'unknown error',
+    });
+  });
+}

package/src/core/http.mjs

@@ -3,6 +3,25 @@ import {
   handleAttachmentUpload,
   handleAttachmentView,
   handleGroupCreate,
+  handleWorkstreamCharterGet,
+  handleWorkstreamCharterSet,
+  handleWorkstreamCreate,
+  handleWorkstreamDelete,
+  handleWorkstreamList,
+  handleAgentList,
+  handleAgentCreate,
+  handleAgentDelete,
+  handleWorkstreamDashboardSet,
+  handleWorkstreamDashboardGet,
+  handleCredentialRequest,
+  handleBriefingPublish,
+  handleBriefingGet,
+  handleServiceCreate,
+  handleServiceUpdate,
+  handleServiceDelete,
+  handleServiceList,
+  handleServiceInfo,
+  handleServiceCall,
   handleGroupMembers,
   handleGroupMembersAdd,
   handleGroupMembersRemove,
@@ -11,6 +30,7 @@ import {
   handleMessageRead,
   handleMessageSearch,
   handleMessageSend,
+  handleProfileAvatarUpload,
   handleProfileShow,
   handleProfileUpdate,
   handleReminderCancel,
@@ -148,6 +168,12 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleProfileUpdate(req, body, cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/profile/avatar' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleProfileAvatarUpload(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
       if (urlNoQuery === '/agent/attachment/upload' && method === 'POST') {
         const body = await readJsonBody(req);
         if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
@@ -216,6 +242,106 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleServerInfo(req, parseQuery(req.url || ''), cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/workstream/charter/get' && method === 'GET') {
+        const r = await handleWorkstreamCharterGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/charter/set' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamCharterSet(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/workstream/list' && method === 'GET') {
+        const r = await handleWorkstreamList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/list' && method === 'GET') {
+        const r = await handleAgentList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleAgentCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/agent/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleAgentDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/dashboard/set' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleWorkstreamDashboardSet(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/dashboard/get' && method === 'GET') {
+        const r = await handleWorkstreamDashboardGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/briefing/publish' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleBriefingPublish(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/briefing/get' && method === 'GET') {
+        const r = await handleBriefingGet(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/credential/request' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleCredentialRequest(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/create' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceCreate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/update' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceUpdate(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/delete' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceDelete(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/list' && method === 'GET') {
+        const r = await handleServiceList(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/info' && method === 'GET') {
+        const r = await handleServiceInfo(req, parseQuery(req.url || ''), cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
+      if (urlNoQuery === '/agent/service/call' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleServiceCall(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
 
       writeJson(res, 404, { error: 'not found' });
     } catch (err) {

package/src/core/runtime-env.mjs

@@ -15,6 +15,7 @@
 const STRIPPED_KEYS = new Set([
   'TICLAWK_CONNECTOR_API_KEY',
   'TICLAWK_CONNECTOR_WS_URL',
+  'TICLAWK_CREDENTIAL_NAMES',
   'TICLAWK_SETUP_CODE',
 ]);
 
@@ -35,11 +36,17 @@ export function buildAgentRuntimeEnv({
   sessionId,
   hostId,
   daemonUrl,
+  conversationId,
+  messageId,
+  target,
 } = {}) {
   const out = {};
   if (agentId) out.TICLAWK_RUNTIME_AGENT_ID = String(agentId);
   if (sessionId) out.TICLAWK_RUNTIME_SESSION_ID = String(sessionId);
   if (hostId) out.TICLAWK_RUNTIME_HOST_ID = String(hostId);
+  if (conversationId) out.TICLAWK_RUNTIME_CONVERSATION_ID = String(conversationId);
+  if (messageId) out.TICLAWK_RUNTIME_MESSAGE_ID = String(messageId);
+  if (target) out.TICLAWK_RUNTIME_TARGET = String(target);
   out.TICLAWK_RUNTIME_DAEMON_URL = daemonUrl || 'http://127.0.0.1:8741';
   return out;
 }

package/src/core/runtime-support.mjs

@@ -1,8 +1,8 @@
 import { getStreamingMode } from './config.mjs';
 import { getAgentHome } from './agent-home.mjs';
+import { debugError } from './logger.mjs';
 const ERROR_MAX_CHARS = 500;
-const DEFAULT_DELTA_FLUSH_MS = 250;
-const DEFAULT_DELTA_FLUSH_CHARS = 64;
+const MAX_SCOPED_RUNTIME_SESSIONS = 50;
 
 function truncateError(text) {
   if (!text) return null;
@@ -42,36 +42,6 @@ export function shouldStreamRuntime(runtimeName, runtime) {
   return Boolean(runtime?.runTurnStream) && getStreamingMode(runtimeName);
 }
 
-export async function sendAdapterMessage(adapter, binding, payload) {
-  await adapter.send(binding, payload);
-}
-
-/**
- * Record the runtime's final turn output as activity (NOT chat).
- *
- * Previously called `sendResult` and treated as "the chat reply path".
- * After the group-chat upgrade, chat is produced exclusively by the
- * agent invoking `ticlawk message send` via the CLI. The runtime's
- * raw final output is still surfaced for trajectory/debug UI, but it
- * no longer materializes as a `messages` row — the trigger
- * `project_agent_event` was updated in PR-2b to drop the chat
- * projection.
- *
- * Renamed so the call sites read self-evidently: "record activity"
- * never reads as "send a chat message".
- */
-export async function recordActivity(adapter, binding, inbound, result) {
-  if (!result?.text && (!result?.mediaUrls || result.mediaUrls.length === 0)) return;
-  await sendAdapterMessage(adapter, binding, {
-    type: 'assistant',
-    text: result.text || '',
-    media: result.media || [],
-    turnId: inbound.messageId || result?.turnId || null,
-    replyToMessageId: inbound.messageId || null,
-  });
-}
-
-
 export async function reportSubprocessFailure({ adapter, binding, inbound, runtimeName, info }) {
   if (!info || info.ok) return;
   const seconds = ((info.durationMs || 0) / 1000).toFixed(1);
@@ -104,12 +74,21 @@ export async function reportSubprocessFailure({ adapter, binding, inbound, runti
   // skips fan-out to member-role agents, breaking what would otherwise
   // be a failure→fan-out→failure cascade when several agents share a
   // broken runtime.
-  await adapter.postAgentReply(binding, {
-    conversationId: inbound?.conversationId || null,
-    text,
-    replyToMessageId: inbound?.messageId || null,
-    visibility: 'admin',
-  });
+  try {
+    await adapter.postAgentReply(binding, {
+      conversationId: inbound?.conversationId || null,
+      text,
+      replyToMessageId: inbound?.messageId || null,
+      visibility: 'admin',
+    });
+  } catch (err) {
+    debugError('runtime', 'failure-notice.failed', {
+      agentId: binding?.id || null,
+      runtimeName,
+      messageId: inbound?.messageId || null,
+      error: err?.message || 'unknown error',
+    });
+  }
 }
 
 export function terminalRuntimeFailure(reason = 'runtime failure') {
@@ -135,80 +114,102 @@ export async function updateBindingRuntimeMeta(ctx, binding, runtimeMetaPatch, e
   });
 }
 
-export function createDeltaAggregator({
-  flushDelta,
-  flushMs = DEFAULT_DELTA_FLUSH_MS,
-  flushChars = DEFAULT_DELTA_FLUSH_CHARS,
-}) {
-  let buffer = '';
-  let pendingMeta = null;
-  let timer = null;
-  let flushChain = Promise.resolve();
-
-  const clearTimer = () => {
-    if (!timer) return;
-    clearTimeout(timer);
-    timer = null;
-  };
+function readScopedSessionKey(inbound = {}) {
+  const conversationId = String(inbound?.conversationId || '').trim();
+  if (!conversationId) return '';
+  const threadRoot = String(inbound?.raw?.thread_root_message_id || '').trim();
+  return threadRoot ? `${conversationId}:thread:${threadRoot}` : conversationId;
+}
+
+function normalizeScopedRuntimeSessions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const out = {};
+  for (const [key, session] of Object.entries(value)) {
+    if (!key || !session || typeof session !== 'object' || Array.isArray(session)) continue;
+    const sessionId = typeof session.sessionId === 'string' ? session.sessionId.trim() : '';
+    if (!sessionId) continue;
+    out[key] = {
+      sessionId,
+      path: typeof session.path === 'string' ? session.path : null,
+      lastRotatedAt: typeof session.lastRotatedAt === 'string' ? session.lastRotatedAt : null,
+      updatedAt: typeof session.updatedAt === 'string' ? session.updatedAt : null,
+    };
+  }
+  return out;
+}
 
-  const startFlush = () => {
-    if (!buffer || typeof flushDelta !== 'function') return flushChain;
-    const text = buffer;
-    const meta = pendingMeta || {};
-    buffer = '';
-    pendingMeta = null;
-    clearTimer();
-    flushChain = flushChain
-      .catch(() => {})
-      .then(() => flushDelta({ text, ...meta }));
-    return flushChain;
+function pruneScopedRuntimeSessions(sessions) {
+  const entries = Object.entries(sessions);
+  if (entries.length <= MAX_SCOPED_RUNTIME_SESSIONS) return sessions;
+  return Object.fromEntries(entries
+    .sort(([, a], [, b]) => {
+      const aTs = Date.parse(a?.updatedAt || a?.lastRotatedAt || '') || 0;
+      const bTs = Date.parse(b?.updatedAt || b?.lastRotatedAt || '') || 0;
+      return bTs - aTs;
+    })
+    .slice(0, MAX_SCOPED_RUNTIME_SESSIONS));
+}
+
+export function resolveRuntimeSessionScope(meta = {}, inbound = {}) {
+  const key = readScopedSessionKey(inbound);
+  if (!key) {
+    return {
+      key: '',
+      sessions: {},
+      sessionId: meta.sessionId || null,
+      path: meta.path || null,
+      lastRotatedAt: meta.lastRotatedAt || null,
+      shouldRotate: !meta.sessionId || Boolean(meta.rotatePending),
+    };
+  }
+
+  const sessions = meta.rotatePending ? {} : normalizeScopedRuntimeSessions(meta.conversationSessions);
+  const scoped = sessions[key] || {};
+  return {
+    key,
+    sessions,
+    sessionId: scoped.sessionId || null,
+    path: scoped.path || null,
+    lastRotatedAt: scoped.lastRotatedAt || null,
+    shouldRotate: !scoped.sessionId || Boolean(meta.rotatePending),
   };
+}
 
-  const scheduleFlush = () => {
-    if (!buffer || timer) return;
-    timer = setTimeout(() => {
-      timer = null;
-      void startFlush();
-    }, flushMs);
-    timer.unref?.();
+export function buildRuntimeSessionMetaPatch(meta = {}, scope = {}, result = {}) {
+  const now = new Date().toISOString();
+  const scoped = Boolean(scope.key);
+  const sessionId = result?.sessionId || scope.sessionId || (scoped ? null : meta.sessionId || null);
+  const path = result?.path || scope.path || (scoped ? null : meta.path || null);
+  const lastRotatedAt = scope.shouldRotate
+    ? now
+    : (scope.lastRotatedAt || meta.lastRotatedAt || now);
+
+  if (!scoped) {
+    return {
+      sessionId,
+      ...(path !== undefined ? { path } : {}),
+      rotatePending: false,
+      lastRotatedAt,
+    };
+  }
+
+  const sessions = {
+    ...(scope.sessions || {}),
   };
+  if (sessionId) {
+    sessions[scope.key] = {
+      sessionId,
+      path,
+      lastRotatedAt,
+      updatedAt: now,
+    };
+  }
 
   return {
-    push(text, meta = {}) {
-      const normalized = typeof text === 'string' ? text : '';
-      if (!normalized) return;
-
-      const nextMeta = {
-        sessionId: meta.sessionId || null,
-        turnId: meta.turnId || null,
-        cwd: meta.cwd || '',
-      };
-
-      const sameContext = !pendingMeta
-        || (
-          pendingMeta.sessionId === nextMeta.sessionId
-          && pendingMeta.turnId === nextMeta.turnId
-          && pendingMeta.cwd === nextMeta.cwd
-        );
-
-      if (!sameContext && buffer) {
-        void startFlush();
-      }
-
-      pendingMeta = nextMeta;
-      buffer += normalized;
-
-      if (buffer.length >= flushChars) {
-        void startFlush();
-        return;
-      }
-
-      scheduleFlush();
-    },
-
-    async flush() {
-      clearTimer();
-      await startFlush();
-    },
+    sessionId,
+    path,
+    conversationSessions: pruneScopedRuntimeSessions(sessions),
+    rotatePending: false,
+    lastRotatedAt,
   };
 }

package/src/migrate/write-initial-memory.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-// Seed the slock-style per-agent home + MEMORY.md for every paired
-// agent in the linked Supabase project.
+// Seed the per-agent home + MEMORY.md for every paired agent in the
+// linked Supabase project.
 //
 //   ~/.ticlawk/agents/<agent_id>/MEMORY.md
 //
-// This replaces the Phase-B variant that wrote MEMORY.md into each
-// agent's *project* workdir. The new design follows slock exactly:
-// agent cwd = its own home dir, MEMORY.md lives in cwd.
+// Replaces the Phase-B variant that wrote MEMORY.md into each agent's
+// project workdir. Each agent now has its own home dir as cwd, with
+// MEMORY.md living at the root of that home.
 //
 // Usage:
 //   node src/migrate/write-initial-memory.mjs           # dry-run

package/src/runtimes/_shared/agent-handbook.mjs

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HANDBOOK_BASICS_FILE = 'BASICS.md';
+
+export const HANDBOOK_FILE_NAMES = Object.freeze([
+  HANDBOOK_BASICS_FILE,
+  'COMMUNICATION.md',
+  'COLLABORATION.md',
+  'GOAL_TASK_CORE.md',
+  'GOAL_AUTHORITY.md',
+  'TASK_WORKER.md',
+  'DM_SCOPE.md',
+  'GROUP_ADMIN_SCOPE.md',
+  'GROUP_MEMBER_SCOPE.md',
+  'SURFACES.md',
+]);
+
+export const LEGACY_HANDBOOK_FILE_NAMES = Object.freeze([
+  'TICLAWK.md',
+  'TICLAWK_CLI.md',
+  'TICLAWK_COLLABORATION.md',
+  'TICLAWK_GOAL_TASK_PROTOCOL.md',
+  'TICLAWK_GOAL_TASK_CORE.md',
+  'TICLAWK_GOAL_AUTHORITY.md',
+  'TICLAWK_TASK_WORKER.md',
+  'TICLAWK_DM_SCOPE.md',
+  'TICLAWK_GROUP_ADMIN_SCOPE.md',
+  'TICLAWK_GROUP_MEMBER_SCOPE.md',
+  'TICLAWK_SURFACES.md',
+  'TICLAWK_WORKSPACE.md',
+  'WORKSPACE.md',
+  'GOAL_TASK_PROTOCOL.md',
+]);
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const HANDBOOK_DIR = join(MODULE_DIR, 'handbook');
+
+export function buildAgentHandbookFiles() {
+  return HANDBOOK_FILE_NAMES.map((name) => ({
+    name,
+    content: readFileSync(join(HANDBOOK_DIR, name), 'utf8').trim(),
+  }));
+}

package/src/runtimes/_shared/brand.mjs

@@ -0,0 +1,2 @@
+export const BRAND_NAME = 'Ticlawk';
+export const CLI_NAME = 'ticlawk';

package/src/runtimes/_shared/goal-task-protocol.mjs

@@ -0,0 +1,50 @@
+/**
+ * Runtime goal/task branch selection.
+ *
+ * Prompt text lives in the managed handbook files. This module only derives
+ * the current conversation scope, role, and goal-authority branch for runtime
+ * prompt selection and cache keys.
+ */
+
+function getInboundRaw(ctx = {}) {
+  return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
+    ? ctx.inbound.raw
+    : {};
+}
+
+function inferScope(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  const conversationType = String(raw.conversation_type || '').trim();
+  if (conversationType === 'group' || conversationType === 'thread') return 'group';
+  return 'dm';
+}
+
+function getRecipientConversationRole(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  return String(raw.recipient_conversation_role || raw.recipient_role || '').trim().toLowerCase() || 'member';
+}
+
+function hasConversationAdminRole(ctx = {}) {
+  const raw = getInboundRaw(ctx);
+  if (raw.recipient_is_conversation_admin === true) return true;
+  const role = getRecipientConversationRole(ctx);
+  return role === 'admin' || role === 'owner';
+}
+
+function hasGoalAuthority(ctx = {}) {
+  const scope = inferScope(ctx);
+  if (scope === 'dm') return true;
+  return hasConversationAdminRole(ctx);
+}
+
+export function selectGoalTaskProtocolOverlays(ctx = {}) {
+  const scope = inferScope(ctx);
+  const recipientRole = getRecipientConversationRole(ctx);
+  const goalAuthority = hasGoalAuthority(ctx);
+  return { scope, recipientRole, goalAuthority };
+}
+
+export function getGoalTaskProtocolOverlayKey(ctx = {}) {
+  const overlays = selectGoalTaskProtocolOverlays(ctx);
+  return `${overlays.scope}:${overlays.recipientRole}:${overlays.goalAuthority ? 'goal' : 'task'}`;
+}