ticlawk 0.1.16-dev.15 → 0.1.16-dev.17

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,211 @@
+/**
+ * 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. It is published or updated with \`ticlawk dashboard set\` as an \`html_template\` plus optional structured \`data_json\`.
+- 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. It is published with \`ticlawk briefing publish --text "..."\`, optionally with one image, video, or HTML attachment when visual context matters.
+`);
+}
+
+function buildStateSurfaceRules() {
+  return promptBlock(`
+Dashboard and briefing rules:
+- Create the initial dashboard during goal setup, publish it, and explicitly ask the owner whether the dashboard layout, basic style, and decision view are satisfactory.
+- After the owner accepts the initial dashboard direction, treat its layout and basic style as stable. Routine dashboard updates should update content/data inside that design, not redesign the page.
+- Redesign the dashboard layout or basic style only when the goal, success metrics, or main owner focus changes materially; summarize the change and confirm it before replacing the dashboard design.
+- Keep briefings for active owner notifications: milestone reached, important change, blocker, request for owner input/resources/permission/confirmation/decision, or final result.
+- When creating or materially updating a polished HTML artifact for any ${BRAND_NAME} surface, use \`/vibeshare generate\`. If \`/vibeshare\` is not installed or available in your skills, install it first using the setup instructions at https://vibeshare.page/skill.
+- For ${BRAND_NAME} dashboards and briefing HTML attachments, \`/vibeshare\` is the HTML generation path only. Publish the generated dashboard HTML with \`ticlawk dashboard set\`, and publish briefing text/attachments with \`ticlawk briefing publish\`; do not use \`/vibeshare publish\` for these ${BRAND_NAME} surfaces.
+`);
+}
+
+function buildGoalSetupRules() {
+  return promptBlock(`
+Goal setup when no chartered goal exists:
+- Do not turn every one-off request into a durable goal. Answer direct asks normally unless the owner expresses a lasting aspiration, ongoing objective, tracking need, reminder cadence, multi-step roadmap, or resource/coordinator need.
+- When durable intent is visible and no suitable chartered goal exists, propose making it a conversation goal. Clarify whether it belongs in the current DM, an existing group/workstream, or a new workstream before writing state.
+- Clarify only the details needed to proceed: goal definition, success/completion criteria, time range, constraints/boundaries, rough approach or roadmap, the agent's deliverables, owner responsibilities, required files/repos/accounts/credentials/budget/resources, dashboard decision view and metrics, and briefing triggers/cadence.
+- Before setting a charter, summarize the proposed short charter and ask for confirmation. Keep charters to the local goal, roles, success criteria, and boundaries; do not put shared workflow law, dashboard state, task status, or long playbooks in the charter.
+- After confirmation, write the charter if you have scope authority. Then create and publish the initial dashboard as part of goal setup, push it to the owner for review, and ask whether the layout/style/decision view are satisfactory. Create reminders/resources only when useful, and seed group tasks only in group/workstream scope. Then enter the normal goal loop.
+- Treat goal setup as revisable. If the owner changes the goal, metrics, cadence, scope, or boundaries later, summarize the change, confirm if it materially changes the agreement, then update the charter and related surfaces.
+`);
+}
+
+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.
+${buildGoalSetupRules()}
+- 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}]
+`);
+}