ticlawk 0.1.16-dev.9 → 0.1.16

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,
@@ -223,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-contract.mjs

@@ -55,7 +55,6 @@ import { normalizeServiceType } from './runtime-registry.mjs';
  * @property {(inbound: any, ctx: RuntimeDeliveryContext) => Promise<boolean>} deliverTurn
  * @property {(binding: any, ctx: { adapter: any, logger: any }) => (Promise<void>|void)} [onBindingUpdated]
  * @property {(ctx: { adapter: any, getBinding: (bindingId: string) => any }) => (Promise<number>|number)} [recoverInFlight]
- * @property {(binding: any, ctx: { adapter: any, logger: any }) => (Promise<number>|number)} [reconcileAfterRestart]
  */
 
 /**

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;
@@ -74,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') {
@@ -105,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),
   };
+}
+
+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 scheduleFlush = () => {
-    if (!buffer || timer) return;
-    timer = setTimeout(() => {
-      timer = null;
-      void startFlush();
-    }, flushMs);
-    timer.unref?.();
+  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/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'}`;
+}

package/src/runtimes/_shared/handbook/BASICS.md

@@ -0,0 +1,27 @@
+# Agent Basics
+
+DO NOT EDIT.
+
+## Workspace
+
+- Your cwd is a persistent, agent-owned workspace.
+- Use it for memory, notes, artifacts, code checkouts, and task files.
+- `MEMORY.md` is the recovery entry point. Read it before acting.
+- Use `notes/<topic>.md` for long-lived detail and link those notes from `MEMORY.md`.
+- Do not store secrets, chat transcripts, or routine progress logs in memory.
+- When working in a repository, choose the specific project directory or worktree before running git or package commands.
+
+## Work Contract
+
+- Normal assistant output is private activity text inside your workspace. It is not sent to users, groups, or other agents.
+- External communication goes through the `ticlawk` CLI.
+- Complete the requested work before stopping. A progress update is allowed, but it is not completion.
+- Read only the local files needed for the current turn.
+
+## Memory Updates
+
+Update `MEMORY.md` when you learn durable user preferences, project facts, group context, active work, standing decisions, open blockers, or collaboration patterns.
+
+Keep memory concise. Link detailed notes instead of turning `MEMORY.md` into a transcript.
+
+Record only durable continuity: your role, stable user/project/domain facts, active goals, open blockers, standing decisions, important group context, preferences, and links to notes or artifacts. Do not record facts already recoverable from the task board, dashboard, briefing, or recent chat history.

package/src/runtimes/_shared/handbook/COLLABORATION.md

@@ -0,0 +1,37 @@
+# Collaboration
+
+DO NOT EDIT.
+
+## DMs
+
+- In a DM, handle the direct ask and own follow-through until it is answered, blocked, transferred, or complete.
+- If the DM refers to group or task work, route it back to the relevant group or task while still answering the user clearly.
+
+## Groups
+
+- Direct mentions, DMs, assignments, and manual reminders normally require action.
+- Ambient group messages are visible context, not automatic work. Stay quiet unless you are clearly the right responder and can add concrete value.
+- When the human owner asks a question or makes a request in a group without naming a specific agent, the group admin is the default responder and must answer or route it.
+- Non-admin group members should not answer owner questions by default. Answer only when you are directly mentioned, assigned, asked by the admin, or reporting on your active task.
+- Write like a teammate coordinating work, not like a protocol trace.
+- Translate private loop decisions into natural messages about what changed, who should do what next, what evidence matters, or what is blocked.
+- Do not echo someone else's completion report or PR summary. The person doing the work should report on it.
+
+## Assigning Work
+
+When assigning work, send a compact instruction with:
+
+- desired outcome
+- important constraints
+- expected evidence
+- where to report back
+
+Avoid exposing internal checklists unless the group explicitly asks for process detail.
+
+## Blockers
+
+If you own a concrete blocker before stopping, follow the goal/task protocol for owner intervention when applicable. Otherwise send one concise actionable message to the person or group that is blocked.
+
+## New Message Notifications
+
+If a new message arrives while you are busy, finish the current step before pivoting unless the new message clearly supersedes the current work.