// Package conformance provides lifecycle scenarios shared by the legacy // tuttid Service, the Agent Host implementation, and downstream host adapters. package conformance import ( "context" "encoding/json" "fmt" agenthost "github.com/tutti-os/tutti/packages/agent/host" ) type SessionSeed struct { WorkspaceID string AgentSessionID string Provider string ProviderSessionID string Cwd string Title string ActiveTurnID string InitialTitleEstablished bool Live bool Kind string Origin string ParentAgentSessionID string Deleted bool DeletedAtUnixMS int64 ExternalResumeSupported *bool Settings agenthost.ComposerSettings Pinned bool RuntimeContext map[string]any } type TurnSeed struct { TurnID string Phase string Outcome string RootProviderTurnID string ProviderTurnBindingJSON json.RawMessage FinalAssistantMessageID string StartedAtUnixMS int64 SettledAtUnixMS int64 Origin string } type InteractionSeed struct { RequestID string TurnID string Kind string Status string } type Fixture struct { Session *SessionSeed LiveOnlySession *SessionSeed AdditionalSessions []SessionSeed Turn *TurnSeed AdditionalTurns []TurnSeed Interaction *InteractionSeed AdditionalInteractions []InteractionSeed PreparedSubmitID string RecoverInteractive bool RecoverInteractiveFollowUpPrompt string RecoverInteractiveFollowUpClientSubmitID string RecoverInteractiveFollowUpDisposition agenthost.RuntimeInteractiveDisposition DisableGoalInbox bool AcceptGoalControlsOnly bool CompleteGoalOnSet bool EmptyPauseResumeGoal bool // RaceRuntimeStartReport makes the test Runtime attempt its ordinary // session-start activity report before CreateSession initializes canonical // state. A conforming Host must keep that report behind the canonical // initialization barrier. RaceRuntimeStartReport bool // FailSessionInitialization fails the canonical initialize half after the // Runtime has started, before its report/event barrier may be released. FailSessionInitialization bool // DisconnectGoalFenceDelivery drops the live Runtime Session during the // first fence delivery, modeling a Host restart with accepted durable intent // but no in-memory provider Session. DisconnectGoalFenceDelivery bool ResumeErr error FailCommitObserver bool RejectInitialExec bool RailProjectPaths []string // GuidanceTargetMismatch makes the test runtime reject guidance whose // explicit TurnID is not the Session.ActiveTurnID. It models the runtime // target race without exposing a runtime/provider API to scenarios. GuidanceTargetMismatch bool // CancelDeliveryUnconfirmed makes the test runtime acknowledge the exact // cancel delivery without being able to confirm that it stopped that turn. // The Host must retain the durable operation instead of inventing a // terminal outcome. CancelDeliveryUnconfirmed bool DeleteAdmissionErr error DeleteSessionPlans [][]string } type SessionObservation struct { SessionID string ProviderSessionID string RailSectionKey string Title string ActiveTurnID string Resumable bool Settings agenthost.ComposerSettings Pinned bool Live bool } type SendObservation struct { Session SessionObservation TurnID string Kind string Goal map[string]any Revision int64 } type GoalObservation struct { Goal map[string]any IntentAccepted bool OperationID string Revision int64 PendingOperationID string SyncStatus string ExecutionPending bool } type CancelObservation struct { Session SessionObservation TurnID string Canceled bool Pending bool Reason string } type OperationObservation struct { OperationID string Status string Result string ConfirmedTurnID string IdentityAnchorTurnID string } type InteractiveObservation struct { Session SessionObservation OperationID string TurnID string RequestID string Disposition agenthost.RuntimeInteractiveDisposition } type Metrics struct { StartCalls int ResumeCalls int ExecCalls int LastStartEnv []string LastResumeEnv []string // GuidanceProviderCalls counts guidance dispatches that passed the // runtime's exact-target gate. ExecCalls includes the rejected gate check. GuidanceProviderCalls int CancelCalls int InteractiveCalls int UpdateSettingsCalls int CloseCalls int GoalControlCalls int GoalReconcileCalls int RuntimeSessionPublishCalls int RuntimeStartReportWrites int RuntimeOperationCommits int GoalOperationCommits int RootTurnSettlements int LastCancelTargets []agenthost.RuntimeCancelTarget LastInteractiveTurnID string LastInteractiveRequestID string LastExecClientSubmitID string LastInitialTitle string LastExecRequiresProviderAcceptance bool LastClosePreservedCanonicalState bool RuntimePreparationCleanupCalls int LastCleanupPreservedRecoverableState bool LastResumeRecreate bool LastResumeGoalGenerationFences []agenthost.RuntimeGoalGenerationFenceInput RecoverySteps []string DeleteAdmissionPlans []agenthost.DeleteSessionsPlan DeleteReports []agenthost.DeleteSessionsReport CanonicalDeleteCalls int DeletionEvents []string } // Driver adapts one host implementation to the shared lifecycle scenarios. // Reset is test-only canonical/runtime seeding; command methods mirror the // provider-neutral Host application surface rather than any transport API. type Driver interface { Reset(context.Context, Fixture) error DisconnectRuntimeSession(context.Context, agenthost.SessionRef) error Create(context.Context, string, agenthost.CreateSessionInput) (SessionObservation, string, error) EnsureSession(context.Context, agenthost.SessionRef) (SessionObservation, error) SendInput(context.Context, agenthost.SessionRef, agenthost.SendInput) (SendObservation, error) CancelTurn(context.Context, agenthost.CancelTurnInput) (CancelObservation, error) SubmitInteractive(context.Context, agenthost.InteractionRef, agenthost.SubmitInteractiveInput) (InteractiveObservation, error) GetInteractionStatus(context.Context, agenthost.InteractionRef) (string, bool, error) SubmitPlanDecision(context.Context, agenthost.SessionRef, string, string, agenthost.SubmitPlanDecisionInput) (OperationObservation, error) UpdateTitle(context.Context, agenthost.UpdateTitleInput) (SessionObservation, error) GetSession(context.Context, agenthost.SessionRef) (SessionObservation, error) ListSessionTurns(context.Context, agenthost.SessionRef, agenthost.SessionTurnQuery) (agenthost.SessionTurnSummaryPage, error) GetCanonicalSession(context.Context, agenthost.SessionRef) (SessionObservation, error) UpdateSettings(context.Context, agenthost.UpdateSettingsInput) (SessionObservation, error) UpdatePin(context.Context, agenthost.UpdatePinInput) (SessionObservation, error) DeleteSession(context.Context, agenthost.SessionRef) (agenthost.DeleteSessionResult, error) DeleteSessions(context.Context, agenthost.DeleteSessionsInput) (agenthost.DeleteSessionsResult, error) PurgeDeletedSessions(context.Context, agenthost.PurgeDeletedSessionsInput) (agenthost.PurgeDeletedSessionsResult, error) GoalControl(context.Context, agenthost.GoalControlInput) (GoalObservation, error) AdoptProviderGoal(context.Context, agenthost.ProviderGoalAdoptionInput) (GoalObservation, error) FenceGoalGeneration(context.Context, agenthost.FenceGoalGenerationInput) (agenthost.FenceGoalGenerationResult, error) GetGoalState(context.Context, agenthost.SessionRef) (GoalObservation, error) ReconcileGoal(context.Context, agenthost.SessionRef) (GoalObservation, error) StepGoalOperations(context.Context, int64) error Recover(context.Context) error Metrics() Metrics } // WorkspaceRuntimeDisconnectDriver is a narrow opt-in lifecycle contract so a // new Host capability does not source-break existing external conformance // drivers that implement the stable Driver interface. type WorkspaceRuntimeDisconnectDriver interface { Driver DisconnectWorkspaceRuntime(context.Context, string) (agenthost.DisconnectWorkspaceRuntimeResult, error) } type WorkspaceRuntimeDisconnectScenario struct { Name string run func(context.Context, WorkspaceRuntimeDisconnectDriver) error } // WorkspaceRuntimeAdmissionDriver exposes only the Host-owned coordination // seam needed to verify admission and durable disconnect fencing. type WorkspaceRuntimeAdmissionDriver interface { WithWorkspaceRuntimeOperation(context.Context, string, func(context.Context) error) error AcquireWorkspaceRuntimeDisconnectFence(context.Context, string) (WorkspaceRuntimeDisconnectFenceDriver, error) } type WorkspaceRuntimeDisconnectFenceDriver interface { Wait(context.Context) (context.Context, error) Release() } type WorkspaceRuntimeAdmissionScenario struct { Name string run func(context.Context, WorkspaceRuntimeAdmissionDriver) error } func RunWorkspaceRuntimeAdmission( ctx context.Context, driver WorkspaceRuntimeAdmissionDriver, scenario WorkspaceRuntimeAdmissionScenario, ) error { if driver == nil { return fmt.Errorf("workspace runtime admission conformance driver is required") } if scenario.run == nil { return fmt.Errorf("workspace runtime admission scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } func RunWorkspaceRuntimeDisconnect( ctx context.Context, driver WorkspaceRuntimeDisconnectDriver, scenario WorkspaceRuntimeDisconnectScenario, ) error { if driver == nil { return fmt.Errorf("workspace runtime disconnect conformance driver is required") } if scenario.run == nil { return fmt.Errorf("workspace runtime disconnect scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } // ProviderlessTerminalDriver is the narrow fault-injection capability for a // Runtime that durably fails the exact canonical Turn before it acquires a // provider identity. It stays separate from Fixture so downstream conformance // drivers can adopt this lifecycle scenario before upgrading their pinned // Tutti dependency; an extra test-driver method is source-compatible with the // previous conformance contract. type ProviderlessTerminalDriver interface { ResetProviderlessTerminalExec(context.Context, *SessionSeed) error } type Scenario struct { Name string run func(context.Context, Driver) error } // RailPlacementRecoveryDriver is separate from Driver so Host consumers adopt // the immutable rail recovery proof explicitly instead of reimplementing rail // normalization in an application adapter. type RailPlacementRecoveryDriver interface { Reset(context.Context, Fixture) error Create(context.Context, string, agenthost.CreateSessionInput) (SessionObservation, string, error) GetSessionWithRailPlacement(context.Context, agenthost.SessionRef, *agenthost.RailPlacement) (SessionObservation, error) } type RailPlacementRecoveryScenario struct { Name string run func(context.Context, RailPlacementRecoveryDriver) error } // DeletedSessionLifecycleDriver is separate from Driver so adapters adopt the // lossless tombstone contract explicitly while rolling out its new canonical // storage capability. type DeletedSessionLifecycleDriver interface { Reset(context.Context, Fixture) error DeleteSession(context.Context, agenthost.SessionRef) (agenthost.DeleteSessionResult, error) ListDeletedSessions(context.Context, agenthost.ListDeletedSessionsInput) (agenthost.DeletedSessionPage, error) RestoreDeletedSession(context.Context, agenthost.RestoreDeletedSessionInput) (agenthost.RestoreDeletedSessionResult, error) GetCanonicalSession(context.Context, agenthost.SessionRef) (SessionObservation, error) Metrics() Metrics } type DeletedSessionLifecycleScenario struct { Name string run func(context.Context, DeletedSessionLifecycleDriver) error } // SessionForkFixture describes fault and recovery states at the public Host // boundary. Implementations may seed those states using their own test-only // canonical/runtime adapters. type SessionForkFixture struct { FailFirstLocalCommit bool RecoverProviderAccepted bool RecoverPermanentlyInconsistent bool KeepSourceActive bool } type SessionForkMetrics struct { ProviderForkCalls int } // SessionForkDriver is separate from Driver so existing Host consumers can // adopt the new lifecycle capability explicitly rather than gaining fake // support through the base session contract. type SessionForkDriver interface { ResetSessionFork(context.Context, SessionForkFixture) error ForkSession(context.Context, agenthost.ForkSessionInput) (agenthost.ForkSessionResult, error) GetSessionForkOperation(context.Context, string, string) (agenthost.ForkSessionResult, bool, error) RecoverSessionForks(context.Context) error SessionForkMetrics() SessionForkMetrics } type SessionForkScenario struct { Name string run func(context.Context, SessionForkDriver) error } // InteractionTreeDriver is separate from the lifecycle Driver because tree // snapshots are a read capability that consumers can adopt independently. type InteractionTreeDriver interface { ResetInteractionTree(context.Context) error GetSessionInteractionTreeSnapshot(context.Context, agenthost.SessionRef, agenthost.SessionInteractionTreeQuery) (agenthost.SessionInteractionTreeSnapshot, error) } type InteractionTreeScenario struct { Name string run func(context.Context, InteractionTreeDriver) error } type SideConversationMetrics struct { ParentActive bool CanonicalWrites int TransientEvents int SideLive bool } // SideConversationDriver is optional because a provider may omit the native // Side adapter entirely. Implementations exercise the common Host lifecycle; // provider-specific protocol details belong in adapter tests. type SideConversationDriver interface { ResetSideConversation(context.Context) error SettleSideParent(context.Context) error OpenSideConversation(context.Context, agenthost.OpenSideConversationInput) (agenthost.OpenSideConversationResult, error) SendSideConversation(context.Context, agenthost.RuntimeExecInput) (agenthost.RuntimeExecResult, error) CloseSideConversation(context.Context, string, string) error SideConversationMetrics() SideConversationMetrics } type SideConversationScenario struct { Name string run func(context.Context, SideConversationDriver) error } func Run(ctx context.Context, driver Driver, scenario Scenario) error { if driver == nil { return fmt.Errorf("agent host conformance driver is required") } if scenario.run == nil { return fmt.Errorf("agent host conformance scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } func RunRailPlacementRecovery( ctx context.Context, driver RailPlacementRecoveryDriver, scenario RailPlacementRecoveryScenario, ) error { if driver == nil { return fmt.Errorf("agent host rail placement recovery conformance driver is required") } if scenario.run == nil { return fmt.Errorf("agent host rail placement recovery conformance scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } func RunSessionFork( ctx context.Context, driver SessionForkDriver, scenario SessionForkScenario, ) error { if driver == nil { return fmt.Errorf("agent host session fork conformance driver is required") } if scenario.run == nil { return fmt.Errorf("agent host session fork conformance scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } func RunDeletedSessionLifecycle( ctx context.Context, driver DeletedSessionLifecycleDriver, scenario DeletedSessionLifecycleScenario, ) error { if driver == nil { return fmt.Errorf("agent host deleted session lifecycle conformance driver is required") } if scenario.run == nil { return fmt.Errorf("agent host deleted session lifecycle conformance scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } func RunInteractionTree( ctx context.Context, driver InteractionTreeDriver, scenario InteractionTreeScenario, ) error { if driver == nil { return fmt.Errorf("agent host interaction tree conformance driver is required") } if scenario.run == nil { return fmt.Errorf("agent host interaction tree conformance scenario %q has no runner", scenario.Name) } return scenario.run(ctx, driver) } func RunSideConversation( ctx context.Context, driver SideConversationDriver, scenario SideConversationScenario, ) error { if driver == nil { return fmt.Errorf("agent host side conversation conformance driver is required") } if scenario.run == nil { return fmt.Errorf( "agent host side conversation conformance scenario %q has no runner", scenario.Name, ) } return scenario.run(ctx, driver) }