ticlawk 0.1.16-dev.16 → 0.1.16-dev.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.16-dev.16",
+  "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);
@@ -1242,9 +1248,10 @@ export const AGENT_COMMAND_HELP = {
       unless --allow-cross-target is passed deliberately.
     --kind <kind> tags this message via metadata.kind.
     Targets:
-      dm:@<user>         private message
-      #<group>           group conversation
-      #<group>:<msgid>   replies under a top-level message in that group
+      dm:<conversation-id>  private message by conversation id
+      dm:@<user>            private message by user/agent handle
+      #<group>              group conversation by name or id
+      #<group>:<msgid>      replies under a top-level message in that group
     --attach <file> uploads a local file and attaches it to the message
       (repeatable; max 10 attachments per message).
   ticlawk message read --target "<target>" [--around <msg-id>] [--before-seq N] [--limit N]
@@ -1325,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

@@ -7,7 +7,8 @@
  * and forwards to the ticlawk backend using the connector API key.
  *
  * Targets are parsed in the daemon (not on the wire to backend) so the
- * CLI can speak `#<group>` / `dm:@<user>` / `#<group>:<short-msg-id>`
+ * CLI can speak `#<group>` / `dm:<conversation-id>` / `dm:@<user>` /
+ * `#<group>:<short-msg-id>`
  * while backend keeps a flat conversation_id contract.
  */
 
@@ -981,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({
@@ -994,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

@@ -71,18 +71,45 @@ Core concepts:
 - 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.
+- 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 "..." --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.
 `);
 }
 
 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.
+- 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.
+- 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.
+`);
+}
+
+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.
 `);
 }
 
@@ -91,6 +118,7 @@ function buildGoalLoopOverlay() {
 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.
@@ -101,7 +129,7 @@ Goal authority overlay: responsible for this conversation's goal and tasks
 - 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.
@@ -136,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.
@@ -182,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

@@ -37,7 +37,7 @@ private activity text; it is not sent to users or groups.
 ## Per-Turn Routine
 
 1. Read \`MEMORY.md\` in your cwd, then only the files/context needed for
-   the current turn.
+   the current turn. Follow linked notes only when they are relevant.
 2. If there is no concrete inbound message or reminder to handle, stop.
 3. If the message includes \`[charter]\`, treat it as the local
    conversation goal and role spec.
@@ -56,10 +56,18 @@ private activity text; it is not sent to users or groups.
 - \`ticlawk charter get/set\`: inspect or update the current conversation's
   goal and role spec. DM agents may write their DM charter; group charter
   writes require admin/owner role.
+- \`ticlawk dashboard set/get\`: publish or read owner-facing HTML
+  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 \`--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.
@@ -105,7 +113,8 @@ private activity text; it is not sent to users or groups.
 
 If a new message arrives while you are busy, finish the current step before
 pivoting unless the new message clearly supersedes the current work. The
-daemon will wake or notify you again; you do not need to poll for messages.`;
+daemon wakes agents for new messages and reminders; you do not need to poll.
+When future self-resume is needed, schedule a reminder.`;
 
 export function buildStandingPrompt(_ctx = {}) {
   return promptBlock(`

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

@@ -105,7 +105,7 @@ ${charter}
 // `messages.metadata.quote = { kind, ref, snippet }`. We render a
 // short, prefix-cache-friendly block and tell the agent how to fetch
 // the full content if needed.
-export function buildQuoteBlock(msg) {
+export function buildQuoteBlock(msg, target = '') {
   const meta = msg.message_metadata || msg.metadata || null;
   const quote = meta && typeof meta === 'object' ? meta.quote : null;
   if (!quote || typeof quote !== 'object') return '';
@@ -116,9 +116,9 @@ export function buildQuoteBlock(msg) {
   const fetchHint = kind === 'briefing'
     ? `ticlawk briefing get ${ref}`
     : kind === 'dashboard'
-      ? `ticlawk dashboard get --target "#${ref}"`
+      ? `ticlawk dashboard get --conversation-id ${ref}`
       : kind === 'message'
-        ? `ticlawk message read --around ${ref}`
+        ? `ticlawk message read --target ${JSON.stringify(target)} --around ${ref}`
         : '';
   const snippetLine = snippet ? `\n  "${snippet.replace(/"/g, '\\"')}"` : '';
   const fetchLine = fetchHint ? `\n  fetch: ${fetchHint}` : '';
@@ -160,7 +160,7 @@ export function buildInboundWakePrompt(msg) {
   const target = buildEnvelopeTarget(msg);
   const groupContext = buildGroupContextBlock(msg);
   const charterBlock = buildCharterBlock(msg);
-  const quoteBlock = buildQuoteBlock(msg);
+  const quoteBlock = buildQuoteBlock(msg, target);
   const text = header
     ? buildWakePromptText({ envelopeHeader: header, target, rawText, groupContext, charterBlock, quoteBlock })
     : rawText;