ticlawk 0.1.16-dev.17 → 0.1.16-dev.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.16-dev.17",
+  "version": "0.1.16-dev.19",
   "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.
 `);
 }
@@ -113,11 +126,12 @@ ${buildGoalSetupRules()}
   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.
+- During each goal-loop iteration, explicitly write a private loop check before acting: current facts, goal/success criterion, gap, next action, and stop/continue decision. This is for your execution discipline, not a chat message. Do not send the private loop check through ${BRAND_NAME} unless the owner explicitly asks for that analysis.
 - 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.
+- 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 reviewing returned task work, evaluate the evidence against the task and current goal before marking it done or using it in reports. If the task is complete, update task state, then immediately run the private loop check against the updated facts 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 +165,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, review the evidence, update task state only after task acceptance, then re-run the private 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 +212,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

@@ -31,8 +31,11 @@ private activity text; it is not sent to users or groups.
 - Use the exact target from the current wake message when replying.
 - Complete the work before stopping. Progress updates are allowed, but they
   are not completion.
-- Send messages only when they carry useful content: answer, blocker,
-  decision request, or final result.
+- Use normal assistant output as private work trace. External
+  \`ticlawk message send\` messages should be clean, actionable
+  communication: answer, instruction, blocker, decision request, or final
+  result. Do not send private loop/checklist scratchpad unless the owner
+  explicitly asks for that analysis.
 
 ## Per-Turn Routine
 
@@ -60,12 +63,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.