@danhachuel/thunderbolt 0.2.71 → 0.2.73

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DanHachuel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -38,13 +38,13 @@ Os dados são segredos de sessão. Os valores não aparecem em tabelas ou logs,
 
 Os adaptadores do MoneyPrinterTurbo e de publicação nas plataformas são ligados pelas configurações locais e pelos pontos de integração em `integrations/`. A UI não inventa dados quando um serviço externo ou credencial não está disponível.
 
-## Navegação da UI 0.2.70
+## Navegação da UI 0.2.72
 
 A barra lateral mantém os níveis principais, nesta ordem: **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. **Pipeline** é expansível e contém **Criação de Vídeos**, **Criação de Músicas**, **Roteiros** e **Upload**. **Automação** também é expansível e contém **Automação Youtube**. **Edição** é expansível e contém **Limpador de Metadados**, **Cortes** e **Editor Python**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Redes Sociais** e **Tutorial Meta**, nessa ordem. **Niche Finder** é expansível e contém **Niche Finder Kaggle** e **Niche Finder Apify**. **Configurações** é expansível e contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
 Dentro de **Configurações > Contas Google**, a UI contém os cartões expansíveis de contas Google/YouTube, `sessionInfo`, documentos de Upload directo, `INNERTUBE_API_KEY`, o formulário **Adicionar outra conta Gmail** e a configuração global do YouTube (OAuth Client ID, OAuth Client Secret e YouTube Data API Key). A página **Configuração API** contém as restantes API Keys, providers, modelos, serviços, materiais, Nano Banana, TikTok, Postiz e o **Teste de vozes**.
 
