forge-openclaw-plugin 0.2.25 → 0.2.27

package/server/migrations/040_screen_time_domain.sql

@@ -0,0 +1,89 @@
+CREATE TABLE IF NOT EXISTS screen_time_settings (
+  user_id TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  tracking_enabled INTEGER NOT NULL DEFAULT 0,
+  sync_enabled INTEGER NOT NULL DEFAULT 1,
+  authorization_status TEXT NOT NULL DEFAULT 'not_determined',
+  capture_state TEXT NOT NULL DEFAULT 'disabled',
+  last_captured_day_key TEXT,
+  last_capture_started_at TEXT,
+  last_capture_ended_at TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS screen_time_day_summaries (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  pairing_session_id TEXT REFERENCES companion_pairing_sessions(id) ON DELETE SET NULL,
+  source_device TEXT NOT NULL DEFAULT 'iPhone',
+  date_key TEXT NOT NULL,
+  total_activity_seconds INTEGER NOT NULL DEFAULT 0,
+  pickup_count INTEGER NOT NULL DEFAULT 0,
+  notification_count INTEGER NOT NULL DEFAULT 0,
+  first_pickup_at TEXT,
+  longest_activity_seconds INTEGER NOT NULL DEFAULT 0,
+  top_app_bundle_ids_json TEXT NOT NULL DEFAULT '[]',
+  top_category_labels_json TEXT NOT NULL DEFAULT '[]',
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (user_id, source_device, date_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_screen_time_day_summaries_user
+  ON screen_time_day_summaries(user_id, date_key DESC);
+
+CREATE TABLE IF NOT EXISTS screen_time_hourly_segments (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  pairing_session_id TEXT REFERENCES companion_pairing_sessions(id) ON DELETE SET NULL,
+  source_device TEXT NOT NULL DEFAULT 'iPhone',
+  date_key TEXT NOT NULL,
+  hour_index INTEGER NOT NULL,
+  started_at TEXT NOT NULL,
+  ended_at TEXT NOT NULL,
+  total_activity_seconds INTEGER NOT NULL DEFAULT 0,
+  pickup_count INTEGER NOT NULL DEFAULT 0,
+  notification_count INTEGER NOT NULL DEFAULT 0,
+  first_pickup_at TEXT,
+  longest_activity_started_at TEXT,
+  longest_activity_ended_at TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (user_id, source_device, date_key, hour_index)
+);
+
+CREATE INDEX IF NOT EXISTS idx_screen_time_hourly_segments_user
+  ON screen_time_hourly_segments(user_id, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS screen_time_app_usage (
+  id TEXT PRIMARY KEY,
+  segment_id TEXT NOT NULL REFERENCES screen_time_hourly_segments(id) ON DELETE CASCADE,
+  bundle_identifier TEXT NOT NULL,
+  display_name TEXT NOT NULL DEFAULT '',
+  category_label TEXT,
+  total_activity_seconds INTEGER NOT NULL DEFAULT 0,
+  pickup_count INTEGER NOT NULL DEFAULT 0,
+  notification_count INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (segment_id, bundle_identifier)
+);
+
+CREATE INDEX IF NOT EXISTS idx_screen_time_app_usage_segment
+  ON screen_time_app_usage(segment_id, total_activity_seconds DESC);
+
+CREATE TABLE IF NOT EXISTS screen_time_category_usage (
+  id TEXT PRIMARY KEY,
+  segment_id TEXT NOT NULL REFERENCES screen_time_hourly_segments(id) ON DELETE CASCADE,
+  category_label TEXT NOT NULL,
+  total_activity_seconds INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (segment_id, category_label)
+);
+
+CREATE INDEX IF NOT EXISTS idx_screen_time_category_usage_segment
+  ON screen_time_category_usage(segment_id, total_activity_seconds DESC);

package/server/migrations/041_companion_source_states.sql

@@ -0,0 +1,21 @@
+CREATE TABLE IF NOT EXISTS companion_pairing_source_states (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  source_key TEXT NOT NULL,
+  desired_enabled INTEGER NOT NULL DEFAULT 1,
+  applied_enabled INTEGER NOT NULL DEFAULT 0,
+  authorization_status TEXT NOT NULL DEFAULT 'not_determined',
+  sync_eligible INTEGER NOT NULL DEFAULT 0,
+  last_observed_at TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE (pairing_session_id, source_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_companion_pairing_source_states_pairing
+  ON companion_pairing_source_states(pairing_session_id, source_key);
+
+CREATE INDEX IF NOT EXISTS idx_companion_pairing_source_states_user
+  ON companion_pairing_source_states(user_id, updated_at DESC);

package/server/migrations/042_movement_boxes.sql

@@ -0,0 +1,47 @@
+CREATE TABLE IF NOT EXISTS movement_boxes (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('stay', 'trip', 'missing')),
+  source_kind TEXT NOT NULL CHECK (source_kind IN ('automatic', 'user_defined')),
+  origin TEXT NOT NULL CHECK (
+    origin IN (
+      'recorded',
+      'continued_stay',
+      'repaired_gap',
+      'missing',
+      'user_defined',
+      'user_invalidated'
+    )
+  ),
+  started_at TEXT NOT NULL,
+  ended_at TEXT NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  subtitle TEXT NOT NULL DEFAULT '',
+  place_label TEXT,
+  anchor_external_uid TEXT,
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  distance_meters REAL,
+  average_speed_mps REAL,
+  editable INTEGER NOT NULL DEFAULT 0,
+  override_count INTEGER NOT NULL DEFAULT 0,
+  overridden_automatic_box_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_stay_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_trip_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_point_count INTEGER NOT NULL DEFAULT 0,
+  has_legacy_corrections INTEGER NOT NULL DEFAULT 0,
+  legacy_origin_key TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  deleted_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_movement_boxes_user_time
+ON movement_boxes(user_id, started_at, ended_at);
+
+CREATE INDEX IF NOT EXISTS idx_movement_boxes_user_source
+ON movement_boxes(user_id, source_kind, deleted_at, started_at);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_movement_boxes_legacy_origin
+ON movement_boxes(user_id, legacy_origin_key)
+WHERE legacy_origin_key IS NOT NULL;

package/server/migrations/043_movement_box_overlap_overrides.sql

@@ -0,0 +1,26 @@
+ALTER TABLE movement_boxes
+ADD COLUMN true_started_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN true_ended_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_started_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_ended_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_by_box_id TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_user_box_ids_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE movement_boxes
+ADD COLUMN override_ranges_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE movement_boxes
+ADD COLUMN is_overridden INTEGER NOT NULL DEFAULT 0;
+
+ALTER TABLE movement_boxes
+ADD COLUMN is_fully_hidden INTEGER NOT NULL DEFAULT 0;

package/skills/forge-openclaw/SKILL.md

@@ -41,8 +41,9 @@ Wiki navigation and search rule:
 Health rule:
 
 - Sleep and sports records are first-class health surfaces, not generic notes or tasks.
-- Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review.
-- Use `forge_update_sleep_session` and `forge_update_workout_session` when the user wants to attach reflective context, tags, or Forge links to an existing health record.
+- Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review and trend reading.
+- Use the shared batch entity tools for ordinary `sleep_session` and `workout_session` create, update, delete, and search work. Do not force agents into a large one-route-per-entity mental model when the batch routes already cover the record cleanly.
+- Use `forge_update_sleep_session` and `forge_update_workout_session` only when the job is reflective enrichment on one existing health record after review, such as attaching notes, tags, mood, meaning, or Forge links.
 - Habit-generated workouts and imported HealthKit workouts belong to the same workout record model, so do not invent a separate storage path for sport sessions.
 
 Write to Forge only with clear user consent. If the user is just thinking aloud, helping first is usually better than writing immediately. After helping, you may offer one short Forge prompt if the match is strong. If the user agrees, ask only for the missing fields and only one to three focused questions at a time. Do not offer Forge again after a decline unless the user reopens it.
@@ -56,15 +57,17 @@ Entity conversation rule:
 - Prefer a progression of:
   concrete example or intent -> working name -> purpose or meaning -> placement in Forge -> operational details -> linked context.
 - For emotionally meaningful non-Psyche records such as goals, habits, and notes, reflect the meaning before you ask for structure.
+- When the user is vague, ask for one small concrete example, stake, or desired outcome before you ask them to name the record.
+- When the user is clear, say what the record seems to be becoming and ask only for the last missing detail.
 - When updating an entity, start with what is changing, what should stay true, and what prompted the update now.
 - When enough is clear, briefly summarize what you heard in the user's own language before asking for the last missing structural detail.
 - The quick intake prompts later in this file are fallback checkpoints, not a script to read aloud.
 
 Forge data location rule:
 
-- by default, Forge stores data under the active runtime root at `data/forge.sqlite`
-- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/data/forge.sqlite`
-- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
+- by default, Forge stores data under the active runtime root at `forge.sqlite`
+- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/forge.sqlite`
+- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/forge.sqlite`
 - if the user wants the data somewhere else for persistence, backup, or manual control, tell them to set `plugins.entries["forge-openclaw-plugin"].config.dataRoot` and restart the OpenClaw gateway
 - if the user asks where the data is stored or how to move it, explain the current default plainly and show the exact config field
 
@@ -76,6 +79,7 @@ Psyche interview rule:
 - Start from a recent concrete example before naming an abstract pattern, belief, or mode.
 - Sound professionally warm and therapist-like: grounded, accurate, reflective, and intentional, not clinical, vague, or lecture-like.
 - After the first real answer, choose one follow-up lane at a time: situation, sequence, meaning, protection, cost, longing/value, or tentative name.
+- For Psyche updates, start with what feels newly true, newly visible, or newly inaccurate, then ask what should stay true before changing the formulation.
 - If the user says they want help understanding a Psyche issue before saving it, ask one orienting question first instead of jumping straight into a full interpretation, diagnosis-like label, save suggestion, replacement belief, or suggested title.
 - In that first exploratory turn, keep the reflection to one or two short sentences, avoid numbered lists or schema dumps, and wait for the user's answer before offering a fuller formulation.
 - In that first exploratory turn, stay in plain prose, end with one question, and do not mention Forge fields or save formatting yet unless the user interrupts to save immediately.
@@ -279,12 +283,12 @@ Use the batch entity tools for stored records:
 `forge_search_entities`, `forge_create_entities`, `forge_update_entities`, `forge_delete_entities`, `forge_restore_entities`
 
 These tools operate on:
-`goal`, `project`, `task`, `habit`, `note`, `calendar_event`, `work_block_template`, `task_timebox`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, `emotion_definition`
+`goal`, `project`, `strategy`, `task`, `habit`, `tag`, `note`, `insight`, `calendar_event`, `work_block_template`, `task_timebox`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, `emotion_definition`, `preference_catalog`, `preference_catalog_item`, `preference_context`, `preference_item`, `questionnaire_instrument`, `sleep_session`, `workout_session`
 
 Use the wiki tools for file-first memory work:
 `forge_get_wiki_settings`, `forge_list_wiki_pages`, `forge_get_wiki_page`, `forge_search_wiki`, `forge_upsert_wiki_page`, `forge_get_wiki_health`, `forge_sync_wiki_vault`, `forge_reindex_wiki_embeddings`, `forge_ingest_wiki_source`
 
-Sleep and workout sessions are not batch entities. Use the health tools instead:
+Use the health tools for review and reflective enrichment, not as the default CRUD architecture:
 `forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
 
 Use live work tools for `task_run`:
@@ -340,7 +344,7 @@ For project deletion and recovery, prefer the generic delete and restore tools:
 
 For restore operations, each item must include `entityType` and `id`.
 
-Batch tools do not create or control `task_run` or `insight`.
+Batch tools do not create or control `task_run`.
 
 Use the exact route-facing field names. Do not invent friendlier aliases. If a field name is unclear, use `forge_get_agent_onboarding` as the schema source of truth.
 
@@ -373,10 +377,21 @@ Use the health tools when the request is about sleep or sports review:
 
 - `forge_get_sleep_overview` to inspect recent nights, averages, regularity, stage breakdown, and linked reflective context
 - `forge_get_sports_overview` to inspect training volume, workout types, effort trends, habit-generated sessions, and linked context
-- `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities
-- `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout
+- `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities after review
+- `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout after review
 - remember that the UI route is `/sports` while the backend overview route is `/api/v1/health/fitness`
 
+Use these exact health batch payload shapes when the user is creating or editing the stored records themselves:
+
+- create a manual sleep session:
+  `{"operations":[{"entityType":"sleep_session","data":{"startedAt":"2026-04-10T22:45:00.000Z","endedAt":"2026-04-11T06:45:00.000Z","qualitySummary":"Slept cleanly after a light evening.","links":[{"entityType":"habit","entityId":"habit_sleep_hygiene","relationshipType":"supports"}]}}]}`
+- update a sleep session through batch CRUD:
+  `{"operations":[{"entityType":"sleep_session","id":"sleep_123","patch":{"notes":"Woke once around 03:00 but settled quickly.","tags":["travel","recovered"]}}]}`
+- create a manual workout session:
+  `{"operations":[{"entityType":"workout_session","data":{"workoutType":"walk","startedAt":"2026-04-11T10:00:00.000Z","endedAt":"2026-04-11T10:45:00.000Z","subjectiveEffort":6,"meaningText":"Reset after a long planning block.","links":[{"entityType":"task","entityId":"task_123","relationshipType":"supports"}]}}]}`
+- update a workout session through batch CRUD:
+  `{"operations":[{"entityType":"workout_session","id":"workout_123","patch":{"moodAfter":"clear","tags":["zone2"]}}]}`
+
 Work-block payload guidance:
 
 - `kind` must be one of `main_activity`, `secondary_activity`, `third_activity`, `rest`, `holiday`, or `custom`
@@ -473,7 +488,8 @@ Additional first-class surfaces:
 
 - Use the high-level batch routes for basic Preferences CRUD. `preference_catalog`, `preference_catalog_item`, `preference_context`, and `preference_item` all go through `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities`.
 - Use the high-level batch routes for basic questionnaire CRUD too. `questionnaire_instrument` goes through `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities`.
+- Use the high-level batch routes for ordinary health-session CRUD too. `sleep_session` and `workout_session` go through `forge_search_entities`, `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities` by default. Keep the dedicated health tools for review surfaces and reflective enrichment on one record.
 - Keep the dedicated Preferences tools only for real preference actions and read models: `forge_get_preferences_workspace`, `forge_start_preferences_game`, `forge_merge_preferences_contexts`, `forge_enqueue_preferences_item_from_entity`, `forge_submit_preferences_judgment`, `forge_submit_preferences_signal`, and `forge_update_preferences_score`.
 - Keep the dedicated questionnaire tools only for real flow actions and read models: `forge_list_questionnaires`, `forge_get_questionnaire`, `forge_clone_questionnaire`, `forge_ensure_questionnaire_draft`, `forge_publish_questionnaire_draft`, `forge_start_questionnaire_run`, `forge_get_questionnaire_run`, `forge_update_questionnaire_run`, and `forge_complete_questionnaire_run`.
 - Self-observation is note-backed. Read the calendar through `forge_get_self_observation_calendar`, but create or update the stored observation as a `note` tagged `Self-observation` with `frontmatter.observedAt` and links to the relevant `behavior_pattern`, `trigger_report`, or other Forge records.
-- `sleep_session` and `workout_session` are first-class health records. Review them through the dedicated health tools instead of treating them like loose notes.
+- `sleep_session` and `workout_session` are first-class health records. Treat them like ordinary stored entities for CRUD, and use the dedicated health tools for read models or post-review enrichment rather than pretending they live on a special mutation island.