ticlawk 0.1.16-dev.17 → 0.1.16-dev.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.16-dev.17",
+  "version": "0.1.16-dev.18",
   "description": "Local connector that links agent harnesses (Claude Code, Codex, OpenClaw, opencode, Pi) to the Ticlawk mobile app.",
   "type": "module",
   "main": "ticlawk.mjs",

package/src/adapters/ticlawk/api.mjs

@@ -625,11 +625,12 @@ export async function getBriefing({actingAgentId, briefingId}) {
   return apiFetch(`/api/agent/briefings/${encodeURIComponent(briefingId)}?${params}`);
 }
 
-export async function publishBriefing({actingAgentId, bodyText, attachmentAssetId, currentConversationId}) {
+export async function publishBriefing({actingAgentId, bodyText, attachmentAssetId, currentConversationId, responseMode}) {
   const body = { acting_as_agent_id: actingAgentId };
   if (bodyText != null) body.body_text = bodyText;
   if (attachmentAssetId != null) body.attachment_asset_id = attachmentAssetId;
   if (currentConversationId != null) body.current_conversation_id = currentConversationId;
+  if (responseMode != null) body.response_mode = responseMode;
   return apiFetch('/api/agent/briefings', {
     method: 'POST',
     body: JSON.stringify(body),

package/src/cli/agent-commands.mjs

@@ -1067,6 +1067,7 @@ export async function runBriefingPublishCommand(args) {
   const env = requireAgentEnv();
   const textArg = getArg(args, 'text');
   const attachPath = getArg(args, 'attach');
+  const mode = String(getArg(args, 'mode') || 'info').trim().toLowerCase();
   if (!textArg) {
     console.error('--text "<short>" is required');
     return 2;
@@ -1075,6 +1076,10 @@ export async function runBriefingPublishCommand(args) {
     console.error('--text must be ≤140 chars');
     return 2;
   }
+  if (!['info', 'approval'].includes(mode)) {
+    console.error('--mode must be info or approval');
+    return 2;
+  }
   let attachmentAssetId = null;
   if (attachPath) {
     const contentType = inferContentType(String(attachPath));
@@ -1097,6 +1102,7 @@ export async function runBriefingPublishCommand(args) {
       body_text: textArg,
       attachment_asset_id: attachmentAssetId,
       current_conversation_id: env.currentConversationId,
+      response_mode: mode,
     },
   });
   printJson(res.body);
@@ -1326,10 +1332,11 @@ export const AGENT_COMMAND_HELP = {
     Any agent. Backend proxies to endpoint_config.url. No retry.
 `,
   briefing: `ticlawk briefing <publish|get>
-  briefing publish --text "..." [--attach <image|video|html path>]
+  briefing publish --text "..." [--mode info|approval] [--attach <image|video|html path>]
     Publish a briefing to the owner's Briefings. Allowed from DMs, or
     from groups where this agent is admin/owner.
     --text  short plain text (≤140 chars)
+    --mode  owner response mode: info shows ack; approval shows approve
     --attach optional image, video, or HTML file when visual context matters
     Briefings are independent of chat — they do NOT appear in any DM
     message stream. Use this verb (not \`message send\`) for any status

package/src/core/agent-cli-handlers.mjs

@@ -982,12 +982,18 @@ export async function handleBriefingPublish(req, body, ctx) {
   const attachmentAssetId = typeof body?.attachment_asset_id === 'string' && body.attachment_asset_id.trim()
     ? body.attachment_asset_id.trim()
     : null;
+  const responseMode = typeof body?.response_mode === 'string' && body.response_mode.trim()
+    ? body.response_mode.trim().toLowerCase()
+    : 'info';
   if (!bodyText) {
     return { status: 400, body: { error: 'body_text is required' } };
   }
   if (bodyText && bodyText.length > 140) {
     return { status: 400, body: { error: 'body_text must be ≤140 chars' } };
   }
+  if (!['info', 'approval'].includes(responseMode)) {
+    return { status: 400, body: { error: 'response_mode must be info or approval' } };
+  }
   const currentConversationId = getCurrentConversationId(req, body);
   try {
     const data = await api.publishBriefing({
@@ -995,6 +1001,7 @@ export async function handleBriefingPublish(req, body, ctx) {
       bodyText,
       attachmentAssetId,
       currentConversationId,
+      responseMode,
     });
     return { status: 200, body: data };
   } catch (err) {

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

@@ -72,7 +72,19 @@ Core concepts:
 - 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.
+- 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 "..." --mode info\` for updates/notifications, or \`--mode approval\` when the owner needs to approve, optionally with one image, video, or HTML attachment when visual context matters.
+`);
+}
+
+function buildOperatingModes() {
+  return promptBlock(`
+Operating modes:
+- Before acting, determine the conversation scope, your role, and the goal state from the inbound message, charter, task board, and recent context.
+- In a DM, own the direct ask. Answer one-off asks directly; when durable owner intent is visible, run goal setup, then run the goal loop once the goal exists.
+- In a group where you are admin or owner and a local goal exists, own the group goal loop and task system.
+- In a group where you are admin or owner and no local goal exists, do not invent one. If the owner clearly expresses a durable group/workstream goal, run goal setup; otherwise handle only the current coordination need.
+- In a group where you are not admin or owner, do not drive the group goal. Work only on assigned, claimable, or directly delegated tasks through the task worker loop.
+- Ambient group messages are visible context, not automatic work, unless your role, task ownership, or expertise makes you clearly the right responder.
 `);
 }
 
@@ -84,6 +96,7 @@ Dashboard and briefing rules:
 - 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.
+- When using \`/vibeshare generate\` for a briefing HTML attachment, include in the generation request that the HTML will render on mobile and should act as a focused visual aid for understanding the briefing: emphasize the key visual elements, relationships, status, numbers, or choices that clarify the message and owner action, rather than trying to include all supporting detail. Do not build complex gestures, slideshows, carousels, paginated flows, or custom navigation that could conflict with the host mobile surface.
 - 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.
 `);
 }
@@ -116,7 +129,7 @@ ${buildGoalSetupRules()}
 - 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.
+- If progress depends on an external or time-based future state and no agent or owner can act now, use a reminder or explicit resume condition rather than silently stalling. Do not use reminders to defer an executable next step or an owner decision/request.
 - 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.
@@ -151,6 +164,7 @@ function buildGroupGoalScopeOverlay() {
 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.
+- When you delegate substantive work to another agent, make it a group task before or while requesting the work. When results return, update task state and re-run the group goal loop.
 - 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.
@@ -197,15 +211,17 @@ export function buildGoalTaskProtocolPrompt(ctx = {}) {
 [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()}
+${buildUniversalInvariants()}
+
+${buildOperatingModes()}
 
 ${authorityOverlay}
 
 ${scopeOverlay}
+
+${buildStateSurfaceRules()}
 [/protocol:${GOAL_TASK_PROTOCOL_MODULE}]
 `);
 }

package/src/runtimes/_shared/standing-prompt.mjs

@@ -60,12 +60,14 @@ private activity text; it is not sent to users or groups.
   dashboards. \`set\` reads JSON from stdin: \`{ html_template, data_json }\`.
   Allowed from DMs, or from groups where this agent is admin/owner.
 - \`ticlawk briefing publish/get\`: publish or read owner-facing briefings.
-  Use \`publish --text "..."\` with an optional \`--attach <image|video|html>\`.
+  Use \`publish --text "..."\` with \`--mode info\` for updates/notifications
+  or \`--mode approval\` when the owner needs to approve, plus an optional
+  \`--attach <image|video|html>\`.
   Allowed from DMs, or from groups where this agent is admin/owner.
 - \`ticlawk task list/create/claim/unclaim/update\`: use only as allowed by
   the goal/task protocol and backend errors.
-- \`ticlawk reminder schedule/snooze/update/cancel\`: use for future
-  follow-up that should be visible and persistent in ${BRAND_NAME}.
+- \`ticlawk reminder schedule/snooze/update/cancel\`: use only for external or
+  time-based future follow-up that should be visible and persistent in ${BRAND_NAME}.
 - \`ticlawk service list/info/call\`: use shared services when a published
   tool matches the task. If a service call fails, report the failure; do not
   retry in a loop.