-A página **AI Influencers > Tutorial Meta** apresenta o guia de configuração de uma conta Instagram profissional e das credenciais Meta para automações com n8n, distribuído localmente em `seed/references/guide-instagram.md` e com ligação para a [fonte original no GitHub](https://github.com/gyoridavid/ai_agents_az/blob/main/episode_8/guide-instagram.md). A página **Configurações > Notificações** é o centro local reservado para futuros eventos de processamento, publicação e integrações.
+A página **AI Influencers > Tutorial Meta** apresenta o guia de configuração de uma conta Instagram profissional e das credenciais Meta para automações com n8n, distribuído localmente em `seed/references/guide-instagram.md` e com ligação para a [fonte original no GitHub](https://github.com/gyoridavid/ai_agents_az/blob/main/episode_8/guide-instagram.md). A página **Configurações > Notificações** mantém um histórico persistente de conclusões e falhas, reconcilia estados escritos por componentes locais e disponibiliza um checkbox independente para cada operação mapeada.
 
 ## Canais Youtube — edição por cartão e vídeos recentes
 

package/app/main.py

@@ -34,6 +34,7 @@ from hermes_ui.cuts import CutsError, download_direct_video_url, generate_clips,
 from hermes_ui.mcp import detect_local_service, install_skill_locally, load_integrations, load_server_config, read_packaged_skill, save_server_config, update_integration
 from hermes_ui.mcp_server import server_status, start_server, stop_server
 from hermes_ui.music import list_music_files, materialize_suno_audio, request_suno_generation, store_music_file
+from hermes_ui.notifications import clear_notifications, list_notifications, mark_all_notifications_read, mark_notification_read, notification_event_catalog, notification_preferences, record_notification, reconcile_persisted_notifications, save_notification_preferences, unread_notification_count
 from hermes_ui.script_documents import list_script_documents, read_script_document, save_script_document, script_storage_path
 from hermes_ui.script_generation import generate_script_document
 from hermes_ui.voice_preview import DEFAULT_SAMPLE, load_preview_file, synthesize_preview
@@ -331,7 +332,16 @@ def generate_creative_for_ui(settings: dict[str, Any], channel: dict, topic: str
         blueprint_for_channel(channel),
         language=str(channel.get("language") or "Português"),
     )
-    return creative_payload_from_result(channel, topic, creative, topic_source=topic_source)
+    payload = creative_payload_from_result(channel, topic, creative, topic_source=topic_source)
+    creative_key = hashlib.sha1(json.dumps({"channel_id": channel.get("id") or "", "topic": topic, "titles": payload.get("title_candidates", [])}, ensure_ascii=False, sort_keys=True, default=str).encode("utf-8")).hexdigest()
+    record_notification(
+        "title_generation_completed",
+        f"Títulos gerados: {payload.get('title') or topic or 'Vídeo'}",
+        f"O pacote de títulos para {channel.get('name') or 'o canal seleccionado'} terminou de ser gerado.",
+        metadata={"channel_name": channel.get("name") or "", "topic": topic},
+        dedupe_key=f"titles:{creative_key}",
+    )
+    return payload
 
 
 def valid_hhmm(value: str) -> bool:
@@ -671,8 +681,10 @@ def render_blueprints():
                 try:
                     blueprint, branding = create_blueprint_from_link(source_url, niche, language, creation_type == "Blueprint + Branding completo", channel_name, blueprint_name)
                     blueprint_path, branding_path = save_generated_blueprint(blueprint, branding)
+                    record_notification("blueprint_completed", f"Blueprint criado: {blueprint_path.stem}", "O Blueprint foi criado e guardado no storage local.", metadata={"name": blueprint_path.stem}, dedupe_key=f"blueprint:{blueprint_path}:{blueprint_path.stat().st_mtime_ns}")
                     st.success(f"Blueprint criado: {blueprint_path.name}")
                     if branding_path:
+                        record_notification("branding_completed", f"Branding criado: {branding_path.stem}", "O Branding foi criado e guardado no storage local.", metadata={"name": branding_path.stem}, dedupe_key=f"branding:{branding_path}:{branding_path.stat().st_mtime_ns}")
                         st.success(f"Branding completo criado: {branding_path.name}")
                     st.rerun()
                 except ValueError as exc:
@@ -692,6 +704,7 @@ def render_blueprints():
                     st.warning("O ficheiro já existe. Confirme a substituição.")
                 else:
                     destination.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+                    record_notification("blueprint_completed", f"Blueprint guardado: {destination.stem}", "O Blueprint importado foi guardado no storage local.", metadata={"name": destination.stem}, dedupe_key=f"blueprint:{destination}:{destination.stat().st_mtime_ns}")
                     st.success(f"Blueprint guardado em {destination}")
                     st.rerun()
             except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
@@ -731,6 +744,7 @@ def render_blueprints():
                 target = BLUEPRINTS / "brandings" / (Path(branding_upload.name).stem.replace(" ", "-") + ".json")
                 target.parent.mkdir(parents=True, exist_ok=True)
                 target.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+                record_notification("branding_completed", f"Branding guardado: {target.stem}", "O Branding importado foi guardado no storage local.", metadata={"name": target.stem}, dedupe_key=f"branding:{target}:{target.stat().st_mtime_ns}")
                 st.success(f"Branding guardado em {target}")
                 st.rerun()
             except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
@@ -1534,6 +1548,7 @@ def render_new_video(page_title: str = "Criação de Vídeos"):
                                     payload["thumbnail_path"] = thumbnail_path
                                     payload["thumbnail_status"] = "generated"
                                     st.session_state["new_video_general_payloads"] = payloads
+                                    record_notification("thumbnail_generation_completed", f"Thumbnail gerada: {payload.get('title') or payload.get('topic') or 'Vídeo'}", "A thumbnail foi gerada com sucesso pelo Nano Banana.", metadata={"channel_name": channel.get("name") or "", "image_path": Path(thumbnail_path).name}, dedupe_key=f"thumbnail:{thumbnail_path}")
                                     st.success("Thumbnail gerada com Nano Banana.")
                                     st.rerun()
                                 except ThumbnailGenerationError as exc:
@@ -1588,6 +1603,7 @@ def render_new_video(page_title: str = "Criação de Vídeos"):
                                 payload["thumbnail_path"] = thumbnail_path
                                 payload["thumbnail_status"] = "generated"
                                 st.session_state["new_video_creative_payload"] = payload
+                                record_notification("thumbnail_generation_completed", f"Thumbnail gerada: {payload.get('title') or payload.get('topic') or 'Vídeo'}", "A thumbnail foi gerada com sucesso pelo Nano Banana.", metadata={"channel_name": selected_one.get("name") if selected_one else "", "image_path": Path(thumbnail_path).name}, dedupe_key=f"thumbnail:{thumbnail_path}")
                                 st.success("Thumbnail gerada com Nano Banana.")
                                 st.rerun()
                             except ThumbnailGenerationError as exc:
@@ -1761,6 +1777,16 @@ def render_scripts():
                         structure_notes=structure_notes,
                         generation_settings=script_settings,
                     )
+                generation_key = hashlib.sha1(f"{document_type}|{generated.get('title', '')}|{generated.get('content', '')}".encode("utf-8")).hexdigest()
+                generated["notification_dedupe_key"] = f"script-generation:{generation_key}"
+                script_event_type = "music_lyrics_generated" if document_type == "Letra de música" else "standalone_script_generated"
+                record_notification(
+                    script_event_type,
+                    f"{'Letra de música' if document_type == 'Letra de música' else 'Roteiro autónomo'} gerado: {generated.get('title') or title or 'Documento'}",
+                    "A geração do documento terminou com sucesso e o rascunho está disponível para revisão.",
+                    metadata={"document_type": "music_lyrics" if document_type == "Letra de música" else "video_script", "title": generated.get("title") or title or "Documento"},
+                    dedupe_key=generated["notification_dedupe_key"],
+                )
                 st.session_state["script_draft"] = generated
                 st.session_state["script_draft_title"] = generated["title"]
                 st.session_state["script_draft_summary"] = generated.get("summary", "")
@@ -1886,6 +1912,9 @@ def render_niche_finder():
                 )
             st.session_state["niche_results"] = results
             st.session_state["niche_last_parameters"] = current_parameters
+            niche_key = hashlib.sha1(json.dumps(current_parameters, ensure_ascii=False, sort_keys=True, default=str).encode("utf-8")).hexdigest()
+            summary = results.get("summary", {}) if isinstance(results, dict) else {}
+            record_notification("niche_analysis_completed", "Análise de nicho concluída", "A análise Kaggle terminou com resultados prontos para consulta.", metadata={"source": "Kaggle", "rows_filtered": summary.get("rows_filtered", 0)}, dedupe_key=f"niche:kaggle:{niche_key}")
             st.success("Análise concluída.")
         except (NicheAnalysisError, DatasetError, OSError) as exc:
             st.error("Não foi possível concluir a análise solicitada com os parâmetros actuais.")
@@ -2029,6 +2058,7 @@ def render_niche_finder_apify():
                 history = []
             history.insert(0, st.session_state["niche_apify_last_run"])
             write_json("niche_apify_runs.json", history[:20])
+            record_notification("niche_analysis_completed", "Análise de nicho concluída", f"A pesquisa Apify terminou com {len(items)} vídeo(s) recebido(s).", metadata={"run_id": finished.run_id, "item_count": len(items)}, dedupe_key=f"niche:apify:{finished.run_id}")
             st.session_state.pop("niche_apify_active_run", None)
             progress.progress(100, text="Pesquisa Apify concluída.")
             st.success(f"Pesquisa concluída: {len(items)} vídeo(s) recebido(s).")
@@ -2570,6 +2600,7 @@ def render_upload_direct():
                     uploads = read_json("uploads.json", [])
                     uploads.append(record)
                     write_json("uploads.json", uploads)
