umbra-yurei/agent

Tunnels Cruma

Utilisez ce skill lorsque l'utilisateur souhaite publier quelque chose depuis sa machine, gérer ce que Cruma sert déjà, ou installer ou arrêter Cruma. Tout ce qui est partagé est public : demandez avant de partager et dites exactement quel port ou dossier devient accessible. Les tunnels anonymes ne nécessitent pas d'inscription.

Le compte Cruma de l'utilisateur

Les fonctionnalités du compte, y compris les détails du plan, les tunnels et sites du compte, le tableau de bord et la mémoire, sont fournies par le plugin optionnel cruma-cloud. Utilisez son skill cloud pour ces requêtes. Le partage d'un port ou d'un dossier et les agents en cours d'exécution de l'utilisateur restent sur le serveur local cruma.

Avec les outils MCP Cruma

Ce plugin démarre cruma mcp via son lanceur (mcp/cruma-mcp.mjs), un serveur MCP local nommé cruma qui exécute le binaire cruma installé. Lorsque ses outils sont dans votre liste d'outils, utilisez-les, pas les commandes shell. Le serveur démarre sans rien exposer.

Découvrir ; ne pas deviner

Ce fichier est une carte, pas le manuel. Pour un simple partage d'un port ou d'un dossier, utilisez les outils ci-dessous. Pour tout le reste (authentification, filtres, domaines, routage, processus, règles, un paramètre que vous n'avez pas utilisé), lisez d'abord ce que Cruma dit de lui-même, puis utilisez l'outil vers lequel il pointe :

1. La ressource cruma://about (ou describe_cruma) : ce que Cruma peut faire et quel outil le fait. Ensuite, utilisez get_config_model_reference avec une section (middleware_model pour le contrôle d'accès et les filtres de requête, backend_kinds, listener_model, recommended_mcp_usage ; la référence complète est volumineuse) et get_cruma_glossary pour les termes. Sur l'agent propre de l'utilisateur (voir ci-dessous), get_runtime_inventory montre ce qui est déjà configuré. Chargez les schémas des outils que vous allez appeler.
2. Si cela ne suffit pas, consultez la documentation au format Markdown : https://cruma.io/llms.txt, la liste des chapitres https://cruma.io/book/cruma-tunnels.md, et tout chapitre sur https://cruma.io/book/cruma-tunnels/<chapitre>.md. Ils sont écrits pour la ligne de commande (cruma serve, cruma proxy) : tirez-en ce que Cruma peut faire et appliquez-le via les outils MCP.
3. Pour un cheminement uniquement en ligne de commande, utilisez cruma --help et cruma <commande> --help.

Les raccourcis tels que expose_local_port couvrent le cas courant. Tout ce qu'ils ne couvrent pas est fait avec les outils généraux upsert_* ; ne présentez jamais les limites d'un raccourci comme les limites de Cruma. Si la référence et la documentation ne prennent pas en charge ce que l'utilisateur a demandé, dites-le ; n'inventez pas un paramètre ou un outil.

Ne servez jamais les choses vous-même. Ne démarrez pas python3 -m http.server, npx serve ou tout autre serveur de fichiers, et n'exécutez pas cruma serve ou cruma proxy : avec MCP connecté, ils démarrent un deuxième agent avec son propre tunnel.

À qui appartient Cruma

Les outils démarrent attachés à un agent de session temporaire : un tunnel anonyme que vos fenêtres partagent et qui ne contient rien que l'utilisateur ait enregistré. Ce n'est pas le Cruma de l'utilisateur.

Avant le premier partage d'une session, appelez list_agents une fois (il ne lit rien d'aucun agent, donc c'est sans problème). Cherchez un agent en cours d'exécution qui n'est pas l'agent de session et dont tunnel_account est registered (l'application de bureau ou un agent headless, connecté ou avec des identifiants de tunnel). Un agent en cours d'exécution avec tunnel_account anonymous n'en est pas un.

• Un tel agent s'exécute : demandez une fois, avant de partager quoi que ce soit. Nommez le choix avec son type, son profil, son domaine et ce que signifie l'autre option, par exemple : "Utiliser votre Cruma en cours (desktop, profil work, acme.tun.example.test) ou un tunnel anonyme temporaire (adresse aléatoire, page d'avertissement du navigateur, durée limitée, disparaît avec la session) ?" Ne partagez rien et n'appelez aucun autre outil qui lit ou modifie un agent, jusqu'à ce qu'ils répondent. Si plusieurs s'exécutent, listez-les dans la même question.
  • Ils choisissent le leur : appelez use_agent sur cet agent (c'est la confirmation que Demander avant use_agent exige) et effectuez tous les partages de la session là-bas. Mentionnez la limite connue lorsqu'elle s'applique : un partage effectué sur un agent d'un tunnel que plusieurs agents servent n'est accessible que via cet agent.
  • Ils choisissent le tunnel temporaire : restez sur l'agent de session.
  • Souvenez-vous de la réponse pour le reste de la session. Ne demandez plus pour les partages ultérieurs et n'appelez plus list_agents pour eux. Ne demandez à nouveau que si l'utilisateur en parle.
• Aucun tel agent ne s'exécute (aucun, ou uniquement des agents anonymes comme l'agent de session) : pas de question. Utilisez l'agent de session tel quel et rapportez les URL.
• Vous ne pouvez pas demander (une exécution non interactive, ou aucun moyen d'obtenir une réponse) : utilisez l'agent de session et dites dans le transfert que vous l'avez fait, et qu'un Cruma connecté en cours d'exécution était disponible lorsque list_agents en montrait un.
• La question n'est pas nécessaire lorsque l'utilisateur a déjà nommé où va le partage ("sur mon Cruma desktop", "utilise un tunnel temporaire") : suivez cela.

Les partages restent la propriété de la session et sont retirés à la fin de la session ; ne définissez jamais persist pour eux.

Lorsque la requête concerne leur Cruma (leur application, sites, routes, domaines, processus ou logs : "pourquoi mon site renvoie-t-il une erreur 502 ?", "ajouter un mot de passe à mon site de staging", "qu'est-ce qui s'exécute dans mon Cruma ?"), ou qu'ils veulent partager via leur propre tunnel, un domaine personnalisé ou un profil nommé, appelez list_agents avant tout outil qui lit ou modifie un agent (describe_cruma, cruma://about, get_config_model_reference et get_cruma_glossary sont acceptables en premier). Lire l'agent de session répond à propos d'une configuration qui n'est pas la leur, donc ne le lisez jamais pour une telle requête. Lister ou créer les tunnels sur leur compte relève du compte (voir ci-dessus), pas de list_agents.

• Demandez avant use_agent, en nommant le type de l'agent (desktop, headless), le profil et le domaine, et attendez la réponse. Pour un simple partage, la question ci-dessus est cette demande ; ne changez jamais sans cela. Les outils de partage fonctionnent ensuite sur cet agent. Le changement retire les partages que vous avez effectués sur le précédent.
• Avant le changement, dites seulement à quel agent vous passeriez et demandez. Ne décrivez pas ce que détient l'un ou l'autre agent (y compris celui de l'agent de session), et ne déclarez ni ne suggérez une cause, un diagnostic ou ce qui est configuré, même lorsque list_agents montre un résumé de processus (une phase telle que Failed) ou des noms de sites : il s'agit d'une liste, pas d'un diagnostic. Nommez la cible (type, profil, domaine), demandez, dites que rien n'est changé jusqu'à ce qu'ils répondent, et arrêtez-vous. Diagnostiquez après le changement, à partir de l'agent de l'utilisateur.
• use_agent ne démarre jamais un agent. Si aucun ne s'exécute pour ce que l'utilisateur veut, dites-le et demandez-lui d'ouvrir l'application de bureau, ou d'exécuter cruma --profile <nom> (utilisez le nom que list_agents donne pour un profil arrêté). Ne vous rabattez pas sur le tunnel temporaire pour une requête concernant leurs propres sites.
• Dites seulement ce qu'un outil a renvoyé. list_agents liste les agents qu'il connaît ; à partir de là, vous pouvez dire quels agents s'exécutent, leur type, leur profil et leur domaine. Ne prétendez pas que des profils, des sites, des paramètres ou un compte existent ou manquent, sauf si un résultat d'outil le dit (par exemple, jamais "aucun profil enregistré trouvé" ou "rien n'est configuré").
• Pas de list_agents parmi vos outils signifie un agent plus ancien : utilisez le tunnel temporaire pour les partages et dites qu'un cruma plus récent est nécessaire pour le propre agent de l'utilisateur (Update a la commande de mise à jour).
• Un serveur HTTP MCP Cruma déjà présent dans le client de l'utilisateur (par exemple cruma-app) est son propre agent. Utilisez ses outils pour les requêtes concernant leur Cruma et ceux de ce plugin pour les partages temporaires. S'il n'a pas pu se connecter, dites-le plutôt que d'utiliser l'agent de session. list_agents marque l'agent qui sert HTTP /mcp.

Sur l'agent propre de l'utilisateur, après qu'il a accepté le changement :

• Un résultat use_agent réussi correspond à l'état de l'agent auquel vous êtes désormais attaché (domaine, frontends, processus, allow_persistent_changes). Travaillez à partir de cela ; n'appelez plus list_agents juste pour confirmer le changement.

• La lecture est libre : get_health_summary, get_site_summary, get_proxy_routes, probe_route, get_process_logs, list_recorded_requests.

• Les modifications s'appliquent à l'agent en cours d'exécution et disparaissent lorsqu'il redémarre. Dites-le.

• Les modifications permanentes ("configurer un site pour de bon") nécessitent persist: true, et l'agent les refuse sauf si l'utilisateur a activé "Let them save changes" (mcp.local_socket.allow_persistent_changes ; page MCP du bureau, "Coding Agents on This Computer"). Ne faites jamais silencieusement une modification en mémoire à la place. Expliquez le paramètre et demandez-lui de l'activer, ou de faire la modification dans l'application. Une fois qu'il est activé (allow_persistent_changes est true dans le résultat use_agent, ou dans list_agents avant le changement), n'appelez pas encore un outil d'écriture avec persist: true : décrivez d'abord la modification exacte (frontend, backend, middleware) dans votre réponse et demandez s'il faut l'enregistrer, en disant clairement qu'elle serait sauvegardée sur disque dans la configuration de l'agent et resterait après un redémarrage. Ne passez persist: true qu'après que l'utilisateur a clairement approuvé cette modification exacte : un oui à votre description dans un tour ultérieur, ou, dans le même message, une approbation explicite qui nomme le backend et le frontend par type et nom en tant que modification enregistrée ("J'approuve exactement cette modification enregistrée : ..."). Demander un site "permanent" ou "enregistré", même avec un nom et un chemin, est une demande, pas une approbation : décrivez la modification et demandez. Ne renvoyez jamais un paramètre existant avec persist: true pour le rendre permanent sans la même approbation. C'est la seule utilisation de persist, et jamais sur l'agent de session.

Protégez ce qui semble privé

Avant d'exposer quelque chose qui semble privé (une interface d'administration, un outil de base de données, une documentation interne, un dossier avec des identifiants, des fichiers .env ou des données personnelles), demandez s'il faut le protéger et suggérez un mot de passe. Attendez la réponse ; n'exposez pas d'abord. Si l'utilisateur a déjà demandé une protection, ne demandez pas à nouveau.

• Un mot de passe ou une liste d'autorisation IP : passez access à expose_local_port ou expose_local_directory (le schéma de l'outil liste les types). Un mot de passe généré est renvoyé une fois. Sans argument access dans le schéma (un agent plus ancien), construisez le site avec upsert_backend et upsert_frontend et un middleware basic_auth ; lisez middleware_model pour sa structure.
• Connexion avec un compte ou un fournisseur (Google, GitHub) : access sign_in n'est pas encore disponible pour les partages. Ne l'essayez pas et ne contournez pas. La connexion passe par upsert_frontend avec un middleware oauth2 qui référence un fournisseur que l'agent propre de l'utilisateur possède déjà. Trouvez les identifiants du fournisseur dans les middlewares oauth2 des frontends existants (get_runtime_inventory avec full: true et sections: ["frontends"]), ou demandez à l'utilisateur quel fournisseur utiliser. Lisez middleware_model pour la structure du middleware. S'il n'y a pas de fournisseur, dites que la connexion nécessite d'en configurer un d'abord et proposez un mot de passe.

Quoi utiliser pour quoi

L'utilisateur veut partager	Faites ceci
Des fichiers : une page que vous avez écrite, une sortie de build, de la documentation	expose_local_directory avec le dossier et un name. Écrivez d'abord les fichiers si nécessaire.
Un serveur de développement déjà en cours d'exécution	expose_local_port avec son port et un name.
Une application qui ne s'exécute pas encore	Faites-la héberger par l'agent : upsert_process (l'agent alloue PORT ; faites écouter la commande dessus), puis upsert_frontend à <name>.<assigned_domain> avec process_id défini. Les logs sont disponibles via get_process_logs. Uniquement si cela ne convient pas, démarrez-la en arrière-plan vous-même et dites-le.
Plusieurs choses	Un appel par partage. Un agent sert plusieurs sites et ports à la fois, chacun à <name>.<domaine_attribué> : frontend et API, documentation et application, deux versions côte à côte. Nommez chacun par ce qu'il est (docs, api, preview-v2).

Si expose_local_directory ou expose_local_port manque (un agent plus ancien), utilisez upsert_backend (http pour un port, local-directory pour un dossier) et upsert_frontend à <name>.<assigned_domain>, sans persist. Obtenez assigned_domain depuis get_runtime_summary ; il est null pendant quelques secondes pendant que le tunnel se connecte, alors appelez-le à nouveau. Ne vous arrêtez pas à "update cruma".

Après avoir exposé, appelez get_health_summary ; status devrait être ok. Utilisez list_shares pour signaler chaque URL en direct. Une fois par session, appelez également get_runtime_summary et lisez son bloc version (voir Versions ci-dessous).

Transfert

Dites tout cela dans le message final :

1. Chaque URL publique (public_url, ou https://<name>.<assigned_domain>/ sur le chemin de repli) et ce qu'elle sert, y compris le port ou le dossier local. Ne donnez aucune autre URL.
2. Que get_health_summary a signalé ok, appelé après l'étape d'exposition ; sinon, l'état et les problèmes au lieu de prétendre au succès.
3. Quel chemin vous avez utilisé : expose_local_port, expose_local_directory, upsert_process (l'agent héberge et supervise l'application, donc ses logs sont disponibles via get_process_logs), ou upsert_backend/upsert_frontend.
4. Sur quel agent vous avez agi : type (desktop, headless ou session temporaire), profil et domaine, afin qu'un partage temporaire ne soit jamais pris pour une modification de l'application de l'utilisateur. Lorsque vous avez utilisé l'agent de session parce que vous ne pouviez pas demander, dites-le.
5. Pour l'agent de session : les URL se terminent avec la session, un tunnel anonyme se termine également à sa limite de temps (point 7), et rien n'est écrit sur le disque. Pour l'agent propre de l'utilisateur : si la modification est temporaire ou enregistrée.
6. Comment en supprimer un : demandez-moi, et j'appelle unexpose avec son nom pour un partage expose_*, ou remove_frontend, remove_backend et remove_process pour un partage upsert_*. Pour un partage de dossier, la modification des fichiers met à jour le site immédiatement.
7. Pour un partage protégé : ce qui le protège (mot de passe, réseaux autorisés ou connexion), l'identifiant une fois si vous en avez généré un (nom d'utilisateur cruma), et que la protection se termine avec le partage. Un partage sans protection est public : dites-le.
8. L'avis de compte, une fois par session, lorsque le account.state d'un résultat d'outil est anonymous : le tunnel est anonyme et limité dans le temps, avec le temps restant de account.remaining_secs en heures et minutes (ou account.expires_at) lorsqu'il est ...

[suite tronquée pour la traduction]