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
- type Deps
- type Engine
- func (e *Engine) EndSession(ctx context.Context, sessionID, reason 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) 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
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.
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.
Functions ¶
This section is empty.
Types ¶
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
// 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
}
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) 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). 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) 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