docs(ai): update opencode guidance

docs/opencode_api.md

@@ -130,7 +130,7 @@ Abort a running generation.
 
 ### `POST /session/:id/prompt_async`
 
-Fire-and-forget variant. Returns `204` immediately. Include `messageID` in the request body to make the assistant response addressable by `GET /session/:id/message/:messageID`. Opencode validates caller-provided message IDs; use IDs starting with `msg`.
+Fire-and-forget variant. Returns `204` immediately. Include `messageID` in the request body so the submitted message can be matched to the later assistant response. Opencode validates caller-provided message IDs; use IDs starting with `msg`.
 
 **Request body:**
 ```json

docs/opencode_server_guide.md

@@ -90,13 +90,23 @@ Optional — override the Basic Auth username (default `opencode`):
 set opencc.username myuser
 ```
 
-Optional but recommended: pick the provider and model. When both are set, `ai` posts to `/session/:id/prompt_async`. Without them, `ai` falls back to blocking `/session/:id/message`, which can use the server default model but is more exposed to HTTP timeouts:
+Optional but recommended: pick the provider and model. When both are set, `ai` posts to `/session/:id/prompt_async` and polls for completion. Without them, `ai` falls back to blocking `/session/:id/message`, which can use the server default model but is more exposed to HTTP timeouts:
 
 ```sh
 set opencc.provider_id anthropic
 set opencc.model_id claude-opus-4-7
 ```
 
+Optional timeout settings:
+
+```sh
+set opencc.timeout_seconds 60
+set opencc.poll_timeout_seconds 300
+set opencc.poll_interval_seconds 2
+```
+
+`opencc.session_id` is auto-managed and saved by `ai`. Set it manually only when you want CC to target an existing session, such as one opened in the attached TUI.
+
 - **CraftOS-PC (localhost):** `http://127.0.0.1:4096`
 - **In-game ATM10:** use your LAN IP (e.g. `192.168.x.x`) — add it to `http.rules` in `config/computercraft-server.toml`
 
@@ -107,6 +117,7 @@ ai ping                    -- ping, reuses existing session
 ai "explain what a turtle is"
 ai new "start a fresh topic" -- forget current session, start fresh
 ai sessions                -- list all server sessions with their IDs
+ai --verbose ping          -- show HTTP/session diagnostics
 ai --help
 ai --version
 ```

docs/trapgpt_guide.md

@@ -1,15 +1,15 @@
 # TrapGPT Guide
 
-TrapGPT est un serveur TrapOS qui ecoute le chat Minecraft avec une Chat Box Advanced Peripherals, envoie les nouveaux messages a `opencode serve`, puis repond tres brievement dans le chat.
+TrapGPT est un programme TrapOS qui ecoute le chat Minecraft avec une Chat Box Advanced Peripherals, envoie les nouveaux messages a `opencode serve`, puis repond tres brievement dans le chat.
 
 ## Prerequis
 
 - Une Chat Box Advanced Peripherals connectee au computer.
-- TrapOS installe avec le package `trapos-ai`.
+- TrapOS installe. Le package complet `trapos` inclut `trapos-ai`; sinon installe `trapos-ai` separement.
 - Un serveur `opencode serve` accessible depuis ComputerCraft HTTP.
 - HTTP active cote serveur Minecraft/ComputerCraft.
 
-Voir aussi [`docs/opencode_server_guide.md`](opencode_server_guide.md) pour lancer `opencode serve`.
+Voir aussi [`opencode_server_guide.md`](opencode_server_guide.md) pour lancer `opencode serve`.
 
 ## Configuration In-Game
 
@@ -26,6 +26,13 @@ Si ton serveur opencode demande un mot de passe Basic Auth:
 set opencc.password ton_mot_de_passe
 ```
 
+TrapGPT utilise les memes settings `opencc.*` que le programme `ai`. Il profite aussi de `opencc.provider_id` et `opencc.model_id`; quand ils sont configures, `libai` utilise l'endpoint async de opencode et evite mieux les timeouts HTTP longs.
+
+```lua
+set opencc.provider_id anthropic
+set opencc.model_id claude-opus-4-7
+```
+
 Settings optionnels pour TrapGPT:
 
 ```lua
@@ -34,12 +41,6 @@ set trapgpt.max_reply_chars 160
 set trapgpt.prefix TrapGPT
 ```
 
-Sauvegarde les settings:
-
-```lua
-settings save
-```
-
 ## Lancement
 
 Depuis le shell CraftOS:
@@ -60,11 +61,15 @@ Ensuite, parle normalement dans le chat Minecraft. TrapGPT collecte les messages
 
 - TrapGPT ecoute pour l'instant seulement les messages joueur `chat`.
 - Les morts et connexions seront ajoutes plus tard.
+- Les messages caches, vides, ou envoyes avec le meme nom que `trapgpt.prefix` sont ignores.
+- Quand `messageUtf8` est fourni par l'evenement `chat`, TrapGPT l'utilise a la place de `message`.
 - Il ne lance jamais deux appels LLM en meme temps.
 - Les messages recus pendant un appel opencode sont gardes en queue.
 - Si plusieurs messages sont en queue, ils sont envoyes ensemble au batch suivant.
-- La session opencode est separee du programme `ai`: elle utilise `trapgpt.opencc.session_id`.
+- Si l'appel opencode echoue, la queue est conservee pour un prochain essai.
+- La session opencode est separee du programme `ai`: elle utilise `trapgpt.opencc.session_id` et le titre de session `trapgpt`.
 - Si le LLM repond exactement `SILENCE`, rien n'est envoye dans le chat.
+- Les reponses sont tronquees a `trapgpt.max_reply_chars` caracteres.
 
 ## Redemarrer Une Session TrapGPT
 
@@ -103,3 +108,9 @@ Pour voir la version installee:
 ```lua
 trapgpt --version
 ```
+
+Pour afficher l'aide:
+
+```lua
+trapgpt --help
+```

manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "TrapOS",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "branch": "next",
   "packages": [
     "trapos"

packages/index.json

@@ -5,8 +5,8 @@
     "trapos-boot": "0.3.2",
     "trapos-net": "0.3.0",
     "trapos-ui": "0.2.2",
-    "trapos-ai": "0.6.3",
+    "trapos-ai": "0.6.4",
     "trapos-sandbox": "0.1.1",
-    "trapos": "0.8.4"
+    "trapos": "0.8.5"
   }
 }

packages/trapos-ai/ccpm.json

@@ -1,6 +1,6 @@
 {
   "name": "trapos-ai",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "TrapOS AI client for opencode serve",
   "dependencies": ["trapos-core"],
   "files": [

packages/trapos/ccpm.json

@@ -1,6 +1,6 @@
 {
   "name": "trapos",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "TrapOS full install meta-package",
   "dependencies": ["trapos-boot", "trapos-net", "trapos-ui", "trapos-test", "trapos-ai"],
   "files": [],

programs/ai.lua

@@ -21,8 +21,8 @@ local function printUsage()
   print('  ai ping');
   print('  ai new <prompt>');
   print('  ai --new <prompt>');
-  print('  ai lua-exec <prompt>');
+  print('  ai lua-exec <prompt>       (deprecated)');
-  print('  ai --lua-exec <prompt>');
+  print('  ai --lua-exec <prompt>     (deprecated)');
   print('  ai sessions');
   print('  ai --sessions');
   print('  ai --verbose <command>');
@@ -174,6 +174,7 @@ if command == 'lua-exec' or command == '--lua-exec' then
     printUsage();
     return;
   end
+  print('warning: ai lua-exec is deprecated and will be removed');
   luaExec(ai, prompt);
   return;
 end