Documentation
¶
Overview ¶
Package engine contient la boucle agentique : il relie le fournisseur, les outils, les permissions, le contrôle sortant et l'audit, et émet des événements typés consommés par les interfaces.
Index ¶
- Constants
- Variables
- func PrepareWrite(st *memory.Store, redact func(string) (string, bool), rules classify.Rules, ...) (out memory.Entry, notices []string, redacted bool, err error)
- type Budget
- type Deps
- type Engine
- func (e *Engine) EndSession(ctx context.Context, sessionID, reason string) error
- func (e *Engine) Remember(sessionID string, scope memory.Scope, text string) (memory.Entry, []string, error)
- func (e *Engine) Respond(permissionID string, r Reply) error
- func (e *Engine) Restore(sessionID string, events []event.Event) error
- func (e *Engine) Rewind(ctx context.Context, sessionID string, toSeq uint64, mode RewindMode, ...) (RewindResult, error)
- func (e *Engine) RewindPlan(sessionID string, toSeq uint64) (checkpoint.Plan, error)
- func (e *Engine) RewindPoints(sessionID string) []checkpoint.Point
- func (e *Engine) SessionTokens(sessionID string) int64
- func (e *Engine) Submit(ctx context.Context, sessionID, input string) error
- func (e *Engine) SubmitInput(ctx context.Context, sessionID string, in Input) error
- func (e *Engine) Subscribe() <-chan event.Event
- type Input
- type Reply
- type RewindMode
- type RewindResult
- type Shaped
Constants ¶
const ( // DefaultContextWindow s'applique quand Deps.ContextWindow vaut 0 ou moins. DefaultContextWindow = 32000 // DefaultCompactionThreshold s'applique quand Deps.CompactionThreshold // vaut 0 ou moins. DefaultCompactionThreshold = 0.8 )
const DefaultMaxIterations = 50
DefaultMaxIterations s'applique quand Deps.MaxIterations vaut 0 ou moins.
const DefaultWarnAt = 0.8
DefaultWarnAt s'applique quand Budget.WarnAt est hors de ]0, 1[.
Variables ¶
var ( // ErrAuditFailure : un Sink a échoué ; l'engine refuse désormais tout tour. ErrAuditFailure = errors.New("audit log write failure") // ErrUnknownPermission : Respond avec un identifiant inconnu ou déjà résolu. ErrUnknownPermission = errors.New("unknown permission request") // ErrSessionActive : Restore sur une session déjà utilisée dans ce processus. ErrSessionActive = errors.New("session already active in this process") )
var ( // ErrTurnInProgress : un tour tient la session ; le rewind n'attend pas. ErrTurnInProgress = errors.New("a turn is in progress") ErrConversationUnavailable = errors.New("conversation cannot be rewound past a compaction") )
var DefaultSystemPrompt = i18n.SystemPrompt(i18n.FR)
DefaultSystemPrompt est le prompt système utilisé quand Deps.SystemPrompt est vide.
var ErrMemoryDisabled = errors.New("memory: disabled")
ErrMemoryDisabled : Remember sans store mémoire (mémoire coupée).
Functions ¶
func PrepareWrite ¶ added in v0.8.0
func PrepareWrite(st *memory.Store, redact func(string) (string, bool), rules classify.Rules, sensitiveSession bool, e memory.Entry) (out memory.Entry, notices []string, redacted bool, err error)
PrepareWrite applique la chaîne d'avant écriture (spec §6) à e : masquage du titre et du contenu (redact nil : aucun), marquage de classification sur le titre masqué entier, titre coupé à 80 caractères (après le masquage, qui sinon pourrait manquer un morceau de secret, et après le marquage, qui sinon pourrait perdre un marqueur), session sensible, redirection d'une entrée sensible project ou global vers user (avec avis), puis limites. Un ID vide est dérivé du titre masqué, ou vaut « sensitive » pour une entrée sensible (le titre ne fuit pas par l'id), sans collision dans la portée finale. Un id choisi par le modèle est gardé tel quel. Une entrée existante garde sa date de création. Rien n'est écrit : l'entrée renvoyée est celle à passer à Put, redacted indique que le masquage a modifié le texte.
Types ¶
type Budget ¶ added in v0.8.0
type Budget struct {
// SessionTokens est le plafond (0 ou moins : aucun).
SessionTokens int64
// WarnAt est la fraction du plafond qui déclenche l'avis unique
// BudgetWarning (hors ]0, 1[ : DefaultWarnAt).
WarnAt float64
}
Budget est le plafond de jetons d'une session : somme input + output des événements Usage (compaction et sous-agents compris).
type Deps ¶
type Deps struct {
Provider provider.Provider
Tools *tools.Registry
Permissions *policy.Permissions
Outbound *policy.Outbound
Sinks []event.Sink // audit en premier
MaxIterations int
SystemPrompt string
ProjectRoot string
Instructions []string // fichiers d'instructions chargés, recopiés dans SessionStarted
Now func() time.Time
// ContextWindow est la fenêtre de contexte du modèle, en jetons estimés
// (0 : DefaultContextWindow).
ContextWindow int
// CompactionThreshold est la fraction de la fenêtre au-delà de laquelle
// l'historique est compacté (0 : DefaultCompactionThreshold).
CompactionThreshold float64
// McpServerDown est émis pour chacun juste après chaque SessionStarted.
UnavailableMCP []event.McpServerDownPayload
// MCP liste les serveurs MCP actifs, recopiés dans SessionStarted.
MCP []event.MCPServerInfo
// Agents liste les sous-agents disponibles (nil : pas d'outil agent).
Agents *agents.Catalog
// BasePrompt est le prompt sans sections skills/agents, base du prompt des
// sous-agents (vide : SystemPrompt).
BasePrompt string
// SkillsSection est la section des skills ajoutée au prompt d'un sous-agent
// qui dispose de l'outil skill.
SkillsSection string
// MemoryIndex est l'index de la mémoire (déjà dans SystemPrompt), ajouté
// au prompt d'un sous-agent qui dispose de memory_read ("" : aucun).
MemoryIndex string
// Lang est la langue du préambule des sous-agents (zéro : FR).
Lang i18n.Lang
// OutputLimit tronque le résultat d'un sous-agent, en caractères (0 : non).
OutputLimit int
// Hooks est l'ensemble des hooks utilisateur (nil : aucun hook).
Hooks *hooks.Set
// TranscriptPath est le fichier de session transmis aux hooks.
TranscriptPath string
// Notify active l'événement de hook Notification (vrai dans l'interface).
Notify bool
// Checkpoints est le magasin des copies d'avant écriture (nil : aucune
// restauration de contenu possible ; les suppressions restent possibles).
Checkpoints *checkpoint.Store
// Profile est le profil de conformité actif, recopié dans SessionStarted
// (le contrôle avant envoi est porté par Outbound).
Profile profile.Name
// Policy est la politique d'organisation active (nil : aucune), recopiée
// dans SessionStarted ; Outbound en revérifie les hôtes avant chaque envoi.
Policy *orgpolicy.Policy
// Allowlists sont les listes blanches de fournisseurs actives (globale,
// projet) ; Outbound en revérifie l'hôte avant chaque envoi.
Allowlists []hostmatch.List
// ShellSandboxed indique que l'outil shell isole ses commandes : les
// demandes qui le concernent portent alors Sandboxed (option « Autoriser
// avec réseau »).
ShellSandboxed bool
// Sandbox décrit l'isolation de la session, recopiée dans SessionStarted
// (nil : omise).
Sandbox *event.SandboxInfo
// Classify porte les règles de classification (chemins, marquages) ; les
// marquages intégrés s'appliquent même avec des règles vides.
Classify classify.Rules
// Router ordonne les fournisseurs candidats de chaque envoi (nil : le
// seul Provider, sans repli ni fournisseur local). Avec un fournisseur
// local (Router.Local()), un contenu classé rend la session sensible au
// lieu d'être refusé ou retenu. Provider reste le fournisseur courant
// (SessionStarted).
Router *routing.Router
// Routing décrit le routage configuré, recopié dans SessionStarted
// (nil : omis).
Routing *event.RoutingInfo
// Budget est le plafond de jetons de la session (SessionTokens 0 : aucun).
Budget Budget
// CompactionRouter et SubagentRouter ordonnent les fournisseurs des
// requêtes de résumé et des sous-agents (nil : Router). Les candidats de
// Router suivent les leurs : un fournisseur dédié refusé par les
// garde-fous laisse la place au fournisseur de la session. Une session
// sensible les ignore : le fournisseur local de Router seul.
CompactionRouter, SubagentRouter *routing.Router
// Memory est le store de la mémoire gouvernée (nil : ni outils mémoire
// ni Remember).
Memory *memory.Store
// Redact masque un texte avant son écriture en mémoire (nil : aucun
// masquage) ; le booléen indique que le texte a changé. Mêmes règles
// qu'à l'envoi.
Redact func(string) (string, bool)
// Client et Transport identifient l'éditeur d'une session ACP, recopiés
// dans SessionStarted (nil, "" : ligne de commande).
Client *event.ClientInfo
Transport string
}
Deps regroupe les dépendances de l'engine.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine exécute les tours d'agent. Il est sûr en usage concurrent ; les tours d'une même session sont sérialisés.
func (*Engine) EndSession ¶ added in v0.5.0
EndSession exécute les hooks SessionEnd (reason) d'une session démarrée dans ce processus ; sans effet sinon. Le délai de chaque hook est plafonné à 5 s (hooks.Run). Un continue:false est sans effet. Aucun TurnCompleted n'est émis. À appeler après la fin du tour en cours (annulé ou terminé) : si un tour tient encore la session, EndSession l'attend au plus jusqu'à la fin de ctx, puis renvoie ctx.Err() sans exécuter de hook.
func (*Engine) Remember ¶ added in v0.8.0
func (e *Engine) Remember(sessionID string, scope memory.Scope, text string) (memory.Entry, []string, error)
Remember enregistre une note de l'utilisateur (/remember) : auteur user, sans demande de permission, même chaîne que memory_write. Le titre est la première ligne non vide (coupée à 80 caractères après masquage, par PrepareWrite), le corps le texte entier, l'id dérivé du titre masqué (« sensitive » pour une note sensible ; suffixe -2, -3… en cas de collision). Une session pas encore démarrée l'est d'abord (SessionStarted). Attend la fin d'un tour en cours de la session. Renvoie l'entrée écrite et les avis à afficher.
func (*Engine) Restore ¶
Restore reconstruit l'état en mémoire d'une session à partir de ses événements persistés (session.Load), dans l'ordre. À appeler avant tout Submit de cette session ; renvoie ErrSessionActive si la session a déjà un état dans cet Engine (y compris après un premier Restore).
L'historique est reconstruit depuis UserMessage, AssistantMessage et ToolResult, tels quels (payloads masqués) ; ContextCompacted remplace les Replaced premiers messages (prompt système exclu) par le message de résumé, et un Replaced hors bornes rend le journal invalide (erreur). Tout appel d'outil resté sans ToolResult reçoit une réponse synthétique avant le message suivant de l'utilisateur ou de l'assistant, et après le dernier événement. Le compteur de séquence et celui des demandes de permission reprennent aux plus grandes valeurs lues ; les autorisations « pour la session » et l'avertissement de juridiction ne sont pas restaurés. Le contexte des hooks (hook_context) est rejoint aux messages utilisateur et au résumé comme pendant le tour ; un UserMessage bloqué par un hook est ignoré, un message de retour de hook Stop est un message utilisateur comme un autre ; HookStarted et HookCompleted sont ignorés. Les événements portant parent_call_id (sous-agents) sont ignorés, sauf PermissionRequested pour le compteur et ToolResult pour l'état de rewind. L'état de rewind (points, écritures, appels non annulables) est rejoué comme en direct ; un Rewound des modes conversation et both tronque l'historique à la longueur du point, celui du mode code met sa note en attente (jointe au prochain UserMessage accepté). SessionStarted et ProviderSelected suivent le fournisseur en cours : les réponses et résumés produits par un fournisseur non local sont marqués llm.Message.Remote (exclus du contrôle sortant des marquages). Un SessionClassified rend la session sensible (définitivement, quel que soit son parent_call_id). Le compteur de jetons du budget est la somme input + output de tous les Usage (sous-agents et hooks compris) ; un BudgetWarning du journal empêche un second avis. Les autres types sont ignorés.
func (*Engine) Rewind ¶ added in v0.6.0
func (e *Engine) Rewind(ctx context.Context, sessionID string, toSeq uint64, mode RewindMode, preview checkpoint.Plan, overwrite []string) (RewindResult, error)
Rewind remet la session au point toSeq selon mode. Seuls les fichiers du plan sont touchés : les fichiers ok, et les conflits dont le chemin figure dans overwrite. preview est le plan montré à l'utilisateur : un fichier dont l'état diffère de preview (ou qui n'y figure pas) n'est pas touché (failed). Un échec sur un fichier n'arrête pas les autres. Le Rewound est émis en dernier.
func (*Engine) RewindPlan ¶ added in v0.6.0
RewindPlan calcule, sans rien modifier, le plan d'un rewind vers le point toSeq. ErrTurnInProgress si un tour tient la session.
func (*Engine) RewindPoints ¶ added in v0.6.0
func (e *Engine) RewindPoints(sessionID string) []checkpoint.Point
RewindPoints renvoie les points de la session, du plus récent au plus ancien (nil pour une session inconnue). N'attend pas la fin d'un tour.
func (*Engine) SessionTokens ¶ added in v0.8.0
SessionTokens renvoie le compteur de jetons (input + output) de la session sessionID : 0 si elle est inconnue. Sert à l'affichage du total cumulé, reprise comprise.
func (*Engine) SubmitInput ¶ added in v0.3.0
SubmitInput exécute un tour complet et bloque jusqu'à sa fin (TurnCompleted, erreur du fournisseur, annulation du contexte ou échec d'audit).
func (*Engine) Subscribe ¶
Subscribe renvoie un canal recevant chaque événement émis après l'appel (tampon de 256). La livraison est bloquante quand le tampon est plein : l'abonné DOIT lire le canal en continu, sinon l'engine se bloque. Appeler avant Submit. Le canal n'est jamais fermé ; quand Submit rend la main, tous les événements du tour sont déjà dans le canal.
type Input ¶ added in v0.3.0
type Input struct {
Text, Typed, Skill, SkillSHA256 string
}
Input est un message utilisateur : Text part au modèle, les autres champs documentent un éventuel skill (Typed = saisie brute de l'utilisateur).
type Reply ¶
type Reply struct{ Allow, Remember, Network bool }
Reply répond à un PermissionRequested. Network accorde le réseau à la commande shell isolée pour cet appel seulement : Remember ne le mémorise jamais.
type RewindMode ¶ added in v0.6.0
type RewindMode string
RewindMode : ce qu'un rewind remet en arrière.
const ( RewindCode RewindMode = "code" RewindConversation RewindMode = "conversation" RewindBoth RewindMode = "both" )
Modes de rewind.
type RewindResult ¶ added in v0.6.0
type RewindResult struct {
Files []event.RewoundFile
// Prompt : texte complet du prompt choisi (modes conversation et both).
Prompt string
// Note : note jointe au prochain message (mode code seul).
Note string
}
RewindResult : bilan d'un rewind.
Source Files