ticlawk 0.1.17-dev.1 → 0.1.17-dev.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.17-dev.1",
+  "version": "0.1.17-dev.10",
   "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 (owner-local) [--recur-weekday 1,2,3].
+  // The timezone is system-owned (the owner's), filled in by the backend — the
+  // agent never passes it. The backend also computes the first fire_at in it.
+  let recurrence = null;
+  const recurAt = getArg(args, 'recur-at');
+  if (recurAt) {
+    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, ...(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
+  (the owner's local HH:MM) and optionally --recur-weekday (ISO 1=Mon..7=Sun,
+  comma-separated; omit for every day). You do NOT set a timezone — the backend
+  fills the owner's timezone and computes the fire time in it. On each fire the
+  reminder auto-advances to the next occurrence and stays active. Example —
+  weekday 18:30 dinner check-in (--fire-at is ignored for recurring, the backend
+  computes it):
+    ticlawk reminder schedule --title "晚餐" --anchor-conversation-id <id> \\
+      --in-minutes 1 --recur-at 18:30 --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

@@ -15,17 +15,18 @@ import { buildEnvelopeTarget, buildCharterBlock } from './wake-prompt.mjs';
 const STEP_GUIDES = {
   gap_analysis: {
     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.
-- 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, report outcome=no_gap.
-- 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.`,
+    body: `Compare the current state against the goal and success criteria. The [goal_context] block above gives you the open tasks, active reminders, and dashboard state — judge from it; read the charter/repo/prior messages only for what it doesn't cover. 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: create it if a durable goal has none, refresh it when progress moved materially (\`ticlawk dashboard set\`; see SURFACES.md).
+- Judge "due now" against the current owner-local time above. Produce only what is due now; do NOT pre-produce future occurrences (a later meal, tomorrow's item) — each one is produced when its own reminder fires and wakes you at that time.
+- If there is concrete work to do NOW, make sure the next unit exists as a task (\`ticlawk task ...\`), then report outcome=gap.
+- If nothing needs doing this instant but the goal is ONGOING/STANDING — its job is to keep something maintained and work recurs (e.g. an active recurring reminder above already covers the next occurrence) — report outcome=wait. Do NOT report no_gap for a standing goal: it has no "done", and parking on no_gap would stop it from waking at the next occurrence. If nothing is scheduled to resume it yet, schedule a reminder first, then report wait.
+- Report outcome=no_gap ONLY if the goal is genuinely, permanently met and will never need action again (an achievement goal that is finished). The completed result is something the owner is waiting on — surface it per the briefing rule below.`,
     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>"]\`, tell the owner what you need and why with \`ticlawk message send\`, 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'],
   },
@@ -48,6 +49,34 @@ function readPayload(msg) {
   };
 }
 
+// Per-step context: the claim attaches msg.goal_context (open tasks, active
+// reminders, current task, dashboard) for transition deliveries. Render the
+// slice THIS step needs so each step decides on facts, not guesses.
+function buildGoalContextBlock(msg, step) {
+  const gc = msg && msg.goal_context && typeof msg.goal_context === 'object' ? msg.goal_context : null;
+  if (!gc) return '';
+  const lines = ['[goal_context] Current state for this goal (given to you — use it, do not re-derive):'];
+  if (gc.now_local) {
+    lines.push(`- current time (owner local): ${gc.now_local}${gc.timezone ? ` [${gc.timezone}]` : ''}`);
+  }
+  if (step === 'gap_analysis' || !STEP_GUIDES[step]) {
+    const tasks = Array.isArray(gc.open_tasks) ? gc.open_tasks : [];
+    const rems = Array.isArray(gc.active_reminders) ? gc.active_reminders : [];
+    lines.push(`- open tasks (${tasks.length}): ${tasks.length
+      ? tasks.map((t) => `#${t.number} ${t.title} [${t.status}]`).join('; ')
+      : 'none'}`);
+    lines.push(`- active reminders (${rems.length}): ${rems.length
+      ? rems.map((r) => `"${r.title}" @ ${r.fire_at}${r.recurrence ? ' (recurring)' : ''}`).join('; ')
+      : 'none'}`);
+    lines.push(`- dashboard: ${gc.dashboard ? 'exists' : 'none yet'}`);
+  } else {
+    const ct = gc.current_task;
+    lines.push(ct ? `- current task: #${ct.number} ${ct.title} [${ct.status}]` : '- current task: (none set)');
+  }
+  lines.push('[/goal_context]');
+  return lines.join('\n');
+}
+
 function buildGoalStepHeader(msg, { step, transitionId, goalVersion, kind }) {
   const target = buildEnvelopeTarget(msg);
   const time = msg.created_at || new Date().toISOString();
@@ -66,6 +95,8 @@ export function buildGoalStepPrompt(msg) {
 
   const sections = [];
   if (charterBlock) sections.push(charterBlock);
+  const goalContextBlock = buildGoalContextBlock(msg, step);
+  if (goalContextBlock) sections.push(goalContextBlock);
 
   if (guide) {
     sections.push([
@@ -74,10 +105,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. Send owner-facing updates with \`ticlawk message send --target ${target} --phase progress\` (use --phase final only when the loop reaches no_gap/wait/blocked-on-owner). 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-weekday 1,2,3]`. Give `--recur-at` as the owner's local wall-clock time; the timezone is filled in by the system, so you never pass it. It auto-advances to the next occurrence on each fire and stays active, so the cadence never runs out.

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

@@ -20,6 +20,24 @@ ${buildReadInstructions(ctx)}
 Read other local files only when the current work clearly needs them.`;
 }
 
+// A goal-lane turn is a single backend FSM step, not a chat message. Its
+// per-step instructions and exact CLI commands (`goal report`, `task`,
+// `approval request`, `message send`) live in the goal-step (user) prompt
+// built by goal-step-prompt.mjs. The system prompt here therefore stays
+// minimal: identity + the one reply invariant. It deliberately omits the
+// chat-lane role framing and handbook read-list, which would compete with
+// the narrow step instruction and pull the model toward proactive
+// assistant behavior. See system.md "Lane-aware standing prompt".
+function buildGoalLaneStandingPrompt(_ctx = {}) {
+  return `You are executing one backend goal-loop step for this conversation, dispatched by the system — not a message from a person. Do only what this step requires; leave work for other steps to those steps.
+
+Your normal output is private and reaches no one. The owner is reached only through Ticlawk surfaces: \`ticlawk message send\` (chat update), \`ticlawk briefing publish\` (active notification/decision), \`ticlawk dashboard set\` (goal-level report). The step tells you which one to use; \`SURFACES.md\` holds the rules for each. Read \`SURFACES.md\` or \`MEMORY.md\` only if the step needs them.`;
+}
+
+function isGoalLane(ctx = {}) {
+  return ctx?.inbound?.lane === 'goal' || readDeliveryReason(ctx) === 'transition';
+}
+
 function getInboundRaw(ctx = {}) {
   return ctx?.inbound?.raw && typeof ctx.inbound.raw === 'object'
     ? ctx.inbound.raw
@@ -144,6 +162,7 @@ function unique(values) {
 }
 
 export function buildStandingPrompt(_ctx = {}) {
+  if (isGoalLane(_ctx)) return promptBlock(buildGoalLaneStandingPrompt(_ctx));
   return promptBlock(buildBaseStandingPrompt(_ctx));
 }
 

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

@@ -84,8 +84,23 @@ export function buildGroupContextBlock(msg) {
 
 export function buildCharterBlock(msg) {
   const charter = (msg.conversation_charter || '').trim();
-  if (!charter) return '';
   const conversationId = msg.conversation_id || '';
+
+  // No charter yet: the goal loop has never been bootstrapped. A transition
+  // cannot arrive before a goal exists, and only the goal-authority agent may
+  // start one — so give that agent (and only it) the bootstrap path. Without
+  // this, a conversation's FIRST goal can never reach the goal lane, because
+  // the steady-state guidance below is gated on a charter already existing.
+  if (!charter) {
+    if (msg.reason === 'transition' || !hasGoalAuthority(msg)) return '';
+    return promptBlock(`
+[conversation_goal]
+This conversation has no goal charter yet, so the backend goal loop is not running.
+If this message sets a goal for this conversation, capture it as the charter — the goal and what "done" looks like, in the owner's words — with \`ticlawk charter set --conversation ${conversationId}\` (body on stdin), then run \`ticlawk goal changed --conversation ${conversationId}\` to start the goal loop. Otherwise handle the message normally. See GOAL_AUTHORITY.md.
+[/conversation_goal]
+`);
+  }
+
   // The goal lane (transition deliveries) executes against the charter; its
   // per-step instructions come from the goal-step prompt, so here the charter
   // is just the goal/success spec. The chat lane must NOT run the loop — it