+                    reconcile_persisted_notifications()
                     (st.success if result.ok else st.error)(result.message)
 
 
@@ -2657,6 +2688,7 @@ def render_upload_postiz():
                 uploads = read_json("uploads.json", [])
                 uploads.append(record)
                 write_json("uploads.json", uploads)
+                reconcile_persisted_notifications()
                 (st.success if result.ok else st.error)(result.message)
 
 
@@ -2833,6 +2865,7 @@ def render_upload_conventional():
                     uploads = read_json("uploads.json", [])
                     uploads.append(record)
                     write_json("uploads.json", uploads)
+                    reconcile_persisted_notifications()
                     (st.success if result.ok else st.error)(result.message)
                     if result.data.get("attempts"):
                         with st.expander("Detalhes dos mecanismos de upload"):
@@ -2852,6 +2885,7 @@ def render_upload_conventional():
                 uploads = read_json("uploads.json", [])
                 uploads.append(record)
                 write_json("uploads.json", uploads)
+                reconcile_persisted_notifications()
                 (st.success if result.ok else st.warning)(result.message)
             if "Instagram" in destination:
                 st.button("Preparar Instagram", key=f"upload_instagram_{task['id']}", disabled=True, help="UI preparada; publicação Instagram ainda não está activa.")
@@ -3358,13 +3392,91 @@ def render_settings():
 
 def render_notifications():
     st.title("Notificações")
-    st.caption("Centro de notificações locais do Thunderbolt.")
-    st.info("Ainda não existem notificações registadas. Os eventos de processamento, publicação e integração serão ligados aqui numa etapa posterior.")
+    st.caption("Centro de notificações internas persistentes do Thunderbolt. As conclusões são guardadas no storage local e aparecem quando a aplicação é actualizada.")
+    reconcile_persisted_notifications()
+    preferences = notification_preferences()
+    catalog = notification_event_catalog()
+    notifications = list_notifications(limit=500)
+    unread_count = unread_notification_count()
+    summary_cols = st.columns(3)
+    with summary_cols[0]:
+        st.metric("Não lidas", unread_count)
+    with summary_cols[1]:
+        st.metric("Total guardado", len(notifications))
+    with summary_cols[2]:
+        st.metric("Operações mapeadas", len(catalog))
+
+    action_cols = st.columns([1.4, 1.4, 2.2])
+    with action_cols[0]:
+        if st.button("Marcar todas como lidas", use_container_width=True, disabled=unread_count == 0):
+            mark_all_notifications_read()
+            st.rerun()
+    with action_cols[1]:
+        if st.button("Actualizar notificações", use_container_width=True):
+            reconcile_persisted_notifications()
+            st.rerun()
+    with action_cols[2]:
+        confirm_clear = st.checkbox("Confirmar limpeza do histórico", key="confirm_clear_notifications")
+        if st.button("Limpar histórico", use_container_width=True, disabled=not confirm_clear):
+            clear_notifications()
+            st.session_state.pop("confirm_clear_notifications", None)
+            st.rerun()
+
+    st.divider()
+    st.subheader("Operações notificadas")
+    st.caption("Ligue ou desligue cada tipo de notificação. As preferências ficam guardadas no storage local e aplicam-se às próximas conclusões.")
+    grouped: dict[str, list[dict[str, str]]] = {}
+    for event in catalog:
+        grouped.setdefault(event["category"], []).append(event)
+    with st.form("notification_preferences_form"):
+        pending_preferences: dict[str, bool] = {}
+        for category, events in grouped.items():
+            st.markdown(f"**{category}**")
+            for event in events:
+                pending_preferences[event["code"]] = st.checkbox(
+                    event["label"],
+                    value=bool(preferences.get(event["code"], True)),
+                    help=event["description"],
+                    key=f"notification_preference_{event['code']}",
+                )
+        if st.form_submit_button("Guardar preferências", type="primary", use_container_width=True):
+            save_notification_preferences(pending_preferences)
+            st.success("Preferências de notificação guardadas.")
+            st.rerun()
+
     st.divider()
-    st.subheader("Preferências de notificação")
-    st.caption("Os canais de e-mail, push e webhook ainda não estão activos nesta versão.")
-    st.checkbox("Notificações no painel", value=True, disabled=True, key="notifications_panel_preview")
-    st.checkbox("Notificações por e-mail", value=False, disabled=True, key="notifications_email_preview")
+    st.subheader("Histórico de notificações")
+    filter_cols = st.columns([1, 1.4])
+    category_options = ["Todas"] + sorted({event["category"] for event in catalog})
+    with filter_cols[0]:
+        selected_category = st.selectbox("Categoria", category_options, key="notifications_category_filter")
+    with filter_cols[1]:
+        selected_state = st.selectbox("Estado", ["Todas", "Não lidas", "Lidas"], key="notifications_state_filter")
+    category_filter = "" if selected_category == "Todas" else selected_category
+    unread_filter = selected_state == "Não lidas"
+    filtered = list_notifications(limit=500, category=category_filter, unread_only=unread_filter)
+    if selected_state == "Lidas":
+        filtered = [item for item in filtered if item.get("read")]
+    if not filtered:
+        st.info("Ainda não existem notificações para os filtros seleccionados.")
+    for item in filtered:
+        with st.container(border=True):
+            notification_cols = st.columns([3.3, 1.4, 1])
+            with notification_cols[0]:
+                st.write(f"**{item.get('title') or item.get('label') or 'Notificação'}**")
+                st.caption(item.get("message") or "")
+                metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
+                if metadata:
+                    public_details = " · ".join(f"{key}: {value}" for key, value in metadata.items() if value not in (None, ""))
+                    if public_details:
+                        st.caption(public_details)
+            with notification_cols[1]:
+                st.caption(f"{item.get('category', 'Sistema')} · {item.get('created_at', '—')}")
+                st.write("Lida" if item.get("read") else "Não lida")
+            with notification_cols[2]:
+                if not item.get("read") and st.button("Marcar como lida", key=f"mark_notification_{item.get('id')}", use_container_width=True):
+                    mark_notification_read(str(item.get("id")))
+                    st.rerun()
 
 
 def render_models_ai_tutorial():
