ticlawk 0.1.17-dev.4 → 0.1.17-dev.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.17-dev.4",
+  "version": "0.1.17-dev.6",
   "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

@@ -375,7 +375,7 @@ export async function getAgentServerInfo({ actingAgentId }) {
 // ── Reminders ──
 
 export async function scheduleAgentReminder({
-  actingAgentId, title, fireAt, anchorConversationId, anchorMessageId,
+  actingAgentId, title, fireAt, anchorConversationId, anchorMessageId, recurrence,
 }) {
   return apiFetch('/api/agent/reminders', {
     method: 'POST',
@@ -385,6 +385,7 @@ export async function scheduleAgentReminder({
       fire_at: fireAt,
       anchor_conversation_id: anchorConversationId,
       anchor_message_id: anchorMessageId ?? null,
+      recurrence: recurrence ?? null,
     }),
   });
 }

package/src/cli/agent-commands.mjs

@@ -557,6 +557,18 @@ export async function runReminderScheduleCommand(args) {
     console.error('--target or --anchor-conversation-id is required');
     return 2;
   }
+  // Optional recurrence: --recur-at HH:MM [--recur-tz <IANA>] [--recur-weekday 1,2,3].
+  // --fire-at remains the FIRST occurrence; the rule advances it after each fire.
+  let recurrence = null;
+  const recurAt = getArg(args, 'recur-at');
+  if (recurAt) {
+    const tz = getArg(args, 'recur-tz') || 'UTC';
+    const wdRaw = getArg(args, 'recur-weekday');
+    const byWeekday = wdRaw
+      ? String(wdRaw).split(',').map((s) => parseInt(s.trim(), 10)).filter((n) => n >= 1 && n <= 7)
+      : [];
+    recurrence = { at: recurAt, tz, ...(byWeekday.length ? { by_weekday: byWeekday } : {}) };
+  }
   const res = await daemonRequest({
     method: 'POST',
     path: '/agent/reminder/schedule',
@@ -567,6 +579,7 @@ export async function runReminderScheduleCommand(args) {
       target,
       anchor_conversation_id: anchorConversationId,
       anchor_message_id: anchorMessageId,
+      recurrence,
     },
   });
   printJson(res.body);
@@ -1425,7 +1438,7 @@ export const AGENT_COMMAND_HELP = {
     to a user, use \`ticlawk message send --attach <file>\` instead.
 `,
   reminder: `ticlawk reminder <schedule|list|snooze|update|cancel|log>
-  ticlawk reminder schedule --title <t> (--fire-at <iso> | --in-seconds N | --in-minutes N) (--target "<target>" | --anchor-conversation-id <id>) [--anchor-message-id <id>]
+  ticlawk reminder schedule --title <t> (--fire-at <iso> | --in-seconds N | --in-minutes N) (--target "<target>" | --anchor-conversation-id <id>) [--anchor-message-id <id>] [--recur-at HH:MM [--recur-tz <IANA>] [--recur-weekday 1,2,3]]
   ticlawk reminder list [--status active|fired|canceled]
   ticlawk reminder snooze <reminder-id> (--fire-at <iso> | --in-seconds N | --in-minutes N)
   ticlawk reminder update <reminder-id> [--title <t>] [--fire-at <iso>]
@@ -1435,6 +1448,17 @@ export const AGENT_COMMAND_HELP = {
   Use reminders for follow-up that depends on future state you cannot resolve
   now. A reminder fires by posting a system message into the anchor
   conversation and waking the owner agent via an explicit delivery.
+
+  RECURRING: for a fixed cadence (e.g. a daily/weekly meal-time check-in), use
+  ONE recurring reminder instead of enumerating many one-shots. Pass --recur-at
+  (local HH:MM), --recur-tz (the owner's IANA timezone), and optionally
+  --recur-weekday (ISO 1=Mon..7=Sun, comma-separated; omit for every day).
+  --fire-at is still the FIRST occurrence; on each fire the reminder
+  auto-advances to the next occurrence and stays active. Example — weekday
+  18:30 Beijing dinner check-in:
+    ticlawk reminder schedule --title "晚餐" --anchor-conversation-id <id> \\
+      --fire-at <next 18:30 Beijing as ISO> \\
+      --recur-at 18:30 --recur-tz Asia/Shanghai --recur-weekday 1,2,3,4,5
 `,
   task: `ticlawk task <create|claim|unclaim|update|list>
   ticlawk task create --target "<target>" [--title <t>] [--assign-agent <agent-id>]

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

@@ -590,6 +590,7 @@ export async function handleReminderSchedule(req, body, ctx) {
       fireAt: body.fire_at,
       anchorConversationId,
       anchorMessageId: body?.anchor_message_id || null,
+      recurrence: body?.recurrence ?? null,
     });
     debugLog('agent-cli', 'reminder.schedule', {
       actingAgentId,

package/src/runtimes/_shared/goal-step-prompt.mjs

@@ -17,15 +17,15 @@ const STEP_GUIDES = {
     title: 'GAP ANALYSIS',
     body: `Compare the current state of the work against the goal and success criteria. Read whatever you need (charter, dashboard, task board, repo, prior messages) to judge where things actually stand. The dashboard is the owner's at-a-glance visualization of how far this goal has progressed — this step owns keeping it true to reality: if a durable goal has no dashboard yet, create it (\`ticlawk dashboard set\`); if overall progress has moved materially, refresh its content/data. See SURFACES.md.
 - If there is concrete executable work toward the goal, first make sure the next unit exists as a task (create/assign it with \`ticlawk task ...\` when a task fits), then report outcome=gap.
-- If the goal/milestone is fully met with no meaningful gap, make sure the dashboard reflects the completed state, publish a final-result briefing for the owner (\`ticlawk briefing publish --mode info\`), then report outcome=no_gap.
+- If the goal/milestone is fully met with no meaningful gap, make sure the dashboard reflects the completed state, then report outcome=no_gap. (The completed result is something the owner is waiting on — surface it per the briefing rule below.)
 - If closing the gap depends on a future or external state that nobody can act on right now, schedule a reminder for the resume condition, then report outcome=wait.`,
     outcomes: ['gap', 'no_gap', 'wait'],
   },
   execute: {
     title: 'EXECUTE',
-    body: `Do the next concrete unit of work toward the goal (or drive the current task to completion). Send interim updates with \`ticlawk message send --phase progress\` as you go.
+    body: `Do the next concrete unit of work toward the goal (or drive the current task to completion). Send routine interim progress with \`ticlawk message send --phase progress\`; if an update clears the briefing bar below (e.g. it is a result the owner explicitly asked to be told about), surface it as a briefing instead.
 - When the unit of work is finished and ready to be checked, report outcome=task_completed.
-- If you cannot proceed without an owner approval, decision, or permission, park ONE canonical approval with \`ticlawk approval request --title "<what you need approved>" [--detail "<context>"]\`, surface the decision to the owner with a briefing (\`ticlawk briefing publish --mode approval\`) saying what you need and why, then report outcome=needs_approval. The owner's approval (button or a natural-language reply) resumes you automatically.
+- If you cannot proceed without an owner approval, decision, or permission, park ONE canonical approval with \`ticlawk approval request --title "<what you need approved>" [--detail "<context>"]\`, tell the owner what you need and why, then report outcome=needs_approval. The owner's approval (button or a natural-language reply) resumes you automatically.
 - If you are blocked by something else (missing input, external failure, a needed resource), explain it to the owner, then report outcome=blocked.`,
     outcomes: ['task_completed', 'needs_approval', 'blocked'],
   },
@@ -74,10 +74,16 @@ export function buildGoalStepPrompt(msg) {
       `Current step: ${guide.title}`,
       guide.body,
       ``,
+      `Briefing rule (independent of which step you are on): a briefing (\`ticlawk briefing publish\`) interrupts the owner — it is only for things worth their attention. Default to NOT sending one; routine progress belongs on the dashboard (the owner pulls it) or a chat \`ticlawk message send\`. Send a briefing only when one of these holds:`,
+      `  (a) the owner must act or decide — e.g. an approval you parked (\`--mode approval\`);`,
+      `  (b) the owner asked to be told about this — a standing request, a scheduled time, or a threshold they set (\`--mode info\`);`,
+      `  (c) something happened the owner would be wrong not to know now — goal done, blocked, materially off-track, or a result they are waiting on (\`--mode info\`).`,
+      `If you are unsure, it is NOT a briefing — put it on the dashboard. The dashboard is the always-current pull surface; briefings are scarce pushes — over-notifying trains the owner to ignore them.`,
+      ``,
       `When the step is done, advance the state machine by running EXACTLY ONE report:`,
       `  ${reportCmd}`,
       ``,
-      `Reporting the outcome is what continues the loop: a running next state arrives as a fresh step, and the loop parks itself when there is no gap or it must wait. Reach the owner only through the surface this step names (\`ticlawk message send --target ${target}\` for chat, plus \`briefing publish\`/\`dashboard set\` where the step calls for them; see \`SURFACES.md\`). Any owner-facing text — chat, briefing, or dashboard — is for the owner in their language: say what changed, why it matters, and what (if anything) they must do; never expose internal task titles, file paths, step numbers, or harness tokens. Report exactly once; do not loop inside this single turn.`,
+      `Reporting the outcome is what continues the loop: a running next state arrives as a fresh step, and the loop parks itself when there is no gap or it must wait. Reach the owner only through Ticlawk surfaces — \`ticlawk message send --target ${target}\` (chat), \`ticlawk briefing publish\` (push, per the rule above), \`ticlawk dashboard set\` (goal report); see \`SURFACES.md\`. Any owner-facing text is for the owner in their language: say what changed, why it matters, and what (if anything) they must do; never expose internal task titles, file paths, step numbers, or harness tokens. Report exactly once; do not loop inside this single turn.`,
       `[/goal_step]`,
     ].join('\n'));
   } else {

package/src/runtimes/_shared/handbook/SURFACES.md

@@ -39,3 +39,5 @@ Use `ticlawk credential request --name <ENV_VAR>` to create the credential slot.
 ## Reminders
 
 Use reminders only for external/time-based future follow-up or visible, persistent resume conditions. Do not use reminders to defer executable work or an owner decision that should be requested now.
+
+For a fixed cadence (a daily or weekly check-in, e.g. meal-time reminders), use ONE recurring reminder, not many enumerated one-shots: `ticlawk reminder schedule ... --recur-at HH:MM --recur-tz <owner IANA tz> [--recur-weekday 1,2,3]`. It auto-advances to the next occurrence on each fire and stays active, so the cadence never runs out.