​

Exec in background + strumento Process

​

Strumento exec

• command (obbligatorio)
• yieldMs (predefinito 10000): passa automaticamente in background dopo questo ritardo
• background (bool): passa immediatamente in background
• timeout (secondi, predefinito 1800): termina il processo dopo questo timeout
• elevated (bool): esegue fuori dalla sandbox se la modalità elevata è abilitata/consentita (gateway per impostazione predefinita, oppure node quando la destinazione exec è node)
• Serve un vero TTY? Imposta pty: true.
• workdir, env

• Le esecuzioni in primo piano restituiscono direttamente l’output.
• Quando passa in background (esplicitamente o per timeout), lo strumento restituisce status: "running" + sessionId e una breve coda dell’output.
• L’output viene mantenuto in memoria finché la sessione non viene sondata o rimossa.
• Se lo strumento process non è consentito, exec viene eseguito in modo sincrono e ignora yieldMs/background.
• I comandi exec avviati ricevono OPENCLAW_SHELL=exec per regole della shell/profilo sensibili al contesto.
• Per attività di lunga durata che iniziano ora, avviale una sola volta e fai affidamento sul risveglio automatico al completamento quando è abilitato e il comando produce output o fallisce.
• Se il risveglio automatico al completamento non è disponibile, oppure ti serve la conferma di successo silenzioso per un comando che è terminato correttamente senza output, usa process per confermare il completamento.
• Non simulare promemoria o follow-up ritardati con loop sleep o polling ripetuto; usa cron per il lavoro futuro.

​

Bridging dei processi figli

• PI_BASH_YIELD_MS: yield predefinito (ms)
• PI_BASH_MAX_OUTPUT_CHARS: limite di output in memoria (caratteri)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: limite stdout/stderr in sospeso per stream (caratteri)
• PI_BASH_JOB_TTL_MS: TTL per le sessioni terminate (ms, limitato a 1m–3h)

• tools.exec.backgroundMs (predefinito 10000)
• tools.exec.timeoutSec (predefinito 1800)
• tools.exec.cleanupMs (predefinito 1800000)
• tools.exec.notifyOnExit (predefinito true): mette in coda un evento di sistema + richiede un heartbeat quando un exec in background termina.
• tools.exec.notifyOnExitEmptySuccess (predefinito false): quando è true, mette in coda anche eventi di completamento per esecuzioni in background riuscite che non hanno prodotto output.

​

Strumento process

• list: sessioni in esecuzione + terminate
• poll: scarica il nuovo output per una sessione (riporta anche lo stato di uscita)
• log: legge l’output aggregato (supporta offset + limit)
• write: invia stdin (data, eof facoltativo)
• send-keys: invia token di tasti espliciti o byte a una sessione supportata da PTY
• submit: invia Enter / ritorno a capo a una sessione supportata da PTY
• paste: invia testo letterale, facoltativamente racchiuso nella modalità di incolla delimitata
• kill: termina una sessione in background
• clear: rimuove dalla memoria una sessione terminata
• remove: termina se è in esecuzione, altrimenti rimuove se è terminata

• Solo le sessioni passate in background vengono elencate/conservate in memoria.
• Le sessioni vengono perse al riavvio del processo (nessuna persistenza su disco).
• I log delle sessioni vengono salvati nella cronologia chat solo se esegui process poll/log e il risultato dello strumento viene registrato.
• process è limitato per agente; vede solo le sessioni avviate da quell’agente.
• Usa poll / log per stato, log, conferma di successo silenzioso o conferma di completamento quando il risveglio automatico al completamento non è disponibile.
• Usa write / send-keys / submit / paste / kill quando ti servono input o interventi.
• process list include un name derivato (verbo del comando + destinazione) per scansioni rapide.
• process log usa offset/limit basati sulle righe.
• Quando sia offset sia limit vengono omessi, restituisce le ultime 200 righe e include un suggerimento per l’impaginazione.
• Quando viene fornito offset e limit viene omesso, restituisce da offset fino alla fine (non limitato a 200).
• Il polling serve per lo stato on-demand, non per pianificare cicli di attesa. Se il lavoro deve avvenire in seguito, usa cron.

​

Esempi

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }

{ "tool": "exec", "command": "npm run build", "background": true }

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }