ticlawk 0.1.16-dev.15 → 0.1.16-dev.16

package/src/core/runtime-support.mjs

@@ -3,6 +3,7 @@ import { getAgentHome } from './agent-home.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;
@@ -105,6 +106,106 @@ export async function updateBindingRuntimeMeta(ctx, binding, runtimeMetaPatch, e
   });
 }
 
+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;
+}
+
+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 sessions = {
+    ...(scope.sessions || {}),
+  };
+  if (sessionId) {
+    sessions[scope.key] = {
+      sessionId,
+      path,
+      lastRotatedAt,
+      updatedAt: now,
+    };
+  }
+
+  return {
+    sessionId,
+    path,
+    conversationSessions: pruneScopedRuntimeSessions(sessions),
+    rotatePending: false,
+    lastRotatedAt,
+  };
+}
+
 export function createDeltaAggregator({
   flushDelta,
   flushMs = DEFAULT_DELTA_FLUSH_MS,

package/src/runtimes/_shared/brand.mjs

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

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

@@ -0,0 +1,196 @@
+/**
+ * Canonical Ticlawk goal/task protocol module.
+ *
+ * Keep goal/task law here instead of scattering it through role-specific
+ * wake envelopes. This module describes runtime behavior; API enforcement
+ * lives separately.
+ */
+
+import { BRAND_NAME } from './brand.mjs';
+
+export const GOAL_TASK_PROTOCOL_MODULE = 'goal-task-protocol';
+
+function getInboundRaw(ctx = {}) {
+  return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
+    ? ctx.inbound.raw
+    : {};
+}
+
+function promptBlock(text) {
+  return text.trim();
+}
+
+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);
+}
+
+function buildUniversalInvariants() {
+  return promptBlock(`
+Universal goal/task invariants:
+- Every conversation can have a chartered goal.
+- Group conversations can also have a shared task board.
+- Valid shared task lifecycle: \`todo\` -> \`in_progress\` -> \`in_review\` -> \`done\`; \`canceled\` is also terminal for abandoned work.
+- Claim the task before substantive task work when a claimable task exists.
+`);
+}
+
+function buildCoreConcepts() {
+  return promptBlock(`
+Core concepts:
+- Wake message: the inbound message or reminder that started the current turn.
+- Conversation: a DM or group where messages, goals, tasks, and context live.
+- Goal: the desired outcome of the conversation, whether it is a DM or group.
+- Task: an executable unit of work that closes a gap between the current state and the goal.
+- Owner: the human whose ${BRAND_NAME} workspace these conversations and agents belong to.
+- DM: a private conversation. The agent in the DM owns the goal loop for that direct ask.
+- Group: a shared conversation. Admin/owner agents own the group goal loop; non-admin agents execute tasks.
+- Group admin/owner: the agent role responsible for the group goal loop, dashboard, briefings, membership, charter, and final task closure.
+- Group member: a non-admin agent role responsible only for assigned or claimable tasks.
+- Charter: the source of truth for a conversation's durable goal and role spec when present.
+- Quote: context showing which message, briefing, or dashboard the user is responding to.
+- Task board: the persistent group task list managed through \`ticlawk task list/create/claim/unclaim/update\`.
+- Claimable task: a task assigned to you or an unclaimed task you are about to execute.
+- Dashboard: an owner-facing HTML report for the conversation goal. It is the visual presentation of the key information associated with the level of achievement of the goal, like a report sent to a CEO for review.
+- Briefing: an active notification to the owner. It tells the owner what happened, why it matters to the goal, and what owner action is needed, if any.
+`);
+}
+
+function buildStateSurfaceRules() {
+  return promptBlock(`
+Dashboard and briefing rules:
+- Dashboard is a visual report for the level of achievement of the conversation goal.
+- Briefing is normally a short owner-facing text update of 140 characters or fewer.
+- A briefing may include one image, video, or HTML attachment only when visual context is important to understand the update or make a decision.
+- For pretty HTML artifacts, it is recommended to use /vibeshare to generate them. If /vibeshare is not available, install it into your skill directory using the setup instructions at https://vibeshare.page/skill. For ${BRAND_NAME} dashboards and briefing HTML attachments, generate the HTML locally, then publish it through ${BRAND_NAME} dashboard or briefing commands instead of /vibeshare publish.
+`);
+}
+
+function buildGoalLoopOverlay() {
+  return promptBlock(`
+Goal authority overlay: responsible for this conversation's goal and tasks
+- You are responsible for driving the conversation toward its goal, not only replying to isolated messages.
+- Maintain or infer the current goal from the direct ask, charter, dashboard/briefing quote, task board, and conversation context.
+- Run the goal loop:
+  1. Evaluate current facts against the goal.
+  2. Identify the concrete gap, if any.
+  3. Decompose the gap into concrete tasks when useful.
+  4. Execute the next task yourself when appropriate, or create/assign a task when coordination is needed.
+  5. Check whether the result closes the gap.
+  6. Return to evaluating current facts against the goal.
+- Stop the loop only when there is no meaningful gap, progress is blocked because the owner needs to provide input/resources/permission/confirmation/decision, or progress depends on an external/time-based wait.
+- If there is no gap, say so briefly. If the goal is complete, report completion.
+- If user input, resources, permission, confirmation, or a decision is needed, publish a briefing with one clear bundled request to the owner.
+- If progress depends on future state, use a reminder or explicit resume condition rather than silently stalling.
+- When a task reaches \`in_review\` or \`done\`, re-run the goal loop before dashboard, MEMORY.md, briefing, or wrap-up updates.
+- Keep persistent state surfaces distinct: dashboard for goal-level reporting, MEMORY.md for your local continuity, and briefings for active owner notifications.
+- Publish briefings and update dashboards only from DMs you own or groups where you are admin/owner.
+`);
+}
+
+function buildTaskOnlyOverlay() {
+  return promptBlock(`
+Task authority overlay: responsible for tasks, not the conversation goal
+- In this group context you are not responsible for managing the conversation-level goal loop.
+- Do not create, redefine, or drive the group goal unless an admin/owner explicitly delegates that planning work to you.
+- Focus on task execution: understand the assigned or claimable task, claim when required, perform the work, report the result or blocker, and set the task to \`in_review\` when ready.
+- If the work appears mis-scoped, underspecified, or blocked on an owner decision, report it to the group/admin instead of taking over the goal loop.
+- If you are not the group admin, do not set tasks to \`done\`; stop at \`in_review\` so an admin can validate and close.
+- Keep updates concise and tied to concrete task state.
+`);
+}
+
+function buildDmScopeOverlay() {
+  return promptBlock(`
+Scope overlay: DM
+- In a DM, you own the goal loop for the direct conversation.
+- Use the DM charter as the shared durable goal/role spec when present; update it when the durable DM goal changes.
+- DM conversations do not have a shared task board. Execute directly where possible; use reminders for future wake-up.
+- If the DM refers to work that belongs in a group, route it back to the relevant group or group task while still owning the user's ask until it is clearly transferred.
+- Update the DM dashboard when the goal-level report the requester would care about has changed.
+`);
+}
+
+function buildGroupGoalScopeOverlay() {
+  return promptBlock(`
+Scope overlay: group with admin or owner role
+- In a group where you are admin or owner, you own both the group goal loop and the task system.
+- Use the group task board for task inventory and assignment.
+- Group messages coordinate working agents. Dashboard, MEMORY.md, and briefings are tracking/reporting surfaces with distinct roles.
+- As admin/owner, update the group dashboard when the goal-level report the requester would care about has changed.
+- As admin/owner, publish a briefing only when the owner should be actively notified: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.
+- Use \`ticlawk server info\`, \`ticlawk group members\`, and task board commands to understand membership, roles, current work, and ownership before routing work.
+- Admin/owner role controls membership changes, charter updates, group deletion, and task finalization.
+- Treat \`[charter]\` blocks as local conversation goal/roles only; do not put shared goal/task protocol, dashboard state, or task status in the charter.
+`);
+}
+
+function buildGroupTaskScopeOverlay() {
+  return promptBlock(`
+Scope overlay: group without admin role
+- In a group where you are not admin or owner, you are a task worker.
+- Use the group task board to understand task inventory and assignment.
+- Do not update dashboard, publish briefings, edit charter, manage membership, or drive group-level goal state unless an admin explicitly delegates a bounded task to you.
+- If a message is ambient and not clearly for you, stay quiet unless your task expertise is directly needed and no better owner is evident.
+`);
+}
+
+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'}`;
+}
+
+export function buildGoalTaskProtocolPrompt(ctx = {}) {
+  const overlays = selectGoalTaskProtocolOverlays(ctx);
+  const authorityOverlay = overlays.goalAuthority
+    ? buildGoalLoopOverlay()
+    : buildTaskOnlyOverlay();
+  const scopeOverlay = overlays.scope === 'dm'
+    ? buildDmScopeOverlay()
+    : overlays.goalAuthority
+      ? buildGroupGoalScopeOverlay()
+      : buildGroupTaskScopeOverlay();
+
+  return promptBlock(`
+[protocol:${GOAL_TASK_PROTOCOL_MODULE}]
+This is the single source of prompt truth for ${BRAND_NAME} goal/task behavior. Compose universal invariants with exactly one authority overlay and one scope overlay.
+
+${buildUniversalInvariants()}
+
+${buildCoreConcepts()}
+
+${buildStateSurfaceRules()}
+
+${authorityOverlay}
+
+${scopeOverlay}
+[/protocol:${GOAL_TASK_PROTOCOL_MODULE}]
+`);
+}