@@ -3782,6 +3894,10 @@ def main():
         "Configuração API": render_settings,
         "Notificações": render_notifications,
     }
+    try:
+        reconcile_persisted_notifications()
+    except Exception:
+        pass
     renderers.get(current_page, render_dashboard)()
 
 if __name__ == "__main__":

package/hermes_ui/automation_worker.py

@@ -10,6 +10,7 @@ from typing import Any
 from . import storage
 from .creative_generation import generate_creative_package, generate_topic_for_channel
 from .domain import create_batch, create_tasks_for_batch
+from .notifications import record_notification
 
 WORKER_STATE_FILE = "automation_worker.json"
 LOCK_FILENAME = "automation_worker.lock"
@@ -257,6 +258,13 @@ def run_once(when: datetime | None = None) -> dict[str, Any]:
                 "batch_id": batch["id"],
                 "task_ids": [task["id"] for task in item["tasks"]],
             }
+            record_notification(
+                "automation_completed",
+                "Automação concluída",
+                f"O lote agendado do canal {item['channel_id']} foi criado com sucesso.",
+                metadata={"channel_id": item["channel_id"], "batch_id": batch["id"], "time": current_minute},
+                dedupe_key=f"automation:{batch['id']}",
+            )
         _write_status(status)
         return {
             "ok": True,
@@ -268,6 +276,13 @@ def run_once(when: datetime | None = None) -> dict[str, Any]:
     except Exception as exc:
         status["last_error"] = str(exc)
         _write_status(status)
+        record_notification(
+            "automation_failed",
+            "Automação falhou",
+            f"A execução automática das {current_minute} terminou com erro: {exc}",
+            metadata={"date": day, "time": current_minute},
+            dedupe_key=f"automation:failed:{day}:{current_minute}",
+        )
         return {"ok": False, "local_time": _local_iso(current), "error": str(exc), "created": created}
 
 

package/hermes_ui/cuts.py

@@ -17,6 +17,7 @@ import requests
 
 from . import storage
 from .metadata_cleaner import VIDEO_EXTENSIONS, _resolve_ffmpeg
+from .notifications import record_notification
 
 
 class CutsError(RuntimeError):
@@ -380,6 +381,14 @@ def generate_clips(
         record["error"] = str(exc)
     _write_manifest(record, run_dir)
     storage.append_json("cuts_runs.json", record)
+    if record["status"] == "complete":
+        record_notification(
+            "cuts_completed",
+            "Cortes concluídos",
+            f"A geração de cortes para {record['source_name']} terminou com {len(record['clips'])} clip(s).",
+            metadata={"run_id": record["id"], "clip_count": len(record["clips"]), "output_format": record.get("output_format") or ""},
+            dedupe_key=f"cuts:{record['id']}",
+        )
     if record["status"] == "error":
         raise CutsError(record["error"])
     return record

package/hermes_ui/domain.py

@@ -4,6 +4,7 @@ import re
 import uuid
 from typing import Any
 
+from .notifications import record_notification
 from .storage import append_json, now, read_json, write_json
 
 STAGES = ["niche", "blueprint", "brand", "script", "title", "thumbnail", "video", "edit", "upload"]
@@ -199,13 +200,49 @@ def update_channel_video(video_id: str, updates: dict[str, Any]) -> dict[str, An
     return None
 
 
+def _notify_task_completion(task: dict[str, Any], previous_state: str = "") -> None:
+    current_state = str(task.get("state") or "")
+    task_id = str(task.get("id") or "")
+    if not task_id or current_state == previous_state and current_state in {"done", "failed"}:
+        return
+    title = str(task.get("title") or task.get("topic") or "Actividade")
+    channel = str(task.get("channel_name") or "Canal")
+    if current_state == "failed":
+        record_notification(
+            "activity_failed",
+            f"Actividade falhou: {title}",
+            f"A actividade de {channel} terminou com erro.",
+            metadata={"task_id": task_id, "channel_name": channel, "error": task.get("error") or ""},
+            dedupe_key=f"task:{task_id}:failed",
+        )
+        return
+    if current_state != "done":
+        return
+    artifacts = task.get("artifacts") if isinstance(task.get("artifacts"), dict) else {}
+    if bool(task.get("music_mode")) or str(task.get("style_wide") or "") == "music":
+        event_type, label = "music_completed", "Música concluída"
+    elif str(task.get("stage") or "") == "script" and not artifacts.get("video"):
+        event_type, label = "script_stage_completed", "Roteiro concluído"
+    else:
+        event_type, label = "video_completed", "Vídeo concluído"
+    record_notification(
+        event_type,
+        f"{label}: {title}",
+        f"A actividade de {channel} terminou com sucesso.",
+        metadata={"task_id": task_id, "channel_name": channel, "stage": task.get("stage") or "", "creation_mode": task.get("creation_mode") or ""},
+        dedupe_key=f"task:{task_id}:{event_type}:done",
+    )
+
+
 def update_task(task_id: str, updates: dict[str, Any]) -> dict[str, Any] | None:
     tasks = read_json("tasks.json", [])
     for task in tasks:
         if task.get("id") == task_id:
+            previous_state = str(task.get("state") or "")
             task.update(updates)
             task["updated_at"] = now()
             write_json("tasks.json", tasks)
+            _notify_task_completion(task, previous_state)
             return task
     return None
 
@@ -216,6 +253,7 @@ def transition_task(task_id: str, state: str | None = None, stage: str | None =
     tasks = read_json("tasks.json", [])
     for task in tasks:
         if task.get("id") == task_id:
+            previous_state = str(task.get("state") or "")
             if state:
                 task["state"] = state
             if stage:
@@ -226,6 +264,7 @@ def transition_task(task_id: str, state: str | None = None, stage: str | None =
                 task["error"] = error
             task["updated_at"] = now()
             write_json("tasks.json", tasks)
+            _notify_task_completion(task, previous_state)
             return task
     return None
 

package/hermes_ui/metadata_cleaner.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from typing import Any
 
 from . import storage
+from .notifications import record_notification
 
 
 def _metadata_root() -> Path:
@@ -175,6 +176,13 @@ def save_edit_record(source: Path, output: Path, metadata: dict[str, Any], run_i
         "created_at": run_info.get("created_at", _now()),
     }
     storage.append_json("metadata_edits.json", record)
+    record_notification(
+        "metadata_cleaning_completed",
+        f"Metadados limpos: {output.name}",
+        "A limpeza de metadados terminou com um ficheiro de saída guardado.",
+        metadata={"record_id": record["id"], "output_name": output.name},
+        dedupe_key=f"metadata_cleaning_completed:{record['id']}",
+    )
     return record
 
 

package/hermes_ui/music.py

@@ -8,6 +8,7 @@ from typing import Any
 import requests
 
 from . import storage
+from .notifications import record_notification
 
 MUSIC_EXTENSIONS = {".mp3", ".wav", ".m4a", ".aac", ".flac", ".ogg"}
 
@@ -35,6 +36,13 @@ def store_music_file(name: str, content: bytes) -> Path:
         raise ValueError("O ficheiro de música está vazio.")
     target = music_directory() / safe_music_name(name)
     target.write_bytes(content)
+    record_notification(
+        "music_completed",
+        f"Música concluída: {target.stem}",
+        f"O ficheiro de música {target.name} foi guardado no storage local.",
+        metadata={"filename": target.name, "source": "local_storage"},
+        dedupe_key=f"music:{target.name}:{target.stat().st_mtime_ns}",
+    )
     return target
 
 

package/hermes_ui/notifications.py

@@ -0,0 +1,340 @@
+"""Persistent local notifications for Thunderbolt activity completion events."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from . import storage
+
+NOTIFICATIONS_FILE = "notifications.json"
+MAX_NOTIFICATIONS = 500
+
+EVENT_CATALOG: tuple[dict[str, str], ...] = (
+    {"code": "video_completed", "category": "Produção", "label": "Vídeo concluído", "description": "Quando uma tarefa de vídeo chegar ao estado final."},
+    {"code": "music_completed", "category": "Produção", "label": "Música concluída", "description": "Quando uma tarefa musical ou um ficheiro musical terminar de ser guardado."},
+    {"code": "standalone_script_generated", "category": "Roteiros", "label": "Roteiro autónomo gerado", "description": "Quando um roteiro independente terminar de ser gerado."},
+    {"code": "music_lyrics_generated", "category": "Roteiros", "label": "Letra de música gerada", "description": "Quando uma letra de música independente terminar de ser gerada."},
+    {"code": "script_stage_completed", "category": "Pipeline", "label": "Etapa de roteiro concluída", "description": "Quando a etapa de roteiro de uma tarefa terminar."},
+    {"code": "title_generation_completed", "category": "Pipeline", "label": "Títulos gerados", "description": "Quando o pacote de títulos terminar de ser gerado."},
+    {"code": "thumbnail_generation_completed", "category": "Pipeline", "label": "Thumbnail gerada", "description": "Quando a imagem final da thumbnail for criada."},
+    {"code": "blueprint_completed", "category": "Pipeline", "label": "Blueprint criado ou importado", "description": "Quando um Blueprint for criado, importado ou guardado."},
+    {"code": "branding_completed", "category": "Pipeline", "label": "Branding criado ou importado", "description": "Quando um Branding for criado, importado ou guardado."},
+    {"code": "niche_analysis_completed", "category": "Pipeline", "label": "Análise de nicho concluída", "description": "Quando uma análise Kaggle ou Apify terminar com resultados."},
+    {"code": "cuts_completed", "category": "Edição", "label": "Cortes concluídos", "description": "Quando a geração de cortes terminar com um manifesto completo."},
+    {"code": "metadata_cleaning_completed", "category": "Edição", "label": "Metadados limpos", "description": "Quando uma cópia com metadados limpos for criada."},
+    {"code": "python_edit_completed", "category": "Edição", "label": "Edição Python concluída", "description": "Quando uma operação do Editor Python guardar o artefacto."},
+    {"code": "automation_completed", "category": "Automação", "label": "Automação concluída", "description": "Quando o worker concluir o lote agendado de um canal."},
+    {"code": "automation_failed", "category": "Automação", "label": "Automação falhou", "description": "Quando uma execução automática terminar com erro."},
+    {"code": "activity_failed", "category": "Sistema", "label": "Actividade falhou", "description": "Quando uma tarefa ou operação persistida terminar em erro."},
+    {"code": "upload_youtube_success", "category": "Upload", "label": "Upload YouTube concluído", "description": "Quando um vídeo for publicado num canal YouTube."},
+    {"code": "upload_tiktok_success", "category": "Upload", "label": "Upload TikTok concluído", "description": "Quando um vídeo for publicado numa conta TikTok."},
+    {"code": "upload_instagram_success", "category": "Upload", "label": "Upload Instagram concluído", "description": "Quando um vídeo for publicado num perfil Instagram."},
+    {"code": "upload_facebook_pages_success", "category": "Upload", "label": "Upload Facebook Pages concluído", "description": "Quando um vídeo for publicado numa Facebook Page."},
+    {"code": "upload_postiz_success", "category": "Upload", "label": "Upload Postiz concluído", "description": "Quando um vídeo for enviado e publicado através do Postiz."},
+    {"code": "mcp_operation_completed", "category": "Integrações", "label": "Operação MCP concluída", "description": "Quando uma operação mutável de integração MCP terminar com sucesso."},
+)
+EVENTS_BY_CODE = {item["code"]: item for item in EVENT_CATALOG}
+SENSITIVE_MARKERS = (
+    "token",
+    "secret",
+    "api_key",
+    "apikey",
+    "cookie",
+    "password",
+    "authorization",
+    "sessioninfo",
+    "session_info",
+    "access_token",
+    "client_secret",
+    "sid",
+    "ssid",
+    "hsid",
+    "apisid",
+)
+
+
+def notification_event_catalog() -> list[dict[str, str]]:
+    return [dict(item) for item in EVENT_CATALOG]
+
+
+def default_notification_preferences() -> dict[str, bool]:
+    return {item["code"]: True for item in EVENT_CATALOG}
+
+
+def notification_preferences() -> dict[str, bool]:
+    settings = storage.read_json("settings.json", {})
+    raw = settings.get("notification_preferences", {}) if isinstance(settings, dict) else {}
+    raw = raw if isinstance(raw, dict) else {}
+    preferences = default_notification_preferences()
+    for code in preferences:
+        if code in raw:
+            preferences[code] = bool(raw[code])
+    return preferences
+
+
+def save_notification_preferences(preferences: dict[str, Any]) -> dict[str, bool]:
+    settings = storage.read_json("settings.json", {})
+    existing = settings.get("notification_preferences", {}) if isinstance(settings, dict) else {}
+    existing = dict(existing) if isinstance(existing, dict) else {}
+    for code in EVENTS_BY_CODE:
+        if code in preferences:
+            existing[code] = bool(preferences[code])
+    settings["notification_preferences"] = existing
+    storage.write_json("settings.json", settings)
+    return notification_preferences()
+
+
+def _redact_text(value: Any) -> str:
+    text = str(value or "").strip()
+    if not text:
+        return ""
+    pattern = r"(?i)(api[_ -]?key|client[_ -]?secret|access[_ -]?token|authorization|bearer|session[_ -]?info)\s*[:=]\s*[^\s,;]+"
+    text = re.sub(pattern, r"\1=[redacted]", text)
+    return re.sub(r"(?i)\bbearer\s+[^\s,;]+", "Bearer [redacted]", text)
+
+
+def _safe_metadata(value: Any, *, key: str = "") -> Any:
+    normalized_key = re.sub(r"[^a-z0-9_]", "", key.lower())
+    if any(marker in normalized_key for marker in SENSITIVE_MARKERS):
+        return "[redacted]"
+    if isinstance(value, dict):
+        return {str(item_key): _safe_metadata(item_value, key=str(item_key)) for item_key, item_value in value.items() if str(item_key).lower() not in {"payload", "response", "headers"}}
+    if isinstance(value, list):
+        return [_safe_metadata(item) for item in value[:50]]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return _redact_text(value) if isinstance(value, str) else value
+    return _redact_text(value)
+
+
+def _history() -> list[dict[str, Any]]:
+    saved = storage.read_json(NOTIFICATIONS_FILE, [])
+    if not isinstance(saved, list):
+        return []
+    return [item for item in saved if isinstance(item, dict)]
+
+
+def record_notification(
+    event_type: str,
+    title: str,
+    message: str,
+    *,
+    metadata: dict[str, Any] | None = None,
+    dedupe_key: str = "",
+) -> dict[str, Any] | None:
+    event = EVENTS_BY_CODE.get(str(event_type))
+    if event is None:
+        raise ValueError(f"Tipo de notificação desconhecido: {event_type}")
+    if not notification_preferences().get(event_type, True):
+        return None
+    history = _history()
+    if dedupe_key:
+        for existing in history:
+            if str(existing.get("dedupe_key") or "") == dedupe_key:
+                return None
+    created_at = datetime.now(timezone.utc).isoformat()
+    entry = {
+        "id": f"notification_{uuid.uuid4().hex[:12]}",
+        "event_type": event_type,
+        "category": event["category"],
+        "label": event["label"],
+        "title": _redact_text(title),
+        "message": _redact_text(message),
+        "created_at": created_at,
+        "read": False,
+        "metadata": _safe_metadata(metadata or {}),
+        "dedupe_key": str(dedupe_key or ""),
+    }
+    storage.write_json(NOTIFICATIONS_FILE, [entry, *history][:MAX_NOTIFICATIONS])
+    return entry
+
+
+def list_notifications(*, limit: int = 200, category: str = "", unread_only: bool = False) -> list[dict[str, Any]]:
+    entries = _history()
+    if category:
+        entries = [item for item in entries if item.get("category") == category]
+    if unread_only:
+        entries = [item for item in entries if not item.get("read")]
+    entries.sort(key=lambda item: str(item.get("created_at") or ""), reverse=True)
+    return entries[: max(1, min(int(limit), MAX_NOTIFICATIONS))]
+
+
+def unread_notification_count() -> int:
+    return sum(1 for item in _history() if not item.get("read"))
+
+
+def mark_notification_read(notification_id: str) -> bool:
+    history = _history()
+    changed = False
+    for item in history:
+        if str(item.get("id")) == str(notification_id):
+            item["read"] = True
+            changed = True
+            break
+    if changed:
+        storage.write_json(NOTIFICATIONS_FILE, history)
+    return changed
+
+
+def mark_all_notifications_read() -> int:
+    history = _history()
+    changed = sum(1 for item in history if not item.get("read"))
+    if changed:
+        for item in history:
+            item["read"] = True
+        storage.write_json(NOTIFICATIONS_FILE, history)
+    return changed
+
+
+def clear_notifications() -> int:
+    count = len(_history())
+    storage.write_json(NOTIFICATIONS_FILE, [])
+    return count
+
+
+def _task_notifications() -> int:
+    created = 0
+    tasks = storage.read_json("tasks.json", [])
+    if not isinstance(tasks, list):
+        return 0
+    for task in tasks:
+        if not isinstance(task, dict):
+            continue
+        task_id = str(task.get("id") or "")
+        if not task_id:
+            continue
+        state = str(task.get("state") or "")
+        title = str(task.get("title") or task.get("topic") or "Actividade")
+        channel = str(task.get("channel_name") or "Canal")
+        if state == "failed":
+            if record_notification("activity_failed", f"Actividade falhou: {title}", f"A actividade de {channel} terminou com erro.", metadata={"task_id": task_id, "channel_name": channel}, dedupe_key=f"task:{task_id}:failed"):
+                created += 1
+            continue
+        if state != "done":
+            continue
+        artifacts = task.get("artifacts") if isinstance(task.get("artifacts"), dict) else {}
+        if bool(task.get("music_mode")) or str(task.get("style_wide") or "") == "music":
+            event_type = "music_completed"
+            label = "Música concluída"
+        elif str(task.get("stage") or "") == "script" and not artifacts.get("video"):
+            event_type = "script_stage_completed"
+            label = "Roteiro concluído"
+        else:
+            event_type = "video_completed"
+            label = "Vídeo concluído"
+        if record_notification(event_type, f"{label}: {title}", f"A actividade de {channel} terminou com sucesso.", metadata={"task_id": task_id, "channel_name": channel, "stage": task.get("stage") or "", "creation_mode": task.get("creation_mode") or ""}, dedupe_key=f"task:{task_id}:{event_type}:done"):
+            created += 1
+        if isinstance(task.get("title_candidates"), list) and task.get("title_candidates"):
+            if record_notification("title_generation_completed", f"Títulos gerados: {title}", f"O pacote de títulos para {channel} terminou de ser gerado.", metadata={"task_id": task_id, "channel_name": channel}, dedupe_key=f"task:{task_id}:titles"):
+                created += 1
+        if str(task.get("thumbnail_status") or "") == "generated" or artifacts.get("thumbnail"):
+            if record_notification("thumbnail_generation_completed", f"Thumbnail gerada: {title}", f"A thumbnail de {channel} está pronta.", metadata={"task_id": task_id, "channel_name": channel}, dedupe_key=f"task:{task_id}:thumbnail"):
+                created += 1
+    return created
+
+
+def _upload_notifications() -> int:
+    created = 0
+    uploads = storage.read_json("uploads.json", [])
+    if not isinstance(uploads, list):
+        return 0
+    event_by_destination = {
+        "youtube": "upload_youtube_success",
+        "tiktok": "upload_tiktok_success",
+        "instagram": "upload_instagram_success",
+        "facebook pages": "upload_facebook_pages_success",
+        "facebook_pages": "upload_facebook_pages_success",
+        "postiz": "upload_postiz_success",
+        "youtube direct frontend": "upload_youtube_success",
+    }
+    for upload in uploads:
+        if not isinstance(upload, dict) or str(upload.get("status") or "").lower() not in {"published", "success", "done"}:
+            continue
+        upload_id = str(upload.get("id") or "")
+        task_id = str(upload.get("task_id") or upload_id or uuid.uuid4().hex[:8])
+        upload_created_at = str(upload.get("created_at") or "")
+        destination = str(upload.get("destination") or "Upload").strip()
+        event_type = event_by_destination.get(destination.lower(), "upload_youtube_success" if destination.lower().startswith("youtube") else "upload_postiz_success" if destination.lower().startswith("postiz") else "upload_youtube_success")
+        target = upload.get("target") if isinstance(upload.get("target"), dict) else {}
+        target_name = str(target.get("name") or target.get("label") or target.get("handle") or target.get("username") or "destino seleccionado")
+        if record_notification(event_type, f"Upload concluído: {destination}", f"O vídeo foi enviado com sucesso para {target_name}.", metadata={"task_id": task_id, "destination": destination, "target": target, "route": (upload.get("data") or {}).get("route") if isinstance(upload.get("data"), dict) else ""}, dedupe_key=f"upload:{upload_id or task_id}:{destination.lower()}:{upload_created_at}"):
+            created += 1
+    return created
+
+
+def _script_notifications() -> int:
+    created = 0
+    records = storage.read_json("scripts.json", [])
+    if not isinstance(records, list):
+        return 0
+    for record in records:
+        if not isinstance(record, dict) or not record.get("id"):
+            continue
+        event_type = "music_lyrics_generated" if str(record.get("document_type") or "") == "music_lyrics" else "standalone_script_generated"
+        label = "Letra de música" if event_type == "music_lyrics_generated" else "Roteiro autónomo"
+        document_id = str(record["id"])
+        dedupe_key = str(record.get("notification_dedupe_key") or f"script:{document_id}:generated")
+        if record_notification(event_type, f"{label} gerado: {record.get('title') or 'Documento'}", f"O documento foi guardado no histórico de roteiros.", metadata={"document_id": document_id, "document_type": record.get("document_type") or ""}, dedupe_key=dedupe_key):
+            created += 1
+    return created
+
+
+def _automation_notifications() -> int:
+    created = 0
+    worker = storage.read_json("automation_worker.json", {})
+    last_runs = worker.get("last_runs", {}) if isinstance(worker, dict) else {}
+    if isinstance(last_runs, dict):
+        for channel_id, run in last_runs.items():
+            if not isinstance(run, dict) or not run.get("batch_id"):
+                continue
+            if record_notification("automation_completed", "Automação concluída", f"O lote agendado do canal {channel_id} foi criado com sucesso.", metadata={"channel_id": channel_id, "batch_id": run.get("batch_id"), "time": run.get("time") or ""}, dedupe_key=f"automation:{run['batch_id']}"):
+                created += 1
+    return created
+
+
+def _generic_completion_notifications() -> int:
+    created = 0
+    cuts = storage.read_json("cuts_runs.json", [])
+    if isinstance(cuts, list):
+        for run in cuts:
+            if isinstance(run, dict) and str(run.get("status") or "") == "complete" and run.get("id"):
+                if record_notification("cuts_completed", "Cortes concluídos", "A geração de cortes terminou com um manifesto completo.", metadata={"run_id": run.get("id")}, dedupe_key=f"cuts:{run['id']}"):
+                    created += 1
+    indexed_sources = (
+        ("metadata_edits.json", "metadata_cleaning_completed", "Metadados limpos", "metadata edit"),
+        ("python_editor_edits.json", "python_edit_completed", "Edição Python concluída", "Python edit"),
+    )
+    for filename, event_type, label, source_label in indexed_sources:
+        records = storage.read_json(filename, [])
+        if not isinstance(records, list):
+            continue
+        for record in records:
+            if not isinstance(record, dict) or not record.get("id"):
+                continue
+            record_id = str(record["id"])
+            output_name = str(record.get("output_name") or "artefacto guardado")
+            if record_notification(event_type, f"{label}: {output_name}", f"A operação {source_label} terminou com sucesso.", metadata={"record_id": record_id, "output_name": output_name, "operation": record.get("operation") or ""}, dedupe_key=f"{event_type}:{record_id}"):
+                created += 1
+    apify_runs = storage.read_json("niche_apify_runs.json", [])
+    if isinstance(apify_runs, list):
+        for run in apify_runs:
+            status = str(run.get("status") or "").lower() if isinstance(run, dict) else ""
+            if status in {"succeeded", "success", "completed", "complete"} and run.get("run_id"):
+                run_id = str(run["run_id"])
+                if record_notification("niche_analysis_completed", "Análise de nicho concluída", f"A pesquisa Apify terminou com {run.get('item_count', 0)} vídeo(s) recebido(s).", metadata={"run_id": run_id, "item_count": run.get("item_count", 0)}, dedupe_key=f"niche:apify:{run_id}"):
+                    created += 1
+    return created
+
+
+def reconcile_persisted_notifications() -> int:
+    """Emit idempotent events for completions written by other local processes."""
+    total = 0
+    for resolver in (_task_notifications, _upload_notifications, _script_notifications, _automation_notifications, _generic_completion_notifications):
+        try:
+            total += resolver()
+        except Exception:
+            # Notifications must never prevent the main production/upload flow.
+            continue
+    return total

package/hermes_ui/python_editor.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from typing import Any
 
 from . import storage
+from .notifications import record_notification
 from .metadata_cleaner import VIDEO_EXTENSIONS as METADATA_VIDEO_EXTENSIONS
 from .metadata_cleaner import _resolve_ffmpeg
 
@@ -257,6 +258,13 @@ def save_edit_record(source: Path, output: Path, run_info: dict[str, Any]) -> di
         "created_at": run_info.get("created_at", _now()),
     }
     storage.append_json("python_editor_edits.json", record)
+    record_notification(
+        "python_edit_completed",
+        f"Edição Python concluída: {output.name}",
+        f"A operação {record.get('operation') or 'de edição'} terminou com um artefacto guardado.",
+        metadata={"record_id": record["id"], "output_name": output.name, "operation": record.get("operation") or ""},
+        dedupe_key=f"python_edit_completed:{record['id']}",
+    )
     return record
 
 

package/hermes_ui/storage.py

@@ -24,6 +24,7 @@ DEFAULTS: dict[str, Any] = {
     "queues.json": {"niche": [], "blueprint": [], "brand": [], "script": [], "title": [], "thumbnail": [], "video": [], "edit": [], "upload": []},
     "batches.json": [],
     "uploads.json": [],
+    "notifications.json": [],
     "display_names.json": {"blueprints": {}, "prompt_masters": {}},
     "niche_apify_runs.json": [],
     "metadata_edits.json": [],
@@ -90,6 +91,30 @@ DEFAULTS: dict[str, Any] = {
         "youtube_client_secret": "",
         "youtube_batch_accounts": [],
         "youtube_batch_selected_account_id": "",
+        "notification_preferences": {
+            "video_completed": True,
+            "music_completed": True,
+            "standalone_script_generated": True,
+            "music_lyrics_generated": True,
+            "script_stage_completed": True,
+            "title_generation_completed": True,
+            "thumbnail_generation_completed": True,
+            "blueprint_completed": True,
+            "branding_completed": True,
+            "niche_analysis_completed": True,
+            "cuts_completed": True,
+            "metadata_cleaning_completed": True,
+            "python_edit_completed": True,
+            "automation_completed": True,
+            "automation_failed": True,
+            "activity_failed": True,
+            "upload_youtube_success": True,
+            "upload_tiktok_success": True,
+            "upload_instagram_success": True,
+            "upload_facebook_pages_success": True,
+            "upload_postiz_success": True,
+            "mcp_operation_completed": True,
+        },
         "kaggle_username": "",
         "kaggle_api_key": "",
         "kaggle_kernel_slug": "thunderbolt-niche-finder",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.2.71",
+  "version": "0.2.73",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "main": "scripts/cli.mjs",
   "type": "module",