nexo-brain 7.23.13 → 7.25.0

package/src/saved_not_used_audit.py

@@ -158,7 +158,7 @@ def format_markdown(report: dict[str, Any]) -> str:
     lines = [
         "## saved_not_used audit",
         "",
-        "| Store | Productor | Consumidor | Ultima escritura | Ultimo uso | Riesgo | Prueba | Estado |",
+        "| Store | Producer | Consumer | Last write | Last use | Risk | Test | Status |",
         "|---|---|---|---|---|---|---|---|",
     ]
     for item in stores or []:
@@ -176,12 +176,12 @@ def format_markdown(report: dict[str, Any]) -> str:
             )
         )
 
-    lines.extend(["", "### Alertas", ""])
+    lines.extend(["", "### Alerts", ""])
     if not findings:
-        lines.append("- Sin alertas saved_not_used.")
+        lines.append("- No saved_not_used alerts.")
     for finding in findings or []:
         lines.append(
-            "- {severity} `{alert_id}` en `{store_id}`: {risk} Prueba: {test}".format(
+            "- {severity} `{alert_id}` in `{store_id}`: {risk} Test: {test}".format(
                 severity=_md(finding.get("severity")),
                 alert_id=_md(finding.get("alert_id")),
                 store_id=_md(finding.get("store_id")),
@@ -196,8 +196,8 @@ def _audit_local_context(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[S
     store = _path_text(cfg.local_context_db_path)
     producer = "nexo-local-index.py -> local_context.api"
     consumer = "nexo_context_router / nexo_local_context / pre_action_context"
-    risk = "Indice local escrito pero no consultado antes de responder."
-    test = "local_assets/chunks/entities > 0 exige local_context_queries reciente."
+    risk = "Local index is written but may not be consulted before answering."
+    test = "local_assets/chunks/entities > 0 requires a recent local_context_queries row."
     if not cfg.local_context_db_path or not cfg.local_context_db_path.exists():
         row = _row("local_context", producer, store, consumer, "", "", risk, test, "missing", "P2", {"path_exists": False})
         return row, []
@@ -264,8 +264,8 @@ def _audit_local_context(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[S
                 consumer,
                 last_write,
                 last_use,
-                "Tablas local_* legacy no vacias pueden atraer consumidores antiguos.",
-                "legacy local_* debe estar vacio o marcado como compat si existe sidecar vivo.",
+                "Non-empty legacy local_* tables may attract old consumers.",
+                "legacy local_* must be empty or marked as compatibility if a live sidecar exists.",
                 {"legacy_main_db_counts": legacy_counts},
             )
         )
@@ -277,8 +277,8 @@ def _audit_memory_pipeline(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list
     store_id = "memory_observations_pipeline"
     producer = "record_memory_event"
     consumer = "memory_observation_worker -> nexo_memory_search / nexo_memory_answer"
-    risk = "Eventos capturados pueden no transformarse en memoria consultable."
-    test = "memory_events y memory_observation_queue deben terminar en memory_observations."
+    risk = "Captured events may fail to become searchable memory."
+    test = "memory_events and memory_observation_queue must end in memory_observations."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     if conn is None:
         return row, []
@@ -308,8 +308,8 @@ def _audit_session_diary(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[S
     store_id = "session_diary"
     producer = "write_session_diary / lifecycle fallback"
     consumer = "startup briefing / nexo_session_diary_read / continuity resume"
-    risk = "Diarios guardados pueden no entrar en continuidad si solo quedan como filas historicas."
-    test = "session_diary debe tener consumidor MCP/startup documentado y fila reciente legible."
+    risk = "Saved diaries may miss continuity if they only remain as historical rows."
+    test = "session_diary must have a documented MCP/startup consumer and a readable recent row."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     if conn is None:
         return row, []
@@ -324,8 +324,8 @@ def _audit_followups_reminders(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow,
     store_id = "followups_reminders"
     producer = "followup/reminder create/update"
     consumer = "nexo_reminders / followup-runner / dashboard"
-    risk = "Items pendientes pueden acumularse sin runner ni lectura humana efectiva."
-    test = "followups/reminders deben tener item_history de consumo o aparecer en nexo_reminders."
+    risk = "Pending items can accumulate without an effective runner or human read path."
+    test = "followups/reminders must have item_history consumption or appear in nexo_reminders."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     if conn is None:
         return row, []
@@ -344,8 +344,8 @@ def _audit_workflows(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[Saved
     store_id = "workflows"
     producer = "nexo_goal_open / nexo_workflow_open / nexo_workflow_update"
     consumer = "workflow_resume / workflow_replay / daily audit"
-    risk = "Workflows abiertos sin checkpoints pierden reanudacion real."
-    test = "workflow_runs abiertos deben tener workflow_checkpoints o updates."
+    risk = "Open workflows without checkpoints lose real resumability."
+    test = "Open workflow_runs must have workflow_checkpoints or updates."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     if conn is None:
         return row, []
@@ -371,8 +371,8 @@ def _audit_change_log(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[Save
     store_id = "change_log"
     producer = "log_change / nexo_task_close"
     consumer = "nexo_change_log / FTS / daily audit / memory export"
-    risk = "Cambios guardados pueden no aparecer en auditorias futuras si el consumidor no consulta change_log."
-    test = "change_log debe tener filas con verify y consumidor MCP."
+    risk = "Saved changes may not appear in future audits if the consumer does not query change_log."
+    test = "change_log must have rows with verify and an MCP consumer."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     if conn is None:
         return row, []
@@ -387,7 +387,7 @@ def _audit_change_log(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[Save
     if missing_verify:
         severity = "P2"
         status = "weak_evidence"
-        findings.append(_finding("change_log_missing_verify", "P2", store_id, producer, row.store, consumer, last_write, "static:nexo_change_log", "Change log sin campo verify reduce prueba de consumo.", test, evidence))
+        findings.append(_finding("change_log_missing_verify", "P2", store_id, producer, row.store, consumer, last_write, "static:nexo_change_log", "Change log rows without verify weaken consumption evidence.", test, evidence))
     return _row(store_id, producer, row.store, consumer, last_write, "static:nexo_change_log", risk, test, status, severity, evidence), findings
 
 
@@ -395,8 +395,8 @@ def _audit_continuity_lifecycle(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow,
     store_id = "continuity_lifecycle"
     producer = "Desktop lifecycle bridge / write_continuity_snapshot"
     consumer = "resume-bundle / lifecycle canonical completion / Desktop flush"
-    risk = "Continuidad local o eventos de cierre pueden quedar escritos sin confirmacion canonica."
-    test = "continuity_queue vacia y lifecycle_events terminal/canonical_done."
+    risk = "Local continuity or close events may be written without canonical confirmation."
+    test = "continuity_queue must be empty and lifecycle_events must be terminal/canonical_done."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     pending_lifecycle = 0
     snapshots = 0
@@ -434,8 +434,8 @@ def _audit_transcripts(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[Sav
     store_id = "transcripts"
     producer = "Claude/Codex clients JSONL"
     consumer = "nexo_transcript_search / nexo_transcript_read fallback"
-    risk = "Sesiones cortas o fuera de roots pueden quedar invisibles al preguntar por trabajo previo."
-    test = "JSONL con >=3 mensajes de usuario debe estar en roots conocidos."
+    risk = "Short sessions or sessions outside roots may stay invisible when asking about prior work."
+    test = "JSONL with >=3 user messages must be in known roots."
     files = _transcript_files(cfg.transcript_roots)
     counts = [_transcript_user_message_count(path) for path in files]
     usable = sum(1 for count in counts if count >= 3)
@@ -460,8 +460,8 @@ def _audit_email_db(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[SavedN
     store_id = "email_db"
     producer = "email_sent_events / nexo-email-monitor"
     consumer = "check-context email lookup / local-context email roots / cognitive ingest"
-    risk = "Emails enviados o monitorizados pueden quedar fuera de continuidad si no se proyectan a memoria."
-    test = "sent_email_events debe tener consumidor directo o memory_events source_type=email_sent."
+    risk = "Sent or monitored emails may miss continuity if they are not projected to memory."
+    test = "sent_email_events must have a direct consumer or memory_events source_type=email_sent."
     store = _path_text(cfg.email_db_path)
     if not cfg.email_db_path or not cfg.email_db_path.exists():
         return _row(store_id, producer, store, consumer, "", "", risk, test, "missing", "P2", {"path_exists": False}), []
@@ -476,7 +476,7 @@ def _audit_email_db(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[SavedN
     if sent and not memory_email_events:
         severity = "P2"
         status = "direct_only"
-        findings.append(_finding("email_db_without_memory_projection", "P2", store_id, producer, store, consumer, last_write, "direct:check-context", "Email DB tiene consumidor directo, pero no hay proyeccion a memory_events.", test, evidence))
+        findings.append(_finding("email_db_without_memory_projection", "P2", store_id, producer, store, consumer, last_write, "direct:check-context", "Email DB has a direct consumer, but no projection to memory_events.", test, evidence))
     return _row(store_id, producer, store, consumer, last_write, "direct:check-context", risk, test, status, severity, evidence), findings
 
 
@@ -484,8 +484,8 @@ def _audit_plugins(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[SavedNo
     store_id = "plugins_catalog_live"
     producer = "plugin_loader._update_registry"
     consumer = "MCP live tool list / nexo_plugin_list / system catalog"
-    risk = "Catalogo puede prometer herramientas que el cliente no tiene cargadas."
-    test = "tools en tabla plugins o catalogo deben estar presentes en live_tools."
+    risk = "Catalog may promise tools the client has not loaded."
+    test = "tools in the plugins table or catalog must be present in live_tools."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     catalog_tools = set(cfg.plugin_catalog_tools)
     last_write = ""
@@ -508,7 +508,7 @@ def _audit_plugins(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[SavedNo
     elif catalog_tools and not live_tools:
         severity = "P2"
         status = "live_unknown"
-        findings.append(_finding("plugin_live_tools_not_provided", "P2", store_id, producer, row.store, consumer, last_write, "", "No hay snapshot live para comparar catalogo de plugins.", test, evidence))
+        findings.append(_finding("plugin_live_tools_not_provided", "P2", store_id, producer, row.store, consumer, last_write, "", "There is no live snapshot to compare the plugin catalog.", test, evidence))
     return _row(store_id, producer, row.store, consumer, last_write, f"live_tools={len(live_tools)}" if live_tools else "", risk, test, status, severity, evidence), findings
 
 
@@ -516,8 +516,8 @@ def _audit_cron_spool(cfg: SavedNotUsedConfig) -> tuple[StoreAuditRow, list[Save
     store_id = "cron_spool"
     producer = "nexo-cron-wrapper.sh"
     consumer = "cron_runs summary / cron spool reconciler / watchdog"
-    risk = "Spool JSON o cron_runs abiertos dejan automatismos en estado ambiguo."
-    test = "cron-spool debe estar vacio y cron_runs no-Evolution debe tener ended_at."
+    risk = "Spool JSON or open cron_runs leave automations in an ambiguous state."
+    test = "cron-spool must be empty and non-Evolution cron_runs must have ended_at."
     row, conn = _open_main_row(cfg, store_id, producer, consumer, risk, test)
     open_runs = 0
     last_write = ""

package/src/script_registry.py

@@ -91,7 +91,53 @@ METADATA_KEYS = {
     "idempotent",
     "max_catchup_age",
     "doctor_allow_db",
+    "agent",
+    "agent_title",
+    "agent_description",
+    "agent_conversation_id",
+    "agent_created_from",
+    "agent_archived",
+    "agent_enabled_before_archive",
+    "agent_icon",
 }
+AGENT_METADATA_KEYS = {
+    "agent",
+    "agent_title",
+    "agent_description",
+    "agent_conversation_id",
+    "agent_created_from",
+    "agent_archived",
+    "agent_enabled_before_archive",
+    "agent_icon",
+}
+METADATA_WRITE_ORDER = [
+    "name",
+    "description",
+    "runtime",
+    "agent",
+    "agent_title",
+    "agent_description",
+    "agent_conversation_id",
+    "agent_created_from",
+    "agent_archived",
+    "agent_enabled_before_archive",
+    "agent_icon",
+    "cron_id",
+    "schedule_required",
+    "schedule",
+    "interval_seconds",
+    "recovery_policy",
+    "run_on_boot",
+    "run_on_wake",
+    "idempotent",
+    "max_catchup_age",
+    "timeout",
+    "requires",
+    "tools",
+    "hidden",
+    "category",
+    "doctor_allow_db",
+]
 SUPPORTED_RUNTIMES = {"python", "shell", "node", "php", "unknown"}
 PERSONAL_SCHEDULE_MANAGED_ENV = "NEXO_MANAGED_PERSONAL_CRON"
 SUPPORTED_RECOVERY_POLICIES = {"none", "run_once_on_wake", "catchup", "restart", "restart_daemon"}
@@ -1130,7 +1176,10 @@ def _compact_schedule_from_record(record: dict) -> str:
         with contextlib.suppress(Exception):
             payload = json.loads(raw)
     if isinstance(payload, list):
-        payload = payload[0] if len(payload) == 1 and isinstance(payload[0], dict) else None
+        if len(payload) == 1 and isinstance(payload[0], dict):
+            payload = payload[0]
+        else:
+            return ""
     if isinstance(payload, dict):
         hour = payload.get("Hour")
         minute = payload.get("Minute")
@@ -1221,6 +1270,400 @@ def _write_metadata_block(path: Path, metadata_lines: list[str]) -> None:
     path.write_text("".join(filtered))
 
 
+def _metadata_lines_from_values(path: Path, metadata: dict) -> list[str]:
+    prefix = _metadata_comment_prefix(path)
+    keys = [key for key in METADATA_WRITE_ORDER if key in metadata]
+    keys.extend(sorted(key for key in metadata if key in METADATA_KEYS and key not in keys))
+    lines: list[str] = []
+    for key in keys:
+        value = str(metadata.get(key) or "").strip()
+        if not value:
+            continue
+        lines.append(f"{prefix} nexo: {key}={value}")
+    return lines
+
+
+def _unknown_inline_metadata_lines(path: Path) -> list[str]:
+    try:
+        raw = path.read_text(errors="ignore")
+    except Exception:
+        return []
+    lines = raw.splitlines(keepends=True)
+    insert_at = 1 if lines and lines[0].startswith("#!") else 0
+    preserved: list[str] = []
+    for index, line in enumerate(lines):
+        if index < insert_at or index >= 25:
+            continue
+        stripped = line.strip()
+        payload = ""
+        if stripped.startswith("# nexo:"):
+            payload = stripped[len("# nexo:"):].strip()
+        elif stripped.startswith("// nexo:"):
+            payload = stripped[len("// nexo:"):].strip()
+        if "=" not in payload:
+            continue
+        key, _value = payload.split("=", 1)
+        if key.strip() not in METADATA_KEYS:
+            preserved.append(line.rstrip("\n") + "\n")
+    return preserved
+
+
+def _update_script_metadata(path: Path, updates: dict, *, remove: set[str] | None = None) -> dict:
+    metadata = dict(parse_inline_metadata(path))
+    for key in remove or set():
+        metadata.pop(key, None)
+    for key, value in updates.items():
+        if key not in METADATA_KEYS:
+            continue
+        text = str(value or "").strip()
+        if text:
+            metadata[key] = _normalize_metadata_value(key, text)
+        else:
+            metadata.pop(key, None)
+    _write_metadata_block(path, _unknown_inline_metadata_lines(path) + _metadata_lines_from_values(path, metadata))
+    return parse_inline_metadata(path)
+
+
+def _is_agent_metadata(metadata: dict | None) -> bool:
+    return _truthy((metadata or {}).get("agent"))
+
+
+def _is_agent_archived(metadata: dict | None) -> bool:
+    return _truthy((metadata or {}).get("agent_archived"))
+
+
+def _format_agent_calendar_value(raw: str) -> tuple[str, str]:
+    compact = _compact_schedule_from_record({
+        "schedule_type": "calendar",
+        "schedule_value": raw,
+        "schedule_label": raw,
+    })
+    if not compact:
+        return "", ""
+    parts = compact.split(":")
+    if len(parts) not in {2, 3}:
+        return "", "calendar"
+    try:
+        hour = int(parts[0])
+        minute = int(parts[1])
+        weekday = int(parts[2]) if len(parts) == 3 else None
+    except (TypeError, ValueError):
+        return "", "calendar"
+    if len(parts) == 3:
+        return compact, f"{hour:02d}:{minute:02d} weekday={weekday}"
+    return compact, f"{hour:02d}:{minute:02d} daily"
+
+
+def _agent_schedule_from_script(script: dict) -> dict:
+    schedules = script.get("schedules") if isinstance(script.get("schedules"), list) else []
+    if schedules:
+        schedule = dict(schedules[0])
+        schedule_type = str(schedule.get("schedule_type") or "")
+        schedule_value = str(schedule.get("schedule_value") or "")
+        label = str(schedule.get("schedule_label") or schedule_value or schedule_type)
+        interval_seconds = 0
+        daily_at = ""
+        if schedule_type == "interval":
+            with contextlib.suppress(Exception):
+                interval_seconds = int(schedule_value)
+        elif schedule_type == "calendar":
+            daily_at, formatted = _format_agent_calendar_value(schedule_value)
+            label = formatted or label
+        return {
+            "schedule_type": schedule_type,
+            "schedule_value": schedule_value,
+            "schedule_label": label,
+            "effective_schedule_label": label,
+            "interval_seconds": interval_seconds,
+            "daily_at": daily_at,
+            "cron_id": str(schedule.get("cron_id") or ""),
+            "schedule_source": "runtime",
+            "schedules": schedules,
+        }
+
+    metadata = script.get("metadata") if isinstance(script.get("metadata"), dict) else {}
+    declared = get_declared_schedule(metadata, str(script.get("name") or ""))
+    if declared.get("valid") and declared.get("required"):
+        return {
+            "schedule_type": str(declared.get("schedule_type") or ""),
+            "schedule_value": str(declared.get("schedule_value") or ""),
+            "schedule_label": str(declared.get("schedule_label") or ""),
+            "effective_schedule_label": str(declared.get("schedule_label") or ""),
+            "interval_seconds": int(declared.get("interval_seconds", 0) or 0),
+            "daily_at": str(declared.get("schedule") or ""),
+            "cron_id": str(declared.get("cron_id") or ""),
+            "schedule_source": "metadata",
+            "schedules": [],
+        }
+
+    return {
+        "schedule_type": "manual",
+        "schedule_value": "",
+        "schedule_label": "",
+        "effective_schedule_label": "",
+        "interval_seconds": 0,
+        "daily_at": "",
+        "cron_id": str(metadata.get("cron_id") or script.get("name") or ""),
+        "schedule_source": "",
+        "schedules": [],
+    }
+
+
+def _agent_health(script: dict) -> str:
+    metadata = script.get("metadata") if isinstance(script.get("metadata"), dict) else {}
+    if _is_agent_archived(metadata):
+        return "archived"
+    if not bool(script.get("enabled", True)):
+        return "disabled"
+    exit_code = script.get("last_exit_code")
+    if exit_code is None:
+        return "unknown"
+    return "ok" if exit_code == 0 else "failing"
+
+
+def _agent_row(script: dict) -> dict:
+    metadata = script.get("metadata") if isinstance(script.get("metadata"), dict) else {}
+    schedule = _agent_schedule_from_script(script)
+    title = str(metadata.get("agent_title") or script.get("name") or "").strip()
+    description = str(
+        metadata.get("agent_description")
+        or script.get("description")
+        or metadata.get("description")
+        or ""
+    ).strip()
+    return {
+        "name": script.get("name", ""),
+        "title": title,
+        "description": description,
+        "path": script.get("path", ""),
+        "runtime": script.get("runtime", "unknown"),
+        "enabled": bool(script.get("enabled", True)),
+        "archived": _is_agent_archived(metadata),
+        "health": _agent_health(script),
+        "last_run_at": script.get("last_run_at", ""),
+        "last_exit_code": script.get("last_exit_code"),
+        "conversation_id": str(metadata.get("agent_conversation_id") or ""),
+        "created_from": str(metadata.get("agent_created_from") or ""),
+        "icon": str(metadata.get("agent_icon") or "automation"),
+        "metadata": metadata,
+        "schedule_configurable": True,
+        **schedule,
+    }
+
+
+def list_agents(*, include_archived: bool = False) -> list[dict]:
+    """List personal scripts explicitly marked as NEXO agents."""
+    from db import init_db, list_personal_scripts
+
+    init_db()
+    sync_personal_scripts()
+    rows = []
+    for script in list_personal_scripts(include_disabled=True):
+        metadata = script.get("metadata") if isinstance(script.get("metadata"), dict) else {}
+        if not _is_agent_metadata(metadata):
+            continue
+        if _is_agent_archived(metadata) and not include_archived:
+            continue
+        rows.append(_agent_row(script))
+    rows.sort(key=lambda row: (bool(row.get("archived")), str(row.get("title") or row.get("name") or "").lower()))
+    return rows
+
+
+def get_agent_status(name_or_path: str) -> dict:
+    from db import init_db, get_personal_script, list_personal_scripts
+
+    init_db()
+    sync_personal_scripts()
+    script = get_personal_script(name_or_path)
+    if not script:
+        return {"ok": False, "error": f"Agent not found: {name_or_path}"}
+    metadata = script.get("metadata") if isinstance(script.get("metadata"), dict) else {}
+    if not _is_agent_metadata(metadata):
+        return {"ok": False, "error": f"Personal script is not marked as an agent: {name_or_path}"}
+    for row in list_personal_scripts(include_disabled=True):
+        if row.get("path") == script.get("path"):
+            script = row
+            break
+    return {"ok": True, "agent": _agent_row(script)}
+
+
+def create_agent_script(name: str, *, description: str = "", runtime: str = "python", force: bool = False) -> dict:
+    created = create_script(name, description=description, runtime=runtime, force=force)
+    path = Path(created["path"])
+    metadata = parse_inline_metadata(path)
+    updates = {
+        "agent": "true",
+        "agent_title": name,
+        "agent_description": description or metadata.get("description") or f"Agent: {created['name']}",
+    }
+    _update_script_metadata(path, updates)
+    sync_result = sync_personal_scripts()
+    return {
+        **created,
+        "agent": True,
+        "sync": sync_result,
+    }
+
+
+def set_agent_enabled(name_or_path: str, enabled: bool) -> dict:
+    status = get_agent_status(name_or_path)
+    if not status.get("ok"):
+        return status
+    agent = status["agent"]
+    if enabled and agent.get("archived"):
+        _update_script_metadata(Path(agent["path"]), {"agent_archived": "false"})
+    result = set_personal_script_enabled(agent["path"], enabled)
+    if not result.get("ok"):
+        return result
+    refreshed = get_agent_status(agent["path"])
+    return {
+        "ok": True,
+        "name": agent["name"],
+        "enabled": enabled,
+        "changed": bool(result.get("changed")),
+        "agent": refreshed.get("agent") if refreshed.get("ok") else agent,
+    }
+
+
+def archive_agent(name_or_path: str, *, archived: bool = True) -> dict:
+    status = get_agent_status(name_or_path)
+    if not status.get("ok"):
+        return status
+    agent = status["agent"]
+    path = Path(agent["path"])
+    metadata = parse_inline_metadata(path)
+    if archived:
+        _update_script_metadata(path, {
+            "agent_archived": "true",
+            "agent_enabled_before_archive": "true" if agent.get("enabled", True) else "false",
+        })
+        next_enabled = False
+    else:
+        previous_enabled = metadata.get("agent_enabled_before_archive")
+        next_enabled = _truthy(previous_enabled) if previous_enabled else True
+        _update_script_metadata(path, {"agent_archived": "false"}, remove={"agent_enabled_before_archive"})
+    toggle = set_personal_script_enabled(agent["path"], next_enabled)
+    refreshed = get_agent_status(agent["path"])
+    return {
+        "ok": bool(toggle.get("ok", True)) and bool(refreshed.get("ok", True)),
+        "name": agent["name"],
+        "archived": archived,
+        "agent": refreshed.get("agent") if refreshed.get("ok") else agent,
+    }
+
+
+def _agent_schedule_ensure_error(result: dict, *, cron_id: str, path: Path) -> str:
+    if not isinstance(result, dict):
+        return "schedule ensure returned an invalid response"
+    if result.get("ok") is False:
+        return str(result.get("error") or "schedule ensure failed")
+    path_text = str(path)
+    for item in result.get("invalid", []) if isinstance(result.get("invalid"), list) else []:
+        if item.get("path") == path_text or item.get("cron_id") == cron_id:
+            return str(item.get("error") or "invalid schedule metadata")
+    for bucket in ("created", "repaired"):
+        for item in result.get(bucket, []) if isinstance(result.get(bucket), list) else []:
+            if item.get("cron_id") != cron_id:
+                continue
+            response = str(item.get("result") or "")
+            if response.upper().startswith("ERROR:"):
+                return response
+    return ""
+
+
+def set_agent_schedule(
+    name_or_path: str,
+    *,
+    interval_seconds: int | None = None,
+    daily_at: str | None = None,
+    clear: bool = False,
+) -> dict:
+    status = get_agent_status(name_or_path)
+    if not status.get("ok"):
+        return status
+    agent = status["agent"]
+    path = Path(agent["path"])
+    metadata = parse_inline_metadata(path)
+    cron_id = _safe_slug(str(metadata.get("cron_id") or agent.get("name") or path.stem))
+    runtime = classify_runtime(path, metadata)
+    if runtime == "unknown":
+        runtime = "shell" if path.suffix.lower() == ".sh" else "python"
+
+    remove = {"schedule", "interval_seconds", "recovery_policy", "run_on_boot", "run_on_wake", "idempotent", "max_catchup_age"}
+    updates = {
+        "agent": "true",
+        "name": metadata.get("name") or agent.get("name") or _logical_personal_script_name(path.stem),
+        "description": metadata.get("description") or agent.get("description") or f"Agent: {agent.get('name')}",
+        "runtime": runtime,
+        "cron_id": cron_id,
+    }
+    if clear:
+        remove.add("schedule_required")
+        _update_script_metadata(path, updates, remove=remove)
+        removed = unschedule_personal_script(str(path))
+        sync_result = sync_personal_scripts()
+        refreshed = get_agent_status(str(path))
+        return {
+            "ok": bool(removed.get("ok", True)),
+            "name": agent["name"],
+            "cleared": True,
+            "removed": removed,
+            "sync": sync_result,
+            "agent": refreshed.get("agent") if refreshed.get("ok") else agent,
+        }
+
+    if interval_seconds is not None:
+        try:
+            interval = int(interval_seconds)
+        except (TypeError, ValueError):
+            return {"ok": False, "error": f"Invalid interval_seconds: {interval_seconds}"}
+        if interval <= 0:
+            return {"ok": False, "error": "interval_seconds must be > 0"}
+        updates.update({
+            "schedule_required": "true",
+            "interval_seconds": str(interval),
+            "recovery_policy": "run_once_on_wake",
+        })
+    elif daily_at:
+        schedule_value = _normalize_schedule_metadata(str(daily_at).strip())
+        updates.update({
+            "schedule_required": "true",
+            "schedule": schedule_value,
+            "recovery_policy": "catchup",
+        })
+    else:
+        return {"ok": False, "error": "Choose interval_seconds, daily_at, or clear=true"}
+
+    candidate_metadata = dict(metadata)
+    for key in remove:
+        candidate_metadata.pop(key, None)
+    for key, value in updates.items():
+        if key in METADATA_KEYS:
+            candidate_metadata[key] = _normalize_metadata_value(key, str(value or ""))
+    declared = get_declared_schedule(candidate_metadata, str(agent.get("name") or path.stem))
+    if not declared.get("valid"):
+        return {
+            "ok": False,
+            "error": str(declared.get("error") or "invalid schedule metadata"),
+            "cron_id": cron_id,
+        }
+
+    _update_script_metadata(path, updates, remove=remove)
+    removed = unschedule_personal_script(str(path))
+    ensured = ensure_personal_schedules(dry_run=False)
+    ensure_error = _agent_schedule_ensure_error(ensured, cron_id=cron_id, path=path)
+    refreshed = get_agent_status(str(path))
+    return {
+        "ok": not ensure_error,
+        "name": agent["name"],
+        "cron_id": cron_id,
+        "error": ensure_error,
+        "removed": removed,
+        "ensure_schedules": ensured,
+        "agent": refreshed.get("agent") if refreshed.get("ok") else agent,
+    }
+
+
 def repair_orphan_personal_schedule_metadata(*, dry_run: bool = False) -> dict:
     """Infer inline metadata for personal LaunchAgents that predate the registry.